This general macro is used to check if enough system resources are
available to begin processing low-priority or batch work, and to determine if
an entry control block (ECB) can be suspended (based on the level of available
resources).
An ECB that calls the LODIC macro with the ECBCREATE or SUSPEND parameters
is marked as a low-priority ECB. Once marked, the ECB can be suspended
when system resources are below the shutdown levels defined for a specified
priority class (see Table 8). Even though the ECB is marked as being able to be
suspended, the ECB cannot be suspended until it gives up control. In
most cases the SUSPEND parameter forces the ECB to immediately give up
control. The ECBCREATE parameter does not force the ECB to immediately
give up control; the ECB must wait until it gives up control by entering
a post-interrupt routine. Once suspended, the ECB does not receive
control again until enough system resources are available.
Format
- label
- A symbolic name may be assigned to the macro statement.
- CHECK
- Checks are performed to see if the available system resources are above
the shutdown levels defined by the CLASS parameter (for example, checks to see
if more work can be started). There is no immediate loss of control if
you use the CHECK parameter. Control returns to the label specified by
the AVAIL parameter (if coded) if more work can be started; otherwise
control returns to the next sequential instruction. The CHECK parameter
does not mark or unmark the ECB as capable of being suspended.
- ECBCREATE
- The ECB is marked as capable of being suspended and a priority class is
assigned to the ECB.
There is no immediate loss of control if the ECBCREATE parameter is
used.
Checks are performed to see if the available system resources are above the
shutdown levels defined by the CLASS parameter (for example, checks to see if
more work can be started). Control returns to the label specified by
the AVAIL parameter (if coded) if more work is allowed to be started;
otherwise, control returns to the next sequential instruction.
- Note:
- For compatibility with the TPF/MVS product, R14 will contain either 0 (no
work can be started), or 1 (work can be started).
- SUSPEND
- The ECB is marked as capable of being suspended and a priority class is
assigned to the ECB.
The SUSPEND parameter causes the ECB to immediately lose control unless the
ECB is holding a resource and HOLD=NO is coded.
Checks are performed to see if the available system resources are above the
shutdown levels defined by the CLASS parameter (for example, checks to see if
more work can be started). If the available system resources are below
the shutdown levels and the ECB is able to lose control, then the ECB is
immediately suspended. If the available system resources are above the
shutdown levels, then the ECB is not immediately suspended. Control
returns to the label specified by the AVAIL parameter (if coded) in all cases
except one. The one case in which control does not return to the label
specified by the AVAIL parameter is the case where the ECB does not lose
control and the available system resources are below the shutdown
levels. In this case, control always returns to the next sequential
instruction.
- UNMARK
- Removes the ability for the ECB to become suspended.
- Note:
- An ECB marked as capable of being suspended remains marked as such until the
LODIC macro with the UNMARK parameter is entered or until the ECB
exits.
- AVAIL=label1
- The location to which to branch if the available system resources are
above the shutdown levels defined by the CLASS parameter (for example, more
work can be started). This keyword is used with the CHECK, ECBCREATE,
and SUSPEND parameters. Without the AVAIL parameter, control always
returns to the next sequential instruction.
- CLASS=BATCH|LOBATCH|IBMHI|IBMLO
- Assigns a priority class to the ECB. The priority class defines a
set of unique shutdown values that are used to determine when the ECB will be
suspended and when the ECB will be unsuspended. The classes are BATCH,
LOBATCH, IBMHI, and IBMLO. Priority classes BATCH and LOBATCH are
supported for user programs. Priority classes IBMHI and IBMLO are
reserved for E-type programs by the TPF system.
The CLASS parameter is used with the CHECK, ECBCREATE, and SUSPEND
parameters.
- Note:
- See Table 8 for the shutdown levels of each priority class.
- HOLD
- Indicates if the ECB can be suspended while holding a resource (FIWHC,
CORHC, ENQC, TASNC, EVNWC, or SYNCC LOCK).
Notes:
- Does not apply to resources held with the $LOCKC macro.
- The HOLD=YES parameter requires restricted authorization
(OPTIONS=(RESTRICT)) in the IBMPAL macro.
- IGNORE
- Defines which block types are ignored when determining if the available
system resources are above the shutdown levels defined by the CLASS
parameter. The block types included will be ignored when determining if
a running ECB should be suspended or if a suspended ECB should resume
running. The IGNORE parameter is used with the CHECK, ECBCREATE, and
SUSPEND parameters. Any subset of the following block types are
supported:
- CMB
- Common Block
- ECB
- Entry Control Block
- FRM
- 4 KB Frame
- IOB
- Input/Output Work Block
- SWB
- System Work Block.
- Note:
- The IGNORE keyword requires restricted authorization (CHECK=RESTRICT) in the
IBMPAL macro.
- CHECKONLY
- Defines which block types are checked when determining if the available
system resources are above the shutdown levels defined by the CLASS
parameter. Only the block types included are checked when determining
if a running ECB should be suspended or if a suspended ECB should resume
running. The CHECKONLY parameter is used with the CHECK, ECBCREATE, and
SUSPEND parameters. Any subset of the following block types is
supported:
- CMB
- Common Block
- ECB
- Entry Control Block
- FRM
- 4 KB Frame
- IOB
- Input/Output Work Block
- SWB
- System Work Block.
- Note:
- The CHECKONLY keyword requires restricted authorization (CHECK=RESTRICT) in
the allocator.
- USRPRM=Rx
- Allows user data to be passed from the application program to the LODIC
service routine user exit. The specified register index is
passed. R0 through R7 are valid.
Entry Requirements
- R9 must contain the address of the ECB being processed.
- The IGNORE and CHECKONLY keywords and the HOLD keyword specified with YES
require the issuing program to have restricted macro usage
authorization.
Return Conditions
- For the ECBCREATE, SUSPEND, or CHECK parameters, control returns to the
label specified by AVAIL, if AVAIL is coded and if resources are available for
the specified priority class; otherwise, control returns to the next
sequential instruction.
- For the UNMARK parameter, control always returns to the next sequential
instruction.
- The return code depends on the shutdown levels defined for the specified
priority class (see Table 8).
- R14 contains a value of 1 if resources are available for that priority
class; otherwise, R14 contains a value of 0
- R15 cannot be predicted.
Programming Considerations
- This macro can be run on any I-stream.
- Once an ECB is marked as capable of being suspended, it becomes suspended
whenever the ECB gives up control and the available system resources are below
the defined shutdown levels (unless the ECB is holding a resource and HOLD=NO
is coded). Once suspended, the ECB remains suspended until the
available system resources return to levels above the defined shutdown
levels.
- The create macros CREMC, CREDC, SWISC, CREXC, and CREEC will pass the
LODIC parameters and the LODIC priority class information from the parent ECB
to the child ECB. If the parent ECB is marked as capable of being
suspended, the child ECB is marked in the same way. The other create
macro, CRETC, does not pass this information.
- When you use a macro to create an ECB (such as CREMC or SWISC), the ECB is
not created immediately. First a system work block (SWB) is placed on a
list in the CPU loop. The ECB is not actually created until the SWB is
dispatched from the list. Because of this delay, call the LODIC macro
each time before creating a single ECB. The application issuing the
LODIC macro must give up control before calling LODIC again to help ensure
that ECBs created are given a chance to receive control and perform
work. Otherwise, system resource depletion can result from too much
work being scheduled and not started.
- ECBs marked with HOLD=YES may hold resources while suspended.
- Suspended ECBs that are using a large amount of resources can result in
conditions in which these ECBs never get control back. Avoid having an
ECB become suspended if it is using a large amount of resources.
- ECBs suspended by a LODIC macro call are purged during cycle-down to 1052
state unless they have been previously identified to survive
cycle-down.
- Table 8 shows the shutdown levels of each priority class. The
values given are the minimum percentage of each block type that must be
available for ECBs to continue running.
In general, when the availability of a particular block type falls below a
shutdown percentage defined in Table 8, ECBs labeled with the associated priority class will be
suspended and will remain suspended until the availability of that block type
rises above the shutdown percentage.
Table 8. Priority Class Table (Shutdown Levels)
Priority Class
| Block Type
|
| CMB
| ECB
| FRM
| IOB
| SWB
|
LOBATCH
| 96%
| 96%
| 96%
| 96%
| 96%
|
BATCH
| 48%
| 48%
| 48%
| 48%
| 48%
|
IBMLO
| 96%
| 96%
| 96%
| 96%
| 96%
|
IBMHI
| 32%
| 32%
| 32%
| 32%
| 32%
|
- Note:
-
- These are the shutdown level values as shipped by IBM.
- IBMLO and IBMHI are reserved for use by IBM.
|
Examples
- The following example:
- Forces the ECB to immediately give up control
- Suspends the ECB whenever the number of available ECBs, SWBs, 4 KB frames,
or CMBs falls below the shutdown level for the BATCH priority class
- Does not allow the ECB to receive control until the number of available
ECBs, SWBs, 4 KB frames, and CMBs are above that shutdown level
- Allows the ECB to be suspended even if the ECB is holding a
resource.
LODIC SUSPEND,CLASS=BATCH,IGNORE=(IOB),HOLD=YES,AVAIL=MOREWORK
- The following example:
- Indicates that this ECB will be suspended whenever the number of available
ECBs, 4 KB frames, or SWBs are below the shutdown level for the LOBATCH
priority class
- Returns control to the GOAHEAD label if more work can be started, (based
on the number of available ECBs, SWBs, or FRMs); otherwise, returns
control to the next sequential instruction.
- Passes register 2 to the LODIC macro service routine user exit
LODIC ECBCREATE,CLASS=LOBATCH,CHECKONLY=(ECB,FRM,SWB),AVAIL=GOAHEAD,USRPRM=R2
- The following example:
- Checks if there are enough system resources to start more work
- Returns control to label GOSTART if available system resources are above
the shutdown levels defined for the LOBATCH priority class; otherwise,
returns control to the next sequential instruction.
LODIC CHECK,AVAIL=GOSTART,CLASS=LOBATCH
- The following example sets this ECB so it cannot be suspended again unless
another LODIC or TMSLC macro is issued.
LODIC UNMARK
- As soon as resources are available, additional ECBs are created to perform
more work.
Create macros copy the LODIC characteristics to their child ECBs.
This is why the LODIC macro with the UNMARK parameter is placed before the
CREMC macro. The ECB that is being created for entry to BRFM will not
have the low-priority of its creating ECB.
CHECK DS 0H
LODIC SUSPEND,CLASS=BATCH,AVAIL=DOWRK
B CHECK
DOWRK DS 0H
LODIC UNMARK
CREMC BRFM
B CHECK