Using KC_SEND_MESSAGE, you can send a message to one or more or all active terminals of a UTM application on a BS2000 system. The message text may be up to 74 characters in length and it is passed to UTM in the data area. UTM then sends the message as UTM message K023 with the specified message as an insert. By default, the message is output in the system line on the terminal. However, the message destination of message K023 can also be changed. If the message destination PARTNER is selected for the UTM message K023 (see the openUTM manual ”Messages, Debugging and Diagnostics”), you can also send the message to one or more or all connected TS applications. The message only goes to dialog partners (LTERM with USAGE=D).
Using KC_SEND_MESSAGE, you can:
send a message to all terminals currently connected to the application. This also applies to terminals connected to the application via an LTERM pool.
send a message to all TS applications connected to the UTM application, provided the message destination PARTNER is generated for K023.
send a message to a certain terminal user or, provided the message destination PARTNER is generated, to a specific TS application. In this case, you must specify in the identification area the name of the LTERM partner via which the terminal is connected to the application. The precondition for delivery of the message is that the terminal must be connected to the application at the time the KC_SEND_MESSAGE call is issued.
If you want to send a message to a certain user, you can ascertain the LTERM partner through which the user is signed on to the application in the following manner:
First, using KC_GET_OBJECT, request information about the user ID under which the user has signed on to the application (object type KC_USER).
UTM then returns the properties of the user ID in the data structure kc_user_str. If, at the time of the request, the user is connected to the application, the field lterm_curr contains the name of the LTERM partner through which the user is signed on. This is the name which you pass in the identification area when sending the message with KC_SEND_MESSAGE.
Execution / transaction management
A KC_SEND_MESSAGE call is not subject to transaction management. It cannot be rolled back by an RSET in the same transaction.
If you do not specify a recipient in the identification area and the parameter area to number=0, UTM identifies all currently active LTERM partners entered with usage_type='D' and sends them the message. The message will already have been sent when control is returned to the program unit.
If you specify the name of an LTERM partner in the identification area and set the parameter area to number=1, successful processing of the KC_SEND_MESSAGE call means that the message has been sent to this LTERM partner. If the LTERM partner cannot currently be reached, UTM returns an appropriate return code.
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area 1 | identification area | selection area | data area | |
Send message to all active LTERM partners | obj_number: 0
| —— | —— | Message |
Send message to one LTERM partner | obj_number: 1 | Name of LTERM partner | —— | Message |
Parameter settings | |
Parameter area | |
Field name | Content |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_SEND_MESSAGE |
1 / 0 | |
Length of object name / 0 | |
select_lth | 0 |
Length of message | |
Object name / — | |
Selection area | |
— | |
Message | |
KDCADMI call |
KDCADMI (¶meter_area, &identification_area, NULL, &data_area) or |
Data returned by UTM | |
Parameter area | |
Field name | Content |
Return codes | |
obj_number
Specify in obj_number whether the message is to be sent to all currently active LTERM partners or only to a specific LTERM partner.
obj_number=0 means:
The message is to be sent to all active LTERM partners. The null pointer must be passed as the address of the identification area.obj_number=1 means:
The message is to be sent to only one LTERM partner. The name of the LTERM partner must be passed in the identification area.
id_lth
The length of the identification area must be specified in id_lth, i.e.:
for obj_number=0 you must specify id_lth=0.
for obj_number=1 you must specify in id_lth the length of the object name which is passed in the identification area.
data_lth
Length of the message to be sent. You must pass the message in the data area. The following must apply: 1 <= data_lth <= 74.
Identification area
How you have to complete the identification area depends on the value set for obj_number.
for obj_number= 0 you must pass the null pointer in the KC_SEND_MESSAGE call.
for obj_number= 1 you must specify in the identification area the union kc_id_area with the name of the LTERM partner (field kc_name8), to which the message is to be sent.
Data area
The message which UTM is to send is to be passed in the data area. The message must be no more than 74 characters in length.
retcode
UTM writes the return codes for the call to the retcode field.
In addition to the return codes listed in section "Return codes", the following codes can also occur.
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_NOT_EXISTENT The name specified in the identification area is unknown, no LTERM partner with this name exists. |
KC_SC_NOT_ALLOWED The operation is not allowed for the LTERM partner specified in the identification area or for the client assigned to this LTERM partner.
|
KC_SC_DELETED The specified LTERM partner no longer exists, it has been deleted from the application configuration. |