User Guide
Chapters
Table of Contents
Trace Statements
Limits

Command Line Format

Command Line Format

There are two ways of specifying utilities to QTAwk:

  1. Specifying the utility on the command line, e.g., Command Line Utility

    QTAwk "/^{_w}*$/{if(!bc++)print;next;}{bc=FALSE;print;}" file1

    This short command line utility will read file1, printing only the first blank line in a series of blank lines. All nonblank lines are printed.

    Note that the "utility" has been enclosed in double quotes, ". This is necessary to keep the operating system from interpreting the utility as a file. In addition, if the utility contains symbols recognized by the operating system command line interpreter, e.g., the re-direction operators, '<' or '>', the quotes keep the interpreter from recognizing the symbols. If the utility contains quotes, e.g., a constant string definition, then the imbedded quotes should be preceded by a back-slash, '\'.

    For example, the short utility:

    QTAwk "{print FNR\" : \"$0;}" file1

    prints each line of file1 preceded by the line number. The constant string, 

    " :  "

    separates the line number from the line. Back-slashes must precede the quotes surrounding the constant string.

  2. Using the f command line option:

    -fufile

    or

    -f ufile

    When a utility may be used frequently or grows too long to include on the command line as above, it becomes necessary to store it in a file. The utility may then be specified to QTAwk with this option. The blank between the f command line option and the utility file name is optional.

    Note: This method of specifying utilities to QTAwk cannot be combined with the command line utility definition method.

Binary File QTAwk Utilities

As explained below more than one utility file may be specified with the f command line option. However, if only one utility file is specified, QTAwk will read the utility file, convert it into internal form and then automatically write the internal form to a file with the same name and path as the utility file, but with ".QTAwk.binary" appended on the end. Note that more than one utility file may be incorporated into the final utility by using the include directive.

On future uses of the utility file, QTAwk will check for the presence of the binary file containing the internal form of the utility. If the binary file exists, QTAwk will check the date and time of the file against the date and time of the source file(s) from which the internal form file was derived. If the date/time of the binary file is later than all of the source files, the binary file is used.

The use of the binary file saves the conversion and error checking process involved. If the date/time of any of the source file(s) is later than the binary file, then the source files are read and a new binary file is written.

If any of the source files are missing, the current binary file is used irregardless of the date/time.

If the binary file is specified on the command line instead of the source file, then the binary file is used without checking for the existence of the source file(s) or executing the date/time check.

Once a binary file exists, the binary file may be distributed to users for use. The distribution and use of the binary file, prevents any accidental changes to the source file(s) and ensures that all users are using the same utilities.

Multiple QTAwk Utilities

More than one utility file may be specified to QTAwk using the f command line option. Each utility file specified is read in the order specified and combined into a single QTAwk utility. In this manner it is possible to keep constantly used pattern-actions or user-defined functions in separate files and combine them into QTAwk utilities as necessary. The order of the utility files is not important except for the order in which predefined patterns are executed and the order in which pattern-action pairs are executed. Thus if a utility file contained only common user-defined functions, it may be defined in any order in relation to other utility files. See also the include directive.

The use of multiple command line utility files, precludes QTAwk from writing a binary file. If binary files are desired, the use of the include directive would be a better solution.

Scanning of the command line for arguments may be stopped with the double hyphen command line argument, --. This argument is not passed to the QTAwk utility.

The command line is scanned for all utility files specified with the f option prior to reading the utility files or any input files. The utility files are then "removed" from the command line and the command line argument count.

#include Directive

A second method for specifying multiple utility files is available that follows the "C" practice of "including" a file at a particular point in a file. QTAwk follows the "C" syntax:

#include "filename.ext"

or

#include \<filename.ext>

The two forms differ only in where QTAwk searches for the file to include. The first form, with double quotes, will search for the specified file only in the current directory if no path is specified. If a path is specified, then the specified path only is searched.

The second form, with the angle brackets, will search first in the current directory and then in the QTAwk default directories specified with the QTAWK environment setting. If a path is specified with this form, the specified path only is searched.

White space is allowed before and after the # symbol. This directive is not recognized within the action portion of any pattern.

By using the include directive, a master file may include pattern/actions and user-defined functions as necessary. It is then necessary to specify only one file on the command line. This makes it much easier to build utilities from several files and remember only one file name to accomplish a desired purpose.

If an attempt is made to include a file mutliple times, QTAwk will output an error message and halt. The command line option, 'm', may be used to force QTAwk to continue processing after the error message, skipping the multiple includes of the same file.

Command Line Options

QTAwk supports the following command line options:

f
utility file specification
F
set field separator, FS, to single character.
v
set variable value before utility execution.
Wi
Do NOT translate Carriage Return/Line Feed pairs to a single Line Feed in input files. Normally, QTAwk opens all input files in "text" mode under OS/2. In "text" mode, Carriage Return/Line Feed pairs are translated to a single Line Feed to match the convention under U*x and Linux. The use of this option disables the translation for all input files and all input files are opened in "binary" mode. Note that this option is only available for the OS/2 version. In the Linux version, no translation is made for any input file. Note also, that unless the utility specifically changes the input record separator, RS, a Carriage Return character will be left on the end of all input lines. To avoid this, change RS as follows:

RS = /\r\n/;

If you expect that lines may be terminated by a mixture of Carriage Return/Line Feed pairs or single Line Feeds, then set RS to:

RS = /\r?\n/;

Note that RS may be changed with the 'v' option as follows:

-v 'RS=/\r\n/'

or

-v 'RS=/\r?\n/'

The record terminator actually used can be obtained from the value of RT.

Wd
delay input parsing. Described under the built-in variable DELAY_INPUT_PARSE.
Wo
Do NOT translate Line Feed characters to a Carriage Return/Line Feed pair in output files. Normally, QTAwk opens all output files in "text" mode under OS/2. In "text" mode, Line Feed characters are translated to a Carriage Return/Line Feed pair to match the convention under OS/2. The use of this option disables the translation for all output files and all output files are opened in "binary" mode. Note that this option is only available for the OS/2 version. In the Linux version, no translation is made for any output file. Note also, that unless the utility specifically changes the output record separator, ORS, no Carriage Return character will be output on the end of all output lines. To avoid this, change ORS as follows:

ORS = "\r\n";

Wm
toggle the flag stopping processing when a file is "included" multiple times. Initially, this flag is false, forcing QTAwk to halt processing when a file is included the second time. Toggling this option will force QTAwk to continue processing when a file is included multiple times. The file is skipped after the first include.

File Search Sequence

QTAwk may search for input files in more than one place. Many times it is convenient to gather all QTAwk utility files into a single directory on a convenient drive, e.g., the directory "\QTAwk\utility" may be used. It would then be convenient to invoke any utility without the necessity of always specifying the full path to the utility. QTAwk recognizes the environment variable setting of "QTAWK" for this purpose. At program invocation QTAwk searches the environment for the setting for "QTAWK" and sets the string value of the built-in variable QTAwk_Path to this string.

For input files, if a drive and/or path is specified with the filename, then that drive and path only are searched for the desired file. If no drive or path is specified, then the current directory is searched, if the file is not found, then the paths (optionally with a drive specifier) specified by the string in the built-in variable QTAwk_Path are searched for the file. Multiple paths may be specified in QTAwk_Path by separating them with semi-colons.

The string value of the built-in variable QTAwk_Path may be altered by the executing utility at any time to change the paths searched for input files.

Setting the Field Separator

The QTAwk input record separator, FS, may be set on the command line with the 'F' option.

QTAwk -F "/:/"

or

QTAwk -F/:/

The blank between the 'F' and the string or regular expression defining the new input record separator is optional. This option may only be specified once on the command line. The command line is scanned for all 'F' options prior to reading any utility files or input files. The option and the new value for FS are then "removed" from the command line and the command line count.

Another method is available for setting FS prior to reading the input files. This method is more general and may be used multiple times on the command line and may be used to set any utility variable and not just FS.

Command Line Variables

Including the following on the command line:

-v"var = value"

or

-vvar=value

or

"var = value"

or

var=value

will set the variable var to the value specified. var may be any built-in or user-defined variable in the QTAwk utility. var must be a variable defined in the current QTAwk utility or a run-time error will occur and QTAwk will stop processing. If preceeded with the option string -v as indicated in the first two examples, the value of the variable is set before execution of the utility starts. If the v option is not specified, the value of var is set when the token is encountered in processing command line tokens.

QTAwk Execution Sequence

QTAwk execution follows the sequence:

  1. The command line is scanned for any options, f, W, F or v. If any such options are found, they are interpreted and removed from the command line. Upon encountering a command line argument of the form -- (double hyphen), scanning of the command line is halted. The -- argument is removed from the command line.
  2. The QTAwk utility is read and converted to internal form. If any f options were found in the preceding step, the associated utility files are opened, read and converted to internal form in the order specified. If no f options were specified, the first command line argument is processed as the QTAwk utility and then removed from the command line arguments. If a Ww option was specified, the associated utility file is opened and the internal form utility written and execution halts.
  3. The ARGC and ARGV built-in variables are set according to the command line parameters. The ARGI built-in variable is set to 1.
  4. Any variable values set on the command line with the v option are set as specified. The v command line option takes the form:
  5. -vvariable=value, or
  6. -v "variable=value"

    7. If the variable specified does not exist, an error message is displayed and execution halted.

  7. Any BEGIN actions in the QTAwk utility are executed. This is done prior to any further interpretation of the command line arguments.
  8. The next command line argument, ARGV[ARGI], is examined. One of two actions is taken depending on the form of the argument:
    1. a variable setting argument of the form:
    2. var=value, or
    3. var = value

      4. The variable is set to the value specified and control loops back to process the next command line argument. If the variable specified does not exist, an error message is displayed and execution halted.

    4. Any other argument is interpreted as a file name. The file specified is opened for input. If the file does not exist, an error message is issued and execution halted. If a single hyphen, -, is specified, it is interpreted as representing the standard input file. If no command line arguments are specified beyond the QTAwk utility or variable setting commands, the standard input file is read for input.
      1. All INITIAL pattern actions are executed.
      2. QTAwk reads the next input file record, a record is determined by the value of the built-in variables RS or RECLEN. The next input record is determined by the value of the built-in variable FILE_SEARCH. If the value of the variable is:
        false
        The next record is the next physical record in the input file.
        true
        The next record is the next record matching the regular expression in the built-in variable FILE_SEARCH_PAT
      3. For each input record:
        1. The record is split into fields which are determined by the value of the built-in variables FS or FIELDWIDTHS. The time when the input record is split into fields is determined by the value of the built-in variable, DELAY_INPUT_PARSE. If the value of the variable is:
          false
          The record is split when read.
          true
          The record is split when a field or the variable NF is referenced.
        2. Each pattern expression is executed in the order encountered in the utility,
          1. If the pattern expression evaluates to TRUE, the associated action is executed immediately.
          2. If the pattern expression evaluates to FALSE, the execution progresses to the next pattern expression.
      4. All FINAL actions are executed.
      5. close the current input file
      6. Loop for next command line argument.
  9. All END actions are executed.
  10. Execution halts.
TOP
User Guide
Chapters
Table of Contents
Trace Statements
Limits