You use the MPUT (message put) call:
to send a dialog message (segment) to a client
to send a message (segment) to a subsequent program unit in the same dialog step or in a linked service
to send a rollback message for the service restart after PEND RS
to send the last screen output of a stacked service to the terminal
with distributed processing, in the job-submitting service, to send a message (segment) to a job-receiving service, or
with distributed processing, in the job-receiving service, to send a message (segment) to the job-submitting service
to request a processing confirmation from an OSI TP partner
to send a negative processing confirmation or an error message to an OSI TP partner.
to create an error message that is sent to a UPIC client, a socket USP application or an HTTP client in the event of abnormal termination of a service (system PEND ER) initiated by openUTM
In an asynchronous service, an MPUT message can only be sent to a job-receiving service or to a follow-up program unit.
The call cannot be used in an MSGTAC program.
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 | KCLM | KCRN | KCMF/kcfn | KCDF | |
BS2000 systems: | "MPUT" | "NT"/"NE" | Length | Blanks | Format identifier | Screen function |
BS2000 systems: | "MPUT" | "NT"/"NE" | Length | Blanks | Blanks / edit profile | Screen function |
Unix, Linux and Windows systems: | "MPUT" | "NT"/"NE" | Length | Blanks | Blanks | — |
Message to program unit | "MPUT" | "NT"/"NE" | Length | TAC | — | — |
Last screen output of stacked service | "MPUT" | "PM" | Length | Blanks | Format identifier / Blanks | Screen function |
Send rollback message | "MPUT" | "RM" | Length | Rollback ID | binär null | binary null / KCRESTRT |
Message to job-receiving service now(LU6.1) | "MPUT" | "NT"/"NE" | Length | Service ID | Format identifier / Blanks | binary null |
Message to job-submitting service (LU6.1) | "MPUT" | "NT"/"NE" | Length | Blanks | Format identifier / Blanks | any value |
Message to job-receiving service (OSI TP) | "MPUT" | "NT"/"NE" | Length | Service ID | Blanks / abstract syntax | 0 |
Message to job-submitting service (OSI TP) | "MPUT" | "NT"/"NE" | Length | Blanks | Blanks / abstract syntax | 0 |
Request a dialog confirmation | "MPUT" | "HM" | 0 | Service ID / blanks | Blanks | 0 |
Error message or neg. confirmation | "MPUT" | "EM" | 0 | Service ID / blanks | Blanks | 0 |
Error message for UPIC clients, socket USP applications or HTTP clients | "MPUT" | "ES" | Length | Blanks | Blanks / Format identifier | 0 |
NT: message segment
NE: last message segment or complete message.
For KCOM = HM/EM/ES/PM/RM you have to set binary zero for all the fields not used in the KDCS parameter area.
Setting the 2nd parameter
Here you have to supply the address of the message area from which openUTM is to read the message.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"MPUT" | |
"NT"/"NE"/"PM"/"RM"/"HM"/"EM"/"ES" | |
Length in bytes | |
Blanks/TAC/Rollback ID/service ID | |
Format identifier / blanks / Name of abstract syntax / edit profile (only on BS2000 systems) | |
Screen function/binary zero | |
Data | |
KDCS call | |
KDCS message area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_MPUTNT/KDCS_MPUTNE | (nb,kclm,kcrn,kcfn,kcdf) |
KDCS_MPUTPM | (nb,kclm,kcfn,kcdf) |
KDCS_MPUTRM | (nb,kclm,kcfn) |
KDCS_MPUTHM/KDCS_MPUTEM | (nb,kcrn) |
KDCS_MPUTES | (nb,kclm,kcfn) |
openUTM return information | |
|---|---|
Field name in the KB return area | Contents |
Return code | |
Internal return code | |
For the MPUT call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, the "MPUT" operation code.
KCOM
In the KCOM field:
NT for message segment.
NE for complete message or final message segment.
PM for the last screen output of a stacked service or the request for a service restart in the sign-on service.
RM for a rollback message.
HM for requesting a processing confirmation from OSI partners.
EM for an error message or a negative processing confirmation to OSI partners.
ES for creating an error message to a UPIC client, a socket USP application or an HTTP client.
KCLM
In the KCLM field, the length of the message in the message area which is to be sent (length zero is also permitted).
KCRN
In the KCRN field, depending on message recipient:
the transaction code of a follow-up program if this MPUT sends a message to a follow-up program in the same application (this also applies for a PEND FC call).
blanks if this MPUT sends a dialog message to a client.
the rollback identification (rollback ID) if a rollback message is to be sent for the service restart. The rollback ID must begin with "<" (see chapter "MGET Receive dialog message", section "Features of a rollback message").
blanks if this MPUT creates an error message for a UPIC client.
blanks for a response to the job-submitting service.
the service ID of a job-receiving service if this MPUT call is directed to a job-receiving service.
KCMF/kcfn
In the KCMF/kcfn field
blanks for a message in line mode
blanks for KCOM = PM with KCLM = 0
blanks or format identifier for messages to a UPIC client or a LU6.1 partner.
Blanks or name of the abstract syntax
The name of the abstract syntax of the message must be specified in the case of messages to OSI TP partners. Here, blanks represent the abstract syntax of UDT. In this case, the BER transfer syntax is used and the encoding of the message is performed by openUTM.
If you enter a value other than blanks, the message must be transferred to openUTM in encoded format, i.e. in the transfer syntax corresponding to this abstract syntax.
Only on BS2000 systems:
a format identifier for a message in format mode or for KCOM = PM with KCLM> 0. If a screen is to be refreshed, the specified format must be a component of the screen to be refreshed.
edit profile for a message in line mode
In all other cases, irrelevant
KCDF
In the KCDF field, a screen function, if the receiver is a terminal.
In the following cases you have to set binary zero in the field:
KCMF/kcfn contains the name of a #format.
The message is intended for a job-receiving service.
The message is intended for an OSI TP job-submitting service.
MPUT PM with KCLM = 0 is used.
Only on BS2000 systems: KCMF/kcfn contains the name of the edit profile.
When sending a rollback message (KCOM = RM), you must specify KCRESTRT or binary zero.
Message area
You enter in the message area the message you want to output.
You enter the following for the KDCS call:
1st parameter
The address of the KDCS parameter area.
2nd parameter
The address of the message area from which openUTM is to read the message (or user information). 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:
KCRCCC
In the KCRCCC field, the KDCS return code.
KCRCDC
In the KCRCDC field, the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).
KDCS return codes in the KCRCCC field for the MPUT call
The following codes can be analyzed in the program:
000 | Function carried out |
41Z | Too many MPUT calls:
|
45Z | The value specified in KCMF/kcfn is invalid. Possible cause: The specified abstract syntax has not been generated for the OSI-LPAP partner |
Additional error codes can be found in the dump:
70Z | The system cannot perform the operation (system or generation error), see KCRCDC. |
71Z | MPUT call in an MSGTAC program unit or no INIT in program unit. |
72Z | Entry in KCOM is invalid or MPUT-PM was entered in an asynchronous program unit. |
73Z | Length entry in KCLM is invalid. |
74Z | Value in KCRN is invalid, because
|
75Z | Value in KCMF/kcfn is invalid. Possible causes:
Only on BS2000 systems:
|
77Z | The message area is missing or cannot be accessed in the specified length. |
89Z | Contents of fields not used in the KDCS parameter area are not equal to binary zero for KCOM PM/RM/HM/EM/ES. |
Features of the MPUT call
The message area is left unchanged when openUTM executes the call.
Maximum message length for MPUT NT/NE
For messages to terminals, to transport system applications of type APPLI or to a subsequent program unit, the total message may be no longer than the value generated in the NB operand of the MAX control statement.
Otherwise, the length of a message segment is limited to 32,767 bytes and the length of the total message is unlimited.
You can use screen functions for outputs in format mode (see "Screen output functions in format mode (BS2000 systems)").
Only on BS2000 systems: If you use edit profiles, KCDF must be set to binary zero, otherwise openUTM returns 70Z.
You can display multiple messages in a processing step, provided that the messages are issued to job-receiving services and the transaction remains open at the end of the processing step. In all other cases a maximum of one message may be displayed.
A message can consist of two or more message segments, e.g. two or more MPUT NT followed by an MPUT NE with the same KCRN. You can create messages in parallel for job-receiving services, i.e. the service ID in KCRN can change. Any other change to the message destination is not permitted, because it creates an end of message for all messages not yet terminated. Following an unpermitted change of message destinations, no further MPUT is permitted. After terminating a message with MPUT NE or MPUT HM, no further MPUT is permitted with KCRN.
With PEND KP/RE/FI/ER/FR and PGWT KP/CM, the entire message is transmitted to the communication partner (formatted, if applicable).
With PEND PA/PR/FC/SP, the message or message segments are passed to the follow-up program whose TAC was specified in KCRN (PEND and MPUT calls). The follow-up program must read each message segment with a separate MGET.
At the end of a processing step all messages not yet terminated are closed implicitly by openUTM.
In a program unit run, ending with PEND PA/PR, PS, SP or FC, the MPUT call can be omitted. In a program unit run ending with PEND KP/RE or PGWT KP, at least one MPUT must be entered. Equally, in a dialog service, at least one MPUT have been entered before PEND FI/ER or FR. However, this does not apply, if the KCSEND field contains the value "N" in an OSI TP server service.
The MPUT is not required in the sign-on service when it is to be followed by a service restart. openUTM then terminated the service that is ready to be restarted abnormally.In an asynchronous service, no MPUT may be issued before a PEND FI/ER or FR.
Empty messages, i.e. KCLM=0, are permitted.
If the empty message is sent to the terminal in format mode, it causes an empty format or partial format to be output.
On BS2000 systems, any dependencies must be taken into account by the FHS start parameters. See the FHS manual.Empty messages are also permitted in the case of distributed processing.
An empty message to a transport system application of the type APPLI will not be sent.
In the case of message segments to socket USP partners, each message segment must be sent by means of a separate MPUT NT. A separate message segment is created for each MPUT NT/NE.
In the case of MPUT calls with KCLM=0, no messages are sent unless automatically created USP headers (see "Output messages of openUTM") are used. In this case, the header is also sent in the case of MPUT NE/NT with a length of zero. Exception: if the program unit contains only a single MPUT NE/NT and KCLM=0, no header is sent.- In case of HTTP clients all message segments created with MPUT NT will be sent in the message body of the HTTP response.
If the receiver is not a terminal, the message is sent transparently, i.e. the message may contain any bit pattern.
An empty message to a UPIC application is sent since the permission to send has been transferred.
Sending message segments
A message can consist of a number of message segments, e.g. multiple MPUT NT followed by an MPUT NE with the same KCRN. You can create messages in parallel for job-receiving services, i.e. the service ID in KCRN can change. Any other change to the message destination is not permitted, because it creates an end of message for all messages not yet terminated. If the last message segment is not identified by "NE" in KCOM, the message terminates automatically when PEND occurs.
If there is a change between line and formatted modes or a change of the edit profile, openUTM responds with 75Z and aborts the service.
Sending partial formats
With a terminal in format mode, a screen can be set up from multiple partial formats. Each of these partial formats must be output with MPUT NT; the last one can be output with MPUT NE.
Screen functions (KCDF) can only be specified with the first MPUT NT. For subsequent MPUT calls, KCDF must contain binary zeros. Otherwise, UTM will terminate the service with 70Z in KCRCCC and K606 in KCRCDC.
Screen functions permitted with partial formats:
KCREPL
Delete screen. This function must be specified when a screen is to be set up anew. If KCREPL is not set, any partial format existing on the screen will be overwritten by a new one. If the same partial format is output again, only the contents of the fields will be replaced (same as KCERAS).
KCALARM
Audible alarm.
KCREPR
Print on hardcopy printer.
KCERAS
Delete unprotected fields; see section "Using partial formats (BS2000 systems)".
Special features of the MPUT RM call
MPUT RM is also permitted if preceded by MPUT NT/NE or MPUT PM calls. The length of the MPUT-RM message is limited to 32,767 bytes.
Only one rollback message can be output in a program unit run. Other MPUT calls are permitted before or after MPUT RM. Rollback messages are deleted when the user signs off. After a service restart, the field KCRPI contains blanks.Special features of the MPUT PM call
openUTM uses MPUT PM to output the last output message of a stacked service on the screen. The following holds:
for KCLM = 0 the output appears unchanged on the screen, for KCLM > 0 it is overwritten (not exceeding the specified length), but sent in its entirety. The length of the MPUT-PM message is limited by the value generated in the NB operand of the MAX control statement.
for output messages in line mode you must always specify KCLM = 0 (and KCMF/kcfn = blanks)
the program unit must terminate with PEND FI, otherwise UTM aborts the service with 82Z
the sign-on service must use this variant at the end of the service if a service restart is to be executed.
Abstract syntax with distributed processing via the OSI TP protocol
If you specify a value not equal to blanks in KCMF/kcfn when communicating with a partner via the OSI TP protocol, then you have to generate this value as the name of an abstract syntax for the partner. In this case, the application program unit has to transfer the message to openUTM in encoded form, i.e. the application must convert the message to the transfer syntax allocated to the abstract syntax. To do this, the application can use an ASN1 compiler. Abstract syntaxes with the name "CCR" or "OSITP" are not permitted.
When communicating via a UPIC client or 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.
MPUT call in the job-submitting service
An MPUT call can be used by a job-submitting service to start a job-receiving service in a partner application, or to send a message to a job-receiving service which has already started.
You have to specify the service ID, which was allocated to the job-receiving service when APRO DM was called, in the KCRN field as target.In a program unit run of the job-submitting service you can only use MPUT to send messages either to the LTERM partner (KCRN=blanks), to the follow-up program unit (KCRN=TAC) or to one or more job-receiving services (KCRN=service ID).
In the job-submitting service KCDF must contain binary 0 for MPUT.
Each message segment output with MPUT NT to a job-receiving service has to be read there with a separate MGET.
In a program unit run, no messages (message segments) may be sent to a job-receiving service prior to PEND PR or PA, otherwise openUTM aborts the job-submitting service with the error code KCRCCC=82Z.
MPUT call in the job-receiving service
Setting the KDCS parameter area is the same as for the MPUT call for a terminal.
When communicating via LU6 protocol, the KCDF field may contain any value which has been passed to the job-submitting service in MGET as screen function. For message segments, only the KCDF value of the first message segment is transferred.
You have to set KCDF to binary zero when communicating via the OSI TP protocol.Each message segment output with MPUT NT to a partner service has to be read there with a separate MGET.
Particularities of the MPUT HM call
With MPUT HM, a program run can request a processing confirmation from an OSI TP partner. The following rules apply when using MPUT HM:
The call can only be used, if the handshake function was selected for communication; otherwise openUTM aborts the service with 72Z. With INIT, the KB header indicates to the job-receiving service whether the handshake is permitted.
An MPUT HM to a partner, which does not have O or U transaction status, is rejected by openUTM with 72Z.
At least one MPUT NT to the partner must have been entered prior to MPUT HM.
MPUT HM produces an end of message for the communication partner.
No data can be passed to the call (KCLM = 0).
Following MPUT HM only one PEND KP or one PGWT KP is permitted. With all other PEND variants, UTM responds with the return code 82Z.
Following MPUT HM you may not issue a further CTRL PR/PE call to the same partner.
Particularities of the MPUT EM call
Using the MPUT EM call you can report an error to an OSI TP partner. If a handshake request is confirmed negatively with the call, MPUT EM must be entered as the first MPUT to the partner that requires a processing confirmation. The call must be issued in the same transaction in which the handshake request was read. Otherwise a positive confirmation is sent.
No data can be passed to the call (KCLM = 0).
An MPUT EM to a partner, which does not have O or U transaction status, is rejected by openUTM with 72Z.
Particularities of the MPUT ES call
The MPUT ES (error system) call can be used in a dialog program unit to create an error message for a UPIC client, a socket USP application or an HTTP client. This error message is only sent when the service is terminated abnormally by openUTM (system PEND ER).
An error message created with MPUT ES remains valid, provided it is not overwritten with another MPUT ES, until the service is terminated with the output of a dialog message to the UPIC client, socket USP application or an HTTP client. In the case of service concatenation (PEND FC), the error message is thus also valid in the concatenated service.
Each subsequent MPUT ES overwrites the error message written last. An MPUT ES with a length of 0 deletes the error message.
The length of the MPUT ES message is limited by the value generated in the NB operand of the MAX control statement.
If the transaction is rolled back, the error message is rolled back to the state of the last synchronization point.