── UNWRAP ─┬───────────────────────────────────┬─<unwrap group>──────►
│ ┌◄──────────────────────────────┐ │
└─┴─┬─ & ───┬─┬─/1\─ USEPATH ───┬─┴─┘
└─ AND ─┘ ├─/1\─ RECOVER ───┤
├─/1\─ DSONERROR ─┤
└─/1\─ REPORT ────┘
►─┬───────────────────┬─┬───────────────────────────────┬──────────────►
└─ <unwrap volume> ─┘ └─ [ ── <task identifier> ── ] ─┘
►─┬────────────────────────────────────────┬───────────────────────────┤
│ ┌◄───────────────────────────────────┐ │
└─┴─ ; ── <task attribute assignment> ─┴─┘┌◄──────── , ────────┐ ──┬─┴─ <unwrap request> ─┴─┬────────────────────────────────┬─┬────────┤ │ └─ , ── <simple unwrap request> ─┘ │ └─ <simple unwrap request> ─────────────────────────────────┘
┌◄────────────────── , ──────────────────┐
──┴─ <unwrap file> ─┬────────────────────┬─┴───────────────────────────┤
└─ TO <destination> ─┘ ┌◄───────────────── , ─────────────────┐
──┴─ <wrap file> ─┬────────────────────┬─┴─────────────────────────────►
└─ TO <destination> ─┘
►─┬─ SEPARATELY ────────────────────────────────────────────────────┬──┤
└─ OUTOF ── <file name> ─┬────────────────────────────────────────┤
└─ ( ── PASSWORD = <wrap password> ── ) ─┘──┬─ <file name> ─┬─────────────────────┬────────────┬──────────────────┤
│ └─ AS ── <file name> ─┘ │
├─ <file number> ─┬─────────────────────┬──────────┤
│ └─ AS ── <file name> ─┘ │
└─ <directory name> ─┬──────────────────────────┬──┘
└─ AS ── <directory name> ─┘<file number>
─── # <integer constant> ──────────────────┤
──┬─ TO ── <destination> ──────────────────────────┬───────────────────┤
└─ FROM ── < source> ─┬────────────────────────┬─┘
└─ TO ── < destination> ─┘── <family name> ────────────────────────────────────────────────────────►
►─┬───────────────────────────────────────────────────────────┬──────────┤
│ ┌◄───────────────────── , ──────────────────────┐ │
└─ ( ─┴─┬─/1\─┬───────────────────────┬─┬─ DISK ──┬───┴─ ) ─┘
│ └─ KIND = ──────────────┘ ├─ PACK ──┤
│ ├─ CD ────┤
│ └─ CDROM ─┤
└─/1\─ PASSWORD = <wrap password> ────────┘── <family name> ─┬────────────────────────────────────────────────┬───┤
│ ┌◄──────────────── , ────────────────┐ │
└─ ( ─┴─┬─ /1\ ─┬─────────────┬─┬─ DISK ─┬─┴─ ) ─┘
│ └─ KIND ── = ─┘ └─ PACK ─┤
└─/1\─ RESTRICTED ─┬─────────────┤
└─ = ┬─ TRUE ─┤
└─ FALSE─┘Explanation
The UNWRAP statement enables users to
-
Unwrap files wrapped by the WRAP statement.
-
Unwrap all or selected wrapped files from a container.
The unwrap process re-creates the original files from the data contained within the wrapped files or containers. By default, UNWRAP also marks system files, compilers, backup files, and code files as restricted. A security administrator on a system running with the security administrator status enabled or a privileged user can override this restriction by setting the RESTRICTED attribute to FALSE. If the file was restricted before being wrapped, it will remain restricted even if the UNWRAP statement specifies RESTRICTED=FALSE.
You can also copy unwrapped data files from a CD-ROM as part of an unwrap operation, by setting the task attribute SW1. The system then tests to see if requested files are wrapped, then it
-
Unwraps wrapped files.
-
Copies other files as CDATA files.
To unwrap files to multiple destinations, a destination that directly follows an unwrap file list has scope only for that list. If a destination does not follow an unwrap file list, then the list uses a destination in the unwrap volume. DISK is used if there is no destination in the unwrap volume.
A destination can be interpreted as being in a simple unwrap request or an unwrap volume. This ambiguity is resolved to maintain consistency with previous semantics, which had only one destination. If the statement contains a destination that might be in an unwrap volume and it is the only destination specified, then it is applied to all files.
To select a file by position within the directory, you can specify the <file number> in the unwrap file statement. You can use the <file number> attribute to unwrap files when the same file name appears more than once in the container directory. The file number value must be an integer greater than zero, fewer than 12 digits in length (including leading zeros).
| Note: | To determine the file number of a particular file in a container,
use the FILEDATA NAMELIST request: RUN *SYSTEM/FILEDATA ("NAMELIST: DIR=*=
CONTAINER=<container>")The DIR parameter must be "*=" to select all files in the directory
because the file number listed in the report refers to the position
in the list rather than the position in the directory. To see the
file numbers in the NAMELIST report, you can direct output a printer,
or use the DEFINEOUTPUT request to set LINEWIDTH to at least 81. For
example:RUN *SYSTEM/FILEDATA ("DEFINEOUTPUT:LINEWIDTH=96;
NAMELIST: DIR=*=
CONTAINER=<container> SCR") |
If the PASSWORD attribute is specified, the file or container is decrypted using the encryption algorithm specified when the file was created and an encryption key derived from the password. The PASSWORD attribute for WRAPPEDDATA files is specified on the source family name and for CONTAINERDATA files on the container file name.
If you specify the RECOVER option in the UNWRAP statement, the unwrap process attempts to recover internal wrapped files whenever it encounters a bad container whose directory is missing, incomplete, or corrupted. The RECOVER option is applicable only to container files and cannot be used with the DSONERROR option. You cannot specify a file number in conjunction with the RECOVER option because the file number cannot be determined if the directory is missing, incomplete, or corrupted.
If you specify the DSONERROR option, the unwrap process aborts whenever it encounters an error.
If you specify the REPORT option, the unwrap process generates a report that describes which files were successfully unwrapped, and which files could not be unwrapped.
USEPATH causes the DATAPATH attribute to be used when resolving nonqualified file names. This includes file names without a usercode or system (*) prefix and without a family name or with a family name of DISK. Only the first element in the DATAPATH attribute string is used. Substitution is applied only when the source volume is disk. It is not used if the source is CD-ROM.
The TASKVALUE attribute can be tested to determine the success or failure of the wrap or unwrap of disk files. When the value of the TASKVALUE attribute is 0, all requests were satisfied. When the value of the TASKVALUE attribute is not 0, one or more files were not wrapped or unwrapped. A nonzero value is also returned if the wrap or unwrap operation is discontinued.
To wrap files into a container, use the INTO syntax. To unwrap files out of a container, use the OUTOF syntax. A directory name of *= wraps or unwraps all files. Only a privileged user can use this directory name. A directory name of = wraps or unwraps all files in the user's directory; if no files exist and the caller is privileged, all files in the system directory are wrapped or unwrapped.
Some wrapped files or wrapped containers might have already been digitally signed by a private key. Unwrapping such files requires you to obtain a corresponding public key and specify it through the task attribute TASKSTRING.
To see what files are wrapped in a container, you can invoke the FILEDATA utility from WFL, as follows:
RUN *SYSTEM/FILEDATA ("ATTRIBUTES: DIR = *=
CONTAINER =
<container name>")You can also use the CANDE LFILES command for the same effect:
LFILES *= :CONTAINER = <container name>
See the System Software Utilities Operations Reference Manual for details.
| Note: | See the MCP System Interfaces Programming Reference Manual for information on MCP_FILEWRAPPER and SIGNATURESUPPORT error results. |
Examples
The following examples demonstrate the UNWRAP statement:
UNWRAP = OUTOF CONTAINER1;
UNWRAP FILEC AS NEWFILEC
OUTOF CONTAINER1;UNWRAP FILEF, FILEB AS NEWFILEB;
The following examples show how to override the RESTRICTED option:
UNWRAP WRAPPED/FILE AS UNWRAPPED/FILE FROM MYCD(CD)
TO MYPACK(RESTRICTED=FALSE);UNWRAP *= OUTOF MYCONTAINER TO MYPACK(RESTRICTED=FALSE);
The following example demonstrates the RECOVER option:
UNWRAP &RECOVER *= AS UWFILES/= OUTOF (THIEN)CONTAINER
FROM DISK TO MYPACKThe following example demonstrates the DSONERROR option:
UNWRAP &DSONERROR MYSTUFFS/= OUTOF MYCONTAINER FROM MYCD(CD)
TO MYPACK;The following example shows how to unwrap a digitally signed wrapped file. The public key is obtained from the person who wrapped the file.
UNWRAP MY/SIGNED/WRAPPED/FILE AS MY/FILE;
TASKSTRING=<the public key's hex string>;The following example shows how to unwrap a digitally signed wrapped container. The public key is obtained from the person wrapped the container.
UNWRAP *= OUTOF MY/SIGNED/CONTAINER;
TASKSTRING=<the public key's hex string>;The following example shows the use of the USEPATH modifier to unwrap files from a container named *DIR/SHARED/PROJECTFILES/MYCONTAINER on PROJECTPACK.
UNWRAP & USEPATH *= OUTOF MYCONTAINER; DATAPATH = *DIR/SHARED/PROJECTFILES ON PROJECTPACK;
The following example shows how to unwrap files from multiple volumes in a single UNWRAP statement. Out of container C1, FILEJ is unwrapped to DISK, and FILEK and FILEL are unwrapped to MYPACK.
UNWRAP FILEJ TO DISK(RESTRICTED=FALSE), FILEK, FILEL OUTOF C1
TO MYPACK;The following example shows how to specify a file number.
UNWRAP #3 OUTOF MYCONTAINER
The following example shows the use of the REPORT option to generate a report. The report shows that TEMP/1 and TEMP/2 were successfully unwrapped from the container, and shows that TEMP/DOESNTEXIST was not unwrapped because it does not exist in TEMPCONTAINER.
UNWRAP & REPORT TEMP/1, TEMP/2, TEMP/DOESNTEXIST
OUTOF TEMPCONTAINER TO DISK
(MCPUSER)TEMP/DOESNTEXIST NOT IN (MCPUSER)TEMPCONTAINER
UNWRAPPING OUT OF CONTAINER: (MCPUSER)TEMPCONTAINER
ON LANGTEST
REPLACED (MCPUSER)TEMP/1 ON LANGTEST
REPLACED (MCPUSER)TEMP/2 ON LANGTEST
