The FPUT (free message PUT) call enables you to create messages or message segments for message queues, which openUTM enters in receiver-specific queue:
output jobs for LTERM partners
background jobs for local asynchronous services
background jobs for remote asynchronous services previously addressed with APRO AM calls
asynchronous messages for local or remote TAC queues
Only on BS2000 systems: pass print options (= RSO parameter list) for RSO printers
The message segments generated with FPUT are gathered by openUTM and terminated with the next PEND call. When the transaction ends the message segments are input as a single message into the appropriate message queue. Exception: If you send formatted message segments to terminals, each of these segments forms a separate message.
In the case of TAC queues, the recipient must read the message from the queue in a separate transaction.
Messages remain in a message queue until they are:
successfully sent (LTERM partner)
successfully processed (asynchronous service) or
successfully read (TAC queue).
The format of the FPUT 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 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 | |
Output job in format mode | "FPUT" | "NT"/"NE" | Length | LTERM name | Format identifier | Screen function |
Unix, Linux, Windows systems: | "FPUT" | "NT"/"NE" | Length | LTERM name | Blanks | — |
BS2000 systems: | "FPUT" | "NT"/"NE" | Length | LTERM name | Blanks / edit profile | Screen function / binary zero |
Message for asynchronous program or | "FPUT" | "NT"/"NE" | Length | TAC / Name of a TAC queue | — | — |
Output job for transport system application | "FPUT" | "NT"/"NE" | Length | LTERM name of application | Blanks | Binary zero |
Background job via LU6.1 | "FPUT" | "NT"/"NE" | Length | service ID | — | — |
Background job via OSITP | "FPUT" | "NT"/"NE" | Length | service ID | Name of abstract syntax / blanks | — |
BS2000 systems: | "FPUT" | "RP" | Length | LTERM name | Blank | Binary zero |
NT: message segment of the job
NE: last message segment or entire message of the job
RP: RSO parameter list (BS2000 systems)
Setting the 2nd parameter
Here you have to supply the address of the message area from which openUTM is to read the message or the RSO parameter list.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"FPUT" | |
"NT"/"NE"/"RP" | |
Length in bytes | |
LTERM name / TAC queue / service ID | |
Format identifier / blanks / edit profile (only on BS2000 systems) | |
Screen function/binary zero | |
Data | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro call | |
Parameters | |
KDCS_FPUTNT / KDCS_FPUTNE | (nb,kclm,kcrn,kcfn,kcdf) |
KDCS_FPUTRP | (nb,kclm,kcrn) |
openUTM return information | |
|---|---|
Field name in the KB return area | Contents |
Return code | |
Internal return code | |
For the FPUT 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, enter either NT or NE for total message or last message segment or RP for an RSO parameter list.
KCLM
In the KCLM field, specify the length of the message to be sent in the message area (length zero is permissible).
For KCOM = RP on BS20000 systems, this is the length of the data structure for the RSO parameter list.
KCRN
In the KCRN field, enter the destination of the message:
the name of the LTERM partner if this FPUT call generates an output job or passes an RSO parameter list
the transaction code of an asynchronous program if this FPUT generates a background job (without distributed processing)
the service ID of a job-receiving service if this background job is directed to a job-receiving service
the name of the TAC queue if the message is to be sent to a TAC queue
the service ID of the remote TAC queue if this message is to be sent to a remote TAC queue
KCMF / kcfn
In the KCMF/kcfn field (If messages are sent to an asynchronous service or a TAC queue of the same application or to an LU6.1 partner then this field is irrelevant), specify:
Blanks in line mode or for a job sent to another application without distributed processing or when passing an RSO parameter list.
In messages to an OSI TP partner:
The name of the abstract syntax of the message. Here, blanks represent the abstract syntax of UTD. In this case the BER transfer syntax is used and the message is encoded openUTM.
If you enter a value other than blanks, the message must be transferred to openUTM in encoded form, i.e. in the transfer syntax corresponding to this abstract syntax.
Only on BS2000 systems:
A format identifier (in format mode)
In the case of messages to RSO printers:
If a format has been specifically created for RSO printers then the FHS formatting system does not need to know the printer type because FHS generates a logical message which is then converted into the physical message by RSO.
If not, FHS must support the printer type as generated in RSO as otherwise formatting errors will occur.Edit profile (for line mode or an RSO printer)
If the message is to be sent to an RSO printer, then only the CCSNAME parameter of an edit profile is evaluated. The name of the character set is passed to RSO. All other parameters of the edit profile are ignored because these options are VTSU-B edit options, and the message is being prepared by RSO.
KCDF
In the KCDF field (irrelevant for background jobs and TAC queues):
the screen function if the FPUT call is intended for an LTERM partner. Enter binary zero for jobs to other applications without distributed processing or when passing RSO parameter lists.
On BS2000 systems, you must also specify binary zero if an edit profile or a #format is specified in KCMF/kcfn.
Message area
In the message area, you specify the message you want to output or the RSO parameter list you want to pass.
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 RSO parameter list. 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 (see next page).
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 FPUT call
The following codes can be analyzed in the program:
000 | Function carried out |
04Z | The name in KCRN changes, and FPUT NE was not specified before. |
40Z | openUTM cannot perform the function (system or generation error, deadlock, long-term locks), see KCRCDC. |
41Z | KCRN addressed the LTERM partner that started the current service or FPUT was issued in the first part of the sign-on service or an FPUT call was issued in the sign-on service after the SIGN ON and before the PEND PS. |
42Z | Entry in KCOM invalid. |
43Z | Length entry in KCLM negative or invalid. |
44Z | Value in KCRN is not a TAC of an asynchronous program or a TAC queue, or the TAC is locked or prohibited and there is no name of an LTERM partner or the LTERM name of a UPIC or HTTP client, or there is no valid service ID (with distributed processing). See KCRCDC. Only on BS2000 systems: |
45Z | The entry in KCMF/kcfn is invalid. Possible causes:
Only on BS2000 systems:
|
47Z | The message area is missing or not accessible in the specified length. |
An additional error code can be found in the dump:
71Z | INIT call missing in this program. |
Features of the FPUT/DPUT call
FPUT and DPUT calls which direct program units to an alias LTERM are processed as follows:
In an LTERM group without an LTERM bundle, openUTM sends FPUT/DPUT calls via the PTERM which is assigned to the primary LTERM.
In the case of an LTERM group whose primary LTERM is the master LTERM of an LTERM bundle, openUTM assigns all the queued messages sent to the group’s alias LTERMs during this transaction to one of the slave LTERMs on transaction end. This procedure guarantees that the receiver possesses the same message sequence as was generated for an LTERM group during a transaction.
FPUT and DPUT calls which direct program units to the master LTERM are assigned to one of the slave LTERMs at transaction end.
FPUT and DPUT calls can also direct program units directly to the primary LTERM.
The message area is not changed when openUTM executes the call
Several jobs can be created in a program unit; the corresponding messages can consist of several segments.
For outputs in +formats, *formats or messages in line mode you can also use the screen output functions, see the chapter "Screen output functions in format mode (BS2000 systems)".
Only on BS2000 systems:
If you use #formats, then the KCDF must be set to binary zero, otherwise openUTM reacts with 40Z.
Similarly, when working with edit profiles openUTM responds with 40Z if KCDF has not been set to binary zero.
The jobs created with FPUT are discarded as a result of PEND ER/FR, PEND RS or RSET.
No output job to the client with which the program is currently working (KCRN
!=KCLOGTER) may be generated in a dialog program.With FPUT calls to another UTM application which was generated as a transport system application, the TAC must be located at the start of the message area.
If necessary, the message is formatted before being output.
Asynchronous jobs are kept until:
the referenced program unit or printout is terminated, or, with jobs to remote asynchronous services, the transfer has been terminated successfully
the message is read at the terminal with KDCOUT and a new input has been made (except for the KDCLAST command) or
the message is read from a TAC queue by means of a DGET call and the transaction containing the DGET is completed successfully.
Jobs with messages of length 0
If a message with a length of 0 is created (known as a "dummy message"), the following applies:
a background job is executed, i.e. the asynchronous service is started without receiving a message
an empty format is output if the job is an output job for a format terminal
in the case of a message for a TAC queue, an empty message is created that can be read by means of a DGET call
if the job is an output job for a transport system, it is accepted but will later be discarded by openUTM.
Background jobs for an asynchronous program in the same application: Each background job starts a separate asynchronous service. If several complete messages are sent to the same TAC in a program unit run, a separate asynchronous service is started for each message.
If several complete messages are sent to the same TAC queue in a program unit run, each message must be read by means of a separate DGET FT call.
There is no interaction between FPUT and DPUT calls, i.e. DPUT calls withKCMOD = "'BLANK'" and FPUT calls can be sent at a certain location independent of one another.
Output jobs intended for a terminal are inserted into the message queue and can be retrieved by the user with the KDCOUT command. Each KDCOUT command retrieves exactly one message. Each message can only be retrieved once. If the KDCOUT command is repeated the next message is retrieved from the queue.
At the end of transaction, a message in the system line informs the terminal user whether asynchronous messages are present for the terminal.
You can suppress this message on BS2000 systems by setting ANNOAMSG=N for the associated LTERM partner in the configuration (default value: ANNOAMSG=Y). Asynchronous messages are then displayed immediately on the screen. This may interrupt the dialog. However, the terminal user can use the KDCDISP command to display the last screen again.
Print options for RSO printers (BS2000 systems)
If you use print options for jobs to RSO printers, you should first pass the list with the print options using FPUT RP, see RSO manual. Then submit the actual print job using FPUT NT/NE.
Handling message segments
Message segments in line mode are combined into one message and sent to the LTERM partner. The message segments generated with FPUT are gathered by openUTM and terminated with the next PEND call, provided they have not yet been terminated in the program unit run with FPUT NE. When the transaction ends, the message segments are sent as a single message to the LTERM partner or to another application.
With formatted message segments to terminals, each segment forms a separate message. The format name in KCMF/kcfn needs not always stay the same. At a terminal, each format (message segment) must be fetched with a KDCOUT command. Each FPUT NT call generates a separate message. It is therefore not possible to structure a screen with different partial formats using FPUT NT calls. The formats arrive in the order in which they were sent.
With message segments to printer, it is possible to switch between formatted message segments and unformatted message segments (in line mode). With message segments to terminals, this switch causes the old message to terminate and a new one to start.
With FPUT NT calls to local or remote asynchronous services or local or remote TAC queues, each message segment must be read with a separate FGET NT.
With PEND, the message segment most recently generated with FPUT is always assumed to be the final message segment, even if it was output with NT.
The maximum number of FPUT NE calls which are possible in a transaction depends on the RECBUF generation parameter in the KDCDEF statement MAX. Each FPUT NE occupies 30 bytes in this buffer. If the buffer is full, FPUT NE is rejected with KCRCDC=K704.
If, in a sequence of message segments, the name in KCRN (i.e. the message receiver) changes but no FPUT with "NE" was entered previously, a warning is issued (04Z) and a new message is started. The previous message (sequence of message segments) is terminated. This means that if the name in KCRN is changed back to the first recipient with a subsequent FPUT, the first message is not continued, but a new message is begun. The message is forwarded to the receiver when the next synchronization point is reached. Parallel messages, as used in DPUT, are therefore not possible.
Only on BS2000 systems: If the edit profile changes within a sequence of message segments addressed to a terminal, openUTM reacts with 45Z.
Influence of generation parameters on the FPUT call
The following notes concern the generation of the UTM application. Further information on the individual generation parameters can be found in the openUTM manual “Generating Applications”.
For messages for terminals and transport system applications, the total message may not exceed the value generated for the NB operand of the control statement MAX. In the case of messages to other partners the length of a message segment is limited to 32,767 bytes and the length of the total message is unlimited.
When the KDCFILE is regenerated with the UTM tool KDCUPD, you can specify in the TRANSFER statement precisely which messages you want to include in the new KDCFILE (see also the openUTM manual “Generating Applications”).
Only on BS2000 systems: The ANNOAMSG operand in the KDCDEF control statement LTERM defines for each LTERM partner whether asynchronous messages are to be output immediately to this terminal or announced with a message. This message appears in the system status line.
FPUT calls with distributed processing
In the job-submitting service, the KDCS parameter area must be given the same values as for background jobs for an asynchronous program in its own application. The only thing that has to be specified as name in the KCRN field is the service ID which was assigned to the job-receiving service in the APRO AM call.
Once the FPUT NE call has terminated (final message segment or complete message) or after return of the KDCS error code 40Z, the service ID is released. This ID can now be used for a new job submitter/receiver relationship in this service.
If the wait time for using a session or association was set to 0 at generation time, and if no connection exists with the partner application at the time the FPUT call is issued, openUTM sets the error codes 40Z in KCRCCC and KD13 in KCRCDC after the FPUT call.