Save Object (SAVOBJ)

The Save Object (SAVOBJ) command saves a copy of a single object or a group of objects located in the same library. When *ALL is specified for the Objects (OBJ) parameter, objects can be saved from a list of libraries. When saving to a save file, only one library can be specified. The system saves the specified objects by writing a copy of each object on tape or optical media, or in a save file. The objects are not affected in the system unless the command specifies that the storage should be freed. However, the description of each object is changed with the date, time, and place when it was last saved, unless *NO is specified for the Update history (UPDHST) parameter.

For job queues, user queues, message queues, and logical files, only the object descriptions are saved, and the contents of the objects are not saved. However, logical file access paths can be saved by specifying *YES for the Save access paths (ACCPTH) parameter. The contents of spooled files on output queues can be saved by specifying *ALL for the Spooled file data (SPLFDTA) parameter. The contents of a save file can be saved by specifying *YES for the Save file data (SAVFDTA) parameter or using the Save Save File Data (SAVSAVFDTA) command. The contents of a data queue can be saved by specifying *DTAQ for the Queue data (QDTA) parameter.

Note: This command ignores all file overrides currently in effect for the job, except for the output file.

Restrictions:

Parameters

Keyword Description Choices Notes
OBJ Objects Single values: *ALL
Other values (up to 300 repetitions): Generic name, name
Required, Positional 1
LIB Library Single values: *SELECT, *USRSPC
Other values (up to 300 repetitions): Generic name, name
Required, Positional 2
DEV Device Single values: *SAVF, *MEDDFN
Other values (up to 4 repetitions): Name
Required, Positional 3
OBJTYPE Object types Single values: *ALL
Other values (up to 300 repetitions): Character value
Optional, Positional 4
VOL Volume identifier Single values: *MOUNTED
Other values (up to 75 repetitions): Character value
Optional, Positional 5
SEQNBR Sequence number 1-16777215, *END Optional
LABEL Label Character value, *LIB Optional
EXPDATE File expiration date Date, *PERM Optional
ENDOPT End of media option *REWIND, *LEAVE, *UNLOAD Optional
SAVF Save file Qualified object name Optional
Qualifier 1: Save file Name
Qualifier 2: Library Name, *LIBL, *CURLIB
MEDDFN Media definition Qualified object name Optional
Qualifier 1: Media definition Name
Qualifier 2: Library Name, *LIBL, *CURLIB
OPTFILE Optical file Path name, * Optional
USEOPTBLK Use optimum block *YES, *NO Optional
TGTRLS Target release Start of change*CURRENT, *PRV, V7R3M0, V7R4M0, V7R5M0End of change Optional
UPDHST Update history *YES, *NO Optional
CLEAR Clear *NONE, *ALL, *AFTER, *REPLACE Optional
PRECHK Object pre-check *NO, *YES Optional
SAVACT Save active *NO, *LIB, *SYNCLIB, *SYSDFN Optional
SAVACTWAIT Save active wait time Element list Optional
Element 1: Object locks 0-99999, 120, *NOMAX
Element 2: Pending record changes 0-99999, *LOCKWAIT, *NOCMTBDY, *NOMAX
Element 3: Other pending changes 0-99999, *LOCKWAIT, *NOMAX
SAVACTMSGQ Save active message queue Qualified object name Optional
Qualifier 1: Save active message queue Name, *NONE, *WRKSTN
Qualifier 2: Library Name, *LIBL, *CURLIB
SYNCID Synchronization ID Name, *NONE Optional
FILEMBR File member Values (up to 50 repetitions): Element list Optional
Element 1: File Name, *ALL
Element 2: Member Single values: *ALL, *NONE
Other values (up to 50 repetitions): Generic name, name
ACCPTH Save access paths *SYSVAL, *NO, *YES Optional
SAVFDTA Save file data *YES, *NO Optional
SPLFDTA Spooled file data *NONE, *ALL Optional
QDTA Queue data *NONE, *DTAQ Optional
PVTAUT Private authorities *NO, *YES Optional
STG Storage *KEEP, *FREE Optional
DTACPR Data compression Start of change*DEV, *NO, *YES, *LOW, *MEDIUM, *HIGH, *ZLIBEnd of change Optional
COMPACT Data compaction *DEV, *NO Optional
OMITLIB Libraries to omit Single values: *NONE, *USRSPC
Other values (up to 300 repetitions): Generic name, name
Optional
OMITOBJ Objects to omit Single values: *USRSPC
Other values (up to 300 repetitions): Element list
Optional
Element 1: Object Qualified object name
Qualifier 1: Object Generic name, name, *NONE, *ALL
Qualifier 2: Library Generic name, name, *ALL
Element 2: Object type Character value, *ALL
SELECT Select Single values: *USRSPC
Other values (up to 300 repetitions): Element list
Optional
Element 1: Include or omit *INCLUDE, *OMIT
Element 2: Object Qualified object name
Qualifier 1: Object Generic name, name, *ALL
Qualifier 2: Library Generic name, name, *ALL
Element 3: Object type Character value, *ALL
Element 4: Object attribute Character value, *ALL, *BLANK
Element 5: File member Generic name, name, *ALL, *ALLMBR
ASPDEV ASP device Name, *, *SYSBAS, *CURASPGRP Optional
OUTPUT Output *NONE, *PRINT, *OUTFILE Optional
OUTFILE File to receive output Qualified object name Optional
Qualifier 1: File to receive output Name
Qualifier 2: Library Name, *LIBL, *CURLIB
OUTMBR Output member options Element list Optional
Element 1: Member to receive output Name, *FIRST
Element 2: Replace or add records *REPLACE, *ADD
INFTYPE Type of output information *OBJ, *LIB, *MBR, *ERR Optional
CMDUSRSPC Command user space Qualified object name Optional
Qualifier 1: Command user space Name
Qualifier 2: Library Name, *LIBL, *CURLIB

Objects (OBJ)

Specifies the names of one or more objects or the generic name of each group of objects to be saved. All the objects must be in the library specified for the Library (LIB) parameter. If *ALL is specified or defaulted for the Object types (OBJTYPE) parameter, all the object types listed in the description of that parameter are saved, provided they are in the specified library and have the specified names.

This is a required parameter.

Single values

*ALL
All the objects in the specified libraries are saved, depending on the values specified for the OBJTYPE parameter.

Other values (up to 300 repetitions)

generic-name
Specify one or more generic names of groups of objects in the specified library to be saved. A generic name is a character string that contains one or more characters followed by an asterisk (*). If an * is not specified with the name, the system assumes that the name is a complete object name.
name
Specify one or more names of specific objects to be saved. Both generic names and specific names can be specified in the same command.

Library (LIB)

Specifies which libraries contain the objects to be saved. If *ALL is specified for the Objects (OBJ) parameter, up to 300 library names can be specified.

This is a required parameter.

Single values

*SELECT
The libraries identified in the Select (SELECT) parameter are saved. Only one library can be specified in the selection criteria when saving to a save file. Special value *SPLF cannot be specified in the selection criteria.
*USRSPC
The libraries identified in the user space specified for the Command user space (CMDUSRSPC) parameter are saved. Only one library can be specified in the user space when saving to a save file. Special value *SPLF cannot be specified in the user space.

Other values (up to 300 repetitions)

generic-name
Specify the generic name of the libraries that contain objects to be saved. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all libraries with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete library name.

Note: A generic library name cannot be specified when saving to a save file.

name
Specify the name of the library that contains objects to be saved.

Note: Only one library can be specified when saving to a save file.

Device (DEV)

Specifies the name of the device used for the save operation. The device name must already be known on the system by a device description.

This is a required parameter.

Single values

*SAVF
The save operation is done using the save file specified for the Save file (SAVF) parameter.
*MEDDFN
The save operation is done using the devices and media identified in the media definition specified for the Media definition (MEDDFN) parameter.

Other values

optical-device-name
Specify the name of the optical device used for the save operation.
tape-media-library-device-name
Specify the name of the tape media library device used for the save operation.
tape-device-name
Specify the names of one or more tape devices used for the save operation. If a virtual tape device is used, it must be the only device specified. If multiple tape devices are used, they must have compatible media formats and their names must be specified in the order in which they are used. Using more than one tape device permits one tape volume to be rewound and unloaded while another tape device processes the next tape volume. To use more than one device in parallel, a media definition must be specified.

Object types (OBJTYPE)

Specifies the types of system objects to be saved.

Single values

*ALL
All object types that are specified by name and are in the specified library are saved. If *ALL is also specified for the Objects (OBJ) parameter, all the objects in the library that are of the types that can be saved are saved.

Other values (up to 300 repetitions)

object-type
Specify the value for each of the types of objects to be saved, such as command (*CMD), file (*FILE), or program (*PGM).

To see a complete list of object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt). For a description of the object types, see "Object types" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Volume identifier (VOL)

Specifies the volume identifiers of the volumes, or the cartridge identifiers of tapes in a tape media library device, on which the data is saved. The volumes must be placed in the device in the same order as specified for this parameter.

Single values

*MOUNTED
The data is saved on the volumes placed in the device. For a media library device, the volume to be used is the next cartridge in the category mounted by the Set Tape Category (SETTAPCGY) command.

Note: This value cannot be specified when using an optical media library device.

Other values (up to 75 repetitions)

character-value
Specify the identifiers of one or more volumes in the order in which they are placed in a device and used to save the data.

Sequence number (SEQNBR)

Specifies, when tape is used, the sequence number to use as the starting point for the save operation.

*END
The save operation begins after the last sequence number on the first tape. If the first tape is full, an error message is issued and the operation ends.
1-16777215
Specify the sequence number of the file to be used for the save operation.

Label (LABEL)

Specifies the name that identifies the data file on the tape volume that is to be used for the save operation. If this parameter is used on the save command, the same label must be specified on the restore command.

Note: You cannot specify *SAVLIB on this parameter, since it is a special value for the Label (LABEL) parameter of the restore command and would prevent you from restoring what you saved.

*LIB
The file label is created by the system using the name of the library specified for the Library (LIB) parameter.
character-value
Specify the data file identifier of the data file used for the save operation. A maximum of 17 characters can be used. This option is valid only for a single-library save operation.

File expiration date (EXPDATE)

Specifies the expiration date of the file created by the save operation. If a date is specified, the file is protected and cannot be overwritten until the specified expiration date.

Notes:

  1. This parameter is valid for tape and optical files.
  2. Specifying this parameter does not protect against a later save operation specifying CLEAR(*ALL).
*PERM
The file is protected permanently.
date
Specify the date when protection for the file ends.

End of media option (ENDOPT)

Specifies the operation that is automatically done on the tape or optical volume after the save operation ends. If more than one volume is used, this parameter applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached.

Note: This parameter is valid only if a tape or optical device name is specified for the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.

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

Save file (SAVF)

Specifies the save file that is used to contain the saved data. The save file must be empty, unless *ALL is specified for the Clear (CLEAR) parameter.

Note: A value must be specified for this parameter if *SAVF is specified for the Device (DEV) parameter.

Qualifier 1: Save file

name
Specify the name of save file to be used.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the thread is used to locate the save file. If no current library entry exists in the library list, the QGPL library is used.
name
Specify the name of the library where the save file is located.

Media definition (MEDDFN)

Specifies the media definition (*MEDDFN) object that identifies the devices and media used to contain the saved data. For information about creating and using a media definition, see the Recovering your system book, SC41-5304, and the Create Media Definition API in the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

If a media definition is specified, the VOL, SEQNBR, SAVF, and OPTFILE parameters cannot be specified. The volume identifiers and sequence numbers are specified in the media definition.

Qualifier 1: Media definition

name
Specify the name of the media definition to be used.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
name
Specify the name of the library to be searched.

Optical file (OPTFILE)

Specifies the path name of the optical file that is used for the save operation, beginning with the root directory of the volume.

For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

*
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'
Specify the path name of the optical file.

Use optimum block (USEOPTBLK)

Specifies whether or not the optimum block size is used for the save operation.

Note: Specifying USEOPTBLK(*YES) may result in a tape that can be duplicated only to a device that supports the same block size.

*YES
The optimum block size supported by the device is used for Save commands. If the block size that is used is larger than a block size that is supported by all device types, then:
  • 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 which supports the same block size that was used.
  • The value for the DTACPR parameter is ignored.
*NO
The optimum block size supported by the device is not used. Save commands use the default block size supported by all device types. The tape volume can be duplicated to any media format using the Duplicate Tape (DUPTAP) command.

Target release (TGTRLS)

Specifies the release of the operating system on which you intend to restore and use the object.

When specifying 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. For example, V5R3M0 is version 5, release 3, modification 0.

Valid values depend on the current version, release, and modification level of the operating system, and they change with each new release. You can press F4 while prompting this command parameter to see a list of valid target release values.

To specify that an object be saved for distribution to a system at a different release level than the system on which the save operation is to occur, the procedure differs for program or non-program objects and by the release level on which a program object is created. If, for example, you are saving an object for distribution to a target system running on an earlier release, you have the following choices:

For program objects:

For non-program objects:

You can:

  1. save the object specifying the targeted earlier release
  2. restore the object on the target system.
*CURRENT
The object is to be restored to, and used on, the release of the operating system currently running on your system. The object can also be restored to a system with any subsequent release of the operating system installed.
*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.
character-value
Specify 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 installed.

Update history (UPDHST)

Specifies whether the save history information of each saved object is changed with the date, time, and location of this save operation. The save history information for an object is displayed using the Display Object Description (DSPOBJD) command. The save history information is used to determine which journal entries are processed when RCVRNG(*LASTSAVE) and FROMENT(*LASTSAVE) or FROMENTLRG(*LASTSAVE) are used on the Apply Journaled Changes (APYJRNCHG) command.

*YES
The last save date, time, and location is updated in each object saved.
*NO
The save history information contained in the description of each object saved is not updated.

Note: UPDHST(*NO) should be used for a save operation that is not intended for recovery. For example, if the save data is sent, record by record, to another system and the save file immediately deleted, the save history information is probably not to be updated.

Clear (CLEAR)

Specifies whether active data on the media is automatically cleared or replaced. Active data is any file on the media that has not expired. For saves to tape, clearing active data will make any files on the tape volume beyond the last file written by the save operation no longer accessible. For saves to optical, the files written by the save operation can be automatically replaced while other files on the volume remain active, or all active files can be automatically cleared. Clearing does not erase the data, it just makes the files no longer accessible.

Notes:

  1. Clearing a tape does not initialize it. You should initialize tapes to a standard label format before the save command is issued by using the Initialize Tape (INZTAP) command and specifying a value for 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.
*NONE
None of the media is automatically cleared. If the save operation encounters active data on a tape volume or in a 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.
*ALL
All of the media is automatically cleared.

If tapes are used and a sequence number is specified for the SEQNBR parameter, the first tape is cleared beginning at that sequence number. All tapes following that first tape are completely cleared. To clear the entire first tape, SEQNBR(1) must be specified.

*AFTER
All media after the first volume is automatically cleared. If the save operation encounters active data on the first tape volume, 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.

Note: The *AFTER value is not valid for save files.

*REPLACE
Active data on the media is automatically replaced. Optical volumes are not initialized. Other media is automatically cleared in the same way as the *ALL value.

Object pre-check (PRECHK)

Specifies whether the save operation for a library ends if any of the following are true:

  1. The objects do not exist
  2. The library or the objects were previously found to be damaged
  3. The library or the objects are locked by another job
  4. The requester of the save operation does not have authority for the library or to save the objects.
*NO
The save operation for a library continues, saving only those objects that can be saved.
*YES
If, after all specified objects are checked, one or more objects cannot be saved, the save operation for a library ends before any data is written. If multiple libraries are specified, the save operation continues with the next library. However, if PRECHK(*YES) and SAVACT(*SYNCLIB) are specified and an object in any library to be saved does not meet the preliminary check conditions, the save operation ends and no objects are saved.

Save active (SAVACT)

Specifies whether an object can be updated while it is being saved.

Note: If your system is in a restricted state and the SAVACT parameter is specified, the save operation is performed as if SAVACT(*NO) was specified.

*NO
Objects that are in use are not saved. Objects cannot be updated while being saved.
*LIB
Objects in a library can be saved while they are in use by another job. All of the objects in a library reach a checkpoint together and are saved in a consistent state in relationship to each other.
*SYNCLIB
Objects in a library can be saved while they are in use by another job. All of the objects and all of the libraries in the save operation reach a checkpoint together and are saved in a consistent state in relationship to each other.

Note: If you specify this value and you are saving many libraries, it can take a long time to reach a checkpoint for all of the objects and libraries in the save operation.

*SYSDFN
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.

Save active wait time (SAVACTWAIT)

Specifies the amount of time to wait for an object that is in use, or for transactions with pending changes to reach a commit boundary, before continuing the save operation.

Element 1: Object locks

For each object that is in use, specifies the amount of time to wait for the object to become available. If an object remains in use for the specified time, the object is not saved.

120
The system waits up to 120 seconds for each individual object lock before continuing the save operation.
*NOMAX
No maximum wait time exists.
0-99999
Specify the number of seconds to wait for each individual object lock before continuing the save operation.

Element 2: Pending record changes

For each group of objects that are checkpointed together, specifies the amount of time to wait for transactions with pending record changes to reach a commit boundary. The Save active (SAVACT) parameter 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 *NOCMTBDY is specified.

*LOCKWAIT
The system waits up to the value specified for Element 1 for transactions with pending record changes to reach a commit boundary.
*NOCMTBDY
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.

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 *NOCMTBDY.

*NOMAX
No maximum wait time exists.
0-99999
Specify the number of seconds to wait for transactions with pending record changes to reach a commit boundary.

Element 3: Other pending changes

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

If a commit boundary is not reached for a library in the specified time, the library is not saved.

*LOCKWAIT
The system waits up to the value specified for Element 1 for the types of transactions that are listed above to reach a commit boundary.
*NOMAX
No maximum wait time exists.
0-99999
Specify the number of seconds to wait for the types of transactions that are listed above to reach a commit boundary.

If 0 is specified, and only one name is specified for the Objects (OBJ) parameter, and *FILE is the only value specified for the Object types (OBJTYPE) parameter, the system will save the object without requiring the types of transactions that are listed above to reach a commit boundary.

Save active message queue (SAVACTMSGQ)

Specifies the message queue that the save operation uses to notify the user that the checkpoint processing for a library is complete. A separate message is sent for each library to be saved when the *SYSDFN or *LIB value is specified for the Save active (SAVACT) parameter. When *SYNCLIB is specified for the SAVACT parameter, one message is sent for all libraries in the save operation.

This parameter can be used to save the objects at a known, consistent boundary to avoid additional recovery procedures following a restore operation. Applications can be stopped until the checkpoint processing complete message is received.

Single values

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

Qualifier 1: Save active message queue

name
Specify the name of the message queue to be used.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the message queue. If no library is specified as the current library for the job, the QGPL library is used.
name
Specify the name of the library where the message queue is located.

Synchronization ID (SYNCID)

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

*NONE
The checkpoint for this save while active operation is not synchronized with any other save while active operation.
name
Specify the name of the synchronized checkpoint. If you specify a name, you must also specify a value of *SYNCLIB for the Save active (SAVACT) parameter.

Note: If you specify a name, the value used for the Save active wait time (SAVACTWAIT) parameter Element 2: Pending record changes is the largest value specified among all of the participating save operations. However, if any participating save operation specifies *NOCMTBDY, then all participating save operations must specify *NOCMTBDY.

File member (FILEMBR)

Specifies the database file members that are saved. This parameter is made up of two parts: the file name and the member name.

Each database file specified here must also be specified for the Objects (OBJ) parameter, by its complete name, a generic name, or *ALL. The Object types (OBJTYPE) parameter value must be *ALL or include *FILE.

Note: This parameter cannot be specified when STG(*FREE) is specified.

Element 1: File

*ALL
The list of member name values that follows this value applies to all files specified for the OBJ parameter.
name
Specify the name of the database file from which the listed members are to be saved. Up to 50 files can be specified, with a member list for each file.

Note: Generic names are not valid for the database file name, but are allowed for the member name.

Note: Duplicate file names are not allowed.

Element 2: Member

Single values

*ALL
All members are saved from the specified file.
*NONE
No members are saved from the specified file. Only the file description is saved.

Other values (up to 50 repetitions)

generic-name
Specify the generic names of the members to be saved from the specified file. A generic name is a character string that contains one or more characters followed by an asterisk (*). If an * is not specified with the name, the system assumes that the name is a complete member name.

Note: If generic member names are specified, the file must contain member names that match the generic names for the file to be saved. For example, if PAY* is specified as a generic member name, and the system is unable to find a member whose name starts with PAY, the file is not saved. If files specified by the FILEMBR parameter are not saved because members with the specified generic name cannot be found, a diagnostic message is sent, the save operation ends, and an escape message is sent specifying the number of files not saved. If at least one of the files processed for the FILEMBR parameter contains a member with the specified generic name, the diagnostic message is not sent, and the number of files not saved is in the final completion message.

name
Specify the names of the members to be saved from the given file.

Note: If specific member names are specified, the specified members must exist in the file for any part of the file to be saved or restored.

Save access paths (ACCPTH)

Specifies whether the logical file access paths that are dependent on the physical files being saved are also saved. The access paths are saved only in the case of the following:

The system checks to ensure the integrity of the access paths. Any discrepancies found by the system will result in the access paths being rebuilt.

Informational messages are sent indicating the number of logical file access paths saved with each physical file. All physical files on which an access path is built must be in the same library. This parameter does not save logical file objects; it only controls the saving of the access paths. More information on the restoring of saved access paths is in the Recovering your system book, SC41-5304.

ATTENTION: If the based-on physical files and the logical files are in different libraries, the access paths are saved. However, if the logical files and the based-on physical files are in different libraries and the logical files or physical files do not exist at restore time (such as during disaster recovery or the files were deleted) the access paths are not restored. They are rebuilt. For the fastest possible restore operation for logical files, the logical files and the based-on physical files must be in the same library and must be saved at the same time.

*SYSVAL
The QSAVACCPTH system value determines whether to save the logical file access paths that are dependent on the physical files that are being saved.
*NO
Only those objects specified on the command are saved. No logical file access paths are saved.
*YES
The specified physical files and all eligible logical file access paths over them are saved.

Note: Specifying this value does not save the logical files.

Save file data (SAVFDTA)

Specifies, for save file objects, whether the description of a save file, or both the description and the contents of a save file, are saved.

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

Spooled file data (SPLFDTA)

Specifies whether to save spooled file data and attributes for output queues that are saved.

*NONE
No spooled file data is saved.
*ALL
For each output queue that is saved, all available spooled file data on the output queue is saved.

Queue data (QDTA)

Specifies, for queue objects, whether the description of a queue, or both the description and the contents of a queue, are saved.

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

Private authorities (PVTAUT)

Specifies whether to save private authorities with the objects that are saved. Saving private authorities will increase the amount of time it takes to save the objects, but it can simplify the recovery of an object or a group of objects. It will not simplify the recovery of an entire system.

*NO
No private authorities are saved.
*YES
Private authorities are saved for each object that is saved.

Note: You must have save system (*SAVSYS) or all object (*ALLOBJ) special authority to specify this value.

Storage (STG)

Specifies whether the system storage that is occupied by the data portion of the specified members (except for save files), modules, programs, service programs, Structured Query Language (SQL) packages, and journal receivers in the library being saved is freed as part of the save operation. Only the data portion of the objects is freed, not the descriptions of the objects.

*KEEP
The storage occupied by the data portion of the objects being saved is not freed.
*FREE
The storage occupied by the data portion of the specified objects being saved is freed as part of the save operation. The storage for all the objects in a library is freed only after all the objects in that library are saved successfully.

Note: To prevent the possible abnormal end of a program, the program being saved must not be running in the system when *FREE is specified.

Data compression (DTACPR)

Specifies whether data compression is used. If the save is running while other jobs on the system are active and software compression is used, the overall system performance may be affected.

Note: If *DEV is specified for both this parameter and the Data compaction (COMPACT) parameter, only device data compaction is performed if device data compaction is supported on the device. Otherwise, data compression is performed.

If *YES is specified for this parameter and *DEV is specified for the COMPACT parameter, both device data compaction and device data compression are performed if supported on the device.

*DEV
If the save is to tape and the target device supports compression, hardware compression is performed. Otherwise, no data compression is performed.
*NO
No data compression is performed.
*YES
If the save is to tape and the target device supports compression, hardware compression is performed. If compression is not supported, or if the save data is written to optical media or to a save file, software compression is performed. Low software compression is used for all devices except optical DVD, which uses medium software compression.
*LOW
If the save operation is to a save file or optical, software data compression is performed with the SNA algorithm. Low compression is usually faster and the compressed data is usually larger than if medium or high compression is used.
*MEDIUM
If the save operation is to a save file or optical, software data compression is performed with the TERSE algorithm. 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.
*HIGH
If the save operation is to a save file or optical, software data compression is performed with the LZ1 algorithm. High compression is usually slower and the compressed data is usually smaller than if low or medium compression is used. Start of change
*ZLIB
If the save operation is to a save file or optical, software data compression is performed using the ZLIB deflate algorithm.End of change

Data compaction (COMPACT)

Specifies whether device data compaction is performed.

*DEV
Device data compaction is performed if the data is saved to tape and all tape devices specified for the Device (DEV) parameter support the compaction feature.

Note: If *DEV is specified for both the Data compression (DTACPR) parameter and this parameter, only device data compaction is performed if device data compaction is supported on the device. Otherwise, data compression is performed if supported on the device.

If *YES is specified for the DTACPR parameter and *DEV is specified for this parameter, both device data compaction and device data compression are performed if supported on the device.

*NO
Device data compaction is not performed.

Libraries to omit (OMITLIB)

Specifies the names of one of more libraries, or the generic names of each group of libraries, to be excluded from the save operation.

Single values

*NONE
No libraries are excluded from the save operation.
*USRSPC
The libraries identified in the user space specified for the Command user space (CMDUSRSPC) parameter are excluded from the save operation.

Other values (up to 300 repetitions)

generic-name
Specify the generic name of the libraries to be excluded. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all libraries with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete library name.
name
Specify the name of the library to be excluded from the save operation.

Objects to omit (OMITOBJ)

Specifies the objects to be excluded from the operation. Up to 300 objects or generic object values can be specified.

Single values

*USRSPC
The objects identified in the user space specified for the Command user space (CMDUSRSPC) parameter are excluded from the save operation.

Other values (up to 300 repetitions)

Element 1: Object

Qualifier 1: Object

*NONE
No objects are excluded from the operation.
*ALL
All objects of the specified object type are excluded from the operation.
generic-name
Specify the generic name of the objects to be excluded.

Note: A generic name is specified as a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, then all objects that have names with the same prefix as the generic object name are selected.

name
Specify the name of the object to be excluded from the operation.

Qualifier 2: Library

*ALL
The specified objects are excluded from all libraries that are part of the operation.
generic-name
Specify the generic name of the libraries that contain objects to be excluded.

Note: A generic name is specified as a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, then all objects that have names with the same prefix as the generic object name are selected.

name
Specify the name of the library that contains the object to be excluded from the operation.

Element 2: Object type

*ALL
All object types are excluded from the operation, depending on the value specified for the object name.
character-value
Specify the object type of the objects to be excluded from the operation.

To see a complete list of object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt). For a description of the object types, see "Object types" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Select (SELECT)

Specifies the selection criteria for the objects to be saved. You can select from the objects specified for the Objects (OBJ), Library (LIB), and Object types (OBJTYPE) parameters.

Single values

*USRSPC
The selection criteria identified in the user space specified for the Command user space (CMDUSRSPC) parameter is used.

Other values (up to 300 repetitions)

Element 1: Include or omit

Specifies whether the selected objects should be included or omitted from the save operation.

*INCLUDE
The selected objects are saved, unless overridden by an *OMIT specification, or unless omitted by the Libraries to omit (OMITLIB) parameter or the Objects to omit (OMITOBJ) parameter.
*OMIT
The selected objects are not included in the save operation.

Element 2: Object

Qualifier 1: Object

*ALL
All object names specified for the Objects (OBJ) parameter are selected.
generic-name
Specify the generic name of the objects to be selected.

Note: A generic name is specified as a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, then all objects that have names with the same prefix as the generic object name are selected.

name
Specify the name of the object to be selected.

Qualifier 2: Library

*ALL
All library names specified for the Library (LIB) parameter are selected.
generic-name
Specify the generic name of the libraries to be selected.
name
Specify the name of the library to be selected.

Element 3: Object type

*ALL
All object types specified for the Object types (OBJTYPE) parameter are selected.
character-value
Specify the object type to be selected.

To see a complete list of object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt). For a description of the object types, see "Object types" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Element 4: Object attribute

*ALL
All object attributes are selected.
*BLANK
Only objects that have no attribute value are selected.
attribute-value
Specify the attribute of the objects to be selected.
generic-attribute-value
Specify the generic attribute of the objects to be selected.

Element 5: File member

Specifies the database file members to select.

If *ALL is specified, the objects selected by the previous elements are included or omitted.

If any value other than *ALL is specified, the File member (FILEMBR) parameter cannot be specified. The objects selected by the previous elements are included, even if the objects are not database files. If the objects selected are database files, the file members selected are included or omitted.

*ALL
All file members are selected. For an *OMIT specification, the selected file or object is also omitted.
*ALLMBR
All file members are selected. For an *OMIT specification, the selected file or object is included and all file members are omitted.
generic-name
Specify the generic name of the file members to be selected. The selected file or object is included even if it does not contain the specified members.
name
Specify the name of the file member to be selected. The selected file or object is included even if it does not contain the specified member.

ASP device (ASPDEV)

Specifies the auxiliary storage pool (ASP) device to be included in the save operation. This parameter is used to subset the list of objects which qualify for the SAV based on the OBJ parameter.

*
The operation includes the system ASP (ASP number 1), all basic user ASPs (ASP numbers 2-32), and, if the current thread has an ASP group, all independent ASPs in the ASP group.
*SYSBAS
The system ASP and all basic user ASPs are included in the save operation.
*CURASPGRP
If the current thread has an ASP group, all independent ASPs in the ASP group are included in the save operation.
name
Specify the name of the ASP device to be included in the save operation.

Output (OUTPUT)

Specifies whether a list with information about the saved objects is created. The information can be printed with the job's spooled output or directed to a database file.

*NONE
No output listing is created.
*PRINT
The output is printed with the job's spooled output.
*OUTFILE
The output is directed to the database file specified for the File to receive output (OUTFILE) parameter.

Note: You must specify a database file name for the File to receive output (OUTFILE) parameter when OUTPUT(*OUTFILE) is specified.

File to receive output (OUTFILE)

Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.

Qualifier 1: File to receive output

name
Specify the name of the database file to which the command output is directed.

Qualifier 2: Library

*LIBL
The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.
*CURLIB
The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the name of the library to be searched.

Note: If a new file is created, the system uses the IBM-supplied file QASAVOBJ with format name QSRSAV as a model.

Output member options (OUTMBR)

Specifies the name of the database file member to which the output is directed when *OUTFILE is specified for the Output (OUTPUT) parameter.

Element 1: Member to receive output

*FIRST
The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified for the File to receive output (OUTFILE) parameter.
name
Specify the name of the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it.

If the member exists, you can add records to the end of the existing member or clear the existing member and add the records.

Element 2: Replace or add records

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

Type of information (INFTYPE)

Specifies the type of information which is printed or directed to the database file.

*OBJ
The list contains an entry for each object requested to be saved.
*ERR
The list contains information about the command, an entry for each library, and an entry for each object that was not successfully saved.
*LIB
The list contains a library entry for each library requested to be saved
*MBR
The list contains an entry for each object, database file member, and spooled file requested to be saved.

Command user space (CMDUSRSPC)

Specifies a user space containing the values for the parameters which have *USRSPC specified for this command. The user space allows up to 32767 list values for each parameter, while the command parameters only allow up to 300 list values. The user space must define the parameters in the format used by the Save Object List (QSRSAVO) API.

Qualifier 1: User space

name
Specify the name of the user space containing the values for the parameters which have *USRSPC specified for this command.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the user space. If no library is specified as the current library for the job, the QGPL library is used.
name
Specify the name of the library where the user space is located.

Examples

Example 1: Saving Program and File With Same Name

SAVOBJ   OBJ(PETE)  LIB(LIBX)  DEV(TAP01)

This command saves the objects named PETE which are located in the LIBX library. If, for example, LIBX contains both a program and a file named PETE, both objects are saved. The storage occupied by the object is not freed because the STG parameter default (*KEEP) was assumed.

Example 2: Freeing System Storage

SAVOBJ   OBJ(MSTRPAY PAY*)  LIB(QGPL)  DEV(TAP01)  STG(*FREE)

The object named MSTRPAY, and all the objects whose names start with the characters PAY located in the general purpose library (QGPL), are saved. As part of the save operation, the system storage that was occupied by the data portion of the saved member, module, program, service program, SQL package, and journal receiver objects is freed.

Example 3: Saving File on Optical

SAVOBJ   OBJ(FILEA)  OBJTYPE(*FILE)  LIB(LIBY)  DEV(OPT01)
         VOL(TOM)  CLEAR(*REPLACE)

The file named FILEA in the LIBY library is saved in a file with the library name LIBY on the optical volume that is identified by the volume identifier TOM. If the LIBY file already exists on the optical volume, it is automatically replaced when FILEA is saved.

Example 4: Saving Objects Supported on Previous Release

SAVOBJ   OBJ(PAY*)  LIB(LIB1)  DEV(TAP01)  TGTRLS(*PRV)

This command saves the objects beginning with the characters PAY from the LIB1 library in a format compatible with the previous release of the operating system. Only those objects supported on the previous release are saved.

Example 5: Saving Description and Data of File

SAVOBJ   OBJ(SAVEFILE)  LIB(MYLIB)  OBJTYPE(*FILE)  DEV(TAP01)
         SAVFDTA(*YES)

This command saves the file named SAVEFILE which is located in the library named MYLIB. Both the description and the data are saved for this save file.

Example 6: Saving a List of Objects

SAVOBJ   OBJ(APP1*)  LIB(*SELECT)  DEV(TAP01)
         SELECT((*INCLUDE PGMLIB/*ALL     *PGM        )
                (*OMIT    PGMLIB/APP1TEST             )
                (*INCLUDE DTALIB*/*ALL    *FILE    PF )
                (*INCLUDE DTALIB*/*ALL    *FILE    LF )
                (*OMIT    DTALIBTEST/*ALL             )
                (*INCLUDE JRNLIB*/*ALL    *JRN        )
                (*INCLUDE JRNLIB*/*ALL    *JRNRCV     ))

This command saves objects with names beginning with APP1, including programs in library PGMLIB except program APP1TEST, physical and logical files in libraries with names beginning with DTALIB except library DTALIBTEST, and journals and journal receivers in libraries with names beginning with JRNLIB.

Example 7: Saving Database File Descriptions

SAVOBJ   OBJ(*ALL)  LIB(DATALIB)  DEV(TAP01)
         SELECT((*INCLUDE *ALL *FILE PF )
                (*INCLUDE *ALL *FILE LF )
                (*OMIT    *ALL *ALL  *ALL *ALLMBR ))

This command saves all physical and logical files in library DATALIB, but does not save the file members. Only the file descriptions are saved.

Error messages

*ESCAPE Messages

CPF3701
&1 objects saved from &3. &2 not saved.
CPF3702
&1 objects saved from &3. &2 not saved. &9 not included.
CPF3703
&2 &1 in &3 not saved.
CPF3708
Save file &1 in &2 too small.
CPF3709
Tape devices do not support same densities.
CPF3727
Duplicate device &1 specified on device name list.
CPF3728
Device &1 specified with other devices.
CPF3730
Not authorized to &2 &1 in library &3.
CPF3731
Cannot use &2 &1 in library &3.
CPF3733
&2 &1 in &3 previously damaged.
CPF3735
Storage limit exceeded for user profile &1.
CPF3738
Device &1 used for save or restore is damaged.
CPF3747
Object names cannot be specified with more than one library.
CPF3749
Objects from library &2 not saved.
CPF3767
Device &1 not found.
CPF3768
Device &1 not valid for command.
CPF377D
Save ended because of read error on internal system resource.
CPF377E
Not enough storage for save-while-active request.
CPF377F
Save ended. Unable to reach checkpoint.
CPF3770
No objects saved or restored for library &1.
CPF3771
&1 objects saved from &3. &2 not saved.
CPF3774
&1 objects saved from &3. &2 not saved. &8 not included.
CPF3778
Not all objects saved from all libraries.
CPF378A
Message queue not available.
CPF378C
SAVACTMSGQ(*WRKSTN) not valid for batch job.
CPF378E
Library &1 not saved.
CPF3781
Library &1 not found.
CPF3782
File &1 in &2 not a save file.
CPF3789
Only one library allowed with specified parameters.
CPF379E
Not enough storage available to save library &1.
CPF3793
Machine or ASP storage limit reached.
CPF3794
Save or restore operation ended unsuccessfully.
CPF3797
Objects from library &3 not saved. Save limit exceeded.
CPF37AB
*NOCMTBDY not allowed with target release.
CPF37AC
Library not allowed with *NOCMTBDY.
CPF37B1
SPLFDTA not allowed with target release.
CPF37B4
User space &1 in &2 not valid.
CPF37B5
PVTAUT not allowed with target release.
CPF37B7
Not authorized to save private authorities.
CPF37B9
Synchronization ID &1 in use.
CPF37BC
Synchronization ID &1 ended. Wait time exceeded.
CPF37BD
Synchronization ID &1 ended. Save ended before checkpoint.
CPF37BE
Synchronization ID &1 not started.
CPF37C7
Synchronization ID &1 ended. SAVACTWAIT error.
CPF380B
Save cannot be completed at this time.
CPF3812
Save file &1 in &2 in use.
CPF3815
Save file &1 in &2 too small for save operation.
CPF384E
USEOPTBLK(*YES) not valid for CD-ROM premastering.
CPF3867
Contents of FILEMBR parameter not correct.
CPF3868
FILEMBR specified but OBJTYPE must be *ALL or *FILE.
CPF3871
No objects saved or restored; &3 objects not included.
CPF388B
Optical file path name not valid.
CPF3892
&2 &1 in &3 not saved.
CPF3894
Cancel reply received for message &1.
CPF38A2
ASP device &1 not correct.
CPF38A3
File &1 in &2 not valid with ASPDEV.
CPF38A4
ASP device &1 not correct.
CPF38AA
Object selection list key not valid.
CPF38AB
FILEMBR not valid with SELECT.
CPF38AC
LIB(*SELECT) not valid with *ALL libraries.
CPF5729
Not able to allocate object &1.
CPF9809
Library &1 cannot be accessed.
CPF9812
File &1 in library &2 not found.
CPF9814
Device &1 not found.
CPF9820
Not authorized to use library &1.
CPF9822
Not authorized to file &1 in library &2.
CPF9825
Not authorized to device &1.
CPF9833
*CURASPGRP or *ASPGRPPRI specified and thread has no ASP group.
CPFB8ED
Device description &1 not correct for operation.
OPT1332
Optical volume not found in device &1.

*STATUS Messages

CPF3770
No objects saved or restored for library &1.
CPF3771
&1 objects saved from &3. &2 not saved.
CPF3871
No objects saved or restored; &3 objects not included.