The GET STORAGE statement is used either to acquire variable storage from a system storage pool or to obtain the address of a previously acquired storage area. Once acquired, the storage is available for use:
Storage availability is governed by GET STORAGE parameter specifications.
►►─── GET STORAGE FOR (storage-data-location) ────────────────────────────────► ►─┬─ TO (end-storage-data-location) ─┬───────────────────────────────────────► └─ LENGTH (storage-data-length) ───┘ ►─── POINTER (storage-data-location-pointer) ─┬──────────┬──┬────────┬───────► ├─ WAIT ◄ ─┤ └─ KEEP ─┘ └─ NOWAIT ─┘ ►─┬──────────┬─┬──────────┬─┬──────────────────────┬─────────────────────────► ├─ LONG ◄ ─┤ ├─ USER ◄ ─┤ └─ STGID (storage-id) ─┘ └─ SHORT ──┘ └─ SHARED ─┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ VALUE (initial-value) ─┘ ►─┬───────────────────────────┬─ ; ──────────────────────────────────────────►◄ └─ LOCATION IS ─┬─ ANY ◄ ─┬─┘ └─ BELOW ─┘
Specifies the variable associated with the storage area being acquired. Storage-data-location is a user-assigned symbolic name.
Indicates the end of the data area for which the system will acquire storage. If this option is specified, storage-data-location must be declared as a PL/I structure variable. End-storage-data-location is the symbolic name of either a user-defined dummy byte field or a variable field not associated with the storage area. End-storage-data-location is specified after the last elementary data-item entry in the structure.
Explicitly defines the length of the data area associated with the requested storage area. This option is specified in place of TO (end-storage-data-location). If the LENGTH option is used, then no restrictions are placed on the data type; that is, storage-data-location does not have to be defined as a PL/I structure variable. Storage-data-length is a user-assigned fixed binary field containing the storage length, or the length itself expressed as a numeric constant.
Specifies the user-assigned pointer variable associated with storage-data-location. Storage-data-location-pointer is defined in variable storage with the pointer attribute. Upon successful completion of the GET STORAGE request, the system returns the address of the storage area to storage-data-location-pointer.
Specifies whether the issuing task is to wait for sufficient storage in the event that storage is not immediately available to meet the requirements of the GET STORAGE request:
Specifies that the issuing task will wait until sufficient storage is available in a storage pool. WAIT is the default.
Specifies that the issuing task will not wait for storage to become available if an insufficient storage condition exists. If NOWAIT is specified, the program should check the ERROR_STATUS field in the IDMS DC communications block to determine if the GET STORAGE request has been completed. If the ERROR_STATUS value is 3202, the program should perform alternative processing before reissuing the GET STORAGE request.
Optionally specifies whether the storage area will be used by subsequent tasks executing on the same logical terminal. When KEEP is specified, the storage area can be accessed by subsequent tasks; otherwise the storage area cannot be accessed by subsequent tasks.
Note: For a more information about KEEP parameter, see the CA IDMS Navigational DML Programming Guide.
Specifies whether the system should allocate the storage from the bottom or the top of a storage pool:
Allocates storage from the bottom of the storage pool. You should specify LONG when allocating kept storage to be held across pseudo-converses. LONG is the default.
Allocates storage from the top of the storage pool. You should specify SHORT when allocating small pieces of storage for a short duration.
An incorrect LONG/SHORT specification will not affect normal program execution; however, it may affect the overall performance of the DC/UCF system.
Specifies whether access to the storage area is to be restricted to the issuing task or is to be available to all tasks in the system:
Specifies that only the issuing task can access the storage area or, if KEEP is specified, only subsequent tasks executing on the same terminal. USER is the default.
Note: During system execution, a program defined at system generation with the NOPROTECT option can access any storage area within the system, including an area associated exclusively with another task. Thus, the USER attribute may not protect the storage area being acquired. However, storage areas can be protected on a system-wide or program-by-program basis during system generation and by the modes specified when storage is allocated.
Specifies that any task in the system can access and modify the acquired storage. Each task must establish addressability to the storage area by explicitly issuing a GET STORAGE request.
Specifies the 4-character ID associated with the storage area. The STGID parameter must be specified with GET STORAGE requests for either previously allocated storage areas or areas to be reallocated. Storage-id is either the symbolic name of a user-defined field that contains the storage ID, or the ID itself enclosed in single quotation marks.
The specified storage ID must be unique; although multiple variable-storage areas (that is, one shared and the others user) can have the same ID, only one such area can be owned by a given task at a time. To access the IDMS DC common work area, specify STGID 'CWA'.
Note: If the STGID parameter specifies the address of an existing storage area, the USER/SHARED parameter must specify the same option as that specified in the GET STORAGE statement that originally allocated the storage area.
Specifies (for new storage only) the value to which the storage area will be initialized before it is returned to the issuing program. Initial-value specifies either the symbolic name of a user-defined field that contains the initial value or the value itself enclosed in single quotation marks. All bytes of the acquired storage area are initialized to the same value.
Specifies that storage must be allocated from below the 16-megabyte line (BELOW) or is eligible for allocation above the 16-megabyte line (ANY). ANY is the default.
The following statement allocates the shared kept storage area, 09PA, and initializes it to all zeros:
GET STORAGE FOR (EMPLMENU_KEPT_STORAGE)
TO (EMPLMENU_KEPT_STORAGE_END)
NOWAIT
KEEP
SHORT
SHARED
STGID ('09PA')
VALUE (LOW_VALUE);
Upon completion of the GET STORAGE function, the ERROR_STATUS field of the IDMS DC communications block indicates the outcome of the operation:
The request has been serviced successfully.
The requested storage cannot be allocated immediately; to wait would cause a deadlock.
The requested storage cannot be allocated because insufficient space exists in the storage pool.
The request specified a storage ID that did not previously exist; the required space has been allocated.
The request specifies an invalid parameter list.
The requested length is zero or negative. The request cannot be serviced because the variable storage The request cannot be serviced because the specified 01-level
|
Copyright © 2014 CA.
All rights reserved.
|
|