You use the MGET (message GET) call to read messages into the message area in a program unit run of a dialog service. In an asynchronous service, the MGET call is only permitted in follow-up program units or a follow-up processing step.
Messages may have the following origins:
a terminal
another application (via LU6.1 or OSI TP)
a transport system application
- a HTTP client
a UPIC client
a previous program unit run of a service of the same service
With message segments, a separate MGET call is necessary for each message segment.
In the case of socket USP applications and HTTP clients, a message segment can be read with several MGET calls. Using KCRLM and the return code it is possible to determine whether a message segment has been read in its entirety.
In case of HTTP client the first MGET reads the query string, if available. If the input message contains no query string, the first MGET reads the message body respectively the first part of the message body.
If the message originates from an OSI partner, it can be a message segment, an error message, a handshake request or a handshake confirmation.
If a function key was pressed, two MGET calls are required: the first provides the return code, the second the data.
Only terminals or UPIC clients may send function keys.
Setting the KDCS parameter area (1st parameter)
The table below shows the various options and the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCS parameter area | ||||
|---|---|---|---|---|---|
KCOP | KCOM | KCLA | KCRN | KCMF/kcfn | |
BS2000 systems: | "MGET" | — | Length | - | Format identifier |
Message in line mode | "MGET" | — | Length | - | Blanks / edit profile (only on BS2000 systems) |
Message from previous program unit of the same application | "MGET" | — | Length | — | Blanks |
Rollback message from a program unit | "MGET" | "NT" | Length | Rollback-ID | Blanks |
Dialog message from job-submitting service | "MGET" | — | Length | — | Format identifier / Blanks / Name of abstract syntax |
Dialog message from job-receiving service | "MGET" | "NT" | Length | Service ID | Format identifier / Blanks/ Name of abstract syntax |
Status information from job-receiving service | "MGET" | "NT" | 0 | Service ID | Blanks |
NT: message segment
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 |
"MGET" | |
"NT"/- | |
Length in bytes | |
Service ID / Rollback ID / - | |
Format identifier / blanks / edit profile (only on BS2000 systems) | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_MGET | (nb,kcla,kcfn) |
KDCS_MGETNT | (nb,kcla,kcrn,kcfn) |
openUTM return information | |
|---|---|
Contents | |
Data | |
Field name in KB return area | |
Screen function/0 | |
Actual length | |
Type of message | |
Service status | |
Transaction status | |
Return code | |
Internal return code | |
Format identifier / blanks / edit profile (only on BS2000 systems) | |
Service ID / Blanks | |
For the MGET call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, enter the FPUT operation code.
KCOM
In the KCOM field "NT" modifier (message segment), (need only be specified for messages from a job receiver and for rollback messages).
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 message is received. Any existing messages are lost). The actual length of the message (segment) is returned in the KCRLM field.
KCRN
In the KCRN field,
(need only be specified for messages from a job receiver and for rollback messages)
for messages from job-receiving services, the service ID of the job-receiving service
for rollback messages, the rollback ID of the rollback message.
KCMF/kcfn
In the KCMF/kcfn field
(irrelevant for messages from previous program unit runs of the same service)
for messages on BS2000 systems in format mode:format identifier
for messages in line mode:blanksalso possible on BS2000 systems: Edit profile
when reading rollback messages:blanks
Message from a UPIC client:format identifier that the UPIC client specified for sending
with distributed processing via LU6.1:format identifier specified by the partner application in KCMF/kcfn when issuing the MPUT call
for messages from OSI TP partners:Name of the abstract syntax of the message. This name was returned in the KCRMF/kcrfn field in the preceding INIT or MGET call.Here, blanks represent the abstract UDT syntax. In this case, BER is used as transfer syntax and openUTM decodes the message.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 must 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 desired length, if KCRCCC=03Z was not set. If the message was longer than specified in KCLA, the remainder will be lost.
Exception: the message originates from a socket USP application or an HTTP client. In this case, the return code 02Z is set, and the rest of the message (segment) can be obtained with the next MGET.
KCRDF
in the KCRDF field, for the first MGET of a job-receiving service with which communication was performed using the LU6.1 protocol, the value in the KCDF field of the associated MPUT call in the job-receiving service. In all other cases this field has the value zero.
KCRLM
in the KCRLM field, the actual length of the message (segment). If a smaller value was specified in KCLA, the message is returned with the length specified in KCLA. In the case of a socket USP applications or HTTP clients, the rest of the message can still be read (KCRCCC = 02Z); otherwise, the rest of the message is lost (KCRCCC = 01Z).
KCRLM=0 for empty messages and if KCRCCC=03Z.
Only on BS2000 systems: When using FHS, the value returned in KCRLM depends on the FHS start parameter KCRLM=.
KCRMGT
in the KCRMGT field, the data read by MGET:
"M"("message)a message. When using MGET for a partner that does not communicate via the OSI TP protocol, only the value "M" can be specified.
When using MGET for a partner that communicates via the OSI TP protocol the following output is also possible:
"C" (confirm)a positive handshake confirmation.
"E" (error)an error message or negative handshake confirmation.
"H" (handshake)a handshake request.
KCVGST/kcpcv_state
in the KCVGST/kcpcv_state field, the service state of the (partner) service, see "MGET Receive dialog message".
KCTAST/kcpta_state
in the KCTAST/kcpta_state field, the transaction state of the partner service, see "MGET Receive dialog message".
KCRCCC
in the KCRCCC field, the KDCS return code, see "MGET Receive dialog message".
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
for a message in line mode: blanks or - on BS2000 systems - name of the edit profile
for a message from a partner service:KCRMF/kcrfn contains the format identifier or the name of the abstract syntax of the next message (segment) which can be read by the service defined in the KCRPI field. After the MGET call for the last message (segment), this field contains the format identifier of the last message (segment).
Only on BS2000 systems:
after reading an entire format: identifier of this format. This is always identical to the identifier of the last output format.
after reading a partial format: identifier of the next partial format with input data. If there is no further partial format with input data, KCRMF/kcrfn contains the identifier of the most recently read partial format. In this case KCRMF=KCMF (kcrfn=kcfn).
KCRPI
in the KCRPI field
for a message from a job-receiving service:service ID of a job-receiving service for which message segments or status information is present which has not yet been read.
in all other cases: blanks.
Service status in the KCVGST/kcpcv_state field
Entry for dialogs without distributed processing:
"O" (open)
The local service is open.
Entries with distributed processing after a message from a partner service:
"C" (closed)
The job-receiving service has terminated (PEND FI)."D" (disconnected)
Communication with a job receiver was terminated as a result of a loss of connection (only with OSI TP)."E" (error)
Only when communicating via LU6.1:The job-receiving service was terminated using PEND ER or PEND FR."I" (inactive)
The job-receiving service is inactive, i.e. it could not be started since, for example, the transaction code was unknown or is locked or no association could be reserved for OSI TP."O" (open)
The partner service is open, you may send further messages to the partner service."P" (pending end dialogue)
This status can only occur in the case of heterogeneous links and for dialogs for which the Commit functionality has not been selected:The job-receiving service wants to end the communication. If the job-submitting service does not agree, it can continue the service using MPUT EM."R" (rollback)
Only when communicating via LU6.1:The job-receiving service was terminated with PEND RS."T" (timeout)
The job-receiving service has been or is being terminated incorrectly, since no answer has been received from the job-receiving service within the generated wait time or it has not been possible to seize a session within the generated wait time."Z" (error)
The job-receiving service has been terminated by the system using PEND ER. (e.g. KDCS call in a job-receiving service with error >= 70Z). The Z service status is also set if a program unit run was terminated with PEND ER, FR or RS in an OSI TP job-receiving service.
If you read a message which originated from a job-submitting service, the service status can only have the value “O”.
With the service statuses D, E, I, R, T and Z no message is passed, i.e. the KCRLM return length is 0.
Transaction status in the KCTAST/kcpta_state field
Entries for dialogs without distributed processing:
"O" (open)
The transaction in the local service is open."C" (closed)
Either start of service or after a synchronization point."R" (rollback)
A rollback message has been read.
Entries for distributed processing after a message from the partner service:
"C" (closed)
Only when communicating via LU6.1:The transaction is finished in the partner service. This situation occurs if PEND RE or PEND FI has occurred in the partner service and PEND RE is active in the local service."H" (heuristic hazard)
Only when communicating using the OSI TP protocol:The result of a transaction is undetermined since communication with at least one communication partner has been interrupted. The possibility that one of the communication partners involved in the last transaction has made a heuristic decision which conflicts with the actual result of the last transaction cannot be excluded."I" (inactive)
A job receiver transaction exists because, for example, the transaction code is unknown or no connection could be reserved during the generated waiting time."M" (mismatch)
It was not possible to synchronize the transaction in the remote service with the transaction in the local service. This may occur after a timeout or after termination and start of a UTM-F application.When communicating via the OSI TP protocol, this situation may occur if at least one of the communication partners involved in the last transaction has made a heuristic decision which conflicts with the actual result of the transaction."O" (open)
The transaction in the partner service is open."P" (prepare to commit)
The partner service has either initiated the end of transaction itself or is requesting the local service to initiate the end of transaction."R" (rollback)
The transaction in the partner service has been rolled back."U" (unknown)
Only possible when communicating via OSI TP without global transaction logging. The transaction status is unknown.
When you read a message from a job-submitting service, only the values "C", "O", "P" or "U" can occur.
KDCS return codes in the KCRCCC field for the MGET call
The following codes can be analyzed in the program:
000 | Operation carried out. |
01Z | Length conflict: KCLA < KCRLM; the message area is too short, the message (segment) has been truncated. |
02Z | In the case of messages from a socket USP application or an HTTP client: |
03Z | For partial formats: For distributed processing and messages from UPIC clients: No message (segment) is transferred to the message area; the KCRPI and KCRMF/kcrfn fields contain a new proposition for the next message (segment). |
05Z | For single formats: In line mode:
Only on BS2000 systems:
|
10Z | Message has already been completely read |
12Z | (Only possible in the job-submitting service) |
19Z | The function key has not been generated or the allocated special function is invalid. |
20Z...39Z |
Only on BS2000 systems:
|
Additional return codes can be found in the dump:
70Z | Operation cannot be performed by the system (system or generation error); see KCRCDC. |
71Z | An MGET call was entered in the first processing step of the first program unit run of an asynchronous service, or INIT is missing in this program unit run. |
72Z | Specification in KCOM is invalid. |
73Z | Length entry in KCLA is invalid. |
77Z | The message area is missing or cannot be accessed in the specified length. |
78Z | Only on BS2000 systems: |
Features of the MGET call
Reaction to length conflicts
The actual message (segment) length is returned in the KCRLM field.
When length conflicts occur, note the following: If KCRLM < KCLA only KCRLM characters (bytes) are moved to the message area. The contents of the rest of the message area are undefined. Only one message (possibly consisting of two or more message segments) can be read in a program unit. If the length entry in KCLA of the parameter area is shorter than the actual message (segment), the remainder (KCRLM-KCLA) is lost and can no longer be read with a subsequent MGET.
Exception: if, in the case of messages from a socket USP application or an HTTP client, the message area is too small (KCLA < KCRLM), the rest of the truncated message segment can be read by means of another MGET call.Example
Three message segments, each of 100 bytes, are to be read using MGET calls. The table below shows the effect of different specifications in the KCLA field.
User specification
UTM returns
Explanations
KCOP
KCLA
KCRLM
Transferred length in MA
KCRCCC
MGET
100
100
100
000
The message segment as received successfully
MGET
50
100
50
01Z
The message segment was longer than specified in KCLA, the remainder is lost.
MGET
150
100
100
000
The message segment was received successfully
MGET
100
000
000
10Z
No fourth message segment was present
Conversion of lower case letters
openUTM does not automatically convert lowercase letters into uppercase letters when MGET is called. However, you can perform this conversion by using the appropriate format generation.
On BS2000 systems you can also perform a conversion by using edit profiles.
Messages of length zero
Messages of length zero are, for example, possible in the following cases:
Only the transaction code (without any further data) was sent at the start of a service
In a follow-up program unit a message is to be read from the preceding program unit of the same service and MPUT was specified with length 0 in the previous program unit or no MPUT was issued.
A client program or a partner service has sent an empty message.
The terminal user pressed a function key without assigning a message,
Only on BS2000 systems: KDCSxx (01 <= xx <= 20) was entered (function key simulation).
Only on BS2000 systems: The terminal user has sent an empty message (DUE function with empty screen)
Removing a transaction code
If a transaction code was specified together with a message at service start and no function key was used, the following is removed from the message
the transaction code, including trailing blanks, if the entry was unformatted(MAX statement parameter LEADING-SPACES)
Only on BS2000 systems:
the first 8 characters of the message (transaction code) if the entry was formatted with *formats
the first 10 characters (attribute field plus TAC) if the entry was formatted with +formats
the first 8 characters of the message (transaction code) if the entry was formatted with +formats
the first eight (with *formats) or ten (with +formats) characters of the first message if the entry was formatted with partial formats.
The removal of the transaction code can be prevented in an INPUT exit.
If the MGET call is used in the BADTACS event service the invalid transaction code is not removed from the input message. The entire message is made available. This also applies if the invalid transaction code is allocated to a function key.
Receiving partial formats
Every partial format must be read with a separate MGET.Following INIT, openUTM supplies, in KCRMF/kcrfn, the name of the first returned partial format in which data were entered. This name must be specified in KCMF/kcfn when issuing MGET. MGET supplies, in KCRMF/kcrfn, the name of the next partial format together with input data, which must be specified in KCMF/kcfn with the following MGET. With the final partial format with input data, KCRMF/kcrfn again has the name specified in KCMF/kcfn, see also example. You recognize the last partial format by the identical entries in KCMF/kcfn and KCRMF/kcrfn or by the return code 10Z in the next MGET.
If no data was input in any of the partial formats, the first MGET call supplies KCRCCC=10Z, KCRLM=0, KCRMF=blanks in the return area.
If the name entered in KCMF/kcfn differs from the one previously supplied in KCRMF/kcrfn then
openUTM does not write data to the message area
openUTM sets KCRLM=0
openUTM sets the return code 03Z in KCRCCC
openUTM writes the ‘correct’ format name again in KCRMF/kcrfn.
Only on BS2000 systems: Note that the way in which partial formats are transferred also depends on the FHS start parameters, see FHS manual. If, for instance, no entry is made in any partial format, some FHS start parameters cause openUTM to return KCRCCC=10Z and KCRMF/kcrfn=blanks after the first MGET.
Example
The three partial formats *PART1, *PART2 and *PART3 are to be read using MGET calls; note the return information in KCMF.
User entries
UTM return info
Explanations
KCOP
KCMF/kcfn
KCRMF/kcrfn
KCRCCC
INIT
*PART1
000
MGET
*PART1
*PART2
000
Read 1st partial format
MGET
*PART2
*PART3
000
Read 2nd partial format
MGET
*PART3
*PART3
000
Read 3rd partial format
MGET
*PART3
*PART3
10Z
Message already completely read
You recognize the last partial format by the identical entries in KCMF/kcfn and KCRMF/kcrfn or by the return code 10Z in the next MGET.
Features of the MGET call with distributed processing
When communicating via the OSI TP protocol, the format identifier for the transfer of the name of the abstract syntax is used. Here, blanks represent the abstract syntax of UDT. In all cases in which the application program unit does not work with UDT, the conversion of the message from the local representation to transfer syntax or vice versa must be performed by the application itself - in accordance with the rules of the abstract syntax. This process is termed the encoding or decoding of a message. To do this, the application can use an ASN1 compiler.
openUTM carries out the encoding and decoding of messages in UDT format.
When communicating via the LU6.1 protocol, openUTM transfers the format identifier. However, it does not format the message: the partner applications exchange only net data. When using MPUT, you can specify any name in the KCMF/kcfn field. This name is indicated to the reading program unit in the KCRMF/kcrfn field after INIT or following a preceding MGET and must be specified in the KCMF/kcfn field when calling MGET.
The return codes for the function keys (19Z through 39Z) cannot occur with an MGET call in the job-receiving service, because the job-submitting service cannot forward any corresponding special functions to the job-receiving service.
In the KDCS return area the MGET call provides the service status and the transaction status of the partner service.
If you do not adhere to the bottom-up strategy (see "Programming rules and recommendations") when communicating via LU6.1, a service restart can nevertheless be initiated by sending a message from the job-submitting service to the job-receiving service. Then the follow-up program unit in the job-receiving service is started. This uses MGET to read the message from the last synchronization point and receives the service status "O" and the transaction status "C" from the job submitter. After the INIT call it recognizes from the service indicator KCKNZVG/kccv_status in the KB header that this is a service restart.
Particularities of the MGET call when communicating with a UPIC client
openUTM transfers the format identifier during communication, but it does not format the message: only net data is exchanged between the UPIC client and the application. When a message is sent, any name can be specified as the format identifier. This name is displayed in the reading program after the INIT or after a preceding MGET in the KCRMF/kcrfn field and must be specified for an MGET call in the KCRMF/kcfn field.
Particularities of the MGET call when communicating with a socket USP application or an HTTP client
A message segment from a socket USP application or an HTTP client can be read by means of several MGET calls. Using the return code it is possible to determine whether a message (segment) has been read. The return code 02Z indicates that a message segment has not yet been read in its entirety. By comparing KCLA and KCRLM you can determine how large the rest of the message segment is. The return code 000 indicates that the message (segment) has been read in its entirety and that the next MGET will read a new message (segment).
Features of a rollback message
A rollback message always originates from a program unit terminated with PEND RS. Following service restart, it is supplied to the program unit which was started as a follow-up program unit after the synchronization point. The rollback message must be read with the first MGET call. It enables the program unit to react appropriately and thus avoids repeated rollback of the transaction. The program unit recognizes a service restart from the service indicator which takes the value "R". It is available in the KCKNZVG/kccv_status field after the INIT call. The rollback message is deleted after processing in the case of a loss of connection or KDCOFF.
With the MPUT call, you specify in the KDCS parameter area, whether (KCDF = KCRESTRT) or not (KCDF contains binary zero) a screen restart is performed when the service is restarted. If no screen restart is requested, openUTM rolls back the transaction and immediately starts the program unit run specified at the last synchronization point. The rollback message can be read with MGET.
MGET call for reading status information from the job receiver
Status information takes the form of messages of length 0 which are internally created by openUTM. Their only purpose is to indicate the status of the job-receiving service when errors occur in distributed processing. The status information is read unformatted using MGET calls (blanks in KCMF/kcfn).
If it was necessary to roll back the distributed transaction then, when the service restarts, it is advisable to restart the program unit for which a message was present at the end of the last distributed transaction, or for which the next input from the terminal is intended. If a program unit is started in the job-submitting service, openUTM sends status information to this program, if necessary. Here you have to consider the following:
The status information relates to the job receivers which caused the distributed transaction to be rolled back and were or are subsequently being terminated.
If the input message at service restart is for the program unit, then the input message has to be read with the 1st MGET and the status information with the second MGET. If, however, the input message originates from the job-receiving service and is not sent by the job receiver, then you only receive the status information of the job receiving service.
If the input message at service restart is for the job-receiving service and if this service cannot be started within a generated wait time (e.g. because of loss of connection), openUTM starts the follow-up program unit in the job-submitting service instead and sends the job-submitting service status information which has to be read with the first MGET.
If, after service restart of the job-submitting service, a job-receiving service is addressed again and if an error reoccurs, then the job-submitting service can be rolled back several times to the same synchronization point. Since the status information is retained from the preceding rollback, you may receive two or more bits of status information. In this case you obtain with each MGET the service ID of a subsequent service for which there is status information.
There may be status information available from different job-receiving services. This status information has to be read in the order suggested by openUTM (KCRPI).
"Substitute messages" are received with distributed processing via OSI TP, even if there is no service restart. If global transaction logging is not active, the transaction in the job-submitting service is not rolled back if an error occurs in the job-receiving service (e.g. timeout).If global transaction logging is active, the transaction in the job-submitting service is not rolled back only if no distributed transaction with the job receiver is open, e.g. if the timer for the association allocation has expired.
Special KDCS functions (BS2000 systems)
The KDCS interface provides "special KDCS functions" as a particular way of entering data at the terminal. The terminal user activates these functions by entering the string (KDCSxx) xx= 01,...,20 when UTM expects to receive input for a follow-up program unit run. A maximum of 20 special KDCS functions are therefore possible. The special KDCS functions are intended to be replacement inputs for terminals that do not have the appropriate keys.