General
Application areas: | Intertask communication; see "Intertask communication (ITC)"Communication; see "Communication (programs, users, system)" |
Macro type: | Type O; see "O-type macros" |
Macro description
A user participating in intertask communication (ITC) can request a message and wait for its arrival by means of the REVNT macro.
Functional description
Each ITC participant may request a message by means of the REVNT macro. It can specify whether it will accept a message from any participant, or only messages from a specified sender. If the participant is waiting for a message from an unspecified sender, this message may also be from a sender that joined ITC later.
If there is not yet a message (or none from the desired sender) in the receive queue of the calling participant when the REVNT macro is issued, the task is interrupted by the system. The interrupted task is continued when the message is received or after the waiting time has elapsed; the length of the waiting time may be specified in the REVNT call. If the message has arrived in the meantime, it is transferred to the task.
The system transcribes the message from the receive queue to the destination field of the program. If there are several messages in the queue, it transcribes the first message or the first message from the desired sender. In the REVNT macro the user may specify whether or not the message is to be deleted after it has been transcribed from the receive queue. If the message is not deleted, it may be transcribed again by means of another REVNT macro.
A message may be 8 bytes to 64 Kbytes long (including a 4-byte record length field). A user who knows the extent of messages to be exchanged when programming may define the length of the destination field accordingly. The system enters both the message and its actual length in the destination field. If the destination field cannot accommodate the entire message, the system transcribes only the first 4 bytes of the message, but it enters the complete length in the record length field.
This is flagged by means of return code X'0C'. If the message length is not known when programming, the user should issue the REVNT macro with the specification REL=NO. The user receives the actual length and may base the size of the destination field on that value; then the entire message may be transcribed by means of a second REVNT macro. This time the user may delete the message by means of REL=YES, or issue the RELBF macro, which clears the first message in the receive queue.
ITC-linked to eventing:
The wait state, in which a task is placed after the REVNT call, can be avoided by linking ITC to eventing if the message is expected from an unspecified sender. In addition, waiting for an ITC message can be combined with waiting for another event (see section “Eventing”).
ITC is linked to an event item by specifying the address of the ID of the event item as an additional operand in the REVNT call. This address must have been defined in a previous ENAEI call. As a result, the task is not interrupted after the REVNT call. The caller is provided with a restricted return code specifying whether or not the REVNT call has been accepted. Information concerning the arrival of the message is delivered to the task by the post code as soon as the SOLSIG call has been processed. The SOLSIG call now permits the user to request a solicit signal for an event at any time after the REVNT call (even prior to the REVNT call if a contingency process has been specified). If no message has been received, the SOLSIG waiting time begins. The task is interrupted unless a contingency process has been specified. The SOLSIG waiting time is terminated by any event occurring for the specified event item. The post code indicates the class to which the event belongs.
Notes
A task may check its receive queue, without being interrupted, by means of the REVNT..., WTIME=0 call.
The limit for the waiting time (WTIME operand) is meant to prevent participants mutually blocking one another (if each is waiting for a message from the other).
Notes on linked REVNT:
The event class indicated in the post code must be checked as to whether an ITC event or another event has occurred.
No further REVNT macro - linked or unlinked - may be issued prior to the completion of a linked REVNT call (rejected with return code X'18').
The event item must not be deleted (DISEI macro) prior to the completion of a linked REVNT call. Otherwise, the REVNT call cannot be completed and messages may be lost (see the note in the section “Intertask communication (ITC)”).
Macro format and description of operandsFormat 1:
REVNT |
destfield,length [,WTIME=seconds] ,REL=YES / NO [,NAME=sendername] [,EIID=address] |
destfield
Symbolic address of the field to which the message from the receive queue is to be transferred. The field must begin on a word boundary. After the transfer its contents are as follows:
Bytes | Contents |
0 - 7 | TC name of the participant that sent the message |
8 - 11 | Record length field (SLF) |
12 - n | message (at least 4 bytes, if the field was too small to accommodate the complete |
The destination field must be at least 16 bytes long and the specification in the record length field must have a value of at least 8.
length
Decimal number specifying the length of the destination field, including the 8 bytes for the sender. The value for “length” may lie between 16 and 65543. The message including the record length field may be between 8 and 65535 bytes long.
WTIME=seconds
Specifies how long a task is to wait for the message if it has not yet been received at the time when the REVNT macro is issued. Times from 0 to 21599 seconds are permissible.If WTIME is not specified, the task waits 600 seconds.
REL=
Specifies whether or not the message is to remain in the receive queue.
YES
The message is deleted after being transferred from the receive queue, even if there was not sufficient space available for the message in the destination field.
NO
The message remains in the receive queue.
NAME=sendername
ITC name of an ITC participant; indicates that a message should only be transferred if the specified participant is the sender.
EIID=address
This operand is required only if ITC is to be linked to eventing (see “Linking ITC to eventing” (Intertask communication (ITC))).
The operand value “address” specifies the symbolic address of a field containing the ID of the event item. The field is 4 bytes long. The system has entered the ID in this field as a result of a previous ENAEI macro.
Format 2:
REVNT |
(1) |
(1)
Register 1 contains the address of an operand field with the following contents:
Bytes | Contents |
0 - 3 | address of receive field |
4 - 7 | length of receive field (hexadecimal) |
8 | X'00' : no linking to eventing |
9 - 11 | C'YES' |
12 - 15 | waiting time in seconds |
16 - 23 | ITC name of the sender made up to 8 bytes with trailing blanks if necessary, |
24 - 27 | address of ID of event item; to be specified only if X' 01' is specified in byte 8 |
Return information and error flags
R15:
+---------------+ | | | | | | | | | | | |a|a| +---------------+
A return code relating to the execution of the REVNT macro is transferred in the rightmost byte of register R15.
REVNT without linkage to eventing:
X'aa' | Meaning |
X'00' | The message has been completely transcribed |
X'04' | Operand error (e.g. memory has not been allocated or is not class 6 memory). No message |
X'08' | The calling task is not an ITC participant. No message has been transcribed |
X'0C' | The destination field is too small for the complete message. Only the header and first |
X'10' | Even during the waiting time no message has been received |
X'18' | Processing of an earlier linked REVNT call has not been completed. The present call is |
REVNT with linkage to eventing:
X'aa' | Meaning |
X'00' | REVNT call accepted |
The following return codes indicate that the REVNT call does not produce an ITC event: | |
X'04' | Operand error (e.g. memory is not class 6 memory or has not been allocated). The REVNT |
X'08' | The calling task is not an ITC participant. The REVNT call is rejected |
X'18' | Processing of an earlier linked REVNT call has not been completed. The present call is |
Meaning of the post code (for linkage to eventing only):
The post code is 4 bytes long and is entered after the SOLSIG macro call under an address specified therein. The leftmost byte indicates the event class (see section “Eventing”). The rightmost byte contains the return code applicable to the particular event class. An ITC event has event class X'08'.
ITC post code | Meaning |
X'08000000' | A linked REVNT call has been completed with the arrival of a message |
X'08000004' | Operand error: The memory space for the destination field is no longer allocated |
X'0800000C' | The destination field is too small for the complete message. Only the header |
X'08000010' | The waiting time has expired and no message has been received |