CALL_UNIX Function (UNIX)

Lets a PV-WAVE procedure communicate with an external routine written in C.

result = CALL_UNIX(p₁ [, p₂, ... , p₃₀])

p_i A variable of any type. At least one parameter must be passed, but there can be up to 30 parameters. If the external routine does not require any parameters, the value of p must be zero.

result A user-defined variable or data type to be returned from the external program. The returned variable cannot be -1, since -1 is reserved to indicate failure.

Close If present and nonzero, causes PV-WAVE to close Unit at the end of CALL_UNIX. (If Unit is not specified, Close has no effect.)

Hostname A string that identifies the node name of the host on which the called external program is executing. If not specified, the default value of "localhost" is used.

Procedure A string with a maximum length of 40 characters. Can say anything, but its intended use is to control program flow in the external routine.

Program An integer identifier that enables the C routine w_listen to match a particular call to CALL_UNIX to a particular external routine. Must be greater than or equal to zero. The default value is zero. Program is intended to allow more than one external routine to be called by CALL_UNIX.

Unit An integer used to reference an RPC socket:

• If Unit is zero, Unit is returned with a valid unit number.

• If Unit is nonzero, the value specified by Unit is used.

• If Unit is not specified, an RPC socket is reopened with each call to CALL_UNIX.

By specifying Unit, the overhead of opening an RPC socket each time is saved. In most cases, however, the overhead is not noticeable.

User A string with a maximum length of 40 characters. Can say anything, but its intended use is for controlling access to the external routine.

Timeout An integer that indicates the maximum time, in seconds, that PV-WAVE will wait for the external routine to finish. The default value is 60 seconds. If the external routine requires more than 60 seconds to execute, Timeout must be specified. There is no value to indicate an infinite amount of time.

CALL_UNIX sends parameters to another process that is running the external C routine.

The external routine uses the following C routines:

• w_listen to connect with the process running PV-WAVE

• w_get_par to actually get the parameters

• w_send_reply, w_smpl_reply, or w_cmpnd_reply to send values and parameters back to PV-WAVE.

For information on these C routines, see the PV-WAVE GUI Application Developer's Guide.

If an error occurs in a call to CALL_UNIX, -1 is returned. ON_IOERROR can also be used to catch CALL_UNIX errors.

---

NOTE: For information on these C routines, see the PV-WAVE GUI Application Developer's Guide.

---

ON_IOERROR, UNIX_LISTEN, UNIX_REPLY