gtpc2m4k | C/C++ Language Support User's Guide |
The lodic_ext function is used to check if enough system
resources are available to begin processing low-priority or batch work, and to
determine if an ECB can be suspended (based on the level of available
resources).
An ECB that calls the lodic_ext function with the
LODIC_ECBCREATE or LODIC_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 10). 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 LODIC_SUSPEND parameter forces the ECB to
immediately give up control. The LODIC_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
#include <tpfapi.h>
int lodic_ext(int flags, const void *usrprm);
- flags
- The following flags are defined in tpfapi.h:
- LODIC_ECBCREATE, LODIC_SUSPEND, LODIC_UNMARK, or LODIC_CHECK
- Choose one of the following four parameters.
- LODIC_ECBCREATE
- The ECB is marked as suspendable and a priority class is assigned to the
ECB.
There is no immediate loss of control if you use the
LODIC_ECBCREATE parameter.
Checks are performed to see if the available system resources are above the
shutdown levels defined by the specified priority class (for example, checks
to see if more work can be started).
- 0
- Indicates that system resources are low and that more work cannot be
started.
- 1
- Indicates that more work can be started.
- LODIC_SUSPEND
- The ECB is marked as capable of being suspended, and a priority class is
assigned to the ECB.
The LODIC_SUSPEND parameter will cause the ECB to immediately
lose control unless the ECB is holding a resource and LODIC_HOLD is
not coded.
Checks are performed to see if the available system resources are above the
shutdown levels defined by the specified priority class (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, the ECB is
not immediately suspended. In all cases but one, a return code of 1
will be returned. A return code of 0 is returned in the case where the
ECB does not lose control and the system resources available are below the
shutdown levels.
- 0
- More work cannot be started.
- 1
- More work can be started.
- LODIC_UNMARK
- Removes the ability for the ECB to become suspended.
- Note:
- An ECB marked as being capable of being suspended remains marked as such
until you enter LODIC_UNMARK or until the ECB exits.
- LODIC_CHECK
- Checks are performed to see if the available system resources are above
the shutdown levels defined by the specified priority class (for example, more
work can be started). There is no immediate loss of control if the
LODIC_CHECK parameter is used. The
LODIC_CHECK parameter does not mark or unmark the ECB as an ECB
that can be suspended.
- LODIC_BATCH, LODIC_LOBATCH, LODIC_IBMHI, or LODIC_IBMLO
- Choose only one of the four priority classes.
A priority class is assigned to the ECB.
- LODIC_BATCH is reserved for users.
- LODIC_LOBATCH is reserved for users.
- LODIC_IBMHI is reserved for IBM written E-type
programs.
- LODIC_IBMLO is reserved for IBM written E-type
programs.
A priority class is used with the LODIC_ECBCREATE,
LODIC_SUSPEND, and LODIC_CHECK parameters.
- Note:
- See Table 10 for the shutdown levels of each priority class.
- LODIC_HOLD
- Indicates if the ECB can be suspended while holding a resource
(fiwhc, corhc, tasnc, evnwc, or
glob_lock). LODIC_HOLD can be used with
LODIC_ECBCREATE and LODIC_SUSPEND.
Notes:
- This parameter does not apply to resources held with the lockc
function.
- Coding LODIC_HOLD requires restricted authorization
(OPTIONS=(RESTRICT)) in the IBMPAL macro.
- usrprm
- Points to user data that will be passed to the LODIC user exit.
Otherwise, coding NULL is acceptable.
Normal Return
The return code depends on the shutdown levels that are defined for the
specified priority class (see Table 10).
- 0
- Indicates that the available system resources are below the shutdown
levels defined for the specified priority class (more work should not be
started).
- 1
- Indicates that the available system resources are above the shutdown
levels defined for the specified priority class (more work can be
started).
These return codes do not apply to the LODIC_UNMARK
parameter.
Error Return
Not applicable.
Programming Considerations
- Once an ECB has been 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 LODIC_HOLD is not coded). Once suspended, the ECB
remains suspended until the available system resources return to levels above
the defined shutdown levels.
- The create functions cremc, credc,
swisc_create, crexc, and creec, will pass the
lodic_ext options and the lodic_ext 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 also marked in the same
way. The other create functions, cretc and
cretc_level, do not pass this information.
- When you use a function to create an ECB (such as cremc or
swisc_create), 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_ext function each time before you
create a single ECB. The application calling lodic_ext must
give up control before calling lodic_ext again to help ensure that
ECBs that are created are given a chance to receive control and perform
work. Otherwise, system resource depletion can result from too much
work scheduled but not started.
- ECBs that are marked with LODIC_HOLD 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 back control. Avoid having an
ECB become suspended if it is using a large amount of resources.
- ECBs that are suspended because of a lodic call will be purged
during cycle-down to 1052 state unless they have been previously identified to
survive cycle-down.
- Table 10 provides 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 10, 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 10. 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%
|
- These are the shutdown level values as shipped by IBM.
- IBMLO and IBMHI are reserved for use by IBM.
Examples
The following example creates a new ECB after checking to see if available
resources exist. The ECB is also marked as a low-priority or batch ECB
and is allowed to be suspended while holding resources. The address of
a save area, called passarea, is passed to the LODIC user
exit.
#include <tpfapi.h>
void QZZ0();
·
·
·
rc = lodic_ext( LODIC_ECBCREATE+LODIC_BATCH+LODIC_HOLD,
&passarea );
if (rc) credc( 0, NULL, QZZ1 );
Related Information
lodic-Check System Load and Mark ECB.