IOA Administration

• Overview

• IOA Online Environment

• Customizing the IOA Online Environment

• IOA Access Method

• IOA Profiles

• Modifying INCONTROL Product Defaults

• Modifying IOA Messages

• Message Destination Tables

• General IP parameters

• IOAMAIL

• IOA support for DO REMEDY

• IOAAPI

• IOA Variable Database Facility

• Expanding Various IOA Files

• CMEM-related maintenance

• IOA Log Index

• Problem Determination

Overview

This chapter describes the customization facilities available within IOA, including:

• IOA Online Environment

• Destination Tables

• Expanding IOA Files

• Problem Determination

• TSO/ISPF

IOA Online Environment

The Online facility can be activated under, and supply services to, the following environments:

• TSO (native)

• VTAM

• TSO/ISPF

• IMS/DC

• ROSCOE/ETSO

• IDMS/DC

• CICS

• COM-PLETE

Options for cross‑memory interfaces to the Online monitor address space are available under native TSO and ROSCOE/ETSO.

There are slight differences in the operation of the Online facility under different environments.

The following topics describe how the IOA Online monitor facility provides support for various environments using CICS as a model scenario. The description also applies to the following environments:

• IMS/DC

• VTAM

• COMPLETE

• IDMS/DC

• ROSCOE CrossMemory Interface

• TSO CrossMemory Interface

Entering the IOA Online Facility

In TSO and ISPF, the IOA Online facility is entered by running a CLIST (located in the IOA CLIST library). The CLIST calls IOAONL, which is the main CLIST that activates the Online facility in the specified environment.

The following CLISTs are provided for activating the IOA Online facility in the indicated environment:

Table 8 CLISTs for Activating the IOA Online Facility

The CLIST format used to activate the IOA Online environment under ISPF or TSO is:

IOAONL APPLTYPE(atype) [TRANID(transmem)]

• atype is the type of environment under which IOA is run. Valid values are I (ISPF), S (TSO) and X (Online monitor).

• transmem is the name of the relevant transaction member in the IOA PARM library. Maximum length: four characters. Optional.

If no transaction member is specified, a full list of all options for the installed products is displayed.

For more information see Transaction Members.

%IOAONL  APPLTYPES

Dataset allocation for the IOA Online environment can be customized using specification of overriding or alternative Allocation members in the CLIST used to activate the IOA Online environment. For more information, see Allocation Members.

%IOAONL APPLTYPE(I)  TRANID(DOLV)

IOA Online Monitor

The IOA Online monitor interacts with different environments (for example, CICS) to provide an online interface for the various IOA applications. The IOA Online monitor generates the INCONTROL product screens, which are available to users signed on to the monitor, and handles all IOA online functions.

Each IOA Online monitor usually operates 24 hours a day as a started task. The IOA Online monitor is usually activated automatically as part of the IPL process.

Principles of Operation

To enable the same user interface to be activated by users under different environments, a virtual environment is built for each user. This virtual environment handles all actions a user requests to perform in the IOA environment. Therefore, any environment being used at a site can be supported by adding a customized routine to convert the virtual environment to the site’s environment.

A special started task, named the IOA Online monitor (IOAOMON), provides an environment for executing IOA applications. One or more IOA Online monitors can be started and each monitor can support several virtual environments (signed‑on users).

Each monitor can customize INCONTROL product screens, constants, messages, colors, commands and PFKey definitions to adapt them to the site’s requirements. It is recommended that the same prefix be used for each group of monitors that are customized for specific functions. For more information, see the description of member IOAXPRM in the INCONTROL for z/OS Installation Guide: Installing.

In addition to site‑wide Global profile customization, each INCONTROL product can be customized to respond differently to individual users signed on to the IOA Online monitor through variables specified in User profiles.

In the CICS environment, a small conversational transaction communicates with the IOA Online monitor using cross‑memory services. The CICS transaction receives a screen from the user terminal and passes the screen to the IOA Online monitor for processing. The IOA Online monitor returns a screen (to be displayed) to the CICS transaction that in turn sends this screen to the CICS user at the terminal. Using this method, the IOA application is performed outside CICS and the normal CICS function is uninterrupted. The memory requirement of each user in the CICS region is approximately the size of the screen (that is, 2x24x80=3840 bytes).

The IOA Online monitor activates each user as a subtask. Therefore, in the event of an error or abend of a user application, other users working under the IOA Online monitor are not affected.

IOA applications work above and below the 16MB line. Therefore, region size limits may restrict the number of users who can work concurrently under the same online monitor. However, it is possible to open any number of additional IOA Online monitors. Each online monitor must have a different name. The general naming convention that is supplied is

IOAOMONx

x can be any valid job name character, a different one for each online monitor.

When a user enters the IOA CICS transaction code, the IOA CICS application searches for a free space in one of the currently active IOA Online monitors. The process of choosing a monitor is transparent to the CICS user. Using this method, there is no limitation on the number of users signing on to IOA.

It is possible to balance the workload of two or more IOA Online monitors. For more information see the BALANCE parameter in the IOA installation chapter of the INCONTROL for z/OS Installation Guide: Installing.

The actual number of users under one monitor varies according to their memory requirements (influenced by how many screens they use concurrently, what type of IOA options they are using, and so on). Many options exist in the IOA Primary Option menu. However, there is no reason for every user to access all options of each product. It may be desirable to limit access to certain options to only a selected group of users. This is done by passing a transaction code to the Online monitor. For more information, see Transaction Members. It is also possible to determine that certain monitors allow users to sign on only with specific transactions thus enabling monitors to be specialized for different groups and numbers of users.

The Control‑D Online Viewing facility runs mostly above the 16MB line. Therefore, it is possible to activate about 70 Online Viewing users under one monitor. However, these users are limited to Online Viewing transactions only. This can be done by forcing users to sign on with the transaction ID DOLV.

A data center can run more than one CICS in the same computer. From the IOA point of view, this is transparent to the user. The IOA Online monitor always returns the screen to the CICS that issued the request. It is possible to define additional transaction IDs for local use (for example, a transaction ID offering all options of the menu except for the IOA Conditions/Resources screen). For more information, see Customizing the IOA Online Environment.

Activating the IOA Online Monitor (IOAOMON)

Each IOA Online monitor usually operates 24 hours a day as a started task. Usually the IOA Online monitor is automatically activated as part of the IPL process by the following operator command:

IOAOMONx

where x is the monitor ID.

The names of the online monitors available in a site are defined in member IOAXPRM in the IOA PARM library. For details, see Customizing the IOA Online Environment.

If the IOA Online monitor is successfully activated, the following message is displayed on the operator console:

CTM777I monitor‑name ONLINE MONITOR INITIALIZATION STARTED

After a few seconds the following message is displayed:

CTM778I monitor‑name ONLINE MONITOR INITIALIZATION COMPLETED

If you try to activate more than one IOA Online monitor with the same monitor ID in the same computer, the newly‑activated monitor immediately shuts down and a relevant message is issued.

The IOA Online monitor uses cross‑memory services to communicate with other address spaces requesting services. Like other address spaces using cross‑memory services, whenever the IOA Online monitor is shut down, the address space entry in the MVS Address Space Vector Table (ASVT) remains non‑reusable until the next IPL, and the message IEF352I is issued (in some MVS versions). If the IOA Online monitor is brought up and down many times, the ASVT may become full. New address spaces do not start, and an immediate IPL may be required.

To prevent this problem, specify a large enough value in MVS initialization parameters MAXUSER, RSVSTRT and RSVNONR in member IEASYSXX in the SYS1.PARMLIB library.

For information about these parameters, see the MVS Initialization and Tuning Reference Manual.

Controlling the Online Monitors

The IOA Online monitor supplies online services to many users. Therefore, it is necessary to control "what is happening inside" each monitor. The following sections describe a series of operator commands that enable such control.

Displaying a List of All Active Users

Enter operator command:

F IOAOMONx,DISPLAY.

where x is the monitor ID.

The following list is displayed on the operator console from which the modify command was issued:

CTM645I  MONITOR USER PGM TRANID TERMINAL START
LASTUSED ST
CTM646I  monitor user pgm tranid terminal start last status

Message CTM646I is displayed for every user in the IOA Online monitor, and contains the following data for each user:

Table 9 Data in Message CTM646I

Displaying a List of All Active Datasets and DD Statements

To display a list of all active datasets and DD statements, specify the following operator command:

F monitor_name,LISTDD

The following information is displayed on the operator console from which the modify command was issued:

Table 10 Information Displayed on Operator Console

Displaying a Detailed Storage Map

To display a detailed storage map by TCB storage key and subpool, specify the following operator command:

F monitor_name,LISTVDET

Every allocated block is listed by TCB and subpool number. The following information is displayed on the operator console from which the modify command was issued:

Table 11 Detailed Storage Map Information

Displaying a Summary Storage Map

To display a summary storage map, specify the following operator command:

F monitor_name,LISTVSUM

Totals for all allocated blocks are listed.

Canceling an IOA Online Monitor User

To cancel a specific user who is currently active under the IOA Online monitor, enter operator command:

F IOAOMONx,CANCEL USER=userid

where x is the monitor ID.

As a result, the user application is terminated and the following message is displayed on the operator console from which the modify command was issued:

CTM795I  monitor-name USER userid CANCELED

Deactivating the IOA Online Monitor

To deactivate the IOA Online monitor, use operator command:

P IOAOMONx

where x is the monitor ID.

Using the zIIP processor by the IOA Online Monitor

The ZIIPXBMO parameter is provided in the IOAPARM member for offloading IOA Online Monitor I/O workloads to zIIP with XBM (Extended Buffer Manager). The default is N, that the I/O workloads are not offloaded to zIIP with XBM.

The XBM modify command allows the IOA Online Monitor to activate the offloading of eligible I/O workloads from general purpose processors to zIIP processors with XBM. This way XBM address space can be started after INCONTROL address spaces, without requiring the INCONTROL address spaces to be restarted.

For the IOA Online Monitor, the XBM modify operator command syntax is as follows:

F IOAOMONx,XBM

where x is the monitor ID.

Problem Determination

Control‑O is supplied with internal debugging (trace) facilities that provide the ability to print an internal debugging trace and to print the contents of Control‑O internal data areas. Under normal circumstances, the trace facilities are dormant. However, if required (that is, if BMC Customer Support has requested debugging information), you can activate the trace facilities by performing the following steps:

Do one of the following:

1. Start a new Control O monitor with the following operator command:

   The ControlO monitor passes control to the new ControlO monitor and shuts down.

   Copy

   S CONTROLO,TRACE=level

2. Issue the following operator command:

   Copy

   F CONTROLO,TRACE=level

   The required trace level is supplied by BMC Customer Support. It can be any value from 000 to 255 (000 specifies no debugging).

   You should not regularly activate ControlO with the TRACE parameter, because a JES problem may cause ControlO to become suspended while waiting for JES.

   Debugging information is printed to files referenced by DD statements DATRACE and DADUMP of the ControlO procedure.

3. When you finish your problem determination procedures, start a new ControlO using operator command

   Copy

   S CONTROLO

   or specify operator command

   Copy

   F CONTROLO,TRACE=00

VTAM Monitor (IOAVMON)

The VTAM monitor (IOAVMON) enables access to the IOA Online monitor for VTAM users without passing though any TP monitors (for example, CICS, IMS/DC). Only one VTAM monitor can be activated at a time.

Activating the VTAM Monitor (IOAVMON)

The VTAM monitor usually operates 24 hours a day as a started task. The monitor is usually automatically activated as part of the IPL process by operator command:

S IOAVMON

The VTAM application is active before starting the VTAM monitor. To activate the VTAM application manually, use VTAM command:

V NET,ACT,ID=ioaappl

where ioaappl is the VTAM major node containing the IOAVMON acbname.

If the VTAM monitor is successfully activated, the following message ia displayed on the operator console:

CTM7A0I monitor-name VTAM MONITOR INITIALIZATION STARTED

After a few seconds, the following messages are displayed:

CTM7A1I monitor-name VTAM MONITOR INITIALIZATION COMPLETED
CTM7ACI monitor-name ACCEPTING LOGONS TO acbname

Deactivating the VTAM Monitor

To deactivate the VTAM monitor, use operator command:

P IOAVMON

Displaying a List of All Active VTAM Users

To display the list of users logged on to IOAVMON, enter operator command:

F IOAVMON,D

The following list is displayed on the console from which the operator command was issued:

CTM7B0I monitor - TERMINAL TRANSID
CTM7B1I monitor - LUname transid

Customizing the IOA Online Environment

All INCONTROL products are accessed using the IOA Online environment. This environment can be customized to meet your site’s needs. Using the methods described in this section, you can, for example, modify menus and allocation tables, and control users’ access to the various features of the INCONTROL products installed at your site.

The members described in this section reside in the libraries pointed to by DD statement DAPARM. The standard concatenation is the IOA PARM and IOAENV libraries. The IOA PARM library can be customized to meet the site’s needs.

Transaction Members

Transaction members are line‑oriented of a transaction member. Each line contains customization information for one of the INCONTROL products installed at the site.

Transaction members can be used to determine

• which products are available to the user.

• which options of each product are available to the user.

• which program member is to be used by the transaction.

The format for each line in a transaction member is:

product [optiona, optionb,...optionx] [PGM=pgmlist]

where:

• product is the INCONTROL product described in the line. Valid values are: IOA, CTM, CTR, CTD, CTV, CTT, CTO, CTL and CTB.
  Products do not need to be listed in any specific order. Only products listed in the transaction member are made available to the user.

• optiona through optionx are the option codes of options to be displayed, or ALL. The option codes are the one or two character codes that are entered in the command line to indicate choice of a specific option. If ALL is specified, all options of the product described in the line are displayed.

• pgmlist is the name of the Program List member used to activate the INCONTROL product described in this line. For more information, see Program List Members.

Certain transaction names cannot be used for user‑defined transaction members. Reserved transaction names are: IOAX, DOLV, KOA, VK, IALL and ECS.

CTD  U

IOA ALL
CTD ALL

CTM 3
IOA 4,5

If a transaction member specifies only one option, once activated, the option is accessed directly without displaying a menu panel. If more than one option is specified, the following options are automatically added to the menu: 0, 1 (in some menus) and X. Therefore, the minimum number of options in a menu member is 4 or 5. Options 0,1, and X do not need to be specified in transaction members and is not specified in PGM members.

Program List Members

A Program list specifies a member containing a list of programs to be activated for the options of an INCONTROL product. A Program List member exists for each INCONTROL product (including IOA).

The naming convention for Program List members is PGMxxx, where xxx is the product suffix (for example, PGMCTM is the Program List member for Control‑M).

Each product has its own program list member that contains all the options of the product. Unless specified otherwise in a transaction member, the product’s program list member is used to specify which options of the product are available for users. The PGM list member is used only if the product is installed as specified in member IOAPARM in the IOA PARM library.

Program List members are line‑oriented. Each line describes a program in the relevant product.

The format for each line in a Program List member is:

program DELETE envir [=]optioncode

Table 12 Format for Program List Member Lines

Changing the option code listed in the Program List member affects only the operation of the program. To ensure that the display shows the new option code, it is necessary to update member MENU in the MSGENG library. For details, see Customizing the Menu.

Option codes for options 0, 1, and X are reserved and cannot be changed.

The following default Program List members are located in the IOAENV library:

• PGMCTB

• PGMCTD

• PGMCTL

• PGMCTM

• PGMCTT

• PGMCTO

• PGMCTR

• PGMCTV

• PGMIOA

The following is the Sample Program List member for Control‑O (member PGMCTO):

CTOTOMP DELETE * =OR 
CTOTMSC DELETE * =OM
CTOTARF DELETE * =OS
CTOTAOP DELETE * =OA
CTOTALO DELETE * =OL

An alternate Program List member can be used to specify a modified version of a specific program (or programs) to be activated for a specific options.

Alternate program lists must contain programs for all available options of the relevant product available to the user.

Allocation Members

Allocation of files and datasets for each INCONTROL product is specified in Allocation members. The naming convention for Allocation members is ALCxxx, where xxx is the product suffix. Each product has its own Allocation member that contains the allocations that need to be made to access the product using the Online facility.

Two sets of Allocation members are provided in the following IOA libraries:

Table 13 IOA Libraries Containing Sets of Allocation Members

The IOAENV and PARM libraries contain Allocation members, including

• ALCIOA

• ALCCTM

• ALCCTD

• ALCCTL

• ALCCTV

• ALCCTB

• ALCCTT

• ALCCTO

• ALCCTR

Allocation members consist of blocks of KEY parameters that function as identifiers. These KEY parameters reference DD statement entries in a DSN member (either member IOADSN in the IOAENV library or member IOADSNL in the PARM library) where the actual DD statements and corresponding information are contained.

When allocating, member IOADSNL in the PARM library is searched for the corresponding key. If the key is not located in this member, member IOADSN in the IOAENV library is searched. Therefore, localized corrections override default allocations.

Allocation specifications are contained in both Allocation members and DSN members. This facilitates the maintenance of DD statements in one location, minimizing the risks inherent to maintaining multiple occurrences of the same DD statement.

Allocation members contain conditional statements that are evaluated according to parameters in the PARM members (for example, IOAPARM, CTMPARM) in the PARM library. The datasets specified in a product's Allocation member are only allocated if its conditional statement evaluates to true.

Allocation Member Format

The format of a key in an Allocation member is:

KEY=keyname

where keyname is the name of the key that points to a DD statement entry by the same name in a DSN member (member IOADSN or IOADSNL). keyname usually matches the DD statement to which it points. Mandatory.

Conditional blocks of execution can be specified using the )SEL and )ENDSEL parameters: If no )SEL parameters are specified, the subsequent allocations (that is, KEY=parameters) apply to all products.

)SEL ppp=value
          KEY=keyname
KEY=keyname
    KEY=keyname
    .
    .
    .
)ENDSEL
*

Table 14 Fields for Conditional Blocks of Execution

Format of a Dataset Entry in a DSN Member

The format of a dataset entry in a DSN member (either IOADSN or IOADSNL) is as follows:

DATASET KEY,
        SEQ=N,
        DD=DDNAME,
        DSN=DSNAME,
        MEM=MEMBER[,]
        CATALOG=YES|NO[,]
        UNIT=unit-name[,]
        VOL=volume serial number
        RETRY=retry number

Table 15 Fields for the Format of a Dataset Entry in a DSN Member

Format of a Sysout Entry in a DSN Member

The format of a sysout entry in a DSN member (either IOADSN or IOADSNL) is:

SYSOUT  key,
        DD=ddname,
        CLASS=x,
        HOLD=YES|NO,
        FREE=CLOSE

Table 16 Fields for the Format of a SYSOUT Entry in a DSN Member

KEY=CTMHELP

DATASET CTMHELP,
        DD=CTMHELP,
        DSN=IOA.V900.MSGENG

To customize allocation at your site, specify one of the following DD statements in the CLIST (or the Online monitor procedure or the KSL) used to activate the IOA Online facility:

Table 18 DD Statements for Customizing Allocation

PROC 0 APPLTYPES ‑
        TRANID(TRANSACTION_ID_MEMBER)
ALLOC DD(DAOVRALC) ‑
        DSN('IOA.V900.PARM(ALCOVR)') SHR REU
%IOAONL APPLTYPE(&APPLTYPE) TRANID(&TRANID)
FREE DD(DAOVRALC)
END:END

PROC 0 APPLTYPES ‑
        TRANID(TRANSACTION_ID_MEMBER)
ALLOC DD(DAALTALC) ‑
       DSN('IOA.V900.PARM(ALCALT)') SHR REU
%IOAONL APPLTYPE(&APPLTYPE) TRANID(&TRANID)
FREE DD(DAALTALC)
END:END

If neither an overriding Allocation member nor an alternate Allocation member is specified, the default Allocation members are used. Overriding and alternate Allocation members can be stored in the IOA PARM library.

Only one overriding or alternate Allocation member can be specified in a procedure (for example, a CLIST). However, multiple overriding and alternate Allocation members can be created at a site for use with different CLISTs and Online monitor procedures.

Sample ALC Member (ALCCTM)

 KEY=DAPASCTM       
 *                 
 )SEL CTM=Y        
 KEY=DACKPT        
 KEY=DAGRPH        
 KEY=DALIB         
 KEY=DASTAT        
 KEY=DAUNITDF      
 *                 
 )SEL HIST=Y       
 KEY=DAHIST        
 )ENDSEL (HIST=Y)  
 *                 
 )ENDSEL (CTM=Y)   

Modifying IOA Online Facility Commands

Every screen of the IOA Online facility supports a set of commands. It is possible to change the names of these commands or to create synonyms. The commands reside in the IOAENV library in members with the following naming convention:

TxxxCMDy

where

• xxx is the screen identifier.

• y is the commands member number, where 1 is the active commands member, and other numbers are alternative members.

When changing the names of these commands or to create synonyms, make sure to make the changes in a member in the PARM library, and not in a member in the IOAENV library.

IOA Online Options Cross-Reference contains a list of all options, screens and their corresponding command members.

A command member is composed of one header line and any number of command lines. The number at the left of the header line is the total number of command lines in the member. It must be updated when lines are added to or deleted from the command member.

The structure of the command line is:

Table 19 Command Line Structure

It is possible to change the command name and/or description by typing in the change. To add a synonym (a command that is to have the same effect as an existing command), duplicate the command line, modify the command name on the duplicated line, and add one to the command line counter at the left side of the header line. To delete a command, delete the command line in the member and decrease the counter by one.

Modifying IOA Online Facility PFKey Definitions

Every screen of the IOA Online facility is associated with a set of PFKeys with preassigned commands. It is possible to change these PFKey definitions. The PFKey assignments reside in the IOAENV library in members with the following naming convention:

TxxxPFy

where

• xxx is the screen identifier. IOA Online Options Cross-Reference contains a detailed list of all screens and their corresponding PFKey members.

• y is the PFKey definition member number, where 1 is the active PFKey definition member, and all other numbers are alternative members.

When changing PFKey definitions, make sure to make the changes in a member in the PARM library, and not in a member in the IOAENV library.

A PFKey member is composed of one header line and any number of PFKey definition lines.

The structure of the PFKey definition line is:

Table 20 PFKey Definition Line Structure

At least one PFKey or Enter key must be defined as the ENTER command.

IOA Primary Option Menu

The IOA Primary Option menu displays INCONTROL product options and facilities available to the user. Customizing the menu is usually not required since the menu is dynamically generated according to the options available to the user.

The IOA Primary Option menu is displayed in one of the following formats:

• When less than a threshold number of options is available, options are displayed in Line format. Options are listed one per line on the screen. An option code, the name of the option, and a brief description is listed for each option Information about the INCONTROL products installed at the site is displayed in the upper right corner of the screen.

• When more than the threshold number of options is available, options are grouped according to product in Box format. In Box format only option codes and option names are displayed. This format enables displaying all INCONTROL products and their options on one screen. Information about INCONTROL products installed at the site is available using the INFO command.

Reducing or increasing the number of available options might change the format in which the Primary Option menu is displayed.

Line Format Display

---------------------       IOA PRIMARY OPTION MENU       ------------------(1)
OPTION ===>                                               USER N06     
                                                          DATE        10.02.00
                                                           
2   JOB SCHEDULE DEF     CTM Job Scheduling Definition      
3   ACTIVE ENV.          TM Active Environment Display      
4   COND/RES             IOA Conditions or Resources Display 
5   LOG                  IOA Log Display                      
6   TSO                  Enter TSO Command                                 
7   MANUAL COND          IOA Manual Conditions Display                     
8   CALENDAR DEF         IOA Calendar Definition                           
IV  VARIABLE DATABASE    IOA Variable Database Definition Facility         
C   CMEM DEFINITION      CTM Event Manager Rule Definition                 
W   WORKLOAD MANAGEMENT  CTM Workload Management
  
COMMANDS:  X - EXIT, HELP, INFO  OR CHOOSE A MENU OPTION               10.19.39

Box Format Display

---------------------       IOA PRIMARY OPTION MENU       ------------------(1)
OPTION ===>                                               USER        N06  
                                                                              
IOA                        Control-D/V                Control-O            
                                                                              
  4  COND-RES                A  MISSION STATUS         OR  RULE DEFINITION 
  5  LOG                     M  MISSION DEF            OM  MSG STATISTICS  
  6  TSO                     R  REPORT DEF             OS  RULE STATUS     
  7  MANUAL COND             T  RECIPIENT TREE         OL  AUTOMATION LOG  
  8  CALENDAR DEF            U  USER REPORTS           OA  AUTOMATION OPTS 
 IV  VARIABLE DATABASE       F  PC PACKET STATUS       OC  COSMOS STATUS   
                            DO  OBJECTS                OK  KOA RECORDER    
                                                                              
                                                                              
Control-M & CTM/Restart    Control-M/Analyzer         Control-M/Tape       
                                                                              
  2  JOB SCHEDULE DEF       BB  BALANCING STATUS       TR  RULE DEFINITION 
  3  ACTIVE ENV.            BM  MISSION DEF            TP  POOL DEFINITION 
  C  CMEM DEFINITION        BV  DB VARIABLE DEF        TV  VAULT DEFINITION
  W  WORKLOAD MANAGEMENT    BR  RULE DEFINITION        TI  INQ/UPD MEDIA DB
                            BA  RULE ACTIVITY          TC  CHECK IN EXT VOL
                                                                              
                                                                              
COMMANDS:  X - EXIT, HELP, INFO  OR CHOOSE A MENU OPTION               16.20.21

The menu is displayed according to the order of each product in the menu table, as described in Customizing the Menu. The IOA menu is always displayed, only in Box format, on the left side of the screen. However, changes to other menus affect the arrangement of the options of other products in the menu.

Customizing the Menu

Options for the IOA Primary Option menu are listed in member MENU in the IOA MSGENG library. This member can be used to modify the information in the menu display. The lines in this member might look like the following:

*      CommentT*    IOA                    
T*X   IOA                    
TM    Control-M              
TMR   Control-M & CTM/Restart
TD    Control-D              
TDV   Control-D/V            
TO    Control-O              
TB    Control-M/Analyzer     
TB2   Control-M/Analyzer     
TT    Control-M/Tape         

Table 21 Customizing the Menu with Member MENU

TM    Control‑M

Lproduct   environment optcode optname       opt‑description

For more information, see the description in member MENU in the IOA MSGENG library.

Customizing IOA Screens

Customization of IOA screens can be accomplished in a number of different ways. This section describes the following topics:

• modifying IOA screens and constants

• supporting multiple languages

• customizing IOA display format members

• customizing extended color support

You should back up members before modifying them for customization of IOA screens, and use these backups for KSL scripts.

Modifying IOA Screens and Constants

IOA screens and constants can be adapted by the user for local language, local site terminology, ease of use, and so on.

IOA screen and constant members are stored in the IOA MSGxxx library, where xxx is a three-character language identifier (for example, ENG for English, GER for German). According to this naming convention, at English speaking sites the library is the IOA MSGENG library.

Throughout this guide, the English version of this library, MSGENG, is referenced. Substitute the appropriate library name where applicable if English is not the language at your site.

The naming convention for these members is:

CTxSyyyz

Table 22 Naming Convention for Language Members

Each member contains definitions for either a screen and its constants, or a set of constants. Definitions are specified as Assembler macro instructions. Each member must be assembled and link edited to create a CSECT and module with a name identical to the screen member name.

A screen is defined by the following macros in the IOA library:

Table 23 Macros that Define a Screen

Each unit of data in an IOA screen is called a block. A block can contain one or more fields.

'====>>>>>> TOP OF ACTIVE JOBS LIST <<<<<<===='

NAME=[field_name,][parameter=value,...]

Table 24 Fields for Defining Screen Fields Using Macro IOASFLD

Constant Blocks

Blocks used to define constants in SYSIN input DD statements, as part of a message, or as statuses on screens, are different from screen field blocks. You can change the length of the fields, disregarding the "total block length rule." An example is member CTMSAESE, which is used to define parameter syntax of the Control‑M AutoEdit Simulation facility.

Definitions

The following terms are used in describing these topics:

Table 25 Definition of Terms

Recommended Steps for Screen Modification

Sources (screen members) of INCONTROL products are modified using an SMP/E USERMOD. Use the following steps to perform this task:

1. Choose a name for a new USERMOD (to be built in the following steps). The name of the USERMOD must be 7 characters in length, must begin with an alphabetic character (that is, not a number or symbol), and must be unique.

2. Create a new member in the IOA CUSTEXIT library with the same name as the USERMOD created in Step 1.

3. Copy the contents of member UMODSRC in the IOA JCL library to the newlycreated member. This member contains a skeleton sample for the USERMOD (to be customized in the following steps).

4. Specify the name of the new USERMOD in the ++USERMOD statement.

5. Determine the FMID and the RMID of the screen source using SMP/E Online option 3.2. Specify SRC as the entrytype, and the name of the screen source as the entryname.

   Specify the FMID in the ++VER statement.

   If the RMID value is not the same as the FMID value, add the RMID value to the ++VER statement using the PRE(rmidvalue) parameter.

6. Specify the screen sourcename in the ++SRC statement.

7. Copy the contents of the source member to the line immediately after the ++SRC statement. Update the copy to meet your needs.

8. Specify the name of the USERMOD in job UMODRACK in the IOA JCL library. Run the job. This job RECEIVEs and APPLYCHECKs the USERMOD.

   Job UMODRACK must end with a completion code of 0.

9. Specify the name of the USERMOD in job UMODAPP in the IOA JCL library. Run the job. This job applies the USERMOD.

   Job UMODAPP must end with a completion code of 0.

Supporting Multiple Languages

Individual users can display the IOA and INCONTROL product interfaces (screens, help, and so on) in a language other than the primary language defined for the site. The primary language for the site is defined during IOA installation.

To set a language for a specific user, that user issues operator command:

SET LANG=xxx

Table 26 Fields for Supporting Multiple Languages

This setting takes effect at the next IOA session and remains in effect for all subsequent IOA sessions (until a new SET LANG command is issued).

When a user selects a language that is not the primary language, a new DD statement is dynamically allocated called DALANGxxx (where xxx is the selected language). The dataset that is associated with this DD statement is prefixed DAMSGxxx. All format screens ($$xxx) and the online help text screens are read from this DD statement. Messages are read from DD statement DAMSG, which contains all necessary message libraries. The typical, compiled screens are loaded from DD statement STEPLIB.

Supporting an Additional Language

In addition to the languages supplied on the installation tape, other languages can also be supported. To support another language, perform the following steps. Assume that the three-character code for the new language to support is lng).

1. Create a new library named MSGlng, which contains the translated message and screen members.

2. Concatenate the new message library (MSGlng) to the DAMSG key in member IOADSNL in the IOA PARM library.

   In member IOADSNL in the IOA PARM library, add the following entry:

   Copy

   DATASET LANGlng,      
           SEQ=1,                
           DD=DALNG%SLANG%,             
           DSN=%ILPREFA%.MSG%SLANG%

Customizing IOA Display Format Members

In certain INCONTROL product screens, it is possible to specify the display type (or format) of the screen. A wide selection of predefined display types is provided. For example, in the Control‑D User Report list, display type S is similar to IBM’s SDSF, while display type J can be used for production control and by programmers. For details, see the appropriate user guide.

If the predefined display types are not adequate, users can define their own display types using the Display Type Editing facility. This section describes parameters that define new display types or modify existing display types.

Another method for customizing display types is described in Concept.

All display formats are defined in members in the IOA MSGENG library. For a list of these members, see Concept, which contains a list of all the options of IOA, and the screen member and/or format members that are used to build the IOA panels. For example, in Control‑D, the display formats of option U are defined in members $$FRM and $$USR in the IOA MSGENG library. These members contain sets of predefined display formats. When a display type is activated, it first checks for any errors, which are displayed in an appropriate screen.

When the user needs to add new formats or modify existing formats, it is highly recommended that the corrections be made in the $Lfrm member (instead of the $$frm member), where frm is the member name. The $Lfrm members are for localization purposes, and are not overwritten during product maintenance.

Each line in a format member is one of the line types listed below. The line type must be written in positions 1 through 10 of the line. The permitted line types are

• @STYLE 

• @HEADER

• @LINE

• @FIELD

• @VAL

• @END

• @DLM

• @INCLUDE

• Color, Highlight and Intensity Parameters

• @DELETE

A line starting with an asterisk (*) is a comment line.

The parameters on the line characterize the line’s attributes. Parameters can be written in positions 11 through 72 of the line. A continuation line is created by leaving the "line type" area blank and using positions 11 through 72 for parameters that describe the line’s attributes.

In order to modify or replace an existing display type the following line must exist in the $Lfrm member before defining the replacement display type:

@DELETE ID=id; LTH=n; TYPE=type; CLASS=class;

where id, n , type, and class are defined as they appear in the @STYLE statement in the original $$frm member which is to be modified or replaced. If this is not done, the following messages are displayed:

ERROR IN MEMBER - $Lfrm
CTMB1CI – THIS FORMAT ALREADY EXISTS

The preceding message may also be displayed as
IOAB1CI – THIS FORMAT ALREADY EXISTS

The following sections describe each line type and its parameters.

@STYLE

@STYLE is a line type used to start a new display format or a replacement display format. The format for an @STYLE line is:

 @STYLE ID=id; TYPE=type; CLASS=class; 
 [IDLIKE=idlike; TYPELIKE=typelike; CLASSLIKE=classlike;] 
 LTH=n;

Table 27 Format of Fields for @STYLE Line

Color, highlight and intensity parameters can also be modified. For more information, see Color, Highlight and Intensity Parameters.

@HEADER

@HEADER is a line type used to describe the header line of the current display format. The format for an @HEADER line is

@HEADER       DATA=data;

where data is the actual header data to be displayed as the header line of the screen in which the display type is shown. The header data can be a maximum of 80 (or 132) characters in length. If less data is specified, it is padded with blanks to fill the physical line.

Color parameters can also be modified. For more information, see Color, Highlight and Intensity Parameters.

@LINE

@LINE is a line type used to start a new line in the current display format. The format for an @LINE line is

@LINE       LONG={Y|N}; SHOWBLINE={Y|N};

Table 28 Format for Fields in the @LINE Line Type

Color parameters can also be modified. For more information, see Color, Highlight and Intensity Parameters.

@FIELD

@FIELD is a line type used to start a new field in the current line in the current display format. The format for an @FIELD line is

@FIELD NAME=name; DATA=data; LTH=ln; PREF=pref; KANJI={Y|N};
OFFSET=ofst; EDIT={Y|N}; DEFAULTEDIT={Y|N}; DFLT=dflt; 
PROFILE=Y/N/name ; AFORCE={Y|N}; EXPAND=YES;

where

• name is the field to be displayed. Valid names are listed in the description of the display types of each product.

• data indicates that constant data to be displayed. This is useful, for example, for displaying a field descriptor. Either NAME or DATA must be present, but not both.

• ln displays the length of the information of the field specified in the NAME parameter, or the display length of the constant information in the DATA parameter. If the actual information provided by NAME or DATA is too short, it is padded with blanks on the right. If the information is too long, it is truncated on the right.

• pref is the prefix to be added to the left of the displayed data specified by NAME or DATA.

• KANJI specifies if Kanji (Japanese writing using Chinese characters) input is allowed. Valid values: Y (Yes) and N (No). N is the default.

• ofst is the offset in the data field from which data is taken for screen display purposes. This mechanism allows the user to split a long data field between several display fields (possibly on several different lines). ofst is the offset from which to start.

• EDIT indicates whether the user can change the displayed field. Valid only if NAME is specified. If Y (Yes), the user can change the displayed field. If N (No), the field is displayed in a protected form. It cannot be modified. N is the default.

• DEFAULTEDIT indicates whether the user is able to edit an insert record. Valid only if NAME is specified. If Y (Yes), for an Insert record, the field is displayed so that the user can enter initial information for it. If N (No), the field is displayed in a protected (cannot be modified) form. N is the default.

• dflt is the default value for the field in an insert line. Valid only if NAME is specified. The data specified is displayed in the field. If DFLT is omitted, the initial value of the field is blank.

• PROFILE=Y/N indicates whether the value of the field (when exiting the Online environment) is saved in the user's profile member and used at the next invocation of the environment. The field name is used as the Profile Variable name. Optional. Valid values: Y (Yes), N (No). Default: N

  PROFILE=name indicates what the value of the field (when exiting the Online environment) is saved in the user's profile member and used at the next invocation of the environment.The name is used as the Profile Variable name. Optional

• AFORCE forces an attribute character before the field. If Y (Yes), forces the character. If N (No), does not force the character. N is the default.

• EXPAND=YES enables a field to expand to its largest possible width based on a 132-column (Type 5) terminal.

Color parameters can also be modified. For more information, see Color, Highlight and Intensity Parameters.

@VAL

@VAL is a line type used to set the color of the current field according to the value of the field. More than one @VAL line type can be specified for different values of the current field. The first match found between the field’s value and the value specified in the @VAL line determines the color of the field. The format for an @VAL line is

@VAL       DATA=data

where data specifies a data string that is be compared to the current value of the field. The data string can contain * and ? mask characters.

Color parameters must also be specified in the line. In case of a match between the field’s current value and data in the @VAL line, the colors specified in the @VAL line override the colors specified in the @FIELD line.

@END

The @END line type is used to end the definition of the current display format.

@DLM

The @DLM line type is used to change the currently used delimiter in this member to a new one. The default delimiter is; This line can be inserted anywhere in the member. The format for an @DLM line is

@DLM=newold

where new is the new delimiter and old is the old delimiter.

In the @DLM line the new delimiter is specified as the value for the DLM keyword but it is delimited by the old delimiter.

@DLM=,;      <<‑‑‑‑‑ delimiter first set to ,
@DLM=&,      <<‑‑‑‑‑ delimiter then set to &
@DLM=;&      <<‑‑‑‑‑ delimiter set back to ;

@INCLUDE

The @INCLUDE line type is used to insert the text of a member into the current member (essentially, performing a copy). This line can be inserted anywhere in the member. The format for an @INCLUDE line is

@INCLUDE=member

where member is the name of the member to include within the current member.

Color, Highlight and Intensity Parameters

The @STYLE, @LINE, @FIELD and @HEADER line types support COLOR, HILITE and INTENS parameters. Color takes effect on color monitors only. Highlight takes effect on both color and monochrome monitors. Intensity takes effect on monochrome monitors only.

Valid colors:

• NONE (Default)

• WHITE

• BLUE

• GREEN

• TURQ

• RED

• PINK

• YELLOW

Valid highlights:

• NONE (Default)

• BLINK USCORE

• REVERSE

• DARK

For of monochrome monitors, users can add the INTENS parameter to the @FIELD line type.

Valid intensities:

• LOW (Default)

• HIGH

Users can create a combination of color and highlight or highlight and intensity for each field by specifying COLOR, HILITE and INTENS parameters on the same @FIELD line. The COLOR, HILITE, and INTENS parameters can all be specified on a line. Each takes effect when appropriate.

• If the above parameters are omitted on the @FIELD line, the field inherits those parameters from the @LINE preceding it.

• If these parameters are omitted on the @LINE line, the line inherits those parameters from the @STYLE preceding it.

• If these parameters are omitted on the @STYLE line, they are set to their default values.

@STYLE, @LINE and @FIELD also accept COLORA and HILITEA parameters that have the same values as COLOR and HILITE, respectively. These parameters can be used to specify a set of alternate colors when displaying records: the first record on the screen is displayed with COLOR and HILITE; the second record is displayed with COLORA and HILITEA; the third record with COLOR and HILITE, and so on. This causes an alternating color effect. If COLORA and HILITEA are omitted, the alternate colors are set to the standard color values.

@DELETE

The @DELETE line type is used to remove or redefine existing styles (after they have been deleted). Whether you simply delete a style, or delete and then modify it, the changes are made in the $Lxxx member and not in the $$xxx member. The format for an @DELETE line is

@DELETE ID=id; LTH=n; TYPE=type; CLASS=class;

where id, n, type, and class are defined as they appear in @STYLE to be deleted or modified.

For example, you can use @DELETE ID=D; LTH=80; TYPE=L; CLASS=L; to prevent users from using the D display type. Once the style is deleted, you can then redefine it for later use.

Extended Color Support

The following is considered when using the extended color feature of the IOA Online facility:

• IMS/DC and IDMS/DC

• IRMA PC Terminal Emulator Users

IMS/DC and IDMS/DC

IOA does not automatically recognize an IMS/DC or IDMS/DC terminal as supporting extended color attributes. If the IMS/DC or IDMS/DC terminal supports extended color attributes, the ICOLOR=YES parameter must be added to the user’s profile. For details on modifying the user’s profile, see Profile Variables

It is important not to use parameter ICOLOR=YES for non‑color terminals. Doing so causes an error and the terminal is inhibited.

IRMA PC Terminal Emulator Users

Early versions of IRMA‘ (from DCA‚) might not interpret the 3270 color stream correctly. Therefore, IOA screens may not appear in the proper colors. If this problem occurs, call your local IRMA representative and request a later version of IRMA that corrects this problem.

Customizing Extended Color Support

The IOA environment uses extended color support if the terminal is capable of supporting it. Various defaults are set so that if no changes are made, extended color is used wherever possible.

Two VTAM commands can be used to help determine whether a particular terminal supports color:

Table 29 VTAM Commands for Determining Color Support

Table 30 Color Support by Environment

In this table, TCOLOR and ICOLOR are IOA Profile variables. For more information about these variables, see IOA Profiles.

For TSO/ROSCOE Cross‑Memory and CICS, the appropriate change must be applied before the ICOLOR variable is activated.

Language support in IOA screens

INCONTROL products are shipped with the default version of IOAX037 (IOA user Exit 37), which is used to translate specific hexadecimal values. The default version of this exit translates certain hexadecimal values to X'40' (blanks). This could result in incorrect display of some screen characters under certain circumstances, in which case this exit may require local tailoring.

For further information on modifying this exit, refer to the description of the IOAX037 Exit inIOA Exits.

IOA Access Method

Several INCONTROL products include files that are processed using an internal component called the IOA Access Method.

The IOA Access Method is used to create indexed (keyed) file structures that offer enhanced data integrity. IOA Access Method files are physical sets of sequential datasets that are allocated, formatted and accessed by INCONTROL products using IOA Access Method utilities.

Most IOA Access Method files consist of two separate sequential datasets:

• a data component, where the actual record information resides

• an index component, which provides keyed access to records in the data component

Some IOA Access Method files may contain only an index or data component.

The IOA Access Method provides dual mirror image file support. This mechanism enables a quick recovery of IOA Access Method files if a disk crash occurs on a disk that contains IOA Access Method primary files.

File Structure

IOA Access Method index component records are fixed length. IOA Access Method file data component records can be fixed or variable length. Each record is represented by the relative byte address of the record (RBA), which consists of four bytes. As shown in the table, the first byte represents the extent number of the record; the next two bytes represent the block number within the extent; the last byte represents the record number within the block.

Table 31 Relative Byte Address Components

Both index file and variable data file information are stored in compressed format, resulting in reduced I/O processing overhead and optimum disk space utilization.

The first block in each IOA Access Method file extent consists of a control record. For data file components with fixed length records, the control record contains an RBA of the first free record in the database; each free record contains an RBA of the next free record. For data file components with variable length records, the control record contains a bit table indicating the blocks within the extent that contain free space for additional records. The IOADIG utility can be used to check the integrity of the list of free records. For details of the IOADIG utility, see the INCONTROL for z/OS Utilities Guide.

IOA Access Method index files function as balanced tree index structures.

In addition to index (key) and data record pointer fields, IOA Access Method file index component records can contain non‑key data, enabling non‑key selection criteria to be used without accessing the associated IOA Access Method file data component. Non‑key data fields in index records can be stored in compressed format, providing maximum space utilization benefits.

Examples of file structure

• ControlD User Report List files are indexed by recipient name, job name and record creation timestamp.

• ControlM/Analyzer Group Definition files are indexed by group name.

Data and index components may extend beyond one physical dataset. Initially, however, a component is allocated as a single physical dataset called the primary extent.

To increase an IOA Access Method file component’s capacity, a maximum of 255 secondary extent datasets can be allocated and formatted. Using an IOA Access Method definition option, secondary extent allocation and formatting can automatically be performed when an out‑of‑space condition occurs.

Deleting Records in IOA Access Method Files

If a record is deleted from an IOA Access Method file, the space previously required for that record is reusable for other records. The block that contained the deleted record is reorganized during the deletion process to consolidate all free space of the block in one piece.

IOA Access Method Naming Conventions

IOA Access Method files that are allocated during IOA, Control‑D, Control‑V, Control‑M/Analyzer, and Control-M/Tape installation are listed in Files Supported by the IOA Access Method, and use the following naming convention:

prefix.dbname.Ennn

where

• prefix is the IOA Access Method file name prefix. The prefix is specified during product installation by setting relevant installation variables (for example,DBPREFB for ControlM/Analyzer, and DBPREFD for ControlD and ControlV). The prefix can contain more than one qualifier.

• dbname is the IOA Access Method file identifier name. The identifier name is specified during product installation as part of the name assigned by parameter DSN in the IOA Access Method file’s definition statements. For example, identifier name ACT is assigned to the ControlD Active User Report list data component while ACTI is assigned to the ControlD Active User Report list index component. The identifier name of an IOA Access Method file is never modified.

• Ennn is the extent sequence number suffix generated internally by IOA Access Method management routines whenever an IOA Access Method file component is allocated. The suffix consists of the letter E followed by nnn, a number from 000 to 255, indicating an IOA Access Method file’s extent sequence number. A maximum of 255 additional file extents can be associated with each IOA Access Method file.

Files Supported by the IOA Access Method

Table 32 IOA Files

Table 33 Control‑D Files

Table 34 Control‑V Files

Table 35 Control‑M/Analyzer Files

Table 36 Control‑M/Tape Files

Jobs or procedures using IOA Access Method files contain a DD statement only for the first extent of the primary file. All other extents are dynamically allocated when the IOA Access Method file is opened.

Building Index Utilities

A building index utility is provided for each INCONTROL product that uses IOA Access Method files.

Table 37 Building Index Utilities for INCONTROL Products

File Utilities

A comprehensive set of utilities is provided for INCONTROL products that use IOA Access Method files. These utilities are used to create and maintain IOA Access Method files.

Table 38 Utilities for IOA Access Method Files

Products that use the IOA Access Method contain additional utilities that are specific to the product. For more details about additional IOA Access Method utilities, see the summary list of utilities in the INCONTROL for z/OS Utilities Guide.

File Definition Statements

When allocating and formatting an IOA Access Method file (that is, using utility IOADBF), a library member containing IOA Access Method File Definition statements is read.

These statements define an IOA Access Method file’s physical and logical attributes, such as dataset name, unit, volume parameters, space parameters, record key length (for IOA Access Method file index components), and whether additional file extents are allocated automatically or manually when the current file extent is full. The members reside in the IOA INSTWORK library.

The attributes of the IOA Access Method file are kept in the file control block. If you need to change these parameters after the file is created, you can first modify the Definition Statements member and then run the IOADBF utility with FUNC=CHANGE.

BMC highly recommends that you make the modifications to the Definition Statements member using the ICE Customization activity, in order to take advantage of its space calculation and job formatting steps. Using ICE, specify the product code (for example, IOA, CTM) in the Customization screen, select Product Customization, and then select major step 2, "Customize Dataset Parameters." Perform the minor steps in order for each file you want to modify.

For more information on IOA Access Method File Definition statements, see the IOADBF utility in the INCONTROL for z/OS Utilities Guide.

Dual Mirror Image File Support

Each IOA Access Method file can be created with dual mirror image file support. For each logical extent of the file, the IOA Access Method automatically allocates a dual extent of the same size. The name of the dual extent is identical to that of the corresponding primary extent, except for the first character of the last qualifier that is set to D instead of E (for example, prefix.dbname.Dnnn).

The dual mirror image file is not supported by Control-M/Tape.

The dual mirror image file is created if parameter DUAL in the IOA Access Method definition member is set to Y (Yes). (For more information, see the IOADBF utility in the INCONTROL for z/OS Utilities Guide.) The definition member also specifies the unit and volume names for the dual file allocation.

The IOA Access Method synchronizes the primary and dual files. All read operations are performed only from the primary file, and all write operations are performed in parallel to both files. The dual file is allocated dynamically.

For improved performance and recovery capability, different volumes must be used for the primary and dual files.

You should activate dual mirror image support for only the data component and not the index component of the IOA Access Method files.

Dual Mirror Image File Parameters

The following parameters are used to manage the dual mirror image file:

• DUALM

  If parameter DUALM is set to Y (Yes) and an error occurs in the dual mirror image file, the current operation fails for the primary file as well. Make any manual corrections before any further processing is done. If parameter DUALM is set to N (No), processing continues for the primary file only, without dual mirror image file support.

• DUALST

  An additional dual mirror image option is an internal timestamp checkpoint to ensure that the primary and dual copies are fully synchronized. This ensures greater data integrity but increases I/O processing overhead.

  This option is activated if parameter DUALST in the IOA Access Method definition member is set to Y (Yes) during file creation. If the timestamp values are not synchronized between the primary and dual files, the dual file is rebuilt. For additional information, see the IOADBF utility in the INCONTROL for z/OS Utilities Guide.

Recovering From a Damaged IOA Access Method File

If the IOA Access Method is used with dual file support and one of the two copies corrupt, the damaged file can be restored by using utility IOADCPY. This utility copies all the extents of the working copy to the corresponding extents of the corrupted copy. For more information, see the IOADCPY utility in the INCONTROL for z/OS Utilities Guide.

IOA Profiles

A profile is a set of values to be used as default values for certain fields in IOA screens during sessions of a specific user or group of users (for example, the library name field in the Job Scheduling Definition entry panel, or a show screen filter).

The IOA Online environment provides the following types of profiles:

• the Global profile, which can only be customized by the system administrator

  This profile serves as the default setting for all users in the Online environment. If the user profile does not indicate a setting for a specific field, or does not provide a value for a specific variable, the value specified in the Global profile is used.

  The Global Profile also contains screen filter definitions that can be used by any user in addition to the filter definitions defined in the user’s User profile.

  The Global profile is a combination of the default values in member $PROFILE and the overriding specifications in member $PROFMOD, as explained in Profile Members.

• user profiles, which are defined for users or specific groups of users.

  These profiles, explained in Profile Members, can include menu definitions and userdefined filters. Settings in the User profile override the settings in the Global profile.

Profile Members

The table describes the profile members and the global profile information they contain.

Table 39 Members Containing Global Profile Information

$PROFFLD and $PROFVAR combined as $PROFILE and are found in the IOAENV library.

User profile members are located in libraries specified in member $PROFILE and, optionally, in $PROFMOD. These libraries are listed in the lines beginning with a dollar sign ($) in the $PROFILE member. For example, the following lines indicate that the user profile for user M89 is in library IOAP.OPRM.PROF and that all other user profiles are in library IOAP.OPR.PROF.

000059 *        POINTERS TO USER'S PROFILE LIBRARIES.     *    
000060 *--------------------------------------------------*
000061 $M89             =IOAP.OPRM.PROF                       
000062 $*               =IOAP.OPR.PROF
By default, the following line is included in member $PROFILE:
$*               =%OLPREFA%.PROF

This line indicates that all user profiles are found in the PROF library with the prefix of the dataset in which IOA was installed.

User profiles can be divided into more than one library. For example,

$M*               =%OLPREFA%.PROFM
$N*               =%OLPREFA%.PROFN

can be used to direct all User profiles beginning with M to be stored in the PROFM library and User profiles beginning with N to be stored in the PROFN library.

Mask characters (* and ?) can be used in the specification of the user names (profiles) to be stored in a specific library.

Profile Contents

The following types of lines can appear in a profile member:

• lines that contain an asterisk (*) in column one are remark lines

• lines that contain a dollar sign ($) in column one indicate user profile libraries

• lines describing either variables, fields or filter fields. These are called Profile Symbol lines

The table describes the format of the Profile Symbol lines.

Table 40 Profile Symbol Lines Format

SRLBLIB         =%OLPREFB%.RULES

SACT900 .ENDNOTOK=N
SACT704 .ENDNOTOK=N

Considerations for Profile Symbol Lines

• Values for Profile variables are specified in ICE (using the Customization option in the main ICE screen, entering IOA in the Product field, and then selecting Product Customization). The values are stored in member $PROFILE in the IOAENV library. For details on what values to specify for the Profile variables using ICE, see Profile Variables.

• Field lines contain values to be used for fields in IOA that are not part of a SHOW window (for example, a library name in a rule, job and mission definition entry panel). Field lines can be located in any of the following members:

Table 41 Members that Can Contain Field Lines

• Filter field lines specify values for selection criteria fields in Show Window filters (For example, Y (Yes) or N (No) for field UTILITIES in the IOA Log Show Screen Filter window indicates whether messages from ControlM/Tape utilities are displayed).

SHOW Window Filters

A filter is a set of values for fields in a show window. The user can name a set of values and activate a filter at a later time by specifying the following command in the command line of the relevant screen:

SHOW filtername

Filters that are saved by a specific user are stored in that user’s User Profile member. To add a filter to the Global profile, perform the following steps:

1. Create and save the filter in your User Profile member.

2. Copy the lines containing the name of the filter from your User Profile member to the Global Profile member ($PROFMOD).

   Some default filters are provided in member $PROFILE.

Filters are provided for the Active Environment screen (option 5 from the IOA Primary Option menu) and the IOA Log Display (option 5 from the IOA Primary Option menu). For more information about IOA filters, see the descriptions of these options in the relevant INCONTROL product user guides.

Profile Attribute in the Screen Definition

IOA is installed with default profile attributes assigned to various fields. You can change these defaults as follows:

A field can be defined with a profile attribute by adding parameter PROF=YES to the field macro definition in the screen definition member in the MSGENG library. For example:

NAME=SSCHROL,ATTR=UH,LTH=4,PROF=YES

For instructions on how to change the screen format, see Recommended Steps for Screen Modification.

Under certain screens, parameter PROF designates the name of the profile variable. When YES is specified, the field name is used as the Profile Variable name. If you want to change the profile attributes of these screens, contact BMC Customer Support.

IOA profile capability can be applied to fields in the header, footer, and windows of each screen, but not to fields that are part of a scrollable area on the screen. If you want to apply the profile capability to a field in a scrollable area, contact BMC Customer Support.

Saving a Profile

A profile is saved by writing it to the user profile library in a member whose name is identical to the user ID (the Online environment session ID, for example, TSO user ID). However, a profile is saved only when the user exits the IOA Online facility, and only in case of normal termination.

If the profile library is full, the attempt to save a User profile fails with a D37 abend. It is recommended that the profile library be compressed regularly.

Profile Variables

Follow the major and minor steps in ICE to specify values for the Profile variables. If you are not familiar with the ICE application, see the INCONTROL for z/OS Installation Guide: Installing.

To change the value of a Profile variable, perform the following steps in ICE:

1. Select Customization.

2. Enter IOA in the Product field.

3. Select Product Customization.

4. Select major step 3, "Profile Variables."

5. Select the type of variable.

6. Locate the desired variable and specify the required value.

   Online help is available for each variable specified using ICE. The following sections describe each variable.

7. Save the values you entered by selecting "Step 6.7 Save Values in $PROFMOD."

   ICE allows referencing of previous settings of Profile variables specified in other (previous or current) environments of IOA. When installing a new IOA environment, it is possible to automatically retrieve the predefined settings at your site. A default value is provided for any new profile variables that are not retrieved.

   To retain predefined settings (for example, from previous INCONTROL versions), copy the version of member $PROFMOD from your previous version to the PARM library after completing the ICE installation.

Window Display Variables

Table 42 Window Display Variables

Color Variables

A color and highlight value can be specified for each of the profile variables described in this section. Each profile variable has its own default color and highlight value. The format for specification of color and highlight is

profile-variable=color,highlight

where

• profilevariable is the name of the profile variable for which color and highlight values are being specified. Profile variables used to specify color for elements in the IOA environment are listed below.

• color is the color of the relevant element. Valid values are BLUE, RED, PINK, GREEN, TURQ, YELLOW and WHITE.

• highlight is the type of display for the element. Valid values are BLINK, USCORE and REVERSE.

The table describes the profile variables that are used to determine the color and highlight attributes of specific elements in the IOA environment.

Table 43 Profile Variables for Color and Highlights

On color terminals, the lines of the record‑level index value are displayed in the color specified in the first parameter.

On monochrome terminals, the record level index lines are highlighted (in either REVERSE, BLINK or USCORE) as specified in the second parameter.

Table 44 Highlight on Monochrome Terminals

Work Mode Variables

Table 45 Work Mode Variables

Presentation Mode Variables

Table 46 Presentation Mode Variables

Miscellaneous Variables

Table 47 Miscellaneous Variables

Modifying INCONTROL Product Defaults

After one or more INCONTROL products are installed and running, certain defaults can be modified within the product. For example, you can increase the number of Control‑M attempts to read a job’s sysout.

To modify INCONTROL product defaults, it is recommended that you perform the process by means of ICE:

1. Enter the main ICE screen.

2. Select Customization.

3. Select the Environment.

4. Enter IOA in the Product field.

5. Select Product Customization.

6. Select major step 5, "Customize IOA Defaults."

7. Select minor step 1, "IOA Defaults Description."

   The IOADFLTS documentation member, which resides in the IOA DOC library, is displayed. This member lists the defaults that can be modified.

8. Review the IOADFLTS member, and then press PF03 to exit this minor step.

9. Select minor step 2, "Modify IOA Defaults."

10. Locate the relevant wish number (for example, enter L WI2239).

11. Set the wish to APPLY=YES.

12. Enter or modify the values of the Data and DataC fields, as necessary.

13. Press Enter and then PF03.

    Member IOADFLTL in IOA PARM is updated with the modified wishes.

14. In addition to member IOADFLTL in the PARM library, there may be user exits in the IOA SAMPEXIT library that can be applied to modify default processing within a specific product.

    Depending on the specific optional wish that you modify, you might need to restart the relevant started tasks for your changes to take effect.

Modifying IOA Messages

IOA messages can be adapted for local languages, site‑specific terminology, and so on.

IOA messages are stored in the IOA MSGnnn library, where nnn is a three-character language identifier (for example, ENG for English, GER for German). According to this naming convention, at English speaking sites the library is the IOA MSGENG library.

Throughout this guide, the English version of this library, IOAENG, is referenced. Substitute the appropriate library name where applicable if English is not the language at your site.

The messages are organized in members with the following naming convention:

XXXXXN

where

• XXXXX is the five-character message code prefix. All messages in this member begins with these characters.

• N is the single character indicating the language of the screen (for example, E for English, G for German).

Each member contains definitions for one or more messages. Each message is defined by the following structure:

Table 48 Structure of Messages

Example

MSGCODE=IOAD82E; SCROLL=ASIS
PARM=(24,38,53)
ALLOCATION FAILED, RC=xx  ERRORCODE=xxxx  INFOCODE=xxxx

MSGCODE=IOAD82E; SCROLL=ASIS
PARM=(24,37,53)
ALLOCATION FAILED, RC=xx  ERRORCODE=xxxx  INFOCODE=xxxx

Redirecting IOA messages

Messages can be redirected by using the MSGROUT member, residing in the IOA PARM library. MSGROUT is provided as an empty member. A sample is shown below:

MSGCODE=msg-prefix,ROUT=(OUT),DDN=PPP
MSGCODE=XMM79,ROUT=(OUT),DDN=PPP
MSGCODE=IOAD97,ROUT=(LOG)
MSGCODE=IOAD91E,ROUT=(WTO),ROUTCDE=(1,2,3),DESC=(1,2,8)
MSGCODE=IOAD9,ROUTCDE=(1,2,3),DESC=(1,2,8)
MSGCODE=IOAD,ROUT=(LOG)

The MSGROUT parameters are described in the following table.

The values given to the ROUT, ROUTCDE, and DESC parameters must be enclosed in parentheses.

MSGROUT is provided with sample lines. Each line that starts with an asterisk (*) is specified as a comment line. Remember to remove the asterisks from the appropriate lines before saving the edited MSGROUT member.

Table 49 MSGROUT Parameters

Message Destination Tables

The IOA Shout facility enables the user to specify messages to be sent to specified destinations upon the occurrence of various events.

Destinations in a production environment are not necessarily fixed. For example, the TSO logon ID of the shift manager may be different for every shift. The Dynamic Destination table allows the user to specify a logical destination name for a group of destinations. When the logical destination name is specified as the destination of a Shouted message, the message is sent to each destination in the group.

The following types of destination tables are provided:

• Dynamic Destination Table

• Mail Destination Table

• SNMP Destination Table

The Dynamic Destination Table

After completing installation, but before using the IOA Shout facility services, you must build and define the parameters in the IOADEST sample member in the IOA PARM library.

WARNING: If you do not define the global parameters in the IOADEST member, the IOA Shout facility will not function.

The destination parameters, contained in the IOADEST member, are described in the table. An example is shown in the figure that follows. For more information about Dynamic Destination tables, see Dynamic Destination Table.

Table 50 IOADEST Parameters

*  TSO users-id                                                        
*------------------------------------------------------------*         
    GROUP=TSO-DEMO-GROUP                                                
      TSO=U001                                                          
      TSO=IBMUSER                                                       
      TSO=SYS01                                                         
*------------------------------------------------------------*         
*  operators users-id                                                  
*------------------------------------------------------------*         
    GROUP=OPER-DEMO-MIXED                                               
      OPER=11                                                           
      OPER2=14                                                          
      TSO=OPER01                                                        
      U=M:OPER-MAIL             must be defined in MAILDEST             
      U=S:OPER-SNMP             must be defined in SNMPDEST             

The Mail Destination Table

After completing installation, but before using the MAIL services, you must specify several parameters in the MAIL section of the IOAPARM member in the IOA PARM library. For more information, see Message Destination Parameters in IOAPARM.

The MAILDEST member contains the default values, including the nicknames and group names, of intended recipients of e-mails generated by IOAMAIL. Initially these default values are sample values. The user is required to edit the MAILDEST member and specify actual values in place of the sample values.

The MAILDEST member contains the default values, including the nicknames and group names of intended recipients of e-mails generated by IOAMAIL.

If you do not define the global parameters in the MAILDEST member, the IOAMAIL facility will not function.

For more information about nicknames and group names and their use in the operation of IOAMAIL, see IOAMAIL.

The MAILDEST parameters are described in the table.

Table 51 MAILDEST Parameters

The SNMP Destination Table

After completing installation, but before sending SNMP traps (messages), you must specify several parameters in the SNMP section of the IOAPARM member in the IOA PARM library. For more information, see Message Destination Parameters in IOAPARM.

In addition, you must define the appropriate parameters in the SNMPDEST member. The IOA IOAENV library contains a sample SNMPDEST member, with an example of how to define the SNMPDEST parameters. Copy the SNMPDEST member to the IOA PARM library and define the parameters appropriately.

SNMP destinations consist of host names, IP addresses, nicknames, group names, and port numbers to where an INCONTROL product can send SNMP traps (messages).

The SNMPDEST parameters are described in the following table.

Table 52 SNMPDEST Parameters

*                                      NICK=R5,                               
    HOST=mvs3                             
NICK=R8,HOST=172.16.254.255            
NICK=mvs8-et,HOST=mvs8-et.isr.bmc.com  
NICK=NABUCO,HOST=172.16.110.117        
NICK=NAB,                              
    HOST=nabuco.bmc.com,PORT=65533                          
                                       
NICK=VASILY,HOST=Vasily                
NICK=ILYA,HOST=172.16.240.90           
                                      
NICK=leonardo,HOST=leonardo.bmc.com
  
GROUP=SNMP                        
     NICK=R5                      
     NICK=VASILY                  
     NICK=ILYA                         
     NICK=NABUCO                       
     HOST=172.16.241.128               
     HOST=leonardo.bmc.com         
     NICK=leonardo                     
  
GROUP=users                       
     HOST=172.16.241.128,PORT=162                       
     HOST=leonardo.bmc.com         
*                                 
GROUP=mvs                         
     NICK=R5                          
     NICK=R8                         
     NICK=mvs8-et                   
     HOST=172.16.130.151           
     HOST=172.16.110.134,PORT=162 

SNMPDEST Destination Coding Rules

• Columns 1–71 can contain statement code.

• Any statement can be interrupted by a comma and can be continued on the next line.

• An asterisk in column one makes the entire statement a comment.

• Any number of empty lines are allowed.

• The HOST statement can be a host name or IP address and can optionally have a PORT parameter appended to it.

• The NICK statement serves as a synonym for a host name or IP address. It is provided for ease of use. If used, it must have a HOST parameter and optionally, a PORT parameter appended to it. The NICK parameter is treated as if it is specified in uppercase.

• All NICK parameters must precede the first GROUP parameter.

• The GROUP statement enables the user to send multiple SNMP traps (messages) to many users simultaneously. It is strictly provided for ease of use. If used, it must have any number of HOST and NICK parameters and optionally, PORT parameters appended to it. The GROUP parameter is treated as if it is specified in uppercase.

The following search order is used to determine the SNMP destination:

1. If the target is specified as a standard dotted-decimal notation, it is treated as an IP address and the SNMP trap (message) is sent to it.

2. The GROUP definitions are searched.

3. If not found, the NICK definitions are searched.

4. If not found, an attempt is made to treat the target as an immediate host name and the SNMP trap (message) is sent to it.       

Replacing the SNMP Destination Table (SNMPDEST)

When the respective INCONTROL product monitor is started, the SNMPDEST SNMP Destination table is loaded to memory. The table contains host names, IP addresses, nicknames, group names, and port numbers to which a product can send SNMP traps (messages). When any address or name is added, changed, or deleted, the changed table should be reloaded to memory by one of the following commands:

F CONTROLM,NEWSNMPDST – for Control-M

F CONTROLO,NEWSNMPDST – for Control-O

After a few seconds, a message describing the result of the operation is displayed on the operator console.

Understanding the SNMP Trap Fields Format

This topic explains the SNMP trap fields format generated by the DO SNMP and SHOUT to U-S commands, and is intended for the administrator setting up the SNMP listener.

The figure below shows an example SNMP trap message taken by a sniffer trace. In this example:

• The Generic trap field is set to 6 (Enterprise specific)

• The Enterprise field of the message is set to 1.3.6.1.4.1.954.512 and is defined as follows:

  • 1.3.6.1.4.1: The IANA-registered Private Enterprise

  • 954: The vendor (BMC)

  • 512: Application (ControlM or ControlO)

• The Specific trap field is set to 3. BMC defines the values of the Specific trap field as follows:

  • 3: Regular

  • 2: Urgent

  • 1: Very Urgent

• The three SNMP Value fields are defined as follows:

  • Control-O: The Application name (either ControlM or ControlO).

  • 061TROLO: The Monitor name.

  • CICSPROD ENDED S878 U000 RC08: The message text itself as it is coded in the MESSAGE field of the DO SNMP panel.

Figure 4 Example SNMP Trap Message

IOA MIB Definitions

Following is a MIB for the SNMP traps sent by the following statements:

• DO SNMP statement of Control-O

• DO SHOUT TO U-S:<snmp destination> statement of Control-M.

The MIB is provided in member IOAMIB in the SAMPLE library.

The MIB is used by the software on the trap recipient side to interpret the fields of the trap message.

IOA-MIB DEFINITIONS ::= BEGIN                                                                                                                       
-- "This file contains the enterprise specific traps (SNMPv1) sent by 
--  Control-M and Control-O on the Mainframe."  
                             
IMPORTS                    
        TRAP-TYPE                                                         
               FROM RFC-1215             
        OBJECT-TYPE                                                       
               FROM RFC1155-SMI        
        DisplayString                     
               FROM RFC1213-MIB;
                                                
-- The OBJECT ID definitions of the enterprise:  
                                                                          
IOA            OBJECT IDENTIFIER ::= { enterprises 954 } 
IOAtraps       OBJECT IDENTIFIER ::= { IOA 512 }                          
                                                                          
-- The three specific traps that can be sent:  
                        
veryurgentTrap TRAP-TYPE 
       ENTERPRISE IOAtraps
       VARIABLES { product,monitor,text } 
       DESCRIPTION "very urgent trap"    
       ::= 1                       
                     
urgentTrap TRAP-TYPE       
       ENTERPRISE IOAtraps                  
       VARIABLES { product,monitor,text }                                 
       DESCRIPTION "urgent trap"       
       ::= 2            
                                          
regularTrap TRAP-TYPE                       
       ENTERPRISE IOAtraps                                                
       VARIABLES { product,monitor,text }                                 
       DESCRIPTION "regular trap"                                         
       ::= 3                                                              
-- The three variables that are included in each trap:                    
                                                                          
product OBJECT-TYPE                                                       
        SYNTAX DisplayString                                              
        ACCESS read-only                                                  
        STATUS mandatory                                                  
        DESCRIPTION "This is the product name, CONTROL-M or CONTROL-O"    
        ::={IOAtraps 1}                                                   
                                                                          
monitor OBJECT-TYPE                                                       
        SYNTAX DisplayString                                              
        ACCESS read-only                                                  
        STATUS mandatory                                                  
        DESCRIPTION "This is the job name of the CONTROL-M/O monitor"     
        ::={IOAtraps 2}                                                   
                                                                          
text   OBJECT-TYPE                                                        
        SYNTAX DisplayString                                              
        ACCESS read-only                                                  
        STATUS mandatory                                                  
        DESCRIPTION "This is the actual text (message) of the trap"       
        ::={IOAtraps 3}                                                   
 END

Support for SNMPv3 Traps

Control-O and Control-M support SNMPv3 traps by activating the SNMP SUBAGENT feature. When activated, SNMP messages that are generated by DO SNMP statements in Control-O rules or DO SHOUT to U-S statements in Control-M rules, are sent to an SNMP Master Agent.

The SNMP Master Agent is an SNMPD or OSNMPD Server on an OS/390 or z/OS computer, which usually runs on the same mainframe on which Control-O or Control-M resides. Once the messages are received by an SNMP Master Agent, they are forwarded to the SNMP TRAP listeners defined during setup of the SNMP Master Agent.

When the SUBAGENT feature is activated, Control-O and Control-M take on the role of an SNMP sub-agent. Control-O or Control-M send the SNMP traps to the Master Agent, and the Master Agent sends the traps to the SNMP listeners.

The communications between Control-O or Control-M, and the SNMP Master Agent, are carried out by UDP and TCP/IP. The protocol used to communicate with the SNMP Master Agent is the Distributed Protocol Interface (DPI) V1.1.

Activating the SNMPv3 Traps Feature

1. Activate this feature by changing the MODE statement in the IOAPARM member to MODE=SUBAGENT. This can be performed through ICE in the following step:

   • IOA Customization

   • Major step: 1 IOAPARM Post-Installation

   • Minor Step: 3 Specify parameters for "Mail" options

2. Additionally, specify valid values for the following SNMP parameters in IOAPARM:

   • host is the hostname or IP address of the host where the Master Agent runs
     Default: 127.0.0.1 (the local host)

   • port is the SNMP port on which the Master Agent listens for SNMP requests Default: 161

   • community is the community name defined in the Master Agent setup
     Default: public

When a MODE=SUBAGENT statement is specified in the IOAPARM member then all other NICK and GROUP statements in the SNMPDEST member are ignored.

If MODE is not set to SUBAGENT then it must be set to any other non-blank value, such as MODE=ALONE.

You can switch between activating and deactivating SUBAGENT MODE by changing the MODE parameter and recycling the corresponding monitor(s). If Control-M is used for sending SNMP traps, stop Control-M monitor and then restart it. If Control-O is used for sending SNMP traps, start a new Control-O monitor without stopping the currently running Control-O monitor.

Replacing the Current Destination Tables

When you want to modify or replace either the Dynamic Destination table or the Mail Destination table, you must follow the procedures described in this section.

Replacing the Dynamic Destination Table (IOADEST)

The Dynamic Destination table is loaded when the respective INCONTROL product monitor is started. To replace the current Dynamic Destination table with a new one, use the appropriate operator command for each INCONTROL product installed at your site, as described in the following table:

Table 53 Operator Commands for Replacing the Dynamic Destination member

The IOADEST table is reloaded and an accompanying message is displayed on the operator console from which the modify command was issued, when the monitor resumes job processing.

Mail Destination Table (MAILDEST)

The Mail Destination table is loaded when the INCONTROL product monitor is started. To replace the current Mail Destination table with a new one, use the appropriate operator command for each INCONTROL product installed at your site.

Table 54 Operator Commands for Loading a New Mail Destination Table

F CONTROLM,NEWMAILDST

F CONTROLO,NEWMAILDST

F CONTROLD,NEWMAILDST

After a few seconds, a message about the result of the operation is displayed on the operator console from which the modify command was issued.

Message Destination Parameters in IOAPARM

After completing installation, but before sending messages, you must define the appropriate parameters in the IOAPARM member in the IOA PARM library. For email messages, specify the parameters in the MAIL section of IOAPARM describe in the table. For SNMP messages, specify the parameters in the SNMP section of IOAPARM described in the second table. A sample MAIL section of the IOAPARM member is shown below.

Table 55 Parameters in the MAIL section of the IOAPARM member

Table 56 Parameters in the SNMP section of the IOAPARM member

Figure 5 Sample MAIL section in IOAPARM

 *-------------------------------------      
 *        MAIL parameters                        
 *-------------------------------------           
 MAIL     SMTPNAME=SMTP,           Name of SMTP STC       
 * The suffix of company's mail address:
           DFLTSFFX=BMC.COM,                                
 * Reply-To Email Address:          
          DFLTRPTO=bmc@hotmail.com,   
          DFLTSNDR=bmc_sender,     The default 'From' name   
          OWNRSUFX=,               To be appended to DFLTSNDR   
          HOSTNAME=MVS3,           Host Name                       
          CLASS=A,                 Class of SMTP sysout  
          DEST=LOCAL,              Destination for mail            
          FORM=,                   FORM name for sysout    
          ENVELOPE=IBM,            EMAIL format: IBM or CA      
          TIMEZONE=,               Indicates the time zone       
          ATSIGN=@,                Separator the owner from domain 
          ATCHSET=ISO-8859-1,      Character set           
          ATCHENC=8                Character encoding    
 *-------------------------------------              

General IP parameters

The IP section in IOAPARM affects the following components:

• SNMP

• Immediate PC file transfers from online (Option U).

• Delayed PC file transfers by Control-D File Transfer Monitor.

Table 56a Parameters in the IP section of the IOAPARM member

IOAMAIL

IOAMAIL can be called by Control‑M and Control‑M/Analyzer, using appropriate subparameters under the DO MAIL or DO SHOUT parameters in a job scheduling definition.

IOAAPI can also be used as an entry point to the IOAMAIL facility. For more information on IOAAPI, see IOAAPI.

Specifying a MAIL Destination

The destinations for e-mail messages sent by IOAMAIL can be specified using several methods, enabling you to send a single e-mail message to several destinations. Different methods can be used for the destinations.

IOAMAIL e-mail destinations can be specified using:

• a fully specified destination name

  • Example: joe_smith@acme.com

• a user name, without specifying any more information

  • IOAMAIL uses the DFLTSFFX parameter in the IOAPARM member as the default suffix for the user name. The result is a fully specified destination name.

  • Example

  • If you specify joe_smith, and the default suffix in the DFLTSFFX parameter is acme.com, IOAMAIL completes the resulting e-mail address as joe_smith@acme.com. (Note that the @ character is taken from the ATSIGN parameter in the IOAPARM member.)

• a nickname, without specifying any more information

  • IOAMAIL searches for the nickname in the set of predefined nicknames in the MAILDEST member. Each nickname and full e-mail address are specified in separate lines in that member.

  • For example, if Joe Smith has the e-mail address joe_smith@acme.com, and is to be given the nickname JOE, the definition will appear in the MAILDEST member as

  • NICK=JOE
    ADDR=JOE_SMITH@ACME.COM

  • If the destination of an IOAMAIL e-mail is then specified as joe, the e-mail address results in joe_smith@acme.com.

• a GROUP name, without specifying any more information

  • Each IOAMAIL GROUP consists of a group of e-mail recipients. Such a group can comprise any number of e-mail destinations. Each such destination can be defined by reference to

• a full e-mail address

• a user name, where the DFLTSFFX parameter in the IOAPARM member is used as the suffix

• an IOAMAIL nickname specified as described above

Each destination must be prefixed with the notation TO or CC. When prefixed TO, the e-mail is sent to that destination as an addressee. When prefixed CC, the e-mail is sent to that destination as a copy.

For more information on the MAILDEST member, see The Mail Destination Table

IOA support for DO REMEDY

The DO REMEDY option in Control-M for z/OS enables creation of a problem ticket in the Remedy Help Desk system by sending a formatted e-mail to a special mailbox that is defined for this purpose. For more information about the DO REMEDY option, see the Control-M for z/OS User Guide.

The Remedy Email Engine reads the incoming message sent to this mailbox and creates problem tickets in the Remedy system, according to the details in each message.

To set up IOA support for DO REMEDY

1. Create an account on a POP3 mail server (for example, Microsoft Exchange Server) and record the following details:

   • Server name or IP address of the POP3 server (for incoming mail)

   • Server name or IP address of the SMTP server (for outgoing mail)

   • Server port number used for connecting to the POP3 server (for incoming mail)

   • Server port number used for connecting to the SMTP server (for outgoing mail)

   • Mailbox name and password

   • E-mail address of this new account

   BMC recommends that you ensure that the new mail account has been set up correctly by trying to access the account from Microsoft Outlook. In Outlook, select Tools=> E-mail Accounts=> Add a new E-mail account=> POP3. After you have filled in the details, press Test Account Settings.

2. Install and configure the Remedy Email Engine.

   • Ensure that the Java SDK is already installed on the computer where the Remedy Email Engine will be installed.

   For detailed instructions about installing the Remedy Email Engine, see the Action Request System 6.3 Remedy Email Engine Guide.

   Remedy Email Engine configuration guidelines

   • Do not specify an RPC port during the first part of the Remedy Email Engine installation.

   • Define the same name for the incoming and outgoing mailboxes during the mailbox configuration part of the Remedy Email Engine installation.

   • When you configure the Remedy Email Engine, specify only the host name (without the domain name) as the SMTP server.

   • BMC recommends that until DO REMEDY has been tested to work successfully, instead of starting the Remedy Email Engine as a service, start it by running the following batch file. Set the debug flag so that debugging messages will go to the command window.

     Edit the emailstart.bat file and add the -Dmail.debug=true option after "%JavaPath%\java":

     Copy

     "%JavaPath%\java" -Dmail.debug=true -cp
     emaildaemon.jar;arapi63.jar;arutil63.jar;activation.jar;mail.jar;imap
     .jar;smtp.jar;pop3.jar;armapi63.jar
     com.remedy.arsys.emaildaemon.EmailDaemon

     The default location of the emailstart.bat file is C:\Program Files\AR System\AREmail.

   • There are additional parameters in the Remedy Email Engine mailbox configuration that cannot be set up in the initial prompt windows. You can access the setup values later by selecting Start=> Programs=> Action Request System=> ARSystem User. After logging on, perform the following steps:

     1. Select Open=> Find and specify AR System Email Mailbox Configuration.

     2. Select the entry that has type Form and click the Search icon. This process should find two mailboxes: Incoming and Outgoing.

     3. Select the Incoming mailbox and change Polling Interval (Minutes) to 1.

     4. Press Advanced Configuration.

     5. Change Reply With Result to No and save your changes.

     6. Restart the Remedy Email Engine.

3. Copy members REMCONFD and REMTMPL from the IOA.BASE.GENERAL library to the IOA.PARM library.

4. Create a copy of REMCONFD in the IOA.PARM library, and name it REMCONF.

5. Configure the parameters in member REMCONF, as described in REMCONF member.

6. Create a copy of REMTMPL in the IOA.PARM library, and name it REMTMPLx, where x is the suffix specified in the REMTPLS parameter of the REMCONF member.

7. Configure the email template in the REMTMPLx member, as described in REMTMPLx member.

8. Define the nickname and email address defined in REMMAIL parameter of REMCONF member in the MAILDEST member (see note below).

9. Recycle the Control-M Monitor.

Understanding the DO REMEDY configuration members

The Remedy interface contains the following configuration members:

• REMCONF member contains general customization parameters for Remedy. For details, see REMCONF member.

• REMTMPLx member or members contain formatted email templates. For details, see REMTMPLx member.

REMCONF member

The REMCONF member contains general customization parameters for Remedy.

The REMCONF member contains separate sections for the different IOA products. Each section begins with the COMPID field, and all parameters that follow that field relate to the product specified in it.

A sample member named REMCONFD is provided in IOA.BASE.GENERAL library, which must be manually copied as REMCONF in order to use it. A default REMCONF member is not provided, to avoid overwriting. An asterisk in column 1 indicates a comment.

Table 57 REMCONF parameters

Sample REMCONF member

The values specified in the REMTRNx parameter are used to replace the URGENCY value specified in the rule Control-M rule with the value that should be used in the Remedy ticket. Refer to "%%URGENCY%%" in REMTMPLx member.

***************************************************************
** REMCONF - Remedy Interface Configuration                  **       
**                                                           **       
** The member should be copied as REMCONF and to reside in   **       
** the IOA.PARM library.                                     **       
**                                                           **       
** Please refer to the INCONTROL for z/OS Administrator      **  
** Guide for more information.                               **       
**                                                           **       
** Notes:                                                    **       
** ------                                                    **       
**                                                           **      
** (1) A sample of the a Remedy Email template (pointed by   **       
**     the REMTMPLS= parameter) can be found in member       **       
**     REMTMPL.                                              **       
**                                                           **       
** (2) Use the following REMTRNx settings for                **       
**     Remedy release 6:                                     **       
**                                                           **       
**       REMTRNL='Low'                                       **       
**       REMTRNM='Medium'                                    **       
**       REMTRNH='High'                                      **       
**       REMTRNU='Urgent'                                    **       
**       REMTRNB='Medium'                                    **       
**                                                           **       
**     Use the following REMTRNx settings for                **       
**     Remedy release 7:                                     **       
**                                                           **       
**       REMTRNL='4-Low'                                     **       
**       REMTRNM='3-Medium'                                  **       
**       REMTRNH='2-High'                                    **       
**       REMTRNU='1-Urgent'                                  **       
**       REMTRNB='3-Medium'                                  **       
**                                                           **       
** (3) Email nick name defined by parameter REMMAIL= should  **       
**     be defined in member MAILDEST.                        **       
**                                                           **       
***************************************************************       
**                                                                    
** Control-M Section                                                  
**                                                                    
  COMPID=M                                                            
    REMMAIL=CTMRMDY                                                   
    REMMSUB=                                                          
    REMTMPLS=M                                                        
    REMTRNL='Low'                                                     
    REMTRNM='Medium'                                                  
    REMTRNH='High'                                                    
    REMTRNU='Urgent'                                                  
    REMTRNB='Medium'                                                  

The sample REMCONFD member is similar.

REMTMPLx member

The REMTMPLx member holds the email template to be used for opening a ticket in Remedy. The REMTMPLS parameter in the REMCONF member points to the REMTMPLx email template member, where x is a free suffix pointing to the required member.

Basic configuration information (such as Remedy server name, schema name, user name, and password) is an integral part of the template.

The member supports mixed case characters (CAPS OFF).

Each line is limited to 70 alphanumeric characters.

A sample template named REMTMPL is provided, and includes separate samples to be used with Remedy 6 and Remedy 7. Instructions on how to configure the member, including the configuration parameters, are included as comments. The sample must be manually copied as REMTMPLx, where x is the suffix specified in the REMTPLS parameter.

The email will be sent to the address pointed by the nickname specified in the REMMAIL parameter, and the email subject is set as specified in the REMMSUB parameter (both of which are located in the REMCONF member).

When the email is built, the template strings are replaced with the values as described in the table.

Table 58 REMTMPL template variables

Sample template

******************************************************************** 
** REMTMPLx - Remedy Email Template                               **  
**                                                                **  
** This is a sample of a Remedy Email template to be used in      **  
** order to open a ticket in Remedy.                              **  
**                                                                **  
** The email template should reside in IOA.PARM library and to    **  
** be named as REMTMPLx where x is the charater specified in      **  
** parameter REMTMPLS= in member IOA.PARM(REMCONF).               **  
**                                                                **  
** This sample includes 2 separate sections:                      **  
**  - The first section should be used with Remedy release 6.     **  
**  - The second section should be used with Remedy release 7.    **  
**                                                                **  
**----------------------------------------------------------------**  
** Steps needed to be done to customize the template:             **  
**                                                                **  
** a.  Select the sample appropriate to your Remedy               **  
**     level (6 or 7).                                            **  
**                                                                **  
** b.  Remove (or comment using an asterisk in column 1)          **  
**     the sample related to the Remedy level not used on         **  
**     your site.                                                 **  
**                                                                **  
** c.  Fill in the customization parameters as defined in         **  
**     your site:                                                 **  
**                                                                **  
**      - The Remedy schema name used for opening the ticket      **  
**      - The Remedy server name                                  **  
**      - The Remedy user name                                    **  
**      - The Remedy User password                                **  
**                                                                **  
** d. Add additional Remedy fields that are required on           **  
**    on your site as additional lines at the bottom of           **  
**    the template.                                               **  
**                                                                **  
** e. The member should be placed in the IOA.PARM library         **  
**    and to be named REMTMPLx where X is the suffix              **  
**    specified in parameter REMTMPLS in member REMCONF           **  
**    which resides in the same library.                          **  
**                                                                **  
** Please refer to the INCONTROL for z/OS Administrator           **  
** Guide for more information.                                    **  
**                                                                **  
********************************************************************  
** Remedy 6 sample                                                **  
** ---------------                                                **  
** Use the following section for Remedy release 6.                **  
** Don't forget to remove the section for Remedy release 7 below. **  
********************************************************************  
Schema: HPD:HelpDesk                                                  
Server: remsrvr                                                       
Login: Demo                                                           
Password:                                                             
Action: Submit                                                        
Format: Short                                                         
Summary* !        8!: %%SUMM%%                                        
Description* !240000007!: %%DESC%%                                    
Category* !200000003!: Software                                       
Type* !200000004!: Other                                              
Item* !200000005!: Other                                              
Login*+ !240000005!: %%USER%%                                         
Name*+ !240000001!: %%USER%%                                          
Source* !260000128!: Email                                            
Solution Details !260000503!:                                         
Status* !        7!: New                                              
Case Type* !260000130!: Incident                                      
Urgency !240000009!: %%URGENCY%%                                      
**                                                                    
********************************************************************  
** Remedy 7 sample                                                **  
** ---------------                                                **  
** Use the following section for Remedy release 7.                **  
** Don't forget to remove the section for Remedy release 6 above. **  
********************************************************************  
char-set: windows-1252                                                
Schema: HPD:IncidentInterface_Create                                  
Server: remsrvr                                                       
Login: Demo                                                           
Password:                                                             
Action: Submit                                                        
Description !1000000000!: %%SUMM%%                                    
Service Type !1000000099!: User Service Request                       
Status !         7!: New                                              
Details !1000000151!: %%DESC%%                                        
First Name* !1000000019!: App                                         
Last Name* !1000000018!: Admin                                        
First Name+ !1000005783!: %%USER%%                                    
Last Name+ !1000005782!: %%USER%%                                     
Impact* !1000000163!: 3-Moderate/Limited                              
Urgency* !1000000162!: %%URGENCY%%                                    
!1000000076!: CREATE                                                  
**                                                                    
********************************************************************  
** Version 7.6.04                                                 **  
** If you want to specify values for the First Name+ and          **  
** Last Name+ parameters in the REMTMPLx member, you must define  **  
** these values as user with valid First and Last names in Remedy,**  
** then remove the asterisks from the First Name+ and Last Name+  **  
** fields, and then specify values of the defined First and Last  **  
** names.                                                         **  
********************************************************************  
char-set: windows-1252                                                
Schema: HPD:IncidentInterface_Create                                  
Server: remsrvr                                                       
Login: Demo                                                           
Password:                                                             
Action: Submit                                                        
Description !1000000000!: %%SUMM%%                                    
Status !         7!: New                                              
Details !1000000151!: %%DESC%%                                        
First Name* !1000000019!: App                                         
Last Name* !1000000018!: Admin                                        
*Uncomment the  First Name+ and Last Name+ if defined in Remedy       
*First Name+ !1000005783!: %%USER%%                                   
*Last Name+ !1000005782!: %%USER%%                                    
Service Type !1000000099!:1                                           
Impact* !1000000163!: %%URGENCY%%                                     
Urgency* !1000000162!: %%URGENCY%%                                    
!1000000076!: CREATE                                                  
RepSource !1000000215!:email                                          

The sample REMTMPL member is similar.

In the sample provided for Remedy version 7.6.04, the lines for the First Name+ and Last Name+ parameters are commented out with asterisks (*) so that by default a Remedy ticket is produced.

If you want to specify values for the First Name+ and Last Name+ parameters in the REMTMPLx member, you must define these values as a user with valid first and last names in Remedy, then remove the asterisks from the First Name+ and Last Name+ fields, and specify the values of the defined First and Last names.

IOAAPI

IOAAPI, the IOA Application Program Interface, provides an interface to some IOA services.

Supported Services

IOAAPI currently supports the services described in the following table:

Table 59 Services Supported by IOAAPI

Access to IOAAPI

IOAAPI can be accessed by the following means:

• a batch program

• a batch statement

• use of the TSO command processor

• a user application program

Service Types Syntax

A service call is made using the following syntax:

service_type service_parms

where

• service_type is one of the supported services

• service_parms are parameters sent along with the service_type

To write a comment in a call string, place an * (asterisk) before the first character. Use this technique if, for example, you want a call string to be omitted from one run of a job.

COND Service

The following is the syntax of a request for the COND service:

COND request_type condition_name date

where:

• request_type is one of the following types of request:

  • ADD

  • DELETE

  • CHECK

    • condition_name is the name of the condition, from 1 through 40 characters

    • date is the date in mmdd format

Return Codes

The ADD request returns condition code 0 when successfully executed and the condition code does not exist. If the condition_name already exists, the condition code is 8.

The DELETE request returns condition code 0 when successfully executed and the condition name exists, unless there was no condition_name, in which case the condition code is 8.

Details of all the COND return codes appear in the following table:

Table 60 IOAAPI COND Return Codes

Examples

COND ADD A_LONG_CONDITION_NAME 0822
COND DELETE CONDITION_ALPHA 1231
COND CHECK ANY-CONDITION 0407

MAIL Service

Before using this service, ensure that you are familiar with IOAMAIL.

The MAIL service can only be used in batch and API runs.

The following is the syntax of a request for the MAIL service:

MAIL request_type(content)

where

• request_type is one of the types of request shown in the following table

• content of the request type, as explained under "Description" in the following table

Table 61 MAIL Request Types

Return Codes

Details of all the MAIL return codes appear in the table.

Table 62 IOAAPI MAIL Return Codes

MAIL TO JOHN_D@ACME.COMMAIL TO GEORGE
MAIL CC CLARA
MAIL SUBJ subject-header-text
MAIL TEXT text-line1
MAIL TEXT text-line2
MAIL TEXT text-line3
MAIL SEND

LOG Service

The LOG service can only be used in batch and API runs. The syntax of a request for the LOG service is

LOG request_type [parm1] [parm2]

where

• request_type is one of the types of request shown in the tablebelow

• parm1 and parm2 depend on the type of request specified as request_type

Table 63 LOG Service Request Types

DATE BETWEEN yymmdd AND yymmdd

TIME BETWEEN hhmm AND hhmm

CODE IN code1 code2 code3 ...

CODE NOT IN code4 code5 code6 ...

FILE ddname

Return Codes

Details of all the LOG return codes appear in the table.

Table 64 IOAAPI LOG Return Codes

LOG DATE BETWEEN 010815 AND 010831
LOG TIME BETWEEN 0800 AND 1800
LOG CODE IN SEL154L SQR606I
LOG CODE IN YQR312I
LOG FILE MYFILE
LOG FIND

Using a Batch Program

Within a batch program, a service request is submitted as the PARM field specification in an EXEC statement.

//EXAM1      EXEC PGM=IOAAPI
//     PARM=’COND ADD COND1 0401’
//STEPLIB DD DISP=SHR,DSN=dataset1
//     DD DISP=SHR,DSN=dataset2
//DAAPIOUT DD SYSOUT=*
//DAPARM DD DISP=SHR,DSN=dataset3
//DACNDF DD DISP=SHR,DSN=dataset4
//DALOG DD DISP=SHR,DSN=dataset5

where

• dataset1 and dataset2 are STEPLIB libraries, set on installation

• dataset3 is the Parameters Dataset file, and is mandatory

• dataset4 is the Conditions file used for COND requests

• dataset5 is the Log file used for LOG requests

Only one request can be made in a batch program.

Using Batch Statements

Requests are passed as an input file. Each record is 80 bytes in length, but only the first 71 bytes are used.

//EXAM2     EXEC PGM=IOAAPI
//STEPLIB DD DISP=SHR,DSN=dataset1
//     DD DISP=SHR,DSN=dataset2
//DAAPIOUT DD SYSOUT=*
//DAPARM DD DISP=SHR,DSN=dataset3
//DACNDF DD DISP=SHR,DSN=dataset4
//DALOG DD DISP=SHR,DSN=dataset5
//DAAPIPRM DD *
     COND DELETE COND2 0115
     COND ADD COND3 0701
     COND CHECK COND4 1231
     MAIL TO USER2
     MAIL CC USER3@ACME.COM
     MAIL SUBJ RUN ENDED
     MAIL TEXT RUN OF TODAY FINISHED OK
     MAIL SEND
     LOG DATE BETWEEN 010401 AND 010415
     LOG CODE IN MTO356I MTO357I
     LOG FILE PRINT
     LOG FIND
//

Conditional Input

Requests passed from a batch statement can be conditional, using the following syntax:

IF LASTCC condition number THEN
      statement_1
      statement_2
      statement_3
      .....
ELSE
      statement_4
      statement_5
      statement_6
      .....
ENDIF

where

• LASTCC is the condition code returned by the last executed request

• condition is either EQ (Equal) or NE (Not Equal)

• number is a numeric value from 1 through 3 digits, for example 4, 04, or 004

Tokens in the IF statement must be separated by blanks. Nested IF statements are not supported. The whole IF statement must reside in the same input record.

ELSE and its group of statements are optional. If used, it must be the only token in a record.

ENDIF must be the only token in a record.

COND CHECK CONDITION_A 0104
IF LASTCC EQ 8 THEN
     COND ADD CONDITION_A 0104
ELSE
     COND ADD CONDITION_B 0104
     MAIL TO USER1
     MAIL TEXT CONDITION_B ADDED
     MAIL SEND
ENDIF

Using the TSO Command Processor

A request can be made using the TSO command processor. The command is passed as a PARM to the command processor.

The format of the command is

IOAAPI COND condition_request condition_name date

Using a User Application Program

Any number of requests can be made using a user application program.

In this guide, CLnn means a character field nn characters in length, padded with blanks to the right.

When the request is made, the following array of addresses is passed:

• A(string1), where string1 is CL8'IOAAPI'

• A(MCTADDR)

• A(string2), where string2 is one of the following, as appropriate:

  • CL8'COND'

  • CL8'MAIL'

  • CL8'LOG'

In the case of each of the services to which these strings refer, that is, COND, MAIL, and LOG, additional addresses are passed. These additional addresses vary according to the service requested, as explained in the following sections.

COND Service Additional Addresses

For more information on the COND service, see COND Service.

The additional addresses that are passed when the COND service is requested are:

• A(string3C), where string3C is CL8'request_type'

• A(string4C), where string4C is CL39'condition_name'
  A(string5C), where string5C is CL4'date'

The request_type, condition_name, and date strings have the meanings explained in COND Service.

MAIL Service Additional Addresses

For more information on the MAIL service, see MAIL Service.

Additional addresses that are passed when the MAIL service is requested are:

• A(string3M) where string3M is CL8'request_type'

• A(string4M) where string4M is CL70' content'

The request_type and content strings have the meanings explained in MAIL Service.

LOG Service Additional Addresses

For more information on the LOG service, see LOG Service.

The additional addresses that are passed when the LOG service is requested depend on the request type, as follows:

• A(string3L) where string3L is CL8'request_type'

• A(string4L) and A(string5L)

where

• request_type is one of the LOG request types described in LOG Service.

• the contents of string4L and string5L depend on the type of request specified in string3L as the request_type, as explained in LOG Service.

DATE Request Type Additional Addresses

In the case of the DATE request type, the additional addresses are as follows:

• A(string3LD), where string3LD is CL8'DATE'

• A(string4LD), where string4LD is the DATE BETWEEN ("from") date in the format CL8'yymmdd'

• A(string5LD), where string5LD is the DATE AND ("until") date in the format CL8'yymmdd'

For more information on DATE, DATE BETWEEN, and DATE AND, see LOG Service.

TIME Request Type Additional Addresses

In the case of request type TIME, the additional addresses are as follows:

• A(string3LT), where string3LT is CL8'TIME'

• A(string4LT), where string4LT is the TIME BETWEEN ("from") time in the format CL8'hhmm'

• A(string5LT), where string5LT is the TIME AND ("until") time in the format CL8'hhmm'

For more information on TIME, TIME BETWEEN, and TIME AND, see LOG Service

CODE Request Type Additional Addresses

In the case of request type CODE, the additional addresses are as follows:

• A(string3LC), where string3LC is CL8'CODE'

• A(string4LC), where string4LC is either CL8'IN' or CL8'NOT IN'

• A(string5LC), where string5LC is CL70'code1 code2 code3 ...'

For more information on CODE, IN, and NOT IN, see LOG Service.

FILE Request Type Additional Addresses

In the case of request type FILE, the additional addresses are as follows:

• A(string3LFL), where string3LFL is CL8'FILE'

• A(string4LFL), where string4LFL is CL8'ddname'
  The string ddname is a DDname of up to 8 characters, and is fully explained, together with its default value of PRINT, in LOG Service.

RECORD Request Type Additional Addresses

In the case of request type RECORD, there is a single additional address, namely, A(string3LR), where string3LR is CL8'RECORD'.

For more information, see LOG Service.

FIND Request Type Additional Addresses

In the case of request type FIND, there is a single additional address, namely, A(string3LFN), where string3LFN is CL8'FIND'.

For more information, see LOG Service.

NEXT Request Type Additional Addresses

In the case of request type NEXT, there is a single additional address, namely, A(string3LN), where string3LN is CL8'NEXT'.

For more information, see LOG Service

IOA Variable Database Facility

The IOA Variable Database facility is comprised of a series of screens and a set of files that enable you to view, create and modify AutoEdit variables that are made available globally to INCONTROL products.

The IOA Variable Database facility is available to Control‑M only with the CMEM monitor active, or when the Control‑O monitor is active.

IOA variable databases are stored in a common storage area on a computer, and are organized into databases. Changes to the value of an AutoEdit variable in an IOA variable database can be accessed by all Control‑M jobs or Control‑O rules on that computer, or, if desired, in the Sysplex if that computer is part of a Sysplex.

When an INCONTROL product starts, the product reads the databases defined in the IOA Variable Database facility and loads the databases’ AutoEdit variables into memory.

Control‑O users can create and access an unlimited number of AutoEdit databases. Other INCONTROL products, such as Control‑M, can only access one AutoEdit database, named IOAVAR.

IOA Variable Database facility databases are specified in the global member list, which is the list of members referenced by DD statement DAGLBLST of the INCONTROL product monitor procedure (currently, either CONTROLO or CTMCMEM). For more information about the global member list, see Defining a New Database.

The IOA Variable Database facility consists of the following files, which are allocated during IOA installation. These files are used to copy information into memory on each computer in which an INCONTROL product is working.

Table 65 IOA Variable Database Facility Files

The IOA Variable Database facility files are IOA Access Method files. Each file consists of two operating system files: a data component and an index component. For more information about the IOA Access Method, see IOA Concepts and Components.

Updates and additions made to the AutoEdit variables directly in memory (such as by rules or KOA scripts) are kept in memory by the INCONTROL product and are available to all other jobs, rules, and so on. While the INCONTROL product is active, a specific database (or all databases) can be reloaded from or written to the IOA Variable Database facility files using operator commands LOADGLOBAL and WRITEGLOBAL. When the INCONTROL product is stopped, command WRITEGLOBAL is automatically performed to update all databases with the latest information.

If Control‑O is installed, the CMEM facility is executed by the Control‑O monitor instead of the CMEM monitor. In this case, references in this section to the CMEM monitor apply to the Control‑O monitor, and operator commands contain the string CONTROLO instead of CTMCMEM.

Also, AutoEdit databases are not stored as partitioned datasets. Therefore, the AutoEdit variables stored in these databases cannot be accessed by Control‑M %%LIBSYM and %%MEMSYM control statements. For Control‑M to access these variables, you must explicitly state its path name and variable name in job definition statements such as SET VAR and DO SET.

The complete format for accessing an AutoEdit variable stored in a database is

%%\<product>\<application>\<group>\<memname>\varname>

When specifying the name of an AutoEdit variable, you can use shortcuts. For example, if the variable is in the current directory, you do not need to specify the entire path name (the variable name alone suffices). For more detailed information on the path name, see Displaying the Values of Databases Screen.

Availability and Implementation Across INCONTROL Products

The IOA Variable Database facility is available for the following INCONTROL products:

Table 66 Availability of the IOA Variable Database Facility

IOAVAR Database

The IOAVAR database, which is loaded into memory because it is specified in member IOAGLBVL in the IOAENV library, is unlike other databases in the IOA Variable Database facility.

• It is the only database that ControlM can access.

• It is the only database that CMEM or Control-O automatically issues the WRITEGLOBAL command, after changes are made to the database in-memory, to ensure that the disk version is up-to-date.

• It consists of a series of variable names and corresponding variable values, instead of user-defined rows and columns (fields).

The IOAVAR can be defined as either DBINOUT (standard database) or S2INOUT (XAE Type 2 database) in member IOAGLBVL in the global member list (the concatenation of files specified in DD statement DAGLBLST).

When using IOAVAR in a Sysplex environment consisting of multiple LPARs, define IOAVAR as S2INOUT. XAE allows for resolution of variables on a Sysplex-wide level by utilizing Coupling Facility structures.

When using IOAVAR on a single LPAR it should be defined as DBINOUT.

WARNING: Loading IOAVAR defined as DBINOUT in multiple LPARs in a Sysplex creates a serious integrity exposure. It may result in each LPAR having a different image of the database (different variables names, different variable values) and in one LPAR overwriting the other LPAR’s database when issuing WRITEGLOBAL (automatically or manually).

For more information about the global member list and XAE databases, see Defining a New Database and Using XAE Type Databases Instead of Standard Type Databases, respectively.

Sharing the Global Variables database

The IOA and Control-O Global Variables database can be shared between Control-M, Control-O, online users, the Control-M application server, IOA APIs, and Control-O XAM. The Control-O or CMEM monitors using shared disks in non‑SYSPLEX environments and in the Coupling Facility in SYSPLEX, can share the Global Variables database. The global variables are loaded and held in memory, which is separate on each LPAR where Control-O or CMEM is being run.

Navigating and Using the IOA Variable Database Facility

To enter the IOA Variable Database facility, select option IV in the IOA Primary Option menu. The IOA Variables entry panel is displayed.

Figure 6 IOA Variables Entry Panel

 ----------------------- IOA Variables - ENTRY PANEL  ---------------------
(IVCOMMAND ===>                                                               
                                                                           
                                                                           
SPECIFY DATABASE NAME                                                      
                                                                           
DATABASE ===>                 (Blank for Database selection list)          
                                                                           
                                                                           
MODE     ===>                 (Blank or ADMIN for Administration mode)     
                                                                           
                                                                           
                                                                           
USE THE COMMAND "SHPF" TO SEE PFK ASSIGNMENT                         16.21.43

• To display the list of all databases: Press Enter. The List of Databases screen is displayed. For more information, see List of Databases Screen.

• ControlO installations can access an unlimited number of databases. ControlM and other INCONTROL product installations can access the IOAVAR database only (even if other databases are displayed).

• To display the Values of Database screen of a specific database: Type the database name in the DATABASE field on the Entry Panel and press Enter.

• An asterisk (*) can be used as a mask character in the DATABASE field of this screen.

When entering either the List of Databases screen or the Values of Database screen, you can either enter as a regular user or an administrator, as follows:

• To enter the IOA Variables Database facility as a regular user, leave the MODE field blank. This enables you to view and update variables in the databases, but you cannot perform administrative functions (add or delete variables).

• To enter the IOA Variables Database facility with full administrator functionality, type ADMIN in the MODE field.

  • Security module IOASE42 prevents regular users from accessing the IOA Variables Database facility as an administrator. For more information on this security module, see the INCONTROL for z/OS Security Guide.

  • In ADMIN mode, only those variables actually written to the IOA Global Variable database are displayed. For example, if using the SET command of the Control-M CTMAPI utility, you prepare a global variable to be written to the database, without subsequently issuing the CKP command, such a variable is not displayed in ADMIN mode.

List of Databases Screen

Figure 7 List of Databases Screen

LIST OF DATABASES -----  IOA VARIABLES IN USE  -----------------------------(IV)
COMMAND ===>                                                    SCROLL===> CRSR
OPT NAME                  DESCRIPTION                             
    COSALLMT              COSMOS - DEMO - METHODS DATABASE        
    COSALLPR              COSMOS - DEMO - PREREQUISITES DATABASE  
    COSIMGOB              COSMOS - DEMO - SYSIMAGE WORKING DATABAS
    IOAVAR                IOA GLOBAL VARIABLE DATABASE            
    PRDALLMT              COSMOS - PROD - METHODS DATABASE        
    PRDALLPR              COSMOS - PROD - PREREQUISITES DATABASE  
    PRDSTCOB              COSMOS - PROD - STC WORKING DATABASE    
    PRDSTCSD              COSMOS - PROD - STC SOURCE DATABASE     
    PRDVTMOB              COSMOS - PROD - VTAM WORKING DATABASE   
    PRDVTMSD              COSMOS - PROD - VTAM SOURCE DATABASE    
    TUTORIAL              AUTOEDIT DATABASES - TUTORIAL           
    XAES1D01              XESXAE - DEMO - S1 - TEMP               
    XAES1D02              XESXAE - DEMO - S1 - INPUT              
    XAES1D03              XESXAE - DEMO - S1 - PROT (S1PROT SAME A
    XAES1D04              XESXAE - DEMO - S1 - INOUT (S1INOUT SAME
    XAES2D01              XESXAE - DEMO - S2 - TEMP               
    XAES2D02              XESXAE - DEMO - S2 - INPUT              
    XAES2D03              XESXAE - DEMO - S2 - PROT (S2PROT SAME A
    XAES2D04              XESXAE - DEMO - S2 - INOUT              
===== >>>>>>>>>>>>>>>>>>>>>>>  NO MORE DATABASES  <<<<<<<<<<<<<<<<<<<<<< =====
OPTIONS:  S SELECT   I INSERT   U UPDATE   V VIEW VARS                08.15.55u

The List of Databases screen displays a list of the databases currently defined. This screen can be entered using the IOA Variables entry panel or when returning from the List of Columns screen. For more information, see List of Columns Screen.

A short description is displayed for each database. This description is specified either when creating a new database, or through Option U. For more information, see Options of the Values of Database Screen.

For a database to be loaded into memory, the database name must be specified in one of the members referenced and concatenated by the DAGLBLST DD statement of the product’s monitor.

Options of the List of Databases Screen

The following options, listed at the bottom of the screen, can be applied to any row in the List of Databases screen. Specify the desired option in the OPT field next to the database name, and press Enter.

Table 67 Options of the List of Databases Screen

List of Columns Screen

Figure 8 List of Columns Screen

LIST OF COLUMNS     IOA DATABASE FACILITY           DATABASE: COSSTCSD     (IV)
COMMAND ===>                                                    SCROLL===> CRSR
     OPT NAME ----------------------------------------------------------------------
         CPU
         OBJECT
         DESIRED
         ATIPL
         NOTIPL
         MODE
         CLASS
         GROUP
         APPL
         DETAIL
         DEBUG
===== >>>>>>>>>>>>>>>>>>   NO MORE COLUMNS IN DATABASE <<<<<<<<<<<<<<<<< =====
   
   
   
OPTIONS:  S SELECT   I INSERT                                          16.44.27

The List of Columns screen displays the list of columns in a database. This screen can be entered by specifying a database name in the IOA Database Facility entry panel, or by specifying option S (SELECT) next to a database name in the List of Databases screen. This screen is also displayed when returning from the Column Definition screen. For a description of this screen, see Column Definition Screen.

The column names listed on this screen represent variable names (also known as database attributes) used in the variable database. The variables listed in the Values of Database screen represent actual variable values. For a of this screen see Displaying the Values of Databases Screen.

This screen supports up and down scrolling conventions.

Options of the List of Columns Screen

The following options, listed at the bottom of the screen, can be applied to any row in the List of Columns screen:

Table 68 Options of the List of Columns Screen

Column Definition Screen

The Column Definition screen allows you to define and order columns. This screen can be entered by selecting either option S (SELECT) in order to edit or option I (INSERT) from the List of Columns screen.

For information on displaying and editing an existing column definition, see Displaying and Editing a Column Definition.

For information on defining a new Variable Database column, see Defining a New Variable Database Column.

Because the column names VARNAME and VALUE in the IOAVAR database are fixed, this screen is only useful for INCONTROL products that can access multiple databases, such as Control‑O.

Displaying and Editing a Column Definition

To display and edit information for a selected column, specify option S (SELECT) next to the preceding column name in the Column Definition screen, and press Enter. The IOA Column Definition screen is displayed:

Figure 9 Displaying Information in the IOA Column Definition Screen

---------------------------  IOA COLUMN DEFINITION  ---------------------(IV.S)
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
| NAME     TSOUSER                DATABASE TUTORIAL                           |
| CREATED    /  /   -   :  :      BY    M86                                   |
| COLUMN ORDER 2645134                                                        |
| DESC     TSO USERID                                                         |
============= >>>>>>>>>> BOTTOM OF COLUMN DEFINITION <<<<<<<<<<<< =============
                                                                              
 PLEASE FILL IN COLUMN DEFINITION                                      16.44.38

Edit any of the following fields in the Column Definition screen:

Table 69 Fields in the Column Definition Screen

To exit the Column Definition screen without implementing any changes, type CAN (CANCEL) in the COMMAND line and press Enter, or press PF04/PF16.

Inserting a New Variable Database

In the OPT field on the List of Databases Screen, enter I to insert a new variable database. The New Database window is displayed.

Figure 10 New Database Window

LIST OF DATABASES --  IOA DATABASE FACILITY   -----------------------------(IV)
COMMAND ===>    +-----------------------------------------------------------+  SR
  OPT NAME      |     SPECIFY A NAME AND DESCRIPTION FOR THE NEW DATABASE   |   
   I  COSALLMT  |                                                           |   
      COSALLPR  |   NEW DATABASE NAME                     CREATE    (Y/N)   |   
      COSIMGOB  |                                                           |   
      COSIMGSD  |   DESCRIPTION                                             |   
      COSSTCOB  |                                                           |   
      COSSTCSD  |   NUMBER OF ROWS 00000100                                 |   
      COSVTMOB  |                                                           |   
      COSVTMSD  +-----------------------------------------------------------+   
===== >>>>>>>>>>>>>>>>>>>>>>>  NO MORE DATABASES  <<<<<<<<<<<<<<<<<<<<<< =====
    
                                                                                   
    
                                                                                   
OPTIONS:  S SELECT   I INSERT   U UPDATE   V VIEW VARS                  12.04.36

The following fields are displayed in this window:

Table 70 Fields of the IOA Variable Database New Database Window

The new database is inserted after the database for which the I (INSERT) option was specified. The list of databases is alphabetized the next time the List of Databases screen is displayed.

New Variable Databases are added to the files on disk. To make variables in a new database immediately available to Control‑O rules, add the name of the new database to the DAGLBLST DD statement in the Control‑O Monitor procedure, and specify the following command:

F CONTROLO,LOADGLOBAL=dbname

where dbname is the name of the new database.

For more information, see Chapter Control-O.

To populate the new database with database columns, see Defining a New Variable Database Column.

Defining a New Variable Database Column

To define a new column for a variable database, specify option I (INSERT) next to the preceding column name in the List of Columns screen, and press Enter.

If you are defining a new column for a variable database that has not yet been populated, specify option I next to the blank column name in the List of Columns screen.

The IOA Column Definition screen is displayed. This screen enables you to define a new column to be added to the current variable database.

The IOA Column Definition screen is displayed. This screen enables you to define a new column to be added to the current variable database.

-----------------------  IOA   COLUMN DEFINITION  -----------------------(IV.S)
COMMAND ===>                                                    SCROLL===> CRSR
     +-----------------------------------------------------------------------------+
       NAME     OBJECT                 DATABASE COSSTCSD                           
       CREATED  08/08/00 - 16:51:51    BY    N25                                   
       COLUMN ORDER 0000000                                                        
       DESC                                                                        
============= >>>>>>>>>> BOTTOM OF COLUMN DEFINITION <<<<<<<<<<<< =============
   
   
   
      
PLEASE FILL IN COLUMN DEFINITION                                      16.51.51

The following fields are displayed in the Column Definition screen.

When defining a new column, values for fields CREATED, DATABASE and BY are automatically inserted and cannot be modified in this screen.

Table 71 Fields of the Column Definition Screen

To add the column, specify the necessary information and press Enter.

To exit this screen without adding a column to the variable database, specify CAN (Cancel) in the COMMAND field of this screen and press Enter.

Updating Database Descriptions

In the OPT field on the List of Databases Screen, specify U to update the description of a variable database. The Update Database Description Window is displayed.

Figure 12 IOA Variable Database Update Database Description Window

LIST OF DATABASES -----  IOA DATABASE FACILITY ------------------------------(IV)
COMMAND ===>      +-----------------------------------------------------------+SR
    OPT NAME      |          UPDATE THE DATABASE DESCRIPTION                  |
        CCCC      |                                                           |
        COSALLMT  |   DATABASE NAME COSDM2SR                UPDATE Y  (Y/N)   |
        COSALLPR  |                                                           |
        COSDM2AC  |   DESCRIPTION  THIS IS A SAMPLE DESCRIPTION               |
        COSDM2PR  |                                                           |
        COSDM3PR  |   NUMBER OF ROWS 00001000                                 |
        COSDM4PR  |                                                           |
        COSDM2RS  +-----------------------------------------------------------+
     U  COSIMGOB              COSMOS - SYSIMAGE OBJECTS
        COSIMGSD              COSMOS - VTAM OBJECTS SOURCE
        COSIMGSR              COSMOS - VTAM OBJECTS SOURCE
        COSMOSPR              COSMOS - PREREQUISITES DATABASE
        COSSTCOB              COSMOS - STC RUNNING OBJECTS
        COSSTCSD              COSMOS - STC OBJECTS SOURCE
===== >>>>>>>>>>>>>>>>>>>>>>>  NO MORE DATABASES  <<<<<<<<<<<<<<<<<<<<<< =====
   
   
 OPTIONS:  S SELECT   I INSERT   U UPDATE   V VIEW VARS                 08.41.55

The following fields are displayed in this window:

Table 72 Fields of the Update Database Description Window

Displaying the Values of Databases Screen

To enter this screen, type option V (VIEW VARS) in the List of Databases screen next to the database you want to display, and press Enter. The variables in the selected database are displayed.

Figure 13 Control-O Values of Database Screen

VALUES OF DATABASE: TUTORIAL                                             (IV.V)
COMMAND ===>                                                    SCROLL===> CRSR
ROW       NAME      TSOUSER   TELEXT                                          
                                                                              
00001000 JOHN      S01       125                                              
00002000 JOE       S02       225                                              
00003000 ALICE     S03       325                                              
00004000 PETER     S04       425                                              
00005000 BENJAMIN  S05       525                                              
======== >>>>>>>>>>>>>>> NO MORE ROWS FOR THIS DATABASE <<<<<<<<<<<<<< ========
                                                                              
OPTIONS:  Z ZOOM     I INSERT   D DELETE   R REPEAT                    16.34.46

The Values of Database screen displays all variables in the selected database.

The column names represent attributes that describe the variable. The rows represent actual values for this variable. Variable values are loaded into memory automatically at Control‑O or CMEM Monitor startup.

Standard up or down scrolling conventions are supported in this screen.

Use the scrolling PFKeys to scroll the information on the screen left (PF10/PF22) and right (PF11/PF23).

Display for Database IOAVAR Only

If you select the IOAVAR database, the following screen is displayed:

Figure 14 Control-M Values of Database Screen (Database IOAVAR)

VALUES OF DATABASE: IOAVAR                                               (IV.V)
COMMAND ===>                                                    SCROLL===> CRSR
ROW       VARNAME                                 VALUE
00022889 %%\M\DEBUG\WORK\MART                    N19GLB4                      
00023866 %%\M\DEBUG\WORK\VAR1                    N19GLOBAL                    
00024902 %%\M\DEBUG\WORK\VAR2                    N19GLB                       
00025863 %%\M\DEBUG\WORK\VAR3                    N19GLB1                      
00026943 %%\M\DEBUG\WORK\VAR4                    N19GLBVAR12345               
00027792 %%\M\DEBUG\WORK\VAR5                    N19GLB3                      
00028972 %%\M\DEBUG\WORK\VAR6                    N19GLB4                      
00029831 %%\M\DEBUG\WORK\N19GLTS1\VAR1           N19GLOBAL2                   
00030765 %%\M\DEBUG\VAR2                         N19GLOBAL3                   
00031985 %%\M\DEBUG\WORK\VAR7                    N19GLB2                      
00032972 %%\M\DEBUG\WORK\N19GLTS1\VAR8           GLBVAR7896                   
00033769 %%\M\DEBUG\VAR11                        N19GLB5                      
00034919 %%\M\DEBUG\WORK\PRM7                    IOA600                       
00035955 %%\M\DEBUG\WORK\PRM8                    ODATE                        
00036932 %%\M\DEBUG\WORK\PRM9                    DRIVER                       
00037778 %%\M\DEBUG\WORK\N19GLTS1\PRM10          GLBVAR7896                   
00038808 %%\M\DEBUG\TRAN                         IALL                         
======== >>>>>>>>>>>>>>> NO MORE ROWS FOR THIS DATABASE <<<<<<<<<<<<<< ========
                                                                               
OPTIONS:  Z ZOOM     I INSERT   D DELETE   R REPEAT                    14.21.37

For database IOAVAR, the Values of Database screen displays the following information about the variables in the database:

Table 73 Fields of the IOA Values of Database Screen

Row Numbers in the Values of Database Screen

Row numbers in a variable database are initially incremented by 1000.

• When a new row is inserted, it is assigned an intermediate number incremented by 100.

• Rows inserted between row numbers with a hundreds value are assigned numbers incremented by ten.

• Rows inserted between row numbers with a tens value are assigned numbers incremented by one.

For example, a row inserted immediately after row 2000 is assigned a number of 2100.

A maximum of 999 rows can be inserted between two original rows in a variable database. Row numbers can be refreshed (that is, they can be assigned new numbers incremented by 1000) as follows:

Unload the IOA Variable Database facility’s Variables file by running job IOAVARUL in the IOA JCL library. This job invokes utility IOADUL.

Reload the file by running job IOAVARLD in the IOA JCL library. This job runs utility IOADLD with parameter RENUM specified.

For more information about utilities IOADUL and IOADLD, see the INCONTROL for z/OS Utilities Guide.

Options of the Values of Database Screen

The following options can be applied to any row in the Values of Database screen (Screen IV.V). Specify an option in the first (leftmost) column of the screen and press Enter.

Table 74 Options of the Values of Database Screen

Variable Database Zoom Screen

The value of each variable can be up to 140 characters in length, but only the first eight characters of each variable value are displayed. The Variable Database Zoom screen enables display of the full variable value. To display the full variable value, specify option Z (Zoom) next to the desired row in the Display screen. The Zoom screen is displayed.

Figure 15 Variable Database Zoom Screen

VALUES OF DATABASE: COSALLMT ROW:  87932454                         (IV.V.Z)
COMMAND ===>                                                    SCROLL===> CRSR
     O NAME      VALUE
     U DESIRED   UP
     U CURRENT   UNKNOWN
     U DESIRED
     U OBJDB     COSVTMOB
     U ACTCLASS
     U METCLASS
     U METHOD    COSMET13
======== >>>>>>>>>>>>>>>> NO MORE COLUMNS IN THIS ROW <<<<<<<<<<<<<<<< ========
   
OPTIONS:  A ADDITIONAL INFORMATION                                     08.31.07

The following predefined display types are available for the Variable Database Zoom screen:

Table 75 Display Types of the Variable Database Zoom Screen

While in the Variable Database Zoom screen, the display type can be changed using the DISPLAY command. Format of the command is:

DISPLAY x

where x is the identifying letter for the desired type.

DISPLAY can be abbreviated to DI.

For a list of display types, enter DISPLAY ? to show the Display Options window. To select a display type in the window, specify S (SELECT) in the Option field next to the ID. To exit the window without selecting a display type, press PF03/PF15 (END).

DI B

The Default display of the Variable Database Zoom screen includes the first 64 characters of the value of each variable in the selected database row.

The following option is available in the Variable Database Zoom screen:

Table 76 Options of the Variable Database Zoom Screen

To exit the Variable Database Zoom screen without implementing any changes specify CAN (cancel) in the COMMAND line and press ENTER.

To enable changes to a variable database loaded in memory to be immediately accessible by Control‑O rules, the modified database must be reloaded by use of the following operator command:

F CONTROLO,LOADGLOBAL=dbname

WARNING: Issuing LOADGLOBAL is hazardous in a live system!

Changes to the databases (for example, through %%SET in JCL, DO SET, or SET VAR) are accumulated in memory and are written to disk during the next WRITEGLOBAL command (performed automatically for the IOAVAR database at set intervals). Between the changes and the WRITEGLOBAL command is a time window in which the LOADGLOBAL command will delete the changes. BMC recommends only using the LOADGLOBAL command for updating a database during a scheduled downtime.

Variables in a variable database can also be updated or modified using DO SET statements in Control‑O rules, or through SETOGLB statements in a KSL/KOA script. For more information, see DO SET in the parameters description chapter of the Control‑O User Guide.

Use the following operator command to save changes made to a variable database in memory:

F CONTROLO,WRITEGLOBAL=dbname

To exit the Variable Zoom screen without implementing any changes, type CAN (CANCEL) in the COMMAND line and press Enter.

Loading AutoEdit Variable Databases

Use one of the following operator commands to load an AutoEdit database into memory:

• If ControlO is not installed, use

  Copy

  F CTMCMEM,LOADGLOBAL[=dbname]

• If ControlO is installed, use

  Copy

  F CONTROLO,LOADGLOBAL[=dbname]

  where dbname indicates the databases to be loaded. Valid values:

  • name - The name of a specific database to load.

  • ALL - All databases listed in the concatenation referenced by DD statement DAGLBLST are loaded. If ControlO is being used, ControlO members are loaded.

  • <none> - Only the default member, $GLOBAL, is loaded.

WARNING: Issuing LOADGLOBAL is hazardous in a live system!

Changes to the databases (for example, through %%SET in JCL, DO SET, or SET VAR) are accumulated in memory and are written to disk during the next WRITEGLOBAL command (performed automatically for the IOAVAR database at set intervals). Between the changes and the WRITEGLOBAL command is a time window in which the LOADGLOBAL command will delete the changes. BMC recommends only using the LOADGLOBAL command for updating a database during a scheduled downtime.

Updating AutoEdit Variable Databases

Use one of the following operator commands to update an AutoEdit variable database with the current status of the AutoEdit variables in memory:

• If ControlO is not installed, use

  Copy

  F CTMCMEM,WRITEGLOBAL[=dbname]

• If ControlO is installed, use

  Copy

  F CONTROLO,WRITEGLOBAL[=dbname]

  where dbname indicates the databases to be updated. Valid values:

  • name - Name of a specific database to be updated.

  • ALL - All databases (and, if using ControlO, members) listed in the concatenation referenced by DD statement DAGLBLST are updated.

  • <none> - Only member $GLOBAL, the default member, is updated.

If command WRITEGLOBAL is used to update a database, only variables that have been modified are written to the database files, enabling more efficient use of computer resources.

Defining a New Database

In some cases it is desirable to isolate the AutoEdit variables of certain jobs and/or rules from other jobs and rules. This can be done to enable the use of checkpoints or to perform initialization on an application basis. To isolate these variables, define a new AutoEdit variable database specifically for the AutoEdit variables you want to keep separate.

Only Control‑O users can define new IOA AutoEdit variable databases. User of other INCONTROL products can access one database, called IOAVAR.

To define a new AutoEdit variable database, use the IOA Variable Database facility, and add the name of the new database to the global member list, which is a concatenation of three members referenced by DD statement DAGLBLST: IOAGLBVL, CTOGLBVL and DAGLBLST.

The global member list is the list of members referenced by DD statement DAGLBLST of the INCONTROL product monitor procedure, which is currently either CONTROLO or CTMCMEM. DD statement DAGLBLST points to a concatenation of the following members:

Table 77 Global Member List

Each line of the global member list describes a database. The format of each line is

database <filetype+attribute>

Table 78 Fields of Global Member List Lines

Below is a screen segment that contains sample content for member DAGLBLST of the Control‑O PARM library.

Figure 16 Sample Content for Member DAGLBLST

Command ===>                                                  Scroll ===> CSR 000001
***********************************************************************
000002 *       ADD LIST OF POOLS                                              
000003 READONLY    INPUT      A READ-ONLY MEMBER                              
000004 * ******************************************************************** 
000005 * *         COSMOS RELATED POOLS                                     * 
000006 * ******************************************************************** 
000007 *                                                                      
000008 *           DEMO DATABASES                                             
000009 *                                                                      
000010 COSWORKV    TEMP       COSMOS - WORKING VARIABLES                      
000011 COSALLPR    DBINPUT    COSMOS - DEMO PREREQUISITES DATABASE            
000012 COSALLMT    DBINPUT    COSMOS - DEMO METHODS DATABASE                  
000013 COSSTCOB    S1TEMP     COSMOS - DEMO STC WORKING DATABASE              
000014 COSVTMOB    S1TEMP     COSMOS - DEMO VTAM WORKING DATABASE             
000015 COSIMGOB    DBTEMP     COSMOS - DEMO SYSIMAGE WORKING DATABASE         
000016 COSSTCSD    DBINPUT    COSMOS - DEMO STC SOURCE DATABASE               
000017 COSVTMSD    DBINPUT    COSMOS - DEMO VTAM SOURCE DATABASE              
000018 COSIMGSD    DBINOUT    COSMOS - DEMO SYSIMAGE SOURCE DATABASE          
000019 *                                                                      
000020 *           PROD DATABASES                                             
000021 *                                                                      
000022 * PRDALLPR  DBINPUT    COSMOS - PROD PREREQUISITES DATABASE            
000023 * PRDALLMT  DBINPUT    COSMOS - PROD METHODS DATABASE                  
000024 * PRDSTCOB  DBTEMP     COSMOS - PROD STC WORKING DATABASE              
000025 * PRDVTMOB  DBTEMP     COSMOS - PROD VTAM WORKING DATABASE             
000026 * PRDSTCSD  DBINPUT    COSMOS - PROD STC SOURCE DATABASE               
000027 * PRDVTMSD  DBINPUT    COSMOS - PROD VTAM SOURCE DATABASE              
000028 *                                                                      
000029 * ******************************************************************** 
000030 * *         COSMOS SAMPLE DEFINITION FOR SYSPLEX-WIDE MANAGEMENT     * 
000031 * ******************************************************************** 
000032 *                                                                      
000033 *           DEMO DATABASES                                             
000034 *                                                                      
000035 * COSSTCOB  S1TEMP     COSMOS - DEMO STC WORKING DATABASE FOR SYSPLEX  
000036 * COSVTMOB  S1TEMP     COSMOS - DEMO VTAM WORKING DATABASE FOR SYSPLEX 
000037 * ******************************************************************** 
000038 * *         TUTORIAL RELATED POOLS                                   * 
000039 * ******************************************************************** 
000040 TUTORIAL    DBINPUT   TUTORIAL                                         
000041 * ******************************************************************** 
000042 * *         XAE TEST RELATED POOLS                                   * 
000043 * ******************************************************************** 
000044   XAES1D01  S1TEMP    XESXAE - DEMO - S1 - TEMP                        
000045 * XAES1D02  S1INPUT   XESXAE - DEMO - S1 - INPUT                       
000046 * XAES1D03  S1PROT    XESXAE - DEMO - S1 - PROT (SAME AS DBPROT)       
000047 * XAES1D04  S1INOUT   XESXAE - DEMO - S1 - INOUT (SAME AS DBINOUT)     
000048   XAES2D01  S2TEMP    XESXAE - DEMO - S2 - TEMP                        
000049   XAES2D02  S2INPUT   XESXAE - DEMO - S2 - INPUT                       
000050 * XAES2D03  S2PROT    XESXAE - DEMO - S2 - PROT (SAME AS DBPROT)       
000051 * XAES2D04  S2INOUT   XESXAE - DEMO - S2 - INOUT                       

After defining and listing the new database, you must activate it with one of the following operator commands:

• If ControlO is not installed, use

  Copy

  F CTMCMEM,LOADGLOBAL[=dbname]

• If ControlO is installed, use

  Copy

  F CONTROLO,LOADGLOBAL[=dbname]

  where dbname is the name of the database.

Updating Contents of a Database in Memory

To implement changes to a variable database that has already been loaded into memory, so that the changes are immediately accessible by Control‑M jobs and other INCONTROL products:

1. Reload the modified database using one of the following operator commands:

   • If ControlO is not installed, use

     Copy

     F CTMCMEM,LOADGLOBAL[=dbname]

   • If ControlO is installed, use

     Copy

     F CONTROLO,LOADGLOBAL[=dbname]

     where dbname is the name of the database.

     Variables in a variable database can also be updated or modified through DO SET statements in Control‑M jobs, or through SETOGLB statements in a KSL/KOA script. For more information, see the DO SET parameter in the job production parameters chapter of the Control‑M for z/OS User Guide.

2. Use one of the following operator commands to save changes made to the database in memory:

   • If ControlO is not installed, use

     Copy

     F CTMCMEM,WRITEGLOBAL[=dbname]

   • If ControlO is installed, use

     Copy

     F CONTROLO,WRITEGLOBAL[=dbname]

     where dbname is the name of the database.

Updating the IOAVAR physical database using screen IV in MODE ADMIN is hazardous in a live system!

The following discussion concentrates on the IOAVAR database which is used by Control-M, but similar problems might occur with Control-O only pools.

Updating the IOAVAR physical database using screen IV in MODE ADMIN in a live system can lead to

• variables getting lost

• blank variable names

The following scenario can lead to variables getting lost.

The IOAVAR database can be changed in the following ways:

• By Control-M SET operations (SET VAR in the Job Scheduling Definition, %%SET in the JCL) that change the live database in memory.

  These changes are saved in the physical database when the WRITEGLOBAL=IOAVAR command is automatically issued.

  Only a WRITEGLOBAL saves these changes to the database.

• By manually changing the physical database via screen IV in MODE ADMIN.

  These manual changes are brought to the live database in memory by a LOADGLOBAL command.

  A LOADGLOBAL=IOAVAR is performed automatically when Control-O/CMEM starts.

  A LOADGLOBAL=IOAVAR can be issued manually when changes that are made to the physical database must be brought into the live database in memory while the system is active.

  A LOADGLOBAL=IOAVAR replaces the entire existing copy of the database in memory.

It is hazardous to update the IOAVAR physical database using screen IV in MODE ADMIN in a live system and issue a LOADGLOBAL because in a live system an IOAVAR variable might be updated at any time and if the LOADGLOBAL is issued just before the WRITEGLOBAL is issued, it will cause recent changes that have not yet been saved with the WRITEGLOBAL to be wiped out.

The following scenario can lead to blank variable names:

When a variable is deleted from the database via IV screen in MODE ADMIN in a live system, and until a LOADGLOBAL=IOAVAR is issued, the variable remains in memory. If the deleted variable is added or updated by Control-M before the LOADGLOBAL=IOAVAR is issued, the variable will still be found in memory, and only the VALUE of the variable will be updated. The WRITEGLOBAL=IOAVAR writes only the value of changed or updated variables to the database (even if the value has not actually changed).

The end result will be that the physical database will include only the VALUE of the IOAVAR variable which has been deleted and updated but without its VARNAME which has been deleted. When viewed in IV screen in MODE ADMIN, blanks will appear in the VARNAME field.

Using XAE Type Databases Instead of Standard Type Databases

The use of XAE databases enables systems in a Sysplex to access and update AutoEdit variables throughout the Sysplex. The AutoEdit variables are held in Coupling Facility structures and can be accessed by all systems connected to the Sysplex. For more information, see the AutoEdit facility chapter in the Control-O User Guide.

A Comparison of XAE Databases

This topic presents three possible XAE configurations for the IOA Variable Database facility’s databases

• no Sysplex

• XAE Type 1 database in a Sysplex, which is available only for ControlO

• XAE Type 2 database in a Sysplex

No Sysplex

At sites where no Sysplex is installed, or when the database is not shared between systems in the Sysplex, only the jobs and rules on each CPU have access to the variables on that system only. There is no access between jobs and rules from one system to another. In this configuration, a standard database is sufficient.

XAE Type 1 Database in a Sysplex

At sites where a Sysplex, an XAE Type 1 database and the Coupling facility are defined

• All jobs and rules can access (resolve) all AutoEdit variables in the database, regardless of the system on which the variables were originally created.

• Only the jobs and rules on the system that originally created the AutoEdit variables can update these variables.

The following figure shows a XAE Type 1 Database in a Sysplex:

Figure 17 XAE Type 1 Database in a Sysplex

XAE Type 2 Database in a Sysplex

At sites where a Sysplex, an XAE Type 2 database and the Coupling facility are defined, all rules and jobs can access (resolve) and update all AutoEdit variables, regardless of the system on which the AutoEdit variables were originally created.

The following figure shows a XAE Type 2 Database in a Sysplex:

Figure 18 XAE Type 2 Database in a Sysplex

Performance Issues

Running the XAE facility can impact INCONTROL product performance. In some cases, the impact may be negligible. For a description of issues of impact, see Using an XAE Type 1 Database and Using an XAE Type 2 Database.

Using system-managed rebuild or duplexing rebuild for the XAE structures will have the following performance impacts:

• When the structures are duplexed, each update of a variable updates both copies of the structures.

• During the system-managed rebuild or duplexing rebuild process, the structures are inaccessible. Requests to access variables will be suspended until the rebuild process ends.

• If Control-O or CMEM is started or stopped when a system-managed process is performed on its structures, Control-O or CMEM initialization or termination will be suspended until the system-managed process ends and the structures are accessible again.

Using Standard Databases

If you use standard databases to store AutoEdit variables, the variables are stored in the Extended Common Service Area (ECSA) and are resolved based on their current values in ECSA. This option provides the best performance, but does not facilitate direct sharing of variables among Sysplex participants.

Using an XAE Type 1 Database

If you use an XAE Type 1 database to store AutoEdit variables, the variables are stored both in the Extended Common Service Area (ECSA) and using the Coupling facility.

The advantage to this method of storing AutoEdit variables is that resolving the variables from the originating, owning, machine (from ECSA) is not costly in terms of performance.

The disadvantages to this method include the following:

• More resources are used than when using a standard AutoEdit database. This is because in addition to writing the variable contents to ECSA, the variable has to be updated in a List structure in the Coupling facility.

• Resolving variables from a machine other than the originating, owning, machine is more costly in terms of performance, because the list in the Coupling facility must be read instead of resolving the value directly from ECSA.

Using an XAE Type 2 Database

If you use an XAE Type 2 database to store AutoEdit variables, the variables are stored both in the Common Service Area (CSA) and using the Coupling facility.

Resolving variables, regardless of from which machine, is always more expensive than with XES Type 1. This is because

• In the best case scenario, the system checks a directory-only caching mechanism implemented with a lock or cache XES structure pair to know if the ECSA copy of the variable is still valid.

• In the worst case scenario, the system must both record your interest in that variable, read the Coupling facility for the latest copy and keep that copy in ECSA).

Setting variables, regardless of from which machine, is always more costly than with XES Type 1. This is because, in addition to updating the ECSA, the system

• updates a directory-only caching mechanism implemented with a lock or cache XES structure pair, to invalidate the ECSA values stored in other computers

• updates the Coupling facility

Serializing the usage of XAE Type 2 database variables requires that you obtain both per-CPU latches and Sysplex-wide locks that can suspend and delay the execution of an address space. Make sure to avoid the excessive delay of important system address spaces.

Calculating the Disk Space Required for the Variable Database

Installation of the IOA Variable Database is preceded by calculation steps that aid in determining the necessary space for the IO access method files.

The IOA Variable Database facility is composed of three IOA Access Method files (each of which requires two additional files, one for the data component and one for the index component, see IOA Variable Database Facility). Each time you add a new database in the List of Databases screen (of Screen IV) you are actually adding a new record to the Database (DBS) file. Each time you add a new column to an existing database in the List of Columns screen (of Screen IV) you are actually adding a new record to the Column (COL) file. Each time you do one of the following actions, you are actually adding a new record to the Variables (VAR) file:

• Directly add a new variable to an existing database in the display screen of Screen IV.

• Indirectly add a new variable to an existing database by executing a WRITEGLOBAL operation, for which a new value for this column/row was not previously defined.

To properly calculate the space required you either need to do one of the following:

• Estimate the average number of databases, columns and rows for the planned databases, and provide this estimate as input to the calculation steps in ICE.

• Rely on values obtained empirically from previous releases or experimentation with the facility.

Enlarging IOA Variable Databases

There are different IOA Variable Database types; each is specified in the DAGLBLST concatenation of the Control-O or CMEM monitor. Each database type, shown in the following list, may require different kinds and amounts of resources to provide their respective functionality:

• DBINOUT

• DBINPUT

• DBPROT

• DBTEMP

• S1INOUT

• S1INPUT

• S1PROT

• S1TEMP

• S2INOUT

• S2INPUT

• S2PROT

• S2TEMP

• When allocating (or enlarging) an IOA Variable Database, you need to know which additional demand you are adding, and on which particular resources or combination of them. This is required to allocate them appropriately. Included among the resources to be considered when preparing to enlarge or allocate an IOA Variable Database are the

• amount of ECSA needed to store the variables

• size of the required navigation control structure to the variables

• amount of ECSA needed for navigation control structures to the variables

• disk space

• coupling facility space

Each of these considerations is explained as follows:

• Calculating the amount of ECSA needed to store the variables.

• Calculating the size of the required navigation control structure to the variables.

• Calculating disk space

• Calculating coupling facility space

• Implementing the increase in size

Calculating the amount of ECSA needed to store the variables.

IOA Variable databases are spreadsheet-like matrixes, where the value stored at the intersection of a specific row number and a specific column name (a slot) represents an atomic variable.

ECSA required for a single variable

The amount of ECSA required to store a single atomic variable is 16 bytes of control information, plus the number of characters in the variable column name, plus the number of characters in the value of the variable in that column.

For example, if a variable in the MYCOL column name has 7 characters in its value, that variable will require a total of 28 bytes of ECSA. This total is computed, for purposes of this example, by adding the 16 bytes required for control information, to the 5 characters in the length of MYCOL column name string, plus the number of characters in the value of the variable in that column, which in this example is 7.

The total size of a single variable slot is limited to 256 characters. Therefore, 240 characters is the maximum that the variable name plus the variable value may occupy.

This calculation is the same for all the database types shown below:

• DBINOUT

• DBINPUT

• DBPROT

• DBTEMP

• S1INOUT

• S1INPUT

• S1PROT

• S1TEMP

• S2INOUT

• S2INPUT

• S2PROT

• S2TEMP

ECSA required for all variables in a single IOA Variable database

You can estimate the ECSA required by a single IOA Variable database by calculating the number of columns, multiplied by the number of rows, multiplied by the average size of a variable, as explained above. To this figure, you must add a figure obtained by adding 1 to the number of columns, and multiplying that result by 256.

This calculation is the same for all the database types shown below:

• DBINOUT

• DBINPUT

• DBPROT

• DBTEMP

• S1INOUT

• S1INPUT

• S1PROT

• S1TEMP

• S2INOUT

• S2INPUT

• S2PROT

• S2TEMP

ECSA required for all variables in all IOA Variable databases

You can calculate the ECSA requirements for all variables in all IOA Variable databases simply by adding together the ECSA requirements for each individual IOA Variable database.

Calculating the size of the required navigation control structure to the variables.

One of the attributes defined for an IOA Variable database is the NUMBER OF ROWS. The NUMBER OF ROWS is set using the =IV screen, when you add or update a new Variable IOA Database. The NUMBER OF ROWS specified for the IOA Variable Database is the primary input required to calculate the size, in ECSA, of a navigation control structure. The NUMBER OF ROWS attribute enables you to

• set a limit on the amount of rows that can be added to a database, and indicate an AutoEdit error if that limit is exceeded

• determine the ECSA space required to allocate a control structure, which helps to easily navigate the databases

This value plays the same role for all the database types shown below:

• DBINOUT

• DBINPUT

• DBPROT

• DBTEMP

• S1INOUT

• S1INPUT

• S1PROT

• S1TEMP

• S2INOUT

• S2INPUT

• S2PROT

• S2TEMP

ECSA required for the control structure of a single IOA Variable Database

The amount of ECSA required to allocate the navigation control structure for a single IOA Variable database is determined by multiplying 16, which is the number of bytes of control information, times the number of rows defined in the database, times the number of columns defined in the database.

This allocation is the same for all the database types shown below:

• DBINOUT

• DBINPUT

• DBPROT

• DBTEMP

• S1INOUT

• S1INPUT

• S1PROT

• S1TEMP

• S2INOUT

• S2INPUT

• S2PROT

• S2TEMP

ECSA required for the control structures of all IOA Variable Databases

You can calculate the ECSA requirements for the control structures of all IOA Variable databases simply by adding together the ECSA requirements of the control structures of each individual IOA Variable database.

Calculating disk space

The database types listed below require disk space for the hardening of the IOA Variable Databases on disk:

• DBINOUT

• DBINPUT

• DBPROT

• S1INOUT

• S1INPUT

• S1PROT

• S2INOUT

• S2INPUT

• S2PROT

The following database types are temporary. They require only ECSA memory, and do not require disk space for the hardening of the IOA Variable Databases on disk.

• DBTEMP

• S1TEMP

• S2TEMP

When disk space is required it can be estimated using the same space calculations discussed in ICE steps 7.1, 7.2, and 7.3 of the IOA installation. The largest consumer of disk space is the Variables file, which is calculated in step 7.3.

Calculating coupling facility space

Different database types require different space allocations. The following table outlines those requirements:

Table 79 Coupling Facility Space Allocation Requirements

When coupling facility space is required it can be estimated using the same space calculations discussed in ICE step 7.7.

Implementing the increase in size

When you increase the value of the NUMBER OF ROWS attribute you

• increase ECSA consumption

• increase the disk space consumption

• increase the coupling facility space required

Implementing size increases when space was overallocated

However, if the disk space and coupling facility space were overallocated, it is not always necessary to re-allocate them. In such cases, it is enough to issue an F CONTROLO,LOADGLOBAL=xxxxx command in one computer, if the database is a XAE Type 2 database, or in all computers, if the database is Type 1, where xxxxx is the name of the database whose NUMBER OF ROWS has changed.

Implementing size increases when space was overallocated

However, if the disk space and coupling facility space were overallocated, it is not always necessary to re-allocate them. In such cases, it is enough to issue an F CONTROLO,LOADGLOBAL=xxxxx command in one computer, if the database is a XAE Type 2 database, or in all computers, if the database is Type 1, where xxxxx is the name of the database whose NUMBER OF ROWS has changed.

Implementing size increases when insufficient space was allocated

The following steps outline the procedure for implementing size increases when an insufficient amount of space was originally allocated:

1. To de-allocate the files, bring down the Control-O or CMEM monitor.

2. If more coupling facility space is required, update the CFRM policy and IOAPLEX definitions accordingly, and activate the CFRM policy. For an example of how to execute this process, see ICE steps 7.8 and 7.10. If additional coupling facility space is not required, skip this step.

3. If more disk space is required continue with the next step. Else continue with step 11.

4. Back up your IOA Variable databases.

5. Unload the databases to flat files. To do so, submit jobs IOADBSUL, IOACOLUL, and IOAVARUL from the IOAprefix.JCL library. This creates three sequential files named IOAprefix.FLAT.DBSD, IOAprefix.FLAT.COLD, and IOAprefix.FLAT.VARD respectively.

6. Rename the IOA Access Method files

7. Format the databases using jobs IOADBSBF, IOACOLBF, and IOAVARBF from ICE customization, with the newly calculated size.

8. Load the databases from the flat files using jobs IOADBSLD, IOACOLLD, and IOAVARLD from the IOAprefix.JCL library.

9. Build the indexes with jobs IOADBSBI, IOACOLBI, and IOAVARBI from the IOAprefix.JCL library.

10. Enter Screen IV from the IOA Main Menu, and verify that the databases contain the same data as before.

11. Bring up the Control-O or the CMEM monitors

Expanding Various IOA Files

The following IOA files can be expanded using ICE:

• IOA Conditions file (CND) (For the procedure, see the IOA file customization section in the INCONTROL for z/OS Installation Guide: Customizing.)

• IOA Log file (LOG)

• IOA Manual Conditions file (NRS)

• IOA Database file (DBS)

• IOA Columns file (COL)

• IOA Variable file (VAR)

Perform the following the steps to expand IOA files.

For complete details about the DBS, COL, and VAR files, see Enlarging IOA Variable Databases.

1. Close all monitors and IOA activities.

   • When expanding the IOA Manual Conditions file (NRS), there is no need to close any monitors or IOA activities.

   • When expanding the IOA Variables Database, shut down only CMEM and the ControlO monitors. However, keep in mind that when these monitors are stopped, ControlM is not able to access the AutoEdit variables in the database.

2. Rename the old file that you want to expand. If you are expanding the IOA Database, Columns, and/or Variables files, unload the following files to sequential files accordingly:

   • IOADBSUL in IOA.JCL library for the Database file.

   • IOACOLUL in IOA.JCL library for the Columns file.

   • IOAVARUL in IOA.JCL library for the Variables file.

3. Delete or Rename the old file that you want to expand. If you are expanding the IOA Variable Database facility’s Columns and/or Variables files, do the following to unload these files to sequential files accordingly:

   1. Using ICE, select Customization. Enter IOA in the Product field, select Product Customization, and then select major step2, "Customize Dataset Parameters." Perform the minor steps in order for each file you want to expand.

   2. Perform minor step1, "Customization Instructions," which provides an overview of the process.

   3. If you are expanding the IOA Log file, perform minor step2, "IOA Log File Space Calculation."

4. Perform minor step3, "IOA Dataset Parameters," which lets you specify values that ICE uses to calculate the appropriate file size. During this step, specify a question mark (?) in any parameter field for help.

   Modify only the parameters relevant for the files you want to expand. The following table lists parameters that can be changed in this step:

   Table 80 Parameters that can be changed in this step

   Parameter	Description	Relevant File
   CNDREC#	Number of records in the IOA Conditions file	Conditions file
   NRSREC#	Number of records per day in the IOA Manual Conditions file	Manual Conditions file
   DUALDB	Mirror Database = Y (Yes) or N (No)	Dual Conditions file

5. If you are expanding the IOA Database, Columns and Variables files, perform minor steps4 through 6, respectively.

6. Perform minor step7, "Save Parameters into Product Libraries," to save the parameter values that you specified in minor step3.

7. Minor steps8 through14 are jobs that perform the expansion. Perform only those steps relevant to the files you want to expand.

   Table 81 File Expansion Jobs

   Files	Job	Parameter Description
   Conditions file	FORMCND in the IOA INSTALL library	This job allocates and formats a new Conditions file (CND/CKP) with the new size. If the user has Control‑M installed and is utilizing the Journaling feature, the Journal Conditions file must also be expanded. For details see Expanding Control-M Files.
   Log file	FORMLOG in the IOA INSTALL library	This job allocates and formats a new Log file (LOG) with the new size.
   Manual Conditions file	FORMNRS in the IOA INSTALL library	This job allocates and formats a new Manual Conditions file (NRS) with the new size.
   Databases file	IOADBDBS in the IOA INSTALL library	This job allocates and formats a new Databases file (DBS) with the new size.
   Columns file	IOADBCOL in the IOA INSTALL library	This job allocates and formats a new Columns file (COL) with the new size.
   Variables file	IOADBVAR in the IOA INSTALL library	This job allocates and formats a new Variables file (VAR) with the new size.

8. Copy the old files into the new ones according to the instructions below:

   Table 82 Copy Methods

   Files	Copy Method
   Conditions file	Copy using utility IOACCND. For information about utility IOACCND, see the INCONTROL for z/OS Utilities Guide.
   Log file	Copy using utility IOACPLOG in the IOA JCL library. For information about utility IOACPLOG, see the INCONTROL for z/OS Utilities Guide.
   Manual Conditions file	Run utility IOALDNRS to load the manual conditions into the new Manual Conditions (NRS) file.
   Databases file	Load sequential file IOADBSLD and build index IOADBSBI into the IOA.JCL library.
   Columns file	Load sequential file IOACOLLD and build index IOACOLBI into the IOA.JCL library.
   Variables file	Load sequential file IOAVARLD and build index IOAVARBI into the IOA.JCL library.

9. Start the monitors and issue other relevant modify commands.

CMEM-related maintenance

For details on maintaining (adding, deleting, or changing) the CPU list, SMFIDs, JES SIDs, and communication files, see the INCONTROL for z/OS Installation Guide.

IOA Log Index

The IOA Log Index provides direct access to specific records or ranges of records in the IOA Log file.

This feature significantly decreases the number of required I/O operations, thereby saving reading time and CPU.

The IOA Log Index has the following impact on the retrieval of IOA Log messages:

Table 82a IOA Log Index impact

Activating the IOA Log Index

To activate the Log Index, run the IOALOGXC utility once with parameter FUNC=ACT.

After the initial activation, run the IOALOGI utility periodically to build the index.

Checking the status of the IOA Log Index

To check the status of the IOA Log Index, you can use the IOAVERFY utility. Run utility IOAVERFY with parameter VERIFY FILE LOG to print the following details:

• Status of the IOA Log Index

• Date and time of the last run of the IOALOGI utility

• Percent of indexing of the IOA LOG file

Alternatively, the Control-M interface to the IBM Health Checker offers an IOA Log Index File Status check (CTM_<monitorName>_IOALOG_INDEX) that provides you with information about the status of the IOA Log Index.

The following messages are examples of messages returned by the Health Checker:

• IOA Log Index is not active:

  Copy

  CTMH1BI_HC IOALOG INDEX FILE CONDITION
  IOALOG index file current status:
  =================================
   
  IOALOG index is not active.
  * Medium Severity Exception *
  CTMH1DE_HC CURRENT STATUS OF IOALOG INDEX IS "NOT ACTIVE"

• IOA Log Index is active but the log is not sufficiently indexed:

  Copy

  CTMH1BI_HC IOALOG INDEX FILE CONDITION
  IOALOG index file current status:
  =================================
   
  IOALOG is currently 52.1% indexed.
  * Medium Severity Exception *
  CTMH1EE_HC CURRENT STATUS OF IOALOG INDEX IS BELOW THRESHOLD OF 85%

• IOA Log Index is active and the log is sufficiently indexed:

  Copy

  CTMH1BI_HC IOALOG INDEX FILE CONDITION
  IOALOG index file current status:
  =================================
   
  IOALOG is currently 89.9% indexed.
   
  CTMH1CI_HC CURRENT STATUS OF IOALOG INDEX IS "OK"

Problem Determination

Control‑O is supplied with internal debugging (trace) facilities that provide the ability to print an internal debugging trace and to print the contents of Control‑O internal data areas. Under normal circumstances, the trace facilities are dormant. However, if required (that is, if BMC Customer Support has requested debugging information), you can activate the trace facilities by performing the following steps:

Do one of the following:

1. Start a new ControlO monitor with the following operator command:

   Copy

   S CONTROLO,TRACE=level

   The ControlO monitor passes control to the new ControlO monitor and shuts down.

2. Issue the following operator command:

   Copy

   F CONTROLO,TRACE=level

   The required trace level is supplied by BMC Customer Support. It can be any value from 000 to 255 (000 specifies no debugging).

   You should not regularly activate ControlO with the TRACE parameter, because a JES problem may cause ControlO to become suspended while waiting for JES.

   Debugging information is printed to files referenced by DD statements DATRACE and DADUMP of the ControlO procedure.

3. When you finish your problem determination procedures, start a new ControlO using operator command

   Copy

   S CONTROLO

   or specify operator command

   Copy

   F CONTROLO,TRACE=00

Internal Trace facility

IOA provides an internal Trace facility that can print internal tracing records and the contents of internal data areas. Under normal circumstances, the Trace facility is dormant. However, if required, that is, if BMC Customer Support has requested tracing information, the Trace facility can be activated.

Use these facilities only when requested by BMC Customer Support.

Tracing can be requested for specific components. Each component has its own identifying numbers for purposes of producing the trace. These numbers are called trace levels. One or more trace levels can be activated at the same time. Trace levels can be modified during execution.

BMC Customer Support provides you with a list of the trace levels that are used, depending on the problem encountered.

Internal tracing can be activated when the monitor is started or during monitor execution, and it can be modified or stopped during monitor execution. The internal trace setting can be displayed.

Activating the internal Trace facility

The IOA Online Monitor and each of the INCONTROL products has its own operator commands that initiate the internal Trace facility. Some products also differentiate between which operator commands are issued, depending on whether the product's monitor is active or inactive. For information on initiating the Trace facility for an INCONTROL product, see the chapter that discusses that product.

For example, to initiate the internal Trace facility in Control‑M, enter the command

F CONTROLM,TRACE=level

Similarly, to initiate the internal Trace facility for the IOA Online Monitor, enter the command

F IOAOMON,TRACE=level

In such a command, level is the list of trace levels to be activated or deactivated. Each INCONTROL product has different numbers of levels. For example, the Control‑M Trace facility has 128 levels (that is, from 1 through 128, inclusive).

Numbers are used to activate or deactivate the trace. Positive numbers activate the trace; negative numbers deactivate the trace. Valid level values are

• any number between 1 and that product's maximum number of levels, or a range of numbers, such as 10:15, to activate the trace. The level is added to the levels already set.

• any number between -1 and the negative value of that product's maximum number of levels, or a range of numbers, such as-20:-25, to deactivate the trace. The level is removed from the active levels.

The following table gives examples of how to specify the levels that are on or off:

Table 83 Examples of turning Trace levels on and off

When the trace level set is completed, the following messages are displayed on the console, along with other product-specific messages (depending on the parameters specified):

IOAD01I TRACE LEVELS SET AS FOLLOWS:
IOAD02I 00nn:00mm – TURNED on or off

Trace facility output

Tracing information is written to one or more of the following locations, depending on which trace levels were turned on:

• DD statement DATRACE of the INCONTROL product's procedure.

• DD statement DADUMP of the INCONTROL product's procedure.

• SYSDATA of the INCONTROL product's started task.

Stopping the internal trace

When you have finished the problem determination procedures, internal tracing is stopped.

Use the following operator command to stop internal tracing in Control‑M:

F CONTROLM,TRACE=(-1:-128)

When tracing is stopped, the following messages are displayed on the console, along with any other product-specific messages:

IOAD01I TRACE LEVELS SET AS FOLLOWS:
IOAD02I 0001:1024 – TURNED OFF

Displaying the internal Trace setting

The internal trace setting (level, DBGJOB value, and DBGPIPE value) can be displayed for a specific monitor.

Operator commands exist for each INCONTROL product for displaying the internal trace setting.

Use the following operator command to display the internal trace setting in Control‑M:

F CONTROLM,TRACE=SHOW

The following messages are produced as the result of the SHOW command, along with any other product-specific messages:

IOAD03I PRESENT TRACE LEVELS ARE AS FOLLOWS:
IOAD04I level:level – on or off
IOAD04I level:level – on or off

Identity Level (IDL) facility

The IDL facility is a diagnostic tool that can be used to determine, store, monitor, and display the maintenance level of the INCONTROL code running in an address space. This section describes:

• IDL features

• Output

• Modify commands

• External tables

• Messages

IDL features

The IDL facility includes features that run automatically, and additional features that can be implemented by specific IDL modify commands.

Automatic features

The IDL facility automatically

• performs level identification of each CSECT of the code running in an address space

• creates level data snapshots and places them in storage at predefined checkpoints, which makes this data available the moment an address space abends

• detects level changes between snaps

• detects changes in address space configuration (list of running tasks) between subsequent snaps

Additional features

With the IDL modify commands (See Modify commands), the IDL facility can be used to

• perform service functions in order to tune IDL facility behavior (see DABAPI and DUP)

• change or set a default group ID (see DEFGROUP)

• display level data of a specific module, modules, CSECT, or CSECTs (see SHOWCSECT and SHOWMODULE)

• display the level data of a predefined group of modules, as listed in the IOALSUM Summary Table (see SHOWGROUP)

• display level data (see SHOWLEVEL)

• perform service functions useful when monitoring an address space or when finding problems (see SHOWMEMORY)

• display a full list of tasks and modules currently running in an address space (see SHOWMODULES)

• display modules or CSECTs that cannot be identified (see SHOWSHORT and SHOWUNKNOWN)

• display level data snapshots (see SHOWSNAP)

• create level data snapshots and place them in storage by means of a modify command (see SNAP)