home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / cobmthrd.zip / MLTITHRD.DOC
Text File  |  1994-02-26  |  6KB  |  138 lines
  1.         Creating Multi-Threaded Applications with the Run Time Environment
  2.  
  3.                 (C) Copyright 1991 Micro Focus Ltd.
  4.  
  5.  
  6. 1.  Creating A Multi-Threaded Application
  7. -----------------------------------------
  8.  
  9. 1.1  Contents
  10. -------------
  11.  
  12.         1. Creating A Multi-Threaded Application
  13.             1.1  Contents
  14.             1.2  Introduction
  15.             1.3  Installing The Support For Multi-Threaded Applications 
  16.             1.4  Example Program
  17.             1.5  Thread Local Data And Shared Data
  18.             1.6  Creating A New Thread Of Execution
  19.             1.7  Thread Termination
  20.             1.8  Restrictions
  21.  
  22.  
  23.  
  24. 1.2  Introduction
  25. -----------------
  26.  
  27. This document describes the current facilities available in the Run
  28. Time Environment to create multi-threaded COBOL applications
  29.  
  30. In a multi-threaded application, the user is able to set off several
  31. concurrent paths of execution within the same program. Each of these paths
  32. of execution is known as a "thread". On OS/2, this facility is mapped onto OS/2
  33. threads. On DOS it is mapped onto the run-time's own pre-emptive task
  34. switching which emulates the behavior of OS/2 threads. Generally, each thread will want to
  35. have its own thread local data as well as having access to shared data that
  36. is available to all threads. 
  37.  
  38.  
  39. 1.3  Installing The Support For Multi-Threaded Applications
  40. -----------------------------------------------------------
  41.  
  42. The Run Time Support to enable the creation of new threads of execution is
  43. contained in the files COBTHRED.DLE (for DOS) and COBTHRED.DLL (for OS/2).
  44. This support MUST be installed in the system by specifying the file name in
  45. the INSTALL section of a .CFG file (see Build chapter in the Run Time
  46. Environment Operating Guide). If you are using Workbench or the Run Time
  47. Environment then this will be MFWB.CFG or RUN.CFG respectively, otherwise it
  48. should be included in the .CFG file you have created when Building your
  49. application.
  50.  
  51.  
  52. 1.4  Example Program
  53. --------------------
  54.  
  55. The supplied example program MTHELLO.CBL is a simple demonstration of how
  56. to use the above call. This example creates a number of threads each of
  57. which updates a different position on the screen with a box that flashes
  58. on or off.
  59.  
  60.  
  61. 1.5  Thread Local Data And Shared Data
  62. --------------------------------------
  63.  
  64. In this implementation, any data that you wish to be shared amongst all threads
  65. must be declared as being EXTERNAL in its WORKING-STORAGE definition. Any
  66. data not marked as EXTERNAL will be assumed to be thread local. 
  67.  
  68.  
  69. 1.6  Creating A New Thread Of Execution
  70. ---------------------------------------
  71.  
  72. A new thread of execution is initiated by making the following call :
  73.  
  74. CALL OS2API "PC_CREATE_THREAD" USING BY REFERENCE thread-id,
  75.                                      BY REFERENCE entry-name,
  76.                                      BY VALUE stack-size SIZE 2
  77.  
  78. where parameters are as follows :
  79.  
  80.     thread-id       PIC X(4)            on exit, contains a handle that
  81.                                         uniquely identifies the new thread.
  82.                                         This handle is known as the thread-id.
  83.  
  84.     entry-name      PIC X(n)            on entry, contains the space-terminated
  85.                                         entry point at which the thread is to
  86.                                         start execution
  87.  
  88.     stack-size      PIC XX COMP-5       on entry, this contains the size of
  89.                                         the stack to be allocated to the new
  90.                                         thread. A stack size of zero means
  91.                                         that the new thread should inherit the
  92.                                         stack size of its creator thread.
  93.  
  94.                                         It should be noted that there is only
  95.                                         approximately 50K of stack space 
  96.                                         available in the run-time within
  97.                                         which all thread stacks must be
  98.                                         allocated. The stack size of the first
  99.                                         COBOL thread is always 8K bytes.
  100.  
  101.                                         A minimum stack size of 2K is
  102.                                         recommended
  103.  
  104.  
  105.     and where OS2API has been defined to be CALL CONVENTION 3 in the SPECIAL
  106.     NAMES section of the program.
  107.  
  108. This call commences a new thread of execution at the COBOL entry point 
  109. defined by 'entry-name'. The new thread in the program containing the
  110. entry point will have its Working-Storage section (i.e. thread local data)
  111. initialised to the current value of the Working-Storage in the copy of the
  112. program that exists in the creating thread. If the program did not exist
  113. in the creating thread, then the Working-Storage will be initialised as for
  114. a fresh program load.
  115.  
  116. The new thread will inherit the command line, all open libraries and all
  117. open COBOL files from the creating thread.
  118.  
  119.  
  120. 1.7  Thread Termination
  121. -----------------------
  122.  
  123. A particular thread of execution terminates when it executes a STOP RUN
  124. statement. You must ensure that all secondary threads have been terminated
  125. before actually terminating the initial thread.
  126.  
  127.  
  128. 1.8  Restrictions
  129. -----------------
  130.  
  131. Multi-threaded applications can only be executed in protected mode. This
  132. means you must use either OS/2 or XM on DOS.
  133.  
  134. Also, full multi-threading is only supported in INT/GNT programs. You can
  135. not use this call to multi-thread a linked OBJ program. However, you can
  136. use it to execute different OBJ programs in different threads.
  137.  
  138.