DADM Administer message queues

The DADM (delayed free message administration) call provides the following functions for administering message queues that enable you:

• to read summary information about messages in a message queue into the message area (user identification, job identification (job ID), creation time, starting time and existing confirmation jobs, original destination ...)

• to read user information into the message area that has been generated with DPUT NI/QI/+I/-I. The user information can only be read if the confirmation job becomes the main job.

• to change the processing order of messages in a message queue

• to delete individual messages or all the messages from the message queue

• to assign either selected messages or all messages in the dead letter queue each to their original destination or to a new destination

Unix, Linux and Windows systems
In a UTM cluster application you can only administer message queues of the local node application.

The format of the DADM call is discussed in detail below. For further information on the administration of the message queue refer to the openUTM manual “Administering Applications”.

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	KCLA	KCRN	KCLT	KCQTYP	KCMOD	Time1
Read overview information	"DADM"	"RQ"	54	Job ID / blank	LTERM/(OSI-)LPAP/TAC	Binary zero	Binary zero	Binary zero
					Queue	"Q"/"U"
Read user information	"DADM"	"UI"	Length	Job ID	Binary zero	Binary zero	Binary zero	Time point (absolute)
Change order	"DADM"	"CS"	0	Job ID	Binary zero	Binary zero	Binary zero	Time point (absolute)
Delete individual message from a queue	"DADM"	"DL"	0	Job ID	LTERM/(OSI-)LPAP/TAC	Binary zero	"C"/"N"	Time point (absolute)
					Queue	"Q"/"U"
Delete all messages from a queue	"DADM"	"DA"	0	Blank	LTERM/(OSI-)LPAP/TAC	Binary zero	Binary zero	Binary zero
					Queue	"Q"/"U"
Move single message	"DADM"	"MV"	0	Job ID	TAC/LPAP/OSI-LPAP/Blank	Binary zero	Binary zero	Time point (absolute)
Move all messages	"DADM"	"MA"	0	Blank	TAC/LPAP/OSI-LPAP/Blank	Binary zero	Binary zero	Binary zero

¹ The time point is specified in the fields KCTAG/kcday, KCSTD/kchour and KCMIN.

All fields of the parameter areas not in use must be assigned the value binary zero.

Setting the 2nd parameter

Here you have to supply the address of the message area into which openUTM is to read the message. A language-specific data structure enables you to structure the message area when calling DADM RQ, in COBOL this is the KCDADC COPY element and in C/C++ the kcdad.h include file.

Setting the parameters
Field name in the KDCS parameter area	Contents
KCOP	"DADM"
KCOM	"RQ"/"UI"/"CS"/"DL"/"DA"/"MV"/"MA"
KCLA	Length in bytes/0
KCRN	Job ID/blanks
KCLT	LTERM name / TAC / (OSI-)LPAP name / queue /binary zero / blanks
KCTYP	Destination type:"Q"/"U"/binary zero
KCMOD	"C"/"N"/binary zero
KCTAG / ...	Time specification  (absolute)
KCTAG/kcday	Day (absolute)/binary zero
KCSTD/kchour	Hour (absolute)/binary zero
KCMIN	Minute (absolute)/binary zero
KCSEK/kcsec	Second (absolute)/binary zero

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

C/C++ macro calls
Macro names	Parameters
KDCS_DADMRQ	(nb,kcla,kcrn,kclt)
KDCS_QADMRQ	(nb,kcla,kcrn,kclt,kcqtyp)
KDCS_DADMUI	(nb,kcla,kcrn,kcday,kchour,kcmin,kcsec)
KDCS_DADMCS	(nb,kcrn,kcday,kchour,kcmin,kcsec)
KDCS_DADMDL	(nb,kcrn,kclt,kcmod,kcday,kchour,kcmin,kcsec)
KDCS_QADMDL	(nb,kcrn,kclt,kcmod,kcday,kchour,kcmin,kcsec,kcqtyp)
KDCS_DADMDA	(nb,kclt)
KDCS_QADMDA	(nb,kclt,kcqtyp)
KDCS_DADMMV	(nb,kcrn,kclt,kcday,kchour,kcmin,kcsec,kcqtyp)
KDCS_DADMMA	(nb,kclt,kcqtyp)

openUTM return information
Message area	Contents
	Data
Field name in the KB return area
KCRLM	Actual length
KCRCCC	Return code
KCRCDC	Internal return code
KCRMF / kcrfn	Job ID/blanks

For the DADM call you make the following entries in the appropriate fields of the KDCS parameter area:

KCOP

In the KCOP field, enter the DADM operation code.

KCOM

In the KCOM field, select the operation modifier:

• RQ to read the overview information on a message queue

• UI to read the user information of a main job created by means of DPUT NI/QI

• CS to give preference to a specific message

• DL to delete a single message

• DA to delete all messages in the message queue

• MV to move a single message from the dead letter queue into either the original message queue, any asynchronous TAC, any TAC queue, an LPAP partner or an OSI-LPAP partner.

• MA to move each message from the dead letter queue. In this case, you have two possibilities:

  • Moving into their original message queues

  • Move all messages with the original destination TAC, LPAP or OSI-LPAP to any other destination of the same type (asynchronous TAC/TAC queue, LPAP partner or OSI-LPAP partner).
    Messages whose original type is not the same as the new destination remain in the dead letter queue.
    To move all messages, up to three calls with new destinations of the type TAC, LPAP and OSI-LPAP are therefore required.

KCLA

In the KCLA field, enter the length of the data to be transferred to the message area. For KCOM = RQ enter 54, for KCOM = CS/DL/DA/MV/MA enter 0.

KCRN

In the KCRN field, specify the message in the queue to be administered. The following specifications are required:

• blanks
  if KCOM = DA/MA or if KCOM = RQ and the call refers to the first message in the queue

• the job ID
  if KCOM = UI/CS/DL/MV or if KCOM = RQ and the call refers to the subsequent messages in the queue. The job ID is always returned to the KCRMF/kcrfn field in the preceding DADM RQ.

KCLT

In the KCLT field, identify the queue. That means:

• If KCOM = RQ/DL/DA, specify:

  • the LTERM name if the message was for an LTERM partner

  • the (MASTER-)(OSI-)LPAP name if the messages was for an (OSI-)LPAP partner

  • the TAC if the message was for an asynchronous program

  • the name of the queue if you want to administer messages of a USER queue, a TAC queue or a temporary queue

• If KCOM = UI/CS, specify binary zero.

• If KCOM = MV/MA, specify the following:

  • the TAC, if the single message or all messages with original target TAC or TAC queue are to be directed to an asynchronous program,

  • the name of a TAC queue, if the single message or all messages with original target TAC or TAC queue are to be directed to a service-controlled queue,

  • the name of an LPAP partner (but not a MASTER-LU61-LPAP), if the individual message or all messages with the original destination LPAP are to be sent to an LPAP partner,

  • the name of an OSI-LPAP partner (but not a MASTER-OSI-LPAP), if the individual message or all messages with the original destination OSI-LPAP are to be sent to an OSI-LPAP partner,

  • blank, if the single message or all messages are each to be assigned back to their original destination.

  All messages whose original target does not match the new target are remaining in the dead letter queue

KCQTYP

In the KCQTYP field, specify the type of the queue:

• If KCOM = RQ/DL/DA, specify:

  • binary zero, if the queue belongs to an LTERM, an (OSI-)LPAP or a TAC, or if it is a TAC queue,

  • Q in the case of a temporary queue created with QCRE,

  • U in the case of a USER queue.

• If KCOM=UI/CS/MV/MA enter binary zero.

KCMOD

In the KCMOD field, specify whether openUTM should activate the negative confirmation job when a job complex is deleted. The following values are possible:

• binary zero, if KCOM = RQ/UI/CS/DA/MV/MA,

• C to delete the complete job if KCOM = DL; in the case of job complexes all the confirmation jobs are deleted also,

• N to activate the negative confirmation job if KCOM = DL; the message itself is deleted.

KCTAG / ...

If KCOM = UI/CS/DL/MV, enter the time the message was generated as follows: in the KCTAG/kcday field, the day in the year (working day, value 001 to 366), in KCSTD/kchour the hour, in the KCMIN field the minute and in KCSEK/ kcsec the second. This time can be ascertained before with DADM RQ.

If KCOM = RQ/DA/MA enter binary zero.

For the KDCS call you enter:

1st parameter

The address of the KDCS parameter area

2nd parameter

The address of the message area into which openUTM is to read the message. You have to enter the address even if you have entered 0 in KCLA.

Macro names

The use of C/C++ calls is described in detail in section "C/C++ macro interface".

openUTM returns:

If KCOM = RQ/UI: the message in its actual or at most in its desired length in the specified message area.

KCRLM

In the KCRLM field: the actual length of the message, possibly deviating from the length requested in KCLA of the parameter area.

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”).

KCRMF / kcrfn

In the KCRMF/kcrfn field: if KCOM = RQ the job ID of the next message in the queue (see KCLT) or blanks for the last message in the queue.

KDCS return codes in the KCRCCC field for the DADM call

The following codes can be analyzed in the program:

000	Operation executed (if KCOM = RQ/UI) or the administration job accepted (if KCOM = CS/DL/DA/MV/MA). The real execution is not determined until the end of the transaction. A decision about actual execution is not made until the end of the transaction (see "Features of the DADM call").
01Z	Length conflict: KCLA < KCRLM, the message is truncated.
07Z	Not all messages from the dead letter queue could be moved because the task-specific buffer area generated for the restart information is too small, see openUTM manual “Generating Applications” "Restart area". Action: Generation with KDCDEF, defining a larger buffer area with MAX RECBUF=(...,length), or repeating the DADM call.
40Z	The system cannot perform the operation (generation error or system error, original destination no longer exists, no administration privileges, locked by another service), see KCRCDC.
42Z	Entry in KCOM invalid.
43Z	Length specified in KCLA is negative or invalid.
44Z	Job ID specified in KCRN is invalid.
46Z	Entry in KCLT is invalid. Possible causes: The specified LTERM or (MASTER-)(OSI-)LPAP name does not exist. The TAC is invalid or locked. The TAC is not a process TAC or a dialog TAC. There is no USER queue or temporary queue with the specified name, or the type specified in KCTYP does not fit the queue name. with KCOM=MV/MA: an LTERM name, master LU61-LPAP name or master OSI-LPAP LPAP name was specified, the specified TAC has been deleted or KDCMSGTC or KDCDLETQ was specified. with KCOM=MV: blanks were specified but the original destination of the message has been deleted. with KCOM=MV: The types of the original target and the new target do not match,i.e.: original target: TAC or TAC- queue, new target LPAP or OSI-LPAP original target: LPAP, new target TAC or TAC queue or OSI-LPAP original target: OSI-LPAP, new target TAC or TAC queue or LPAP
47Z	Message area missing or cannot be written in the specified length.
49Z	Contents of unused fields of KDCS parameter area not equal to binary zero.
56Z	Value in KCMOD or time entry in KCTAG/kcday, KCSTD/kchour, KCMIN or KCSEK/ksec is invalid.

An additional return code can be found in the dump:

71Z	INIT missing in this program.

Return information in the message area for DADM RQ

There is a data structure available for the return information for the DADM RQ call, for COBOL the KCDADC COPY element and for C/C++ the kcdad.h include file. This data structure can be used to define the message area and has the following structure:

Byte	Field name COBOL/C/C++	Meaning
1 - 8	KCDAGUS	UTM user ID of the job submitter
9 - 16	KCDADPID	Job ID (assigned by UTM)
17 - 25	KCDAGTIM1	Time of the FPUT/DPUT call in the form dddhhmmss:
17 - 19	KCDAGDOY	ddd	Day in the year (value range 000 - 366)
20 - 21	KCDAGHR	hh	Hour (value range 00 - 23)
22 - 23	KCDAGMIN	mm	Minute (value range 00 - 59)
24 - 25	KCDAGSEC	ss	Second (value range 00 - 59)
26 - 34	KCDASTIM1	For time-delayed jobs enter the desired starting time in the form dddhhmmss:
26 - 28	KCDASDOY	ddd	Day in the year (value range 000 - 366)
29 - 30	KCDASHR	hh	Hour (value range 00 - 23)
31 - 32	KCDASMIN	mm	Minute (value range 00 - 59)
33 - 34	KCDASSEC	ss	Second (value range 00 - 59)
		For a job without time delay blanks are returned.
35	KCDAPMSG	Y	positive confirmation job exists
		N	no positive confirmation job exists
36	KCDANMSG	Y	negative confirmation job exists
		N	no negative confirmation job exists
37 - 44	KCDADEST	Destination of the message or the original destination for dead letter queue
45	KCDATYPE	Type of the message destination or type of original destination for dead letter queue
		Q	for temporary queue
		U	for USER queue
		T	for TAC queue
		A	for asynchronous TAC
		L	for LTERM
		P	for LPAP
		O	for OSI-LPAP
46 - 53	KCDAFCTM	Generation time or time DPUT converted to FPUT in the message. In the case of service-driven queues, the messages displayed with DADM RQ can be unambiguously assigned to the messages read with DGET BF. KCDADPID or KCDAFCTM must correspond to the return values KCRDPID or KCRGTM of the corresponding DGET BF call.
54	KCDAGUST	Type of the submitter
		U	for user
		S	for LU6.1 session
		O	for OSI association

¹ For C/C++, the KCDAGTIM and KCDASTIM summary fields are not defined. However the specific fields for day/hour/minute/second are defined.

Features of the DADM call

• Ascertaining the job ID

  The job ID is assigned internally by UTM. It can be ascertained in the program unit as follows with a DADM RQ call: for the first DADM RQ call (with KCRN = blanks) openUTM supplies information on the first message in the queue. On this occasion openUTM writes the job ID amongst other things to the message area. If there are more messages for the queue in the message queue, openUTM in each case returns the job ID of the next message to KCRMF/kcrfn. When the last message in the queue is reached, openUTM enters blanks in the KCRMF/kcrfn field.

• DADM CS/DL/DA/MV/MA calls (change order, delete or move) are transaction-logged and are not executed until the end of the transaction. After such a call, therefore, KCRCCC = 000 does not necessarily guarantee that the call can be executed successfully, because the message in the queue could be deleted in the meantime by another DADM call. You can check whether a DADM CS/DL/DA/MV/MA call has been successful by issuing a DADM RQ call in a subsequent transaction.

• The DADM CS call puts the relevant message in first position in the queue. In the case of time-driven messages whose starting point has not yet been reached, the call is rejected with 40Z.

• After a delete job with DADM DL/DA no more delete jobs can be submitted within the same transaction and no DADM CS call; openUTM rejects this with 40Z.

• Jobs that are currently being processed cannot be administered. This applies, for example, if messages in a USER queue or a temporary queue are currently being read. If these jobs are destined for printers, printing can be stopped by means of a PADM call.

• A program unit which issues a DADM call must be running under a user ID with administration privileges, otherwise openUTM acknowledges the DADM call with 40Z. There is the following exception:
  If a service is started from a printer control LTERM and if only such jobs are administered which are directed to printers of the printer control LTERM, then neither the program unit nor the user need the administration privileges.

• The dead letter queue consists of messages that could not be processed. To be able to process these messages, possibly after eliminating the error, they must either be assigned to their original destination or to a new destination with the same type. You can use DADM MV to move a single message or DADM MA to move all messages from the dead letter queue into a specific queue or the original queue. In this case, there are two possibilities:

  • Move to the relevant initial message queue(s).

  • Move the message or all messages with the original destination TAC (asynchronous TAC or TAC queue), LPAP or OSI-LPAP to any other destination of the same type.

  A previously defined QLEV and the STATUS of the recipient queue is thereby ignored.

  With DADM MA, messages are remaining in the dead letter queue in the following cases without this is indicated by a return code:

  • KCLT = blank: All messages whose original destination no longer exists.

  • KCLT != blank: All messages whose original destination does not match the new destination. Messages whose original destination no longer exists only match the new destination asynchronous TAC or TAC queue.