Using Storage Pools
To facilitate online programming and intertask communication, CA IDMS provides storage management functions that allow you to acquire space explicitly in storage pools.
idmscu19
To facilitate online programming and intertask communication, CA IDMS provides storage management functions that allow you to acquire space explicitly in storage pools.
These functions control allocation of variable storage in a CA IDMS storage pool or work area. Shared by system and user programs, the storage pool also contains space for buffers and initial storage areas (ISAs) used by Assembler and PL/I programs.
All variable-storage entries (except COBOL LINKAGE SECTION and PL/I BASED storage entries) defined by your program are acquired automatically from the CA IDMS storage pool when the program starts and released automatically when the program ends.
Using CA IDMS storage management functions, you can:
- Acquire variable storage from a storage pool
- Establish addressability to previously acquired variable storage
- Release all or part of previously acquired variable storage
Types of Acquired Storage
You must specify whether the acquired storage is available to other users:
- Userstorage is available only to the issuing task; no other tasks can access it. CA IDMS maintains user storage through the issuing task's task control element (TCE).
- Sharedstorage is available to all tasks running under the CA IDMS system. CA IDMS links shared storage to the common system area (CSA) as well as to the TCE, as illustrated in the figure below. CA IDMS uses the CSA to locate the address of a shared area to satisfy requests from other tasks for shared storage.Shared storage is available to all tasks within the CA IDMS system; however, each task must explicitly establish addressability to access such storage.
TCE and CSA Ownership
Shared storage is linked to both the TCE and CSA; user storage is linked only to the TCE, as the figure below shows.
┌─────────┐ ┌───────────┐ │ │ STORAGEID='WRK1' │ │ │ TCE │ Shared │ CSA │ │ (Task1) │ │ │ │ │ └─┬─────────┘ │ ├────────────────┐ │ Storage pool └─────────┘ │ │ ┌───────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ ┌────────┐ │ └────►─────────┐ │ │ │ STORAGEID='WRK2'└────────► WRK1 │ │ │ TCE │ User ├─────────┴──────────┐ │ │ (Task2)├──────────────────────────► WRK2 │ │ │ │ ├────────────────────┘ │ │ │ │ │ └─────────┘ └───────────────────────────────────────────┘
Kept Storage
If you require that storage remain allocated after a task ends, it should be assigned the
KEEP
attribute when it is initially allocated. Kept storage is associated with the logical terminal on which the task is executing and with the task itself; such storage can be released only through a program request.Releasing Storage
When storage is explicitly released or a task terminates, CA IDMS releases linkage to the TCE.
For a quick reference of storage release procedures and conditions, see Storage Pool Summary.
'User storage only'. You can explicitly release all or a part of user storage. For a partial release, TCE linkage and the KEEP attribute remain unaffected.
This article describes the following information:
2
2
User Storage
User storage is associated exclusively with the issuing task through the TCE; when the task terminates, user storage is released. By dynamically acquiring only the amount of storage needed, you can make more effective use of storage resources.
Steps to Acquire User Storage
To dynamically acquire and use variable storage from the storage pool within a single task, perform the following steps:
- Acquire variable storage from the storage pool by issuing a GET STORAGE statement that specifies the USER parameter.
- Check for an ERROR-STATUS of 3210 (DC-NEW-STORAGE).
- Perform the IDMS-STATUS routine if 3210 is not returned.
- Perform processing, using the acquired storage as needed.
- Release the acquired storage by issuing a FREE STORAGE statement that specifies the appropriate storage ID.
Example of Acquiring User Storage
The program excerpt below shows the acquisition and release of user storage.
The program acquires the minimum amount of storage needed to complete the processing specified by the user.
DATA DIVISION. LINKAGE SECTION. 01 COPY IDMS RECORD EMPLOYEE. 05 EMPLOYEE-END PIC X. 01 COPY IDMS RECORD DEPARTMENT. 05 DEPARTMENT-END PIC X. 01 ERROR-DATA. 05 ERROR-DEPT-ID PIC 9(4). 05 ERROR-MESSAGE-CODE PIC X(4). 05 ERROR-DATA-END PIC X. PROCEDURE DIVISION. MAIN-LINE. *** THIS PROGRAM ACQUIRES STORAGE FOR EITHER THE *** *** DEPARTMENT RECORD OR THE EMPLOYEE RECORD *** *** DEPENDING ON THE CONTROL KEY PRESSED BY THE *** *** TERMINAL OPERATOR. *** BIND MAP SOLICIT. BIND MAP SOLICIT RECORD SOLICIT-REC. MAP IN USING SOLICIT. INQUIRE MAP SOLICIT MOVE AID TO DC-AID-IND-V. IF CLEAR-HIT DC RETURN ELSE IF PA01-HIT GO TO A100-GET-EMPLOYEE ELSE IF PA02-HIT GO TO A100-GET-DEPARTMENT ELSE GO TO U100-ERROR-PROC. * A100-GET EMPLOYEE. IF SOLICIT-EMP-ID NOT NUMERIC GO TO U200-ERROR-EMP-ID. *** ACQUIRE USER STORAGE FOR THE EMPLOYEE RECORD *** GET STORAGE FOR EMPLOYEE TO EMPLOYEE-END NOWAIT SHORT USER STGID 'EMPL' VALUE IS LOW-VALUE ON DC-NEW-STORAGE NEXT SENTENCE. MOVE SOLICIT-EMP-ID TO EMP-ID-0415. OBTAIN CALC EMPLOYEE ON DB-REC-NOT-FOUND GO TO U200-ERROR-NO-EMP. .
User Kept Storage
User kept storage is available to all tasks running on a logical terminal until a task associated with that terminal releases the storage. User kept storage is ideal for passing small amounts of information between tasks. CA IDMS maintains TCE linkage for user kept storage across tasks by using the logical terminal element (LTE). When a new task is initiated from the same terminal, CA IDMS transfers this linkage from the LTE to the TCE of the new task.
Steps to Acquire User Kept Storage
To dynamically acquire and use variable storage from the storage pool and make the storage available to multiple tasks running on the same logical terminal:
- Acquire variable storage from the storage pool by issuing a GET STORAGE statement that specifies both the USER and the KEEP parameters.You can indicate that storage is eligible for allocation above the 16Mb line by specifying LOCATION IS ANY on the GET STORAGE statement.
- Check for an ERROR-STATUS of 3210 (DC-NEW-STORAGE).
- Perform the IDMS-STATUS routine if 3210 is not returned.
- Perform processing, using the acquired storage as needed.
- Issue a DC RETURN statement, optionally specifying the next task to be invoked.
Accessing User Kept Storage
In subsequent tasks invoked on the same logical terminal:
- Establish addressability to the previously acquired storage by issuing a GET STORAGE request that names the storage ID specified for the storage area when it was first allocated.
- Perform processing, using the acquired data.
You should release the acquired storage as soon possible by issuing a FREE STORAGE statement that specifies the appropriate storage ID.
Example of Acquiring User Kept Storage
The program excerpt below shows the initial assignment of user kept storage.
The program performs preliminary error checking before transferring control to a database retrieval program.
DATA DIVISION. 01 TRANSPROG PIC X(8) VALUE 'DEPTGET'. 01 SOLICIT-REC. 05 SOLICIT-DEPT-ID PIC X(4). LINKAGE SECTION. 01 PASS-DEPT-INFO. 05 PASS-DEPT-ID PIC 9(4). 05 PASS-DEPT-INFO-END PIC X. PROCEDURE DIVISION. BIND MAP SOLICIT. BIND MAP SOLICIT RECORD SOLICIT-REC. * MAP IN USING SOLICIT. INQUIRE MAP SOLICIT MOVE AID TO DC-AID-IND-V. IF CLEAR-HIT DC RETURN. * IF SOLICIT-DEPT-ID NOT NUMERIC GO TO ERROR-DEPT-ID. *** ACQUIRE USER KEPT STORAGE *** GET STORAGE FOR PASS-DEPT-INFO TO PASS-DEPT-INFO-END NOWAIT KEEP LONG USER STGID 'DEPT' VALUE IS LOW-VALUE ON DC-NEW-STORAGE NEXT SENTENCE. *** MOVE MAP DATA TO FIELDS IN ACQUIRED STORAGE *** MOVE SOLICIT-DEPT-ID TO PASS-DEPT-ID. *** TRANSFER CONTROL TO DATABASE ACCESS PROGRAM *** TRANSFER CONTROL TO TRANSPROG NORETURN.
Reestablishing Addressability to User Kept Storage
The program excerpt below establishes addressability to the previously acquired storage and releases it. The program uses data from the previously acquired storage to perform database access.
DATA DIVISION. 01 NTCODES. 05 NEXT-TASK PIC X(8) VALUE 'DEPTMOD'. 01 MESSAGES. 05 DEPT-DISPLAY-MESS PIC X(20) VALUE 'DEPARTMENT DISPLAYED' 05 DEPT-DISPLAY-MESS-END. PIC X. 01 SOLICIT-REC. 05 SOLICIT-DEPT-ID PIC X(4). LINKAGE SECTION. 01 PASS-DEPT-INFO. 05 PASS-DEPT-ID PIC 9(4). 05 PASS-DEPT-INFO-END PIC X. PROCEDURE DIVISION. *** ESTABLISH ADDRESSABILITY TO PREVIOUSLY ACQUIRED STORAGE *** GET STORAGE FOR PASS-DEPT-INFO TO PASS-DEPT-INFO-END NOWAIT KEEP LONG USER STGID 'DEPT'. BIND MAP SOLICIT. BIND MAP SOLICIT RECORD SOLICIT-REC. *** MOVE DATA TO DATABASE CALC-KEY AND MAP DATA FIELD *** MOVE PASS-DEPT-ID TO DEPT-ID-0410. MOVE PASS-DEPT-ID TO SOLICIT-DEPT-ID. *** RELEASE STORAGE *** FREE STORAGE STGID 'DEPT'. . *** DATABASE ACCESS *** . MAP OUT USING SOLICIT MESSAGE IS DEPT-DISPLAY-MESS TO DEPT-DISPLAY-MESS-END. DC RETURN NEXT TASK CODE NEXT-TASK.
Shared storage is available to all tasks running concurrently under the CA IDMS system.
Shared storage is usually accessed by a concurrent nonterminal task. For example, such a nonterminal task might support the main task by performing print functions.
For more information on nonterminal tasks, see Initiating Nonterminal Tasks.
When Shared Storage Is Released
CA IDMS maintains an in-use counter for each area of shared storage. Each time a task establishes addressability to an area of shared storage, CA IDMS adds 1 to the in-use counter. When a task terminates or releases the storage, CA IDMS subtracts 1 from the in-use counter. CA IDMS releases shared storage when the in-use counter is set to zero.
Steps to Acquire Shared Storage
To dynamically acquire and use variable storage from the storage pool and make the storage available to other tasks running under the same CA IDMS system, perform the following steps:
- Acquire variable storage from the storage pool by issuing a GET STORAGE statement that specifies the SHARED parameter.
- Check for an ERROR-STATUS of 3210 (DC-NEW-STORAGE).
- Perform the IDMS-STATUS routine if 3210 is not returned.
- Perform processing, using the acquired storage as needed.
- Optionally, release the shared storage by issuing a FREE STORAGE statement that specifies the appropriate storage ID.
Steps to Access Shared Storage
To access the data from another task executing concurrently under the same CA IDMS system, perform the following steps:
- Establish addressability to the previously acquired storage by issuing a GET STORAGE request that names the storage ID specified for the storage area when it was first allocated.
- Perform processing using the acquired data.
- Optionally, release the shared storage by issuing a FREE STORAGE statement that specifies the appropriate storage ID.
Shared kept storage is available to all tasks running under the CA IDMS system. Once a storage area with the SHARED KEEP attribute is established, any task running under the CA IDMS system can access that area.
When Shared Kept Storage Is Released
CA IDMS maintains an in-use counter and a keep flag for each area of shared kept storage. Shared kept storage is released only when
both
of the following conditions are true:- The in-use counter is set to zero, indicating that there are no current users of the area.
- The keep flag is turned off (the FREE STORAGE statement turns the keep flag off)
If either condition is false, the storage area remains allocated. With this feature, shared kept storage areas remain allocated even when they are not being used, provided the keep flag remains on.
Each time a task establishes addressability to an area of shared kept storage, CA IDMS adds 1 to the in-use counter. When the task terminates, CA IDMS subtracts 1 from the in-use counter. When a program issues a FREE STORAGE request, CA IDMS subtracts 1 from the in-use counter
and
turns off the keep flag. Once a FREE STORAGE request is issued, if the in-use counter is zero, CA IDMS releases the storage. Once turned off, the keep flag cannot be reset.Difference from User Kept Storage
Unlike user kept storage, shared kept storage is not linked to the LTE across tasks executing on the same terminal.
Startup Shared Kept Storage
One shared storage area having the keep attribute is allocated at system startup for use by all tasks; this storage area is never freed. This area is called the common work area (CWA) and can contain application-defined information, if so requested during system generation.
For more information about the CWA, see
CA IDMS Administrating section
.Example of Shared Kept Storage
The program excerpt below shows programmatic access to data previously placed in the CWA.
This program accesses the CWA in order to obtain the current date in Gregorian format:
DATA DIVISION. 01 NTCODES. 05 NEXT-TASK PIC X(8) VALUE 'DEPTGET'. 01 CWA PIC X(4) VALUE 'CWA'. 01 SOLICIT-REC. 05 SOLICIT-DEPT-ID PIC X(4). 05 SOLICIT-GREG-DATE PIC X(8). LINKAGE SECTION. 01 CWA-DATA. 05 CWA-DATE PIC X(8). 05 CWA-DATA-END PIC X. PROCEDURE DIVISION. BIND MAP SOLICIT. BIND MAP SOLICIT RECORD SOLICIT-REC. *** GET THE DATE IN GREGORIAN FORMAT FROM THE CWA *** GET STORAGE FOR CWA-DATA TO CWA-DATA-END NOWAIT KEEP SHORT SHARED STGID CWA. MOVE ZEROS TO SOLICIT-DEPT-ID. MOVE CWA-DATE TO SOLICIT-GREG-DATE. MAP OUT USING SOLICIT. DC RETURN NEXT TASK CODE NEXT-TASK.
Storage Pool Summary
Acquired storage is associated with the TCE, the CSA, or both. Additionally, user storage with the keep attribute is linked to the LTE.
The table below shows the procedures and conditions under which CA IDMS maintains linkage when storage is released. This table assumes that the FREE STORAGE request releases the entire storage area.
Storage Attribute
| After FREE STORAGE Request
| After Task Termination
|
USER | Storage is released. | Storage is released. |
USER KEEP | Storage is released. | Storage remains allocated; TCE linkage is transferred to the LTE. |
SHARED | Storage is released only if the in-use counter is set to zero. | Storage is released only if the in-use counter is set to zero. |
SHARED KEEP | Storage is released only if the in-use counter is set to zero. | Storage remains allocated. |
How Storage Is Allocated and Released
The following diagrams illustrate how CA IDMS allocates and releases storage.
- Task 1, running on terminal B, establishes addressability to two variable areas of kept storage. WRK1 is designated shared keep; WRK3 is designated user keep. Because task 1 is the only task using WRK1, the in-use counter associated with WRK1 is set to 1.
- Task 1 terminates without issuing a FREE STORAGE request for either WRK1 or WRK3. CA IDMS automatically decrements the in-use counter and transfers linkage for WRK3 to the LTE for terminal B. Because WRK1 is shared, CA IDMS does not maintain linkage to the LTE. Although WRK1 has no users, it remains allocated because an explicit FREE STORAGE was not issued.
- Task 2 is initiated on terminal B and issues a GET STORAGE request for WRK1. Task 3 is initiated on terminal C and issues a GET STORAGE request for WRK1. The in-use counter for WRK1 indicates two users.
- Task 3 issues a FREE STORAGE request for WRK1; CA IDMS turns the keep flag off and decrements the in-use counter by 1.
- Task 2 terminates without issuing a FREE STORAGE request for WRK1; CA IDMS decrements the in-use counter by 1. Because the keep flag is off and the in-use counter is set to zero, CA IDMS releases the storage associated with WRK1.
