Save Object (QsrSave) API

The Save Object (QsrSave) API saves a copy of one or more objects that can be used in the integrated file system.

For detailed restrictions on using this API to save objects in libraries or to save document library objects, see Saving file systems in the Backing up your system topic collection.

Authorities and Locks

User Space

User Space Authority

*USE

User Space Library Authority

*EXECUTE

User Space Lock

*EXCLRD

Objects to Be Saved, Devices, Save While Active, Save-While-Active Message Queue, and Output

Locking

See Save-while-active object locking rules in the Backing up your system topic collection for information about object locking for the Save Object (SAV) command.

Authority

See Authority required for objects used by commands in the Security reference topic collection for authorities required for the Save Object (SAV) command.

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. However, it should be noted that the library name that is actually used is not passed back to the user. Care should be taken when you use 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
0	0	BINARY(4)	Number of variable length records
4	4	BINARY(4)	Offset to first record
8	8	CHAR(8)	Reserved
Note: These fields repeat for each variable length record.
		BINARY(4)	Key
		BINARY(4)	Offset to next record
		CHAR(8)	Reserved
		CHAR(*)	Data

If the length of the data is longer than the key identifier's data length, the data will be truncated at the right. No message will be issued.

If the specified data length 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 and an error message will not be returned.

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.

Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.

Field Descriptions

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

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

Offset to first record. The offset from the beginning of the user space to the first variable length record.

Offset to next record. The offset from the beginning of the user space to the next 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 28.

Reserved. Reserved. The possible value is:

x'00'

This field should contain x'00's.

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 the Field Descriptions.

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

The object path name key and the device path name key are required keys. The other keys are optional.

Key	Type	Field	SAV Command Parameter
1	CHAR(*)	Device path name	DEV
2	CHAR(*)	Object path name	OBJ
3	CHAR(1)	Directory subtree	SUBTREE
4	CHAR(1)	System	SYSTEM
5	CHAR(40)	Change period	CHGPERIOD
6	CHAR(1)	Object precheck	PRECHK
7	CHAR(10)	Target release	TGTRLS
8	CHAR(*)	Update history	UPDHST
9	CHAR(*)	Volume identifier	VOL
10	CHAR(*)	Label	LABEL
11	BINARY(4)	Sequence number	SEQNBR
12	CHAR(7)	Expiration date	EXPDATE
13	CHAR(1)	End of media option	ENDOPT
14	CHAR(1)	Clear	CLEAR
15	CHAR(1)	Data compression	DTACPR
16	CHAR(1)	Data compaction	COMPACT
17	CHAR(*)	Optical file	OPTFILE
18	CHAR(1)	Save while active	SAVACT
19	CHAR(*)	Save-while-active message queue	SAVACTMSGQ
20	CHAR(*)	Output	OUTPUT, INFTYPE
21	CHAR(1)	Use optimum block size	USEOPTBLK
22	CHAR(1)	Save-while-active option	SAVACTOPT
23	CHAR(10)	ASP device name	ASPDEV
24	CHAR(*)	Name pattern	PATTERN
25	CHAR(2)	Scan objects	SCAN
26	CHAR(10)	Synchronization ID	SYNCID
27	CHAR(1)	Private authorities	PVTAUT
28	CHAR(1)	Asynchronous bring	ASYNCBRING

Field Descriptions

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

ASP device name. The names of the auxiliary storage pool (ASP) devices to be included in the save operation. The default is *ALLAVL. The possible values are:

*ALLAVL	The operation includes the system ASP (ASP number 1), all basic user ASPs (ASP numbers 2-32), and all available independent ASPs.
*	The operation includes the system ASP, all basic user ASPs, and, if the job has a linked ASP group, all independent ASPs in the linked ASP group.
*SYSBAS	The operation includes the system ASP and all basic user ASPs.
*ASPGRP	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.

Asynchronous bring. Whether objects should be asynchronously brought into memory during the save processing. Depending on the directory tree structure, the amount of memory available, and the number of ojects which qualify for the save, asynchronously bringing the objects may improve save performance. The best performance improvement may be seen with a well balanced directory tree in which all objects qualify for the save. In situations where a large number of objects reside in a single directory, few objects qualify for the save, or the system is memory constrained, performance may degrade with Asynchronous bring specified. The default is 0. The possible values are:

0	Asynchronous bring is not done. (*NO)
1	Asynchronous brings are done. (*YES)

Change period. A date and time range. Objects that changed within the range are saved.

If this key is not specified, the default of *ALL will be used for the start date and time and the end date and time.

Offset		Type	Field
Dec	Hex
		CHAR(10)	Start date
		CHAR(10)	Start time
		CHAR(10)	End date
		CHAR(10)	End time

End date. The date before which objects that have changed are saved. The possible values are:

*ALL	No ending date is specified. All objects changed since the starting date are saved.
end-date	The date before which objects that have changed are saved in the format CYYMMDD: C Century, where 0 indicates years 19xx and 1 indicates years 20xx. YY Year MM Month DD Day

End time. The time on the end date before which objects that have changed are saved. The possible values are:

*ALL	All times of day are included in the range.
end-time	The time on the end date before which objects that have changed are saved in the format HHMMSS: HH Hour MM Minute SS Second Note: An explicit time is valid only if the ending date is an explicit date.

Start date. The date after which objects that have changed are saved. The possible values are:

*ALL	No starting date is specified. All objects changed prior to the ending date are saved.
*LASTSAVE	Objects are saved that have changed since the last time they were saved with update history. Notes: If this value is specified, the value *ALL must be specified on all other elements of this key. For file systems that are accessed through the network server, the PC archive attribute is used. For other file systems, the system archive attribute is used.
start-date	The date after which objects that have changed are saved in the format CYYMMDD: C Century, where 0 indicates years 19xx and 1 indicates years 20xx. YY Year MM Month DD Day

Start time. The time on the start date after which objects that have changed are saved. The possible values are:

*ALL	All times of day are included in the range.
start-time	The time on the start date after which objects that have changed are saved in the format HHMMSS: HH Hour MM Minute SS Second Note: An explicit time is valid only if the starting date is an explicit date.

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:

1. 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.
2. Clearing an optical volume does initialize it.
3. 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 device data compaction is performed. 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 for the device key support the compaction feature. (*DEV) Note: If 1 is specified for the data compaction key and 2 is specified for the data compression key, only device data compaction is performed if compaction is supported on the device. Otherwise, data compression is performed if supported on the device. If 1 is specified for the data compaction key and 1 is specified for the data compression key, both device data compaction and device data compression are performed if supported on the device.

Data compression. Whether data compression is performed. 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. 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 has the hardware compression feature, hardware compression is done. If the feature is not present, or if the save data is written to optical or save file, software data compression is done. Low (SNA) software compression is used for all devices except optical DVD, which uses medium (TERSE) software compression. (*YES) Note: If 1 is specified for the data compression key and 1 is specified for the data compaction key, both device data compaction and device data compression are performed if supported on the device.
2	If the tape device has the hardware compression feature installed, processing proceeds as if 1 were specified for the data compression key. If the compression feature is not installed or if save data is written to optical or save file, processing proceeds as if 0 were specified for the data compression key. (*DEV) 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 path name. The path name of the device to which the objects are saved.

Offset		Type	Field
Dec	Hex
		BINARY(4)	Number in array
		BINARY(4)	Offset to first device path name
Note: These fields repeat for each device path name
		BINARY(4)	Offset to next device path name
		CHAR(12)	Reserved
		CHAR(*)	Device path name

Device path name. The path name of the device to which the objects are saved. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

device-path-name

The path name of the media definition, media library device, optical device, save file, or tape device used to save the objects. If a media definition, media library device, optical device, or save file path name is specified, it must be the only element in the array. 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.

Number in array. The number of devices used during the save operation. The possible values are:

1-4	The number of devices used during the save operation.

Offset to first device path name. The offset from the beginning of the user space to the first device path name in the list. The possible value is:

n	The offset from the beginning of the user space to the first device path name in the list.

Offset to next device path name. The offset from the beginning of the user space to the next device path name in the list. The possible value is:

n	The offset from the beginning of the user space to the next device path name in the list. If the current device path name is the last device path name in the array, this value should be 0.

Reserved. Reserved. The possible value is:

x'00'

This field should contain x'00's.

Directory subtree. Whether the directory subtrees are included in the save operation. The default is 1. The possible values are:

0	No subtrees are included in the save operation. If a directory matches the object name pattern specified, the objects in the directory are included. If the directory has subdirectories, neither the subdirectories nor the objects in the subdirectories are included. (*NONE)
1	The entire subtree of each directory that matches the object name pattern is included. The subtree includes all subdirectories and the objects within those subdirectories. (*ALL)
2	The objects in the first level of each directory that matches the object name pattern are included. The subdirectories of each matching directory are included, but the objects in the subdirectories are not included. (*DIR)
3	Only the objects that exactly match the object name pattern are included. If the object name pattern specifies a directory, objects in the directory are not included. (*OBJ)
4	The objects that match the object name pattern are processed along with the storage for related objects. Objects that are saved using this value can only be restored using SUBTREE(*STG). (*STG)

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 media in the device cannot be overwritten until the expiration date. The default is 0999999. The possible values are:

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

Label. The file identifier of the media to be used for the save operation. The default is *GEN. The possible values are as follows:

*GEN	The system generates the label. For objects in libraries, this is the equivalent of LABEL(*LIB) on the Save Object (SAVOBJ) and the Save Library (SAVLIB) commands. For document library objects, this is the equivalent of LABEL(*GEN) on the Save Document Library Object (SAVDLO) commands. For objects in other file systems, the label is SAVyyyymmdd, where yyyymmdd is: yyyy Year mm Month dd Day
file-identifier	The identifier (maximum of 17 characters) of the tape file used for the save operation.

Name pattern. Specifies a pattern to be used to include or omit objects.

Offset		Type	Field
Dec	Hex
		BINARY(4)	Number in array
		BINARY(4)	Offset to first pattern name
Note: These fields repeat for each pattern name.
		BINARY(4)	Offset to next pattern name
		CHAR(1)	Option
		CHAR(11)	Reserved
		CHAR(*)	Pattern name

Number in array. The number of pattern names. The possible values are:

1-n	The number of pattern names.

Pattern Name. Specifies a pattern name. The possible value is:

pattern-name

The object name or pattern that can match many names.

Offset to first pattern name. The offset from the beginning of the user space to the first pattern name in the list. The possible value is:

n	The offset from the beginning of the user space to the first pattern name in the list.

Offset to next pattern name. The offset from the beginning of the user space to the next pattern name in the list. The possible value is:

n	The offset from the beginning of the user space to the next pattern name in the list. If the current pattern name is the last pattern name in the array, this value should be 0.

Option. Whether names that match the pattern should be included or omitted from the save operation.

Note: The subtree key specifies whether the subtrees are included or omitted.

The possible values are:

0	All objects which are included by the OBJ parameter are included in the save except those objects which match the PATTERN parameter. This value overrides objects that are included with option 1 and is intended to be used to omit a subset of a previously selected patterns. (*OMIT)
1	Only objects which are included by the OBJ parameter and match the PATTERN parameter are included in the save, unless overridden by an omit specification. (*INCLUDE)

Reserved. Reserved. The possible value is:

x'00'

This field should contain x'00's.

Object path name. The path name of the object to save. You can specify a pattern for this path name.

Offset		Type	Field
Dec	Hex
		BINARY(4)	Number in array
		BINARY(4)	Offset to first object path name
Note: These fields repeat for each object path name.
		BINARY(4)	Offset to next object path name
		CHAR(4)	Reserved
		CHAR(1)	Option
		CHAR(7)	Reserved
		CHAR(*)	Object path name

Number in array. The number of object path names to be saved. The possible values are:

1-300

The number of object path names to be saved.

Object path name. The path name of the object to save. You can specify a pattern for this path name. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

object-path-name

The object path name or pattern that can match many names.

Offset to first object path name. The offset from the beginning of the user space to the first object path name in the list. The possible value is:

n	The offset from the beginning of the user space to the first object path name in the list.

Offset to next object path name. The offset from the beginning of the user space to the next object path name in the list. The possible value is:

n	The offset from the beginning of the user space to the next object path name in the list. If the current object path name is the last object path name in the array, this value should be 0.

Option. Whether names that match the pattern should be included or omitted from the save operation. When determining whether the name matches a pattern, name patterns are always treated as relative to the current working directory.

Note: The subtree key specifies whether the subtrees are included or omitted.

The possible values are:

0	The objects that match the object name pattern are not saved. This value overrides objects that are included with option 1 and is intended to be used to omit a subset of a previously selected pattern. (*OMIT)
1	The objects that match the object name pattern are saved, unless overridden by an omit specification. (*INCLUDE)

Reserved. Reserved. The possible value is:

x'00'

This field should contain x'00's.

Object precheck. Whether the save operation ends if any of the selected objects cannot be saved. The default is 0. The possible values are:

0	The save operation does not end. Objects that can be saved are saved. (*NO)
1	The save operation ends. Nothing is saved unless all of the selected objects can be saved. (*YES)

Optical file. The path name of the optical file that is used for the save operation. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. 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 information can be directed to a spooled file, a stream file, or a user space.

Offset		Type	Field
Dec	Hex
		CHAR(1)	Option
		CHAR(1)	Type of output information
		CHAR(14)	Reserved
		CHAR(*)	Output path name

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

0	No output is created. (*NONE)
1	The output is printed with the job's spooled output. (*PRINT)
2	The output is directed to an existing stream file or user space specified by the output path name.

Output path name. The path name of the existing stream file or user space to which the output of the API is directed. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

path-name

The path name of the existing stream file or user space to which the output of the API is directed.

Reserved. Reserved. The possible value is:

x'00'

This field should contain x'00's.

Type of output information. The type of information that is directed to the spooled file, stream file, or user space specified for the output key. The possible values are:

0	The file contains information about the command, and an entry for each directory. (*SUMMARY)
1	The file contains information about the command, an entry for each directory, and an entry for each object that was not successfully saved. (*ERR)
2	The file contains information about the command, an entry for each directory, an entry for each object that was successfully saved, and an entry for each object that was not successfully saved. (*ALL)

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)

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

0	The objects that are in use are not saved. Objects cannot be updated while they are being saved. (*NO)
1	Objects can be saved and used at the same time. The object checkpoints can occur at different times. (*YES)
2	Objects can be saved and used at the same time. All of the object checkpoints occur at the same time. (*SYNC)

Save-while-active message queue. The path name of the message queue that the save operation uses to notify the user that save-while-active checkpoint processing is complete.

Offset		Type	Field
Dec	Hex
		CHAR(1)	Option
		CHAR(15)	Reserved
		CHAR(*)	Save-while-active message-queue path name

Option. Whether a message should be used to notify the user that save-while-active checkpoint processing is complete. The default is 0. The possible values are:

0	No notification message is sent. (*NONE)
1	The notification message is sent to the work station message queue. (*WRKSTN)
2	The notification message is sent to the specified save-while-active message-queue path name.

Reserved. Reserved. The possible value is:

x'00'

This field should contain x'00's.

Save-while-active message-queue path name. The path name of the message queue that will be used to notify the user that save-while-active checkpoint processing is complete. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

Save-while-active message-queue path name

The path name of the message queue.

Save-while-active option. The options that should be used with the save-while-active key. The possible values are:

0	No special save-while-active options will be used. (*NONE)
1	When 1 or 2 is specified for the save-while-active key, objects will be enabled to be saved when they are being updated if the corresponding system attribute for the object is set. This option should be used only by applications to save objects that are associated with the application and that have additional backup and recovery considerations. See Save-while-active function in the Backing up your system topic collection for additional information. (*ALWCKPWRT)
2	When 1 or 2 is specified for the save-while-active key and a network server storage space in directory '/QFPNWSSTG' qualifies for the save, the network server storage space will be saved even if it is active. (*NWSSTG)
9	When 1 or 2 is specified for the save-while-active key, all save-while-active options will be used. (*ALL) When a network server storage space in directory '/QFPNWSSTG' qualifies for the save, the network server storage space will be saved even if it is active. Objects will be enabled to be saved when they are being updated if the corresponding system attribute for the object is set.

Scan objects. Whether objects will be scanned while being saved when exit programs are registered with any of the integrated file system scan-related exit points and whether objects that previously failed a scan should be saved.

The integrated file system exit points are:

• Integrated File System Scan on Open Exit Program
• Integrated File System Scan on Close Exit Program

Offset		Type	Field
Dec	Hex
		CHAR(1)	Scan during save
		CHAR(1)	Save failed objects

Scan during save. Whether objects will be scanned while being saved when exit programs are registered with any of the integrated file system scan-related exit points. The default is 0. The possible values are:

0	Objects will not be scanned by the scan-related exit programs. (*NO)
1	Objects will be scanned according to the rules described in the scan-related exit programs. (*YES)

Save failed objects. Whether objects that previously failed a scan should be saved. The default is 0. The possible values are:

0	Objects that have either previously failed a scan or that fail a scan by a QIBM_QP0L_SCAN_OPEN exit program during this save will not be saved. (*NOSAVFAILED)
1	Objects that have either previously failed a scan or that fail a scan during this save will be saved. (*SAVFAILED)

Sequence number. The tape file sequence number to be used. The default is -1. The possible values are:

-1	The system saves the object starting after the last sequence number on the first tape. If the first tape is full, an error message is issued and the operation ends. (*END)
1-16777215	The sequence number of the file. Any existing files on the tape at or beyond this sequence number are overwritten.

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 2 for the save while active key.

System. Whether to process objects that exist on the local system or remote systems. The default is 0. The possible values are:

0	Only local objects are processed. (*LCL)
1	Only remote objects are processed. (*RMT)
2	Both local and remote objects are processed. (*ALL)

Target release. The release level of the operating system on which you intend to use the object being saved. The default is *CURRENT. The possible values are:

*CURRENT	The object is to be restored to, and used on, the release of the operating system that is currently running on your system. The object can also be restored to a system with any subsequent release of the operating system.
*PRV	The object is to be restored to the previous release with modification level 0 of the operating system. The object can also be restored to a system with any subsequent release of the operating system installed.
target-release	The release in the format VxRxMx. The object can be restored to a system with the specified release or with any subsequent release of the operating system. When you specify the target-release value, the format VxRxMx is used to specify the release, where Vx is the version, Rx is the release, and Mx is the modification level. Valid values depend on the current version, release, and modification level, and they change with each new release. For a complete list of valid values for TGTRLS, see Current release to previous release support in the Recovering your system topic collection.

Update history. Whether to update the save history on objects saved with this save operation. The save history is used when *LASTSAVE is specified for the start time value of the change period key on a subsequent save operation. The possible values include:

Offset		Type	Field
Dec	Hex
		BINARY(4)	Number in array
Note: This field repeats for each update history value.
		CHAR(1)	Update history

Number in array. The number of update history values. The possible values are:

1-2	The number of update history values.

Update history. Whether to update the save history on objects saved with this save operation. The save history is used when *LASTSAVE is specified for the start time value of the change period key on a subsequent save operation. The default is 0. The possible values include:

0	The save history is not updated. (*NO)
1	The save history is updated. For file systems that are accessed through the network server, the PC archive attribute is set to No. For other file systems, the system archive attribute is set to No. (*YES)
2	The system save history is updated. The system archive attribute is set to No. (*PC)
3	The PC save history is updated. The PC archive attribute is set to No. (*SYS)

Use optimum block size. Whether the optimum block size is used for the save operation. The default is 1. The possible values are:

0

The optimum block size supported by the device is not used. Save uses the default block size supported by all device types. The tape volume can be duplicated to any media format by using the Duplicate Tape (DUPTAP) command. (*NO)

1

The optimum block size supported by all devices is used. If the optimum block size is used, the following can occur: Performance may improve. The tape file that is created is only compatible with a device that supports the block size used. Commands such as Duplicate Tape (DUPTAP) do not duplicate files unless the files are being duplicated to a device that supports the same block size that was used. The value for the data compression key is ignored.

Volume identifier. The volume identifiers of the volumes, or the cartridge identifier of a tape in a tape media library device, on which data is saved. The volumes must be placed in the device in the order specified on this key. After all specified volumes are filled, the save operation continues on whatever volumes are mounted on the device.

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

Length of each volume identifier. The character length of each of the volume identifiers. The possible value follows:

n	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.

Number in array. The number of volume identifiers that are used during the save operation. The default is 0. The possible values are:

0	The volume currently placed in the device is used. If 0 is specified for a tape media library device, volume identifiers must be supplied by using the Tape Management exit program during the save or restore operation. If 0 is specified, the length of each volume identifier value is ignored. (*MOUNTED) Note: This value cannot be specified for an optical media library device.
1-75	The number of volume identifiers used during the save operation.

Offset to first volume identifier. The offset from the beginning of the user space to the first volume identifier in the list. The possible value is:

n	The offset from the beginning of the user space to the first volume identifier in the list.

Offset to next volume identifier. The offset from the beginning of the user space to the next object volume identifier in the list. The possible value is:

n	The offset from the beginning of the user space to the next volume identifier in the list. If the current volume identifier is the last volume identifier in the array, this value should be 0.

Volume identifier. The volume identifiers of one or more volumes to be used. The possible value is:

Volume identifier

The volume identifiers of one or more volumes to be used.

Dependencies between Keys

The following two tables list the dependencies between the different keys. If the dependency pertains only to 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
Device = optical library device	Volume identifier
Synchronization ID <> *NONE	Save while active = 2

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
Device = media definition	Optical file Sequence number Volume identifier
Device = optical device	Label Sequence number Use optimum block size
Device = save file	Clear = 2 End of media option Expiration date Label Optical file Sequence number Use optimum block size Volume identifier
Device = tape device	Optical file
Save while active = 0	Save-while-active message queue Save-while-active option
Private authorities = 1	Target release = release earlier than    Version 6 Release 1

Relationship to SAV Command

Because of the relationship between the QsrSave API and the SAV command, the following situations should be noted:

• Message text: Several messages produced by this API refer to parameters or values of the SAV 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 QsrSave for integrated file system objects. If QsrSave is used to save objects in libraries or document library objects (DLOs), the generated output indicates that the corresponding library or document library objects (DLO) command generated the media.

Error Messages

Message ID	Error Message Text
CPF0001 E	Error found on &1 command.
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.
CPF9999 E	Function check. &1 unmonitored by &2 at statement &5, instruction &3.

---

API introduced: V4R3

---

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