QCRE Create temporary queue

The QCRE (queue create) call is used to create a temporary queue dynamically.

The prerequisite for a successful QCRE call is that enough table spaces for QUEUE objects must have been reserved at generation by means of the QUEUE statement.

In the QCRE call you can either assign a name for the queue to be created or specify that openUTM assigns a name automatically, which is then entered in the KCRQN (queue name) return field.
openUTM creates queue names that follow on from each other from printable digits. If the queue names are assigned by openUTM, the same queue name is not used again for 100 million QCRE calls. This ensures that long-running services for communication do not inadvertently use a temporary queue whose name has been reassigned after being deleted.

The format of the QCRE call is described in detail below. You will find more information on the subject of “message queuing“ in section "Message Queuing (asynchronous processing)".

Setting the KDCS parameter area (1st parameter)

The following table shows the entries required in the KDCS parameter area.

Function of the call	Entries in the KDCS parameter area
	KCOP	KCOM	KCRN	KCLA	KCMF/kcfn	KCQMODE
Create queue without name	"QCRE"	"NN"	Blanks	Queue level	Blanks	"S" / "W" / binary zero
Create queue with name	"QCRE"	"WN"	Queue name	Queue level	Blanks	"S" / "W / binary zero

Setting the parameters
Field name in the KDCS parameter area	Contents
KCOP	"QCRE"
KCOM	"NN"/"WN"
KCRN	Blanks / name of the queue
KCLA	Queue level of the queue
KCMF / kcfn	Blanks
KCQMODE	"S" / "W" / binary zero

KDCS call
1st parameter
KDCS parameter area

C/C++ macro call
Macro names	Parameters
KDCS_QCRENN	(kcla,qmode)
KDCS_QCREWN	(kcla,kcrn,qmode)

openUTM return information
Field name in the KB return area	Contents
KCRQN	Name assigned by openUTM
KCRCCC	Return code

In the KDCS parameter area you make the following entries for the QCRE call:

KCOP

In the KCOP field, enter the QCRE operation code.

KCOM

In the KCOM field:

• NN (no name)
  if openUTM is to create the name of the queue automatically

• WN (with name)
  if you assign the name yourself

KCRN

In the KCRN field, enter the name of the queue (KCOM=WN) or blanks (KCOM=NN). A name you assign must not begin with a digit and must adhere to the conventions for generatable names. In other words, it can consist only of the characters A...Z, a...z, 0...9, $, #, @. If necessary, it must be filled with blanks.

KCLA

In the KCLA field, enter the queue level. In other words, you enter the maximum number of messages that can be stored in this queue.
If you specify zero, openUTM uses the value or default value of the QLEV parameter from the QUEUE statement of the generation.

KCMF / kcfn

The KCMF/kcfn field must be supplied with blanks.

KCQMODE

In the KCQMODE field:

• S (standard)
  if further messages are to be rejected when the queue level is reached

• W (wrap)
  if a new message overwrites the oldest existing message when the queue level is reached

• Binary zero
  openUTM uses the value or default value of the QMODE parameter from the QUEUE statement of the generation.

In the KDCS call, specify:

1st parameter

The address of the KDCS parameter area.

Macro names

How to use macro calls for C/C++ is described in detail in the section "C/C++ macro interface".

openUTM returns:

KCRQN

in the KCRQN field the name generated automatically (when KCOM=NN).

KCRCCC

in the KCRCCC field the KDCS return code (see next page).

KDCS return codes in the KCRCCC field for the QCRE call

The following codes can be analyzed in the program:

000	The operation was executed.
16Z	KCOM=WN: The queue name already exists. KCOM=NN: openUTM could not find a free name. In this case, you can try to find a free queue name with another QCRE NN call. Note on name assignment: openUTM assigns names consisting only of digits and remembers the last name it assigned. When QCRE is specified with KCOM=NN, openUTM searches the next 100 names consisting of digits for a free entry. If these names are all occupied, openUTM terminates the search with 16Z. At the next QCRE NN call, the next 100 names are searched.
40Z	The operation cannot be executed because: there is no free table space left for temporary queues (what to do: increase the value for NUMBER in the QUEUE statement and regenerate, or use QREL to delete temporary queues that are no longer required). because there is no free table space left in the process-specific buffer for restart data (what to do: increase the value of MAX RECBUF=(..., length) and regenerate).
42Z	The value in KCOM is invalid.
43Z	The value in KCLA (queue level) is negative or invalid.
44Z	The queue name begins with a digit (KCOM=WN), or KCRN does not contain any blanks (KCOM=NN).
45Z	KCMF/kcfn was not supplied with blanks.
46Z	The value in KCQMODE is invalid.
49Z	Unused fields have a value other than binary zero.

An additional return code can be found in the dump: 

71Z	An INIT has not yet been called in the program unit run.

Features of the QCRE call

• No administration authorization is required to create a temporary queue.

• If the queue names are assigned by openUTM, they are not used again for 100 million QCRE calls.

• If a temporary queue is created with QCRE, messages can be written in this queue in the same transaction. However, these messages cannot be read and administered until the transaction is successfully completed.

• In the case of UTM-S, temporary queues and their messages are preserved after the end of the application run until they are deleted explicitly by means of a QREL call.In the case of UTM-F, temporary queues are deleted automatically at the end of the application run. All the messages still stored in the queue are lost.