Writing data to a sequential file, socket or pipe¶
put # |
Write data to a sequential file, socket or pipe |
putfield # |
Write CSV formatted data to a sequential file, socket or pipe |
Contents
SYNTAX
Writes data in ASCII text format to the sequential file, socket or pipe which is open on the channel specified.
The putfield # command performs standard CSV (comma separated value) formatting on the data. CSV has become a standard for interchanging data between applications. Applications that can read and write CSV files include Microsoft Word and Excel.
The put # command does no formatting, outputting the data exactly as presented to it. In most other respects the two commands are identical. Any differences are specified in the appropriate section below.
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. 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 is stdout (standard output). On MS-DOS and UNIX, this is the screen unless redirected to a file. On Windows,the screen cannot be output to directly but redirection is possible if the program is run from a DOS command.
Note however that in a !report section, the put #0 command sends its output to the printer. If the printer is a Windows printer, or if the printer parameter file has print mode set to S (Standard) instead of W (Windows), the Windows GUI print mechanism is bypassed, and the printer can be controlled directly. The use of put #0 with the print mode W (Windows) is discouraged as this is an obsolescent feature in Windows.
Printer control sequences can be defined in the printer parameter file, or output using the put #0 command with binary fields. The Generic/Text Only print driver should be used to ensure that this works properly; other drivers may not support the feature.
The putfield #0 command does not send its output to the printer in a !report section. Channel 0 is still stdout.
To output formatted data to a screen window use the put command.
See Sequential files for more information.
expression
Each expression is evaluated and the result output as ASCII text.
putfield # honours the following CSV conventions:
1 |
Values that have the first character in sys.Separator or a quotation mark embedded in their text are automatically enclosed in quotation marks. |
2 |
Inside a quoted value, an embedded quotation mark is output twice. |
3 |
Leading and trailing spaces are removed from alphanumeric fields unless the character “k” (keep spaces) is included in the format. |
As an example, the following field values:
123
embedded, comma
just text
embedded"quote
not"quoted
would be formatted by putfield # into the following line:
123,“embedded,comma”, just text, “embedded”“quote”,not"quoted
put = # outputs text as presented to it, never enclosing values in quotes.
[:format]
Each expression may, optionally, have a format attached. The format is preceded by a colon. It is normally a string constant in quotes, but may be an alphanumeric field containing a valid Sculptor format.
If no format is specified, a suitable format for the data type of the expression is used. In the case where expression is a simple field_id, the default format is the format of this field.
The putfield # command removes leading and trailing spaces from all values except alphanumeric text that has the letter “k” (keep spaces) in its format.
See Field formats.
[err = label]
Errors may be trapped by means of the optional err trap, or by means of the general traps clause. If an error occurs, 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:
No |
Manifest constant |
Meaning |
1 |
BAD_CHANNEL |
channel number is not between 0 and 64, or no file open on channel |
10 |
FPUTERR |
File not open for writing or disk full |
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.
Separating items in a put[field] list¶
Items may be separated either by a comma or by a semicolon. If a comma is used, the value of the Sculptor system variable sys.Separator is output in place of the comma. If a semicolon is used, no separator character is output between the items.
The default separator character is the comma (,), but it may be redefined to another character or to multiple characters by assignment to the Sculptor system variable sys.Separator. This field is normally an a1 type, but the type may be redefined with a greater length if a multiple-character separator is required.
When putfield # is being used to write standard CSV files, set sys.Separator to “,” or, for more readable output, to “, ”, and use commas to separate the items in the list.
Terminating the data list¶
Unless the last item in the list is terminated by a comma or semicolon., a newline (RETURN) is appended to the end of the data. If the last item is terminated by a comma, the separator character is output. If it is terminated by a semicolon., nothing is output at the end of the last item.
Binary format¶
Non-alphanumeric data is converted to text. Therefore, if expression were equal to 7, this would be converted to the ASCII code for the number 7 before output. To output a binary value, use a field which is type b (binary) or has the b flag assigned. Note that binary cannot be specified by use of the expression[:format] construction; the format “b” indicates a format string, not a flag character.
Multi-byte numeric fields are output starting with the most significant byte.
NOTES
If an alphanumeric field has the r or v flag, and the length of the data is less than the field length, the field is written as stored, preserving the field length, rather than padding with spaces.
EXAMPLE
open #1, "TESTFILE" append traps = OPENTRAP
put #1, tmp.Fld1, tmp.Fld2, tmp.Fld3 traps = PUTTRAP
put #0, FirstDate:"dD/mM/YYYY"
RELATED TOPICS |