I/O Device Guide
Local Interprocess Communication
|
|
OPEN program:(parameters):timeout
OPEN cpipename:program:timeout OPEN cpipename:(program:parameters:::closetimeout):timeout
Argument | Description |
---|---|
cpipename | Command Pipes Only either "|CPIPE|" or "|CPIPE|xxxxxx", where xxxxxx represents a user-specified unique identifier. |
program | A command pipe can execute a program with a command shell, or without a command shell (directly). Executing without a command shell is preferred in most situations. A standard pipe executes a program with a command shell. Command Pipes Only To execute without a command shell, specify /COMMAND=program. If program has arguments, you must specify them using the /ARGS keyword. If you specify either the /COMMAND or /ARGS keyword, the program is executed without a command shell: (/COMMAND=program), (/COMMAND=program:/ARGS=arg1) and (program:/ARGS=arg1) are all valid syntax. /ARGS can take a single argument, a comma-separated list of arguments, or an array. For example, (/COMMAND=program:/ARGS=arg1,arg2). You can specify a variable number of arguments using an array: SET array(1)=arg1, array(2)=arg2, array=2
OPEN device:(/COMMAND=cmd:/ARGS=array...) To execute using a command shell, specify program, omitting both the /COMMAND and /ARGS keywords. The program string contains the full pathname of a program installed on your system. It contains the command name and its arguments (if any) to be executed on the host system. For a standard pipe, limited to <256 characters. For command pipe, maximum length is platform dependent, but substantially more than 256 characters. |
parameters | Read. For a standard pipe specify “Q” or “QR” to open a queue or pipe to accept input from another process. For a command pipe: because a command pipe is unambiguously a pipe, the “Q” letter code is not required; specify “R”. Write. For a standard pipe specify “QW” to open a queue to send input to another process. For a command pipe: because a command pipe is unambiguously a pipe, the “Q” letter code is not required; specify “W”. You can specify these and other parameters using the /keyword parameters, separated by colons. For example, OPEN "|CPIPE|":(cmd:/READ:/IOTABLE="UTF8"). The following optional keyword parameters are commonly used with pipes: “K/name/” (or “Knum” ) to enable I/O translation, if translation has been enabled system-wide. You identify the previously defined table on which the translation is based by specifying the table's name. The “+” and “-” options for turning protocols on and off are not available with the “K” protocol. “Y/name/” (or “Ynum”) to tell the system to use the named $X/$Y Action Table. You identify the previously defined $X/$Y Action Table on which translation is based by specifying the table's name. $X/$Y action is always enabled. If Y is not specified and a system default $X/$Y is not defined, a built in $X/$Y action table is used. The “+” and “-” options for turning protocols on and off are not available with the Y protocol. You can specify the “S” (stream), “F” (fixed length), or “U” (undefined length) mode parameters with the above parameters. You cannot specify the “V” (variable length) mode parameter. For a complete list of letter code and keyword parameters, refer to OPEN Mode Parameters in the “Sequential File I/O” chapter of this manual. |
closetimeout | Optional UNIX® only: You can specify the number of seconds the CLOSE command will wait for the command process to exit when closing a piped command device. The default is 30 seconds. You can override this closetimeout by specifying an I (immediate) argument on the CLOSE command for interprocess communication. |
timeout | Optional A positive integer whose value in seconds is the longest time InterSystems IRIS waits for an OPEN to successfully finish. If InterSystems IRIS is able to open interprocess communication before the timeout expires, it sets $TEST to 1. If InterSystems IRIS is not able to open interprocess communication before the timeout expires, it sets $TEST to 0. If you omit the timeout or specify 0, the OPEN returns control to the process immediately. |
OPEN "|CPIPE|1":"/nethome/myprog":10 // using shell, no args OPEN "|CPIPE|1":("/nethome/myprog":/WRITE):10 // using shell, no args, WRITE OPEN "|CPIPE|2":/COMMAND="/nethome/myprog":10 // no shell, no args OPEN "|CPIPE|3":("":/COMMAND="/nethome/myprog"):10 // no shell, no args OPEN "|CPIPE|4":(/COMMAND="/nethome/myprog":/ARGS=arg1):10 // no shell, 1 arg OPEN "|CPIPE|5":("/nethome/myprog":/ARGS=arg1):10 // no shell, 1 arg OPEN "|CPIPE|6":("/nethome/myprog":/ARGS=arg1:/WRITE):10 // no shell, 1 arg, WRITE OPEN "|CPIPE|7":(/COMMAND="/nethome/myprog":/ARGS=arg1,arg2):10 // no shell, 2 args OPEN "|CPIPE|8":(/COMMAND="/nethome/myprog":/ARGS=args...:/WRITE):10 // no shell, args array, WRITE
print ; Send the first layer of global ^TEXT to the printer. SET IO="/usr/bin/lp" OPEN IO:"QW" ; Open the pipe to lp USE IO WRITE "The first layer of ^TEXT",! ; Print the title ; . . . ; Print each line, using $ORDER on the global ^TEXT USE IO WRITE !,"The End.",# CLOSE IO ; close the pipe, spooling the file to lpsched QUIT
getids ; read the login IDs of everybody currently on SET IO="/usr/bin/who" SET $ZTRAP="EOT" KILL LOGINS OPEN IO:"Q" ; note that "R" (the default) is understood SET users=0 FOR I=0:0 { USE IO READ USER SET users=users+1 SET LOGINS(USER)="" } QUIT EOT SET $ZTRAP="" USE 0 WRITE !,USERS," is/are currently logged on.",! CLOSE IO QUIT
Keyword | Default | Description |
---|---|---|
/IOTABLE[=name] /IOT[=name] |
If name is not specified, the default I/O translation table for the device is used. | Corresponds to the K\name\ parameter code, which establishes an I/O translation table for the device. |
/TRANSLATE[=n] /TRA[=n] |
1 | Associated with the K parameter code. /TRANSLATE or /TRANSLATE=n for nonzero values of n enable I/O translation for the device. /TRANSLATE=n for a zero value of n disables I/O translation for the device. |
/XYTABLE[=name] /XYT[=name] |
If name is not specified, the default $X/$Y action table for the device is used. | Corresponds to the Y\name\ parameter code, which establishes a $X/$Y action table for the device. |
Keyword | Default | Description |
---|---|---|
/IGNOREEOF[=n] /IGN[=n] |
0 | Corresponds to the I parameter code, which specifies that a READ operation should be retried (ignoring any EOF condition) indefinitely or until the specified timeout expires. /IGNOREEOF or /IGNOREEOF=n for nonzero values of n enable the parameter code and /IGNOREEOF=n for a zero value of n disables the parameter code. |
/PARAMS=str /PAR=str |
No default | Corresponds to the parameter codes positional parameter. (It provides a way to specify a parameter code string in a position independent way.) |
/QUEUE /QUE |
The device is not recognized as an interprocess communications pipe. | Corresponds to the “Q” parameter code, which specifies that an interprocess communications pipe should be opened. Note that using this command requires Use permission on the %System_Callout resource. |
/Read | Read is the default if neither /Read nor /Write is specified. | Corresponds to the “R” parameter code, which specifies that a queue or pipe should be opened to accept data from another process. |
/Write /WRI |
Read is the default if neither /Read nor /Write is specified. | Corresponds to the “W” parameter code, which specifies that a queue or pipe should be opened to send data to another process. |
READ:pc readargument,...
formatting-mode string variable:timeout *variable:timeout variable#n:timeout
CLOSE cpipename:"I"
OPEN "|NPIPE|3":(server:pipename)
Keyword | Default | Description |
---|---|---|
/HOSTNAME=str /HOS=str |
The default is "" (quotes without content), which opens the pipe as a server. | Corresponds to the server positional parameter, which specifies the Windows NT workstation/server name. It is not necessary to specify this keyword when opening the pipe as a server. Use "." (a quoted period) to connect to a local pipename. |
/IBUFSIZE=n /IBU=n |
2048 | Specifies the size of the named pipe input buffer that holds data received from the pipe but not yet delivered to the application. |
/INSTANCES=n /INS=n |
1 | Specifies the maximum number of instances allowed for the named pipe. A value greater than 1 allows more than one server to open an instance of the named pipe, so that more than one client at a time can be served. |
/OBUFSIZE=n /OBU=n |
2048 | Specifies the size of the output buffer used by the operating system. This buffer size is advisory, since the operating system sizes the buffer according to system-imposed constraints. |
/PIPENAME=str /PIP=str |
No default | Corresponds to the pipename positional parameter which specifies the name of the pipe. |
Buffers Allocated | READ Device # | WRITE Device # |
---|---|---|
1 | 224 | 225 |
2 | 226 | 227 |
3 | 228 | 229 |
... | ... | |
15 | 252 | 253 |
16 | 254 | 255 |
17 | 64 | 65 |
18 | 66 | 67 |
... | ... | ... |
83 | 196 | 197 |
84 | 198 | 199 |
85 | 4 | 5 |
86 | 6 | 7 |
87 | 8 | 9 |
88 | 10 | 11 |
89 | 12 | 13 |
90 | 14 | 15 |
91 | 16 | 17 |
92 | 18 | 19 |
93 | 2048 | 2049 |
94 | 2050 | 2051 |
95 | 2052 | 2053 |
... | ... | ... |
254 | 2370 | 2371 |
255 | 2372 | 2373 |
256 | 2374 | 2375 |
OPEN device::timeout
device | A device number from the table above. OPEN an even-numbered device to issue READ commands. OPEN an odd-numbered device to issue WRITE commands. For two processes to communicate, they must open a set of device pairs. |
timeout | Optional A positive integer whose value in seconds is the longest time InterSystems IRIS waits for an OPEN to finish. If you specify 0, the OPEN returns control to the process immediately. |