Opening a sequential file, named pipe or socket ¶

open #

Open a sequential file, named pipe or socket

Contents

Opening a sequential file, named pipe or socket
- Sending messages between two computers
- Standard input, output and error channels

SYNTAX

open #channel, pathname | “pathname” create | read | append [err = label] \
          [fe = label] [nsf = label] [traps = label]

open #channel , “|pipename” create | read | update [err = label] \
          [fe = label] [nsf = label] [traps = label]

open #channel , “[server]:<socket_no>” create | read | update [err = label] \
          [fe = label] [nsf = label] [traps = label]

Opens a sequential file, socket or pipe on the channel number represented by channel. When no longer required, it should be closed by means of the close # command.

#channel

The channel number must be an integer expression in the range 1-64. It may be a constant, field name or expression. If the channel number is outside the range 1-64, error number 1 is returned in the system variable sys.Error.

Channel 0 is the standard I/O channel and may not be opened.

pathname | “pathname”

Open the sequential file whose name and directory is specified in pathname, which may be a string constant in double quotes, a field name or an expression.

“|pipename”

Open the specified named pipe. The name of the pipe must be preceded by the pipe symbol (“|”). Named pipes are supported by most Unix platforms and by Windows NT, but not by Windows 95/98. The name may be a string constant in double quotes, a field name or an expression.

“[server]:<socket_no>”

Open the socket with the number specified. Sockets are supported on all 32-bit Windows platforms and on most Unix platforms, and can be used across a network. A server program omits the “server:” part of the open # command because it listens for any client to connect on the specified socket. A client program must specify the server name and the socket number that it wishes to connect to. Normally, both server and client will use update mode, though a socket can be opened in read-only mode if required.

The socket number may be a string constant in double quotes, a field name or an expression.

File mode

The mode in which the file, socket or pipe is to be opened must be specified. There are four modes available:

read	The file is opened for reading. If it does not already exist, an error occurs. The file is read by means of the get[field] # command.
create	The file is created if it does not already exist. If it does exist, it is truncated to zero length. The current file ownership and access permissions are preserved. The file is written to by means of the put[field] # command. See the fe trap below.
append	Sequential files only. The file is created if it does not already exist. If it does exist, the file pointer is positioned at the end of the file. It may be repositioned at the start of the file by means of the rewind # command. The file is written to by means of the put[field] # command. If a sequential file needs to be opened both for reading and for writing, it may be opened twice, on different channels.
update	Sockets and pipes only. The channel is open both for reading and writing. This mode is not the same as the append mode that can be used with sequential files.

[err = label]

Errors other than File exists and No such file 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:

No	Manifest constant	Meaning
1	BAD_CHANNEL	channel number is not between 1 and 64
2	IN_USE	channel already in use
3	BAD_NAME	name expression is not a string
4	NO_FILE	file cannot be accessed
5	NO_ZERO	attempt to open channel 0
6	NO_PERMS	no permission (UNIX)
7	TOO_MANY	too many files open
11	FILE_EXISTS	File exists and fe clause used

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 open # command is ignored.

[fe = label]

If a file is opened in create mode, and it already exists, its current contents are destroyed. This condition may be trapped by the fe trap, which works as follows:

open #channel, pathname create

The fe condition is not trapped. The file is created and the old contents are lost.

open #channel, pathname create fe = label

The fe condition is trapped and control passed to a specified line label. Sculptor passes control to the line specified, and a new file is not created.

open #channel, pathname create fe = IGNORE

The fe condition is trapped with the special label IGNORE A new file is not created. It is assumed that the programmer intends to check sys.Traps.

[nsf = label]

Traps the No such file condition which is generated if the specified file (or pipe, or socket) does not exist. Control passes to the line indicated by label.

If this condition is not trapped, the error No such file is displayed and control passes to the active menu, if any. If no menu is active the program exits.

In a !report section, an untrapped nsf causes the command to be 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.

Sending messages between two computers ¶

If the open # command is used to open a serial port (COM1 to COM9), then from Sculptor V5 onwards all I/O on that port is unbuffered. This makes it possible to use a serial port to send messages between two computers. To set the baud rate and handshaking parameters, execute the DOS mode command before opening the port. Parameters must be identical on both the sending and receiving computers. To see the full syntax of the mode command, type “mode /?” at a DOS prompt.

A program must make its own arrangements to detect end of message. See the sample programs in $SCULPTOR\demo\comports, which demonstrate one way to achieve this.

Standard input, output and error channels ¶

The standard input, output and error channels can be opened by using the following syntax:

Standard input	open #channel, “stdin” read
Standard output	open #channel, “stdout” create
Standard error	open #channel, “stderr” create

See Sequential files for further information.

NOTES

Channel 0 (zero) is the standard I/O channel and may not be opened. See Standard input, output and error channels for details on how to open these channels.
If a file is already open on the specified channel, it is closed and the new file opened.
The number of files that may be open at the same time is operating system dependent. It is not usually fewer than 16.

EXAMPLES

open #5, seqfile create traps = OPENTRAP      /* Open a sequential file */
open #8, "/dev/barcode" read err = OPENERR    /* Open a device */
open #18, ":5672" read                        /* Open a socket */
open #24, "|details" update                   /* Open a pipe */
open #4, "stdin" read                         /* Open the standard input channel */