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
- 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.
..bf TITLE
RPC_ATTACH_STUB
RPC_attach_stub
..pf
- Parameters
- 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.
..bf TITLE
RPC_CALL
RPC_call
..pf
- Parameters
- 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.
..bf TITLE
RPC_CALL_STATUS
RPC_call_status
..pf
- 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.
..bf TITLE
RPC_caller_address
RPC_CALLER_ADDRESS
..pf
- Parameters
- 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.
..bf TITLE
RPC_CLOSE
RPC_close
..pf
- Parameters
- 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.
..bf TITLE
RPC_CONFIGURE
RPC_configure
..pf
- Parameters
- 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
- 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".
..bf TITLE
RPC_DETACH_STUB
RPC_detach_stub
..pf
- Parameters
- 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
- 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
- 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
- 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
- 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.
..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
- 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.
..bf TITLE
RPC_NEW
RPC_new
..pf
- Parameters
- 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.
..bf TITLE
RPC_OPEN
RPC_open
..pf
- Parameters
- OUT status rpc_status by address
- OUT handle integer by address
- 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
- 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.
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
- 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
- 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
- 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.
..bf TITLE
RPC_SWITCH
RPC_switch
..pf
- Parameters
- 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.