12th July 2002

Opal Interface

These include two new file methods called ZIPFILE and UNZIPFILE; simple progress bar support for SUPERVISOR is also available. The Metalogic OBI (Operations Browser Interface) package supports the new zip technologies. OBI can be accessed from here:

Url http: course2mcp

The syntax and usage of the zip file methods are shown below:

  -- .ZIPFILE - ( <string exp.> -+--------------+-+-----------+-- ) -|
                                 +- , -+- MZIP -+ +- <Specs> -+
                                       +- GZIP -+
                                       +- ZLIB -+

  -- .UNZIPFILE - ( <string exp.> --+--------------+-- ) -------|
                                    +- <DontWait> -+

  <Specs>

   -- , ---+-- HIGH --+------+--------------+-------|
           +-- LOW ---+      +- <DontWait> -+

  <DontWait>

   -- , - DONTWAIT -+---------------+------------|
                    +- = <integer> -+

Both ZIPFILE and UNZIPFILE are methods similar to .READ in that they use dynamic variable references to access a physical file. To create a zip file:

  $ZIP:="(META)BIG/FILE/GZ ON DEV";
  $SOURCE:="(META)BIG/FILE ON DEV";
  $RES:= $$ZIP.ZIPFILE($SOURCE,MZIP,HIGH);
  If MZIPLASTERROR Neq MZIPOK Then
     Show("MZIP error ->",$RES);

Here the calling OPAL will wait until the ZIPFILE operation is complete. If the caller is SUPERVISOR, then the calling slot is marked as 'WAIT ZIP' if interrogated using an EV ? or SLOT command. If the calls fails, the $RES variable is assigned the error message and the MZIPLASTERROR attribute is set to MZIPERROR. Each error message is prefixed by "Err".

The <Specs> modifier allows the caller to specify a compression model identified by HIGH or LOW and a means of tracking progress of any zip operation. HIGH compression yields smaller archives but consumes more CPU; LOW compression is the default.

The optional <Dontwait> specification allows the caller to track the progress of a zip/unzip operation from OPAL scripts executed by SUPERVISOR only, at this time. A new OPAL statement, called ON PROGRESS, is available which is regularly called by the zip routines to return updated progress information. Currently, only one progress attribute is available - MYSELF(PROGRESS). Here is an example:

              $ZIP:="(META)BIG/FILE/GZ ON DEV" 
              $SOURCE:="(META)BIG/FILE ON DEV"
              $RES:= $$ZIP.ZIPFILE($SOURCE,MZIP,HIGH,DONTWAIT);
              If MZIPLASTERROR Neq MZIPOK Then
              Show("MZIP error ->",$RES)
              Else 
              ON PROGRESS DO
              Begin 
              SHOW("Zip progress ",MYSELF(PROGRESS)," %"); 
              End 

By default, SUPERVISOR triggers ON PROGRESS events every second but this may be overridden by assigning an integer value to DONTWAIT:

 $RES:= $$ZIP.ZIPFILE($SOURCE,MZIP,HIGH,DONTWAIT=5)

ZIP and UNZIP Functions

The syntax and usage of the zip string functions are shown below:

              -- ZIP -- ( -- <input string> --+-----------------+-- ) -------| 
                                              +- , -+-- MZIP ---+
                                                    +-- GZIP ---+ 
                                                    +-- ZLIB ---+ 
              
              -- UNZIP -- ( -- <compressed string> -- ) ---------------------| 
              
              

Both ZIP and UNZIP can only be used to compress and decompress a single data stream. For ZIP, either MZIP, GZIP or ZLIB should be specified; MZIP is the default. MZIP is Metalogic's own compression mechanism and is optimised for MCP systems. Files that have been compressed by MZIP cannot currently be unpacked on non-MCP systems.

A ZIP function example:

              $ZIPSTRING:=Repeat("ABCDEF",20000); %12,000 chars 
              If Not $Z:=ZIP($ZIPSTRING,GZIP) Hdis "Err" Then 
                SHOW("Compressed string-> ",Length($ZIPSTRING))
              Else 
                SHOW("Zip Error-> ",$Z)

All ZIP and UNZIP errors are returned as the function result and are prefixed by  "Err". In SUPERVISOR environments, the attribute MZIPLASTERROR returns a non-zero value if the operations fails.

Output files for GZip or ZLib compressions are now EXTMODE=OCTETSTRING.

If the zipped output goes to a file, the original file size in bytes is placed into the ReleaseId attribute in EBCDIC decimal.

If an output procedure is supplied and output is requested to file or Tar, the procedure is called as a progress report. The first call is at 0, and the RDLenF result gives the number of MB before the next call, with a minimum of 1 MB.

Output FileKind is now DCPSYMBOL for compressed data, and if output is not via the Tar procedure, the expanded file is CDATA.

Meta_Zip now checks for input/output file availability and array size. Error messages are now returned in the output array.