CBL_THREAD_CREATE

Creates a thread from a named entry point.

Syntax:

call "CBL_THREAD_CREATE" using by reference entry-name
                         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-name`	pic x(`n`) space or null terminated	pic x(`n`) space or null terminated
`thread-param`	pic x(`n`) space or null 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-name

Space or null terminated name for the thread

thread-param

Parameter passed to the new thread

param-size

Set to one of the following values:

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 the thread is detached.

Bit 1

0	Thread priority is relative (-100 to +100).
1	Thread priority is absolute (0 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 .NET environment

Bit 4

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

Remaining bits

Reserved

priority

Set 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

Tell the run-time system how big a stack to give 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.