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 POSSIG or SOLSIG calls are made repeatedly in a program. Instead, an event list (EVENTLST) is created and if, for example, signals are to be sent to an event item (using the POSSIG function), a single entry is made in the list. In subsequent stages of the program when (real) send requests are issued, they will simply reference this entry each time (using RPOFEI). The entry may 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 (using ENAEI).
Macro description
The macro DPOFEI creates a POSSIG entry in the event list EVENTLST. All the necessary details are copied into the entry (name of the event item or event item ID, post code, maximum time for collecting the signal (event)). A reference number for the entry is passed back to the caller.
It is possible to chain together several consecutive calls to DPOFEI. The chain can also be terminated using the macro DSOFEI. When using a chain, note that:
DSOFEI must always appear as the last macro in the chain.
The first macro call which results in an error will terminate the chain; any entries already created will be deleted.
The operand REFNUM (for communicating the reference number) may only be specified in the first macro call in the chain.
A maximum of 5 macro calls may be chained together. All macros in the chain must use the same interface format.
Macro format and description of operands
DPOFEI |
{ {EINAME=name / EINAMAD={addr / (r)} [,EINAMLN=length] } ,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} / EIID={addr / (r)}} [,REFNUM=addr / (r)] [, {SPOSTAD={addr / (r)} / SPOSTR=r}] ,SPOSTL=1 / 2 ,CONTINU=NO / YES / DSOFEI [,LIFETIM=sec / (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 reference number for the EVENTLST entry is passed to the caller.
Field length = 4 bytes; aligned on a word boundary.
addr
Symbolic address of the field in which the reference number is to be stored.
(r)
Register containing the address value “addr”.
SPOSTAD=
Indicates that the address which follows is for a field containing a post code which is to be sent to the receiver of the signal (see the macro SOLSIG or DSOFEI).
The post code has a length of 4 or 8 bytes. Field length = 4 or 8 bytes; aligned on a word boundary.
A post code in the form X'00000000' will not be sent. The operand SPOSTR permits the same function to be executed more rapidly.
addr
Symbolic address of the field containing the post code.
(r)
Register containing the address value “addr”.
SPOSTR=
Indicates a register which (directly) contains the post code. If the 8-byte post code
(=2 words) is used, the register following the specified register (in number) must contain the second word of the post code. A post code in the form X'00000000' will not be sent.
r
Register containing the post code.
SPOSTL=
Gives the post code length in words.
1
Post code length = 1 word (=4 bytes).
2
Post code length = 2 words.
CONTINU=
Enables the DPOFEI macro to be chained with other, immediately succeeding DPOFEI or DSOFEI calls.
NO
No further DPOFEI or DSOFEI call follows.
YES
A DPOFEI macro call follows.
DSOFEI
A DSOFEI macro call follows.
LIFETIM=
Can be used to specify a time interval (in seconds), within which the signaled event must be collected (using the macro SOLSIG or DSOFEI). After this time interval has expired, the event will be deleted from the event queue.
Execution may be delayed by up to +10 seconds.
sec
Time specification in seconds.
1 <= seconds <= 43200. Default value: seconds = 600.
(r)
Register containing the value of “sec”.
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 DPOFEI macro is transferred in R15.
X'bb' | X'aa' | Meaning |
X'00' | X'00' | Normal execution. A POSSIG entry was created. All the specified operands are |
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 caller 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. |
Example of a chained macro structure:
DPOFEI START
BALR
USING
. . .
DPOFEI EIID=IDP1,REFNUM=REFNR,CONTINU=YES
DPOFEI EIID=IDP2,CONTINU=YES
DPOFEI EIID=IDP3,CONTINU=DSOFEI
DSOFEI EIID=IDS1
. . .
TERM
***** DEFINITIONS ******************************
. . .
IDP1 DS CL4
IDP2 DS CL4
IDP3 DS CL4
IDS1 DS CL4
REFNR DS F
. . .
END