Previous Topic Next topic Print topic


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.

Previous Topic Next topic Print topic