CALL_UNIX Function (UNIX)
Lets a PV-WAVE procedure communicate with an external routine written in C.
Usage
result = CALL_UNIX(p1 [, p2, ... , p30])
Input Parameters
pi—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.
If an error occurs in a call to CALL_UNIX, –1 is returned. ON_IOERROR can also be used to catch CALL_UNIX errors.
See Also
Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.