Setting the KDCS parameter area (1st parameter)
The following two tables show the various options and 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 | "DPUT" | "NT"/"NE" | Length | LTERM name | Format identifier | Screen function |
Unix, Linux and Windows systems: | "DPUT" | "NT"/"NE" | Length | LTERM name | Blanks | — |
BS2000 systems: | "DPUT" | "NT"/"NE" | Length | LTERM name | Blanks / edit profile | Screen function / binary zero |
Background job for asynchronous program in the same application | "DPUT" | "NT"/"NE" | Length | TAC | — | — |
Message for service-controlled queue | "DPUT" | "QT"/"QE" | Length | Name of the queue | — | — |
Job for transport system application | "DPUT" | "NT"/"NE" | Length | LTERM name of application | Blanks | Binary zero |
Background job for job-receiving service via LU6.1 | "DPUT" | "NT"/"NE" | Length | service -ID | — | — |
Background job for job-receiving service via OSI TP | "DPUT" | "NT"/"NE" | Length | service-ID | Blanks / name of abstract syntax | — |
Log user information | "DPUT" | "NI"/"QI" | Length | as for related DPUT NT/NE or DPUT QT/QE | Blanks | Binary zero |
BS2000 systems: | "DPUT" | "RP" | Length | LTERM name | Blank | Binary zero |
NT, QT: Message segment for job
NE, QE: Last message segment or entire message for job
NI, QI: User information for a subsequent message
RP: RSO parameters (BS2000 systems
Entry in KCOM field | Additional entries in the KDCS parameter area (KCPUT/kc_dput) | ||||||
|---|---|---|---|---|---|---|---|
KCMOD | KCTAG/ kcday | KCSTD/ kchour | KCMIN | KCSEK/ kcsec | KCQTYP | Other fields | |
"NT"/"NE" | "A" | 001 - 365/366 | 00 - 23 | 00 - 59 | 00 - 59 | — | — |
"R" | 000 - 364/365 | — | |||||
Blanks | — | — | — | ||||
"QT"/"QE" | "A" | 001 - 365/366 | 00 - 23 | 00 - 59 | 00 - 59 | Binary zero | Binary zero |
"R" | 000 - 364/365 | ||||||
Blanks | Binary zero | Binary zero | "U" / "Q" / Binary zero | ||||
"NI" | "A" | 001 - 365/366 | 00 - 23 | 00 - 59 | 00 - 59 | Binary zero | Binary zero |
"R" | 000 - 364/365 | ||||||
Blanks | Binary zero | Binary zero | "U" / "Q" / Binary zero | ||||
"QI" | "A" | 001 - 365/366 | 00 - 23 | 00 - 59 | 00 - 59 | Binary zero | Binary zero |
"R" | 000 - 364/365 | ||||||
Blanks | Binary zero | Binary zero | "U" / "Q" / Binary zero | ||||
"RP" (BS2000 systems) | "A" | 001 - 365/366 | 00 - 23 | 00 - 59 | 00 - 59 | Binary zero | Binary zero |
"R" | 000 - 364/365 | ||||||
Blank | Binary zero | ||||||
A: absolute time
R: relative time (= time interval)
In the case of DPUT NT/NE or DPUT QT/QE you have to specify the same times as for the associated DPUT NI or DPUT QI.
Setting the 2nd parameter
Here you have to supply the address of the message area from which openUTM is to read the message or user information or the RSO parameter list.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"DPUT" | |
"NT"/"NE"/"QT"/"QE"/"NI"/"QI"/"RP" | |
Length in bytes | |
LTERM name / TAC / service ID / queue name | |
Format ID / blanks / Name of abstract syntax / Name of edit profile (only BS2000 systems) | |
Screen function / binary zero | |
"R"/"A"/'BLANK' | |
| Time specification (rel./abs.) | |
|
|
|
|
|
|
|
|
"U" / "Q" / binary zero | |
Data | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_DPUTNT/KDCS_DPUTNE | (nb,kclm,kcrn,kcfn,kcdf,kcmod,kcday,kchour,kcmin,kcsec) |
KDCS_DPUTQT/KDCS_DPUTQE | (nb,kclm,kcrn,kcfn,kcdf,kcmod,kcday,kchour,kcmin,kcsec,kcqtyp) |
KDCS_DPUTNI | (nb,kclm,kcrn,kcmod,kcday,kchour,kcmin,kcsec) |
KDCS_DPUTQI | (nb,kclm,kcrn,kcmod,kcday,kchour,kcmin,kcsec,kcqtyp) |
KDCS_DPUTRP | (nb,kclm,kcrn,kcmod,kcday,kchour,kcmin,kcsec) |
openUTM return information | |
|---|---|
Field name in KB return area | Contents |
Return code | |
Internal return code | |
For the DPUT call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, enter the DPUT operation code.
KCOM
In the KCOM field, enter the required operation modifier:
NT for the message segment of the job
NE for the total message or last message segment of the job
NI for the user information associated with the job.
QT for the message segment for a service-controlled queue
QE for the entire message or last message segment for a service-controlled queue
QI for the user information associated with the message for a service-controlled queue
RP for the parameter list of an RSO printer (only on BS2000 systems).
KCLM
In the KCLM field, specify the length of the message to be sent (length zero is permissible).
For KCOM = RP, this is the length of the RSO parameter list (only on BS2000 systems).
KCRN
In the KCRN field, enter the destination of the message:
the name of the LTERM partner if this DPUT call generates an output job or passes an RSO parameter list
the name of the USER queue, TAC queue or temporary queue, if this DPUT call creates a message to a service-controlled queue (KCOM=QT/QE/QI).
the transaction code of an asynchronous program if this DPUT call 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.
KCMF / kcfn
In the KCMF/kcfn field:
Blanks in line mode or for a job sent to another application without distributed processing.
In the case of messages to OSI TP partners:
The name of the abstract syntax of the message. Space characters stand for the abstract syntax of UDT; in this case, BER is used as the transfer syntax and the message is encoded 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 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.
Blanks when passing an RSO parameter list.
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.
In the case of messages to an asynchronous service of the same application, to USER, TAC or temporary queues or to an LU6.1 partner, this field is irrelevant.
KCDF
In the KCDF field, enter the screen function for output jobs to terminals. Enter binary zero for user information (KCOM = NI/QI), RSO parameter lists or jobs for transport system applications.
In the case of background jobs, messages to LU6.1 partners and messages to USER, TAC and temporary queues, this field is irrelevant.
On BS2000 systems, you also have to specify binary zero if an edit profile or a #format is entered in KCMF/kcfn.
KCMOD
In the KCMOD field, select the type of time entry:
A for absolute
R for relative
blanks, if the job is to be executed without a wait time.
messages to USER and temporary queues cannot be sent on a time-driven basis, which is why blanks must be specified in KCMOD
KCTAG / ...
Here you enter the necessary time specifications for the call, absolute or relative depending on the entry in KCMOD:
for absolute time entry: desired time with day of the year in KCTAG/kcday (working day), hour in KCSTD/kchour, minute in KCMIN and second in KCSEK/kcsec.
for relative time entry: interval to desired execution time with number of days in KCTAG/kcday, number of hours in KCSTD/kchour, number of minutes in KCMIN and the number of seconds in KCSEK/kcsec.
for KCMOD = blanks:
binary zero if user information is to be logged with KCOM = NI/QI or when a message is to be sent to a USER or temporary queue (KCOM= QE/QT) (otherwise irrelevant)
KCQTYP
In the KCQTYP field, specify in the case of messages to a queue the type of the queue(only in conjunction with KCOM=QT/QE/QI):
Q for a temporary queue created with QCRE
U for a queue assigned to a user ID (USER queue)
binary zero in all other cases
Message area
You enter in the message area the message or user information 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 UTM is to read the message or user information 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.
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 DPUT call without job complex
The following codes can be analyzed in the program:
000 | Function carried out |
06Z | Time entry changed without preceding DPUT NE, i.e. at least one of the fields KCMOD, KCTAG/kcday, KCSTD/kchour, KCMIN or KCSEK/kcsec has a value differing from that in the first message segment (for KCMOD=A/R). |
40Z | openUTM cannot perform the function, see entry in KCRCDC. Possible causes:
|
41Z | The call is not allowed at this location:
|
42Z | The entry in KCOM is invalid. |
43Z | The length entry in KCLM is negative or invalid. |
44Z | The value in KCRN or KCQTYP is invalid. Possible causes:
|
45Z | The entry in KCMF/kcfn is invalid. Possible causes:
Only on BS2000 systems:
|
47Z | The address of the message area is invalid. |
49Z | The contents of unused fields of the KDCS parameter area are not equal to binary zero. |
51Z | After a DPUT NI/QI there is no DPUT NT/NE/QT/QE to the same destination. |
52Z | An attempt was made to send a time-driven message to a USER queue or temporary queue. |
56Z | The entry in KCMOD is invalid or the time entry in KCTAG/kcday, KCSTD/kchour, KCMIN or KCSEK/kcsec is invalid or is outside the generated time span. |
An additional return code can be found in the dump:
71Z | INIT was not issued in this program. |
Features of the DPUT call
The message area is not changed when the call is executed by UTM.
More than one job can be generated in one program unit; the corresponding messages can each comprise more than one segment.
You can also use screen output functions when you output +formats, *formats or messages in line mode, see chapter "Screen output functions in format mode (BS2000 systems)".
If you use #formats, you have to specify binary zero for KCDF, otherwise openUTM returns 40Z.
Only on BS2000 systems: If you use edit profiles (), openUTM also returns 40Z if you have not specified binary zero for KCDF.Jobs generated with DPUT are discarded as a result of PEND ER/FR, PEND RS or RSET.
The TAC must be located at the beginning of the message area for DPUT calls to another UTM application that is generated as a transport system application.
The message is also formatted before it is output.
Messages are kept until:
the referenced program unit or the printout is terminated, or
the transfer has succeeded for jobs to remote asynchronous services, or
the message is read at the terminal using KDCOUT and a new input has been made (except for the KDCLAST command).
the message to a queue is read by means of a DGET call, and the corresponding transaction is successfully completed.
Jobs with messages of length 0
If you generate a message with a length of 0 (so-called "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 in format mode
an output job for a transport system application is accepted, but will later be discarded by openUTM.
Output jobs that are for one specific terminal are placed in the terminal message queue and can be read by the user with the KDCOUT command. Exactly one message is read per KDCOUT command. Each message can only be read once. If the KDCOUT command is entered more than once, then the next message is read from the terminal queue.
The user is informed at the end of a transaction that there are asynchronous messages available for a terminal through a message in the system status line.
This announcement can be suppressed on BS2000 systems if ANNOAMSG=N was specified in the configuration for the affected LTERM partner (default value: ANNOAMSG=Y). Asynchronous messages are then displayed immediately on the screen. This can disturb the dialog flow. The terminal user can, however, re-display the last screen using the KDCDISP command.
There is no interaction between FPUT and DPUT calls, i.e. you can send DPUT calls with KCMOD = "'BLANK'" and FPUT calls to the same destination independently of each other.
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 DPUT RP, see RSO manual. Then submit the actual print job using DPUT NT/NE. The time specifications in DPUT RP and DPUT NT/NE must match.
Handling message segments
message segments in line mode are combined and output as one message to the LTERM partner. The message segments generated with DPUT are gathered by openUTM and terminated by the next PEND call, provided they have not yet been terminated by the program unit run with DPUT NE. When the transaction ends, the message segments are sent as a single message to the LTERM partner or to the other application.
with formatted message segments to terminals, each segment generates a new format. The format name in KCMF may change. At a terminal, each format (each message segment) must be fetched with a KDCOUT command. Each DPUT NT call generates its own message. It is therefore not possible to structure the screen with different partial formats using DPUT 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 DPUT NT calls to a local or asynchronous service each message segment must be read with a separate FGET.
with DPUT QT calls to a service-controlled queue, each message segment must be read by means of a separate DGET.
with PEND, the message segment most recently generated with DPUT is always assumed to be the final message segment, even if it was output with NT.
In a sequence of message segments, a change of the destination specified in KCRN with no preceding DPUT NE/QE is only permissible in certain cases (see next point).
Only on BS2000 systems: If the edit profile changes within a sequence of message segments addressed to a terminal, openUTM reacts with 45Z.
The maximum possible number of DPUT NT/QE calls in a transaction depends on the RECBUF generation parameter in the KDCDEF statement MAX. 30 bytes per DPUT NE are occupied in this buffer. If the buffer is full, DPUT NE is rejected with KCRCDC=K704.
Parallel messages
Parallel messages (i.e. change of destination before DPUT NE/NQ) are permissible if the destinations belong to different categories. There are three categories:
LTERM partners, local asynchronous programs and service-controlled queues (KCRN=LTERM/TAC/queue name)
job complexes (KCRN = complex ID)
remote asynchronous services (KCRN = service ID) or remote TAC queues
Within these categories, parallel asynchronous jobs are only permitted if they are jobs for remote asynchronous services.
Apart from that, parallel job complexes are not supported, and the change of the LTERM/TAC/queue name requires the message to be concluded by means of DPUT NE/QE.
Influence of generation parameters on the DPUT 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”.
Limits for the time entry in the DPUT call are defined with the operands DPUTLIMIT1 and DPUTLIMIT2 in the MAX statement. The interval between the desired execution time and the DPUT call must not be greater than the time entry in DPUTLIMIT2 if before the time of the DPUT call, nor greater than the time entry in DPUTLIMIT1 if after the time of the DPUT call:
Current time - DPUTLIMIT2 < execution time < current time + DPUTLIMIT1The time of the DPUT call is taken as the current time.
In the case of DPUT calls with KCMOD = A or R to LTERM partners generated with LTERM ..., QAMSG=N, openUTM does not check at the time of the DPUT call to see whether a client or printer is connected to the LTERM partner. It only does this once the time specified in the DPUT call has arrived. If there is then no connection, openUTM will store the message until a connection is set up.
In the case of DPUT calls with KCMOD = "'BLANK'" to LTERM partners generated with LTERM ..., QAMSG=N, openUTM checks at the time of the DPUT call whether a client/printer is connected to this LTERM partner. If not, UTM rejects the call with KCRCCC = 44Z, KCRCDC= K705.
For all messages to terminals and transport system applications generated with DPUT, the entire message must not exceed the maximum length of 32700 bytes.
When the KDCFILE is regenerated with the UTM tool KDCUPD, you can specify in the TRANSFER statement precisely which messages you wish to transfer to the new KDCFILE (see also openUTM manual “Generating Applications”).
The UTM administrator can use the administration call KDCINF STAT to query the number of waiting time-driven jobs (see the openUTM manual “Administering Applications”, Administration commands, KDCINF).
DPUT calls with distributed processing
Prior to the DPUT call, the KDCS parameter area in the job-submitting service must be given the same values as for sending messages to a TAC queue or for generating background jobs to 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 call.
Once the DPUT NE/QE call has terminated (final message segment or complete message) or after the KDCS return code 40Z, the service ID in the job-submitting service is released. This ID can now be used to address another job-receiving service.
Only after the specified time has elapsed will the job generated with DPUT be sent to the partner application (if a free session or association is available).
Parallel asynchronous jobs to different job-receiving services are permissible.
User information (DPUT NI/QI)
User information is always associated with a job generated by a DPUT call. The user information must be generated before the job itself. The addressee (entry in KCRN) and the time entry in the user information and in the job must agree. If this is not sequence is not adhered to, error 51Z occurs. If the associated job for an item of user information does not exist (i.e. if there is user information but no job), openUTM aborts the service at the PEND call with KCRCCC = 86Z.
User information can only be read with a DADM call; it is a type of "log information" and is not transferred to the addressee. The user information of a confirmation job can not be read until the confirmation job has been activated.
Background jobs for an asynchronous program in the same application
Each background job starts an asynchronous service at the time specified.
Asynchronous programs which run in time-driven mode should check whether their work is still relevant, or whether they should terminate immediately. The program can ascertain the current time and date, as well as the time and date of application start-up, via the INFO call.
If the program needs the time of the DPUT call, it must be contained in the message.DPUT calls can also be used to implement periodically recurring asynchronous jobs. This is done with an asynchronous program containing the periodically recurring action as well as a DPUT call to the program itself. The time can be specified as relative or absolute.