Infrasctucture Msg Function Reference

Msg
The messaging API is a wrapper for both the MO (message object) API and the IO API.    Applications sharing data or client server peers need only agree upon the name of each request and response field to communicate.    This allows applications to request the same service from servers running on different processors or written in different lanugages.   
A message object is partitioned into records containing fields.    The first record is number 1 (one) and always contains the fields: "type", "code", "status", and "reqid".    For an explanation of the use of these fields, please see the Orb documentation.    Fields are name/value pairs and are opaque as to actual storage type.    Messages are created for a specific destination or a specific virtual circuit.    However, an assembled message may be redirected to a different virtual circuit (Caveat: this can only work when the message is NOT multi-packet).    All message API functions return an integer except msgGetMp() which returns a character pointer.    When a message is transmitted via socket, only the required data is actually moved, thus, when it arrives, the message is no longer the default size.    Also remember that the received message handle contains all the information about the sender and how to return information to the sender.    Messages are created with a destination defined and as fields and records are added to the message transmissions of packets may occur unbeknownst to the caller.    The final msgSnd will alert the receiving end that the last data has been transmitted.    Also be aware that as information is extracted, from the received message, waits may occur unbeknownst to the caller so that more information may be made available from the sender.    One paradigm to consider is that a requester on one machine may be unloading fields from a message while the sender is still placing fields into the message on a different machine.   
Note: if you need to get a String field, from a message, which is of unknown size, you may use msgGetSa() which allocates a buffer, copies the string field's contents into it, then returns a pointer to the buffer.    You must free the buffer yourself.    This is needed because msgGetS is a macro which does a sizeof on the data buffer and in the case of an allocated field you will get the size of the pointer, not the buffer.    A similar procedure may be used for Binary data using msgGetBa() to retrieve the data from a binary field.

msgAckNak     msgClientReq     msgDup     msgFree     msgFwdDst     msgFwdId    
msgGetAckNak     msgGetB     msgGetBa     msgGetBL     msgGetFld     msgGetFldAlloc    
msgGetFldCnt     msgGetFldInfo     msgGetFldLen     msgGetFldType     msgGetI     msgGetId    
msgGetId     msgGetLen     msgGetMax     msgGetMp     msgGetRcnt     msgGetS    
msgGetSa     msgGetSL     msgInit     msgMkDst     msgMkId     msgMkReq    
msgMkRsp     msgNxtFld     msgPutB     _msgPutFld     msgPutFmt     msgPutI    
msgPutS     msgPutSL     msgRcd     msgRew     msgRst     msgRtn    
msgRcv     msgSnd     rtrMkReq    

int  msgAckNak( int hndl, int stat )
Creates an acknowledge or Negative acknowledge message and sends it to the originator of the message referenced by handle.

int  msgClientReq( int hndl, int timeOut )
Send the supplied request message and wait for the response.    The response must be of the same type as the request, else the new message is queued for the next msgRcv().    Returns the handle of the response message, esle ERR or NOT_FND (time out).

int  msgDup( int hndl )
Creates a message which is the duplicate (attached to the same Vc) with the same type, code, etc.

int  msgFree( int hndl )
Free the message represented by the message handle 'hndl'.

int  msgFwdDst( int hndl, char* dst )
Forward the message referenced by 'hndl' to the destination 'dest'.

int  msgFwdId( int hndl, int sd )
Forward the message referenced by handle 'hndl' to the peer connected to virtual circuit 'sd'.

int  msgGetAckNak( int timeout )
Wait for an Ack / Nak response.    If the response arrives before time out, return the 'status' field else return zero.

int  msgGetB( int hndl, char* name, uchar* data )
Get the information named "name" from the current record and store it as binary into "data". Returns the number of bytes stored.

int  msgGetBa( char* out, int hndl, char* name, uchar* data )
Allocate a buffer, copy the contents of the field named "name" from the current record into it, then save a pointer to the buffer into "out".    Returns the number of bytes stored.    The caller must free the buffer.    This is a macro using _msgGetFldA.

int  msgGetBL( int hndl, char* name, int dataLen, uchar* data )
Get the information named "name" from the current record and store it as binary into "data" which is of length "dataLen". Returns the number of bytes stored.

int  msgGetFld( int hndl, char* fldNam, int typ, void* dat )
This is the main get field referenced by macros msgGetI(), msgGetS(), msgGetB(), etc.    Get the value of field named 'fldNam' from the message referenced by 'hndl'.    Place the resultant value in 'dat'.    Return the length of data stored int 'dat' else NULL (not found).

int  msgGetFldAlloc( int hndl, char* fldNam, void* dat )
This is the main get field referenced by macros msgGetI(), msgGetS(), msgGetB(), etc.    Get the value of field named 'fldNam' from the message referenced by 'hndl'.    Place the resultant value in 'dat' (datLen is used for error checking in STR and BIN types).    Return the length of data stored int 'dat' else NULL (not found).

int  msgGetFldCnt( int hndl )
Get the number of Fields in the current record.

int  msgGetFldInfo( int hndl, char* fldNam, int* len )
Get information about the current field in message referenced by 'hndl'. The field name is placed in 'fldNam' and it's length is placed in 'len'.

int  msgGetFldLen( int hndl, char* fldNam )
Return the field length (in bytes) of the field "fldNam" in message referenced by 'hndl'.   

int  msgGetFldType( int hndl, char* fldNam )
Return the field type (MO_INT, MO_STR, MO_BIN) of the field "fldNam" in message referenced by 'hndl'.   

int  msgGetI( int hndl, char* name, int data )
Get the information named "name" from the current record and store it, as an integer into "data". Returns the number of bytes stored.

int  msgGetId( int hndl )
Returns the actual socket descriptor that the message arrived on.

int  msgGetId( int hndl )
Get the virtual circuit Id from the message referenced by 'hndl'.

int  msgGetLen( int hndl )
Return the overall length of the message.

int  msgGetMax( int hndl )
Get the maximum size of the message.

int  msgGetMp( int hndl )
Get the lower level message pointer for the message referenced by 'hndl'.

int  msgGetRcnt( int hndl )
Get the number of records in the message.

int  msgGetS( int hndl, char* name, char* data )
Get the information named "name" from the current record and store it as a string in "data".    the "data" field cannot be a pointer to an allocated buffer since msgGetS is a macro which does a sizeof on the data buffer and in the case of an allocated field you will get the size of the pointer, not the buffer.    In the case where you need a very large buffer use msgGetSa() which will allocate the buffer for you.    Returns the length +1 (space required to store the string).

int  msgGetSa( char* out, int hndl, char* name )
Allocate a string and copy the field named "name" from the current record into it.    Save a pointer to the buffer into "out".    The caller is responsible for freeing the buffer.    Returns the length +1 (space required to store the string).    This is a macro using _msgGetFldA.

int  msgGetSL( int hndl, int name, char* data )
Get the information named "name" from the current record and store it as a string in "data" which is of length "dataLen".

int  msgInit( int argc, char* argv[] )
Initialize the message interface reading a configuration file.

int  msgMkDst( char* dest )
Creates a message of the default size. The destination is established to the named process for the first and any additional packets. Returns an integer handle for referencing the message.

int  msgMkId( int id )
Creates a message of the default size. The destination is established via the supplied I/O Virtual Circuit ID for the first and any additional packets. Returns an integer handle for referencing the message.

int  msgMkReq( char* dest, int type, int code )
Creates a message of the default size. The destination is established to the named process for the first and any additional packets. Assigns fields "type", "code", "status"=0, and "reqId"=0. Returns an integer handle for referencing the message.

int  msgMkRsp( int oldHndl, int status )
Creates a message of the default size. The destination is established to the named process for the first and any additional packets. Assigns fields "type", "code" = RESPONSE, "status", and "reqId". Returns an integer handle for referencing the new message.

int  msgNxtFld( int hndl, char* fName, int* fLen )
Move the internal field pointer to the next field. Returns the type of the next field.

int  msgPutB( int hndl, char* name, uchar* data, int datLen )
Add a new field to the current record named "name". The data is of length "datLen" and taken from the binary "data".

int  _msgPutFld( int hndl, char* name, int fldNam, uchar* data, int dataLen )
Add a new field to the current record named "name". The data is taken from the binary "data". Data Length is takef from "dataLen". This is the actual PufFld function referenced by almost all 'Put' MACROS. Returns OK, MO_FULL, else ERR.

int  msgPutFmt( int hndl, char* name, char* fmt, ... elipsis )
Add a new field to the current record named "name". The data will be type STRING and consists of the foramat string "fmt" and any converted arguments (...). Conversions and arguments are identical to sprintf. Returns OK, MO_FULL, esle ERR.

int  msgPutI( int hndl, char* name, int data )
Add a new field to the current record named "name". The data is taken from the integer "data". Returns OK, MO_FULL, esle ERR.

int  msgPutS( int hndl, char* name, char* data )
Add a new field to the current record named "name". The data is taken from the string "data". Returns OK, MO_FULL, esle ERR.

int  msgPutSL( int hndl, char* name, int dataLen, char* data )
Add a new field to the current record named "name". The data of length "dataLen" is taken from the string "data". Returns OK, MO_FULL, esle ERR.

int  msgRcd( int hndl, int rcdNbr )
Move the a specific record within the message object, indicated by "rcdNbr". If "rcdNbr" is zero, move the the next record.

int  msgRew( int hndl )
The internal pointers in the message are all set back to the beginning record and fields.    This call is made after building a new message and transmitting it, by the msgSnd() call.    Is should also be used before running moPnt() (see mo description).    CAVEAT: Rewind doesn't work on multi-packet messages.    Also, you must get all needed data from the first packet before unloading a BIG packet, since the first and succeeing packets will be freed as new packets containing big field segments arrive.    We made this decision based on the overall memory requirements for to handling extremely large messages (we didn't want to keep an entire message around when all you really need is the current packet).    Remember the data from a large field is being loaded into one buffer large enough to accommodate the entire field and to keep redundant data in already unloaded packets would double the required space.

int  msgRst( int hndl )
Re-initializes the message object within the message and restores the message to it's default size.

int  msgRtn( int hndl )
Return the message to it's origin. This is usually used with msgRst and following msgPutFld calls.

int  msgRcv( int waitTime )
Wait for "waitTime" milliseconds or until a message is received. If "waitTime" is negative, wait forever. The handle is returned if a message is received else a zero (timeout) or negative is returned (error).

int  msgSnd( int handle )
Send the message to it's destination.    Returns OK if mesage was sent, else ERR.

int  rtrMkReq( char* dest, char* path, int xType, int xCode )
Creates a message of the default size. The destination is established to the local Orb for the first and any additional packets. Assigns fields "type" = OSRVRTR, "code" = RTRFWD, "status"=0, "reqId"=0, "rtrPath" =path, "execType" =xType, "execCode" =xCode, and "questor" = localHost/Process. Returns an integer handle for referencing the message.