Set up procedure

Use the following procedure to get started.

Step 1: Start and configure the CICS internal trace

C\Prof gathers information on CICS activity from the CICS internal trace. To record transaction profiles, C\Prof requires you to place the CICS internal trace into the STARTED state, and to set a table size large enough to ensure that C\Prof can collect from the trace before the oldest entries are overwritten by new entries (a condition known as wrapping). To reduce the likelihood of wrapping, it is recommended that you set an initial value for the trace table size to 32 MB and only increase it incrementally as required.

To run C\Prof, you will need to start and configure the CICS internal trace in each CICS region that you wish to monitor. This can be done using any of the following methods:

• Dynamically at any time using the CICS-supplied transaction CETR.

• At CICS startup with system initialization parameters (SIT).

• Allow C\Prof to control the trace using the C\Prof trace control program, TXCCICS1 together with the TRACECONTROL, ACTIVATETRACE, and RESETTRACE control statements.

These methods are described in the sections below.

CETR method

To temporarily configure the CICS internal trace using CETR:

1. Log onto your CICS region.

2. Start transaction CETR. The CICS Trace Control Facility is displayed.

   

3. CETR CICS Trace Control Facility

4. Set the Internal Trace Status to STARTED.

5. Set the Internal Trace Table Size to 32768 (32 MB) or higher.

6. Set the Master System Trace Flag to ON.

7. Press Enter to save your settings, and then press PF3 to quit.

SIT method

To configure the CICS internal trace at startup, add the following system initialization parameters to your CICS regions:

• SYSTR=ON

  The SYSTR system initialization parameter specifies the setting of the master system trace flag.

• INTTR=ON

  The INTTR system initialization parameter specifies whether the internal CICS trace destination is to be activated at system initialization.

• TRTABSZ=32768

  The TRTABSZ system initialization parameter specifies the size, in kilobytes, of the internal trace table. Set it to a value of 32768 KB (32 MB) or higher.

TRACECONTROL method

You can optionally configure the collector to invoke the C\Prof trace control program TXCCICS1. TXCCICS1 can be used to adjust the status and size of the CICS internal trace automatically when collection starts and stops. This method can be useful if your normal internal trace settings are not compatible with the requirements of collection. This can occur, for example, if the internal trace must usually be in a STOPPED state, or if you require a trace table size during normal operations that is too small for C\Prof.

If you wish to use the C\Prof trace control program for a specific CICS region, it is recommended that you complete the remaining steps in this quick start guide before attempting to use trace control in that CICS region. When you have finished this setup procedure, refer to Configuring automatic internal trace control for specific CICS regions for more information on setting up the program and how to add the relevant control statements to your configuration file to enable the feature.

Step 2: Update product settings

Configure the C\Prof ISPF dialog by completing the following steps.

1. Start the C\Prof ISPF dialog.

   To do this, use the new menu option you created in Create a C\Prof menu option.

   
   C\Prof primary option menu

2. Select option 6 Settings.

   
   The Settings panel

3. Review the following settings, replacing TXC.V1R2M0 with the high-level qualifier you selected during product installation:

   • C\PROF Link library

     Specify the name of the C\Prof link library, TXC.V1R2M0.STXCLINK, in the space provided. The C\PROF link library contains the ISPF and batch executable modules.

   • C\PROF Link library (APF)

     Specify the name of the C\Prof link library, TXC.V1R2M0.STXCAUTH, in the space provided. This APF authorized library is used as the STEPLIB in JCL generated for the following purposes:

     • Discovering CICS systems and generating a configuration file (as described in Step 4: Generate a configuration file)

     • Recording from the internal trace (as described in Step 8: Record transaction data)

   • CICS SDFHLINK

     Leave this field empty if you have performed the optional CICS installation step Installing CICS-required modules in the MVS linklist in the IBM Knowledge Center as the modules are already available to all users and no further action is required. Otherwise, specify one of the following libraries:

     • The name of the CICS SDFHLINK library you created in CICS trace formatting routines. This library must contain modules DFHTRxxx and DFHTTxxx for each release of CICS you wish to support.

     • The actual CICS SDFHLINK library for the version of CICS that you wish to support. Using this option may limit you to supporting only one version of CICS at a time.

   • Personal Profile

     The profile library is used by the ISPF dialog to permanently save certain session details, including the trace data set list. This data set is allocated for you and can be any name. You can share this library with other C\Prof users.

   • Temporary work files

     Specify the size and units for temporary work files used by C\Prof.

     C\Prof uses temporary work files to contain transaction lists and trace data associated with your active requests. Long lists may require additional work file space. Message TXC1043E is issued by the ISPF dialog when the space settings are too small. Select a starting value of 5 MB for both primary and secondary quantity field. Increase the size if your profiling requests fail.

   • Job statement information

     Specify default job statement information. These job cards are used for all JCL that is generated by the ISPF dialog.

4. Press PF3 to exit.

Step 3: Allocate configuration and checkpoint data sets

The C\Prof collection server requires you to supply a configuration file and to register data sets created through the collection process in a checkpoint data set. In this step, we will use primary menu option 5 Configure to create the initial data set for the server configuration file and for a checkpoint data set.

1. On the C\Prof primary option menu, select option 5 Configure. The Configure the server panel is shown.

2. Enter a data set naming prefix in the +PREFIX field. C\Prof will use this prefix as a high-level qualifier for all data sets created during setup and for all data collected by the C\Prof collection server.

   +PREFIX is a substitution variable. For example, when +PREFIX is specified as USER.CPROF and the data set name pattern is +PREFIX.CONFIG then the fully qualified data set name is USER.CPROF.CONFIG.

   +PREFIX is optional. If you choose not to use it then the required data sets must specify their own name or pattern.

3. Review the name specified in the Configuration field and make changes as desired. The Configuration control data set is used to store the configuration file and JCL generated by the dialog.

4. Select option 1 Allocate the configuration and JCL library to allocate the data set.

5. Review the status message at the top-right of the screen to confirm that the allocation was successful.

6. In the LPAR field, enter the name of the LPAR where the CICS regions you wish to monitor are running. C\Prof inserts this value into JCL generated in subsequent steps.

   Note: If you want to collect from additional LPARs, complete the setup procedure and then refer to the topic Expanding your collection topology to CICS regions in other LPARs for more information.

7. Review the checkpoint data set name specified in the Checkpoint field and make changes as desired.

   

   The Configure the server panel

   The checkpoint data set is a VSAM KSDS used by C\Prof in the following ways:

   • To register data sets created by the C\Prof collection server during the trace collection process.
   • To locate collected data as requested in the C\Prof ISPF dialog.
   • To manage the removal of data collected by the C\Prof collection server once the data has reached a specified expiration threshold using the housekeeping.

8. Select option 2 Allocate the checkpoint data set to generate JCL to allocate the checkpoint data set.

9. Submit the generated IDCAMS JCL.

Tips:

• All JCL generated by the dialog is stored in the data set specified in the Configuration field. You can use the Member column to specify alternative names to use when storing the corresponding JCL.
• After the configuration data set has been allocated, the Configuration field label becomes a point and shoot screen element that you can use to browse and edit the contents of the data set. Simply place your cursor on Configuration and press Enter.
• To view a list of members in the configuration data set, enter M on the Option line.
• The same checkpoint data set can be used by multiple collectors to provide a unified view of transaction data. Use this technique if you wish to collect data from multiple LPARs. Additional information can be found in Collecting from CICS regions that use multiregion operation (MRO).

Step 4: Generate a configuration file

In this step, we will use the discover utility to discover your running CICS regions and generate the collector configuration file required by the C\Prof collection server.

1. On the Configure the server panel, review the settings for archive data set naming.

   Archive data sets are used by C\Prof to store data collected from the CICS internal trace. Archive data sets can be shared between users to provide universal access to trace data from a single C\Prof collection server, or they can be created by individuals for private use. The settings you choose in this step are used by C\Prof to determine the naming conventions used for these data sets.

   There are two archive data set storage options: generation data groups (GDG) and Dynamic. Select option 1 to manage archive data sets using GDGs, or option 2 to allow C\Prof to allocate data sets on-demand using the dynamic option.

   Consider the following tradeoffs when making your choice.

   • GDG base entries

     GDG requires base entries before C\Prof can write data to the data set. This places an additional burden on administrators when you change your data set naming pattern, when new CICS regions are introduced, and when the name of your CICS region or group is changed as you will need to create new base entries each time they change. Dynamic has no such limitations.

     If you select GDG, you will be prompted to create the GDG base entries later in this setup procedure.

   • Housekeeping

     GDG provides an automatic high-water mark on the amount of archive data that resides on DASD at any one time. Using GDGs ensures that once the generation data set limit has been reached, the oldest data set is automatically deleted.

     When using the dynamic option, new data set are allocated as required without regard for how much data has already been collected. This can potentially cause operational issues if left unmanaged. When using the dynamic option, consider using the C\Prof housekeeping utility (see Cleaning up old collection data via housekeeping) to periodically delete old data sets that have expired.

   • Limited number of data sets

     GDG is limited to 255 generation data sets (999 with extended GDG support in z/OS 2.2).

     Dynamic has no limit on the number of data sets that can be cataloged at any one time.

   One you have selected your storage option, review the naming pattern supplied in the adjacent field. You can use the default naming pattern, or you can customize the naming pattern if you wish to use a different data set naming scheme.

   To learn more data set naming and allocation in C\Prof, see ARCHDSN=pattern.

2. Select option 3 Discover your CICS regions to generate JCL for the discover utility.

3. Optional: If you want to collect data from CICSPlex SM address spaces (CMAS), uncomment the CMAS control statement by removing the preceding hashes (##).

4. Optional: The WITHGROUPING control statement in the generated JCL instructs the discovery process to automatically group the CICS regions it finds. It does this by determining which CICS regions are connected via CONNECTION or IPCONN definitions. This is useful when defining a group of regions that use MRO. If you do not wish to group your regions in this way, simply remove the WITHGROUPING statement.

   To learn more about region grouping in C\Prof, see GROUP=name and GROUPEND.

5. Submit the generated JCL.

C\Prof locates your running CICS regions and generates the configuration file using the name supplied in the Member column. A list of discovered CICS regions can be found in the SYSPRINT output data set.

SYS1     TXC0001I C\\PROF is starting
CICSDEV1 TXC0382I CICS region was discovered: CICS TS V5.4 (710) Size=32768K
                  Wrap=38.35 seconds
CICSPRD2 TXC0382I CICS region was discovered: CICS TS V5.1 (680) Size=32768K
                  Wrap=41.81 seconds
...

Example of SYSPRINT output data set from CICS region discovery

Tip: If desired, all users can share the same configuration file and gain access to the same collected data. No additional user setup is required.

Step 5: Edit the configuration file

Before you run the collector, review the generated configuration file.

1. On the Configure the server panel, select option 4 Edit the configuration. The configuration file is displayed.

   Tip: The data set and member name of the configuration file is displayed at the top of the screen for future reference.

2. Specify a z/OS UNIX domain socket name for the C\Prof collection server. The server uses this socket to listen for trace collection requests from the C\Prof ISPF dialog. To specify the socket name, complete the following steps:

   1. Find the SOCKET=<zFS_file_name> control statement.
   2. Replace <zFS_file_name> with a file name in the z/OS UNIX file system (zFS) of your choice.

   You do not need to create the file yourself. Simply supply the full name and path you wish to use in a writable location appropriate to your environment. The maximum length is 108 characters. Access to the C\Prof collection server is secured by file access to the specified zFS path name. Write access is required to connect to the socket.

   Example: To assign zFS path /u/cicsprod/cprof.sock, specify SOCKET=/u/cicsprod/cprof.sock in your configuration file.

   Note: C\Prof can still be used to collect data without a socket by using the alternative method of submitting ad hoc batch requests. It is strongly recommended that you use the SOCKET as it provides rich collection and trace status information in option 1 Regions on the C\Prof primary option menu and serves as a foundation for creating a cross-LPAR collection topology. If, however, your environment precludes you from using a socket, you can omit the SOCKET statement and continue with a limited set of functions. Some deviation with the screens displayed in this document can also be expected.

3. Edit and group your CICS regions. To do this, complete the following steps:

   1. Edit the CICS control statements.

      Configuration files generated by C\Prof contain a list of all CICS regions that were running whilst the discovery process was taking place. These CICS regions are defined in the configuration file using CICS control statements.

      To submit collection requests for a CICS region, it must be defined in the configuration file. If a CICS region was offline at the time of discovery, you can manually insert it now. If you do not want to allow collection on a specific CICS region, simply remove it from the configuration file.

   2. Define multiregion operation (MRO) groups using the GROUP and MRO control statements.

      If you have a set of CICS regions that use multiregion operation (MRO), define an MRO group in the configuration file. An MRO group is defined using the GROUP=name MRO=YES and GROUPEND statements.

      Example: To define a group named SYS1 that contains an MRO group that includes a terminal-owning region (TOR), an application owning region (AOR), and a file owning region (FOR), use the following control statements:

      GROUP=SYS1 MRO=YES
      CICS=CICSTOR
      CICS=CICSAOR
      CICS=CICSFOR
      GROUPEND
      

      Grouping CICS regions for multiregion operation (MRO)

      Note: For more information on how C\Prof treats MRO transactions, see Collecting from CICS regions that use multiregion operation (MRO).

   3. Define operational groups.

      The GROUP control statement can also be used to group sets of CICS regions for operational management purposes. This can be useful if you wish to submit a single collection request for a group of regions (for example, all of your test CICS regions) rather than submitting several individual requests for each group member. To do this, use the same syntax as in the step above, but set MRO=NO (or omit the MRO statement entirely).

      Example: To define a group named TESTGRP that contains two independent CICS regions used for testing, use the following control statements:

      GROUP=TESTGRP
      CICS=CICSTST1
      CICS=CICSTST2
      GROUPEND
      

      Grouping CICS regions for operational management

4. Optional: The following additional control statements have been automatically added to your configuration file. To learn more about the C\Prof configuration file, it is highly recommended that you take the time to review the information below. If a control statement is commented with double hashes (##), simply remove the hashes to enable the statement.

   • SERVER

     Sets the collection mode to SERVER. C\Prof will start as a collection server and then wait for its first user-initiated collection request. This statement is required.

   • SERVICE=<class>

     To operate effectively, the collector must be able to quickly process the CICS internal trace. To ensure that the collector can perform this function, it is recommended that the collector have the same or higher Workload Manager (WLM) service class or dispatching priority as CICS. This is particularly important when running the collector in an environment where transaction volume and CPU utilization is high. You can use the optional SERVICE control statement in the configuration file to instruct C\Prof to set its required service class. To do this, replace with the service class of your choice. For more information, see SERVICE=service-class-name. The collector uses only a small amount of CPU and is often in a wait state so its impact on the system is low.

   • XCFGROUP=<name>

     The XCFGROUP control statement is an advanced option used to enable cross-collector communication, useful for establishing an expanded collection topology of multiple C\Prof collection servers that may span multiple LPARs. For now, do not adjust the XFGROUP control statement. When you have completed all the steps contained in the quick start procedure, refer to the information supplied in Expanding your collection topology to CICS regions in other LPARs for more on extending your collection topology.

   • PREFIX=<value>

     The +PREFIX control statement allows you to define a reusable naming prefix for data sets created by C\Prof. Replace the value with a prefix of your choice. The prefix will be prepended to the values you specify on the CHECKPT and ARCHDSN control statements described below.

   • CHECKPT=<data-set-name>

     The CHECKPT control statement is used to specify the name of the checkpoint data set. The value of the CHECKPT statement reflects the name you chose in Step 3: Allocate configuration and checkpoint data sets. This statement is required. More information on the CHECKPT control statement can be found in CHECKPT.

   • ARCHDSN=<pattern>

     The ARCHDSN control statement is used to specify the naming conventions used to store collected trace data. The settings applied in your configuration file have been derived from the choices you made in Step 4: Generate a configuration file. This statement is required. Rules that govern the naming of data sets can be found in ARCHDSN=pattern.

   • SUMMARY, DETAIL, and AUXILIARY

     These control statements specify the allocation attributes for the three types of data sets that can be created by the C\Prof collection server (summary, detail, and auxiliary trace data sets). If you are unsure what allocation attributes may be required at your site, talk to your systems administrator for further guidance. You can adjust the allocation attributes for these data sets as desired using the information supplied in AUXTRSW.

   • LEVEL=2

     The LEVEL control statement controls how much detail is collected when recording for transaction profiling. For standard profiling, use LEVEL=2 to collect summary information and important trace events. For other options, see LEVEL=value.

   • ACTIVATETRACE=1 and RESETTRACE=1

     ACTIVATETRACE=1 or higher grants C\Prof permission to adjust the active CICS trace levels for optimized profiling of transactions. RESETTRACE=1 restores your trace point levels to the state they were in before recording began. These are the recommended settings for profiling as they supply a complete application view of the trace.

     Note: Changing the CICS trace levels can impact the CICS region and increase transaction CPU and response time. If you do not want C\Prof to temporarily adjust your trace points during collection, review the settings in ACTIVATETRACE for additional options. Note however that changing these options can limit C\Prof's ability to provide a complete application perspective of the trace.

   • TRACECONTROL=<options>

     If your CICS environment prevents you from permanently running the CICS internal trace in the STARTED state, you can use the TRACECONTROL control statement with the ACTIVATETRACE, and RESETTRACE control statements to automatically set the required status and size of the CICS internal trace when collection starts and stops. For more information, see Configuring automatic internal trace control for specific CICS regions. Otherwise, leave this setting unchanged.

1. Save the file and then press PF3 to exit.

Note: The C\Prof configuration file has a variety of additional options to tailor collection to your environment. For a complete set of options, see Control statement summary.

Step 6: Define archive data set GDG base entries (GDG only)

If you have selected dynamic data set allocation instead of GDG (see Step 4: Generate a configuration file), you do not need to perform this step. Instead, proceed directly to Step 7: Start the C\Prof collection server.

If you have selected the GDG data set naming option, you will need to define the archive data set GDG base entries before you can start the collector by completing the following steps:

1. On the Configure the server panel, select option 5 Define the archive data set GDG base entries.

   Note: The C\Prof ISPF dialog uses your configuration file to determine which base entries it needs to create. If your configuration file has a syntax error, you will be prompted to correct it before proceeding.

2. Optional: Review the JCL. By default, the GDG limit is set to 5 (LIM=005). If you need to retain more data you can increase the value to a maximum of 999 as necessary.

3. Submit the generated JCL.

Step 7: Start the C\Prof collection server

Generate C\Prof collection server JCL from the ISPF dialog.

1. On the Configure the server panel, select option 6 Generate JCL to run the collection server.

2. Submit the generated JCL. Note the data set and member name at the top of your screen. You can use this to run your collector at any time without having to re-generate the JCL. More information on collector JCL can be found in JCL.

3. Review the collector SYSPRINT output data set to verify that C\Prof has started.

SYS1     TXC0001I C\Prof is starting
         TXC0400I Configuration processing was successful; DD=SYSIN
USR#SYS1 TXC0501I Operator commands can now be issued
...

Example collector SYSPRINT data set: collection server startup sequence

The C\Prof collection server is now ready to accept collection requests.

Note: Message codes and associated descriptions can be found in Messages and Codes.

Step 8: Record transaction data

Use the C\Prof ISPF dialog collect data from the CICS internal trace.

1. Return to the C\Prof primary option menu (PF3) and select option 1 Regions.

   Collection statistics for each of your CICS regions are displayed. The Trace and Size columns report the status and table size of the internal trace for each CICS region. These values reflect the settings you assigned in Step 1: Start and configure the CICS internal trace.

2. To record profiling data from a CICS region, enter line action R.

   

   Submitting a profiling request using the Region List panel

   Tip: To see a list of actions available for a CICS region, enter line action /.

3. Review the settings on the Start Collection panel. The Duration fields allow you to automatically terminate collection on the CICS region after the specified time limit. Specify any duration you wish, but for the purposes of this quick start guide, it is suggested that you enter a value of 5 Minutes.

4. To start recording, press Enter. The Region List is displayed once again.

5. Press Enter at any time to refresh the Region List. If you submitted a successful collection request, the value in the Status column changes to PROFILING. The value in the Collected column will increase to indicate successful data collection from the CICS internal trace. At this time, trace data is being written to new archive data sets which are, in turn, being registered by C\Prof in a checkpoint data set.

6. Optional: Review the collector SYSPRINT output data set to verify that collection has commenced and that archive data sets have been allocated.

   ...
   CICS54D2 TXC0300I Monitoring of internal trace is starting: CICS TS V5.4 (710)
                     Size=32768K AP=1 EI=2 LD=1 PG=1 RA=1 RI=1 RM=1 XM=1 XS
   CICS54D2 TXC0805I New archive data set was allocated;
                     DSN=USR.CPROF.CICS54D2.D160401.T130504.D001
   ...
   

   Example collector SYSPRINT data set: collector startup sequence

Note: The CICS internal trace is a circular buffer where the oldest trace entries are continuously being overwritten with new entries due to ongoing activity in CICS. The pace at which this overwriting occurs is reported in the Wrap Speed column on the Region List panel. If a CICS region is busy and its internal trace table is small, its Wrap Speed will be short. If you are collecting from a CICS region with a short Wrap Speed, the C\Prof collection server may issue error message TXC0303E to indicate that the trace has wrapped before C\Prof could capture all the trace entries. As a result, collection must stop for the affected CICS region. If the CICS region belongs to a group that uses multiregion operation (MRO), collection must stop for these regions also.

To resolve wrapping issues in a CICS region: Try increasing the size of the internal trace table. More information can be found Step 1: Start and configure the CICS internal trace. Once you have increased the size of the trace, restart the collector, verify that the value in the Wrap Speed column has increased, and then resubmit your collection request. If increasing the size of the CICS internal trace table does not resolve the wrapping issues for this CICS region, review the additional optimization and troubleshooting methods in Configuring for optimum performance.

Step 9: Browse the transaction list

To analyze the results of collection, use the ISPF dialog.

1. On the C\Prof primary option menu, select option 1 Regions.

2. To view profiling data from a CICS region, enter line action S.

   

   Viewing profiling data using the Region List panel

   The Transaction Selection Criteria panel is displayed.

3. Enter 1 to specify a Relative date, and a time range that reaches back far enough to include those transactions you collected in Step 8: Record transaction data. For example, if 10 minutes have passed since you started the recording, select 15 Minutes ago to Now.

   

   The Transaction Selection Criteria panel

4. Press Enter to see a list of transactions captured by C\Prof.

The Transaction List panel (ISPF)

Note: If you can t see any transactions, use the following methods to verify your setup:

1. Check the status of the CICS internal trace. If you collect from a CICS region where the CICS internal trace is in the STOPPED state, only exception events will be captured. You can review the required settings in Step 1: Start and configure the CICS internal trace in Step 1: Start and configure the CICS internal trace.
2. Review the C\Prof collection server SYSPRINT output data set. Check that new data sets are being allocated. Try running a transaction in the CICS region to stimulate the creation of an archive data set. Check for other warnings or errors. More information on messages issued by C\Prof can be found in Messages and codes.
3. Relax the filtering criteria on the Transaction Selection Criteria panel. Select more transactions by specifying a longer relative time. More information can be found in Applying a filter to the transaction list (FILTER command).
4. The ISPF dialog uses the checkpoint data set in your configuration file to retrieve archived transaction data. Check that you have used the same configuration file as your collector. You can specify a different configuration file at any time by overtyping the name in the Configuration field. Be sure to surround your data set name with single quotes (') when specifying a fully qualified data set name.

Step 10: Install the C\Prof Web UI (web server and application

The C\Prof Web UI is a web-browser based interface that supplements the transaction analysis capabilities of the C\Prof ISPF dialog. The C\Prof Web UI is installed as a web application bundled with its own copy of the Apache Tomcat application server into the z/OS UNIX environment on your mainframe. For more information on the functions of the C\Prof Web UI, see C\Prof Web UI.

To use the C\Prof Web UI, you must be running a C\Prof collection server.

Before you begin

Before you install the C\Prof Web UI, read the following important information:

1. As some installation files require extended attributes (program control), the installation must be performed by a z/OS UNIX administrator or a systems programmer with READ access to the BPX.FILEATTR.PROGCTL resource in the SAF FACILITY class.

2. To run the bundled Apache Tomcat application server, you must have READ access to the BPX.SERVER resource in the SAF FACILITY class.

3. The application server can be configured to use either unsecured connections with HTTP, or secured connections using HTTPS. HTTPS is highly recommended to ensure secure transmission of z/OS user IDs, passwords, and collected transaction data over your network. At a minimum, consider using HTTPS in production environments.

   To use HTTPS, you must first create a keyring and connect to it a digital certificate. For more information, see Generating a keyring and certificate for secure connections.

   If you are unsure which method to use, consider using HTTP on a demonstration or test system before reapplying this procedure for HTTPS.

Procedure

To install the C\Prof Web UI, complete the following steps:

1. Return to the C\Prof primary option menu (PF3) and select option 5 Configure.

2. On the Configure the server panel, select option 7 Install the web server and application.

3. In the C\Prof installation directory (CPROF_HOME) field, enter an installation location for C\Prof Web UI (web server and application). For example, /u/cprof/.

4. In the Java JDK directory field, enter the path name of your Java 1.8 ("Java 8") installation (JAVA_HOME) in z\OS UNIX. The C\Prof Web UI requires the 64-bit version of Java 8 which is typically installed on your mainframe in /usr/lpp/java/J8.0_64/.

5. The C\Prof Web UI can be served using either HTTP (without security) or HTTPS (secure). These options are described below:

   • Configuring using HTTP

     HTTP provides unsecured access to the C\Prof web server. If you wish to use HTTP, you only need to enter the TCP/IP port number that you wish to use to serve the C\Prof Web UI. To do this, use the Port number field in the HTTP settings section. Be sure to select a port on your system that is not being used by another application.

     Note: In this configuration, z/OS user IDs and passwords will be transmitted across your network in plain text. To establish secure communication, use HTTPS (see below).

   • Configuring using HTTPS (recommended)

     To use HTTPS to establish secure communication with the web server, enter the TCP/IP port number in the Port number field and the name of your SAF keyring with its associated user ID in the Keyring field of the HTTPS settings section. This user ID will also be the user account being used to run Apache Tomcat.

     For example, for user USR1 with a keyring named CProfKeyring.TXCSRVR, enter USR1/CProfKeyring.TXCSRVR.

     Note: If you have not yet created a keyring for the Apache Tomcat user, see Generating a keyring and certificate for secure connections.

     

     The Web UI installation panel - HTTPS setup

6. Press enter to generate JCL to install the C\Prof Web UI.

7. Review and then submit the generated JCL. The batch job will perform the following actions:

   1. Extract the C\Prof Web UI assets from its PAX archive file located in your C\Prof installation data set into your z\OS UNIX environment. This includes libraries for the application server as well as the C\Prof Web UI web application.

   2. Update your application server's server.xml file (an ASCII file located in the conf directory of your installation), used to configure your server with the options you selected in Steps 4 and 5. For more information on the structure of this file, see the Apache Tomcat Configuration Reference.

8. Review the job SYSOUT output data set for error messages. If the job completed successfully (return code 0), proceed to the next step.

   Created directory /u/cprof                                  
   Extracting PAX archive                                        
   Running install.sh  --https-port 12345 --keyring USR1/CProfKeyring.TXCSRVR
   bin/install.sh                                                
   Installation complete
   

   Example SYSOUT output data set for successful HTTPS web server installation

   If the job did not complete successfully, review any error messages, make changes and try again. Authorization errors may indicate that you have insufficient authority to define programs in UNIX files to program control. Contact your systems programmer or security administrator for assistance.

9. Return to the Configure the server panel and select option 8 Generate JCL to run the web server.

10. Enter the following information:

    • The installation location you specified in step 3 in the C\Prof installation directory field
    • The location of Java you specified in step 4 in the Java JDK directory field.

11. Press enter to generate JCL to run the web server.

12. Review and submit the generated JCL.

    Note: The C\Prof Web UI communicates with the C\Prof collection server using the configuration file specified in the TXCCONF DD statement. If you wish to connect to a different collection server, simply change the file name as desired.

13. Review the STDERR output data set to verify that the server has started. For example:

    29-Mar-2018 09:38:50.975 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 4500 ms
    

    If the job did not complete successfully, review any error messages, make changes, and try again.

14. Open a web browser to start using the C\Prof Web UI. For more information, see Logging on.

For more information on operating and configuring the server, see Web UI application server.

Step 11: Register the product

Note: C\Prof can be used without registering the product during the evaluation period. If you have purchased the product and received a product key, complete the following steps to register the product. If you have purchased the product but you do not yet have a product key, please contact Rocket Software product support.

To register your product, use the Configure the server panel.

1. Return to the C\Prof primary option menu (PF3) and select option 5 Configure.

2. On the Configure the server panel, select option 9 Activate C\PROF using the registration key.

3. Enter your product key into the space provided. Overwrite the text PLEASE PASTE THE KEY IN HERE.

   For example:

   TXCKEY CSECT , .C\PROF PRODUCT KEY
   TXCKEY AMODE 31
   TXCKEY RMODE ANY
   *
   *         *----+----1----+----2----+----3--*
   &KEY SETC '19B395020BD365912231EDB19929CD37'
   *         *----+----1----+----2----+----3--*
   *
   &CHECK SETC X2C('&KEY') .CHECK FOR VALID HEXADECIMAL DIGITS
   DC CL32'&KEY' .THE ACTUAL KEY VALUE
   *
   END TXCKEY
   

   Pasting your product key into the registration JCL (sample only)

4. Submit the generated JCL.

What to do next?

Now that you have completed your C\Prof setup, continue reading from one of the following subjects to learn more about the product:

Enterprise-wide data collection and analysis

Learn how to use C\Prof for data collection and analysis across your organization. In this section, you will learn more about the transaction profiler, how to view application events, and how to deep dive into the trace events themselves. You will learn how to record to auxiliary trace data sets and to take a back-in time snapshot, and how to import auxiliary trace data sets into the C\Prof transaction profiler. Finally, you will learn how to set up an automatic problem capture system using snapshot, and how to expand C\Prof collection to CICS regions in other LPARs.

Working with auxiliary trace data sets

If you are working primarily with auxiliary trace data sets, you can use the C\Prof trace viewer to browse formatted trace entries, or to import them into the C\Prof transaction profiler. If you have an auxiliary trace data set produced by the CICS auxiliary trace facility, you can use C\Prof to conduct advanced analysis.

Ad hoc batch data collection

Users who prefer to submit ad hoc batch data collection requests can generate JCL using the C\Prof ISPF dialog. With the dialog, you can generate JCL for transaction profiling, recording to auxiliary trace data sets, snapshot, and for importing auxiliary trace data sets into the C\Prof transaction profiler. If you have a CICS dump, you can also generate JCL to invoke IPCS with a C\Prof VERBEXIT that converts the dump into an auxiliary trace data set. Once you have your auxiliary trace data set, you can use the C\Prof trace viewer to view the trace entries, or you can import the auxiliary trace data set into the transaction profiler.

Use the C\Prof Web UI

Explore the enhanced analysis capabilities of the C\Prof Web UI. For more information, see C\Prof Web UI.