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.
When a 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.
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 name of the default service is the same as the server name,
TMQUEUE. In this case the configuration file might include the following:
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 then looks like this:
DATA-REC contains the message to be processed.
LEN in
TPTYPE-REC gives the length of the message. Some Oracle 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.
Settings in TPQUEDEF-REC are used to tell the Oracle Tuxedo system how the
TPENQUEUE() call is handled; the following are valid settings:
The message is not enqueued if a blocking condition exists. If TPNOBLOCK is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and
tperrno(5) is set to
TPEBLOCK. If
TPNOBLOCK is set and a blocking condition exists because the target queue is opened
exclusively by another application, the call fails,
tperrno() is set to
TPEDIAGNOSTIC, and the diagnostic field of the
TPQCTL structure is set to
QMESHARE. In the latter case, the other application, which is based on an Oracle product other than the Oracle Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). Either
TPNOBLOCK or
TPBLOCK must be set.
When TPBLOCK is set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
The TPQUEDEF-REC structure has members that are used by the application and by the Oracle 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.
If this value is set, the message is made available after the time specified by DEQ-TIME.
DEQ-TIME is an absolute time value as generated by
time(2) or
mktime(3C) (the number of seconds since 00:00:00 Universal Coordinated Time—UTC, January 1, 1970). Set
TPQNOTIME if neither an absolute or relative time value is set.
TPQTIME-ABS,
TPQTIME-REL, or
TPQNOTIME must be set. The absolute time is determined by the clock on the machine where the queue manager process resides.
If this value is set, the correlation identifier value specified in CORRID is available when a message is dequeued with
TPDEQUEUE(). This identifier accompanies any reply or failure message that is queued so that an application can correlate a reply with a particular request. Set
TPQNOCORRID if a correlation identifier is not available.
If this value is set, a reply queue named in REPLYQUEUE is associated with the queued message. Any reply to the message is queued to the named queue within the same queue space as the request message. Set
TPQNOREPLYQ if a reply queue name is not available.
If this value is set, a failure queue named in FAILUREQUEUE is associated with the queued message. If (1) the enqueued message is processed by
TMQFORWARD(), (2)
TMQFORWARD was started with the
-d option, and (3) the service fails and returns a non-NULL reply, a failure message consisting of the reply and its associated
tpurcode is enqueued to the named queue within the same queue space as the original request message. Set
TPQNOFAILUREQ if a failure queue name is not available.
If TPQDELIVERYQOS is set, the flags specified by
TPQUEQOS-DELIVERY-FLAG control the quality of service for message delivery. One of the following mutually exclusive flags must be set:
TPQQOSDELIVERYDEFAULTPERSIST,
TPQQOSDELIVERYPERSISTENT, or
TPQQOSDELIVERYNONPERSISTENT. If
TPQDELIVERYQOS is not set,
TPQNODELIVERYQOS must be set. When
TPQNODELIVERYQOS is set, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If TPQREPLYQOS is set, the flags specified by
TPQUEQOS-REPLY-FLAG control the quality of service for reply message delivery for any reply. One of the following mutually exclusive flags must be set:
TPQQOSREPLYDEFAULTPERSIST,
TPQQOSREPLYPERSISTENT, or
TPQQOSREPLYNONPERSISTENT. The
TPQREPLYQOS flag is used when a reply is returned from messages processed by
TMQFORWARD. Applications not using
TMQFORWARD to invoke services may use the
TPQREPLYQOS flag as a hint for their own reply mechanism.
If TPQREPLYQOS is not set,
TPQNOREPLYQOS must be set. When
TPQNOREPLYQOS is set, the default delivery policy of the
REPLYQUEUE queue dictates the delivery quality of service for any reply. Note that the default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.
The valid TPQUEQOS-DELIVERY-FLAG and
TPQUEQOS-REPLY-FLAG flags are:
Additionally, the APPL-RETURN-CODE member of
TPQUEDEF-REC can be set with a user-return code. This value is returned to the application that calls
TPDEQUEUE() to dequeue the message.
As output from TPENQUEUE(), the following may be set in the
TPQUEDEF-REC structure:
The following is a valid setting in TPQUEDEF-REC controlling output information from
TPENQUEUE(). If this setting is true when
TPENQUEUE() is called, the Oracle Tuxedo /Q server
TMQUEUE(5) populates the associated element in the record with a message identifier. If this setting is not true when
TPENQUEUE() is called,
TMQUEUE() does
not populate the associated element in the record with a message identifier.
If this value is set and the call to TPENQUEUE() is successful, the message identifier is stored in
MSGID. The entire 32 bytes of the message identifier value are significant, so the value stored in
MSGID is completely initialized (for example, padded with null characters). The actual padding character used for initialization varies between releases of the Oracle Tuxedo /Q component. If
TPQNOMSGID is set, the message identifier is not available.
If the call to TPENQUEUE() fails and
TP-STATUS is set to
TPEDIAGNOSTIC, a value indicating the reason for failure is returned in
DIAGNOSTIC. The following are the possible values:
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 the override 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.
You can set a value in PRIORITY to specify the priority for the message. The value must be in the range 1 to 100; the higher the number, the higher the priority, unlike values specified with the UNIX
nice command. If
PRIORITY was not one of the queue ordering parameters, setting a priority here has no effect on the dequeuing order. The priority value is retained however, so that it can be inspected when the message is dequeued.
You can specify in DEQ-TIME either an absolute time or a time relative to the completion of the enqueuing operation at which the message is made available. You set either
TPQTIME-ABS or
TPQTIME-REL to indicate how the value should be treated. A queue may be created with
time as a queue-ordering criterion, in which case messages are ordered by the message availability time.
If the 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 outside of the caller’s 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 timeout, the caller is left in doubt about whether the failure occurred before or after the message was enqueued.
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 queue 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.
QSPACE-NAME identifies a queue space previously created by the administrator. When the
TMQUEUE 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 name of the default service is the same as that of the server,
TMQUEUE. In this case the configuration file may include the following:
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 then looks like the following:
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 length prior to the call to
TPDEQUEUE() and compare it to
LEN after the call completes. 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 Oracle Tuxedo system how the
TPDEQUEUE() call is handled; the following are valid settings:
The message is not dequeued if a blocking condition exists. If TPNOBLOCK is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and
tperrno(5) is set to
TPEBLOCK. If
TPNOBLOCK is set and a blocking condition exists because the target queue is opened
exclusively by another application, the call fails,
tperrno() is set to
TPEDIAGNOSTIC, and the diagnostic field of the
TPQCTL structure is set to
QMESHARE. In the latter case, the other application, which is based on an Oracle product other than the Oracle Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). Either
TPNOBLOCK or
TPBLOCK must be set.
When TPBLOCK is set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). This blocking condition does not include blocking on the queue itself if the
TPQWAIT setting is specified. Either
TPNOBLOCK or
TPBLOCK must be set.
If this value is set, the record type of DATA-REC is not allowed to change. That is, the type and subtype of the received record must match the type and subtype of the record
DATA-REC. Either
TPNOCHANGE or
TPCHANGE must be set.
The first argument to TPDEQUEUE() is the structure
TPQUEDEF-REC. The
TPQUEDEF-REC structure has members that are used by the application and by the Oracle 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
“The TPQUEDEF-REC Structure” on page 4‑6.
As input to TPDEQUEUE(), the following elements may be set in the
TPQUEDEF structure:
Setting this value requests that the message identified by MSGID be dequeued. The message identifier is returned by a prior call to
TPENQUEUE(). Note that the message identifier is not valid if the message has moved from one queue to another. Note also that the entire 32 bytes of the message identifier value are significant, so the value identified by
MSGID must be completely initialized (for example, padded with spaces).
Setting this value requests that the message identified by CORRID be dequeued. The correlation identifier is specified by the application when enqueuing the message with
TPENQUEUE(). Note that the entire 32 bytes of the correlation identifier value are significant, so the value identified by
CORRID must be completely initialized (for example, padded with spaces).
Note that each TPDEQUEUE() request specifying the
TPQWAIT control parameter requires that a queue manager (
TMQUEUE) action object be available if a message satisfying the condition is not immediately available. If one is not available, the
TPDEQUEUE() request fails. The number of available queue manager actions are specified when a queue space is created or modified. When a waiting dequeue request completes, the associated action object associated is made available for another request.
If TPQPEEK is set, the specified message is read but not removed from the queue. The
TPNOTRAN flag must be set. It is not possible to read messages enqueued or dequeued within a transaction before the transaction completes.
When a thread is non-destructively dequeuing a message using TPQPEEK, the message may not be seen by other non-blocking dequeuers for the brief time the system is processing the non-destructive dequeue request. This includes dequeuers using specific selection criteria (such as message identifier and correlation identifier) that are looking for the message currently being non-destructively dequeued.
On output from TPDEQUEUE(), the following elements may be set in
TPQUEDEF-REC:
The following is a list of valid settings in TPQUEDEF-REC controlling output information from
TPDEQUEUE(). For any of these settings, if the setting is true when
TPDEQUEUE() is called, the associated element in the record is populated with the value provided when the message was queued, and the setting remains true. If the value is not available (that is, no value was provided when the message was queued) or the setting is not true when
TPDEQUEUE() is called,
TPDEQUEUE() completes with the setting not true.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with an explicit priority, then the priority is stored in
PRIORITY. The priority is in the range 1 to 100, inclusive, and the higher the number, the higher the priority (that is, a message with a higher number is dequeued before a message with a lower number). If
TPQNOPRIORITY is set, the priority is not available.
If this value is set and the call to TPDEQUEUE() is successful, the message identifier is stored in
MSGID. The entire 32 bytes of the message identifier value are significant. If
TPQNOMSGID is set, the message identifier is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a correlation identifier, then the correlation identifier is stored in
CORRID. The entire 32 bytes of the correlation identifier value are significant. Any Oracle Tuxedo /Q provided reply to a message has the correlation identifier of the original message. If
TPQNOCORRID is set, the correlation identifier is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a delivery quality of service, then the flag—
TPQQOSDELIVERYDEFAULTPERSIST,
TPQQOSDELIVERYPERSISTENT, or
TPQQOSDELIVERYNONPERSISTENT—specified by
TPQUEQOS-DELIVERY-FLAG indicates the delivery quality of service. If
TPQNODELIVERYQOS is set, the delivery quality of service is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a reply quality of service, then the flag—
TPQQOSREPLYDEFAULTPERSIST,
TPQQOSREPLYPERSISTENT, or
TPQQOSREPLYNONPERSISTENT—specified by
TPQUEQOS-REPLY-FLAG indicates the reply quality of service. If
TPQNOREPLYQOS is set, the reply quality of service is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a reply queue, then the name of the reply queue is stored in
REPLYQUEUE. Any reply to the message should go to the named reply queue within the same queue space as the request message. If
TPQNOREPLYQ is set, the reply queue is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a failure queue, then the name of the failure queue is stored in
FAILUREQUEUE. Any failure message should go to the named failure queue within the same queue space as the request message. If
TPQNOFAILUREQ is set, the failure queue is not available.
The remaining settings in TPQUEDEF-REC are set to the following values when
TPDEQUEUE() is called:
TPQNOTOP,
TPQNOBEFOREMSGID,
TPQNOTIME_ABS,
TPQNOTIME_REL,
TPQNOEXPTIME_ABS,
TPQNOEXPTIME_REL, and
TPQNOEXPTIME_NONE.
If the call to TPDEQUEUE() fails 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 for
TPENQUEUE() described in
“TPQUEDEF-REC Structure” on page 4‑6 (except for
QMENOSPACE and
QMERELEASE) and the following additional codes.
When TPDEQUEUE() is called with flags set to include
TPQWAIT, if a message is not immediately available, the
TMQUEUE server waits for the arrival, on the queue, of a message that matches the
TPDEQUEUE() request before
TPDEQUEUE() returns control to the caller. The
TMQUEUE process sets the waiting request aside and processes requests from other processes while waiting to satisfy the first request. If
TPQGETBYMSGID and/or
TPQGETBYCORRID are also specified, the server waits until a message with the indicated message identifier and/or correlation identifier becomes available on the queue. If neither of these flags is set, the server waits until any message is put onto the queue. The amount of time it waits is controlled by the caller’s transaction timeout, if the call is in transaction mode, or by the
-t option in the
CLOPT parameter of the
TMQUEUE server, if the call is not in transaction mode.
The TMQUEUE server can handle a number of waiting
TPDEQUEUE() requests at the same time, as long as action resources are available to handle the request. If there are not enough action resources configured for the queue space,
TPDEQUEUE() fails. If this happens on your system, increase the number of action resources for the queue space.
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 is enqueued to the failure queue in the same transaction as the one in which the message is deleted from the queue.
2.
|
When you call TPENQUEUE() to put the message on the queue, set the following:
|
(Fill in the values for CORRID,
REPLYQUEUE and
FAILUREQUEUE before issuing the call. On return from the call, save
CORRID.)
3.
|
When you call TPDEQUEUE() to check for a reply, specify the reply queue in QNAME and set the following:
|
(Use the saved correlation identifier to populate CORRID 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.)
4.
|
Set up another call to TPDEQUEUE(). This time have QNAME point to the name of the failure queue and set the following:
|
Populate TPQCORRID 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.