Save Object List (QSRSAVO) API

Required Parameter Group:

1	Qualified user space name	Input	Char(20)
2	Error Code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: No

The Save Object List (QSRSAVO) API saves a list of objects or spooled files specified by the user. The list of objects, as well as any additional information needed for the save operation, is generated by the user into a user space.

Authorities and Locks

User Space

User Space Authority: *USE
User Space Library Authority: *EXECUTE
User Space Lock: *SHRNUP

Objects to Be Saved
If the user has save system (*SAVSYS) special authority, the following authorities are not needed. To save user profiles, you need *SAVSYS special authority. To save private authorities, you need *SAVSYS or all object (*ALLOBJ) special authority.

Object Authority: *OBJEXIST
Library Authority: *EXECUTE
Object Lock: *SHRNUP
Library Lock: *SHRUPD

Note: Lower levels of locking may be used for objects in certain cases. See Save while active object locking rules in the Backup and recovery topic collection for more information about these special cases.

Spooled Files to Be Saved
If the user has save system (*SAVSYS) special authority, the following authorities are not needed.

Output Queue Authority: *OBJEXIST
Output Queue Library Authority: *EXECUTE
Output Queue Lock: *EXCLRD

Note: Additional authority may be needed to change spooled file attributes. See New Attributes Format for more information.

Devices

Save File Authority: *USE and *ADD
Save File Library Authority: *EXECUTE
Save File Lock: *EXCLRD
Tape or Optical Authority: *USE
Tape or Optical Lock: *EXCL
Media Library Device Lock: *SHRUPD
Media Definition Authority: *USE
Media Definition Library Authority: *EXECUTE
Media Definition Lock: *EXCLRD
Auxiliary Storage Pool (ASP): *USE

Note: If the save file will be cleared, *OBJMGT authority is also required.

Save While Active

Message Queue Authority: *OBJOPR and *ADD
Message Queue Library Authority: *EXECUTE

Output Files

Output File Lock: *SHRRD

If the output file does not exist:

Output File Library Authority: *READ and *ADD

If the output file exists and a new member will be added:

Output File Authority: *OBJMGT, *OBJOPR, and *ADD
Output File Library Authority: *EXECUTE and *ADD

If the output file exists and an existing member will be appended:

Output File Authority: *OBJMGT and *ADD
Output File Library Authority: *EXECUTE

If the output file exists and an existing member will be replaced:

Output File Authority: *OBJMGT, *OBJOPR, *ADD, and *DLT
Output File Library Authority: *EXECUTE

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The user space that is to hold all the information for the save operation. The first 10 characters contain the user space name. The second 10 characters contain the name of the library where the user space is located. See User Space Format for the format of the information in the user space.

You can use the following special values for the library name. It should be noted, however, that the library name that is actually used is not passed back to the user. Care should be taken when using these special values to avoid unexpected results.

*CURLIB	The job's current library is used to locate the user space. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list is used to locate the user space.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

User Space Format

The following defines the format for the information in the user space. For detailed descriptions of the fields in the user space format, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Number of variable length records
Note: These fields repeat for each variable length record.
		BINARY(4)	Length of variable length record
		BINARY(4)	Key
		BINARY(4)	Length of data
		CHAR(*)	Data

If you specify a data length that is longer than the key field's defined data length, the data is truncated at the right. No error message is returned.

If you specify a data length that is shorter than the key field's defined data length, an error message is returned for binary fields. If the field is a character field, the data is padded with blanks.

Note: This does not apply to keys that allow a list of values to be specified. In these cases, the amount of data read is based on the specified number of entries in the list.

If keys are duplicated in the user space, only the last value for a given key is used for the save operation.

It is recommended, but not required, to align each variable length record on a 4-byte boundary. That is, you should make the length of each variable length record a multiple of 4, even if the data length is not a multiple of 4.

Field Descriptions

Data. The data used to specify the value for the given key.

Key. The parameter of the Save Object (SAVOBJ) command to specify. See Valid Keys for the list of valid keys.

Length of data. The length of the data used to specify the value for the given parameter.

Length of variable length record. The length of the variable length record.

Number of variable length records. The number of variable length records that are passed in the user space. The valid range is from 2 through 38.

Valid Keys

The following table lists the valid keys for the key field area of the variable length record. For detailed descriptions of the keys, see Field Descriptions.

Some messages for this API refer to parameters and values of the Save Object (SAVOBJ) command. This table can also be used to locate the key names that correspond to the SAVOBJ command parameters. The field descriptions contain, in addition to detailed descriptions, the corresponding parameter values.

The library key and the device key are required keys. The other keys are optional.

Key	Type	Field	SAVOBJ Command Parameter
1	CHAR(*)	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
35	CHAR(*)	Spooled file data	SPLFDTA
45	CHAR(*)	Queue data	QDTA
46	CHAR(10)	Synchronization ID	SYNCID
47	CHAR(1)	Private authorities	PVTAUT

Field Descriptions

The values shown in parentheses are the corresponding values for the SAVOBJ command parameters.

ASP device name. The names of the auxiliary storage pool (ASP) devices to be included in the save operation. When saving user profiles, these are the ASPs from which private authorities are saved. The default is *. The possible values are:

*	The operation includes the system ASP (ASP number 1), all basic user ASPs (ASP numbers 2-32), and, if the job has a linked ASP group, all independent ASPs in the linked ASP group.
*ALLAVL	The operation includes the system ASP, all basic user ASPs, and all available independent ASPs. Note: This value is valid only when saving user profiles.
*SYSBAS	The operation includes the system ASP and all basic user ASPs.
*CURASPGRP	If the job has a linked ASP group, all independent ASPs in the linked ASP group are included in the save operation.
ASP device name	The operation includes the specified independent ASP.

Clear. Whether active data on the media is cleared or replaced automatically. Active data is any file on the media that has not expired. Clearing active data removes all files from the volume, starting at the specified sequence number for the tape. Replacing active data on optical media replaces only the optical files created by this operation. The default is 0.

Notes:

Clearing a tape does not initialize it. Before the save command is issued, you should initialize the tape to a standard label format by using the Initialize Tape (INZTAP) command and specifying a value on the NEWVOL parameter.
Clearing an optical volume does initialize it.
If a volume that is not initialized is encountered during the save operation, an inquiry message is sent and an operator can initialize the volume.

The possible values are:

0	None of the media is cleared automatically. If the save operation encounters active data on a tape or save file, an inquiry message is sent, allowing the operator to either end the save operation or clear the media. If the save operation encounters the specified optical file, an inquiry message is sent, allowing the operator to either end the save operation or replace the file. (*NONE)
1	All of the media is cleared automatically. (*ALL) If tapes are used and a sequence number is specified for the sequence number key, the first tape is cleared beginning at that sequence number. All tapes following the first tape are completely cleared. To clear the entire first tape, 1 must be specified for the sequence number key.
2	All media after the first volume is cleared automatically. If the save operation encounters active data on the first tape, an inquiry message is sent, allowing the operator to either end the save operation or clear the media. If the save operation encounters the specified optical file on the first volume, an inquiry message is sent, allowing the operator to either end the save operation or replace the file. (AFTER) Note:* This value is not valid for save files.
3	Active data on the media is replaced automatically. Optical volumes are not initialized. Tapes and save files are cleared automatically in the same way as the value 1. (*REPLACE)

Data compaction. Whether data compaction is used. The default is 1. The possible values are:

0	Device data compaction is not performed. (*NO)
1	Device data compaction is performed if the data is saved to tape and all tape devices specified support the compaction feature. (*DEV)

Data compression. Whether data compression is used. The default is 2. The possible values are:

0	No data compression is performed. (*NO)
1	If the save operation is to tape and the target device supports compression, hardware compression is performed. If compression is not supported on the device, or if the save data is written to optical or save file, software compression is performed. Low (SNA) software compression is used for all devices except optical DVD, which uses medium (TERSE) software compression. (*YES)
2	If the save operation is to tape and the target device supports compression, hardware compression is performed. Otherwise, no data compression is performed. (DEV) Note:* Note: If 2 is specified for the data compression key and 1 is specified for the data compaction key, only device data compaction is performed if compaction is supported on the device. Otherwise, data compression is performed if supported on the device.
3	If the save operation is to a save file or optical, low (SNA) software data compression is done. If the save operation is being done while other jobs on the system are active and software data compression is used, the overall system performance may be affected. Low compression is usually faster than medium or high compression. The compressed data is usually larger than if medium or high compression is used. (*LOW)
4	If the save operation is to a save file or optical, medium (TERSE) software data compression is done. If the save operation is being done while other jobs on the system are active and software data compression is used, the overall system performance may be affected. Medium compression is usually slower than low compression but faster than high compression. The compressed data is usually smaller than if low compression is used and larger than if high compression is used. (*MEDIUM)
5	If the save operation is to a save file or optical, high (LZ1) software data compression is done. If the save operation is being done while other jobs on the system are active and software data compression is used, the overall system performance may be affected. High compression is usually slower than low and medium compression.The compressed data is usually smaller than if low or medium compression is used. (*HIGH)

Device. The names of the devices used for the save operation. The device must already be known on the system by a device description. For the format of this field, see Device Key Format.

End of media option. The operation that is performed automatically on the tape or optical volume after the save operation ends. If more than one volume is used, this key applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached. The default is 0.

Note: This parameter is valid only if a tape or optical device name is specified. For optical devices, 2 is the only value supported; 0 and 1 are ignored.

The possible values are:

0	The tape is automatically rewound, but not unloaded, after the operation ends. (*REWIND)
1	The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive. (*LEAVE)
2	The tape is automatically rewound and unloaded after the operation ends. Some optical devices eject the volume after the operation ends. (*UNLOAD)

Expiration date. The expiration date of the tape file or optical file created by the save operation. If a date is specified, the file is protected and cannot be overwritten until the specified expiration date. The default is 0999999. The possible values are:

0999999	The file is protected permanently. (*PERM)
Expiration date	The date when protection for the file ends, specified in the format CYYMMDD: C Century, where 0 indicates years 19xx and 1 indicates years 20xx. YY Year MM Month DD Day

File member. A list of the database files and their members that are to be saved. Each database file specified here must also be specified in the list of objects to be saved. If this key is not specified, the default of *ALL will be used for both the file name and the member name. For the format of this field, see File Member Format.

Label. The name that identifies the data file on the tape. Although the label key is defined as CHAR(*), the maximum length of a label is currently 17. If the length of data field is specified as more than 17, the label is truncated such that only the first 17 characters are used. The default is *LIB.

*LIB	The file label is created by the system using the name of the library specified for the library key.
Data file identifier	The data file identifier of the data file used. This option is valid only for a single-library save operation.

Library. A list of libraries that contain the objects that are saved. If more than one library is specified, *ALL must be the only object name specified (object information key) and the device cannot be *SAVF. For the format of this field, see Library Key Format.

Media definition. The name and library of the media definition that identifies the devices and media used to contain the saved data. For information about creating and using a media definition, see Saving to multiple devices to reduce your save window in the Backing up your system topic collection and Create Media Definition (QSRCRTMD, QsrCreateMediaDefinition) API. The first 10 characters contain the media definition name; the second 10 characters contain the library in which the media definition is located.

You can use these special values for the library name:

*CURLIB	The job's current library is used to locate the media definition. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list.

Object information. A list of the name and type of the objects to be saved. If *ALL is specified for the object name and object type, the list cannot contain other entries. The default for both the object name and the object type is *ALL. For the format of this field, see Object Information Format.

Object precheck. Whether the save operation for a library should end if all objects specified by the API do not satisfy all the following conditions:

The objects exist
The objects were not previously found to be damaged
The objects are not locked by another job
The requester of the save operation has authority to save the objects

The default is 0. The possible values are:

0	The save operation for a library continues, saving only those objects that can be saved. (*NO)
1	If one or more objects cannot be saved after the specified objects are checked, the save operation for a library ends before any data is written. (*YES)

Omit libraries. A list of the libraries to be omitted from the save operation. The default is *NONE. For the format of this field, see Omit Library Key Format.

Omit object information. A list of the name and type of the objects and library to be omitted from the save operation. If *ALL is specified for the object name and object type, the list cannot contain other entries. The default for both the object name and the object type is *ALL. For the format of this field, see Omit Object Information Format.

Optical file. The name that identifies the file on the optical volume. Although the optical file is defined as CHAR(*), the maximum length of an optical file name is currently 256 characters. If the length of data field is specified as more than 256 characters, the name is truncated such that only the first 256 characters are used. The default is '*'. The possible values are:

''*	The system generates an optical file name in the root directory of the optical volume.
'Optical-directory-path-name/'*	The system generates an optical file name in the specified directory of the optical volume.
Optical file path name	The path name of the optical file that is used for the save operation, beginning with the root directory of the volume.

Output. Whether a list of information about the saved objects is created. The default is 0. The possible values are:

0	No output listing is created. (*NONE)
1	The output is printed with the job's spooled output. (*PRINT)
2	The output is directed to the database file specified with the output file key. (*OUTFILE)

Output member. The name of the database file member used to save the object information. This field also determines whether to replace or add the data if the member already exists. The defaults are *FIRST for the output member name field and 0 for the option field. For the format of this field, see Output Member Format.

Private authorities. Whether to save private authorities for the objects that are saved. The default is 0. The possible values are:

0	No private authorities are saved. (*NO)
1	Private authorities are saved for each object that is saved. To specify this value, you need save system (SAVSYS) or all object (ALLOBJ) special authority. (*YES)

Qualified output file. The qualified name of the database file to which the information about the objects is directed. This key is required only if the output key is set to 2. The first 10 characters contain the output file name; the second 10 characters contain the output file library. The possible values for output file library are:

*CURLIB	The job's current library is used to locate the output file. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list is used to locate the output file.
Library name	The name of the library where the output file is located.

Queue data. A description of queue data to be saved. The default is no queue data. For the format of this key, see Queue Data Key Format.

Save access paths. Whether the logical file access paths that are dependent on the physical files being saved are also saved. The default is 2. The possible values are:

0	The logical file access paths are not saved. (*NO)
1	The specified physical files and all eligible logical file access paths over them are saved. (*YES)
2	The system value QSAVACCPTH determines whether to save the logical file access paths that are dependent on the physical files that are being saved. (*SYSVAL)

Save file. The name and library of the save file that is used to contain the saved data. The first 10 characters contain the save file name; the second 10 characters contain the library where the save file is located.

You can use these special values for the library name:

*CURLIB	The job's current library is used to locate the save file. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list.

Save file data. For save file objects, whether only the description of a save file, or both the description and the contents of a save file are saved. The default is 1. The possible values are:

0	Only the description of a save file is saved. (*NO)
1	The description and contents of a save file are saved. (*YES)

Note: For System/38™ environments, the default value of 1 is not valid; therefore, this key must explicitly be set to a value of 0.

Save while active. Whether an object can be updated while it is being saved. The default is 0. The possible values are:

0	Objects that are in use are not saved. (*NO)
1	Objects in a library can be saved while they are in use by another job. Objects in a library may reach checkpoints at different times and may not be in a consistent state in relationship to each other. (*SYSDFN)
2	Objects in a library can be saved while they are in use by another job. All the objects in a library reach a checkpoint together. They are saved in a consistent state in relationship to each other. (*LIB)
3	Objects in a library can be saved while they are in use by another job. All the objects and all the libraries in the save operation reach a checkpoint together. They are saved in a consistent state in relationship to each other. (*SYNCLIB)

Save while active message queue. The name and library of the message queue that is used to notify the user that the checkpoint processing for a library is complete. The first 10 characters contain the message queue name; the second 10 characters contain the name of the library where the message queue is located. If *NONE or *WRKSTN is specified for the message queue name, blanks must be specified for the message queue library. The defaults are *NONE for the message queue name and blanks for the library.

The possible values for the message queue name are:

*NONE	No notification message is sent.
*WRKSTN	The notification message is sent to the work station message queue. This is not valid in batch mode.
Message queue name	The name of the message queue.

The possible values for the message queue library are:

*CURLIB	The job's current library is used to locate the message queue. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list is used to locate the message queue.
Library name	The name of the library where the message queue is located.

Save while active wait time for object locks. If an object is not available, the amount of time to wait for a lock on the object before continuing the save operation. The default is 120. The possible values are:

-1	No maximum wait time exists.
0-99999	The time (in seconds) to wait.

Save while active wait time for other pending changes. For each library, the amount of time to wait for transactions with other pending changes to reach a commit boundary. Other pending changes include the following:

Data Definition Language (DDL) object level changes for that library.
Any API commitment resource that was added without the option to allow normal save processing. For more information, see Add Commitment Resource (QTNADDCR) API.

If a commit boundary is not reached for a library in the specified time, library is not saved. The default is -2. The possible values are:

-1	No maximum wait time exists. (*NOMAX)
-2	The system waits up to the value specified on the Save while active wait time for object locks key for the types of transactions that are listed above to reach a commit boundary. (*LOCKWAIT)
0-99999	The time (in seconds) to wait. If 0 is specified, and only one object is specified on the Object information key, and that object is a file, then the system will save the object without requiring the types of transactions that are listed above to reach a commit boundary.

Save while active wait time for pending record changes. For each group of objects that are checkpointed together, the amount of time to wait for transactions with pending record changes to reach a commit boundary. The Save while active key determines which objects are checkpointed together. If 0 is specified, all objects being saved must be at commit boundaries. If any other value is specified, all objects that are journaled to the same journals as the objects being saved must reach commit boundaries. If a commit boundary is not reached in the specified time, the save operation is ended, unless the value -3 is specified. The default is -2. The possible values are:

-1	No maximum wait time exists. (*NOMAX)
-2	The system waits up to the value specified on the Save while active wait time for object locks key for transactions with pending record changes to reach a commit boundary. (*LOCKWAIT)
-3	The system will save objects without requiring transactions with pending record changes to reach a commit boundary. Therefore, objects may be saved with partial transactions. (*NOCMTBDY) If you restore an object that was saved with partial transactions, you cannot use the object until you apply or remove journal changes (APYJRNCHG or RMVJRNCHG command) to reach commit boundaries. You will need all journal receivers that contain information about the partial transactions to apply or remove the changes. Until you apply or remove the changes, any future save of that object will include the partial transactions, even if you do not specify this value.
0-99999	The time (in seconds) to wait.

Sequence number. The sequence number to use for the save operation when tape is used. The default is -1. The possible values are:

-1	The save operation begins after the last sequence number on the tape volume.
1-16777215	The sequence number of the file to be used for the save operation.

Spooled file data. A description of spooled file data to be saved. The default is no spooled file data. For the format of this key, see Spooled File Data Key Format.

Storage. Whether the system storage that is occupied by the data portion of the following objects in the library being saved is freed:

Files
Modules
Programs
Service programs
Structured Query Language (SQL) packages
Journal receivers

The default is 0. The possible values are:

0	The storage occupied by the data portion of the objects is not freed. (*KEEP)
1	The storage occupied by the data portion of the objects is freed. The storage is freed only after all the objects in the library are saved successfully. (*FREE)

Synchronization ID. The name of the synchronized checkpoint in which this save while active operation will participate. The synchronized checkpoint must already be started by the Start Save Synchronization (STRSAVSYNC) command. The default is *NONE. The possible values are:

*NONE

The checkpoint for this save while active operation is not synchronized with any other save while active operation.

name

The name of the synchronized checkpoint. If you specify a name, you must also specify a value of 3 for the save while active key.

Note: If you specify a name, the value used for the save while active wait time for pending record changes key is the largest value specified among all of the participating save operations. However, if any participating save operation specifies -3, then all participating save operations must specify -3.

Target release. The release of the operating system on which the objects will be restored and used. The object types specified (in the object information field) must exist on the specified release. The default is *CURRENT. The possible values are:

*CURRENT	The objects are restored to, and used on, the release of the operating system currently running on the system.
*PRV	The objects are to be restored on the previous release that has modification level 0 of the operating system.
Release level	The release level in the format VxRxMx, where x is the number of the version, release, and modification level.

Type of output information. The type of information that is printed or directed to the output database file. The default is 0. The possible values are:

0	The list contains an entry for each object requested to be saved. (*OBJ)
1	The list contains an entry for each library requested to be saved. (*LIB)
2	The list contains an entry for each object, database file member, and spooled file requested to be saved. (*MBR)
3	The list contains an entry for each library that is requested to be saved and an entry for each object that was not successfully saved. (*ERR)

Update history. Whether the save history information of each object is changed to the date, time, and location of this save operation. The default is 1. The possible values are:

0	The save history information of each object saved is not updated. (*NO)
1	The last save date, time, and location is updated in each object saved. (*YES)

Use optimum block size. Whether the tape device's optimum block size should be used. The default is 0. The possible values are:

The tape device's optimum block size is not used. A block size that is compatible with all IBM i releases and tape devices is used. (*NO)

The tape device's optimum block size is used. The system may create a tape that is only compatible with a tape device that supports the same block size. Performance will likely but not necessarily improve. Commands such as Duplicate Tape (DUPTAP) do not duplicate the tape unless it is being duplicated to a tape device that supports the same block size. (*YES) Data compression is ignored when optimum block size is used.

Volume identifier. The volume identifiers of the tape volumes or optical volumes on which the object data is to be saved. All volume identifiers must be entered in the order in which you want them saved. The default is *MOUNTED. For the format of this field, see Volume Identifier Format.

Device Key Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: This field repeats for each device name.
		CHAR(10)	Device name

Field Descriptions

Device name. The name of the device used for the save operation. The possible values for each element of the array are:

*SAVF	The save operation is done using the save file specified by the save file key. If specified, it must be the only element in the array.
*MEDDFN	The save operation is done by using the devices and media that are identified in the media definition, which is specified by the media definition key. If specified, it must be the only element in the array.
Media library device name	The name of the media library device used for the save operation. If specified, it must be the only element in the array.
Optical device name	The name of the optical device used for the save operation. If specified, it must be the only element in the array.
Tape device name	The name of the tape device used for the save operation. A maximum of four tape devices may be used. They must be specified in the order in which they should be used.

Number in array. The number of devices to be used during the save operation. The possible values are 1 through 4.

File Member Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: These fields repeat for each file.
		CHAR(10)	File name
		CHAR(2)	Reserved
		BINARY(4)	Number of members
Note: This field repeats for each member associated with the given file.
		CHAR(10)	Member

Field Descriptions

File name. The name of the file being saved. The possible values are:

*ALL	The list of member names that follow this value applies to all files indicated in the list of objects to save. If *ALL is specified for the file name, it must be the only file name in the list.
Database file name	The name of the database file from which the listed members are saved.

Member. The name of the member to save. The possible values are:

*ALL	All members are saved from the specified file. If *ALL is specified for member name, it must be the only member name for that file.
*NONE	No members are saved from the specified file. Only the file description is saved.
Member name	The name of the member to save. It may be either a simple name or a generic name.

Number in array. The number of file and member structures used during the save operation. The possible values are 1 through 50.

Number of members. The number of member names for the given file name. Possible values are 1 through 50.

Reserved. An ignored field.

Library Key Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: This field repeats for each library name.
		CHAR(10)	Library name

Field Descriptions

Library name. The name of the library containing the objects. The possible values are:

*SPLF	Spooled file data is to be saved. If this value is specified, it must be the only element in the array, the spooled file data key must be specified, and *ALL must be specified for the object name and object type.
Library name	Either a simple or generic library name

Number in array. The number of libraries used during the save operation. The possible values are 1 through 32767.

Object Information Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: These fields repeat for each object name.
		CHAR(10)	Object name
		CHAR(10)	Object type

Field Descriptions

Number in array. The number of objects that are specified for this key. There is no limit for the number in array field. The total amount of information in the user space, however, cannot exceed 16MB.

Object name. The name of the object that is to be saved. The possible values are:

*ALL	All the objects in the specified libraries, depending on the values specified for object type
Object name	Either a simple name or a generic name

Object type. The type of the object that is to be saved. The possible values are:

*ALL	All objects with the specified object name that are valid types for the SAVOBJ command on the current release of the system.
*USRPRF	All user profiles with the specified object name. If this value is specified, all entries in the object information key must specify this type and the saved data must be restored with the RSTUSRPRF command.
Object type	A valid type for the SAVOBJ command on the current release of the system

Omit Library Key Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: This field repeats for each library name.
		CHAR(10)	Library name

Field Descriptions

Library name. The name of the library containing the objects to omit. The possible values are:

*NONE	No libraries are excluded from the save operation.
Library name	Either a simple or generic library name

Number in array. The number of libraries to omit from the save operation. The possible values are 1 through 32767.

Omit Object Information Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: These fields repeat for each object name.
		CHAR(10)	Object name
		CHAR(10)	Library name
		CHAR(10)	Object type

Field Descriptions

Library name. The name of the library that is to be omitted. The possible values are:

*ALL	All the libraries, depending on the values specified for object and object type
Library name	Either a simple name or a generic name

Number in array. The number of values that are specified for this key. The possible values are 1 through 32767.

Object name. The name of the object that is to be omitted. The possible values are:

*ALL	All the objects in the specified libraries, depending on the values specified for object type
Object name	Either a simple name or a generic name

Object type. The type of the object that is to be omitted. The possible values are:

*ALL	All objects with the specified object name that are valid types for the SAVOBJ command on the current release of the system
*USRPRF	All user profiles with the specified object name.
Object type	A valid type for the SAVOBJ command on the current release of the system

Output Member Format

Offset		Type	Field
Dec	Hex	Type	Field
		CHAR(10)	Output member name
		CHAR(1)	Option

Field Descriptions

Option. An indicator of whether to add to or replace the existing member. The possible values are:

0	The existing records in the specified database file member are replaced by the new records. (*REPLACE)
1	The new records are added to the existing information in the database file member. (*ADD)

Output member name. The name of the file member that receives the output. The possible values are:

*FIRST	The first member in the file is used and receives the output.
Member name	If the member does not exist, the system creates it.

Queue Data Key Format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Number in array
Note: This field repeats for each queue data value.
		BIN(4)	Queue data

Field Descriptions

Queue data. For queue objects, whether only the description of a queue, or both the description and the contents of a queue are saved. The default is 0.

The possible values are:

0	Only the description of a queue is saved. (*NONE)
1	The description and contents of a standard data queue are saved. Only the description of a Distributed Data Management (DDM) data queue is saved. (*DTAQ)

Number in array. The number of queue data values. The possible value is 1.

Spooled File Data Key Format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Spooled file data
4	4	BINARY(4)	Length of spooled file data header
8	8	BINARY(4)	Offset to spooled file selection list

Field Descriptions

Length of spooled file data header. The length of the spooled file data header information. The possible values are:

8	The header information ends with the length field.
12	The header information ends with the offset to selection list field.

Offset to spooled file selection list. The offset from the start of the user space to the first spooled file selection list entry. See Spooled File Selection List Entry Format. The default is 0. If the value of the spooled file data field is 2, the value of this field must be greater than 0. Otherwise, the value must be 0.

Spooled file data. Whether to save spooled file data and attributes. The default is 0. The possible values are:

0	No spooled file data is saved. (*NONE)
1	For each output queue that is saved, all available spooled file data on the output queue is saved. (*ALL)
2	Selected spooled file data is saved. The offset to selection list field must be specified.

Spooled File Selection List Entry Format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Length of spooled file selection list entry
4	4	BINARY(4)	Offset to next spooled file selection list entry
8	8	BINARY(4)	Include or omit
12	C	BINARY(4)	Selection criteria format
16	10	BINARY(4)	Offset to selection criteria
20	14	BINARY(4)	Offset to new attributes

Field Descriptions

Include or omit. Whether the spooled files selected by this entry are included or omitted from the save operation. Omit takes precedence over include. The possible values are:

0	Spooled files that match all of the values specified in the selection criteria are omitted from the save operation.
1	Spooled files that match all of the values specified in the selection criteria are included in the save operation, unless another entry omits them. At least one entry must have this value.

Length of spooled file selection list entry. The length of the spooled file selection list entry information. The possible values are:

20	The selection list entry ends with the offset to selection criteria field.
24	The selection list entry ends with the offset to new attributes field.

Offset to new attributes. The offset from the start of the user space to the new attributes for the spooled files included by this selection list entry. The value must be 0 if the Include or omit field value is 0. For the format of the new attributes, see New Attributes Format.

Offset to next spooled file selection list entry. The offset from the start of the user space to the next spooled file selection list entry. The value must be 0 for the last entry in the list.

Offset to selection criteria. The offset from the start of the user space to the selection criteria.

Selection criteria format. The format of the spooled file selection criteria. The possible values are:

1	The selection criteria is specified by the Spooled File ID Format. This format identifies exactly one spooled file.
2	The selection criteria is specified by the Spooled File Attributes Format. This format identifies any number of spooled files.

Spooled File ID Format

This is the format of the spooled file selection criteria when a value of 1 is specified for the selection criteria format field. The criteria specified must uniquely identify a single spooled file.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Length of Spooled file ID
4	4	CHAR(26)	Qualified job name
30	1E	CHAR(10)	Spooled file name
40	28	BINARY(4)	Spooled file number
44	2C	CHAR(8)	Job system name
52	34	CHAR(7)	Creation date
59	3B	CHAR(6)	Creation time

Field Descriptions

Creation date. The date the spooled file was created. This value is considered after the qualified job name, spooled file name, spooled file number, and job system name values. The possible values are:

*LAST	The spooled file with the latest creation date and time for the specified qualified job name, spooled file name, spooled file number, and job system name is selected.
*ONLY	There is only one spooled file with the specified qualified job name, spooled file name, spooled file number, and job system name.
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. This field must be set to blanks if *LAST or *ONLY is specified for creation date. This value is considered after the qualified job name, spooled file name, spooled file number, job system name, and creation date values. The possible values are:

*LAST	The spooled file with the latest creation time for the specified qualified job name, spooled file name, spooled file number, job system name, and creation date is selected.
*ONLY	There is only one spooled file with the specified qualified job name, spooled file name, spooled file number, job system name, and creation date.
Time	The time the spooled file was created, in the format HHMMSS: HH Hour MM Minute SS Second

Job system name. The name of the system where the job that owns the spooled file ran. This value is considered after the qualified job name, spooled file name, and spooled file number values. The possible values are:

*ONLY	There is only one spooled file with the specified qualified job name, spooled file name, spooled file number, creation date, and creation time.
*CURRENT	The spooled file created on the current system with the specified qualified job name, spooled file name, spooled file number, creation date, and creation time is selected.
*ANY	The job system name is not considered when selecting a spooled file. Use this value when you want the creation date and creation time values to take precedence over the job system name when selecting a spooled file.
System name	The name of the system where the job that owns the spooled file ran.

Length of spooled file ID. The length of the spooled file ID information. The possible values are:

65	The spooled file ID ends with the creation time field.

Qualified job name. The name of the job that owns the spooled file. The qualified job name has three parts:

Job name	CHAR(10)	A specific job name or the following special value: * Current job. The rest of the qualified job name must be blank.
User name	CHAR(10)	A specific user profile name or blanks when the job name is *.
Job number	CHAR(6)	A specific job number or blanks when the job name is *.

Spooled file name. The name of the spooled file.

Spooled file number. The unique number of the spooled file. The possible values are:

0	There is only one spooled file with the specified qualified job name and spooled file name. (*ONLY)
-1	The spooled file with the highest number for the specified qualified job name and spooled file name is selected. (*LAST)
-2	The spooled file number is not considered when selecting a spooled file. Use this value when you want the system name value or spooled file create date and spooled file create time values to take precedence over the spooled file number when selecting a spooled file. (*ANY)
1-999999	The number of the spooled file for the specified qualified job name and spooled file name.

Spooled File Attributes Format

This is the format of the spooled file selection criteria when a value of 2 is specified for the selection criteria format field.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Length of spooled file attributes
4	4	CHAR(20)	Qualified output queue
24	18	CHAR(10)	Spooled file name
34	22	CHAR(10)	Job name
44	2C	CHAR(10)	User name
54	36	CHAR(6)	Job number
60	3C	CHAR(10)	User-specified data
70	46	CHAR(8)	Job system name
78	4E	CHAR(10)	Form type
88	58	CHAR(13)	Starting creation date and time
101	65	CHAR(13)	Ending creation date and time

Field Descriptions

Ending creation date and time. Spooled files with a creation date and time less than or equal to this date and time are selected. The default is *ALL. The following special value is allowed:

*ALL	Ending creation date and time are not used to select spooled files.

The date and time must be specified in the format CYYMMDDHHMMSS:

C: Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY: Year
MM: Month
DD: Day
HH: Hour
MM: Minute
SS: Second

Form type. Spooled files with this form type are selected. Either a specific value or generic value may be specified. The default is *ALL. The following special values are allowed:

*ALL	Spooled files with any form type are selected.
*STD	Spooled files that specify the standard form type are selected.

Job name. Spooled files owned by this job are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special value is allowed:

*ALL	Spooled files owned by any job are selected.

Job number. Spooled files owned by a job with this job number are selected. If a job number is specified, then a specific job name and a specific user name must also be specified. The default is *ALL. The following special value is allowed:

*ALL	Spooled files owned by a job with any job number are selected.

Job system name. Spooled files owned by a job on this system are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special values are allowed:

*ALL	Spooled files created on any system are selected.
*CURRENT	Spooled files owned by a job on the current system are selected.

Length of spooled file attributes. The length of the spooled file data attributes information. The possible values are:

24	The spooled file attributes end with the qualified output queue field.
34	The spooled file attributes end with the spooled file name field.
44	The spooled file attributes end with the job name field.
54	The spooled file attributes end with the user name field.
60	The spooled file attributes end with the job number field.
70	The spooled file attributes end with the user-specified data field.
78	The spooled file attributes end with the job system name field.
88	The spooled file attributes end with the form type field.
101	The spooled file attributes end with the starting creation date and time field.
114	The spooled file attributes end with the ending creation date and time field.

Qualified output queue. Spooled files on this output queue are selected, if they are found in the ASPs specified for the ASP device key. The qualified output queue has two parts:

Object name

CHAR(10). A specific or generic output queue name or the following special value:

*ALL	Spooled files on all output queues that satisfy the library name are selected.

Library name

CHAR(10). A specific or generic library name, or one of the following special values:

*ALL	All libraries.
*CURLIB	The job's current library. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The libraries in the library list.

Spooled file name. Spooled files with this name are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special value is allowed:

*ALL	Spooled files with any name are selected.

Starting creation date and time. Spooled files with a creation date and time greater than or equal to this date and time are selected. The default is *ALL. The following special value is allowed:

*ALL	Starting creation date and time are not used to select spooled files.

The date and time must be specified in the format CYYMMDDHHMMSS:

C: Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY: Year
MM: Month
DD: Day
HH: Hour
MM: Minute
SS: Second

User name. Spooled files owned by this user are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special value is allowed:

*ALL	Spooled files with any user are selected.

User-specified data. Spooled files with this user-specified data value are selected. Either a specific value or generic value may be specified. The default is *ALL. The following special value is allowed:

*ALL	Spooled files with any user-specified data value are selected.

New Attributes Format

This is the format of new attributes to be assigned to the selected spooled files.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Length of new attributes
4	4	BINARY(4)	Expiration days

Field Descriptions

Expiration days. The number of days from the start of the operation when the selected spooled files will expire. The expiration date will be set for the spooled files on the system after they have been successfully saved. The default is 0.

Note: The user needs additional authority to use any value other than 0. The default value of 0 will be used for any spooled files which the user is not authorized to change. The user is authorized to change the expiration date of a spooled file if any of the following conditions are met.

The user owns the spooled file.
The user has spool control (*SPLCTL) special authority.
The user has job control (*JOBCTL) special authority, and the output queue on which the spooled file resides is specified as OPRCTL(*YES).
The user owns the output queue on which the spooled file resides, and the output queue is specified as AUTCHK(*OWNER).
The user has read, add, and delete authorities to the output queue on which the spooled file resides, and the output queue is specified as AUTCHK(*DTAAUT).

The possible values are:

-1	The expiration date for the selected spooled files will be set to *NONE (no expiration date).
0	The expiration date for the selected spooled files will not be changed.
1-366	The expiration date for the selected spooled files will set to the number of days specified past the date that the save operation begins.

Length of new attributes. The length of the new attributes information. The possible values are:

8	The new attributes end with the expiration days field.

Volume Identifier Format

Offset		Type	Field
Dec	Hex	Type	Field
		BINARY(4)	Number in array
Note: These fields repeat for each volume identifier.
		BINARY(4)	Length of volume identifier
		CHAR(*)	Volume identifier

Field Descriptions

Length of volume identifier. The character length of the identifier of the volume. The possible value is:

The size of a single volume identifier. The maximum size of a tape volume identifier is 6 characters. The maximum size of an optical volume identifier is 32 characters. If a volume identifier larger than the maximum size is entered for this key, it is truncated to the maximum size. If the volume identifier is *MOUNTED, this value must be 8.

Number in array. The number of volume identifiers used during the save operation. The possible values are 1 through 75.

Volume identifier. The identifier of a volume. The possible values are:

*MOUNTED	The volume currently placed in the device is used. If MOUNTED is specified, it must be the only value specified. This value cannot be specified for an optical media library device. MOUNTED cannot be specified for a tape media library device unless a category is set with the Set Tape Category (SETTAPCGY) command.
Volume identifier	The identifier of a volume.

Dependencies between Keys

The following two tables list the dependencies between the different keys. If the dependency holds only for a certain value, then that value is also shown (key = n, where n is the value). Otherwise, if the dependency is true for all values of the key, then only the name of the key is given.

The following table lists the conditions where specifying a certain key forces the use of another key.

If you specify...	...must be specified
Multiple library names or generic library	Object name = *ALL
Device = tape device	Volume identifier ¹ Sequence number ¹ Label ¹ Expiration date ¹ End of media option ¹
Device = optical device	Volume identifier Optical file ¹ Expiration date ¹
Device = media definition	Media definition
Output = 1	Type of output information ¹
Output = 2	Output file Output member ¹ Type of output information ¹
Save while active = 1, 2, or 3	Save while active wait time for object locks ¹ Save while active wait time for pending record changes ¹ Save while active wait time for other pending changes ¹ Save while active message queue ¹
Storage = 1	Save while active = 0 ¹
Object type = *USRPRF	Library = QSYS Label = QFILEUPR¹
Library name = *SPLF	Object name = ALL¹ Object type = ALL¹ Spooled file data = 2
Library name <> *SPLF	Spooled file data = 0¹ or 1
Synchronization ID <> *NONE	Save while active = 3
Notes: This key does not have to be explicitly specified. The default may be taken to satisfy this dependency.

The following table lists the conditions where specifying a certain key excludes the user from using another key, or a particular value of that key.

If you specify...	...cannot be specified
Save file	Volume identifier Sequence number Label Expiration date End of media option Clear = 2 Optical file Use optimum block size Media definition
Media definition	Volume identifier Sequence number Optical file
Tape, optical, or media definition for the device	Save file
Save while active = 0	Save while active wait time for object locks Save while active wait time for pending record changes Save while active wait time for other pending changes Save while active message queue
Output = 0	Output file Output member Type of output information
Optical file	Label Use optimum block size
Object type = *USRPRF	Any other object type Save while active Save while active wait time for object locks Save while active wait time for pending record changes Save while active wait time for other pending changes Save while active message queue File member Queue data Save access paths Save file data Spooled file data Storage Omit library Media definition
Spooled file data <> 0	Target release = release earlier than Version 5 Release 4
Queue data = 1	Target release = release earlier than Version 5 Release 4
Private authorities = 1	Target release = release earlier than Version 6 Release 1

Relationship to SAVOBJ and SAVSECDTA Commands

Because of the relationship between the QSRSAVO API and the SAVOBJ and SAVSECDTA commands, the following situations should be noted:

Message text: Several messages produced by this API refer to parameters or values of the SAVOBJ command (for example, *AFTER). To determine which key a given parameter corresponds to, see Valid Keys. To determine which key value a given parameter value corresponds to, see Field Descriptions.
Command type: The command type listed for the API on headings of displays and print files is SAVOBJ or SAVSECDTA, not QSRSAVO.
This API can be used to save one or more user profiles. It does not save other objects that are saved by the SAVSECDTA command, such as authorization lists and authority holders. The saved user profiles must be restored with the RSTUSRPRF command.
This API can be used to save user profiles for a previous release; the SAVSECDTA command saves user profiles for the current release only. When a user profile is saved for a previous release, the interactive profile section of the user profile which contains session settings and product level information, is not saved.

Error Messages

Message ID	Error Message Text
CPF222E E	&1 special authority is required.
CPF24B4 E	Severe error while addressing parameter list.
CPF3700 E	All CPF37xx messages could be signalled. xx is from 01 to FF.
CPF3800 E	All CPF38xx messages could be signalled. xx is from 01 to FF.
CPF3C31 E	Object type &1 is not valid.
CPF3C4D E	Length &1 for key &2 not valid.
CPF3C81 E	Value for key &1 not valid.
CPF3C82 E	Key &1 not valid for API &2.
CPF3C83 E	Key &1 not allowed with value specified for key &2.
CPF3C84 E	Key &1 required with value specified for key &2.
CPF3C85 E	Value for key &1 not allowed with value for key &2.
CPF3C86 E	Required key &1 not specified.
CPF3C87 E	Key &1 allows one value with special value.
CPF3C90 E	Literal value cannot be changed.
CPF3CF1 E	Error code parameter not valid.
CPF5729 E	Not able to allocate object &1.
CPF9800 E	All CPF98xx messages could be signaled. xx is from 01 to FF.
CPFB8ED E	Device description &1 not correct for operation.

API introduced: V3R1

[ Back to top | Backup and Recovery APIs | APIs by category ]