Manage Learn to apply best practices and optimize your operations.

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

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.

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.

Key value summary

Key Data Type Description Corresponding parameter on the SAVOBJ command
1 CHAR(*). An array of 20-character elements. Object name in bytes 1-10. Object type in bytes 11-20. Object information OBJ & OBJTYPE
2 CHAR(*) Library LIB
3 CHAR(*) Device DEV
4 CHAR(20) Save file SAVF
5 CHAR(1) Update history UPDHST
6 CHAR(*) Volume identifier VOL
7 BINARY(4) Sequence number SEQNBR
8 CHAR(*) Label LABEL
9 CHAR(7) Expiration date EXPDATE
10 CHAR(1) End of media option ENDOPT
11 CHAR(10) Target release TGTRLS
12 CHAR(1) Clear CLEAR
13 CHAR(1) Object precheck PRECHK
14 CHAR(1) Save while active SAVACT
15 BINARY(4) Save while active wait time for object locks SAVACTWAIT
16 CHAR(20) Save while active message queue SAVACTMSGQ
17 CHAR(*) File member FILEMBR
18 CHAR(1) Save access paths ACCPTH
19 CHAR(1) Save file data SAVFDTA
20 CHAR(1) Storage STG
21 CHAR(1) Data compression DTACPR
22 CHAR(1) Data compaction COMPACT
23 CHAR(1) Output OUTPUT
24 CHAR(20) Qualified output file OUTFILE
25 CHAR(11) Output member OUTMBR
26 CHAR(1) Type of output information INFTYPE
27 CHAR(*) Optical file OPTFILE
28 CHAR(1) Use optimum block size USEOPTBLK
29 CHAR(*) Omit library OMITLIB
30 CHAR(*) Omit object information OMITOBJ
31 CHAR(20) Media definition MEDDFN
32 CHAR(10) ASP device name ASPDEV
33 BINARY(4) Save while active wait time for pending record changes SAVACTWAIT
34 BINARY(4) Save while active wait time for other pending changes SAVACTWAIT

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.

Dig Deeper on Data backup, storage and retrieval on iSeries