Positional Parameters for OPEN and USE Commands
The following positional parameters are available for the OPEN and USE commands. You can set these parameters for a device in either the OPEN or USE command, or take the defaults configured in the Management Portal. These parameters are positional; if you omit a parameter, you must include its preceding colon as a placeholder.
margin
The 1st positional parameter: An integer value specifying the right margin (and thus the number of characters per line). Values from 1 to 255 set the right margin for output; any other value disables the right margin. An empty string leaves the margin setting unchanged. On Windows platforms, you cannot use “:n” to control the print margin used. Such notation is ignored by InterSystems IRIS. Code such as “|PRN| :121” is ignored. To control the printer width, send the appropriate control characters for that printer. The notation does work on other platforms.
The default margins for various terminal types are defined in the Management Portal. Select System Administration, Configuration, Device Settings, Device Subtypes. When you click on “Edit” for each listed device subtype, it displays a Right Margin: default option.
protocols
The 2nd positional parameter: A string of letter code characters enclosed in quotation marks (for example, "BNFU”), where each letter enables one of the terminal’s rules for communicating. Letter codes are not case-sensitive. Letter codes may be specified in any order; because InterSystems IRIS executes them in left-to-right order, interactions between letter codes may dictate a preferred order in some cases. For a table of letter codes, see Letter Code Protocols.
A preceding plus or minus affects protocols as follows:
-
No preceding plus or minus: New string replaces prior protocols string.
-
Plus (+) precedes letter code string: Protocols in new string are added to prior protocols string.
-
Minus (-) precedes letter code string: Protocols in new string are turned off, but other protocols remain in effect.
The + and – options for turning protocols on and off are not available in DSM-11 compatibility modes.
terminator
The 3rd positional parameter: A string of up to eight characters, any of which will terminate a READ. These terminators are in addition to those built into the protocols. See Using Terminators to End I/O Operations.
portstate
The 4th positional parameter: A string of up to eight bytes in positional order that govern the COM port state. The portstate bytes are as follows (bytes are numbered from 1 in left-to-right order):
| Byte |
Meaning |
Values |
| 1 |
Disconnect |
D=disconnect (hangup) the port. blank=do not disconnect the port. |
| 2 |
Modem Control |
1=use modem control. 0=do not use modem control. blank=no change to modem control. |
| 3 |
Data Bits |
5=five data bits. 6=six data bits. 7=seven data bits. 8=eight data bits. blank=no change to data bit setting. |
| 4 |
Parity |
0=no parity. 1=odd parity. 2=even parity. 3=mark parity. 4=space parity. blank=no change to parity setting. |
| 5 |
Stop Bits |
1=one stop bit. 5=1.5 stop bits. 2=two stop bits. blank=no change to stop bit setting. |
| 6 |
Flow Control |
X=use Xon/Xoff flow control. C=use CTS/RTS flow control. D=use DSR/DTR flow control. N=disable flow control. blank=no change to flow control. |
| 7 |
DTR Setting |
0=disable DTR (set it off, keep it off). 1=enable DTR (set it on, keep it on). blank=no change to DTR state. |
| 8 |
$ZA Error Reporting |
0=disable $ZA error reporting (default). 1=enable $ZA error reporting. blank=no change to $ZA error reporting. |
The following example shows a COM port state string:
OPEN "COM2":(:::" 0801x0")
The string values are: blank (do not disconnect the port); 0 (do not use modem control); 8 (eight data bits); 0 (no parity); 1 (one stop bit); X (use Xon/Xoff flow control); 0 (disable DTR); default (disable $ZA error reporting).
The Disconnect parameter performs a hangup on modem-controlled ports by lowering the DTR signal for two seconds and then restoring it. A disconnect does not close the port; following a disconnect you can dial out again without reopening the COM device.
The Modem Control parameter determines how InterSystems IRIS responds to the state of the RLSD (Received Line Signal Detector) pin, also known as the DCD (Data Carrier Detect). If the line is modem controlled (modem control=1), InterSystems IRIS monitors the state of the RLSD, and generates an <ENDOFFILE> error if a READ command is issued when carrier is not present. InterSystems IRIS does not generate an error when a WRITE command is issued when carrier is not present. This is because it must be possible to send the dial command to the modem prior to a connection being established. InterSystems IRIS modem control can be enabled (1) or disabled (0) at any time. It is suggested that you disable modem control while sending commands to the modem, then enable modem control once carrier is detected and connection has been established.
The DTR Setting parameter is used to control login from an attached modem. If the DTR setting is 0 (zero), the DTR control signal is off, and modems cannot communicate with the computer. This prevents a dial-in connection from occurring. If the DTR setting is 1 (one), the DTR control signal is on, and modems can communicate with the computer. A dial-in connection can occur. If you configure DTR as off (0), then you must set it to on (1) with the OPEN command or USE command to be able to dial out using a connected modem. In most cases, the DTR setting is unimportant when using a null modem cable to connect directly to a terminal device or a serial printer. This is because the null modem cable should force the DTR control pin on.
The $ZA Error Reporting parameter enables reporting of the status of modem control pins to the $ZA special variable. This checking can be done regardless of the Modem Control byte setting for the COM port. If $ZA error reporting is enabled, COM port errors are cleared with a call to the Windows ClearCommError() function. The port error state is reported in the $ZA bits 16 through 22. For a table of $ZA bit values, refer to $ZA in the ObjectScript Reference.
baud
The 5th positional parameter: an integer value that specifies the desired COM port baud rate. The following baud rates are supported: 110, 300, 600, 1200, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000.
