ENQAR - Enqueue access request

General

Application area:	(Task) serialization; see "(Task) serialization"
Macro type:	Type S, MF format 1: standard/L/E form; see "S-type macros"

ENQAR generates either a 24-bit or a 31-bit interface, depending on the specification. In the event of macro chaining, all macros chained must make use of the same interface (either 24-bit or 31-bit interface).

Macro description

This macro requests access to the specified serialization item. The access request is entered in the queue of the serialization item and the program is placed in the wait state until it is the first in the queue. The program is then continued and uses the serialization item until a DEQAR macro is issued for this serialization item.
If there is no serialization item with the specified name in the defined scope, the serialization item is established and an implicit enable function (see the ENASI macro) is performed.The COND operand enables the user to specify whether the access request is to be performed unconditionally, or only if it can be satisfied immediately. The time for which a program will wait for an access request to be honored can be limited by means of the LIFETIM operand.
The CONTINU operand allows up to 255 ENQAR macros to be chained. Such a chain of macros will be processed only if all individual requests can be honored at the same time.

Macro format and description of operands

ENQAR

{ {SINAME=name / SINAMAD={addr / (r)} [,SINAMLN=length] }

,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} /

SIID={addr / (r)} }

,CONTINU=NO / YES

,COND=UNCOND / IMMED

[,LIFETIM=sec / (r)]

[,PARMOD=24 / 31]

[,MF=L / (E,..)]

SINAME=name

Specifies the name of the serialization item. This specification is unique only in conjunction with the SCOPE operand.

SINAMAD=
Specifies the address of the serialization item name. This name is unique only if the SCOPE operand is also specified.

addr
Symbolic address of the field containing the name.

(r)
Register containing the address.

SINAMLN=
Specifies the length in bytes of the serialization item name. The length must be at least 1 byte and not more than 54 bytes.
If the operand is missing, the length attribute of the SINAMAD operand is assumed if SINAMAD=addr is specified; if SINAMAD=(r), the maximum length (54) is assumed.

length
Length of the serialization item name.

SCOPE=
Specifies the scope of the serialization item (i.e. participants authorized to use it).

LOCAL
The use of the serialization item is limited to the calling task.

GROUP
All the tasks with the same user ID as the calling task are participants.

USER_GROUP
All the tasks, whose user IDs belong to the same user group as the user ID of the creating participant, can be participants.
The operand value assumes the existence of user groups and may therefore only be specified when the SRPM function unit of the SECOS software product is available in the system.

This is why the GETUGR macro (see the “SECOS” manual [14 (Related publications)]) has to check whether SRPM is available prior to a macro call with SCOPE=USER_GROUP. The program reaction is dependent on the result (return code).

GLOBAL
All the tasks in the system are participants.

SIID=

Specifies the ID of the serialization item. This ID is supplied to the user by the ENASI macro. If the ID is used instead of the name of the serialization item, processing is speeded up. The ID identifies the item uniquely.

addr
Symbolic address of a 4-byte field containing the ID.

(r)
Register containing the address.

CONTINU=
This operand allows up to 255 ENQAR macros to be chained.

NO
This is the last (or only) macro of a sequence.

YES
YES indicates that another ENQAR macro follows behind this macro.

COND=
Defines access request processing. If the request can be satisfied immediately, it is satisfied; if it cannot be satisfied immediately, the request is entered in the queue of the referenced serialization item. In this case, the calling program must wait until the complete request can be processed or until the waiting time specified by means of the LIFETIM operand has elapsed.
This operand may be used only in the last macro of a series of ENQAR macros chained by means of CONTINU; nevertheless it applies to the whole series.

UNCOND
The request is not subject to any conditions.

IMMED
The access request is processed only if the complete request can be satisfied immediately.

LIFETIM=
Specifies the time in seconds the task is to wait for the access requests to be processed. A return code indicates whether the request was satisfied or whether the maximum waiting time has elapsed.
The operand may be used only in the last macro of a series of ENQAR macros chained by means of CONTINU; nevertheless it applies to the whole series.

sec
Time in seconds. 1 sec <= wait time <= 43200 sec.
Processing precision for this macro is +10 seconds. Default setting: 600 seconds.

(r)
Register containing the time in seconds.

MF=

For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro or according to the default setting for the assembler (= 24-bit interface).

24
The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).

31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb). Data lists start with the standard header.

Notes on the macro call

• An implicit enable is performed when the calling task has not yet requested an explicit or implicit enable (see the ENASI macro) for this serialization item. However, an implicit enable does not cause an ID to be supplied.

• Each further explicit or implicit enable macro issued in a program for a serialization item that was specified earlier in an explicit enable and then disabled (see the DISSI macro) does not necessarily assign the same ID to this serialization item as the first enable macro.

• An enable performed as part of an ENQAR macro and the entry in the queue form one operation.

• If the same serialization item name was specified in two enable macros with different scopes, the system will process two different serialization items.

• When the list form of the macro (MF=E) is used, the following should be noted:Only one macro with MF=E is required for execution, regardless of whether the macro applies to one request or to a series of requests. In the case of a series of requests, the operand list is generated through macro chaining (MF=L) by means of the CONTINU operand.

Return information and error flags

Register R1 contains the operand list address.

R15:

+---------------+
|   |   |   |   |
|b|b| | | | |a|a|
+---------------+

A structured return code (aa=primary return code, bb=secondary return code) relating to the execution of the ENQAR macro is transferred in register R15.

X'bb'	X'aa'	Meaning
X'04'	X'00'	All enqueue requests were satisfied: At least one serialization item was established and assigned to the task of the calling program.
X'08'	X'00'	All enqueue requests were satisfied: At least one serialization item was assigned to the task of the calling program.
X'0C'	X'00'	All enqueue requests were satisfied: All serialization items were already assigned to the task of the calling program.
X'3C'	X'00'	All enqueue requests were satisfied: A DEQAR macro, issued by another task that was not the “holder” of the serialization item, has already been processed. This DEQAR macro was processed because HOLDER=ANY was specified. This return code has priority over all others with RS=X' 00' .
X'10'	X'04'	Not all enqueue requests were satisfied: Invalid operands were specified: invalid address (e.g. address within a DSECT) invalid length, invalid name, invalid LIFETIM value SCOPE, CONTINU or COND value undefined COND or LIFETIM specification entered for an item that is not the last in a series chained with CONTINU.
X'14'	X'04'	Not all enqueue requests were satisfied: An invalid ID was specified.
X'18'	X'04'	Not all enqueue requests were satisfied: The maximum number of serialization items which can be used simultaneously was exceeded.
X'1C'	X'04'	Not all enqueue requests were satisfied: The complete request could not be satisfied immediately (if COND=IMMED) within the waiting time (if COND=UNCOND).
X'24'	X'04'	Not all enqueue requests were satisfied: The calling program is already using the requested serialization item.

X'bb'	X'aa'	Meaning
X'40'	X'04'	Not all enqueue requests were satisfied: No class 5 memory was available for processing the request.
X'44'	X'04'	Not all enqueue requests were satisfied: A disable request for at least one serialization item was issued (by a contingency process with higher priority), while the enqueue request was still pending.