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

Code du point d'entrée Description

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

Nom en C Nom en COBOL Caractéristiques/Longueur Utilisation

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

Nom en C Nom en COBOL Caractéristiques Utilisation

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

Numéro Description

 

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 :

  • instruction Case
  • Break

 

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

Plateforme Répertoire/Nom de bibliothèque Programme C Programme COBOL

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

 

Type de traitement Libellé Point d'entrée

Open

P79

79

Close (Fermeture)

P80

80

Point d'appel xx

Pxx

xx

Related Links