Version 1.2.3
Last updated: February 20, 2004
SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name>
<Service Name> is the name by which the FSEXT service will be known on this machine.
<Service Jar File Name> is the fully-qualified name of the STAFFSExt.jar file.
SERVICE FSExt LIBRARY JSTAF EXECUTE {STAF/Confg/STAFRoot}/services/STAFFSExt.jar
SERVICE FSExt LIBRARY JSTAF EXECUTE C:/STAF/services/STAFFSExt.jar
SERVICE FSExt LIBARRY JSTAF EXECUTE /uar/local/staf/services/STAFFSExt.jar
Or, you can dynamically add the FSEXT service using the SERVICE service's ADD SERVICE
request.
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.
The optional parameter 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.
The optional parameter 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.
The optional parameter 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".
Minimum security level of 3 required to do a processfile.
All return codes from PROCESSFILE are documented in "FSEXT Error Code Reference".
The result buffer will be empty on return from PROCESSFILE.
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 1> [FILE <file 2> [...]] [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 x 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.
The optional parameter EXISTS may be specified to indicate that COMPAREDIR 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.
The optional parameter ATTEMPTS may be specified to indicate the number of times that the comparison should be made. This value will default to 1.
The optional parameter INTERVAL may be specified with the ATTEMPTS parameter to indicate how long, in milliseconds, FSEXT should wait between attempts to compare the directory. This parameter defaults to 15000 (15 seconds).
Minimum security level of 3 required to do a processfile.
All return codes from COMPAREDIR are documented in "FSEXT Error Code Reference".
The result buffer will be empty if all comparisons were successful. The result buffer will contain the first file which failed a check if not all specified files could be found. If EXISTS is not specified, the result buffer may contain a list of all extraneous files.
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 1> [STRING <string 2> [...]] [NOT] [IGNORECASE] [SAVEONFAILURE]
file specifies the file in which to search. This filename must be fully qualified.
string x specifies a string that should be used as part of the search criteria. The STRING option may be specified one or more times.
The optional parameter NOT may be specified to indicate that FILECONTAINS 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.
The optional parameter IGNORECASE may be specified to indicate that a case insensitive search should be performed.
The optional parameter 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".
Minimum security level of 3 required to do a processfile.
All return codes from FILECONTAINS are documented in "FSEXT Error Code Reference".
The result buffer will be empty if the search was successful based on the search criteria. The result buffer will contain the string which could not be found if a positive search fails. If a negative search fails, NOT specified, then the result buffer will contain the byte offset of the string and the string which was found and caused the failure. The format is: offset:string
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 1> [STRING <string 2> [...]] [IGNORECASE] [SAVEONFAILURE] [LINENUMBER <line number>]
file specifies the file in which to search. This filename should be fully qualified.
string x specifies a string that should be used as part of the search criteria. The STRING option may be specified one or more times.
The optional parameter IGNORECASE may be specified to indicate that a case insensitive search should be performed.
The optional parameter 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".
The optional parameter 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.
Minimum security level of 3 required to do a processfile.
All return codes from LINECONTAINS are documented in "FSEXT Error Code Reference".
If the query was successful, the result buffer will contain the line number and the contents of the line where the strings were found. If the query failed and LINENUMBER was specified, the result buffer will conatin the line number and the contents of the line specified by the LINENUMBER parameter. If the query failed and LINENUMBER was not specified the result buffer will be empty. NOTE: The contents of the result buffer will be in the format line#:line
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 <tofile>] [TOMACHINE <tomachine>] [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.
Minimum security level of 4 required to do a substitute.
All return codes from SUBSTITUTE are documented in "FSEXT Error Code Reference". NOTE: This command calls the FS copy command and may return any Return Codes that copy does.
The result buffer will be empty upon successful completion of this command and may contain additional information if the command fails.
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 INTERVAL milliseconds and try again. This will repeat until the file exists or until the TIMEOUT value is reached. NOTE: Use of the NOT parameter 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, FSEXT should wait before performing the next check for the file. The default is 15000 (15 seconds).
not indicates that the waitforfile command should wait for a file NOT to exist. This may be useful in checking that a file was succesfully deleted.
Minimum security level of 3 required to do a processfile.
All return codes from WAITFORFILE are 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.
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. |