Use the Save Object List API to let users customize nightly saves -- Part I

Ron Turull

The Save Object List (QSRSAVO) API is a bit awkward to work with compared to most of the other system APIs, but for doing customized saves it is well worth the effort. For example, you can let users maintain a file where they can specify the objects they want backed up each night. You can then use the QSRSAVO API to save the objects more efficiently than is possible with the various save commands. (I'll provide the code to do this in the next installment.) This would eliminate the need for you (or the system administrator) to maintain and decide which user-created objects (e.g., queries) need to be backed up, thus freeing-up your precious time.

Understanding how the QSRSAVO API works
Unlike most APIs that use parameters to allow the caller to specify processing options, the QSRSAVO employs a user space. That is, before calling the QSRSAVO API, the caller must write the would-be parameters to a user space in a predefined format. You then pass the user space name to the QSRSAVO API (via a parameter), and the API reads the information from the specified user space to determine how to process the request. I can only guess that the rational behind this is that there are potentially so many processing options available that it would make a parameter list too complicated (although, I have seen plenty of complicated parameter lists on other APIs).

More Information Simplify individual object restores Ensuring effective backups Proof of backup needed

The user space is made up of variable-length records that are keyed using predefined values. Each record holds information that would normally be associated with a single parameter. The predefined key values range from 1 to 34 and can be thought of as parameter numbers that allow you to specify whatever parameters you wish and in any order. The variable-length records have the following format:

• Length of variable-length record. A 4-byte binary field that specifies the overall length of this variable-length record.
• Key. A 4-byte binary field that specifies one of the predefined key values. Each key corresponds to a parameter on the Save Object command (SAVOBJ). The chart below summarizes the valid key values. See the System API Reference (SC41 3801) for details.
• Length of data. A 4-byte binary field used to specify the length of the parameter data.
• Parameter data. The parameter data appropriate for the specified key.

At the very beginning of the user space, in the first four bytes, a 4-byte binary field should have the total number of variable-length records specified. The variable-length records should start at byte 5 (offset 4) and must be consecutive.

Guide to the key values
The chart below summarizes the valid key values. Again, you will find details for all the key values in the System API Reference (SC41 3801). Alternatively, you can surf over to IBM's Information Center.

The library key (2) and the device key (3) are the only required keys. All the others are optional. This is very similar to the SAVOBJ command for which Object, Library, and Device are the only required parameters. For the QSRSAVO API, the object information key (1) defaults to *ALL.

-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.