Get a newline terminated string from a sequential file, socket or pipe¶
fgets |
Read a newline terminated string from a sequential file, socket or pipe |
SYNTAX
fgets file_handle field_id [err = label] [to = timeout[:label]] [traps = label]
Reads ASCII text data from the sequential file, socket or pipe which is open on the specified file_handle into the specified field until a newline or the field_id is filled.
file_handle |
It can be the handle returned by the fopen command (it returns a negative number to differentitate the #channel case) or an integer in the range 1-64 specifying the number of the channel on which the sequential file, socket or pipe (opened by the open # command) is open. It may be a constant, field name or expression. See Sequential files for more information. |
|||||||||||||||
field_id |
The field_id specified must be the name of a field in a Sculptor keyed file declared in the program or of a temporary field declared in the program. The field may be of any type; standard type conversion rules are applied to convert the input data to the type required. The end-of-line character is not stored. |
|||||||||||||||
[err = label] |
Errors return the trappable condition err, which may be trapped by the err = clause or by the general traps = clause. The error number is stored in the system variable sys.Error , and control passes to the line indicated by label. The error numbers are defined by manifest constants in the file errors.h, which is located in the Sculptor include directory. This file may be included in a program by means of an !include declaration. The possible errors are:
If an error occurs and is not trapped, an error message is displayed and control passes to the active menu, if any. If no menu is active the program exits. |
|||||||||||||||
[to = timeout[:label]] |
Defines the timeout value and if the label is defined then control passes to the line indicated by label, in case the timeout is reached. If this condition is not trapped, the error timeout exceeded is displayed and control passes to the active menu, if any. If no menu is active the program exits. |
|||||||||||||||
[traps = label] |
General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped. Although the err = clause is non-specific, it still takes priority over traps. |
NOTES
If an alphanumeric field has the r or v flags, the field is stored as read, preserving the field length, rather than padding with spaces. If the length of the data is less than the field length, the value is stored null terminated, rather than padded with spaces to the field length.
If no input is currently available the fgets command waits. The check # command can be used to check whether bytes are available.
EXAMPLE
Read the first line of the file:
!temp fHandle,,i2
!temp lineTxt,,a128,,v
fopen fHandle "seqfile" "r"
fgets fHandle lineTxt
RELATED TOPICS |