Use this general macro to wait for a named event to be completed.
The SAWNC macro is similar to the EVNWC macro. However, if the caller
of the SAWNC macro has to wait for an event to be completed, the caller can be
interrupted by a signal. The SAWNC macro is used with the EVNTC and
POSTC macros.
You can use the EVNTC, EVNWC, POSTC, and SAWNC macros to pass the contents
of a core block from one entry control block (ECB) to another ECB.
Format
- label
- A symbolic name can be assigned to the macro statement.
- TYPE
- The type of event:
- CNT
- Count event.
- MSK
- Mask event.
- CB
- Core block type of event.
If TYPE=CB is coded, the LEVEL keyword must be specified and the BLOCK
keyword can also be specified. If the BLOCK keyword is specified, the
event name is retrieved from the area specified by the BLOCK keyword, and the
error code, if 1, is returned in the area specified by the BLOCK
keyword.
- LIST
- Event is oriented around a corresponding list of specified values.
Each POSTC macro that is issued contains a value that will be used to post the
like value in the EVNTC specified list. When all values are posted in
the event list, the event is completed.
- Note:
- For TYPE=LIST, the BLOCK parameter must be specified.
- LEVEL=Dx
- The data level of a core block reference word (CBRW) and file address
reference word (FARW). Valid values are D0-DF. The FARW
contains the symbolic name of the event. The LEVEL and BLOCK keywords
are mutually exclusive except when CB is specified for the TYPE
keyword.
- BLOCK=label1
- An area formatted as defined by the EV0BK DSECT that contains the name of
the event. Other fields defined by the EV0BK DSECT are used to return
values from the completed event. The LEVEL and BLOCK keywords are
mutually exclusive except when CB is specified for the TYPE keyword.
- ERROR=label2
- A label where control is passed if the event ends with an error.
- NFOUND=label3
- A label where control is passed if the event does not exist.
- EINTR=label4
- The label of an instruction to be given control if SAWNC macro processing
is interrupted by a signal.
Entry Requirements
- Register 9 (R9) must contain the address of the ECB being
processed.
- If only the BLOCK keyword is specified, the symbolic name of the event
must be in the EVNBKN field in the area pointed to by the BLOCK
keyword. For TYPE=LIST, allocate the full size of the EV0BK DSECT to
ensure that there is enough room for the returned data list.
- If only the LEVEL keyword is specified, the symbolic name of the event
must be in file address reference word CE1FAx, where x is
the data level (0-F).
- If CB is specified for the TYPE keyword and the BLOCK keyword is also
specified, the event name is retrieved from the area specified by
BLOCK. Otherwise, the event name must be specified in the FARW
specified by the LEVEL keyword.
Return Conditions
- If only the BLOCK keyword is specified:
- The area specified by the BLOCK keyword is filled as it relates to the
specified event type. See POSTC-Mark Event Completion for more information about the POSTC macro.
- If it is a MSK type, the specified area will be filled in with the
remaining mask and the contents of the accumulated POST MASK 2 field (EVNbkm2)
from the event.
- If it is a CNT type, the specified area will be filled in with the
remaining count value.
- If it is a CB type, the core block reference word (CBRW) specified by the
LEVEL parameter is set to the value passed by the POSTC macro. Issue
the LEVTA macro to determine if a core block was passed.
- If it is a LIST type, the area specified will be filled in with the data
list information. To determine the status of the data list items, the
flag field (EVNBKLIF) of each item must be interrogated. Valid values
for this flag field are defined in the EV0BK DSECT.
- The EVNBKE field is set with the error indicator if an error
occurred.
- For the MSK-, CNT-, or CB-type event, the error indicator in the EVNBKE
field is the value returned in the ERCODE parameter as coded in the POSTC
macro.
- For the LIST-type event, the error indicator in the EVNBKE field is set to
a generic error code value of X'7F'. The error indicator field
(EVNBKLIE) for each list data item contains the value returned in the ERCODE
parameter as coded in the POSTC macro.
- If only the LEVEL keyword is specified, the CBRW for the level is set to
the remaining mask or count value in CE1CRx bytes 0-1, where
x is a data level (0-F), and to the contents of the
accumulated POST MASK 2 field in CE1CRx bytes 3-4, where
x is a data level (0-F).
- If CB is specified for the TYPE keyword, the CBRW and FARW specified are
set to the values passed by the POSTC macro. Use the LEVTA macro to
determine if a core block is passed.
- Control is returned to the next sequential instruction (NSI) except for
the following conditions:
- If the event named by either the BLOCK or LEVEL keyword is not found, an
immediate return is made to the label specified by the NFOUND keyword.
- If the event ended with an error, control is returned to the label
specified by the ERROR keyword.
- If SAWNC macro processing is interrupted by a signal, control is returned
to the label specified by the EINTR keyword.
- The contents of R14 are unknown. The contents of R0-R7 are
preserved across this macro call.
- The error indicated by R15 is returned in the ERCODE keyword as coded in
the POSTC macro.
Programming Considerations
- This macro can run on any I-stream.
- The SAWNC macro enables the named event to allow event completion to be
posted to the ECB:
- If the event has not completed successfully when SAWNC macro processing
begins, the input/output (I/O) counter and flags for the named event are
incremented so that when the event is completed, the event can be posted to
the calling ECB.
- If the named event has completed successfully when SAWNC macro processing
begins, SAWNC macro processing starts the posting process.
- Defined events in multiple database function (MDBF) systems are subsystem
unique.
- Using the SAWNC macro causes an unconditional loss of control for the
calling ECB unless the named event is not found.
- More than one ECB can wait for the same named event except for a core
block type of event. When the event is completed successfully, all
waiting ECBs are posted as completed.
- For a core block type of event, only the creating ECB can wait on the
event. For any other ECB attempting to wait on the event, control is
returned to the label specified by the NFOUND keyword as a not-found
condition.
- The EVNTC and SAWNC macros can be coded to delay an ECB for a specified
number of seconds. This essentially delays the ECB by the amount of
time specified by the TIMEOUT keyword of the EVNTC macro. It is not
necessary to code the POSTC macro.
- Unless the SAWNC macro returns control to the calling ECB because the
event name cannot be found, the calling ECB gives up control and subsequently
regains control when one of the following occurs:
- Event completion is posted (with or without error).
- The timeout value ends.
- A pending alarm is triggered, causing a SIGALRM signal to be sent.
- A signal is sent to the calling process.
Examples
None.