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.

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.