tinit() — Attach and initialize MTF subtasks

Standards

Standards / Extensions	C or C++	Dependencies
Language Environment®	C only

Format

#include <mtf.h>

int tinit(const char *parallel_loadmod_name, int num_subtasks);

General description

Restriction: This function is not supported in AMODE 64.

Initializes the multitasking facility (MTF) environment under MVS™.

To avoid infringing on the user's name space, this nonstandard function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you use LANGLVL(EXTENDED).

To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile with LANGLVL(EXTENDED). When you use LANGLVL(EXTENDED) any relevant information in the header is also exposed.

tinit() is invoked from a main task to dynamically attach and initialize the number of subtasks specified by num_subtasks, where num_subtasks ranges from 1 to MAXTASK (which is defined in the header file mtf.h). After the subtasks have been attached and initialized by tinit(), each of the subtasks will be given a task_id and can then compute independent pieces of the program, in parallel with the main task, under the control of the tsched() and tsyncro() library functions.

The parallel load module (parallel_loadmod_name) must contain all parallel functions and reside in a partitioned data set named in the STEPLIB DD statement of the JCL that runs the program.

The tinit() function may be called by a main task only once before invoking tterm(). Invocations of tinit() after the first are one are terminated with a returned value indicating that MTF is already active.

After tterm() has been called to terminate and remove the MTF environment, or after an abend, tinit() can be called again to create a new MTF environment. The new initialization is independent of the old one and may provide a different number of tasks and/or a different parallel load module.

If tinit() is called from a parallel function, tinit() will be terminated with a returned value indicating that MTF calls cannot be issued from a parallel function.

If tinit() is called by a program running under IMS, CICS®, or DB2®, the request will not be processed and the returned value will indicate that MTF calls are not supported under these systems.

Returned value

If the subtasks have been attached successfully and the MTF environment created, tinit() returns MTF_OK.

If unsuccessful, tinit() sets errno to one of the following values:

Error Code: Description
EACTIVE: MTF has already been initialized and is active.
EAUTOALC: Automatic allocation of standard stream DD has failed.
EMODFIND: Parallel load module was not found.
EMODFMT: Parallel load module has an invalid format.
EMODREAD: Parallel load module was not successfully read.
ENAME2LNG: Parallel load module name is longer than 8 characters.
ENOMEM: There was insufficient storage for MTF-internal areas.
ESUBCALL: The MTF call was issued from a subtask.
ETASKABND: One or more subtasks have terminated abnormally.
ETASKFAIL: The attempt to attach task(s) failed.
ETASKNUM: Number of tasks specified is invalid (<1 or >MAXTASK).
EWRONGOS: MTF is not supported under IMS, CICS or DB2*.

Note: These values are macros and can be found in the mtf.h header file.