This general macro is used to define for the control program a named event
that can be waited on by this ECB and posted by other ECBs. This macro
is used with the POSTC (see POSTC-Mark Event Completion) and the EVNWC macros (see EVNWC-Wait for Event Completion).
You can use the EVNTC, POSTC, EVNWC, and SAWNC macros to pass the contents
of a core block from one ECB to another ECB.
Format
- label
- A symbolic name can be assigned to the macro statement.
- LEVEL=Dx
- A core block reference word and file address reference word
(D0-DF). LEVEL and BLOCK are mutually exclusive.
- BLOCK=address|(Ry)
- If specified, it is the address of an area which contains the EVNTC
parameters. The area should be formatted as defined by the data area
EV0BK. BLOCK and LEVEL are mutually exclusive. If a register is
specified, it must be R0-R7 or R14-R15.
- TYPE
- The type of event being defined. Refer to Entry Requirements for
more information about the TYPE parameter.
- CNT
- Event is a counter type. Each POSTC issued will cause the specified
count to be decremented by one. When the count becomes 0, the event
will be marked complete.
- MSK
- Event is mask type. Each POSTC issued will contain a 16 bit mask
which will be used to reset the EVNTC specified mask bits. When the
event's mask is completely reset, the event will be marked
complete.
- CB
- Event is core block oriented, implies count of 1. The first POSTC
will cause the event to be marked complete.
- LIST
- Event is oriented around a list of specified values. Each POSTC
macro that is issued will contain a value that will be used to post the
corresponding value in the EVNTC macro specified list. When all values
are posted in the event list, the event will be marked completed.
- Note:
- For TYPE=LIST, the BLOCK parameter must be specified.
- NAME=Y|N
- If specified as Y, the event name is supplied by the issuer in the file
reference word for this level or in the area specified by the BLOCK
parameter. If not specified, or given as 'N', a unique name is
generated by the macro processor and returned in the file reference word for
the level or in the area specified by the BLOCK parameter.
- DUPNAM=label1
- This must be specified if NAME=Y is given. This is the label to
branch to if the specified name already exists in the event table.
- TIMEOUT=n
- If specified, the value in seconds an ECB can wait on the event before the
event is assumed to be in error. The value may be specified either by a
self-defining value (from 0 to 4096) or by a value in a register (from 0 to
32 768). If a value of 0 is specified, time-out is not
performed. The default time-out is 180 seconds. If a register is
specified, it must be R0-R7 or R14-R15.
- STATE
- Indicates valid states for time-out processing. The default value
is NORM.
- NORM
- Event will have time-out processing only when in NORM state. During
time out processing the count specified by TIMEOUT will be decremented by one
provided that the system state is NORM. If the value of TIMEOUT becomes
0, the event is posted as having timed out, regardless of system state.
NORM is the default.
- 1052
- Event will timeout processing in all states with S-TIMERS on.
During time out processing the count specified by TIMEOUT will be decremented
by one. If the value of TIMEOUT becomes 0, then the event is posted as
having timed out, regardless of system state.
Entry Requirements
- EVNTC using LEVEL
- The symbolic name to be assigned to the event, if supplied by the issuer,
must be 8 characters in length, and must be in CE1FAx, where x is the
specified level.
- For CNT type, CE1CRx, bytes 0-1 must contain the count value for
the event. This is a 16-bit number.
- For MSK, CE1CRx, bytes 0-1 must contain the 16-bit mask value to be
used for the event.
- For CB, CE1CRx is not used.
- EVNTC using BLOCK
- The symbolic name to be assigned to the event, if supplied by the user,
must be 8 characters long, and must be in EVNBKN.
- For CNT type, EVNBKC1 must contain the count value for the event.
This is a 16-bit number.
- For MSK EVNBKM1 must contain the 16-bit mask value to be used for the
event.
- For CB, there is no area to be set up.
- For LIST, EVNBKLC must contain the number of items in the data list,
EVNBKLS must contain the size of a data item, and EVNBKLI must contain the
list of data items.
- Note:
- Using the GENLC macro to create or modify the list will ensure that these
fields are defined correctly. See GENLC-Generate a Data List for more information.
- R9 must contain the address of the ECB being processed.
Return Conditions
- Control is returned to the next sequential instruction unless the
specified name is not unique, in which case the label for DUPNAM is branched
to.
- If the LEVEL parameter was used, the value of the core reference word is
unchanged and the file reference word will contain the assigned name for the
event. The level is available for reuse.
- If the BLOCK parameter was used, the EV0BK area is unchanged unless NAME=N
was specified, in which case the field EVNBKN will contain the assigned name
for the event.
- The contents of R14 and R15 are unknown. The contents of R0-R7 are
preserved across this macro call.
Programming Considerations
- This macro can be executed on any I-stream.
- Defined events in MDBF systems are subsystem unique.
- To ensure that an event ends, use an EVNWC or SAWNC macro.
- If a count-type event is dynamically incremented using the EVINC macro,
use the EVNWC or SAWNC macro after the final count is defined. (See EVINC-Increment Count for Event.)
- The level that is used must not be holding a block. If it is, a
system error occurs and the ECB exits.
- You can use the EVNTC macro and either the EVNWC or SAWNC macro to delay
an ECB for a specified number of seconds. When the EVNWC or SAWNC macro
is processed, the ECB will be delayed by the amount of time specified by the
TIMEOUT parameter of the EVNTC macro. You do not have to code the POSTC
macro.
- Use the GENLC macro to generate the event data list (see GENLC-Generate a Data List for more information).
- The EV0BK DSECT describes the user area that is used as a parameter to the
following macros:
- EVNTC
- See EVNTC-Define Internal Event.
- EVNWC
- See EVNWC-Wait for Event Completion.
- POSTC
- See POSTC-Mark Event Completion.
- SAWNC
- See SAWNC-Wait for Event Completion, Signal Aware.
- GENLC
- See GENLC-Generate a Data List.
The use of a user area defined by the EV0BK DSECT allows the application to
use the above macros without needing a free data level. If this user
area is not used, the application must have an available data level.
The user area defined by the EV0BK DSECT is used to pass to the SVC handler
for these macros the information needed to perform the specified
function.
The name field is required for the EVNTC, POSTC, EVNWC, and SAWNC
macros. Other fields in the EV0BK DSECT may be required according to
the macro that is being issued.
- The event area is allocated and created by the user application
program. It consists of an area of storage and exists only as long as
that area of storage is owned by the issuing application program.
- The basic EV0BK block requires 16 bytes of storage. The extended
EV0BK block, one for which a data list is defined, can require up to a maximum
of 424 bytes. EV0BK must start on a fullword boundary.
- The content of the user event area is as follows:
- Field
- Description
- EVNBKN
- This is the name of the event. It is can either be supplied by the
application or dynamically created by the EVNTC macro. For POSTC and
EVNWC, the name must be supplied.
- EVNBKC1
- This must be set by the application for a count type of event. This
value specifies the number of POSTC macros that must be issued before the
event is considered satisfied.
- EVNBKM1
- This field is used both when creating a mask type of event and also when
posting the same event. When creating the event, this field supplies
the master mask, which must be reset to 0 before the event is to be considered
satisfied. For a POSTC macro, EVNBKM1 specifies the bits to be reset in
the mask specified when the event was created.
- EVNBKM2
- This is a 16-bit mask which can be used for informational purposes and is
OR'd into an accumulator and returned to the application when the event
has been satisfied. It is referred to as the POST MASK 2 field in the
POSTC and EVNWC macro descriptions.
- EVNBKLC
- This field is used when creating a list-type event and also when posting
the same event. This field will contain the number of items contained
in the data list.
- EVNBKLS
- This field is used when creating a list-type event and also when posting
the same event. This field will contain the size, in bytes, of a data
list item.
- EVNBKLI
- This field is used when creating a list-type event and also when posting
the same event. This field will contain the list of data items.
Each item in the list has the following format:
- EVNBKLIF
- This is the flag byte; it indicates the status of the data
item.
- EVNBKLIE
- This is the error value if the item is posted with an error.
- EVNBKVLS
- This is an optional user-defined return value area.
- EVNBKLID
- This is the list item data.
- EVNBKE
- This field is used by the EVNWC macro for returning the error value when
an event has been posted with an error.
For CNT, MSK, and CB event types, the value in this field is set by the
application when it issues the POSTC macro. The value can be any
combination of bits except X'80'. The X'80' value is
reserved by the TPF 4.1 system to present a timeout error
indication.
For a LIST event type, issuing a POSTC macro indicating an error for any of
the list items causes the EVNBKE field to be set to X'7F'. The
error value for the list item in error is set in the EVNBKLIE field for that
list item.
- EVNBKL
- Is the size of the area defined by the EV0BK DSECT, which is currently 16
bytes.
The following table indicates the fields used and or modified by the event
macros:
Field Name
| EVNTC
| POSTC
| EVNWC
| SAWNC
|
EVNBKN
| Optional
| Required
| Required
| Required
|
EVNBKC1
| Possibly Required
|
|
|
|
EVNBKM1
| Possibly Required
| Possibly Required
| Modified
| Modified
|
EVNBKM2
|
| Optional
| Modified
| Modified
|
EVNBKLC
| Possibly Required
| Possibly Required
| Modified
| Modified
|
EVNBKLS
| Possibly Required
| Possibly Required
| Modified
| Modified
|
EVNBKLI
| Possibly Required
| Possibly Required
| Modified
| Modified
|
EVNBKE
|
|
| Modified
| Modified
|
Notes:
- Field names are defined in the EV0BK DSECT.
- Fields marked "Possibly Required" depend on the type of event being
specified.
- Fields marked "Modified" are modified by the SVC Handler.
- Fields with no indication are ignored.
Examples
- A count-type event is defined for an ECB using the count value in the
first 2 bytes of CE1CR5.
EVNTC LEVEL=D5,TYPE=CNT
- The same count-type event is defined but the time-out value is specified
as 10 seconds using the TIMEOUT parameter.
EVNTC LEVEL=D5,TYPE=CNT,TIMEOUT=10
- The address for an EV0BK formatted block is specified in R1 for a
count-type event. The time-out in seconds is specified in R7.
The name for the event is specified in the EVNBKN field of EV0BK. If
the specified name is already associated with an event, control transfers to
label ERROR1.
EVNTC BLOCK=(R1),TYPE=CNT,NAME=Y,DUPNAM=ERROR1,TIMEOUT=(R7)
- The address of an EV0BK formatted block is specified in R15 for a
mask-type event. EV0BK field EVNBKM1 contains the mask. A
time-out value is specified in R14.
EVNTC BLOCK=(R15),TYPE=MSK,TIMEOUT=(R14)
- A list of active processors is generated for creating an event. The
list-type event is defined by using the EV0BK block specified in R4.
GENLC CREATE,BLOCK=(R4),DATA=PROCESSOR,INCLUDE=ACTIVE
EVNTC BLOCK=(R4),TYPE=LIST