Qualifiers

This section describes the purpose of each SWAP qualifier.  Then it lists all the qualifiers in alphabetical order and describes each qualifier in detail.

It provides a complete qualifier reference "manual" for the experienced SWAP user.



Qualifier Syntax
SWAP qualifiers look and act like DCL qualifiers.  They conform to normal OpenVMS DCL command qualifier syntax.

A qualifier consists of a keyword, or a keyword followed by a value or list of values.  The keyword starts with a slash.  All qualifiers apply to the entire command.  SWAP qualifiers have one of the following formats:

    SWAP/qualifier

    SWAP/qualifier=n (a numeric value)

    SWAP/qualifier=x (a alphanumeric value)

    SWAP/qualifier=() (a list of values separated by commas)

All the qualifiers have defaults.


Wildcards
The wildcards characters "*" and "%" can be used in filenames.


SWAP Qualifier List
This page contains a complete list of all SWAP qualifiers.  Subsequent pages contain detailed descriptions of each qualifier.


The following qualifiers can be used with SWAP

/COLUMNS=(start_column[,end_column])    Define columns to search

/CONFIRM                    Prompt user for action

/EXACT                    Use case in search
/EXCLUDE=(file_spec[,...])            Files to omit

/LENGTH=maximum_record_length        Truncate records

/LOG                        Send messages to terminal

/MENU                    Invoke SWAP’s menu interface

/OUTPUT[=file_spec]            File for messages

/RANGE=(start_number[,end_number])    Define records to search

/STATISTICS                    Report substitution statistics

/TAB[=number_of_spaces]            Replace TAB with blanks

/VERSION                    Show the SWAP version you are running

/NOCONFIRM                Don't prompt user

/NOEXACT                    Don't consider case

/NOLOG                    Don't send messages

/NOOUTPUT                    Don't record messages

/NOSTATISTICS                Don't report statistics

/NOTAB                    Don't replace TAB's

/COLUMNS
 Indicates which columns to search in each record.  If /COLUMNS isn't specified, all columns from 1 to EOL (End of Line) will be searched.  Start column must be 1 or greater.  End column must be greater than or equal to start column.  If end column is omitted, EOL is assumed.  The default is /COLUMNS=(1,EOL).

FORMAT

    /COLUMNS=(start_column[,end_column])                          
        default /COLUMNS=(1,EOL)

KEYWORDS
    start-column

The start-column is the first column of each record in the file that SWAP should begin checking for matches at.  The default value is 1.

    end-column

The end-column is the last column of each record in the file that SWAP should check for matches at.  The default value is the end of each line (EOL).

EXAMPLES
    $ SWAP /COLUMN=(10,40) *.COM "Changed by" "Modified by"

Change every occurrence of the string "Changed by" to "Modified by" in columns 10 to 40 of every command procedure in the current directory.

    $ SWAP/COLUMNS=(7,72) *.* "Johnny" "Bobby"

Only columns 7 through 72 inclusive will be searched for "Johnny" (ignoring case).  Columns 1_6 and 73 to EOL will be left unchanged.  All files in the default directory will be searched.

NOTE:    A tab character is considered to take up one character space.  When a tab is displayed on the screen, it usually is shown as 8 spaces.  The /COLUMNS qualifier considers tabs to be one character.  Therefore, if a line contains a tab, then a space, it will be displayed as 9 spaces but column one will contain the tab and column 2 will contain the space.

NOTE:    When using variables the command line should always include /column=(1,1) or the column value set to “1:1" in the modify setup menu item. This will prevent Swap from moving over 1 column after the substitution is done and performing it again until the end of the line is reached.
    

/CONFIRM
 Controls whether the user is to be prompted before each substitution.  If the user specifies /CONFIRM, SWAP will provide the following options:  
    • Make the substitution

• Ignore this substitution, continue with the file

• Ignore this file, continue with other files

• Abort the command

• Help

The default action is for SWAP not to prompt for confirmation before substitutions.  This qualifier is for string substitutions ONLY.  The /TAB and /LENGTH qualifiers cannot be confirmed, they are performed reguardless of the state of the /CONFIRM qualifier.

FORMAT
    /CONFIRM
    /NOCONFIRM (Default)

KEYWORDS
    None

EXAMPLES
    $ SWAP/CONFIRM *.* A B

SWAP will ask the user what action to take each time it finds the search string "A".  All files in the default directory will be searched.

/EXACT
  Controls whether SWAP is case sensitive during the search; the upper and lower case of the search string should be considered.  If the user specifies /EXACT, each character of the search string must agree in case with the input string for a match to occur.  The default action is to not consider case when looking for matches to the search string.

FORMAT
    /EXACT

KEYWORDS
    None

EXAMPLE

    $ SWAP/EXACT *.DAT "John" "Ralph"

SWAP will test for case during the search (it will look for "John").  It will substitute "John" for "Ralph" in all .DAT files in the default directory.

/EXCLUDE
  Use the /EXCLUDE qualifier to provide SWAP with a list of files that should not be processed. If /EXCLUDE isn't specified, all files specified will be searched.

FORMAT
    /EXCLUDE=(file_spec[,...])

KEYWORDS
    file-spec

The file specification of the file or files you want SWAP to not process.  To specify multiple files, separate the file names with commas, and enclose the list in parenthesis.  If a single file is specified, the parenthesis are not necessary.  You cannot use device, directory, or logicals in the /EXCLUDE clause but wildcards are allowed.  If the file exists in two directories (specified in the input specification), and that file is in the /EXCLUDE the file will be ignored in both directories.

EXAMPLES
    $ SWAP/EXCLUDE=MAIN.FOR *.FOR "test" "temp"

All FORTRAN source programs in the default directory will be processed except MAIN.FOR. "test" (ignoring case) will be substituted with "temp".

    $ SWAP/EXCLUDE=(CHARLIE.RNO,SYSUPD.*) *.RNO "test" "temp"

All runoff (.RNO) files in the default directory will be processed.  CHARLIE.RNO and all files named "SYSUPD" will be ignored.  "test" (case ignored) will be substituted with "temp".

/INFORMATION
 This qualifier specifies that you want SWAP to display its information screen. This screen will display various system and license related items.The /VERSION qualifier also displays the same information.

FORMAT
    /INFORMATION

KEYWORDS
    None

EXAMPLES
    $ SWAP/INFORMATION

SWAP will display the information screen.

/LENGTH
 Indicates the maximum record length for the output file.  Records longer than this will be truncated.  Shorter records will be left unchanged.  If /LENGTH isn't specified, records up to the RMS maximum record length will be unchanged.  It is suggested that the /STATISTICS qualifier be used with the /LENGTH qualifier.  This will provide important audit information about truncated records.

FORMAT
    /LENGTH=max_record_length
        /LENGTH=RMS_max_record_length (Default)

KEYWORD
    max-record-length

The maximum record length that SWAP will write out when modifying a file.  Max-record-length must be greater than 1.  If it is larger than the RMS maximum record length for the file, the smaller value is used.  The RMS maximum record length of text input files is frequently 255 bytes, this is the length the EDT text editor creates files with.

EXAMPLES
    $ SWAP/LENGTH=80 *.* "" ""

Input records longer than 80 characters will be truncated to 80 for all files in the default directory.  No other substitution will be performed.

    $ SWAP/LENGTH=72 *.* "coffee" "tea"

All files in the default directory will be searched for "coffee" (ignoring case).  "tea" will be substituted for each occurance of "coffee".  Each record will be truncated (if necessary) to 72 characters.

/LOG
 Controls whether swap logs its actions to the terminal as they are taken.  There are numerous information messages that will be displayed on the screen along with the report.  These all start with SWAP_I_.  These are only informational messages and not errors.  They are there to help you monitor SWAP as it processes the files.  The default action for SWAP is to log its actions.

FORMAT

/LOG

    /NOLOG (Default)

KEYWORDS
    None

EXAMPLE

$ SWAP/NOLOG *.* jack "Jill"

All files in the default directory will be searched for the string "jack" (ignoring case).  "Jill" will be substituted in for all occurances of "jack" (ignoring case).  No messages will be written to the screen.

/OUTPUT
 Controls whether SWAP writes a copy of the action messages to a file while it's processing your request.  Use /OUTPUT if you want to keep or print a copy of all the changes SWAP has made.

FORMAT
    /OUTPUT=file_spec
KEYWORDS
    file-spec

Can be any valid file specification.  If no file specification is provided with the /OUTPUT qualifier the messages will be written to SWAP_CHANGES.LOG in the current directory.

EXAMPLES
    $ SWAP/OUTPUT *.* "a" "A"

All files in the default directory will be searched for "a" (igoring case).  For each occurance found, "A" will be substituted in.  A record of all substitutions will be written to SWAP_CHANGES.LOG.

    $ SWAP/OUTPUT=CHANGES.SWP *.* "telephone" "dictaphone"

All files in the default directory will be searched for "telephone" (igoring case).  For each occurance found, "dictaphone" will be substituted in.  A record of all substitutions will be written to CHANGES.SWP.

/MENU
This qualifier specifies that you want to use the menu interface for SWAP.

FORMAT
    /MENU

KEYWORDS
    None

EXAMPLES
    $ SWAP/MENU

SWAP will display the menu interface.

/RANGE
 Indicates which records to search in each file.  If /RANGE isn't specified, all records from 1 to EOF (End of File) will be searched.  Start record must be 1 or greater.  End record must be greater than or equal to start record.  If end record is omitted, EOF is assumed.

FORMAT
    /RANGE=(start_record[,end_record])
        /RANGE=(1,EOF) (Default)

KEYWORDS
    start-record

The start-record is the first record of each file that SWAP is to begin checking for  matches at.  The default value is 1.

    end-record

The end-record is the last record of each file that SWAP is to check for matches in.  The default value is to check to the end of the file (EOF).

EXAMPLES
    $ SWAP/RANGE=(30,400) *.* "cord" "wire"

All files in the default directory will be searched for "cord" (ignoring case).  All occurances found will be changed to "wire".  For each file, records 1_29 and 401 through end of file will be ignored.  The rest will be searched.

    $ SWAP/RANGE=7 *.* "smell" "taste"

All files in the default directory will be searched for "smell" (ignoring case).  All occurances found will be changed to "taste".  For each file, the first 6 records will be ignored.  The rest will be searched.

/STATISTICS
Controls whether string substitution statistics are reported to the screen (/LOG) and/or to the output file (/OUTPUT).  It is suggested that this qualifier be used when the /TAB or /LENGTH qualifiers are used.  This is the best way to keep track of these changes.  The default action is to not report statistics.

FORMAT
    /STATISTICS
         /NOSTATISTICS (Default)

KEYWORDS
    None

EXAMPLE
    $ SWAP/STATISTICS *.FOR "FORTRAN" "COBOL"

All files with .FOR extentions will be searched for "FORTRAN" (ignoring case).  All occurances found will be changed to "COBOL".  SWAP will report which files were changed and how many substitutions were made.  There are also a number of other statistics that will be included.

/TAB
 Indicates the number of blanks to substitute for a TAB character.  If /TAB isn't specified, TAB characters will be unchanged.  If /TAB is specified without an argument, /TAB=8 will be used.  Number of spaces must be equal to or greater than 1.  Only tab characters within the boundaries specified by the /RANGE and /COLUMNS qualifiers will be changed.

It is suggested that the /STATISTICS qualifier be used with the /TAB qualifier.  This will provide important audit information about tab substitutions.

FORMAT
    /TAB[=number_of_spaces]
        /NOTAB (Default)
KEYWORDS
    number-of-spaces

The number of spaces that each TAB character seen should be replaced with during processing.  The default value is 8.

EXAMPLES
    $ SWAP/TAB=4 TEST.FOR "MAXIMUM" "MINIMUM"

TEST.FOR will be searched for the string "MAXIMUM" (ignoring case).  All occurances will be changed to "MINIMUM".  TAB characters will be replaced with 4 blanks in ALL records of TEST.FOR.

/VERSION
Use the /VERSION qualifier to show the current version of SWAP you are using as well as all the product and license information. This qualifier is the same as  /INFORMATION.

FORMAT:
    /VERSION

EXAMPLE:

    $ SWAP/VERSION

Display which version of swap you are using and the information screen.