Fetch next Line from File for Scanning

This Subprogram fetchs the next line of text from the currently opened Scan File.

Short Name Calling Sequence

STATUS = UILISN(TEXT[,LENGTH])

Long Name Calling Sequence

STATUS = UI_LINE_SCAN(...)

Input Arguments

None

Output Arguments

TEXT (Character) Text of Line LENGTH (Integer) Length of Text (Optional)

Function Value

UI__SUCCESS ) Success UISUCC )

UI__TRUNCATED ) Success - Text truncated UITRUN )

UI__END_OF_FILE ) End of File detected UIEOF )

UI__NOT_INITIALIZED ) Package not Initialized UININI )

UI__NO_INPUT ) Scan File not open UINOIN )

Note:

1. The text of the next line within the File is returned in upper case unless it is enclosed within single or double quotes. Continuation lines (denoted by a trailing ``-" character) will be concatenated before they are returned to the caller.
2. Comments within the file are denoted by the ``!" character. Any subsequent text will be ignored and not be returned to the caller. Lines containing only comments (i.e. the ``!" character is in column 1) will be ignored completely.
3. The LENGTH Argument is optional and, if present, will be set to the occupied length of the line, ignoring trailing spaces. If truncation has occurred, LENGTH gives the number of characters following truncation.
4. If the text line (which may be up to 500 characters in length) is longer than the declared length of the TEXT Argument it will be truncated and function UI__TRUNCATED returned to the caller.
5. Function UI__END_OF_FILE will be returned when the file scan is exhausted and no further lines remain. This condition causes an implicit call to UI_CLOSE_SCAN and hence the Application Programmer need not call this Subprogram explicitly.