tmslc: ECB time slice facility

Use this function to enable or disable time slicing for an ECB.

When an ECB is enabled for time slicing, the ECB will lose control at defined time intervals. This allows other tasks in the system to receive control.

Last updated

  • Changed in 2023.
  • Changed in 2021.
  • Changed for PUT15 (information only; no code change).
  • Changed for PUT14.
  • Changed for PUT04.
  • Changed for PUT00.

Format

#include   <tpf/sysapi.h>
int        tmslc(int flags, char *name);
flags
The following flags are defined in sysapi.h:
TMSLC_ENABLE or TMSLC_DISABLE
Choose only one of the previous options.
TMSLC_ENABLE
Allow the ECB to time slice.
When the entry control block (ECB) reaches the RUNTIME value, it gets suspended. The ECB will remain suspended for the value specified in the MINSUSP parameter.
Note:
  1. RUNTIME and MINSUSP are values defined with the name parameter.
  2. If you do not specify the TMSLC_HOLD parameter and the ECB is holding a resource, the ECB will not get suspended.
TMSLC_DISABLE
Disable time slicing.

Return the ECB to normal operation.

TMSLC_HOLD
This optional parameter is valid only for the TMSLC_ENABLE option. This optional parameter indicates if the ECB can be suspended while holding a resource (fiwhc, corhc, tasnc, evnwc, or glob_lock).
Note: This does not apply to resources held with the lockc function.
TMSLC_LETRUN
This optional parameter is valid only for the TMSLC_DISABLE option. If you code the TMSLC_LETRUN parameter, the ECB will not lose control. If you do not code the TMSLC_LETRUN parameter, the ECB will lose control unless the ECB was not enabled with the TMSLC_HOLD parameter and the ECB is currently holding a resource.
name
One of the following values:
  • A pointer to a 1- to 8-character time-slice name if the TMSLC_ENABLE value is specified for the flag parameter. The time-slice name must be uppercase alphanumeric and null-terminated. The time-slice name is associated with the following parameters:
    • RUNTIME
    • MAXTIME
    • MINSUSP
    • MAXECB
    The predefined time-slice names and values of the associated parameters are shown in Table 1.
  • Null if the TMSLC_DISABLE value is specified for the flag parameter.

Normal return

The return code will be 0.

Error return

A negative return code indicates that an error occurred:
-1
The name specified for the name parameter is not recognized.
-2
The maximum number of ECBs that can be time sliced is already active for the specified time-slice name.

Programming considerations

  • An ECB enabled for time slicing must never issue a LOCKC macro unless the program that issues the lock request was allocated with the NOTIMESLICE program attribute.
  • An ECB enabled for time slicing must never update a global field or other storage area that can be updated simultaneously by other ECBs unless the program that makes the update was allocated with the NOTIMESLICE program attribute.
  • Programs allocated with the NOTIMESLICE program attribute will not lose control when time slicing is active. If a time slice occurs while the program is processing, the time slice will be delayed until the program gives up control.
  • Coding the TMSLC_LETRUN parameter is advantageous only in a highly repetitive loop where time slicing is enabled and disabled frequently. Otherwise, to avoid timeout errors, do not specify the TMSLC_LETRUN parameter.
  • An ECB that is enabled for time slicing and that is running with the TMSLC_HOLD parameter can hold a resource while suspended. This can cause hang conditions. Resources held by an ECB that can be time sliced should not be needed elsewhere.
  • An ECB that is enabled for time slicing may be exited with a 000010 system error if the TMSLC_HOLD parameter is not specified. This can occur if the ECB is holding a resource (which prevents time slicing) and has been running without giving up control for greater than the time allowed by the application timeout value (500 ms).
  • An ECB will exit with a 000010 system error if the ECB is not forced to give up control and the ECB continues to run for 500 ms without giving up control.
  • The maximum amount of accumulated run time that an ECB enabled for time slicing is allowed before exiting with a 002010 system error is not reset each time the TMSLC_ENABLE parameter is issued. The amount of time set for the MAXTIME value should allow the ECB to complete its task.
  • ECBs that are suspended because of a tmslc call will be purged during system cycle-down to 1052 state unless they have been previously identified to survive cycle-down.
  • Resource control is shipped with predefined time-slice names. Table 1 shows the predefined time-slice names and values of the parameters associated with them.
    Table 1. Time-slice name table
    Time-slice name Values
    RUNTIME MAXTIME MINSUSP MAXECB
    IBMBEV 50 ms 10000 ms 0 ms 9999
    IBMDEBUG 300 ms 0 ms 0 ms 50
    IBMHIPRI 100 ms 10000 ms 100 ms 50
    IBMINDEF 50 ms 0 ms 2000 ms 20
    IBMLOPRI 50 ms 20000 ms 1000 ms 50
    IBMPARSE 50 ms 0 ms 100 ms 50
    IBMRT4J 1 ms 0 ms 0 ms 9999
    ILDAP 50 ms 0 ms 10 ms 50
    IBMTRANS 50 ms 0 ms 0 ms 9999
    • These are the values for the time-slice name parameters as shipped by IBM®.
    • To add new time-slice names, use the ZTMSL command or the TMSLC macro with the ASSIGN parameter. You can also use the ZTMSL command to display, change, and remove time-slice names.

Examples

The following example allows an ECB to be time sliced based on the attributes associated with the time-slice name, BIGSORT. The ECB can be time sliced even if it is holding a resource. 
#include <tpf/sysapi.h>
void QZZ0();
    ⋮
    rc = tmslc( TMSLC_ENABLE+TMSLC_HOLD, "BIGSORT" );
    if (rc < 0)
        /* warn the user that an error occurred */
    else
        /* start running in time slice mode */
        ⋮
    tmslc( TMSLC_DISABLE, NULL );