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:

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). ..bf TITLE

RPC_ACCEPT RPC_accept ..pf
Parameters
  1. OUT status rpc_status by address
  2. IN s socket by value*
  3. 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.
..bf TITLE

RPC_ATTACH_STUB RPC_attach_stub ..pf
Parameters
  1. OUT status rpc_status by address
  2. IN stub entry_point by value*
  3. IN service rpc_name by address
  4. 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.
..bf TITLE

RPC_CALL RPC_call ..pf
Parameters
  1. IN handle integer by address
  2. IN OUT p_buf rpc_message_pointer by address
  3. 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.
..bf TITLE

RPC_CALL_STATUS RPC_call_status ..pf
Parameters
  1. IN handle integer by address
  2. IN OUT p_buf rpc_message_pointer by address
  3. 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.
..bf TITLE RPC_caller_address

RPC_CALLER_ADDRESS ..pf
Parameters
  1. OUT status rpc_status by address
  2. 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.
..bf TITLE

RPC_CLOSE RPC_close ..pf
Parameters
  1. OUT status rpc_status by address
  2. IN handle handle_type by value*
Effect
The reverse of RPC_OPEN. The handle specified becomes invalid for use in future calls.
..bf TITLE

RPC_CONFIGURE RPC_configure ..pf
Parameters
  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.
..bf TITLE

RPC_CREATE_SERVER RPC_create_server ..pf
Parameters
  1. OUT status rpc_status by address
  2. IN client rpc_name by address
  3. 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".
..bf TITLE

RPC_DETACH_STUB RPC_detach_stub ..pf
Parameters
  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.
..bf TITLE

RPC_DISPOSE RPC_dispose ..pf
Parameters
  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.
..bf TITLE

RPC_EARLY_RETURN RPC_early_return ..pf
Parameters
  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.
..bf TITLE

RPC_ESTABLISH RPC_establish ..pf
Parameters
  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.
..bf TITLE

RPC_HARDWARE_RESET RPC_hardware_reset ..pf
Parameters
  1. OUT status rpc_status by address
  2. 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.
..bf TITLE

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

RPC_LOOP_SERVER RPC_loop_server ..pf
Parameters
  1. OUT status rpc_status by address
  2. 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.
..bf TITLE

RPC_NEW RPC_new ..pf
Parameters
  1. OUT p rpc_message_pointer by address
  2. 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.
..bf TITLE

RPC_OPEN RPC_open ..pf
Parameters
  1. OUT status rpc_status by address
  2. OUT handle integer by address
  3. IN service 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.
..bf TITLE

RPC_QUEUE_SERVER RPC_queue_server ..pf
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
  1. OUT status rpc_status by address
  2. IN s socket by value*
  3. IN action entry_point by value*
  4. 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. AST user 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.
..bf TITLE

RPC_REPORT_ERROR RPC_report_error ..pf
Parameters
  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.
..bf TITLE

RPC_SERVICE RPC_service ..pf
Parameters
  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.
..bf TITLE

RPC_START_SERVER RPC_start_server ..pf
Parameters
  1. OUT status rpc_status by address
  2. 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.
..bf TITLE

RPC_SWITCH RPC_switch ..pf
Parameters
  1. OUT status rpc_status by address
  2. IN handle integer by address
Effect
Retranslates the logical name of the package. If it has changed, closes the communication channel and reopens it.