The device to be opened, specified by a device ID or a device alias. A device ID can be an integer (a device number), a device name, or the pathname of a sequential file. If a string, it must be enclosed with quotation marks. The maximum length of device is 256 characters.
Optional The list of parameters used to set device characteristics. The parameter list is enclosed in parentheses, and the parameters in the list are separated by colons. Parameters can either be positional (specified in a fixed order in the parameter list) or keyword (specified in any order). A mix of positional and keyword parameters is permitted. The individual parameters and their positions and keywords are highly device-dependent.
Use the OPEN command to acquire ownership of a specified device (or devices) for input/output operations. An OPEN retains ownership of the device until ownership is released with the CLOSE command.
An OPEN command can be used to open multiple devices by using a comma to separated the specifications for each device. Within the specification of a device, its arguments are separated by using colons (:). If an argument is omitted, the positional colon must be specified; however, trailing colons are not required.
The OPEN command can be used to open devices such as terminal devices, magnetic tape devices, spool devices, TCP bindings, interprocess pipes, named pipes, and interjob communications.
The OPEN command can also be used to open a sequential file. The device argument specifies the file pathname as a quoted string. The parameters argument specifies the parameters governing the sequential file. These parameters can include the option of creating a new file if the specified file does not exist. Specifying the timeout argument, though optional, is strongly encouraged when opening a sequential file.
The OPEN command is not used to access a Caché database file.
On Windows, ObjectScript allocates each process an open file quota between database files and files opened with OPEN. When OPEN causes too many files to be allocated to OPEN commands, you receive a <TOOMANYFILES> error. The Caché maximum number of open files for a process is 1,024. The actual maximum number of open files for each process is a platform-specific setting. For example, Windows defaults to a maximum of 998 open files per process. Consult the operating system documentation for your system.
An optional postconditional expression. Caché executes the OPEN command if the postconditional expression is true (evaluates to a nonzero numeric value). Caché does not execute the OPEN command if the postconditional expression is false (evaluates to zero). Only one postconditional is permitted, even if the OPEN command opens multiple devices or files. For further details, refer to Command Postconditional Expressions in Using Caché ObjectScript.
The device to be opened. You can specify the device using any of the following:
Physical device number, specified as a positive integer. For example, 2 is always the spooler device. This is the only way to specify a magnetic tape device (numbers 47 through 62). This number is internal to Caché and is unrelated to device numbers assigned by the platform operating system.
Device ID, specified as a quoted string. For example, "|TRM|:|4294318809". This value for the current device is found in the $IO special variable.
Device alias, specified as a positive integer. A device alias refers to a physical device number.
File pathname, specified as a quoted string. This is used for opening sequential files. A pathname can be canonical (c:\myfiles\testfile) or relative to the current directory (\myfiles\testfile).
The list of parameters used to set operating characteristics of the device to be opened. The enclosing parentheses are required if there is more than one parameter. (It’s good programming practice to always use parentheses when you specify a parameter.) Note the required colon before the left parenthesis. Within the parentheses, colons are used to separate multiple parameters.
The parameters for a device can be specified using either positional parameters or keyword parameters. You can also mix positional parameters and keyword parameters within the same parameter list.
In most cases, specifying contradictory, duplicate, or invalid parameter values does not result in an error. Wherever possible, Caché ignores inappropriate parameter values and takes appropriate defaults.
If you do not specify a list of parameters, Caché uses the device’s default parameters. The default parameters for a device are configurable. Go to the Management Portal, select [Home] > [Configuration] > [Device Settings] > [Devices] to display the current list of devices. For the desired device, click edit to display its Open Parameters: option. Specify this value in the same way you specify the OPEN command parameters, including the enclosing parentheses. For example, ("AVL":0:2048).
Positional parameters must be specified in a fixed sequence in the parameter list. You can omit a positional parameter (and receive the default value), but you must retain the colon to indicate the position of the omitted positional parameter. Trailing colons are not required; excess colons are ignored. The individual parameters and their positions are highly device-dependent. There are two types of positional parameters: values and letter code strings.
A value can be an integer (for example, record size), a string (for example, host name), or a variable or expression that evaluates to a value.
A letter code string uses individual letters to specify device characteristics for the open operation. For most devices, this letter code string is one of the positional parameters. You can specify any number of letters in the string, and specify the letters in any order. Letter codes are not case-sensitive. A letter code string is enclosed in quotation marks; no spaces or other punctuation is allowed within a letter code string (exception: K and Y may be followed by a name delimited by backslashes: thus: K\name\). For example, when opening a sequential file, you might specify a letter code string of ANDFW (append to existing file, create new file, delete file, fix-length records, write access.) The position of the letter code string parameter, and the meanings of individual letters is highly device-dependent.
Keyword parameters can be specified in any sequence in the parameter list. A parameter list can consist entirely of keyword parameters, or it can contain a mix of positional and keyword parameters. (Commonly, the positional parameters are specified first (in their correct positions) followed by the keyword parameters.) You must separate all parameters (positional or keyword) with a colon (:). A parameter list of keyword parameters has the following general syntax:
The individual parameters and their positions are highly device-dependent. As a general rule, you can specify the same parameters and values using either a positional parameter or a keyword parameter. You can specify a letter code string as a keyword parameter by using the /PARAMS keyword.
The number of seconds to wait for the OPEN request to succeed. The preceding colon is required. timeout must be specified as an integer value or expression. If timeout is set to zero (0), OPEN makes a single attempt to open the file. If the attempt fails, the OPEN immediately fails. If the attempt succeeds it successfully opens the file. If timeout is not set, Caché will continue trying to open the device until the OPEN is successful or the process is terminated manually. If you use the timeout option and the device is successfully opened, Caché sets the $TEST special variable to 1 (TRUE). If the device cannot be opened within the timeout period, Caché sets $TEST to 0 (FALSE). Note that $TEST can also be set by the user, or by a JOB, LOCK, or READ timeout.
The name of the mnemonic space that contains the device control mnemonics used by this device. By default, Caché provides two mnemonic spaces: ^%XMAG for magnetic tape devices, and ^%X364 (ANSI X3.64 compatible) for all other devices and sequential files. Default mnemonic spaces are assigned by device type.
Go to the Management Portal, select [Home] > [Configuration] > [Device Settings] > [IO Settings]. View and edit the File, MagTape, Other, or Terminal mnemonic space setting.
A mnemonic space is a routine that contains entry points for the device control mnemonics used by READ and WRITE commands. The READ and WRITE commands invoke these device control mnemonics using the /mnemonic(params) syntax. These device control mnemonics perform operations such a moving the cursor to a specified screen location or rewinding a magnetic tape.
Use the mnespace argument to override the default mnemonic space assignment. Specify an ObjectScript routine that contains the control mnemonics entry points used with this device. The enclosing double quotes are required. Specify this option only if you plan to use device control mnemonics with the READ or WRITE command. If the mnemonic space does not exist, a <NOROUTINE> error is returned. For further details on mnemonic spaces, see I/O Devices and Commands in the Caché I/O Device Guide.
In the following example, the OPEN command attempts to acquire ownership of device 2 (the spooler). The first positional parameter (3) specifies the file number within the ^SPOOL global and the second positional parameter (12) specifies the line number within the file. If you later use the USE command to make this the current device (that is, USE 2), ObjectScript sends subsequent output to the spooler.
In the following example, the OPEN command attempts to acquire ownership of the sequential file CUSTOMER within the timeout period of 10 seconds.
Note that because no parameters are specified, the parentheses are omitted, but the colon must be present.
The following example opens a sequential file named Seqtest; the letter code positional parameter is NRW. The N letter code specifies that if the file does not exist, create a new sequential file with this name. The R and W letter codes specify that the file is being opened for reading and writing. The timeout is 5 seconds.
NEW$NAMESPACESET$NAMESPACE="%SYS"SETdir=##class(%SYSTEM.Process).CurrentDirectory(); determine Caché directory SETseqfilename=dir_"Samples\Seqtest"OPENseqfilename:("NRW"):5WRITE!,"Opened a sequential file named Seqtest"USEseqfilenameWRITE"a line of data for the sequential file"CLOSEseqfilename:"D"WRITE!,"Closed and deleted Seqtest"QUIT
This example requires that UnknownUser have assigned the %DB_CACHESYS role.
OPEN establishes ownership of the specified device. The process retains ownership of the device until the process either terminates or releases the device with a subsequent CLOSE command. While a device is owned by a process, no other process can acquire or use the device.
A process can own multiple devices at the same time. However, only one device can be the current device. You establish an owned device as the current device with the USE command. The ID of the current device is found in the $IO special variable.
A process always owns at least one device (designated as device 0), which is its principal device. This device is assigned to the process when it is started and is typically the terminal used to sign onto Caché. The ID of the principal device is found in the $PRINCIPAL special variable.
When a process terminates, Caché issues an implicit CLOSE for each of the devices owned by the process and returns them to the pool of available devices.
To change the parameters for a device that is already owned by the process, you can:
Close and then reopen the device with new parameter values.
If the device is a terminal, TCP, or magnetic tape device, you can issue an OPEN with new parameter values on an already open device.
If you specify the device on another OPEN command, any device parameters set by the initial OPEN command remain in effect unless explicitly changed. Depending on the type of device, subsequent I/O may be different than if you had closed and then reopened the device.
For some devices, you can omit the parameters option and later set the desired characteristics with the parameters option on the USE command.
An alias is an alternate numeric device ID. It must be a valid device number, it must be unique and cannot conflict with an assigned device number.
You can establish a numeric alias for a device. Go to the Management Portal, select [Home] > [Configuration] > [Device Settings] > [Devices] to display the current list of devices and their aliases. For the desired device, click edit to edit its Alias: option.
After you have assigned an alias to a device, you can use the OPEN command or the %IS utility to open the device using this alias.
Caché allocates each process' open file quota between database files and files opened with OPEN. When OPEN causes too many files to be allocated to OPEN commands, you receive a <TOOMANYFILES> error. The Caché maximum number of open files for a process is 1,024. The actual maximum number of open files for each process is a platform-specific setting. For example, Windows defaults to a maximum of 998 open files per process.