List Save File (QSRLSAVF) API
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Qualified save file name | Input | Char(20) |
| 4 | Object name filter | Input | Char(10) |
| 5 | Object type filter | Input | Char(10) |
| 6 | Continuation handle | Input | Char(36) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The List Save File (QSRLSAVF) API lists the contents of a save file. The generated list replaces any data that already exists in the user space; it does not add the new list to an existing one. The generated list is not sorted.
Authorities and Locks
- Save File Library Authority
- *USE
- Save File Authority
- *USE
- Save File Lock
- *EXCLRD
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list
- Format name
- INPUT; CHAR(8)
The content and format of the information returned for the save file. The possible format names are:
SAVF0100 Library level SAVF0200 Object level SAVF0300 Member level SAVF0400 Spooled files For more information, see the specified formats in the Format of the Generated List.
- Qualified save file name
- INPUT; CHAR(20)
The save file about which to list information, and the library in which the save file is located. The first 10 characters contain the save file name, and the second 10 characters contain the library name. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list
- Object name filter
- INPUT; CHAR(10)
The name of the objects to search for. This name may be a simple name, a generic name, or the special value *ALL. If the name is not a valid name, an empty list will be returned. This field must be *ALL for the SAVF0100 format.
- Object type filter
- INPUT; CHAR(10)
The type of objects to search for. You may either enter a specific type or the special value *ALL. For a complete list of the available object types, see the Control language topic collection. This field must be *ALL for the SAVF0100 format, the SAVF0300 format, and the SAVF0400 format.
- Continuation handle
- INPUT; CHAR(36)
The handle used to continue from a previous call to this API that resulted in partially complete information. You can determine if a previous call resulted in partially complete information by checking the information status field in the generic user space header following the API call. For information about the generic header, see User spaces.
If the API is not attempting to continue from a previous call, this parameter must be set to blanks. Otherwise, a valid continuation value must be supplied. The value may be obtained from the continuation handle returned field in the header section. See Format of the Generated List for information about the header section.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated List
The save file list consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section (containing one of the following):
- SAVF0100 format
- SAVF0200 format
- SAVF0300 format
- SAVF0400 format
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see the DLTOLDSPLF example programs in Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | Save file name specified |
| 38 | 26 | CHAR(10) | Save file library name specified |
| 48 | 30 | CHAR(10) | Object name filter specified |
| 58 | 3A | CHAR(10) | Object type filter specified |
| 68 | 44 | CHAR(36) | Continuation handle specified |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
| 20 | 14 | CHAR(10) | Save file name used |
| 30 | 1E | CHAR(10) | Save file library name used |
| 40 | 28 | CHAR(36) | Continuation handle returned |
SAVF0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Library saved |
| 10 | A | CHAR(10) | Save command |
| 20 | 14 | CHAR(8) | Save date and time |
| 28 | 1C | BINARY(4) | Auxiliary storage pool |
| 32 | 20 | BINARY(4) UNSIGNED | Records |
| 36 | 24 | BINARY(4) | Objects saved |
| 40 | 28 | BINARY(4) | Access paths |
| 44 | 2C | CHAR(10) | Save active |
| 54 | 36 | CHAR(6) | Release level |
| 60 | 3C | CHAR(1) | Data compressed |
| 61 | 3D | CHAR(8) | System serial number |
| 69 | 45 | CHAR(1) | Private authorities |
| 70 | 46 | CHAR(2) | Reserved |
| 72 | 48 | CHAR(10) | Auxiliary storage pool device name |
| 82 | 52 | CHAR(2) | Reserved |
| 84 | 54 | BINARY(4) | Members in library saved |
| 88 | 58 | BINARY(4) | Spooled files saved |
| 92 | 5C | CHAR(10) | Synchronization ID |
SAVF0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Object name |
| 10 | A | CHAR(10) | Library saved |
| 20 | 14 | CHAR(10) | Object type |
| 30 | 1E | CHAR(10) | Extended object attribute |
| 40 | 28 | CHAR(8) | Save date and time |
| 48 | 30 | BINARY(4) | Object size |
| 52 | 34 | BINARY(4) | Object size multiplier |
| 56 | 38 | BINARY(4) | Auxiliary storage pool |
| 60 | 3C | CHAR(1) | Data saved |
| 61 | 3D | CHAR(10) | Object owner |
| 71 | 47 | CHAR(20) | Document library object (DLO) name |
| 91 | 5B | CHAR(63) | Folder |
| 154 | 9A | CHAR(50) | Text description |
| 204 | CC | CHAR(10) | Auxiliary storage pool device name |
SAVF0300 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | File name |
| 10 | A | CHAR(10) | Library saved |
| 20 | 14 | CHAR(10) | Member name |
| 30 | 1E | CHAR(10) | Extended object attribute |
| 40 | 28 | CHAR(8) | Save date and time |
| 48 | 30 | BINARY(4) | Members saved |
SAVF0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(10) | Spooled file name |
| 36 | 24 | BINARY(4) | Spooled file number |
| 40 | 28 | CHAR(8) | Job system name |
| 48 | 30 | CHAR(7) | Creation date |
| 55 | 37 | CHAR(6) | Creation time |
| 61 | 3D | CHAR(10) | Output queue name |
| 71 | 47 | CHAR(10) | Output queue library |
| 81 | 51 | CHAR(3) | Reserved |
Field Descriptions
Access paths. The number of logical file access paths that were saved for the library.
Auxiliary storage pool. The auxiliary storage pool (ASP) of the object when it was saved. For the SAVF0100 format, this is the ASP of the library. For the SAVF0200 format, this is the ASP of the object. The possible values are:
| 1 | System ASP |
| 2 - 32 | Basic user ASPs |
| 33 - 255 | Independent ASPs |
Auxiliary storage pool device name. The name of the independent auxiliary storage pool (ASP) device of the object when it was saved. For the SAVF0100 format, this is the ASP of the library. For the SAVF0200 format, this is the ASP of the object.
Creation date. The date the spooled file was created, in the format CYYMMDD:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
Creation time. The time the spooled file was created, in the format HHMMSS:
| HH | Hour |
| MM | Minute |
| SS | Second |
Continuation handle returned. A continuation point for the API.
This value is set based on the contents of the information status variable in the generic header for the user space. The following situations can occur:
- Information status-C. The information returned in the user space is valid and complete. No continuation is necessary and the continuation handle is set to blanks.
- Information status-P. The information returned in the user space is valid but incomplete. The user may call the API again, continuing where the last call ended. The continuation handle contains a value that may be supplied as an input parameter in later calls.
- Information status-I. The information returned in the user space is not valid or complete. The contents of the continuation handle are unpredictable.
Continuation handle specified. The handle used to continue from a previous call to this API that resulted in partially complete information.
Data compressed. Whether the data was stored in compressed format. The possible values are:
| 0 | The data is not compressed. |
| 1 | The data is compressed. |
Data saved. Whether the data for this object was saved with the object. The possible values are:
| 0 | The data was not saved. The object's storage was freed by a previous save command before this save operation. |
| 1 | The data was saved. The object's storage was not freed by a previous save command before this save operation. |
Document library object (DLO) name. The name of the document, folder, or mail object that was saved. If the object is a document or folder, the first 12 characters will contain the DLO name. If the object is a mail object, the full 20 characters will be used for the mail object name. If the save file does not contain DLO information, this field will be blank.
Extended object attribute. Extended information about the object type. If there is not an extended object attribute for the object, this field will be blank.
File name. The name of the file that was saved.
Folder. The name of the folder that was saved. The folder name is a fully qualified name. If the object is not a *FLR or *DOC object, this field will be blank. For *DOC and *FLR objects, this field will be set to the qualified name of the folder or to *NONE.
Format name. The format of the returned output.
Job name. The name of the job that owns the spooled file.
Job number. The number of the job that owns the spooled file.
Job system name. The name of the system where the job that owns the spooled file ran.
Library saved. The name of the library from which the objects are saved.
Members in library saved. The number of members saved for the library.
Member name. The name of the file member that is saved. The member names are not in sorted order.
Members saved. The number of members saved for the file.
Object name. The name of the object saved. If the object is a DLO object, this field will contain the system name of the object.
Object name filter specified. The name of the objects to search for. Only objects with names that match the filter are listed.
Object owner. The name of the object owner's user profile.
Objects saved. The number of objects that are saved for this library.
Object size. The size of the object in units of the size multiplier. The true object size is equal to or smaller than the object size multiplied by the object size multiplier.
Object size multiplier. The value to multiply the object size by to get the true size. The value is 1 if the object is smaller than or equal to 999 999 999 bytes, 1024 if it is larger than 999 999 999 but smaller than or equal to 4 294 967 295, and 4096 if larger than 4 294 967 295.
Object type. The type of object. For a list of object types, see the Control language topic collection.
Object type filter specified. The type of objects to search for. Only object types that match the filter are listed.
Output queue library. The name of the output queue library that contained the spooled file.
Output queue name. The name of the output queue that contained the spooled file.
Private authorities. Whether the save operation specified that private authorities should be saved with the objects. The possible values are:
| 0 | Objects were saved without their private authorities. |
| 1 | Objects were saved with their private authorities. |
Records. The number of records used to contain the saved information in the save file.
Release level. The earliest release level of the operating system on which the objects can be restored.
Reserved. An ignored field.
Save active. Whether objects in the library are allowed to be updated while they are being saved. The possible values are:
| *LIB | Objects in the library are saved while in use by another job. All of the objects in the library reached a checkpoint together and were saved in a consistent state in relationship to each other. All objects in the library are saved at the same time. |
| *NO | Objects in the library are not saved while in use by another job. |
| *SYNCLIB | Objects in the library are saved while in use by another job. All of the objects and all of the libraries in the save operation reached a checkpoint together. The objects and the libraries were saved in a consistent state in relationship to each other. |
| *SYSDFN | Objects in the library are saved while in use by another job. Objects in the library may have reached a checkpoint at different times and may not be in a consistent state in relationship to each other. |
| *YES | Document library objects are saved while in use by another job. This value is valid only if the SAVDLO command is used for the save operation. |
Save command. The save command that is used when the save operation is performed. The possible values are:
| QSYS | Contents of the save file are created by the operating system by using a function other than the CL commands. |
| SAVCFG | Saves configuration information. |
| SAVCHGOBJ | Saves objects that changed since the date and time specified on the referenced date parameter. |
| SAVDLO | Saves documents or folders located in library QDOC. |
| SAVLIB | Saves a copy of a library. |
| SAVLICPGM | Saves licensed programs. |
| SAVOBJ | Saves an object or group of objects from the same library. |
| SAVSECDTA | Saves objects required for the security function. |
Save date and time. The time at which the objects were saved in system time-stamp format.
Save file library name specified. The name of the save file library as specified in the call to the API.
Save file library name used. The name of the save file library used to produce the listing.
Save file name specified. The name of the save file as specified in the call to the API.
Save file name used. The name of the save file used to produce the listing.
Spooled file name. The name of the spooled file.
Spooled file number. The number of the spooled file in the job that owns it.
Spooled files saved. The number of spooled files saved in the save file.
Synchronization ID. The name that was used to synchronize checkpoints for more than one save while active operation.
System serial number. The serial number of the system on which the save was performed. If the save media is from a System/38™, the system serial number will be blank.
Text description. The text description of the object. If the object is a DLO object, the following pertains:
- Characters 1 through 44 contain the text description.
- The last 6 characters are padded with blanks.
User name. The name of the user who owns the spooled file.
User space library name specified. The name of the library containing the user space as specified in the call to the API.
User space library name used. The name of the library used to produce the listing.
User space name specified. The name of the user space as specified in the call to the API.
User space name used. The name of the user space used to produce the listing.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF22FD E | Continuation handle not valid for API &1. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3704 E | Request ended; data management error occurred. |
| CPF3743 E | File cannot be restored, displayed, or listed. |
| CPF3782 E | File &1 in &2 not a save file. |
| CPF3793 E | Machine storage limit reached. |
| CPF381F E | Save file &1 cannot be processed by API QSRLSAVF. |
| CPF3812 E | Save file &1 in &2 in use. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9806 E | Cannot perform function for object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9809 E | Library &1 cannot be accessed. |
| CPF9810 E | Library &1 not found. |
| CPF9812 E | File &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9822 E | Not authorized to file &1 in library &2. |
| CPF9830 E | Cannot assign library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Backup and Recovery APIs | APIs by category ]