The IDL RPC library contains several C language interface functions that facilitate communication between your application and IDL. There are functions to register and unregister clients, set timeouts, get and set the value of IDL variables, send commands to the IDL server, and cause the server to exit.
IDL_RPCCleanup
Calling Sequence
int IDL_RPCCleanup( CLIENT *pClient, int iKill)
Description
Use this function to release the resources associated with the given CLIENT structure or to kill the IDL RPC server.
Parameters
pClient
A pointer to the CLIENT structure for the client/server connection to be disconnected.
iKill
Set iKill to a non-zero value to kill the server when the connection is broken.
Return Value
This function returns 1 on success, or 0 on failure.
IDL_RPCDeltmp
Calling Sequence
void IDL_RPCDeltmp( IDL_VPTR vTmp)
Description
Use this function to de-allocate all dynamic memory associated with the IDL_VPTR that is passed into the function. Once this function returns, any dynamic portion of vTmp is deallocated and should not be referenced.
Parameters
vTmp
The variable that will be de-allocated.
Return Value
None.
IDL_RPCExecuteStr
Calling Sequence
int IDL_RPCExecuteStr(CLIENT *pClient, char * pCommand)
Description
Use this function to send IDL commands to the IDL RPC server. The command is executed just as if it had been entered from the IDL command line.
This function cannot be used to send multiple line commands and will return an error if a “$” is detected at the end of the command string. It will also return an error if “$” is the first character, since this would spawn an interactive process and hang the IDL RPC server.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
pCommand
A null-terminated IDL command string.
Return Value
This function returns the following values:
1: Success.
0: Invalid command string.
For all other errors, the value of !ERROR_STATE.CODE is returned. This number could be passed as an argument to the IDL function STRMESSAGE() to determine the exact cause of the error.
Note: When an error occurs in IDL, the !ERROR_STATE system variable remains populated with that error until it is cleared or another error occurs. IDL_RPCExecuteStr() merely returns the error code stored in !ERROR_STATE. To clear the error state, call:
MESSAGE, /RESET
IDL_RPCGetMainVariable
Calling Sequence
IDL_VPTR IDL_RPCGetMainVariable(CLIENT *pClient, char *Name)
Description
Call this function to get the value of an IDL RPC server main level variable referenced by the name contained in Name. IDL_RPCGetMainVariable will then return a pointer to an IDL_VARIABLE structure that contains the value of the variable.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
Name
The name of the variable to find.
Return Value
On success, this function returns a pointer to an IDL_VARIABLE structure that contains the value of the desired IDL RPC main level variable. On failure this function returns NULL.
Note that the returned variable is marked as temporary and should be deleted when the variable is no longer needed.
IDL_RPCGettmp
Calling Sequence
IDL_VPTR IDL_RPCGettmp(void)
Description
Use this function to create an IDL_VPTR to a dynamically allocated IDL_VARIABLE structure. When you are finished with this variable, pass it to IDL_RPCDeltmp() to free any memory allocated by the variable.
Parameters
None.
Return Value
On success, this function returns an IDL_VPTR. On failure, it returns NULL.
IDL_RPCGetVariable
Calling Sequence
IDL_VPTR IDL_RPCGetVariable(CLIENT *pClient, char *Name)
Description
Use this function to get a pointer to an IDL_VARIABLE structure that contains the value of an IDL RPC server variable referenced by Name. The current scope of the IDL program is used to get the value of the variable.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
Name
The name of the variable to find.
Return Value
On success, this function returns a pointer to an IDL_VARIABLE structure that contains the value of the desired IDL RPC variable. On failure this function returns NULL.
Note that the returned variable is marked as temporary and should be deleted when the variable is no longer needed. For more information on IDL RPC variables, see Client Variables.
IDL_RPCImportArray
Calling Sequence
IDL_VPTR IDL_RPCImportArray(int n_dim, IDL_MEMINT dim[], int type, UCHAR *data, IDL_ARRAY_FREE_CB free_cb)
Description
Use this function to create an IDL array variable whose data the server supplies, rather than having the client API allocate the data space.
Parameters
n_dim
The number of dimensions in the array.
dim
An array of IDL_MAX_ARRAY_DIM elements, containing the size of each dimension.
type
The IDL type code describing the data.
data
A pointer to your array data.
free_cb
If non-NULL, free_cb is a pointer to a function that will be called when the IDL RPC client routines frees the array. This feature gives the caller a sure way to know when the data is no longer referenced. Use the called function to perform any required cleanup, such as freeing dynamic memory or releasing shared or mapped memory.
Return Value
An IDL_VPTR that points to an IDL_VARIABLE structure containing a reference to the imported array. This function returns NULL if the operation was unsuccessful.
IDL_RPCInit
Calling Sequence
Client *IDL_RPCInit(long ServerId, char* pHostname)
Description
Use this function to initialize an IDL RPC client session.
The client program is registered as a client of the IDL RPC server. The server that the client is registered with depends on the values of the parameters passed to the function.
Parameters
ServerId
The ID number of the IDL server that the program is to be registered with. If this value is 0, the default server ID (0x2010CAFE) is used.
pHostname
This is the name of the machine where the IDL server is running. If this value is NULL or “”, the default, “localhost”, is used.
Return Value
A pointer to the new CLIENT structure is returned upon successful completion. This opaque data structure is then later used by the client program to perform operations with the server. This function returns NULL if the operation was unsuccessful.
IDL_RPCInitWithLoopback
Calling Sequence
Client *IDL_RPCInitWithLoopback(long PortId, char pHostname)
Description
Use this function to initialize an IDL RPC client session via the loopback interface.
The client program is registered as a client of the IDL RPC server. The server that the client is registered with depends on the values of the parameters passed to the function.
Parameters
PortId
On the IDL server, the ID number of the port on which the program should be registered.
If this value is 0, the default port ID (0xC350) is used.
pHostname
This is the name of the machine where the IDL server is running. If this value is NULL or “”, the default, “localhost”, is used.
Return Value
A pointer to the new CLIENT structure is returned upon successful completion. This opaque data structure is then later used by the client program to perform operations with the server. This function returns NULL if the operation was unsuccessful.
IDL_RPCMakeArray
Calling Sequence
char * IDL_RPCMakeArray( int type, int n_dim, IDL_MEMINT dim[], int init, IDL_VPTR *var)
Description
This function creates an IDL RPC client temporary array variable with a data area of the specified size.
Parameters
type
The IDL type code for the resulting array.
n_dim
The number of array dimensions. The constant IDL_MAX_ARRAY_DIM defines the upper limit of this value.
dim
A C array of IDL_MAX_ARRAY_DIM elements containing the array dimensions. The number of dimensions in the array is given by the n_dim argument.
init
This parameter specifies the sort of initialization that should be applied to the resulting array. init must be one of the following:
- IDL_ARR_INI_NOP: No initialization is done. The data area of the array will contain whatever garbage was left behind from its previous use.
- IDL_ARR_INI_ZERO: The data area of the array is zeroed.
var
The address of an IDL_VPTR containing the address of the resulting IDL RPC client temporary variable.
Return Value
On success, this function returns a pointer to the data area of the allocated array. The value returned is the same as is contained in the var->value.arr->data field of the variable. On failure, it returns NULL.
As with variables returned from IDL_RPCGettmp(), the variable allocated via this function must be de-allocated using IDL_RPCDeltmp() when the variable is no longer needed.
IDL_RPCOutputCapture
Calling Sequence
int IDL_RPCOutputCapture( CLIENT *pClient, int n_lines)
Description
Use this routine to enable and disable capture of lines output from the IDL RPC server. Normally, IDL will write any output to the terminal on which the server was started. This function can be used to save this information so that the client program can request the lines sent to the output buffer.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
n_lines
If this value is less than or equal to zero, no output lines will be buffered in the IDL RPC server and output will be sent to the normal output device on the IDL RPC server. If the value of this parameter is greater than zero, the specified number of lines will be stored by the IDL RPC server.
Return Value
This function returns 1 on success, or 0 on failure.
IDL_RPCOutputGetStr
Calling Sequence
int IDL_RPCOutputGetStr(CLIENT *pClient, IDL_RPC_LINE_S *pLine, int first)
Description
Use this function to get an output line from the line queue being maintained on the RPC server. The routine IDL_RPCOutputCapture() must have been called to initialize the output queue on the RPC server before this routine is called.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
pLine
A pointer to a valid IDL_RPC_LINE_S structure. The buf field of this structure will contain the output string returned from the IDL RPC server and the flags field will be set to one of the following (from idl_export.h):
- IDL_TOUT_F_STDERR: Send the text to stderr rather than stdout, if that distinction means anything to your output device.
- IDL_TOUT_F_NLPOST: After outputting the text, start a new output line. On a tty, this is equivalent to sending a new line (‘\n) character.
first
If first is set equal to a non-zero value, the first line is popped from the output buffer on the IDL RPC server (the output buffer is treated like a stack). If first is set equal to zero, the last line is de-queued from the output buffer (the output buffer is treated like a queue).
Return value
A true value (1) is returned upon success. A false value (0) is returned when there are no more lines available in the output buffer or when an RPC error is detected.
IDL_RPCSetMainVariable
Calling Sequence
int IDL_RPCSetMainVariable( CLIENT *pClient, char *Name, IDL_VPTR pVar)
Description
Use this routine to assign a value to a main level IDL variable in the IDL RPC server session referred to by pClient. If the variable does not already exist, a new variable will be created.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
Name
A pointer to the null-terminated name of the variable, which must be in upper-case.
pVar
A pointer to an IDL_VARIABLE structure that contains the value that the IDL RPC main level variable referenced by Name should be set to.
Return Value
This function returns 1 on success, or 0 on failure.
IDL_RPCSetVariable
Calling Sequence
int IDL_RPCSetVariable( CLIENT *pClient, char *Name, IDL_VPTR pVar)
Description
Use this routine to assign a value to an IDL variable in the IDL RPC server session referred to by pClient. If the variable does not already exist, a new variable will be created. Unlike IDL_RPCSetMainVariable(), this routine sets the variable in the current IDL program scope.
Parameters
pClient
A pointer to the CLIENT structure that corresponds to the desired IDL session.
Name
A pointer to the null-terminated name of the variable, which must be in upper-case.
pVar
A pointer to an IDL_VARIABLE structure that contains the value that the IDL RPC variable referenced by Name should be set to.
Return Value
This function returns 1 on success, or 0 on failure.
IDL_RPCStoreScalar
Calling Sequence
void IDL_RPCStoreScalar(IDL_VPTR dest, int type, IDL_ALLTYPES *value)
Description
Use this function to store a scalar value into an IDL_VARIABLE structure. Before the scalar is stored, any dynamic part of the existing IDL_VARIABLE is de-allocated.
Parameters
dest
An IDL_VPTR to the IDL_VARIABLE in which the scalar should be stored.
type
The type code for the scalar value.
value
The address of an IDL_ALLTYPES union that contains the value to store.
Return Value
None.
IDL_RPCStrDelete
Calling Sequence
void IDL_RPCStrDelete(IDL_STRING *str, IDL_MEMINT n)
Description
Use this function to delete a string.
IDL_RPCStrDup
Calling Sequence
void IDL_RPCStrDup(IDL_STRING *str, IDL_MEMINT n)
Description
Use this function to duplicate a string.
IDL_RPCStrEnsureLength
Calling Sequence
void IDL_RPCStrEnsureLength(IDL_STRING *s, int n)
Description
Use this function to check the length of a string.
IDL_RPCStrStore
Calling Sequence
void IDL_RPCStrStore( IDL_STRING *s, char *fs)
Description
Use this function to store a string.
IDL_RPCTimeout
Calling Sequence
int IDL_RPCTimeout(long lTimeOut)
Description
Use this function to set the timeout value used when the RPC client makes requests of the server.
Parameters
lTimeOut
A integer value, in seconds, specifying the timeout value that will be used in RPC
operations.
Return Value
This function returns 1 on success, or 0 on failure.
IDL_RPCVarCopy
Calling Sequence
void IDL_RPCVarCopy(IDL_VPTR src, IDL_VPTR dst)
Description
Use this function to copy the contents of the src variable to the dst variable. Any dynamic memory associated with dst is de-allocated before the source data is copied. This function emulates the callable IDL function IDL_VarCopy().
Parameters
src
The source variable to be copied. If this variable is marked as temporary (returned from IDL_RPCGettmp(), for example) the dynamic data will be moved rather than copied to the destination variable.
dst
The destination variable that src is copied to.
Return Value
None.
IDL_RPCVarGetData
Calling Sequence
void IDL_RPCVarGetData(IDL_VPTR v, IDL_MEMINT *n, char **pd, int ensure_simple)
Description
Use this function to obtain a pointer to a variable’s data, and to determine how many data elements the variable contains.
Parameters
v
The variable for which data is desired.
n
The address of a variable that will contain the number of elements in v.
pd
The address of a variable that will contain a pointer to v’s data, cast to be a pointer to pointer to char (e.g. (char **) &myptr).
ensure_simple
If TRUE, this routine calls the ENSURE_SIMPLE macro on the argument v to screen out variables of the types it prevents. Otherwise, EXCLUDE_FILE is called, because file variables have no data area to return.
Return Value
On exit, IDL_RPCVarGetData() stores the data count and pointer into the variables pointed at by n and pd, respectively.
Variable Accessor Macros
The following macros can be used to get information on IDL RPC variables. These macros are defined in idl_rpc.h.
All of these macros accept a single argument, v, of type IDL_VPTR.
IDL_RPCGetArrayData(v)
This macro returns a pointer (char*) to the data area of an array block.
IDL_RPCGetArrayDimensions(v)
This macro returns a C array which contains the array dimensions.
IDL_RPCGetArrayNumDims(v)
This macro returns the number of dimensions of the array.
IDL_RPCGetVarByte(v)
This macro returns the value of a 1-byte, unsigned char variable.
IDL_RPCGetVarComplex(v)
This macro returns the value (as a struct, not a pointer) of a complex variable.
IDL_RPCGetVarComplexR(v)
This macro returns the real field of a complex variable.
IDL_RPCGetVarComplexI(v)
This macro returns the imaginary field of a complex variable.
IDL_RPCGetVarDComplex(v)
This macro returns the value (as a struct, not a pointer) of a double precision, complex variable.
IDL_RPCGetVarDComplexR(v)
This macro returns the real field of a double-precision complex variable.
IDL_RPCGetVarDComplexI(v)
This macro returns the imaginary field of a double-precision complex variable.
IDL_RPCGetVarDouble(v)
This macro returns the value of a double-precision, floating-point variable.
IDL_RPCGetVarFloat(v)
This macro returns the value of a single-precision, floating-point variable.
IDL_RPCGetVarInt(v)
This macro returns the value of a 2-byte integer variable.
IDL_RPCGetVarLong(v)
This macro returns the value of a 4-byte integer variable.
IDL_RPCGetVarLong64(v)
This macro returns the value of a 8-byte integer variable.
IDL_RPCVarIsArray(v)
This macro returns non-zero if v is an array variable.
IDL_RPCGetVarString(v)
This macro returns the value of a string variable (as a char*).
IDL_RPCGetVarType(v)
This macro returns the type code of the variable. IDL type codes are discussed in Type Codes.
IDL_RPCGetVarUInt(v)
This macro returns the value of an unsigned 2-byte integer variable.
IDLRPCGetVarULong(v)
This macro returns the value of an unsigned 4-byte integer variable.
IDL_RPCGetVarULong64(v)
This macro returns the value of an unsigned 8-byte integer value.
See Also
Type Codes, String Processing