2 CLI_parse_foreign

 Cli_parse_foreign does a DCL parse of the command line for a foreign
 command, emulating as closely as possible what DCL does before it activates
 an image which has been installed in a process's command table. The idea is
 to avoid the eternal wait for SET COMMAND to complete by linking the table
 into the image and using cli_parse_foreign to parse the command line
 made up of the verb parameter concatenated with the string returned by
 lib$get_foreign.

3 Usage

To use cli_parse_foreign, you set up a command file, say FIAT_TABLE.EXE
as follows:

module FIAT_TABLE	! name of the object module
define verb FIAT
   routine cli_abort	! abort if cli$dispatch is called

Then type $ SET COMMAND/OBJECT FIAT_TABLE

In your FIAT program, declare FIAT_TABLE to be an external variable and
call CLI_parse_foreign(FIAT_TABLE,'FIAT'). In Pascal, inherit MCVLIB and
declare

var
   FIAT_TABLE: [external] cli_tableType;

Finally, type $ link FIAT,FIAT_TABLE to link the table with the rest of
the command.

3 Deficiencies

Cli_parse_foreign doesn't make a command act completely like an image
installed in a process's command table:

    1) The command is still a foreign command, which implies that it must
       be defined with a DCL symbol, e.g.
          verb :== $programDirectory:verb.exe
       Thus its parameters may be only 251 characters long, after
       squeezing spaces, expanding symbols, and so on. (Why 251 instead
       of 255 or 256 I don't know.)
       Also if users want to put things like
          verb2 :== verb/qualifier
       in login.com files, they must use
          verb2 :== 'verb'/qualifier
       or something similar.

    2) Cli_parse_foreign will refuse to prompt for missing parameters if
       sys$input is not the terminal, but if you put something like
          $ define/user sys$input sys$command
          $ verb
       in a command procedure, the user will be prompted, which is not the
       case with DCL.

    3) Since the image is always run, certain fine points of behaviour
       will be different if syntax errors are found. You can't continue
       from a control-Y'd image after making an error in the command
       syntax of an image called using cli_parse_foreign, for instance.

    4) Cli_parse_foreign is intended to be called ONCE, at the beginning
       of your program. It will exit if it finds a parsing error, after
       printing the usual DCL error message (except that the facility name
       will be CLI instead of DCL) without printing any traceback
       messages, and without giving ANY other exception handlers a shot at
       the condition, whether those handlers are established by you or by
       the debugger. After such an exit, the value of the $STATUS symbol
       will have the value it would have when DCL found the same error,
       plus %X10000000 (since the 'do not print' flag is turned on to
       prevent $exit from printing the error message again). It will also
       exit if the user hits control-Z during prompting for missing
       parameters. In that case, the value of $STATUS will be ss$_normal.

    5) Cli_parse_foreign calls the last chance exception handler to
       print the error messages mentioned in the note above, so don't
       mess with that handler before you call cli_parse_foreign. (The
       procedure calls the last chance handler because the $putmsg system
       service does some very weird things with certain common signal
       array setups; the last chance handler somehow fixes this up.)
