Last updated: February 26, 2008
The FSExt service is an external STAF service that provides the following File System EXTension services:
The purpose of the FSExt service is to provide some tools to perform extended file system requests which may be useful in automation environments.
This service requires:
Install the FSExt service by downloading the FSExtV301.zip/tar file from Get STAF Services and extracting its contents to a local directory (e.g. C:\STAF\services or /usr/local/staf/services). The STAFFSExt.jar file is the service jar file needed when registering the FSExt service.
The FSExt service is written in Java and since it is an external service, it must be registered with the SERVICE configuration statement in the STAF configuration file. The syntax is:
SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name> [OPTION <Name[=Value]>]...where:
SERVICE FSExt LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/fsext/STAFFSExt.jar SERVICE FSExt LIBRARY JSTAF EXECUTE C:/STAF/services/fsext/STAFFSExt.jar SERVICE FSExt LIBARRY JSTAF EXECUTE /usr/local/staf/services/fsext/STAFFSExt.jarOr, you can dynamically add the FSEXT service using the SERVICE service's ADD SERVICE request.
The FSEXT service uses no STAF variables.
The FSExt service provides the following requests:
Either captures the data from one file to another or compares two files.
PROCESSFILE [MODE <capture | compare>] FILE1 <File1> FILE2 <File2> [SORT] [SAVEONFAILURE]
FILE1 specifies the file to be used as the source for compares or captures.
FILE2 specifies the file to be used as the destination for compares or captures.
MODE is used to determine whether to compare two files or whether to capture data from one file to another. If capture is specified, data is copied from File1 to File2. If compare is specified, File1 and File2 are compared. The default is to perform a compare operation.
SORT may be specified to indicate that a line-by-line lexicographic sort should be performed on the files before the comparison takes place. This option only has an affect when the compare mode has been specified.
SAVEONFAILURE may be specified to indicate that, if the compare fails, file1 should be saved for later analysis. The file will be saved in the same directory as file2 with the name of file1 appended with an extension of ".fail".
This request requires at least trust level of 3.
All return codes from PROCESSFILE are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".
The result buffer will be empty on return from PROCESSFILE.
PROCESSFILE FILE1 C:/tests/testA/gold.out FILE2 C:/results/testA.out
PROCESSFILE FILE1 C:/tests/testA/gold.out FILE2 C:/results/testA.out SORT SAVEONFAILTURE
PROCESSFILE MODE capture FILE1 C:/tests/testA/results.txt FILE2 C:/results/testA.txt
Compares the contents of a directory against a list of filenames. This command only checks if the specified files exist. It does not do any comparison as to the contents of the files.
COMPAREDIR DIR <Dir> FILE <File> [FILE <File>]... [EXISTS] [ATTEMPTS <Num Attempts> [INTERVAL <Polling Interval]]
DIR specifies the directory to be used in the comparison. This must be a fully qualified directory name.
FILE specifies a file that should be checked. These files must be specified relative to the specified directory. The FILE parameter may be specified one or more times.
EXISTS may be specified to indicate that the request should only check that the specified files exist and should ignore any extraneous files. If this parameter is not specified, the compare will fail if any files exist in the specified directory which were not specified via the FILE parameter(s).
ATTEMPTS may be specified to indicate the number of times that the comparison should be made. This value will default to 1.
INTERVAL may be specified with the ATTEMPTS option to indicate how long, in milliseconds, the service should wait between attempts to compare the directory. This option defaults to 15000 (15 seconds).
This request requires at least trust level of 3.
All return codes from COMPAREDIR are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".
COMPAREDIR DIR C:/tests/testA FILE testA.exe FILE help.txt FILE results/testA.out
COMPAREDIR DIR C:/tests/testA/results FILE testA.out EXISTS
COMPAREDIR DIR C:/tests/testA/results FILE testA.out EXISTS ATTEMPTS 3 INTERVAL 60000
Verifies that a list of strings are either present or not present within a given file. This command will essentially grep the file for each of the given strings. NOTE: This is a case sensitive search by default.
FILECONTAINS FILE <File> STRING <String> [STRING <String>]... [NOT] [IGNORECASE] [SAVEONFAILURE]
FILE specifies the file in which to search. This filename must be fully qualified.
STRING specifies a string that should be used as part of the search criteria. The STRING option may be specified one or more times.
NOT may be specified to indicate that the request should check that none of the strings appear in the file. The default is to check that all of the strings appear in the file.
IGNORECASE may be specified to indicate that a case insensitive search should be performed.
SAVEONFAILURE may be specified to indicate that if the specified search fails a copy of the file should be made, in the same directory, with an extension of ".fail".
This request requires at least trust level of 3.
All return codes from FILECONTAINS are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".
Definition of map class STAF/Service/FSExt/FileContainsNotError | |||
---|---|---|---|
Description: This map class represents information about the string that caused the failure. | |||
Key Name | Display Name | Type | Format / Value |
offset | Byte Offset | <String> | |
string | Found String | <String> | |
Notes:
|
FILECONTAINS FILE C:/results/testA.out STRING Success
FILECONTAINS FILE C:/results/testB.out STRING "PASSES: 50" STRING "FAILS: 0" SAVEONFAILURE
FILECONTAINS FILE C:/results/testC.out NOT STRING Error STRING Failure STRING "Warning: " IGNORECASE
Verifies that a list of strings appear within a single line of a given file. This directive will grep the file and return a successful result only if all of the strings appear in one of the lines of the file. NOTE: This is a case sensitive search by default.
LINECONTAINS FILE <File> STRING <String> [STRING <String>]... [IGNORECASE] [SAVEONFAILURE] [LINENUMBER <Line #>]
FILE specifies the file in which to search. This filename should be fully qualified.
STRING specifies a string that should be used as part of the search criteria. The STRING option may be specified one or more times.
IGNORECASE may be specified to indicate that a case insensitive search should be performed.
SAVEONFAILURE may be specified to indicate that if the specified search fails a copy of the file should be made, in the same directory, with an extension of ".fail".
LINENUMBER may be specified to indicate that the strings must exist on this specific line number in the file. NOTE: Negative line numbers may be used to indicate an offset from the end of the file. For example, -1 would indicate the last line of the file, -2 would be the second to last line, and so on.
This request requires at least trust level of 3.
All return codes from LINECONTAINS are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".
Definition of map class STAF/Service/FSExt/FileContainsNotError | |||
---|---|---|---|
Description: This map class represents information about the string that caused the failure. | |||
Key Name | Display Name | Type | Format / Value |
lineNumber | Line Number | <String> | |
line | Line | <String> |
LINECONTAINS FILE C:/results/testA.out STRING "Pass: 15" STRING "Fail: 0"
Output: If the request is submitted from the command line and the strings were found in line 12 of the file, the result, in default format, could look like:
Line Number: 12 Line : Testcase Totals: Tests: 3, Pass: 15, Fail: 0
FILECONTAINS FILE C:/results/testB.out STRING "Success!!!" IGNORECASE LINENUMBER -1
Output: If the request is submitted from the command line and the string was found in the last line of the file (which contained 54 lines), the result, in default format, could look like:
Line Number: 54 Line : success!!!
Copies a file, substituting any STAF variables in the file with their respective values. Variables are signified by the syntax %{staf_variable}% (ex: %{STAF/Config/BootDrive}% ). This service reads the file, replaces any variables and then calls the FS service to perform the copy.
SUBSTITUTE FILE <File> [TOFILE <To File>] [TOMACHINE <To Machine>] [FAILIFNEW | FAILIFEXISTS]
FILE specifies the file to use as the source. This filename must be fully qualified.
TOFILE specifies the destination for the copy. If this is the same as the source (and TOMACHINE is not specified) then the source file will be overwritten with the modified file. This filename must be fully qualified. The default value is the same as the value for FILE. NOTE: If neither TOFILE nor TOMACHINE are specified, the source file will be overwritten with the modified file.
TOMACHINE specifies the destination machine for the copy. The default is the local machine. NOTE: If neither TOMACHINE nor TOFILE are specified, the source file will be overwritten with the modified file on the local machine.
FAILIFNEW indicates that the copy should fail if the destination file does not exist.
FAILIFEXISTS indicates that the copy should fail if the destination file exists.
This request requires at least trust level of 4.
All return codes from SUBSTITUTE are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".
The result buffer will be empty upon successful completion of this command and may contain additional information if the command fails.
SUBSTITUTE FILE C:/tests/testA.txt
SUBSTITUTE FILE C:/tests/testA.txt TOFILE D:/testA/testA.bat TOMACHINE client1 FAILIFEXISTS
Blocks until a file exists or the timeout value is reached. This command will check to see if a file exists. If it does not, it will wait for a specified interval and try again. This will repeat until the file exists or until the timeout value is reached. NOTE: Use of the NOT option also allows to check that a file does not exist.
WAITFORFILE FILE <File> [TIMEOUT <Timeout>] [INTERVAL <Interval>] [NOT]
FILE specifies the file to check. This filename must be fully qualified.
TIMEOUT specifies how long FSEXT should check for the file before failing. This time is expressed in milliseconds. The default value is to wait indefinitely.
INTERVAL specifies how long, in milliseconds, the service should wait before performing the next check for the file. The default is 15000 (15 seconds).
NOT indicates that the request should wait for a file NOT to exist. This may be useful in checking that a file was successfully. deleted.
This request requires at least trust level of 3.
All return codes from WAITFORFILE are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".
The result buffer will be empty upon successful completion of this command. If the check failed, the result buffer will contain the name of the file.
WAITFORFILE FILE C:/results/testA.out
WAITFORFILE FILE C:/results/testB.out TIMEOUT 300000 INTERVAL 60000
WAITFORFILE NOT FILE C:/tests/testA.tmp TIMEOUT 60000
In addition to the common STAF return codes, the following FSEXT return codes are defined:
Table 1. FSEXT Service Return Codes
Error Code | Meaning | Comment |
---|---|---|
4001 | File Comparison Failed | The file comparison failed. |
4002 | Not A Directory | The value specified for the DIR parameter is not a directory. |
4003 | File Not Found | The specified file was not found on the file system. |
4004 | File Exists | The specified file exists. (The NOT parameter was specified.) |
4005 | Extraneous Files Found | Extraneous files were found in the specified directory. |
4006 | String(s) Not Found | The specified String(s) were not found. |
4007 | String(s) Found | The specified String(s) were found. (The NOT parameter was specified.) |
4008 | Line Number Does Not Exist | The line number specified by the LINENUMBER parameter does not exist in the file. |
4100 | Java IOError | A Java IOError occurred during command execution. Check the result buffer for more information. |