The call DGET (data GET) is used to read a message or message segment into the message area from a service-controlled queue. The following are service-controlled queues: TAC queues, USER queues and temporary queues
DGET provides several ways of reading the messages of a queue:
sequential processing (DGET FT/NT)
browsing (DGET BF/BN)
selective processing (DGET PF/PN)
With sequential or selective processing the message is read and then deleted from the queue, whereas with browsing the message remains in the queue. For the dead letter queue only browsing (read without delete) is allowed.
Each variant also allows several message segments to be read. The first segment is read using DGET FT/BF/PF (first). Subsequent segments are read within the same program unit run using DGET NT/BN/PN (next) without an intervening PGWT call.
In this way, as many message segments as have been sent with DPUT QT can be read. Each message segment sent with DPUT QT must be read using a separate DGET.
Message segments that have not been read are lost
when a new message is read with DGET FT,
when PGWT is called,
when the program unit run is terminated.
If the transaction is rolled back, processed messages are placed back in the queue (redelivery) and can then be read and processed again using DGET. The maximum number of redeliveries can be set in the generation (MAX REDELIVERY=). Once this limit has been reached, then, depending on the TAC statement’s DEAD-LETTER-Q parameter for the generation, the processed message is either deleted at the end of the transaction or is saved in the dead letter queue unless (in the case of message complexes) no negative acknowledgment job has been defined.
Messages from USER or temporary queues cannot be saved in the dead letter queue. They are therefore lost after the maximum number of redeliveries.
The format of the DGET call is described in detail in the following. You will find more information on the subject of message queues in section "Message Queuing (asynchronous processing)".
Setting the KDCS parameter area (1st parameter)
The following tables show the different options and the entries that have to be made in the KDCS parameter area.
Sequential processing | |||||||||
|---|---|---|---|---|---|---|---|---|---|
Function of the call | Entries in the KDCS parameter area | ||||||||
KCOP | KCOM | KCLA | KCMF/ kcfn | KCRN | KCQTYP | KCWTIME | KCQRC | KCDPID | |
Read new message or first message segment from queue | "DGET" | "FT" | Length | Blank | Queue name | Type of the queue | Wait time in seconds | 0 | Binary zero |
Read next message segment from queue | "DGET" | "NT" | Length | Blank | Queue name | Type of the queue | 0 | 0 | Binary zero |
Browsing | |||||||||
|---|---|---|---|---|---|---|---|---|---|
Function of the call | Entries in the KDCS parameter area | ||||||||
KCOP | KCOM | KCLA | KCGTM | KCRN | KCQTYP | KCWTIME | KCQRC | KCDPID | |
Read first message segment of the first or next message | "DGET" | "BF" | Length | Blank / creation time* | Queue name | Type of the queue | Wait time in seconds | -1 / redelivery counter | Blank / DPUT ID |
Read next message segment | "DGET" | "BN" | Length | Creation time* | Queue name | Type of the queue | 0 | 0 | DPUT ID |
Selective processing | |||||||||
|---|---|---|---|---|---|---|---|---|---|
Function of the call | Entries in the KDCS parameter area | ||||||||
KCOP | KCOM | KCLA | KCGTM | KCRN | KCQTYP | KCWTIME | KCQRC | KCDPID | |
Process first message segment of a specific message | "DGET" | "PF" | Length | Creation time* | Queue name | Type of the queue | 0 | 0 | DPUT-ID |
Process next message segment | "DGET" | "PN" | Length | Creation time* | Queue name | Type of the queue | 0 | 0 | DPUT-ID |
* Value in the KB return area KCRGTM of the preceding DGET BF
Setting the 2nd parameter
Here you have to make available the address of the message area to which openUTM is to read the message.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"DGET" | |
"FT"/"NT"/"BF"/"BN"/"PF"/"PN" | |
Length in bytes | |
Blanks | |
Name of the queue | |
"T"/"U"/"Q“ | |
Wait time in seconds/0 | |
0 / -1 / redelivery counter | |
Binary zero / blank / DPUT ID | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro call | |
Parameter | |
KDCS_DGETFT/KDCS_DGETNT | (nb,kcla,kcfn,kcrn,kcqtyp,kcwtime,kcfkt1,kcfkt2) |
KDCS_DGETBF/KDCS_DGETBN/KDCS_DGETPF/KDCS_DGETPN | (nb,kcla,kcrn,kcqtyp,kcwtime,kcqrc,kcgtm,kcdpid) |
Returns from openUTM | |
|---|---|
Contents | |
Data | |
Field name in KB return area | |
Actual length | |
KCRMF/kcrfn (DGET FT/NT only) | In the case of OSI TP partner: name of the abstract syntax |
KCRWVG (DGET FT only) | Number of services that are waiting |
KCRUS (DGET FT only) | UTM user ID of the message creator |
KCRQRC (DGET BF only) | Queue-specific redelivery counter |
KCRGTM (DGET BF only) | Creation time of the message read |
KCRDPID (DGET BF only) | DPUT ID of the message read |
KCRRC (DGET FT/BF/BN/PF only) | Redelivery counter of the message read |
Return code | |
Internal return code | |
In the KDCS parameter area you make the following entries for the DGET call:
KCOP
In the KCOP field, enter the DGET operation code.
KCOM
In the KCOM field, enter:
FT to process the first message segment of the first/new message
NT to process a further message segment of the first/new message
BF to read the first message segment of a message (browse without deleting)
BN to read a further message segment of the message (browse without deleting)
PF to process the first message segment of a specific message
PN to process a further message segment of a specific message
KCLA
In the KCLA field, specify the length of the message area to which the message is to be read. openUTM enters the length of the message segment that has actually been read in the KCRLM return field.
If the message and all its message segments is not to be read, you can specify the value 0 here for DGET FT. A subsequent DGET NT is then rejected with the return code 10Z.
KCMF/kcfn
KCGTM
The KCGTM or KCMF/kcfn field must be supplied as follows:
with blank for KCOM = FT/NT.
with blank for KCOM = BF if the first segment of the first message of the queue is to be read.
with the creation time of the message for KCOM = BN/PF/PN or if, for KCOM = BF, the next message is to be read. The creation time is returned in the KCRGTM field for the last DGET BF call.
KCRN
In the KCRN field, specify the name of the queue from which the message is to be read.
KCQTYP
In the KCQTYP field, specify the type of the queue:
T for a TAQ queue
U for a USER queue
Q for a temporary queue
KCWTIME
In the KCWTIME field, specify for DGET FT/BF the maximum number of seconds to be waited for the arrival of a message. If you specify 0, there will be no wait. If a wait time is specified, the subsequent program unit when PEND is specified must be assigned to a TAC class.
In the case of DGET NT/BN/PF/PN you must specify 0.
KCQRC
In the KCQRC field, specify for DGET BF the behavior after a transaction has been processed and rolled back. You can specify:
either the value returned in the KCRQRC field for the previous DGET BF call. This ensures that all messages of the queue are always read. A message that has already been processed may be read again after the transaction has been rolled back.
or the value -1 or the constant KDCS_NO_QRC. This may mean that not all messages of the queue are read.
You must specify 0 for DGET FT/NT/BN/PF/PN.
KCDPID
In the KCDPID field, specify:
binary zero for KCOM = FT/NT
blank if, for KCOM = BF, the first segment of the first message is to be read.
the DPUT ID for KCOM = PF/PN or if, for KCOM = BF/BN, the next message/message segment is to be read. The DPUT ID is returned in the KCRDPID field in the previous DGET BF call.
In the KDCS call you specify:
1st parameter
The address of the KDCS parameter area.
2nd parameter
The address of the message area to which openUTM is to read the message. You also specify the address of the message area when you enter a length of 0 in KCLA.
Macro names
The section "C/C++ macro interface" describes in detail how to use macro calls for C/C++.
openUTM returns:
Message area
In the specified message area the message segment in its actual length or, at most, the length of the message area.
KCRLM
In the KCRLM field the actual length of the message segment read providing a value> 0 was specified in KCLA.
For KCOM = FT/NT:
KCRMF/kcrfn
In the KCRMF field the name of the abstract syntax of the message segment read, provided the message originates from an OSI TP partner. Otherwise, it returns blanks.
KCRWVG
In the KCRWVG field the number of services that are already waiting for messages from the specified queue (the current service is not counted). KCRWVG is only supplied in the case of DGET FT.
KCRUS
In the KCRUS field the UTM user ID under which the DGET message was created. KCRUS is only supplied in the case of DGET FT.
For KCOM = BF:
KCRQRC
In the KCRQRC field, the queue-specific redelivery counter. This value is needed to supply the KCQRC field in the next DGET BF call.
KCRGTM
In the KCRGTM field, the creation time (binary) of the message read. This value is needed to supply the KCGTM field in the next DGET BF/BN/PF/PN call.
KCRDPID
In the KCRDPID field, the DPUT ID of the message read. This value is needed to supply the KCDPID field in the next DGET BF/BN/PF/PN call.
For KCOM = BF/BN/PF:
KCRRC
In the KCRRC field, the redelivery counter of the message read. This indicates how often the message was redelivered after the transaction was processed and rolled back. KCRRC can accept a maximum value of 254. If this value has been reached and if the number of redeliveries was not limited at generation, the value 254 is always returned after each additional DGET BF/BN/PF call.
For all variants:
KCRCCC
In the KCRCCC field the KDCS return code (see next page).
KCRCDC
In the KCRCDC field, the internal return code of openUTM (see openUTM manual ”Messages, Debugging and Diagnostics”).
KDCS return codes in the KCRCCC field for the DGET call
The following codes can be analyzed in the program:
000 | The operation was executed. |
01Z | Length conflict: KCLA < KCRLM; the message was truncated because the message segment is longer than the message area. |
04Z | Not all of the message segments were read at the previous DGET call; as a result of the current DGET FT/BF/PF call, the message segments that have not yet been read are lost. |
08Z | In the case of reading with waiting (KCWTIME>0): there is currently no message. In this case, no more DGET calls are permitted and the program unit must be terminated with PEND PA/PR or a wait point must be set with PGWT PR. As soon as a message arrives, the maximum wait time elapses or the queue is deleted, openUTM continues the service with the next program unit or openUTM continues the service after the PGWT PR. A follow-up program unit must be assigned to a TAC class. |
10Z | In the case of DGET NT/BN/PN: all the message segments of the message have been read. |
11Z | In the case of reading without waiting (KCWTIME=0): there is no message. |
40Z | In the case of DGET NT/BN/PN: the name or type of the specified queue does not match the previous DGET call of the current program unit run. Message segments may have been lost. No message has been read. In the case of DGET FT/PF: there is a generation error (the value MAX ...,RECBUF=... is too low). |
41Z | The DGET call is made in the first part of the sign-on, which is impermissible, or the previous DGET call produced the return code 08Z. This means it is necessary to wait, and no further DGET calls are permitted in this program unit. |
42Z | Possible causes:
|
43Z | The value in KCLA or KCWTIME is negative or invalid, or KCWTIME was not supplied with 0 for DGET NT/BN/PF/PN. |
44Z | The value in KCRN is invalid. This means one of the following things:
|
45Z | The value in KCMF/KCGTM is invalid:
|
47Z | The message area is missing, or the specified area address is invalid. |
49Z | Unused fields have a value that is not equal to binary zero. |
53Z | For DGET BF/PF: the value in KCDPID is not a valid DPUT ID or does not match the entries in KCRN and KCQTYP. For DGET BN/PN: the value in KCDPID or KCGTM does not match the corresponding value of the last DGET BF/PF call. |
An additional return code can be found in the dump:
71Z | An INIT has not yet been called in the program unit run. |
Features of the DGET call
Message length
The actual message length is returned in the KCRLM field. The following applies:
When KCRLM <= KCLA, only KCRLM characters (bytes) are transferred to the message area. The contents of the rest of the message area are undefined.
When KCRLM > KCLA, only KCLA characters are transferred to the message area. The rest (KCRLM - KCLA) are lost and can no longer be read by means of a subsequent DGET.
In the description of the MGET call you will find an example that indicates what openUTM does when there are length conflicts.
Browsing and processing
During browsing (DGET BF/BN) messages can be read in parallel by several services.
During message processing (DGET FT/NT/PF/PN) each message segment can be read once only. All message segments are deleted as soon as the transaction is terminated.
If a message is to be read (DGET BF/BN) and then processed with DGET PF, the DPUT ID and creation time returned for DGET BF must be specified in the DGET PF call.
Waiting for messages
In a dialog or asynchronous service DGET calls may be issued for different queues until it is necessary to wait for a message. In other words, if there is no message for a DGET call with waiting, this is indicated in the program by KCRCCC = 08Z (KCWTIME > 0).
The following KDCS calls should be programmed, depending on whether a wait is required for a message.
If a wait is required, the program unit must be terminated with PEND PA/PR so that it is possible to wait for the arrival of the message outside the program context, or a wait point must be set in the program unit using PGWT PR.
If no wait is required, the transaction must be rolled back (RSET, PEND RS or PGWT RB) or the service must be terminated with PEND ER/FR.
Otherwise, the error code 72Z is returned for the PEND call.
Continuing the program
If there is a wait for a DGET message, openUTM starts the next program unit or continues the program after the PGWT PR:
as soon as a message arrives
when the maximum wait time elapses or
when the queue is deleted
as soon as the processed message is redelivered (redelivery after transaction rollback), providing DGET FT is used for waiting or KCQRC was supplied with the value of the KB return field KCRQRC by the previous browse call.
In a) to c) above all services waiting for messages in the queue are continued (not just the first waiting service).
In the case of redelivery (d)) only the services that are able to read redelivered messages are continued. This ensures that arriving or redelivered messages can be read in parallel by the services.
If the program is continued in a PEND PA/PR follow-up program unit, it must be assigned to a TAC class. In other words, TAC classes must have been generated if this functionality is to be available. If they have not been, the PEND call is rejected with KCRCCC=74Z.
Redelivery
If a transaction is rolled back, any processed message is placed back in the queue and can be read again. The application must have been generated accordingly and the generated maximum number of redeliveries must not have been reached. For more information refer to the openUTM manual “Generating Applications”, REDELIVERY operand in the MAX statement.
In the KDCMSGTC service and in the KDCSGNTC sign-on service, the DGET call can only be used without specifying a wait time.
If the main message of a job complex is read, and a positive or negative confirmation job is defined for it (only possible in the case of TAC queues),
the positive confirmation job is started once the transaction containing the DGET call has been successfully terminated,
the negative confirmation job is started once the transaction containing the DGET call has been rolled back without delivery of the main message again, i.e. there is no redelivery.
If DGET is used to read from a queue for which there is data access control, the user ID under which the service is running and the LTERM partner must have access authorization (KSET) for the corresponding queue. Users are however always allowed to access their own USER queue. In the case of applications without explicitly generated user IDs, no data access control can be assigned for the queues assigned to the USERs.
Saving faulty messages into the dead letter queue
If an error occurs, messages from TAC queues can be saved into the global dead letter queue as a last fallback stage. The queue must be generated with DEAD-LETTER-Q=YES for this. A processed message is then placed into the dead letter queue when the transaction is rolled back, if it cannot be redelivered (see redelivery) and if no negative acknowledgement job was defined.
When a message is saved into the dead letter queue, the number of redeliveries for this message is rolled back to zero if necessary.