Optional parameters

The following are the optional parameters of the ARCHBACK macro:

DATE

specifies the address of a field which contains the backup date to assign to the new backup version that will be created via the ARCHBACK macro. DATE can ONLY be specified with NEWNAME or the invocation will fail. For dateaddr, substitute the address of a data area that contains the backup date. The field referenced by dateaddr must contain 7 characters in the form of yyyyddd. This parameter applies to both SMS-managed and non-SMS-managed data sets.

NEWNAME

specifies the data set name to assign to the new backup version that is created by specifying the BACKDS command. The NEWNAME parameter must be fully-qualified and in the standard data set name format.

RETAINDAYS

specifies the number of days to retain a specific backup copy of a data set. For rdaddr substitute the address of the 5–byte data area that contains the RETAINDAYS value. RETAINDAYS specifies the minimum number of days (0–50000) that DFSMShsm retains the backup copy. If you specify 99999, the data set backup version never expires. Any value greater than 50000 (and other than 99999) causes a failure with an ARC1605I error message. A retain days value of 0 indicates that:

the backup version might expire within the same day that it was created if EXPIREBV processing takes place,
the backup version is kept as an active copy before roll-off occurs,
the backup version is not managed as a retained copy.

SPHERE

specifies whether the AIX and PATH components of a VSAM data set will be backed up with the base cluster. SPHERE can ONLY be specified with NEWNAME or the invocation will fail. If NO is specified, a backup of the base cluster will be performed, but backup for any associated AIXs and/or PATHs will not be performed. If YES, the default, is specified, a backup of the entire VSAM SPHERE will be performed. The following restrictions apply when using the SPHERE parameter:

No more than one PATH can be defined for the data set to back up, and no more than one PATH can be defined for the NEWNAME data set.
No more than one AIX can exist for the data set to back up, and no more than one AIX can exist for the NEWNAME data set.

This parameter applies to both SMS-managed and non-SMS-managed data sets.

TIME

specifies the address of a field which contains the backup time to assign to the new backup version that will be created via the ARCHBACK macro. TIME can ONLY be specified when NEWNAME AND DATE are also specified. For timeaddr, substitute the address of a data area that contains the backup time. The field referenced by timeaddr must contain 6 characters in the form of hhmmss. For hhmmss, substitute the time to assign to the backup version. If the seconds are unknown, specify '00' for ss. If TIME is not specified, DFSMShsm will set a time of 120000. This parameter applies to both SMS-managed and non-SMS-managed data sets.

GVCN

overrides the SETSYS DSBACKUP(GENVSAMCOMPNAMES) setting. If GVCN=YES is specified, and the NEWNAME data set represents a VSAM base cluster that is either migrated or uncataloged, DFSMShsm will process the request, and default names will be assigned to the VSAM data and index components. If GVCN=NO is specified, and the NEWNAME data set represents a VSAM base cluster that is either migrated or uncataloged, the data set backup command will fail. DFSMShsm ignores the GVCN specification when the NEWNAME data set is cataloged to a volser other than MIGRAT. This parameter applies to both SMS-managed and non-SMS-managed data sets.

If the old component's name is equal to the old cluster name (plus any suffix), then the new component name will equal the new cluster name, plus the same suffix of the old component. For more information on how component (default) names are derived during rename processing see z/OS DFSMSdss Storage Administration.

ASYNC

specifies whether the special asynchronous backup processing is requested. The requesting application must be authorized by the authorized program facility (APF) to request the ASYNC option. If ASYNC=YES is specified, the WAIT parameter must also be specified as YES to allow the ECB to be posted back to the user when DFSMShsm completes the function. The default is NO. This parameter applies to both SMS-managed and non-SMS-managed data sets.

If YES is specified, storage for the generated MWE is obtained in the requester's private storage, and an event control block (ECB) address is returned in register 1 when control is returned to the requester. The application program is responsible for freeing this storage area; however, do not free it until the ECB is posted. You must use the ARCFMWE macro to free the storage area by supplying the ECB address. In cases where a zero value is returned for the ECB address, the request has failed and storage is not obtained for the MWE. Upon return from the ARCFMWE macro, the return code is in register 15 and a reason code is in register 0. If register 15 contains a return code of 400, 401, or 806, this error is from the completion of the ARCFMWE macro. All other return codes contained in register 15 are from the completion of the ARCHBACK macro. The last reported, nonzero return code is in register 15. For example:

If the return code from ARCHBACK is:	And the return code from ARCFMWE is:	Then the return code placed in register 15 is from:
Zero	Nonzero	ARCFMWE
Nonzero	Zero	ARCHBACK
Nonzero	Nonzero	ARCFMWE

WAIT

specifies whether you want the application to wait until DFSMShsm has processed this request. If you specify YES without ASYNC=YES, the application does not receive control back until DFSMShsm completes processing of the request. The default is NO. This parameter applies to both SMS-managed and non-SMS-managed data sets.

TARGET

specifies whether tape or DASD will be the target of the backup output data set. If you specify TAPE, the backup data set goes to tape. If you specify DASD, the backup data set goes to DASD. If you specify neither, DFSMShsm decides the target for this data set.

CC

specifies whether you want to use concurrent copy and which notification options that you want. If you specify PREFERRED, CACHEPREFERRED or VIRTUALPREFERRED, you have indicated that you want to use concurrent copy, if it is available. However, processing continues even if concurrent copy is not available. If you specify REQUIRED, CACHEREQUIRED or VIRTUALREQUIRED then a form of concurrent copy is a requirement, and the command fails if that form of concurrent copy is not available. If you specify STANDARD, you do not want to use concurrent copy. The default is STANDARD.

If you specify PHYSICALEND, you will receive notice when the physical end of the backup has completed. If you specify LOGICALEND, you will receive notice when the concurrent copy initialization has completed. The default is PHYSICALEND.

Note:

If you use the CC option with LE or PE, you must also specify the option WAIT=YES.
You can abbreviate PHYSICALEND and LOGICALEND as PE and LE, respectively. You can abbreviate PREFERRED as PREFER. You can abbreviate CACHEPREFERRED as CPREF, VIRTUALPREFERRED as VPREF, CACHEREQUIRED as CREQ, and VIRTUALREQUIRED as VREQ.

DSNENQ

specifies whether the data set is serialized by DFSMShsm during backup processing. If NO is used, the data set is not enqueued during backup processing, and the application program is responsible for data set serialization. The data set is not allocated and the SYSDSN resource is not obtained if NO is chosen. If YES is chosen, normal serialization occurs. The default is YES.

VOLUME

specifies the address of a field that contains the volume serial number of a volume that contains the requested uncataloged data set. For volseraddr, use the address of the six-character field that contains the volume serial number. The volume serial number must be left-justified and padded with blanks. This parameter applies only to non-SMS-managed data sets.

Note: Do not specify the VOLUME parameter if the data set to be backed up is a cataloged data set. If you specify the VOLUME parameter, you must also specify the UNIT parameter.

UNIT

specifies the address of a field that contains the unit type of the non-DFSMShsm-managed volume that contains the uncataloged data set. For unitaddr, use the address of the four-byte field that contains the UCB device type. For example, X'3010200E' is the UCB unit type for a 3380 device. For a table showing the supported unit types and UCBs, see Table 1. This parameter applies only to non-SMS-managed data sets.

Note: Do not specify the UNIT parameter if the data set to be backed up is a cataloged data set. If you specify the UNIT parameter, you must also specify the VOLUME parameter.

SNAPDCB

specifies the address of an open DCB that can be used for SNAP macro processing. This feature is intended for problem determination. If you specify this parameter, review Usage notes. For dcbaddr, specify the address of an open DCB.

TEST

specifies whether to refrain from sending a request for service to DFSMShsm. If YES is specified, the service request is not sent. If NO is specified, a service request is sent to DFSMShsm. In both cases the parameters specified to the macro are checked for correctness. A 4xx return code results for invalid parameters. The default is NO.