Creating an ICSF CTRACE configuration data set

Starting with ICSF FMID HCR77A1, ICSF CTRACE support has been enhanced to support configurable ICSF CTRACE options from PARMLIB. During SMP/E install, a default CTICSF00 PARMLIB member is installed in SYS1.PARMLIB. The CTICSF00 PARMLIB member provides default component trace values for ICSF. By default, ICSF CTRACE support will trace with the KdsIO, CardIO, RdIO, and SysCall filters using a 2M buffer. Configurable options are commented out within this PARMLIB member to provide examples of how to turn them on.
Note: Beginning with FMID HCR77A1, ICSF needs to have read access to all data sets in the PARMLIB concatenation to access the CTRACE parmlib member CTICSF00.

The CTICSF00 PARMLIB member can be used to create customized ICSF CTRACE Configuration Data Sets in PARMLIB. A customized ICSF CTRACE Configuration Data Set can then be specified in the ICSF Options Data Set using the new CTRACE option.

For example, CTRACE(CTICSFxx), where xx is any 2 characters that were used when copying the default CTICSF00 parmlib member.

Component tracing is active when ICSF starts using the trace options defined in the CTICSFxx PARMLIB member, where 00 is the default. If the specified PARMLIB member is incorrect or absent, ICSF CTRACE will attempt to use the default CTICSF00 PARMLIB member. If the CTICSF00 PARMLIB member is incorrect or absent, ICSF CTRACE will perform tracing using an internal default set of trace options. The operator can specify trace options individually on the TRACE CT command, or can specify the name of a CTICSFxx PARMLIB member containing the desired trace options. Using a PARMLIB member on the TRACE CT command can help minimize operator intervention and avoid syntax or keystroke errors.

The contents of the CTICSF00 PARMLIB member, is as follows:
/***START OF SPECIFICATIONS*****************************************/           
/*                                                                 */           
/*  $MAC (CTICSF00) COMP(05101) PROD(CSF):                         */           
/*                                                                 */           
/*01* MACRO NAME: CTICSF00                                         */           
/*                                                                 */           
/*01* DESCRIPTIVE NAME: CTRACE Options for ICSF Startup            */           
/*                                                                 */           
/*01* COPYRIGHT:                                                   */           
/*                                                                 */           
/*     LICENSED MATERIALS - PROPERTY OF IBM                        */           
/*                                                                 */           
/*     5650-ZOS                                                    */           
/*                                                                 */           
/*    COPYRIGHT IBM CORP. 2015                                     */           
/*                                                                 */           
/*     STATUS = HCR77B1                                            */           
/*                                                                 */           
/*01* FUNCTION:                                                    */           
/*      Define the default ICSF CTRACE options                     */           
/*                                                                 */           
/*01* COMPONENT: 05101 (CSF)                                       */           
/*                                                                 */           
/*01* DISTRIBUTION LIBRARY:  PARMLIB                               */           
/*                                                                 */           
/***END OF SPECIFICATIONS*******************************************/           
TRACEOPTS                                                                       
/*-----------------------------------------------------------------*/           
/*   ON OR OFF: PICK 1                                             */           
/*-----------------------------------------------------------------*/           
          ON                                                                    
/*        OFF                                                      */           
/*-----------------------------------------------------------------*/           
/*   ASID: 1 TO 16, 2-HEXBYTE VALUES                               */           
/*-----------------------------------------------------------------*/           
/*        ASID(0042,0043,0044)                                     */           
/*-----------------------------------------------------------------*/           
/*   JOBNAME: 1 TO 16, 8 BYTE VALUES                               */           
/*   This option takes 1 to 16 comma-separated 8 byte values. Each */           
/*   value specified represents a jobname that should be traced by */           
/*   ICSF CTRACE support.  Additionally, other jobnames that begin */           
/*   with the same characters will also be traced. For example, if */           
/*   a USERID is specified, all TSO jobs matching USERIDc, where   */           
/*   'c' is a character between A-Z will be traced, and, all Unix  */           
/*   processes matching USERIDn, where 'n' is a number from 0-9    */           
/*   will be traced.                                               */           
/*-----------------------------------------------------------------*/           
/*        JOBNAME(USERID,JOBNAME1)                                 */           
/*-----------------------------------------------------------------*/           
/*   BUFSIZE: A VALUE IN RANGE 16K TO 16M                          */           
/*-----------------------------------------------------------------*/           
          BUFSIZE(2M)                                                           
/*-----------------------------------------------------------------*/           
/*   OPTIONS: NAMES OF FUNCTIONS TO BE TRACED, OR "ALL", OR "MIN"  */           
/*-----------------------------------------------------------------*/           
/*        OPTIONS(           */                                                 
/*                'ALL'      */                                                 
/*               ,'KDSIO'    */                                                 
/*               ,'CARDIO'   */                                                 
/*               ,'SYSCALL'  */                                                 
/*               ,'DEBUG'    */                                                 
/*               ,'RDIO'     */                                                 
/*               ,'RDDATA'   */                                                 
/*               ,'MIN'      */                                                 
/*                )          */                                                 
           OPTIONS('KDSIO','CARDIO','SYSCALL','RDIO')

TRACEOPTS - This option takes a value of either ON or OFF. Turning this option OFF reduces ICSF CTRACE to use a minimal set of tracing. Turning this option OFF disables ICSF CTRACE. When OFF is specified all other trace options within the PARMLIB options data set should be commented out

ASID - This option takes 1 TO 16 comma-separated 2-hexbyte values. Each value specified represents an address space ID that should be traced by ICSF CTRACE support

JOBNAME - This option takes 1 TO 16 comma-separated 8 byte values. Each value specified represents a jobname that should be traced by ICSF CTRACE support. Additionally, other jobnames that begin with the same characters will also be traced. For example, if a USERID is specified, all TSO jobs matching USERIDc, where 'c' is a character between A-Z will be traced, and, all Unix processes matching USERIDn, where 'n' is a number from 0-9 will be traced.

BUFSIZE - This option takes a value in the range between 16K to 16M, where K represents kilobytes and M represents megabytes. This value is used to specify the ICSF CTRACE buffer size to be allocated.

OPTIONS - This option is used to specify the ICSF CTRACE filters to use for tracing. A comma-separated list of filter names, each enclosed with single quotes, may be specified. The following filters are supported by this option:
  • ALL - This filter provides output for all ICSF trace records regardless of their filter specification.
  • CARDIO - This filter traces activity with requests to cryptographic coprocessors.
  • DEBUG - This filter provides granular trace output for debugging specific ICSF modules. This filter should only be turned on at the direction of IBM service professionals. Turning this level of tracing on may degrade ICSF performance.
  • KDSIO - This filter traces update activity to the CKDS, PKDS, and TKDS.
  • MIN - This filter traces a minimum set of operations that are not covered by the other filters.
  • RDDATA - This filter traces remote device request and response messages.
  • RDIO - This filter traces activity pertaining to remote device I/O events.
  • SYSCALL - This filter traces entry and exit from ICSF callable services.

The TRACEENTRY option in the ICSF Options Data Set has been deprecated. If this option is specified, it will be ignored and will produce a CSFO0212 message.