New in version 6.3.0: See the new features.

Opening a sequential file, named pipe or socket ¶

fopen

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

fopen field pathname mode [err = label] [to = timeout[:label]] [traps = label]

Opens a sequential file, socket or pipe and saves the handle in the field. When no longer required, it should be closed by means of the fclose or close # commands.

field

The field where the sequential file handle is stored. When the execution of the command is successful, the value returned is negative (to differentiate from normal #channel). This means that the field must be a signed integer i[1-8].

pathname | “pathname”

Open the 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 may omit the “server:” part of the open # command because the server is listening for clients on the given 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.

mode

The mode in which the file, socket or pipe is to be opened must be specified. These modes are the same as the “C” fopen call:

r	read: Open file for input operations. The file must exist.
w	write: Create an empty file for output operations. If a file with the same name already exists, its contents are discarded and the file is treated as a new empty file.
a	append: Open file for output at the end of a file. Output operations always write data at the end of the file, expanding it. Repositioning operations (fseek, fsetpos, rewind) are ignored. The file is created if it does not exist.
r+	read/update: Open a file for update (both for input and output). The file must exist.
w+	write/update: Create an empty file and open it for update (both for input and output). If a file with the same name already exists its contents are discarded and the file is treated as a new empty file.
a+	append/update: Open a file for update (both for input and output) with all output operations writing data at the end of the file. Repositioning operations (fseek, fsetpos, rewind) affect the next input operations, but output operations move the position back to the end of file. The file is created if it does not exist.

With the mode specifiers above the file is open as a text file. In order to open a file as a binary file, a b character has to be included in the mode string.

[err = label]

Errors other than Timeout 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	field is wrong
4	NO_FILE	file cannot be accessed
12	TIMEOUT_EXCEEDED	timeout exceeded

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

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

Sending messages between two computers ¶

If the fopen 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	fopen field “stdin” “r”
Standard output	fopen field “stdout” “a”
Standard error	fopen field “stderr” “a”

See Sequential files for further information.

NOTES

The number of files that may be open at the same time is operating system dependent. It is not usually fewer than 16.

EXAMPLES

A small example to create a file, write something and close it:

!temp fd,,i2

  fopen fd "test.txt" "w" traps=trap_ERR

  . Write some content with fputs
  fputs fd "Some text" traps=trap_ERR

  fclose fd traps=trap_ERR
  exit 0

trap_ERR:
  error "Error=" + tostr(sys.Error)

Serveral cases:

!temp fld,,i4

  fopen fld seqfile "w+" traps = OPENTRAP      /* Open a sequential file r/w */
  fopen fld "/dev/barcode" "r" err = OPENERR   /* Open a device */
  fopen fld ":5672" "r"                        /* Open a socket */
  fopen fld "|details" "a"                     /* Open a pipe */
  fopen fld "stdin" "r"                        /* Open the standard input */