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).
|
|
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 | 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
Open-list API provides crucial information on activation groups -- part 2
One of the many Open List APIs gives programs the ability to determine which activation groups are active in the job and allows the program to retrieve the activation groups' attributes. It can also provide the same information on activation groups in another job. This information can be crucial to programs that, for example, are designed to end other activation groups or are multi-threaded.
In part 1, we discussed what the Open List of Activation Group Attributes (QWVOLAGP) API does and what information the API can return to your program. Now, let's look at how you go about using the API.
Start the conversation
0 comments