General
Application area: | Eventing; see "Eventing" |
Macro type: | Type S, MF format 1: standard/L/E form; see "S-type macros" |
Macro description
The ENAEI macro allows a task to establish an event item. If an event item with the specified name already exists in the defined scope (established by an ENAEI macro call in another task), the macro only causes the event item to be assigned to the task of the calling program. Otherwise the event item is established and assigned by the system.
A call to this macro also makes available an ID for the event item; this ID can be used in subsequent calls, to speed up processing.
A program can use up to 2000 event items simultaneously.
Macro format and description of operands
ENAEI |
{ EINAME=name / EINAMAD={addr / (r)} [,EINAMLN=length] } ,SCOPE=LOCAL / GROUP / USER_GROUP / GLOBAL ,EIIDRET=addr / (r) ,SOSIGQ=FIFO / LIFO [,PARMOD=24 / 31] [,MF=L / (E,..)] |
EINAME=
Specifies the name of the event item.
name
Name of the event item. 1 <= name length <= 54.
Name format:
1st character: letter, #, @;
2nd through 54th character: any combination of characters from the
character set (A,...,Z,0,...,9,$,#,@).
The first blank (X'40') terminates the name.
EINAMAD=
Specifies the address of a field containing the name of the event item (for name format see above).
addr
Symbolic address (name) of the field.
(r)
Register containing the “addr” address value.
EINAMLN=
Specifies the length of the event item name if EINAMAD=... was specified.
length
Length of the name in bytes.
Default setting:
length attribute of the field specified with EINAMAD=...
54 bytes if EINAMAD=(r) was specified.
SCOPE=
Specifies the scope of the event item (i.e. the participants authorized to use it).
LOCAL
the use of the event 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.
EIIDRET=
Specifies the address of a field where an ID of the event item is entered.
addr
Symbolic address (name) of the field to hold the ID. Field length = 4 bytes. The field should be aligned on a word boundary.
(r)
Register containing the “addr” address value.
SOLSIGQ=
Specifies the queueing method to be used for SOLSIG requests. All ENAEI macros having a given event item must define the same queueing method for SOLSIG requests.
FIFO
FIFO = first in - first out
LIFO
LIFO = last in - first out
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).
Return information and error flags
During macro processing, 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 ENAEI macro is transferred in register R15.
X'bb' | X'aa' | Meaning |
X'04' | X'00' | Function executed: the event item was established by the system and assigned to |
X'08' | X'00' | Function executed: an event item already established by the system was assigned |
X'0C' | X'04' | No action taken: the event item had already been assigned to the task of the calling |
X'10' | X'04' | No action taken: invalid operands were specified. |
X'18' | X'04' | No action taken: the maximum number of event items which can be used |
X'1C' | X'04' | No action taken: event item specifications (FIFO and LIFO) do not agree for |
For examples, see the sections “Eventing” ("Eventing") and “Contingency processes” ("Contingency processes") and also the POSSIG ("POSSIG - Post signal request") and SOLSIG macro description ("SOLSIG - Solicit signal request").