General
Application area: | (Optimized) eventing; see "Eventing" |
Macro type: | Type S, MF format 1: standard/L/E form; see "S-type macros" |
Forward Eventing (FEV) is an optimized form of synchronous eventing. FEV avoids the necessity for repeated validation of the specified operands when SOLSIG or POSSIG calls are issued repeatedly in a program. Instead, an event list (EVENTLST) is created and if, for example, signals are to be requested from an event item (using the SOLSIG function), a single SOLSIG entry is made in the list. In subsequent stages of the program, whenever a (real) receive request is issued (using RSOFEI) it will simply refer to the EVENTLST entry. The entry can be explicitly deleted again (using DELFEI).
A maximum of 2047 entries may be generated per participant in the EVENTLST. The task of the calling program must be assigned to the event item (by a preceding ENAEI).
Macro description
The macro DSOFEI creates a SOLSIG entry in the event list EVENTLST. All the necessary details are copied into the entry (name of the event item or ID, post code, maximum waiting time allowed for the signal (event) to occur. A reference number for the entry is passed to the caller.
Macro format and description of operands
DSOFEI |
{ { EINAME=name / EINAMAD={addr / (r)} [,EINAMLN=length] } ,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} / EIID={addr / (r)}} ,REFNUM={addr / (r)} [,LIFETIM={sec / (r)}] [, { RPOSTAD={addr / (r)} / RPOSTR=r }], RPOSTL={1 / 2}, RPOSTNUM={number / (r)} [,PARMOD={24 / 31}] [,MF={L / (E,..)}] |
EINAME=
Indicates that the name which follows is that which the caller assigned to the event item, using the macro ENAEI (note the interaction with the SCOPE operand).
name
Name of the event item.
EINAMAD=
Indicates that the address which follows is that of a field which contains the name of the event item (note the interaction with the SCOPE operand).
addr
Symbolic address of the field containing the name of the event item.
(r)
Register containing the address value “addr”.
EINAMLN=
Indicates that the length of the name of the event item follows.
If this operand is omitted, the length of the name is taken to be the same as for the field specified in EINAMAD=addr, or 54 bytes if EINAMAD=(r) was used.
length
Length of the name in bytes.
SCOPE=
Specifies the scope of the event item (i.e. participants authorized to use it). The name of the event item is unique only in combination with the scope. SCOPE must always be specified in conjunction with EINAME or EINAMAD.
LOCAL
Use of the event item is limited to the caller's task.
GROUP
All the tasks with the same user ID as the caller's 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.
EIID=
Specifies the location of the event item ID.
This event item ID is passed to the user when the macro ENAEI is executed. It provides a unique identifier for the event item; its use results in faster execution of the macro.
addr
Symbolic address of a 4-byte field containing the event item ID.
(r)
Register containing the address value “addr”.
REFNUM=
Indicates that the address which follows identifies a field in which the caller is to receive the reference number for the entry in the EVENTLST.
Field length = 4 bytes; aligned on a word boundary.
addr
Symbolic address of the field into which the reference number is to be put.
(r)
Register containing the address value “addr”.
LIFETIM=
Can be used to specify a time interval (in seconds), which is the maximum time that the task of the calling program should wait for the occurrence of the event (signal). Termination of the wait may be delayed by up to +10 seconds.
sec
Time specification in seconds. 1 <= sec <= 43200.
Default value: sec = 600.
(r)
Register containing the value of “sec”.
RPOSTAD=
Indicates that the address which follows is for a field in which a post code may be entered (see the macro POSSIG).
The post code has a length of 4 or 8 bytes. The RPOSTL operand determines whether both words of the post code or just the 1st word are to be transferred to this field.
The operand RPOSTR permits the same function as RPOSTAD to be executed more rapidly.
addr
Symbolic address of the field in which the post code is to be entered. Field length = 4 or 8 bytes.
(r)
Register containing the address value “addr”.
RPOSTR=
Specifies a register in which the post code it to be entered directly. A post code consisting of 2 words is entered in the specified register and the one following it (in number) if RPOSTL=2 is specified.
r
Register to receive the post code.
RPOSTL=
Gives the number of words to be received as post code.
1
Only one word (the first) of the post code is to be transferred.
2
The complete post code (= 2 words) is to be transferred.
RPOSTNUM=
Specifies the maximum number of post codes which are to be transferred. The range specified for RPOSTAD must be large enough to be able to receive all post codes. Required length: RPOSTNUM*2+1 (1 byte indicator X'FF', end of list).
number
Number of post codes to be transferred.
(r)
r = register with the number of post codes to be transferred.
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 execution of the macro, register R1 contains the address of the operand list; register R0 is overwritten.
R15:
+---------------+ | | | | | |b|b| | | | |a|a| +---------------+
A structured return code (aa=primary return code, bb=secondary return code) relating to the execution of the DSOFEI macro is transferred in register R15.
X'bb' | X'aa' | Meaning |
X'00' | X'00' | Normal execution. A SOLSIG entry has been created. All the specified operands |
X'04' | X'04' | No action taken: the permitted maximum of 2047 calls has been exceeded. |
X'0C' | X'04' | No action taken: the event item is not enabled for the task of the calling program. |
X'10' | X'04' | No action taken: invalid operand specified. |
X'14' | X'04' | No action taken: there is no event item with the specified name or ID. |