The FGET (free message GET) call enables you to read an asynchronous message or message segment into the message area from the message queue allocated to the service.
The FGET call is only permitted in the first program unit run and processing step of an asynchronous service. Each message can only be read once. Each message segment must be read with its own FGET. The message (message segment) can be read again following an RSET call.
The format of the FGET call is described in detail below. For further information on message queuing refer to section "Message Queuing (asynchronous processing)".
Setting the KDCS parameter area (1st parameter)
The table below shows the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCS parameter area | ||
|---|---|---|---|
KCOP | KCLA | KCMF/kcfn | |
Read asynchronous message | "FGET" | Length | Format identifier / blanks / name of abstract syntax / edit profile (only on BS2000 systems) |
Setting the 2nd parameter
Here you have to supply the address of the message area into which openUTM is to read the message.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"FGET" | |
Length in bytes | |
Format identifier / blanks / name of abstract syntax / name of edit profile (only on BS2000 systems) | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_FGET | (nb,kcla,kcfn) |
openUTM return information | |
|---|---|
Contents | |
Data | |
Field name in the KB return area | |
Actual length | |
Return code | |
Internal return code | |
Format identifier/blanks | |
Redelivery counter | |
For the FGET call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, enter the FGET operation code.
KCLA
In the KCLA field, specify the length in which the message is to be read. This length must not exceed the message area into which the message is to be read. Length zero means no receiving of messages. Any existing messages are lost.
KCMF/kcfn
In the KCMF/kcfn field, enter the format of the message to be read:
in line mode: blanks
or on BS2000 systems: name of the edit profile (returned in the KCRMF/kcrfn field in the case of INIT). This name starts with a blank.
in format mode on BS2000 systems: format identifier of the expected (partial) format. This is returned in the KCRMF/kcrfn field in the case of INIT or a preceding FGET call.
for a message from a program unit of the same application or from an LU6.1 partner: irrelevant.
in messages to an OSI TP partner:
name of the abstract syntax of the message.
This name was returned in the KCRMF/kcrfn field in the preceding INIT call. Here, blanks represent the abstract UDT syntax encoded in accordance with BER (Basic Encoding Rules); only in this case does openUTM transfer the message to the program unit decoded.
If you enter a value other than blanks, openUTM transfers the message to the program unit in encoded format (i.e. in the transfer syntax corresponding to this abstract syntax) and the program unit itself must convert the message into the local representation. This is possible, for example, using an ASN.1 compiler.
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area
2nd parameter
The address of the message area into which openUTM is to read the message. You enter the address of the message area even if you have entered the length 0 in KCLM.
Macro names
The use of C/C++ calls is described in detail in the section "C/C++ macro interface".
openUTM returns:
Message area
in the specified message area, the message (segment) in its actual or at most in its desired length.
KCRLM
in the KCRLM field, the actual length of the message (segment), possibly deviating from the length requested in the KCLA of the parameter area.
KCRCCC
in the KCRCCC field the KDCS return code (see next page).
KCRCDC
In the KCRCDC field, the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).
KCRMF/kcrfn
In the KCRMF/kcrfn field:
After reading in line mode: blanks
or on BS2000 systems: name of the edit profile of the last output message.
After reading a partner service:
name of the format identifier or abstract syntax of the next message (segment).
Only on BS2000 systems:
After reading an entire format: ID of most recently read format (always identical to ID of last output format).
After reading a partial format: Identifier of the next format with input data.
After reading final partial format: ID of most recently read partial format. In this case KCRMF = KCMF (or: kcrfn=kcfn).
KCRRC
in the KCRRC field, the redelivery counter of the message read. This contains the number of redeliveries of the FGET message after abnormal termination of the asynchronous services in the first transaction.
Sender information, etc. is located in the KB header (entered by openUTM during INIT).
KDCS return codes in the KCRCCC field for the FGET call
The following codes can be analyzed in the program:
000 | Operation carried out. |
01Z | Length conflict: KCLA<KCRLM; message was truncated. |
03Z | With partial formats: Entry message from a OSI TP partner: |
05Z | With individual formats: format in screen display different from format entered in KCMF/kcfn. Only on BS2000 systems: |
10Z | Message or all message segments already completely read. |
Additional error codes to be found in the dump:
71Z | Function called in a follow-up program unit or following a PGWT call of an asynchronous service or in a dialog service or still no INIT issued in program unit run. |
73Z | Length entry in KCLA negative or invalid. |
77Z | The message area is missing or cannot be accessed in the specified length. |
Features of the FGET call
The actual message length is returned in the KCRLM field. The following holds:
When KCRLM <= KCLA, only KCRLM characters (bytes) are transferred into the message area. The contents of the remainder of the message area are undefined.
When KCRLM > KCLA, only KCLA characters are transferred into the message area. The remaining bytes (KCRLM-KCLA) are lost. They can no longer be read with a subsequent FGET.
The description of the MGET call presents an example explaining how openUTM reacts in case of length conflicts
A program unit can also receive asynchronous messages of length 0 when, for example,
a function key was pressed, but no message was allocated
a transaction code was sent without further data
if a program in the same application sent a background job with a message of length 0.
TAC input from the terminal or a transport system application:
When an asynchronous TAC is entered in line mode and a format ID is entered in KCMF/kcfn, return code KCRCCC=05Z is not set (as with MGET), but rather KCRCCC=000, assuming the call is otherwise error-free.
When partial formats are input, each partial format must be read using a separate FGET.
If a message is input together with an asynchronous TAC, the TAC is separated from the message: the TAC is not read into the message area, but is available in the KB header after INIT.
openUTM does not convert from lowercase to uppercase letters.
Only on BS2000 systems: However, conversion is possible using edit profiles.
The number of redeliveries is returned in the KCRRC field. A message is always redelivered if an asynchronous service was terminated abnormally in the first transaction. 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.
Saving faulty messages into the dead letter queue:
If an error occurs, asynchronous messages to transaction codes can be saved into the global dead letter queue as a last fallback stage. The TAC must be generated with DEAD-LETTER-Q=YES for this. If the asynchronous process terminates abnormally without successful termination of a transaction, the FGET message is placed in the dead letter queue if it cannot be redelivered (see redelivery) and no negative acknowledgement job was defined. As soon as an asynchronous process has reached a save point, neither redelivery nor saving the FGET message into the dead letter queue is possible since the message is taken to have been successfully processed.
When a message is saved into the dead letter queue, the number of redeliveries for this message is rolled back to zero if necessary.
Each message segment sent with FPUT NT must be read using a separate FGET.