New in version 6.3.0: See the new features.

Writing formatted data to a sequential file, socket or pipe


Writing formatted data to a sequential file, socket or pipe


fprintf file_handle format [expression [, expression]… ] \
[err = label] [to = timeout[:label]] [traps = label]

Writes formatted data to a sequential file, socket or pipe which is open on the specified 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.


It contains the text to be written to the file_handle and allows the programmer to specify a pattern in which the data should be formatted. It can optionally contain embedded format tags that are replaced by the values specified in subsequent additional expressions. The special tags:

Format tag



The % character will be substituted by the next expression outside the format string. If there is more than one %, further expressions are substituted in order of appearance.


A literal percent sign is output.


An end of line character is printed (operating system dependent)


A linefeed character is printed (ASCII 13)


A tab character is printed (ASCII 9)


A literal backslash is output.


It can be a Sculptor keyed file field, !record field or a temporary field declared in the program. The fields may be of any type.

Or a record_id that refers to a !record or a ![o]file declared in the program. Including record arrays and nested records.

Or just an expression (funcion calls, operations, constants…)

The data is written as text data directly from the supplied expression using the standard Sculptor conversion rules.

[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:


Manifest constant




file_handle is wrong



write error, check errno



timeout exceeded



general error, check errno



bad/wrong number of arguments

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.


  • If an alphanumeric field has the r or v flags, 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.


A fprintf example:

!temp fHandle,,i2
!temp sName,,a32,,v
!temp iAge,,i2

fopen fHandle "seqfile" "w"

tmp.sName = "Paul"
tmp.iAge = 33

fprintf fHandle "Name: %\\nAge: %\\n" sName, iAge

fclose fHandle







get[field] #

put[field] #

Sequential files