fssrv.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          : FSSrv SCRIPT
.*  Descriptive Name   : Software Test Automation Framework FS Service
.*  Detail:
.*
.*     This file describes the STAF FS (File System) Service.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.file system service
:ih1.services
:i2.file system service
:h2 id=fssrv.File System (FS) Service
:h3.Description
:p.The File System service, called FS, allows you to interface with the file
system on STAF Clients.  It provides the following commands.
:ul compact.
:li.COPY FILE - Allows you to copy files from and to the machine
:li.COPY DIRECTORY - Allows you to copy entire directories (and its
subdirectories if needed)
:li.GET FILE - Retrieves the contents of a file
:li.GET ENTRY - Retrieves an attribute of a file system entry
:li.QUERY - Retrieves the various attributes of file system entry
:li.LIST DIRECTORY - Lists the contents of a directory
:li.LIST COPYREQUESTS - Lists the copy requests in progress
:li.LIST SETTINGS - Lists the operational settings for the File System
service
:li.CREATE - Creates a directory
:li.DELETE - Deletes a file system entry
:li.SET - Changes operational settings for the File System service
:li.&help.
:eul.
:p.In the descriptions of these commands, three different options are used to
refer to objects in the file system.  :xph.FILE:exph. is used when the object in
question must be a file.  :xph.DIRECTORY:exph. is used when the object in
question must be a directory.  :xph.ENTRY:exph. is used when the object in
question may be any object in the file system.
:p.Some of these commands allow match patterns to be specified.  These patterns
recognize two special characters, '*' and '?'.  '*' matches an string of
characters (including an empty string).  '?' matches any single character (the
empty string does not match).
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.COPY
:i3.file system service
:h3.COPY FILE
:p.COPY FILE allows you to copy files between machines, as well as locally.

:h4.Notes:
:ol compact.
:li.A file copied via the FS service does not retain its system or extended attributes.
:li.The FS service supports copying files whose size is less than 4 GB on most
platforms, assuming the operating system supports the creation of large files, that is,
files larger than 2 GB.
:eol.

:h4.Syntax
:xmp.
COPY FILE <FileName> &lbrk.TOFILE <Name> | TODIRECTORY <Name>&rbrk. &lbrk.TOMACHINE <Machine>&rbrk.
     &lbrk.TEXT &lbrk.FORMAT <Format>&rbrk.&rbrk. &lbrk.FAILIFEXISTS | FAILIFNEW&rbrk.
:exmp.
:p.:xph.FILE:exph. specifies the name of the file to copy. &varres.
:p.:xph.TOFILE:exph. specifies the name of the file to create.
If neither :xph.TOFILE:exph. nor :xph.TODIRECTORY:exph. is specified, this
defaults to the same, unresolved, name as specified in :xph.FILE:exph..
&varres. These variables will be resolved on the target machine.
:p.:xph.TODIRECTORY:exph. specifies the name of the directory to copy the file to.
The name of the "to file" will be the same as specified in :xph.FILE:exph..
This directory must already exist on the target machine.
&varres. These variables will be resolved on the target machine.
:p.:xph.TOMACHINE:exph. specifies the machine to copy the file to.  This
defaults to the machine which originated the request.
Specifying:xph. local :exph.indicates to copy the file to the same
machine that the file is being copied from.
Note that specifying:xph. local :exph.instead of the from machine's host name can
significantly improve performance, especially if your TCP network performance
is slow.  This is because:xph. local :exph.(or:xph. local://local:exph.) indicates
to use the local network interface versus specifying a TCP host name or IP address
indicates to use the TCP network interface.  &varres.
:p.:xph.TEXT:exph. specifies to convert line-ending characters in the file being
copied as specified via the :xph.FORMAT:exph. option and to perform codepage conversion.
This option should only be specified for a text file, not a binary file.
:p.:xph.FORMAT:exph. specifies the end-of-line character(s) to use.  &varres.
See :hdref refid=fsgetfile. for more information on available formats.
.*:p.:xph.CONVERT:exph. specifies to perform codepage conversion.  Note that
.*specifying this option decreases performance for the copy request.
:p.:xph.FAILIFEXISTS:exph. specifies that the copy should fail if
:xph.TOFILE:exph. already exists.  The default is to replace the file if it
exists.
:p.:xph.FAILIFNEW:exph. specifies that the copy should fail if :xph.TOFILE:exph.
does not already exist.  The default is to create the file if it does not
exist.
:h4.Security
There can be up to three machines involved in a COPY FILE request
(and any of these machines can be the same machine):
:ol compact.
:li.:xph.orgMachine:exph. - The machine that submitted (i.e. originated) the
COPY FILE request
:li.:xph.sourceMachine:exph. - The machine where the file to be copied resides
(this is the machine to which you submitted the COPY FILE request)
:li.:xph.toMachine:exph. - The machine where the file will be copied to
:eol.
:p.&seclvl. 4 as follows:
:ul compact.
:li.The:xph. sourceMachine :exph.must give at least trust level 4 to the:xph. orgMachine:exph..
:li.The:xph. toMachine :exph.must give at least trust level 4 to the:xph. sourceMachine:exph..
:li.The:xph. toMachine :exph.must give at least trust level 4 to the:xph. orgMachine:exph..
:eul.
:p.
An exception to these trust requirements is if the:xph. orgMachine :exph.is the same
as the:xph. toMachine :exph.and the:xph. STRICTFSCOPYTRUST :exph.operational setting
is disabled (which it is by default), then the:xph. toMachine :exph.does not have to
give trust level 4 to the:xph. sourceMachine:exph..  See :hdref refid=opparms. for
more information on the:xph. STRICTFSCOPYTRUST :exph.operational parameter.

:h4.Return Codes
:p.All return codes from COPY FILE are documented in :hdref refid=retcode..
:h4.Results
:p.The result buffer will contain no data on return from a COPY FILE command.
:h4.Examples
:p.In the following examples, assume the command is being submitted locally from
machine TestSrv1.
:p.
:ul.
:li.:hp2.Goal::ehp2. Copy file c:\testcase\tc1.cmd from machine TestSrv1 to file
c:\testcase\tc1.cmd on machine Client1
:p.
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE c:\testcase\tc1.cmd TOMACHINE Client1:exph.
:p.
:li.:hp2.Goal::ehp2. Copy file c:\testcase\tc1.cmd from machine TestSrv1 to file
d:\WebTests\webtc1.cmd on machine Client1.  Don't overwrite the file if it
exists.
.br
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE c:\testcase\tc1.cmd TOFILE d:\WebTests\webtc1.cmd TOMACHINE Client1 FAILIFEXISTS:exph.
:p.
:li.:hp2.Goal::ehp2. Copy text file test1.txt (in the directory specified by STAF
variable TestcaseDir) from machine TestSrv1 to file test1.txt (in the
directory specified by STAF variable TestcaseDir) on machine Client1.
Convert any line-ending characters in the file to those appropriate for
machine Client1, if machine Client1 has a different platform (e.g. Unix)
than machine TestSrv1 (e.g. Windows).
:p.
:hp2.Syntax::ehp2.&nbsp; Note that both of these :xph.COPY FILE:exph. examples are equivalent.
:xmp.
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT FORMAT Native
:exmp.
:p.
:li.:hp2.Goal::ehp2. Copy text file c:\tc\test1.txt from machine TestSrv1
to file c:\tc\test1.txt on machine Client1.  Convert any line-ending
characters in the file to a space.
:p.
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE c:\tc\test1.txt TOMACHINE Client1 TEXT FORMAT " ":exph.
:eul.
:p.
In the following examples, assume the command is being submitted to machine
Client1 from machine TestSrv1.
:p.
:ul.
:li.:hp2.Goal::ehp2. Retrieve file d:\WebTests\Logs\WebTC1.log from Client1 and store
it in directory f:\Logs on machine TestSrv1.
:p.
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE f:\Logs\WebTC1.log :exph.
:p.
:li.:hp2.Goal::ehp2. Copy file d:\WebTests\Logs\WebTC1.log from Client1 to server
LogSrv in directory h:\Logs.
:p.
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE d:\WebTests\Logs\WebTC1.log TODIRECTORY h:\Logs TOMACHINE LogSrv:exph.
:p.
:li.:hp2.Goal::ehp2. Copy file d:\WebTests\Logs\WebTC1.log from Client1 to file c:\temp\tc1.log
on machine Client1.
:p.
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE c:\temp\tc1.log TOMACHINE local:exph.
:p.
:li.:hp2.Goal::ehp2. Copy the startup.cmd on the boot drive of Client1 to the boot
drive of TestSrv1.  Convert any line-ending characters of the text file as
needed.
:p.
:hp2.Syntax::ehp2.&nbsp; :xph.COPY FILE {STAF/Config/BootDrive}\startup.cmd TEXT:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.COPY DIRECTORY
:i3.file system service
:h3.COPY DIRECTORY 
:p.COPY DIRECTORY allows you to copy entire directories (including subdirectories
if needed) between machines, as well as locally.

:h4.Notes:
:ol compact.
:li.A file copied via the FS service does not retain its system or extended attributes.
:li.The types of entries supported by a COPY DIRECTORY request are files and directories.
:li.The FS service supports copying files whose size is less than 4 GB on most
platforms, assuming the operating system supports the creation of large files, that is,
files larger than 2 GB.
:eol.

:h4.Syntax
:xmp.
COPY DIRECTORY <Name> &lbrk.TODIRECTORY <Name>&rbrk. &lbrk.TOMACHINE <Machine>&rbrk.
     &lbrk.NAME <Pattern>&rbrk. &lbrk.EXT <Pattern>&rbrk. &lbrk.CASESENSITIVE | CASEINSENSITIVE&rbrk.
     &lbrk.TEXTEXT <Pattern>... &lbrk.FORMAT <Format>&rbrk.&rbrk.
     &lbrk.RECURSE &lbrk.KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES&rbrk.&rbrk.
     &lbrk.IGNOREERRORS&rbrk. &lbrk.FAILIFEXISTS | FAILIFNEW&rbrk.
:exmp.
:p.:xph.DIRECTORY:exph. specifies the name of the source directory to copy. &varres.
:p.:xph.TODIRECTORY:exph. specifies the name of the destination directory.  This defaults
to the same, unresolved, name as specified in :xph.DIRECTORY:exph.. &varres.  These
variables will be resolved on the target machine.
:p.:xph.TOMACHINE:exph. specifies the machine to copy the directory and its contents to.
This defaults to the machine which originated the request.
Specifying :xph.local:exph. indicates to copy the directory and its contents to the same
machine that the directory is being copied from.
Note that specifying:xph. local :exph.instead of the from machine's host name can
significantly improve performance, especially if your TCP network performance
is slow.  This is because:xph. local :exph.(or:xph. local://local:exph.) indicates
to use the local network interface versus specifying a TCP host name or IP address
indicates to use the TCP network interface.  &varres.
:p.:xph.NAME:exph. specifies a pattern used to match the name of files in the specified
directory (and files in its subdirectories, if :xph.RECURSE:exph. is specified).
Only the files whose names match this pattern will be copied.
Match patterns may be specified using special characters '*' and/or '?'.
The default pattern is "*".  &varres.
:p.:xph.EXT:exph. specifies a pattern used to match the extension of files in the specified
directory (and files in its subdirectories, if :xph.RECURSE:exph. is specified).
Only the files whose extensions match this pattern will be copied.
Match patterns may be specified using special characters '*' and/or '?'.
The default pattern is "*".  &varres.
:note.The COPY/LIST DIRECTORY commands recognize the "name" (:xph.NAME:exph.)
portion of a filename as the character(s) that preceed a period (or the entire
filename if it does not include a period) and the "extension" (:xph.EXT:exph.)
portion of a filename are character(s) that follow a period.
For example, for filename myfile.txt the "name" portion is "myfile" and
the "extension" portion is "txt".  To match filenames whose name begins
with "my" and whose extension is "txt", you could specify options
:xph.NAME my* EXT txt:exph..
:p.:xph.CASESENSITIVE:exph. specifies that the patterns specified by :xph.NAME:exph.,
:xph.EXT:exph., and :xph.TEXTEXT:exph. are to be matched in a case sensitive manner.
:p.:xph.CASEINSENSITIVE:exph. specifies that the patterns specified by :xph.NAME:exph.,
:xph.EXT:exph., and :xph.TEXTEXT:exph. are to be matched in a case insensitive manner.
:note.If neither :xph.CASESENSITIVE:exph. nor :xph.CASEINSENSITIVE:exph. is
specified, the default is determined by the operating system -- unix systems
default to :xph.CASESENSITIVE:exph., all others default to :xph.CASEINSENSITIVE:exph..
Options :xph.CASESENSITIVE:exph. and :xph.CASEINSENSITIVE:exph. only have an effect if
you also specify a pattern to match using at least one of the following options:
:xph.NAME:exph., :xph.EXT:exph., or :xph.TEXTEXT:exph..
:p.:xph.TEXTEXT:exph. specifies a pattern used to match the extension of text files being 
copied.  The files whose extensions match this pattern should contain text, not binary
data.  The line-ending characters in the files being copied whose extensions match
this pattern will be converted as specified via the :xph.FORMAT:exph. option and
codepage conversion will be performed.
Multiple :xph.TEXTEXT:exph. patterns are handled as an "or" condition.
Match patterns may be specified using special characters '*' and/or '?'.  &varres.
:p.:xph.FORMAT:exph. specifies the end-of-line character(s) to use.  &varres.
See :hdref refid=fsgetfile. for more information on available formats.
.*:p.:xph.CONVERT:exph. specifies to perform codepage conversion.  Note that specifying
.*this option decreases performance for the copy request.
:p.:xph.RECURSE:exph. specifies that the subdirectories in :xph.DIRECTORY:exph. will be
recursively copied.
:p.:xph.KEEPEMPTYDIRECTORIES:exph. specifies that the empty directories are also to be
created in the :xph.TODIRECTORY:exph. on the target.  The default behavior is to prune
the empty directories while copying files.
:p.:xph.ONLYDIRECTORIES:exph. specifies that the directory (empty diretoreis and no files
copied) structure is to be created in the :xph.TODIRECTORY:exph. on the target machine.
Using the :xph.NAME:exph., :xph.EXT:exph., :xph.CASESENSITIVE:exph. and
:xph.CASEINSENSITIVE:exph. options with the :xph.ONLYDIRECTORIES:exph. option will be
ignored as no files will be copied.
:p.:xph.IGNOREERRORS:exph. specifies that errors encountered copying entries should not
be returned.  By default, all errors encountered while copying entries will be returned
in the result buffer.
:p.:xph.FAILIFEXISTS:exph. specifies that the copy should fail if
:xph.TODIRECTORY:exph. already exists.  The default is to copy over the directory contents
if it exists.
:p.:xph.FAILIFNEW:exph. specifies that the copy should fail if :xph.TODIRECTORY:exph.
does not already exist.  The default is to create the directory if it does not exist.

:h4.Security
There can be up to three machines involved in a COPY DIRECTORY request
(and any of these machines can be the same machine):
:ol compact.
:li.:xph.orgMachine:exph. - The machine that submitted (i.e. originated) the
COPY DIRECTORY request
:li.:xph.sourceMachine:exph. - The machine where the directory to be copied resides
(this is the machine to which you submitted the COPY DIRECTORY request)
:li.:xph.toMachine:exph. - The machine where the directory will be copied to
:eol.
:p.&seclvl. 4 as follows:
:ul compact.
:li.The:xph. sourceMachine :exph.must give at least trust level 4 to the:xph. orgMachine:exph..
:li.The:xph. toMachine :exph.must give at least trust level 4 to the:xph. sourceMachine:exph..
:li.The:xph. toMachine :exph.must give at least trust level 4 to the:xph. orgMachine:exph..
:eul.
:p.
An exception to these trust requirements is if the:xph. orgMachine :exph.is the same
as the:xph. toMachine :exph.and the:xph. STRICTFSCOPYTRUST :exph.operational setting
is disabled (which it is by default), then the:xph. toMachine :exph.does not have to
give trust level 4 to the:xph. sourceMachine:exph..  See :hdref refid=opparms. for
more information on the:xph. STRICTFSCOPYTRUST :exph.operational parameter.

:h4.Return Codes
:p.All return codes from COPY DIRECTORY are documented in :hdref refid=retcode..
:h4.Results
:p.
:ul.
:li.On successful return, the result buffer will be empty.
:p.
:li.If errors were encountered copying entries and :xph.IGNOREERRORS:exph.
was not specified, the result buffer will contain a
marshalled :xph.<List> of <Map&colon.STAF/Service/FS/ErrorInfo>:exph. representing
a list of error information about the entries that were not successfully copied.
The map is defined as follows: 
:table id='fsErrorInfoTable' cols='* * * *'.
:tcap.Definition of map class STAF/Service/FS/ErrorInfo
:tnote text='Description'.This map class represents error information for an entry
in a directory.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.name
:c.Name
:c.&stringObj.
:c.
:row.
:c.rc
:c.RC
:c.&stringObj.
:c.
:row.
:c.osRC
:c.OS RC
:c.&stringObj. | &noneObj.
:c.
:tnote text='Notes'.
:ol compact.
:li.The "Name" value will be the full path name of the entry that was not
copied successfully.
:li.The "RC" value will be the STAF return code for the copy request error.
:li.The "OS RC" value will be the operating system return code, if the STAF
return code indicated a base operating system error occurred (i.e. if RC == 10),
otherwise it will be &noneObj..
:eol.
:etnote.
:etable.
:p.
For example, if a copy directory request is submitted from the command line,
and two errors occurred during the copy, the result, in table format, could look like:
:xmp.
Name                RC OS RC
------------------- -- ------
c:\tmp\project.htm  17 <None>