CBL_THREAD_CREATE_P

Creates a thread from a procedure pointer.

Syntax:

call "CBL_THREAD_CREATE_P" using  by value entry-point
                           by reference    thread-param
                           by value        param-size
                           by value        flags
                           by value        priority
                           by value        stack-size
                           by reference    thread-id

Parameters:

	Using call prototype (see Key)	Picture
`entry-point`	cblt-ppointer	usage procedure-pointer.
`thread-param`	pic x(`n`) null or space terminated	Any data item.
`param-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)
`priority`	cblt-sx4-comp5	pic s9(9) comp-5
`stack-size`	cblt-os-size	pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
`thread-id`	cblt-pointer	usage pointer.

On Entry:

entry-point

Procedure-pointer set to the appropriate entry point of program to execute.

thread-param

Parameter passed to the new thread

param-size

Set to one of the folllowing:

0	Only the address of `thread-param` is passed as the parameter to the entry point in the new thread without any copying of data values
>0	The value of `thread-param` is copied for a length of `param-size` and the address of this copy area is passed to the new thread. The value of `thread-param` will still be intact for the created thread, even if the creating thread changes or deallocates `thread-param` immediately after the CBL_THREAD_CREATE call.

flags

A number in which the bits can be set as follows:

Bit 0

0	Detach thread immediately when the thread terminates.
1	Do not detach thread immediately. Even when the thread has terminated, its resources are not freed until thread is detached.

Bit 1

0	Thread priority is absolute (0 to 100).
1	Thread priority is relative (-100 to +100).

Bit 2

0	Any monitors or mutexes locked by this thread when the thread terminates can cause a run-time system error.
1	An error will not be issued if monitors or mutexes are locked when the thread terminates

Bit 3

0	Create active
1	Create suspended Restriction: This is deprecated in the JVM environment

Bit 4

Restriction: This bit is not supported in JVM COBOL.

0	Multi-threaded Apartment model (MTA)
1	Single threaded Apartment model (STA)

Remaining bits

Reserved.

priority

Sets the priority. Normally, the priority is in the range -100 to+100 and is relative to the current thread's priority. Values of -1 and +1 indicate the smallest decrement/increment that gives the thread a lower/higher priority than the caller (unless the caller already has the lowest/highest possible priority). If a negative/positive value would take the thread's priority lower/higher than is possible, then the lowest/highest value is used. If bit 1 of flags is set to 1, then the priority is an absolute value 0 to 100.

stack-size

Specifies the size of the stack given to the new thread. A value of 0 causes a sensible default to be used. If the parameter appears to be invalid, the run-time system will either ignore it, or return an error indicating an invalid value was provided.

On Exit:

thread-id: A thread identifier.
return-code: A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines.

Comments:

The entry point specified can be implemented in any language.

If the call succeeds and a new thread is created, its thread identifier is stored in thread-id and the RETURN-CODE is set to 0. This is true even if the thread is created detached, however in this case the caller should take care to ensure that the new thread still exists before using the thread-id in any other call.

If the call fails thread-id is set to NULL and an error number is set in RETURN-CODE.