In this section: Reference: |
Messaging and Queuing utilizes message-oriented middleware (software that functions between application programs and the network infrastructure) as the core of its distributed computing environment. Message-oriented middleware enables application programs to interact by exchanging messages.
The API Messaging and Queuing model-employing message-oriented middleware merged with the SQL client/server model-enables the distributed components of an application to communicate, synchronously or asynchronously, by exchanging records known as messages. In the API, this peer-to-peer communication between application programs is expressed in terms of the following message types:
Messaging and Queuing places SQL queries on local queues for subsequent delivery to remote servers. Servers process the queries in a first-come, first-serve order, and place one or more correlated response messages (result sets) on an output queue. Later, the communications component of Messaging and Queuing relays these response messages to queues accessible to the requester.
Messaging and Queuing maintains a message queue for each addressable asynchronous server. It reveals the contents of individual queues by materializing a result set representing the structure of the queue as if it were a table. With EDABROWSE, Messaging can extract the current status of any completed query and locate the corresponding response message by scanning tables that describe completed Units of Work.
Messaging and Queuing imposes certain restrictions on method calls directed to asynchronous data sources. The restrictions apply both to the preparation and issuance of SQL queries, and to the browsing and manipulation of message queues.
For information on preparation and issuance of SQL queries, see API Data Structures. For information on EDABROWSE and other method calls, see Method Reference.
A message is a record passed between two applications. The API controls the format of the messages in each direction to exchange the data in an efficient manner.
The fields in the asynchronous messaging information packet are not exposed to the application and are always under the control of the API. The API supplies the values for these fields as information becomes available. The attributes and descriptions are shown below.
This information is maintained in the Message Table of the EDABASE Data Structures and can be viewed using EDABROWSE. For information on tables, see API Data Structures.
A message is created when the sending application invokes EDASQL, and normally ceases to exist when the receiving application deletes it from the queue. Messages persist until an application program explicitly deletes them. The EDABROWSE method provides a searched delete capability enabling application programs to remove a specific message or a group of related messages from the queue.
Attribute |
Description |
Message Identifier |
A unique, 8-byte message ID associated with the message. |
UOW Identifier |
Also called the Correlation Identifier. The ID of Unit of Work (UOW) that prompted this response message. The system places correlation identifiers in response messages so client programs can associate queries and responses. When a client issues an SQL query message, the API returns the query message identifier (using EDAINSPECT) to the application. When the server responds with a result set message, the correlation ID field of an SQL query message is set to the query message identifier. The client then uses the query message identifier to link a result set message to an SQL query message. |
User ID |
The user ID of the originator of the UOW. |
Status |
The status of a query message expressed. Possible values are: 1 = EDA_UOWSTATE_CONFIRM 2 = EDA_UOWSTATE_FAILED 3 = EDA_UOWSTATE_INDOUBT 4 = EDA_UOWSTATE_TIMEDOUT Note: Only response messages carry this information. |
Message Return Code |
The return code from the Message Server. Possible values are: 1 = Timeout 2 = No DEM 3 = No Entry 4 = Target Failure 5 = Protocol Failure Note: Only response messages carry this information. |
Status Code |
The status code in the SCB status field. Note: Only response messages carry this information. |
Date/Time Sent Stamp |
The time and date the message was sent. |
Date/Time Processed Stamp |
The time and date the message was processed. Note: Only response messages carry this information. |
The API reacts to a completed EDASQL operation directed to an asynchronous server by placing a query message in a local queue. In time, a query message migrates from a local queue to a remote queue. Eventually, an agent associated with a remote queue extracts the request string from a query message and submits it to an asynchronous server. A query message remains in a remote queue until the agent receives a suitable response from the server. This approach enables the agent to resubmit the request if the server fails to process it correctly. Finally, the agent obtains a suitable response and relays it to the client's queue. Should a suitable response give rise to many large result sets, the agent would transmit multiple attachments with the same UOW handle to the client's queue. However, when the Message Table is browsed, the client application sees only two messages listed for the same UOW; the original query message and the response message. The number of attachments to the response is transparent to the client application. The entire contents of the response message are accessible in a single invocation of EDASQL and are retrieved as a single response message.
The client, who in the interim has periodically scanned the Message Table of the EDABASE database looking for something to process, isolates a row containing a result set locator that correlates with a query statement. The client materializes a result set locator using an EDASQL call with the UOW handle value in the statement parameter. The execute parameter is set to four (4) to indicate that this is an ALOB materialization. The application then processes the result set row by row-by invoking EDAFETCH or a combination of EDANEXT and EDAFIELD exactly as is the case with synchronous servers.
Note: A query message, a result set locator, and other messages correlate to a query message and remain in a local queue until the application explicitly releases them. The client deletes a query message, and all messages that correlate to a query message, by calling EDABROWSE with an appropriate command parameter.
Method calls that launch asynchronous client requests resemble method calls that initiate session-based client requests. But despite strong surface similarities, there are important differences between message-based and session-based processing environments. The API obliges application programs to obtain request status information from an entirely different source. In a synchronous context, application programs employ EDATEST to synchronize their operation with the server. In an asynchronous context, EDATEST is only meaningful once the application has begun to process a response message; application programs must obtain request status by extracting information from the Status field of a Message Table instance.
The Status field of an SQL request row in the Message Table can assume any of the following values:
Variable |
Description |
EDA_UOWSTATE_CONFIRM |
This message contains the response generated by the server. |
EDA_UOWSTATE_FAILED |
The query failed and could not be retried. This is the status of a query having an invalid user ID and/or password. |
EDA_UOWSTATE_TIMEDOUT |
The response from the server was not received in the time allotted. |
EDA_UOWSTATE_INDOUBT |
The message never received a response of confirmation, failure, or time-out. |
Note: Each Status value listed corresponds to a completion status. No UOWs are available for browsing until processing of each has been completed.
When EDASQL emits a message, the API returns the unique identifier assigned to a message in a variable (EDA_VAR_ASYID) associated with the controlling SCB. Application programs use UOW identifiers to correlate requests and responses.
| iWay Software |