CALL

La commande CALL (Appeler un programme) permet d'appeler le programme indiqué et de lui donner le contrôle. Le cas échéant, le programme ou l'utilisateur émettant la commande CALL peut passer des paramètres au programme appelé. La commande CALL peut être utilisée dans un travail par lot, dans un travail interactif et en langage de contrôle (CL) interprété et compilé. Lorsque le programme appelé termine le traitement, il peut rendre le contrôle au programme appelant, à l'aide de la commande RETURN.

Si la commande CALL est émise par un programme CL ou une procédure CL ILE, chaque valeur de paramètre transmise au programme appelé peut être une constante de chaîne alphanumérique , une constante numérique, une constante logique, une constante en virgule flottante, une variable CL ou une expression. Une valeur indiquée sous la forme d'une constante en virgule flottante est convertie au format en virgule flottante binaire double précision avant d'être transmise au programme appelé. Lorsque des paramètres sont transmis, la valeur de la constante, de la variable ou de l'expression peut être utilisée par le programme appelé. Les paramètres ne peuvent pas être transmis sous l'une des formes suivantes : listes de valeurs, noms qualifiés, paramètres nuls (dont la valeur est nulle, indiquée par *N) ou paramètres de mot clé. Vous pouvez transmettre jusqu'à 255 paramètres au programme appelé.

Si des paramètres sont transmis à un programme à l'aide de la commande CALL, leurs valeurs sont transmises dans l'ordre de leur apparition sur la commande, qui doit concorder avec l'ordre figurant dans la liste des paramètres du programme appelé.

Les paramètres d'un programme appelé peuvent être utilisés à la place de ses variables. Cependant, aucune mémoire dans le programme appelé n'est associée aux variables qu'il reçoit. La mémoire d'une variable transmise se trouve dans le programme où elle a été initialement déclarée. En cas de transmission d'une constante, une copie de celle-ci est créée, puis transmise au programme appelé. Si une expression est transmise, une zone de résultat intermédiaire est créée et transmise au programme appelé.

Résultat : si une variable est transmise, le programme appelé peut modifier sa valeur et cette modification peut se répercuter dans le programme appelant. Si c'est la valeur d'une constante ou d'une expression qui est modifiée par le programme appelé, la modification ne peut pas être connue du programme appelant. Par conséquent, si ce dernier appelle de nouveau le même programme, la valeur initiale des constantes ou des expressions sera prise en compte.

Le manuel Ensemble de rubriques Gestion des travaux de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/ fournit plus de détails sur la transmission de variables à l'aide de la commande CALL via la commande SBMJOB (Soumettre un travail).

Restrictions :

• Vous devez disposer des droits *OBJOPR (opération sur les objets) et *EXECUTE (droits d'exécution) pour le programme à appeler et des droits *EXECUTE pour la bibliothèque dans laquelle figure le programme.
• La commande CALL prend en charge les travaux à unités d'exécution multiples, c'est-à-dire qu'elle peut être utilisée pour appeler un programme lorsqu'elle s'exécute dans un travail comportant plusieurs unités d'exécution. Aucune vérification n'est effectuée, que le programme à appeler prenne en charge les unités d'exécution multiples ou non.

Paramètres

Programme (PGM)

Indique le programme à appeler.

Ce paramètre est obligatoire.

Qualificatif 1 : Programme

nom

Indiquez le nom du programme à appeler.

Qualificatif 2: Biblio

*LIBL

La recherche porte sur toutes les bibliothèques de la liste des bibliothèques de l'unité d'exécution en cours jusqu'à ce que la première occurrence soit trouvée.

*CURLIB

Le programme est recherché dans la bibliothèque en cours de l'unité d'exécution. Si cette bibliothèque n'est pas indiquée, QGPL est utilisée par défaut.

nom

Indiquez le nom de la bibliothèque contenant le programme.

Paramètres (PARM)

Indique les valeurs à transmettre au programme appelé. Vous pouvez transmettre jusqu'à 255 valeurs.

Chacune des valeurs ne peut être indiquée que sous l'une des formes suivantes : une constante de chaîne alphanumérique, une constante numérique, une constante logique, une constante en virgule flottante double précision, une variable du programme ou une expression. Pour une commande CALL exécutée en dehors d'un programme CL compilé ou d'une procédure CL ILE, toutes les paramètres doivent être des valeurs constantes.

Pour une commande CALL spécifiée au paramètre CMD d'une commande SBMJOB exécutée à partir d'un programme CL compilé, toutes les variables CL utilisées pour les paramètres de la commande CALL sont converties en valeurs constantes lorsque la commande SBMJOB est exécutée. Ainsi, les valeurs peuvent être transmises dans la chaîne de commande envoyée au nouveau travail. Les blancs de fin des variables CL alphanumériques sont tronqués, ce qui peut affecter le nombre d'octets transmis au programme appelé. Les variables CL décimales et de nombre entier spécifiées en tant que paramètres sur la commande CALL imbriquée seront converties en constantes numériques et transmises sous la forme de nombres décimaux condensés. Si le programme appelé dans le nouveau travail attend des paramètres de type alphanumérique ou décimal condensé d'une longueur spécifique, vous pouvez spécifier les informations de longueur pour chaque paramètre.

Le type et la longueur de chaque paramètre doivent être identiques à ceux des paramètres définis dans le programme appelé. Le nombre de paramètres et l'ordre de leur envoi et de leur réception doivent également être identiques. Si le type, le nombre, l'ordre et la longueur des paramètres de la commande CALL ne correspondent pas dans le programme appelé, vous risquez d'obtenir des résultats inattendus.

Les paramètres peuvent être transmis et reçus de la manière suivante :

• Les paramètres de type constante alphanumérique sont transmis sous forme de 32 octets au minimum. Pour les paramètres de type constante alphanumérique de plus de 32 octets, par défaut, la longueur de la chaîne constante est utilisée pour déterminer le nombre d'octets transmis au programme appelé. Vous pouvez contrôler le nombre d'octets transmis pour un paramètre de type constante alphanumérique en spécifiant les informations de longueur de paramètre de manière explicite.
• Par défaut, pour les constantes numériques, la valeur est transmise sous forme de nombre décimal condensé avec 15 chiffres au total et 5 décimales. Vous pouvez contrôler le type utilisé pour une constante numérique en spécifiant les informations de type de paramètre de manière explicite. Si la valeur *INT ou *UINT est spécifiée pour le type, vous pouvez contrôler le nombre d'octets (2, 4 ou 8) transmis pour ce paramètre de type constante numérique en spécifiant les informations de longueur de paramètre de manière explicite. Si la valeur *DEC est spécifiée pour le type, vous pouvez contrôler le nombre total de chiffres et le nombre de décimales utilisés pour ce paramètre de type constante numérique en spécifiant les informations de longueur de paramètre de manière explicite.
• Les constantes logiques sont transmises sous forme de 1 octet ayant une valeur logique de "1" ou de "0".
• Les constantes et les valeurs spéciales en virgule flottante (*NAN, *INF et *NEGINF) sont transmises par défaut sous forme de nombres en virgule flottante à double précision. Ces nombres occupent 8 octets et sont indiqués sous la forme sn.nEsn, où s est un signe plus (+) ou moins (-) ; par exemple, -2.47E+3 ou 3.653E24. Vous pouvez contrôler la transmission du paramètre sous la forme d'une simple précision en spécifiant explicitement la valeur 4 comme longueur de paramètre.
• Une variable de programme CL peut être transmise au programme appelé si la commande CALL est exécutée à partir d'un programme CL ou d'une procédure CL ILE. Pour une commande CALL spécifiée au paramètre CMD d'une commande SBMJOB, la valeur de la variable CL est convertie en valeur constante lorsque la commande SBMJOB est exécutée et est traitée comme une constante alphanumérique ou numérique.
• Les paramètres de type expression alphanumérique sont transmis sous forme de 32 octets au minimum. Pour les paramètres de type expression alphanumérique de plus de 32 octets, par défaut, la longueur de la chaîne résultante intermédiaire est utilisée pour déterminer le nombre d'octets transmis au programme appelé. Vous pouvez contrôler le nombre d'octets transmis pour un paramètre de type expression alphanumérique en spécifiant les informations de longueur de paramètre de manière explicite.
• Par défaut, pour les expressions numériques, la valeur est transmise sous forme de nombre décimal condensé avec 15 chiffres au total et 5 décimales. Vous pouvez contrôler le type utilisé pour une expression numérique en spécifiant les informations de type de paramètre de manière explicite. Si la valeur *INT ou *UINT est spécifiée pour le type, vous pouvez contrôler le nombre d'octets (2, 4 ou 8) transmis pour ce paramètre de type expression numérique en spécifiant les informations de longueur de paramètre de manière explicite. Si la valeur *DEC est spécifiée pour le type, vous pouvez contrôler le nombre total de chiffres et le nombre de décimales utilisés pour ce paramètre de type expression numérique en spécifiant les informations de longueur de paramètre de manière explicite.
• Vous ne pouvez pas utiliser la valeur *N pour indiquer une valeur nulle car celle-ci n'est pas une valeur de paramètre prise en charge dans le langage de contrôle.

Elément 1 : Paramètre

valeur-non-restreinte

Indiquez une valeur de constante ou une variable CL ou une expression à transmettre au programme appelé. Une variable CL et une expression ne peuvent être spécifiées que si la commande CALL est exécutée à partir d'un programme CL compilé.

Elément 2 : Type et longueur de paramètre

Indique, pour les valeurs de paramètre numérique, en virgule flottante et de type constante alphanumérique, ou pour les valeurs d'expression, la façon dont le paramètre est transmis au programme appelé. Si vous exécutez une commande CALL à partir d'un programme CL compilé pour appeler un programme dans le même travail et qu'une variable CL est spécifiée, le type et la longueur de paramètre sont déterminés par le type et la longueur déclarés pour la variable CL.

Valeurs uniques

*DFT

Pour une constante ou une expression alphanumérique, un minimum de 32 octets est transmis. Si la chaîne constante ou la chaîne de résultat intermédiaire de l'expression est supérieure à 32 octets, la longueur de paramètre correspond à celle de la chaîne constante ou de la chaîne de résultat intermédiaire de l'expression. Pour une constante ou une expression numérique, le paramètre est transmis sous forme de nombre décimal condensé avec 15 chiffres au total et 5 décimales. Pour les variables CL, si un programme est appelé dans le même travail, les informations de longueur de paramètre correspondent à la longueur déclarée pour la variable.

Remarque :Pour les variables CL spécifiées dans une commande CALL utilisée avec une autre commande, telle que SBMJOB, la valeur stockée dans la variable CL est convertie en constante numérique ou alphanumérique avec les blancs de fin retirés des chaînes alphanumériques. La constante résultante sera traitée comme une valeur de paramètre constante.

Elément 1 : Type

Indique le type de paramètre à transmettre. La valeur de ce paramètre ne peut pas être indiquée par une variable CL.

*DEC

Paramètre de type décimal contenant une valeur décimale condensée.

*CHAR

Paramètre de type alphanumérique contenant une valeur de chaîne alphanumérique.

*LGL

Paramètre de type logique contenant la valeur logique '1' ou '0'.

*INT

Paramètre de type entier contenant une valeur binaire signée.

*UINT

Paramètre de type entier contenant une valeur binaire non signée.

*FLT

Paramètre en virgule flottante contenant une valeur en virgule flottante binaire.

Elément 2 : Longueur

entier

Pour les paramètres de type alphanumérique, entier ou en virgule flottante, spécifiez le nombre d'octets pour les paramètres transmis. Pour les paramètres de type décimal, spécifiez le nombre de chiffres pour les paramètres transmis. La longueur ne peut pas être supérieure à la longueur maximale admise pour ce type de paramètre CL. La longueur doit être égale à 2, 4 ou 8 pour les paramètres de type entier. La longueur doit être 4 ou 8 pour les paramètres en virgule flottante.

Elément 3 : Nombre de positions décimales

entier

Cet élément n'est admis que pour les paramètres de type décimal. La longueur de la valeur du paramètre inclut le nombre de positions décimales dans la valeur. La longueur maximale de la valeur décimale est de 24 chiffres (y compris ceux figurant à droite de la virgule décimale). Vous pouvez indiquer jusqu'à neuf positions décimales. Si neuf positions décimales sont spécifiées, la valeur figurant à gauche de la virgule décimale ne peut jamais être supérieure à 999,999,999,999,999, car seuls 15 chiffres sur les 24 restent disponibles pour la partie entière.

Si une longueur en chiffres est indiquée pour un paramètre de type décimal sans que le nombre de positions décimales soit précisé, 0 est utilisé par défaut (aucune position décimale).

La longueur maximale pour chacun des six types de variable est la suivante :

• Décimal -- 24 chiffres, 9 positions décimales
• Alphanumérique -- 32767 octets
• Logique -- 1 octet
• Entier -- 8 octets pour CL ILE, 4 octets pour CL OPM
• Entier non signé -- 8 octets pour CL ILE, 4 octets pour CL OPM
• En virgule flottante -- 8 octets

Remarque :Lorsque les attributs supplémentaires (Type,Longueur,Nombre de positions décimales) pour le paramètre sont spécifiés, le compilateur crée une valeur temporaire définie par ces attributs. Lorsque ces attributs supplémentaires de valeur temporaire ne sont pas identiques à ceux de la valeur de paramètre, une troncature est effectuée. Par exemple, si la constante numérique 1234.45 est transmise avec la valeur (*INT 4) spécifiée, la partie décimale sera tronquée ; si la longueur du résultat intermédiaire de l'expression de type alphanumérique est supérieure à celle de l'attribut Longueur spécifié, la partie la plus longue sera tronquée.

Exemples

Exemple 1 : Appel d'un programme sans aucun paramètre

CALL   PGM(PAYROLL)

Le programme nommé PAYROLL est appelé sans que des paramètres lui aient été transmis. La liste des bibliothèques est utilisée pour localiser le programme appelé.

Exemple 2 : Transmission d'une constante alphanumérique avec un type et une longueur par défaut

CALL   PGM(PAYROLL)  PARM('1')

Le programme nommé PAYROLL est appelé avec une constante alphanumérique transmise comme chaîne entre apostrophes. Le programme doit déclarer une zone contenant jusqu'à 32 caractères pour recevoir la constante. La liste des bibliothèques est utilisée pour localiser le programme appelé.

Exemple 3 : Transmission de paramètres avec des types et des longueurs par défaut

CALL   PGM(LIB1/PAYROLL)  PARM(CHICAGO 1234 &VAR1)

Le programme nommé PAYROLL situé dans la bibliothèque LIB1 est appelé. Le programme appelant transmet trois paramètres : la constante alphanumérique 'CHICAGO' est transmise sous forme de 32 octets, la constante numérique 1234 est transmise sous forme de valeur décimale condensée avec 15 chiffres au total et 5 chiffres décimaux (15 5), et le contenu de la variable CL &VAR1. Les attributs de la variable CL déterminent ceux du troisième paramètre.

Exemple 4 : Appel d'un programme avec des constantes en virgule flottante et des types et des longueurs par défaut

CALL   PGM(PGM1)  PARM(1.5E3 *INF)

Le programme nommé PGM1 est appelé avec les deux valeurs en virgule flottante à double précision qui lui sont transmises.

Exemple 5 : Transmission de paramètres avec des types et des longueurs explicites

CALL   PGM(LIB1/MYPGM)  PARM(('ABC' (*CHAR 50)) +
                             (1234 (*DEC 12 2)) &VAR1)

Le programme nommé MYPGM situé dans la bibliothèque LIB1 est appelé. Le programme appelant transmet trois paramètres : la constante alphanumérique 'ABC' est transmise sous forme de 50 octets, la constante numérique 1234 est transmise sous forme de valeur décimale condensée avec 12 chiffres au total et 2 chiffres décimaux (12 2), et le contenu de la variable CL &VAR1. Les attributs de la variable CL déterminent ceux du troisième paramètre.

Exemple 6 : Transmission de paramètres d'expression avec des types et des longueurs par défaut

CALL PGM(QSYS/QCMDEXC) PARM(&CMD %SIZE(&CMD))

Le programme nommé QCMDEXC situé dans la bibliothèque QSYS est appelé. Le programme appelant transmet deux paramètres : Le contenu de la variable CL &CMD et l'expression numérique %SIZE(&CMD), transmise sous forme de valeur décimale condensée avec 15 chiffres au total et 5 chiffres décimaux (15 5). Les attributs de la variable CL déterminent ceux du premier paramètre.

Exemple 7 : Transmission de paramètres d'expression avec des types et des longueurs explicites

CALL   PGM(LIB1/MYPGM) +
       PARM((%SST(&VAR1 5 2) (*CHAR 50)) +
            ((&VAR2 + 1) (*DEC 12 2)))

Le programme nommé MYPGM situé dans la bibliothèque LIB1 est appelé. Le programme appelant transmet deux paramètres : L'expression alphanumérique %SST(&VAR1 5 2) est transmise sous forme de chaîne alphanumérique de 50 octets, l'expression numérique (&VAR2 + 1) est transmise sous forme de valeur décimale condensée avec 12 chiffres au total et 2 chiffres décimaux (12 2).

Exemple 8 : Appel d'un programme avec des constantes en virgule flottante et des types et des longueurs explicites

CALL   PGM(PGM1)  PARM((1.5E3 (*FLT 4)) (*INF (*FLT 4)))

Le programme nommé PGM1 est appelé avec les deux valeurs en virgule flottante simple précision qui lui sont transmises.

Exemple 9 : Transmission de paramètres d'expression avec des types et des longueurs explicites

CALL PGM(QSYS/QCMDEXC) PARM((&CMD *DFT) (%SIZE(&CMD) (*INT 4)))

Le programme nommé QCMDEXC situé dans la bibliothèque QSYS est appelé. Le programme appelant transmet deux paramètres : Le contenu de la variable CL &CMD et l'expression numérique %SIZE(&CMD), transmise sous forme de nombre entier de 4 octets. Les attributs de la variable CL déterminent ceux du premier paramètre.

Exemple 10 : Appel d'un programme dans un nouveau travail avec un type et une longueur de paramètre par défaut

SBMJOB  CMD(CALL PGM(PAYLIB/PAYROLL) +
            PARM(&LASTNAME &FIRSTNAME &DEPT &SALARY))

Le programme nommé PAYROLL situé dans la bibliothèque PAYLIB est appelé. Le programme appelant transmet quatre paramètres qui sont convertis en constantes lorsque la commande SBMJOB est exécutée. En admettant que les variables &LASTNAME, &FIRSTNAME et &DEPT soient déclarées en tant que variables alphanumériques (*CHAR) dans le programme appelant, les constantes alphanumériques seront transmises alignées à gauche et complétées par des blancs si la valeur de variable est inférieure à 32. Par exemple, si &LASTNAME a pour valeur 'SMITH' lorsque la commande SBMJOB est exécutée, la valeur 'SMITH' complétée par 27 blancs est transmise en tant que valeur de paramètre. Si le programme appelé s'attend à ce que le premier paramètre soit transmis sous forme de 50 octets, un problème se pose si les octets 33 à 50 sont référencés. Si le paramètre &SALARY est déclaré comme *DEC avec LEN(12 2) avec la valeur 1500.00 lorsque la commande SBMJOB est exécutée, la valeur sera convertie en constante numérique et transmise en tant que valeur décimale condensée avec 15 chiffres au total et 5 chiffres décimaux. Le programme appelé doit être codé pour s'attendre à ce que le paramètre soit une valeur décimale condensée avec 15 chiffres au total et 5 chiffres décimaux.

Exemple 11 : Appel d'un programme dans un nouveau travail avec des types et des longueurs de paramètre explicites

SBMJOB  CMD(CALL PGM(PAYLIB/PAYROLL) +
            PARM((&LASTNAME (*CHAR 50)) +
                 (&FIRSTNAME (*CHAR 40)) +
                 &DEPT +
                 (&SALARY (*DEC 12 2))))

Le programme nommé PAYROLL situé dans la bibliothèque PAYLIB est appelé. Le programme appelant transmet quatre paramètres qui sont convertis en constantes lorsque la commande SBMJOB est exécutée. En admettant que les variables &LASTNAME, &FIRSTNAME et &DEPT soient déclarées en tant que variables alphanumériques (*CHAR) dans le programme appelant, les constantes alphanumériques seront transmises alignées à gauche. Etant donné que des types et des longueurs explicites sont spécifiés, le stockage utilisé pour ces paramètres de type constante alphanumérique sera complété par des blancs pour atteindre la longueur spécifiée. Par exemple, 50 octets sont transmis pour la constante alphanumérique créée à partir de la valeur de variable &LASTNAME et 40 octets sont transmis pour la constante alphanumérique créée à partir de la valeur de variable &FIRSTNAME. La constante alphanumérique créée à partir de la variable &DEPT sera transmise à l'aide de la longueur par défaut ; par exemple, si la valeur &DEPT est '123A', elle sera complétée par 28 blancs. La valeur de paramètre &SALARY sera convertie en constante numérique et transmise en tant que valeur décimale condensée avec 12 chiffres au total et 2 chiffres décimaux.

Messages d'erreur

Messages *ESCAPE

CPD0783

La variable &3 pour &2 doit être TYPE(*DEC), LEN(&4,&5).

CPF0005

La chaîne de commande retournée dépasse la longueur de variable fournie.

CPF0006

Erreurs trouvées dans la commande.

CPF0805

Erreur lors de l'appel du programme &1 de &2.

CPF0806

Erreur lors du démarrage de la procédure.