Application Configuration System

Library Manager

Chapter 14: Concurrency Support

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.

14.1 Overview

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.

14.2 Operation

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.

14.2.1 Installing Concurrency Support

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.

14.2.2 Example program

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.

14.2.3 Run-unit Management

When dealing with run-units, you might find it useful to understand the following terminology and concepts:

Term	Description
Originator	The first run-unit that makes the call to create a run-unit.
Parent	A run-unit that makes the call to create a run-unit.
Child	The run-unit created from the call made by the parent.
Coru	The set of run-units containing the originator and all descendant run-units.

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:

All COBOL programs in a child run-unit are in their initial state.
COBOL and RTS switches, environment variables and open libraries are inherited by the child.
Open files and heaps are not inherited by the child.

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.

14.2.4 Run-unit Intercommunication

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

14.3 Run-unit and Memory Routines

The following COBOL system library routines are available.

Memory allocation:

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).

Run-unit Handling:

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

14.3.1 Introduction to Run-unit Handling Routines

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.

14.3.2 Descriptions of Routines

CBL_ALLOC_MEM

Dynamically allocates memory.

Syntax:

call "CBL_ALLOC_MEM" using     mem-pointer 
                     by value  mem-size 
                               flags 
                     returning status-code

Parameters:

`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

On Entry:

mem-size The number of bytes of memory to allocate.

flags

The type of memory required:

0	Relocatable and nonshared.
1	Relocatable and shared.
2	Fixed (DOS only) and nonshared.

On Exit:

mem-pointer A pointer to the memory allocated. The allocated memory is not initialized.

Comments:

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.

CBL_CULL_RUN_UNITS

Clears any dead run-units.

Syntax:

call "CBL_CULL_RUN_UNITS"

Parameters:

None

Comments:

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.

CBL_EXEC_RUN_UNIT

Creates an asynchronous run-unit.

Syntax:

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

Parameters:

`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

On Entry:

`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.

On Exit:

run-unit-id The unique handle identifying the new run-unit.

status-code

Status of operation:

0	Success
157	Out of memory
181	Invalid parameter
200	Internal logic error

Comments:

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:

All COBOL programs in the child are in their initial state.
To improve both speed and size, the stack-size and flags parameters should be either literal or level-01 items.
Data is not shared between run-units unless explicitly specified using CBL_GET_SHMEM_PTR, CBL_PUT_SHMEM_PTR or CBL_ALLOC_MEM.
COBOL and RTS switches, environment variables, and open libraries are inherited by the child.
Open files and heaps are not inherited by the child.
Screen I/O from one run-unit can interfere with that from another run-unit causing unexpected results. This is particularly a problem on UNIX. Avoid screen I/O operations from more than one concurrent run-unit.

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_FREE_MEM

Frees dynamically allocated memory.

Syntax:

call "CBL_FREE_MEM" using by value mem-pointer 
                    returning      status-code

Parameters:

`mem-pointer`	usage pointer.
`status-code`	See Key in the Preface

On Entry:

mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_MEM.

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_MEM routine.

CBL_GET_SHMEM_PTR

Reads a named value.

Syntax:

call "CBL_GET_SHMEM_PTR" using     node-value 
                                   node-name 
                         returning status-code

Parameters:

`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

On Entry:

`node-name`	The length of name.
`name`	The value assigned to node-name.

On Exit:

node-value The value of the named value.

Comments:

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

Creates or updates a named value.

Syntax:

call "CBL_PUT_SHMEM_PTR" using by value node-value 
                         by reference   node-name 
                         returning      status-code

Parameters:

`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

On Entry:

`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.

On Exit:

None

Comments:

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_YIELD_RUN_UNIT

Yields the remainder of a run-unit's time-slice.

Syntax:

call "CBL_YIELD_RUN_UNIT"

Parameters:

None

Comments:

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.

Memory allocation:

Run-unit Handling:

CBL_ALLOC_MEM

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

CBL_CULL_RUN_UNITS

Syntax:

Parameters:

Comments:

See also:

CBL_EXEC_RUN_UNIT

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_FREE_MEM

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_GET_SHMEM_PTR

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_PUT_SHMEM_PTR

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_YIELD_RUN_UNIT

Syntax:

Parameters:

Comments:

See also: