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.