WRAP Statement

<wrap statement> 

── WRAP ─┬───────────────────────────────────┬─<wrap group>────────────►
         │ ┌◄──────────────────────────────┐ │
         └─┴─┬─ & ───┬─┬─/1\─ USEPATH ───┬─┴─┘
             └─ AND ─┘ ├─/1\─ DSONERROR ─┤
                       ├─/1\─ COMPRESS ──┤
                       └─/1\─ REPORT ────┘
►─┬─────────────────┬─┬───────────────────────────────┬────────────────►
  └─ <wrap volume> ─┘ └─ [ ── <task identifier> ── ] ─┘
►─┬────────────────────────────────────────┬───────────────────────────┤
  │ ┌◄───────────────────────────────────┐ │
  └─┴─ ; ── <task attribute assignment> ─┴─┘

<wrap group> 

    ┌◄─────── , ───────┐
──┬─┴─ <wrap request> ─┴─┬──────────────────────────────┬─┬────────────┤
  │                      └─ , ── <simple wrap request> ─┘ │
  └─ <simple wrap request> ───────────────────────────────┘

<simple wrap request> 

  ┌◄──────────────── , ───────────────┐
──┴─ <wrap file> ─┬─────────────────┬─┴────────────────────────────────┤
                  └─ FROM <source> ─┘

<wrap request> 

  ┌◄──────────────── , ───────────────┐
──┴─ <wrap file> ─┬─────────────────┬─┴────────────────────────────────────────►
                  └─ FROM <source> ─┘
►─┬─ SEPARATELY ─────────────────────────────────────────────────────────────┬─┤
  └─ INTO ── <file name> ─┬──────────────────────────────────────────────────┤
                          │     ┌◄───────────────── , ─────────────────┐     │
                          └─ ( ─┴─┬─/1\─ ENCRYPT = AESGCM ───────────┬─┴─ ) ─┘
                                  └─/1\─ PASSWORD = <wrap password> ─┘

<wrap file> 

──┬─ <file name> ─┬─────────────────────┬───────────┬──────────────────┤
  │               └─ AS ── <file name> ─┘           │
  └─ <directory name> ─┬──────────────────────────┬─┘
                       └─ AS ── <directory name> ─┘

<wrap volume> 

──┬─ TO ── <destination> ─────────────────────────┬────────────────────┤
  └─ FROM ── < source> ─┬───────────────────────┬─┘
                        └─ TO ── <destination> ─┘

<source> 

── <family name> ─┬───────────────────────────────────────────┬────────┤
                  └─ ( ────────┬─────────────┬─┬─ DISK ─┬─ ) ─┘
                               └─ KIND ── = ─┘ └─ PACK ─┘

<destination> 

── <family name> ─┬──────────────────────────────────────────────────┬─┤
                  │     ┌◄───────────────── , ─────────────────┐     │
                  └─ ( ─┴─┬─ /1\ ─┬─────────────┬─┬─ DISK ─┬─┬─┴─ ) ─┘
                          │       └─ KIND ── = ─┘ └─ PACK ─┘ │
                          ├─/1\─ RESTRICTED ─┬───────────────┤
                          │                  └─ = ┬─ TRUE ───┤
                          │                       └─ FALSE ──┤
                          ├─/1\─ ENCRYPT = AESGCM ───────────┤
                          └─/1\─ PASSWORD = <wrap password> ─┘

Explanation

The WRAP statement enables users to

  • Wrap disk files into new files with a FILEKIND value of WRAPPEDDATA.

  • Wrap multiple disk files into a single file with a FILEKIND value of CONTAINERDATA.

  • Create wrapped files and wrapped containers with digital signatures.

  • Create compressed files and containers.

  • Create encrypted files and containers.

A wrapped file created using the WRAP statement contains the file data and the original disk file headers. A wrapped container is made up of one or more wrapped files. Both wrapped files and containers can be transported across an open network and then be re‑created on another ClearPath MCP system using the UNWRAP statement.

To wrap files from multiple sources, a source that directly follows a wrap file list has scope only for that list. If a destination does not follow a wrap file list, then the list uses a destination in the wrap volume. Family DISK is used if there is no source in the wrap volume.

A source can be interpreted as being in a simple wrap request or a wrap volume. This ambiguity is resolved to maintain consistency with previous semantics, which had only one source. If the statement contains a source that might be in a wrap volume and it is the only source specified, then it is applied to all the files.

The COMPRESS option causes the wrapped files and containers to be created compressed. The UNWRAP statement automatically decompresses wrapped files. The COMPRESSION product key (nnn-COMPRESSION-CPR) is required if the wrapped container file is not for Unisys support use.

If the PASSWORD attribute is specified, the file or container is encrypted using an encryption key derived from the password. The encryption algorithm can be specified using the ENCRYPT attribute (only AESGCM is currently supported). If the ENCRYPT attribute is not specified, the default encryption algorithm (currently AESGCM) is used. The encryption attributes for WRAPPEDDATA files are specified on the destination family name and for CONTAINERDATA files on the container file name.

If you specify the DSONERROR option, the wrap process aborts whenever it encounters an error.

If you specify the REPORT option, the wrap process generates a report that describes which files were successfully wrapped, and which files could not be wrapped.

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. For details on using the "=" and "*=" syntax, refer to the COPY or ADD statement earlier in this section.

Although WRAP statement syntax permits the specification of the RESTRICTED attribute, primarily for consistency with the UNWRAP statement, the attribute has no meaning upon a wrap operation and is ignored. Refer to the UNWRAP statement earlier in this section for information on how to use the RESTRICTED attribute.

To wrap a SYSTEMDIRECTORY file, you must specify its file name in full. For example, the statement “WRAP *SYSTEMDIRECTORY/= AS SYSDIR/= FROM . . .”does not wrap a system directory file but the following statement does: 

WRAP *SYSTEMDIRECTORY/001 AS SYSDIR/1 FROM. . .

When the MCP wraps a SYSTEMDIRECTORY file, it erases the special system file mark from the internal attributes of the wrapped file so that when the file is unwrapped, the file can be removed with the WFL REMOVE statement or be renamed with the WFL CHANGE statement.

To wrap a JOBDESC file, which is a file with a FILEKIND attribute value of JOBDESCFILE, you must specify the file name in full. For example, the statement “WRAP *= INTO . . .” does not wrap a job description file, but the following statement does: 

WRAP *JOBDESC INTO . . .

When the MCP wraps a JOBDESC file, it changes the FILEKIND attribute of the wrapped file to DATA.

MCP_FILEWRAPPER takes special action to ensure that the copies of the various files making up a KEYEDIOII set are consistent with each other. In general, when you wrap a KEYEDIOII file, it is advisable to wrap all the related files in the same wrap statement. If any of the files in the KEYEDIOII set are opened for update, then none of the files are wrapped.

Digital Signatures

The WRAP statement enables also you to create a wrapped file or wrapped container with an embedded digital signature. A digital signature is a hash pattern that is created by applying an industry standard signature algorithm to the file along with a private key. This hash pattern travels with the file across a network and is used with a public key to ensure that the file has not been compromised during the transfer process.

To wrap files with a digital signature, you must

  • Obtain a public and private key pair for the software level that the files are to be wrapped against. For information on how to generate digital signature public and private keys, refer to the procedure MCP_GENERATEDSAKEYS in the MCP System Interfaces Programming Reference Manual.

  • Specify the hex string value of the private key through the task attribute TASKSTRING. If the files are to be wrapped against a software level other than the current level, specify that software level through the task attribute TARGET.

    Note: A digital signature key pair generated for one software level cannot be used to wrap files against another software level.

  • Pass on the corresponding public key to the party responsible for unwrapping the digitally signed wrapped files or wrapped containers.

Digital signatures are optional for most files. However, when wrapping a file whose FILEKIND attribute value is KEYSFILE, the system requires the file to be digitally signed. This restriction ensures that sensitive data contained in the keysfile is not being modified in any way and guarantees the authenticity of the originator of the file.

Note: See the MCP System Interfaces Programming Reference Manual for information on MCP_FILEWRAPPER and SIGNATURESUPPORT error results.

Examples

The following example shows how to create the wrapped file WRAPPED/FILEA from FILEA and WRAPPED/FILEB from FILEB: 

WRAP  FILEA AS WRAPPED/FILEA,
      FILEB AS WRAPPED/FILEB;

The following example shows how to create the wrapped file FILED by overwriting the original file with the same title: 

WRAP FILED;

The following example shows how to create the container CONTAINER1 that includes FILEE and FILEF: 

WRAP FILEE, FILEF INTO CONTAINER;

The following example shows how to create the container CONTAINER2 that includes the renamed files FILEG2 and FILEH2: 

WRAP  FILEG AS FILEG2, 
      FILEH AS FILEH2 
                    INTO CONTAINER2;

The following example shows how to create both wrapped files and containers in one single WRAP statement: 

WRAP  FILEI AS WRAPPED/FILEI,
      FILEJ SEPARATELY,
      FILEK, FILEM INTO CONTAINER3,
      FILEN AS FILEN2, FILEO INTO CONTAINER4;

The following example demonstrates the DSONERROR option. If any of the specified files is missing, the container MYCONTAINER is not created. 

WRAP &DSONERROR MYFILE/A, MYFILE/B, MYFILE/C
                INTO MYCONTAINER FROM DISK TO PACK;

The following example shows how to create a digitally signed wrapped file against SSR level 59.1. The private key has already been generated based on SSR level 59.1. 

WRAP MY/FILE AS MY/SIGNED/WRAPPED/FILE;
     TARGET=591; TASKSTRING=<59.1 private key's hex string>;

The following example shows how to create a digitally signed wrapped container against the current software level. The private key has already been generated based on the current software level. 

WRAP MY/DIRECTORY/= INTO MY/SIGNED/CONTAINER;
     TASKSTRING=<current level private key's hex string>;

The following example shows the use of the USEPATH modifier to wrap the files *DIR/SHARED/PROJECTFILES/MYFILE from PROJECTPACK and *YOURFILE from DISK into a container named *DIR/SHARED/PROJECTFILES/MYCONTAINER on PROJECTPACK. 

WRAP & USEPATH MYFILE, *YOURFILE INTO MYCONTAINER;
   DATAPATH = *DIR/SHARED/PROJECTFILES ON PROJECTPACK;

The following examples show how to wrap files from multiple volumes in a single WRAP statement. The container C1 is created by wrapping FILEJ from DISK, and FILEK and FILEL from MYPACK. 

WRAP FILEJ FROM DISK, FILEK, FILEL FROM MYPACK INTO C1;
WRAP FILEJ FROM DISK, FILEK, FILEL INTO C1 FROM MYPACK;

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 wrapped into the container, and shows that TEMP/DOESNTEXIST was not wrapped because it does not exist on PACK. 

WRAP & REPORT TEMP/1, TEMP/2, TEMP/DOESNTEXIST 
    INTO TEMPCONTAINER;

(MCPUSER)TEMP/DOESNTEXIST NOT ON PACK
WRAPPING INTO CONTAINER: (MCPUSER) TEMPCONTAINER 
    ON PACK
(MCPUSER)TEMP/1 WRAPPED FROM PACK 
(MCPUSER)TEMP/2 WRAPPED FROM PACK
Prev  Up  Next
WHILE Statement  Home  Expressions