| 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(*) |
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.
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 |
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.
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 |
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.
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.
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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The save file list consists of:
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.
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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:
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:
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.
| 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. |
[ Back to top | Backup and Recovery APIs | APIs by category ]