This chapter lists all the functions by category. If you know what you want to do, but do not know which function to use, look it up in this chapter. If you know the name of a function and want a complete description of it, you can find it in the chapter "Function Reference".
Lookup of Administered Objects
FioranoMQ supports lookup of administered objects using the JNDI interface. In case of the CRTL this support has been provided using an InitialContext structure that works mostly on the lines of the InitialContext object of JNDI. Client applications can create an IntialContext and lookup different administered objects from the FioranoMQ server.
Creating InitialContext
The InitialContext is used to search for administered objects from the FioranoMQ server. The lookup operation performed by the InitialContext in the CRTL is similar to how it is done in Java using JNDI (Java Naming and Directory Interface). The only difference is that there is no entity called IntialContextFactory in the CRTL.
CRTL contains several APIs for creating the InitialContext. These can be sub-di-vided into two major categories:
- APIs that have individual parameters as arguments
- APIs that take a Hashtable environment as argument
In this case the different parameters required for creating the InitialContext like username, password, providerURL, and transport protocol are passed as separate arguments to the API. The table below lists these APIs with a brief purpose of each.
API | Function |
---|---|
newHashtable | Constructs a new, empty hashtable with a default initial capacity (11) and load factor, which is 0.75. |
newInitialContext_HT TP | Constructs the Initial Context for lookup of Admin Objects, using the HTTP protocol for communication. |
newInitialContext_SS L | Constructs the Initial Context for lookup of Admin Objects using the SSL protocol. The various SSL parameters are passed as arguments to this API. |
newInitialContext | Constructs the Initial Context for lookup of Admin Objects using the url, username and password that are passed as parameters |
newInitialContext1 | Constructs the Initial Context for lookup of Admin Objects using the serverName, port, username and password passed as arguments. |
newInitialContextDefaultParams | Creates the Initial Context for lookup of Admin Objects using the default values for address, port number, user-name and password. |
APIs that take a Hashtable environment as argument
The InitialContext can be created by passing all required environment parameters and their values in a Hashtable structure.The permissible name and values of some of these parameters can be checked in the chapter on datatypes and constants. For more information on creating and populating the hashtable structure, refer to the UtilityAPIs section of this chapter.
API | Function |
newInitialContext_env | Constructs a new, empty hashtable with a default initial capacity (11) and load factor,which is 0.75. |
HTTP support using the IntialContext
The HTTP mode allows client applications to connect to the FioranoMQ server run-ning in HTTP mode, both directly and through proxy servers. The only change re-quired in the application for using HTTP is while creating the InitialContext object. The following functions can be used to connect to the server, using the HTTP pro-tocol:
InitialContext newInitialContext_HTTP(mqstring url, mqstring user-name, mqstring passwd);
The above function is provided specifically for using HTTP protocol. However it does not allow you to specify a proxy server.
InitialContext newInitialContext_env(struct _Hashtable* env);
The above function is a more generic function, which accepts various parameters in a hashtable. This function can be used for all the protocols such as TCP, SSL, HTTP, and HTTPS. The following variables can be specified in the hashtable to configure the transport layer for HTTP:
- SECURITY_PRINCIPAL Username, which is used to perform lookup at the FioranoMQ server.
- SECURITY_CREDENTIALS Password for the user.
- PROVIDER_URL URL of the FioranoMQ server to connect to
- TRANSPORT_PROTOCOL Transport protocol to be used (HTTP in this case).
- HTTP_PROXY_URL URL of the proxy server to be used. If not specified, the runtime sends the request directly to the FioranoMQ server.
- HTTP_PROXY_TYPE Type of proxy server.
- PROXY_AUTHENTICATION_REALM Not supported currently.
- PROXY_PRINCIPAL Username to be used for connecting to the proxy server.
- PROXY_CREDENTIALS Password for the proxy user.
- FORCE_HTTP_10 Certain proxy servers do not support HTTP/1.1 persistent connections. For such servers, the flag "FORCE_HTTP_10" has to be set to TRUE.
The following code snippet has been extracted from an application using HTTP protocol.
InitialContext ic = NULL;
Hashtable env = newHashtable ();
HT_Put (env, SECURITY_PRINCIPAL, "anonymous");
HT_Put (env, SECURITY_CREDENTIALS, "anonymous");
HT_Put (env, PROVIDER_URL, "http://localhost:1856/");
HT_Put (env, HTTP_PROXY_URL, "http://localhost:8080");
HT_Put (env, HTTP_PROXY_TYPE, "MS_ISA_PROXY");
HT_Put (env, PROXY_AUTHENTICATION_REALM, "");
HT_Put (env, PROXY_PRINCIPAL, "modena");
HT_Put (env, PROXY_CREDENTIALS, "modena");
HT_Put (env, FORCE_HTTP_10, "TRUE")
ic = newInitialContext_env (env);
HTTPS Support using the InitialContext
The current version of CRTL allows applications to connect to the FioranoMQ server, running in HTTP in the Phaos SSL mode. The following function can be used for configuring InitialContext to use HTTPS protocol.
InitialContext newInitialContext_env(struct _Hashtable* env);
The parameters that can be used for configuring C-runtime in HTTPS mode are as follows:
- SECURITY_PRINCIPAL Username, which is used to perform lookup at the FioranoMQ server.
- SECURITY_CREDENTIALS Password for the user.
- PROVIDER_URL URL of the FioranoMQ server to connect to.
- TRANSPORT_PROTOCOL Transport protocol to be used (HTTPS in this-case).
- HTTP_PROXY_URL URL of the proxy server to be used. If not specified, the runtime sends the request directly to the FioranoMQ server.
- HTTP_PROXY_TYPE Type of proxy server.
- PROXY_AUTHENTICATION_REALM Not supported currently.
- PROXY_PRINCIPAL Username to be used for connecting to the proxy server.
- PROXY_CREDENTIALS Password for the proxy user.
- FORCE_HTTP_10 Certain proxy servers do not support HTTP/1.1 persistent connections. For such servers, the flag "FORCE_HTTP_10" has to be set-TRUE.
- SSL_CERT_FILE Fully qualified path of Certificate file.
- SSL_PRIVATE_KEY_FILE Fully qualified path of the Private key file.
- SSL_PRIVATE_KEY_PASSWORD Password for private key, if it is pass-word-encrypted, else NULL.
The following code snippet has been extracted from an application, which uses HTTPS protocol.
InitialContext ic = NULL; Hashtable env = newHashtable ();HT_Put (env, SECURITY_PRINCIPAL, "anonymous");HT_Put (env, SECURITY_CREDENTIALS, "anonymous");HT_Put (env, PROVIDER_URL, "http://localhost:1856/");HT_Put (env, TRANSPORT_PROTOCOL, HTTPS_PROTOCOL);HT_Put (env, HTTP_PROXY_URL, "http://localhost:8080");HT_Put (env, HTTP_PROXY_TYPE, "MS_ISA_PROXY");HT_Put (env, PROXY_AUTHENTICATION_REALM, "");HT_Put (env, PROXY_PRINCIPAL, "modena");
SSL support using the InitialContext
The only change in the C Client application for communicating with the FioranoMQ server on SSL is the creation of the InitialContext that is used for looking up various administered objects.
For a C client application to connect to the FioranoMQ server running over Phaos SSL, extra environment parameters are required for creating the InitialContext object. These extra parameters are listed below.
- CertFile: This is the digital certificate file. This parameter has to be passed with the fully qualified path name of the file. The certificate file must be in PEM format and must be sorted starting with the certificate to the highest level (root CA).
- PrivateKeyFile: This is the private key file. This parameter has to be passed-with the fully qualified path name of the file. The file must be in the PEM format.
- keyPassword: keyPassword is required if the private key file is encrypted with a password, otherwise a NULL value must be passed.These parameters can be provided to the InitialContext object in one of two possible ways.
These parameters can be added to a Hashtable structure that is provided in the CRTL. For creating a hashtable the fiorano_hashtable.h file needs to be included in the application. The Hashtable can be created using the following API.
Hashtable env = newHashtable ();
The parameters mentioned above can be added to this Hashtable in the following-manner.
HT_Put (env, TRANSPORT_PROTOCOL, SSL_PROTOCOL);
HT_Put (env, SSL_CERT_FILE, "C:
Program Files\\Fiorano\\Fiora-noMQ\\crtl\\bin
dsa-client-cert.der");HT_Put (env, SSL_PRIVATE_KEY_FILE, " C:
Program Files\\Fio-rano\\FioranoMQ\\crtl\\bin
enc-dsa-client-key.pem");HT_PUT(env, SSL_PRIVATE_KEYPASSWORD, "passwd");
Now this Hashtable is used for creating the InitialContext as follows:
InitialContext newInitialContext_env(struct _Hashtable* env);
This InitialContext can now be used to in the same way as it is for Client applications connecting over TCP.
Another way of creating the InitialContext is by using separate APIs for the case of SSL in which the above mentioned parameters are passed as arguments.
InitialContext newInitialContext_SSL(mqstring url, mqstring user-
name, mqstring passwd,mqstring certFile, mqstring privateKeyFile, mqstring keyPass);InitialContext newInitialContext1_SSL(mqstring serverName, mqint port, mqstring username,mqstring passwd, mqstring certFile, mqstring privateKeyFile, mqstring keyPass); h2.Looking up Objects using InitialContext
A single API is provided for looking up any administered object from the FioranoMQ server. The name of the administered object is provided as an argument to the API. The API returns an mqobject that has to be type-casted into the structure of the administered object that is being looked up. The objects that can be looked up using the InitialContext are Topic, TopicConnectionFactory, Queue, and QueueConnectionFactory.
API | Function |
IC_Lookup | Lookup an administered object from FioranoMQ server with name of the object passed as argument. |
IC_LookupTCF | Lookup an administered object from FioranoMQ server with name of the object passed as argument. This is used for server less mode. If server is present, it looks up as normal Lookup function |
IC_LookupQCF | Lookup an Queue Connection Factory object from FioranoMQ server with name of the object passed as argument. This is used for server less mode. If server is present, it looks up as normal Lookup function. |
Destroying the InitialContext
The InitialContext created in CRTL should be destroyed before the user program exits to avoid any memory leaks, using the following function.
API | Function |
IC_free | Frees up the resources allocated to the initial context structure. |
Following code snippet shows the use of the InitialContext.
InitialContext ic = NULL;
Queue queue = NULL;Topic topic = NULL;ic = newInitialContext("http://mymachine:1856","ayrton", "senna");//...queue = (Queue)IC_lookup(ic, "primaryqueue");topic = (Topic)IC_lookup(ic, "primarytopic");//...IC_free(ic);//...//Free other objects before exit
Point to Point Model
Using a QueueConnectionFactory
The QueueConnectionFactory is a factory object used to create QueueConnections with the FioranoMQ server. A ConnectionFactory object encapsulates a set of connection configuration parameters that has been defined by an administrator.This is an administered object and should be looked up from the FioranoMQ server using the InitialContext (as explained in the section Lookup Administered Objects of this chapter). The user cannot create QueueConnectionFactory object using the CRTL. This can be done using the FioranoMQ AdminTool or by using the admin APIs provided in the default Java RTL.
One of the predefined QueueConnectionFactory objects in the FioranoMQ server is the primaryQCF. This is used in all the examples explained in the document where a QCF is necessary.
Creating a QueueConnection
QueueConnectionFactories are used to create QueueConnections with the FioranoMQ server. The QueueConnection is created with the server running on the ConnectURL specified in the QueueConnectionFactory and if the same is unavailable then the RTL tries to make a connection with a BackupURL, if any.
QueueConnections can be created using default user identity ("anony-mous","anonymous" in case of FioranoMQ) or by specifying a username and password.
API | Function |
---|---|
QCF_createQueueConnectionDefParams | Creates a queue connection with default user identity |
QCF_createQueueConnection | Creates a queue connection with specified user identity |
Destroying a QueueConnectionFactory
Before quitting, the QueueConnectionFactory object, created in the application, should be destroyed using the following function.
API | Function |
QCF_free | Frees all the resources allocated for the Queue-ConnectionFactory |
The following code sample looks up a QueueConnectionFactory from the FioranoMQ server and uses it to create a QueueConnection.
QueueConnectionFactory qcf = NULL;
//...qcf = (QueueConnectionFactory)IC_Lookup(ic,"primaryQCF");qc = QCF_createQueueConnection(qcf, "ayrton", "senna");//...QCF_free(qcf);//...//Free other objects before exit. h2.Using a QueueConnection
The QueueConnection is an active connection to the FioranoMQ server. It is used to create one or more queue sessions for producing and consuming messages. It is created using the QueueConnectionFactory. For more information, read the Using a QueueConnectionFactory section of this chapter.
Starting and Stopping a QueueConnection
The delivery of messages on a connection is controlled by the start and stop APIs. Starting a connection starts or resumes the delivery of messages to consumers on that connection. Likewise, stopping the connection temporarily stops the delivery of messages to all consumers on that connection.
The ExceptionListener functionality is enabled only if the connection is started. The following APIs are used to control the start and stop of QueueConnections.
API | Function |
---|---|
QC_start | Starts (or restarts) the delivery of incoming messages of a connection. |
QC_stop | Temporarily stops the delivery of incoming messages of a connection. |
ExceptionListener and ClientID of a QueueConnection
ExceptionListeners are used to check for error conditions on a QueueConnection. Users can set and get ExceptionListeners on a QueueConnection.
The ExceptionListener is not a structure but a callback function in the CRTL that is defined as:
void (*ExceptionListenerPointer)(char *exception, void *pParam);
The client applications have to set the function pointer of the above callback function as the ExceptionListener.When an exception occurs on a connection the same callback function is invoked by the CRTL. As can be seen from the above definition, CRTL gives the exception trace and a parameter as arguments to the callback function. The parameter in this case is set by the client application to be used by the user in the callback function.
The ClientID uniquely identifies a QueueConnection on the FioranoMQ server. If a ClientID has not been set, the FioranoMQ server assigns a unique ClientID to each QueueConnection.
API | Function |
QC_setExceptionListener | Sets an exception listener for this connection |
QC_getExceptionListener | Returns the ExceptionListener structure for this Queue connection |
QC_setClientID | Sets the client identifier for this connection |
QC_getClientID | Gets the client identifier for this connection |
Creating a QueueSession
A QueueConnection can be used to create QueueSessions using the following API.
API | Function |
QC_createQueueSession | Creates a QueueSession with the given mode |
Closing and Destroying a QueueConnection
The QueueConnection has to be closed and destroyed before quitting the application.
Closing a QueueConnection terminates all pending messages received for all consumers created on the connection's sessions. Closing a connection not only closes the communication channel with the server but does not free up the memory allocated to the object. So, it must be destroyed. The following APIs are used for closing and destroying the QueueConnection.
API | Function |
QC_close | Closes the connection. |
QC_free | Frees all the resources allocated for the QueueConnection |
Here is the sample code of how to use a QueueConnection and destroy it.
//...
QueueConnection qc = NULL;//...qc = QCF_createQueueConnection(qcf, "ayrton", "senna");//...QC_setClientID("myConnection");QC_start(qc);//...QC_setExceptionListener(qc,onException,param);//..QC_createSession(qc,FALSE,AUTO_ACKNOWLEDGE);QC_stop(qc);//if needed//...QC_close(qc);//...QC_free(qc);//... h2.Using a QueueSession
A QueueSession object provides methods for creating QueueReceiver, Queue-Sender, QueueBrowser, Queue, and TemporaryQueue objects.
If there are messages that have been received but not acknowledged when a QueueSession terminates, these messages are retained and redelivered when a consumer next accesses the queue.
Transactions on a QueueSession
For non-transacted sessions any messages sent using the sender created on the session are sent to the server immediately following the QSNDR_send() call and an acknowledgement is sent for the message, immediately when it is received.
JMS specifies another type of session named transacted session. In transacted sessions, each transaction groups a set of produced messages and a set of consumed messages into an atomic unit of work. When a transaction is committed, its atomic unit of input is acknowledged and its associated atomic unit of output is sent. If a transaction rollback is done, its produced messages are destroyed and its consumed messages are automatically recovered. A transacted session can be created by setting the value of the second argument to TRUE in the QC_createSession API explained in the section "Using a QueueConnection"of this chapter.
The following APIs of CRTL are used to implement transacted sessions in applications.
API | Function |
QS_commit | Commits all messages done in this transaction and releases any locks held at the time of call of this API. |
QS_rollback | Rollbacks any messages done in this transaction and releases any locks held at the time of call of this API. |
QS_getTransacted | Indicates if the session is in transacted mode |
QS_recover | Stops message delivery in this session, and restarts message delivery with the oldest unacknowledged message |
Senders, Receivers and Browsers on a QueueSession
A QueueSession can be used to create senders, receivers, (with and without message selectors) and browsers (with and without message selectors) on a Queue using the following APIs.
API | Function |
QS_createSender | Creates a QueueSender to send messages to the specified queue. |
QS_createReceiver | Creates a QueueReceiver to receive messages from the specified queue. |
QS_createReceiverWithSelector | Creates a QueueReceiver to receive messages from the specified queue, using a message selector |
QS_createBrowser | Creates a QueueBrowser to peek at the messages using a message selector on the specified queue |
QS_createBrowserWithSelector | Creates a QueueBrowser to peek at the messages using a message selector on the specified queue. |
Creating Fiorano Messages
A QueueSession can be used to create different message types using the APIs listed in the table below. All messages are created with the default JMSHeader and an empty message body.
API | Function |
QS_createBytesMessage | Creates a bytes message. |
QS_createMapMessage | Creates a map message. |
QS_createStreamMessage | Creates a StreamMessage. |
QS_createTextMessage | Creates a text message. |
QS_createTextMessageWithText | Creates an initialized text message. |
Creating and Destroying Queues
The Queue is a destination object for messages in JMS. This is an administered object that can be looked up from the FioranoMQ server using the InitialContext. A C client application can also create its own Queue object using the QueueSession.
A QueueSession can be used to create a TemporaryQueue as well. The CRTL provides APIs to delete and destroy temporary queues as shown in the table below.
API | Function |
QS_createQueue | Creates a queue identity given a Queue name. |
QS_createTemporaryQueue | Creates a temporary queue |
TMPQ_delete | Deletes this temporary queue |
Q_free | Frees all the resources allocated on behalf of a queue structure. |
TMPQ_free | Frees all the resources allocated on behalf of a temporary queue |
Asynchronous Listener on QueueSession
A QueueSession can be used to register a MessageListener on a Queue for receiving messages asynchronously. The delivery of messages on this listener starts only when a receiver is created on the Queue using the same QueueSession. For more information, read the Using a QueueReceiver section in this chapter.
The following APIs control the use of the MessageListener on a QueueSession.
API | Function |
---|---|
QS_setMessageListener | Sets the distinguished MessageListener of the session |
QS_setFioranoMessageListner | Sets the distinguished MessageListener of the session. This API can be used to set a FioranoMessageListener callback pointer that can be passed a parameter, which in turn can be used in the implementation of the callback function. |
QS_getMessageListener | Returns the distinguished message listener of the session. |
Closing and Destroying a QueueSession
QueueSessions need to be closed and destroyed before quitting an application
Closing a QueueSession terminates all pending message received for all con-sumers created on the connection's sessions. Closing a connection not only closes the communication channel with the server but does not free up the memory allo-cated to the object. So, it must be destroyed. The following APIs are used for clos-ing and destroying the QueueConnection.
API | Function |
QS_close | Closes the queue session and resources allocated on behalf of the QueueSession. |
QS_free | Frees all the resources allocated on behalf of the QueueSession |
Using a QueueSender
A client uses a QueueSender to send messages to a queue. Normally, the Queue is specified when a QueueSender is created. This Queue can also be specified as NULL while creating a QueueSender in which case it is termed as an unidentified QueueSender.
If the QueueSender is created with an unidentified or NULL Queue, an attempt to use the send methods, which assume that the Queue has been identified, results in an error.
During the execution of its send method, a message must not be changed by other threads within the client. If the message is modified, the result of the send is undefined.
After sending a message, a client may retain and modify it without affecting the message that has been sent. The same message may be sent multiple times.
The following message headers are set as part of sending a message:
- JMSDestination
- JMSDeliveryMode
- JMSExpiration
- JMSPriority
- JMSMessageID
- JMSTimeStamp.
When the message is sent, the values of these headers are ignored. After the completion of the send, the headers hold the values specified by the method sending the message. It is possible for the send method not to set the JMSMessageID and JMSTimeStamp if the setting of these headers is explicitly disabled by the QSNDR_setDisableMessageID or QNSDR_setDisableMessageTimestamp method.
Message Params For A Sender
CRTL provides APIs using which certain parameters in the MessageHeader of messages to be sent can be controlled at the QueueSender level. Applications can set the priority, delivery mode, and the time to live in the sender. These values are in turn be set for all messages that are sent by the concerned sender.
Applications can also disable the generation of JMSMessageID and JMSMessageTimestamp for all messages sent by a QueueSender.
The APIs for the above-mentioned functions are listed in the following table.
API | Function |
QSNDR_setDeliveryMode | Sets the delivery mode for the sender. |
QSNDR_getDeliveryMode | Gets the default delivery mode of the sender. |
QSNDR_setPriority | Sets the default priority of the sender. |
QSNDR_getPriority | Gets the default priority of the sender. |
QSNDR_setTimeToLive | Sets the default length of time in milliseconds from its dispatch time, for which a produced message should be retained by the message system. |
QSNDR_getTimeToLive | Gets the default length of time in milliseconds from its dispatch time, for which a produced message should be retained by the message system |
QSNDR_setDisableMessageID | Sets whether message IDs are disabled. |
QSNDR_getDisableMessageID | Gets an indication of whether message IDs are disabled. |
QSNDR_setDisableMessageID | Sets whether message timestamps are disabled. |
QSNDR_getDisableMessage Timestamp | Gets an indication of whether message timestamps are disabled |
Sending a Message on a Queue
The FioranoMQ CRTL provides different APIs for sending a message on a Queue. These APIs can be used to send messages on the Queue on which the sender is created and also on any other specified Queue.
API | Function |
QSNDR_send | Sends a message to the queue on which the sender was created. Uses the default delivery mode, timeToLive and priority of the QueueSender |
QSNDR_send1 | Sends a message specifying delivery mode, priority and time to live to the queue. |
QSNDR_send2 | Sends a message to the specified queue. Uses the default delivery mode, timeToLive and priority of the QueueSender |
QSNDR_send3 | Sends a message to the specified queue, also specifying the delivery mode, priority and time to live to the queue |
Closing and Destroying a QueueSender
An application should close and destroy the QueueSender before quitting. The close call does not free the memory occupied by the QueueSender. All senders created using a QueueSession are also closed in the close call of the QueueSession.
API | Function |
---|---|
QSNDR_close | Closes the queue sender and the resources allocated on behalf of the QueueSender. |
QSNDR_free | Frees the resources allocated on behalf of the queue sender |
Using a QueueReceiver
A client uses a QueueReceiver object to receive messages that have been delivered to a queue.
Although it is possible to have multiple QueueReceivers for the same queue, the CRTL API does not define how messages are distributed between the QueueReceivers.
If a QueueReceiver specifies a message selector, the messages that are not selected remain on the queue. By definition, a message selector allows a QueueReceiver to skip messages. This means that when the skipped messages are eventually read, the total ordering of the reads does not retain the partial order defined by each message producer. Only QueueReceivers without a message selector reads messages in message producer order.
Synchronous Message Receive
Messages can be received synchronously from a Queue using the QueueReceiv-er's receive calls. These receive calls are of three distinct types:
- A blocking call that blocks for a infinite time period and returns as soon as a message is available in the queue
- A blocking call the blocks for a specified timeout period and returns if a message is available or if the timeout period expires
- A non-blocking call that returns without waiting for a message to be available
The APIs can be used perform the synchronous receive operations mentioned above.
API | Function |
QRCVR_receive | Receives the next message produced for this queue receiver. |
QRCVR_receiveWithTimeout | Receives the next message that arrives within the meout specified timeout |
QRCVR_receiveNoWait | Receives the next message if one is immediately available |
Asynchronous Message Receive
The CRTL specifies a way to receive messages asynchronously using the MessageListener. Unlike the JMS API, MessageListener is a callback function and not a structure. This callback function is defined as:
void (*MessageListener)(Message msg);
The CRTL provides another version of this callback function. This version can be given a parameter as function argument. This can be useful in cases where the application wants to perform some operation in the callback function that requires some external structure. This callback is termed as FioranoMessageListener and is defined as:
void (FioranoMessageListener)(struct _Message, void* pParam);
The callback function and the parameter are passed as arguments to the setFioranoMessageListener API described in the following table.
The QueueSession can also be used to set a MessageListener as explained in the section "Using a QueueSession"of this chapter. In case an application sets a MessageListener on both the QueueSession and a QueueReceiver created from the same session then the QueueSession's callback function is invoked.
API | Function |
---|---|
QRCVR_setMessageListener | Sets MessageListener of the message consumer. |
QRCVR_setFioranoMessageListener | Sets MessageListener of the message consumer. This API can be used to set a FioranoMessageLis-tener callback pointer that can be passed a parame-ter, which in turn can be used in the implementation of the callback function. |
QRCVR_getMessageListener | Gets the MessageListener of the queue receiver. |
Closing and Destroying a QueueReceiver
An application should close and destroy the QueueReceiver before quitting the application. The close call does not free the memory occupied by the QueueReceiver. All receivers created using a QueueSession are also closed in the close call of the QueueSession.
API | Function |
QRCVR_close | Closes the queue receiver and the resources allocated on behalf of the QueueReceiver |
QRCVR_free | Frees the resources assigned to a queue receiver |
Request/Reply on Queues
The QueueRequestor object is provided by the CRTL to simplify the making service requests. It creates a TemporaryQueue for the responses and provides a request function that sends the request message and waits for its reply. This request can be sent with a specified timeout interval as well.
The QueueReplier is not a seperate structure in the CRTL like the QueueRequestor. A reply to a request message can be sent using the following steps.
- Create a QueueReceiver on the Queue on which the requestor is sending requests. This QueueReceiver may receive messages synchronously or asynchronously.
- Create a QueueSender on any Queue or a NULL Queue.
- Start the QueueConnection on which the receiver is created.
- When the request is received by the above QueueReceiver, get the JMSReplyTo (which is a TemporaryQueue by default) and the JMSCorrelationID (only for the case of requestWithTimeout) from the request message. For more information, read the Fiorano Message section in this chapter.
- Now create a reply message using the QueueSession of the receiver and set the JMSCorrelationID extracted from the request in the reply message. This step has to be performed only if requestWithTimeout is being used.
- Send the reply on the JMSReplyTo destination extracted from the request message using the QueueSender created above.
The implementation of the steps, mentioned above, is shown in the following code snipppet.
qr = QS_createReceiver(qss, queue);
qsn = QS_createSender(qss, queue);..//snmsg = QS_createTextMessage(qss);..//QRCVR_setMessageListener(qr, onMsgRecv);QC_start(qc);void onMsgRecv(Message msg){rpstr = (mqstring)malloc(100*(sizeof(char)));mqstring corrID = NULL;Queue tqueue = NULL;..//corrID = MSG_getJMSCorrelationID(msg);MSG_setJMSCorrelationID(snmsg, corrID);FTMSG_setText(snmsg,rpstr);..//tqueue = MSG_getJMSReplyTo(msg);QSNDR_send2(qsn, tqueue, snmsg);..// free the replyTo destination and the message structures}
Creating a Requestor
The QueueRequestor is created on a Queue using a QueueSession. The following API can be used for the same.
API | Function |
newQueueRequestor | Creates a new QueueRequestor on the specified Queue. |
Sending a Request
The QueueRequestor is used to send requests on a Queue. These requests can be sent with an infinite timeout or for a specified timeout period. In case of request with a timeout, the requestor waits for a reply for the timeout period and return null if no reply is available within the timeout period.
API | Function |
QRQST_request | Sends a request and waits for a reply. |
QRQST_requestWithTimeout | Sends a request and waits for a reply within the specified timeout interval |
Closing and Destroying a QueueRequestor
A QueueRequestor must be closed and destroyed before quitting an application. The close API of the QueueRequestor does not free the memory allocated to the structure.
API | Function |
---|---|
QRQST_close | Closes the queue requestor and all the resources allocated on behalf of the QueueRequestor. |
QRQST_free | Frees the resources allocated on behalf of the QueueRequestor |
Browsing a Queue
A QueueBrowser is used for browsing a Queue for messages. This can be created using a QueueSession as explained in the section "Using a QueueSession"of this chapter.
A QueueBrowserEnumeration structure is returned by the getEnumeration call of the QueueBrowser which in turn is used for browsing the messages.
The QueueBrowser and QueueBrowserEnumeration have to be closed and destroyed by the application.
The following APIs are used for browsing a Queue.
API | Function |
---|---|
QBWSR_getQueue | Get the queue on which this queue browser is created |
QBWSR_getMessageSelector | Gets message selector expression of this queue browser |
QBWSR_getEnumeration | Gets an enumeration for browsing the current queue messages in the same order as they would be received |
QBWSR_free | Frees the resources allocated for the Queue-Browser. |
QBWSR_close | Closes all the resources on behalf of a Queue-Browser. |
QBE_nextElement | Gets the next message available with the queue browser enumeration |
QBE_hasMoreElements | Checks if the queue browser enumeration contains more elements that is, messages. QBE_free |
QBE_free | Frees all the resources allocated on behalf of QueueBrowserEnumeration |
Publish-Subscribe Model
Using a TopicConnectionFactory
TopicConnectionFactory is a factory object used to create TopicConnections with the FioranoMQ server. A ConnectionFactory object encapsulates a set of connection configuration parameters that has been defined by an administrator.This is an administered object and should be looked up from the FioranoMQ server using the InitialContext (as explained in the section Lookup Administered Objects of this chapter). The user cannot create his/her own TopicConnectionFactory object using the CRTL. This can be done using the FioranoMQ AdminTool or by using the admin APIs provided in the default Java RTL.
One of the predefined TopicConnectionFactory objects in the FioranoMQ server is the primaryTCF. This is used in all the examples explained in the document where a TCF is necessary.
Creating a TopicConnection
TopicConnectionFactories are used to create TopicConnections with the FioranoMQ server. The TopicConnection is created with the server running on the ConnectURL specified in the TopicConnectionFactory and if the same is unavailable then the RTL tries to make a connection with a BackupURL, if any.
TopicConnections can be created using default user identity ("anonymous","anon-ymous" in case of FioranoMQ) or by specifying a username and password.
API | Function |
TCF_createTopicConnection DefParams | Creates a queue connection with default user identity |
TCF_createTopicConnection | Creates a queue connection with specified user identity. |
Destroying a TopicConnectionFactory
The TopicConnectionFactory object created in the application should be destroyed before quitting, using the following function.
API | Function |
TCF_free | Frees all the resources allocated for the TopicConnectionFactory |
. Here is the sample code of how to look up a TopicConnectionFactory from the FioranoMQ server and use it to create a TopicConnection.
TopicConnectionFactory tcf = NULL;
//...tcf = (TopicConnectionFactory)IC_Lookup(ic,"primaryTCF");tc = QCF_createTopicConnection(tcf, "ayrton", "senna");//...TCF_free(tcf);//...//Free other objects before exit.
Using a TopicConnection
The TopicConnection is an active connection to the FioranoMQ server. It is used to create one or more topic sessions for producing and consuming messages. It is created using the TopicConnectionFactory as mentioned in the "Using a TopicConnection-Factory" section of this chapter.
Starting and Stopping a TopicConnection
The delivery of messages on a connection is controlled by the start and stop APIs. Starting a connection starts or resumes the delivery of messages to consumers on that connection and stopping the connection temporarily stops the delivery of messages to all consumers on that connection.
The ExceptionListener functionality also gets enabled only if the connection is started.
Following APIs are used to control the start and stop of TopicConnections.
API | Function |
TC_start | Starts (or restarts) delivery of incoming messages of a connection |
TC_stop | Temporarily stops delivery of incoming messages of a connection. |
ExceptionListener on a TopicConnection
ExceptionListeners are used to check for error conditions on a TopicConnection. Users can set and get ExceptionListeners on a TopicConnection.
The ExceptionListener is not a structure but a callback function in the CRTL that is defined as
void (*ExceptionListenerPointer)(char *exception, void *pParam);
The client applications have to set the function pointer for such a callback function as the ExceptionListener and whenever some exception occurs on a connection that callback function is invoked by the CRTL. As can be seem from the above definition the CRTL gives the exception trace and a parameter as arguments to the callback function. The parameter in this case is set by the client application to be used by the user in the callback function.
The ClientID uniquely identifies a TopicConnection on the FioranoMQ server. If no ClientID is set the FioranoMQ server assigns a unique ClientID to each TopicConnection.
API | Function |
TC_setExceptionListener | Sets an exception listener for this connection |
TC_getExceptionListener | Gets the ExceptionListener object for this connection |
TC_setClientID | Sets the client identifier for this connection |
TC_getClientID | Gets the client identifier for this connection. |
TopicSessions on a TopicConnection
A TopicConnection can be used to create TopicSessions using the following API.
API | Function |
TC_createTopicSession | Creates a TopicSession with the given mode. |
Closing and Destroying a TopicConnection
The TopicConnection has to be closed and destroyed before quitting from the user application.
Closing a TopicConnection terminates all pending message receives on the con-nection's session's consumers. Closing a connection only closes the communication channel with the server but doesn't free up the memory allocated to the object. So, it must be destroyed. The following APIs are used for closing and destroying the TopicConnection.
API | Function |
TC_close | Terminates the connection with Fiorano JMS server and closes the resources allocated on behalf of the TopicConnection |
TC_free | Frees all the resources allocated for the TopicConnection |
Here is the sample code of how to use a TopicConnection and destroy it.
//...
TopicConnection qc = NULL;//...tc = TCF_createTopicConnection(tcf, "ayrton", "senna");//...TC_setClientID("myConnection");TC_start(tc);//...TC_setExceptionListener(qc,onException,param);//..TC_createSession(tc,FALSE,AUTO_ACKNOWLEDGE);TC_stop(tc);//if needed//...TC_close(tc);//...TC_free(tc);//... h2.Using a TopicSession
A TopicSession provides methods for creating TopicPublishers, TopicSubscribers, and TemporaryTopics. It also provides the unsubscribe method for deleting its cli-ent's durable subscriptions.If there are messages that have been received but not acknowledged when a TopicSession terminates, a durable TopicSubscriber must retain and redeliver them; a nondurable subscriber need not do so.
Transactions on a TopicSession
For non-transacted sessions any messages sent using the publisher created on the session are sent to the server immediately following the TP_publish() call and an acknowledgement is sent for the message, immediately when it is received by a subscriber.
JMS specifies another type of session that is, transacted session, in which each transaction groups a set of produced messages and a set of consumed messages into an atomic unit of work. When a transaction is committed, its atomic unit of input is acknowledged and its associated atomic unit of output is sent. If a transaction rollback is done, its produced messages are destroyed and its consumed messages are automatically recovered. A transacted session can be created by setting the value of the second argument to TRUE in the TC_createTopicSession API explained in the section "Using a TopicConnection" of this chapter.
The following APIs of CRTL are used to implement transacted sessions in applications.
API | Function |
---|---|
TS_commit | Commits all messages done in this transaction and releases any locks held at the time of call of this API. |
TS_rollback | Rollbacks any messages done in this transaction and releases any locks held at the time of call of this API. |
TS_getTransacted | Gets an indication whether the session is transacted. |
TS_recover | Stops message delivery in this session, and restarts sending messages with the oldest unacknowledged message. |
Publishers and Subscribers on a TopicSession
A TopicSession can be used to create publishers and subscribers (with and without message selectors) on a Topic using the following APIs.
Both durable and non-durable subscribers can be created using a TopicSession.
API | Function |
---|---|
TS_createPublisher | Creates a Publisher for the specified topic. |
TS_createSubcriber | Creates a non-durable Subscriber to the specified topic. |
TS_createSubscriber OnTempTopic | Creates a non-durable Subscriber to the specified temporary topic |
TS_createSubscriber WithSelector | Creates a non-durable Subscriber to the specified topic using the specified message selector |
TS_createDurableSub scriber | Creates a durable Subscriber to the specified topic. |
TS_createDurableSub scriberWithSelector | Creates a Durable Subscriber to the given Topic with given message selector and local message delivery options |
Creating Fiorano Messages
A TopicSession can be used to create different message types using APIs listed in the table below. All messages are created with the default JMSHeader and an empty message body.
API | Function |
---|---|
TS_createBytesMessage | Creates a bytes message |
TS_createMapMessa ge | Creates a map message |
TS_createStreamMes sage | Creates a StreamMessage |
TS_createTextMessa ge | Creates a text message |
TS_createTextMessa geWithText | Creates an initialized text message |
Creating and destroying Topics
The Topic is a destination object for messages in the publish/subscribe model of JMS. This is an administered object that can be looked up from the FioranoMQ server using the InitialContext. A C client application can also create its own Topic object using the TopicSession.
Before quitting a C client application both Topics and Temporary topics must be freed if created or looked up.
API | Function |
TS_createTopic | Creates a topic identity given a topic name |
TS_createTemporaryTopic | Creates a temporary topic |
TMPT_delete | Deletes this temporary topic |
T_free | Frees the memory allocated to the topic structure |
TMPT_free | Frees all the resources allocated on behalf of the temporary topic |
Asynchronous Listener on TopicSession
A TopicSession can be used to register a MessageListener on a Topic for receiving messages asynchronously. The delivery of messages on this listener starts only when a subscriber is created on the Topic using the same TopicSession. For more information on the MessageListener refer to the section "Using a TopicSubscriber" in this chapter.
The following APIs control the use of the MessageListener on a TopicSession.
API | Function |
TS_setMessageListener | Sets the distinguished message listener of the session. |
TS_setFioranoMessa geListener | Sets the distinguished MessageListener of the session. This API can be used to set a FioranoMessageListener callback pointer that can be passed a parameter, which in turn can be used in the implementation of the callback function. |
TS_getMessageListener | Returns the distinguished message listener of the session. |
Closing and Destroying a TopicSession
TopicSessions need to be closed and destroyed before quitting an application that is using them.
Closing a TopicSession terminates all pending message receives on the session's consumers. Closing a session doesn't free up the memory allocated to the object,
API | Function |
TS_close | Closes the topic session and resources allocated on behalf of the TopicSession |
TS_free | Frees all the resources allocated on behalf of the TopicSession |
Using a TopicPublisher
A client uses a TopicPublisher object to publish messages on a topic. A TopicPublisher object is the publish-subscribe form of a message producer.
Normally, the Topic is specified when a TopicPublisher is created. This Topic can also be specified as NULL while creating a TopicPublisher in which case it is termed as an unidentified TopicPublisher.
If the TopicPublisher is created with an unidentified or NULL Topic, an attempt to use the send methods that assume that the Topic has been identified results in an error.
During the execution of its publish method, a message must not be changed by other threads within the client. If the message is modified, the result of the publish is undefined.
After publishing a message, a client may retain and modify it without affecting the message that has been published. The same message object may be published multiple times.
The following message headers are set as part of publishing a message: JMSDestination, JMSDeliveryMode, JMSExpiration, JMSPriority, JMSMessageID and JM-STimeStamp. When the message is published, the values of these headers are ignored. After completion of the publish, the headers hold the values specified by the method publishing the message. It is possible for the publish method not to set JMSMessageID and JMSTimeStamp if the setting of these headers is explicitly disabled by the TP_setDisableMessageID or TP_setDisableMessageTimestamp method.
Message Params for a Publisher
The CRTL provides APIs using which certain parameters in the MessageHeader of messages to be published can be controlled at the TopicPublisher level. Applications can set the priority, delivery mode and the time to live in the publisher. These values are in turn be set for all messages that are published by the concerned publisher.
Applications can also disable the generation of JMSMessageID and JMSMessageTimestamp for all messages published by a TopicPublisher.
API | Function |
---|---|
TP_setDeliveryMode | Sets the default delivery mode of the producer |
TP_getDeliveryMode | Gets the default delivery mode of the producer |
TP_setPriority | Sets the default priority of the producer |
TP_getPriority | Gets the default priority of the producer |
TP_setTimeToLive | Sets the default length of time in milliseconds from its dispatch time, for which a produced message should be retained by the message system. |
TP_getTimeToLive | Gets the default length of time in milliseconds, from its dispatch time, for which a produced message should be retained by the message system |
TP_setDisableMessageID | Sets whether message IDs are disabled for this Topic Publisher |
TP_getDisableMessageID | Gets an indication of whether message IDs are disabled. |
TP_setDisableMessage Timestamp | Sets whether message timestamps are disabled |
TP_getDisableMessage Timestamp | Gets an indication of whether message timestamps are disabled |
Publishing a message on a Topic
The FioranoMQ CRTL provides different APIs for publishing a message on a Topic. These APIs can be used to publish messages on the Topic on which the publisher is created and also on any other specified Topic.
API | Function |
TP_publish | Publishes a message to the topic on which the publisher is created. Uses the default delivery mode, timeToLive and priority of the topic |
TP_publish1 | Publishes a message to the topic on which the publisher is created, specifying delivery mode, priority and time to live to the topic. |
TP_publish2 | Publishes a message to a topic for an unidentified message producer. Uses the default delivery mode, timeToLive and priority of the topic. |
TP_publish3 | Publishes a message to a topic for an unidentified message producer, specifying delivery mode, priority and time to live. |
Destroying a TopicPublisher
An application should close and destroy the TopicPublisher before quitting the application. The close call does not free the memory occupied by the TopicPublishebr. All senders created using a TopicSession are also closed in the close call of the TopicSession.
API | Function |
TP_close | Closes the TopicPublisher and the resources allocated on behalf of the TopicPublisher. |
TP_free | Frees the resources allocated on behalf of the topic publisher |
Using a TopicSubscriber
A client uses a TopicSubscriber object to receive messages that have been published to a topic. A TopicSubscriber object is the publish/subscribe form of a message consumer.
A TopicSession allows the creation of multiple TopicSubscriber objects per topic. It delivers each message for a topic to each subscriber eligible to receive it. Each copy of the message is treated as a completely separate message. Work done on one copy has no effect on the others; acknowledging one does not acknowledge the others; one message may be delivered immediately, while another waits for its subscriber to process messages ahead of it.
Regular TopicSubscriber objects are not durable. They receive only messages that are published while they are active.
Messages filtered out by a subscriber's message selector would never be delivered to the subscriber. From the subscriber's perspective, they do not exist.
In some cases, a connection may both publish and subscribe to a topic. The subscriber NoLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection.
If a client needs to receive all the messages published on a topic, including the ones published while the subscriber is inactive, it uses a durable TopicSubscriber. The FioranoMQ server retains a record of this durable subscription and insures that all messages from the topic's publishers are retained until they are acknowledged by this durable subscriber or they have expired.
Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name that uniquely identifies (within client identifier) each durable subscription it creates. Only one session at a time can have a TopicSubscriber for a particular durable subscription.
A client can change an existing durable subscription by creating a durable Topic-Subscriber with the same name and a new topic and/or message selector. Changing a durable subscription is equivalent to unsubscribing (deleting) the old one and creating a new one.
The unsubscribe method is used to delete a durable subscription. The unsubscribe method can be used at the Session or TopicSession level. This method deletes the state being maintained on behalf of the subscriber by its provider.
Synchronous Message Receive
Messages can be received synchronously from a Topic using the receive call of the TopicSubscriber. This receive call is a blocking call that blocks for an infinite time period, for a specified timeout period or does not block at all. The call returns as soon as a message is available on the concerned Topic. The following APIs can be used to perform the synchronous receive operations.
API | Function |
---|---|
TSUB_receive | Receives the next message produced for this topic subscriber |
TSUB_receiveWithTime | Receives the next message that arrives within the out specified timeout interval. |
TSUB_receiveNoWait | Receives the next message if one is immediately available |
Asynchronous message receive
The CRTL specifies a way to receive messages asynchronously using the MessageListener. Unlike the JMS API the MessageListener in the CRTL is a callback function and not a structure. This callback function is defined as
void (*MessageListener)(Message msg);
This callback is invoked by the CRTL when a message arrives from the FioranoMQ server. A client application has to set the function pointer of the callback function it declares in the setMessageListener call.
The CRTL provides another version of this callback function that can be given a parameter as function argument. This can be useful in cases where the application wants to perform some operation in the callback function that requires some external structure. This callback is termed as FioranoMessageListener and is defined as
void (FioranoMessageListener)(struct _Message, void* pParam);
The callback function and the parameter are passed as arguments to the setFioranoMessageListener API described in the table below.
A TopicSession can also be used to set a MessageListener as explained in the section "Using a TopicSession"of this chapter. In case an application sets a Message.
API | Function |
TSUB_setMessageListner | Sets the MessageListener of the message consumer |
TSUB_setFioranoMes sageListener | Sets MessageListener of the message consumer. This API can be used to set a FioranoMessageListener callback pointer that can be passed a parameter, which in turn can be used in the implementation of the callback function. |
TSUB_getMessageListner | Gets the MessageListener of this message consumer |
Destroying a TopicSubscriber
An application should close and destroy the TopicSubscriber before quitting the application. The close call does not free the memory occupied by the TopicSubscriber. All subscribers created using a TopicSession are also closed in the close call of the TopicSession.
API | Function |
TSUB_close | Closes the TopicSubscriber and the resources allocated on behalf of TopicSubscriber. |
TSUB_free | Frees the resources allocated on behalf of Topic-Subscriber |
Request/Reply on Topics
The TopicRequestor object is provided by the CRTL to simplify making service requests. It creates a TemporaryTopic for the responses and provides a request function that sends the request message and waits for its reply. This request can be sent with a specified timeout interval as well.
The TopicReplier is not a separate structure in the CRTL like the TopicRequestor. A reply to a request message on a Topic can be sent using the following steps.
- Create a TopicSubscriber on the Topic on which the requestor is sending requests. This TopicSubscriber may receive messages synchronously or asynchronously.
- Create a TopicPublisher on any Topic or a NULL Topic.
- Start the TopicConnection on which the subscriber is created.
- When the request is received by the above TopicSubscriber get the JMSReplyTo (which is a TemporaryTopic) and the JMSCorrelationID (only for the case of requestWithTimeout) from the request message. For information on APIs to get the mentioned parameters refer to the section "FioranoMessage" in this chapter.
- Now create a reply message using the TopicSession of the subscriber and set the JMSCorrelationID extracted from the request in the reply message. This step has to be done only if requestWithTimeout is being used.
- Send the reply on the JMSReplyTo destination extracted from the request message using the TopicPublisher created above.
The following code snippet depicts the above mentioned steps.
..// steps for creation of TopicSession and lookup of Topic
tsub = TS_createSubscriber(ts, topic);tpub = TS_createPublisher(ts, topic);..//snmsg = TS_createTextMessage(ts);..//TSUB_setMessageListener(tsub, onMsgRecv);TC_start(tc);void onMsgRecv(Message msg){rpstr = (mqstring)malloc(100*(sizeof(char)));mqstring corrID = NULL;Topic tTopic = NULL;..//corrID = MSG_getJMSCorrelationID(msg);MSG_setJMSCorrelationID(snmsg, corrID);FTMSG_setText(snmsg,rpstr);..//tTopic = MSG_getJMSReplyTo(msg);TPUB_publish2(ts, tTopic, snmsg);..// free the replyTo destination and the message structures
Creating a TopicRequestor
The TopicRequestor is created on a Topic using a TopicSession. The following API can be used for the same.
API | Function |
newTopicRequestor | Creates a TopicRequestor |
Sending a request on a Topic
The TopicRequestor is used to send requests on a Topic. These requests can be sent with an infinite timeout or for a specified timeout period. In case of request with
API | Function |
TRQST_request | Sends a request and waits for a reply |
TRQST_requestWithTimeout | Sends a request and waits for a reply within the specified timeout interval |
Closing and Destroying a TopicRequestor
A TopicRequestor must be closed and destroyed before quitting an application. The close API of the TopicRequestor does not free the memory allocated to the structure.
API | Function |
TRQST_close | Closes the topic requestor and all the resources allocated on behalf of TopicRequestor. |
TRQST_free | Frees the resources allocated on behalf of TopicRequestor |
Client-Side Logging
In order to enable logging in CRTL, the following system environmental variables have to be set.
Variable | Value |
ENABLE_CLIENT_LOGGER | TRUE |
TRACE_LEVEL | ERROR, INFO, DEBUG |
ERROR | logs only when error has occurred. |
INFO | logs general information & errors |
DEBUG | logs general information, errors and debug statements |
In INFO level information about successful look up or creation of objects is logged. Logging in publish and receive calls are moved to DEBUG level due to the file size constraint when messages are published continuously.
- In DEBUG level, addresses of any memory that is being freed are logged.
- If DEBUG level is set, both INFO and ERROR statements will be logged.
- Similarly, if INFO level is set ERROR statements will also be logged.
Logging is done internally in CRTL. The log file will be created in the directory where the application exists. The following functions are available for the user.
LH_setLoggerName
Declaration: mqboolean LH_setLoggerName(mqstring name);
sets file name[in which data is logged] to name. The default file name is "cclient".
For example –
LH_setLoggerName("Publisher");
'.log' is appended to the file name.
Note: The maximum file size for the log file is set to 1 MB. As a result new log file will be created when the file size exceeds 1 MB. New files will be created with numbering as name_0.log, name_1.log, name_2.log and so on.
LH_getLogger
Declaration: LogHandler *LH_getLogger();
It returns the reference to the logHandler, using which data can be logged from application.
The structure used for logger is LogHandler.
LH_setTraceLevel
Declaration: mqboolean LH_setTraceLevel(LogHandler logger,mqstring level);
The trace level can also be set using this function. The legal values for the "level" are:
- "ERROR"
- "INFO"
- "DEBUG"
For example, trace level can be set or changed to "INFO" by calling, LH_setTraceLevel(logger, "INFO");
LH_logData
Declaration: mqboolean LH_logData(LogHandler logger, mqstring info, ...);
This function logs the given data to the log file.It is variable argument function. The usage of this function is similar to "printf" function.
For example, LH_logData(logger, "Logging from file - %s, func -%s", "FileName", "funcName");
In log file it is printed as follows:
Fri Dec 19 14:41:25 2008 :APPL: Logging from file - FileName, func -funcName
CSPBowser
CSP Browser is used to browse the messages stored in Client-Side Persistent Cache. While browsing messages are read from CSP and are not deleted. So, next time when the Server is re-connected, messages are sent to the Server.
The structures used for CSP Browsing are CSPBrowser and CSPEnumeration.
The following functions are used for CSP Browsing:
CSPM_createCSPBrowser
Declaration: CSPBrowser CSPM_createCSPBrowser(mqstring dbPath);
This function returns the CSPBrowser Object for CSP cache located in the dbPath.
CSPB_getAllConnections
Declaration: ListEnumerator CSPB_getAllConnections(CSPBrowser browser);
This function returns the enumeration of all the Connection IDs whose messages are stored in CSP
CSPB_getTopicsForConnection
Declaration: ListEnumerator CSPB_getTopicsForConnection(CSPBrowser browser, mqstring connID);
This function returns the Enumeration of all the topic names for the specified connection with clientID as connID.
CSPB_getQueuesForConnection
Declaration: ListEnumerator CSPB_getQueuesForConnection(CSPBrowser browser, mqstring connID);
This function returns the Enumeration of all the queue names for the specified connection with clientID as connID.
CSPB_browseMessagesOnQueue
Declaration: CSPEnumeration CSPB_browseMessagesOnQueue(CSPBrowser browser, mqstring queueName, mqboolean checkTransacted);
This function returns the enumeration of messages stored in the queue specified by queueName. It searches for messages in queue in all the existing connections. If checkTransacted is TRUE, transacted messages are also browsed.
CSPB_browseMessagesOnQueue2
Declaration: CSPEnumeration CSPB_browseMessagesOnQueue2(CSPBrowser browser, mqstring connectionID, mqstring queueName, mqboolean checkTransacted);
This function returns the enumeration of messages stored in the queue specified by queueName. It searches for messages in queue for the connection specified by connectionID. If checkTransacted is TRUE, transacted messages are also browsed.
CSPB_browseMessagesOnTopic
Declaration: CSPEnumeration CSPB_browseMessagesOnTopic(CSPBrowser browser, mqstring topicName, mqboolean checkTransacted);
This function returns the enumeration of messages stored in the topic specified by topicName. It searches for messages in topic in all the existing connections. If checkTransacted is TRUE, transacted messages are also browsed.
CSPB_browseMessagesOnTopic2
Declaration: CSPEnumeration CSPB_browseMessagesOnTopic2(CSPBrowser browser, mqstring connectionID, mqstring topicName, mqboolean checkTransacted);
This function returns the enumeration of messages stored in the topic specified by topicName. It searches for messages in topic for the connection specified by connectionID. If checkTransacted is TRUE, transacted messages are also browsed.
CSPB_numberOfMessagesinCSPQueue
Declaration: mqlong CSPB_numberOfMessagesinCSPQueue(CSPBrowser browser, mqstring connID, mqstring queueName, mqboolean checkTransacted);
This function returns the number of messages stored in the queue specified by queueName for a given connection with clientID connID.
If checkTransacted is TRUE, transacted messages are also counted.
CSPB_numberOfMessagesinCSPTopic
Declaration: mqlong CSPB_numberOfMessagesinCSPTopic(CSPBrowser browser, mqstring connID, mqstring topicName, mqboolean checkTransacted);
This function returns the number of messages stored in the topic specified by topicName for a given connection with clientID connID.
If checkTransacted is TRUE, transacted messages are also counted.
CSPB_free
Declaration: void CSPB_free(CSPBrowser browser);
This function frees the CSP Browser Structure.
CSPE_hasMoreElements
Declaration: mqboolean CSPE_hasMoreElements(struct _CSPEnumeration* cspEnum);
This function checks whether more elements are available in the enumeration.
CSPE_nextElement
Declaration: mqobject CSPE_nextElement(struct _CSPEnumeration* cspEnum);
This function returns the next element of this enumeration if this enumeration object has at least one more element to provide.
CSPE_free
Declaration: void CSPE_free(struct _CSPEnumeration* cspEnum);
This function frees the CSP Enumeration structure cspEnum.
Fiorano Message
Message is the most widely used entity in JMS. The different types of messages defined by JMS are:
- TextMessage
- StreamMessage
- BytesMessage
- MapMessage
- ObjectMessage
The CRTL provides the functionality related to TextMessage, StreamMessage, BytesMessage, and MapMessage. The ObjectMessage functionality is not provided.
Apart from these four types, a generic message type "Message" is also defined. In the CRTL, all the four of them are just synonyms for the same type, "Message".
The type name Message is used in the JMS functions, which can operate on any type of message. The specific type names are used in the functions, which operate on that particular type of message.
The methods defined in the base class Message and its subclasses in JMS are defined in CRTL with meaningful prefixes. These prefixes are summarized in the following table.
Message | Prefix |
Message | MSG |
TextMessage | FTMSG |
BytesMessage | FBMSG |
StreamMessage | FSMSG |
MapMessage | FMMSG |
Even though these functions expect specific types of messages as arguments, the compiler won't detect any errors different types of messages are passed. This is because all messages are just type defined to the same type. Therefore, it is the responsibility of the developer, to send proper types of messages as arguments, failing which an error is set at the runtime.
JMS messages are composed of the following parts:
- Header All messages support the same set of header fields. Header fields contain values used by both clients and providers to identify and route messages.
- Properties Each message contains a built-in facility for supporting applica-tion-defined property values. Properties provide an efficient mechanism for supporting application-defined message filtering.
- Body The JMS API defines several types of message body, which cover the majority of messaging styles currently in use.
All message types can be created using a QueueSession or a TopicSession. For more information on this refer to the sections "Using a QueueSession" and "Using a TopicSession" of this chapter.
Message Bodies
The CRTL API defines five types of message body. They are:
- Stream A StreamMessage object's message body contains a stream of values of different datatypes. It is filled and read sequentially.
- Map A MapMessage object's message body contains a set of name-value pairs, where names are mqstring objects, and values are different C datatypes. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined.
- Text A TextMessage object's message body contains an mqstring object. This message type can be used to transport plain-text messages, and XML messages.
- Bytes A BytesMessage object's message body contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format. In many cases, it is possible to use one of the other body types, which are easier to use. Although the JMS API allows the use of message properties with byte messages, they are typically not used, since the inclusion of properties may affect the format.
Message Header
The MessageHeader contains standard information relating to a Message that is used by the FioranoMQ server and by the client applications. The header contains the following fields:
- JMSType
- JMSMessageID
- JMSTimestamp
- JMSDeliveryMode
- JMSPriority
- JMSExpiration
- JMSDestination
- JMSReplyTo
- JMSCorrelationID
- JMSRedelivered
The JMSMessageID and JMSTimestamp are set by the FioranoMQ server after a message send or publish call returns. Any values set by the client applications for these header fields are ignored.
The JMSDestination, JMSDeliveryMode, JMSPriority, and JMSExpiration are set to the values specified in the send or publish call after the call returns. Any values set by the client applications for these variables in the Message structure are ignored during the send/publish call.
The JMSCorrelationID header field is used for linking one message with another. It typically links a reply message with its requesting message. The following APIs are used to control the message header fields.
API | Function |
---|---|
MSG_setJMSCorrelationID | Sets the correlation ID for this message. |
MSG_setJMSCorrelationIDAsBytes | Sets the correlation ID for this message as mqbyteArray |
MSG_setJMSDelivery Mode | Sets the delivery mode for this message. |
MSG_setJMSDestination | Sets the destination for this message. |
MSG_setJMSExpiration | Sets the expiration value of the message. |
MSG_setJMSMessageID | Sets the message ID for this message |
MSG_setJMSPriority | Sets the priority for this message. |
MSG_setJMSRedelivered | Set to indicate whether this message is being redelivered |
MSG_setJMSReplyTo | Sets the destination, where a reply to this message should be sent |
MSG_setJMSTimestamp | Sets the message timestamp as mqlong. |
MSG_setJMSType | Sets the message type. |
MSG_getJMSCorrelationID | Gets the correlation ID of the message as mqstring. |
MSG_getJMSCorrelationIDAsBytes | Gets the correlation ID of the message as mqbyteArray |
MSG_getJMSDeliveryMode | Gets the delivery mode for this message. |
MSG_getJMSDestination | Gets the destination for this message. |
MSG_getJMSExpiration | Gets the expiration time of the message. |
MSG_getJMSMessageID | Gets the message ID for this message |
MSG_getJMSPriority | Gets the message priority |
MSG_getJMSRedelivered | Gets an indication of redelivery of this message |
MSG_getJMSReplyTo | MSG_getJMSReplyTo which a reply to this message should be sent |
MSG_getJMSTimestamp | Gets the message timestamp for this message |
MSG_getJMSType | Gets the message type |
Message Properties
A Message object contains a built-in facility for supporting application-defined property values. In effect, this provides a mechanism for adding application-specif-ic header fields to a message.
Properties allow an application, via message selectors, to have the FioranoMQ server select, or filter, messages on its behalf using application-specific criteria.
Property names must obey the rules for a message selector identifier. Property names must not be null, and must not be empty strings. If a property name is set and it is either null or an empty string, an exception is thrown.
Property values can be mqboolean, mqbyte, mqshort, mqint, mqlong, mqfloat, mqdouble, and mqstring.
Property values are set prior to sending a message. When a client receives a message, its properties are in read-only mode. If a client attempts to set properties at this point, an exception is thrown. If clearProperties is called, the properties can now be both read from and written to. Note that header fields are distinct from properties. Header fields are never in read-only mode.
A property value may duplicate a value in a message's body, or it may not. For best performance, applications should use message properties only when they need to customize a message's header. The primary reason for doing this is to support customized message selection.
The following APIs can be used to set and get different properties in a Message structure.
API | Function |
---|---|
MSG_setBooleanProperty | Sets an mqboolean property value, into the Message, with the given name |
MSG_setByteProperty | Sets an mqbyte property value, into the Message, , with the given name |
MSG_setDoubleProperty | Sets an mqdouble property value, into the Message, with the given name |
MSG_setFloatProperty | Sets an mqfloat property value, into the Message, with the given name |
MSG_setIntProperty | Sets an mqint property value, into the Message, with the given name |
MSG_setLongProperty | Sets an mqlong property value, into the Message, with the given name |
MSG_setObjectProperty | Sets an Object as a property on a message |
MSG_setShortProperty | Sets an mqshort property value, into the Message, with the given name |
MSG_setStringProperty | Sets an mqstring property value, into the Message, with the given name |
MSG_getBooleanProperty | Gets the mqboolean property value with the given name |
MSG_getByteProperty | Gets the mqbyte property value with the given name |
MSG_getDoubleProperty | Gets the mqdouble property value with the given name |
MSG_getFloatProperty | Gets the mqfloat property value with the given name |
MSG_getIntProperty | Gets the mqint property value with the given name |
MSG_getLongProperty | Gets the mqlong property value with the given name |
MSG_getObjectProperty | Gets an Object Property from the message |
MSG_getShortProperty | Gets the mqshort property value with the given name |
MSG_getStringProperty | Gets the mqstring property value with the given name |
MSG_getPropertyNames | Gets an array of all the property names |
MSG_propertyExists | Checks if a property value exists |
MSG_clearProperties | Clears the properties of the message. The message header fields and body are not cleared |
BytesMessage
A BytesMessage object is used to send a message containing a stream of uninterpreted bytes. The receiver of the message supplies the interpretation of the bytes.
This message type is for client encoding of existing message formats. If possible, one of the other self-defining message types should be used instead.
Although the JMS API allows the use of message properties with byte messages, they are typically not used. This is because the inclusion of properties may affect the format.
The data types can be written explicitly using methods for each type. When the message is first created, and when clearBody is called, the body of the message is in write-only mode. After the first call to reset has been made, the message body is in read-only mode. After a message has been sent, the client that sent it can retain and modify it without affecting the message that has been sent. The same message object can be sent multiple times. When a message has been received, the provider has called reset so that the message body is in read-only mode for the client.
If clearBody is called on a message in read-only mode, the message body is cleared and the message is in write-only mode. If a client attempts to read a message in write-only mode, an exception is thrown. If a client attempts to write a message in read-only mode, an exception is thrown.
Following APIs can be used to control the data in a bytes message.
API | Function |
---|---|
FBMSG_clearBody | Clears the body of the bytes message. s |
FBMSG_readBoolean | Reads an mqboolean from the bytes message stream. |
FBMSG_readByte | Reads a signed 8-bit value from the bytes message stream. |
FBMSG_readBytes | Reads an mqbyteArray of the specified length from the bytes message stream. |
FBMSG_readChar | Reads a Unicode character value from the bytes message stream. |
FBMSG_readDouble | Reads an mqdouble from the bytes message stream. |
FBMSG_readFloat | Reads an mqfloat from the bytes message stream. |
FBMSG_readInt | Reads a 32 bit signed integer (mqint) from the bytes message stream. |
FBMSG_readLong | Reads a signed 64-bit integer (mqlong) from the bytes message stream. |
FBMSG_readShort | Reads an mqshort from the bytes message stream. |
FBMSG_readUnsigne dByte | Reads an unsigned 8-bit number from the bytes message stream. |
FBMSG_readUnsignedShort | Reads an unsigned 16-bit number (mqshort) from the bytes message stream |
FBMSG_readUTF | Reads in mqstring that has been encoded using a modified UTF-8 format from the bytes message stream |
FBMSG_reset | Puts the message body in read-only mode, and repositions the stream of bytes to the beginning |
FBMSG_writeBoolean | Writes an mqboolean to the bytes message stream as a 1-byte value |
FBMSG_writeByte | Writes an mqbyte to the bytes message stream as a 1-byte value |
FBMSG_writeBytes | Write an mqbyteArray to the bytes message stream |
FBMSG_writeBytesWithOffset | Writes a portion of mqbyteArray to the bytes message stream |
FBMSG_writeChar | Writes an mqchar as 2 bytes to the bytes message stream |
FBMSG_writeDouble | Writes an mqdouble to the bytes message stream. |
FBMSG_writeFloat | Writes an mqfloat to the bytes message stream |
FBMSG_writeInt | Writes an mqint to the bytes message stream. |
FBMSG_writeLong | Writes an mqlong to the bytes message stream |
FBMSG_writeShort | Writes an mqshort to the bytes message stream |
FBMSG_writeUTF | Write an mqstring to the bytes message stream, using UTF-8 encoding in a machine-independent manner |
MapMessage
A MapMessage object is used to send a set of name-value pairs. The names are mqstring objects, and the values are different data types of the C programming language. The names must have a value that is not null, and not an empty string. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined.
The data-types can be read or written explicitly using methods for each type.
When a client receives a MapMessage, it is in read-only mode. If a client attempts to write to the message at this point, an exception is thrown. If clearBody is called, the message can now be both read from and written to.
API | Function |
---|---|
FMMSG_clearBody | Clears the contents of the message. |
FMMSG_getBoolean | Gets the mqboolean value with the given name. |
FMMSG_getByte | Gets the mqbyte value with the given name. |
FMMSG_getBytes | Gets the mqbyteArray with the given name. |
FMMSG_getChar | Gets the mqchar value with the given name. |
FMMSG_getDouble | Gets the mqdouble value with the given name. |
FMMSG_getFloat | Gets the mqfloat value with the given name. |
FMMSG_getInt | Gets the mqint value with the given name. |
FMMSG_getLong | Gets the mqlong value with the given name. |
FMMSG_getMapNames | Gets an array of all the map names. |
FMMSG_getShort | Gets the mqshort value with the given name. |
FMMSG_getString | Gets the mqstring value with the given name. |
FMMSG_itemExists | Checks if an item with the given name exists in this MapMessage |
FMMSG_setBoolean | Sets the mqboolean value with the given name. |
FMMSG_setByte | Sets the mqbyte value with the given name. |
FMMSG_setBytes | Sets the mqbyteArray with the given name. |
FMMSG_setBytesWithOffset | Sets a portion of mqbyteArray with the given name. |
FMMSG_setChar | Sets the mqchar value with the given name. |
FMMSG_setDouble | Sets the mqdouble value with the given name. |
FMMSG_setFloat | Sets the mqfloat value with the given name. |
FMMSG_setInt | Sets the mqint value with the given name. |
FMMSG_setLong | Sets the mqlong value with the given name. |
FMMSG_setShort | Sets the mqshort value with the given name |
FMMSG_setString | Sets the mqstring value with the given name. |
StreamMessage
A StreamMessage object is used to send a stream of data types of the C programming language. It is filled and read sequentially.
The data-types can be read or written explicitly using methods for each type.
When the message is first created, and when clearBody is called, the body of the message is in write-only mode. After the first call to reset has been made, the message body is in read-only mode. After a message has been sent, the client that sent it can retain and modify it without affecting the message that has been sent. The same message object can be sent multiple times. When a message is received, the CRTL has called reset so that the message body is in read-only mode for the client.
- If clearBody is called on a message in read-only mode, the message body is cleared and the message body is in write-only mode.
If a client attempts to read a message in write-only mode, an exception is thrown. If a client attempts to write a message in read-only mode, an exception is thrown.
API
Function
FSMSG_clearBody
Clears the contents of the stream message
FSMSG_readBoolean
Reads an mqboolean from the stream message
FSMSG_readByte
Reads an mqbyte from the stream message
FSMSG_readBytes
Reads an mqbyteArray from the stream message
FSMSG_readChar
Reads an mqchar from the stream message
FSMSG_readDouble
Reads an mqdouble from the stream message.
FSMSG_readFloat
Reads an mqfloat from the stream message
FSMSG_readInt
Reads an mqint from the stream message
FSMSG_readLong
Reads an mqlong from the stream message
FSMSG_readShort
Reads an mqshort from the stream message
FSMSG_readString
Reads an mqstring from the stream message
FSMSG_reset
Puts the message body in read-only mode, and repositions the stream to the beginning.
FSMSG_writeBoolean
Writes an mqboolean to the stream message, as a1-byte value
FSMSG_writeByte
Writes an mqbyte to the stream message
FSMSG_writeBytes
Writes an mqbyteArray to the stream message
FSMSG_writeBytesWithOffset
Writes a portion of an mqbyteArray to the stream message
FSMSG_writeChar
Writes an mqchar to the stream message
FSMSG_writeDouble
Writes an mqdouble to the stream message
FSMSG_writeFloat
Writes an mqfloat to the stream message
FSMSG_writeInt
Writes an mqint to the stream message
FSMSG_writeLong
Writes an mqlong to the stream message
FSMSG_writeShort
Writes an mqshort to the stream message
FSMSG_writeString
Writes an mqstring to the stream message
TextMessage
A TextMessage object is used to send a message containing an mqstring. It inherits from the Message interface and adds a text message body.
This message type can be used to transport text-based messages, including those with XML content.
When a client receives a TextMessage, it is in read-only mode. If a client attempts to write to the message at this point, an exception is thrown. If clearBody is called, the message can now be both read from and written to.API
Function
FTMSG_getText
Gets the string containing data of this message
FTMSG_setText
Sets the string containing data of this message.
Acknowledging a message
The CRTL provides the acknowledge API in the Message which is equivalent to the Message.acknowledge API of JMS. A call to this API acknowledges all messages delivered in that session till the message on which the call is made.
This call is relevant for sessions that are created using the CLIENT_ACKNOWLEDGEMENT mode. In order to rollback messages received on a client ack session the TS_recover API can be used.API
Function
MSG_acknowledge
Acknowledges all consumed messages of the session of this consumed message.
Destroying a message
A Message structure should be destroyed by the Client application after the message has been used to avoid memory leaks.
All types of messages can be destroyed using the following API call.API
Function
MSG_free
Frees the resources allocated for the message
Large Message Support
With Large Message Support (LMS) in FioranoMQ, clients can transfer large files in the form of large messages with theoretically no limit on the message size. Large messages can be attached with any JMS message and the client can be sure of a reliable and secure transfer of the message through FioranoMQ server. Please refer to chapter 15 of FioranoMQ concepts guide for detailed explanation of LMS.
The following functions can be used to use LMS implementation.LMSG_ getMessageStatus
Declaration: LMTransferStatus LMSG_getMessageStatus(Message msg);
Gets the status of the message. Status includes number of bytes transferred, number of bytes left to be transferred, and so on.LMSG_ setLMStatusListener
Declaration: void LMS_LMSG_setLMStatusListener(Message msg , LMStatusListener listener, int updateFrequency);
Sets the status listener for the message. This function is used to know the status of message transfer asynchronously.
LMStatusListener is defined as
typedef void (*LMStatusListener)(LMTransferStatus status, mqboolean exOccurred);LMSG_ getLMStatusListener
Declaration: LMStatusListener LMSG_getLMStatusListener(Message msg);
Gets the status listener for the message.LMSG_ saveTo
Declaration: void LMSG_saveTo(Message msg, mqstring fileName, mqboolean isBlocking);
Saves the contents of the message in the file specified.LMSG_ resumeSaveTo
Declaration: void LMSG_resumeSaveTo(Message msg, mqboolean isBlocking);
Resumes saving the contents of the message in the file specified.LMSG_resumeSend
Declaration: void LMSG_resumeSend(Message msg);
Resumes an incomplete transfer. This function is used to resume a message transfer which could not be completed earlier either due to some internal error or due to some problem at the client side.LMSG_ cancelAllTransfers
Declaration: void LMSG_cancelAllTransfers(Message msg);
Cancels all message transfers which are currently transferring this message. A cancelled transfer also removes the resume information of the transfer. Hence a transfer once cancelled cannot be resumed.LMSG_ cancelTransfer
Declaration: void LMSG_cancelTransfer(Message msg, int consumerID);
Cancels the transfer specified by the consumerID.
A cancelled transfer also removes the resume information of the transfer. Hence a transfer once cancelled cannot be resumed.LMSG_ suspendAllTransfers
Declaration: void LMSG_suspendAllTransfers(Message msg);
Suspends all the message transfers which are transferring this large message temporarily.
Suspending a transfer only stops the thread which is doing the message transfer and does not delete resume related information. Hence, a suspended transfer can be resumed using resume functions.LMSG_suspendTransfer
Declaration: void LMSG_suspendTransfer(Message msg, int consumerID);
Suspends the transfer specified by the consumerID temporarily.
Suspending a transfer only stops the thread which is doing the message transfer and does not delete resume related information. Hence, a stopped transfer can be resumed using resume functions.LMSG_setFragmentSize
Declaration: void LMS_setFragmentSize(Message msg, int size);
Sets the fragment size for the message.LMSG_getFragmentSize
Declaration: int LMSG_getFragmentSize(Message msg);
gets the fragment size of the message.LMSG_setWindowSize
Declaration: void LMSG_setWindowSize(Message msg, int size);
Sets the frequency after which acknowledgement will be sentLMSG_getWindowSize
Declaration: int LMSG_getWindowSize(Message msg);
gets the window size of the message.LMSG_setRequestTimeoutInterval
Declaration: void LMSG_setRequestTimeoutInterval(Message msg, long timeout);
Sets the time until which the sender will wait for message transfer to startLMSG_getRequestTimeoutInterval
Declaration: long LMSG_getRequestTimeoutInterval(Message msg);
Gets the time until which the sender will wait for message transfer to startLMSG_ setResponseTimeoutInterval
Declaration: void LMSG_setResponseTimeoutInterval(Message msg, long responseInterval);
Sets the time until which the sender/receiver will wait for message from the other end.LMSG_getResponseTimeoutInterval
Declaration: long LMSG_getResponseTimeoutInterval(Message msg);
Gets the time until which the sender/receiver will wait for messages from the other end. The following functions are to get the status information from LMTransferStatus Structure.LMTS_getBytesTransferred
Declaration: mqlong LMTS_getBytesTransferred(LMTransferStatus lmts);
Returns the number of bytes transferred.LMTS_getBytesToTransfer
Declaration: mqlong LMTS_getBytesToTransfer(LMTransferStatus lmts);
Returns the number of bytes to be transferred.LMTS_getLastFragmentID
Declaration: mqlong LMTS_getLastFragmentID(LMTransferStatus lmts);
Returns the ID of the last fragment.LMTS_getPercentageProgress
Declaration: float LMTS_getPercentageProgress(LMTransferStatus lmts);
Returns the percentage of the progress of message transfer.LMTS_getStatus
Declaration: mqbyte LMTS_getStatus(LMTransferStatus lmts);
Returns the status of the Message transfer.
LM_TRANSFER_NOT_INIT or 1
Indicates that the transfer has not yet started
LM_TRANSFER_IN_PROGRESS or 2
Indicates that transfer is currently in progress
LM_TRANSFER_DONE or 3
Indicates that the transfer is complete for one consumer
LM_TRANSFER_ERR or 4
Indicates that an error occurred during the transfer
LM_ALL_TRANSFER_DONE or 5
Indicates that the transfer is complete for all consumersLMTS_isTransferComplete
Declaration: mqboolean LMTS_isTransferComplete(LMTransferStatus lmts);
Returns TRUE if transfer completes, else returns FALSE.LMTS_isTransferCompleteForAll
Declaration: mqboolean LMTS_isTransferCompleteForAll(LMTransferStatus lmts);
Returns TRUE if all the transfers are completed, else returns FALSE.LMTS_getLargeMessage
Declaration: Message LMTS_getLargeMessage(LMTransferStatus lmts);
Returns the large message for which this status is created.LMTS_getConsumerID
Declaration: int LMTS_getConsumerID(LMTransferStatus lmts);
Returns the consumerID of the connection that is being used.
These functions are used to get any pending large messages.LMC_getUnfinishedMessagesToSend
Declaration: RMEnum LMC_getUnfinishedMessagesToSend(FioranoConnection fc);
Gets the enumeration of Messages whose transfers are pending as they were not fully sent.LMC_getUnfinishedMessagesToReceive
Declaration: RMEnum LMC_getUnfinishedMessagesToReceive(FioranoConnection fc);
Gets the enumeration of Messages which were not fully received and need to be resumed.
RMEnum is Recoverable Messages Enumeration. The following functions should be called to use the RMEnum structure.RME_hasMoreElements
Declaration: mqboolean RME_hasMoreElements(RMEnum enumr);
Returns true if there are more elements in the enumeration, false otherwise.RME_nextElement
Declaration: mqobject RME_nextElement(RMEnum enumr);
Return the next element (Message Object) of the enumeration.Error Handling
The error handling mechanism in CRTL is very similar to Exception handling in Java. An exception/error stack is maintained and the errors occurred during a call to any API are pushed into this stack automatically. When the call returns, the user should check for any error occurred during that call and take necessary steps. For this purpose, the user is provided with the following functions, which operate on this error stack.
API
Function
MqExceptionOccured()
Returns a Boolean value indicating whether an exception occurred, in the most recent API call.
MqPrintException()
Prints the exception stack, including the error code and a description
MqExceptionClear()
Clears the stack of exceptions occurred until this call
MqGetLastErrCode()
Gets the error code of the last exception pushed in the exception stack
The MqExceptionOccurred() can be avoided by checking the return value of the API call.
- The APIs, which don't return any value in Java, are declared to return an mqboolean in CRTL indicating the success/failure of the call.
- The APIs, which return basic data types in Java, are declared to return an mqboolean and take a value-result argument of that type in CRTL. The mqboolean value returned indicates the success of the call
- The APIs, which return an object in Java, return a pointer in CRTL. The return value is NULL if an error occurred during the call.
The MqExceptionClear() function should be called after every failed API call. Or, it is possible that the following API calls fail due to the exception that occurred during this call.
The exception stack is maintained in the Thread Local Storage, so that the exception that occurred in one thread doesn't interfere the flow of other threads.
The MqGetLastErrCode() should be used, when the user wants to check what error has occurred in the API call and proceed accordingly. On the other hand, the MqPrintException() is used to print a detailed description of the Error, which leads to the root of the exception.
Utility APIs
Key-value pairs in Hashtable
Hashtable represents a pointer to an internally maintained structure, which maintains key value pairs.
API | Function |
---|---|
HT_Clear | Clears this hashtable so that it contains no keys and/or elements. |
HT_ContainsKey | Tests if the specified mqstring is a key in this hash-table. |
HT_ContainsValue | Returns true if this hashtable maps one or more keys to this value. |
HT_Get | Returns the value to which the specified key is mapped in this hashtable. |
HT_IsEmpty | Tests if this hashtable maps no keys to values. |
HT_Put | Maps the specified key to the specified value in the argument hashtable. |
HT_RemoveElement | Removes the key (and its corresponding value) from this hashtable. |
HT_Size | Returns the number of keys in this hashtable. |