Appel externe ITR501
Ce chapitre décrit les appels externes et la façon de les utiliser.
Vue générale
Les appels externes comprennent un ensemble de modules indépendants qui sont stockés à l’intérieur du module ITR501. Ils sont activés automatiquement par les commandes $SEARCH ($RECH) et $CHECK ($CTRL) du Langage de Manipulation des Données (LMD).
Caractéristiques
Le module ITR501 existe en C (ITR501C) et en COBOL (ITR501).
Si vous utilisez le module ITR501C, vous pouvez utiliser les points d'entrée pré-codés qui facilitent l’accès aux modules Euroconverter ainsi que l’accès à des données stockées en base Oracle. Pour cela, vous devez enlever les commentaires qui précèdent les instructions de ces points d’entrée.
Liste des valeurs des points d’entrée
|
De “01” à “73”
(code numérique)
de 0A à ZZ (code alphanumérique)
|
Fonctions personnalisables
|
| “79”
|
Fonction d'ouverture et d’initialisation du module, appelée au démarrage de la vacation.
Cette fonction paramétrable permet notamment d’implémenter l'ouverture des fichiers nécessaires et la connexion aux bases de données.
|
| “80”
|
Fonction de fermeture, appelée à l'arrêt de la vacation.
Cette fonction paramétrable permet d’implémenter la fermeture des fichiers et la déconnexion des bases de données.
|
|
|
Points d’entrée pré-codés pour ITR501C
|
| “70”
|
Appel aux modules Euroconverter.
Le paramètre de retour dépend du module activé.
|
| “71”
|
Fonctions de formatage des champs
|
| “75”
|
Commande $SEARCH qui active un ordre «select» sur une colonne de table.
Le paramètre renvoyé correspond à la première ligne de la table qui satisfait au critère de la sélection
|
| “76”
|
Commande $SEARCH qui active une procédure Oracle.
Le paramètre renvoyé correspond à la procédure activée
|
| “77”
|
Commande $CHECK qui contrôle l'existence d'une valeur dans une colonne de table.
|
| “78”
|
Commande $CHECK qui contrôle une valeur par une procédure Oracle.
|
Les données échangées
Certains champs alphanumériques peuvent avoir différentes descriptions selon le langage de programmation et le format utilisé (Latin ou UTF-16). Pour plus d’information, reportez-vous à Gérer les Exits et les appels externes.
Données en ENTRÉE
|
sDATA256
|
LPZDATA256
|
Alphanumérique / 256
|
Valeur du paramètre de recherche ou de contrôle
|
|
sLONG
|
LPLONG
|
Numérique / 3
|
Longueur du paramètre attendu en sortie :
sa valeur varie de 1 à 256
(pour une fonction $SEARCH)
|
|
sCLASSE
|
LPCLASSE
|
Alphanumérique / 1
|
Classe du paramètre attendu en sortie : “A”, “N”, “S”, “P”, “D”
(pour une fonction $SEARCH)
|
|
sCDPARAM
|
LPCDPARAM
|
Alphanumérique / 2
|
Code du point d'entrée
|
Données en SORTIE
|
sDATA256
|
LPZDATA256
|
Alphanumérique / 256
|
Valeur du paramètre de retour
(pour une fonction $SEARCH)
|
|
sCDPARAM
|
LPCDPARAM
|
Alphanumérique / 2
|
Code du point d'entrée
|
|
FLAG
|
LPFLAG
|
Alphanumérique / 1
|
Code retour de la fonction :
- 0 : recherche ou contrôle correct
- 9 : recherche ou contrôle incorrect
- F : erreur système
|
|
lsZONERR
|
LPZONERR
|
Alphanumérique / 50
|
Libellé de l'erreur si une erreur a été détectée
|
|
sCDERR
|
LPCDERR
|
Numérique / 7
|
Code erreur si une erreur a été détectée
|
|
sSTATUS
|
LPSTATUS
|
Alphanumérique / 2
|
Statut de l’erreur si une erreur a été détectée
|
Mise en œuvre
Conventions d’écriture
|
|
Conventions d’écriture communes
|
|
1
|
Les données renvoyées par la fonction implémentée au point d'entrée choisi doivent être renseignées
|
|
2
|
Par défaut, le code retour est à zéro (OK)
Si vous le modifiez, il doit prendre une des valeurs citées dans le tableau précédent
|
|
3
|
Chaque point d'entrée activé dans les phrases de garnissage des règles de traduction et de modification doit être déclaré dans ITR501.
S'il n'est pas déclaré, le CRE traité est mis en anomalie
|
|
4
|
Par défaut, tous les points d'entrée numériques sont déclarés dans l'appel externe
Même si aucun code n'est implémenté, le code retour est OK
|
|
5
|
Les points d'entrée alphanumériques doivent être déclarés dans l'appel externe
|
|
|
Conventions pour le langage C
|
|
6
|
Il faut ajouter dans le switch (nCDPARAM) l’instruction :
|
|
|
Conventions COBOL
|
|
6
|
Il faut ajouter dans le paragraphe AUTRES-CODES l'instruction :
IF LPCDPARAM = “entry_point_code” GO TO P-code_point_entrée
Définir une étiquette P-code_point_entrée
|
Valeur des champs Data
Les 25 premiers caractères du champ sDATA256 (ou LPZDATA256) contiennent la valeur du code émetteur lors de l'ouverture (point d'entrée "79").
Dans le cas d'une fonction $SEARCH, il est conseillé de réinitialiser ce champ avant de le garnir avec la valeur de retour, afin d'éviter les "valeurs résiduelles parasites".
Lorsque vous initialisez ce champ, quel que soit son type, vous devez justifier à gauche les données conformément à la longueur définie par sLONG (ou LPLONG).
ITR501C (langage C) met à disposition les fonctions de conversion pour lire et écrire les données échangées dans le format attendu :
- SPK_Num2Pack : conversion d'une valeur de type numérique (non signée) en valeur de type packé
- SPK_Pack2Num : conversion d'une valeur de type packé en valeur de type numérique
- SPK_Num2Sign : conversion d'une valeur de type numérique en valeur de type signé
- SPK_Sign2Num : conversion d'une valeur de type signé en valeur de type numérique
- SPK_IsSPKformat : contrôle de numéricité sur une valeur (signée ou décimale)
Pour plus de détails sur les fonctions de conversion, reportez-vous à Conversion de données – Fonctions en C.
Des prototypes de ces fonctions sont disponibles dans :
- Le fichier ITR501.h situé pour :
- UNIX dans le répertoire $RDJ_EXEC/exit
- Windows, dans le répertoire %RDJ_EXEC%\exit
- le fichier ITR501 dans la bibliothèque MVS SCRLIB.H
Pour plus d’information sur les valeurs renvoyées lors d’une conversion, reportez-vous à Valeurs de retour
Pour accéder à Oracle, vous pouvez utiliser les fonctions disponibles SQL pré-codées disponibles dans ITR501 aux points d’entrée "75" à "78".
- SQLSELECT : récupération d'une valeur à partir d'une instruction select dans une colonne de table
- SQLPROC : récupération d'une donnée résultant de l'activation d'une procédure
- SQLDIRECTSELECT : récupération d'une valeur à partir d'une instruction "select", dont l'instruction complète est transmise à la fonction
- SQLCTRLSELECT : contrôle d'existence d'une valeur par le lancement d'une instruction select.
Pour plus de détail sur les fonctions SQL et les valeurs renvoyées, reportez-vous à Fonctions SQLxxx.
Si vous voulez accéder à une base de données par l’ITR501 en langage COBOL, un exemple d'utilisation est proposé en commentaires dans le programme.
Compatibilité avec la version RDJ 1.5.3.2
La zone de communication actuelle a été revue. Elle reste cependant compatible avec la version RDJ 1.5.3.2.
Les changements intervenus dans la zone de communication sont les suivants :
- La longueur totale de la zone de communication est passée de 283 à 380 caractères.
- Les noms des champs ont changé, mais leur séquencement et justification sont restés identiques.
- La longueur du message d’erreur est passée de 20 à 50 caractères.
- Des codes et statuts d’erreur ont été ajoutés.
- Le code du point d'appel est alphanumérique (il était numérique dans l’ancienne version).
Paramétrage
Aucun paramétrage particulier n'est à définir puisque l'appel est effectué dès lors que les fonctions $SEARCH ($RECH) et $CHECK ($CTRL) sont activées dans les phrases de garnissage (règles de traduction et modification).
Nom des modules
|
Windows
|
%RDJ_EXEC%\exit
|
ITR501.c
ITR501.h fichier entête
|
ITR501.cbl
|
|
UNIX
|
$RDJ_EXEC/exit
|
ITR501.c
ITR501.h fichier entête
|
ITR501.cbl
|
|
MVS
|
&RDJEXEC..SRCLIB
|
ITR501C
entête ITR501H
|
ITR501
|
|
Open
|
P79
|
79
|
|
Close (Fermeture)
|
P80
|
80
|
|
Point d'appel xx
|
Pxx
|
xx
|