Built-In Variables

1. the integer value of the index of the last element of ARGV plus one, or
2. if the last element of ARGV has a string index, ARGI is set to zero.

Setting ARGI to zero, ARGC or a value for which there is no element of ARGV with a corresponding index value, will cause the current input file to be the last command line argument processed.

1. determine next record according to RS and read record,
2. set value of RT,
3. set FNR and NR.
4. parse record according to FS and set NF and $i, 1 <= i <= NF.
5. start executing pattern expressions

The fourth step in the above sequence can be delayed until a field variable value or NF is needed by setting DELAY_INPUT_PARSE to a true value.

Any characters read from the standard input file, stdin, are echoed to the standard output file, stdout, if ECHO_INPUT has a true value. If ECHO_INPUT has a false value, then characters read from stdin are not echoed to stdout. When the input to QTAwk has been redirected or piped by the operating system, or the input file has been specified on the command line as a single hyphen, '-', then any input read will be echoed to stdout according to the value of ECHO_INPUT. Since the default value of ECHO_INPUT is 0, the following simple command line utility:

QTAwk "{print;}" <input_file

will display a single copy of each input line.

Modifying the utility as:

QTAwk "BEGIN{ECHO_INPUT=1;}{print;}" <input_file

will display two copies of each record from the redirected input file. The first record will be displayed because of the echoed input from 'stdin'. The second copy of the input record will be from the explicit print statement.

When the standard input file is the keyboard, any characters read are always echoed to the console display. In addition, if ECHO_INPUT is true, then any characters read are also echoed to the standard output file.

When the standard input file is redirected from a file or piped from the output of another application program, it is convenient to set ECHO_INPUT to a false value to prevent echoing each input character to the standard output file.

For input read from the keyboard file with the fgetc function, ECHO_INPUT should be set to a true value to display key values as they are pressed.

The following table shows the effect of ECHO_INPUT on input from the standard input file and the keyboard file:

ECHO_INPUT->	true	false
echo keyboard to display	yes	no
echo stdin to display	yes	yes
echo stdin to stdout	yes	no
echo redirected stdin to display	no	no
echo redirected stdin to stdout	yes	no

For example, running the following simple utility will display all environment strings defined and passed to QTAwk:

 C:\>qtawk "BEGIN{for(i in ENVIRON)print i,ENVIRON[i];}"

The following is typical of the output obtained:

0 COMSPEC=C:\OS2\MDOS\COMMAND.COM
1 PROMPT=$i$p$g
2 PATH=C:\OS2;C:\OS2\MDOS;C:\OS2\MDOS\WINOS2;C:\;
3 KEDFILE=D:\KEDIT
4 TMP=D:\
5 TEMP=C:\OS2\MDOS\WINOS2\TEMP
6 LIB=D:\C700\LIB;C:\C700\MFC\LIB
7 INCLUDE=D:\C700\INCLUDE;C:\C700\MFC\INCLUDE;C:\MASM\INCLUDE
8 HELPFILES=D:\C700\HELP\*.HLP;C&colon./C700\HELP
9 INIT=D:\C700\INIT
10 QTAWK=E:\QTAwk_Fn;
11 QTGREP=D:\QTAwk_Fn;
12 ETC=g:\tcpip\dos\etc

n1 n2 n3 ... nn

the splitting of input records into fields is governed by the numbers in FIELDWIDTHS rather than FS. Each number in FIELDWIDTHS specifies the width of a field including columns between fields. If you want to ignore the columns between fields, you can specify the width as a separate field that is subsequently ignored. When the value FIELDWIDTHS does not match this form, field splitting is done using FS in the usual manner. If the length of the input record is greater than the sum of the field widths specified in FIELDWIDTHS. QTAwk creates an additional field and assigns the remainder of the input record to the field.

Assigning the following string to FIELDWIDTHS:

FIELDWIDTHS = "8 25 6 15 9 10";

QTAwk will break subsequent records into 1 to 7 fields depending on the record length. For records with a length of exactly 73 (== 8 + 25 + 6 + 15 + 9 + 10), each field has the lengths specified. For records with greater than 73 characters, the additional characters are assigned to field 7. For records with less than 73 characters, QTAwk creates fields until the characters in the record are exhausted.

This variable is especially helpful when used in conjunction with the RECLEN for fixed length input records. For example, a "dir" under PC/MS-DOS produces records of fixed length as follows:

15:31:50.44>dir

The volume label in drive C is OS2.
The Volume Serial Number is A736:0414.
Directory of C:\

AUTOEXEC BAT       798  12-01-96  5:54p
BOOT     DAT     16896  11-26-96  5:51p
CID          < DIR >    11-26-96  5:57p
CONFIG   SYS     12810   2-06-97  6:58p
DESKTOP      < DIR >    11-26-96  6:01p
DMISL        < DIR >    11-26-96  5:47p
DOS      DAT     33280  11-26-96  5:51p
IBMCOM       < DIR >    11-26-96  5:57p
      29 file(s)     203191 bytes used
                   15196160 bytes free

After reading the first 5 records, setting:

RECLEN = 40;
FIELDWIDTH = "8 1 3 1 9 2 2 1 2 1 2 1 2 1 2 1 1";

Allows for easily accessing each component of the listing as follows:

$1 ==> filename string
$3 ==> file extension string
$5 ==> file size or "< DIR >" string
$7 ==> month of file date
$9 ==> day of file date
$11 ==> year of file date
$13 ==> hour of file time
$15 ==> minute of file time
$16 ==> 'p' or 'a' of file time

For HPFS under OS/2, the directory listing is no longer a fixed length, since filenames are no longer fixed length. The following is typical of a directory listing for HPFS:

The volume label in drive C is OS2.
The Volume Serial Number is A736:0414.
Directory of C:\

12-01-96   5:54p       798           0  AUTOEXEC.BAT
11-26-96   5:51p     16896           0  boot.dat
 8-12-96   2:43a     43369           0  CDFS.IFS
11-26-96   5:57p     < DIR >         0  CID
 2-06-97   6:58p     12810           0  CONFIG.SYS
11-26-96   6:01p     < DIR >       447  Desktop
11-26-96   5:51p     33280           0  DOS.DAT
11-26-96   5:25p     < DIR >         0  IBMINST
11-26-96   5:58p       256           0  IBMLVL.INI
11-26-96   5:27p     < DIR >         0  IBMVESA
 8-30-96   5:58p     47168           0  README
11-26-96   5:35p     <.DIR>.       300  SPOOL
       30 file(s)     203191 bytes used
                    15198720 bytes free
      

Leaving RECLEN as zero and setting FIELDWIDTHS as:

FIELDWIDTHS = "2 1 2 1 2 2 2 1 2 1 1 9 1 10 2";

The components of the directory listing can be accessed via the fields as:

$1 ==> file date month
$3 ==> file date day
$5 ==> file date year
$7 ==> file time hour
$9 ==> file time minute
$10 ==> 'a' or 'p'
$12 ==> file size string or "<DIR>" string
$14 ==> file attributes size
$16 ==> remainder of record == file name string,

Judicious use of the FIELDWIDTHS variable with records with fields with precisely defined sizews, can make accessing particular fields very easy.

If assigned a new string value by the user's utility, the full drive and path must be specified if necessary to find the file. QTAwk will strip off the drive and path and assign the filename to the FILENAME variable. The following statements will save the current filepath and name and re-assign it for later use:

# Save Current File Name
fpn_hold = FILEPATH >< FILENAME;
.
.
.
# Revert To Processing Original Input File
FILENAME = fpn_hold;

Valid character values for sorting are given in the table below. Note that case is unimportant.

value	Sort
n	sort by file name
e	sort by file extension
wd	sort by file write date
cd	sort by file creation date
ad	sort by file last access date
wt	sort by file write time
ct	sort by file creation time
at	sort by file last access time
s	sort by file size

Any other character(s) will be ignored.

If multiple sort options are specified, the files returned are sorted in the order of preference given.

For example:

# Will Sort By Write Date, Write Time,
# File Extension, File Name And Last By Size
FILE_SORT = "wdwtens";

See also NR.

1. setting to a single blank, ' ' or " ", will set FS to the default value of /{_z}+/. With the default value for FS, leading and trailing white space will be stripped from the input record prior to splitting the record into fields.
2. setting to a value other than a regular expression constant, the regular expression value will be derived. The regular expression will be converted to the regular expression internal form when the assignment is made. Input records are scanned for a string matching the regular expression and matching strings become field separators. The length of matching strings is governed by the LONGEST_EXP. built-in variable.

   ---

   NOTE: If FS is explicitly assigned the default value of /{_z}+/, the splitting of the input record into fields will be accomplished exactly the same as if FS had been assigned a single blank character except that the striping of leading and trailing white space is not done. Thus, if a record has leading white space, the first field will be the null string preceding the white space.

   ---

3. setting to the null string, "", causes field splitting to be done at each character of the input record, i.e., each input field will be a single character from the input record and the number of fields in the input record, NF, will be set to the length of the input record.

If FS is any other single character, such as ",", then each occurrence of that character separates two fields. Two consecutive occurrences delimit an empty field. If the character occurs at the beginning or the end of the line, that too delimits an empty field. The space character is the only single character which does not follow these rules.

Suppose you want single spaces to separate fields the way single commas were used above. You can set FS to /[\s]/. This regular expression matches a single space and nothing else.

There is an important difference between the two cases:

1. FS = " "; and
2. FS = /{_z}+/;

For both values of FS, fields are separated by runs of spaces and/or tabs. However, in the first case, QTAwk will first strip leading and trailing whitespace from the record before parsing the record into fields.

For example, with the following input record:

" a b c d e f "

if FS is the default, then the first field of the input record is:

"a"

If, however, FS is set as:

FS = /{_z}+/;

then the first field of the input record is a null string since the leading and trailing white space have not been stripped from the record.

Additionally, if any field is changed the record is rebuilt. The rebuilding process can occur in two ways depending upon the value of the built-in variable, RETAIN_FS. If RETAIN_FS is false, the default value, then QTAwk rebuilds the record by concatenating the fields separated by the string value of OFS. Leading and trailing white space are not retained. If, however, the value of RETAIN_FS is true, then if any field is changed, the new value REPLACES the old value in the input record. All other characters of the input record are unchanged.

Thus, the following short utility:

{
    print;
    for ( i = 1 ; i <= NF ; i++ ) $i = strupr($i);
    print;
}

the output for the above input record is:

"   a b c d e f   "
"A B C D E F"

If the following BEGIN action is added to the above utility,

BEGIN {
    RETAIN_FS = TRUE;
}

then the output is:

"   a b c d e f   "
"   A B C D E F   "

There are times when you may want to examine each character of a record separately. In QTAwk, this is easy to do, you simply assign the null string to FS:
FS = "";

In this case, each character in the record will become a separate field.

{
    for ( i = 1 ; i <= NF ; i++ )
    print "Field " >< i >< ":",$i;

With the input record:

"a b c d e f"

the output is:

Field 1: a
Field 2: b
Field 3: c
Field 4: d
Field 5: e
Field 6: f

1. any match using the match operators, ~~ and !~, either explicit or implied, in pattern expressions,
2. any match using the match operators, ~~ and !~, either explicit or implied, in action expressions,
3. any match using the functions:
   1. gensub
   2. gsub
   3. index
   4. match
   5. split
   6. sub
   7. strim
   8. srchrecord
   9. fsrchrecord
4. any search using the FILE_SEARCH_PAT variable,
5. any match of one string against another using the equality operators, == and !=
6. any match of one character against another using the equality operators, == and !=
7. any match of one string against another string in switch/case statements,
8. any match of one character against another character in switch/case statements,
9. any match against a regular expression in switch/case statements,
10. all searches for record terminator character/strings using RS.
11. all searches for field separator character/strings using FS.

1. ABDAY_1 (Sun) -- the abbreviated name of the 1st day of the week
2. ABDAY_2 (Mon) -- the abbreviated name of the 2cd day of the week
3. ABDAY_3 (Tue) -- the abbreviated name of the 3rd day of the week
4. ABDAY_4 (Wed) -- the abbreviated name of the 4th day of the week
5. ABDAY_5 (Thu) -- the abbreviated name of the 5th day of the week
6. ABDAY_6 (Fri) -- the abbreviated name of the 6th day of the week
7. ABDAY_7 (Sat) -- the abbreviated name of the 7th day of the week
8. ABMON_1 (Jan) -- the abbreviated name of the 1st month of the year
9. ABMON_10 (Oct) -- the abbreviated name of the 10th month of the year
10. ABMON_11 (Nov) -- the abbreviated name of the 11th month of the year
11. ABMON_12 (Dec) -- the abbreviated name of the 12th month of the year
12. ABMON_2 (Feb) -- the abbreviated name of the 2cd month of the year
13. ABMON_3 (Mar) -- the abbreviated name of the 3rd month of the year
14. ABMON_4 (Apr) -- the abbreviated name of the 4th month of the year
15. ABMON_5 (May) -- the abbreviated name of the 5th month of the year
16. ABMON_6 (Jun) -- the abbreviated name of the 6th month of the year
17. ABMON_7 (Jul) -- the abbreviated name of the 7th month of the year
18. ABMON_8 (Aug) -- the abbreviated name of the 8th month of the year
19. ABMON_9 (Sep) -- the abbreviated name of the 9th month of the year
20. AM_STR (AM) -- the string used to denote time before noon
21. CURRENCY_SYMBOL ($) -- the currency symbol
22. DAY_1 (Sunday) -- the full name of the 1st day of the week
23. DAY_2 (Monday) -- the full name of the 2cd day of the week
24. DAY_3 (Tuesday) -- the full name of the 3rd day of the week
25. DAY_4 (Wednesday) -- the full name of the 4th day of the week
26. DAY_5 (Thursday) -- the full name of the 5th day of the week
27. DAY_6 (Friday) -- the full name of the 6th day of the week
28. DAY_7 (Saturday) -- the full name of the 7th day of the week
29. DECIMAL_POINT (.) -- the decimal point used in formatted numerics
30. D_FMT (%m/%d/%y) -- format string used for date
31. D_T_FMT (%a %d %b %Y %r %Z) -- format string used for date and time. Date and time formats are explained in Date/Time Formats.
32. FRAC_DIGITS () -- the number of digits to display to the right of the decimal point for monetary values.
33. GROUPING () -- the sizes of the digits groups for non-monetary values. Successive elemnts of the string describe groups going away from the decimal point. An element value of zero, 0, calls for the previous value to be repeated indefinitely. An element value of 256 ends any further grouping.
34. INT_CURR_SYMBOL (USD ) -- the international currency symbol specified by ISO 4217.
35. INT_FRAC_DIGITS () -- the number of digits to display to the right of the decimal point for international monetary values.
36. LOCALE (en) -- locale name
37. MON_1 (January) -- full name of the 1st month of the year
38. MON_10 (October) -- full name of the 10th month of the year
39. MON_11 (November) -- full name of the 11th month of the year
40. MON_12 (December) -- full name of the 12th month of the year
41. MON_2 (February) -- full name of the 2cd month of the year
42. MON_3 (March) -- full name of the 3rd month of the year
43. MON_4 (April) -- full name of the 4th month of the year
44. MON_5 (May) --full name of the 5th month of the year
45. MON_6 (June) --full name of the 6th month of the year
46. MON_7 (July) --full name of the 7th month of the year
47. MON_8 (August) --full name of the 8th month of the year
48. MON_9 (September) --full name of the 9th month of the year
49. MON_DECIMAL_POINT (.) -- the decimal point for monetary values
50. MON_GROUPING () -- the sizes of the digits groups for monetary values. Successive elemnts of the string describe groups going away from the decimal point. An element value of zero, 0, calls for the previous value to be repeated indefinitely. An element value of 256 ends any further grouping.
51. MON_THOUSANDS_SEP (,) -- the separator for digits groups to the left of the decimal point for monetary values
52. N_CS_PRECEDES () -- whether the currency symbol precedes (1) or follows (0) the value for negative monetary values
53. NEGATIVE_SIGN (-) -- the negative sign for monetary values
54. NOEXPR (^[nN].*) -- a regular expression which can be used to recognize a negative response to a yes/no question
55. N_SEP_BY_SPACE () -- whether the currency symbol is separated by a space (1) or immediately follows (0) the value for negative monetary values
56. N_SIGN_POSN () -- for negative monetary value, whether:
    1. 0 --> parentheses surround the value and the currency symbol
    2. 1 --> the negative sign precedes the value and the currency symbol
    3. 2 --> the negative sign follows the value and the currency symbol
    4. 3 --> the negative sign immediately precedes the currency symbol
    5. 4 --> tthe negative sign immediately follows the currency symbol
57. P_CS_PRECEDES () -- whether the currency symbol precedes (1) or follows (0) the value for positive monetary values
58. PM_STR (PM) -- the string used to denote time after noon
59. POSITIVE_SIGN () -- the positive sign for monetary values
60. P_SEP_BY_SPACE () -- whether the currency symbol is separated by a space (1) or immediately follows (0) the value for positive monetary values
61. P_SIGN_POSN () -- for positive monetary value, whether:
    1. 0 --> parentheses surround the value and the currency symbol
    2. 1 --> the positive sign precedes the value and the currency symbol
    3. 2 --> the positive sign follows the value and the currency symbol
    4. 3 --> the positive sign immediately precedes the currency symbol
    5. 4 --> tthe positive sign immediately follows the currency symbol
62. T_FMT (%r) -- format string used for time. Date and time formats are explained in Date/Time Formats.
63. T_FMT_AMPM (%I:%M:%S %p) -- format string used for time with before/after noon designation
64. THOUSANDS_SEP (,) -- the separator for digits groups to the left of the decimal point for non-monetary values
65. YESEXPR (^[yYsS].*) -- a regular expression which can be used to recognize a positve response to a yes/no question

1. patterns
2. expressions containing the match operators, ~~ and !~
3. the match function
4. the gensub function
5. the gsub function
6. the sub function
7. the strim function
8. input record separator strings matching RS pattern(s)
9. input record field separator strings matching FS. pattern(s)
10. field separator matching in the split function

If assigned a false value, then the first string matching the regular expression is found.

1. If a directory and/or path name name is specified for an module file, then that path only is searched.
2. If no directory or path name is specified, then the current directory is searched. If the file is not found, then all paths specified in Module_Path are searched for the file in the order specified. Multiple paths may be specified, separated by a semi-colon. This follows the same convention for specifying multiple paths in the system environment path setting, "PATH".

The value of Module_Path may be reset at any time by the user's utility to change the paths to be searched for module files. Setting the value of Module_Path to a false value, will null the directory search, only the current directory will be searched.

If the new value of NF is greater than the current value, the current input line is lengthened. The method by which QTAwk split the current record into fields determines how the record is lengthened. If QTAwk is using the value of FS to split records into fields, then the current record is lengthened by concatenating empty fields separated by the output field separator string, OFS, onto the end of the record.

If field splitting is currently done using the FIELDWIDTHS variable, then, QTAwk follows the following rules for adding new fields:

1. new fields are added using the fields widths specified in FIELDWIDTHS. The new fields are filled using the current string value of FIELDFILL. The string value of FIELDFILL is repeated as necessary to fill each field.
2. When the field to be added exceeds the number of fields specified in FIELDWIDTHS, then new fields are added as if field splitting was accomplished using FS.

Note: Under OS/2, whenever RECLEN is assigned a non-zero value, the current input file is read as a "binary" file. Normally, the current input file is opened in "text" mode under OS/2, i.e., Carriage Return/Line Feed pairs are translated to single Line Feed characters. However, when fixed length records are being read, then the translation is no longer performed. The translation may also be turned off with the command line option, "-Wi". Refer to Command Line Options

1. setting to the null string, "", will set RS to the regular expression /\n\n+/. Thus, blank lines, i.e., two or more consecutive newline characters, bound input records.
2. setting to a value other than a regular expression constant, the regular expression value will be derived. The regular expression internal form will be derived when the assignment is made. The input file character stream is scanned for a string matching the regular expression and matching strings become record separators. The length of matching strings is governed by the LONGEST_EXP built-in variable.

The string matching RS is assigned to RT.

1. USER_FUNCTIONS["some_function"] == "source_file_1.awk"
2. USER_FUNCTIONS["library_function_1"] == "library_functions.awk"

1. If a directory and/or path name name is specified for an input file, then that path only is searched.
2. If no directory or path name is specified, then the current directory is searched. If the file is not found, then all paths specified in QTAwk_Path are searched for the file in the order specified. Multiple paths may be specified, separated by a semi-colon. This follows the same convention for specifying multiple paths in the system environment path setting, "PATH".

The value of QTAwk_Path may be reset at any time by the user's utility to change the paths to be searched for input files. Setting the value of QTAwk_Path to a false value, e.g., the null string (""), will null the directory search, only the current directory will be searched.