PURPOSE

TPENQUEUE - routine to enqueue a message

SYNOPSIS


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.

DESCRIPTION

TPENQUEUE stores a message on the queue named by QNAME in the QSPACE-NAME queue space. A queue space is a collection of queues, one of which must be QNAME.

When the message is intended for a System/T server, the QNAME matches the name of a service provided by a server. The system provided server, TMQFORWARD(5), provides a default mechanism for dequeuing messages from the queue and forwarding them to servers that provide a service matching the queue name. If the originator expected a reply, then the reply to the forwarded service request is stored on the originator's (stable) queue. The originator will dequeue the reply message at a subsequent time. Queues can also be used for a reliable message transfer mechanism between any pair of System/T processes (clients and/or servers). In this case, the queue name does not match a service name but some agreed upon title for transferring the message.

The data portion of a message is specified by DATA-REC and LEN in TPTYPE-REC specifies how much of DATA-REC to enqueue. Note that if DATA-REC is a record of a type that does not require a length to be specified, then LEN is ignored (and may be 0). If REC-TYPE in TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and a message is enqueued with no data portion. The REC-TYPE and SUB-TYPE, both in TPTYPE-REC, must match one of the REC-TYPEs and SUB-TYPEs recognized by QSPACE-NAME.

The message is queued at the priority defined for QSPACE-NAME unless overridden by a previous call to TPSPRIO(3cbl).

If the caller is within a transaction and TPTRAN is set, the message is queued in transaction mode. This has the effect that if TPENQUEUE returns successfully and the caller's transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. If the caller's transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be deleted from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.

The message is not queued in transaction mode if either the caller is not in transaction mode, or TPNOTRAN is set. In this case, the queued message is stored on the queue in a separate transaction. Once TPENQUEUE returns successfully, the submitted message is guaranteed to be available. If a communication error or a timeout occurs (either transaction or blocking timeout), the application will not know whether or not the message was successfully stored on the queue.

The order in which messages are placed on the queue is controlled by the application via TPQUEDEF-REC as described below; the default queue ordering is set when the queue is created.

F:Following is a list of valid settings in TPQUEDEF-REC.

TPNOTRAN: If the caller is in transaction mode and this setting is used, then the message is not enqueued within the same transaction as the caller. A caller in transaction mode that sets this to true is still subject to the transaction timeout (and no other). If message enqueuing fails that was invoked with this setting, the caller's transaction is not affected. Either TPNOTRAN or TPTRAN must be set.
TPTRAN: If the caller is in transaction mode and this setting is used, then the message is enqueued within the same transaction as the caller. The setting is ignored if the caller is not in transaction mode. Either TPNOTRAN or TPTRAN must be set.
TPNOBLOCK: The message is not enqueued if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Either TPNOBLOCK or TPBLOCK must be set.
TPBLOCK: When TPBLOCK is specified 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.
TPNOTIME: This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.
TPTIME: This setting signifies that the caller will receive blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME or TPTIME must be set.
TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is re-issued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.
TPNOSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is not restarted and the routine fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

Additional information about queuing the message can be specified via TPQUEDEF-REC. This information includes values to override the default queue ordering placing the message at the top of the queue or before an enqueued message; an absolute or relative time after which a queued message is made available; a correlation identifier that aids in correlating a reply or failure message with the queued message; the name of a queue to which a reply should be enqueued; and the name of a queue to which any failure message should be enqueued.

Control Parameter

TPQUEDEF-REC is used by the application program to pass and retrieve information associated with enqueuing the message. Settings are used to indicate what elements in the record are valid.

On input to TPENQUEUE, the following elements may be set in TPQUEDEF-REC:


   05 DEQ-TIME          PIC S9(9) COMP-5.
   05 PRIORITY          PIC S9(9) COMP-5.
   05 MSGID             PIC X(32).
   05 CORRID            PIC X(32).
   05 REPLYQUEUE        PIC X(15).
   05 FAILUREQUEUE      PIC X(15).
   05 APPL-RETURN-CODE  PIC S9(9) COMP-5.

The following values indicate what values are set in the TPQUEDEF-REC.

TPQTOP: Setting this value indicates that the queue ordering be overridden and the message placed at the top of the queue. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering. Set TPQDEFAULT to use default queue ordering. TPQTOP, TPQBEFOREMSGID, or TPQDEFAULT must be set.
TPQBEFOREMSGID: Setting this value indicates that the queue ordering be overridden and the message placed in the queue before the message identified by MSGID. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering. Set TPQDEFAULT to use default queue ordering. TPQTOP, TPQBEFOREMSGID, or TPQDEFAULT must be set.
TPQTIME-ABS: If set, the message is made available after the time specified by DEQ-TIME. DEQ-TIME is an absolute time value as generated by time() or mktime() (the number of seconds since 00:00:00 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.
TPQTIME-REL: If set, the message is made available after a time relative to the completion of the queuing transaction. DEQ-TIME specifies the number of seconds to delay after the transaction completes before the submitted message should be available. Set TPQNOTIME if neither an absolute or relative time value is set. TPQTIME-ABS, TPQTIME-REL, or TPQNOTIME must be set.
TPQPRIORITY: If set, the priority at which the message should be enqueued is stored in PRIORITY. The priority must be in the range 1 to 100, inclusive. 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). Set TPQNOPRIORITY if a priority value is not available.
TPQCORRID: If set, the correlation identifier value specified in CORRID is available when a message is dequeued with TPDEQUEUE(3cbl). This identifier accompanies any reply or failure message that is queued such that an application can correlate a reply with a particular request. Set TPQNOCORRID if a correlation identifier is not available.
TPQREPLYQ: If set, a reply queue named in 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. Set TPQNOREPLYQ if a reply queue name is not available.
TPQFAILUREQ: If set, a failure queue named in FAILUREQUEUE is associated with the queued message. If a failure occurs when the enqueued message is subsequently dequeued, a failure message will go to the named queue within the same queue space as the original request message. Set TPQNOFAILUREQ if a failure queue name is not available.

Additionally, APPL-RETURN-CODE can be set with a user-return code. This value will be returned to the application that dequeues the message.

On output from TPENQUEUE, the following elements may be set in TPQUEDEF-REC:


   05 MSGID       PIC X(32).
   05 DIAGNOSTIC  PIC S9(9) COMP-5.

Following is a list of valid settings controlling output information from TPENQUEUE. If the setting is true when TPENQUEUE is called, the associated element in the record is populated if available and the setting remains true. If the value is not available, the setting will not be true after TPENQUEUE completes.

TPQMSGID: If set and the call to TPENQUEUE was successful, the message identifier will be stored in MSGID.
TPQNOMSGID is set if a message identifier is not available.

If the call to TPENQUEUE failed and TP-STATUS is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in DIAGNOSTIC. The possible values are defined below in the DIAGNOSTICS section.

RETURN VALUES

Upon successful completion, TPENQUEUE sets TP-STATUS to [TPOK].

ERRORS

Under the following conditions, TPENQUEUE fails and sets TP-STATUS to the following values (unless otherwise noted, failure does not affect the caller's transaction, if one exists):

[TPEINVAL]: Invalid arguments were given (for example, QSPACE-NAME is SPACES or settings in TPQUEDEF-REC are invalid).
[TPENOENT]: Cannot access the QSPACE-NAME because it is not available (the associated TMQUEUE(5) server is not available).
[TPETIME]: A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and both TPBLOCK and TPTIME were specified. If a transaction timeout occurred, then any attempts to call TPDEQUEUE or TPENQUEUE will fail with TPETIME until the transaction has been aborted.
[TPEBLOCK]: A blocking condition exists and TPBLOCK was set.
[TPGOTSIG]: A signal was received and TPNOSIGRSTRT was set.
[TPEPROTO]: TPENQUEUE was called in an improper context. There is no effect on the queue or the transaction.
[TPESYSTEM]: A System/T error has occurred. The exact nature of the error is written to a log file. There is no effect on the queue.
[TPEOS]: An operating system error has occurred. There is no effect on the queue.
[TPEDIAGNOSTIC]: Enqueuing a message from the specified queue failed. The reason for failure can be determined by the diagnostic value returned via TPQUEDEF-REC.

DIAGNOSTIC VALUES

The following diagnostic values are returned during the enqueuing of a message.

[QMEINVAL]: An invalid setting was specified.
[QMEBADRMID]: An invalid resource manager identifier was specified.
[QMENOTOPEN]: The resource manager is not currently open.
[QMETRAN]: The call was made with the TPNOTRAN setting and an error occurred trying to start a transaction in which to enqueue the message.
[QMEBADMSGID]: An invalid message identifier was specified.
[QMESYSTEM]: A system error has occurred. The exact nature of the error is written to a log file.
[QMEOS]: An operating system error has occurred.
[QMEABORTED]: The operation was aborted. When executed within a global transaction, the global transaction has been marked rollback-only. Otherwise, the queue manager aborted the operation.
[QMEPROTO]: An enqueue was done when the transaction state was not active.
[QMEBADQUEUE]: An invalid or deleted queue name was specified.
[QMENOSPACE]: There is no space on the queue for the message.