%STATUS

Lire le code d'état d'une opération

Renvoie le code d'état de la dernière opération sur un fichier ou, sans argument, le code d'erreur du programme.

Syntaxe

%STATUS(nom-fichier)
%STATUS

nom-fichier: Le fichier dont on veut l'état. Sans argument, on obtient le code d'état du programme.
Résultat: Un entier : 0 quand tout va bien, sinon un code. Les codes inférieurs à 1000 sont des situations du programme ou de lecture (11 fin de fichier, 12 non trouvé, 102 division par zéro, 211 appel en erreur…), à partir de 1000 des erreurs d'entrée-sortie.

À quoi ça sert

Quand %ERROR ou un bloc on-error signale une erreur, %STATUS dit laquelle. On peut ainsi répondre différemment à un doublon (1021), à un fichier fermé (1211) ou à une donnée illisible (1299), sans afficher un message générique.

Connaître les quelques codes courants suffit dans la pratique ; le premier exemple les fait tous apparaître.

Exemple 1 : Les codes d'état courants d'un fichier

**free
// %STATUS : les codes d'etat courants apres une operation sur fichier (avec extension E).
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-f client keyed usropn;
dcl-f f_client usage(*input : *output : *update) keyed;

// Rien d'anormal : le statut est 0
chain(e) (100) f_client;
rapport('CHAIN 100 trouve' : %status(f_client) : %error);

// Enregistrement non trouve : 12, mais ce n'est pas une erreur
chain(e) (999) f_client;
rapport('CHAIN 999 absent' : %status(f_client) : %error);

// Fin de fichier : 11, pas une erreur non plus
setgt *hival f_client;
read(e) f_client;
rapport('READ en fin de fichier' : %status(f_client) : %error);

// A partir de 1000, ce sont de vraies erreurs
clear f_clientr;
numcli = 100;
write(e) f_clientr;
rapport('WRITE cle en double' : %status(f_client) : %error);

chain(e) (100) f_client;
update(e) f_clientr;
update(e) f_clientr;
rapport('2e UPDATE sans CHAIN' : %status(f_client) : %error);

chain(e) (100) client;
rapport('CHAIN fichier ferme' : %status(client) : %error);

open(e) client;
open(e) client;
rapport('OPEN deja ouvert' : %status(client) : %error);

chain(e) (300) client;
rapport('CHAIN date NULL' : %status(client) : %error);

*inlr = *on;

dcl-proc rapport;
  dcl-pi *n;
    libelle char(24) const;
    statut  int(10) const;
    erreur  ind const;
  end-pi;
  snd-msg libelle + ': statut ' + %char(statut) +
          ', %ERROR = ' + %char(erreur);
end-proc;

Résultat réel, compilé et exécuté sur IBM i 7.5 :

CHAIN 100 trouve        : statut 0, %ERROR = 0
CHAIN 999 absent        : statut 12, %ERROR = 0
READ en fin de fichier  : statut 11, %ERROR = 0
WRITE cle en double     : statut 1021, %ERROR = 1
2e UPDATE sans CHAIN    : statut 1221, %ERROR = 1
CHAIN fichier ferme     : statut 1211, %ERROR = 1
OPEN deja ouvert        : statut 1215, %ERROR = 1
CHAIN date NULL         : statut 1299, %ERROR = 1

Une procédure affiche le libellé, le statut et %ERROR. À retenir : 12 (non trouvé) et 11 (fin de fichier) sont des statuts sans erreur (%ERROR à 0). Sont de vraies erreurs : 1021 (clé en double), 1221 (second UPDATE sans nouveau CHAIN), 1211 (fichier fermé), 1215 (fichier déjà ouvert) et 1299 (erreur de mappage de données, ici la date NULL).

Exemple 2 : Le statut du programme dans un MONITOR

**free
// %STATUS sans argument : le code d'erreur du programme, lu dans un bloc MONITOR.
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-pr absent extpgm('NOEXISTE');
end-pr;

dcl-f client keyed;

dcl-s zero   packed(5:0) inz(0);
dcl-s ratio  packed(9:2);
dcl-s valeur packed(9:2);

monitor;
  ratio = 1250.50 / zero;
on-error *all;
  snd-msg 'Division par zero : statut ' + %char(%status);
endmon;

monitor;
  valeur = %dec('12x' : 9 : 2);
on-error *all;
  snd-msg 'Texte non numerique : statut ' + %char(%status);
endmon;

monitor;
  absent();
on-error *all;
  snd-msg 'Programme absent : statut ' + %char(%status);
endmon;

monitor;
  chain (300) client;
on-error *all;
  snd-msg 'Erreur de fichier : statut ' + %char(%status) +
          ', pour le fichier ' + %char(%status(client));
endmon;

*inlr = *on;

Résultat réel, compilé et exécuté sur IBM i 7.5 :

Division par zero : statut 102
Texte non numerique : statut 105
Programme absent : statut 211
Erreur de fichier : statut 1299, pour le fichier 1299

Sans argument, %STATUS donne le code de l'erreur qui a déclenché le on-error : 102 pour la division par zéro, 105 pour la conversion %DEC d'un texte non numérique, 211 pour un programme appelé qui n'existe pas, 1299 pour l'erreur de fichier. Le dernier cas montre que cette erreur est visible aussi bien par %STATUS que par %STATUS(client).

Le piège

Un statut non nul n'est pas toujours une erreur. Après un CHAIN qui ne trouve rien, %STATUS(fichier) vaut 12 mais %ERROR vaut 0. Même chose pour la fin de fichier (11). Si on teste seulement « statut différent de zéro », on traite un simple « non trouvé » comme une panne.

À l'inverse, %STATUS n'a de sens que juste après l'opération : la suivante l'écrase (un CHAIN réussi le remet à 0).