IMS compliance control blocks

To make compliance audit data in IMS accessible for security audit compliance checks, IMS compliance control blocks are provided in IMS Operations Manager and IMS Connect address spaces.

Some IMS address spaces that use IMS Base Primitive Environment (BPE) provide compliance-related data in in-memory control blocks that are shipped as source within the address spaces. This compliance-related data is consolidated from other internal control blocks whose mappings are not shipped as source. To allow products that perform security audit compliance checks to obtain compliance audit data, IMS compliance control blocks are provided in the following IMS address spaces:

IMS Operations Manager (OM)
IMS Connect

IMS compliance control blocks are classified as a DMTI (Diagnosis, Modification, and Tuning Interface).

Structure of the BPE address space compliance data

BPE creates a primary-level address space z/OS® name/token pair at the initialization of address spaces that provide compliance data. The name of the name/token pair is the same for all address spaces that provide compliance data. The name is a set value: BPECOMPLIANCEDAT.

The structure of BPE address space compliance data. More details are explained in the paragraph below this figure.

The first four bytes of the token in the pair are the 31-bit address of a BPE compliance data header, which is mapped by the source-shipped BPECPLHD macro as DSECT BPECPLHD. The BPECPLHD macro contains general system information about the address space, such as the address space type, name, and version.

The BPECPLHD_COMPDATA_PTR field points to a component-specific compliance data block that is unique to the component address space type, for example, OM or IMS Connect.

Some components might have extra compliance subblocks that are connected to the main compliance data block.

Locating IMS compliance data blocks

You can find the address of the BPECPLHD and the main component compliance data block by using the following code sample.

Restriction: The following code sample contains code fragments and is shown only for illustration purposes. This code can be part of a larger module for accessing the compliance data.

         L     R15,X'10'           Get A(CVT)
         L     R15,X'220'(,R15)    Follow chain per doc in
         L     R15,X'14'(,R15)      MVS Auth Assembler Ref
         L     R15,X'08'(,R15)     NT retrieve rtn address

         CALL  (15),(CPNTLEV,CPNTNAME,DS_TOKEN,DS_RETCODE),            *
               MF=(E,DS_PARMS)     Retrieve token

         ICM   R15,15,DS_RETCODE   Get IEANTRT return code
         JNZ   ERROR               If not 0, not found or error

         L     R9,DS_TOKEN         Token word 1=A(BPECPLHD)
         USING BPECPLHD,R9         Address BPECPLHD
         L     R8,BPECPLHD_COMPDATA_PTR  Pt to component data

       :
       :

*
* Module constants and literals
*
         DS    0F                  Ensure FW aligned
CPNTNAME DS    0CL16               NT name =
*                                   'BPECOMPLIANCEDAT'
         DC    A(BPECPLHD_NT_NAME1)  - 'BPEC'
         DC    A(BPECPLHD_NT_NAME2)  - 'OMPL'
         DC    A(BPECPLHD_NT_NAME3)  - 'IANC'
         DC    A(BPECPLHD_NT_NAME4)  - 'EDAT'

CPNTLEV  DC    A(IEANT_PRIMARY_LEVEL)  Name token level

         LTORG ,                   Literals

          :
          :

*
* DSECT mapping module working storage (assumed based via
* a USING in the code above)
*
DYNSTOR       DSECT ,
DS_TOKEN      DS    CL16          Retrieved name token
DS_RETCODE    DS    F             Return code from services

DS_PARMS      DS    0F
              DS    4F            Parmlist for IEANTRT

          :
          :

         BPECPLHD ,               Inc BPECPLHD DSECT
         IEANTASM ,               Inc z/OS name/token sym

Once you find the BPECPLHD block in an address space, perform the following tests to validate the blocks are ready for use:

Test the BPECPLHD_CURSTCK field or the BPECPLHD_UPDCOUNT field to check whether the value is zero.
- If the value of the field is zero, the compliance data is not initialized yet. Don't use any data that is contained within the compliance blocks.
Test flag bits BPECPLHD_F1_TERM and BPECPLHD_F1_ABTERM.
- If any flag is set, the address space is in termination processing. Don't continue to access the BPECPLHD block or any related blocks because the storage that contains the blocks could be freed at any time.
Check the 4-character IMS component address space type in the BPECPLHD_COMPTYPE field to determine the kind of IMS address space data that you are accessing. This field is left-aligned and padded with blanks if needed.
- The type is OM for an IMS Operations Manager address space.
- The type is HWS for an IMS Connect address space.

Operations Manager compliance block

In an Operations Manager (OM) address space, the BPECPLHD_COMPDATA_PTR field points to the OM compliance data block. This block is defined in the CSLOCPLB macro as DSECT CLSOCPLB. The CSLOCPLB macro has one subblock that is mapped by DSECT CSLOCPLB_PLEX. The CSLOCPLB_PLEX contains compliance data that is specified in the IMSPLEX statement in the CSLOINxx PROCLIB member. The main CSLOCPLB block field CSLOCPLB_PLEXPTR points to the CSLOCPLB_PLEX block.

IMS Connect compliance block

In an IMS Connect address space, the BPECPLHD_COMPDATA_PTR field points to the IMS Connect compliance data block. This block is defined in the HWSCPLB macro as DSECT HWSCPLB.

The HWSCPLB has two chains of subblocks:

HWSCPLB_PLEX: Contains compliance data that is associated with an IMSplex, which is defined to the IMS Connect address space. The main HWSCPLB block field HWSCPLB_PLEXPTR points to the first HWSCPLB_PLEX block on the chain, and the value might be zero. The chain is a singly linked list that uses the HWSCPLB_PLEX_NEXTPTR field. A zero in this pointer indicates the end of chain.
HWSCPLB_DSTR: Contains compliance data that is associated with a data store, which is defined to the IMS Connect address space. The main HWSCPLB block field HWSCPLB_DSTRPTR points to the first HWSCPLB_DSTR block on the chain, and the value might be zero. The chain is a singly linked list that uses the HWSCPLB_DSTR_NEXTPTR field. A zero in this pointer indicates the end of chain.

IMS Connect allows both IMSplexes and data stores to be deleted via type 2 DELETE IMSCON commands. When an IMSplex or a data store is deleted, its corresponding HWSCPLB_PLEX or HWSCPLB_DSTR block is not removed from the HWSCPLB chain. Instead, IMS Connect marks the block as being logically deleted by setting a flag bit, HWSCPLB_PLEX_F1_DEL for IMSplex blocks, or HWSCPLB_DSTR_F1_DEL for data store blocks. If you write code that scans the IMSplex and data store compliance block chains, you should test the delete flag in each block, and skip processing it if the bit is set. Also note that IMS Connect will find and reuse a logically-deleted compliance block if a new IMSplex or data store is later created by a CREATE IMSCON command.

Field level details

For details on individual compliance data that is collected in each block, see the macros BPECPLHD, CSLOCPLB, and HWSCPLB in the IMS SDFSMAC macro data set.

Ensuring consistency and recovering compliance data

To ensure data consistency and recover data, save your data, set up recovery protection for asynchronous programs, and regularly retrieve the compliance token.

The IMS component code may update the compliance data at any time, including while your program is accessing the compliance blocks (for example, some settings can be changed dynamically by command). To ensure consistency of data, save the value in the BPECPLHD_CURSTCK field or the BPECPLHD_UPDCOUNT field before you access the compliance data. When you have the data that is needed, verify whether the value in BPECPLHD_CURSTCK or BPECPLHD_UPDCOUNT is the same value that you saved. If the two values are different, gather the data again to ensure the consistency because the data is updated.

If your program is accessing either the BPECPLHD block or the related component compliance blocks while it is running asynchronously to the BPE address space, it must have a recovery set.

Remember: Running asynchronously in this case means running under:

A service request block (SRB)
A task control block (TCB) in the address space that is not the BPE JOBSTEP TCB or a descendant TCB
A TCB in another address space in cross-memory or AR mode

Recovery protection is required because the BPE address space might terminate while your program is running.

Attention: This could delete the storage in the address space.

BPE deletes the compliance name/token pair at the start of both a normal and an abnormal termination. However, if you previously located the name/token pair, you might retrieve the data before BPE deletes it. For that reason, always retrieve the token every time your code runs and never reuse a saved BPECPLHD or compliance data block address for an extended period.