DPUT call in a job complex

A DPUT call within a job complex enables you to

• send time-driven messages (so-called basic jobs) and the associated messages/message segments (output jobs for LTERM partners or for asynchronous services, messages to TAC queues or background jobs to asynchronous services or TAC queues previously addressed with an APRO AM call)

• have user information associated with these jobs logged

• generate confirmation jobs and associated user information.

Setting the KDCS parameter area (1st parameter)

The table below shows the various options and corresponding entries in the KDCS parameter area.

Function of the call	Entries in the KDCS parameter area
	KCOP	KCOM	KCLM	KCRN	KCMF	KCDF
Basic job for LTERM partner or for local asynchronous service or local TAC queue	"DPUT"	"NT"/"NE"	Length	Complex ID	Format ID / blanks/ name of abstract syntax / edit profile (only BS2000 systems)	Screen function / binary zero
Basic job for TAC queue	"DPUT"	"QT"/"QE"	Length	Complex ID	——
Basic job for remote asynchronous service or remote TAC queue	"DPUT"	"NT"/"NE"	Length	Complex ID	——
User information for a job	"DPUT"	"NI"/"QI"	Length	Complex ID	Blanks	binary zero
Create confirmation job	"DPUT"	"+T"/"-T"	Length	Complex ID	Blanks	binary zero
User information for confirmation job	"DPUT"	"+I"/"-I"	Length	Complex ID	Blanks	binary zero

The operation modifiers in the KCOP field have the following significance:

NT/QT: message segment of a basic job
NE/QE: last message segment or total message of a basic job
NI/QI: user information associated with basic job
+T/-T: positive or negative confirmation job
+I/-I: user information associated with positive or negative confirmation job

The QE/QT/QI operation modifiers refer to a basic job with a TAC queue as the destination. It is not possible to specify a USER or temporary queue as the destination in the DPUT call in the job complex, because KCQTYP is not evaluated here and the destination is specified for the associated MCOM call.

The time entries for DPUT NT/NE/NI or DPUT QT/QE/QI are made as for the DPUT call without job complex. For DPUT NI/QI/+T/-T/+I/-I you have to set binary zero in all the unused fields of 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 or user information.

Setting the parameters
Field name in KDCS parameter area	Contents
KCOP	"DPUT"
KCOM	"NT"/"NE"/"NI"/"QT"/"QE"/"QI"/"+T"/"-T"/ "+I"/"-I"
KCLM	Length in bytes
KCRN	Complex identifier
KCMF/kcfn	Format ID / blanks / name of abstract syntax / name of edit profile (only BS2000 systems)
KCDF	Screen function / binary zero
KCMOD	""R"/"A"/"?"/binary zero
KCTAG / ...
KCTAG/kcday	Day (rel./abs.)/"?"/binary zero
KCSTD/kchour	Hour (r./a.)/"?"/binary zero
KCMIN	Minute (r./a.)/"?"/binary zero
KCSEK/kcsec	Second (r./a.)/"?"/binary zero
KCQTYP	irrelevant (not evaluated)
Message area
	Data

KDCS call
1st parameter	2nd parameter
KDCS parameter area	Message area

C/C++ macro calls
Macro names	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_DPUTPT / KDCS_DPUTMT / KDCS_DPUTPI / KDCS_DPUTMI	(nb,kclm,kcrn)

openUTM return information
Field name in the KB return area	Contents
KCRCCC	Return code
KCRCDC	Internal return code

For the DPUT call within a job complex 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/QT for message segment of the basic job

• NE/QE for total message or last message segment of the basic job

• NI/QI for user information associated with the basic job

• +T for a positive confirmation job

• –T for a negative confirmation job

• +I for user information relating to the positive confirmation job

• –I for user information relating to the negative confirmation job

The QE/QT/QI operation modifiers refer to a basic job with a TAC queue as the destination.

KCLM

In the KCLM field, specify the length of the message to be sent (length zero is permissible).

KCRN

In the KCRN field, enter the complex identifier (complex ID) assigned to the job complex (assigned in the MCOM call).

KCMF/kcfn

In the KCMF/kcfn (irrelevant for messages sent to an asynchronous service of the same application or to an LU6.1 partner):

• Blanks in line mode or for a job sent to another application without distributed processing.

In 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.

• 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, enter the screen function for output jobs to terminals. Enter binary zero for user information (KCOM = NI/QI) or jobs for transport system applications.

This field is irrelevant for background jobs and messages to TAC queues.

On BS2000 systems, you must also specify binary zero if an edit profile or a #format is entered in KCMF/kcfn.

KCMOD

In the v field, you select the type of time entry for messages to the basic job (KCOM=NT/NE/NI or QT/QE/QI):

• A for absolute

• R for relative

• blanks, if the job is to be executed without wait time

Binary zero must be entered for messages to confirmation jobs (KCOM = +T/-T/+I/-I).

KCTAG / ...

For KCOM = NT/NE/NI or QT/QE/QI enter the necessary time specifications as for the DPUT call without job complex in these fields. For KCOM = +T/-T/+I/-I enter binary zero.

KCQTYP

The KCQTYP field is not evaluated.

Message area

Make the following entry in the message area:
the message or user information 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 DPUT call in a 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). openUTM takes the time entry from the first DPUT call and continues the message
40Z	openUTM cannot perform the function, see entry in KCRCDC. For distributed processing: there is no logical connection to the partner application and KCMOD = "'BLANK'".
41Z	The call is not allowed at this location: an additional basic job is to be issued or user information is to be logged after a basic job (DPUT NE/QE) has been completed or the format identifier changes due to several DPUT NTs or the call was initiated in the first part of the sign-on service or the call was initiated in the sign-on service after a SIGNON call and before the PEND PS call.
42Z	The entry in KCOM is invalid or KCOM = +T/-T was specified without defining a job complex or destination for the confirmation job
43Z	The length entry in KCLM is negative or invalid.
44Z	The complex identifier given in KCRN is invalid.
45Z	The entry in KCMF/kcfn is invalid. Possible causes: the format identifier in KCMF/kcfn is invalid if the message destination is a partner with which communication is performed using the OSI TP protocol, this return code indicates that the abstract syntax specified in the KCMF/kcfn field has not been generated for the partner application. Only on BS2000 systems: the edit profile has not been generated the edit profile changes in message segments
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	Incorrect DPUT call sequence (see below).
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 timespan.

An additional return code can be found in the dump:

71Z	INIT call missing in this program.

Features of the DPUT call within a job complex

• The following rules hold for the order of the DPUT calls:

• • the user information has to be written before the associated (confirmation) job: DPUT NI before DPUT NT/NE or DPUT QI before DPUT QT/QE, DPUT +I before DPUT +T and DPUT -I before DPUT -T. Only one DPUT +I/-I per DPUT +T/-T is permitted. The user information of a confirmation job cannot be read until the confirmation job has been activated.

  • the basic job must be started before the first confirmation job: DPUT NT/NE or DPUT QT/QE before the first DPUT +T/-T. Two or more DPUT +T or DPUT -T are permissible; these are considered in each case as one positive confirmation job (with +T) and one negative confirmation job (with -T).

• Changing the format identifier if there are more than one message segments (DPUT NT) is not permissible.

• If a DPUT call has return code 40Z all the messages and information associated with the job complex are lost; the complex ID is released.

  For DPUT messages via distributed processing the service ID is also released with 40Z.

  For all other return codes smaller than 70Z all the data of the complex is kept including the complex ID.

• Parallel asynchronous jobs (i.e. change of destination before DPUT NE/QE) are permitted if the destinations belong to different categories, i.e. it is possible to have a DPUT with KCRN = LTERM/TAC/Queue or KCRN = VGID before the DPUT NE.

  Example for parallel asynchronous jobs

  KDCS call	Destination and identifier	Remarks
  MCOM BC	KCRN = PRINTER1 KCCOMID = *COMPLEX KCPOS = ATAC5	Define start of a job complex and destinations of the job
  DPUT NT	KCRN = *COMPLEX	1st message segment of basic job
  DPUT NE	KCRN = ATAC1	Background job for a program
  APRO AM	KCRN = LTAC KCPA = APPL1 KCPI = > VGID	Address job-receiving service
  DPUT NE	KCRN = > VGID	Background job for job-receiving service
  DPUT NE	KCRN = *COMPLEX	2nd message segment of basic job
  DPUT +T	KCRN = *COMPLEX	Positive confirmation job
  MCOM EC	KCRN = binary zero KCCOMID = *COMPLEX	End of job complex