Control-O Utilities

This chapter provides a detailed description of the Control-O utilities.

CTOALOCP – Backing Up the Automation Log

The CTOALOCP utility copies the contents of one Automation Log file to another Automation Log file or to a sequential data set. The utility can be used to perform any of the following functions, depending on the parameters specified:

• Backing up the Automation Log to another Automation Log. Automation Log backup files can be displayed, just like the current Automation Log file, using the Automation Log screen (option OL).

• Increasing the size of the current Automation Log file.

• Copying the Automation Log to a sequential file. The sequential file can be processed by a report generator utility or restored and displayed later as an Automation Log file.

• Restoring a sequential backup file to the format of an Automation Log file.

• Changing the data set organization of an Automation Log.

Parameters are passed to the CTOALOCP utility using the DALCPPRM DD statement.

The following parameters can be specified:

Table 310 CTOALOCP Parameters

Examples for CTOALOCP

TODSN     SYS3.MYLOG
TOVOLUME  WORK02
TOUNIT     DISK

TODSN     SYS3.MYLOG
TOVOLUME  WORK02
TOUNIT    DISK
TORECNUM  100000

TODSN     SYS3.MYLOG
TOVOLUME  WORK02
TOUNIT    DISK
TORECNUM  100000

STARTDATE 001027
STARTTIME 150000
ENDDATE   001027
ENDTIME   200000
TODSN     SYS3.MYLOG.D2710.F15T20
TOVOLUME  WORK02
TOUNIT    DISK
TORECNUM  MINIMAL

STARTDATE 001020
ENDDATE   001021
TODSN     SYS6.MYLOG.F20T21
TOTYPE    S
TOVOLUME  WORK02
TOUNIT    DISK
TORECNUM  MINIMAL

CTOCSF – Copy the Message Statistics File

The CTOCSF utility copies the Message Statistics file. The utility is generally used to create a new Message Statistics file whose size is better adapted to the site’s needs.

Begin

Before copying the file, the following steps must be followed:

1. If the Control-O monitor is active, stop the Control-O statistics collection task using the command

   Copy

   F CONTROLO,STOPSTAT

   Message CTO189I indicates that statistics accumulation has stopped.

2. Verify that no users have allocated the Message Statistics file using Control-O screen OM.

3. Rename the current Message Statistics file (input file for the copy operation), for example, using ISPF 3.2 or 3.4.

4. Perform the following steps:

   1. Enter ICE and select Customization.

   2. In the Customization screen, set Product ID to CTO.

   3. Select major step "Customize Control-O Dataset Parameters."

   4. Select minor step "Control-O Dataset Parameters."

   5. Change parameter STREC# from (for example) 10000 records to 20000 records to change the size of the new Message Statistics file.

   6. Select minor step "Save Parameters Into Product Libraries."

   7. Select minor step "Allocate and Format CTO Statistics Files."

   8. Create and format a target statistics file using the CTOFRSTF program.

   9. Submit the job and create a new Statistics file.

5. Edit member CTOCSFJ in the Control-OJCL library. Change DD statement DASTF DSN to match the name specified in Step 3.

Example for CTOCSF

//COPYST JOB
//COPYFILE EXEC CTOCSF
//DASTF DD DISP=SHR,DSN=old-dsname
//

F CONTROLO,STARTSTAT

CTOCTA – List Programs Running in an Address Space

The CTOCTA utility enables you to determine which programs are running in a specific address space. This utility is used primarily for gathering information to be included in the input file of the CTOCTI utility, described in CTOCTI Input File.

Activating the CTOCTA Utility

Use the following JCL to activate the utility (sample job is located in the Control-O JCL library):

// I600INCT JOB ,IOA600,MSGCLASS=X,CLASS=A
// JCLLIB  ORDER=IOAP.V600.PROCLIB
// INCLUDE MEMBER=IOASET
// DISPGMNM EXEC PGM=CTOCTA,PARM=ASNAME
//

CTOCTA Parameter

The following parameter must be specified in the EXEC statement that invokes the CTOCTA JCL procedure:

Table 311 CTOCTA Parameter

CTOCTA Return Codes

Table 312 CTOCTA Return Codes

Example for CTOCTA

CTO660I ADDRESS SPACE M70TEST  WILL BE PROCESSED NOW
CTO666I PROGRAM IEAVAR00 FOUND IN THE RB CHAIN
CTO666I PROGRAM IEESB605 FOUND IN THE RB CHAIN
CTO666I PROGRAM IEFSD060 FOUND IN THE RB CHAIN
CTO666I PROGRAM IEFIIC   FOUND IN THE RB CHAIN
CTO666I PROGRAM TESTPGM  FOUND IN THE RB CHAIN
CTO666I PROGRAM IEAVTSDT FOUND IN THE RB CHAIN
CTO664I ADDRESS SPACE M70TEST  ACTIVE

CTOCTI – Generate Input for the SYSIMAGE Facility

SYSIMAGE is a facility used by the Control-O Status Monitoring System (COSMOS) to automatically generate an Object database that reflects your current environment. The CTOCTI utility is part of the SYSIMAGE facility to accumulate the information necessary for creation of the Object database.

A sample input file (CTOOBJFL) is supplied with information about the objects in a typical environment. Edit this file to reflect your environment and the objects you want COSMOS to manage. The input file is described in detail below.

For more information about COSMOS, see the Control-O/COSMOS z/OS User Guide.

Activating the CTOCTI Utility

Use the following JCL to activate the utility (sample job is located in the Control-O JCL library):

// I600INCT JOB ,IOA600,MSGCLASS=X,CLASS=A
// JCLLIB  ORDER=IOAP.V600.PROCLIB
// INCLUDE MEMBER=IOASET
// BLDCOSDB EXEC PGM=CTOCTI
// OBJFILE   DD  DISP=SHR,DSN=&OLPREFO..PARM(CTOOBJFL)
//

where OLPREFO is the prefix name of the Control-O PARM library and is usually resolved automatically from IOASET.

CTOCTI Input File

Object names and program names used as input for the utility are specified in sample input file CTOOBJFL located in the Control-O PARM library.

CTOCTI Sample segment of the input file

*OBJECT_DETAIL__OBJECT CLASS____AS_NAME_PGMNAME_X 
 ELD                                     ETILOADR
 PDS MANAGER                             PDSMOPR
 TEST PDS MANAGER                PDSMANT PDSMOPR X
 BB CSA MONITOR                          PMGCSWRN
 RESOLVE                                 ASTXA1MN
 ENDEAVOR                                LDMMAIN
 CONTROL-D                               CTDMON
 TSO                                     IKTCAS00
 PCAUTH                          PCAUTH  IEAVXMASX
 RASP                            RASP    IARDINITX
 TRACE                           TRACE   IEAVETAIX
 XCFAS                           XCFAS   IXCINJSTX
 GRS                             GRS     ISGNASIMX

CTOCTI Format of the Input File

Table 313 CTOCTI Formats

Modifying the Input File (CTOCTI)

Before running the CTOCTI utility, you should modify the input file in the following ways:

• Exclude system resources from the utility output by placing an ‘X’ in column 49 of the rows describing the resource objects.

• Add rows for objects (started tasks) not listed in the input file. At least an object name and program name must be specified for each new row.

• Modify object and/or class names to conform to your site standards.

If a started task that is running in the system is not listed in the input file, it is listed in the output of the utility. Instead of a specific object name and description, **UNDEF_OBJECT** is returned.

The program name associated with a specific address space can be determined using the CTOCTA utility, as described on CTOCTA – List Programs Running in an Address Space.

CTOCTI Return Codes

Table 314 CTOCTI Return Codes

CTOCTI Utility Output

The output of the CTOCTI utility is a series of messages describing objects (resources) at your site. These messages are used to trigger the SYSIMAGE facility and generate an Object database to be used by COSMOS.

The following is a sample output for this utility:

Figure 117 CTOCTI Sample Output

CTO657I OBJECT_NAME/DESC | CLASS_NAME/DESCR | ADDRSPAC | STATUS__ J  CTO658I
-------------------------|------------------|----------|----------------------
CTO659I ELD                 N/A                      N/A                  INACTIVE   
CTO659I PDS MANAGER         N/A                      PDSMAN               ACTIVE     
CTO659I TEST PDS MANAGER    N/A                      PDSMANT              INACTIVE   
CTO659I BB CSA MONITOR      N/A                      N/A                  INACTIVE   
CTO659I RESOLVE             N/A                      RESOLVE              ACTIVE     
CTO659I ENDEAVOR            N/A                      N/A                  INACTIVE   
CTO659I CONTROL-D           N/A                      GADTROLD             ACTIVE     
IOSAS                       N/A                      IOSAS                EXCLUDED   
CATALOG                     N/A                      CATALOG              EXCLUDED   
THIS JOB                    N/A 
 M19XB4CT             ACTIVE
**UNDEF OBJECT**            *UNDEFINEDCLASS*         GRS                  ACTIVE

Certain messages return an object name of **UNDEF_OBJECT**. These messages describe started tasks that were active in the environment, but were not listed in the input file for the utility. The SYSIMAGE facility creates objects for undefined address spaces. However, such objects are not assigned values in the DETAIL and CLASS columns of the Object database.

To ensure that no started tasks are omitted from the Object database created from the utility output:

Begin

1. Run the CTOCTI utility (not using the SYSIMAGE facility while the rule CTO659I of Control-O/COSMOS is not loaded or held).

2. Check the messages generated by the utility for undefined objects.

3. Edit the input file for the CTOCTI utility as follows:

   1. Add rows for the missing started tasks.

   2. Specify an appropriate object name for each started task.

   3. Determine the program name for each started task (using the CTOCTA utility) and specify it in the input file.

4. When all started tasks have been defined in the input file for the CTOCTI utility, rerun this utility using the SYSIMAGE facility.

   The SYSIMAGE facility uses the utility output to create an Object database that includes all started tasks not excluded using the input file to the utility.

CTORSTM – Statistics Report Utility

The CTORSTM utility generates statistical reports based on information provided by the Message Statistics facility. CTORSTM output can be used to analyze site automation requirements and the progress of the automation process. CTORSTM output can also be used as input for report generator utilities (such as SAS, SP/SS, or EASYTRIEVE).

A sample JCL that invokes procedure CTORSTM can be found in member CTORSTMJ in the Control-O JCL library. The output report is written to SYSPRINT. Report parameters are passed to the CTORSTM utility using the DAREPIN DD statement.

CTORSTM SORT Parameter

The following parameter can be specified to sort the report data:

Table 315 CTORSTM SORT Parameter

CTORSTM INCLUDE / EXCLUDE Statements

The scope of the copy can be limited by one or more INCLUDE / EXCLUDE statements. Each INCLUDE / EXCLUDE statement contains parameters that limit the messages for that statistics are collected.

CTORSTM Parameters in INCLUDE / EXCLUDE Statements

The parameters that can be specified in INCLUDE / EXCLUDE statements:

Table 316 CTORSTM INCLUDE / EXCLUDE Parameter

Example for CTORSTM

//REPORT EXEC CTORSTM
//DAREPIN DD *
INCLUDE DFH*
INCLUDE $HASP*
EXCLUDE $HASP100
SORTBY MSGID
/*

1---------------------------------- ----------------------------------------------------
 CONTROL-O STATISTIC REPORT- INVOCATION PARAMETERS         - LAST RESET ON 00/07/12 13:57:41            PAGE          1
 PRODUCED BY CONTROL-O VERSION 6.3.01                      - REPORT TIME - 00/08/10 11:50:3             SYSTEM ID  OS35
 ---------------------------------- ----------------------------------------------------
 INCLUDE $DFH*                                                            00130000
 INCLUDE $HASP*                                                           00130000
 EXCLUDE $HASP100                                                         00130000
SORTBY COUNT                00140000
--------------------------------- ------------------------------------------------------
CONTROL-O STATISTIC REPORT- SORTED BY COUNT              - LAST RESET ON 00/07/12 13:57:41              PAGE          2
PRODUCED BY CONTROL-O VERSION 6.3.01                     - REPORT TIME - 00/08/10 11:50:31              SYSTEM ID  OS35
--------------------------------- ------------------------------------------------------
MESSAGE ID   T COUNT      HANDLED    SUPRESSED  MESSAGE  EXT
------------ - ---------- ---------- ---------- -------- -------------------------------
$HASP373     M      45289      45289          0 $HASP373 M54T     STARTED - INIT 2    - CLASS A - SYS OS35
$HASP395     M      44650      44650          0 $HASP395 M26A     ENDED
$HASP250     M      40644      40644          0 $HASP250 M04TTXLM PURGED -- (JOB KEY WAS B402CAE1)
$HASP309     M      17522      17522          0 $HASP309 INIT 2    INACTIVE ******** C=A
$HASP890     M       9734       9734          0 $HASP890 JOB(M04TTXLM)
$HASP686     M       9181       9181          0 $HASP686 OUTPUT(N61SRULE)  OUTGRP=1.1.1 CANCELLED
$HASP375     M       7990       7990          0 $HASP375 N16PRPS  ESTIMATED  LINES EXCEEDED
$HASP006     M       3758       3758          0 $HASP006 $CJ2201,P     TRANSLATED BY EXIT HASX05C TO  $CJ(2201),P
$HASP125     M       2698       2698          0 $HASP125 INTRDR     SKIPPING FOR JOB CARD FROM TSU15147 K06
$HASP301     M        633        633          0 $HASP301 N16PRPS  - DUPLICATE JOB NAME - JOB DELAYED
$HASP880     M        475        475          0 $HASP880 LINE1       UNIT=SNA,STATUS=ACTIVE/NODE6,DISCON=NO
$HASP003     M        471        471          0 $HASP003 RC=(52),
$HASP263     M        455        455          0 $HASP263 WAITING FOR ACCESS TO JES2 CHECKPOINT VOLUME NDS8H2
$HASP679     M        441        441          0 $HASP679 $SN,A=JES06    REJECTED - ALREADY IN SESSION WITH JES06, RC=08
$HASP881     M        235        235          0 $HASP881 LOGON1
APPLID=JES07,STATUS=ACTIVE

CTORSTM Fields of the Report

Report information is displayed according to the following fields:

Table 317 CTORSTM Fields

CTOMVDSC – Emergency ON MVALERT Disconnect

The CTOMVDSC utility forces a disconnect of ON MVALERT support in emergency situations. It functions in much the same way as the following command:

F CONTROLO,STOPMVI,FORCE

WARNING: Use this utility only in appropriate emergencies. Do not use unless specifically advised by BMC Customer Support.

The utility can be activated using the CTOMVDSC job, which is located in the IOAprefix.INSTWORK library. The CTOMVDSC utility procedure is located in the IOAprefix.PROCLIB library.

Activating the CTOMVDSC Utility

You can activate the CTOMVDSC utility

• as a JCL job statement, for example

  Copy

  //DISCONCT EXEC CTOMVDSC

• as an emergency MVS started task command, entered from the console, for example

  Copy

  S CTOMVDSC

CTOMVDSC Return Codes

Table 318 CTOMVDSC Return Codes

CTOOEDSC – Emergency USS Support Disconnect

The CTOOEDSC utility forces a disconnect of USS support in emergency situations. It functions in much the same way as the following command:

F CONTROLO,STOPUSS,FORCE

WARNING: Use this utility only in appropriate emergencies. Do not use unless specifically advised by BMC Customer Support.

The utility can be activated using the CTOOEDSC job, which is located in the IOAprefix.INSTWORK library. The CTOOEDSC utility procedure is located in the IOAprefix.PROCLIB library.

Activating the CTOOEDSC Utility

You can activate the CTOOEDSC utility

• as a JCL job statement, for example

  Copy

  //DISCONCT EXEC CTOOEDSC

• as an emergency MVS started task command, entered from the console, for example

  Copy

  S CTOOEDSC

CTOOEDSC Return Codes

Table 319 CTOOEDSC Return Codes

CTOSMDSC – Emergency ON SMS Disconnect

The CTOSMDSC utility forces a disconnect of ON SMS support in emergency situations. It functions in much the same way as the following command:

F CONTROLO,STOPSMS,FORCE

WARNING: Use this utility only in appropriate emergencies. Do not use unless specifically advised by BMC Customer Support.

The utility can be activated using the CTOSMDSC job, which is located in the IOAprefix.INSTWORK library. The CTOSMDSC utility procedure is located in the IOAprefix.PROCLIB library.

Activating the CTOSMDSC Utility

You can activate the CTOSMDSC utility

• as a JCL job statement, for example

  Copy

  //DISCONCT EXEC CTOSMDSC

• as an emergency MVS started task command, entered from the console, for example

  Copy

  S CTOSMDSC

CTOSMDSC Return Codes

Table 320 CTOSMDSC Return Codes

CTOTEST – Simulate Messages and/or Commands

The CTOTEST utility simulates messages and commands used to trigger Control-O rules. The messages or commands are specified in a data set used as input for the utility. When the utility is run, Control-O responds to the specified messages as if they had been issued in the usual manner.

This utility can be used to

• Check the performance of a rule or group of rules.

• Check if an existing rule handles a specific message or command.

• Check Control-O response to a series of commands and/or messages.

The CTOTEST utility is run on each record in the input file. A pair of messages is generated for each run of the utility. The first message describes the record being processed. The second message describes the Control-O response to the input record. A return code (described below) is supplied as part of the second message.

Activating the CTOTEST Utility

// CTOSIM EXEC PGM=CTOTEST,PARM=N500
// INCLUDE MEMBER=ioaenv
// CMDMSGFL DD DSN=dsname,DISP=SHR

CTOTEST Parameters

The following parameter must be specified in the EXEC statement that invokes the CTOTEST procedure:

Table 321 CTOTEST EXEC Parameter

The following parameter must be specified in DD statement CMDMSGFL:

Table 322 CTOTEST CMDMSGFL Parameter

Format of the CTOTEST Input File

The input file for the CTOTEST utility has the following characteristics:

• Physical sequential

• Record length: 127

• Record format: Fixed or Fixed block

Records in the input file have the following format:

nyyyyyyyyyyyy

where

• n – Single digit indicating the type of message or command to be simulated. Valid values are:

  • 1 – MVS or JES2 message

  • 2 – IMS

  • 3 – JES3 command

  • 4 – JES3 message

  • 5 – JES2 command

• yyyyyyyyyyy… – Text of the message or command to be simulated. Maximum length: 126 characters. Comment lines (indicated by an asterisk in column one) can also be included in the input data set.

CTOTEST Return Codes

The following return codes may be returned by each run of the CTOTEST utility. If an internal error is detected while processing an input record, that record is ignored and processing continues with the next record of the input data set.

Table 323 CTOTEST Return Codes

Example for CTOTEST

// CTOSIM   EXEC PGM=CTOTEST,PARM=N500
// CMDMSGFL  DD  *

5$D MODULE(HASPCOMM)
1IEC301A S JOB T56E DSNAME
1IEF403I M70TT123 STARTED

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
CTO500I INPUT LEN=019 REC=$D MODULE(HASPCOMM)
CTO503I RC000 LEN=000 REC=
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
CTO500I INPUT LEN=025 REC=IEC301A S JOB T56E DSNAME
CTO503I RC000 LEN=000 REC=
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
CTO500I INPUT LEN=024 REC=IEF403I M70TT123 STARTED
CTO503I RC000 LEN=000 REC=
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=