Progress
External Program
Interfaces


Session Objects

The Session objects, jms/pubsubsession.p and jms/ptpsession.p, encapsulate JMS connections and sessions.

The life cycle of a Session object consists of these general stages:

  1. The application creates a session, but is not yet connected to the SonicMQ Adapter.
  2. The application sets connection and session attributes.
  3. The application runs beginSession to connect to the SonicMQ Adapter.
  4. The application uses session methods to publish and subscribe or send and receive messages from a queue.
  5. When the application finishes, it calls deleteSession to delete the connection from the application to the SonicMQ Adapter, delete the connection from the SonicMQ Adapter to SonicMQ, and delete the Session object.

The following sections describe methods common to both Session objects, pubsubsession.p and ptpsession.p.

Creating a Session Procedure

The application creates a session procedure by calling pubsubsession.p or ptpsession.p persistently with the adapterConnection input parameter. At this point, the application has not created the actual JMS session or connected to the SonicMQ Adapter.

The adapterConnection parameter specifies the connection parameters to the SonicMQ Adapter. This allows an application to set different session level attributes before starting the JMS session.

Examples of valid adapterConnection parameters include:

"-H host1 -S 5162" /*The Name Server is on host1, listening on UDP port 5162*/ 
""            /*The Name Server is local, listening on the default UDP port*/ 
“-URL http://host1:3099/uri?AppService=adapter.progress.jms” 
              /*Connecting through HTTP (on a WebClient)*/ 
“-URL AppServer://host1:5162/uri?AppService=adapter.progress.jms” 
              /*Equivalent to "-H host1 -S 5162"*/ 

This is an example of an invalid adapterConnection parameter:

 “-URL http://host1:3099/uri”  /*The value adapter’s service name is missing*/ 

This is the definition of the adapterConnection input parameter to jms/pubsubsession.p and jms/ptpsession.p:

SYNTAX
DEFINE INPUT PARAMETER adapterConnection AS CHAR. 

Setting JMS Connection and Session Attributes

Next, the application specifies connection and session attributes.

The following procedure specifies the service name under which the SonicMQ Adapter is registered with the NameServer. The default is adapter.progress.jms; if the SonicMQ Adapter uses that service name, setAdapterService is unnecessary:

SYNTAX
PROCEDURE setAdapterService.  
DEFINE INPUT PARAMETER serviceName AS CHAR.  

The following procedure specifies the JMS broker implementation, SonicMQ. If set on the client side, it overwrites the jmsServerName property set on the SonicMQ Adapter side:

SYNTAX
PROCEDURE setJmsServerName.  
DEFINE INPUT PARAMETER jmsServerName AS CHAR. 

The following procedure sets the value of the SonicMQ broker URL. If set on the client, it overwrites the default brokerURL property set on the SonicMQ Adapter side. The creation of a session fails if no value was set on the client or at the SonicMQ Adapter:

SYNTAX
PROCEDURE setBrokerURL.  
DEFINE INPUT PARAMETER brokerURL AS CHAR.  

The following procedure specifies the interval in seconds for the SonicMQ Adapter to actively ping the SonicMQ broker so communication failure can be detected promptly. The setPingInterval functionality is a SonicMQ extension. A pingInterval value can also be specified in the srvrStartupParam property of the SonicMQ Adapter as a default for all the clients. No pinging is performed by default. (See the SonicMQ Programming Guide ). setPingInterval must be called before beginSession is called:

SYNTAX
PROCEDURE setPingInterval.  
DEFINE INPUT PARAMETER interval AS INT. 

The following procedure sets the user value for the SonicMQ broker login. If set, it overwrites the default user property set on the SonicMQ Adapter side:

SYNTAX
PROCEDURE setUser. 
DEFINE INPUT PARAMETER User AS CHAR. 

The following procedure sets the password value for the SonicMQ broker login. If set, it overwrites the default password property set on the SonicMQ Adapter side:

SYNTAX
PROCEDURE setPassword.  
DEFINE INPUT PARAMETER password AS CHAR. 

The following procedure sets the clientID value for the SonicMQ broker connection. If set, it overwrites the default clientID set on the server side. A clientID is required for durable subscriptions:

SYNTAX
PROCEDURE setClientID.  
DEFINE INPUT PARAMETER clientID AS CHAR. 

The following procedure makes the session transacted for sending. A session is not transacted by default:

SYNTAX
PROCEDURE setTransactedSend. 

The following procedure makes the session transacted for receiving. A session is not transacted by default:

SYNTAX
PROCEDURE setTransactedReceive. 

Getting JMS Connection and Session Attributes

The following function returns a comma-separated list of connection and provider attributes in this order: JMSVersion, JMSMajorVersion, JMSMinorVersion, JMSProviderName, JMSProviderVersion, JMSProviderMajorVersion, and JMSProviderMinorVersion:

SYNTAX
FUNCTION getConnectionMetaData RETURNS CHAR. 

The following functions return the value set by the preceding set... procedures. Null is returned if the set... procedure was not called; False is returned if setTransacted... was not called:

SYNTAX
FUNCTION getJmsServerName RETURNS CHAR. 
FUNCTION getAdapterService RETURNS CHAR. 
FUNCTION getBrokerURL RETURNS CHAR. 
FUNCTION getUser RETURNS CHAR. 
FUNCTION getPassword RETURNS CHAR. 
FUNCTION getClientID RETURNS CHAR. 
FUNCTION getTransactedSend RETURNS LOGICAL. 
FUNCTION getTransactedReceive RETURNS LOGICAL. 

Setting Message Delivery Parameters

Message delivery parameters set on the Session object are used as defaults for all messages sent in that session. The default can be changed by setting the parameters of the publish call, the sendToQueue call, or the requestReply call. These values cannot be changed after beginSession is called.

The following procedure sets the default message priority. The range of priority values is 0 – 9; the default is 4. Setting an UNKNOWN value has no effect:

SYNTAX
PROCEDURE setDefaultPriority. 
DEFINE INPUT PARAMETER priority AS INT. 

The following procedure sets the default time to live, the value in milliseconds from the time a message is sent to the time the SonicMQ broker can delete the message from the system. A setting of 0 means that the message never expires. The default is JMS broker-dependent; the SonicMQ default value is 0. Any fractional part of the decimal value is truncated. If the value does not fit in a Java long value, Java rules for decimal-to-long conversions are used. Setting an UNKNOWN value has no effect:

SYNTAX
PROCEDURE setDefaultTimeToLive. 
DEFINE INPUT PARAMETER millis AS DECIMAL. 

The following procedure sets the message persistency value. The allowed values for message persistency are: PERSISTENT, NON_PERSISTENT, NON_PERSISTENT_ASYNC, and UNKNOWN (?). The default value is PERSISTENT. The evaluation is case insensitive. A call with an UNKNOWN value has no effect. NON_PERSISTENT_ASYNC is a SonicMQ extension of the JMS specification:

SYNTAX
PROCEDURE setDefaultPersistency  
DEFINE INPUT PARAMETER deliveryMode AS CHAR. 

Getting Message Delivery Parameters

The following function returns the value specified by setDefaultPriority. It returns 4 if setDefaultPriority was not called:

SYNTAX
FUNCTION getDefaultPriority RETURNS INT. 

The following function returns the value specified by setDefaultTimeToLive. It returns UNKNOWN if setDefaultTimeToLive was not called:

SYNTAX
FUNCTION getDefaultTimeToLive RETURNS DECIMAL. 

The following function returns the value specified by setDefaultPersistency. It returns PERSISTENT if setDefaultPersistency was not called:

SYNTAX
FUNCTION getDefaultPersistency RETURNS CHAR. 

Connecting To the SonicMQ Adapter

To actually connect to the SonicMQ Adapter and start a JMS connection and session, an application calls beginSession. Note that the application does not call beginSession until after setting some (or none) of the previously described attributes. If beginSession returns an error, the Session object is automatically deleted:

SYNTAX
PROCEDURE beginSession. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Session-level Methods

The following procedure starts receiving messages after creating a new session or after calling stopReceiveMessages. Messages can be sent without calling startReceiveMessages:

SYNTAX
PROCEDURE startReceiveMessages.  

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure causes the SonicMQ Adapter broker to stop receiving messages on behalf of the 4GL client and to stop sending messages already received by the SonicMQ Adapter broker for the client. A subsequent call to startReceiveMessages resumes message reception and delivery.

If this procedure is called in a pubsubsession object and the subscription is not durable, messages published while reception is stopped are not delivered. A single message that was already sent to the client before stopReceiveMessages was called might be received by the client after the stopReceiveMessages call:

SYNTAX
PROCEDURE stopReceiveMessages. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure closes a session and its underlying connection and deletes the session procedure:

SYNTAX
PROCEDURE deleteSession. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following function returns the AppServer connection ID. This value is typically used to correlate the session to log entries on the server side. This function returns UNKNOWN when called before calling beginSession:

SYNTAX
FUNCTION getConnectionID RETURNS CHAR. 

Load Balancing

Sonic supports the creation of load-balanced clusters. If client-side load balancing is enabled, a connect request can be redirected to another broker within a SonicMQ cluster, provided broker-side load-balancing is enabled.

The following function enables or disables client-side load balancing:

SYNTAX
PROCEDURE setLoadBalancing 
DEFINE INPUT PARAMETER loadBalancing AS LOGICAL. 

The following function reports the current status of client-side load balancing, returning TRUE if it is enabled or FALSE if it is disabled:

SYNTAX
FUNCTION getLoadBalancing RETURNS LOGICAL. 

Request/Reply

Request/Reply is a mechanism for the JMSReplyTo message header field to specify the destination where a reply to a message should be sent.The requestReply method sends a message to a destination and designates the messageConsumer parameter for processing replies. Since this call is supported by both the pubsubsession.p object and the ptpsession.p object, Progress uses the term, destination, which can be used for both topics and queues.

Java–JMS supports a manual approach through the JMSReplyTo field, whereas the 4GL–JMS implementation automates the request/reply sequence:

The 4GL–JMS implementation uses a temporary destination for the reply. It is an error to set the JMSReplyTo field of the message explicitly if requestReply is used. The reply is received by messageConsumer asynchronously, just like any other message reception. The temporary destination is deleted when the Message Consumer object is deleted:

SYNTAX
PROCEDURE requestReply.  
DEFINE INPUT PARAMETER destination AS CHAR.  
DEFINE INPUT PARAMETER message AS HANDLE. 
DEFINE INPUT PARAMETER replySelector AS CHAR.      /*UNKNOWN means 
                                                     receiving all replies*/ 
DEFINE INPUT PARAMETER messageConsumer AS HANDLE.  /*UNKNOWN is illegal*/ 
DEFINE INPUT PARAMETER priority AS INT.            /*Session default is 
                                                     used if UNKNOWN.*/ 
DEFINE INPUT PARAMETER timeToLive AS DECIMAL.      /*Session default is 
                                                     used if UNKNOWN.*/ 
DEFINE INPUT PARAMETER deliveryMode AS CHAR.       /*Session default is 
                                                     used if UNKNOWN.*/ 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Transaction and Recovery Methods

The following procedure sends all messages published (or sent to a queue) up to that point in the current transaction. It is an error to call this method in a Session object that is not transacted for sending:

SYNTAX
PROCEDURE commitSend. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure acknowledges all messages received up to that point in the current transaction. It is an error to call this procedure in a Session object that is not transacted for receiving:

SYNTAX
PROCEDURE commitReceive. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure discards all messages sent up to that point in the current transaction. It is an error to call this procedure in a Session object that is not transacted for sending:

SYNTAX
PROCEDURE rollbackSend. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure starts redelivering the messages received up to that point in the current transaction. It is an error to call this procedure in a Session object that is not transacted for receiving:

SYNTAX
PROCEDURE rollbackReceive. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure starts redelivering all unacknowledged messages received up to that point in the current session. It is an error to call this procedure in a Session object that is not transacted for receiving:

SYNTAX
PROCEDURE recover. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Factory Procedures

Message objects can be created before or after connecting to the SonicMQ Adapter (the beginSession call). This means you can test message manipulation functionality without connecting to the SonicMQ Adapter. Message consumer objects can be called only after beginSession is called.

The following procedure returns a new Message Consumer object in the consumerHandle output parameter:

SYNTAX
PROCEDURE createMessageConsumer. 
DEFINE INPUT PARAMETER procHandle AS HANDLE.  
DEFINE INPUT PARAMETER procName AS CHAR.     
DEFINE OUTPUT PARAMETER consumerHandle AS HANDLE. 

The following procedure creates a new Header Message object in the messageHandle output parameter:

SYNTAX
PROCEDURE createHeaderMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

The following procedure creates a new TextMessage object in the messageHandle output parameter:

SYNTAX
PROCEDURE createTextMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

The following procedure creates a new MapMessage object in the messageHandle output parameter:

SYNTAX
PROCEDURE createMapMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

The following procedure creates a new StreamMessage object in the messageHandle output parameter:

SYNTAX
PROCEDURE createStreamMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

The following procedure creates a new BytesMessage object in the messageHandle output parameter:

SYNTAX
PROCEDURE createBytesMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

The following procedure creates a new XMLMessage object in the messageHandle output parameter:

SYNTAX
PROCEDURE createXMLMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

The following procedure creates a new MultipartMessage object in the messageHandle output parameter:

SYNTAX
PROCEDURE createMultipartMessage. 
DEFINE OUTPUT PARAMETER messageHandle AS HANDLE. 

Fail-over Support

Sonic lets a client specify a list of Sonic brokers to connect to. This makes it easier for the client to connect to a broker when one or more brokers are not available. Sonic also lets the application specify whether to try connecting to the brokers in the list sequentially or randomly.

The following method is called instead of setBrokerURL to specify a list of broker URLs for the client to connect to:

SYNTAX
PROCEDURE setConnectionURLs. 
DEFINE INPUT PARAMETER brokerList AS CHARACTER. 

The following method returns a comma-separated list of Sonic broker URLs for the client to try to connect to:

SYNTAX
FUNCTION getConnectionURLs RETURNS CHARACTER. 

The following method lets the application specify whether the brokers in a connection list are tried sequentially or randomly:

SYNTAX
PROCEDURE setSequential. 
DEFINE INPUT PARAMETER seq AS LOGICAL. 

The following method reports whether the brokers in a connection list are tried sequentially or randomly:

SYNTAX
FUNCTION getSequential RETURNS LOGICAL. 

Error Handling

Applications should handle asynchronous conditions programmatically by creating a messageConsumer object and passing it to the setErrorHandler procedure in the Session object. Asynchronous conditions are always reported as a TextMessage with several possible CHAR message properties. The CHAR properties that might be included in the message header are: exception, errorCode, linkedException-1, linkedException-2… linkedException-N (where N is a number of additional exceptions linked to the main exception). (See the example in the "Installing an Error Handler To Handle an Asynchronous Error" section in Using the SonicMQ Adapter.")

The getPropertyNames message function can be used to get the list of properties in the error message header. If the application does not call setErrorHandler, a default error handler displays the error message and the properties in alert boxes:

SYNTAX
PROCEDURE setErrorHandler. 
DEFINE INPUT PARAMETER messageConsumer AS HANDLE. 

NOTE: The application must create the error-handling messageConsumer object and call setErrorHandler after calling beginSession.

The following procedure turns the automatic display of synchronous errors and conditions on and off. If set to true, synchronous errors and conditions are not automatically displayed by the 4GL–JMS implementation. If set to false, synchronous errors and conditions are automatically displayed in alert boxes. The default value is false:

SYNTAX
PROCEDURE setNoErrorDisplay. 
DEFINE INPUT PARAMETER noDisplay AS LOGICAL. 

NOTE: Messages inherit the display/noDisplay property from the session that created them. However, after a message is created, it is independent from the session; setNoErrorDisplay must be called in the message itself to change the property.

Processing Messages

The waitForMessages call waits and processes events as long as the user-defined function UDFName (in procH) returns true and there is no period of more than timeOut seconds in which no messages are received. The user-defined function is evaluated each time after a message is handled:

SYNTAX
PROCEDURE waitForMessages: 
DEFINE INPUT PARAMETER UDFName AS CHAR NO-UNDO.  
DEFINE INPUT PARAMETER procH AS HANDLE NO-UNDO.  
DEFINE INPUT PARAMETER timeOut AS INT NO-UNDO.  

Flow Control

When the SonicMQ Adapter sends a message to a queue that is full or to a topic whose queue is full, an error is raised.

Also, the SonicMQ Adapter lets the client set the prefetch count and the prefetch threshold, which are used when the client retrieves messages from a queue. The prefetch count sets how many messages the Sonic client can retrieve in a single operation from a queue that contains multiple messages. The prefetch threshold determines when the Sonic client goes back to the broker for more messages. For example, a threshold of one means that the client does not go back to the broker until the last message has been delivered.

The following method sets the prefetch count:

SYNTAX
PROCEDURE setPrefetchCount.  
DEFINE INPUT PARAMETER count AS INTEGER. 

The following method sets the prefetch threshold:

SYNTAX
PROCEDURE setPrefetchThreshold.  
DEFINE INPUT PARAMETER threshold AS INTEGER. 

Comparison Of pubsubsession.p With ptpsession.p

The persistent procedures, pubsubsession.p and ptpsession.p, have the same methods except:

NOTES:

pubsubsession.p

Most methods are common to both pubsubsession.p and ptpsession.p. This section describes only those methods unique to pubsubsession.p.

An application creates the session procedure for Pub/Sub messaging by calling pubsubsession.p persistently with the following input parameter:

SYNTAX
DEFINE INPUT adapterConnection AS CHAR. 

For more information about adapterConnection, see the "Creating a Session Procedure" section in this chapter.

Publishing To a Topic

An application uses the publish procedure to publish messages to a topic. The publish procedure takes five input parameters:

The publish procedure publishes a message to topicName. If the publication is in reply to a received message, topicName can be the replyTo field obtained from the original message:

SYNTAX
PROCEDURE publish. 
DEFINE INPUT PARAMETER topicName AS CHAR.  
DEFINE INPUT PARAMETER message AS HANDLE.  
DEFINE INPUT PARAMETER priority AS INT.             /*Session default is 
                                                      used if UNKNOWN.*/ 
DEFINE INPUT PARAMETER timeToLive AS DECIMAL.       /*Session default is 
                                                      used if UNKNOWN.*/ 
DEFINE INPUT PARAMETER deliveryMode AS CHAR.        /*Session default is 
                                                      used if UNKNOWN.*/ 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Subscribing To a Topic

An application uses the subscribe procedure to subscribe to a topic. The subscribe procedure takes five input parameters:

The subscribe procedure subscribes to topicName. The messages are handled asynchronously by the messageConsumer object. A subscriptionName parameter with a value other than UNKNOWN specifies a durable subscription. Durable subscriptions require the JMS client to have a clientID identifier. The client must call setClientID in the pubsubsession.p object (or set the default clientID on the server side) if a durable subscription is desired. If the subscriptionName value is UNKNOWN or an empty string, the subscription is not durable. The default of noLocalPublications is false; the session, by default, gets its own publications:

SYNTAX
PROCEDURE subscribe. 
DEFINE INPUT PARAMETER topicName AS CHAR. 
DEFINE INPUT PARAMETER subscriptionName AS CHAR.  
DEFINE INPUT PARAMETER messageSelector AS CHAR.    
DEFINE INPUT PARAMETER noLocalPublications AS LOGICAL.  
DEFINE INPUT PARAMETER messageConsumer AS HANDLE.  

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

The following procedure cancels a durable subscription. It is an error to call this procedure if there is an active message consumer for that subscription; call deleteConsumer first to delete the message consumer:

SYNTAX
PROCEDURE cancelDurableSubscription. 
DEFINE INPUT PARAMETER subscriptionName AS CHAR. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

ptpsession.p

Most Session methods are common to both pubsubsession.p and ptpsession.p. This section describes only those methods unique to ptpsession.p.

Applications use ptpsession.p. for PTP messaging. The session procedure for PTP messaging is created by calling ptpsession.p persistently with the following input parameter:

SYNTAX
DEFINE INPUT adapterConnection AS CHAR.  

For more information about adapterConnection, see the "Creating a Session Procedure" section in this chapter.

Sending Messages To a Queue

Applications use the sendToQueue procedure to send messages to a queue. The sendToQueue procedure takes five input parameters:

This procedure sends a message to queueName. If the sending is in reply to a received message, queueName can be the replyTo field obtained from the original message:

SYNTAX
PROCEDURE sendToQueue. 
DEFINE INPUT PARAMETER queueName AS CHAR.  
DEFINE INPUT PARAMETER message AS HANDLE.  
DEFINE INPUT PARAMETER priority AS INT.              /*Session default is 
                                                       used if UNKNOWN.*/ 
DEFINE INPUT PARAMETER timeToLive AS DECIMAL.        /*Session default is 
                                                       used if UNKNOWN.*/ 
DEFINE INPUT PARAMETER deliveryMode AS CHAR.         /*Session default is 
                                                       used if UNKNOWN.*/ 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Receiving Messages From a Queue

Applications use receiveFromQueue to receive messages from a queue. The receiveFromQueue procedure takes three input parameters:

This procedure receives messages from queueName. The messages are handled asynchronously by the messageConsumer procedure:

SYNTAX
PROCEDURE receiveFromQueue. 
DEFINE INPUT PARAMETER queueName AS CHAR. 
DEFINE INPUT PARAMETER messageSelector AS CHAR.   *UNKNOWN means 
                                                   receiving all messages.*/ 
DEFINE INPUT PARAMETER messageConsumer AS HANDLE. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Browsing Messages On a Queue

Applications use browseQueue to view messages in a queue without consuming them. This procedure receives (for browsing) all messages currently in the queue in the messageConsumer object:

SYNTAX
PROCEDURE browseQueue.  
DEFINE INPUT PARAMETER queueName AS CHAR.  
DEFINE INPUT PARAMETER messageConsumer AS HANDLE. 

NOTES:


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095