Macro | Brief description |
CHKEI | Checks the queue status for an specified event item |
DELFEI | Deletes a SOLSIG/POSSIG entry in the EVENTLST (optimized eventing, forward |
DISEI | Terminates participation in eventing. The specified event item is deleted if it is not being |
DPOFEI | Generates a POSSIG entry in the EVENTLST (optimized eventing, forward eventing) |
DSOFEI | Generates a SOLSIG entry in the EVENTLST (optimized eventing, forward eventing) |
ENAEI | Enables participation in eventing. The task is assigned to the specified event item |
POSSIG | Signals the occurrence of an event to a specified event item |
RPOFEI | Signals an event to the event item (optimized eventing, forward eventing) |
RSOFEI | Requests notification of the arrival of a signal from an event item (optimized eventing, |
SOLSIG | Issues a solicit a signal request for an event item |
General
Eventing is a technique which makes it possible to coordinate the execution of two or more (user) programs in different tasks. For example, program B is to read data records from a file only after program A has updated it; or program A is to write a data record in a shared memory area only after program B has read the preceding record. Coordination of the programs is achieved by the use (for control purposes) of a common event variable to determine the actions of the operating system (to put a task into a wait state, to end the wait state, or to start a contingency process). The event variable is addressed via the event item. The entire procedure - posting of events, their interrogation and the consequent actions taken - is referred to as eventing. The external representation of eventing is the event item.
From the viewpoint of the operating system, the participants in eventing are the tasks which are associated with a common event variable (event item); from the user's viewpoint, the participants are the (user) programs which are executed in these tasks.
Basic functions of eventing
Enabling participation in eventingPrograms whose execution is to be coordinated must open (enable) their participation in eventing and specify the name (and scope) of a common variable (event item). The declarations concerning participation, and the specification of the event item, apply only to the program currently being executed.For each event item, two queues are set up (POSSIG and SOLSIG queues). A task may use up to 2000 event items simultaneously.
Sending a signalA program wishing to report the completion of a particular processing operation sends a POSSIG signal to eventing. This signal is entered in the POSSIG queue (on the FIFO principle).
Requesting a signalA program requiring information about the completion of a particular processing step in another program sends a SOLSIG request to eventing. This request is entered in the SOLSIG queue (on the FIFO or LIFO principle, according to specification).
Servicing the queues (see figure 18)The first POSSIG signal in the POSSIG queue is assigned to the first SOLSIG request in the SOLSIG queue - irrespective of which tasks they originated from. If the SOLSIG request cannot be satisfied (i.e. the POSSIG queue is empty), two courses of action are possible:
synchronous eventing (see figure 15 and figure 16)The task which issued the SOLSIG request is put into a wait state either until a POSSIG signal is received by eventing or until the specified waiting time has elapsed. (Execution of the program is synchronized using the POSSIG signal.)
asynchronous eventing (see figure 17)The task which issued the SOLSIG request is not put into a wait state. If the SOLSIG request can be satisfied during the subsequent continued running of the program, or a long enough time elapses to satisfy the specified waiting time, then a contingency routine specified in the program is started.
If the SOLSIG request can be satisfied immediately (the POSSIG queue is not empty), then either the program execution will continue with the instruction which follows the SOLSIG macro, or a contingency routine specified in the SOLSIG call is started.Each participant can check the status of the queues; the information given indicates whether there are any POSSIG signals in the POSSIG queue, and whether there are any SOLSIG requests in the SOLSIG queue.
Disabling eventingParticipation in eventing can be disabled at any time. The participant is deleted from the list of participating tasks. Any SOLSIG requests which are still in the SOLSIG queue at that time are deleted. Any POSSIG signals not yet assigned at that time remain in the POSSIG queue.Participation is implicitly terminated when a program ends (not at the end of the task). The event item and all the internal processing lists are deleted when the last (or only) program terminates its participation.
Post code (see figure 18)Eventing only registers the arrival of a POSSIG signal. No information is provided about the event giving rise to the signal (file closed, record written, ...). Since the first entry in one queue is always paired with the first entry in the other queue, it is not possible to address a particular receiver or sender directly. However, the sender of the POSSIG signal may send a short message (post code) with the signal. The code is passed to the task whose SOLSIG request is satisfied by this POSSIG signal. It enables the receiver to determine whether the POSSIG signal is connected with its program execution or not.
The post code is 4 or 8 bytes long (4 bytes when using the 24-bit interface). The table below summarizes the important applications for various classes of event:
Application/ | Post Code | Remarks |
(POSSIG) | X'aa....aa' | aa....aa: string specified by the user (4 or 8 bytes) |
ITC | X'08000000' | REVNT event terminated |
X'08000004' | Operand error | |
X'0800000C' | Receiving field too small | |
X'08000010' | Timeout | |
DCAM | X'0Caa...a' | aa...a: character string provided by the user (3 or 7 bytes) |
UPAM | X'1000i..a' | 31-bit addressing mode |
X'10aaaaaa' | 24-bit addressing mode | |
CJC | X'1400iiii' | Condition satisfied |
X'1404iiii' | Job variable deleted | |
X'1408iiii' | Catalog exported |
Table 6: Applications/event classes and their post codes
The macro ETCNAM (with no operands) is used to generate symbolic names for the individual event classes.
ETCNAM 1 *,MACRO: ETCNAM, VERSION: VER040 1 * 1 * EVENT TYPE CODES WHICH MAY BE 1 * OUTPUT FROM THE SYSTEM TO THE USER 1 * 1 ETCTCS EQU X'04' TCS-EVENT 1 ETCITC EQU X'08' ITC-EVENT 1 ETCDCM EQU X'0C' DCAM-EVENT 1 ETCUPM EQU X'10' UPAM-EVENT 1 ETCCJC EQU X'14' CONDITIONAL JOB CONTROL-EVENT
Figure 14: Eventing: Synchronous operation The event is signaled before the waiting time has expired
Figure 15: Event item queues
Figure 16: Eventing: Synchronous operation
The event is signaled after the waiting time has expired
Figure 17: Eventing: Asynchronous operation. The event is signaled before the waiting time has expired
Figure 18: Information transfer (eventing)
The basic functions described are implemented using two groups of macros. The user eventing group of macros allows comprehensive use of the basic functions. The forward eventing (FEV) group of macros supplements user eventing with optimized variants which make for more efficient execution. Forward eventing can only be used in the synchronous mode. User eventing and forward eventing macros can be used together.
User eventing
User eventing is implemented using the following macros:
ENAEI: Enable participation in eventingPOSSIG: Send a POSSIG signalSOLSIG: Register a SOLSIG requestCHKEI: Check event item queue
DISEI: Disable participation in eventing
Participation in eventing is enabled by calling the macro ENAEI. The macro call must include a name for the event item and the scope (group of participants in eventing). The name is only valid within the specified scope. These two items of information are used internally to construct an ID for the event item. The ID is passed back to the calling participant and can be used in subsequent eventing macros (this speeds execution of the macros). Each participant in eventing receives a unique ID. If a user disables eventing in a program, and then later re-enables it in the same program run, the ID which is then issued may be different from the first one. Eventing is enabled by the first participant to issue the ENAEI macro. The event item and the requisite internal processing lists are then established automatically; subsequent participants are assigned to the event item.The scope may include a task, all tasks under a user ID, or all tasks in the system (the same name associated with a different scope would represent a different eventing procedure).
The POSSIG macro is used to send a signal to eventing. The sending of the POSSIG signal does not cause the task to be interrupted. The macro call may specify a contingency routine that is to be started either if it was possible to assign a SOLSIG request to the POSSIG signal, or if a specified time allowed for such an assignment has expired (the SOLSIG queue is empty). After the waiting time has expired, the POSSIG signal is deleted from the queue.When it is executed, the contingency routine supplies an event information code in register R2 (see "Contingency processes"). The event information code indicates whether the expected event has occurred (a POSSIG signal was assigned) or not; the code thus represents a kind of acknowledgment of the POSSIG signal.
The POSSIG call may also specify a contingency message, which will be passed to the contingency routine in register R1 after it has started.Several consecutive POSSIG calls may be chained together. The chain may also terminate with the macro SOLSIG.
The
SOLSIG macro is used to send a SOLSIG request to eventing. In the case of synchronous eventing, the task is put into a wait state until a POSSIG signal can be assigned to the SOLSIG request or until the specified waiting time has expired. It is also possible to specify that the task should not wait for the arrival of the POSSIG signal.In the case of asynchronous operation, the task is not put into a wait state. A contingency routine specified in the macro call is started if either
a POSSIG signal can be assigned to the SOLSIG request within a specified waiting time, or
the waiting time has expired.
In situation 1. it is possible to direct that a new SOLSIG request be sent immediately.
The following items of information are passed on to the contingency process:
the contingency message specified in the SOLSIG macro in register R1 of the contingency process.
the event information code in register R2.
the post code from the POSSIG macro in register R3 (plus register R4).
In both synchronous and asynchronous operation, the SOLSIG request is deleted from the SOLSIG queue on expiry of the waiting time.
The macro CHKEI can be used to check the occupancy of the queues. The information requested is supplied to the participant in the form of the return code.
The macro DISEI terminates participation in eventing. Any SOLSIG requests remaining in the SOLSIG queue are deleted. Assigned forward events are also deleted (see below). Any POSSIG signals not yet assigned remain in the POSSIG queue. The event item is deleted when the last (only) participant issues the DISEI macro.
Forward eventing
Forward eventing supplements user eventing with the following macros:
DPOFEI: Create a POSSIG entry in the EVENTLST
DSOFEI: Create a SOLSIG entry in the EVENTLST
RPOFEI: Send a POSSIG signal
RSOFEI: Register a SOLSIG request
DELFEI: Delete a POSSIG-/SOLSIG entry in the EVENTLST
Forward eventing (FEV) is an optimized form of synchronous eventing. FEV avoids the need for repeated validation of the operands when either POSSIG or SOLSIG calls to a particular event item are repeated. Instead, an event list (EVENTLST) is set up and in the case of SOLSIG requests, for example, a SOLSIG entry is made. In subsequent steps in the program, any (real) SOLSIG request will simply refer to this entry. The entry can be explicitly deleted subsequently. The same applies to the sending of POSSIG signals. For each participant, a maximum of 2047 entries can be created in the EVENTLST.Participation in eventing must be enabled using the macro ENAEI and terminated using DISEI. The macro CHKEI can be used to check the POSSIG or SOLSIG queue. From the viewpoint of eventing, it makes no difference whether, for example, a POSSIG signal is sent using POSSIG or using RPOFEI. The same applies to the sending of a SOLSIG request. Forward eventing can only be used in synchronous operation. A post code may be specified.
The macro DPOFEI creates a POSSIG entry in the EVENTLST. A reference number for the entry is returned to the caller. As in the case of the POSSIG macro, several successive DPOFEI calls can be chained. The specifications given in the macro call are copied into the EVENTLST entry. A post code may be specified. However, a contingency routine (POSSIG macro) must not be specified.
The macro DSOFEI creates a SOLSIG entry in the EVENTLST. A reference number for the entry is returned to the caller. The operand values specified in the macro call are copied into the EVENTLST entry. Only synchronous operation is permitted.
An RPOFEI macro referencing the POSSIG entry in the EVENTLST causes a POSSIG signal to be sent to eventing.
An RSOFEI macro referencing the SOLSIG entry in the EVENTLST causes a SOLSIG request to be registered with eventing.
The DELFEI macro can be used to delete a POSSIG entry or a SOLSIG entry in the EVENTLST.
Example: synchronous operation
The programs EV1 and EV2 are started in separate interactive jobs (at different data display terminals). EV2 is reading from a file that EV1 wants to copy. EV2 signals the closing of the file to EV1; then EV1 copies the file.
Both programs are to run in 31-bit addressing mode: EV1 below and EV2 above the 16-Mb boundary.
Program EV1
EV1 START
EV1 AMODE ANY
EV1 RMODE ANY
GPARMOD 31
PRINT NOGEN
BALR 3,0
USING *,3
ENAEI EINAME=EVE,SCOPE=GROUP,EIIDRET=ABRID1 —————————————————— (1)
GDATE TOD=TIME1
WROUT MESS1,ERROR
SOLSIG EIID=ABRID1,COND=UNCOND,RPOSTAD=PCEMPF,RPOSTL=2, -
LIFETIM=800 ———————————————————————————————————————————— (2)
M1 GDATE TOD=TIME2
WROUT MESS2,ERROR ———————————————————————————————————————————— (3)
CMD 'COPY-FILE','TEST.FILE.1,TEST.FILE.2'
WROUT TEXT,ERROR
DISEI EIID=ABRID1 ———————————————————————————————————————————— (4)
TERM
ERROR TERM DUMP=Y
*** DEFINITIONS ***
ABRID1 DS F
MESS1 DC Y(MESS1END-MESS1)
DS CL2
DC X'01'
DC C'PROGRAM WAITING SINCE '
TIME1 DS CL8
MESS1END EQU *
MESS2 DC Y(MESS2END-MESS2)
DS CL2
DC X'01'
DC C'POSSIG SIGNAL RECEIVED AT '
TIME2 DS CL8
DC C'; POSTCODE = '
PCEMPF DS CL8
MESS2END EQU *
TEXT DC Y(TEXTEND-TEXT)
DS CL2
DC X'01'
DC C'COPY-FILE COMMAND EXECUTED'
TEXTEND EQU *
END
(1) | Event item EVE is enabled. |
(2) | EV1 issues a SOLSIG call for EVE and provides a receiving field for a post code (2 words). Then EV1 waits for a maximum of 800 seconds for the arrival of a POSSIG signal. |
(3) | After the arrival of the POSSIG signal (or after the wait time has finished), EV1 is continued and outputs a message. EV2 has closed the TEST.FILE.1 file; EV1 can copy the file. |
(4) | EV1 disables event item EVE. |
Program SRC.EV2
EV2 START
EV2 AMODE ANY
EV2 RMODE ANY
GPARMOD 31
PRINT NOGEN
BALR 3,0
USING *,3
ENAEI EINAME=EVE,SCOPE=GROUP,EIIDRET=ABRID2 —————————————————— (5)
OPEN TESTFCB,INPUT —————————————————————————————————————————— (6)
GET TESTFCB,INAREA
CLOSE CLOSE ALL
GDATE TOD=TIME1
POSSIG EIID=ABRID2,SPOSTAD=PCSEND,SPOSTL=2 ——————————————————— (7)
WROUT MESS1,ERROR
DISEI EIID=ABRID2 ———————————————————————————————————————————— (8)
TERM
ERROR TERM DUMP=Y
*** FILE ***
DS 0F
TESTFCB FCB FCBTYPE=SAM,LINK=FILIN,EXIT=E1
E1 EXLST EOFADDR=CLOSE,COMMON=CLOSE
*** DEFINITIONS ***
ABRID2 DS F
PCSEND DC X'C5E5F26060C5E5F140' FIELD ALIGNED ON WORD BOUNDARY!
MESS1 DC Y(MESS1END-MESS1)
DS CL2
DC X'01'
DC C'POSSIG SIGNAL SENT AT '
TIME1 DS CL8
MESS1END EQU *
INAREA DS CL200
END
(5) | EV2 is connected to event item EVE. |
(6) | EV2 opens the TEST.FILE.1 file and reads a data record. The file is closed. |
(7) | EV2 sends a POSSIG signal and transfers a post code (2 words). |
(8) | EV2 disables event item EVE. |
Runtime log of the interactive job with program EV1.SRC
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,ev1), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,ev1)) % ASS6011 ASSEMBLY TIME: 525 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 86 MSEC //end % ASS6012 END OF ASSEMBH /start-executable-program library=macexmp.lib,element-or-symbol=ev1 ——— (1) % BLS0523 ELEMENT 'EV1', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'EV1', VERSION ' ' OF '<date> <time>' LOADED PROGRAM WAITING SINCE 13:14:41 ———————————————————————————————————————— (2) POSSIG SIGNAL RECEIVED AT 13:20:22; POSTCODE = EV2--EV1 COPY-FILE COMMAND EXECUTED ———————————————————————————————————————————— (3)
(1) | EV1 is loaded and started. |
(2) | EV1 has been waiting for the POSSIG signal. |
(3) | The POSSIG signal was received; EV1 copies the file. |
Runtime log of the interactive job with program EV2.SRC
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,ev2), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,ev2)) % ASS6011 ASSEMBLY TIME: 871 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 86 MSEC //end % ASS6012 END OF ASSEMBH /add-file-link link-name=filin,file-name=test.file.1 /start-executable-program library=macexmp.lib,element-or-symbol=ev2 ——— (4) % BLS0523 ELEMENT 'EV2', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'EV2', VERSION ' ' OF '<date> <time>' LOADED POSSIG SIGNAL SENT AT 13:20:22 ———————————————————————————————————————— (5)
(4) | EV2 is loaded and started. |
(5) | EV2 sends the POSSIG signal, after it has closed the TEST.FILE.1 file. |
For further examples see the section on contingency processes ("Contingency processes") and the POSSIG and SOLSIG macro descriptions.