gtpc2m4kC/C++ Language Support User's Guide

lodic_ext-Check System Load and Mark ECB with Extended Options

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:

  1. This parameter does not apply to resources held with the lockc function.

  2. 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

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.