xUnit support for CICS applications (ZUnit)

You need the assistance of a CICS® , TCP/IP and possibly a security administrator to complete this customization task, which requires specific resources or special customization tasks.
  • Update CICS region JCL
  • Define resources to CICS
  • Reserve a TCP/IP port
  • Define security profiles and permits
Frameworks that assist developers in writing code to perform repeatable, self-checking unit tests are collectively known as xUnit. IBM® Developer for z/OS® provides such a framework for unit testing of Enterprise COBOL and PL/I code, called ZUnit. This customization task extends ZUnit to support testing CICS applications through recording of the parameters used in EXEC CICS calls.
Note: Support for testing CICS applications relies on services offered by IBM z/OS Dynamic Test Runner, FMID HAL6xxx. Ensure that this FMID is installed and configured. You might find it convenient to perform the customization tasks described here in conjunction with those described in Support for CICS applications of the Dynamic Test Runner Host Configuration Guide as there are common resources updated by both tasks.
To record a CICS application, ZUnit requires the following CICS updates:
  • CICS system initialization (SIT) parameter updates
    • Specify TCPIP=YES.
    • Specify USSHOME=/usr/lpp/cicsts/cicsts61, where /usr/lpp/cicsts/cicsts61 is the path used during the SMP/E installation of CICS Transaction Server.
    Note: Security considerations documents the impact of specifying these optional SIT parameters:
    • SEC=YES
    • CMDSEC=ALWAYS
    • RESSEC=ALWAYS
  • CICS JCL updates:
    • Specify REGION=0M on the EXEC statement to provide sufficient room to buffer the recording.
    • Define the FEL.SFELLOAD load library in the region’s DFHRPL DD statement, where FEL is the high level qualifier used during the SMP/E install of z/OS Explorer Extensions.
      • Alternatively, you can define a LIBRARY resource definition in the CSD for this load library. A sample definition can be found in the FEL.SFELSAMP(AZUCSD) sample CSD update job.
  • CICS CSD updates:
    • Define ZUnit to your CICS region, as documented in the AZUCSD sample CSD update job. AZUCSD is located in FEL.#CUST.JCL, unless you specified a different location when you customized and submitted job FEL.SFELSAMP(FELSETUP). For more information. see Customization setup.

The ZUnit CICS recorder uses a CICS PIPELINE to communicate with the ZUnit client. This CICS service requires that a TCP/IP port be defined in the CSD. The developers who use this service need to know the host system name and the port on which the service is listening.

The ZUnit CICS recorder uses a temporary storage queue in auxiliary storage to store log data. The log data is written to a queue named _AZU_LOGRS_. You can browse the log data with the CICS command CEBR. When the log data is too big to reserve TS queues in auxiliary storage for other programs, purge it manually in the CEBR command screen. Abend AIER (resp-18 NOSPACE) occurs when an auxiliary TS queue runs out of space.

You can run the AZUM transaction from a CICS terminal to manage logging. When the log level is set to a larger value, more data is output to the log files. The syntax of the AZUM transaction is:
AZUM { GETLOGLEVEL | SETLOGLEVEL0 | SETLOGLEVEL1 | SETLOGLEVEL2 }
GETLOGLEVEL
Show the current log level
SETLOGLEVEL0
Set the current log level to 0 (error only).
SETLOGLEVEL1
Set the current log level to 1 (error and warning)
SETLOGLEVEL2
Set the current log level to 2 (error, warning and information)

Security considerations

Multiple user IDs are involved when using ZUnit to test CICS applications:
  1. The user ID used by the end-user when connecting to the host using the IBM Developer for z/OS client, referred to as the client user ID in this section.
  2. The user ID used by the CICS region when doing actions requested by ZUnit, referred to as the CICS user ID in this section. The CICS user ID can differ from the client user ID, for example it can be the CICS default user.
  3. The user ID used by an administrator or end-user to interact directly with CICS, referred to as CICS admin ID in this section. The CICS admin ID can differ from both the client user ID and the CICS user ID.
  4. The user ID that the CICS region runs under, referred to as the CICS region user ID in this section.
Data set

As part of its processing, ZUnit creates a recording (also known as "playback") data set that will be populated by Dynamic Test Runner. The high level qualifier(s) of this data set can be configured in the ZUnit client preferences (default is the client user ID followed by ZUNIT.PB). The low level qualifier is the name of the program under test. Two user IDs require authorization to the security profile in the DATASET class that protects these recording data sets:

  • The client user ID requires ALTER access so that it can create them
  • The CICS region user ID requires UPDATE access so that it can write to them
For example, use the following z/OS Security Server (RACF) commands to define a data set profile for client user ID IBMUSER using the default high level qualifier, and to authorize users to use it:
ADDSD 'IBMUSER.ZUNIT.PB.*' UACC(NONE) DATA('ZUNIT PLAYBACK')
PERMIT 'IBMUSER.ZUNIT.PB.* ' CLASS(DATASET) ACCESS(ALTER) ID(IBMUSER)
PERMIT 'IBMUSER.ZUNIT.PB.* ' CLASS(DATASET) ACCESS(UPDATE) ID(#CICS_region_user_ID)
SETROPTS GENERIC(DATASET) REFRESH
SEC=YES

When CICS security is enabled with the SEC=YES system initialization parameter, users of the ZUnit management transaction (CICS admin ID) require READ access to the profile protecting the AZUMCICS transaction. Default resource and grouping class names for transactions are TCICSTRN and GCICSTRN, respectively, but these names can be overridden by the XTRAN CICS system initialization parameter.

For example, use the following z/OS Security Server (RACF) commands to define a profile for transaction AZUM in the TCICSTRN class, and to authorize users to run it:
RDEFINE TCICSTRN AZUM UACC(NONE)DATA('ZUNIT MANAGEMENT')
PERMIT AZUM CLASS(TCICSTRN) ACCESS(READ) ID(#CICS_admin_ID_group)
SETROPTS GENERIC(TCICSTRN) REFRESH
No further security configuration is required unless CICS security is enabled with the SEC=YES system initialization parameter, and either CMDSEC=ALWAYS or RESSEC=ALWAYS is specified as a CICS system initialization parameter.
CMDSEC=ALWAYS

If SEC=YES and CMDSEC=ALWAYS are specified as CICS system initialization parameters, then client user IDs require ALTER access to TDQUEUE, the security profile that protects the CICS Transient Data queue (TD queue) commands. Default resource and grouping class names for CICS commands are CCICSCMD and VCICSCMD, respectively, but these names can be overridden by the XCMD CICS system initialization parameter.

For example, use the following z/OS Security Server (RACF) commands to define a profile for TD queue commands in the CICSCMD class, and to authorize users to issue the TDQUEUE commands:
RDEFINE CCICSCMD TDQUEUE UACC(NONE)
PERMIT TDQUEUE CLASS(CCICSCMD) ACCESS(ALTER) ID(#client_user_ID_group)
SETROPTS GENERIC(CCICSCMD) REFRESH
RESSEC=ALWAYS
If SEC=YES and RESSEC=ALWAYS are specified as CICS system initialization parameters, then client user IDs require the following resource authorization:
Transient data queues (TD queues)

Client user IDs require ALTER access to ZU*, the profile that protects ZUnit CICS TD queues. Default resource and grouping class names for CICS TD queues are DCICSDCT and ECICSDCT, respectively, but these names can be overridden by the XDCT CICS system initialization parameter.

For example, use the following z/OS Security Server (RACF) commands to define a profile for TD queues in the DCICSDCT class, and to authorize users to access them:
RDEFINE DCICSDCT ZU* UACC(NONE) DATA('ZUNIT')
PERMIT ZU* CLASS(DCICSDCT) ACCESS(ALTER) ID(#client_user_ID_group)
SETROPTS GENERIC(DCICSDCT) REFRESH
Programs
Client user IDs require:
  • READ access to AZUCREST
  • READ access to all load modules or program objects containing routines that are called by programs under test using non-CICS interfaces

Default resource and grouping class names for CICS programs are MCICSPPT and NCICSPPT, respectively, but these names can be overridden by the XPPT CICS system initialization parameter.

For example, use the following z/OS Security Server (RACF) commands to define profiles for program AZUCREST in the MCICSPPT class and programs under test in the NCICSPPT class, and to authorize users to access them:
RDEFINE MCICSPPT AZUCREST UACC(NONE) DATA('ZUNIT')
RDEFINE NCICSPPT TESTPGM1 UACC(NONE) ADDMEM(#test_program_1,#test_program_2,#test_program_3)
RDEFINE NCICSPPT TESTPGM2 UACC(NONE) ADDMEM(#test_program_4,#test_program_5)
PERMIT AZUCREST CLASS(MCICSPPT) ACCESS(READ) ID(#client_user_ID_group)
PERMIT TESTPGM1 CLASS(NCICSPPT) ACCESS(READ) ID(#client_user_ID_group1)
PERMIT TESTPGM2 CLASS(NCICSPPT) ACCESS(READ) ID(#client_user_ID_group2)
SETROPTS GENERIC(MCICSPPT) REFRESH
SETROPTS GENERIC(NCICSPPT) REFRESH
Temporary Storage queues (TS queues)
By default, no authorization is required for temporary storage queues (TS queues). If you want to enforce security for TS queues, define two TSMODELs in CICS:
  • One with PREFIX(_AZU_LOG) LOCATION(AUXILIARY) SECURITY(YES)
  • One with PREFIX(_AZU_CTL) LOCATION(MAIN) SECURITY(YES)
Client user IDs require UPDATE authorization to, at least, profiles for TS queues with names starting with _AZU_LOGRS_ and _AZU_CTL2_.

The default resource and grouping class names for temporary storage queues are SCICSTST and UCICSTST, respectively, but these names can be overridden by the XTST CICS system initialization parameter.

For example, use the following z/OS Security Server (RACF) commands to define profiles for TS queues used by ZUnit, and to authorize users to access them:
RDEFINE SCICSTST _AZU_* UACC(NONE) DATA('ZUNIT')
PERMIT _AZU_* CLASS(SCICSTST) ACCESS(UPDATE) ID(#client_user_ID_group)
SETROPTS GENERIC(SCICSTST) REFRESH