Paramètre SPLFDTA (Key #35)

SPLFDTA (Key #35) est plus complexe parce qu’il y a de multiples façons de sélectionner des fichiers spoolés. La figure 11 montre les structures de données utilisées pour manipuler ce paramètre, et la figure 12 montre le code. Les premiers éléments de données sont les mêmes que pour les autres paramètres (c’est-à-dire les champs  RcdLen, KeyNbr et DataLen) dans la structure de données SavObjParms. En A de la figure 12, DataLen est le total des tailles des structures de données SplfDtaParm, SplfDtaSelect SplfDtaAttr, parce que c’est tout ce dont vous avez besoin pour sauvegarder les nouveaux fichiers spoolés. Ce paramètre peut être utilisé de manière beaucoup plus longue et complexe, avec toute la granularité nécessaire à ce que vous sauvegardez, mais il est inutile d’aller aussi loin pour ce programme.
Une fois la structure de données SavObjParms initialisée, le programme calcule un pointeur juste pour la dépasser afin de pouvoir commencer à remplir la structure de données SplfDtaParm (B dans la figure 12). Le premier champ à initialiser est SplfData, et il peut avoir l’une de trois valeurs : *ZERO (aucun fichier spoolé n’est sauvegardé), 1 (pour chaque file de sortie sauvegardée, les fichiers spoolés qu’elle contient sont sauvegardés), ou 2 (seuls certains fichiers spoolés sont sauvegardés, et il faut fournir d’autres critères de sélection). L’exemple de programmes utilise l’option 2.

Le champ suivant à initialiser est SplfHdrLen, qui est la longueur de la structure de données SplfDtaParm. Deux valeurs sont possibles, selon ce qui a été spécifié dans le champ SplfData mentionné ci-dessus. Si c’était *ZERO ou 1, cette valeur doit être 8, qui est la longueur qui ne couvrirait que les champs SplfData et SplfHdrLen dans la structure de données. (Je ne vois pas bien pourquoi les développeurs mettent le champ SplfHdrLen en deuxième position dans la structure de données. Il semblerait plus logique de le mettre en tête, mais ce n’est pas notre propos aujourd’hui.) L’autre longueur possible est 12, qui couvre non seulement les deux premiers champs, mais aussi le dernier dans cette structure de données. En B de la figure 12, le programme indique la taille complète de la structure SplfData, qui est 12.

Ce dernier champ est celui qui est spécifiquement requis quand SplfData est sur 2 : le champ SplfOffset, qui est le décalage vers le fichier spoolé Selection Criteria. En jargon IBM, un décalage (offset) est une position de départ à partir du début d’un espace utilisateur—pas simplement à partir du début de la section courante dans l’espace utilisateur ; cette distance est appelée « déplacement. » (La longueur des divers enregistrements de paramètres dans l’espace utilisateur est un bon exemple d’utilisation des déplacements.) Le moyen le plus facile pour calculer un décalage au coeur de l’action est de définir un nouveau pointeur en utilisant le déplacement vers la nouvelle position, puis de calculer le décalage en soustrayant le pointeur de l’espace utilisateur de base de la nouvelle valeur du pointeur.

Le fichier spoolé Selection Criteria est la liste des structures de données pour laquelle vous pouvez sélectionner ou omettre des ensembles spécifiques de fichiers spoolés pour, ou à partir de la sauvegarde. La structure SplfDtaSelect se trouve dans l’exemple en B de la figure 11 et le code qui l’initialise, en C de la figure 12. Au moyen de cette structure, vous pouvez sélectionner ou omettre des fichiers spoolés individuels ou en groupe. (Vous pouvez aussi l’utiliser pour changer la date d’expiration de chaque ensemble de fichiers spoolés après leur sauvegarde, bien que je n’en parle pas dans cet article.)

Le premier champ dans cette structure de données est nommé Length : c’est la longueur de la structure SplfDtaSelect. Les valeurs possibles sont 20 (si vous excluez un décalage pour définir les nouveaux attributs) ou 24 (pour l’inclure). Bien qu’il soit sur 24, je vais finalement définir le décalage à *ZERO.

Le deuxième champ est appelé Offset, et—ça tombe bien—c’est le décalage vers la prochaine structure du fichier spoolé Selection Criteria. Mais comme je n’ai besoin que d’une structure de données Selection Criteria, je le mets à *ZERO pour dire à l’API que c’est le dernier ou le seul dans la liste.

Le troisième champ est un indicateur numérique nommé Include qui dit à l’API s’il faut inclure ou omettre les fichiers spoolés. *ZERO les omettra, et 1 les inclura. Bien entendu je vais choisir le dernier.

Le quatrième champ est appelé Format, et c’est le format numérique de la structure qui fournit les critères servant à sélectionner (ou omettre) les fichiers spoolés. Les valeurs possibles sont 1 et 2. La valeur 1 dit à l’API que je vais fournir l’identification du fichier spoolé (nom de job complet, nom du fichier spoolé, numéro, etc.) pour sélectionner un fichier spoolé unique, ce qui serait encombrant pour cette application. Dans le code, je spécifie 2 (C dans la figure 12), pour dire à l’API que je vais fournir les critères de sélection.

Le cinquième champ est nommé SelectOffset, et c’est le décalage vers les critères de sélection. Je le calcule en ajoutant la taille de la structure SplfDtaSelect au champ SplfOffset.

Enfin, le sixième champ est appelé NewAttrOffset, et c’est le décalage vers les nouveaux attributs mentionnés ci-dessus. Je le mets à *ZERO parce que je ne veux pas changer les dates d’expiration des fichiers spoolés après leur sauvegarde.
La dernière structure de données à initialiser pour ce paramètre est SplfDtaAttr. Son concept est semblable aux paramètres de sélection sur beaucoup de commandes de fichiers spoolés : Work With Spooled Files (WRKSPLF), Hold Spooled File (HLDSPLF), Release Spooled File (RLSSPLF), Delete Spooled File (DLTSPLF), etc. La structure de données se trouve en C de la figure 11 et le code pour l’initialiser, en D de la figure 12.

Les noms des champs de sélection doivent être explicites. Le plus souvent, ils contiendront un nom, un nom générique, ou une autre valeur spéciale appropriée. (Si, par exemple, vous avez spécifié MYOUTQ* dans le champ OutqName et *LIBL dans le champ OutqLib, vous sauvegarderez tous les fichiers spoolés présents dans les files de sortie dans la liste de bibliothèques dont les noms commencent par MYOUTQ.) Les seules exceptions sont les champs StrCrtDate et EndCrtDate, qui seraient utilisés pour entrer une plage date/heure et sélectionner des fichiers spoolés d’après leur date/heure de création. Ce sont tous les deux des champs de 13 octets, et la date/heure doit être au format SAAMMJJHHMMSS (où S est le chiffre du siècle : 0=19xx, 1=20xx, 2=21xx, etc.). Indépendamment de ce qui serait normalement stocké dans ces champs, la valeur spéciale *ALL peut s’appliquer à chacun d’entre eux pour dire à l’API de ne pas en tenir compte lors de la sélection.

En D de la figure 12, je spécifie *ALL dans chaque champ, sauf StrCrtDate, qui est initialisé par un champ date/heure calculé précédemment. Dans le source de commande et de programme que vous pouvez télécharger (à systeminetwork.com/code ou peterlevy.com), la valeur qui est insérée dans StrCrtDate résulte de deux paramètres de commandes : REFDATE et REFTIME. Si REFDATE(*SAVLIB) est spécifié, le programme la calculera en extrayant la dernière date/heure de sauvegarde de la bibliothèque QUSRSYS, en utilisant l’API Retrieve Object Description (QUSROBJD). Si une date ou une heure a été fournie dans les paramètres, il utilisera plutôt ces valeurs. Dans les deux cas, ce critère est utilisé par l’API QSRSAVO pour sauvegarder tous les fichiers spoolés créés à cette date/heure ou après. Si la dernière date/heure de sauvegarde dans la bibliothèque QUSRSYS ne correspond pas à la dernière heure où tous les fichiers spoolés ont été sauvegardés, votre programme doit passer la date/heure réelle dans ces deux paramètres de commandes.

À la fin du programme, les fichiers spoolés apparaîtront sur le média (ou dans un fichier de sauvegarde) comme s’ils avaient été sauvegardés à partir d’une file de sortie nommée *SPLF dans la bibliothèque *SPLF. Bien entendu ce n’est qu’une apparence, parce que quand vous aurez choisi l’option 5 pour afficher les fichiers spoolés, vous verrez qu’ils venaient tous de files de sortie distinctes. Autre source d’agacement possible : quand les commandes SAVCHGxxx seront utilisées avec la commande SAVNEWSPLF, tous les fichiers spoolés sauvegardés se retrouveront à la fin du média et non parsemés comme ils le seraient avec les commandes SAVxxx.
J’ai aussi essayé de déterminer si vous pouviez combiner la sauvegarde des objets changés et des nouveaux fichiers spoolés en utilisant l’API QSRSAVO, mais malheureusement ce n’est pas possible. Il est quand même curieux que l’API puisse sauvegarder les nouveaux fichiers spoolés mais pas les objets changés, tandis que les commandes peuvent sauvegarder les objets changés mais pas les nouveaux fichiers spoolés. Ce serait bien plus simple pour tout le monde si IBM prenait en charge à la fois les paramètres REFDATE/REFTIME dans l’API QSRSAVO et le paramètre SPLFDTA sur les commandes SAVCHGxxx.

Si vous téléchargez l’exemple de code, vous remarquerez sûrement l’absence des nombreux paramètres que j’aurais pu inclure à partir des commandes SAVxxx. Ce n’est pas par paresse, mais parce que j’ai pris un programme réel que j’avais écrit pour ma société et l’ai transformé en un exemple de programme pour cet article. Il se trouve que ce programme n’a pas un frontal de commandes et qu’il gère d’autres activités étrangères à l’article.

Si vous voulez utiliser l’exemple de programme en production, sachez qu’il est assez facile d’étendre la commande et le programme. Vous pouvez ajouter des paramètres et du texte d’aide à la commande. Le code supplémentaire nécessaire, pour inclure les valeurs de paramètres ajoutées dans l’espace utilisateur pour l’API, peut être copié à partir du code des autres paramètres et adapté aux nouvelles valeurs. (Les paramètres ENDOPT et VOL sont deux bons candidats qui me viennent à l’esprit.) Envoyez-moi vos changements par courriel : je les inclurai dans les nouvelles versions sur mon site web, en vous en attribuant la paternité.

Sauvegardez vos fichiers spoolés

Vous n’en êtes peut-être pas conscients mais, comme je l’ai écrit dans l’introduction, vos utilisateurs attachent beaucoup d’importance aux fichiers spoolés. Si votre site ne les sauvegarde pas, je vous engage à le faire. Si vous ne les sauvegardez que pendant les week-ends, lors de la sauvegarde complète du système, vous pouvez désormais sauvegarder les nouveaux pendant le SAVCHGxxx quotidien avec l’API QSRSAVO. Après quoi, si d’importants fichiers spoolés sont supprimés ou purgés accidentellement, on vous remerciera de les avoir sauvegardés en permanence et pas uniquement les week-ends.