CBL_EXEC_RUN_UNIT

Creates a synchronous or asynchronous run unit.

Syntax:

call "CBL_EXEC_RUN_UNIT" using        command-line
                         by value     command-line-len
                         by reference run-unit-id
                         by value     stack-size
                         by value     flags
                         returning    status-code

Parameters:

	Using call prototype (see Key)	Picture
`command-line`	pic x(`n`).	pic x(`n`).
`command-line-len`	cblt-os-size.	pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
`run-unit-id`	cblt-x8-comp5.	pic x(8) comp-5. Must be level 01.
`stack-size`	cblt-os-size.	pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
`flags`	cblt-os-flags.	pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
`status-code`	See Library Routines - Key

On Entry:

command-line

The command passed to the new run unit. This should be the program-name followed by any parameters.

line-length

The length of the command line.

stack-size

This parameter is ignored.

flags

A word indicating how the new run unit is created as follows:

Bit 0

0	CBL_EXEC_RUN_UNIT returns to the caller immediately after creating the child process.
1	CBL_EXEC_RUN_UNIT waits for the new run unit to complete before returning to the caller.

Bit 1

0	The newly created run unit inherits all COBOL and run-time switches, environment variables and open libraries as they exist in the caller at the time of creation.
1	The newly created run unit only inherits all environment variables as they exist in the caller at the time of creation.

Bit 2

0	The newly created run unit inherits the caller's console for screen I/O. Only one member of the coru should access this console at a time, otherwise unpredictable results may be encountered.
1	The newly created run unit has a new console for terminal I/O allocated to it. This console is independent from the parent and can be used for screen I/O.

Remaining bits

Reserved - must be set to 0.

On Exit:

run-unit-id

If bit 0 of flags is not set, the unique handle identifying the new run unit. If bit 0 of flags is set, this value is unchanged.

status-code

Status of operation:

0	Success
157	Out of memory
181	Invalid parameter
200	Internal logic error
255	Called program not found
Other non-zero	Returned error code from the executed program

Comments:

The run unit that makes the call is known as the parent, while the run unit created is known as the child. When the child is created it inherits certain attributes from its parent. The attributes inherited by the child are copies of the attributes in the parent at the exact time of the call; any changes made to the attributes of the parent after the call are not reflected in the child's attributes. Similarly, any changes made to the child's attributes are not reflected in the parent's attributes.

Bit 1 flag controls which attributes of the parent are inherited by the child.

In the .NET environment, the run unit created by this command does not inherit any COBOL or run-time switches, or environment variables. CBL_EXEC_RUN_UNIT does not open libraries for the run unit it creates.

The set of run units containing the initial run unit and all run units created from it is known as the coru.

You should be aware of the following when using run units:

All COBOL programs in the child are in their initial state.
Data can be shared between run units by allocating it as shared memory using CBL_ALLOC_MEM or CBL_ALLOC_SHMEM, and then passing the address of this memory between the run units using CBL_PUT_SHMEM_PTR and CBL_GET_SHMEM_PTR
Open files and heaps are never inherited from the parent.
Screen I/O from one run unit can interfere with that from another run unit causing unexpected results. This is particularly a problem on UNIX but can also be an issue on Windows if the console is being shared by two or more processes. Avoid screen I/O operations from more than one concurrent run unit.

OnUNIX platforms that enable you to create executable files that have either a 32-bit address space, or a 64-bit address space, the run units comprising a coru must use the appropriate address space.

If a 32-bit run-unit creates a 64-bit run unit, no attributes are shared between the run units; this is also true if a 64-bit run unit creates a 32-bit run unit. In either case, the mismatching child run unit is treated as an initial run unit of a new coru.