OPEN Verb - Open File

Parameter

Description

channelno

Valid channel number.

MODE=string

System-dependent channel options, as seen below. (Using an unsupported MODE string will produce !ERROR=152.)

Note: These modes are system-dependent and may not be supported on all operating systems. Consider using these modes carefully, as they will result in non-portable code.

Options
O_RDONLY applies to all file types and opens the file as read only.

These modes apply to STRING files only, not to any of the BBx/BBj file types:

O_TRUNC

O_APPEND

O_CREATE

O_EXCL

Truncates the file.

Automatically sets the current file position to the end of the file.

Creates a string file to open if it does not exist.

Returns an error if the customer specified O_CREATE and the file already exists.

ISZ=num

In PRO/5, this LOCKs the file and processes it as if it were a raw STRING file. BBj does not LOCK the file automatically on open.

• int is usually -1 (ISZ=-1), but any non-zero value may be used.
• ISZ=0 is equivalent to not specifying the ISZ= option.
• In other Business BASICs, ISZ=int causes the file to be OPENed as if it were an INDEXED file with a record size of int. To approximate this behavior in PRO/5, process the file using READ RECORD and WRITE RECORD, with the SIZ=int qualifier.
• Any file opened with ISZ=-1 returns a file type of $03$ (STRING) in the FID().

In PRO/5 the automatic LOCK cannot be reversed with the UNLOCK verb. The file must be CLOSEd to clear the LOCK. In BBj, the file can be LOCKed and UNLOCKed as usual.

ERR=lineref

Branch to be taken if an error occurs during execution.

fileid

Name of the file, device to be opened.

Mode

Description

2GB

Converts a 4GB-formatted file back to 2GB (PRO/5 Rev. 2.x only).

• If the file size is over 2GB, opening the file will result in a failure of the OPEN and no conversion will take place.

• If a 4GB file ever exceeds 2GB, it cannot be converted back to 2GB using the "MODE=2GB" option. Deleting records to bring it under 2GB will not shrink the file. It is possible to create a new 2GB file, then copy the existing data into it.

4GB

Converts an MKEYED file from 2GB to 4GB (PRO/5 Rev. 2.x only).

• Using this mode for a file that is already 4GB-enabled will not cause PRO/5 to return an error, but it will take much longer to open the file.

• Using this mode on systems that do not support 4GB files will cause the OPEN and conversion process to fail. No changes will be made to the state of the MKEYED file.

PASSWD=

In PRO/5 PRO/5 and Visual PRO/5 4.10 and higher, and BBj 3.01 and higher, use password to when reading from or writing to password protected records

Only recoverable MKEYED files support this feature. Standard MKEYED files are not supported. Records written to a file opened with a password cannot be read unless the file was opened with the same password. Attempting to read a password protected record from a file that was opened with the wrong password will cause an !ERROR=7 (tcb(10)=19).

Attempting to read unprotected records from a file that was opened with a password will also cause an !ERROR=7 (tcb(10)=19).

This feature protects the individual records, not the file as a whole. Unprotected records or records protected with a different password can be added without knowledge of the password for the existing records. However, such additions will not be readable when the file is opened with the "official" password.

When using this feature, all records in the file should be protected with the same password. Otherwise, the file will be more difficult to repair if it becomes damaged or corrupt. This feature is designed to protect records from unauthorized reads and writes. It does not encrypt the data. Although older versions of PRO/5 and VPRO/5 cannot read protected records, they can remove protected records without knowledge of the password.

PIPE

In PRO/5 15.01 and higher, and BBj 15.10 and higher, the OPEN verb by default is restricted from opening pipes (commands starting with "<", ">", or "|") in console mode.  This is to protect against accidentally overwriting a data file as a side effect of inadvertently specifying a pipe expression.  To open a pipe at console, set SETOPTS byte 9 bit $10$ or include MODE="PIPE" in the OPEN.

CISAM

Required to OPEN a C-ISAM file.

CRYPTPASS=

In PRO/5 PRO/5 and Visual PRO/5 5.0 and higher, and BBj 4.0 and higher, this option opens an encrypted file with the specified encryption key. If the wrong key is specified or an encrypted file is opened without specifying this mode option, the open still succeeds, but READ returns meaningless data. The algorithm used depends on which version of b3crypt.dll or b3crypt.so is installed on your system. If b3crypt.dll or b3crypt.so was changed to a different version after the file was created, it might not be possible to read the file without changing b3crypt.dll or b3crypt.so back to the other version.

DDECLIENT

Local DDE connect.

NDDECLIENT

Network DDE connect.

KEYCHANGE={YES|NO}

When this mode is specified on the OPEN of a SYSGUI device, it directs Visual PRO/5 to accept or reject the Windows Keyboard Request event that controls the setting of international keyboards in Windows 95/98 or NT:

• "KEYCHANGE=YES" allows the change.

• "KEYCHANGE=NO" rejects the change.

If a MODE is not specified, Visual PRO/5 does not allow keyboard changes.

PERSIST

Causes all channels (including sockets) opened with this mode to remain open through the execution of a BEGIN statement. END closes the channel.

PREVIEW

Starts the Print Preview program and is added to the OPEN of a SYSPRINT device.

TEXT

Prints raw text to a SYSPRINT device. This mode does not work with PREVIEW.

FONT=

Replaces FONT= SYSPRINT. Any font valid for the device, such as enumerated in FIN(chan,ind=2), may be used. For example, the following forces a particular font to be used:

ALIAS LP SYSPRINT "printer" dialog,font="Courier New"

The number of available columns and rows is determined by the page size available to the Windows driver.

TMARGIN=

Specifies the top margin of the page. This, along with the LMARGIN= mode, specifies the starting position of the first line on the page for the SYSPRINT device.

LMARGIN=

Specifies the top margin of the page. LMARGIN, along with the TMARGIN= mode, specifies the starting position of the first line on the page for the SYSPRINT device.

HOST=<host>

Specifies the host.

PORT=<port>

If HOST= is specified, this mode identifies the port to connect to.

If HOST= is not specified, this mode identifies the port to start a server on.

REUSEADDR

Allows the reuse of local addresses.

KEEPALIVE

Enables the periodic transmission on messages on the TCP socket.

DONTROUTE

Bypasses standard routing.

LINGER

Delays a close command until all data has been sent.

NODELAY

Causes data to be sent immediately instead of waiting for a full send buffer.

HOST=<host>

Host to send packets to by default.

PORT=<port>

If HOST= is specified, this mode identifies the port to send packets to.

If HOST= is not specified, this mode identifies the port to listen to.

REUSEADDR

Allows the reuse of local addresses.

DONTROUTE

Bypasses standard routing.

BROADCAST

Enables the transmission of broadcast messages.