RTVMSG

La commande RTVMSG (Extraire un message) s'utilise dans un programme CL ou une procédure REXX pour extraire un message prédéfini d'un fichier message et le copier dans des variables CL. Des valeurs de substitution peuvent être spécifiées dans le paramètre MSGDTA (sous la forme d'une chaîne de caractères unique contenant une ou plusieurs zones de données de messages concaténées) pour remplacer les variables de substitution dans le texte de message prédéfini. Par la suite, le programme peut écrire le message sur une unité de sortie, en vue de son impression par exemple.

L'invite CL correspondant à cette commande indique la longueur minimale pour les variables extraites en regard des paramètres auxquels est associée une valeur minimale. Pour les variables de type caractère, un seul nombre s'affiche. Pour les variables décimales, deux nombres s'affichent. Le premier nombre indique la longueur de variable minimale et le second le nombre minimal de positions décimales.

Restrictions : L'utilisateur de cette commande doit disposer des droits d'utilisation (*USE) sur le fichier message et la bibliothèque dans laquelle il est stocké.

Paramètres

Identificateur de message (MSGID)

Précise l'identificateur du message qui doit être extrait du fichier message indiqué.

Ce paramètre est obligatoire.

fichier message (MSGF)

Indique le fichier message contenant le message prédéfini qui doit être extrait.

Ce paramètre est obligatoire.

Qualificatif 1 : fichier message

nom

Indiquez le nom du fichier message contenant le message qui doit être extrait.

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 fichier message est recherché dans la bibliothèque en cours du travail. Si celle-ci ne figure pas dans la liste des bibliothèques, QGPL est prise par défaut.

nom

Entrez le nom de la bibliothèque contenant le fichier message.

Valeurs zone donnée de msg (MSGDTA)

Indique les valeurs de substitution utilisées dans le message extrait. Vous pouvez indiquer une chaîne de caractères ou la variable CL contenant cette chaîne.

Vous pouvez spécifier autant de valeurs de substitution dans la chaîne que de variables de substitution dans la description du message prédéfini. Les valeurs, remplaçant les variables de substitution dans le texte de message, doivent être spécifiées par les règles suivantes :

• Plusieurs valeurs doivent être concaténées pour former une seule chaîne de caractères. La longueur totale de la chaîne de caractères des valeurs de substitution concaténées ne doit pas dépasser 512 caractères.
• Plusieurs valeurs de la chaîne de caractères doivent être spécifiées dans le même ordre que les variables de substitution définies dans le paramètre FMT de la commande ADDMSGD.
• Chaque valeur doit être indiquée avec la longueur de la variable associée dans la description de message. La chaîne spécifiée doit être de même longueur que la totalité des zones de données de message dans la description de message.
• Dans le cas de valeurs multiples, chaque valeur de substitution peut être spécifiée en tant que constante de programme CL ou variable CL. N'importe quelle combinaison de constantes et de variables peut donc être spécifiée si ces dernières sont concaténées en une chaîne, puis exprimées dans un format et une séquence prévus par la description de message.
• La longueur de la valeur de substitution doit être identique à celle définie pour les variables de substitution. Si la longueur de la valeur de substitution est supérieure à celle de la variable de substitution , les données de message sont tronquées. Si la valeur de substitution est plus courte, elle devient une zone indéfinie.
• Le système considère que les données de message fournies correspondant à une zone de type *CCHAR ont pour CCSID celui du travail exécutant cette commande, sauf si le paramètre MDTACCSID est spécifié. Pour plus d'informations sur la zone de type *CCHAR, reportez-vous à la description de la commande ADDMSGD.

Pour plus d'informations sur le codage de ce paramètre, reportez-vous à la description du paramètre MSGDTA dans la commande SNDPGMMSG.

Variable texte de 1er niveau (MSG)

Indique le nom de la variable CL de type caractère dans laquelle est renvoyé le texte du message extrait. Si un nom de variable CL n'est pas spécifié, le texte de message n'est pas renvoyé au programme. La longueur de cette zone n'est pas fixe, mais la plupart des messages ne dépassent pas 132 caractères.

Variable pour MSGLEN (5 0) (MSGLEN)

Indique le nom de la variable décimale CL dans laquelle est renvoyée la longueur totale du texte de message pouvant être extrait. La longueur renvoyée correspond à la longueur totale une fois que les valeurs de substitution (indiquées au paramètre MSGDTA) sont placées dans le texte.

La variable décimale indiquée doit comporter 5 chiffres.

Variable texte de 2e niveau (SECLVL)

Indique le nom de la variable CL de type caractère dans laquelle est renvoyé le texte de message de deuxième niveau ou l'aide-message du message extrait. Si un nom de variable n'est pas spécifié, l'aide-message n'est pas renvoyée au programme. La longueur de cette zone n'est pas fixe, mais la plupart des aides message ne dépassent pas 3000 caractères.

Variable pour SECLVLLEN (5 0) (SECLVLLEN)

Indique le nom de la variable décimale CL dans laquelle est renvoyée la longueur totale de l'aide-message en cours d'extraction. La longueur renvoyée correspond à la longueur totale une fois que les valeurs de substitution (indiquées au paramètre MSGDTA) sont placées dans le texte de message de deuxième niveau.

La variable décimale indiquée doit comporter cinq positions.

Variable pour SEV (2 0) (SEV)

Indique le nom de la variable décimale CL dans laquelle est renvoyé le code de gravité du message extrait. La variable décimale indiquée doit comporter deux positions. Si un nom de variable n'est pas spécifié, le code de gravité du message extrait n'est pas renvoyé au programme.

Variable pour ALROPT (9) (ALROPT)

Indique le nom de la variable CL dans laquelle est renvoyée l'option d'alerte du message extrait. Cette variable doit comporter neuf positions. Si une variable de type caractère n'est pas spécifiée, l'option d'alerte du message extrait n'est pas renvoyée au programme.

Variable pour LOGPRB (1) (LOGPRB)

Indique si le message sera consigné dans l'historique des incidents. Cette variable alphanumérique doit avoir une longueur de 1 position. Les valeurs renvoyées sont O (Oui) ou N (Non).

Convertir en CCSID (CCSID)

Indique l'ID codé de jeu de caractères (CCSID) dans lequel vous souhaitez que le texte de votre message soit renvoyé. Ce CCSID s'applique uniquement au texte renvoyé dans les paramètres MSG et SECLVL. Lorsque les données de remplacement sont substituées dans le texte renvoyé aux paramètres MSG ou SECLVL, seule la partie des données de remplacement définie comme caractère convertible (*CCHAR) est convertie. Pour plus d'informations sur la zone *CCHAR, reportez-vous à la commande ADDMSGD (Ajouter une description de message).

*JOB

Avant d'être renvoyée, la description de message extraite est convertie au CCSID du travail.

*HEX

Avant d'être renvoyée, la description de message extraite n'est pas convertie.

ID-codé-jeu-caractères

Indiquez le CCSID dans lequel vous souhaitez que le CCSID de la description de message soit converti avant que cette dernière soit renvoyée.

Remarque :Les valeurs admises sont comprises entre 1 et 65535. La liste des valeurs de CCSID admises est fournie dans le manuel Internationalisation de l'iSeries Information Center, à l'adresse http://www.ibm.com/eserver/iseries/infocenter. Seuls sont acceptés les CCSID possibles pour votre travail.

Pour plus d'informations sur le gestionnaire des messages et la manière dont ce dernier utilise les CCSID, reportez-vous au manuel Rubriques Internationalisation de l'i5/OS dans l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

CCSID de données de message (MDTACCSID)

Indique le CCSID dans lequel le système considérera que sont les données de message fournies. Ceci s'applique uniquement aux parties des données de remplacement définies comme *CCHAR. Le reste des données de remplacement ne sera jamais converti et le système considérera que leur CCSID est égal à 65535.

*JOB

Le système considère que les données de message fournies ont pour CCSID celui du travail exécutant cette commande.

*HEX

Le système considère que les données de message fournies sont dans le CCSID 65535 et ne les convertit en aucun cas.

ID-codé-jeu-caractères

Le système considère que les données de message ont pour CCSID celui indiqué. Les valeurs admises sont comprises entre 1 et 65535. La liste des valeurs de CCSID admises est fournie dans le manuel Internationalisation de l'iSeries Information Center, à l'adresse http://www.ibm.com/eserver/iseries/infocenter.

Var pour CCSID texte (5 0) (TXTCCSID)

Indique, le cas échéant, le nom de la variable CL renvoyant l'ID codé de jeu de caractères (CCSID) associé au texte renvoyé par les paramètres MSG et SECLVL. Le CCSID dans lequel la description de message est stockée est renvoyé dans l'un des cas suivants :

• Si une erreur de conversion se produit.
• Si le CCSID du travail a la valeur 65535 et que vous n'avez pas indiqué le paramètre CCSID.
• Si vous indiquez la valeur *JOB au paramètre CCSID.
• Si le CCSID dans lequel vous avez demandé la conversion du texte est 65535.

Sinon, le CCSID dans lequel vous souhaitiez convertir le texte est renvoyé. Si vous ne voulez pas que le texte soit converti avant son renvoi mais que vous voulez connaître dans quel CCSID la description de message est stockée, indiquez 65535 au paramètre CCSID. Le CCSID dans lequel la description de message est stockée est renvoyé au paramètre TXTCCSID. Vous pouvez également rechercher une éventuelle erreur de conversion en comparant le CCSID que vous avez transmis avec le paramètre TXTCCSID renvoyé. S'ils ne sont pas identiques et sont différents de 65535, une erreur de conversion s'est produite.

Var pour CCSID données (5 0) (DTACCSID)

Indique, le cas échéant, le nom de la variable CL renvoyant l'ID codé de jeu de caractères (CCSID) associé aux données de remplacement auxquelles la valeur *CCHAR a été attribuée. Les autres données de remplacement ne sont pas converties avant d'être renvoyées. Le CCSID indiqué au paramètre MDTACCSID est renvoyé dans l'un des cas suivants :

• Si une erreur de conversion se produit.
• Si le CCSID du travail a la valeur 65535 et que vous n'avez pas indiqué le paramètre CCSID.
• Si vous indiquez la valeur *JOB au paramètre CCSID.
• Si le CCSID dans lequel vous avez demandé la conversion du texte est 65535.

Sinon, le CCSID dans lequel vous souhaitiez que le texte soit converti est renvoyé. Lorsqu'il n'existe aucune donnée de remplacement *CCHAR dans le texte, 65535 est renvoyé. Vous pouvez rechercher une erreur de conversion en comparant le CCSID que vous avez transmis avec le paramètre DTACCSID renvoyé. S'ils ne sont pas identiques et sont différents de 65535, une erreur de conversion s'est produite.

Exemples

Exemple 1 : Remplacement des variables de substitution

RTVMSG   MSGID(UIN0145)  MSGF(INVN)  MSG(&WORK)
         MSGDTA('quand vous voulez')

Cette commande extrait le texte du message UIN0145 stocké dans le fichier message INVN. Le texte extrait est copié dans la variable CL &WORK une fois que les variables de substitution sont remplacées par les valeurs quand, vous et voulez. Cet exemple part du principe que les variables de substitution &1, &2 et &3 ont été définies dans le message en tant que variables caractères, chacune comportant 4 caractères.

Exemple 2 : Extraction de texte de message de premier et de second niveau

RTVMSG   MSGID(UIN0150)  MSGF(INV)  MSG(&MSG)
         SECLVL(&SECLVL)

Cette commande extrait le texte de message de premier niveau et de second niveau du message UIN0150, qui est stocké dans le fichier message INV, puis le place dans les variables CL &MSG et &SECLVL.

Messages d'erreur

Messages *ESCAPE

CPF2401

Accès non autorisé à la bibliothèque &1.

CPF2407

fichier message &1 non trouvé dans &2.

CPF2411

Accès non autorisé au fichier message &1 dans &2.

CPF247E

Le CCSID &1 est incorrect.

CPF2471

Longueur de zone incorrecte.

CPF2499

L'identificateur de message &1 n'est pas valide.

CPF2531

fichier message &1 de &2 endommagé pour &3.

CPF2547

fichier message QCPFMSG endommagé.

CPF2548

fichier message &1 dans &2 endommagé.

CPF8126

fichier message &4 de &9 endommagé.

CPF9830

Allocation de la bibliothèque &1 impossible.

Messages *STATUS

CPF2419

Identificateur &1 non trouvé dans fichier message &2 de &3.

Messages *NOTIFY

CPF2465

Texte de remplacement du msg &1 de &2 dans &3 incorrect pour fmt indiqué.