MPXAPI User Guide


TABLE OF CONTENTS

CONCEPTS
Client
Server
Service
Server Class
COMPONENTS
CLIENT SIDE API
Initailisation/Termination
initCMP
termCMP
Synchronous calls
callCMP
Asynchronous calls
asyncCallCMP
getReplyCMP
General
changeServerClassCMP
getLastErrorCMP
getLastRetCodeCMP
getLastResultCMP
enableTimeoutsCMP
disableTimeoutsCMP
Client Error Codes
Client Environment Variables
SERVER SIDE API
SMPSERVICE
SMPSVCDISPATCH
runSMP
returnSMP
BUFFER MANAGEMENT
allocBufferMPX
reallocBufferMPX
dupBufferMPX
freeBufferMPX
getBufferTypeMPX
getBufferSubtype
ADMIN PROCESS
GENERAL ENVIRONMENT VARIABLES

CONCEPTS

MPXAPI is a simple remote (process) calling api. This simple API hides the complexity of Interprocess Communication and buffer management. It allows clients to call Services that exist in Server processes simply. As the clients and servers are loosely coupled this can also give the benifit of better resource usage. There can be many clients calling a limited number of servers. This allows expensive resources to be multiplexed among many client processes (ie: Database connections, Network connections, Other Application interfaces etc).

The major concepts used by MPXAPI include: Client, Server, Server Classes and Services. These will briefly be explained here.

Client

Clients within MPXAPI are entities that request services from a remote Server. This can be done in a synchronous or asynchronous manner.

Server

Servers are entities that provide services that can be requested by clients. Servers process requests received from Clients and send back appropriate responses.

Service

Services are functional capabilities offered by Server processes. In general, a Service will equate to a routine within the Server. When MPXAPI receives a request for a service it will dispatch the request to the associated routine. One routine could be associated with one Service or many Services. This is up to the application programmer.

Server Class

Server classes are groups of servers that provide exactly the same interface (ie: Services), hence the use of 'Class'. Clients make requests to Server Classes without knowing which physical Server process will service the request. Therefore ALL servers within a Server Class must provide exactly the services. The server processes will generally be multiple instances of the same executable (this is not enforced however). Different interfaces must be represented by different Server Classes.


COMPONENTS

There are three main components to the MPXAPI. The header file mpx.h, the shared library libmpx.so and the administration process mrwadmsvr (optional).

The header file contains all the public decalarations for the MPXAPI. Both client and server side (and common) declarations are held in this file.

libmpx.so is the library containing the implementation of MPXAPI. It must be linked with all code using the API (both clients and servers).

mrwadmsvr is an optional server process that monitors connection and disconnection requests from clients. In the case of client failure the administration process will cleanup global resources that where held by the aborting client.


CLIENT SIDE API

The client side of MPXAPI has two methods of remote calls. The first is a synchronise method that sends a buffer to the requested service and waits for a response. The second is an asynchronise method that allows the client to send mutliple requests and retrieve the responses at some later time.

Nearly all methods within the API require a handle. This handle is used by the MPXAPI to understand in which context the call is being made. A process may have open many handles at any one time. These handles can all point to the same server class or different server classes.


Initailisation/Termination

The methods used to initialise and terminate use of MPXAPI are:


CHANDLE initCMP(char *serverClass);

initCMP takes a pointer to a string that names the Server Class that the handle should be initially associated with. This is generally one of the first things a client must do.

PARAMETERS

serverClass Server Class that the handle should be associated with.

RETURNS

An opaque handle on success or 0 on failure.
void termCMP(CHANDLE handle);

termCMP takes a handle allocated by initCMP and free's resources associated with the handle. Using a handle after it has been passed to termCMP is undefined.

PARAMETERS

handle A handle previously allocated by initCMP

RETURNS

NOTHING

Synchronous calls

Synchronous calls are made using:


int callCMP(CHANDLE handle, char *serviceName, char *idata, long ilen,
            char **odata, long *olen, long flags);

callCMP will send the buffer pointed to by idata to the remote service serviceName. On return, the reply buffer from the service will be pointed to by odata.

You can pass the same buffer for both the send and receive buffer. If the receive buffer is not big enough for the reply it will be freed and replaced by an appropriately sized buffer. Never assume odata will point to the same buffer you passed in!

PARAMETERS

handle A handle previously allocated by initCMP
serviceName The name of the service that the request is destined for
idata Buffer to be sent. It must be allocated with allocBufferMPX or 0
ilen Length of input buffer.
odata Buffer to receive reply into. It must be allocated with allocBufferMPX or 0. Can be the same buffer as idata.
olen Must contain the length of the output buffer before call. Will contain new length of output buffer after call.
flags only CMP_NOTIME is currently valid for callCMP. No other flags should be set.

RETURNS

CMP_OK on success or CMP_FAIL on failure. Further information can be obtained about the error by calling
getLastErrorCMP.

Asynchronous calls

Asynchronous calls are made using:


int asyncCallCMP(CHANDLE handle, char *serviceName, char *idata, long ilen,
                 long flags);

asyncCallCMP will send the buffer pointed to by idata to the remote service serviceName. It doesn't wait for a response back from the service. Instead, it returns a call token that can be used to retrieve the reply with getReplyCMP at a later time.

PARAMETERS

handle A handle previously allocated by initCMP
serviceName The name of the service that the request is destined for
idata Buffer to be sent. It must be allocated with allocBufferMPX or 0
ilen Length of input buffer.
flags CMP_NOTIME CMP_NOBLOCK

RETURNS

A call token to be used with getReplyCMP or CMP_FAIL on failure. Further information can be obtained about the error by calling getLastErrorCMP.
int getReplyCMP(CHANDLE handle, int *callToken, char **data, long *len,
                long flags);

getReplyCMP retrieves a reply for a request previously sent with asyncCallCMP.

PARAMETERS

handle A handle previously allocated by initCMP
callToken Call token returned by a previous call to asyncCallCMP
odata Buffer to receive reply into. It must be allocated with allocBufferMPX or 0. Can be the same buffer as idata.
olen Must contain the length of the output buffer before call. Will contain new length of output buffer after call.
flags CMP_NOTIME CMP_NOBLOCK CMP_GETANY

RETURNS

CMP_OK on success or CMP_FAIL on failure. Further information can be obtained about the error by calling getLastErrorCMP.

General

There are a number of routines related to the client api that are not directly related with making the remote calls. They are:
int changeServerClassCMP(CHANDLE handle, char *serverClass);

changeServerClassCMP allows the Server Class , associated with a handle, to be changed after initialisation. This routine should be used rather than terminating a handle and initialising a new one.

PARAMETERS

handle A handle previously allocated by initCMP
serverClass The new Server Class that the handle should be associated with.

RETURNS

CMP_OK on success or CMP_FAIL on failure. Further information can be obtained about the error by calling getLastErrorCMP.
long getLastErrorCMP(CHANDLE handle);

getLastErrorCMP accesses the last error associated with the handle supplied.

PARAMETERS

handle A handle previously allocated by initCMP

RETURNS

Returns the last error associated with the handle. See
Client Error Codes for more information.
long getLastRetCodeCMP(CHANDLE handle);

getLastRetCodeCMP returns the return code of the last service call. See returnSMP for values that may be returned.

PARAMETERS

handle A handle previously allocated by initCMP

RETURNS

Return code of last service called.
long getLastResultCMP(CHANDLE handle);

getLastResultCMP returns the value of the user defined return code from the last call. See returnSMP for more information.

PARAMETERS

handle A handle previously allocated by initCMP

RETURNS

Returns the result code from last service called.
void enableTimeoutsCMP();

enableTimeoutsCMP enables the time out clock. By default the clock is not started. The clock uses SIGALRM and therefore may interupt and system service calls made by the client. This is why it is NOT enable by default. When timeouts are enabled timeout checking is only performed at course granularity (currently 10 seconds with MRW). The default value is 60 seconds. This default can be changed with the environment variable MPX_CLIENT_TIMEOUT. Timeouts could be enabled just before a call to MPXAPI and disabled directly afterwards is SIGALRM will affect other client code.

PARAMETERS

NONE

RETURNS

NOTHING
void disableTimeoutsCMP();

disableTimeoutsCMP disables further processing of timeouts. Also stops the timeout clock (ie: no more SIGALRM's).

PARAMETERS

NONE

RETURNS

NOTHING

Client Error Codes

CMP_SEND_FAIL A failure occurred while trying to send the request message to the service.
CMP_RECV_FAIL A failure occurred while trying to retrieve the response from a service.
CMP_NOMEM A call to allocate memory failed.
CMP_BLOCK the CMP_NOBLOCK flag was specified and a blocking condition exists.
CMP_INTR An interupt was received while performing the operation. Generally the operation can be retried.
CMP_TIME The client has been blocked to long an has received a timeout. Only occurs when timeouts are enabled.

Client Environment Variables

MPX_CLIENT_TIMEOUT Changes the default value of for client operation timeouts.

SERVER SIDE API

The Server Side API is a simple interface allowing application programmers to focus on the job at hand (writing business logic) rather than the details of remote call operations.

The input buffer is provided as a parameter to a user defined function and reply buffers are passed back to the client using returnSMP.

Dispatching to the appropriate service implementation routine is controlled by an array of SMPSVCDISPATCH elements. Each element associates a particular Service with an implementation routine (user written code).


typedef void (*SMPSERVICE)(SMPCALLINFO *);

SMPSERVICE is a template describing the prototype that programmers must use for routines that service calls will be dispatched to. This routine is made known to MPX by the SMPSVCDISPATCH elements passed to runSMP.


typedef struct smpSvcDispatch
{
   char serviceName[SMP_SVCNAME_SIZE];
   SMPSERVICE serviceRoutine;
} SMPSVCDISPATCH;

The SMPSVCDISPATCH structure defines the mapping between a a Service (a logical entity) and a routine (physical entity). The MPXAPI uses this information to dispatch requests to the appropriate routine.


int runSMP(char *serverClass, SMPSVCDISPATCH *dispatchInfo);

runSMP starts the processing of messages for the Server. Messages are dispatched to the routines as described by the array dispatchInfo of SMPSVCDISPATCH elements. The last element in the array must be initialised with 0. A catch all routine can be declared in the array by using the service name of '*'. This should be the last complete element in the array as no further checks will be made after seeing '*' as the service name.

PARAMETERS

serverClass The Server Class that this server should be assigned to.
dispatchInfo Is an array of SMPSVCDISPATCH elements describing the mapping between Services and routines. Last element must be initialiased with zeros.

RETURNS

SMP_OK on success. SMP_INIT_FAIL on initialisation error or SMP_NO_EVAR if it could not resolve the environment variable for the Server Class.
void returnSMP(long returnValue,
               long resultCode,
               char *data,
               long length,
               long flags);

returnSMP passes control back to MPX api and the input buffer is sent back to the client. Control is NEVER returned to the user code following a returnSMP. The stack is unwound ready for the next request to be processed.

PARAMETERS

returnValue The returnValue gives an indication to the success of the service operation to the client. This value can be retrieved by the client by calling getLastRetCodeCMP.
  • SMP_RET_OK should be used to signify success.
  • SMP_RET_FAIL signifies that service failed to process the request correctly.
  • SMP_RET_EXIT sends the buffer back to the client (with SMP_RET_OK) and then forces runSMP to return.
  • SMP_RET_EXITF sends the buffer back to the client (with SMP_RET_FAIL) and then forces runSMP to return.
  • SMP_RET_ERR should not be used. It is used by MPXAPI when it cannot successfully perform the reply as requested.
  • resultCode This is a user defined code that will be passed back to the client and can be retrieved using getLastResultCMP.
    data Buffer to be sent back to client. It must be allocated with allocBufferMPX or be the input buffer or 0.
    length Length of input buffer.
    flags No flags currently implemented

    RETURNS

    NEVER returns!

    BUFFER MANAGEMENT

    There are number of routines that must be used to allocate and free buffers that will be passed through MPXAPI. There is also the notion of buffer types and subtypes. A buffer type describes the type of buffer being sent (XML, string etc.) and subtype may be a specialisation of the type. Currently on BINARY is implemented.

    To implement the buffer types there is a buffer type table that allows new buffer types to be added. Here the buffer type, subtype and routines for initialistion and freeing are declared. The buffer types can be found in libmpx/mpxbt.c.

    Buffers passed into and out of SMPSERVICE routines should NOT be freed! MPXAPI will free these on the programmers behalf.


    char *allocBufferMPX(char *bufferType, char *bufferSubtype, long length);
    

    Allocates a buffer with the specified type, subtype and length.

    PARAMETERS

    bufferType Type of buffer to be allocated.
    bufferSubtype Subtype of buffer to be allocated.
    length length of buffer to be allocated.

    RETURNS

    Newly allocated buffer on success else 0.
    char *reallocBufferMPX(char *buffer, long length);
    

    Reallocates a buffer to the specified lenght.

    PARAMETERS

    buffer Buffer to be resized.
    length length that the resized buffer should be.

    RETURNS

    Pointer to resized buffer on success else 0. If result is 0 buffer remains unmodified.
    char *dupBufferMPX(char *buffer);
    

    Duplicates the specified buffer. The new buffer has the same type,subtype and length as the orginal. Contents are copied directly from the orignal buffer to the new buffer.

    PARAMETERS

    buffer Buffer to be resized.

    RETURNS

    Returns pointer to duplicated buffer on success else 0.
    void freeBufferMPX(char *buffer);
    

    Frees the buffer specified.

    PARAMETERS

    buffer Buffer to be freed.

    RETURNS

    NOTHING
    char *getBufferTypeMPX(char *buffer);
    

    Returns the name of the Type of the buffer.

    PARAMETERS

    buffer Buffer to be checked.

    RETURNS

    Buffer type. This should not be modified!
    char *getBufferSubtypeMPX(char *buffer);
    

    Returns the name of the Subtype of the buffer.

    PARAMETERS

    buffer Buffer to be checked.

    RETURNS

    Buffer subtype. This should not be modified!

    ADMIN PROCESS

    The adminstration process is responsible for processing adminstration messages. Currently only two administration messages are generated and both come from clients. There is a message to notify of connection and another for disconnection.

    These messages are currently generated in a lower layer of MPX called MRW (Multiple Readers and Writers layer) and cannot be directly manipulated from MPX's public API.

    The generation of administration messages can be stopped by not defining the environment variable MRWADM. If this environment variable is defined there MUST be some process processing the messages generated by clients or the clients will eventually block during initialisation due to the queue being full.

    mrwadmsvr is a supplied adminstration server that will process connection and disconnection administration messages. This server will constantly check the status of all connected clients. If a client has exited without first calling termCMP, mrwadmsvr will cleanup any resources that were associated with the client. NOTE: this can only be done if mrwadmsvr runs under the same uid as the clients. mrwadmsvr takes no parameters and listens on the queue defined by MRWADM. This queue can be the same as an existing Server Class queue or a totally seperate queue (admin messages will not be retrieved by normal servers).


    GENERAL ENVIRONMENT VARIABLES

    MPX_SVRCLS_* This environment variable specifies the queue key to be used for a particular Server Class. The Server Class name replaces the '*'. For example, a Server Class with the name TEST would define this environment variable to be MPX_SVRCLS_TEST.
    MRWADM

    If MRWADM is defined it specifies a key for a queue that administration messages will be processed from. Also, when it is defined there MUST be an adminstration process (ie: mrwadmsvr) running to process the admin messages generated by clients. Failing to do so will eventually cause clients to block during initialisation as the queue will become full.

    If this evironment variable is not defined no adminstration messages will be generated by clients.


    Ashley Betts