Utilizzare una API in programma RPG ILE equivale ad eseguire una normale istruzione CALL come con un qualunque programma esterno. Ciò che rende l'utilizzo delle API un
po' più complesso è la comprensione dei parametri di input e output richiesti. Il tutto è reso a volte ancora più complesso dal fatto che molte API necessitano di determinati parametri e restituiscono risultati di lunghezza variabile, per cui è necessario ricorrere all'utilizzo di puntatori.
va bene
La documentazione di tutte le API disponibili può essere letta accedendo al link:
Vedi (J1PATHFILE-http://publib.)

Prestare attenzione alla versione del sistema operativo (in questo caso ci riferiamo alla versione 5.3).

Per accedere alla documentazione relativa ad altre versioni del sistema operativo si consiglia di consultare il sito "base" della documentazione IBM relativa all'Iseries.

Vedi (J1PATHFILE-http://publib.)

Utili esempi sull'utilizzo di API possono essere trovati anche in questi siti:
Vedi (J1PATHFILE-http://www.thi)
Vedi (J1PATHFILE-http://www.cod)

Esempio di utilizzo di una API

Syntax Check SQL Statement (QSQCHKS) API.
Nel file QAPIGEN si può vedere il membro QSQCHKS
Vedi QSQCHKS - controllo sintassi SQL (MBQAPIGEN-QSQCHKS)

Dal sito IBM sopra citato si legge che i parametri di questa API sono i seguenti:

---

Questo esempio comprende parametri di input e di output a lunghezza variabile.
Il tipo di dato Char(*) significa puntatore ad una varibile di tipo CHAR (con un poco di conoscenza del il linguaggio C, tutto risulterà molto famigliare).
Per utilizzare questa Api in un programma QRPGLE è consigliabile definire un prototipo di chiamata, che consenta di utilizzare la stessa sotto forma di procedura.
Il nostro programma RPG comprenderà quindi le seguenti specifiche D (queste definizioni sono presenti nella /COPY QAPIGEN,QSQCHKS.

---

D SQLSYNTAX Pr ExtPgm( 'QSQCHKS' ) .
D SQLSTR 32767a Const Options( *VarSize ) .
D SQLSTRL 10i 0 Const .
D SQLSTRRN 10i 0 Const .
D SQLLANG 10a Const .
D SQLOPT 32767a Const Options( *VarSize ) .
D SQLINF 32767a Options( *VarSize ) .
D SQLINFL 10i 0 Const .
D SQLREC 10i 0 .
D SQLERROR 32767a Options( *VarSize ) .

• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • .
                                                                                                                                              

Nel prototipo sono stati dichiarati i parametri:

• CHAR(*) è stato definito come Const Options(*VarSize)
  
• Binary(4) è stato dichiarato come 10I 0
  

La dichiarazione come Const è riservata ai soli paramatri di input.
Il prototipo può anche ridefinire il nome dell'API (come avviene in questo caso, dove l'API verrà utilizzata richiamando la procedura SQLSYNTAX). In ogni caso, la procedura può essere chiamata come il none dell'API stessa.

Per utilizzare l'API in un programma RPGLE occorre definire anche le DS che rappresentano la struttura dei parametri di input e output.
La definizione di queste DS (non per tutte le API) può essere cercata nel file sorgente QSYSINC/QRPGLESRC, la cui libreria viene fornita con il sistema operativo, ma non è normalmente installata. Essa può essere installata attraverso la normale procedura per i programmi su licenza (prodotto 5722SS1 opz. 13 OS/400 - Include apertura del sistema).

Se una delle definizioni presenti in questa libreria è stata utilizzata in un programma di Sme.up, se ne potrà trovare una copia in SMESTD/QAPIGEN (con lo stesso nome membro).
E' importante osservare come non sia sempre possibile utilizzare queste definizioni includendole nel nostro programma con la direttiva /COPY, in quanto molto spesso contengono solo la parte "fissa" della DS, lasciando al programmatore l'onere di definirne la parte variabile.
L'API di cui stiamo parlando non fa eccezione a questa regola (vedere QSYSINC/QRPGLESRC,QSQCHKS).

Per definire le DS necessarie alla nostra API è necessario specificare la struttura dei parametri per le DS previste. Si rimanda al membro QSQCHKS in QAPIGEN per il dettaglio delle DS necessarie
per l'utilizzo di questa API.
Per illustrare la struttura di Ds "variabile" frequentemente utilizzata dalla API, ecco nel dettaglio una di queste DS.

---

D*Type Definition for parte variabile di SQLOPT .

• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • .
                                                                                                                                                

DQSQVO DS .
D* Qsq Vlen Option .
D QSQK 1 4B 0 .
D* Key .
D QSQLVO 5 8B 0 .
D* Length Vlen Option .

Nell'esempio riportato il parametro SQLOPT è strutturato nel modo seguente:

• Numero di opzioni (N) passate
  
• Ripetizione di N volte della struttura QSQVO
  

Per quanto riguarda la DS relativa agli errori si può utilizzare la /COPY APIERROR
Vedi APIERROR Struttura dati per ERROR CODE PARAMETER (MBQAPIGEN-APIERROR)

La /COPY QAPIGEN,QSQCHKS include a sua volta questa /COPY

Dopo il richiamo dell'API, se la variabile AeBytAvl contiene un valore <> di 0, il richiamo dell'API non è avvenuto correttamente.
N.B.: Il campo AeBytAvl è definito nella DS degli errori (APIERROR)

Il richiamo avrà pertanto una struttura di questo tipo:

---

E' necessario prestare particolare attenzione nel caso si utilizzino variabili di tipo VARING (come nell'esempio la variabile $SQLSTR) come parametro di input, con indicazione della lunghezza del parametro passato: non si dovrà utilizzare la funzione %SIZE, come si farebbe con variabili non varing, ma la funzione %LEN (la funzione %SIZE applicata alla variabile $SQLSTR restituirebbe sempre il valore 32769 (32767 + 2 bytes).