.so roff$library:help.mac
.tp 1 CLI_SET 

Command Line Interpreter for VAX/VMS Program Development in C

CLI_SET provides a comprehensive method of extracting qualifier and 
parameter information from the command line. CLI_SET relieves the C
programmer from constructing descriptors and calling CLI$_PRESENT and/or
CLI$_GET_VALUE for each qualifier and parameter on the command line.
Instead, the programmer builds a table containing vital information and
passes that table to one procedure call:

When CLI_SET returns, all the significant variables of a program (be
they boolean, integer, character string, or floating point) contain the
information extracted from the command line. 

CLI_SET is also advantageous in processing qualifier lists and
managing memory for list and string variables automatically.

CLI_SET provides a standard interface for all programs that query the 
command line, providing easy access for maintenance programmers to update
default qualifier variables, add functionality, and gain a better
understanding of the programs variables and their relationship to the
command line qualifiers and parameters. CLI_SET is, in a way, 
self-documenting.
.tp 2 CLI_SET
.sy
#include "cli_set.h"

long cli_set( optab )
	OPTION	optab;	/*  Array of structures
			    describing arguments  */

.in
.fi
returns SS$_NORMAL when a parameter in optab has been found, and
CLI$_ABSENT when all parameters in the optab have already
been processed.
.tp 2 CLI_INIT
.sy
void cli_init( optab )
	OPTION optab[];

.in
.fi
Sets variable pointers in the option table to NULL. This
is necessary for CLI_SET to dynamically allocate space to
these pointers. If the pointers point into oblivion, who
knows what might happen.
.tp 2 CLI_FREE
.sy
void cli_free( optab )
	OPTION optab[];

.in
.fi
Frees dynamic memory allocated from CLI_SET. Use this only
if extra memory is important and you are through processing
commands from a specific option table.
.tp 2 Option_table
The option table is a structure array that defines each qualifier
parameter. Included in the structure is:

.in 3
1. Label   - Defined in the .CLD file
2. Type    - Type of variable (i.e. $BOOLEAN, $STRING, $INTEGER, etc)
3. Address - The address of the variable to store the value
4. Default - The default value to be used if the qualifier is missing
.tp 3 Example
.nf
OPTION table[] = {
.in 3
"file",		$STRING|$PARAM,	&filespec,	"",
"confirm",	$BOOLEAN,	&o_confirm,	FALSE,
"queue",	$STRING,	&o_queue,	&default_queue,
"job_copies",	$INTEGER,	&o_job_copies,	1,
"",		0,		NULL,		NULL
};
.tp 2 Data_types
.nf
The following data types are provided:
   $BOOLEAN		/confirm, /noconfirm
   $STRING		/queue=sys$print, /name="My Job"
   $INTEGER		/job_copies=3
   $FLOAT		/point_size=13.75

Modifiers can augment the data types:
   $LIST|$STRING	/header=("left","","right")
   $LIST$INTEGER	/tabs=(5,8,15,20,25)
   $LIST|$FLOAT         /margins=(10.2,35.5,35.5,10.2)
   $PARAM|$STRING       /print foo.dat, bar.dat

.fi
The $PARAM modifier tells CLI_SET that the option is 
parameter and should be processed one at a time. CLI_SET
will return SS$_NORMAL while there are parameters found
on the command line, and CLI$_ABSENT when the parameters
have been exhausted. Thus the CLI_SET procedure call can
be placed in a while loop with the condition not equal to
CLI$_ABSENT.
.tp 2 Include_file
The include file cli_set.h
defines the symbols for the types of arguments
($BOOLEAN, $LIST, $FLOAT, $NUMBER, $PARAM, $STRING),
and defines the structure type OPTION
used to declare the option table
(which is an array of type OPTION).
See the example for more information.
.tp 2 Command Definition Language
CLI_SET does not replace the need to use
the CLD facility provided by VMS. The
CLD is required to parse the command line
and verify its validity. Therefore, options
defined in the CLI_SET option table should
also be defined in the .CLD file. An example
of a CLD file exists in the [example] subdirectory.
.tp 2 Examples
An example program and CLD file are on the files
.jn
[cli_set.example]test_cli_set.c
[cli_set.example]test_cli_set.cld
.jf
These files may be copied freely.