Additional Topics > External Development Guide > Remote Procedure Calls > The IDL RPC Library

# The IDL RPC Library

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
- IDL_RPCDeltmp
- IDL_RPCExecuteStr
- IDL_RPCGetMainVariable
- IDL_RPCGettmp
- IDL_RPCGetVariable
- IDL_RPCImportArray
- IDL_RPCInit
- IDL_RPCInitWithLoopback
- IDL_RPCMakeArray
- IDL_RPCOutputCapture
- IDL_RPCOutputGetStr
- IDL_RPCSetMainVariable
- IDL_RPCSetVariable
- IDL_RPCStoreScalar
- IDL_RPCStrDelete
- IDL_RPCStrDup
- IDL_RPCStrEnsureLength
- IDL_RPCStrStore
- IDL_RPCTimeout
- IDL_RPCVarCopy
- IDL_RPCVarGetData
- Variable Accessor Macros

## 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