Sequential files

Contents

• Sequential files

  • Channel 0

  • Fcmds and file handles

  • Communication between programs

A sequential file, pipe or socket can be opened from within a Sculptor program, and data read from or written to it. When the channel is opened it is allocated a channel number in the range 1-64. All subsequent operations on the file (or socket, or pipe) refer to it by means of this channel number.

Sculptor commands that perform operations on channels end with the # character, e.g. check #, getfield #. The # character is immediately followed by the required channel number. For example:

check #22

checks for available bytes in the file open on channel 22.

The Sculptor commands and functions relevant to channels are:

check #	Check if bytes are available in a sequential file, socket or pipe
close #	Close a sequential file, socket or pipe
execute()	Execute another program
flush #	Flush pending output to a specified channel
get[field] #	Read data into fields from a sequential file, socket or pipe
inchar()	Return the ASCII value of the next character from a channel
open #	Open a sequential file, socket or pipe
put[field] #	Write data to a sequential file, socket or pipe
rewind #	Rewind a sequential file to the beginning
seek #	Position a sequential file at a stated position
tell()	Return the current position of a sequential file
wind #	Position a sequential file at the end

Channel 0

Channel 0 is a special case, used by Sculptor to refer to stdin (the standard input channel) and stdout (the standard output channel).

Standard input is the keyboard, unless input has been redirected from a file.

Standard output is the screen, unless redirected to a file.

So:

get #0	reads data from stdin
put #0	writes data to stdout

Sculptor does not permit channel 0 to be opened or closed. It allows it to be used if it is open when the program starts. This is operating-system dependent, as follows:

MS-DOS, UNIX	stdin and stdout are always open, and default to the terminal. Both stdin and stdout can be redirected from/to a file. If a DOS program is running under Windows, it must be running in a DOS box, which represents the terminal.
Windows	stdin and stdout are closed. The only exception occurs when the program has been started from a DOS command and the channel has been redirected from or to a file. Provided that these two conditions are true, the file can be read using get[field] #0 and written to using put[field] #0. Note however that inside a !report section, put #0 sends its output to the printer.

The open # command can be used to open the standard input, output and error channels.

Fcmds and file handles

New in version 6.3.0: See the new features.

This new group of commands can be used with files, pipes or sockets and work in a similar way to their C counterparts:

fclose	Close a sequential file, socket or pipe
fgets	Read a newline terminated string
fopen	Open a sequential file, socket or pipe
fprintf	Writing formatted data to a sequential file
fputs	Write a newline terminated string
fread	Read binary data from a sequential file, socket or pipe
frewind	Rewind a sequential file to the beginning
fseek	Position a sequential file at a stated position
fwrite	Writing binary data to a sequential file, socket or pipe

The Fcmds work with file handles but also support Sculptor sequential channels (as the normal channel commands support file handles). To differentiate between file handles and channels, the file handles are stored as negative number while the channels as positive.

Warning

Due the use of negative numbers for file handles, remember to use a signed integer to store file handles (i1, i2, i3, i4 or i8)

So for example fprintf into standard output can be done using the Channel 0:

!temp str,,a20,,v = "World"

fprintf 0 "Hello %!" str

The opposite is also possible, use a fopen’ed stdout file handle with the classical channel commands:

!temp str,,a20,,v = "World"
!temp fHandle,,i4

fopen fHandle "stdout" "a"
put #fHandle, "Hello " + str +"!"

Communication between programs

Using the execute() function, another program can be executed and comunicate with it through specified channels (pipes)

Apart from this, under all operating systems, it is possible to run two console programs with a pipe between them:

program1 | program2

This directs stdout of program1 to stdin of program2. Now, if program1 uses put[field] #0 and program2 get[field] #0, data can be sent from program1 to program2. Note that this flow of communication can travel in that direction only.

The stdin = and stdout = clauses of the exec command enable the standard input and/or output of the child task to be redirected to designated channel numbers. This, in effect, creates a two-way communication.

Note

A console program is one that runs from the operating system’s command line, in character-mode, rather than from a graphical user interface.