NDC comm CompuFax Callable Interface, Callable Com m ands, Faxcmdproc commandline

10.2 The CompuFax Callable Interface

10.2.1 Callable Com m ands

The CompuFax command interface is available as a shareable image that may be called from user-written programs. This makes the entire functionality of the CompuFax command processor available to a user application. The FAX command processor itself (the program invoked by the FAX command) is implemented using this interface. The source file for this program, FAX_CMD.C, has been included with the CompuFax software as an example. A list of callable commands is given below.

10.2.1.1 FAX_CMD_PROC

This is the main entry point for the CompuFax system command processing routine in the CompuFax shareable image. It provides a callable interface to the CompuFax system which may be used by user applications. All capabilities of the command processor are available through this interface.

When this function returns, the global longword FAX_CMD_STATUS will contain the completion status of the most recent command executed. This is particularly meaningful when a command is passed to this function.

Calling Sequence:

FAX_CMD_PROC [commandline]

Arguments

name: commandline

type: charactercoded text string

access: read only

mechanism: by descriptor.fixed length string descriptor

This optional command gives a CompuFax command as ASCII text. The command is processed and the function returns when processing is complete. The command is processed just as if it had been entered from the keyboard. If this parameter is not passed or is passed as zero, the user is prompted for input and control is not returned until the EXIT command is entered or ^Y is pressed.

Notes: See also FAX_CMD_SET_HANDLE for a description of how to control exception handling. See FAX_CMD_SET_INPUT and FAX_CMD_SET_OUTPUT for a description of how to control input and output of additional command lines to CompuFax. See FAX_CMD_FORCE_EXIT for a description of terminating the command input loop from a user condition handler. This routine sets out of band ASTs on ^C and ^Y and cancels them before returning. A side effect of this is that any out of band input AST declared by the user is canceled as well.

10.2.1.2 FAX_CMD_SET_HANDLE

This function is used to set the address of a condition handler that will be used by subsequent calls to FAX_CMD_PROC. If a handler is set by this function then all errors will be passed to the user handler. The user handler is called with the same parameters as a normal VMS condition handler.

The return status from the user condition handler is not used (SS$_CONTINUE or SS$_CONTINUE). If the severity of the signaled condition is less than SEVERE then, after the user handler is called, execution will continue at the point where the condition arose (as if the user handler had returned SS$_CONTINUE). If the severity is SEVERE then a stack unwind will be done. The effect of this will be that the current FAX command will immediately complete.

9 0