The Common Storage Control (CSC) functions provide a facility that allows the application program to obtain, modify, and release storage outside of the application thread area. This facility allows a Com-plete application program to interact with another application program by sharing "common" storage. The storage is not located within the thread, but is located outside the thread in an area that is managed by Com-plete.
Com-plete's CSC routines use a control block to communicate with the application program. Information about the request, such as function type (for example, GEN, GET), is placed in the control block before invoking the COMSTOR routine. Com-plete returns the status of the call and other information to the application program in the control block.
Several function types are available to the application program to maintain this storage. They include:
GEN - obtains and initializes storage;
FREE - frees the storage;
PUT - modifies part or all of the storage by moving data into it from the application program;
GET - "reads" the storage by moving part or all of it into the application program.
GEN is used to obtain working storage outside of the thread. Specifically, the storage is not rolled out with the thread when the application program is rolled out; however, the storage is available to other application programs while the program that obtained and initialized it is rolled out. The storage is obtained from a special buffer pool managed by Com-plete and cannot be modified directly.
The area parameter is used to initialize the storage obtained by the GEN call. If no area parameter is supplied, the area is not initialized.
Note that the storage obtained by a COMSTOR GEN function call is considered "non-accountable", that is, the storage is controlled by the application and can only be freed by an explicit call from an application program. Synchronization of the access to the storage is left up to the application programs involved.
FREE is used to free the storage previously obtained by GEN. After control is returned from the FREE function call, the storage is no longer available to any application programs. The storage ID (see the CSCID field explained in the table below) can be re-used to obtain and initialize a new piece of storage.
PUT is used to modify the storage that was
obtained with GEN. The entire area, or just a part of it, can be modified.
Thecontrolblock parameter specifies the offset and length of the data
in the GENed area that is to be modified. The area parameter is the
name of a field containing data to be used for the modification.
GET is used to "read" the storage previously obtained with GEN and/or modified by PUT. The entire GENed area, or just a part of it, can be moved into the application. The controlblock parameter specifies the offset and length of the data in the GENed area to be moved into the application program. The area parameter is the name of a field that is the target for the data to be moved.
- Format
The format for using the COMSTOR function is:
COMSTOR (retcode, controlblock , area)
retcode Required.
A fullword where Com-plete places the return code upon completion of the operation.control-block Required.
The label of a data area containing the common storage control block. Refer to the CSC control block table below. The desired function is indicated within this control block.area The label of a data area, the usage of which is dependent upon the specified function.Optional. - Return Codes
After each call, the return code must be examined. All return codes are posted in the first parameter, as follows:
0 The function completed normally. 4 The function did not complete. The control block address is invalid. 8 The function did not complete. Refer to the CSCFBK field in the control block for the feedback code. - Feedback Codes
If Com-plete finds the location of the CSC control block to be valid but discovers some other error, the application program receives return code 8 and the CSCFBK field contains one of the following feedback codes:
4 The storage already exists (GEN), or the storage does not exist (FREE, PUT, GET). 8 The amount of storage requested is not available (GEN). 12 Control storage is unavailable. Too many GEN requests are outstanding. Notify the system programmer. 16 INVALID function. 20 AREA PARM missing. 24 AREA length (CSCLEN) invalid. 28 DATA offset (CSCOFF) invalid. 32 The storage is held by ROLEVT and cannot be changed (FREE, PUT). - Abends
There are no abends associated with the Common Storage Control functions.
Com-plete Common Storage Control uses a control block to pass information back and forth between itself and the application program. The control block is the second parameter in each call to the COMSTOR function, and is formatted as shown in the following table:
| Name | Length | Offset | Description |
|---|---|---|---|
| CSCNAME | 4 | 0 | Character; must be CSCB |
| CSCFUNC | 4 | 4 | Character; function - must be GEN, GET, PUT, or FREE |
| CSCID | 8 | 8 | Character; storage identifier - used to uniquely identify (i.e., "name") the storage |
| CSCLEN | 4 | 16 | Signed binary; data length - the length of the data to be moved to or from the GENed area. |
| CSCOFF | 4 | 20 | Signed binary; offset to data - the offset in the GENed area to which, or from which, the data is to be moved. |
| CSCAREA | 4 | 24 | Storage address; address of the GENed area in Com-plete storage. The storage pointed to by this address should not be directly referenced; it is in protected storage. If an ECB is built as the first word of the GENed area, the data name of CSCAREA can be used as the ECB parameter of a Com-plete ROLEVT function. |
| CSCRC | 2 | 28 | Signed binary; return code. |
| CSCFBK | 2 | 30 | Signed binary; feedback code - indicates the status of the COMSTOR call. See feedback codes in previous section for valid values. |