Open Text File for Scanning

This Subprogram opens the specified Text File such that lines within the File may be fetched via subsequent calls to UI_LINE_SCAN.

Short Name Calling Sequence

STATUS = UIOPSN(FILNAM)

Long Name Calling Sequence

STATUS = UI_OPEN_SCAN(...)

Input Arguments

FILNAM (Character) Filename

Output Arguments

None

Function Value

UI__SUCCESS ) Success UISUCC )

UI__NOT_INITIALIZED ) Package not Initialized UININI )

UI__STACK_DEPTH ) Open File maximum Stack UISTAK ) Depth exceeded

UI__OPEN_INPUT ) Unable to open File UICIFI )

UI__RECURSIVE_INPUT ) Attempt to open Recursive UIRIFI ) Scan File

Note:

1. On a VAX, the file type defaults to ``.UID" if it isn't explicitly specified within FILNAM and the file defaults to ``UIPACK.UID" if FILNAM is null (all spaces).
2. UIPACK uses the next available Logical Unit Number from its pool used to access Indirect Command Files in order to access the specified file. This means that this Subprogram should not be called during the scanning of an Indirect Command File if the nesting of such files exceeds 3. Error UI__STACK_DEPTH will result if this is attempted and the request will be ignored.
3. Once a text file has been opened by a call to this Subprogram, all subsequent Input will be taken from this file. Thus no call to a normal Prompted Input Subprogram (UI_GET_xxx) or Menu Subprogram should be made until the text file has been completely scanned and closed (via a call to UI_CLOSE_SCAN). Calls to Verb or Menu definition Subprograms are allowed however, except for calls to UI_DEFINE_FILE which is also disallowed. The results of violating these restrictions is unpredictable.
4. Calls to UI_OPEN_SCAN cannot be nested. Thus each call to this Subprogram must be followed by a call to UI_CLOSE_SCAN, either explicitly, or implicitly via the detection of End-of-File by a subsequent call to UI_LINE_SCAN. Error UI__RECURSIVE_INPUT will be returned if this is attempted.