RPC Library Routines Reference

# Library Routines

There follows a list of those library routines which may be called by application code in order to perform functions above those of pure remote procedure call. The methods and reasons for calling these are described in earlier chapters. Many of these routines are documented here only for completeness, and will never be called by the user.

Note that although the stubs produced by the RPC compiler are deliberately matched to FORTRAN or C calling conventions, these library routines exist only in one form, and the caller is required to ensure that the calling conventions outlined below are met.

See also:

- Definitions of RPC system data types

## Library Routines

The routines are listed for reference in alphabetical order. For a pascal declaration file for these routines, see the file rpcproc.h (logical name rpc_proc under VMS).

### RPC_ACCEPT

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN s socket by value*
- IN timeout integer by value*

Effect
  This routine waits for a single request on the given socket, and services it according to the currently attached stub modules. The socket, s, must be a value returned by a previous call to rpc_create_server. The timeout is specified in units of 10ms. If no request arrives during the timeout period, then a status value of RPC_s_timeout is returned. A timeout value of 0 allows an outstanding request to be serviced without waiting for a new one. A value of -1 may be used to specify an infinite timeout. A maximum of one request is handled per call to RPC_accept.

### RPC_ATTACH_STUB

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN stub entry_point by value*
- IN service rpc_name by address
- OUT pkg_no integer by address

Effect
  The server stub is declared. The 'stub' parameter must be the entry point of the server stub routine. The 'service' parameter must be the name of the service (normally as declared in the package definition file). The returned 'pkg_no' parameter is the package number allocated to the stub (0 for the first one, 1 for the next, etc) which may be used by the client as an explicit address, or may be passed to RPC_DETACH_STUB.
Note
  Called by stubs only. Not called by user application code.

### RPC_CALL

Parameters

- COMPACT=1>
- IN handle integer by address
- IN OUT p_buf rpc_message_pointer by address
- IN timeout integer by value*

Effect
  A remote call is made. The 'handle' parameter must be a value previously returned by a call to RPC_OPEN. The p_buf parameter is a pointer to the buffer.
If an error occurs, the program is stopped with a message, or a user error handler is called. In the latter case, the stack is unwound to cause a premature exit from the caller (the stub) as to continue to unpack parameters could cause further errors.
Note
  Called by stubs only. Not normally called by user application code.

### RPC_CALL_STATUS

Parameters

- IN handle integer by address
- IN OUT p_buf rpc_message_pointer by address
- IN timeout integer by value*

Return value
  Call status, type rpc_status, VMS format
Effect
  A remote call is made. The 'handle' parameter must be a value previously returned by a call to RPC_OPEN. The p_buf parameter is a pointer to the buffer.
If an error occurs, it is reflected in an even return value with the VMS (facility, message, severity) format. If no error occurs, the return value is RPC_S_NORMAL (=1).
Note
  Called by stubs only. Not normally called by user application code.

### RPC_CALLER_ADDRESS

..pf

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- OUT name rpc_name by address

Effect
  Returns the RPC address of the process which called the current procedure. The format for an ethernet connection will be in the normal RPC format with an explicit packet type, for example

    		AA0004002F58_5050.ETHERNET

For a DECNET connection to a multiclient server, the address will be the RPC address of the client process, assuming that it has started a server with the name of the process as DECNET object name:

    		VXCRNA::"0=FRED".DECNET

Note
  Called by application code in a server procedure to find out the name of the client who called it. This routine must be called from within a remote procedure, as only then is the "current client" defined. Returns an RPC address blank filled.
Note
  Not available on M6809.

### RPC_CLOSE

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN handle handle_type by value*

Effect
  The reverse of RPC_OPEN. The handle specified becomes invalid for use in future calls.

### RPC_CONFIGURE

Parameters

- COMPACT=1>
- OUT status rpc_status by address

Effect
  Retranslates the logical name of each open package. For each one which has changed, closes the communication channel and reopens it with the new address. See also RPC_switch.
Note
  Called by a client program.

### RPC_CREATE_SERVER

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN client rpc_name by address
- OUT s socket by address

Effect
  Initialises a server, opening the communication channel where necessary. The socket returned may be used by future calls to RPC_ACCEPT. Used when writing a "polling server".

### RPC_DETACH_STUB

Parameters

- COMPACT=1>
- IN pkg_no integer by value*

Effect
  Opposite to RPC_ATTACH_STUB. The server stub is disconneted from the RPC system, and can no longer be accessed by a client.
Note
  Called by server stubs only. Not called by user application code.

### RPC_DISPOSE

Parameters

- COMPACT=1>
- IN P rpc_message_pointer by value*

Effect
  Opposite of rpc_new. The message buffer is deallocated (returned to the pool).
Note
  Called by client stubs only. Not called by user application code.

### RPC_EARLY_RETURN

Parameters

- COMPACT=1>
- INOUT P rpc_message_pointer by address

Effect
  The message is returned to the caller. This is normally done automatically by the runtime system, but in some cases (/concurrent option) the stub may wish to force an early return, before futher processing.
Note
  Called by server stubs only. Not called by user application code.

### RPC_ESTABLISH

Parameters

- COMPACT=1>
- IN handler entry_point by value*

Effect
  Deletes any previous user error handler. Establishes the specified handler such that whenever a fatal error occurs during an RPC call, the user error handler will be called, and passed the offending message as a parameter. On return from the user error handler (under VMS or on the M680x0), the stack will be unwound to prevent the rest of the stub from executing, and return will be made to directly to the user program after the remote call.

### RPC_HARDWARE_RESET

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN handle integer by address

Effect
  Finds the physical address of the hardware of the server in use, and performs (if possible) a physical reset function on it.

### RPC_INIT

Parameters
  None
Effect
  Initialises the entire RPC run time system.
Note
  Need not be called under VAX/VMS or Turbopascal.

### RPC_LOOP_SERVER

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN client rpc_name by address

Effect
  A communication channel is opened, and any requests received serviced. The routine loops until an error occurs, then closes the communication channel.
Note
  This is the routine called by the default SERVERLOOP main program.

### RPC_NEW

Parameters

- COMPACT=1>
- OUT p rpc_message_pointer by address
- IN size integer by value*

Effect
  Allocates an rpc buffer for a future call. The size parameter is currently ignored.
Note
  Called by stubs only. Not called by user application code.

### RPC_OPEN

Parameters
Status
  out, rpc_status, by address
handle
  out, integer, by address
service
  in, rpc_name, by address
Effect
  This is the binding routine. It establishes communication with a server for the package specified in the 'service' parameter. This may be a logical name or a physical RPC address. The 'handle' parameter returned is used by the stub in all calls, and in any call to RPC_CLOSE.

### RPC_QUEUE_SERVER

Note
  This is only used when one is making a special multitask server. (Eg MODEL TCS Terminal Control System). Not normally called by user code.
Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN s socket by value*
- IN action entry_point by value*
- IN dummy integer by value*

Effect
  An asynchronous receive request is queued for the server socket given, such that the 'action' routine will be called when the next request arrives. (The last parameter is dummy).
This routine queues an asynchronous user routine (AST) to be called when the next request arrives on the given socket (see RPC_Create_Server). It allocates space for the incoming message, and passes the address of this to the AST routine. The user AST routine has entry point astadr and is passed by address one parameter (M, of type RPC_message). This parameter is suitable to be passed to RPC_Service (see below). This parameter is all that is required by the service routine below: the user program may, however, want to perform some pre- or post- processing, such as forking off other tasks to handle the requests, or application functions.

### RPC_REPORT_ERROR

Parameters

- COMPACT=1>
- IN status rpc_status by address

Effect
  Logs an error message corresponding to the given status code. Under VAX/VMS, causes an image EXIT, with the status code as exit status.

### RPC_SERVICE

Parameters

- COMPACT=1>
- IN p rpc_message_pointer by address

Effect
  Services the request specified in the message pointer to by 'p'. The return message is sent. Note that on VMS, pointer is passed by address, unlike the parameter to the user AST routine of RPC_Queue_Service.

### RPC_START_SERVER

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN client rpc_name by address

Effect
  An asynchronous server is started. That is, a communication channel is opened, and an asynchronous read request is queued on that channel. When the read completes, the RPC system services the request and queues another read, so that the server continues to run.
The set of clients to be serviced is identified by the string parameter, which may in some cases include wildcards. The procedure returns immediately, but from then on any requests coming in are serviced asynchronously. The effect is as though RPC_Accept (q.v.) were called automatically whenever a request arrives.

### RPC_SWITCH

Parameters

- COMPACT=1>
- OUT status rpc_status by address
- IN handle integer by address

Effect
  Retranslates the logical name of the package. If it has changed, closes the communication channel and reopens it.