OPEN

Open a channel

OPEN(channel, mode_spec, file_spec[, ALLOC:blocks][, LOCK:lock_spec]
&    [, OPTIONS:"runtime_option[, ...]"][, POSITION:pos_spec][, RECSIZ:record_size]
&    [, SERVERCONNECTION:myhand][, SHARE:share_spec][, TEMPFILE[:temp_spec]][, FDL:string]
&    [, BKTSIZ:bucket_size][, BLKSIZ:block_size][, BUFNUM:number][, BUFSIZ:blocks]
&    [, CONTIG:value][, DEQ:blocks][, RECTYPE:record_type]) [[error_list]]

Arguments

channel

The channel to be opened. Valid channel numbers are 1 through 1024. Alternatively, you can set channel to a variable that equals 0 to make the runtime generate a channel number automatically. (n)

mode_spec

See Modes and submodes for mode specification syntax:

file_spec

The name of the file or device to be opened. The default file extension is .ddf. For ISAM files, the default extension is .ism. See File specifications for more information about valid file specifications. (a)

ALLOC

(optional) Defines the initial allocation for a file being opened for output. See ALLOC for a complete description. (OpenVMS only)

LOCK

(optional) Specifies whether record locking is performed on the specified channel. See LOCK for a complete description.

OPTIONS

(optional) Specifies one or more runtime options. See OPTIONS for a complete description.

POSITION

(optional) Defines the position at which the first sequential I/O operation begins. See POSITION for a complete description. (Windows, Unix only)

RECSIZ

(optional) Sets the record size for the file being opened. With this option you can specify a record size, or you can set the record size to the length of the first record in the file. See RECSIZ for a complete description.

SERVERCONNECTION

(optional) Open the file on the specified xfServer connection (instead of using the @server syntax). See SERVERCONNECTION for a complete description.

(optional) Specifies whether the file can be accessed by other users. On an OPEN statement, you can specify the SHARE qualifier with a file open for input and/or with a sequential file type. See SHARE for a complete description.

TEMPFILE

(optional) Defines an intermediate file to be used when opening in output mode (as in versions prior to Synergy DBL 5). See Temporary files (Windows and Unix) for more information.

FDL

(optional) Specifies an FDL or XDL string or file description. See FDL for a complete description.

BKTSIZ

(optional) Specifies the RMS bucket size to be used on the OPEN statement. See BKTSIZ for a complete description. (OpenVMS only)

BLKSIZ

(optional) Specifies the RMS block size in bytes. See BLKSIZ for a complete description. (OpenVMS only)

BUFNUM

(optional) Sets the number of process local I/O buffers. See BUFNUM for a complete description. (OpenVMS only)

BUFSIZ

(optional) Sets the buffer size. See BUFSIZ for a complete description. (OpenVMS only)

CONTIG

(optional) Allocates the contiguity of a file. See CONTIG for a complete description. (OpenVMS only)

DEQ

(optional) Sets the number of blocks to add when a file is automatically extended. See DEQ for a complete description. (OpenVMS only)

RECTYPE

(optional) Defines the type of records to write to a file. See RECTYPE for a complete description. (OpenVMS only)

error_list

(optional) An I/O error list. If any one of the specified errors occurs as part of the OPEN, control is transferred to the associated label.

Discussion

This Discussion includes the following subtopics:

Modes and submodes
Opening a terminal
Opening a port (Windows and Unix)
OPEN
Open pipes (OpenVMS)
Using O:P mode on OpenVMS
Temporary files (Windows and Unix)
Maximum file size

The OPEN statement opens a file or device (for example, a terminal, port, mailbox device, etc.) on a specified channel and defines the type of input and output allowed.

If a qualifier that has no function under a specific system is specified, it is ignored and no error occurs.

If the OPEN is successful, all subsequent I/O operations are able to reference the opened channel. If an error other than a “Channel is in use” error ($ERR_CHNUSE) occurs during the OPEN, the specified channel is not assigned and is still available for a subsequent OPEN.

If an .is2 file is detected, an OPEN on ISAM files fails with a “Failure during I/O operation” error ($ERR_IOFAIL) from Synergy DBL and a DE_OPNIDX error from Synergy DBMS Connection.

If channel is passed as a writable variable with a zero value (var=0), the next free channel number will be used, and the channel number variable will be updated with the channel number value. The variable must be able to contain a four-digit number, or a BIGNUM error will occur. The runtime will start looking for an unused channel number at 1024 (the maximum) and search backwards to 1 until it finds one.

On Windows, we recommend that Synergy data files (including temporary files, such as SORT or DTKTMP files) either reside in directories that are excluded from real-time scanning by a virus scanner or use extensions the virus scanner does not scan by default.

Modes and submodes

Mode_spec is one of the following mode specifications:

mode[:sub]

Compile-time mode

MODE:var

Mode and submode are determined at runtime.

mode

The mode in which to open the channel: (a)

I = Input mode. Allows read access of an existing file.

O = Output mode. Creates a new file opened for exclusive access. Files opened in O mode on OpenVMS default to sequential submode. To change the default to stream, use the /stream qualifier.

U = Update mode. Allows read and write access of an existing file and locks the record when read.

A = Append mode. Functions like output mode, except that if the file already exists, it positions to the end of the file.

sub

(optional) One of the following submodes in which to open the file: (a)

S = Sequential submode. Specifies sequential access of the file.

R = Relative submode. Specifies relative access of the file.

I = Indexed submode. Indicates that the file is an ISAM file.

B = Block submode. Allows direct block access to files. (See the Discussion for more information.)

P = Print submode. Used with output mode only. Creates a file for output to a printer-like device.

C = Character submode. Indicates that character I/O is performed on the specified channel (used for terminal I/O).

* = Wildcard. Opens the file as if the appropriate submode for the file’s actual organization had been specified (S for sequential, R for relative, or I for indexed). This submode cannot be used with output mode (O), and using the DELETE statement is not allowed on a file opened in U:* mode. (OpenVMS only)

var

An expression that contains the mode and optional submode in the form mode[:sub] from above (for example, “i:i”). (a)

When you specify an I/O mode, mode determines how a program accesses a file, and submode defines how a program processes a file and, in some cases, the organization of the file being accessed. The submode enables you to detail the use of the file. If a submode is present on a file opened in output mode, the created file has the characteristics specified by submode. If a submode is present on a file opened in any other mode, the file’s characteristics are checked.

If you open a channel without specifying a submode, the default is stream submode on all systems except OpenVMS. On OpenVMS,

If no submode is specified on file creation, the default is sequential (which means you can’t use GET and PUT statements on the file). When creating a file with xfServer without a submode, the file will be sequential with stream record format. However, when a file is created directly on OpenVMS without a submode the file will be sequential with variable-length record format.
If no submode is specified on existing file opens, the submode is determined by the file type.

We recommend that you always specify a submode, even if the default submode automatically determines the file type for your system. The behavior that occurs when a submode is not specified may differ if you migrate to another system.

When block (B) submode is specified, only I/O requests that are a multiple of the block or sector size of the operating environment are allowed on READ, READS, and WRITE statements. However, if you are opening to a device, the device—rather than the operating environment—may determine the block size. All operations in block submode start on a block size boundary.

The WRITES statement does not require that the buffer be a multiple of the block size. Sequential operations following a WRITES operation with a buffer that is not a multiple of block size start on the next block size boundary. The area between partial write and the next block is undefined.

Only certain combinations of I/O modes and submodes are allowed on certain I/O statements. The following table lists each of the I/O statements and their valid modes and submodes.

= Allowed
V = OpenVMS only
WU = Windows, Unix
* = Must add permission on OpenVMS

Submode and mode	ACCEPT	DELETE	DISPLAY	FIND	FORMS	GETS	PUTS	READ	READ FST	READ LST	READS	REVERSE	WRITE	WRITE LST EOF	WRITES
Stream I
Sequential stream_CR I				V				V	V		V
Sequential stream_LF I				V				V	V		V
Stream O
Sequential stream_CR O			V								V				V
Sequential stream_LF O			V								V				V
Stream U
Sequential stream_CR U^a				V	V			V			V		V		V
Sequential stream_LF U^a				V	V			V			V		V		V
Sequential I										WU
Sequential O										WU
Sequential U				V	V			V	V		V		V		V
Relative I										WU		*
Relative O										WU		*		WU
Relative U										WU		*		WU
ISAM I										*
ISAM O										*
ISAM U		^b								*
Block I
Block O
Block U
Null device I	V		V		V	V	V				V				V
Null device O	V		V		V	V	V				V				V
Null device U	V		V		V	V	V
Mailbox I											V
Mailbox O											V				V
Mailbox U											V				V
Record-oriented device I											V
Record-oriented device O
Record-oriented device U
Spooled network device O:P			V		V						V				V
Spooled network device U					V						V				V
Printer O:P	V					V	V				V
Print O
Print U
Terminal I
Terminal O
Terminal U
Pipe I	WU					WU
Pipe O			WU		WU		WU
Pipe U											V				V

a. Due to unpredictable results and potential side effects of the RMS implementation, we do not recommend or support opening a stream_CR or stream_LF file in update mode.

b. U:* cannot be used with DELETE on OpenVMS. To delete records, open the file with an explicit submode (e.g., U:I).

If an invalid mode is specified on the OPEN statement, you’ll get a “Bad mode specified” error ($ERR_IOMODE).

An OPEN for output mode supersedes existing files, unless the FLAGS subroutine runtime option 3 is set. To create an ISAM file, you must specify the FDL qualifier with either an XDL file, FDL file, or XDL or FDL string.

Input mode (I:I) sets up input-only access and restricts the channel to the use of the CLOSE, FIND, READ, and READS statements. Update mode (U:I) declares that the channel can be used for input as well as deletion and update activity. In U:I mode, all ISAM I/O statements are available for use.

If the LOCK qualifier is not specified, subsequent I/O operations use automatic locks. In input mode, this means that no record locking is performed on the data file (.is1), but tree locking is performed on the index file (.ism) to maintain the integrity of the ISAM file’s index. In update mode, this means that both record locking and tree locking are performed. Whenever locking (record or file) is used, when you open a file in I:I mode, neither the index nor data file require write permission. With U:I mode, both the index and data files need write permission.

The default record locking state is automatic locking. If you specify LOCK:Q_NO_LOCK on the OPEN statement to change the default record locking behavior, no record locking is performed.

An OPEN using append (A) or output (O) mode includes an implied SHARE mode of Q_EXCL_RW to gain exclusive access to the file.

Opening a terminal

A terminal device (TT:) can be opened in either input or output mode, and with or without the C submode. If a terminal is opened in input mode, output can also be performed, and vice versa.

On OpenVMS, when you open TT:, Synergy DBL works in the following manner:

If neither system option #35 nor #39 is set, DBL opens SYS$INPUT and SYS$OUTPUT. If you’re running your program from a command file or batch job, DCL maps SYS$INPUT to SYS$COMMAND, so that input comes from the command file, not the terminal.
If system option #35 or #39 is set, DBL opens the logical TT:. If you’re running your Synergy program from a command file, the logical TT: is defined by DCL as the terminal, so DBL opens the terminal. If you’re running your program from a batch job, a detached job, or a network process (any process for which the deprecated %TNMBR routine returns a negative value, which currently includes just these three types), DBL works as if system options #35 and #39 are not set. See the preceding paragraph.

If you want to get your input from the terminal when you’re running from a command file on OpenVMS, either set system option #35 or #39, or define SYS$INPUT as TT:. For example:

$ define/user sys$input tt:

Defining SYS$INPUT as TT: only works for the program that is started immediately following this define command, and the logical does not remain set across program chains. If several programs are to be run in the command file, the define/user command should be present before each one. The logical will be reset after the program is run.

Opening a port (Windows and Unix)

On Windows, you must include a colon at the end of the port name passed as the file_spec argument. For example, to open the COM1 port, your OPEN statement would look something like this:

open(portnum, 'o', 'com1:')

If the colon isn’t present, “com1” is interpreted as a filename rather than a device and won’t be found.

On Unix, do not include a colon at the end of the port name. If the port name ends in a colon, it’s interpreted as an environment variable. Also, you must pass both the path and the device name. For example:

open(portnum, 'o', '/dev/tty03')

Open pipes (Windows and Unix)

You can optionally execute a command through an opened pipe using the following syntax:

OPEN(channel, mode, command)

channel

The channel to be opened (1–1024). (n)

mode

Either I for input mode or O for output mode, with no submode specified. Mode determines the direction of the pipe, which might be output from the Synergy program to a subprocess, or input to the Synergy program from a subprocess. (a)

command

A vertical bar (|) followed by a command to be executed (up to 255 characters). Command shares one end of the pipe with the Synergy program executing the OPEN. (a)

You can get the status of the command after a CLOSE statement using the XSTAT subroutine.

On Windows, you cannot use this method for shell commands, such as dir. For shell commands, you must execute the program (cmd) and pass the command (dir). For example:

open(2,i,"|cmd /c dir")

To execute a shell script on Unix, the first line must begin with #! or the script will not execute. For example:

#! /bin/bash

If you are using option #22 for LPQUE, make sure the first line of dblpq includes this line.

Open pipes (OpenVMS)

You can execute a command or a series of commands through an opened pipe using this syntax:

OPEN(channel, mode, command)

channel

The channel to be opened (1–1024). (n)

mode

Either I for input mode, O for output mode, or U for a two-way pipe, with no submode specified. Mode determines the direction of the pipe, which might be output from the Synergy DBL program to a subprocess, or input to the Synergy program from a subprocess, or both. (a)

command

A vertical bar ( | ) followed by a command to be executed (up to 255 characters). Command shares one end of the pipe with the Synergy program executing the OPEN. (a)

You can get the status of the last command executed after a CLOSE statement using the XSTAT subroutine.

Using the above open pipe syntax, an OpenVMS command can be written, output from the command can be read, and when end of file has been encountered on the READS, another command can be written. Your program can write ASCII(3) or ASCII(25) to stop the current program running on that pipe. (These are OpenVMS terminal driver special sequences, Ctrl+C and Ctrl+Y, that interrupt a program.) Sending ASCII(25) sends EOF to the pipe, which is the exit signal for many OpenVMS programs. You can do a READ from a pipe with a time-out that limits how long to wait for a command to produce output. This is useful when dealing with programs that can be run at a pipe, but go into loops or other infinite wait states.

Using O:P mode on OpenVMS

If you need to edit files created in O:P mode on OpenVMS, set system option #38 before running the program that creates the files. If system option #38 is not set, the files will not look correct when you edit them. Additionally, stream files (files opened in O:S mode with RECTYPE of 4, 5, or 6) will not look correct when PRINTed or TYPEd. Use O:P mode for files to be PRINTed or TYPEd. Also, if you use the FLAGS subroutine (with flag 6 set) to disable carriage control, do not try to PRINT or TYPE the file unless you use O:P mode and set system option #38.

If you open a mailbox device in O:P mode on OpenVMS, the runtime generates an error.

Temporary files (Windows and Unix)

If you specify the TEMPFILE qualifier when opening a file in output mode and a file with the same name already exists, a temporary file is created. The temporary file either replaces the existing file on a CLOSE, or it is deleted if no CLOSE is performed or if a PURGE is executed. If you open an existing file in output mode without specifying the TEMPFILE qualifier, no temporary file is created and the existing file is deleted on the OPEN.

Maximum file size

The maximum file size for each operating system is as follows:

System	File type	Maximum size per physical file
Windows	FAT16/32	2,147,483,647 bytes
	TBYTE ISAM file on NTFS	REV 4: 1,099,511,627,775 bytes (1 terabyte) REV 6: 281,474,976,710,655 bytes (256 terabytes)
	Non-TBYTE ISAM file on NTFS	2,147,483,647 bytes
	Non-ISAM file	Physical drive size limit
Unix	TBYTE ISAM file	REV 4: 1,099,511,627,775 bytes (1 terabyte) REV 6: 281,474,976,710,655 bytes (256 terabytes)
	Non-TBYTE ISAM file	2,147,483,647 bytes or file size ulimit (whichever is smaller)
	Non-ISAM file	Physical drive size limit
OpenVMS	RMS OpenVMS 6.0 or higher	1,099,511,627,775 bytes

On Unix, for files larger than 2 GB, ensure the file system being used enables Large File Support (LFS) and the operating system setting for the file size ulimit is sufficient for the largest file size expected. This is especially important when using terabyte ISAM files. An “Output file is full” error ($ERR_FILFUL) occurs when a file reaches the system-imposed file size ulimit.

In Synergy .NET, when using multiple threads, ensure I/O to a specific channel is synchronized so it only occurs on one thread at a time. Destructors that perform I/O implicitly cause multi-threading. If you open files to xfServer with threading, see S_SERVER_THREAD_INIT for more information.