Application responsibilities for using CSM

Requirement: An application must be authorized in order to use the CSM API. This is described in z/OS Communications Server: SNA Programming.

As system-authorized applications, all programs using CSM should be written to handle CSM storage in a responsible manner. Therefore, the application design should adhere to the following guidelines for requesting CSM services. Applications using CSM for VTAM's high performance data transfer (HPDT) service should see the guidelines described in the z/OS Communications Server: SNA Programmer's LU 6.2 Guide.

Guidelines:

Data in CSM storage should be modified only by the original requester of the buffers. The original requester is the application that obtained the storage using the IVTCSM REQUEST=GET_BUFFER macroinstruction. All other applications are considered borrowers of the buffers and must treat the data as read-only. For information about possible exceptions to this rule, see Responsibilities of buffer ownership for more details.
All programs directly referencing CSM storage must do so in the proper storage key. All CSM storage is allocated in key 6.
The IVTCSM REQUEST=COPY_DATA macroinstruction allows data to be copied into or out of CSM storage. The authorized invoker can be in any key. Using this service might reduce the impact to the application due to storage key mismatches when CSM storage must be accessed.
An application must not reference or use CSM storage after passing ownership of that storage to another user.
An application that has accepted ownership of CSM storage is obligated to return the storage to CSM unless that application is passing the storage to another user. See Ownership of buffers for more information. Storage is returned to CSM on the IVTCSM REQUEST=FREE_BUFFER macroinstruction.
Applications should use the IVTCSM REQUEST=RESOURCE_STATS macroinstruction to monitor the status of CSM storage. The application must be capable of reacting to storage constraint conditions that might jeopardize the application's or system's operation. See Obtaining CSM resource statistics for more information. The RESOURCE_STATS request is described on page IVTCSM REQUEST=RESOURCE_STATS.
Generally, applications should request buffers from data space instead of ECSA to ensure that more virtual storage is available to all users of CSM. ECSA should be used only if there are special application requirements.
The application's use of CSM should be documented so that the installation can adjust ECSA and fixed storage limits in the CSM parmlib member as necessary. This information should be available in application installation documentation so that necessary changes to the limits can be made prior to application installation.