Reading data from a sequential file, socket or pipe¶
get # |
Read data from a sequential file, socket or pipe |
getfield # |
Read CSV formatted data from a sequential file, socket or pipe |
SYNTAX
get # channel, field_id [, field_id]… [err = label] [traps = label]
getfield # channel, field_id [, field_id]… [err = label] [traps = label]
Reads ASCII text data from the sequential file, socket or pipe which is open on the specified channel number into the listed field or fields.
channel |
The channel number must be an integer expression in the range 0-64. It is the number that was allocated to the file when it was opened (using open #). It may be a constant, field name or expression. If the channel number is outside the range 0-64, error number 1 is returned in the system variable sys.Error. Channel 0 refers to stdin (standard input). On MS-DOS and UNIX this is the keyboard unless redirected from a file. On Windows, the keyboard cannot be read directly but redirection from a file is possible if the program is run from a DOS command. See Sequential files for more information. |
||||||||||||
field_id |
Each 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 fields may be of any type; standard type conversion rules are applied to convert the input data to the type required. The separator character(s) and end-of-line character(s) are not stored, except as already noted for getfield #. |
||||||||||||
[err = label] |
If an error occurs, the error number is stored in the system variable sys.Error, and control passes to the line indicated by the label specified in the err clause. 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 a !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. If an untrapped error occurs in a !report section, the command is ignored. |
||||||||||||
[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. |
The get # command¶
The get # command reads in a single record, which may consist of several data items separated by a special separator character. These data items are assigned to the specified fields in order.
The record must be composed entirely of ASCII text. Leading and trailing spaces are ignored. The end of the record is marked by the system end-of line character or characters. This is, for example, \n (newline) on UNIX, and \r\n (return/newline) on MS-DOS. Simple text files created on a system have the correct end-of-line character(s).
The record may consist of a single data item or of multiple data items. Data items in a record are separated by the separator character, defined in sys.Separator (the default being a comma). The data items read in are assigned to the corresponding fields in the field name list. If there are more fields listed than there are data items in the record read in, the extra fields are given a null value. If there are more data items than fields, the extra data items are ignored.
The maximum number of characters that can be read by a single get # command is 4000.
The getfield # command¶
The getfield # command reads only the number of fields specified. It can therefore be used to read one field at a time if required. Unlike get #, it recognises CSV (comma separated value) format. CSV has become a standard for interchanging data between applications. Applications that can read and write CSV files include Microsoft Word and Excel.
Each field is a block of text, delimited by any character contained in the Sculptor system variable sys.Separator. The default separator character is the comma, and this value should be used when reading standard files. However, sys.Separator may be set to another character or to a list of separator characters if required.
Every time getfield # is executed, the character that terminated the last field is stored in sys.LastSeparator.
getfield # honours the following CSV conventions:
1 |
Quoted text is read as a single field. Text is deemed to be quoted if the first non-blank character is a quotation mark |
2 |
Within quoted text, two consecutive quotation marks are treated as a single, embedded quotation mark. |
3 |
Leading spaces before each field are ignored (unless in quotes). |
- As an example, the line:
123,“embedded,comma”, just text, “embedded”“quote”,not"quoted
parses into the following field values:
123
embedded, comma
just text
embedded"quote
not"quoted
Separator character¶
The default separator character is the comma (,), but it may be redefined to another character or to multiple characters by assignment to the system variable sys.Separator. The separator character is not stored in the receiving field.
NOTES
If an alphanumeric field has the r flag, 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 get[field] # command waits. The check # command can be used to check whether bytes are available.
EXAMPLE
open #3, tmpfile read traps = TRAP_OPEN
get #3, pr_name, pr_add1, pr_add2, pr_add3 traps = TRAP_GET
RELATED TOPICS |