RTVDTAARA

Extraire une zone de données

En bref

RTVDTAARA se lit RTV (Extraire (récupérer)) + DTAARA. Sur IBM i, le nom d'une commande associe presque toujours un verbe et un objet.

Syntaxe minimale

RTVDTAARA DTAARA(…) RTNVAR(…)

Paramètres

DTAARA Spécification zone de données obligatoire
RTNVAR Variable pour valeur retour obligatoire

Astuce : dans une session 5250, tapez RTVDTAARA puis F4 pour l'invite de saisie, et F1 sur un paramètre pour son aide.

Aide IBM i de la commande

Texte du F1, IBM i 7.5 en français (bibliothèque QSYS)

Où s'exécute : Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)
Compatible multitâche : Sous conditions

La commande RTVDTAARA (Extraire une zone de données) est utilisée dans un programme CL ou REXX pour extraire tout ou partie d'une zone de données indiquée et pour copier le résultat dans une variable. La commande RTVDTAARA ne permet pas d'extraire d'autres attributs de la zone de données. La zone de données n'est pas requise lors de la compilation du programme CL.

Dans le cas d'un travail de groupe, la zone de données spécifiée peut correspondre à la zone de données de groupe (*GDA). Cette zone de données est automatiquement associée au groupe et devient inaccessible aux travaux externes à ce groupe. Cette zone de données de type caractère comporte 512 octets. Pour plus d'informations sur les travaux de groupes, reportez-vous au manuel Ensemble de rubriques Gestion des travaux de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

Une zone de données locale (*LDA) est une zone de données alphanumérique d'une longueur de 1024 octets. Elle est automatiquement associée au travail et n'est accessible que par ce dernier.

Dans le cas d'un travail à démarrage anticipé, la zone de données spécifiée peut être la zone de données contenant les données PIP (*PDA). Cette zone est automatiquement associée au travail à démarrage anticipé et n'est accessible que par ce dernier. La longueur de cette zone de données alphanumérique est 2000 octets. Pour plus d'informations sur les travaux à démarrage anticipé, reportez-vous au manuel Ensemble de rubriques Gestion des travaux de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

Lorsqu'une zone de données non locale, une zone de données de groupe ou une zone de données PIP doit être extraite pendant le traitement de la commande RTVDTAARA, elle est verrouillée pendant toute la durée de l'opération d'extraction, de sorte que les commandes des autres travaux ne peuvent ni la modifier ni la détruire avant la fin du traitement. Si la zone de données est partagée avec d'autres travaux et que sa mise à jour s'effectue à l'aide de plusieurs commandes d'un travail, elle doit être affectée de manière explicite à ce travail jusqu'à la fin du traitement. Aucune allocation n'est requise pour les zones de données locales, de groupe ou PIP. Pour les autres zones, l'allocation s'effectue de manière explicite à l'aide de la commande ALCOBJ (Allouer un objet). Aucune allocation n'est nécessaire pour les zones de données non locales, de groupe ou de paramètre d'initialisation de programme.

La fonction de table et la vue QSYS2.DATA_AREA_INFO renvoient des informations similaires.

Restrictions

Pour utiliser cette commande, l'utilisateur doit disposer du droit d'utilisation (*USE) sur la zone de données et du droit d'exécution (*EXECUTE) sur la bibliothèque de stockage des données. Aucun droit spécifique n'est requis pour extraire la valeur d'une zone de données locale ou d'une zone de données de groupe.
Cette commande est à unités d'exécution protégées sous certaines conditions. Les restrictions suivantes s'appliquent :
1. L'extraction de zones de données DDM dans un travail qui admet les unités d'exécution multiples n'est pas à unités d'exécution protégées.
2. L'extraction de zones de données DDM échoue lorsque plusieurs unités d'exécution sont actives dans un travail.

Paramètres

Mot-clé	Description	Valeurs possibles	Remarques
DTAARA	Spécification zone de données	Liste d'éléments	Obligatoire, positionnel 1
	Élément 1: Zone de données	Valeurs uniques: LDA, GDA, PDA Autres valeurs: Nom d'objet qualifié*
	Qualificatif 1: Zone de données	Nom
	Qualificatif 2: Biblio	Nom, LIBL, CURLIB
	Élément 2: Spécifications de sous-chaîne	Valeurs uniques: ALL Autres valeurs: Liste d'éléments*
	Élément 1: Position de début sous-chaîne	1-2000
	Élément 2: Longueur sous-chaîne	1-2000
RTNVAR	Variable pour valeur retour	Sans restriction	Obligatoire, positionnel 2

Spécification zone de données (DTAARA)

Indique le nom de la zone de données dont la valeur doit être extraite.

Ce paramètre est obligatoire.

Elément 1 : Zone de données

Valeurs uniques

*LDA: Valeur extraite de la zone de données locale.
*GDA: Extraction de la valeur de la zone de données de groupe. Cette valeur n'est admise que si le travail est un travail de groupe.
*PDA: Extraction de la valeur de la zone de données du paramètre d'initialisation de programme. Cette valeur n'est admise que si le travail est un travail à démarrage anticipé.

Qualificatif 1 : Zone de données

nom: Indiquez le nom de la zone de données.

Qualificatif 2 : Biblio

*LIBL: La recherche porte sur toutes les bibliothèques de l'unité d'exécution jusqu'à ce que la première occurrence soit trouvée.
*CURLIB: La bibliothèque en cours pour l'unité d'exécution permet de localiser l'objet. Si celle-ci n'est indiquée, QGPL est prise par défaut.

nom: Indiquez le nom de la bibliothèque contenant la zone de données.

Elément 2 : Spécifications de sous-chaîne

Valeurs uniques

*ALL: Extraction de l'intégralité de la zone de données.

Elément 1 : Position de début sous-chaîne

1-2000: Indiquez la position de début de la zone de données à extraire.

Elément 2 : Longueur sous-chaîne

1-2000: Indiquez la longueur de la sous-chaîne de zone de données à extraire. Il est impossible d'extraire des données en dehors de la zone de données. Par conséquent, indiquez une position de début et une longueur correspondant toujours à des positions au sein de la zone de données.

Variable pour valeur retour (RTNVAR)

Indique le nom de la variable qui reçoit le contenu de la zone de données.

Aucune conversion de type n'est effectuée par la commande RTVDTAARA :

Si RTNVAR a pour valeur TYPE(*DEC), la zone de données extraite doit être TYPE(*DEC).
Si RTNVAR a pour valeur TYPE(*CHAR), la zone de données extraite doit être TYPE(*CHAR) ou TYPE(*LGL).
Si RTNVAR a pour valeur TYPE(*LGL), la zone de données extraite doit être TYPE(*LGL) ou TYPE(*CHAR) avec une valeur "0" ou "1".

Si la chaîne extraite est d'une longueur inférieure à celle de la variable indiquée au paramètre RTNVAR, elle est complétée de blancs à droite. La longueur de la chaîne extraite doit être inférieure ou égale à celle de la variable.

En cas d'extraction d'une zone de données décimale, les positions décimales sont alignées. La valeur de la partie entière doit tenir dans la partie correspondante dans la variable. La fraction est tronquée si elle comporte plus de chiffres que la partie correspondante dans la variable.

Ce paramètre est obligatoire.

valeur-non-restreinte: Indique le nom de la variable de programme qui reçoit le contenu de la zone de données.

Exemples

La zone de données utilisée DA1 a été créée par la commande suivante :

CRTDTAARA   DTAARA(DA1)  TYPE(*CHAR)  LEN(3)  VALUE(ABC)

et la variable &CLVAR1 a été déclarée ainsi :

DCL   VAR(&CLVAR1)  TYPE(*CHAR)  LEN(5)  VALUE(VWXYZ)

Exemple 1 : extraction d'une zone de données alphanumérique

RTVDTAARA   DTAARA(DA1)  RTNVAR(&CLVAR1)

résultat :

&CLVAR1 = 'ABC  '

Exemple 2: extraction d'un sous-ensemble d'une zone de données alphanumérique

RTVDTAARA   DTAARA(DA1 (2 1))  RTNVAR(&CLVAR1)

résultat :

&CLVAR1 = 'B    '

Exemple 3: extraction d'une zone de données décimale

La zone de données utilisée DA2 a été créée avec les attributs suivants :

CRTDTAARA   DTAARA(DA2)  TYPE(*DEC)  LEN(5 2)  VALUE(12.39)

et la variable &CLVAR2 a été déclarée ainsi :

DCL   VAR(&CLVAR2)  TYPE(*DEC)  LEN(5 1)  VALUE(4567.8)

Exécution de la commande :

RTVDTAARA   DTAARA(DA2)  RTNVAR(&CLVAR2)

résultat :

&CLVAR2 = 0012.3

Remarque : les chiffres fractionnaires sont tronqués au lieu d'être arrondis.

Messages d'erreur

Messages *ESCAPE

CPF0811: Longueur du paramètre RTNVAR incorrecte pour la zone de données.
CPF0812: Type du paramètre RTNVAR incorrect pour la zone de données &1.
CPF0813: Valeur non logique pour la zone de données &1.
CPF101A: L'opération sur la zone de données DDM &1 de &2 a échoué.
CPF1015: Zone de données &1 non trouvée dans &2.
CPF1016: Non autorisé à utiliser la zone de données &1 de &2.
CPF1021: Bibliothèque &1 non trouvée pour zone de données &2.
CPF1022: Non autorisé à bibliothèque &1 pour zone de données &2.
CPF1043: L'alignement sur une limite pour la zone de données n'est pas valide. Boundary alignment for data area not valid.
CPF1044: Le paramètre AREA n'est pas valide pour la zone de données. AREA parameter not valid for data area.
CPF1045: Le paramètre CPYPTR n'est pas valide pour la zone de données. CPYPTR parameter not valid for data area.
CPF1046: DTAARA(*GDA) admis uniquement pour travaux de groupe.
CPF1063: Impossible d'allouer la zone de données &1 dans &2.
CPF1067: Impossible d'allouer la bibliothèque &1.
CPF1072: Paramètre DTAARA(*PDA) incorrect car il ne s'agit pas d'un travail anticipé.
CPF1087: Sous-chaîne non permise pour zone de données décimale ou logique.
CPF1088: Position de début à l'extérieur de la zone de données.
CPF1089: Sous-chaîne incorrecte pour zone de données.
CPF180B: Fonction &1 non admise.
CPF9899: Erreur lors du traitement de la commande.