SQABasic "FileTestUtilities" Library

 MODULE DESCRIPTION:

 Routines for testing files and/or directories in SQA Robot.

Declarations Constants Global Variables User-Defined Types Routine Details

User Dependencies:

(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)

Internal Dependencies:

(stuff this library needs at compile time.)

Exported Declarations

Function CompareDirectories      BasicLib FileTestUtilities 
Function CompareFilesByPath      BasicLib FileTestUtilities 
Function CompareFilesByInfo      BasicLib FileTestUtilities 
Function SeparateDirectoryEntries  BasicLib FileTestUtilities 
Function SyncFileInfoFIFOS       BasicLib FileTestUtilities 
Function FilterTextFile          BasicLib FileTestUtilities 

Constants


' Text file filter mode constants (for FilterTextFile rountine)
Const FILE_FILTER_MODE_DEFAULT  As Integer = 0
Const FILE_FILTER_MODE_REGEXP   As Integer = 1



Globals


    (none)

User-Defined Types


    (none)

Routine Details



  Function SyncFileInfoFIFOS(aFIFO() As FileInfo, aFIFOInfo As BufferInfo,
                             bFIFO() As FileInfo, bFIFOInfo As BufferINfo,
                             logFac As LogFacility) As Integer

 DESCRIPTION:

      Tries to sync up two FIFOS which supposedly have matching entries.
      The routine requires the FIFO entries were entered in a sorted fashion
      so that comparison feedback and synchronization can occur appropriately.

      Example Use: One FIFO contains the FileInfos of a bench directory and
                   another FIFO contains the FileInfos of a new install.

      This routine helps keep the FileInfo compares in synch when new or
      missing files are found.

 PARAMETERS:

      aFIFO()     reference FileInfo() for FIFO A
      aFIFOInfo   reference BufferInfo for FIFO A
      bFIFO()     reference FileInfo() for FIFO B
      bFIFOInfo   reference BufferInfo for FIFO B
      logFac      logFacility to use for reporting errors.

 RETURNS:

       the number of errors encountered during synchronization.
      -1 on generic failure.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: AUG 27, 1999
 History:

      AUG 27, 1999    Original Release
      JUL 10, 2000    (CANAGL)    Modified for new Buffer and FIFO utilities.




  Function SeparateDirectoryEntries (path As String _
                                     , dBuffer() As FileInfo, dBufferInfo As BufferInfo _
                                     , fBuffer() As FileInfo, fBufferInfo As BufferInfo) _
                                     As Integer

 DESCRIPTION:

      Separate the files in a single directory into separate FIFO buffers.
      One FIFO will contain all non-directory FileInfos.  The other will contain
      all FileInfos for subdirectories.
      (.) and (..) directory files are ignored and omitted.
      This routine does not initialize or clear the FIFOs provided.  It pushes
      new values into the FIFOs.

 PARAMETERS:

      path            the full path of the directory to parse
      dBuffer()       reference to the directory FIFO to use
      dBufferInfo     reference to the directory FIFO BufferInfo to use
      fBuffer()       reference to the file FIFO to use
      fBufferInfo     reference to the file FIFO BufferInfo to use

 RETURNS:

       The total number of entries found in the directory excluding (.) or (..)
      -1 if the path was not a valid directory

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: AUG 27, 1999
 History:

      AUG 27, 1999    Original Release




  Function CompareFilesByInfo(aInfo As FileInfo, bInfo As FileInfo,
                              mode As Integer,
                              logFac As LogFacility) As Integer

 DESCRIPTION:

      Performs a full compare of two files based on the mode value provided.
      This will compare the FileInfos AND perform a BINARY_COMPARE of the
      files if the mode calls for it.  Since this is possible the routine
      exits with failure if either file does not exist even if BINARY_COMPARE
      mode is not enabled.
      Use CompareFileInfos if no BINARY_COMPARE is intended.

 PARAMETERS:

      aInfo   FileInfo reference to the source file to compare
      bInfo   FileInfo reference to the bench file to compare
      mode    which items to compare.  See COMPARE CONSTANTS for valid values.
      logFac  LogFacility to log error messages.

 RETURNS:

      if non-negative the return value is the number of errors found.
     -1 if target or bench filename is FileNotFound
     -3 generic unknown failure

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: AUG 27, 1999
 History:

      AUG 27, 1999    Original Release




  Function CompareFilesByPath(aPath As String, bPath As String,
                              mode As Integer,
                              logFac As LogFacility) As Integer

 DESCRIPTION:

      Performs a full compare of two files based on the mode value provided.
      This will create two FileInfos based on the provided paths then perform
      the comparison using CompareFilesByInfo.
      Use CompareFileInfos if no BINARY_COMPARE is intended.

 PARAMETERS:

      aPath   full path to the source file to compare
      bPath   full path to the bench file to compare
      mode    which items to compare.  See COMPARE CONSTANTS for valid values.
      logFac  LogFacility to log error messages.

 RETURNS:

      if non-negative the return value is the number of errors found.
     -1 if target or bench filename is FileNotFound
     -3 generic unknown failure

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: AUG 27, 1999
 History:

      AUG 27, 1999    Original Release




 Function CompareDirectories (target As String, bench As String,
                              doSubs As Integer,
                              mode As Integer,
                              logFac As LogFacility) As Integer

 DESCRIPTION:

      Compares a target directory structure against a bench directory structure.
      Compares file names, lengths, time/date stamps, and contents based on
      the provided mode value.

 PARAMETERS:

      target   filename of directory structure to test against the bench
      bench    filename of directory structure to use as the bench
      doSubs   =0 do NOT processes subdirectories. 1 means DO process subdirectories
      mode    items to compare. See the COMPARE CONSTANTS for valid values of mode.
              Note that usually you should not include PATH_COMPARE within
              the mode value since they are almost always different.
      logFac  LogFacility to log errors messages.

 RETURNS:

      if non-negative the return value is the number of errors found.
     -1 if target or bench filename is FileNotFound
     -2 if target or bench filename is NOT A DIRECTORY
     -3 generic unknown failure

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: AUG 27, 1999
 History:

      AUG 27, 1999    Original Release
      JUL 10, 2000    (CANAGL) Modified for new Buffer and FIFO utilities.




 Function ApplyRegExpFileFilter ( _
                                 source As String, _
                                 target As String, _
                                 pattern As String, _
                                 replacewith As String ) As Integer

 DESCRIPTION:

      Applies a regular expression filter on a text file.

      The function parses the source file, replaces all occurences of text
      that match the specified pattern with a specified string, and saves
      the parsed text to a new file.

 PARAMETERS:

      source      Required. Full path to the file to be filtered.

      target      Required. Full path to the file to save the filtered text to.
                  If file exists, it is overwriten. Use the same spec as source
                  to save changes to the original file.

      pattern     Required. Regular expression pattern to search for. Must not
                  be empty.

      replacewith Required. String to replace the matching patterns with.
                  "" to remove the matching patterns.

 RETURNS:

      0   if successful;
      1   if failed (specified file not found; invalid parameters etc).

 ERRORS:

      none

 Orig Author: Yuesong Wang
 Orig   Date: NOV 11, 2002
 History:

      NOV 11, 2002    Original Release




 Function FilterTextFile ( _
                          source As String, _
                          target As String, _
                          Optional mode, _
                          Optional option1, _
                          Optional option2, _
                          Optional option3 ) As Integer

 DESCRIPTION:

      Filters the text content of a file based on provided mode and options.

      The text content of the source file is read in, filtered (i.e.
      transformed/modified in most cases) and saved to the target file.

 PARAMETERS:

      source  Required. Full path to the file to be filtered.

      target  Required. Full path to the file to save the filtered text to.
              If file exists, it is overwriten. Use the same spec as source
              to save changes to the original file.

      mode    Optional. Numeric value that indicates the filter mode. One of
              the valid FILE_FILTER_MODE constants defined by the library.
              See table below for a complete list of supported modes. If
              omitted, FILTER_MODE_DEFAULT is used.

      option1 Optional. Variant value that indicates a parameter for mode.
              Depending on mode, this has different meanings. See table below.

      option2 Optional. Variant value that indicates a parameter for mode.
              Depending on mode, this has different meanings. See table below.

      SUPPORTED FILTER MODE AND FILTER OPTIONS

      MODE        OPTIONS                     COMMENT
      ========================================================================
      DEFAULT     NONE                        No filtering. source is copied to
                                              target unchanged.

      REGEXP      1 - PATTERN                 All occurences of regular expression
                      Required; String        PATTERN in source will be replaced
                  2 - REPLACEMENT             with REPLACEMENT. Default value for
                      Optional; String        REPLACEMENT is "", i.e. to remove
                  3 - IGNORECASE              all text matching PATTERN. Set IGNORECASE
                      Optional; Integer       to True (-1) to do case-insensitive
                                              seach when matching pattern. Default
                                              is False (0).

 RETURNS:

      0   if successful;
      1   if failed (specified file not found; invalid mode/option spec etc).

 ERRORS:

      none

 Orig Author: Yuesong Wang
 Orig   Date: NOV 11, 2002
 History:

      NOV 11, 2002    Original Release


Copyright (C) SAS Institute
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php 
==============================================================================