Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
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:
Top |
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: *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 | *CURRENT, *PRV, V5R4M0, V6R1M0, V7R1M0 | 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 | *DEV, *NO, *YES, *LOW, *MEDIUM, *HIGH | 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 | ||
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 |
Top |
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
Other values (up to 300 repetitions)
Top |
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
Other values (up to 300 repetitions)
Note: A generic library name cannot be specified when saving to a save file.
Note: Only one library can be specified when saving to a save file.
Top |
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
Other values
Top |
Specifies the types of system objects to be saved.
Single values
Other values (up to 300 repetitions)
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/.
Top |
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
Note: This value cannot be specified when using an optical media library device.
Other values (up to 75 repetitions)
Top |
Specifies, when tape is used, the sequence number to use as the starting point for the save operation.
Top |
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.
Top |
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:
Top |
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.
Top |
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
Qualifier 2: Library
Top |
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
Qualifier 2: Library
Top |
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/.
Top |
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.
Top |
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:
Top |
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.
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.
Top |
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:
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.
Note: The *AFTER value is not valid for save files.
Top |
Specifies whether the save operation for a library ends if any of the following are true:
Top |
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.
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.
Top |
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.
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.
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.
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.
Top |
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
Qualifier 1: Save active message queue
Qualifier 2: Library
Top |
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.
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.
Top |
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
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
Other values (up to 50 repetitions)
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.
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.
Top |
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.
Note: Specifying this value does not save the logical files.
Top |
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.
Top |
Specifies whether to save spooled file data and attributes for output queues that are saved.
Top |
Specifies, for queue objects, whether the description of a queue, or both the description and the contents of a queue, are saved.
Top |
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.
Note: You must have save system (*SAVSYS) or all object (*ALLOBJ) special authority to specify this value.
Top |
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.
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.
Top |
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.
Note: This value is not valid for tape.
Note: This value is not valid for tape.
Note: This value is not valid for tape.
Top |
Specifies whether device data compaction is performed.
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.
Top |
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
Other values (up to 300 repetitions)
Top |
Specifies the objects to be excluded from the operation. Up to 300 objects or generic object values can be specified.
Single values
Other values (up to 300 repetitions)
Element 1: Object
Qualifier 1: Object
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.
Qualifier 2: Library
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.
Element 2: Object type
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/.
Top |
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.
Top |
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.
Note: You must specify a database file name for the File to receive output (OUTFILE) parameter when OUTPUT(*OUTFILE) is specified.
Top |
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
Qualifier 2: Library
Note: If a new file is created, the system uses the IBM-supplied file QASAVOBJ with format name QSRSAV as a model.
Top |
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
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
Top |
Specifies the type of information which is printed or directed to the database file.
Top |
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
Qualifier 2: Library
Top |
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.
Top |
*ESCAPE Messages
*STATUS Messages
Top |