A votre service

Entries
et RtvStkEnt (Retrieve Stack Entry) apparaissent en A et B, respectivement.
Bien qu’un seul appel adressé à 
QWVRCStk puisse extraire toutes les
informations sur la pile d’appel, j’ai
préféré créer ces deux procédures
pour la simplicité d’emploi. Les applications
peuvent déterminer le
nombre total des entrées de la pile
d’appel en utilisant la procédure
RtvNbrStkEnt puis extraire les informations
pour une certaine entrée de
pile d’appel en utilisant la procédure
RtvStkEnt.

Le prototype de procédure pour
l’API QWVRCStk apparaît en C. Vos
applications n’utilisent pas ce prototype
: il est réservé à  l’usage interne
du programme de service CallStack.
Les procédures de CallStack,
RtvNbrStkEnt et RtvStkEnt, utilisent le
prototype pour appeler l’API.

La procédure RtvNbrStkEnt accepte
comme entrée les éléments individuels
du nom de job qualifié dont
la procédure extraira les informations
de la pile d’appel. RtvNbrStkEnt accepte
également comme entrée/sortie
un paramètre d’erreur API facultatif.
Après bonne exécution, la
procédure renvoie le nombre d’entrées
sur la pile d’appel. Une valeur de
0 (zéro) est signe d’échec.

En D, je précise une structure de
données, RtvInfoDS, qui contiendra
les informations renvoyées par
QWVRCStk. La structure de données
ne définit que le nombre total d’entrées
de la pile d’appel pour le thread
(TotStkEnt), le nombre d’entrées de
la pile extraites (NbrStkEnt) et un
champ d’état (Statuts) qui indique si
l’API a extrait des informations complètes.
Aucune autre information extraite
n’est nécessaire dans cette procédure.

La logique de RtvNbrStkEnt est
simple et directe. La procédure effectue
le travail de préparation initial, appelle
l’API QWVRCStk pour extraire la
pile d’appel, et renvoie le nombre
d’entrées de la pile d’appel à  son appelant
quand il n’y a aucune erreur.

La procédure RtvStkEnt accepte comme entrée les éléments individuels
du nom de job qualifié dont la
procédure extraira les informations de
la pile d’appel et le numéro d’entrée
ordinal a extraire. Ces paramètres
d’entrée sont suivis des paramètres de
sortie ci-après :

• Request level

• Program name

• Program library

• Module name

• Module library

• Activation group name

• Procedure name

La procédure accepte également
comme entrée/sortie un paramètre
d’erreur API facultatif. La procédure
renvoie une variable indicatrice indiquant
la bonne fin, ou non, de la procédure.
La réussite est indiquée par
« 0 », l’échec par « 1 ».

De la même manière qu’avec la
procédure RtvNbrStkEnt, la structure
de données RtvInfoDS (destinée à 
contenir les informations renvoyées
par QWVRCStk) apparaît également
dans RtvStkEnt (en E). Toutefois,
RtvStkEnt ajoute le sous-champ
FirstEntOff (first entry offset), qu’elle
utilise pour déterminer la position de
début de la première sous-structure
d’entrée de la pile d’appel (voir
figure 1). Observez que la structure de
données est bien plus longue que la
taille dont ses sous-champs ont besoin.
C’est vrai parce que les sous-champs
définis ne constituent que la partie statique
de l’information extraite. La zone
suivant cette zone statique contient les
détails des entrées de la pile d’appel.

La structure de données StkEntDS
(en F) indique les champs qui constituent
une entrée de pile d’appel. Cette
structure de données est fondée sur le
pointeur StkEntPtr, signifiant qu’aucun
stockage n’est alloué pour la structure
de données. En réalité, la structure de
données se contente de mettre en correspondance
les données qu’elle
trouve avec l’adresse indiquée dans
StkEntPtr. Il est donc facile d’extraire une entrée de pile d’appel des données
présentes dans la structure de
données RtvInfoDS. La procédure définit
simplement le pointeur StkEntPtr
afin qu’il pointe au début d’une entrée
de pile d’appel, et les sous-champs de
StkEntDS contiennent les détails de
cette entrée.

Dans la structure de données
StkEntDS, on notera les sous-champs
Prc Displace (displacement to procedure
name) et PrcName Len (procedure
name length). Comme le nom de
la procédure est de longueur variable
et n’a pas d’emplacement fixe dans la
structure des entrées de la pile d’appel
(c’est-à -dire qu’il suit les informations
de longueur variable), ces champs sont
nécessaires pour trouver et extraire le
nom de la procédure. Les champs en G
mappent la partie nom de procédure
de la structure.

La procédure RtvStkEnt effectue d’abord la préparation initiale puis appelle
l’API QWVRCStk pour extraire la
pile d’appel. Après quoi, la procédure
doit extraire l’entrée de pile d’appel sélectionnée.
En H, RtvStkEnt valide le
numéro de l’entrée de pile d’appel sélectionnée.
Si l’application spécifie un
numéro d’entrée de pile incorrect, la
procédure renvoie une erreur. La
procédure s’assure également de la
disponibilité d’informations de pile
complètes, en vérifiant l’état de l’information
renvoyée (en I). Si l’information
est incomplète, RtvStkEnt renvoie
une erreur. Ensuite, RtvStkEnt détermine
si elle a extrait toutes les entrées
de pile d’appel pour le thread (en J) et
renvoie une erreur si ce n’est pas le
cas.

Après avoir transmis ces validations,
la procédure extrait l’entrée de
pile d’appel sélectionnée en naviguant
au travers des entrées de pile d’appel du début jusqu’à  l’entrée sélectionnée.
Cette opération est nécessaire parce
qu’il nous faut les détails provenant
d’une entrée de pile d’appel pour calculer
l’emplacement de début de l’entrée
suivante.

En K, RtvStkEnt calcule l’adresse
de la première entrée de pile d’appel
et stocke cette information dans le
pointeur StkEntPtr. Comme résultat, la
structure de données StkEntDS
contient des références correctes à  la
première entrée de pile d’appel. La
procédure amorce ensuite une boucle
qui s’exécute répétitivement jusqu’à  ce
qu’elle trouve l’entrée sélectionnée.
RtvStkEnt extrait le nom de la procédure
(en L). Cette section ajoute d’abord le déplacement vis-à -vis du
nom de la procédure (PrcDisplace) à 
l’adresse de l’entrée de pile d’appel
(trouvée dans le pointeur SrkEntPtr) et
place le résultat dans le pointeur
PrcNamePtr. Cela fournit une adresse
au début du nom de la procédure.
Ensuite, la fonction substring extrait le
nom de la procédure (PrcName). La
procédure définit ensuite les paramètres
de sortie restants. Pour finir, en
M, RtvStkEnt incrémente le pointeur
SrkEntPtr afin qu’il pointe sur la prochaine
entrée de pile d’appel. Après
exécution de toutes les itérations de la
boucle, RtvStkEnt sort, renvoyant une
indication de réussite et les paramètres
de sortie contenant les détails de l’entrée de pile d’appel sélectionnée.

La figure 3 présente un exemple de
code d’application qui utilise les procédures
du programme de service
CallStack. Ici, j’indique la valeur spéciale
* pour le champ JobName pour
indiquer que les procédures doivent
interroger la pile d’appel du job courant.

Après avoir défini les prototypes et
les champs de procédure que l’application
utilise, l’exemple extrait le numéro
des entrées de pile d’appel en
appelant la procédure RtvNbrStkEnt. Il
faut toujours effectuer cette étape
juste avant d’extraire une ou plusieurs
entrées de pile d’appel pour s’assurer
que l’on référence des numéros d’entrées de pile d’appel ordinaux valides.
L’exemple montre que quand
vous spécifiez le paramètre de structure
d’erreur d’API facultatif, vous pouvez
l’utiliser pour déterminer si une erreur
s’est produite dans RtvNbrStkEnt.
Si vous n’incluez pas la structure d’erreur
API, vous pouvez tester si la valeur
de renvoi (NbrStkEnt) est 0 (zéro)
pour déterminer si une erreur s’est
produite. Je suggère de toujours utiliser
la structure d’erreur API.

L’application exemple entame ensuite
une boucle qui extrait chacune
des entrées de pile d’appel du job en
appelant la procédure RtvStkEnt une
fois pour chaque numéro d’entrée de
pile d’appel ordinal. Après chaque appel
adressé à  la procédure RtvStkEnt, il
faut traiter les éventuelles erreurs survenues.
Si vous n’incluez pas le paramètre
de structure d’erreur API facultatif,
vous pouvez vérifier si la variable
d’indicateur renvoyée (RtnCode)
contient une valeur de « 1 » pour déterminer
si une erreur s’est produite.