Macro | Brief description |
CLCOM | Terminates participation in intertask communication |
OPCOM | Opens intertask communication for a participant, and supplies an ITC name |
RELBF | Deletes the first message in the ITC receive queue of the ITC participant |
REVNT | Receives a message for the ITC name of the participant |
SEVNT | Sends a message to another ITC participant |
Intertask communication (ITC) procedure
Intertask communication (ITC) allows message exchanges between programs which are being executed in different tasks. ITC requires each ITC participant to have a unique identity in the form of an ITC name. From the viewpoint of the operating system, ITC participants are those tasks which have an ITC name maintained in the communication table; from the user's viewpoint, they are the (user) programs which are being executed in these tasks and which have called OPCOM. By participating in intertask communication, all tasks in the system can exchange messages and - if necessary - wait for their arrival, provided they know each other's ITC names. Each ITC participant may send and receive messages. A participant (program) can send a message to another participant, but will not be informed automatically of receipt of the message. The receiver can acknowledge receipt by returning a message.
In addition to sending messages, a participant may ask to be given messages already sent or yet to be sent by other participants. If the message is not yet available at the time of the request, the program run can be halted for a selected period of time. As soon as the message arrives, or on expiration of the waiting period, the system will resume the program run and deliver the message. The receiver can specify the participant whose message is to terminate this waiting period, or can accept any participant as the sender.
The following macros are used for intertask communication:
OPCOM: Open ITC participation
SEVNT: Send message
REVNT: Request message
RELBF: Delete receive queue
CLCOM: Close ITC participation
Opening and closing ITC participation
A program wanting to participate in ITC must call the OPCOM macro, and give an ITC name. The system checks this name and rejects it if it has already been assigned to another ITC participant. If the name is unique and if sufficient system memory (for ITC participant lists) is available, the system includes the task with its ITC name in the participant list. If the task is the first ITC participant, the OPCOM call also initiates the intertask communication (the system sets up a communication table). OPCOM is rejected if insufficient system memory is available for the lists and tables.
As soon as the OPCOM call has been accepted by the system, the participant can send messages to or receive messages from other ITC participants, itprovided that their ITC names are known to one another.
The user can terminate participation in ITC by means of the macro CLCOM. If the NOKEEP operand is specified in the macro, participation is terminated completely for that user, and no further messages may be sent or received. The system deletes any existing messages in the receive queue and erases the user's ITC name from the participant list.
If the user calls the CLCOM macro with the KEEP operand, then only the participation as receiver is terminated. The system delivers no messages, but the user can still evaluate the receive queue and send messages to other participants. If the receive queue is empty when the CLCOM KEEP call is issued, the system proceeds as for the CLCOM NOKEEP call.
It is recommended that ITC participation be terminated with the call sequence CLCOM KEEP/CLCOM NOKEEP, in order to prevent messages being lost. Otherwise, messages arriving between the REVNT and the CLCOM calls will be lost.
If a program or task is terminated without the macro CLCOM having been called, the system will terminate ITC participation for this program or task with an internal call of the CLCOM NOKEEP macro. This may result in messages being lost. To avoid this, the receive queue can be evaluated in an STXIT routine (see "STXIT procedure with contingency processing"). The routine should issue the call CLCOM KEEP, check any messages present, return the proper acknowledgment and close with CLCOM NOKEEP, thus forestalling system-internal program/task termination (including CLCOM NOKEEP).
The receive queue
For each ITC participant, the system sets up a receive queue in system memory, in which it queues all messages to the participant in the order of their arrival. The participant must evaluate and delete the messages in the queue.
If a participant requests a message (REVNT macro), the system passes to it the message that came in first, and which is also the first in the queue (FIFO principle). If the participant requests a message from a specific sender, it receives the first message transmitted by this sender. The system always transfers the message that is first in line. Thus, a participant wanting to request the next message must first delete the first one. When a message is
initially requested (with a REVNT macro), the system can be directed to delete it from the queue after it has been transferred. Depending on the particular request, this may be the first message in the queue or the first one from a specific sender. The first message from a specific sender cannot be deleted explicitly, but only in conjunction with the request (REVNT). The first message in the queue can, however, be deleted explicitly with the RELBF macro. The participant can delete the whole receive queue by calling the RELBF macro in a loop and testing the return code each time to check whether the receive queue is empty.
As soon as participation in ITC is terminated (with CLCOM), the system stops accepting messages for the receive queue of the participant concerned. Simultaneously with the closing of ITC participation, the program or task can have the system cancel its receive queue. Alternatively, it can continue to evaluate the existing messages and subsequently release the receive queue by means of a further CLCOM call.
Sending messages
An ITC participant can send messages to any other participant at any time (using the SEVNT macro), provided sufficient system memory is available. The sender merely needs to know the ITC name of the receiver. The system does not, however, notify the intended receiver that a message has arrived. The addressed participant must take the initiative and request the message. Once the message has been received, it is good practice for the receiver to send back a message as an acknowledgment. The sender can then request this at a convenient time (e.g. after all messages have been sent off) by means of a REVNT macro.
The sending participant holds the message ready in a separate program area. The message may be up to 64 K in length. After calling the SEVNT macro, the system checks whether the receiver's ITC name is syntactically correct, and whether it is contained in the participant list. It also makes sure that the messages contained in the receive queue do not exceed a total length of > 128 K. If the check proves positive, the system transfers the message to the receiver's receive queue. The sending task is continued without waiting after the SEVNT call and can send further messages to any desired receiver.
Requesting and receiving messages
Each ITC participant can request a message with the REVNT macro and - if it has not yet arrived - wait for it. The receiver can specify that the message is to come from a specific sender or that a message from any participant will be accepted. If the receive queue is empty or contains no messages from the desired sender, the system interrupts the task after the REVNT call until the message arrives or until the waiting time has expired (see figure 9). The waiting time interval (between 1 second and 6 hours) can be set in the REVNT call. As soon as the task is continued, the REVNT return code can be tested to check whether the message is arrived.
The request for a message (REVNT macro) can be linked with eventing. The eventing mechanism regards the arrival of the message as an ITC event (see following section).
The system transfers the message from the receive queue into a program area of the participant, together with the sender's ITC name and its length. If the receiving field is not large enough to accommodate the complete message, the system transfers only the header, consisting of the name of the sender, the length of the complete message and the first 4 bytes of the message.
A participant requesting a message with REVNT can also specify that the system is to delete it from the receive queue after transmission (operand REL=YES). Operand REL=NO causes the message to be retained. This allows the same message to be requested more than once. Until the first message in the queue is deleted it will continue to be the one transferred with each request. To have the next message transferred, the participant must delete the first one (implicitly with REVNT or explicitly with RELBF).
If a participant receives messages of different lengths, it may not be advisable to reserve a full-length destination field (64K + 7 for sender name and message). If REVNT is called with a length of 16 (and REL=NO), only the message header (sender name, record length field and 4 bytes of information) will be transmitted. The participant can then decide either to delete the message or to request more memory space (REQM) to enlarge the destination field. A further request can then be made for the message, this time in its full length.
Figure 9: Intertask communication (ITC): program requesting a message
Linking ITC to eventing
This section assumes that the reader is familiar with eventing, which is described on "Eventing" and "Contingency processes" of the present manual.
Event classes:
Eventing permits users to have the execution of their program interrupted until one of a number of different events occurs (see "Eventing"). The events that can influence eventing are subdivided into various classes according to their origin (see figure 10). At present the following event classes are available:
Optional events
UPAM events
ITC events
DCAM events
CJC events
In the class of optional events, the user determines when and whether to signal an event to eventing (POSSIG, see "Eventing"). Events of all other classes (ITC, UPAM etc.), though originating during program execution, are signaled to eventing by the system, not by the program (internal POSSIG). In addition, the nature of such events is defined:
for example, a UPAM event occurs upon completion of an I/O operation, and the arrival of an ITC message (or expiration of a specified waiting time) is regarded as an ITC event.
A program which solicits a signal from an event item (SOLSIG) may also be the one in which the expected event occurs. For example, a program initiates an I/O operation via PAM and then requests a signal for the event (SOLSIG). As a result, the program is interrupted (synchronous eventing) by the event item and continued as soon as an internal POSSIG indicates that the I/O operation has been completed.
A participant cannot restrict its signal request to a specific event class. The signal received (continuation or contingency start) may refer to any event that may occur within the scope of the event item. By means of the post code (see "Extended addressing with data spaces"), eventing informs the participant of the class and precise circumstances of the event.
Execution of the program can therefore be made dependent on a number of different events. This is useful when several events are expected but the program does not know which of them will occur first (e.g. arrival of ITC message or reading of a PAM block completed).
Figure 10: Event classes
ITC message as an ITC class event
The effect of linking ITC and eventing is that an (ITC) event occurs whenever an ITC message is received or the waiting time expires. The link is established through specification of an event item ID address in the REVNT call. As a result, program execution will not be interrupted by the REVNT call. The message sender need not be a participant in eventing.
Linking ITC and eventing permits more flexible program execution than ITC alone:
The participant can combine a wait for an ITC message with a wait for another event.
Example
The participant program issues a PAM (see “DMS Macros” manual [7 (Related publications)]) and a REVNT call, both linked to an event item. It then issues a SOLSIG call and is interrupted. Upon its resumption, it checks the post code to see whether the message has arrived, or the I/O operation has been completed.The participant can postpone the wait interrupt: The interrupt occurs not after the REVNT call, but after the subsequent SOLSIG call (see figure 11 and figure 12).
Example
Using a linked REVNT call, the participant requests an ITC message and continues processing. At some later point it issues a SOLSIG call to check whether the message has arrived. Only if the message is still outstanding will the interrupt occur.The participant can avoid any wait interrupt by specifying a contingency routine in the SOLSIG call (see figure 13). In such an asynchronous instance of eventing, the SOLSIG call may equally well be issued prior to the REVNT call.
Example
To evaluate an ITC message and to perform all actions contingent on it, a contingency routine is defined in a program. The contingency routine is specified in the SOLSIG call. The message is requested by a REVNT call given before or after the SOLSIG call. Program execution is not interrupted either by REVNT or by SOLSIG (which would cause it to wait), but only by the contingency routine, which starts its execution as soon as an event occurs.
The SOLSIG call does not enable a participant to request a specific event. Eventing assigns to the participant the first event occurring within its scope which has not yet been requested by other (previous) SOLSIG calls. By means of the post code, the participant must filter out the relevant events.
The scope of an event item may comprise one task, all tasks under one user ID, or all tasks within the system. The scope is defined when enabling the event item.
Several event items (with various scopes) can exist at the same time, and a task may associate itself with various event items at the same time (see "Eventing").
Program structure for the linked use of ITC and eventing (without contingency process) (see figures 11 and 12).
Participation in both ITC and eventing must be enabled (OPCOM and ENAEI). The system enters the ID of the event item under the address specified in the ENAEI macro.If the event item has already been enabled, the participant has to belong to the specified scope in order to join in. If other participants within the same scope also call the SOLSIG macro, it is impossible to predict to which participant an event will be assigned by the event item.
A message is requested with the REVNT macro. In addition to the known operands, the address of the ID used in the ENAEI call is specified in the EIID operand.
Execution of the program is not interrupted. The program has to check the REVNT return code in R15 to ascertain whether the call has been accepted, or rejected due to a format error. A rejected REVNT call does not produce an ITC event. The return code for a linked REVNT cannot contain any details of the message; only the post code contains such details.
No further REVNT call (linked or unlinked) may be issued prior to the completion of a linked REVNT call (i.e. message received or waiting time expired). Other calls linked to the event item, e.g. a PAM call, are permissible.At a time convenient for its execution, the program calls the SOLSIG macro and specifies an address for the post code. Program execution is not interrupted if the signal request is immediately satisfied. Otherwise, in the case of synchronous eventing, program execution is interrupted for a period not longer than the specified waiting time interval.
Upon continuing its execution, the program first checks the return code of the SOLSIG call for format errors or expiration of the SOLSIG waiting time. (The expiration of the REVNT waiting time is specified in the post code.)
The post code is checked. The system has stored it at the address specified in the SOLSIG call (or in register 3 for a contingency process). The leftmost byte of the post code indicates the class to which a specific event belongs (ITC event: X'08'). The program then proceeds to the processing section provided for the particular event class.
Processing of an ITC event: The rightmost byte of the post code is checked. It indicates whether the REVNT waiting time has expired or whether the message, or only the message header, has been transmitted. From this point on, REVNT calls may again be issued.
For many ITC applications, one message is likely to be immediately followed by others. In such a case, any additional REVNT calls should not be linked to eventing. The SOLSIG calls required are time-consuming, and are of no advantage if the message has already arrived. Instead, the program will continue to issue unlinked REVNT calls specifying WTIME=0 until all outstanding messages have been received.
Subsequently, a linked REVNT call will again be useful for expecting further messages.The program terminates its participation in ITC and eventing by means of CLCOM and DISEI (see note).
Until an event has been signaled for a linked REVNT call (i.e. message arrived or waiting time expired) the participant may not disable the associated event item. Otherwise, the contingency process will be started due to the DISEI call (asynchronous eventing), or, with synchronous eventing, an ITC event can no longer be signaled even if the message has already been transmitted. The following procedure is recommended: The participant must check internally whether the last linked REVNT has been completed (e.g. by means of a counter; for local scope, with CHKEI). The DISEI call can then be issued. By issuing CLCOM KEEP, the participant can suppress the reception of any further messages. Any messages still waiting in the message queue are picked up by means of unlinked REVNT calls. Afterwards, ITC participation can be terminated with CLCOM NOKEEP.
Note: waiting times
Both the REVNT call and the SOLSIG call can be used to set a waiting time.The REVNT waiting time limits the duration of the message request. If the waiting time expires and no message has arrived, this is regarded as an ITC event. The system issues an internal POSSIG call to the event item, which in turn signals an ITC event to the participant. Upon expiration of the REVNT waiting time, the rightmost byte of the post code contains the value X'10'.The SOLSIG waiting time limits the duration of the solicit signal request. If the waiting time expires and the event item has not signaled an event, the interrupted program is continued (synchronous operation) or the contingency routine is started (asynchronous operation). Upon expiration of the SOLSIG waiting time, the return code of the SOLSIG call has the value X'20000004'. (Expiration of the REVNT waiting time is regarded as an ITC event. In this case, the SOLSIG return code has the value X'00000000').
Figure 11: ITC linked to eventing (synchronous operation):
The requested message arrives after the SOLSIG call
Figure 12: ITC linked to eventing (synchronous operation): The requested message arrives before the SOLSIG call
Figure 13: ITC linked to eventing (asynchronous operation):
A contingency process is executed when the message arrives.
Example
Program structure for the linked use of ITC and eventing, with a contingency process (see figure 13).
Program segment with ITC processing (basic process)
EXAMPLE START
BALR 6,0
USING *,6
:
:
ENAEI EINAME=EVE,EIIDRET=ECODE ------------- (1)
ENACO CONAME=CONTEVE,COADAD=CONTADR,
COIDRET=CONTI
OPCOM PARTIC
:
:
SOLSIG EIID=ECODE,COID=CONTI,LIFETIM=3600 --- (2)
C 15, RC00
BNE SOLSERR
:
:
REVNT RECEIPT,100,WTIME=600,EIID=ECODE ------ (3)
C 15,RC00
BNE REVERR
:
:
CLCOM ---------------------------------------- (4)
DISCO COID=CONTI
DISEI EIID=ECODE
TERM
Contingency routine (contingency process)
CONTANF BALR 5,0------------------------------------ (5)
USING *,5
ST 3,POSTCODE
: Checking of post codes for
: various event classes
CLI POSTCODE,ITCEVENT
BE ITCPROC
: Processing of events
: belonging to other classes
:
ITCPROC : Checking of post codes for
: reception of messages.
: Evaluation of the message
RETCO
Error routine
REVERR (Error handling in REVNT call)
:
B ....
:
SOLSERR (Error handling in SOLSIG call)
:
B ....
:
Data
ECODE DS F
CONTADR DC A(CONTANF)
CONTI DS F
RECEIPT DS CL100
RC00 DC A(0)
POSTCODE DC A(0)
ITCEVENT EQU X'08'
EN
(1) | Participation in eventing is enabled. The name of the event item is EVE. The address of the event item ID is ECODE. The scope is local.A contingency routine is defined. Its ID resides at the address CONTI. ITC participation is opened. The ITC name is PARTIC. |
(2) | Using the SOLSIG call, an event signal is requested. A contingency routine is specified in the call. This is to be started if a message arrives or, at the latest, upon expiration of the waiting time. The SOLSIG call may also be issued after the REVNT call. |
The basic process continues (unless interrupted by the contingency process because the message had already arrived). The SOLSIG return code is checked. If it is not equal to zero, the system did not accept the call. The SOLSERR error routine checks to find the cause.
(3) | An ITC message is requested. The specification EIID=ECODE links this request to event item EVE. Execution of the program is not interrupted. Calls for other event classes (e.g. PAM) may be issued before or after this REVNT call.A return code in R15 not equal to zero indicates that the call was not accepted. The REVERR error routine checks to find the cause. |
(4) | The participant program wants to terminate linked ITC processing: It terminates participation in ITC with CLCOM, deletes the contingency definition with DISCO and disables event item EVE with DISEI. (For ways of preventing messages being lost, see the note preceding the example.) |
(5) | The contingency routine stores the post code supplied by the system in register R3 and then evaluates its leftmost byte. This byte indicates the class of the event that initiated the contingency routine. In the processing section for the corresponding event class, the contingency routine evaluates the rightmost post code byte, which contains the return code for the class. For ITC events, this return code indicates whether the waiting time has expired or whether the message has been transmitted (see REVNT). Then if, for example, the waiting time has expired, it can issue another linked REVNT call (a return to the first REVNT call is not possible). The contingency routine is terminated by the RETCO macro. |