API QSRSAVO

Prototype pour ILE RPG

Tout programme qui utilise cette API doit stocker les paramètres servant à effectuer la sauvegarde dans l’espace utilisateur avant d’appeler l’API. (Ces paramètres sont quelque peu différents de ceux de la commande SAVxxx, mais nous en reparlerons.) Si une erreur se produit pendant la sauvegarde, le paramètre code d’erreur contiendra une identification de message et des données de message.

API QSRSAVO

La première chose à faire est de créer l’espace utilisateur. Ce point a déjà été couvert (voir « Auto-Extending a User Space, » SystemiNetwork.com, article ID 19590), et j’inclus le programme de service nécessaire dans le code téléchargeable. Il va de soi qu’il faut trois API système pour créer l’espace utilisateur, le changer pour étendre automatiquement sa taille, et extraire un pointeur qui est renvoyé vers le programme appelant. Ce pointeur vise directement  l’espace de données dans l’espace utilisateur et il servira à construire les paramètres pour la sauvegarde.

L’opération suivante consiste à ajouter ces paramètres à l’espace utilisateur. Ils sont constitués d’un ensemble d’enregistrements de longueur variable qui correspondent, le plus souvent exactement mais parfois vaguement, aux paramètres des diverses commandes SAVxxx. De plus, au lieu de noms de paramètres, l’API demande des « numéros de clé » (key numbers). Par exemple, le paramètre LIB parameter correspond au numéro de clé 2, le paramètre DEV au numéro 3, et les paramètres OBJ & OBJTYPE sont combinés dans le numéro de clé 1.

La figure 2 montre les deux structures de données que j’utilise pour tous les paramètres. Les quatre premiers octets dans l’espace utilisateur constituent un entier binaire qui doit contenir le nombre total d’enregistrements (SavObj.RcdNbr). Vient ensuite le premier enregistrement. Lui et les suivants ont la même structure de données de base (SavObjParms), constituée de trois entiers puis des données. Le premier entier contient la longueur de tout l’enregistrement (RcdLen), le deuxième contient le numéro de clé de paramètre (KeyNbr), et le troisième est la longueur des données (DataLen). À noter que le pointeur de base pour la structure de données SavObj, SplfUsrSpcPtr, est aussi l’endroit où le pointeur vers l’espace utilisateur est stocké et n’est jamais changé. Le pointeur vers la structure de données SavObjParms est incrémenté pour chaque nouvel enregistrement. (Bien sûr, rien n’empêche de créer une structure de données géante où toutes les positions seraient codées en dur et qui dispenserait d’utiliser et de comprendre des pointeurs. Mais cette structure serait trop rigide en cas de modification future du programme.)

Le moment est venu de créer le premier paramètre, qui sera la liste des objets et des types d’objets. La figure 3 montre le code RPG qui est utilisé et qui exécute les étapes suivantes :

1.    Initialiser à 1 l’entier SavObj.Rcdnbr pour le premier enregistrement.
2.    Calculer le pointeur pour la structure de données SavObjParms (SavObjParmsPtr) pour le placer juste après l’entier SavObj.Rcdnbr.
3.    Initialiser les champs RcdLen, KeyNbr, et DataLen : longueur d’enregistrement, numéro de clé pour le paramètre OBJ/OBJTYPE (1), et longueur des données, respectivement.
4.    Calculer le pointeur pour la structure de données SavObjParmList (SavObjParmPtr) pour le placer juste après l’entier DataLen.
5.    Dans ce cas, les données sont une liste, donc le premier élément de ces données est un entier de quatre octets qui indique le nombre d’éléments présents dans la liste. Ici il est initialisé à 1 (ElemNbr) car il n’y a qu’un élément dans la liste.
6.    Calculer le pointeur pour la structure de données ObjObjTypeParm que l’on voit dans la figure 4 (SavObjElemPtr) pour le placer juste après l’entier ElemNbr.
7.    Pour finir, initialiser les deux éléments de la structure de données ObjObjTypeParm à *ALL objects et *ALL object types.

Bien que le programme ne sauvegarde que les fichiers spoolés, le premier paramètre spécifiant *ALL objects et *ALL object types doit être spécifié.

Le code servant à créer le deuxième paramètre pour la liste de bibliothèques se trouve dans la figure 5, et il est identique au code de la figure 3, à ceci près :

•    L’entier SavObj.Rcdnbr est incrémenté de 1 pour l’enregistrement du deuxième paramètre.
•    le calcul du pointeur pour la structure de données SavObjParms (SavObjParmsPtr) utilise la valeur RcdLen de l’enregistrement du paramètre précédent pour le régler sur une nouvelle position juste après lui.
•    Le KeyNbr est initialisé avec le numéro de clé pour le paramètre LIB (2).
•    La portion données contient une liste de bibliothèques à sauvegarder. Comme je ne sauvegarde que les fichiers spoolés, je substitue la valeur spéciale *SPLF. La figure 6 montre la structure des données du paramètre LIB.

Cette manière d’ajouter des paramètres à l’espace utilisateur continue jusqu’à la fin. Pratiquement tout paramètre valide convient pour sauvegarder les nouveaux fichiers spoolés, et vous pouvez les voir tous dans le tableau Valid Keys (tinyurl.com/ValidKeys) pour la documentation de l’API QSRSAVO.

Certains paramètres sont plus pertinents que d’autres. Par exemple, vous pouvez utiliser save-while-active pour sauvegarder les fichiers spoolés ; ainsi le paramètre SAVACT et les paramètres associés peuvent être utiles. D’un autre côté, le stockage pour les fichiers spoolés sauvegardés n’est jamais libéré après la sauvegarde, et donc l’inclusion du paramètre STG serait un gaspillage de code.