The Code Debug CICS Script Facility lets users record the primary and line commands they enter during a debugging session, save them in a PDS or PDSE, and then replay them later. This section explains how to set up — or disable — the Script Facility. For information on how to record and play back scripts, see the CAPTURE and INCLUDE primary commands in the Code Debug CICS Reference space.

Code Debug’s scripting capability is intended only for replicating breakpoints, keeps, and modifications to working storage data. Code Debug is not meant to be used as an automated testing tool.

Overview

The Code Debug CICS Script Facility uses an MVS subtask to perform the physical I/O to a script PDS or PDSE. Since a subtask is used, the CICS TCB does not have to wait for completion of the I/O. This allows other CICS tasks and Code Debug debugging sessions not using scripts to continue execution. In addition, because dynamic allocation facilities are included in the subtask, setup of the Script Facility is quick and easy. The Script Facility subtask uses single-threaded access, which forces Code Debug users who have concurrent script requests outstanding to wait for prior requests to complete. Other tasks, however, including Code Debug debugging sessions that are not using a script, can continue to execute normally without waiting. Since the time required to save or execute a script is minimal, waits should not be noticeable to the user.

Two types of script data sets may be accessed during a debugging session:

• User script data set
• System script data set.

A user script data set can be user-defined or site-defined. The ability to access user script data sets can be disabled as a region or site option. By default, the Script Facility will try to access a user script data set first when executing a script. Individual users can choose not to utilize user script data sets.

The system script data set is used when:

• The current script request cannot be satisfied from a user script data set.
• The user has decided not to utilize a user script data set.
• Access to user script data sets has been disabled as an installation option.

Your site can set up a system script data set as a read-only repository of scripts to be shared by multiple users. The site installer is responsible for creating the data set with the procedures in this section prior to its first use.

Script data sets must be defined as fixed blocked with a logical record length (LRECL) of 120. User-defined user script data sets, if allowed by your site, do not need to be pre-allocated. Allocation will occur when a user first attempts to save a script. System script data sets and site-defined user script data sets must be pre-allocated. JCL members DBCDEFSS (for system script data sets) and DBCDEFUS (for user script data sets) contain JCL to allocate the required data sets.

Activation of the Script Facility requires few, if any, JCL changes. If your site allows dynamic allocation of data sets, enabling and customizing the Script Facility requires no CICS startup JCL changes and only a few global parameter changes, all of which can be done via the BMC PARMLIB. If your site does not use dynamic allocation, you will need to modify your CICS startup JCL in addition to specifying global parameter changes.

This role involves Code Debug CICSInstaller.

This section explains how to enable and configure the Code Debug CICS Script Facility. In some steps, global parameter values are set using the BMC PARMLIB. All of the global parameters set in this section are described in Configuration-Parameters. For details on modifying the parameters, see Methods-of-Specifying-and-Updating-Parameters.

Your site’s external security manager—RACF for example—must grant authority to create Code Debug’s system and user script data sets.

Task 10.1.1 Enable the Script Facility

Enable the Script Facility by adding the following line to your site’s BMC PARMLIB:

Task 10.1.2 Add Program DBUGPLTS to Your CICS Shutdown PLT

In your CICS shutdown PLT, before the line reading DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM, add the following entry:

Task 10.1.3 Create a System Script Data set 

The system script data set is intended to serve as a repository of scripts to be shared by all Code Debug CICS users in a single region or multiple regions. For example, the data set could be enabled for READ and WRITE access in a test region where new scripts are developed. In all other CICS regions, the data set could be enabled as a READONLY data set. This would allow multiple users in these regions to utilize the scripts without concern about modifying them.

Member DBCDEFSS contains JCL to create an Code Debug CICS system script data set. Modify the JCL according to the instructions as follows, then submit it to create your system script data set.

1. Add a job card and any necessary OUTPUT specifications to the front of the member.

2. Change the XDSSDSN parameter in the JCL to the data set name you want to use for your system script data set, then write that DSN as follows:

   XDSSDSN:____________________

   Warning

   Important

   Your site’s external security manager must grant authority to create system script data sets with the chosen DSN.

3. Change the XDSSUNI parameter to the DASD unit name on which the data set is to be allocated.
4. Change the XDSSVOL parameter to the volume and serial number on which the data set is to be allocated.
5. Change the XDSSBLK parameter to the blocksize you want to use. This value must be a multiple of 120. Do not modify the LRECL specified in the JCL.
6. If you want the data set to be allocated as a PDSE, uncomment the line reading DSNTYPE=LIBRARY,.
7. The following parameters can also be changed, if required:
   • XDSSTYP=TRK — allocation type
   • XDSSPA=15 — primary allocation units
   • XDSSSA=15 — secondary allocation units
   • XDSSDB=44 — number of directory blocks.
8. Submit the JCL to allocate your system script data set.

Task 10.1.4 Set Access to Your System Script Data set

You can configure the system script data set with READONLY or WRITE access.

To make the data set READONLY, add the following parameter to your XDGBxxxx member in the BMC PARMLIB:

SCRIPT_FACILITY_SYSTEM_SCRIPT_STATUS=READONLYTo enable WRITE access, add the following parameter to your XDGBxxxx member in the BMC PARMLIB:

Task 10.1.5 Enable Allocation of Your System Script Data set

If your site allows dynamic allocation of data sets in CICS regions, go to Step 1. If your site does not allow dynamic allocation of data sets in a CICS region, go to Step 2.

1. Add the following parameters to your XDGBxxxx member in the BMCPARMLIB:
   
   SCRIPT_FACILITY_SYSTEM_SCRIPT_DDNAME=DYNAMIC
   
   SCRIPT_FACILITY_SYSTEM_SCRIPT_DSN= dsn from Create a System Script Data set, Step 2
   
   No CICS startup JCL changes are needed.
   Go to Decide Whether Your Site Will Allow User Script Data sets.
   
   
2. Modify your XDGBxxxx member in the BMC PARMLIB and CICS startup JCL as follows:
   1. Select a 1- to 8-character ddname for your system script data set and write it as follows:
      ddname:____________________
   2. Add the following parameter to your XDGBxxxx member in the BMC PARMLIB:
      SCRIPT_FACILITY_SYSTEM_SCRIPT_DDNAME= ddname written above System script not dynamically alloc.
3. Add the following DD statement to your CICS startup JCL:
   
   //ddname written above DD DISP=SHR,DSN=dsn from Create a System Script Data set, Step 2

Task 10.1.6 Decide Whether Your Site Will Allow User Script data sets 

User script data sets enhance the useability of the Script Facility. BMC recommends allowing their use.

If you want user script data sets, but your site does not allow dynamic allocation of data sets in CICS regions, go to Create a Shared User Script data set.

If your site does not want the enhanced usability provided by user script data sets, go to Set Defaults for Saving Scripts if Debugging is Terminated During Capture.

Task 10.1.7  Decide Whether Your Site Will Force All Users to Share a Single User Script Data set.

Restricting all users to a common pre-defined user script data set can result in decreased usability and naming conflicts. BMC recommends individual user-defined user script data sets.

If you want user-defined user script data sets, continue with Enable Allocation of User-Defined User Script data sets.

If your site wants to restrict users to a single shared user script data set, go to Create a Shared User Script data set.

Task 10.1.8  Enable Allocation of User-Defined User Script Data sets

The first two global parameters in this step establish dynamically allocated user-defined user script data sets. Default values are shown for the remaining global parameters which set the default allocation values for new user script data sets on the Script Data set Allocation screen (0.6). If you want to use different values, see Configuration-Parameters for more information.

Add the parameters listed as follows to your XDGBxxxx member in the BMC PARMLIB. Parameters with a value of NULL are set to a blank (null) value—not the word “null.”

SCRIPT_FACILITY_USER_SCRIPT_ENABLE=YES
SCRIPT_FACILITY_USER_SCRIPT_DDNAME=DYNAMIC
SCRIPT_FACILITY_USER_SCRIPT_BLKSIZE=27960
SCRIPT_FACILITY_USER_SCRIPT_DIR_BLOCKS=44
SCRIPT_FACILITY_USER_SCRIPT_CLASS=NULL
SCRIPT_FACILITY_USER_SCRIPT_LIBRARY=NO
SCRIPT_FACILITY_USER_SCRIPT_MGMT_CLASS=NULL
SCRIPT_FACILITY_USER_SCRIPT_PRIMARY_ALLO=15
SCRIPT_FACILITY_USER_SCRIPT_DSN_PREFIX=NULL
SCRIPT_FACILITY_USER_SCRIPT_SECOND_ALLO=15
SCRIPT_FACILITY_USER_SCRIPT_STG_CLASS=NULL
SCRIPT_FACILITY_USER_SCRIPT_SMS=NO
SCRIPT_FACILITY_USER_SCRIPT_TYPE=TRK
SCRIPT_FACILITY_USER_SCRIPT_UNIT=SYSDA
SCRIPT_FACILITY_USER_SCRIPT_VOLUME=NULLGo to Set Defaults for Saving Scripts if Debugging is Terminated During Capture.

Task 10.1.9  Create a Shared User Script Data set 

The user script data set is intended to serve as a repository of scripts controlled by individual Code Debug CICS users.

Member DBCDEFUS contains JCL to create an Code Debug CICS user script data set. Modify the JCL according to the instructions as follows, then submit it to create your user script data set.

1. Add a job card and any necessary OUTPUT specifications to the front of the member.
2. Change the XDUSDSN parameter in the JCL to the data set name you want to use for your user script data set, then write that dsn as follows:
   XDUSDSN:___________________
3. Change the XDUSUNI parameter to the DASD unit name on which the data set is to be allocated.
4. Change the XDUSVOL parameter to the volume and serial number on which the data set is to be allocated.
5. Change the XDUSBLK parameter to the blocksize you want to use. This value must be a multiple of 120. Do not modify the LRECL specified in the JCL.
6. If you want the data set to be allocated as a PDSE, uncomment the line reading DSNTYPE=LIBRARY,.
7. The following parameters can also be changed, if required:
   • XDUSTYP=TRK — allocation type
   • XDUSPA=15 — primary allocation units
   • XDUSSA=15 — secondary allocation units
   • XDUSDB=44 — number of directory blocks.
8. Submit the JCL to allocate your user script data set.

Task 10.1.10 Enable Allocation of Your User Script Data set

If your site allows dynamic allocation of data sets in CICS regions, go to Step 1. If your site does not allow dynamic allocation of data sets in a CICS region, go to Step 2.

1. Add the following parameters to your XDGBxxxx member in the BMC PARMLIB:
   SCRIPT_FACILITY_USER_SCRIPT_DDNAME=DYNAMIC
   SCRIPT_FACILITY_USER_SCRIPT_DSN= dsn from Create a System Script Data set, Step 2
   No CICS startup JCL changes are needed.
   Go to Set Defaults for Saving Scripts if Debugging is Terminated During Capture.
2. Modify your XDGBxxxx member in the BMC PARMLIB and CICS startup JCL as follows:\
   1. Select a 1- to 8-character ddname for your user script data set and write it as follows:
      ddname:____________________
   2. Add the following parameter to your XDGBxxxx member in the BMC PARMLIB:
      SCRIPT_FACILITY_USER_SCRIPT_DDNAME=ddname written above
   3. Add the following DD statement to your CICS startup JCL:
      // ddname written above DD DISP=SHR,DSN= dsn from Create a Shared User Script Data set, step 2.

Task 10.1.11 Set Defaults for Saving Scripts if Debugging is Terminated During Capture 

Global parameter SCRIPT_FACILITY_SESS_TERMINATION_STATUS sets the default for whether or not a script is saved when an Code Debug debugging session is terminated, either intentionally or due to terminal timeout, while that script is being captured. It can be set to SAVE or DISCARD.

SCRIPT_FACILITY_SAVE_AS_NAME sets the default name for scripts saved when a debugging session is terminated. Setting SCRIPT_FACILITY_SAVE_AS_NAME to eight asterisks (********) will cause the userID of the person capturing a script to be used for the script name. A 1- to 8-character name can also be specified for the default script name.

Users can override the default values on the Script Data set Allocation screen (0.6).

Add the following parameters to your XDGBxxxx member in the BMC PARMLIB:

Task 10.2 Disabling the Script Facility

If your site chooses not to use the Script Facility, you can disable it by adding the following line to your site’s global parameters:

SCRIPT_FACILITY_ENABLE=NOFor more information, see Methods-of-Specifying-and-Updating-Parameters.