User Guide
Chapters
Table of Contents
Group Patterns
Format Specification

User Defined Functions

User Defined Functions

QTAwk supports user-defined functions and has enhanced them over Awk in several important aspects.

Local Variables

In QTAwk it is no longer necessary to declare local variables as excess arguments in the function definition. QTAwk has included the local keyword. This keyword may be used in any compound statement, but was invented specifically for user-defined functions. Consider the simple function to accumulate words from the current input record in the formatting utility: 

# accumulate words for line
function addword(w) {
    local lw = length(w); # length of added word

    # check new line length
    if ( cnt + size + lw >= width ) printline(yes);
    line[++cnt] = w; # add word to line array
    size += lw;
}

The fact that lw is local to the function and will disappear when the function is exited is obvious from the definition of lw. It is also now easy to pick out the function arguments, 'w' in this case. The initialization of lw to the length of the argument passed is also easily picked up from the definition. The local keyword thus truly separates local variables from the function arguments and global variables.

Argument Checking

By using the _arg_chk built-in variable, it is also possible to have QTAwk now do some argument checking for the user. If _arg_chk is TRUE, then QTAwk will, at run-time, check the number of arguments passed against the number of arguments defined. If the number passed differs from the number defined, then a run-time error is issued and QTAwk halts. When _arg_chk is FALSE, QTAwk will check at run-time only that the number of arguments passed is less than or equal to the number defined. This follows the Awk practice and allows for the use of arguments defined, but not passed, as local variables. The default value of _arg_chk is FALSE. It is recommended that _arg_chk be set to TRUE and the local keyword used to define variables meant to be local to a function.

Variable Length Argument Lists

QTAwk allows user-defined functions to be defined with a variable number of arguments. The actual number of arguments will be determined from the call at run-time. QTAwk follows the C syntax for defining a function with a variable number of arguments: 

# function to determine maximum value
function max(...)  {
    local max = vargv[1];
    local i;

    for ( i = 2 ; i <= vargc ; i++ )
      if ( max < vargv[i] ) max = vargv[i];
    return max;
}

The ellipses, ..., are used as the last argument in a user-defined argument list to indicate that a variable number of arguments follow. In the max function shown, no fixed arguments are indicated. Within the function, the variable arguments are accessed via the built-in singly-dimensioned array, vargv. The built-in variable vargc is set equal to the number of elements of the array and, hence, the variable number of arguments passed to the function. Since the variable arguments are passed in a singly dimensioned array, the for statement may be used to access each in turn: 

# function to determine maximum value
function max(...)  {
    local max = vargv[1];
    local i;

    for ( i in vargv )
      if ( max < vargv[i] ) max = vargv[i];
    return max;
}

A user-defined function may have fixed arguments and a variable number of arguments following: 

# function with both fixed and variable number of arguments
function sample(arg1,arg2,...)  {
    .
    .
    .
}

If a user-defined function is to have a variable number of arguments, then the local keyword must be used to define local variables. The ellipses denoting the variable arguments must be last in the function definition argument list.

Null Argument List

A user defined function may be defined with no arguments. Consider the function to accumulate words from input records for the text formatter: 

# function to add current line to parsed text
function add_line() {
    for ( i = 1 ; i <= NF ; i++ ) if ( length($i) ) addword($i);
}

In the case of a user-defined function with no arguments to be passed, the function may be invoked with no parenthesized parameter list. Consider the invocation of the add_line function in the text formatter. The action executed for input records which do not start with a format control word is: 

{
    if ( format ) add_line;
    else if ( table_f ) format_table($0);
    else output_line($0,FALSE);
}

In QTAwk, the add_line function may be invoked as "add_line" as above or as "add_line()", with a null length parameter list.

QTAwk has also relaxed the Awk rule that the left parenthesis of the parameter list must immediately follow a user-defined function invocation. QTAwk allows blanks between the name and the left parenthesis. The blanks are ignored.

Arrays and Used-Defined Functions

Just as arrays are integrated into QTAwk expressions, arrays are also integrated into the passing of arguments to, and the return value from, user-defined functions. Used-defined functions may return arrays as well as scalars. This will be illustrated in a sample utility later.

QTAwk passes scalar arguments to user-defined functions by value, i.e., if a scalar variable is specified as an argument to a function, a copy of the variable is passed to the function and not the variable itself. This is called pass by value. Thus, if the function alters the value of the argument, the variable is not altered, only the copy. When the function terminates, the copy is discarded, and the variable still retains its original value.

Note that arguments may be passed as constants, e.g., 4. QTAwk does not pass the constant literally, but creates a temporary variable with the desired constant value and passes the temporary variable to the function. The temporary variable is discarded by QTAwk on function termination. Thus, internal to the function the value of the temporary variable may be changed by the function, but any changes are discarded on function termination since the temporary variable is discarded.

In contrast, QTAwk passes array variables by "reference". This means that the local variable represented by the function argument, is the referenced variable and not a copy. Any changes to the local variable are actually made to the referenced variable.

In QTAwk, function arguments may also be constant arrays and not variable arrays, i.e., the argument may be the result of an arithmetic operation on an array. For example, if A is an array, then the result of the expression: 

"A + 10"

is an array. QTAwk creates a temprorary array variable and passes a reference to the temporary array as the function argument. The temporary variable is discarded at function termination.

QTAwk passes by reference under two conditions:

  1. The argument is a global or local array variable when the function is invoked,
  2. The argument is a global or local scalar variable when the function is invoked and at function termination the argument is an array. In this case, the argument may not have been directly referenced as an array, but may be the result of an operation involving an array. Alternatively the argument may have been passed to another function which referenced it as an array or set it to the result of operations on arrays.

    This second condition is patterned after the action of the first argument of the split function: 

    No_fields = split(strg,ary);

    Whatever value(s) the variable ary had when split is called, is discarded by the call and ary is an array when the function terminates.

    The same action can be acheived with a user-defined function.

The following QTAwk utility with a user-defined function will illustrate the use of arrays and scalars as function arguments and the return of arrays by user-defined functions. 

 1: BEGIN {
 2:     # create arrays 'a' and 'b'
 3:     for ( i = 1 ; i < 6 ; i++ ) a[i] = b[i] = i;
 4:     # create scalars 'c' and 'f'
 5:     c = f = 10;
 6:
 7:     # pass scalar variables/values and return scalar value
 8:     print "scalar : " >< set_var(c,c,c) >< " and c == " >< c;
 9:
10:     # pass two arrays, 'a' & 'b',
11:     # and one scalar constant, 'c+0'
12:     # function will return an array "== a + b + (c+0)"
13:     d = set_var(a,b,c+0);
14:     # print returned array 'd' (== a + b + (c+0))
15:     for ( i in d ) print "d[" >< i >< "] = " >< d[i];
16:     #print scalar 'c' to show unchanged
17:     print c;
18:
19:     # pass two arrays, 'a' & 'b',
20:     # and one scalar variable, 'c'
21:     # function will return an array "== a + b + c"
22:     e = set_var(a,b,c);
23:     # print returned array
24:     for ( i in e ) print "e[" >< i >< "] = " >< e[i];
25:     # print former scalar, 'c',
26:     # converted to array by operation c = b + 2;
27:     for ( i in c ) print "c[" >< i >< "] = " >< c[i];
28:
29:     # pass two arrays, 'a' & 'b', and constant array, 'b+0'
30:     h = set_var(a,b,b+0);
31:     # print returned array
32:     ( i in h ) print "h[" >< i >< "] = " >< h[i];
33:     # print array 'b' to assure that unchanged
34:     for ( i in b ) print "b[" >< i >< "] = " >< b[i];
35:     # attempt illegal operation in function: w = f + b
36:     #   adding array, 'b', to scalar, 'f'.
37:     # error message will be issued and execution halted
38:     g = set_var(f,b,f);
39: }
40:
41: function set_var(x,y,z) {
42:     # create local variable
43:     local w = x + y + z;
44:
45:     # alter third argument
46:     # if second argument an array,
47:     # this will convert third to an array
48:     # (if not already passed as an array).
49:     z = y + 2;
50:     return w;
51: }

This QTAwk utility illustrates several ideas in using arrays and user-defined functions in QTAwk. Line 8:

print "scalar : " >< set_var(c,c,c) >< " and c == " >< c;

calls the function 'set_var' with three scalar variables, all 'c'. Three copies of 'c' are actually passed. The local variable, 'w', is computed using scalar quantities and is a scalar quantity. Since argument 'y' is a scalar quantity, the result of the expression:

z = y + 2;

is a scalar and the third argument, 'c', is unchanged. A functional value of 30 (== c + c + c) is returned.

Line 13:

d = set_var(a,b,c+0);

passes arrays as the first and second arguments. The third argument is a constant scalar value, and thus QTAwk creates a temporary variable with a scalar value of c+0 which is passed to the function. Line 49 in the function:

z = y + 2;

changes the third argument internal to the function to an array. However, the third argument for this call is a temporary variable created when the call was made, and it is discarded at function termination.

The return value of the function, line 43:

w = x + y + z; (== a + b + 10;)

is an array. Line 15:

for ( i in d ) print "d[" >< i >< "] = " >< d[i];

prints the values of the array:


d[1] = 12
d[2] = 14
d[3] = 16
d[4] = 18
d[5] = 20

Line 22:

e = set_var(a,b,c);

passes arrays as the first and second arguments. The third argument is a variable, and thus can be changed by the function if the third argument at function termination is an array. The return value of the function:

w = x + y + z; # (== a + b + c;)

is an array as above. Note that at function termination, the third argument, c, is now an array since it was set to the result of an operation on an array, at line 49:

z = y + 2;

which is now equivalent to:

z = b + 2;

Thus, at function termination the scalar variable c has been converted to an array. Line 27:

for ( i in c ) print "c[" >< i >< "] = " >< c[i];

will print the values of the array elements:
c[1] = 3 ( == b[1] + 2)
c[2] = 4 ( == b[2] + 2)
c[3] = 5 ( == b[3] + 2)
c[4] = 6 ( == b[4] + 2)
c[5] = 7 ( == b[5] + 2)

Line 30:

h = set_var(a,b,b+0);

passes arrays as the first and second arguments. The third argument is a constant array. QTAwk creates a temporary variable to hold the constant array which is passed to the function. The return value of the function is an array as above. Note that at function termination, the third argument is again an array as above. However, the third argument has been passed as a temporary variable and it is discarded at function termination. Line 34:

for ( i in b ) print "b[" >< >< i"] = " >< b[i];

prints the array 'b' to assure that it was not changed.

Line 38:

g = set_var(f,b,f);

will result in an illegal operation in the function:

local w = x + y + z; (== f + b + f;)

this operation is now attempting to add an array to a scalar:

f + b

This operation will result in an error message and halt execution.

The above sample QTAwk utility illustrates the power of user-defined functions in automatically handling scalars and arrays as both arguments and return values and adjusting accordingly. The same function may be used interchangeably for both arrays and scalars with natural and predictable results.

Adding User-Defined Functions in Modules

There is another way to add user defined functions to a QTAwk utility, by dynamically linking modules, written in 'C', which are compiled and linked. The modules are then loaded at run-time by using the builtin function 'load_module'. Functions written in C in the loaded module may then be called just like any user defined function written in QTAwk. Such functions have the same properties and act just like a user defined function defined with the "function" pre-defined pattern keyword.

Writing such user defined functions in 'C' has at least three advantages:

  1. Operating System features not accessable under QTAwk are easily accessable through 'C' language programs. This makes such facilities accessable to QTAwk utilities.
  2. User defined functions written in 'C' and compiled and linked will run much faster than functions written in the QTAwk language which is interpreted at run-time.
  3. The functions may be dynamically loaded as needed and unloaded when no longer needed. The ability to unload such user defined functions gives the user the flexibility to write two or more modules which define the same user defined function. In this manner the actions of such a function may differ from input file to input file as desired.
If the user is reasonably proficient in 'C', writing such functions, compiling and linking them is not difficult. An example of one such module
written in 'C' is the sim_srev_mod.c. The script used to compile and link this module contains the necessary commands under Linux to prepare any module to be used to extend QTAwk. This script assumes that the QTAwk header file, QTAwk_plugins.h, is in the parent directory. If this is not true, simply change the command line:

gcc -shared -nostartfiles -c -g -I.. -o sim_srev.o sim_srev.c

changing the two periods following '-I' to the directory containing the header file. For example, if the header file is contained in the directory:

/usr/local/share/QTAwk/modules/

then change the command to:

gcc -shared -nostartfiles -c -g -I/usr/local/share/QTAwk/modules/ -o sim_srev.o sim_srev.c


The QTAwk utility, sim_srev.awk, can be run to load and execute the user defined functions defined in this module.

This module has three user defined functions:

  1. 'sim_srev_version' which takes no arguments and returns a version string. Such a function is not strictly necessary, but is recommended since it allows the QTAwk user to recognize which version of the user defined functions are contained in the loaded module. 
  2. 'sim_srev' which duplicates the action of the builtin function 'srev', and
  3. 'rev_caps' which translates uppercase characters to lowercase and lowercase characters to uppercase.
In addition there are two other 'C' functions:
  1. 'QTAwk_init_load_module' - the function called by the 'load-module' function to initialize the module and register the three user defined functions with QTAwk.
  2. 'sim_srev_exit' the function called by QTAwk when the module is unloaded. This function is not necessary, but can be included to cleanup any memory or other variables used in the module.
Studying this module, the user can discern that there are five parts to any module:
  1. The initialization part. This includes a function which calls two QTAwk functions to perform two tasks:
    1. QTAwk_register_function_count(3) -- This function call informs QTAwk of the number of user defined functions in the module which will be registered and which can thus be called from a QTAwk utility, and
    2. QTAwk_register_function("sim_srev_version",NULL,FALSE) - this function is called for each user defined function to "register". The function call specifies:
      1. the 'C' function name which is the same as the user defined function name. The 'C' function named will be linked as the user defined function. If the specified name is not fouind in the loaded module, a fatal error occurs.
      2. a pointer to a NULL terminated list  of pointers to strings which will be the argument names for calling the user defined function. If this pointer is NULL, then the user defined function will have no fixed argument.
      3. a boolean TRUE, 1, or FALSE, 0, value specifying whether the user defined function can have a variable number of arguments after any fixed arguments specified by argument 2. above.
    In addition, any initialization required for the functions in the module may be performed.

    The module initialization function may have any name desired by the user or the standard QTAwk module initialization function name:  'QTAwk_init_load_module'
    If no name is specified for the module initialization function in the 'load_module' builtin function call, then QTAwk will search the module for the standard name and link to it. If a name is specified in the 'load_module' call, then that function name is searched for when the module is loaded. If it is found, then the function specified is linked as the module initialization function. If no initialization function is found a fatal error occurs.
  2. An optional part which contains the function which is registered as a QTAwk user defined function which returns a version string or number for the module.
  3. The part of the module which contains the functions which act as the QTAwk user defined functions. Note that the 'C' language function names and the QTAwk user defined functions names are identical. This makes maintaining the functions easier. Also, note that there may be multiple user defined functions per module. It may be easier to group together functions into a single module which are related in their purpose.
  4. The exit part of the module. This part is optional.  It will be called by the QTAwk 'unload_module' builtin function before the module is unloaded from memory.

    The module exit function may have any name desired by the user or the standard QTAwk module exit function name:
    'QTAwk_exit_load_module'
    In the 'load_module' builtin function call, QTAwk will search the module for the standard name and link to it. If desired the user may use any name and register the name as the exit function by calling the 'QTAwk_set_module_exit_function' function specifying the name. QTAwk will search the module for the specified name and link to it.
  5. The module shutdown part. This part is also optional. It is slightly different from the exit part, in that the function registered here by the initialization function as the module shutdown function will be executed at normal program termination. T o register a module shutdown function, the initialization function must call the QTAwk function 'QTAwk_set_module_shutdown_function'. QTAwk will search the module for the function and link to it during initialization. Refer to the tmpfile.c module for an example of a shutdown function. In the tmpfile.c module, system services are called to create temporary files with filenames following a pattern specified by the calling QTAwk utility. The module returns the final filename to the calling QTAwk utility. If the module is not unloaded with the 'unload_module' function, then the module shutdown function is called at program termination. The module shutdown function then deletes all temporary files created.
The names of dynamic user defined functions to be loaded in modules do not become user defined function names until the appropriate module has been loaded and the functions registered with QTAwk. Until that occurs the names are regarded as simple variable names. Also, if the module is then unloaded, the names revert from user defined function names to variable names.

For example, if the name "combine_digits" is to be loaded in a module as a user defined function, then the following sequence:

combine_digits(param_1,param_2);
before the appropriate module is loaded is parsed as:
  1. a variable followed by
  2. a parenthesis enclosed list of expressions separated by the comma operator. The value of the expression list is the value of the last expression, param_2
The final result would be the concatenation of the string values of 'combine_digits' and the value of the expression list. After the module is loaded, this is then parsed as a call to the user defined function "combine_digits" with 2 arguments: param_1 and param_2.

Note that before the module is loaded, the variable "combine_digits" may be assigned a value. This value is retained after the module is loaded. It is also retained if the module is unloaded. If the value of a dynamically loaded user defined function name as a variable is desired when the appropriate module has been loaded, the builtin function 'ud_sym' may be used to obtain the value. Since the builtin function 'ud_sym' accesses the symbol table directly and is not parsed, the value of the symbol may be accessed at any time.

Executing the statement:
get_value = ud_sym("combine_digits");
Will assign the value of the variable "combine_digits" to the variable "get_value" even when the module defining "combine_digits" as a user defined function has been loaded.

This behavior has the advantage of allowing the QTAwk utility which dynamically loads and unloads modules to determine if a module is loaded and which version has been loaded. Studying the QTAwk utility, sim_srev.awk, you will notice that the utility sets and prints the value of the variable 'sim_srev_version' before the module is loaded. The statement:
print("Simulated 'srev' Module Version:",sim_srev_version);
is executed before the module is loaded, after the module is loaded and after the module has been unloaded. Running the utility, you will notice that before the module is loaded and after it has been unloaded, the output is "Not Installed". When the module is loaded the output is "Simulate 'srev' Module version 1.00".

To learn more about using modules in QTAwk, review the files included with the source code in the directory 'Plugins'. There are several examples of modules, the QTAwk utilities to use the modules and the shell scripts to compile and link the modules to produce the "*.so" files (under Linux) needed. In particular the following examples are included:

  1. ArraySeq_mod.awk, ArraySeq_mod.c, and ArraySeq_mod.sh
  2. dual_mods.awk
  3. exe_builtin.awk, exe_builtin.c, and exe_builtin.sh
  4. sim_srev.awk, sim_srev.c and sim_srev.sh
  5. time_mod.awk, time_mod.c and time_mod.sh
  6. var_args_mod.awk, var_args_mod.c and var_args_mod.sh
In writing a 'C' module, there are several QTAwk functions available to interact with QTAwk. The functions are explained in the QTAwk header file, QTAwk_plugins.h,  and listed in the table below. There are six 'C' types defined in the header file:
typedef long long int qta_long;
 This is a double long integer under "gcc". It is the natural representation of all QTAwk variable integer values.
typedef unsigned long long int qta_ulong;
 This is a double long unsigned integer under "gcc". It is the natural representation of all QTAwk variable unsigned integer values.
typedef struct var_inst *Variable_ptr;
 This a pointer to a QTAwk variable. Any such pointers returned to the user 'C' module functions should never be changed.
typedef struct QTAwk_index *QTAwk_index_ptr;
 This a pointer to the structure defined below for passing array indices to and from QTAwk
typedef union index_rep {
    unsigned long  numeric_index;   /* Numeric Index */
    unsigned char *char_index;      /* String  Index */
} index_rep;

 This is a union for storing either an integer or string index
typedef struct QTAwk_index {
    unsigned char  index_type;
    index_rep      index_rep;
} QTAwk_index;
 This is the structure containing the actual index and specifies the type of index stored.

QTAwk functions avaiable for use by 'C' functions in modules:
  1. QTAwk_register_function_count
  2. QTAwk_register_function
  3. QTAwk_set_module_exit_function
  4. QTAwk_set_module_shutdown_function
  5. QTAwk_get_argument
  6. QTAwk_get_value
  7. QTAwk_set_value
  8. QTAwk_get_type
  9. QTAwk_get_name
  10. QTAwk_get_named_variable
  11. QTAwk_get_variable_set
  12. QTAwk_get_local_variable_set
  13. QTAwk_assign
  14. QTAwk_dup
  15. QTAwk_execute_builtin_function
  16. QTAwk_true_false
  17. QTAwk_index_var
  18. QTAwk_create_array_element
  19. QTAwk_get_array_element
  20. QTAwk_get_indices
  21. QTAwk_first_array_element
  22. QTAwk_next_array_element
  23. QTAwk_array_finish
  24. QTAwk_array_delete
  25. QTAwk_get_field_var
  26. QTAwk_set_file
  27. QTAwk_close_file
  28. QTAwk_get_file
QTAwk_register_function_count
 prototype:
void              QTAwk_register_function_count(
unsigned       function_count);

Function to prepare to register dynamically loaded function names.

IMPORTANT: This function must be called prior to registering any user defined function via the next QTAwk function.

Called once before calling next function to register each function.

This call passes the number of functions to register.
This function is called by the 'initialization' function of a module loaded with the QTAwk built-in function:
'load_module'
QTAwk_register_function
 prototype:
unsigned char  *QTAwk_register_function(
unsigned char  *function_name,
unsigned char **argument_names,
unsigned        variable_arguments);

function to register function names loaded dynamically.
Call for each function loaded.
Returns:
  1. NULL --> function name successfully registered and available
  2. non-NULL pointer --> Error in registering function name. Pointer points to a string with the error message.
This function is called by the 'initialization' function of a module loaded with the QTAwk built-in function:
 'load_module'
When the 'load_module' built-in function is called, QTAwk has the file named in the first argument loaded into memory and linked with QTAwk. The function named in the second argument, which is in the module loaded, is called. That function then initializes the loaded module and must call this function to register with QTAwk each function name loaded. If this function is not called to register the function names, then none of the functions in the loaded module are known and cannot be called.

The arguments are:
  1.  function_name --> string containing the name of the function to be called.
  2. argument_names --> array of pointers to strings containing the names of the function arguments starting with the first argument and proceeding in order.  NULL terminated list.   Pass NULL for zero arguments or if all arguments are optional.
  3. variable_arguments --> if non-zero, then any arguments after the number specified by       'argument_names' are determined by the calling command. If  'argument_names' is NULL, then all arguments are optional.  The number of arguments actually used in the call is passed at run time.  This allows functions similar in calling sequence to the 'print' functions. The number of variable arguments passed is specified in the 'vargc' QTAwk  variable argument, and the arguments are array elements of the singly dimensioned 'vargv' QTAwk  variable argument. 'vargc' is passed as the first argument after the arguments specified in 'argument_names' and 'vargv' is the second argument after the arguments specified in 'argument_names'
When registered functions are called, all function arguments have been loaded into an array of QTAwk local variables. The registered function must use the 'QTAwk_get_argument' function to retrieve the arguments.

The registered function is called with one argument, an unsigned integer specifying the number of arguments which have been loaded into the array of local variables.

All registered functions are assumed to return a QTAwk variable, i.e., all registered functions are assumed to have a function prototype of:

  Variable_ptr registered_function(unsigned argument_count);

Returning a NULL pointer, is equivalent to returning no value to the calling QTAwk utility.

This function returns NULL if no error occurred in registering the function(s) or a pointer to an error string if an error occurred.

A module may be "unloaded" by calling the QTAwk built-in function:
  'unload_module'
All functions which have been registered for the module are automatically unregistered and the module unloaded from memory when 'unload_module' is called.
QTAwk_set_module_exit_function
 prototype:
void            QTAwk_set_module_exit_function(
unsigned char  *function_name);

This function registers the module exit function. If the exit function has the standard exit function name 'QTAwk_exit_load_module', then the function was found and linked automatically. If the user desires a different, unique name for the module exit function, then it must be registered using this function call in the initialization function.

The module exit function must have a prototype similar to the following:

unsigned QTAwk_exit_load_module(void);
QTAwk_set_module_shutdown_function
 prototype:
void            QTAwk_set_module_shutdown_function(
unsigned char  *function_name);

This function registers the module shutdown function. If the module is have a shutdown function, then it must be registered using this function call in the initialization function.

The module shutdow function is assumed to have a function prototype similar to:

void QTAwk_shutdown_function(void);

That is the shutdown function takes no arguments and returns no value.
QTAwk_get_argument
 prototype:
Variable_ptr   QTAwk_get_argument(
unsigned       arg_cnt,
unsigned char *arg_name);

QTAwk function to get argument for dynamically loaded function. May pass either the argument count (starting with 1 for first argument), or the argument variable name.

The variable name to be used is the name specified in the call to 'QTAwk_register_function'

Search by name takes precedence over search by count.
QTAwk_get_value
 prototype:
void          *QTAwk_get_value(
Variable_ptr   QTAwk_variable,
unsigned      *return_type);

QTAwk function to retrieve value of QTAwk variable. Use variable class defined constants in the header file to specify value desired. The available constants are:
NO_VAL
 No assigned value. Initialized to zero and the null string.
REGEXP_VAL
 regular expression type
STRING_VAL
 string type
STRING_INT
 string representing a single integer value. Assigned automatically by QTAwk
STRING_FLT
 string representing a single floating point value. Assigned automatically by QTAwk
CHAR_VAL
 single character type
LONG_VAL
 QTAwk integer type, define in header file as 'qta_long' type
DOUBLE_VAL
 floating point type

The function returns a pointer to 'void' type which must be cast to the type specified in the call.

The following value types all return an 'unsigned char *', i.e., a pointer to string value:
  1. REGEXP_VAL
  2. STRING_VAL
  3. STRING_INT
  4. STRING_FLT
The "CHAR_VAL" type returns an "unsigned char *" value.

The "LONG_VAL" returns a pointer to a "qta_long" value defined under Linux as "long long int *", "qta_log *"

The "DOUBLE_VAL" returns a pointer to a "double" value, "double *"

Cast the return pointer to a pointer to the desired type and copy the value to local memory. The memory used for the return value WILL be overwritten by subsequent calls.

NOTE: if the return type is specified as "NO_VAL", then the value returned is whatever type the QTAwk variable already is and 'return_type' is set to the appropriate type value. This is one method of ascertaining the type of a QTAwk variable. The 'QTAwk_get_type' function is a better way.

If the QTAwk variable is not of the type requested, then it is converted to that type following the QTAwk normal rules for conversion.
QTAwk_set_value
 prototype:
Variable_ptr   QTAwk_set_value(
Variable_ptr   QTAwk_variable,
void const    *value,
unsigned       set_type);

QTAwk function to set QTAwk variable value. Any previous variable values are discarded.

The first argument is the QTAwk variable to set.

The second argument is a pointer to the value (caller casts to a "void *").

The third argument is one of the variable class constants defined above and in the QTAwk header file
If one of the following string types is used:
  1. REGEXP_VAL
  2. STRING_VAL
  3. STRING_INT
  4. STRING_FLT
The string value is copied and the value of the variable is set to the copy.

If a type of "NO_VAL" is specified, the variable is initialized to a value of the null string and a zero integral value.

Also see the QTAwk function 'QTAwk_assign' for assigning the value of one variable to another.
QTAwk_get_type
 prototype:
unsigned       QTAwk_get_type(
Variable_ptr   QTAwk_variable);

QTAwk function for determining the type of a QTAwk variable. The return value is an unsigned integer value for one of the type constants defined above:
  1. NO_VAL
  2. REGEXP_VAL
  3. STRING_VAL
  4. STRING_INT
  5. STRING_FLT
  6. CHAR_VAL
  7. LONG_VAL
  8. DOUBLE_VAL
QTAwk_get_name
 prototype:
unsigned char *QTAwk_get_name(
Variable_ptr   QTAwk_variable);

QTAwk function to get the name of the specified variable.

Return a pointer to unsigned char.

The returned value is a copy of the variable name and the memory has been allocated by a call to 'calloc'.

The calling function must ensure that the memory is released when no longer needed.
QTAwk_get_named_variable
 prototype:
Variable_ptr   QTAwk_get_named_variable(
unsigned char *variable_name);

QTAwk function to get the named variable specified. The name specified may be any built-in variable or variable named by the user utility.

Note that local variable names are searched first, then global names. Note that "local" names are those 'local' to the braced statement within which the dynamically loaded user function is called.

NOTE: If a local or global variable with the specified name does not exist a global variable with the specified name will be created.
QTAwk_get_variable_set
 prototype:
Variable_ptr   QTAwk_get_variable_set(
void const    *value,
unsigned       set_type);

QTAwk function to get a QTAwk variable initialized to a specified value. The returned variable is assigned the value specified, c.f., 'QTAwk_set_value' function call for the the values that may be used for the first and second arguments.

If a type of "NO_VAL" is specifed, this call returns an initialized variable set set to zero

This is a "temporary" variable. This variable will disappear "magically" when the dynamically loaded user function returns.

An illustration of this function can be found in the moules:
  1. ArraySeq_mod.c
  2. exe_builtin_mod.c
  3. sim_srev.c
  4. time_mod.c
  5. var_args_mod.c
QTAwk_get_local_variable_set
 prototype:
Variable_ptr   QTAwk_get_local_variable_set(
unsigned char *vname,
void const    *value,
unsigned       set_type);

QTAwk function top get a 'local' variable. The returned variable is local to the calling dynamically loaded user function - identical to using the "local" keyword. The Variable will be "lost" when the function returns.

Note: the variable MUST be named, i.e., a non-NULL value must be passed for the first argument, 'vname'

This variable will disappear "magically" when the dynamically loaded user function returns.
QTAwk_assign
 prototype:
Variable_ptr   QTAwk_assign(
Variable_ptr   QTAwk_l_variable,
Variable_ptr   QTAwk_r_variable);

QTAwk function to set the value of one QTAwk variable to another QTAwk variable.

Assign the value of QTAwk_r_variable to QTAwk_l_variable.
Equivalent to:
   QTAwk_l_variable = QTAwk_r_variable;
QTAwk_dup
 prototype:
Variable_ptr   QTAwk_dup(
Variable_ptr   QTAwk_variable);

QTAwk function to duplicate a QTAwk variable. The specified variable value is duplicated and returned. Note that the duplicate variable is NOT named even if the duplicated variable is named.

An illustration of this function can be found in the module exe_builtin_mod.c
QTAwk_execute_builtin_function
 prototype:
Variable_ptr   QTAwk_execute_builtin_function(
unsigned       function_number,
unsigned       argument_count,
               ...);

QTAwk function to execute a specified built-in function.
 
Returns a pointer to a QTAwk variable.

The first argument is one of the defined function constants defined in the QTAwk header file.

The second argument is the number of QTAwk variables following the count in the call which are passed to the desired builtin function.

The arguments for the builtin function are then the remaining arguments in the call.  All of these arguments are QTAwk variables.

ALWAYS put a NULL argument at the end of the argument list to signal the end.

DO NOT include the terminating NULL pointer in the argument count in the second argument.

All built-in functions except 'sub', 'gsub' and 'gensub' may be called.

An illustration of this function can be found in the module exe_builtin_mod.c
QTAwk_true_false
 prototype:
unsigned       QTAwk_true_false(
Variable_ptr   QTAwk_variable);

QTAwk function to determine and return the boolean value of the specified QTAwk variable.

Returns:
  1. 1 for TRUE
  2. 0 for FALSE
QTAwk_index_var
 prototype:
int            QTAwk_index_var(
Variable_ptr   QTAwk_variable,
unsigned      *index_levels);

QTAwk function to determine if variable indexed.
 Returns:
  1. -1 --> variable NOT indexed
  2. 0 --> indexed variable and base variable
  3. index --> integer specifying the number of indices
Examples:
Assume the following QTAwk variables
    var1 is unindexed, i.e., a scalar
    var2 is indexed and has three levels of indices, e.g., var2[3][2][4]
 Then the following calls return the values indicated:
 QTAwk_index_var(var1,&index_lvl) == -1             index_lvl == 0
 QTAwk_index_var(var2,&index_lvl) == 0              index_lvl == 3
 QTAwk_index_var(var2[1],&index_lvl) == 1           index_lvl == 3
 QTAwk_index_var(var2[1][2],&index_lvl) == 2        index_lvl == 3
 QTAwk_index_var(var2[1][2][2],&index_lvl) == 3     index_lvl == 3

Using the functions 'QTAwk_get_named_variable' and 'QTAwk_get_array_element' and
 'var3' is a variable declared in the module function:
Variable_ptr var3;
qta_long lcl_long = 3;

var3 = QTAwk_get_local_variable_set("tvar",(void *)&lcl_long,LONG_VAL);
QTAwk_index_var(var3,&index_lvl) == -1   index_lvl = 0
var3 =  QTAwk_get_named_variable("var2");
QTAwk_index_var(var3,&index_lvl) == 0    index_lvl = 3
var3 = QTAwk_get_array_element(var3,"n",1); // retrieves var2[1]
QTAwk_index_var(var3,&index_lvl) == 1    index_lvl = 3
var3 = QTAwk_get_array_element(var3,"nn",1,2); // retrieves var2[1][2]
QTAwk_index_var(var3,&index_lvl) == 2    index_lvl = 3
var3 = QTAwk_get_array_element(var3,"nnn",1,2,2); // retrieves var2[1][2][2]
QTAwk_index_var(var3,&index_lvl) == 3    index_lvl = 3

The second argument returns the number of index levels for the variable, e.g., if var2 above is a 3x3 matrix, then 3 is returned in all the above calls.

NOTE: since QTAwk uses "sparse" arrays, the returned value in the second argument can vary with calls using diferent array elements within the same array.
QTAwk_create_array_element
 prototype:
unsigned       QTAwk_create_array_element(
Variable_ptr   QTAwk_variable,
void          *value,
unsigned       set_type,
unsigned char *index_str,
               ...);

QTAwk function to create an array element. The indices are specified in the calling arguments. The arguments are:
  1. Variable_ptr   QTAwk_variable --> the base array variable
  2. void          *value          --> pointer to desired value 
  3. unsigned       set_type       --> integer specifying value type
  4. unsigned char *index_str      --> string indicating types of indices (case ignored)
    • n or N == integer index
    • s or S == string index
  5. index_1
  6. index_2
  7. .
  8. .
  9. .
 For Example, to create an array element with both integer and string indices, the first index being integer, 2, the second index being a string, "State", and the third index being an integer, 35. We would have the following calling arguments:
  QTAwk_create_array_element(var,val,type,"nsn",2,"State",35);

Returns 1, TRUE, if element successfully created, 0, FALSE, otherwise.

An illustration of this function can be found in the module time_mod.c the QTAwk utility to execute is in time_mod.awk and the shell script to compile and link is in time_mod.sh.
QTAwk_get_array_element
 prototype:
Variable_ptr   QTAwk_get_array_element(
Variable_ptr   QTAwk_variable,
unsigned char *index_str,
               ...);

QTAwk function to get an array element. The indices are specified in the calling arguments. The arguments are:
  1. Variable_ptr   QTAwk_variable --> the base array variable 
  2. unsigned char *index_str      --> string indicating types of indices (case ignored) 
    • n == integer index
    • s == string index  
  3. index_1
  4. index_2
  5. .
  6. .
  7. .
 An illustration of this function can be found in the modules:
  1. exe_builtin_mod.c
  2. time_mod.c
  3. var_args_mod.c
QTAwk_get_indices
 prototype:
QTAwk_index_ptr  QTAwk_get_indices(
Variable_ptr     QTAwk_variable,
unsigned        *index_count);

QTAwk function to return array indices for variable specified

Integer returned in second argument, index_count, spcifies the number of indices used to specify the array element passed,

For example if the array has been created using:
     tmp_variable = varray[2]["State"][35]
then:
     QTAwk_get_indices(tmp_variable,&index_lvl);
then the return value is a pointer to an array of index structures with index_lvl set to 2.

The return value is an array of index structures defined above. The memory has been allocated by a call to 'calloc' and the user function must free the memory when the structure array is no longer needed.

An illustration of this function can be found in the module ArraySeq_mod.c
QTAwk_first_array_element
 prototype:
Variable_ptr            QTAwk_first_array_element(
Variable_ptr            QTAwk_variable,
unsigned                 *sequence_state,
QTAwk_index_ptr   Index);

This function and the next two are QTAwk functions to sequence over array elements. They are similar to the statement:
for ( i in array )
To execute call function:
     sequence_state = QTAwk_first_array_element(QTAwk_variable,&seqstate,Index)
then call function:
    array_variable = QTAwk_next_array_element(sequence_state,Index)
This is the QTAwk function to initialize the array element sequence function and return the first array element. Returns NULL if variable not indexed. Call with the variable at which to start the index sequencing. The module ArraySeq_mod.c illustrates the use of these functions. The script, ArraySeq_mod.sh, illustrates compiling and linking the module and the QTAwk utility, ArraySeq.awk, illustrates loading and executing the functions defined.

The index sequencing will be at the next level of index, e.g., assuming 'ar' is a 3x3 matrix, calling with 'ar' would sequence through the elements ar[1], ar[2], ar[3] and calling with ar[1] would sequence through the elements ar[1][1] ar[1][2] ar[1][3].

If there is no next level of index, this function returns zero, 0.

Thus, the above two call is similar to the statements:
 for ( i in ar )
     for ( j in ar[i] ) print(ar[i][j]);

This function will a QTAwk variable and an unsigned integer in the second argument.

IMPORTANT: DO NOT change the value of this integer,

This integer will be passed to the two sequencing functions below.
QTAwk_next_array_element
 prototype:
Variable_ptr             QTAwk_next_array_element(
unsigned                   sequence_state,
QTAwk_index_ptr   Index);

QTAwk function to sequence through variable indices. Called with 2 arguments:
  1. sequence_state: integer value set in the 'QTAwk_first_array_element' function parameter.
  2. Index: pointer to Index structure to return index value of element returned.
This function returns a pointer to the QTAwk variable which is the next array element or NULL if no more elements.
QTAwk_array_finish
 prototype:
void      QTAwk_array_finish(
unsigned  sequence_state);

ALWAYS call this function when finished sequencing through an array. This is Especially necessary if the last call to 'QTAwk_next_array_element' in the sequencing has not returned a NULL value.

NOTE: call after using obtaining the value of the last element returned. If called before obtaining the value by a  call to 'QTAwk_get_value', then the value returned will be zero, 0, or the null string.
QTAwk_array_delete
 prototype:
void             QTAwk_array_delete(
Variable_ptr     QTAwk_variable);

QTAwk function to delete array element or all of array. The same as the QTAwk statement:
delete QTAwk_variable;
QTAwk_get_field_var
 prototype:
Variable_ptr QTAwk_get_field_var(
int          f_index);

QTAwk function to retrieve field variable of current input record.

IMPORTANT: DO NOT directly change any values of the variable. ALWAYS use the 'QTAwk_assign' or the 'QTAwk_set_value' functions to change the value.

f_index specifies the field variable desired and corresponds to '$f_index'
QTAwk_set_file
 prototype:
unsigned char *QTAwk_set_file(
unsigned char *fname,
FILE               *ofile,
file_modes        mode,
unsigned           error_flag,
unsigned char *error_msg);

Call this function to set/open a file for use in a QTAwk script.

Called with 5 arguments:
  1. fname - The full filename, including path if not in the current directory, of the file to open.
  2. ofile - a pointer to an open stream or NULL. If the module function has already opened the desired file, then this pointer designates the stream to associate with the filename. If NULL, then QTAwk will open the file in the mode specified by the next argument. NOTE: the module function MUST open the file in the mode specified by the next argument.
  3. mode - the mode in which to open the file, or the mode in which the file has been opened.
    The mode specified must be one from the  'file_modes' enum type defined in the QTAwk_plugins.h header file. The available types are:
    READ_FILES
    		 Use this mode if the file is opened for reading only.
    WRITE_FILES
    		 Use this mode if the file is opened for writing only.
    APPEND_FILE
    		 Use this mode if the file is to be opened for writing/appending to the end of the file.
    READ_BINARY_FILES
    		 Use this mode if the file is opened for writing only. NOTE: under Linux, this mode is identical to READ_FILES
    WRITE_BINARY_FILES
    		 Use this mode if the file is opened for writing only. NOTE: under Linux, this mode is identical to READ_FILES
    APPEND_BINARY_FILE
    		 Use this mode if the file is to be opened for writing/appending to the end of the file. NOTE: under Linux, this mode is identical to READ_FILES

  4. error_flag - if non-zero, QTAwk will halt on an error in opening the specified file in the specified mode. The non-zero value will be the return value to the system.
  5. error_msg - if 'error-flag' is non-zero and an error occurrs in openeing the specified file in the specified mode, this text will be displayed before exiting.

This functions returns a string by whiich the file is known in QTAwk, namely the string value of the first argument.
QTAwk_close_file
 prototype:
int                     QTAwk_close_file(
unsigned char *fname);

Call this function to close an open file - normally used to close file opened by function 'QTAwk_set_file', but can close any file currently open for reading/writing by QTAwk. Note this function will not close pipes.

Called with one argument, the string by which QTAwk knows the desired file. If called to close a file opened by 'QTAwk_set_file', this string is the return value of that function.
QTAwk_get_file
 prototype:
FILE              *QTAwk_get_file(
unsigned char *fname,
file_modes       *mode);

Call this function to get a file known to the QTAwk script.

Returns a pointer to the stream for the file or NULL if the ile is not known.

2 arguments:
  1. fname - the string by which QTAwk knows the desired file. If called to close a file opened by 'QTAwk_set_file', this string is the return value of that function.
  2. mode - a pointer to 'file_modes' variable. The mode of the file is returned in this pointer. Only the values 'READ_FILES' or 'WRITE_FILES' are returned. This call makes no distinction between files opened for writing and files opened for writing at the end, appending.

Useful Included Modules
Some modules are included with QTAwk besides those above which demonstrate the use of modules. These modules are detailed here.

Note that the 'strtoint_module' demonstrates an easy way to import some of the powerful C library functions into QTAwk. Following the template of the 'strtoint_module', the user can implement a module to call any of the C library functions and thus make that function immediately available in QTAwk. For example, a module could implement one or more of the powerful collating functions in the library, or one or more of the string searching functions. The 'tmpfile_mod', 'cpu.time_module', and 'system.info_module' modules demonstrate how system calls may be made immediately available to QTAwk.
tmpfile_mod
 Files:
  1. tmpfile_mod.c - C source file
  2. tmpfile_mod.sh - shell script to compile and link
  3. tmpfile_mod.so - loadable module

This adds a user defined function to create a temporary file. It uses the operating system call to create the filename. It defines the user defined function: tempfile(filepattern). The call to the system function creates the temporary file following the pattern specified, including any directory path specified in the pattern. NOTE: the temporary filename will be created by appending 6 unique characters to the end of the pattern specified. The file willbe opened and then closed to ensure that the name is available for use and cannot be used by any other process. The module will keep a record of any filenames created and the module shutdown function will automatically delete all temporary files created by calls to the user defined function.

User defined functions:
  1. tempfile(file_pattern) - File_pattern is a string pattern for the filename desired. Function returns a full filename for a temporary file. The file has been opened and closed and so already exists.
Version Function: tmpfile_mod_version()

The "exit" function, called when the module is unloaded, frees memory used by the function and removes any temporary files created. The user must ensure that any temporary files are no longer open and will not be use further.

The "shutdown" function, called when QTAwk exits, is the same function as the "exit" function.
secure_hash_module Files:
  1. defines.h - useful definitions
  2. protos.sh - shell script for producing the prototypes files
  3. secure_hash.awk - QTAwk script with "BEGIN" predefined pattern defining constants defining the secure hash types and which loads the secure_hash_module.so file
  4. secure_hash_module.c - main C source file. Also contains the source for the Secure Hash Algorithm hashes
  5. Secure_hash_module.sh - shell script to compile and link the secure hash module
  6. secure_hash_module.so - loadable secure hash module
  7. secure_hash_proto.h - prototype file
  8. secure_hash_static_proto.h - static function prototype file
  9. secure_hash_test.awk - QTAwk script for testing the secure hash module
  10. shs.h - C header file
  11. shsmac.h - C header file
  12. stdfun.h - C header file
  13. tiger.c - C source for the Tiger 192 bit hash
  14. tiger_sboxes.h- C header file
  15. Whirlpool.c - C source file for the Whirlpool 512 bit hash
  16. whirlpool.h - C header file
Associated script files that are to be used in conjuction with the loadable module:
  1. secure_hash.awk - this file contains a single "BEGIN" Pattern/Action  pair and a single "END" Pattern/Actiion pair. The BEGIN action defines the following constants and executes the 'load_module' builtin function to load the secure hash module:
    1. SHA_HASH_160  == 1 -->  # 160 bit Secure Hash FIPS 180-2 , 2002, August 1 
    2. SHA_HASH_224  == 2 -->  # 224 bit Secure Hash FIPS 180-2 , 2002, August 1
    3. SHA_HASH_256  == 3 -->  # 256 bit Secure Hash FIPS 180-2 , 2002, August 1
    4. SHA_HASH_384  == 4 -->  # 384 bit Secure Hash FIPS 180-2 , 2002, August 1
    5. SHA_HASH_512  == 5 -->  # 512 bit Secure Hash FIPS 180-2 , 2002, August 1
    6. RMD_HASH         == 6 -->  # RIPEMD 160 bit Hash
    7. WHIRLPOOL_H  == 7 -->  # Whirlpool 512 bit secure hash
    8. TIGER_HASH      == 8 -->  # Tiger 192 bit secure hash
    The END action unloads the secure hash module.
This file should be "included" in the file which will utilize the secure hashes.

User defined functions:
  1. HASH_Init(Hash_Type) - call this function to initiate a secure hash. 'Hash_Type' is one of the constants defined in the "secure_hash.awk" file. This function returns an integer value, 'Hash_Cnt', which is used in the functions below for updating and finalizing the secure hash initialized here. Using the "Hash_Cnt' return value to indicate the hash allows multiple hashes to be initialized, updated and finalized.

    A return value of zero, 0, indicates an error, usually an improper value for 'Hash_Type'.
  2. HASH_Update(Hash_Cnt,String_to_Hash,bytecount) - update the hash value using the string passed. Parameters are:
    1. Hash_Cnt - an integer value returned by "HASH_Init" specifying the hash to be updated.
    2. String_to_Hash - string used to update the hash value.
    3. bytecount - the length of the string in parameter 2.
  3. HASH_Final(Hash_Cnt) - Finalize the hash. Add the total length of the vaules hashed and round out the hash to a multiple of the hash buffer. The single parameter, Hash_Cnt, specifies the hash finalizing and is the return value of the 'HASH_Init' function. After a hash has been finalized, it can no longer be updated.
  4. HASH_copy(Hash_Cnt) - copy the hash specified. Return an integer value specifying the new hash. This function may be used if a hash must be finalized for an intermediate result, and then continue updating the original (or the copy).
  5. HASH_Cmp(Hash_Cnt1,Hash_Cnt2) - Compare two hashes for equality. Two parameters:
    1. Hash_Cnt1 - the integer value specifies the first hash for comparison.
    2. Hash_Cnt2 - the integer value specifies the second hash for comparison.
    Returns an integer boolean value, TRUE or FALSE.
  6. HASH_Wrd(Hash_Cnt,Hash_Wrd) - Return the value of the specified word of the hash specified. Two parameter:
    1. Hash_Cnt - the inetger value specifying the hash
    2. Hash_Wrd - integer value specifying the word desired. Greater than or equal to 1. If greater than the number of words in the hash, then the value is used modulo the number of words in the hash. For:
      1. 160 bit hash: 1 <= Hash_Wrd <= 5 (32 bit words)
      2. 192 bit hash: 1 <= Hash_Wrd <= 6 (32 bit words)
      3. 224 bit hash: 1 <= Hash_Wrd <= 7 (32 bit words)
      4. 256 bit hash: 1 <= Hash_Wrd <= 8 (32 bit words)
      5. 384 bit hash: 1 <= Hash_Wrd <= 6 (64 bit words)
      6. 512 bit hash: 1 <= Hash_Wrd <= 8 (64 bit words)
  7. HASH_Num_Words(Hash_Cnt) - returns the number of words in the hash specified by 'Hash_Cnt'
  8. HASH_Bits(Hash_Cnt) - returns the number of bits in the hash specified by 'Hash_Cnt'
  9. HASH_Type(Hash_Cnt) - returns the hash type of the hash specified by 'Hash_Cnt'. A value between 1 and 8 corresponding to the integer constants defined above.
  10. HASH_Status(Hash_Cnt) - returns a TRUE or FALSE value depending on whether the hash specified by 'Hash_Cnt' has been finalized.
  11. HASH_Free(Hash_Cnt) - free the hash specified by 'Hash_Cnt'. Once "freed", it can no longer be updated, finalized or referenced.
  12. calc_file_HASH(filename,Hash_Cnt,Hash_Type,make_final) - Calculate the hash value for the file specified. Four parameters:
    1. filename - the filename of the file for which to calculate the hash value.
    2. Hash_Cnt - if zero, 0, then initialize a new hash and update the hash value using the contents of the file specified by 1. If non-zero, then assume the value is an integer value specifying a hash to be updated using the contents of the file specified. If hashing a string before hashing a file, Hash_Cnt would specify the hash initialized and updated with the string. If more than one file is to be incorporated into the hash, Hash_Cnt would be zero for the first file and then equal to the return value for the remaining file(s).
    3. Hash_Type - an integer value equal to one of the hash type constants defined above. Used only if Hash_Cnt in 2. is zero, 0.
    4. make_final - if a TRUE value, i.e., a non-zero numeric value or a non-null string, then the hash computed or updated is finalized. If FALSE, the hash is not finalized. If you desire to incorporate the contebnts of more than one file into the hash value, set this parameter to FALSE for all but the last file. Alternatively, a FALSE value may be used for all files, and the "HASH_Final" function used to finalize the hash values.  The later approach must be used if a string value is to added to the hash value after the last file.
    Return an integer value. If Hash_cnt is zero, 0, then return a unique integer specifying the hash. If Hash_Cnt is non-zero, then return Hash_Cnt.
  13. HASH_to_Str(Hash_Cnt) - convert the hash specified by Hash_Cnt to a hexadecimal string. The first byte of the string is equal to the integer value of the hash type of the hash, i.e., the value of one of the hsh type constants defined above. The hash is finalized prio to conversion if not already finalized.
  14. Str_to_HASH(hash_string) - convert the string passed to a finalized hash. Return an integer value specifying the hash.
  15. init_hash_array(hash_string) - initialize a set of hashes. The hashes to be used are specified by the string passed. Each byte of the string if used (modulo TIGER_HASH) + 1, yielding a value between 1 and 8. The number of hashes initialized is equal to the length of the string passed. Any hash may be specified more that once, but specifying any hash more than once is needless redundancy. Any 8 consecutive ASCII value bytes may be used to specify the hashes. Thus, the following strings are resonable strings to use:
    • "abcdefgh" --> specifies integer values:  2,3,4,5,6,7,8,1
    • "bcdefghi" --> specifies integer values:  3,4,5,6,7,8,1,2
    • "01234567" --> specifies integer values: 1,2,3,4,5,6,7,8
    • "12345678" --> specifies integer values: 2,3,4,5,6,7,8,1
    • "ABCDEFGH" --> specifies integer values: 2,3,4,5,6,7,8,1
    • "nopqrstu" --> specifies integer values: 7,8,1,2,3,4,5,6
    By specifying consecutive ASCII values in this manner, the order of the hashes in the set can be randomized.

    Returns an integer value specifying the hash set initialized. This integer value is distinct from the integer value return by the "HASH_Init" function even if the two returns values may be equal.
  16. update_hash_array(Hash_Cnt,String_to_Hash,bytecount) - Update the set of hashes specified. Three parameters:
    1. Hash_Cnt - an integer value returned by "init_hash_array" specifying the hash set to be updated.
    2. String_to_Hash - string used to update the values of the hashes in the set.
    3. bytecount - length of the string passed in parameter 2.
  17. finalize_hash_array(Hash_Cnt) - Finalize the set of hashes specified. Once finalized, the hashes can no longer be updated.
  18. free_hash_array(Hash_Cnt) - Free memory utilized by the set of hashes specified.
  19. copy_hash_array(Hash_Cnt1,Hash_Cnt2) - copy the set of hashes specified to another set. Return an integer value specifying the new set of hashes. This function may be used if a hash set must be finalized for an intermediate result, and then continue updating the original (or the copy).
  20. calc_file_hash_array(filename,Hash_Cnt,hash_string,make_final) - This function is the same as the "calc_file_HASH" function except that the values for the set of hashes specified in "Hash_Type" is used. Hash_Type is a string as described for "init_hash_array".
  21. comp_hash_array(Hash_Cnt1,Hash_Cnt2) - compare two set of hashes.
  22. array_HASH_to_Str(Hash_Cnt) - convert the set of hashes specified to a set of hexadecimal strings. Return a QTAwk array variable. The array is indexed by integers starting with 1. The value of each array element is the hexadecimal string of the corresponding hash in the hash set. The first byte of each hexadecimal string is equal to the value of the integral hash type.
Version function: Secure_Hashes_Version()

"exit" and "shutdown" functions are the same function and free memory used by the above functions.
cpu.time_module Files:
  1. cpu.time_module.c - C source file
  2. cpu.time_module.sh - shell script to compile and link
  3. cpu.time_module.so - loadable module

Module starts/stops the CPU timer and returns the elapsed time for the QTAwk process and returns the clock ticks for the QTAwk process.

User defined functions:
  1. _CPU_start_time() - function to start the CPU elapsed timer. Up to 20 timers available. Returns an integer specifying the timer started.
  2. _CPU_stop_time(start_count) - return the elapsed time for the timer specified. The time is returned as whole seconds.
  3. _CPU_times(start_count) - return an array with the clocks tics and elapsed CPU time. The array returned has the following indices and values:
    Index string value
    		 Array element value
    clock_tics_per_second integer value specifying the number of CPU clocks ticks per second
    start_time
    		 elapsed CPU time on timer specified by 'start_count' parameter. The same value as would be returned by the "_CPU_stop_time" function. If 'start_count' not a valid timeer or zero, this array element omitted.
    tm_utime This is the total processor time the calling process has used in executing the instructions of the QTAwk process.
    tm_stime This is the processor time the system has used on behalf of the QTAwk process.
    tm_cstime
    		 This is similar to `tms_cutime', but represents the total processor time system has used on behalf of all the terminated child processes of the QTAwk process.
    tm_cutime
    		 This is the sum of the `tms_utime' values and the `tms_cutime' values of all terminated child processes of the QTAwk process, whose status has been reported to the QTAwk process by `wait' or `waitpid'.  In other words, it represents the total processor time used in executing the instructions of all the terminated child processes of the QTAwk process, excluding child processes which have not yet been reported by `wait' or `waitpid'.

Version function: _CPU_time_module_version()

No "exit" function.

No "shutdown" function.
strtoint_module Files:
  1. strtoint_module.c - C source file
  2. strtoint_module.sh - shell script to compile and link
  3. strtoint_module.so - loadable module
  4. strtoint.awk - QTAwk script to demonstrate module function
This module provides the functionality of the C standard library function of the same name.

User defined functions:
  1. strtoint(string,base) - The `strtol' ("string-to-long") function converts the initial part of STRING to a signed integer, which is returned as an integral value.
    This function attempts to decompose STRING as follows:
    • A (possibly empty) sequence of whitespace characters.  Which characters are whitespace is determined by the `isspace' function ( Classification of Characters).  These are discarded.
    • An optional plus or minus sign (`+' or `-').
    • A nonempty sequence of digits in the radix specified by BASE.
      If BASE is zero, decimal radix is assumed unless the series of digits begins with `0' (specifying octal radix), or `0x' or `0X' (specifying hexadecimal radix); in other words, the same syntax used for integer constants in C.
      Otherwise BASE must have a value between `2' and `36'.  If BASE is `16', the digits may optionally be preceded by `0x' or `0X'.  If base has no legal value the value returned is an error string.

      This function is not necessary for QTAwk for the octal, decimal and hexadecimal bases since QTAwk converts strings to numeric in those bases automatically. However, for converting strings such as "abcdef" in base 36 to a decimal numeric, this function is useful.
    • Any remaining characters in the string.

    If the string is empty, contains only whitespace, or does not contain an initial substring that has the expected syntax for an integer in the specified BASE, no conversion is performed.  In this case, `strtoint' returns a value of zero, 0.

    In a locale other than the standard `"C"' locale, this function may recognize additional implementation-dependent syntax.

    If the string has valid syntax for an integer but the value is not representable because of overflow, `strtoint' returns an error string.
It is probably best to check the type of the return value with the 'e_type' builtin function. If a string type is returned, return value of 2 (an integral value would have a type of 6), then an error in the conversion has been encountered.

The "strtoint.awk" QTAwkscript illustrates checking for conversion errors and printing the error string if an error occurs.

Function returns the integer conversion value or an error string if

Version function: strtoint_version()

No "exit" function.

No "shutdown" function.
system.info_module Files:
  1. system.info_module.c - C source file
  2. system.info_module.sh - shell script to compile and link
  3. system.info_module.so - loadable module
Version function: system_info_module_version()

This module supplies system information: Operating system, machine, host name, etc.

User defined functions:
  1. get_sys_info() - returns a singly dimensioned array:
    string index value
    		 element value
    System.Name
    		 This is the name of the operating system in use.
    release
    		 This is the current release level of the operating system implementation.
    version
    		 This is the current version level within the release of the operating system.
    machine
    		 This is a description of the type of hardware that is in use.

    GNU uses a three-part name to describe a system configuration; the three parts are CPU, MANUFACTURER and SYSTEM-TYPE, and they are separated with dashes.  Any          possible combination of three names is potentially meaningful, but most such combinations are meaningless in practice and even the meaningful ones are not necessarily supported by any particular GNU program.

    Since the value in `machine' is supposed to describe just the hardware, it consists of the first two parts of the configuration name: `CPU-MANUFACTURER'
    nodename
    		 This is the host name of this particular computer.  In the GNU C library, the value is the same as that returned by 'gethostname'
    hostname
    		 This is the NIS or YP domain name.
    1_min_load_average
    		 1 minute load average
    5_min_load_average
    		 5 minute load average
    15_min_load_average
    		 15 minute load average
    totalram
    		 Total usable main memory size
    freeram
    		 Available memory size
    sharedram
    		 Amount of shared memory
    bufferram
    		 Memory used by buffers
    totalswap
    		 Total swap space size
    freeswap
    		 swap space still available
    procs
    		 Number of current processes
    totalhigh
    		 Total high memory size
    freehigh
    		 Available high memory size
    mem_unit
    		 Memory unit size in bytes

No "exit" function.

No "shutdown" function.
format_module
 Files:
  1. format_module.c - C source file
  2. format_module.sh - shell script to compile and link
  3. format_module.so - loadable module
This modules replaces the previous builtin "justify" function.
User defined fnctions:
  1. justify(words,number_words,width[,pad_character]) - This user defined function replaces the previous builtin function of the same name and functionality.

    This function forms a single string of text from the elements of an array. The string of text is formed by concatenating the string values of the array elements until a string of the desired length is formed. The string values of each array element are separated by at least one padding character. The first character of the resultant string is the first character of the first array element. The last string character is the last character of the last array element.

    This function has two forms:
    1. justify(words,number_words,width) - return string width characters long formed by justifying number_words elements of array words padded with blanks. 
    2. justify(words,number_words,width,pad_character) - return string width characters long formed by justifying number_words elements of array words padded with character pad_character.
    For both forms, if number_words elements of array words with at least one character between elements would exceed width, then the number of array elements justified is reduced to fit in the length width.  
Version function: justify_module_version()

No "exit" function.

No "shutdown" function.

TOP
User Guide
Chapters
Table of Contents
Group Patterns
Format Specification