<ARCHDEF> Tag syntax

The <ARCHDEF> and corresponding </ARCHDEF> tags identify the beginning and end of a specific archive retrieval request. The following attributes may be found on the <ARCHDEF> tag:

name="archive name"

specifies the path name for an archive file to be extracted by GIMUNZIP. The path name may include a subdirectory name (provided by the subdir attribute when the archive was created by GIMZIP). The path name value is a relative value and it is relative to the package directory specified on the SMPDIR DD statement. The name attribute is mutually exclusive with the archid attribute.

Note: If the archive file has been segmented in the package, you should specify the name of the archive file, not the names of the archive segment files. GIMUNZIP will combine the associated archive segment files to extract the complete archive.

archid="archive id"

specifies a unique archive id associated with an archive file to be extracted by GIMUNZIP. GIMUNZIP will search the package attribute file looking for the archive file with this unique archid. The archid attribute is mutually exclusive with the archive name attribute.

volume="data set volume | *"

specifies the volume serial number of the volume on which GIMUNZIP is to request the allocation of the data set to be extracted from the archive file. The volume identifier must be from 1 to 6 alphanumeric characters or an asterisk (*).

Note:

1. If you are extracting a sequential, partitioned, or VSAM data set into an existing cataloged data set, you should not specify the volume attribute.
2. If you are extracting a sequential or partitioned data set:
   • Into a new data set to be allocated on a specific volume, or into an existing, uncataloged data set on a specific volume, you must specify volume=data set volume. If you specify volume=* it is ignored.
   • Into an existing, uncataloged data set on a specific volume, you must specify volume=data set volume. If you specify volume=* it is ignored.

   The data set is first allocated with a disposition of (OLD,KEEP) using the specified volume. If the data set is not on the volume, the data set is allocated again with a disposition of (OLD,KEEP) without specifying a volume, to see if there is an existing cataloged data set that should be used for the extraction. If an existing cataloged data set is allocated, the archive is extracted into the cataloged data set, even though the volume on which it is allocated is different from the volume specified.

3. If you are extracting a VSAM data set:
   • Into a new data set, you can specify volume=data set volume,

     Or,

     You can specify volume=*. GIMUNZIP uses the value on the VOLUMES parameter on the IDCAMS DEFINE command that GIMUNZIP will generate to create the new VSAM data set. Using the VOLUMES(*) parameter on the generated IDCAMS DEFINE command may allow SMS to assign a volume for the new VSAM data set if the automatic class selection (ACS) routines allow it.

   • Into an existing destination data set, a data set volume you specify on the volume attribute is ignored.

     Since VSAM data sets must be cataloged, the catalog is checked first to see if the VSAM destination data set already exists.

4. If you specify volume=data set volume, GIMUNZIP will use the specified volume to dynamically allocate work space to the SYSUT1 ddname during the processing of the archive. If you do not specify the volume attribute or you specify volume=*, then you must make available at least one volume of mounted storage or the allocation to the SYSUT1 ddname will fail.
5. If you are extracting a UNIX file or directory, you do not need to specify the volume attribute. It is ignored. However, if you specify a volume attribute, it must be syntactically correct.

newname="name"

specifies the data set name or absolute pathname to use for the data set or file to be extracted from the archive file. This name replaces the original name of the data set or file that is recorded in the archive's file attribute file.

The newname specified must identify the same type of data as the file being unzipped. That is, if the file being unzipped is a data set, newname must represent a data set. If the file being unzipped is a file or directory in the UNIX file system, newname must represent a file or directory in the UNIX file system.

The first character of an absolute pathname of a file or directory in the UNIX file system must be a slash (/). If the newname value does not begin with a slash, GIMUNZIP processing will assume that it is an MVS™ data set name and that it will conform to the MVS data set naming conventions. If the newname value does begin with a slash, it is assumed to be a file or directory in the UNIX file system. When a file or directory in the UNIX file system is specified, the newname value can be from 1 to 1023 bytes long with 255 characters between delimiters (/). The value can be any character from X'40' through X'FE', except less than (<) and greater than (>) signs, ampersands (&), and double quotation marks ("). All data beyond column 72 is ignored, including blanks. The pathname of a file or directory in the UNIX file system is case sensitive and will not be converted to uppercase alphabetic during processing of the GIMUNZIP package control tags.

The newname specified may identify an existing data set, directory, or file. In this case, the archived file is unzipped into the existing data structure specified on the newname attribute. If the newname attribute is not specified for a file or directory in the UNIX file system, the original name for the file or directory is used. If neither the prefix nor the newname attributes are specified when a data set is being extracted, the original name for the data set is used.

prefix="data set prefix"

specifies a data set prefix to use for the data set to be extracted from the archive file. This prefix replaces the high-level qualifier of the original name for the data set as recorded in the archive's file attribute file. The specified data set prefix can be up to 26 characters long and must conform to standard data set naming conventions.

The resolved name using the prefix attribute may be for an existing data set. In this case, the archived data is extracted into the existing data set specified using the prefix attribute.

A prefix value has no meaning when the file being unzipped is a file or directory in the UNIX file system. In this case, the prefix value is parsed but ignored.

If neither the prefix nor the newname attributes are specified, the original name for the data set is used.

replace="YES | NO"

indicates whether data in an existing data set, file or directory should be replaced by data from the archive file. A value of YES indicates the data in the existing data set, file or directory should be replaced. A value of NO is equivalent to not specifying the replace attribute and indicates the data should not be replaced. The replace attribute is not meaningful when the data set, file or directory does not already exist.

• For an archive of a partitioned data set or directory in the UNIX file system, replace="YES" indicates that existing members in a partitioned data set and files in a directory will be replaced by members or files with the same name from the archive file. If replace="NO" is specified, or if the replace attribute is not specified at all, existing members and files will not be replaced.
• For an archive of a sequential data set or a file in the UNIX file system, replace="YES" indicates the existing data set or file and its attributes will be replaced with the data from the archive file. If replace="NO" is specified, or if the replace attribute is not specified at all, the existing sequential data set or file will not be replaced with the data from the archive file.
  Note: GIMUNZIP will not check if a sequential data set or file is empty. If the data set or file exists, it will not be replaced unless replace="YES" is specified.
• For a VSAM data set (cluster), replace="YES" indicates that an existing VSAM cluster should be populated with the data from the archive file. If replace="NO" is specified, or if the replace attribute is not specified at all, there will be no attempt to populate the existing VSAM cluster with the data from the archive.
  Note:

  1. The existing VSAM cluster must be of the same type as the archived cluster (ESDS, KSDS, LDS, or RRDS).
  2. The existing VSAM cluster must have characteristics that are compatible with the archived cluster (such as, record size, key size, and key offset). GIMUNZIP does not verify the compatibility of these characteristics.
  3. To replace the contents of an existing cluster, the cluster is altered to a reusable state by using an IDCAMS ALTER command, if necessary, before the data from the VSAM archive is copied into the cluster by using an IDCAMS REPRO command. The REPRO command will use both the REPLACE and REUSE operands. Following the REPRO operation, the cluster is altered back to a nonreusable state if that was its state to begin with.

preserveid="YES | NO"

indicates whether the UID and GID of the extracted file or directory should:

• Remain as defined when the archive was created, or
• Inherit the UID and GID of the userid performing the extract operation (GIMUNZIP).

A value of YES indicates that the UID and GID from when the archive was created will be preserved. A value of NO is equivalent to not specifying the preserveid attribute and indicates that the UID and GID should be inherited from the userid performing the extract operation (GIMUNZIP).

Note:

1. Preserving the UID and GID defined when the archive was created may cause GIMUNZIP to fail if the installer does not have the proper permissions.
2. The preserveid attribute applies only when extracting a UNIX file or directory from an archive. When extracting a data set, preserveid is parsed for syntax but otherwise ignored.