Execute a Command File

This Subprogram allows the Application Program to accept all subsequent text from the specified file rather than the User. A return will be made to normal (User) Input when the end-of-file is encountered.

Short Name Calling Sequence

STATUS = UIEXFI(FILNAM)

Long Name Calling Sequence

STATUS = UI_EXECUTE_FILE(...)

Input Arguments

FILNAM (Character) File Name

Output Arguments

None

Function Value

UI__SUCCESS ) Success UISUCC )

UI__NOT_INITIALIZED ) Package not Initialized UININI )

UI__STACK_DEPTH ) Command File maximum UISTAK ) stack depth exceeded

UI__OPEN_INPUT ) Unable to open File UICIFI )

UI__RECURSIVE_INPUT ) Attempt to Execute UIRIFI ) Recursive Input File

Note:

1. This Subprogram does not actually execute the commands in the specified file, but increments the Command Indirection Level such that all subsequent requests for Input from the Application Program will be directed to the File rather than the User at the Terminal. The Command Indirection Level will be decremented when end-of-file is detected and, unless Command File nesting has been specified (see next note), further input will be requested from the User.
2. Calls to this Subprogram may be nested, but the Files thus referenced will be executed in reverse order. Thus the sequence:-

            CALL UIEXECUTEFILE(FILE1)
            CALL UIEXECUTEFILE(FILE2)
            CALL UIEXECUTEFILE(FILE3)
   

   will result in the Commands from File ``FILE_3" being executed first, then ``FILE_2" and finally ``FILE_1".
3. On a VAX, the file type defaults to ``.UIC" if it isn't explicitly specified within FILNAM, and the file defaults to ``UIPACK.UIC" if FILNAM is null (all spaces).
4. Command Files may be nested up to a maximum of 4 deep. Function Value UI__STACK_DEPTH will result if an attempt to exceed this limit is made, and the request will be ignored.
5. The UI__RECURSIVE_INPUT Error will be signalled if the specified File already exists on the Command Input Stack and the request will be ignored (This corresponds to File A calling File B which then attempts to call File A).
6. All Errors apart from UI__NOT_INITIALIZED are treated as User Interaction Errors and cause the Command File Stack to be unwound and further input to be taken from the keyboard.