ADDBKP

La commande ADDBKP (Ajouter un point d'arrêt) permet d'établir jusqu'à dix points d'arrêt dans un programme. Un point d'arrêt correspond au stade d'un programme où le traitement est interrompu pour donner le contrôle à l'utilisateur ou à un autre programme. Le point d'arrêt est défini au moyen d'un numéro de spécification ou label d'une commande ou d'une instruction machine. Le programme s'arrête juste avant le traitement de l'instruction programme ou machine sur laquelle est défini le point d'arrêt.

Cette commande présente les valeurs de certaines variables de programme lorsqu'un point d'arrêt est atteint. Jusqu'à 10 variables peuvent être définies pour chaque point d'arrêt, sachant que la commande permet de définir 10 points d'arrêt au maximum. Ce sont cependant les mêmes variables de programme qui sont utilisées pour les différents points d'arrêt indiqués. Ainsi, pour obtenir des groupes de variables différents pour chaque point d'arrêt, vous devez entrer des commandes séparées.

Cette commande indique des points d'arrêt conditionnels dans lesquels le programme est interrompu lorsqu'une condition est remplie. Cette condition implique deux variables de programme, ou une variable de programme et une constante. Lors de l'utilisation des points d'arrêt conditionnels, il est possible d'arrêter le programme lorsqu'une variable de programme devient une valeur certaine.

Un point d'arrêt conditionnel peut également être indiqué à l'aide d'une valeur de saut. Le programme ne s'arrête pas tant que les instructions de point d'arrêt n'ont pas été traitées autant de fois que l'indique le compteur de sauts. Par la suite, le point d'arrêt interrompt le programme.

Lorsqu'un point d'arrêt est atteint dans le cadre d'un débogage interactif, l'utilisateur accède à un écran qui lui permet d'identifier le point d'arrêt et éventuellement les valeurs des variables de programme spécifiées, au moment de l'interruption du programme. Ces informations sont consignées dans l'historique du travail. L'utilisateur peut appuyer sur la touche F10 pour appeler l'écran d'entrée de commandes ou sur la touche F3, s'il souhaite quitter l'écran en cours et annuler le programme. Il peut aussi appuyer sur ENTREE s'il désire relancer l'exécution du programme.

Lorsqu'un point d'arrêt est atteint dans le cadre d'un débogage par lots, les informations relatives au point d'arrêt sont écrites dans un fichier imprimante. Le cas échéant, un autre programme est appelé pour effectuer les opérations requises, selon la condition de point d'arrêt. Le nom du programme appelé est précisé dans le paramètre Pgm point d'arrêt à appeler (BKPPGM).

Lorsqu'un travail interactif débogue un autre travail et que ce dernier atteint un point d'arrêt, un écran de point d'arrêt s'affiche. Cet écran apparaît dans le travail interactif et interrompt l'affichage en cours. Avant de retourner à votre écran, vous devez appuyer sur la touche ENTREE pour permettre la reprise du programme interrompu.

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é.

• Cette commande ne peut pas être utilisée pour ajouter des points d'arrêt à un programme lié.

• Pour utiliser cette commande, vous devez disposer du droit *ALLOBJ sur tous les objets.

Paramètres

Numéro d'instruction (STMT)

Indique les numéros des instructions programme ou machine (10 au maximum) pour lesquels un point d'arrêt a été défini dans le programme. Lors de l'exécution, le programme s'arrête avant le traitement d'une instruction constituant un point d'arrêt.

Ce paramètre est obligatoire.

La liste peut contenir jusqu'à 10 numéros (numéros d'instructions programme ou machine, labels de programme) valides pour le programme indiqué dans le paramètre PGM. Tout numéro d'instruction machine doit être précédé d'une barre oblique, sachant que la barre oblique et le numéro doivent figurer entre apostrophes.

Dans les programmes HLL (en langage évolué), différents labels et/ou instructions peuvent être mappés à la même instruction interne, notamment lorsque plusieurs instructions ne portant pas directement sur des variables (DO, END ou commentaires par exemple) se suivent dans un programme. Pour déterminer quelles instructions peuvent être mappées à la même instruction interne, consultez le listage IRP (Intermediate Representation of a Program).

Ainsi, l'ajout d'un point d'arrêt peut redéfinir un point d'arrêt ajouté précédemment pour une instruction différente. Dans ce cas, le nouveau point d'arrêt remplace le point d'arrêt précédent.

Variables du programme (PGMVAR)

Indique jusqu'à 10 noms de variables de programme au maximum (programme en langage évolué ou en langage machine). Le nom et la valeur de chaque variable de programme s'affichent lorsque l'un des points d'arrêt indiqué dans le paramètre Numéro d'instruction (STMT) est atteint. Lors de l'exécution, le programme s'arrête avant l'instruction constituant un point d'arrêt.

Remarque :Dans certains langages évolués tels que RPG, les variables déclarées mais non mentionnées dans le programme ne peuvent pas être indiquées au paramètre PGMVAR.

Valeurs uniques

*NONE

Aucune variable de programme ne s'affiche pour les points d'arrêt définis.

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 des variables de programme (10 au maximum), séparés par des blancs, à afficher lorsqu'un point d'arrêt est atteint. Tout nom contenant des caractères spéciaux doit figurer entre apostrophes.

Si la variable de programme est un tableau, les indices représentant l'élément du tableau peuvent être indiqué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 imbriqués, 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 défini par un entier, un numéro MI ODV, un astérisque (sous-tableau à une dimension) ou encore une variable numérique. Pour plus de détails sur le test et le débogage au niveau de l'interface machine et sur la valeur de la variable de programme, 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/.

Elément 2 : Variable de pointeur base

valeur-caractère

Indiquez jusqu'à cinq pointeurs de base pour chaque variable de programme à afficher. Dans certains langages, la variable de programme peut être basée sur une variable de pointeur. Ces valeurs vous permettent de définir les 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 imbriqués, 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 défini par un entier, un numéro MI ODV ou une 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 affichées les variables.

*CHAR

Affiche les variables en format caractères.

*HEX

Affiche les variables en format hexadécimal.

Programme (PGM)

Indique le programme auquel sont ajoutés les points d'arrêt.

*DFTPGM

Les points d'arrêt sont ajoutés au programme actuellement défini comme le programme par défaut, en mode débogage.

nom

Indiquez le nom du programme auquel les points d'arrêt sont ajoutés. Ce programme doit déjà être en mode débogage.

Position de début sortie (START)

Définit, dans le cas de variables de chaîne, la position à partir de laquelle les valeurs de la chaîne sont affichées lorsqu'un point d'arrêt est atteint. 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. La position de début ainsi définie correspond à une position binaire ou caractère selon le type de la chaîne.

Pour les points d'arrêt conditionnels, le paramètre Position de début sortie (START) indique aussi le point de départ de la chaîne faisant l'objet de la comparaison.

1

L'affichage de la variable se fait à partir de la première position et a pour longueur celle définie au paramètre Caractères à afficher (LEN).

entier

Indiquez la position à partir de laquelle la variable de programme est affichée.

La valeur entrée au paramètre 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, dans le cas de variables de chaîne uniquement, la longueur de la chaîne à afficher lorsque le point d'arrêt est atteint, à partir de la position définie au paramètre Position de début sortie (START). Si plusieurs variables de chaîne sont indiquées au paramètre Variables du programme (PGMVAR), la même longueur est utilisée pour chacune d'elles. 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).

Pour les points d'arrêt conditionnels, la paramètre Caractères à afficher (LEN) indique aussi la longueur de la chaîne faisant l'objet de la comparaison.

*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 pour le paramètre 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.

Valeur de saut (SKIP)

Indique combien de fois doivent être traitées les instructions indiquées au paramètre Numéro d'instruction (STMT) avant l'arrêt du programme.

0

Le programme s'arrête immédiatement lorsque les instructions sont traitées. Aucun saut de points d'arrêt n'est effectué.

entier

Indiquez combien de fois les instructions doivent être traitées avant l'arrêt du programme. Si plusieurs instructions sont précisées, chacune d'elle aura sa propre valeur de saut. Un compteur de saut séparé est prévu pour chaque instruction.

Condition de point d'arrêt (BKPCOND)

Indique une condition, définie par une expression, qui doit être vraie pour que le programme soit arrêté. L'expression est testée avant le traitement des instructions précisées au paramètre Numéro d'instruction (STMT) Si l'expression est fausse, le point d'arrêt n'affecte pas le déroulement du programme. Si l'expression est vraie, le programme s'arrête.

*NONE

Aucune condition de point d'arrêt n'est indiquée.

expression-point-d'arrêt

Indiquez une expression signalant un point d'arrêt conditionnel. Une telle expression se compose de trois éléments :

• Une variable (*PGMVAR1 à *PGMVAR10)
• Un opérateur
• Une valeur de comparaison

variable

Indiquez la variable à utiliser dans l'expression de point d'arrêt. Par exemple, *PGMVAR1 indique la première variable du paramètre Variables du programme (PGMVAR), *PGMVAR2 indique la deuxième, et ainsi de suite . Seules des variables numériques, alphanumériques ou binaires peuvent être indiquées.

opérateur

Indiquez le type de comparaison à effectuer pour un point d'arrêt conditionnel. Les opérateurs de comparaison suivants sont possibles :

*EQ

égal à

*NE

différent de

*GT

supérieur à

*LT

inférieur à

*GE

supérieur ou égal à

*NL

non inférieur à (équivaut à *GE)

*LE

inférieur ou égal à

*NG

non supérieur à (équivaut à *LE)

*CT

contient

Remarque :L'opérateur *CT compare deux chaînes de caractères pour voir si la première contient une ou plusieurs occurrences de la seconde. Cette comparaison recherche une concordance exacte et tient compte des majuscules et des minuscules.

valeur de comparaison

Indiquez une constante ou une autre variable à comparer avec la première variable. Si une constante est précisée, elle doit être de même type que la variable. Si la variable est numérique, la constante doit être un nombre. Si la variable est un bit, la constante doit être une chaîne composée uniquement de '1' et de '0'. Si la variable est un caractère, la valeur de comparaison est traitée comme une chaîne de caractères, même si un nombre est mentionné.

Si une autre variable de programme est indiquée, elle est comparée avec la première variable. Les deux variables doivent être de même type. Si les variables sont numériques, elles doivent être toutes les deux en virgule flottante ou toutes les deux en virgule fixe. Par exemple, un nombre condensé ne peut pas être comparé à un nombre en virgule flottante.

Pour comparer deux variables en virgule fixe, ou une variable en virgule fixe et une constante, le total des chiffres les représentant ne doit pas dépasser 31. Par exemple, une variable PACKED(24,2) ne peut être comparée avec une variable PACKED(24,20). La première variable requiert 22 chiffres avant la virgule et deux chiffres après la virgule. La deuxième variable requiert quatre chiffres avant la virgule et 20 chiffres après la virgule. Leur comparaison nécessite une variable comportant 22 chiffres avant la virgule et 20 chiffres après la virgule. Le total de ces chiffres dépasse le maximum admis de 31.

Lorsque deux chaînes de caractères sont comparées, la plus courte des deux est complétée par des blancs à droite de la virgule. Lorsque deux chaînes de bits sont comparées, elles doivent avoir la même longueur. Le paramètre Valeur de saut (SKIP) et le paramètre Condition de point d'arrêt (BKPCOND) peuvent s'utiliser ensemble. Dans ce cas, l'expression de point d'arrêt n'est pas évaluée tant que le point d'arrêt n'a pas fait le nombre de sauts défini par SKIP. Alors, l'expression de point d'arrêt est évaluée et le programme s'arrête si l'expression est vraie.

Pgm point d'arrêt à appeler (BKPPGM)

Indique le nom du programme utilisateur à appeler (éventuellement) lorsqu'un point d'arrêt est atteint dans le programme indiqué au paramètre Programme (PGM). Lorsque le programme défini par le paramètre BKPPGM est appelé, quatre paramètres lui sont transmis pour identifier le programme, le niveau de récursivité, l'identificateur de l'instruction HLL et le numéro de l'instruction machine où s'est produit le point d'arrêt. Ces paramètres ont le format suivant :

1. Nom de programme (10 octets). Désigne le programme dans lequel le point d'arrêt a été atteint.
2. Niveau de récursivité (5 octets). Le niveau de récursivité du programme dans lequel le point d'arrêt a été atteint. Il s'agit d'un nombre composé de 11 à 5 chiffres complété par des blancs à droite.
3. Identificateur d'instruction (10 octets). L'identificateur d'instruction en langage évolué qui a été trouvé. Ce numéro est indiqué dans la commande ADDBKP (Ajouter un point d'arrêt). Si un numéro d'instruction machine a été utilisé pour indiquer le point d'arrêt, ce paramètre contient une barre oblique (/) suivie d'une valeur hexadécimale à 4 chiffres correspondant au numéro d'instruction machine.
4. Numéro d'instruction (5 octets). Le numéro d'instruction machine correspondant à l'instruction en langage évolué constituant un point d'arrêt. Ce numéro n'est pas précédé d'une barre oblique ; il est composé de 1 à 4 caractères hexadécimaux représentant le numéro d'instruction MI, suivis de blancs. Si le troisième paramètre contient un numéro d'instruction machine, les numéros contenus dans le troisième et le quatrième paramètre sont identiques.

Toutes les valeurs de paramètre sont justifiées à gauche et complétées par des blancs à droite. Lorsque le programme appelé rend le contrôle, le traitement du programme en cours de débogage reprend, à partir de l'instruction où est placé le point d'arrêt.

Valeurs uniques

*NONE

Aucun programme de gestion de points d'arrêt n'est appelé lorsqu'un point d'arrêt, indiqué dans cette commande, est atteint, dans le cadre d'un traitement par lots. L'exécution du programme interrompu se poursuit.

Qualificatif 1 : Pgm point d'arrêt à appeler

nom

Indiquez le nom du programme utilisateur à appeler si l'un des points d'arrêt de cette commande est atteint au cours d'un débogage en traitement par lots. Le programme indiqué doit être différent du programme indiqué au paramètre Programme (PGM). Si ces deux programmes sont identiques, les résultats seront imprévisibles. Après l'exécution du programme appelé, le contrôle est rendu au programme interrompu, dont l'exécution 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

Le programme est recherché dans la bibliothèque en cours du travail. Si celle-ci n'est pas précisée, QGPL est prise par défaut.

nom

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

Exemples

Exemple 1 : ajout de points d'arrêt en mode débogage

ADDBKP  STMT(150 RTN1 205) PGMVAR('&TEMP' '&INREC')

Cette commande permet de placer des points d'arrêt aux numéros d'instruction CL 150 et 205 et à l'étiquette RTN1 pour le programme par défaut en mode débogage. Lorsque l'un de ces points d'arrêt est atteint, les variables CL &TEMP et &INREC s'affichent automatiquement. Les variables CL doivent inclure une perluète (&) et être définies entre apostrophes.

Exemple 2 : ajout de points d'arrêt au programme HLL

ADDBKP  STMT(100)  PGMVAR('AMOUNT(200)') PGM(MYPROG)

Dans cet exemple, nous considérons que MYPROG est un programme à langage évolué soumis à une opération de débogage dans un environnement interactif, et que la variable de programme AMOUNT est un tableau à 250 éléments dans MYPROG. Cette commande permet d'ajouter un point d'arrêt à l'instruction 100 dans MYPROG. Lorsque MYPROG est lancé, le programme cesse le traitement à l'instruction 100 et la valeur du 200ème élément du tableau AMOUNT s'affiche. Si AMOUNT avait été défini sans indice, tous les éléments du tableau auraient été affichés.

Exemple 3 : arrêts de programme après l'instruction de traitement 10 fois

ADDBKP   STMT(10)  SKIP(1000)

Cette commande permet d'arrêter le programme par défaut lorsque l'instruction 10 est traitée 1000 fois (le point d'arrêt est ignoré 1000 fois).

Exemple 4 : arrêt du programme après le traitement de plusieurs instructions

ADDBKP   STMT(10 20 30)  SKIP(50)

Cette commande permet d'arrêter le programme par défaut lorsque les instructions 10, 20 et 30 sont traitées 50 fois.

Exemple 5: point d'arrêt conditionnel

ADDBKP   STMT(10)  PGMVAR(X)  BKPCOND(PGMVAR1 *EQ 5)

Cette commande permet d'arrêter le programme par défaut à l'instruction 10 lorsque la variable X est égale à cinq.

Exemple 6 : point d'arrêt conditionnel

ADDBKP   STMT(20)  PGMVAR((S1) (S2))  SKIP(100)
         BKPCOND(*PGMVAR1 *CT *PGMVAR2)

Cette commande permet d'arrêter après le centième traitement, et uniquement si la chaîne de caractères S2 apparaît dans la chaîne de caractères S1.

Messages d'erreur

Messages *ESCAPE

CPF1999

Erreurs dans la commande.