CALL_UNIX Function (UNIX)

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

Usage

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

Input Parameters

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.

Returned Value

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.

Keywords

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.

Discussion

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 Application Developer’s Guide.