Application Configuration System | Library Manager |
The Concurrency support provided with this COBOL system enables several programs to be active at the same time to achieve better use of the Central Processing Unit (CPU) and more sophisticated application programming techniques.
The Micro Focus Run-time Environment (RTE) provides support for the concurrent operation of run-units. A run-unit consists of your main COBOL program and all the programs or subprograms called by the main program, directly or indirectly. A run-unit, therefore, can be a single program or a suite of programs.
These run-units can communicate with each other using library routines to access a shared memory area. Descriptions of these routines are contained at the end of this chapter.
16-bit OS/2:
On 16-bit OS/2, this concurrency support facility is mapped onto
OS/2 threads.
16-bit Windows:
On 16-bit Windows this concurrency support facility is mapped onto the run-time
system's own co-operative task switching.
32-bit:
On 32-bit COBOL systems this concurrency support facility is mapped onto an
operating system's process.
DOS:
On DOS, it is mapped onto the run-time system's own preemptive task switching
which emulates the behavior of OS/2 threads.
The following sections describe how to install Concurrency support, how to manage run-units and how to enable run-units to communicate with one another.
16-bit:
On the 16-bit COBOL system, the run-time support to enable the creation of new
run-units is contained in the files cobenv.dle (for
DOS), cobenv.dll (for OS/2), and
cobenv.dlw (for Windows). You must install this support in the
system by specifying the filename in the INSTALL section of a
.cfg file. For the Run-time Environment, it is run.cfg;
otherwise, it is the .cfg file you created when building your
application.
Alternatively, you can load the relevant module by simply putting a CALL statement to the module at the start of your initial run-unit, before any of the services below are invoked.
32-bit:
On 32-bit systems, the support is available in the standard run-time system.
An example program, condemo.cbl, that makes use of most of the routines described below, is included with the sample programs. We recommend that you study this example program in conjunction with reading this chapter.
When dealing with run-units, you might find it useful to understand the following terminology and concepts:
On creation, the child inherits certain attributes from its parent. The attributes inherited are copies of the parent's attributes at the exact time of the call; any changes made to the parent's attributes after the call are not reflected in the child's attributes. Similarly, any changes made to the child's attributes are not reflected in the parent's attributes.
You should be aware of the following when using run-units:
There are a number of COBOL library routines provided for managing run-units:
Routine
|
Description
|
---|---|
CBL_EXEC_RUN_UNIT | Creates an asynchronous COBOL run-unit. |
CBL_YIELD_RUN_UNIT | Yields the remainder of a run-unit's time-slice to unspecified run-units. |
CBL_CULL_RUN_UNITS | Clears any dead run-units. |
Full descriptions of these routines are contained at the end of this chapter.
16-bit on Windows:
Concurrency on the 16-bit COBOL system for Windows is implemented in a
non-preemptive (cooperative) manner. This means that if the current thread does
not give up its process time (by yielding its time slice), other threads will
not execute. You can yield a time slice by calling PC_WIN_YIELD (see your Programmer's
Guide to Creating User Interfaces for details of writing Windows
programs.
16-bit on DOS, Windows and OS/2:
Because of the architecture of the 16-bit COBOL run-time system on DOS, Windows
and OS/2, we advise that you do not create more than four run-units, and that
you keep the stack requirements for each run-unit to a minimum. Each run-unit
created reduces the maximum limit for the number of programs loaded. For
example, an 8K stack for an additional run-unit reduces the number of programs
loadable by about 30.
Named values and dynamically allocated shared memory provide two means by which run-units can communicate with one another.
Named memory provides a way of passing pointers between different run-units using a name defined at compile time. Named values can be read simultaneously by all units in the coru because the run-time system protects and serializes any updates. The maximum number of named values that can be defined is dependent upon the amount of memory your machine has.
The pointer value could, for example, be a pointer to a block of dynamically allocated memory. Any currently executing run-unit can access this block of memory by simply fetching its address using the name previously assigned. If many run-units wish to alter data in that block of memory, you will need some kind of semaphoring to maintain the integrity of the data.
Shared memory is owned by the coru, so it is freed when the coru terminates. Conversely, non-shared memory is owned by the program that created it, so it is freed when the program is canceled.
The following routines are provided to enable run-units to make use of shared and/or dynamically allocated memory using named values.
Routine
|
Description
|
---|---|
CBL_PUT_SHMEM_PTR | Creates or updates a named value. |
CBL_GET_SHMEM_PTR | Reads a named value. |
CBL_ALLOC_MEM | Dynamically allocates memory. |
CBL_FREE_MEM | Frees dynamically allocated memory. |
Note: Data is not shared between run-units unless explicitly specified using CBL_GET_SHMEM_PTR and CBL_PUT_SHMEM_PTR
The following COBOL system library routines are available.
CBL_ALLOC_MEM | Dynamic memory allocation |
CBL_FREE_MEM | Free dynamically allocated memory |
X"91" function 60/61 | Fixing data in memory (available only in DOS). |
CBL_CULL_RUN_UNITS | Clear dead run-units |
CBL_EXEC_RUN_UNIT | Create run-unit |
CBL_GET_SHMEM_PTR | Read named value |
CBL_PUT_SHMEM_PTR | Create/update named value |
CBL_YIELD_RUN_UNIT | Yield the current run-unit |
The multiple run-unit routines enable you to make use of the Concurrency support provided with this system.
To use these routines with the 16-bit COBOL system, you must place the module cobenv.dle (DOS), cobenv.dll (OS/2) or cobenv.dlw (Windows) in the install section of your trigger's configuration file. The routines work only with .int and .gnt files. They do not work with linked executable files.
Dynamically allocates memory.
call "CBL_ALLOC_MEM" using mem-pointer by value mem-size flags returning status-code
mem-pointer |
usage pointer. Must be level 01. |
mem-size |
pic x(4) comp-5. |
flags |
pic x(4) comp-5. |
status-code |
See Key in the Preface |
mem-size |
The number of bytes of memory to allocate. | ||||||
flags |
The type of memory required:
|
mem-pointer |
A pointer to the memory allocated. The allocated memory is not initialized. |
The memory allocated is not initialized to any value.
You must set either the ALIGN"4" or ALIGN"8" Compiler directive if you use this routine.
Updates to any shared memory allocated to this function are not serialized or protected by the run-time system; you should use semaphores to maintain the integrity of the data.
Nonshared memory is owned by the program that created it, and is released when the program is canceled if it hasn't already been released using CBL_FREE_MEM routine. Shared memory is owned by the COBOL run-unit (coru) - the set of run-units containing the initial run-unit and all run-units created from it; it is released when the coru is terminated.
32-bit:
With 32-bit run-time systems, the maximum size of nonshared memory is
restricted only by your operating system (unless the -l run-time switch is set).
The size for shared memory allocated using this routine is limited to a maximum
of around of 64000 bytes.
32-bit on UNIX:
With the 32-bit run-time system on UNIX, the maximum size of nonshared memory
is restricted only by the operating system (unless the -l run-time switch is
set). The size for shared memory allocated using this routine is limited to a
maximum of around of 64000 bytes.
32-bit on Windows NT and OS/2:
With the 32-bit run-time systems on Windows NT and OS/2 V2, the maximum size of
nonshared memory is restricted only by the operating system. The run-time
tunable, shared_memory_segment_size
, can be used to set the
maximum size. The default is 65536, and the minimum is 8192 bytes.
Clears any dead run-units.
call "CBL_CULL_RUN_UNITS"
None
This routine clears any run-units that have been terminated by a STOP RUN or kill, but have not yet been removed.
16-bit:
On the 16-bit COBOL system, this routine works only with .int and .gnt
files. It does not work with linked object code.
Introduction to Run-unit Handling Routines
Creates an asynchronous run-unit.
call "CBL_EXEC_RUN_UNIT" using command-line by value command-line-len by reference run-unit-id by value stack-size flags returning status-code
command-line |
pic x(n). |
command-line-len |
pic x(4) comp-5. |
run-unit-id |
pic x(8) comp-5. Must be level 01. |
stack-size |
pic x(4) comp-5. |
flags |
pic x(4) comp-5. |
status-code |
See Key in the Preface |
command-line |
The command passed to the new run-unit. This should be the program name followed by any parameters. |
line-length |
The length of the command line. |
stack-size |
Suggests the size of the stack (in bytes) to be allocated to
the new run-unit. Specifying zero for this parameter causes the child's stack to
be the same size as the parent's.
With the 16-bit COBOL system, a minimum of 2K must be allocated. DOS, Windows and OS/2 allocate 8K for the stack of the initial run-unit. This parameter is ignored if running with a 32-bit COBOL system. |
flags |
Reserved for future use. Must be zero. |
run-unit-id |
The unique handle identifying the new run-unit. | ||||||||
status-code |
Status of operation:
|
You must set either the ALIGN"4" or ALIGN"8" Compiler directive if you use this routine.
The run-unit that makes the call is known as the parent, while the run-unit created is known as the child. On creation, the child inherits certain attributes from its parent. The attributes inherited by the child are copies of the attributes in the parent at the exact time of the call; any changes made to the attributes of the parent after the call are not reflected in the child's attributes. Similarly, any changes made to the child's attributes are not reflected in the parent's attributes.
The set of run-units containing the initial run-unit and all run-units created from it is known as the coru.
You should be aware of the following when using run-units:
16-bit:
On the 16-bit COBOL system, this routine works only with .int and .gnt
files. It does not work with linked object code.
Introduction to Run-unit Handling Routines
Frees dynamically allocated memory.
call "CBL_FREE_MEM" using by value mem-pointer returning status-code
mem-pointer |
usage pointer. |
status-code |
See Key in the Preface |
mem-pointer |
The pointer returned when the memory was allocated using CBL_ALLOC_MEM. |
None
This routine releases memory allocated by the CBL_ALLOC_MEM routine.
Reads a named value.
call "CBL_GET_SHMEM_PTR" using node-value node-name returning status-code
node-value |
usage pointer. |
node-name |
Group item defined as: |
name-length |
pic x comp-5 value n. |
name |
pic x(n) value "name". |
status-code |
See Key in the Preface |
node-name |
The length of name. |
name |
The value assigned to node-name. |
node-value |
The value of the named value. |
Named values provide a way of passing pointers between different run-units using a name agreed at run time. Named values can be read simultaneously by all units in the coru because the run-time system protects and serializes any updates. The maximum number of named values depends on how much memory your machine has.
16-bit:
On the 16-bit COBOL system, this routine works only with .int and .gnt
files. It does not work with linked object code.
CBL_PUT_SHMEM_PTR
Introduction to Run-unit Handling Routines
Creates or updates a named value.
call "CBL_PUT_SHMEM_PTR" using by value node-value by reference node-name returning status-code
node-value |
usage pointer. |
node-name |
Group item defined as: |
name-length |
pic x comp-5 value n. |
name |
pic x(n) value "name". |
status-code |
See Key in the Preface |
node-value |
The value to assign to the created/updated named value. |
name-length |
The length of name. |
name |
The name of the named value. |
None
Named values provide a way of passing pointers between different run-units using a name agreed at run-time. Named values can be read simultaneously by all units in the coru because the run-time system protects and serializes any updates. The maximum number of named values depends on how much memory your machine has.
16-bit:
On the 16-bit COBOL system, this routine works only with .int and .gnt
files. It does not work with linked object code.
CBL_GET_SHMEM_PTR
Introduction to Run-unit Handling Routines
Yields the remainder of a run-unit's time-slice.
call "CBL_YIELD_RUN_UNIT"
None
This routine has no effect in UNIX environments.
The remainder of the run-unit's time-slice is yielded to unspecified run-units.
16-bit:
On the 16-bit COBOL system, this routine works only with .int and .gnt
files. It does not work with linked object code.
Introduction to Run-unit Handling Routines
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Application Configuration System | Library Manager |