List Save File (QSRLSAVF) API
Required Parameter Group:
| 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
Control Language (CL) information. 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 space format for list
APIs.
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.
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 space format for list APIs. 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 API Examples.
| 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) |
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(3) |
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 |
| 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:
- 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 Control Language (CL)
information.
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.
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.
System serial number. The serial number of the system on
which the save was performed. If the save media is from a System/38(TM),
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