zipsrv.script

Software Testing Automation Framework (STAF)的开发代码

.***************************************************************************
.* Software Testing Automation Framework (STAF)
.* (C) Copyright IBM Corp. 2001
.*
.* This software is licensed under the Common Public License (CPL) V1.0.
.****************************************************************************

.*************************-START-OF-PROLOG-****************************
.*
.*  File Name       : ZipSrv SCRIPT
.*  Descriptive Name: Software Test Automation Framework
.*  Detail          : This file describes the STAF Zip Service
.*
.**************************-END-OF-PROLOG-*****************************
:i1.zip service
:ih1.services
:i2.zip service
:h2 id=zipsrv.Zip Service
:h3.Description
The Zip service is an external STAF service that provides the following
functions:
:ul compact.
:li.ADD (aka ZIP ADD) - Add a file or directory into a ZIP archive
:li.UNZIP - Extract files from ZIP archive
:li.LIST - List content of ZIP archive
:li.DELETE - Delete files from ZIP archive
:li.&help.
:eul.
:p.The purpose of the Zip service is to allow a test case to easily work with Zip archives.
:p.By using of Zlib compression library, the Zip service can create, extract, delete and 
manage PKZip, WinZip and Jar compatible archives.
:p.The Zip service supports the following features: create / extract PKZip,
WinZip, and Jar compatible archives; save / restore owner, group and permission information
on files and directories; delete file(s) from an Zip archive; list content of an
Zip archive, append file / directory to an existing Zip archive, etc.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.zip service
:h3.Registration
The Zip service is an external service and must be registered with the SERVICE
configuration statement. The syntax is:
:xmp.
SERVICE :xph.<Name>:exph. LIBRARY STAFZip
:exmp.
:p.:xph.<Name>:exph. is the name by which the Zip service will be known on this
machine.  The recommended name of the Zip service is "ZIP".
:h4.Example
:xmp.
service ZIP library STAFZip
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.ADD (aka ZIP ADD)
:i3.zip service
:h3.ADD (aka ZIP ADD)
Adds a file or directory into a Zip archive. If the Zip archive does not exist, 
it will create it and add the file or directory to it.  If the Zip archive already 
exists, it will add the file or directory to it.
:h4.Syntax
:xmp.
ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> &lbrk.RECURSE&rbrk. >
    &lbrk.RELATIVETO <Directory>&rbrk.
:exmp.    
or
:xmp.
ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> &lbrk.RECURSE&rbrk. >
    &lbrk.RELATIVETO <Directory>&rbrk.
:exmp.

An :xph.ADD:exph. request is equivalent to a :xph.ZIP ADD:exph. request.
An :xph.ADD:exph. request is preferred.  A :xph.ZIP ADD:exph. request is deprecated
and will generate a trace message with a Deprecated tracepoint.
:p.:xph.ZIPFILE:exph. contains the fully qualified ZIP archive name.
:p.:xph.FILE:exph. contains the fully qualified file name you want to add into
the ZIP archive.
:p.:xph.DIRECTORY:exph. contains the fully qualified directory name you want to
add info the ZIP archive.
:p.:xph.RELATIVETO:exph. contains the prefix to be excluded from the fully
qualified file name or directory name that is to be added into the ZIP archive.
:p.:xph.RECURSE:exph. indicates that the all the files and subdirectories in the
given directory will be added recursively.
:h4.Security
:p.&seclvl. 4.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
Zip also returns codes documented in :hdref refid=ziperr..
:h4.Results
:p.On a successful return, the result buffer will contain no data on return from 
a ZIP command.
:h4.Examples
:ul.
:li.:hp2.Goal::ehp2. Add file C:/file.txt to Zip archive D:/myzip.zip.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.ADD ZIPFILE D:/myzip.zip FILE C:/file.txt:exph.
:p.
:li.:hp2.Goal::ehp2. Add directory /opt/mydir to Zip archive, relative to directory /opt.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RELATIVETO /opt:exph.
:p.
:li.:hp2.Goal::ehp2. Add directory /opt/mydir and all its subdirectories and files to Zip archive, 
relative to directory /opt.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RECURSE RELATIVETO /opt:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.UNZIP
:i3.zip service
:h3 id=unzip.UNZIP
:p.Extract files from a Zip archive to a specified directory.
:h4.Syntax
:xmp.
UNZIP  ZIPFILE <Name> TODIRECTORY <Name>
       &lbrk.FILE <Name>&rbrk.... &lbrk.RESTOREPERMISSION&rbrk. &lbrk.REPLACE&rbrk.
:exmp.
:p.:xph.ZIPFILE:exph. contains the fully qualified ZIP archive name.
:p.:xph.TODIRECTORY:exph. contains the fully qualified output directory name.
:p.:xph.FILE:exph. contains the fully qualified file name to be unzipped.
:p.:xph.RESTOREPERMISSION:exph. indicates that the owner, group and permission
attributes of the file will be restored.
:p.:xph.REPLACE:exph. indicates that the file will be over written if it already
exists in the specified directory.

:h4.Security
:p.&seclvl. 4.

:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
UNZIP also returns codes documented in :hdref refid=ziperr..

:h4.Results
:p.On a successful return, the result buffer will contain no data on return from a UNZIP command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Unzip an archive myzip.zip to folder D:/mydata
:p.:hp2.Syntax::ehp2.&nbsp; :xph.UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY D:/mydata/:exph.
:p.
:li.:hp2.Goal::ehp2. Unzip the file myjava/Hello.java from myzip.zip to
folder /usr/lpp/mydata and restore permission, replace existing file if there is
any:
:p.:hp2.Syntax::ehp2.&nbsp; :xph.UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY /usr/lpp/mydata/FILE myjava/Hello.java RESTOREPERMISSION REPLACE:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.LIST
:i3.zip service
:h3.LIST
List content of a ZIP archive.
:h4.Syntax
:xmp.
LIST ZIPFILE <Name>
:exmp.
:p.:xph.ZIPFILE:exph. contains the fully qualified ZIP archive name.
:h4.Security
:p.&seclvl. 3.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
LIST also returns codes documented in :hdref refid=ziperr.
:h4.Results
:p.On successful return, the result buffer will contain a marshalled
:xph.<List> of <Map&colon.STAF/Service/Zip/ZipInfo>:exph. representing
content of the Zip archive. The map is defined as follows: 
:table cols='* * * 3*'.
:tcap.Definition of map class STAF/Service/Zip/ZipInfo
:tnote text='Description'.This map class represents an entry in Zip archive.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.length
:c.Length
:c.&stringObj.
:c.
:row.
:c.method
:c.Method
:c.&stringObj.
:c.
:row.
:c.size
:c.Size
:c.&stringObj.
:c.
:row.
:c.ratio
:c.Ratio
:c.&stringObj.
:c.
:row.
:c.date
:c.Date
:c.&stringObj.
:c.
:row.
:c.time
:c.Time
:c.&stringObj.
:c.
:row.
:c.crc-32
:c.CRC-32
:c.&stringObj.
:c.
:row.
:c.name
:c.Name
:c.&stringObj.
:c.
:tnote text='Notes'.
:ol compact.
:li.The "Length" value is the uncompressed size of the file.
:li.The "Method" value is compression method, often in the
format of :xph.<Compression Method>&colon.<Compression level>:exph.
used to compress the file. For example "Defl&colon.X", "Defl" stands for "Deflated", 
"X" stands for "Maximum compression". Compression level can also contain the following
values: "N" stands for "Normal compression", "F" stands for "Fast and Super fast 
compression". Compression method can also contain the following values: "Stored" stands
for "No compression", "Unkn." stands for "Unknown compression method".
:li.The "Size" value is the compressed size of the file.
:li.The "Ratio" value is the compression ratio of the file.
:li.The "Date" value is the date stamp of the original file.
:li.The "Time" value is the time stamp of the original file.
:li.The "CRC-32" value is the CRC-32 value of the file.
:li.The "Name" value is the relative name of the file.
:eol.
:etnote.
:etable.
:p.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Show me the content of a ZIP archive.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.LIST ZIPFILE /usr/local/staf/services/STAXV300.zip:exph.
:p.:hp2.Results::ehp2. If the request is submitted from the
command line, the result, in table format, could look like:
:xmp.
Length  Method Size    Ratio Date     Time  CRC-32   Name
------- ------ ------- ----- -------- ----- -------- ------------------------
  30745 Defl&colon.N    9575  31%  04-02-04 11:16 cfd0aacb History
  27227 Defl&colon.N   24653  90%  04-02-04 11:16 c03ffb2c STAFEvent.jar
2566524 Defl&colon.N 2501266  97%  04-02-04 11:16 e1f6f392 STAX.jar
 185037 Defl&colon.N  172931  93%  04-02-04 11:16 51b7700d STAXMon.jar
      0 Stored       0   0%  04-02-04 11:16 00000000 libraries/
  58695 Defl&colon.N   11009  18%  04-02-04 11:16 0142b502 libraries/STAXUtil.html
  82953 Defl&colon.N   15887  19%  04-02-04 11:16 349eee04 libraries/STAXUtil.xml
   2453 Defl&colon.N    1082  44%  04-02-04 11:16 a98db290 readme.1st
      0 Stored       0   0%  04-02-04 11:16 00000000 samples/
   5274 Defl&colon.N     826  15%  04-02-04 11:16 277d4fb7 samples/FunctionList.xsl
  11140 Defl&colon.N    2959  26%  04-02-04 11:16 8584d238 samples/sample1.xml
 764931 Defl&colon.N  512404  66%  04-02-04 11:16 8165dd0c staxug.pdf
:exmp.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.DELETE
:i3.zip service
:h3.DELETE
Delete files from ZIP archive.
:h4.Syntax
:xmp.
DELETE ZIPFILE <Name> FILE <Name> &lbrk.FILE <Name>&rbrk.... CONFIRM
:exmp.
:p.:xph.ZIPFILE:exph. contains the fully qualified ZIP archive name.
:p.:xph.FILE:exph. contains the fully qualified file name to be deleted.
:p.:xph.CONFIRM:exph. confirms you really want to delete the file from zip
archive.
:h4.Security
:p.&seclvl. 4.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
Delete also returns codes documented in :hdref refid=ziperr..
:h4.Results
:p.On a successful return, the result buffer will contain no data on return from a DELETE command.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Delete file myjava/Hello.java from Zip archive D:/myzip.zip.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.DELETE ZIPFILE D:/myzip.zip FILE myjava/Hello.java CONFIRM:exph.
:p.
:li.:hp2.Goal::ehp2. Delete file myjava/Hello.java and bin/run from Zip archive /opt/myzip.zip.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.DELETE ZIPFILE /opt/myzip.zip FILE myjava/Hello.java FILE bin/run CONFIRM:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.error codes
:i2.zip service
:h3 id=ziperr.Zip Error Code Reference
:p.In addition to the common STAF return codes (see :hdref refid=retcode. for
additional information), the following Zip return codes are defined:
:table id     = ziperr
       headhi = 3
       frame  = box
       cols   = '* 2* 4*'
       align  = 'c l l'.
:tcap.Zip Service Return Codes
:thd.
:c.Error Code
:c.Meaning
:c.Comment
:ethd.
:row.
:c.:hp2.4001:ehp2.
:c.General zip error
:c.An general error occured, additional error message can be found in result
buffer.
:row.
:c.:hp2.4002:ehp2.
:c.Not enough memory
:c.There is not enough memory in the system.
:row.
:c.:hp2.4003:ehp2.
:c.Change file size error: <file>
:c.Error changing the file size.
:row.
:c.:hp2.4004:ehp2.
:c.Error creating directory: <dir>
:c.Error creating directory in the file system.
:row.
:c.:hp2.4005:ehp2.
:c.Invalid zip file: <file>
:c.Invalid zip file format.
:row.
:c.:hp2.4006:ehp2.
:c.Bad CRC
:c.Bad CRC in the zip archive.
:row.
:c.:hp2.4007:ehp2.
:c.Invalid owner group
:c.Invalid owner / group on the system when restore permission.
:row.
:c.:hp2.4008:ehp2.
:c.Invalid file mode
:c.Invalid file mode.
:etable.