ADDTRC

La commande ADDTRC (Ajouter une trace au débogage) indique quelles instructions dans un programme doivent faire l'objet d'une trace en mode débogage. Jusqu'à 5 plages d'instructions en langage évolué ou d'instructions machine peuvent être ainsi définies à l'aide d'une ou de plusieurs commandes ADDTRC (Ajouter une trace au débogage), et jusqu'à 10 variables de programme peuvent être enregistrées ou soumises à modification au sein de chaque plage d'instructions. Chaque variable associée à une plage d'instructions nécessite une commande séparée ADDTRC (Ajouter une trace au débogage). Lors de l'exécution du programme faisant l'objet d'une trace, le système enregistre la séquence dans laquelle les instructions sont traitées, et éventuellement la valeur des variables associées à la trace. A l'issue de la trace, vous pouvez afficher ces informations à l'aide de la commande DSPTRCDTA (Afficher les résultats de trace).

Toutes les plages de trace définies dans un programme sont actives simultanément. Si un numéro d'instruction HLL (en langage évolué) et un numéro d'instruction machine sont utilisés conjointement pour définir une plage de trace, celle-ci sera traitée comme plage de trace HLL. En d'autres termes, le système effectue la trace du numéro d'instruction machine indiqué, ainsi que des numéros d'instructions HLL compris entre cette instruction machine et l'instruction HLL mentionnée. Pour plus de détails sur le test et le débogage au niveau de l'interface machine, reportez-vous au manuel Rubriques CL de la catégorie Programmation de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

Restrictions :

• Vous pouvez utiliser cette commande uniquement en mode débogage. Pour démarrer le mode débogage, utilisez la commande STRDBG.
• Vous ne pouvez pas utiliser cette commande si vous faites la maintenance d'un autre travail et si celui-ci est dans une file d'attente de travaux, ou bien s'il est suspendu, interrompu ou arrêté.

• Vous ne pouvez pas utiliser cette commande pour tracer des programmes liés.

Paramètres

Instructions à tracer (STMT)

Indique les instructions programme (ou instructions machine) qui doivent faire l'objet d'une trace dans le programme.

*ALL

La trace porte sur toutes les instructions du programme en langage évolué indiqué.

*ALLINST

La trace porte sur toutes les instructions machine du programme indiqué.

numéro-instruction-début numéro-instruction-fin

Indiquez les numéros d'instructions HLL (langage évolué) ou les numéros d'instructions machine à partir desquels la trace commence et éventuellement de ceux où elle finit. 5 plages de trace au maximum peuvent être définies simultanément pour tout programme en mode débogage. Chaque plage de trace commence par l'instruction de début définie et toutes les instructions suivantes sont tracées jusqu'à l'instruction de fin. En l'absence de cette dernière, seule l'instruction constituant l'instruction de début est traitée. Tout numéro d'instruction machine doit être précédé d'une barre oblique, et figurer entre apostrophes (y compris la barre oblique).

Dans les programmes en langage évolué, plusieurs instructions et/ou labels peuvent être mappés à la même instruction interne, notamment lorsque plusieurs instructions qui n'interviennent pas directement sur les variables (DO, END ou commentaires par exemple) se suivent dans un programme. Pour déterminer les instructions et labels pouvant être mappés à la même instruction, utilisez le listage IRP (Représentation intermédiaire d'un programme).

Variables du programme (PGMVAR)

Indique les noms des variables dont les valeurs sont enregistrées lorsqu'une instruction à tracer est traitée dans un programme. Selon la valeur entrée au paramètre Quand sortir (OUTVAR), ces valeurs sont enregistrées pour chaque instruction à tracer traitée ou seulement lorsque la valeur d'une variable change. Les variables d'un programme peuvent être représentées par leur nom HLL (langage évolué) ou par leur numéro MI ODV.

Valeurs uniques

*NONE

Aucune valeur de variable de programme n'est enregistrée lors de la trace.

Autres valeurs (jusqu'à 10 répétitions)

Elément 1 : Variable programme

*CHAR

Cette valeur spéciale peut être indiquée à la place d'un nom de variable si un pointeur de base est également indiqué. Elle présente une vue alphabétique d'un pointeur à afficher sans l'utilisation d'une variable de base.

valeur-caractère

Indiquez les noms de 10 variables de programme au maximum dont les valeurs sont enregistrées lors de la trace. Si le nom d'une variable contient des caractères spéciaux, il doit figurer entre apostrophes.

Si la variable de programme est un tableau, les indices représentant les éléments du tableau peuvent être spécifiés. Lorsqu'un nom de tableau est indiqué sans indice, tous les éléments du tableau sont enregistrés. Il est également possible de définir un sous-tableau à une dimension. Cette variable de programme ne doit pas dépasser 132 caractères. Ce nombre comprend les qualifiants, indices, blancs, parenthèses et virgules. Ce nombre comprend les qualifiants, indices, blancs, parenthèses et virgules, à l'exclusion des apostrophes lorsque des caractères spéciaux sont utilisés. Un indice peut être un entier, un numéro MI ODV, un astérisque (sous-tableau à une dimension) ou encore un nom de variable numérique.

Pour plus d'informations, reportez-vous à la rubrique "Parameter values used for testing and debugging" de "CL concepts and reference" dans le manuel Rubriques CL de la catégorie Programmation de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

Elément 2 : Variable de pointeur base

valeur-caractère

Indiquez un maximum de cinq pointeurs de base pour chaque variable de programme spécifiée pour l'élément 1 de ce paramètre. Dans certains langages, la variable de programme peut être basée sur une variable de pointeur. Cet ensemble de valeurs vous permet de spécifier des pointeurs de base pour la variable à enregistrer. Tout nom de pointeur de base contenant des caractères spéciaux doit figurer entre apostrophes.

Si le pointeur de base est un tableau, les indices représentant un élément du tableau doivent être précisés. Le nom d'un pointeur de base ne doit pas dépasser 132 caractères. Ce nombre comprend les qualifiants, indices, blancs, parenthèses et virgules. Ce nombre comprend les qualifiants, indices, blancs, parenthèses et virgules, à l'exclusion des apostrophes lorsque des caractères spéciaux sont utilisés. Un indice peut être un entier, un numéro MI ODV ou encore un nom de variable numérique.

Pour plus d'informations, reportez-vous à la rubrique "Parameter values used for testing and debugging" de "CL concepts and reference" dans le manuel Rubriques CL de la catégorie Programmation de l'IBM i Information Center, à l'adresse http://www.ibm.com/systems/i/infocenter/.

Format de sortie (OUTFMT)

Indique le format dans lequel doivent être enregistrées des variables.

*CHAR

Enregistre les variables en format caractère.

*HEX

Enregistre les variables en format hexadécimal.

Programme (PGM)

Désigne le programme contenant les numéros des instructions ou d'instructions machine indiqués à tracer.

*DFTPGM

Le programme précédemment défini comme programme par défaut contient les instructions à tracer.

nom

Indiquez le nom du programme qui contient les instructions devant faire l'objet d'une trace. Ce programme doit déjà être en mode débogage.

Position de début sortie (START)

Indique, dans le cas de variables de chaîne seulement, la première position, dans la chaîne, dont la valeur doit être enregistrée lors de la trace (position de début). Lorsque plusieurs variables de chaîne sont définies pour le paramètre Variables du programme (PGMVAR), la même valeur de départ est utilisée pour chacune. Selon le type de chaîne (binaire ou caractères), la position de début correspond à une valeur binaire ou à un caractère de début.

1

La variable est enregistrée à partir de la première position, en respectant la longueur définie au paramètre Caractères à afficher ( LEN).

entier

Indiquez la première position enregistrée dans la variable de programme.

La valeur entrée au paramètre Position de début sortie (START) ne doit pas être supérieure à la longueur maximale des variables de chaîne indiquées. Cependant, si la longueur maximale d'une chaîne est égale à 0, la valeur 1 est admise en réponse au paramètre START. La valeur entrée pour le paramètre LEN, plus la valeur indiquée pour le paramètre START, moins un, ne doit pas dépasser la longueur maximale de chaîne. Toute variable de chaîne indiqué pour le paramètre PGMVAR est soumise à cette vérification.

Caractères à afficher (LEN)

Indique, pour les variables de chaîne seulement, la longueur de la chaîne à enregistrer lors de la trace, à partir de la position définie au paramètre Position de début sortie ( START). Lorsque plusieurs variables de chaîne sont définies pour le paramètre Variables du programme (PGMVAR), la même valeur est utilisée pour chacune. La longueur ainsi définie correspond au nombre de bits ou de caractères qui s'affichent, selon le type de la chaîne (caractères ou binaire).

*DCL

La variable de chaîne s'affiche jusqu'à la fin de la chaîne si elle ne dépasse pas 200 octets. Si la longueur maximale de la variable de chaîne est égale à 0, la seule valeur admise au paramètre Caractères à afficher ( LEN) est *DCL.

entier

Indiquez la longueur des données à afficher. Cette valeur( ainsi que la combinaison des valeurs entrées pour les paramètres START et LEN, ne doit pas être supérieure à la longueur de la plus petite chaîne définie par la valeur du paramètre PGMVAR.

Quand sortir (OUTVAR)

Précise si les valeurs des variables de programme doivent être enregistrées systématiquement ou uniquement lorsque leur valeur change. Ce paramètre est ignoré si *NONE est spécifié ou pris par défaut au paramètre Variables du programme ( PGMVAR).

Remarque :Pour chaque plage, les valeurs de toutes les variables soumises à la trace sont systématiquement enregistrées la première fois qu'une instruction de la plage est traitée. La valeur entrée sur le paramètre OUTVAR détermine à quel moment les variables sont enregistrées pour toutes les instructions suivantes de la plage.

*CHG

Le système enregistre les valeurs de toutes les variables de programme lorsqu'au moins une valeur a changé depuis le dernier point de trace. Une variable est considérée comme modifiée lorsque sa valeur ou l'un de ses attributs (longueur, limite supérieure ou inférieure, indices) a été modifié. Par exemple, un tableau dont la limite supérieure aurait changé est considéré comme modifié.

Remarque :Une valeur qui a été modifiée peut sembler inchangée si elle contient des caractères ne pouvant être affichés (si leur valeur hexadécimale est inférieure à 40). La valeur est enregistrée, même si vous ne pouvez constater la modification. Si *HEX est entré au paramètre Format de sortie ( OUTFMT), les modifications peuvent être observées dans les données de trace.

*ALWAYS

Le système enregistre les valeurs des variables spécifiées, qu'elles aient été modifiées ou non, chaque fois qu'une instruction est tracée.

Programme de gestion de trace (TRCPGM)

Indique le programme fourni par l'utilisateur qui est appelé lorsqu'une instruction faisant l'objet d'une trace est trouvée dans le programme indiqué au paramètre Programme ( PGM). Le programme qui contient l'instruction soumise à une trace passe des paramètres d'information au programme de gestion de trace lorsque celui-ci est appelé. Ces paramètres définissent le nom du programme, le niveau de récursivité, l'identificateur d'instruction en langage évolué, le numéro d'instruction machine où a été trouvée l'instruction de trace et un indicateur de variable modifiée. Les paramètres ont les formats suivants :

1. Nom de programme (10 octets). Indique le nom du programme dans lequel l'instruction soumise à une trace a été trouvée.
2. Niveau de récursivité (5 octets). Indique le niveau de récursivité du programme dans lequel l'instruction soumise à une trace a été trouvée. Il s'agit d'un nombre de 1 à 5 chiffres complétés par des blancs à droite.
3. Identificateur d'instruction (10 octets). Indique l'identificateur d'instruction en langage évolué qui a été trouvé. Si l'instruction faisant l'objet d'une trace ne correspond pas à un identificateur d'instruction, le paramètre contient une barre oblique (/) suivie d'une valeur hexadécimale de 4 chiffres correspondant au numéro d'instruction machine.
4. Numéro d'instruction (5 octets). Indique le numéro d'instruction machine correspondant à l'instruction en langage évolué où l'instruction faisant l'objet d'une trace a été trouvée. Ce numéro d'instruction machine n'est précédé d'aucune barre oblique. Il est composé de 4 caractères hexadécimaux représentant le numéro d'instruction machine, suivis d'un ou plusieurs blancs. Si le programme transmet un numéro d'instruction machine au troisième paramètre, les valeurs du troisième et du quatrième paramètre seront identiques.

Toutes les valeurs de paramètre sont alignées à gauche et remplies de blancs à droite. Lorsque le programme comportant l'instruction soumise à une trace reprend le contrôle, le traitement se poursuit.

Lorsqu'un programme de gestion de trace est indiqué ainsi que la valeur OUTVAR(*CHG), ce programme n'est appelé que si une variable de programme indiquée au paramètre Variables du programme (PGMVAR) est modifiée. Aucun résultat de trace n'est enregistré.

Valeurs uniques

*NONE

Aucun programme de gestion de trace n'est appelé lorsqu'un point soumis à une trace indiqué dans cette commande est rencontré dans le cadre d'un environnement de traitement par lots. Le programme interrompu poursuit le traitement.

Qualificatif 1 : Programme de gestion de trace

nom

Indiquez le nom du programme utilisateur à appeler lorsqu'une instruction soumise à une trace est rencontrée durant le débogage dans un environnement de traitement par lots. Le programme indiqué doit être différent du programme indiqué au paramètre Programme (PGM). Si un programme identique est indiqué pour les paramètres TRCPGM et PGM, les résultats peuvent être inattendus. Une fois le programme exécuté, le programme interrompu reprend le contrôle et le traitement se poursuit.

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

La recherche porte sur la bibliothèque en cours du travail. Si celle-ci n'est pas précisée, QGPL est utilisée par défaut.

nom

Indiquez le nom de la bibliothèque sur laquelle doit porter la recherche.

Exemples

ADDTRC   STMT((100 120) (150 200)) PGMVAR('&CTR' '&BRCTR' '&SAM')

Cette commande permet de tracer des instructions de programme dans le programme par défaut entre les plages d'instructions 100 à 120 et 150 à 200. De plus, lorsque les valeurs d'une ou plusieurs variables de programme &CTR, &BRCTR et &SAM sont modifiées par l'une des instructions tracées dans ces plages, les valeurs de ces trois variables sont enregistrées avant le traitement de l'instruction tracée. Lorsque toutes les instructions tracées ont été traitées ou lorsqu'un point d'arrêt est atteint, la commande SPTRCDTA peut être utilisée pour afficher les données de trace collectées.

Messages d'erreur

Messages *ESCAPE

CPF1999

Erreurs dans la commande.