Threads are either created by one of the following methods:
Threads created by the first two methods are called COBOL threads. Threads created directly by the operating system are called other-language threads.
As the creation and manipulation of COBOL threads is portable, and the preferred method, we will only deal with them here.
The starting point for a thread must be either a non-nested Program-Id, a COBOL entry-point or an externally visible routine written in another language, such as C. It must not be a nested program, or a section or paragraph name.
The name of the starting point can be specified as a text string. The overhead in using a text string to find the entry point is equivalent to resolving the verb CALL identifier. It is possible to avoid this overhead by using a procedure pointer as the object of a START verb.
The starting point for every created thread is provided with only one parameter. If the BY CONTENT phrase is used in passing this parameter, a copy of it is made by the system before the thread is created, leaving the calling thread free to modify the original parameter upon return from the START verb.
Creation of a thread with a non-detached handle (via the IDENTIFIED BY clause) enables the return value to be obtained later by the WAIT verb. After the WAIT verb has completed the specified thread handle becomes invalid and all resources associated with the subject thread are released.
A STOP RUN RETURNING statement in the created thread does not end the run unit; it simply provides a return value and terminates the thread. It is equivalent to:
call 'CBL_THREAD_EXIT' using by value address of thread-parm.
A STOP RUN statement in other-language threads or in the main thread of a run unit not created by CBL_THREAD_CREATE will wait for all active COBOL threads to finish and then terminate the run unit.
Return values from threads are always pointers. This allows you to return both simple and complex data structures.
A thread can terminate itself with STOP RUN or a call to CBL_THREAD_EXIT. A thread also terminates normally when the starting point program exits via EXIT PROGRAM or GOBACK. It is also sometimes useful for another thread to cause a COBOL thread to be terminated. The CBL_THREAD_KILL routine achieves this.
Example - Creating and Terminating a Thread
$set reentrant
Data Division.
Working-Storage Section.
01 thread-handle usage pointer.
01 thread-return usage pointer.
Linkage Section.
01 thread-parm picture x(32).
01 thread-return-record picture x(32).
Procedure Division.
*> Starting point
call 'CBL_THREAD_CREATE'
using 'CREATED ' *> Note the space before the second single-quotation-mark
'This is a 32 character parameter'
by value 0 *> Optional parameter size
1 *> Flag to create non-detached
0 *> Default priority
0 *> Default stack
by reference thread-handle
if return-code = 0
call 'CBL_THREAD_WAIT' using
by value thread-handle
by reference thread-return
set address of thread-return-record
to thread-return
display thread-return-record
end-if
stop run.
Entry "CREATED" using thread-parm.
display thread-parm
stop run returning address of thread-parm.
This application simply creates a thread with the starting point CREATED. The thread displays its parameter and returns the address of that parameter for use in the parent thread. The STOP RUN RETURNING in the CREATED thread does not end the run unit, instead it simply provides a return value and terminates the thread. It is equivalent to:
call 'CBL_THREAD_EXIT' using by value address of thread-parm.