Self Extracting Archives

Overview

COPYWRITE Self Extracting Archive is an A-Series codefile which contains an archive of files. When the codefile runs, it extracts each file from the archive, and passes it to Library Maintenance, which copies it to the destination volume.

The archive codefile can run on any MCP, and does not require any other UNISYS or METALOGIC software to extract the files.

Instructions may be associated with each file in the archive, and the archive file itself, to perform actions such as starting a job, running a program or entering an ODT command, defining anMCS , recalling a USERDATAFILE or doing a HALTLOAD.

How to create a Self Extracting Archive

An archive codefile is created as though a CD-ROM image is being created, but theLOCKEDFILE attribute is set on the destination volume.

	COPY *= FROM RELEASE(PACK) TO SETUP(CD,HOSTNAME=LOCAL,LOCKEDFILE);

The destination volume name is the name given to the archive. In the example, an archive codefile called SETUPwill be created. The codefile is given a FILEKIND of ESPOLCODE, so that it can be easily identified as an archive.

The archive may be created using either an ADD, COPY or COPY&COMPARE statement. The type of statement does not affect how the archive is created, but it does determine how the files are extracted.

If the archive is created with a COPY statement, the files are extracted with a COPY statement, so that any existing files will be overwritten. (See Switches for how this behaviour may be changed).

If the archive is created with an ADD statement, the files are extracted with an ADD statement, so that if a file already exists on the disk, the archive file will not be added.

If the archive is created with a COPY&COMPARE statement, the files are only extracted if they are a better version than the file on disk, or there is no file on disk.

Instructions may be associated with the archive codefile when it is created, by label equating the TASKSTRING attribute containing instructions, to the COPY statement. For example,

 	COPY *= FROM RELEASE(PACK)
 TO SETUP(CD,HOSTNAME=LOCAL,LOCKEDFILE);TASKSTRING ="ENTER *ODTCOMMANDS ON %3"

Instructions may be associated with the execution of the archive by label equating the TASKSTRING attribute containing instructions, to the RUN statement. For example,

    	RUN $SETUP;TASKSTRING="TD"

Instructions may be associated with a file by using the INSTRUCTIONS function of the COPYWRITE utility to store the instructions in the disk file header. For example,

	     U *METALOGIC/COPYWRITE Instructions 
                MY/FILENAME SL APPLES=OBJECT/APPLES ON %5\TD

Instructions may be associated with a file by label-equating a Simple Install *INSTALLDATAFILE. If there are ODT commands specified in the *INSTALLDATAFILE, they are converted to Instructions, and stored with the file in the archive. For example,

    	TASK T;
    	T(FILE INSTALLDATAFILE(FILENAME=*INSTALLDATAFILE/SYSTEM/461));
		COPY *SYSTEM/GENERALSUPPORT FROM RELEASE461(PACK)
		TO SETUP(CD,HOSTNAME=LOCAL,LOCKEDFILE)[T];

Instructions may be applied programmatically to a file using the SetInstructions entrypoint exported from the COPYWRITE library.

    	Boolean PROCEDURE
    	SetInstructions(FileName,Instructions,Reason); 
 	Value FileName,Instructions;
 	String FileName,Instructions,Reason;
  	Library CopyWrite;

Instructions, other than those label equated at run time, are permanently associated with either the file in the archive, or the archive codefile.

Option	Summary of options for Creating an Archive
COPY	The files will be extracted from the archive using a COPY statement. Should a file with the same name already exist, it will be overwritten. SW3 may be set when the archive is run to change this to anADD.
ADD	The files will be extracted from the archive using an ADD statement. Should a file with the same name already exist, the archive file will not be copied.
COPY&COMPARE	When the COMPARE option is set, a file will only be extracted from the archive if it is a 'better version' than the one on disk. The archive is a 'better version' if the file does not exist on disk, or if it has a higher CYCLE andVERSION, a later CREATIONTIMESTAMP and a later TIMESTAMP, in that order. It is not a better version if it is identical to the one on disk. This avoids the problem of overwriting library codefiles that are SLed.
; TASKSTRING="<instructions>"	When the TASKSTRING attribute is label-equated to the COPY statement which creates an archive, the instructions it contains are applied to the archive file. Instructions on the archive file are executed after the files have been extracted.SW4 may be used at run time to disable instructions.
TASK T; T(FILE INSTALLDATAFILE (FILENAME= <filename>)); ... ;[T]	An INSTALLDATAFILE may be label equated to a Simple Install INSTALLDATAFILE, using a Task variable. COPYWRITE* constructs a list of filenames from the INSTALLDATAFILE, of all files which have associated ODT* commands, or an Install library. The filenames are given a usercode of . If the COPY* statement specifies a filename (or AS filename) which appears in the list, the associated commands are converted to the Instructions syntax, and are stored in the Archive along with the file, and they are executed when the file is extracted.
;OPTIONS = DEBUG	This option may be used to display diagnostic information, which is normally just annoying.
(CD,HOSTNAME=<hostname>,LOCKEDFILE,...	This combination of attributes, specified on the destination volume, makes COPYWRITE create a self extracting archive
...HOSTNAME=<hostname>, USERCODE='<username>', AUTOUNLOAD=ON, ...	After the archive has been created (and Wrapped or made into a CD Image) it will be transferred to the <hostname> using binary FTP. The user account details are specified in the USERCODE attribute, as described in the WFL Manual.
...SINGLEUNIT, ..	If the SINGLEUNIT attribute is specified as a destination volume attribute, then only a single extraction can occur without the need to RSVP with an OK to an ACCEPT. After the first successful extraction, an RSVP will be required each time the archive is executed. The purpose of this feature is to prevent a subsequent extraction, in a case where this could affect a previously installed product.
...BLOCKSIZE=<integer>, ..	A Block is defined to be the Compiler CodeFile AreaSize of 504 Sectors. The default BLOCKSIZE is the greater of 1 and the number of Blocks in an Area of METALOGIC/ COPYWRITE/ EXTRACTARCHIVE. A BLOCKSIZE of 1 limits the absolute size of an archive to 10000 Areas a 504 Sector Block per Area, and it also creates an Archive with a Segmented Header, which is not loadable during a ColdStart by SYSTEM/LOADER. The BLOCKSIZE attribute can be used to increase the number of Blocks per Area to avoid these limits. A BlockSize of 100 will result in an Archive with an AreaSize of 50400 Sectors (100 * 504 Sectors).
...SCRATCHPOOL=WRAP , ...	After the archive has been created, it is wrapped into a WRAPPEDFILE. This requires theWRAP licensekey from UNISYS.
...SCRATCHPOOL=LMCD , ...	After the archive has been created, it is copied into a Library/Maintenance CD Image.
...FAMILYOWNER=*, ... ...FAMILYOWNER=<name>, ...	Only applicable with SCRATCHPOOL=LMCD. This attribute specifies the usercode under which the archive will be copied into the CD Image.

Extracting the files from the Archive

The files may be extracted from the archive by running the archive codefile.

When running under CANDE, a $ may be necessary, to prevent CANDE appending OBJECT before the archive name. For example in WFL, RUN SETUP, but in CANDE , RUN $SETUP .

These switches may be set, to control the archive extraction,

Switch	Description
SW1	When this switch is set, a list of the files in the archive is displayed, however, no files are extracted from the archive.
SW2	When this switch is set, a confirmation using an AX is required before each file is copied to the destination volume.
SW3	When set, the files are extracted using an ADD statement, so that the archive files will not overwrite any existing files, even if the archive was created using a COPY statement.
SW4	When this switch is set, the instructions are not executed, but are displayed.
SW5	This switch, when set at runtime, sets the same option as the COPY&COMPARE statement, when the archive is created. If the file on disk is the same version or a better version than the file in the archive, the archive file is not copied. The 'best' version is determined by comparing these attributes in the this order, CYCLE, VERSION, CREATIONTIMESTAMP and TIMESTAMP.
SW6	Available.
SW7	This switch when set, prevents a Halt/Load from being done, even though a HALTLOAD instruction has been issued.
SW8	Available.

The files are copied to the family under which the archive is run. This may be changed by label equating a FAMILY task attribute. If there is no family, the files are copied to DISK.

For example, RUN SETUP;FAMILY DISK = DISK ONLY;

A WFL MODIFYstatement may be used to apply a FAMILY task attribute value to the archive.

Reporting on the files in a Self Extracting Archive

The archive may be run with SW1 set.This will produce a report of the names of the files in the directory, however, no files will be extracted. If the archive is run from a terminal, then the report is displayed on the terminal, otherwise the report is DISPLAYed on the ODT.

A report can be obtained using the TT PDT command of SUPERVISOR,

   TT PDT IN <archive name>

The COPYWRITE utility may also be run,

    U *METALOGIC/COPYWRITE PDT CD IMAGE
    <archive name>

Security

An archive created by a PU, is marked as EXECUTABLE, while an archive created by a non PU, is marked as NON-EXECUTABLE.

The archive may be marked as NON-EXECUTABLE using the command,

    MP <archive name> -EXECUTABLE

The archive may be marked as RESTRICTED using the command,

    RESTRICT FILE <archive name>

ONLY A PRIVILEGED USER MAY EXTRACT FILES FROM AN ARCHIVE.

If a non privileged user executes an archive, the directory is displayed, however, no files are extracted.

Instructions

Instructions may be applied to each file in the archive, to the archive codefile itself, extracted from an *INSTALLDATAFILE, and they may also be label equated when the archive is executed.

After a file has been extracted and copied, the file is checked for the presence of instructions. If they are present, then the instructions are executed. Instructions from an *INSTALLDATAFILE are executed first, then those applied to the Disk File Header are executed.

After all the files have been extracted from the archive, the archive codefile is checked for the presence of instructions. If they are present, then the instructions are executed.

After the instructions associated with the archive codefile have been executed, the TASKSTRING of the running archive is checked for the presence of instructions. If they are present, then the instructions are executed.

Syntax:

<instructions> ::=	<statement list>
<statement list> ::=	<statement> \| <statement list> \ <statement>
<statement> ::=	<wfl statement> \| <primitive run statement> \| <accept statement> \| <odt statement> \| <mcs statement> \| <sm statement> \| <to statement> \| <pass statement> \| <recall statement> \| <install statement> \| <enter statement> \| <haltload statement> \| <usercode statement> \| <coms statement>
<wfl statement>::=	BEGIN JOB <wfl job> \| START <wfl start> \| RUN<wfl run> \| AT <remote wfl job> \| PRINT<wfl print>
<primitive run statement>::=	??RUN <filetitle>
<accept statement> ::=	AX <text> \| ACCEPT <text>
<odt statement>::=	<text>
<mcs statement>::=	MCS <filetitle>
<wfl job> ::=	<text>
<wfl start>::=	<text>
<wfl run>::=	<text>
<remote wfl job>::=	<text>
<wfl print>::=	<text>
<text>::=	<text element> \| <text><text element>
<text element> ::=	<EBCDIC character> \| %% \| \\ \| %0 \| %1 \| %2 \| %3 \| %4 \| %5 \| %6 \| %7 \| %8 \| %9 \| %10 \| %11 \| %12
<filetitle>::=	{A-Series File Title or a <text element> which returns a File Title}
<sm statement>::=	SM <mcs identifier> <text>
<to statement>::=	TO <mcs identifier> <text>
<mcs identifier>::=	COMS \| CANDE \| SUPERVISOR \| MARC \| <filetitle>
<pass statement>::=	PASS <window name> <text>
<recall statement>::=	RECALL <filetitle>
<install statement>::=	INSTALL <libobject> ( <libparam> ) IN SL <libname> \| INSTALL <libobject> ( ) IN SL <libname>
<libobject>::=	<name>
<libname>::=	<name>
<libparam>::=	{Any text not including a right parenthesis ')' }
<name>::=	{An ALGOL identifier or a <text element> which returns an identifier }
<enter statement>::=	ENTER <filetitle>
<haltload statement>::=	HALTLOAD
<usercode statement> ::=	USERCODE <name> \| USERCODE "<name>" \| USERCODE .
<coms statement> ::=	COMS <coms command>

Semantics:

A <wfl statement> is passed to CONTROLCARD for execution. See the WFL manual for syntax and semantics.
A <primitive run statement> sets the NAME attribute of a Task variable to the <filetitle>, sets the FAMILYNAME and USERCODE to ".", and then executes anALGOL RUN statement.
An <accept statement> copies the text into an array, and then executes anALGOL ACCEPT statement.
An <odt statement> passes the text to DCKEYIN.
Statements are separated by a backslash.
The maximum size of <instructions> in a Disk File Header is about 4750 bytes of text.
The substitution characters (such as %0) are described below.
The <filetitle> in the <mcs statement> may contain an ON <family name> part, but the title must not exceed 72 characters. If an mcs with the same name (given that the family is ignored, and any (USERCODE) is removed), already exists, it is not created, otherwise *SYSTEM/IDC is run to create theMCS. The name of the report file produced by IDC is displayed.
If *SYSTEM/IDC is not present in the path of the archive codefile, aWAITING ENTRY enters the mix.
Any <text> which does not start with one of the keywords, is taken to be an <odt statement>.
The <sm statement> and the <to statement> send a message to anMCS, but in different ways. If the <sm statement> is used, theMCS must be running, and a <mixno> SM message is sent usingDCKEYIN. If the <to statement> is used, the MCS and DATACOM are started if not already running, and the message is inserted into their intercom queue.
The <pass statement> passes text to a COMS window. It builds aTO COMS PASS <window name> <text> statement.
If passing a message to aMARC window, use aTO MARC <text> statement which creates aTO COMS PASS MARC <text> statement.
The <recall statement> changes the <filename> to be the *SYSTEM/USERDATAFILE. The file must reside on the DL USERDATA.
The <install statement> is usually created from the corresponding elements in an *INSTALLDATAFILE, but may be used to link to any entrypoint which matches theINSTALLSUPPORT entrypoint definition.
Boolean PROCEDURE InstallFunction(Output,Control,Info);% See SimpleInstall @ 13012000
Value Control;
File Output;
Real Control;
Array Info[0];
Library InstallSupport;
The <enter statement> loads the text from the <filetitle> and assumes it contains instruction statements, which are then executed. An Enter file may contain any instruction statements, including an <enter statement>. Beware of creating an infinite loop. An Enter file may be anyFILEKIND, but only the text fields are loaded.
An Enter file with FILESTRUCTURE = STREAM, is converted toEBCDIC if the contents areASCII, and theCR LF are translated to spaces.
An Enter file with FILESTRUCTURE = ALIGNED180, is assumed to beEBCDIC. Leading and trailing blanks are eliminated from each record. If a record starts with a percent sign (%), it is ignored as an instruction record. If a record starts with two percent signs (%%), it is ignored as an instruction record, but the following text is displayed on theODT.
A <haltload statement> schedules a Halt/Load when, and only if, all the files are successfully extracted from the archive. If theAUTORUNNING MCP option is not set, then the archive waits on an AX:OK confirmation before Halt Loading. If AUTORUNNING is set, then a warning message is issued 30 seconds before the Halt/Load, which may provide an opportunity toDS the Archive before the Halt/Load happens. The Halt/Load command can be rendered ineffective usingSW7 (See Switches).
The USERCODE statement will fail unless the archive is marked as TASKING.
The text following the COMS statement is passed to the PA_REQUEST entrypoint of COMS, if the Library Linkage to COMS is successful.

Substitution:

If a backslash (\)is required in the <text>, then enter a double backslash (\\).
If a percent (%) is required in the <text> in a context where it is ambiguous with a substitution (such as %0), enter a double percent (such as %%0).

Symbol	Description
%0	The title of the archive codefile which may include a family name (Myself.NAME).
%1	The family name of the archive codefile.
%2	The filename of the file extracted (no family name).
%3	The family name to which the file was extracted (unless deceived by an IL).
%4	The title of the file extracted, which contains both the filename and the family name (the same as %2 ON %3). When no family name exists, DISK is inserted.
%5	The Halt/Load family name.
%6	The DL LOG family name.
%7	The DL BACKUP family name.
%8	The DL ROOT family name
%9	The HOSTNAME
%10	The GROUPNAME
%11	The USERCODE under which the archive is running
%12	The filename of the file extracted, except that the file usercode is replaced with the usercode under which the archive is running. This gives the filename of the file as if it had been copied to the local usercode environment.

TheDL family substitutions are checked each time the substitution character is encountered, so an instruction which changes aDL will take effect the next time theDL is referenced. For example, an instruction on the first file could setDL ROOT DISK, and thereafter %8 would returnDISK. Note, that if theDL ROOT family is not present, a waiting entry is forked, and DL ROOT is not set.
When the instructions being executed are for the archive file, the archive file is treated as the file being extracted.

Sample Instructions:

No samples.

Creating a ColdStart Self Extracting Archive

A Self Extracting Archive may be used during a COLDSTART. The archive code avoids using any intrinsics requiringGENERALSUPPORT, and when it detects the Halt/Load Reason is 'COLD START ', or thatWFLSUPPORT is unavailable, it avoids using theWFLSUPPORT Library.

ODT Commands are passed directly to theMCP, and do not requireGENERALSUPPORT.

This state exists long enough to install at least GENERALSUPPORT, WFLSUPPORT and PRINTSUPPORT, which are the most critical. They are the most critical because at some point the Archive will require them, or require something which requires them, and if not installed, the Archive is suspended by the MCP, and the Archive is deadlocked.

Given the above, these recommendations are for making a Self Extracting Archive which is going to be used during a ColdStart, assuming a Halt/Load disk calledDISK.

Create a Self Extracting Archive (called RELEASE461 in the examples below), perhaps by decompiling a running system using MetalogicSUPERVISOR, or by using MetalogicFLEX to select files using an*INSTALLDATAFILE and generating aWFL job .
Make sure that theSYSTEM/KEYSFILE, SYSTEM/GENERALSUPPORT, SYSTEM/WFLSUPPORT andSYSTEM/PRINT/= are copied into the Archive first.
Create theCOLDSTART CD usingCOPYWRITE (orLIBRARY/MAINTENANCE), by combining anMCP with the Self Extracting Archive,
COPY *SYSTEM/DELTA/MCP,*RELEASE461 FROM RELEASE461(PACK),
TO COLDSTART(CD,HOSTNAME=LOCAL,CDCOPIES=1)
AfterSYSTEM/LOADER is loaded, these are some typical commands entered during aCOLDSTART,
SYSTEMSERIAL 1234
COLDSTART
LOAD MCP SYSTEM/DELTA/MCP FROM CD 51
OP+AUTORUNNING
STOP
After the MCP has been loaded, and System Initialization has been completed, primitive copy the Archive from the CD,
??COPY RELEASE461 FROM COLDSTART(CD)
Ensure the Archive code file is privileged,
MP RELEASE461 +PU
Execute the Archive,
??RUN RELEASE461
This can bring a system fromCOLDSTART toCANDE very quickly.

Applications

A typical use of a self extracting archive is to package an application and the intelligence needed to install it, into a single distributable file, which the client simply has to execute.
For example, theCOPYWRITE runtime package is released might be a self extracting archive. It extracts the codefiles comprising the COPYWRITE application, SLs the libraries and if necessary creates anMCS in theNIF.
A development test environment which must be refreshed each time a set of tests are to be performed, can be created within a self extracting archive. The test procedures execute the self extracting archive as the first step in the testing process.
A disaster backup system may be bootstrapped from a self extracting archive, after the most primitive MCP environment has been established. This can be combined with the awesome power of Metalogic Supervisor, to completely configure an A-SeriesMCP environment.

Example

COPY (mcp451)symbol/mcp as junk/mcp from mcp451(pack) to fred(cd,hostname=x,lockedfile)

#BOT 06369 (NFT)WFLCODE ON NUCLEUS
#BOT 06370 (NFT)FILE/TRANSFER
#BOT 06371 (NFT)FILE/TRANSFER/SERVICES
#6371 Metalogic CopyWrite Version 45.450.06 was compiled at 15:48:3 on the 20th April 2000 (MCP 45.131.1358)
#6371 (NFT)JUNK/MCP copied
#EOT 06371 (NFT) (NFT)FILE/TRANSFER/SERVICES
#EOT 06370 (NFT) (NFT)FILE/TRANSFER
#EOT 06369 (NFT) (NFT)WFLCODE ON NUCLEUS

(NFT) : DIRECTORY
. FRED : ESPOLCODE CODEVERSION=44.1 VERSION= 45.0450.00006 EXECUTABLE:UNSAFE
ALTERDATE=04/20/2000 16:03:31 CEST AREALENGTH=15120 (504 RECORDS)
AREAS=1195 AREASECTORS=504 ATTMODIFYDATE=04/20/2000 16:03:31 CEST
BACKUPDATE=04/20/2000 16:03:31 CEST BLOCKSIZE=270
BLOCKSTRUCTURE=FIXED COPYDESTDATE=04/20/2000 16:03:31 CEST
COPYSOURCEDATE=04/20/2000 16:03:31 CEST
CREATIONDATE=04/20/2000 16:03:31 CEST CRUNCHED CYCLE=1
EXECUTEDATE=04/20/2000 16:03:31 CEST EXTMODE=EBCDIC
FILELENGTH=18068400 FILEORGANIZATION=NOTRESTRICTED
FILESTRUCTURE=ALIGNED180 FRAMESIZE=48
LASTACCESSDATE=04/20/2000 16:03:31 CEST LASTRECORD=602279
MAXRECSIZE=30 MINRECSIZE=30 READDATE=04/20/2000 16:03:31 CEST
SAVEFACTOR=0 SECURITY=OWNER NFT:RWX, GROUP <none>:NO, OTHER:NO
PRIVATE (I/O) TIMESTAMP=04/20/2000 16:07:57 TOTALSECTORS=602280
NO WARNINGS

r $fred;sw1
#RUNNING 06382
#6382 DISPLAY:Metalogic Self Extracting Archive.
#6382 DISPLAY:Archive FRED created at Site 1215 on MCP 45.131.1358.
<1> (NFT)JUNK/MCP

r $fred
#RUNNING 06383
#6383 DISPLAY:Metalogic Self Extracting Archive.
#6383 DISPLAY:Archive FRED created at Site 1215 on MCP 45.131.1358.
#6383 PK130 (NFT)JUNK/MCP REPLACED ON WORK
#6383 PK130 (NFT)NFTTEMP/JUNK/MCP CHANGED TO (NFT)JUNK/MCP ON WORK
#6383 DISPLAY:(NFT)JUNK/MCP copied on WORK.
#6383 DISPLAY:1 files were extracted to WORK.
#ET=3:28.8 PT=2:27.6 IO=1:15.2