This chapter deals with the use of the ATMI COBOL language functions for enqueuing and dequeuing messages: The BEA TUXEDO programmer coding client or server programs for the queued message facility should be familiar with the COBOL language binding to the BEA TUXEDO ATMI. General guidance on BEA TUXEDO programming is available in the BEA TUXEDO COBOL Guide. Detailed pages on all the ATMI functions are in Section 3cbl of the BEA TUXEDO Reference Manual.
The calls used to place a message on a BEA TUXEDO System/Q queue can originate in any client or server process associated with the application. The list includes:
TPENQUEUE and TPDEQUEUE, plus some ancillary functions.
Prerequisite Knowledge
Where Requests Can Originate
The coverage of BEA TUXEDO System/Q programming in this chapter reflects the illustration in Chapter 1, or at least the left-hand portion of it. In that figure a client (or a process acting in the role of a client) queues a message by calling The illustration in Chapter 1 goes on to show the queued message being dequeued by the server Some examples of customization are given after the discussion of the basic model.
The syntax for When a There are some important arguments to control the operation of The entry for server group The example shown on the reference page for Within a queue space, message queues are named according to application services that process the requests. Settings in Emphasis on the Default Case
TPENQUEUE and specifying a queue space available through the TMQUEUE server. The client later retrieves a reply via a TPDEQUEUE call to TMQUEUE.
TMQFORWARD and sent to an application server for processing (via TPCALL). When a reply to the TPCALL is received, TMQFORWARD enqueues the reply message. Since a major goal of TMQFORWARD is to provide an interface between the queue space and existing application services, it does not require further application coding. For that reason, this chapter concentrates on the client-to-qspace side.
Enqueuing Messages
TPENQUEUE is as follows.
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPENQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.TPENQUEUE call is issued it tells the system to store a message on the queue identified in QNAME in TPQUEDEF-REC in the space identified in QSPACE-NAME in TPQUEDEF-REC. The message is in DATA-REC, and LEN in TPTYPE-REC has the length of the message. By the use of settings in TPQUEDEF-REC, the system is informed how the call to TPENQUEUE is to be handled. Further information about the handling of the enqueued message and replies is provided in the TPQUEDEF-REC structure.
Command Line Arguments, TPENQUEUE(3)
TPENQUEUE(3cbl). Let's look at some of them.
TPENQUEUE: the QSPACE-NAME in TPQUEDEF-REC Argument
QSPACE-NAME identifies a queue space previously created by the administrator. When a server is defined in the SERVERS section of the configuration file, the service names it offers are aliases for the actual queue space name (which is specified as part of the OPENINFO parameter in the GROUPS section). For example, when your application uses the server TMQUEUE, the value pointed at by QSPACE-NAME is the name of a service advertised by TMQUEUE. If no service aliases are defined, the default service is the same as the server name, TMQUEUE. In this case the configuration file can include the following.
TMQUEUE
SRVGRP = QUE1 SRVID = 1
GRACE = 0 RESTART = Y CONV = N
CLOPT = "-A"
or
CLOPT = "-s TMQUEUE"QUE1 has an OPENINFO parameter that specifies the resource manager, the pathname of the device and the queue space name. The QSPACE-NAME argument in a client program can then look like this.
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 TPSTATUS-REC.
COPY TPSTATUS.
01 USER-DATA-REC PIC X(100).
*
*
*
MOVE LOW-VALUES TO TPQUEDEF-REC.
MOVE "TMQUEUE" TO QSPACE-NAME IN TPQUEDEF-REC.
MOVE "STRING" TO QNAME IN TPQUEDEF-REC.
SET TPTRAN IN TPQUEDEF-REC TO TRUE.
SET TPBLOCK IN TPQUEDEF-REC TO TRUE.
SET TPTIME IN TPQUEDEF-REC TO TRUE.
SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.
MOVE LOW-VALUES TO TPTYPE-REC.
MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.
MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.
CALL "TPENQUEUE" USING
TPQUEDEF-REC
TPTYPE-REC
USER-DATA-REC
TPSTATUS-REC.TMQUEUE(5) shows how alias service names can be included when the server is built and specified in the configuration file. The example in Appendix A, "A Sample Application," also specifies an alias service name.
TPENQUEUE: the QNAME in TPQUEDEF-REC Argument
QNAME contains such a value; an exception in which QNAME is not an application service is described later in the chapter.
TPENQUEUE: the DATA-REC and LEN in TPTYPE-REC Arguments
DATA-REC contains the message to be processed. LEN in TPTYPE-REC gives the length of the message. Some BEA TUXEDO record types (VIEW, for example) do not require LEN to be specified; in such cases, the argument is ignored. If RECTYPE in TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and the message is enqueued with no data portion.
TPENQUEUE: the Settings in TPQUEDEF-REC
TPQUEDEF-REC are used to tell the BEA TUXEDO system how the TPENQUEUE call is handled; the following are valid settings:
TPNOTRAN
TPNOTRAN or TPTRAN must be set.
TPTRAN
TPNOTRAN or TPTRAN must be set.
TPNOBLOCK
TP-STATUS set to TPEBLOCK. Either TPNOBLOCK or TPBLOCK must be set.
TPBLOCK
TPNOBLOCK or TPBLOCK must be set.
TPNOTIME
TPNOTIME or TPTIME must be set.
TPTIME
TPNOTIME or TPTIME must be set.
TPSIGRSTRT
TPSIGRSTRT or TPNOSIGRSTRT must be set.
TPNOSIGRSTRT
TP-STATUS to TPEGOTSIG. Either TPSIGRSTRT or TPNOSIGRSTRT must be set.
The TPQUEDEF-REC structure has members that are used by the application and by the BEA TUXEDO system to pass parameters in both directions between application programs and the queued message facility. It is defined in the COBOL COPY file. The client that calls TPQUEDEF-REC uses settings to mark members the application wants the system to fill in. The structure is also used by TPDEQUEUE; some of the members do not come into play until the application calls that function. The complete structure is shown in Listing 4-1.
Listing 4-1 The TPQUEDEF-REC Structure
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPNOBLOCK VALUE 0.
88 TPBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPNOTRAN VALUE 0.
88 TPTRAN VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPNOTIME VALUE 0.
88 TPTIME VALUE 1.
05 TPSIGRSTRT-FLAG PIC S9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPNOCHANGE-FLAG PIC S9(9) COMP-5.
88 TPNOCHANGE VALUE 0.
88 TPCHANGE VALUE 1.
05 TPQUE-ORDER-FLAG PIC S9(9) COMP-5.
88 TPQDEFAULT VALUE 0.
88 TPQTOP VALUE 1.
88 TPQBEFOREMSGID VALUE 2.
05 TPQUE-TIME-FLAG PIC S9(9) COMP-5.
88 TPQNOTIME VALUE 0.
88 TPQTIME-ABS VALUE 1.
88 TPQTIME-REL VALUE 2.
05 TPQUE-PRIORITY-FLAG PIC S9(9) COMP-5.
88 TPQNOPRIORITY VALUE 0.
88 TPQPRIORITY VALUE 1.
05 TPQUE-CORRID-FLAG PIC S9(9) COMP-5.
88 TPQNOCORRID VALUE 0.
88 TPQCORRID VALUE 1.
05 TPQUE-REPLYQ-FLAG PIC S9(9) COMP-5.
88 TPQNOREPLYQ VALUE 0.
88 TPQREPLYQ VALUE 1.
05 TPQUE-FAILQ-FLAG PIC S9(9) COMP-5.
88 TPQNOFAILUREQ VALUE 0.
88 TPQFAILUREQ VALUE 1.
05 TPQUE-MSGID-FLAG PIC S9(9) COMP-5.
88 TPQNOMSGID VALUE 0.
88 TPQMSGID VALUE 1.
05 TPQUE-GETBY-FLAG PIC S9(9) COMP-5.
88 TPQGETNEXT VALUE 0.
88 TPQGETBYMSGID VALUE 1.
88 TPQGETBYCORRID VALUE 2.
05 TPQUE-WAIT-FLAG PIC S9(9) COMP-5.
88 TPQNOWAIT VALUE 0.
88 TPQWAIT VALUE 1.
05 DIAGNOSTIC PIC S9(9) COMP-5.
88 QMEINVAL VALUE -1.
88 QMEBADRMID VALUE -2.
88 QMENOTOPEN VALUE -3.
88 QMETRAN VALUE -4.
88 QMEBADMSGID VALUE -5.
88 QMESYSTEM VALUE -6.
88 QMEOS VALUE -7.
88 QMENOTA VALUE -8.
88 QMEPROTO VALUE -9.
88 QMEBADQUEUE VALUE -10.
88 QMENOMSG VALUE -11.
88 QMEINUSE VALUE -12.
88 QMENOSPACE VALUE -13.
05 DEQ-TIME PIC 9(9) COMP-5.
05 PRIORITY PIC S9(9) COMP-5.
05 MSGID PIC X(32).
05 CORRID PIC X(32).
05 QNAME PIC X(15).
05 QSPACE-NAME PIC X(15).
05 REPLYQUEUE PIC X(15).
05 FAILUREQUEUE PIC X(15).
05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-5.
05 APPL-RETURN-CODE PIC S9(9) COMP-5.
05 APPKEY PIC S9(9) COMP-5.
The following is a list of valid settings for the parameters controlling input information for TPENQUEUE.
TPQTOP
TPQBEFOREMSGID
MSGID. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering to put a message ahead of another by MSGID. TPQTOP and TPQBEFOREMSGID are mutually exclusive settings. Assumes a prior (successful) call with TPQMSGID set.
TPQTIME-ABS
DEQ-TIME. The DEQ-TIME is an absolute time value as generated by time(2) or mktime(3C), if they are available in your UNIX operating system, or gp_mktime(3c), provided with the BEA TUXEDO system. The value set in DEQ-TIME is the number of seconds since 00:00:00 UTC, January 1, 1970. TPQTIME-ABS can be overridden and the message dequeued immediately by MSGID or CORRID.
TPQTIME-REL
DEQ-TIME specifies the number of seconds to delay after the transaction completes before the submitted request should be processed. TPQTIME-REL can be overridden and the message dequeued immediately by MSGID or CORRID. TPQTIME-ABS and TPQTIME-REL are mutually exclusive settings.
TPQPRIORITY
PRIORITY. PRIORITY must be in the range 1 to 100, inclusive.
TPQCORRID
CORRID is available when a request is dequeued with TPDEQUEUE. This identifier accompanies any reply or failure message that is queued so an application can correlate a reply with a particular request. The entire value should be initialized such that the value can be matched at a later time.
TPQREPLYQ
REPLYQUEUE is associated with the queued message. Any reply to the message will be queued to the named queue within the same queue space as the request message. If a reply is generated for the service and a reply queue is not specified or the reply queue does not exist, the reply is dropped.
TPQFAILUREQ
FAILUREQUEUE is associated with the queued message. If a failure occurs when executing the enqueued message, a failure message will go to the named queue within the same queue space as the original request message.
Additionally, the APPL-RETURN-CODE member of TPQUEDEF-REC can be set with a user-return code. This value will be returned to the application that calls TPDEQUEUE to dequeue the message.
On output from TPENQUEUE, the following elements may be set in the TPQUEDEF-REC structure.
05 TPQUE-MSGID-FLAG PIC S9(9) COMP-5.
88 TPQNOMSGID VALUE 0.
88 TPQMSGID VALUE 1.
05 DIAGNOSTIC PIC S9(9) COMP-5.
88 QMEINVAL VALUE -1.
88 QMEBADRMID VALUE -2.
88 QMENOTOPEN VALUE -3.
88 QMETRAN VALUE -4.
88 QMEBADMSGID VALUE -5.
88 QMESYSTEM VALUE -6.
88 QMEOS VALUE -7.
88 QMENOTA VALUE -8.
88 QMEPROTO VALUE -9.
88 QMEBADQUEUE VALUE -10.
88 QMENOMSG VALUE -11.
88 QMEINUSE VALUE -12.
88 QMENOSPACE VALUE -13.
05 MSGID PICX(32).
Setting of TPQUE-MSGID-FLAG requests output information from TPENQUEUE. If this setting bit is turned on when TPENQUEUE is called, then the associated element in the structure is populated if available and the bit remains set. If the value is not available, TPENQUEUE completes with the setting bit turned off.
TPQMSGID
TPENQUEUE was successful, the message identifier will be stored in MSGID. If the call to TPENQUEUE fails and TP-STATUS is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in DIAGNOSTIC. Following are the possible values.
QMEINVAL]
QMEBADRMID]
QMENOTOPEN]
QMETRAN]
TPNOTRAN set and an error occurred trying to start a transaction in which to enqueue the message.
QMEBADMSGID]
QMESYSTEM]
QMEOS]
QMENOTA]
QMEPROTO]
QMEBADQUEUE]
QMENOSPACE]
The remaining members of the control structure are not used on input to TPENQUEUE.
If the administrator in creating a queue allows TPENQUEUE calls to override the order of messages on the queue, you have two mutually exclusive ways to use that capability. You can specify that the message is to be placed at the top of the queue by setting TPQTOP or you can specify that it be placed ahead of a specific message by setting TPQBEFOREMSGID and setting MSGID to the ID of the message you wish to precede. This assumes that you saved the message-ID from a previous call in order to be able to use it here. Your administrator must tell you what the queue supports; it can be created to allow either or both of these overrides, or to allow neither.
If the queue was created with PRIORITY as a queue ordering parameter, you can set a value in PRIORITY to specify the dequeuing priority for the message. The value must be in the range 1 to 100; the higher the number the higher the priority, unlike the UNIX nice command. If PRIORITY was not one of the queue ordering parameters, setting a priority here has no effect.
A queue can be created with time as a queue ordering parameter. When this is the case, you can specify in DEQ-TIME either an absolute time for the message to be dequeued or a time relative to the enqueuing transaction. You set either TPQTIME-ABS or TPQTIME-REL to say how the value should be treated.
The following example shows how to enqueue a message with a relative time. It will become eligible for processing sixty seconds in the future.
01 TPQUEDEF-REC.COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 TPSTATUS-REC.
COPY TPSTATUS.
01 USER-DATA-REC PIC X(100).
*
*
*
MOVE LOW-VALUES TO TPQUEDEF-REC.
MOVE "QSPACE1" TO QSPACE-NAME IN TPQUEDEF-REC.
MOVE "Q1" TO QNAME IN TPQUEDEF-REC.
SET TPTRAN IN TPQUEDEF-REC TO TRUE.
SET TPBLOCK IN TPQUEDEF-REC TO TRUE.
SET TPTIME IN TPQUEDEF-REC TO TRUE.
SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.
SET TPQDEFAULT IN TPQUEDEF-REC TO TRUE.
SET TPQTIME-REL IN TPQUEDEF-REC TO TRUE.
MOVE 60 TO DEQ-TIME IN TPQUEDEF-REC.
SET TPQNOPRIORITY IN TPQUEDEF-REC TO TRUE.
SET TPQNOCORRID IN TPQUEDEF-REC TO TRUE.
SET TPQNOREPLYQ IN TPQUEDEF-REC TO TRUE.
SET TPQNOFAILUREQ IN TPQUEDEF-REC TO TRUE.
SET TPQMSGID IN TPQUEDEF-REC TO TRUE.
MOVE LOW-VALUES TO TPTYPE-REC.
MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.
MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.
CALL "TPENQUEUE" USING
TPQUEDEF-REC
TPTYPE-REC
USER-DATA-REC
TPSTATUS-REC.
Messages are always enqueued within a transaction; the only question is, within whose transaction? There are two choices. If caller of TPENQUEUE is in transaction mode and TPTRAN is set, then the enqueuing is done within the caller's transaction. The caller knows for certain from the success or failure of TPENQUEUE whether the message was enqueued or not. If the call succeeds, the message is guaranteed to be on the queue. If the call fails, the transaction is rolled back, including the part where the message was placed on the queue.
If the caller of TPENQUEUE is not in transaction mode or if TPNOTRAN is set, the message is enqueued in a separate transaction. If the call to TPENQUEUE returns success, the message is guaranteed to be on the queue. If the call to TPENQUEUE fails with a communication error or with a transaction or blocking timeout, the caller is left in doubt about whether the failure occurred before or after the message was enqueued.
Note that specifying TPNOTRAN while the caller is not in transaction mode has no meaning.
The syntax for TPDEQUEUE is as follows.
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPDEQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
When this call is issued it tells the system to dequeue a message from the QNAME in TPQUEDEF-REC queue, in the space named QSPACE-NAME in TPQUEDEF-REC. The message is placed in DATA-REC. LEN in TPTYPE-REC is set to the length of the data. If LEN is 0 on return from TPDEQUEUE, the message had no data portion. By the use of settings in TPQUEDEF-REC the system is informed how the call to TPDEQUEUE is to be handled.
There are some important arguments to control the operation of TPDEQUEUE(3cbl). Let's look at some of them.
QSPACE-NAME identifies a queue space previously created by the administrator. When a server is defined in the SERVERS section of the configuration file, the service names it offers are aliases for the actual queue space name (which is specified as part of the OPENINFO parameter in the GROUPS section). For example, when your application uses the server TMQUEUE, the value pointed at by QSPACE-NAME is the name of a service advertised by TMQUEUE. If no service aliases are defined, the default service is the same as the server name, TMQUEUE. In this case the configuration file can include the following.
TMQUEUE
SRVGRP = QUE1 SRVID = 1
GRACE = 0 RESTART = Y CONV = N
CLOPT = "-A"
or
CLOPT = "-s TMQUEUE"
The entry for server group QUE1 has an OPENINFO parameter that specifies the resource manager, the pathname of the device and the queue space name. The QSPACE-NAME argument in a client program can then look like this:
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 TPSTATUS-REC.
COPY TPSTATUS.
01 USER-DATA-REC PIC X(100).
*
*
*
MOVE LOW-VALUES TO TPQUEDEF-REC.
MOVE "TMQUEUE" TO QSPACE-NAME IN TPQUEDEF-REC.
MOVE "REPLYQ" TO QNAME IN TPQUEDEF-REC.
SET TPTRAN IN TPQUEDEF-REC TO TRUE.
SET TPBLOCK IN TPQUEDEF-REC TO TRUE.
SET TPTIME IN TPQUEDEF-REC TO TRUE.
SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.
MOVE LOW-VALUES TO TPTYPE-REC.
MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.
MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.
CALL "TPDEQUEUE" USING
TPQUEDEF-REC
TPTYPE-REC
USER-DATA-REC
TPSTATUS-REC.
The example shown on the reference page for TMQUEUE(5) shows how alias service names can be included when the server is built and specified in the configuration file. The example in Appendix A, "A Sample Application," also specifies an alias service name.
Reply queue names in a queue space need to be agreed upon within the application. The administrator creates a reply queue (and often an error queue) in the same manner a message queue is created. QNAME contains the name.
The arguments have a different flavor than they do on TPENQUEUE. DATA-REC is where the system is to place the message being dequeued.
It is an error for LEN to be 0 on input. When TPDEQUEUE returns, LEN contains the length of the data retrieved. If it is 0, it means that the reply had no data portion. This can be a legitimate and successful reply in some applications; receiving even a 0 length reply can be used to show successful processing of the enqueued request. If you wish to know whether the record has changed from before the call to TPDEQUEUE, save the prior length and compare it to LEN. If the reply is larger than LEN, then DATA-REC will contain only as many bytes as will fit. The remainder are discarded and TPDEQUEUE fails with TPTRUNCATE.
Settings in TPQUEDEF-REC are used to tell the BEA TUXEDO system how the TPDEQUEUE call is handled; the following are valid settings:
TPNOTRAN
TPNOTRAN or TPTRAN must be set.
TPTRAN
TPNOTRAN or TPTRAN must be set.
TPNOBLOCK
TP-STATUS set to TPEBLOCK. This blocking condition does not include blocking on the queue itself if the TPQWAIT setting is specified. Either TPNOBLOCK or TPBLOCK must be set.
TPBLOCK
TPETIME). This blocking condition does not include blocking on the queue itself if the TPQWAIT setting is specified. Either TPNOBLOCK or TPBLOCK must be set.
TPNOTIME
TPNOTIME or TPTIME must be set.
TPTIME
TPNOTIME or TPTIME must be set.
TPNOCHANGE
DATA-REC is not allowed to change. That is, the type and sub-type of the received record must match the type and subtype of the record DATA-REC. Either TPNOCHANGE or TPCHANGE must be set.
TPCHANGE
DATA-REC, then DATA-REC's record type changes to the received record's type so long as the receiver recognizes the incoming record type. That is, the type and sub-type of the received record must match the type and sub-type of the record DATA-REC. Either TPNOCHANGE or TPCHANGE must be set.
TPSIGRSTRT
TPSIGRSTRT or TPNOSIGRSTRT must be set.
TPNOSIGRSTRT
TP-STATUS to TPEGOTSIG. Either TPSIGRSTRT or TPNOSIGRSTRT must be set.
The first argument to TPDEQUEUE is a structure TPQUEDEF-REC. The TPQUEDEF-REC structure has members that are used by the application and by the BEA TUXEDO system to pass parameters in both directions between application programs and the queued message facility. The client that calls TPDEQUEUE uses settings to mark members the application wants the system to fill in. As described earlier, the structure is also used by TPENQUEUE; some of the members only apply to that function. The entire structure is shown in Listing 4-1.
On input to TPDEQUEUE, the following elements may be set in the TPQUEDEF structure.
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPNOBLOCK VALUE 0.
88 TPBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPNOTRAN VALUE 0.
88 TPTRAN VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPNOTIME VALUE 0.
88 TPTIME VALUE 1.
05 TPSIGRSTRT-FLAG PIC S9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPNOCHANGE-FLAG PIC S9(9) COMP-5.
88 TPNOCHANGE VALUE 0.
88 TPCHANGE VALUE 1.
05 TPQUE-ORDER-FLAG PIC S9(9) COMP-5.
88 TPQDEFAULT VALUE 0.
88 TPQTOP VALUE 1.
88 TPQBEFOREMSGID VALUE 2.
05 TPQUE-TIME-FLAG PIC S9(9) COMP-5.
88 TPQNOTIME VALUE 0.
88 TPQTIME-ABS VALUE 1.
88 TPQTIME-REL VALUE 2.
05 TPQUE-PRIORITY-FLAG PIC S9(9) COMP-5.
88 TPQNOPRIORITY VALUE 0.
88 TPQPRIORITY VALUE 1.
05 TPQUE-CORRID-FLAG PIC S9(9) COMP-5.
88 TPQNOCORRID VALUE 0.
88 TPQCORRID VALUE 1.
05 TPQUE-REPLYQ-FLAG PIC S9(9) COMP-5.
88 TPQNOREPLYQ VALUE 0.
88 TPQREPLYQ VALUE 1.
05 TPQUE-FAILQ-FLAG PIC S9(9) COMP-5.
88 TPQNOFAILUREQ VALUE 0.
88 TPQFAILUREQ VALUE 1.
05 TPQUE-MSGID-FLAG PIC S9(9) COMP-5.
88 TPQNOMSGID VALUE 0.
88 TPQMSGID VALUE 1.
05 TPQUE-GETBY-FLAG PIC S9(9) COMP-5.
88 TPQGETNEXT VALUE 0.
88 TPQGETBYMSGID VALUE 1.
88 TPQGETBYCORRID VALUE 2.
05 TPQUE-WAIT-FLAG PIC S9(9) COMP-5.
88 TPQNOWAIT VALUE 0.
88 TPQWAIT VALUE 1.
05 MSGID PIC X(32).
05 CORRID PIC X(32).
05 QNAME PIC X(15).
05 QSPACE-NAME PIC X(15).
Following are valid settings on input to TPDEQUEUE.
TPNOstring
TPQGETBYMSGID
MSGID be dequeued. The message identifier would be one that was returned by a prior call to TPENQUEUE. This option cannot be used with the TPQWAIT setting.
TPQGETBYCORRID
CORRID be dequeued. The correlation identifier would be one that the application specified when enqueuing the message with TPENQUEUE. This option cannot be used with the TPQWAIT setting.
TPQWAIT
Following is a list of valid settings for the parameters controlling output information from TPDEQUEUE. If the setting is true when TPDEQUEUE is called, then the associated element (see Listing 4-1) in the structure is populated if available and the setting remains true. If the value is not available, the setting will not be true after TPDEQUEUE completes.
TPQPRIORITY
PRIORITY.
TPQMSGID
TPDEQUEUE was successful, the message identifier will be stored in MSGID.
TPQCORRID
TPDEQUEUE was successful and the message was queued with a correlation identifier, the value will be stored in CORRID. Any reply to a queue must have this correlation identifier.
TPQREPLYQ
REPLYQUEUE. Any reply to the message should go to the named reply queue within the same queue space as the request message.
TPQFAILUREQ
FAILUREQUEUE. Any failure message should go to the named failure queue within the same queue space as the request message.
If the call to TPDEQUEUE failed and TP-STATUS is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in DIAGNOSTIC. The valid settings for DIAGNOSTIC include those shown above for TPENQUEUE and the following additional codes.
QMENOMSG]
QMEINUSE]
When TPDEQUEUE is called with TPQWAIT set, the TMQUEUE server may be blocked waiting for a message to come onto the queue. The amount of time it is blocked can be controlled by the transaction timeout value set by the caller in TPBEGIN or by the -t option in the CLOPT parameter of the TMQUEUE server (if the transaction is started in the server). To avoid blocking TPENQUEUE calls that also use the TMQUEUE server, it may be desirable to configure two or more TMQUEUE servers (or MSSQ sets) offering different service names for the same queue space. It could be set up so that all enqueue and non-waiting dequeue operations use one set of TMQUEUE servers and all waiting dequeue operations use the second set.
In considering how best to handle errors in dequeuing it is helpful to differentiate between errors encountered by TMQFORWARD as it attempts to dequeue a message to forward to the requested service and errors that occur in the service that processes the request. This subject was discussed in Chapter 1, "Introduction and Overview of BEA TUXEDO System/Q," but is repeated here in the context of writing application programs.
By default, if a message is dequeued within a transaction and the transaction is rolled back, then the message ends up back on the queue and can be dequeued and executed again. It may be desirable to delay for a short period before retrying to dequeue and execute the message, allowing the transient problem to clear (for example, allowing for locks in a database to be released by another transaction). Normally, a limit on the number of retries is also useful to ensure that an application flaw doesn't cause significant waste of resources. When a queue is configured by the administrator, both a retry count and a delay period (in seconds) can be specified. A retry count of 0 implies that no retries are done. After the retry count is reached, the message is moved to an error queue that is configured by the administrator for the queue space. If the error queue is not configured, then messages that have reached the retry count are simply deleted. Messages on the error queue must be handled by the administrator who must work out a way of notifying the originator that meets the requirements of the application. This kind of handling is almost transparent to the originating program that put the message on the queue. There is a virtual guarantee that once a message is successfully enqueued it will be processed according to the parameters of TPENQUEUE and the attributes of the queue. Notification that a message has been moved to the error queue should be a rare occurrence in a system that has properly tuned its queue parameters.
A failure queue (normally, different from the queue space error queue) may be associated with each queued message. This queue is specified on the enqueuing call as the place to put any failure messages. The failure message for a particular request can be identified by an application-generated correlation identifier that is associated with the message when it is enqueued.
The default behavior of retrying until success (or a predefined limit) is quite appropriate when the failure is caused by a transient problem that is later resolved, allowing the message to be handled appropriately.
There are cases where the problem is not transient. For example, the queued message may request operating on an account that does not exist (and the application is such that it won't come into existence within a reasonable time period if at all). In this case, it is desirable not to waste any resources by trying again. If the application programmer or administrator determines that failures for a particular operation are never transient, then it is simply a matter of setting the retry count to zero, although this will require a mechanism to constantly clear the queue space error queue of these messages (for example, a background client that reads the queue periodically). More likely, it is the case that some problems will be transient (for example, database lock contention) and some problems will be permanent (for example, the account doesn't exist) for the same service.
In the case that the message is processed (dequeued and passed to the application via a TPCALL) by TMQFORWARD, there is no mechanism in the information returned by TPCALL to indicate whether a TPESVCFAIL error is caused by a transient or permanent problem.
As in the case where the application is handling the dequeuing, a simple solution is to return success for the service, that is, TPRETURN with TPSUCCESS, even though the operation failed. This allows the transaction to be committed and the message removed from the queue. If reply messages are being used, the information in the buffer returned from the service can indicate that the operation failed and the message will be enqueued on the reply queue. The APPL-CODE in the TPSVCRET-REC argument of TPRETURN can also be used to return application specific information.
In the case where the service fails and the transaction must be rolled back, it is not clear whether or not TMQFORWARD should execute a second transaction to remove the message from the queue without further processing. By default, TMQFORWARD will not delete a message for a service that fails. TMQFORWARD's transaction is rolled back and the message is restored to the queue. A command line option may be specified for TMQFORWARD that indicates that a message should be deleted from the queue if the service fails and a reply message is sent back with length greater than 0. The message is deleted in a second transaction. The queue must be configured with a delay time and retry count for this to work. If the message is associated with a failure queue, the reply data will be enqueued to the failure queue in the same transaction as the one in which the message is deleted from the queue.
If your application expects to receive replies to queued messages, here is a procedure you may want to follow:
TPSUCCESS on a logical failure and return an
explanatory code in the APPL-CODE in the TPSVCRET-REC argument of TPRETURN.
TPENQUEUE to put the message on the queue, set the following:
(Fill in the values for TPQCORRID TPQREPLYQ
TPQFAILUREQ TPQMSGIDCORRID, REPLYQUEUE and FAILUREQUEUE before issuing the call. On return from the call, save CORRID.)
TPDEQUEUE to check for a reply, specify the reply queue in QNAME
and set the following:
(Use the saved correlation identifier to populate TPQCORRID TPQREPLYQ
TPQFAILUREQ TPQMSGID
TPQGETBYCORRIDCORRID before issuing the call. If the call to TPDEQUEUE fails and sets TP-STATUS to TPEDIAGNOSTIC, then further information is available in the DIAGNOSTIC settings. If you receive the error code QMENOMSG, it means that no message was available for dequeuing.)
TPDEQUEUE. This time have QNAME point to the name of the
failure queue and set the following:
Populate TPQCORRID TPQREPLYQ
TPQFAILUREQ TPQMSGID
TPQGETBYCORRIDTPQCORRID with the correlation identifier. When the call returns, check LEN to see if data has been received and check APPL-RETURN-CODE to see if the service has returned a user return code.
Sequential processing of messages can be achieved by having one service enqueue a message for the next service in the chain before its transaction is committed. The originating process can track the progress of the sequence with a series of TPDEQUEUE calls to the reply_queue, if each member uses the same correlation-ID and returns a 0 length reply.
Alternatively, word of the successful completion of the entire sequence can be returned to the originator by using unsolicited notification. To make sure that the last transaction in the sequence ended with a TPCOMMIT, a job step can be added that calls TPNOTIFY using the client identifier that is carried in the TPQUEDEF-REC structure. The originating client must have called TPSETUNSOL to name the unsolicited message handler being used.
In all of the foregoing discussion of enqueuing and dequeuing messages there has been an implicit assumption that the queues were being used as an alternative form of request/response processing. It may have occurred to you that the message itself does not have to be a service request and you would be correct. The queued message facility can be used equally as effectively to transfer data from one process to another.
If it suits your application to use BEA TUXEDO System/Q for this purpose, have the administrator create a separate queue and code your own receiving program for dequeuing messages from that queue.