FSEXT (File System EXTension) Service User's Guide

Version 3.0.2

Last updated: December 1, 2009


Table of Contents

  • Overview
  • Installation and Configuration
  • Variables
  • Request Syntax
  • PROCESSFILE
  • COMPAREDIR
  • FILECONTAINS
  • LINECONTAINS
  • SUBSTITUTE
  • WAITFORFILE
  • FSExt Error Code Reference

  • Overview

    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.


    Installation and Configuration

    This service requires:

    Install the FSExt service by downloading the FSExtV302.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:

    Examples

    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.jar
    
    Or, you can dynamically add the FSEXT service using the SERVICE service's ADD SERVICE request.


    Variables

    The FSEXT service uses no STAF variables.


    Request Syntax

    The FSExt service provides the following requests:

    PROCESSFILE

    Either captures the data from one file to another or compares two files.

    Syntax

    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".

    Security

    This request requires at least trust level of 3.

    Return Codes

    All return codes from PROCESSFILE are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".

    Results

    The result buffer will be empty on return from PROCESSFILE.

    Examples

    COMPAREDIR

    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.

    Syntax

    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).

    Security

    This request requires at least trust level of 3.

    Return Codes

    All return codes from COMPAREDIR are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".

    Results

    Examples

    FILECONTAINS

    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.

    Syntax

    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".

    Security

    This request requires at least trust level of 3.

    Return Codes

    All return codes from FILECONTAINS are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".

    Results

    Examples

    LINECONTAINS

    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.

    Syntax

    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.

    Security

    This request requires at least trust level of 3.

    Return Codes

    All return codes from LINECONTAINS are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".

    Results

    Examples

    SUBSTITUTE

    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.

    Syntax

    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.

    Security

    This request requires at least trust level of 4.

    Return Codes

    All return codes from SUBSTITUTE are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".

    Results

    The result buffer will be empty upon successful completion of this command and may contain additional information if the command fails.

    Examples

    WAITFORFILE

    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.

    Syntax

    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.

    Security

    This request requires at least trust level of 3.

    Return Codes

    All return codes from WAITFORFILE are standard STAF return codes documented in the STAF User's Guide or documented in "FSEXT Error Code Reference".

    Results

    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.

    Examples


    FSEXT Error Code Reference

    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.