Local Interprocess Communication

Opening Pipes to InterSystems IRIS Utilities

You can open a pipe to an InterSystems IRIS utility as well as to UNIX® or Windows processes. Before you can use a pipe for utility I/O, your system manager must define the pipe device on your InterSystems IRIS system.

After the system manager defines the pipe device, when you run a utility (such as %RD), you answer the “Device:” prompt with the mnemonic the system manager defined. Your output goes automatically to that device.

Pipes and Command Pipes

InterSystems IRIS supports both standard pipes and command pipes (CPIPE). Standard pipes are used for relative short command strings, in which the command name and its arguments are less than 256 characters. Command pipes are used when the command string is 256 characters or more in length. In both cases, pipes can only be used on UNIX® and Windows systems.

Standard Pipe OPEN

The following is the OPEN command syntax for standard pipes:

OPEN program:(parameters):timeout

Because program is the first argument (the device argument), it must follow the OPEN command device name limitation of 256 characters.

If an OPEN command is issued for a standard pipe that is already open, the second OPEN is ignored. No error is issued.

Command Pipe OPEN

The following is the OPEN command syntax for command pipes:

OPEN cpipename:program:timeout
OPEN cpipename:(program:parameters:::closetimeout):timeout

The cpipename argument can take the value "|CPIPE|" if there is only command pipe open concurrently. To open multiple concurrent pipes, specify "|CPIPE|xxxxxx", where xxxxxx represents a user-specified unique identifier. This cpipename argument is the argument specified for subsequent USE and CLOSE commands.

Because program is the second argument, it is not limited to 256 characters. The maximum length of program is platform dependent.

If an OPEN command is issued for a command pipe that is already open, the second OPEN is ignored. No error is issued.

OPEN Command for Interprocess Communication

The OPEN command allows your program to communicate with processes external to InterSystems IRIS.

OPEN Command Pipe Examples

The following are valid command pipe OPEN statements. Each example specifies a timeout of 10 seconds:

  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

On a Windows system, an argument can include a blank space or a double quote (") character. In these cases, the argument can be quoted, and a literal double quote character can be escaped by doubling it:

  OPEN "|CPIPE|9":("/nethome/myprog":/ARGS="string with blanks"):10
  OPEN "|CPIPE|10":("/nethome/myprog":/ARGS="string with literal "" character"):10

OPEN Errors

If you issue an OPEN command with the “QW” parameter for a non-IPC device, a <WRITE> error occurs when you try to write to this device.

The following UNIX® example opens an output pipe to the lp program, whose pathname in this case is /usr/bin/lp. Then it sends output from the global ^TEXT to the printer through this pipe.

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

You can alter this example so that the OPEN command passes arguments to the lp program. For example, to specify that lp should send the output to the printer device named laserjet, you could replace the SET command with the following:

   SET IO="/usr/bin/lp -dlaserjet"

The following example shows how to read from an external program. Here the process opens an input pipe to the UNIX® program who, so that it can read the IDs of all users who are currently logged in to UNIX®.

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

On a Windows system, when a CPIPE OPEN program argument specifies /COMMAND or /ARGS, the system uses CreateProcess() to run the command. If the CreateProcess() fails, the OPEN will fail with a <NOTOPEN> error. The GetLastError() value is available via $SYSTEM.Process.OSError()Opens in a new tab.

On a UNIX® system, when a CPIPE OPEN program argument specifies /COMMAND or /ARGS, the system creates a new process which issues an exec() to run the command. If the exec() fails, the OPEN will fail with a <NOTOPEN> error. The exec() errno is available via $SYSTEM.Process.OSError()Opens in a new tab.

READ Command for Interprocess Communication

Syntax

READ:pc readargument,...

READ reads data from a pipe.

where readargument can be:

formatting-mode
string
variable:timeout
*variable:timeout
variable#n:timeout

Use the I formatting-mode parameter with pipes. The I parameter lets you issue a timed READ for a named pipe without losing any data that can occur in a partial record that follows an <ENDOFFILE> error. When you use this parameter on a READ, the READ ignores <ENDOFFILE> messages.

The value of the I formatting-mode is “off” by default. If you include this parameter in a READ command without a timeout, your process hangs until there is data to process.

CPIPE Exit Codes

You can retrieve the exit code of a command pipe (|CPIPE|) process. This exit code must be retrieved before the |CPIPE| device is closed. It is obtained with the PipeExitCodeOpens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. Exit codes are always integer values. If the exit code is not available, the method returns a null string and sets the status argument with an explanation, as shown in the following example:

  SET exitcode=$SYSTEM.Process.PipeExitCode(device, .status)
  IF exitcode="" {DO $SYSTEM.OBJ.DisplayError(status)}
  ELSE {WRITE "CPIPE exit code is ",exitcode } 

On a UNIX® system, an exit code is available only for non-shell commands; that is, CPIPE devices opened with /COMMAND or /ARGS.

CLOSE Command for Interprocess Communication

If you create a child process using OPEN with a “Q” (/QUEUE) parameter code, the child process may survive a CLOSE operation on the device. Survivability of a queued interprocess communications pipe is platform-dependent. On UNIX® systems the child process always survives the CLOSE. On Windows systems the survival of the process depends upon how old the process is. A child process that has just been initiated does not survive a CLOSE operation, but once a child process is fully established it survives a CLOSE.

On UNIX® systems, you can specify the how long the CLOSE command should wait when closing a piped command device. The timeout default is 30 seconds. You can modify this default by specifying the OPEN command closetimeout positional argument. You can override the default or specified timeout for a CLOSE command by specifying the optional “I” positional argument. The “I” argument specifies immediate close (close after 1 second). The CLOSE syntax is as follows:

CLOSE cpipename:"I"

Using Named Pipes to Communicate with Visual Basic

On Windows, use named pipes in InterSystems IRIS as you would use TCP devices, but use the device name “|NPIPE|nnn” instead of “|TCP|nnn”. The OPEN arguments are as follows:

OPEN "|NPIPE|3":(server:pipename)

where server is the Windows NT machine name, and pipename is the name of the pipe that it is to be connected to. Windows 95/98 machines cannot be named pipe servers, but can only connect to them.

To connect to a local pipename, use "." (a quoted period) as a server. To create a pipe (as a server), use "" (quotes without content) as the server name. The following are all valid server names:

   OPEN "|NPIPE|3":(".":"localpipe")
   OPEN "|NPIPE|3":("mother":"test")
   OPEN "|NPIPE|3":("":"info")

A server can open a named pipe and immediately issue a write before the client side has opened the same named pipe. The write operation will hang until the client side opens the named pipe. A user can interrupt the hang by issuing a Control-C.

Once open, a pipe acts like an ordinary device. On the server side, clients can be disconnected as in TCP with:

   USE "|NPIPE|3":"DISCONNECT"

Alternatively:

   USE "|NPIPE|3" WRITE *-2

Specifying Memory Buffers for Interjob Communication Devices

The system manager can configure the IJC buffers using the Management Portal. Select System Administration, Configuration, Additional Settings, Advanced Memory. The two parameters that can be set are:

• ijcnum: The maximum number of IJC devices. The range is from 0 through 256. The default is 16. If you edit this setting, you must restart InterSystems IRIS to apply the change.

• ijcbuff: The maximum size (in bytes) of each IJC buffer. The range is from 512 through 8192. The default size is 512 bytes. If you edit this setting, you must restart InterSystems IRIS to apply the change.

Each IJC device corresponds to one IJC buffer of the size specified in ijcbuff. You can write a message of length ijcbuff minus 1.

Interjob Communication Device Numbers

Interjob communication devices are automatically defined numbered by InterSystems IRIS. Their actual identification numbers depends on the maximum number of IJC buffers configured on the system.

The table below gives the ranges of IJC device numbers that are available on your system, depending on the number of IJC buffers that you have allocated.

For example, if you allocate 8 IJC buffers, then device numbers from 224 through 239 are defined on the system (even numbers for READ devices and odd numbers for WRITE devices).

As another example, if you allocate 94 IJC buffers, then the following range of device numbers are defined: 224 through 255, 64 through 199, 4 through 19, and 2048 through 2051. You can use any even/odd number pairs with OPEN, USE, READ, WRITE, and CLOSE commands.

I/O Commands for IJC Devices

You use all of the standard I/O commands with IJC devices: OPEN, USE, READ, WRITE, and CLOSE.

OPEN Command

The OPEN command reserves interjob communication devices for your use.

Syntax

OPEN device::timeout

where:

Argument	Description
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.

This example shows how two processes communicate by opening separate devices for reading and writing:

Process A                          Process B 
OPEN 227 USE 227 WRITE "MSG_1"
WRITE "MSG_2"                       OPEN 226 USE 226 READ X
CLOSE 227                           CLOSE 226
OPEN 224 USE 224 READ X             WRITE X
CLOSE 224                           MSG_1
WRITE X                             .
MSG_3                               .
                                    .
                                    OPEN 225 USE 225 WRITE "MSG_3" 
                                    CLOSE 225

Process A begins by opening device 227 and writing MSG_1 to it. InterSystems IRIS writes this message into the buffer shared by devices 226 and 227. Process A then writes a second message to the same buffer. Now Process B opens companion device 226 and reads the first message (MSG_1) from the buffer.

Now Process A wants to read a message, so it must open a different device, 224. Because the buffer for this device and its companion, 225, is currently empty, Process A waits until Process B opens device 225 and writes MSG_3 to it. After InterSystems IRIS places this message in the buffer shared by devices 224 and 225, the READ command to device 224 succeeds.