gtpc2m7n | C/C++ Language Support User's Guide |
This function is used 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.
Format
#include <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.
Notes:
- RUNTIME and MINSUSP are values defined with the name
parameter.
- If you do not specify TMSLC_HOLD 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 TMSLC_LETRUN, the ECB will not lose
control. If you do not code TMSLC_LETRUN, the ECB will
lose control unless the ECB was not enabled with TMSLC_HOLD and
the ECB is currently holding a resource.
- name
- The time-slice name parameter is a pointer to a 1- to
8-character name. This name must be null-terminated.
The time-slice name has four time-slice parameters associated with it:
RUNTIME, MAXTIME, MINSUSP, and MAXECB.
The predefined time-slice names and values of the parameters associated
with them are shown in Table 19.
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
- This macro cannot be run while the system is in restart.
- Using the tmslc function requires authorization to issue a
restricted function.
- Do not use this function so that time slicing is enabled
throughout the life of the transaction because there is no protection against
having an ECB that can be time-sliced call a segment that cannot allow
time-slicing.
- Only enable time slicing in specific CPU-intensive code paths. Time
slicing is not supported across TPF services such as:
- Calls to TPF real-time segments (CYYM, CYYA, BPKD, and others)
- TPFDF library functions
- TPF application programming interface (API) library functions
because these services may reference shared memory, issue $LOCKC macros,
or hold critical resources. Ensure that time slicing is disabled before
calling such system services.
Time slicing can be enabled across standard C library functions that are
supported by the TPF 4.1 system and have been identified as not being
modified for the TPF system environment.
- An ECB enabled for time slicing must never issue a $LOCKC macro.
- An ECB enabled for time slicing must never update a global field or other
storage area that can be updated simultaneously by other ECBs.
- Coding TMSLC_LETRUN is advantageous only in a highly
repetitive loop where time slicing is enabled and disabled frequently.
Otherwise, to avoid timeout errors, do not specify
TMSLC_LETRUN.
- 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 a 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 three predefined time-slice names.
Table 19 shows the predefined time-slice names and values of the
parameters associated with them.
Table 19. Time-Slice Name Table
Time-Slice Name
| RUNTIME Value
| MAXTIME Value
| MINSUSP Value
| MAXECB Value
|
IBMLOPRI
| 50 ms
| 20000 ms
| 1000 ms
| 50
|
IBMHIPRI
| 100 ms
| 10000 ms
| 100 ms
| 50
|
IBMINDEF
| 50 ms
| 0 ms
| 2000 ms
| 20
|
- These are the values for the time-slice name parameters as shipped by
IBM.
- IBMLOPRI, IBMHIPRI, and IBMINDEF are reserved for use 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 <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 );
Related Information
None.