Save Restore Object (SAVRSTOBJ)

The Save/Restore Object (SAVRSTOBJ) command saves and restores a single object, or a group of objects located in the same library, to another system. The objects can be restored to the same library or a different library. The types of objects that can be saved and restored are the same set of objects allowed on the Save Object (SAVOBJ) command. Objects on the system from which the objects are being saved are not affected by the SAVRSTOBJ command.

For job queues, message queues, and logical files, only the object descriptions are saved and restored, not the contents. Logical file access paths can be saved and restored by specifying ACCPTH(*YES). The contents of a save file can be saved and restored by specifying SAVFDTA(*YES). The contents of spooled files on output queues can be saved and restored by specifying SPLFDTA(*ALL). The contents of a data queue can be saved and restored by specifying QDTA(*DTAQ).

Notes:

1. This command ignores all file overrides currently in effect for the job.
2. When the address type is *IP, this command communicates with remote system using TCP/IP, Enterprise Extender is not used. The ObjectConnect server is required to be active on the remote system.
3. When the address type is *SNA, RMTPORT, RMTUSER and RMTPWD are ignored. If an OptiConnect connection is active, OptiConnect is preferred to access the remote system.

Restrictions:

1. To use this command, you must have either the special authority *SAVSYS specified in the user profile by the SPCAUT parameter or have (a) object existence authority for each object specified and (b) read authority for the specified library. If you do not have the necessary authority to a specified object, all objects except that one are saved and restored.

2. Both systems intended to participate in the save and restore operation must be connected to the interworking ethernet network or, the same APPN network, or if the OptiConnect for IBM i option is to be used, both systems must be joined by the OptiConnect for IBM i hardware and software.

Parameters

Keyword	Description	Choices	Notes
OBJ	Objects	Single values: *ALL Other values (up to 300 repetitions): Generic name, name	Required, Positional 1
LIB	Saved library	Single values: *ALLUSR Other values (up to 300 repetitions): Generic name, name	Required, Positional 2
RMTLOCNAME	Remote location name	Element list	Required, Positional 3
	Element 1: Name or address	Character value
	Element 2: Type	*SNA, *IP
RMTPORT	Remote port	1-65534, *DFT	Optional
RMTUSER	Remote user ID	Name, *NONE, *CURRENT, *KERBEROS	Optional
RMTPWD	Remote password	Character value, *NONE	Optional
OBJTYPE	Object types	Single values: *ALL Other values (up to 73 repetitions): *ALRTBL, *BNDDIR, *CHTFMT, *CLD, *CLS, *CMD, *CRG, *CRQD, *CSI, *CSPMAP, *CSPTBL, *DTAARA, *DTAQ, *EDTD, *EXITRG, *FCT, *FILE, *FNTRSC, *FNTTBL, *FORMDF, *FTR, *GSS, *IGCDCT, *IGCSRT, *IGCTBL, *IMGCLG, *JOBD, *JOBQ, *JOBSCD, *JRN, *JRNRCV, *LOCALE, *MEDDFN, *MENU, *MGTCOL, *MODULE, *MSGF, *MSGQ, *NODGRP, *NODL, *ORTBL, *OUTQ, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PGM, *PNLGRP, *PRDAVL, *PRTIMG, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *RCT, *SBSD, *SCHIDX, *SPADCT, *SQLPKG, *SQLUDT, *SQLXSR, *SRVPGM, *SSND, *SVRSTG, *S36, *TBL, *USRIDX, *TIMZON, *USRQ, *USRSPC, *VLDL, *WSCST	Optional
OUTPUT	Output	*NONE, *PRINT	Optional
STRLIB	Starting library	Name, *FIRST	Optional
OMITLIB	Libraries to omit	Single values: *NONE Other values (up to 300 repetitions): Generic name, name	Optional
OMITOBJ	Objects to omit	Values (up to 300 repetitions): Element list	Optional
	Element 1: Object	Qualified object name
	Qualifier 1: Object	Generic name, name, *ALL, *NONE
	Qualifier 2: Library	Generic name, name, *ALL
	Element 2: Object type	Character value, *ALL, *ALRTBL, *BNDDIR, *CHTFMT, *CLD, *CLS, *CMD, *CRG, *CRQD, *CSI, *CSPMAP, *CSPTBL, *DTAARA, *DTAQ, *EDTD, *EXITRG, *FCT, *FILE, *FNTRSC, *FNTTBL, *FORMDF, *FTR, *GSS, *IGCDCT, *IGCSRT, *IGCTBL, *JOBD, *JOBQ, *JOBSCD, *JRN, *JRNRCV, *LOCALE, *MEDDFN, *MENU, *MGTCOL, *MODULE, *MSGF, *MSGQ, *M36, *M36CFG, *NODGRP, *NODL, *ORTBL, *OUTQ, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PGM, *PNLGRP, *PRDAVL, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *RCT, *SBSD, *SCHIDX, *SPADCT, *SQLPKG, *SQLUDT, *SQLXSR, *SRVPGM, *SSND, *SVRSTG, *S36, *TBL, *USRIDX, *TIMZON, *USRQ, *USRSPC, *VLDL, *WSCST
SELECT	Select	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, *ALRTBL, *BNDDIR, *CHTFMT, *CLD, *CLS, *CMD, *CRG, *CRQD, *CSI, *CSPMAP, *CSPTBL, *DTAARA, *DTAQ, *EDTD, *EXITRG, *FCT, *FILE, *FNTRSC, *FNTTBL, *FORMDF, *FTR, *GSS, *IGCDCT, *IGCSRT, *IGCTBL, *JOBD, *JOBQ, *JOBSCD, *JRN, *JRNRCV, *LOCALE, *MEDDFN, *MENU, *MGTCOL, *MODULE, *MSGF, *MSGQ, *NODGRP, *NODL, *ORTBL, *OUTQ, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PGM, *PNLGRP, *PRDAVL, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *RCT, *SBSD, *SCHIDX, *SPADCT, *SQLPKG, *SQLUDT, *SQLXSR, *SRVPGM, *SSND, *SVRSTG, *S36, *TBL, *USRIDX, *USRQ, *USRSPC, *VLDL, *WSCST
	Element 4: Object attribute	Character value, *ALL, *BLANK
	Element 5: File member	Generic name, name, *ALL, *ALLMBR
ASPDEV	ASP device	Name, *, *SYSBAS, *CURASPGRP	Optional
TGTRLS	Target release	Simple name, *CURRENT, *PRV	Optional
PRECHK	Object pre-check	*NO, *YES	Optional
SAVACT	Save active	*NO, *LIB, *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
FILEMBR	File member	Values (up to 300 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
OPTION	Option	*ALL, *NEW, *OLD, *FREE	Optional
MBROPT	Data base member option	*MATCH, *ALL, *NEW, *OLD	Optional
ALWOBJDIF	Allow object differences	Single values: *NONE, *ALL, *COMPATIBLE Other values (up to 4 repetitions): *AUTL, *FILELVL, *OWNER, *PGP	Optional
RSTLIB	Restore to library	Name, *LIB	Optional
RSTASPDEV	Restore to ASP device	Name, *SAVASPDEV	Optional
RSTASP	Restore to ASP number	1-32, *SAVASP	Optional
FRCOBJCVN	Force object conversion	Single values: *SYSVAL, *NO Other values: Element list	Optional
	Element 1: Convert during restore	*YES
	Element 2: Objects to convert	*RQD, *ALL
STRJRN	Start journaling	*YES, *NO	Optional

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.

Saved library (LIB)

Specifies the library containing the objects to be saved and restored.

Single values

*ALLUSR

All user libraries are saved and restored. All libraries with names that do not begin with the letter Q are saved and restored except for the following:

#CGULIB     #DSULIB     #SEULIB
#COBLIB     #RPGLIB
#DFULIB     #SDALIB

Although the following Qxxx libraries are provided by IBM, they typically contain user data that changes frequently. Therefore, these libraries are considered user libraries and are also saved and restored:

QDSNX       QRCLxxxxx   QUSRDIRDB   QUSRVI
QGPL        QSRVAGT     QUSRIJS     QUSRVxRxMx
QGPL38      QSYS2       QUSRINFSKR  QWQCENT
QMGTC       QSYS2xxxxx  QUSRNOTES   QWQREPOS
QMGTC2      QS36F       QUSROND
QMPGDATA    QUSER38     QUSRPOSGS
QMQMDATA    QUSRADSM    QUSRPOSSA
QMQMPROC    QUSRBRM     QUSRPYMSVR
QPFRDATA    QUSRDIRCF   QUSRRDARS
QRCL        QUSRDIRCL   QUSRSYS

Note: A different library name, in the format QUSRVxRxMx, can be created by the user for each previous release supported by IBM to contain any user commands to be compiled in a CL program for the previous release. For the QUSRVxRxMx user library, VxRxMx is the version, release, and modification level of a previous release that IBM continues to support.

Other values (up to 300 repetitions)

generic-name

Specify the generic name of the library. 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. Up to 300 generic library values can be specified.

name

Specify the name of the library to be saved and restored. Up to 300 library names can be specified.

Remote location (RMTLOCNAME)

Specifies the target system and the type of connection used to connect to the target system.

This is a required parameter.

Element 1: Name or address

character-value

The syntax for this element is dependent on the value specified for the second element:

• When the address type is *SNA, specify the name of the target system using the format nnnnnnnn.cccccccc, where nnnnnnnn is the network identifier (ID) and cccccccc is the remote location name. If no network ID is specified, the network attributes are used to determine the default network ID.
• When the address type is *IP, specify a host name or an internet address to identify the target system. Host names must follow these conventions:
  • The first character must be either A through Z or 0 through 9.
  • The last character must be either A through Z, 0 through 9, or a period (.).
  • Blanks ( ) are not allowed.
  • The special characters, period (.), underscore (_), and minus (-) are allowed.
  • Parts of the name separated by periods (.) cannot exceed 63 characters in length.

    Note: Each part of the name separated by periods (.) must begin and end with an English alphabetic character or a numeric character.

  • Names must be from 1 to 255 characters in length.

  The IPv4 address is specified in the form nnn.nnn.nnn.nnn where nnn is a decimal number ranging from 0 through 255. An IPv4 Internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address.

  The IPv6 address is specified in the form x:x:x:x:x:x:x:x where x is a hexadecimal number ranging from 0 through X'FFFF'. "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address.

  If the Internet address is entered from a command line, the address must be enclosed in single quotation marks.

Element 2: Type

*SNA

The target system is accessed using a Systems Network Architecture (SNA) address and protocol.

*IP

The target system is found using a host name or an internet address over a TCP/IP connection.

Remote port (RMTPORT)

Specifies a certain port that an application on the remote server system is listening on (if it's other than a default port for ObjectConnect server).

*DFT

This default value uses the port configured in TCPIP service table.

1-65534

Specify the port number to be used. You should be aware of the specific port the remote server is listening on. Otherwise, a port that is specified can result in the remote host rejecting the open attempt.

Remote user ID (RMTUSER)

Specifies the user profile being sent to the remote server system. If a profile is specified for this parameter and password security is active on the remote system, *NONE is not valid for the Remote password (RMTPWD) parameter.

*NONE

No user ID is sent. If authentication type on the remote system is configured to require a user ID, the command will fail.

*CURRENT

The user profile of the job using this command is sent.

*KERBEROS

Authentication occurs using Kerberos. The default credentials cache file for the current user is used to locate existing Kerberos ticket-granting tickets. The Add Kerberos Ticket (ADDKRBTKT) command or the Qshell kinit tool can be used to create or refresh expired tickets.

Note: Kerberos needs to be configured on both systems for this authentication type to be used.

name

Specify the name of the user profile to use (that exists) on the remote system. If a profile is specified and password security is active on the remote system, a password must be specified, even if the profile specified is the same as the current profile.

Remote password (RMTPWD)

Specifies the password being sent to the remote system.

character-value

Specify a password to be sent to the remote system to verify the user specified for the RMTUSER parameter.

Note: If specifying *KERBEROS in RMTUSER parameter, the RMTPWD parameter is ignored.

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

Output (OUTPUT)

Specifies whether information about the saved and restored objects is printed.

*NONE

No output is created.

*PRINT

Information about the saved objects is printed with the spooled output of the job. Information about the restored objects is printed with the spooled output of the job at the remote location.

Starting library (STRLIB)

Specifies the library with which to begin the save operation.

If an unrecoverable media error occurs during the save operation, this parameter can be used to restart the operation.

The basic steps for restarting a save operation are:

1. Check the job log to determine the library where the previous save operation failed. Find the last library saved, which is indicated by a successful completion message.
2. Load the next tape and ensure the tape is initialized.
3. Add the following to your original save command:

     STRLIB(library-name)  OMITLIB(library-name)
   

   where the library-name for the STRLIB and OMITLIB parameters is the last library successfully saved. This starts the save operation on the library after the last successfully saved library.

   To restore the libraries, you will need to perform a separate restore operation for each save operation that was performed.

*FIRST

The save operation begins with the first library value specified for the Library (LIB) parameter. If the first value is a generic name or special value, the save operation begins with the first library that matches this value.

name

Specify the name of the library with which to begin the save operation.

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.

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.

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.

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.

Target release (TGTRLS)

Specifies the release level of the operating system on which you intend to use the object being saved.

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.

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

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 the objects in a library reach a checkpoint together and are saved in a consistent state in relationship to each other.

*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:

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

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:

• All members on which the access paths are built are included in this save operation.
• The access paths are not invalid or damaged at the time of the save.

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 and restore private authorities with the objects that are saved and restored.

*NO

No private authorities are saved or restored.

*YES

Private authorities are saved and restored with the objects.

Note: You must have save system (*SAVSYS) or all object (*ALLOBJ) special authority on the system from which objects are being saved, and *ALLOBJ special authority on the restore system, 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.

Option (OPTION)

Specifies how to handle restoring each object.

*ALL

All the objects in the saved library are restored to the library. Objects in the saved library replace the current versions in the system library. Objects not having a current version are added to the system library. Objects presently in the library, but not on the media, remain in the library.

*NEW

Only the objects in the saved library that do not exist in the current version of the system library are added to the library. Only objects not known to the system library are restored; known objects are not restored. This option restores objects that were deleted after they were saved or that are new to this library. If any saved objects have a version already in the system library, they are not restored, and an informational message is sent for each one, but the restore operation continues.

*OLD

Only the objects in the library having a saved version are restored; that is, the version of each object currently in the library is replaced by the saved version. Only objects known to the library are restored. If any saved objects are no longer part of the online version of the library, they are not added to the library; an informational message is sent for each one, but the restore continues.

*FREE

The saved objects are restored only if they exist in the system library with their space freed. The saved version of each object is restored on the system in its previously freed space. This option restores objects that had their space freed when they were saved. If any saved objects are no longer part of the current version of the library, or if the space is not free for any object, the object is not restored and an informational message is sent for each one. The restore operation continues, and all of the freed objects are restored.

Data base member option (MBROPT)

Specifies, for database files that exist on the system, which members are restored. If *MATCH is used, the member list in the saved file must match, member for member, the current version on the system. All members are restored for files that do not exist, if the file is restored.

*MATCH

The saved members are restored if the lists of the members where they exist match, member for member, the lists of the current system version. MBROPT(*MATCH) is not valid when *ALL is specified for the Allow object differences (ALWOBJDIF) parameter.

*ALL

All members in the saved file are restored.

*NEW

Only new members (members not known to the system) are restored.

*OLD

Only members already known to the system are restored.

Allow object differences (ALWOBJDIF)

Specifies whether differences are allowed between the saved objects and the restored objects.

Notes:

1. You must have all object (*ALLOBJ) special authority to specify any value other than *NONE for this parameter.
2. If differences are found, the final message for the restore operation is an escape message rather than the normal completion message.

The types of differences include:

• Authorization list: The saved object had an authorization list, and either the object exists on the system but does not have the same authorization list, or the object does not exist and it is being restored to a different system than the save system.

  Note: This parameter has no effect when the saved object did not have an authorization list. If the object exists, it is restored with the authorization list of the existing object. If it does not exist, it is restored with no authorization list.

• File level id: The creation date and time of the database file on the system does not match the creation date and time of the file that was saved.

• Member level id: The creation date and time of the database file member on the system does not match the creation date and time of the member that was saved.

• Ownership: The owner of an object on the system is different than the owner of an object from the save operation.

• Primary Group: The primary group of an object on the system is different than the primary group of an object from the save operation.

Single values

*NONE

None of the differences listed above are allowed on the restore operation. See the description of each individual value to determine how differences are handled.

*COMPATIBLE

All of the differences listed above are allowed on the restore operation. See the description of each individual value to determine how differences are handled. This value allows differences that are compatible with existing physical database files. This value also allows file level differences with existing logical database files. This value is usually preferable to the value *ALL, which also allows differences that are not compatible with existing database files.

*ALL

All of the differences listed above are allowed on the restore operation. File level id and member level id differences are handled differently than the *FILELVL value. If there is a file level difference and *ALL is specified for the Data base member option (MBROPT) parameter, the existing version of the file is renamed and the saved version of the file is restored. If there is a member level difference, the existing version of the member is renamed and the saved version of the member is restored. This value will restore the saved data, but the result may not be correct. You will need to choose whether the restored data or the renamed data is correct, and you will need to make the necessary corrections to the database. For other differences, see the description of each individual value to determine how differences are handled.

Other values (up to 4 repetitions)

*AUTL

Authorization list differences are allowed. If the saved object had an authorization list and the object exists on the system but does not have the same authorization list, the object is restored with the authorization list of the existing object. If the saved object had an authorization list and the object does not exist and it is being restored to a different system than the save system, the object is restored and it is linked to the authorization list. If the authorization list does not exist, the public authority is set to *EXCLUDE.

If this value is not specified, authorization list differences are not allowed. If the saved object had an authorization list and the object exists on the system but does not have the same authorization list, the object is not restored. If the saved object had an authorization list and the object does not exist and it is being restored to a different system than the save system, the object is restored, but it is not linked to the authorization list, and the public authority is set to *EXCLUDE.

*FILELVL

File level id and member level id differences are allowed. An attempt will be made to restore existing physical files even though the physical file on the save media may have a different file level id or member level id than the physical file on the system. The physical file data will only be restored for those physical files whose format level identifiers on the save media match the format level identifiers of the corresponding physical file on the system.

If this value is not specified, file level id and member level id differences are not allowed. If an object already exists on the system with a different file level id or member level id than the saved object, the object is not restored.

*OWNER

Ownership differences are allowed. If an object already exists on the system with a different owner than the saved object, the object is restored with the owner of the object on the system.

If this value is not specified, ownership differences are not allowed. If an object already exists on the system with a different owner than the saved object, the object is not restored.

*PGP

Primary group differences are allowed. If an object already exists on the system with a different primary group than the saved object, the object is restored with the primary group of the object on the system.

If this value is not specified, primary group differences are not allowed. If an object already exists on the system with a different primary group than the saved object, the object is not restored.

Restore to library (RSTLIB)

Specifies the library in which the objects are to be restored.

*LIB

The name of the library that was specified on the LIB parameter is used.

name

Specify the name of the library to which you want to restore the objects.

Restore to ASP device (RSTASPDEV)

Specifies the auxiliary storage pool (ASP) device to which the data is to be restored.

Note: You can specify either the RSTASPDEV parameter or the RSTASP parameter, but not both.

*SAVASPDEV

The data is restored to the same ASP from which it was saved.

name

Specify the name of the ASP device to be used.

Restore to ASP number (RSTASP)

Specifies whether objects are restored to the auxiliary storage pool (ASP) from which they were saved or to the system ASP (ASP number 1) or to a basic user ASP (ASP numbers 2 through 32).

Some objects cannot be restored to user ASPs. More information about object types which can be restored to user ASPs is in the Recovering your system book, SC41-5304. If the library exists in, or is being restored to the system ASP, journals, journal receivers, and save files can be restored to basic user ASPs. All other object types will be restored to the ASP of the library.

ATTENTION: System or product libraries (libraries that begin with a Q or #) must not be created in or restored to a user ASP. Doing so can cause unpredictable results.

*SAVASP

The objects are restored to the ASP from which they were saved.

1-32

Specifies the ASP number. When the specified ASP is 1, the specified objects are restored to the system ASP, and when the specified ASP is 2 through 32, the objects are restored to the basic user ASP specified.

Force object conversion (FRCOBJCVN)

Specifies whether to convert user objects to the format required for use in the current version of the operating system, or to be compatible with the current machine, when the objects are restored.

Notes:

1. This parameter applies only to user objects of the *MODULE, *PGM, *SRVPGM, and *SQLPKG object types.
2. An object must have creation data (either observable or unobservable) to be converted.
3. If an object needs to be converted (because it is formatted for an earlier version of the operating system or is incompatible with the current machine), but is not converted during this restore operation, the object is automatically converted the first time it is used.

Single values

*SYSVAL

The objects are converted based on the value of the QFRCCVNRST system value.

*NO

The objects are not converted during the restore operation.

Note: If FRCOBJCVN(*NO) is specified, then the QFRCCVNRST system value must have a value of either "0" or "1".

Element 1: Convert during restore

*YES

The objects are converted during the restore operation.

Notes:

1. If FRCOBJCVN(*YES *RQD) is specified, then the QFRCCVNRST system value must have a value of "0", "1", or "2". FRCOBJCVN(*YES *RQD) will override a QFRCCVNRST value of "0" or "1". If FRCOBJCVN(*YES *ALL) is specfied, then QFRCCVNRST can have any valid value and FRCOBJCVN(*YES *ALL) overrides the QFRCCVNRST system value.
2. Specifying this value increases the time of the restore operation, but avoids the need to convert the objects when they are first used.

Element 2: Objects to convert

*RQD

The objects are converted only if they require conversion to be used by the current operating system or to be compatible with the current machine. If the objects do not have all creation data (either observable or unobservable), the objects cannot be converted and will not be restored.

*ALL

All objects are converted regardless of their current format and machine compatibility, including compatible objects already in the current format. However, if the objects do not have all creation data (either observable or unobservable), the objects cannot be converted and will not be restored.

Start journaling (STRJRN)

Specifies whether to start journaling for new objects that are restored.

Notes:

1. Journal information that was saved will be restored for new objects whether journaling is started or not.
2. Journaling will not be changed for existing objects.

*YES

Journaling will be started for new objects that were being journaled when they were saved.

*NO

Journaling will not be started for the objects that are restored.

Examples

Example 1: Saving and Restoring Generic Objects using *IP with user profile and password

SAVRSTOBJ   OBJ(ABCD*)  LIB(ACE)  RMTLOCNAME(SYSTEM1 *IP)
            RMTUSER(USRPRF1) RMTPWD(MYPASSWORD)
            OBJTYPE(*PGM)  ALWOBJDIF(*NONE)

This command saves the objects beginning with the characters ABCD located in the library named ACE and restores them on the remote system named SYSTEM1 using address type *IP with valid user profile USRPRF1 and password MYPASSWORD on the system SYSTEM1.

Example 2: Saving and Restoring a Specific Object using *IP with Kerberos

SAVRSTOBJ   OBJ(FLETCH)  LIB(CHASE)  RMTLOCNAME(SYSTEM1 *IP)
            RMTUSER(*KERBEROS)
            ALWOBJDIF(*ALL)  OPTION(*NEW)

This command saves the object named FLETCH located in the library named CHASE and restores it on the remote system named SYSTEM1 using address type *IP and Kerberos ticket-granting tickets in default credentials cache file if it is does not already exist on the remote system.

Example 3: Saving and Restoring Generic Objects using *SNA

SAVRSTOBJ   OBJ(ABCD*)  LIB(ACE)  RMTLOCNAME(SYSTEM1)
            OBJTYPE(*PGM)  ALWOBJDIF(*NONE)

This command saves the objects beginning with the characters ABCD located in the library named ACE and restores them on the remote system named SYSTEM1 using address type *SNA.

Example 4: Saving and Restoring a Specific Object using *SNA

SAVRSTOBJ   OBJ(FLETCH)  LIB(CHASE)  RMTLOCNAME(SYSTEM1)
            ALWOBJDIF(*ALL)  OPTION(*NEW)

This command saves the object named FLETCH located in the library named CHASE and restores it on the remote system named SYSTEM1 using address type *SNA if it is does not already exist on the remote system.

Error messages

*ESCAPE Messages

CPCAD80

&1 objects saved and restored.

CPFAD8D

An error occurred during the &1 operation.

CPFAD80

Unable to establish connection from &1 to &2.

CPFAD81

User profile &1 not found on remote location &2.

CPFAD82

Remote location &1 not found.

CPFAD83

Remote location &1 cannot be source location.

CPFAD84

ObjectConnect internal error, function code &1, return code &2.

CPFAD86

Location name &1 unable to close &2.

CPFAD88

Unable to establish connection from &1 to &2.

CPFAD93

APPC failure. Failure code is &3.

CPF389C

ObjectConnect ended, function code

ObjectConnect ended, function code &1, return code &2.amp;1, return code

ObjectConnect ended, function code &1, return code &2.amp;2.