Part 5: Appendixes

• INCONTROL Product Data Sets

• IOAGATE Installation and Configuration Considerations

• Structure of the IOA Conditions File

• Housekeeping

• Uninstalling

• Message Considerations

• Control-M Virtual Storage Requirements

• Defining Subsystems

• National Language Support Facility

• General Parameter Descriptions

• Installation Guide Planning Sheets

INCONTROL Product Data Sets

The following topics list the Data Sets for INCONTROL products:

• IOA Data Sets

• SMP/E Data Sets

• Control-M Data Sets

• Control-M JCL Verify Data Sets

• Control-M/Restart Data Sets

• Control-D Data Sets

• Control-O Data Sets

• Control-V Data Sets

• Control-M/Analyzer Data Sets

• Control-M/Tape Data Sets

IOA Data Sets

Table 145 IOA Base Data Sets

Table 146 IOA Installation Data Sets

Table 147 IOA Operation Data Sets

Table 148 IOA Repository Data Sets

Table 149 IOA Maintenance Data Sets

SMP/E Data Sets

Table 150 SMP/E Data Sets

Control-M Data Sets

Table 151 Control-M Installation Data Sets

Table 152 Control-M Operation Data Sets

Table 153 Control-M Repository Data Sets

Control-M JCL Verify Data Sets

Table 154 Control-M JCL Verify Installation Data Sets

Table 155 Control-M JCL Verify Operation Data Sets

Control-M/Restart Data Sets

Table 156 Control-M/Restart Operation Data Sets

Control-D Data Sets

Table 157 Control-D Installation Data Sets

Table 158 Control-D Operation Data Sets

Table 159 Control-D Repository Data Sets

Control-O Data Sets

Table 160 Control-O Installation Data Sets

Table 161 Control-O Operation Data Sets

Control-V Data Sets

Table 162 Control-V Operation Data Sets

Control-M/Analyzer Data Sets

Table 163 Control-M/Analyzer Installation Data Sets

Table 164 Control-M/Analyzer Operation Data Sets

Table 165 Control-M/Analyzer Repository Data Sets

Control-M/Tape Data Sets

Table 166 Control-M/Tape Installation Data Sets

Table 167 Control-M/Tape Operation Data Sets

Table 168 Control-M/Tape Repository Data Sets

IOAGATE Installation and Configuration Considerations

The following topics describe IOAGATE installation and configuration issues:

• IOAGATE Planning

• IOAGATE Configuration

• IOAGATE Recovery Considerations

• SSL Support

• Validation of an Incoming IP Address

• IOAGATE Network Map

For information on the application servers for the following products

• Control-M, see Step 21 – Install Control-M Application Server

• Control-D/Page On Demand, see Step 13.4 – Start Page On Demand (Optional).

• Control-O, see Step 11 – Control-O Communication (Optional).

For a more complete discussion of these products, refer to the appropriate user guide for that INCONTROL product, as well as the appropriate chapter in the INCONTROL Administrator Guide.

IOAGATE Planning

Ensure that you have completed the IOAGATE Installation Sheet.

IOAGATE Configuration

IOAGATE is a mainframe software communications gateway (middleware) that enables INCONTROL mainframe applications to communicate with other mainframe and non-mainframe applications over the network.

Client applications access INCONTROL products by means of an application server through IOAGATE.

Figure 47 Access of INCONTROL Products through IOAGATE

IOAGATE supports multiple concurrent application servers of different applications and their clients. A single IOAGATE can support

• Control-O (specifically Control-O to Control-O connections)

• Control-M JCL Verify monitor (CTJMON) (specifically CTJMON to CTJMON connections)

• Control-M

• Control-D (specifically Control-D/Page On Demand and Control-D/File Transfer Option)

IOAGATE allows one application to communicate with multiples of the same application.

IOAGATE can support multiple, dedicated or shared communication channels. A shared channel indicates that multiple applications use that same port or LU for their communication. A dedicated channel refers to a port or LU that is used exclusively by one application.

IOAGATE can periodically check the connection to the client when it is in a TCP/IP dual communications model. For an explanation of dual communications model, see Channel Sharing. When IOAGATE discovers broken connections, it closes them and listens for new ones.

In addition, IOAGATE can recover broken connections with clients. IOAGATE can recover failed application servers and subtasks as well.

IOAGATE distributes client requests to the next available application server through a sequential search of available application server address spaces.

Supporting Multiple Application Servers

IOAGATE supports communication between multiple application servers and their clients.

The following example illustrates multiple INCONTROL applications communicating with multiple clients.

Figure 48 Multiple INCONTROL Applications Communicating with Multiple Clients

Channel Sharing

A channel consists of the following components:

• Communications protocol (TCP/IP or SNA)

• Communications model

A set of communication subtasks inside IOAGATE that interface with TCP/IP or VTAM according to the protocol and model

Specific applications use a specific communications model. A communications model refers to the type of connection that handles the multiple users’ requests. These connections may be either Dual Connection Channels or Multiple Connection Channels.

Dual Connection Channels (DC) are two connections that are multiplexed by the client application in order to handle a multitude of users. This model is used by Control‑M and Control‑M/Enterprise Manager. The first connection is dedicated for traffic from IOAGATE to the client application and the other connection is for traffic in the opposite direction.

Multiple Connection Channels (MC) use a single port or LU to establish all new connections, each of which then receives its own socket and/or conversation and communication traffic. Control‑D/Page On Demand, Control‑D/File Transfer Option, Control‑O, and Control‑M/JCL Verify use this type of connection.

One Multiple Connection Channel can be shared between different instances of the same application using Multiple Connection Channels with the same protocol. For example, multiple instances of Control-D/WebAccess could be configured to use the same channel.

Dedicated Channels

The simplest way to configure an IOAGATE channel is shared channel use. When a shared channel is overloaded, the IOAGATE channel can be configured for dedicated use by product. Congestion on a Multiple Connection TCP channel can also be relieved by assigning more communication subtasks to a channel. For more information, see "UPERTASK" in Specifying Advanced Channel Parameters.

The following example illustrates IOAGATE configured with dedicated channels:

Figure 49 IOAGATE Configured with Dedicated Channels

When using a dedicated channel configuration with IOAGATE

• Control-D/Page On Demand may use either a TCP/IP or SNA protocol with a Multiple Connection Channel

• Control-M and Control-M/Enterprise Manager must use a TCP/IP protocol with a Dual Connection Channel

• Control-O may use either a TCP/IP or SNA protocol with a Multiple Connection Channel

• Control-D/File Transfer Option must use a TCP/IP protocol with a dedicated Multiple Connection Channel

• Control M/JCL Verify must use a TCP/IP protocol with a Multiple Connection Channel

Application Server Cloning

For Control‑D/Page On Demand and Control‑D/File Transfer Option applications, if an application server address space is overloaded, additional address spaces can be defined in additional APSERVER statements, to distribute the load. For more information, see Option 1, Application, for the Add function under Step 20.2 – Configure IOAGATE Parameters. Additional application server subtasks within an application server can also be defined, to relieve overload. For more information, see Option 1, Application, for the A (Advanced) function under Step 20.2 – Configure IOAGATE Parameters.

TCP/IP Requirements

The following describes customization requirements for configuring the communication between IOAGATE and client applications using the TCP/IP protocol.

TCP/IP on z/OS

• z/OS IBM Communication server (CS)

• SNS/TCPaccess v 5.3 or above from CA

Functional TCP/IP Connection

A functional TCP/IP connection is required between IOAGATE and the client application, that is,

• Control-M/EM

• Control-D/Page On Demand

• Control-D Session Agent

• IOAGATE (for Control-O to Control-O and for CTJMON to CTJMON connections)

Any network topology configuration that supports TCP/IP (hardware and software) can be used, as long as TCP/IP connections can be established between IOAGATE and the client application workstation. Connectivity should be verified before you start the client application, for example, by using the ping command, Telnet commands, or other TCP/IP applications to test.

Multiple Connection Channels Using SNA Session Support

This section describes how to establish parallel sessions between the following specific client applications:

• Control-D/WebAccess Server and IOAGATE over Microsoft SNA Server

• Control-O to Control-O and IOAGATE using IBM Communication Server for z/OS

Enabling parallel sessions between the client applications and IOAGATE allows sessions to connect to their respective repositories through a single logical unit.

Note:The steps for mainframe-related configuration activities are provided in the following topic. For non-mainframe related steps, see the documentation of the relevant client application.

To support parallel sessions, the following components must be configured:

• Mainframe (in VTAM and IOAGATE)

• Microsoft SNA Server or Microsoft Host Integration Server 2000 or 2004

Changes must be made in VTAM and IOAGATE to support parallel sessions.

Enabling Parallel Session Support:

This procedure describes how to enable parallel session support.

Begin

1. Verify independent logical unit support by verifying that the SNA connection supports XID format3, and that the node VTAMPU definition includes the XID=YES configuration.

   The SNA server physical unit (PU) connection must support PU2.1.

   To verify the XID type used by the SNA connection, do the following:

   1. Open Microsoft SNA Server Manager.

   2. Double-click the Connections tree node.

   3. Right-click the connection used for the independent LU session and select Properties from the popup menu.

      SWPU30 is used as an example connection name.

      The Connection Properties dialog box is displayed.

      Figure 50 Connection Properties: General Tab

      

      Click the System Identification tab.

      Figure 51 Connection Properties: System Identification Tab

      

      In the XID Type field, select Format3 and click OK.

      For more information on defining aPU that supports an independent logical unit, see the Microsoft SNA Server Administration Guide.

2. Add a new LU called LUPRL to the SNA server node VTAM member and set LOCADDR to0 to configure the logical unit as independent.

   Copy

   SWPU30   PUADDR=01, 
                               CPNAME=CPSWPU30, 
                               PUTYPE=2, 
                               XID=YES, 
                               ... 
                           LUPRLLULOCADDR=0

3. Use INACT and ACT commands to initiate the new LU definition.

4. In SYS1.VTAMLST, create a new application Major Node for IOAGATE with parallel session support, or add the following definitions, which appear in the ECAMAPPL member in the SAMPLE library, to an existing member:

   Copy

   VBUILD   TYPE=APPL
                           PODLUP   APPL AUTH=(VPACE),
                           DSESLIM=256,/* Max concurrent logged on users */
                           OPERCNOS=ALLOW,
                           APPC=YES,
                       VPACING=7 

   Do not specify DLOGMODE or MODETAB.

   The logical unit (LU) name PODLUP can be changed if you alter all references to it.

5. Activate the application major node. For an existing application major node, recycle the node using INACT and ACT commands.

   When a new logical unit is defined, the DSESLIM takes effect immediately. When adding DSESLIM to an existing LU (and performing INACT and ACT), DSESLIM does not take effect immediately.

   The following CNOS command can be used to set the parallel session limits to take effect immediately:

   Copy

   F VTAM,CNOS,ID=PODLUP,LUNAME=LUPRL,LOGMODE=#INTER,LIMITS=(256,0,256)

   where PODLUP is the name of the remoteLU and LUPRL is the name of the localLU.

6. Specify the LUname to IOAGATE. Set the APPLID parameter to PODLUP in the ECAPARM member under the SNA multi-connection used for this connection.

Configuration of Microsoft SNA Server

Microsoft SNA Server can be configured to allow parallel sessions to connect to IOAGATE using SNA protocol. This is accomplished by defining a single logical unit that is shared by all users.

To configure Microsoft SNA, see the documentation of the relevant client application.

SNA Parameters Configuration Table

The following table shows how each element is configured to establish parallel sessions between the various client applications and IOAGATE over Microsoft SNA Server.

SNA Parameters

Table 169 SNA Parameters

IOAGATE Recovery Considerations

IOAGATE supports the following recovery features:

• VIPA and DVIPA Support

• Automatic Restart Management Support

This section describes how to implement these features with IOAGATE.

VIPA and DVIPA Support

This subsection describes IOAGATE support for the VIPA (Virtual IP Address) and DVIPA (Dynamic Virtual IP Address) features of the IBM OS/390 or z/OS Communications Server.

Unlike a regular IP address, which is associated with a specific communication adapter, a Virtual IP Address is not associated with a specific adapter and may be transferred from one z/OS image to another.

VIPA and DVIPA have the following flavors:

• VIPA Takeover

• Pure Dynamic VIPA for a Single Application Instance

• Dynamic VIPA for Multiple Application Instances with the Sysplex Distributor

VIPA Takeover

The VIPA takeover feature associates an individual VIPA with a TCP/IP stack, allowing the VIPA to be moved from a failing z/OS image to a backup image. This is functionally similar to replacing a computer but keeping the same IP address. Using this feature, all applications that are moved to the backup image can be reached by the same IP address that they were associated with on the failed image.

If this method is used for IOAGATE recovery, IOAGATE should be restarted on the backup image which has taken over the VIPA address.

IOAGATE transparently supports VIPA takeover, and therefore no special definitions are required in IOAGATE to implement it.

Pure Dynamic VIPA for a Single Application Instance

The pure Dynamic VIPA (DVIPA) feature allows a VIPA to be associated with a particular application instance. Using this feature, when an application is moved to another z/OS host image in a Sysplex environment, the VIPA remains associated with that application.

If the application fails, the application can be restarted in another TCP/IP stack in the Sysplex environment. The VIPA associated with that application is automatically activated at the new stack when the application BINDs to it.

General Sysplex Environment Requirements

When using the pure DVIPA feature for IOAGATE recovery, you must configure your Sysplex environment as follows:

• RUN a routing server OMPROUTE on each image in the Sysplex

  The new location of the moved IPAddress must be advertised to routers in the network, so that reconnection requests are routed to the backup z/OS image. This requires running a Dynamic Routing Server (OMPROUTE) on both the original z/OS image, and the backup image.

• DEFINE DVIPA support in the TCP/IP profile

  To enable DVIPA support for an application, use the VIPARANGE statement in the TCP/IP profile to define the VIPA for each TCP/IP stack where the application may run.

  For OS/390 version 2.8, the following example illustrates the syntax for VIPARANGE:

  Copy

  VIPADYNAMIC
                          VIPARANGE DEFINE 255.255.255.0 172.16.240.193
                      ENDVIPADYNAMIC

  1. Create a local CA certificate called MYCA using the following command. Modify the command parameters to reflect the naming conventions used at the installation:

     Copy

     RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('MYCA') O('BMC') C('US'))
     KEYUSAGE(CERTSIGN) WITHLABEL('MYCA')

  2. Create a private/public key pair and a digital certificate using the following command. The local CA certificate, MYCA, is used for the digital certificate. Replace GATEUSER with the IOAGATE RACF user ID.

     Copy

     RACDCERT ID(GATEUSER) GENCERT SUBJECTSDN(CN('IOAGATE') O('BMC') 
     C('US'))WITHLABEL('IOAGATE') SIGNWITH(CERTAUTH LABEL('MYCA')) 
     KEYUSAGE(HANDSHAKE)

  3. Assign the digital certificate a trusted status using the following command:

     Copy

     RACDCERT ID(GATEUSER) ALTER (LABEL('IOAGATE')) TRUST

  4. Export the digital certificate using the following command:

     Copy

     RACDCERT CERTAUTH EXPORT(LABEL('MYCA')) DSN('hlq.EXPORT.P12')

  5. Add the digital certificate to the client's key database using sslcmd or the Java keytool utility.

  For OS/390 version 2.10 and later, the following example illustrates the syntax for VIPARANGE:

  Copy

  VIPADYNAMIC
  VIPARANGE DEFINE MOVEABLE NONDISRUPT 255.255.255.0 172.16.240.193
  ENDVIPADYNAMIC

IOAGATE Implementation

IOAGATE implements DVIPA support using the following channel parameter in the CHANNEL declaration in the ECAPARM member:

BIND={INADDR_ANY|IP_Address|Hostname}

where

• INADDR_ANY indicates that IOAGATE BINDS to any IPaddress, meaning that it listens to all adapters. Default.

• IP_Address or Hostname indicates that IOAGATE BINDs to either the given IP_address or the IPaddress after Hostname resolution, respectively.

If the IP address as set in the BIND parameter is defined in the TCP/IP profile as an application-associated DVIPA, the specified IP address is associated with IOAGATE and "follows" IOAGATE when it "fails" on one image and restarts on the other image.

Considerations for Implementing DVIPA Support for IOAGATE with the Control-M Application Server (CTMAS)

When a z/OS image fails, Control‑M/Enterprise Manager running on either Unix or Windows NT detects the connection failure to IOAGATE through its keep-alive mechanism, and attempts to reconnect to IOAGATE. When IOAGATE and CTMAS are restarted on a backup image using the DVIPA associated with IOAGATE, Control‑M/Enterprise Manager will successfully reconnect to IOAGATE on the new image.

IOAGATE running in conjunction with the CTMAS can be moved to any z/OS image in a Sysplex without being tied to the z/OS image in which the main Control‑M Monitor is running. This is because CTMAS communicates with Control-M through files such as the Active Jobs file (AJF), IOA Conditions file, and Control‑M Resources file, as well as through Shouts and GRS (the ENQ/DEQ mechanism).

Although multiple IOAGATE instances can be started in parallel anywhere in a Sysplex to support other applications, only one instance of IOAGATE used in conjunction with CTMAS can exist in the Sysplex, using the CTMPLEX facility. For more information on CTMPLEX, see the Control‑M chapter in the INCONTROL for z/OS Administrator Guide.

Dynamic VIPA for Multiple Application Instances with the Sysplex Distributor

The IBM Communications Server enables you to run multiple instances of an application on multiple z/OS images, allowing the multiple application instances to share the same Dynamic Virtual IP Address. The Sysplex Distributor distributes connection requests from clients between the application instances based on predefined policies.

Sysplex Environment Requirements

Implement the Sysplex Distributor according to the appropriate IBM documentation.

The following example illustrates how to define the DVIPA address 172.16.240.193 as a distributed DVIPA under the control of the Sysplex Distributor.

VIPADYNAMIC
                VIPARANGE DEFINE MOVEABLE NONDISRUPT 255.255.255.0 172.16.240.193
                VIPADISTRIBUTE DEFINE 172.16.240.193 PORT 4000 DESTIP ALL
            ENDVIPADYNAMIC

Considerations when using Control-D/Page On Demand for Control-D/WebAccess Support

The Sysplex Distributor is useful when using IOAGATE in conjunction with Control‑D/Page On Demand for support of Control‑D/WebAccess. Control‑D/WebAccess can potentially have thousands of users in one Sysplex. The Sysplex Distributor enables you to distribute the load between multiple z/OS images, providing scalability, load balancing, and availability.

When you use the Sysplex Distributor with Control-D/WebAccess, define the following channel parameter in the CHANNEL declaration in the ECAPARM member:

BIND=DVIPA_address

Using the example as described in Sysplex Environment Requirements, the corresponding definitions for that example would be:

PORT=4000,
            BIND=172.16.240.193

Automatic Restart Management Support

Automatic restart management can reduce the impact of an unexpected error to a system program by restarting it automatically, without operator intervention. In a Sysplex environment, a system program can enhance its own recovery potential by registering as an element of the automatic restart management function of the cross system coupling facility (XCF).

To provide program recovery through automatic restart management, your installation must activate a policy through the SETXCF START command. This can be an installation-written policy or part of the IBM-supplied policy defaults. Because an installation-written policy may affect your program, you must understand how your installation uses automatic restart management for recovery in a Sysplex. Details of the automatic restart management function are described in the section of IBM publication OS/390 MVS Sysplex Services Guide that discusses using the automatic restart management function of XCF.

In general, the operating system restarts an element under the following conditions:

• when the element itself fails—in this case, the operating system restarts the element on the same system

• when the system on which the element was running unexpectedly fails or leaves the Sysplex—in this case, the operating system restarts the element on another system in the Sysplex. This is called a cross-system restart.

The operating system will not attempt to restart an element if

• the element has not yet registered as an element of automatic restart management

• the element is cancelled through a CANCEL, STOP, or FORCE command (without the ARMRESTART parameter specified)

• JES is down or has indicated that the element should not be restarted

• the element has reached the restart attempts threshold specified in the policy

• the policy indicates that this element should not to be restarted

• access to the ARM couple data set was lost

Installing and Implementing Automatic Restart Management for IOAGATE

1. Follow the instructions to set up an automatic restart management policy as specified in the section of IBM publication z/OS V1Rx MVS Setting Up a Sysplex that discusses automatic restart management parameters for administrative data utility. Some of the restart parameters are discussed in Restart Parameters.

   Your system does not need to specify an automatic restart management policy if the default values are acceptable. The default values, if any, are described under each parameter in IBM publication z/OS V1Rx MVS Setting Up a Sysplex, in the section discussing automatic restart management parameters for administrative data utility.

2. Specify the IOAGATE ARMELEM parameter in the ECAPARM member as described in Step 20 – Install IOAGATE (Optional).

3. Stop and then restart the IOAGATE monitor. At restart, IOAGATE checks the ARMELEM parameter in ECAPARM and, if specified, registers as an element of automatic restart management. The IOAGATE monitor then issues the following message:

   Copy

   ECAG0HI ENABLED FOR THE AUTOMATIC RESTART MANAGEMENT FUNCTION

   If IOAGATE fails to activate ARM when starting up, it issues the following message:

   Copy

   ECAG0JW AUTOMATIC RESTART MANAGEMENT REQUEST FAILED R15=XX REASON=XXXX

Automatic Restart Management and IOAGATE Failure

If ARM support is enabled and IOAGATE fails unexpectedly, the following message is issued when the operating system automatically restarts IOAGATE:

ECAG0II AUTOMATIC RESTART IN PROGRESS AFTER UNEXPECTED FAILURE

Restart Parameters

There are several ARM policy parameters you can choose to determine where, under what circumstances, and how many times, IOAGATE is to be restarted. Some of these restart parameters are described in the following table.

Table 170 Restart Parameters

To obtain information about elements of the automatic restart manager while the system is active, you can issue the D XCF,ARMSTATUS,DETAIL MVS operator command. For more information about this command, see the discussion about displaying cross system coupling facility (XCF) information, in the IBM publication MVS System Commands.

RESTART_GROUP(IOAGATE)
                    TARGET_SYSTEM(OS35)
                    ELEMENT(IOAGATE)
                TERMTYPE(ELEMTERM)

SSL Support

SSL is available for providing secure communication for IOAGATE. Procedures for implementing SSL are described in this section (refer to the following table). The steps required for implementing SSL can be performed on the mainframe, externally, or partially on the mainframe and partially externally. You can use Control‑M Configuration Manager for implementing SSL, as described in detailed in the Control-M SSL Guide.

Table 171 Various SSL Operations for INCONTROL Components

IOAGATE supports Security Access Facility (SAF) (for example, RACF) as the key database. Various settings for IOAGATE and the corresponding SSL security levels are indicated in the following table.

Table 172 SSL Security Levels Supported by IOAGATE

Control-D/Agent client 3.7.00 (or later) can transfer files to Control-D on an MVS using IOAGATE and the Control-D/File Transfer Option application server.

For a background on SSL refer to the internet. For documentation of SSL support by Control-M/EM and Control-M Configuration Manager, refer to the Control-M SSL Guide. For documentation of SSL support by Control-D/Agent client refer to Control‑D/Agent User Guide version 3.7.00 (or later).

Creating Keys and Certificates for IOAGATE for Use with Control-M and Control-D

Key pairs and certificates can be created for IOAGATE by using a SAF on the mainframe or an external CA, or with a combination of these two approaches. These keys and certificates can be used for communication with Control-M or Control-D. See the following table for the method appropriate to your site.

Table 173 Alternate Methods of Generating and Signing IOAGATE Keys and Certificates

Table 174 Additional Operations

Using the Basic Methods: RACF or Control-M Configuration Manager

In this section, the procedures using RACF (an example of SAF) and Control-M Configuration Manager are described.

This procedure describes how to create keys and certificates using RACF.

Begin

Generating Certificates with Control-M/EM or "Bring Your Own"

This procedure describes how to generate certificates with Control-M/EM or "Bring Your Own".

Begin

1. In the Control-M Configuration Manager, choose Tools => System Configuration=> Control-M/EM System Parameters=> Advanced=> CmsCommMode

2. Set the CmsCommMode parameter to auto.

3. In the Control-M Configuration Manager, choose Tools => Security=> Manage SSL=> Generate Component Certificates...

   Two certificates (files) are generated in the Certificate_for Control-M_for_zOS folder.

   For Control-D/WebAcess Server, ready-made certificates can be found here:
   <Installation Path>/config/ssl/ioagte.

   • IOAGATE.PCK12

     This is the certificate which includes the private/public key pair of IOAGATE. This file is encrypted with a password that can be found in the README file created by Control-M/EM or provided in Control-D.

   • CACERT.PEM

     This is the certificate of the CA (Control-M/EM or Control-D) itself that is needed for decrypting IOAGATE.PCK12. If client authentication is required, this certificate is also the certificate of the CA that signed the certificate of the client.

4. FTP IOAGATE.PCK12 to z/OS in binary mode. Assume that the file name on z/OS is IOAGATE.PCK12.

   By default, FTP allocates the new file with the following attributes:

   • Organization: PS

   • Record format: VB

   • Record length: 256

   • Block size: 6233

5. FTP CACERT.PEM to z/OS in ASCII (text) mode. Assume that the file name on z/OS is CACERT.PEM.

   By default, FTP allocates the new file with the following attributes:

   • Organization: PS

   • Record format: VB

   • Record length: 256

   • Block size: 6233

6. Import CACERT.PEM to RACF using the following command:

   Copy

   RACDCERT CERTAUTH ADD ('CACERT.PEM') WITHLABEL('CACERTXX')

   Choose XX so that the name is unique and does not conflict with an existing name.

7. Create IOAGATERING (if it does not already exist) with the following command:

   Copy

   RACDCERT ID(GATEUSER) ADDRING(IOAGATERING)

8. Connect CACERTXX to IOAGATERING with the command:

   Copy

   RACDCERT ID(GATEUSER) CONNECT(CERTAUTH LABEL('CACERTXX')
   RING(IOAGATERING))

9. Import IOAGATE's certificate with the command:

   Copy

   RACDCERT ID(GATEUSER) ADD('IOAGATE.PCK12') TRUST WITHLABEL('IOAGATEXX')
   PASSWORD('ctm_zos_hhmm')

   The hhmm part of the password can be found in the README file generated by Control-M/EM.

10. Connect IOAGATEXX to IOAGATERING with the command

    Copy

    RACDCERT ID(GATEUSER) CONNECT(ID(GATEUSER) LABEL('IOAGATEXX')
    RING(IOAGATERING) DEFAULT USAGE(PERSONAL))

11. For connecting to Control-M Configuration Manager and to Control-M/EM, define the following in ECAPARMC and in ECAPARMM CHANNELs:

    • SSL=YES

    • KEYRING=IOAGATERING

    • KEYRLAB=IOAGATEXX

    If client authentication is needed, also specify:

    • CLIAUTH=YES

    Both IOAGATEC and IOAGATEM must have the same SSL definitions.

12. Stop and restart IOAGATEM and IOAGATEC.

Using Variations of the Basic Methods

Key pairs and certificates can either be created for IOAGATE by using RACF on the mainframe and then certified with an external CA or they can be generated outside the mainframe and then imported to the mainframe. These procedures are described in this section.

Certifying Keys Created with RACF Using an External CA

This procedure describes how to certify keys created with RACF using an external CA.

Begin

1. Define a local CA certificate and a digital certificate for IOAGATE as described in the first steps of the following procedure: "To create keys and certificates using RACF" in Using the Basic Methods: RACF or Control-M Configuration Managers.

2. Generate a certificate request for IOAGATE, using following command:

   Copy

   RACDCERT ID(GATEUSER) GENREQ (LABEL('IOAGATE')) DSN('hlq.GENREQ')

   The GENREQ command generates a certificate request in PKCS#10 format, based on an existing certificate with a private key and writes it to hlq.GENREQ.

3. Send the resulting file to a CA for signing. The reply from the CA contains the signed certificate.

4. FTP (in ASCII mode) the reply from the CA to the mainframe, replacing the IOAGATE certificate.

   The following command assumes that the certificate has been uploaded into the hlq.NEWCERT.PEM data set:

   Copy

   RACDCERT ID(GATEUSER) ADD('hlq.NEWCERT.PEM')  TRUST WITHLABEL('IOAGATE')

Creating Keys and Certificates Manually, and Importing them into the Mainframe

This procedure describes how to create keys and certificates externally, and then import them into the mainframe.

Begin

1. Generate and export the certificate to be used by IOAGATE including the private key in PKCS#12 format.

   The exact generation and export process depends on the platform and tool being used, and is not described here. The export process will request a password for encrypting the generated file. This password is needed in the next step.

2. FTP (in ASCII mode) the certificate of the CA, which signed the IOAGATE’s keys and certificates, to the mainframe and import it:

   Copy

   RACDCERT CERTAUTH ADD('hlq.CACERT1.PEM') WITHLABEL('CACERT1')

3. FTP the PKCS#12 file to the mainframe to a sequential file and import it:

   The PKCS#12 file must be transferred either in binary or in ASCII format, depending on the exact encoding of the PKCS#12 file. If the file is encoded using Base64 then it must be transferred in ASCII mode. Determine the required transfer mode by examining the first line. If the first line is "-----BEGIN CERTIFICATE-----", use ASCII format. Otherwise use binary format.

   The following assumes that the file has been uploaded to the 'hlq.GATECERT.P12' data set and that it has been encrypted with the password abcd1234:

   Copy

   RACDCERT ID(GATEUSER) ADD('hlq.GATECERT.P12') TRUST WITHLABEL('IOAGATE')
   PASSWORD('abcd1234')

Regardless of which of the above methods is used, the following procedures are required.

Creating a Keyring

This procedure describes how to create a keyring.

Begin

1. Create the RACF keyring for IOAGATE.

   The following command creates a keyring named IOAGATERING for user ID GATEUSER:

   Copy

   RACDCERT ID(GATEUSER) ADDRING(IOAGATERING)

2. Connect IOAGATE’s certificate to the keyring.

   The certificate containing the private key used for decryption must be connected to the user's keyring as the default certificate:

   Copy

   RACDCERT ID(GATEUSER) CONNECT(ID(GATEUSER)
   LABEL('IOAGATE')  RING(IOAGATERING) DEFAULT USAGE(PERSONAL))

3. Connect CA’s certificate to the keyring.

   Copy

   RACDCERT ID(GATEUSER) CONNECT(CERTAUTH
   LABEL('CACERT1')  RING(IOAGATERING)

Adding Client Authentication

This procedure describes how to add client authentication.

Begin

1. FTP (in ASCII mode) the CA's certificate to the mainframe and import it:

   Copy

   RACDCERT CERTAUTH ADD('hlq.CACERT.PEM') WITHLABEL('CACERT')

2. Connect the CA's certificate to IOAGATE's keyring:

   Copy

   RACDCERT ID(GATEUSER) CONNECT(CERTAUTH LABEL('CACERT') RING(IOAGATERING))

Using Demo Certificates for IOAGATE with Control-M

For testing SSL functionality between IOAGATE and Control-M/EM and Control-M Configuration Manager, install the demo certificates provided by Control‑M/EM and by IOA.

The following sample members are provided with the IOA installation in the SAMPLE library:

• CERTGATE - Demo certificate for IOAGATE, including a private/public key pair signed by the demo certificate authority that is included in the demo key database of Control-M/EM and Control-M Configuration Manager.

• CERTCA - Demo certificate of the above demo certificate authority.

• CERTCOPY - Sample job for copying the demo certificates to a sequential variable blocked (VB) file.

Enabling SSL on the Control-M/EM Side

This procedure describes how to enable SSL on the Control-M/EM side.

Begin

1. In the Control-M Configuration Manager, choose Tools => System Configuration=> Control-M/EM System Parameters=> Advanced=> CmsCommMode

2. Set the CmsCommMode parameter to auto.

For more information about the CmsCommMode parameter, see the "Control‑M/EM" sub-section in the "SSL communication parameters" section in the "Preparing to use SSL" chapter in the Control-M SSL Guide.

Enabling SSL on the INCONTROL Side

This procedure descrbies how to enable SSL on the INCONTROL side.

Begin

1. Copy the CERTCA and CERTGATE sample members to sequential files using the CERTCOPY sample job.

   This step is needed because RACDCERT must be provided with the demo certificates in a sequential VB file.

   The SAMPLE job CERTCOPY is listed below:

   Copy

   //COPYCERT  JOB (ACCOUNT),'PGMR',NOTIFY=&SYSUID
   //IEBGENER EXEC PGM=IEBGENER
   //SYSPRINT DD SYSOUT=*
   //SYSUT1 DD DISP=SHR,DSN=IOAP.V900.SAMPLE(CERTCA)
   //SYSUT2 DD DISP=(,CATLG),DSN=IOA.CERTCA.DEMO
   //       RECFM=VB,LRECL=84,BLKSIZE=27998,
   //       UNIT=3390,SPACE=(TRK,(1,1))
   //SYSIN DD DUMMY
   //*
   //IEBGENER EXEC PGM=IEBGENER
   //SYSPRINT DD SYSOUT=*
   //SYSUT1 DD DISP=SHR,DSN=IOAP.V900.SAMPLE(CERTGATE)
   //SYSUT2 DD DISP=(,CATLG),DSN=IOA.CERTGATE.DEMO
   //       RECFM=VB,LRECL=84,BLKSIZE=27998,
   //       UNIT=3390,SPACE=(TRK,(1,1))
   //SYSIN DD DUMMY

2. Import the CA certificate:

   Copy

   RACDCERT CERTAUTH ADD('IOA.CERTCA.DEMO') TRUST WITHLABEL('CACERT')

3. Import IOAGATE's certificate:

   GATEUSER is assumed to be the RACF USERID of IOAGATE. Replace all occurrences of GATEUSER in the sample commands below with the actual IOAGATE user ID.

   Copy

   RACDCERT ID(GATEUSER) ADD('IOA.CERTGATE.DEMO') TRUST WITHLABEL('IOAGATE')
   PASSWORD('abcd1234')

4. Define a key ring for IOAGATE:

   Copy

   RACDCERT ID(GATEUSER) ADDRING(IOAGATERING)

5. Connect the certificates to IOAGATE's keyring:

   Copy

   RACDCERT ID(GATEUSER) CONNECT(CERTAUTH LABEL('CACERT')
   RING(IOAGATERING)USAGE(CERTAUTH))
   
   RACDCERT ID(GATEUSER) CONNECT(ID(GATEUSER) LABEL('IOAGATE')
   RING(IOAGATERING))

Using Non-demo Certificates for IOAGATE with Control-D

This procedure describes how to use non-demo certificates for Control-D/WebAccess Server, or Control-D/File Transfer Option (FTO), from the distributed systems side.

Begin

1. Create a key pair for your server and a digital certificate contained in the ctdagent.keystore file.

   keytool -genkey -alias ctdagent –keyalg RSA -keystore keystore_file_path -storepass

   keystore_password -keypass keystore_password -dname distinquished_name

   The password for storepass and keypass must be identical.

   Where distinquished_name (X.509 attributes of the certificate) are:

   • Common name (CN): Control-D_Agent

   • Country name (C): IL

   • State (ST): NotApplicable

   • Locality (L): NotApplicable

   • Organization (O): bmc

   • Organization Unit (OU): DBA

   Copy

   keytool -genkey -alias ctdagent -keyalg RSA -keystore ctdagent.keystore1
   storepass sarina -keypass sarina -dname "C=IL, CN=Control-D_Agent,
   ST=NotApplicable, L=NotApplicable, O=BMC, OU=DBA"

2. Generate a certificate signing request (CSR).

   1. Run the following keytool utility to export a CSR from the keystore in order to sign it:

      keytool -certreq -alias ctdagent -keystore keystore_file_path –storepass keystore_password -file certfilename.crs

      Copy

      keytool -certreq  -alias ctdagent -keyalg RSA -keystore ctdagent.keystore1
      -storepass sarina -file ctdagentCerttest.crs

      Use a private or commercial trusted CA to sign the certificate. In the following sample we will connect to VeriSign http://www.verisign.com/ to get a trial certificate.

      The CSR you have previously generated is a string of text generated by your server. Provide this string to VeriSign during the enrollment process.

      When enrolling for your certificate, you will be prompted to select a server platform. In our case, select Server not listed and type Java keystore.

      Figure 52 VeriSign Trust Center

      

   2. You will receive the trial SSL certificate by mail.

      Perform the instructions described in the mail that you receive.

3. Install the CA certificates:

   Install the Trail Root CA and the Trail Intermediate CA certificate on the server’s keystore.

   Download the root CA certificate from the link that you receive by mail and save it with the following name: rootCA.cer

   Download the intermediate CA certificate from the link and save it with the following name: intermediateCA.cer

4. Import the root CA certificate and the intermediate CA certificate:

   1. Import the root CA to your keystore file with the following command:

      keytool –import –alias RootCA –keystore <your_keystore_filename> -trustcacerts –file rootCA.cer

      Copy

      > keytool -import -alias RootCA -keystore ctdagent.keystore1 -file
      rootCA.cer -trustcacerts
      Enter keystore password:  tsarina
      Owner: CN=VeriSign Trial Secure Server Root CA - G2, OU="For Test Purposes
      Only.  No assurances.", O="VeriSign, Inc.", C=US
      Issuer: CN=VeriSign Trial Secure Server Root CA - G2, OU="For Test Purposes
      Only.  No assurances.", O="VeriSign, Inc.", C=US
      Serial number: 168164a428ca12dfab12f19fb1b93554
      Valid from: 4/1/09 3:00 AM until: 4/1/29 2:59 AM
      Certificate fingerprints:
          MD5:  E0:19:F5:FC:C0:9A:13:0E:38:B7:BF:0D:02:40:D3:C2
          SHA1: 51:51:B8:63:8A:4C:1F:15:54:56:ED:37:C9:10:35:CA:D3:01:B9:36
      Trust this certificate? [no]:  yes
      Certificate was added to keystore

   2. Import your intermediate CA certificate to your keystore file with the following command:

      keytool –import –alias IntermediateCA –keystore <your_keystore_filename> -trustcacerts –file intermediateCA.cer

5. Install the trail SSL certificate:

   Copy the certificate from your mail and paste it into a text file using notepad or vi.

   Enter the following command to import your trail SSL certificate:

   keytool –import –alias <your_aliasname> –keystore <your_keystore_filename> -trustcacerts –file <your_certificate_filename.DER>

   The alias name in this command must be the same as the alias name used during the generation of the private key and CSR. The signed certificate must be in X.509 DER (Definite Encoding Rule) format.

   Copy

   keytool -import -alias ctdagent  -keystore ctdagent.keystore1 -file
   signedcert.der -trustcacerts

6. Configure the ctdagent.ssl.properties file and change your keystore password

   1. Update parameter: KeystoreFile=ctdagent.keystore1

   2. Change the encrypted KeystorePassword:

      • Run bmc-ctd-ssl-changepass (UNIX) or ctd-ssl-changepass.bat (Windows) from the <INSTALLATION PATH>/bin directory.

      • Enter a new password at the prompt to update the ctdagent.ssl.properties configuration file.

7. Recycle the Control-D/Agent file transfer server service.

Using Non-demo Certificates for Control-D, from the Mainframe Systems Side

This procedure describes how to use non-demo certificates for Control-D, from the mainframe systems side.

Before You Begin

This level is specified by setting SSL=Yes and CLIAUTH=No (the default when SSL=Yes) in the ECAPARM member.

The following certificates must be in place for this support:

• IOAGATE must have a certificate representing a private/public key and signed by a CA. This certificate must be defined in SAF (for example, RACF) and added to the keyring defined for IOAGATE by the KEYRING parameter in the ECAPARM member.

• The certificate of the CA that has signed IOAGATE's certificate must be added to the key database on the peer side.

Begin

1. Define a local certificate authority and a digital certificate for IOAGATE

   1. Generate a local Certificate Authority

      Copy

      RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('Control-D_Agent') O('BMC')
      C('IL') L(‘NotApplicable’) SP(‘NotApplicable’)) KEYUSAGE(CERTSIGN)
      WITHLABEL('GATECA')

   2. Generate a Digital Certificate with a Private Key for IOAGATE

      A digital certificate with a private key must be generated for the IOAGATE user.

      Copy

      RACDCERT ID(STCUSER) GENCERT SUBJECTSDN(CN(' Control-D_Agent')
      O('BMC') C('IL') L('NotApplicable')
      SP('NotApplicable'))WITHLABEL('IOAGATE') SIGNWITH(CERTAUTH
      LABEL('GATECA')) KEYUSAGE(HANDSHAKE)

   3. The RACDCERT ALTER command is required to add the TRUST attribute to the certificate:

      Copy

      RACDCERT ID(STCUSER) ALTER (LABEL('IOAGATE')) TRUST

2. Generate a certificate request (CSR) for IOAGATE

   The following command will generate a certificate request and write it to hlq.GENREQ:

   Copy

   RACDCERT ID(STCUSER) GENREQ (LABEL('IOAGATES')) DSN('ilprefa.GENREQ')

3. Send the CSR file to a certificate authority for signing.

4. FTP (in ASCII mode) the reply containing the signed certificate to the mainframe, and import it as IOAGATE’s certificate.

   The following command assumes that the certificate has been uploaded into data set hlq.NEWCERT.PEM:

   Copy

   RACDCERT ID(STCUSER) ADD('IOAQ.Q71MN.NEWCERT.PEM') TRUST WITHLABEL('IOAGATES')

5. FTP (in ASCII mode) the certificate authority's certificate to the mainframe and import it:

   You will receive a mail from Verisign. Install the intermediate certificate according to the mail. The following commands import the intermediate certificate:

   Copy

   RACDCERT CERTAUTH ADD('ilprefa.CACERT.PEM') WITHLABEL('CACERTV')

6. Connect the certificates to IOAGATE’s keyring.

   Copy

   RACDCERT ID(STCUSER) CONNECT(CERTAUTH LABEL('CACERTV')
   RING(IOAGATERING)USAGE(CERTAUTH))
   
   RACDCERT ID(STCUSER) CONNECT(ID(GATEUSER)
   LABEL('IOAGATES')RING(IOAGATERING))

7. Recycle IOAGATE and application server.

Using Demo Certificates for IOAGATE with Control-D

For Control-D/File Transfer Option (FTO), Control-D/Agent provides a DEMO certificate signed by the DEMO CA of Control D . The Control-D for z/OS is also signed by the same DEMO CA.

For SSL setup for Control-D/WebAccess Server, verify that you have already obtained the keys and certificates using the Generating Certificates with Control-M/EM or "Bring Your Own".

Enabling SSL on the Control-D/Agent File Transfer Server

This procedure describes how to enable SSL on the Control-D/Agent file transfer server.

Begin

1. In the configuration file, sesmgr.config, <INSTALLATION PATH>/config, set SSL true to enable the server to listen in SSL mode on the port.

2. Restart Control-D/Agent file transfer server.

Enabling SSL on the Control-D/Agent File Transfer Client

This procedure describes how to enable SSL on the Control-D/Agent file transfer server.

Begin

The -ssl command line parameter should be added to the command line to communicate with the host using SSL.

bmc-ctd-sftclient  -h=host -p=port -u -f=input_file -d=output  -ssl

The Control-D file transfer client can send files to Control-D on z/OS via IOAGATE when IOAGATE is configured for Control-D/File Transfer Option support.

Setting Up the Control-D/File Transfer Option or the Control-D/WebAccess Server in IOAGATE for SSL

This procedure describes how to set up the Control-D/File Transfer Option or the Control-D/WebAccess Server in IOAGATE for SSL.

Begin

1. Specify the following parameters in ECAPARM:

   Copy

   SSL=YES,
   KEYRING=<IOAGATE's keyring>,
   KEYRLAB=<IOAGATE's certificate label>,
   CLIAUTH=NO | YES,
   SSL=YES,
       KEYRING=IOAGATERING,
       KEYRLAB=IOAGATEF,
       CLIAUTH=NO,

2. Use the following members in the SAMPLE library:

   • CERTGATF - DEMO Certificate for IOAGATE with private-public key pair signed by the DEMO certificate authority

   • CERTCAF - DEMO Certificate of the CA with its public key

   • CERTFTOF - Sample job to convert certificates to files that can be used as input to RACDCERT

3. Copy SAMPLE members CERTCAF and CERTGATF to sequential files using sample job CERTFTOF.

   This step is needed because RACSCERT must be provided with the demo certificates in a sequential VB file, with trailing blanks removed.

   Assume that these files will be called IOAQ.Q71MN.CERTCAF.DEMO and IOAQ.Q71MN.CERTGATF.DEMO.

   Copy

   //Q53CER JOB ,OR,CLASS=A,MSGCLASS=X,REGION=0M,NOTIFY=&SYSUID    
   //*                                                             
   //*                                                             
   //    JCLLIB  ORDER=IOAQ.Q71MN.PROCLIB                          
   //    INCLUDE MEMBER=IOASET                                     
   //COPY1  EXEC PGM=SORT                                          
   //SYSOUT DD SYSOUT=*                                            
   //SORTIN DD DSN=IOAQ.Q71MN.SAMPLE(CERTCAF),DISP=SHR             
   //VBOUT  DD DSN=IOAQ.Q71MN.CERTCAF.DEMO,                        
   //      DISP=(NEW,CATLG,DELETE),                                
   //      SPACE=(TRK,(1,1),RLSE),                                 
   //      VOL=SER=IOAQ31,UNIT=3390,                               
   //      DCB=(RECFM=VB,LRECL=68,BLKSIZE=6800)                    
   //SYSIN DD *                                                    
     OPTION COPY                                                   
     OUTFIL FNAMES=VBOUT,FTOV,VLTRIM=X'40'                         
   /*                                                              
    //COPY2  EXEC PGM=SORT                                          
    //SYSOUT DD SYSOUT=*                                            
    //SORTIN DD DSN=IOAQ.Q71MN.SAMPLE(CERTGATF),DISP=SHR            
    //VBOUT  DD DSN=IOAQ.Q71MN.CERTGATF.DEMO,                       
    //      DISP=(NEW,CATLG,DELETE),                                
   //      SPACE=(TRK,(1,1),RLSE),                                 
   //      VOL=SER=IOAQ31,UNIT=3390,                               
   //      DCB=(RECFM=VB,LRECL=68,BLKSIZE=6800)                    
   //SYSIN DD *                                                    
     OPTION COPY                                                   
     OUTFIL FNAMES=VBOUT,FTOV,VLTRIM=X'40'                         
   /*

4. Go to RACF and issue the following RACF commands:

   1. Import the CA certificate:

      Copy

      RACDCERT CERTAUTH ADD('IOAQ.Q71MN.CERTCAF.DEMO') TRUST
      WITHLABEL('CACERTF')

   2. Import IOAGATE's certificate:

      Copy

      RACDCERT ID(STCUSER) ADD('IOAQ.Q71MN.CERTGATF.DEMO') TRUST
      WITHLABEL('IOAGATEF') PASSWORD('abcd1234')

   3. Define a key ring for IOAGATE:

      Copy

      RACDCERT ID(STCUSER) ADDRING(IOAGATERING)

   4. Connect the certificates to IOAGE's keyring:

      Copy

      RACDCERT ID(STCUSER) CONNECT(CERTAUTH LABEL('CACERTF')
      RING(IOAGATERING) USAGE(CERTAUTH))
      
      RACDCERT ID(STCUSER) CONNECT(ID(STCUSER) LABEL('IOAGATEF')
      RING(IOAGATERING))

      RING according to KEYRING defined in ECAPARM.

   5. Recycle IOAGATE and the application server of Control-D/File Transfer Option.

Useful RACF Commands

The command:

RACDCERT ID(STCUSER) LISTRING(IOAGATERING)

shows the following (sample):

Digital ring information for user STCUSER:                           
                                                                                     
 Ring:                                                              
      >IOAGATERING<                                                 
 Certificate Label Name             Cert Owner     USAGE      DEFAULT
 --------------------------------   ------------   --------   -------
 CACERT15                           CERTAUTH       CERTAUTH     NO  
 IOAGATED0112                       ID(STCUSER)    PERSONAL     YES

The command:

RACDCERT ID(STCUSER) LIST

shows the following (sample):

 Label: IOAGATED0112
   Certificate ID: 2Qfi48Pk4sXZydbBx8HjxcTw8fHy
   Status: TRUST
   Start Date: 2009/12/01 15:12:26
   End Date:   2029/11/26 15:12:26
   Serial Number:
        >00F844CEEA5CB9AD20<
   Issuer's Name:
        >[email protected]=A.OU=Tzahi.O=Efrat.L=Nir.SP=kuku.C=IL<
   Subject's Name:
      >[email protected]=CONTROL-M for z/OS.OU=CONTROL-MaD.O=BMC <
      >Software Ltd..L=Tel-Aviv.SP=NA.C=IL<
   Private Key Type: Non-ICSF
   Private Key Size: 1024
   Ring Associations:
     Ring Owner: STCUSER
     Ring:
        >IOAGATERING<

Validation of an Incoming IP Address

This feature enables you to validate incoming IP addresses against a table in the ECAIPLSx member in IOA.PARM library. This list of IP addresses is a source table that contains IP addresses that are allowed or forbidden to communicate with IOAGATE. All incoming addresses are checked against the table.

Define these IP addresses using one of the following methods:

• Defining specific IP addresses. For IPv4 addresses, these entries define the implicit subnet mask, 255.255.255.255

• For IPv4 addresses, defining the full range of IP addresses for a given IP segment, by placing asterisks in that segment and in all subordinate segments. With this notation, the IP address range a.b.*.* means that the last two segments of the incoming IP address can be anything and you only want to check the first two segments. Such entries define an implicit subnet mask with zeros in the segments where the asterisks appear and 255 in the other segments. For example, the range 165.4.*.* defines the subnet mask 255.255.0.0. This subnet means that only the first two segments are checked.

• For IPv4 addresses, defining a range using a standard subnet mask. You should use this method when you want to define a range of IP address which does not fall in exact segment boundary. For example, 165.4.240.0,MASK=255.255.240.0 means that you want to check the first two segments and also the four leftmost bits of the third segment (240=X'F0').

• For IPv6 addresses, defining a range of addresses by specifying the lowest and highest addresses in the range. For example:

  Copy

  ALLOW FD66:BC12:AC12:101::1-FD66:BC12:AC12:101::FFFF

  The low and high addresses must be separated by one hyphen, no spaces.

  ALLOW * and FORBID * apply also to IPv6 addresses.

  If the text extends beyond column 70 (for example, if the 2 IP addresses are 39 character long each), use the following 2-line format:

  • Line 1: ALLOWFR or FORBIDFR in column 1, followed by a space and the low IP address.

  • Line 2: ALLOWTO or FORBIDTO in column 1, followed by a space and the high IP address.

    Copy

    ALLOW *
    FORBIDFR 2001:500:100:1191:250:56FF:FEB7:4A30
    FORBIDTO 2001:500:100:1191:250:56FF:FEB7:4A39

Guidelines for Defining IP Addresses

Up to 999 records can be specified in a list of IP addresses. The order of ALLOW and FORBID statements is not important.

Define IP addresses using the following guidelines:

• Any IP address or range of addresses that you want to permit, must begin with ALLOW. Any IP address or range of addresses that you want to restrict must begin with FORBID

  ALLOW * and FORBID * are the only valid shorthand entries. All other IP addresses must have 4 segments separated by a period.

• The first statement of the list must always be either ALLOW * or FORBID *. An asterisk in such statement means all addresses or no address. Both ALLOW * and FORBID * statements create the following mask: 0.0.0.0

• If an address matches more than one rule, the rule that is more specific is the one that is applied. The absolute value of a mask as a hexadecimal number determines how specific the rule is. The greater the absolute value of the mask associated with a rule, the more specific it is.

  The IP address 165.4.241.7 matches both of the following rules:

  Copy

  ALLOW 165.4.*.*        
  FORBID 165.4.240.0,MASK=255.255.240.0

  The rule ALLOW 165.4.*.* has the implicit mask 255.255.0.0 associated with it. The second rule uses the mask 255.255.240.0, which has a higher value, meaning the second rule is more specific. The result is that the connection from IP address 165.4.241.7 will be rejected.

• When an IP address matches multiple rules where no one rule is more specific than the rest, FORBID is applied.

The source format of an IP List is processed at the initialization of IOAGATE (when IOAGATE is started) and when a F IOAGATE,REFRESH=ECAIPLSx modify command is issued to detect syntax errors.

For more information on defining a list of IP addresses, refer to the ECAIPLS Member

Name suffix parameter in Adding Channels.

IOAGATE Network Map

Separate IOAGATE gateways can connect one application to another. Control-O and Control-M JCL Verify currently use this method of communication to enable one Control-x (Control-O or Control-M JCL Verify monitor - CTJMON) application to pass information to another Control-x application, each using a separate IOAGATE gateway. For Control-O, this connection uses either the SNA or TCP/IP protocol. For Control-M JCL Verify this connection uses the TCP/IP protocol.

Throughout this section Control-O is used to demonstrate this method of communication – though everything described is true for Control-M JCL Verify as well other than where stated otherwise.

Figure 53 IOAGATE Connecting Instances of Control-O

IOAGATE must be able to discern whether it is connecting to another IOAGATE gateway or directly to another application server. This is done by network mapping.

Defining the IOAGATE Network Map

Creating a network map to connect IOAGATEs on different machines at various sites requires defining the network map member in the IOA PARM library. The member name is specified by the NETWMAP parameter in ECAPARM. The IOA SAMPLE library contains a sample member, ECANWMAP, with sample definitions that can be customized for your site.

Planning the Network Map

All ECAPARM members of all IOAGATEs in your network must be defined. Each one should have a unique NODE (GTWID in previous versions).

Decide which application servers should communicate with each other. A sketch of all network entities and their connections should be drawn.

Example

This example illustrates SNA and TCP connections. For more information, refer to the ECANWAP member in the IOA SAMPLE library.

There are three mainframes at the site:

• MF01

• MF02

• MF03

Control-O and IOAGATE are installed on each one.

MF01 Definitions: The ECAPARM member includes:

MF02 Definitions: The ECAPARM member includes:

MF03 Definitions: The ECAPARM member includes:

Application server CONTROLO in MF01 should communicate with CONTROLO in MF02, and application server CONTROLO in MF01 should communicate with CONTROLO in MF03.

The following figure illustrates the network map for the sample configuration.

Coding the Network Map

When coding the network map in the IOA.PARM library member with the name specified in the ECAPARM NETWMAP parameter, BMC recommends that you code the network map for the whole network and distribute this member to all sites that run IOAGATE. Each IOAGATE is able to extract the relevant information for itself from the same global map definitions.

All the parameters in the network map are mandatory.

The following are sample coded network maps that correspond to the sample configuration in the Example above.

Figure 55 Sample Coded Network Map for SNA

LOCAL  APPL=CONTROLO,NODE=GATE01
                PARTNER APPL=CONTROLO,NODE=GATE02,LUNAME=LU02
                PARTNER APPL=CONTROLO,NODE=GATE03,LUNAME=LU03
                LOCAL  APPL=CONTROLO,NODE=GATE02
                PARTNER APPL=CONTROLO,NODE=GATE01,LUNAME=LU01
                LOCAL  APPL=CONTROLO,NODE=GATE03
            PARTNER APPL=CONTROLO,NODE=GATE01,LUNAME=LU01

Figure 56 Sample Coded Network Map for TCP

LOCAL  APPL=CONTROLO,NODE=GATE01
                PARTNER APPL=CONTROLO,NODE=GATE02,HOST=HOST2,
                PORT=2760,CONNECTOR=LOCAL
                PARTNER APPL=CONTROLO,NODE=GATE03,HOST=HOST3,
                PORT=2760,CONNECTOR=LOCAL
                LOCAL  APPL=CONTROLO,NODE=GATE02
                PARTNER APPL=CONTROLO,NODE=GATE01,
                CONNECTOR=PARTNER
                LOCAL  APPL=CONTROLO,NODE=GATE03
                PARTNER APPL=CONTROLO,NODE=GATE01,
            CONNECTOR=PARTNER

Each LOCAL statement defines a specific IOAGATE in the network. Each PARTNER statement under the LOCAL statement defines another remote IOAGATE with which this specific IOAGATE will communicate.

When an IOAGATE starts, it reads the network map member specified in the ECAPARM member and locates the LOCAL statement that corresponds to that IOAGATE. This LOCAL statement is the one that has the same value in the NODE parameter as the value coded in the NODE parameter of the ECAPARM member.

In the sample network map in Figure 43, because the IOAGATE on MF01 in Figure 42 has NODE set to GATE01 in the ECAPARM member, that IOAGATE locates the first LOCAL statement in the network map. That IOAGATE establishes a connection with each partner IOAGATE specified in the PARTNER statements under that LOCAL statement.

Considerations For SNA — The connection to the partner IOAGATE is the LUNAME specified on the PARTNER statement. This LUNAME must match the APPLID in the ECAPARM member of the partner IOAGATE. Each IOGATE initiates a connection to its partner IOAGATEs, so that between each pair of IOAGATEs there are two connections.

For example, in the configuration illustrated in Figure 42, the IOAGATE on MF01 connects to both LU02, which is the IOAGATE on MF02 (because it has APPLID=LU02), and LU03, which is the IOAGATE on MF03.

Considerations For TCP — The connection to the partner IOAGATE is to the host and port specified by the HOST and PORT parameters, but only if CONNECTOR is set to LOCAL. If CONNECTOR is set to PARTNER, IOAGATE waits for the partner IOAGATE to initiate the connection. Therefore, you must define one IOAGATE with CONNECTOR set to LOCAL and the other with CONNECTOR set to PARTNER.

The PORT parameter defined in the MAP must match the port on which the partner IOAGATE listens for incoming connections. That port is defined in the ECAPARM CHANNEL statement of the partner IOAGATE.

For example, in the configuration illustrated in Figure 42:

• IOAGATE on MF01 connects to both

  • port 2760 on HOST2, which is IOAGATE on MF02, because it listens to on port 2760 to HOST2

  • port 2760 on HOST3, which is IOAGATE on MF03

• HOST2 must resolve to an IP address of TCP/IP on MF02

• HOST3 must resolve to an IP address of TCP/IP on MF03

• IOAGATE on MF02 and IOAGATE on MF03 wait for MF01 to initiate the connection

The value of APPL can be any of the following:

• J (for Control-M JCL Verify)

• O (for Control-O)

• CONTROLO

• ControlO

Structure of the IOA Conditions File

The IOA Conditions file is comprised of the following parts:

• 1 physical record for synchronization purposes.

• 32 logical records for prerequisite conditions, as follows:

  • 31 logical records; one for each day of the month.

  • 1 logical record for STAT conditions.

The record size, in bytes, of a physical record in the IOA Conditions file is fixed at 32 KB.

The CNDREC# parameter specifies the number of physical records in each logical record.

Each prerequisite condition requires 24 bytes. Therefore, the number of conditions allowed for each date is equal to 1/24 of the 32 KB times the value specified for the CNDREC# parameter. You can also use long condition names. Each long condition name occupies two entries, or 48 bytes each.

Due to MVS access method limitations, a maximum of 32KB bytes can be specified for the record size of a physical record in the IOA Conditions file. This default value is the maximum block size for 3380 disks and 3390 DASD devices. This default allows a maximum of 1365 conditions in each prerequisite condition record of the IOA Conditions file.

If your site uses a large number of conditions such as OUT conditions created by Control‑M, and you require more than the maximum 32KB for each record in the IOA Conditions file, additional slots can be allowed for each record. For more information about this option, see "CNDREC#" in Parameters.

Use the following formula to calculate the region size needed for the IOA Conditions file:

32760 * ((32 * CNDREC#) + 2 + INT((CNDREC# - 1 ) / 255) )

The following examples illustrate the use of the formula:

• If CNDREC# is set to 1, about 1.11 MB of virtual storage is needed to load the IOA Conditions file.

• If CNDREC# is set to 2, about 2.16 MB of virtual storage is needed to load the IOA Conditions file.

For more information about the CNDREC# parameter, see Step 5 – Specify Target Configuration Parameters.

Housekeeping

The following topics describe various housekeeping options available from the Maintain your Environment option on the ICE Main Menu:

• Accessing Housekeeping Activities

• Reference

• Refresh Tables

• Tailor Job

• Copy Procedure

Accessing Housekeeping Activities

To access housekeeping activities, do the following:

1. Open the IOA Installation—Main menu.

2. Select the Maintain your Environment option.

3. Select the ICE refresh option.

   The IOA Installation – ICE refresh screen is displayed.

   Figure 57 IOA Installation: ICE Refresh Screen

--------------------- IOA Installation - ICE refresh  ------------------------
                OPTION  ===>                                                                  
                Environment: DOC900                                                           
                Product: IOA               Enforce Step Order ==> YES                          
                   Reference Libraries Prefix: IOAP.V900                                      
                   1  REFERENCE       - Insert Reference into Parameters Table                
                   2  REFRESH TABLES  - Implement a New Set of ICE Tables                     
                   3  TAILOR JOB      - Tailor any Job from Installation Libraries            
               4  COPY PROCEDURE  - Copy a Procedure to a Site Procedure Library          

Reference

This option allows you to specify members of an existing installation from which values should be inserted into the reference column in the Parameters Table. Use this option to specify members other than the default members supplied during environment definition.

To access this option, do the following:

1. Type 1 in the OPTION field to select Option 1, REFERENCE, and press Enter.

   The Reference Member Specification Panel is displayed.

   Figure 58 Reference Member Specification Panel

   Copy

   --------------------- Reference Member Specification Panel -------------------
                           COMMAND ===>                                                                  
                           Product  IOA            Environment: DOC900                                   
                                Reference Member                                                         
                                ================                                                         
                                Type          Dataset Name                           Member              
                                DEFPARM   ==> IOAP.V9zz.PARM                     ==> DEFPARM             
                                xxxPARM   ==> IOAP.V9zz.PARM                     ==> IOAPARM             
                                The Reference release was determined according to the Reference libraries
                                prefix specified in the ENVIRONMENT table. Check/change the value.       
                                Reference release ==> 900                                                
                            Insert into REFERENCE column                     ==> YES  (Yes/No)       

2. The reference values can be retrieved from a version 8.x.xx installation or a version 7.x.xx installation. To do this, type 800 or 700, as appropriate, in the Reference release field, and press Enter.

   You can retrieve values from both the DEFPARM member and from the xxxPARM member or, if you want, from only one of these. If you leave the Member field blank in either line, no values will be retrieved from the data set referenced in that line.

3. When the process of retrieving the values has been completed, press Enter again. The IOA Installation – Main Menu is redisplayed.

Refresh Tables

Refreshes the current set of ICE tables, so that changes and modifications to the IOA and INCONTROL environments are implemented.

If a change results in the replacement of ICE tables, the new copy of the table must be merged with all values previously entered during installation, customization, and so on.

To refresh the ICE elements that were replaced by the change, type 2 in the OPTION field and press Enter.

The tables are refreshed.

After the tables are refreshed, the following message is displayed:

IOA7B8I ICE TABLES REPLACED

Tailor Job

Modifies jobs in the installation libraries. This can be used as an alternative method for modifying jobs that reformat (recreate) INCONTROL product Data Sets. During the installation process, only the jobs you select are tailored before submission and saved in the INSTWORK library. This option provides you with a method for building, or rebuilding, any job from the installation libraries.

As a default, the job is built in a temporary file but you can save the file in the INSTWORK library if you choose.

To use this method, do the following:

1. Type 3 in the OPTION field and press Enter. The Build a Job Specification Panel for this option is displayed.

   Figure 59 The Build a Job Specification Panel

   Copy

   ----------------------- Build a Job Specification Panel ----------------------
                           COMMAND ===>                                                                  
                                                                                                         
                           Product Code ..... ==> CTx                                                    
                                                                                                         
                           Job to be Tailored ==>                                                        
                                                                                                         
                           Output Library ... ==> TEMP             (TEMP=ISPF temporary file)            
                                                                   (INSTWORK=Standard ICE work library)  
                                                                                                         
                       Press Enter to build the job            PF3 to Exit                           

2. Insert values for the parameters in this screen, as shown in the following table:

   Table 175 Parameters in the Build a Job Specification Panel

   Parameter	Description
   Product Code	This parameter defaults to the INCONTROL product that corresponds to the Product ID that you specified.
   Job to be Tailored	The member name.
   Output Library	The output library to serve as the location for the tailored member. Valid values are: TEMP – The file is stored in a temporary location. Default. INSTWORK – The file is stored in the INSTWORK library.

3. When you have inserted values for the parameters in this screen, press Enter.

   The job is then built.

Copy Procedure

Copies procedures to a site procedure library.

Certain situations require that you manually copy a procedure to a site procedure library. For example, if the SITEPROC IOA installation parameter is set to DONTCOPY, you must copy a modified version of the CTRTROLR procedure to a site procedure library.

To do this, do the following:

1. Type 4 in the OPTION field and press Enter. The Build a Job Specification Panel for this option is displayed.

   Figure 60 Copy a Procedure Specification Panel

   Copy

   ----------------------- Build a Job Specification Panel   Enter required field
                           COMMAND ===>                                                                  
                           This utility copies an IOA procedure to a site procedure library.             
                           The procedure is copied with remame after the necessary JCL statements        
                           were inserted into it.                                                        
                           You can request that the members IOASET and IOAENV will be copied as well.    
   
                           Input procedure name  ==>                                                     
   
                           Output procedure name ==>                                                     
   
                           Site library ........ ==> DONTCOPY                                            
   
                           Copy IOASET and IOAENV==> Y   (Y/N)                                           
   
                       Press Enter to copy the procedure       PF3 to Exit                           

2. Define the parameters in this screen as shown in the following table:

   Table 176 Parameters in the Build a Job Specification Panel (2)

   Parameter	Description
   Input procedure name	Name of the procedure to copy.
   Output procedure name	To rename the procedure, specify a procedure name. Otherwise, leave blank.
   Site library	The name of your site procedure library.
   Copy IOASET and IOAENV	Indication that you want the IOASET and IOAENV members copied also to the new site procedure library. Valid values are: Y – Copy the IOASET and IOAENV members. Default. N – Do not copy the IOASET and IOAENV members.

3. Press Enter.

Uninstalling

This section discusses the uninstalling process activated from the INCONTROL Installation and Customization (ICE) Main Menu.

Before the uninstallion is performed, ICE displays a list of the datasets that were allocated by ICE for the current environment. These datasets will be deleted if you proceed with the uninstall. Review the list of datasets to ensure that these files are not used by another IOA environment, and then confirm that all the datasets are relevant to the current environment and can be deleted without affecting any other IOA environments.

Uninstalling an IOA Environment

This procedures describes how to uninstall an IOA environment.

Begin

1. On the main ICE panel, select Uninstallation.

2. When prompted, select the relevant environment.

3. When prompted, confirm that all the data sets are relevant to the current environment and can be deleted without affecting any other IOA environments.

Message Considerations

The JES, MVS, INCONTROL product and security (ACF2) messages listed in the following table should not be modified or suppressed by an automatic operator, since IOA and the INCONTROL products assume and are based on the original structure of these messages.

Table 177 Messages that Should Not Be Modified or Suppressed

Control-M Virtual Storage Requirements

The following topics describe the virtual storage requirements of the Control‑M monitor, files, and utilities:

• Control-M Monitor

• Control-M New Day Procedure

• Utility CTMCAJF

Control-M Monitor

The Control‑M monitor procedure Control-M is supplied with a default region size of 0 MB. The specified region size is honored by z/OS unless a local exit is employed to limit the region size of jobs and started tasks (STCs). The region size may be limited by MVS Exit IEALIMIT, by IEFUSI, or by other MVS and JES exits.

If Control‑M monitor startup fails due to insufficient region size, message IEF374I of the Control‑M monitor sysout can be examined to determine how much virtual storage was actually used.

At startup, the monitor obtains working storage. The monitor tries to allocate this storage above the 16 MB line. When the Journaling facility is enabled (parameter JRNL in member CTMPARM of the IOA PARM library is set to Y) storage above the bar (4GB) is also allocated.

Under certain circumstances, RMF and SDSF display incorrect real storage consumption of the monitor. They actually show virtual storage consumption. This can occur due to one or more of the following:

• There is no paging activity in the z/OS system.

• The Control-M monitor is running non-swappable.

In such cases, z/OS does not perform any page-outs and does not update its counters.

Calculations

Calculate the amount of virtual storage required by the Control‑M monitor by doing the following:

• considering the number of records in the Active Jobs File (AJF), as defined by parameter AJFSIZE in member CTMPARM in the IOA PARM library

  The monitor loads the entire Active Jobs file into virtual storage. Each entry of the Active Jobs file requires 1024 bytes. For example, assuming there are 20,000 records in the Active Jobs file, the Control-M monitor requires 20MB of storage above the 16MB line to process the Active Jobs file.

• considering the number of records per day defined for the IOA Conditions file (CND), and the blocksize of each such record, which is 32 K (32760 bytes)

  The monitor loads the entire CND file into virtual storage. When one record per day is defined by parameter CNDREC# in member IOAPARM, 1.05MB of virtual storage is needed by Control-M for the CND file.

  If one condition record per day is not sufficient to contain the required number of conditions, multiple records per day can be defined by means of parameter CNDREC# in member IOAPARM. The default value of CNDREC# is 1. A maximum of 32 records per day can be specified. The total number of records in the CND file can be calculated as follows:

  TOTAL CND RECORDS = (CNDREC# * 32) + 1

  To determine the total amount of virtual storage required by the CND file, multiply the total number of records by the record length. For example: If parameter CNDREC# equals 2 and the CND file contains 65 records, 2.06MB virtual storage is needed by the Control-M monitor for the CND file.

• determining how many records you need for quantitative and control resources. (This is usually done during product customization.) The system needs one additional record for its use

  If, for example, you define 5 records for quantitative and 5 for control resources, Control-M needs (5+5+1) * 32K bytes of virtual memory to accommodate all resources.

• adding space for the basic software used by the Control-M monitor, which requires between 750 to 1000K of virtual storage, depending on the environment and the functions used.

• In-memory Trace facility:

  The amount of virtual storage required by the Control-M monitor for the In-memory Trace facility (described in the IOA Admin guide) is determined by the buffer size specified in the member CTMTRCMx (x=L, M or H) in the CTM PARM library. The LINES parameter specifies the maximum number of lines to be held in memory. The calculation is as follows: Virtual Storage buffer required = Number of LINES * 192 The LINES parameter in the member may be modified by the user ifdesired. The virtual storage requirements for the Control-M Application server is determined by the buffer size specified in the member CTMTRCAx (x=L, M or H) in the CTM PARM library according to the formula above.

• setting aside space for user dependent work areas and programs

  • the size of user exits and the destination tables

  • the maximum size of AutoEdit members referenced at job submission time

  • the blocksize of the JCL library and of the library that contains AutoEdit members

  These items usually requires a small amount of virtual storage, and therefore it is not essential to calculate it exactly. However, remember to reserve some storage for these items.

• when the JRNL parameter is set to Y, considering the number of records in the Control-M AJF for Journaling Synchronization image (CKPJNL), as defined by the AJFSIZE parameter in the CTMPARM member in the IOA PARM library. This storage is obtained above the bar.

• periodically checking the content of message IEF374I in the sysout of the Control-M monitor to compare the actual storage requirements with the existing region size definition.

Control-M New Day Procedure

The amount of virtual storage required by the first step of the New Day procedure (procedure CTMTDAY) is determined by the size of the Active Jobs file plus the size of the IOA Conditions file (CND) plus the sizes of the Control‑M Resource files plus approximately 10% for additional areas required for processing.

If parameter HIST is set to YES in member CTMPARM (that is, History Active Jobs file processing is enabled), the amount of virtual storage required by the CLRHIST step of the CTMTDAY procedure is determined by the size of the History file plus approximately 10% for additional areas required for processing.

Utility CTMCAJF

The COMPRESS function of utility CTMCAJF requires the same amount of virtual storage as the Control‑M New Day procedure for the Active Jobs file.

The COPY utility requires virtual storage equivalent to the sum of the source and target files.

Defining Subsystems

In MVS, a subsystem can be defined dynamically or by adding it to an IEFSSNnn PARMLIB member. The definition in the IEFSSNnn member applies only after the next IPL. The dynamic definition applies immediately and lasts until the next IPL. The following topics describe how to define subsystems:

• Subsystem Definition

• Dynamic Subsystem Definition

• Special Considerations for Control-O

Subsystem Definition

Edit the IEFSSNnn member in the SYS1.PARMLIB library, where nn is the suffix specified in the IEASYS member in the SYS1.PARMLIB library. If the suffix is not specified in the IEASYS, the default is 00. The subsystem can be defined using positional or keyword parameter structure.

• When using the keyword parameter structure, add a record to the IEFSSNnn member in the following format:

  Copy

  SUBSYS SUBNAME(xxxx)

  where xxxx is the name of the subsystem

• When using the positional parameter structure, add a record to the IEFSSNnn member in the following format:

  xxxx

  where xxxx is the name of the subsystem

INCONTROL subsystems are initialized when their corresponding monitors are started. There is no need to define them in the IEFSSNnn member.

They can be defined in IEFSSNnn member without specifying a subsystem initialization routine.

If INCONTROL subsystems are defined, their position in the IEFSSNnn member is not important (see Special Considerations for Control-O).

INCONTROL subsystems are not affected by the BEGINPARALLEL statement, which might appear in IEFSSNnn, because INCONTROL subsystems have no subsystem initialization routines and the BEGINPARALLEL statement indicates that the subsystem initialization routines specified in SUBSYS statements that follow the BEGINPARALLEL statement are invoked in parallel.      

For more information, see the relevant IBM MVS Initialization and Tuning Reference.

Dynamic Subsystem Definition

There are number of ways a subsystem can be dynamically defined without having to perform an IPL.

• When an INCONTROL product or component is started and its subsystem is not defined, it can define the subsystem dynamically. The subsystem is added at the end of the subsystem chain and remains until the next IPL. Using this method, the subsystem does not have to be defined in IEFSSNnn.

  The decision whether dynamic definition is allowed is controlled by the IOA Installation SSALLOC parameter or, for the IOA Online Monitor, by the IOA Online Monitor global Dynamic definition parameter.

  For more information see the explanations for these parameters in the relevant product sections of this manual.

• The subsystem can be defined using the following operating system command:

  Copy

  SETSSI ADD,SUB=xxxx

  where xxxx is the name of the subsystem

  For more information, see the description of the SETSSI command in the IBM MVS System Commands manual.

• Certain products can define a subsystem dynamically. To use this method, see the appropriate product manual.

Special Considerations for Control-O

To enable Control-O to change or suppress subsystem commands (for example, commands for DB2 that start with the '-' character), the Control-O subsystem must be defined in the IEFSSNnn member BEFORE the definition of the target subsystems of these commands.

An exception to this rule is the interception of JES2 commands using the IEFJFRQ dynamic subsystem exit, instead of a Control-O subsystem. For more information, see the JCMDSSN parameter in Step 2.1 – Control-O Operational Parameters.

National Language Support Facility

BMC enables you to configure your system to support one or more of the following national languages, in addition to English:

• French

• German

• Japanese

The following topics describe the National Language Support installation:

• System Installation Preparation

• Installing National Language Support

System Installation Preparation

Install the National Language Support (NLS) from one of the following sources:

• The BMC Electronic Product Distribution (EPD) site

• CD

Installing NLS

This procedure describes how to install NLS.

Begin

1. Prepare your system.

   For information about the space requirements, see the INCONTROL for z/OS release notes that accompany this release. The DCB information for the image file is as follows:

   Copy

   RECFM=FB, LRECL=1024, BLKSIZE=27648

2. Transfer the image file to the mainframe as a binary file, by doing one of the following actions:

   • Download the National Language Support installation from the EPD site at http://www.bmc.com/available/epd.html

   • Copy the file from the productCD.

3. Uncompress the image file.

   The IBM TRSMAIN (alias of AMATERSE) program is required because the image files are delivered in a compressed format that was created using TRSMAIN.

   1. Once the image file has been uploaded to your mainframe, make the necessary changes in the following UNTERSE job to uncompress the image file.

      Copy

      **************************** Top of Data ******************************
                                      //UNTERSE JOB <=== tailor job card to local standards
                                      //*
                                      //UNTERSES EXEC PGM=TRSMAIN,PARM=UNPACK
                                      //SYSPRINT DD SYSOUT=*
                                      //INFILE DD DISP=SHR,DSN=uploaded.image.file <===UPDATE
                                      //OUTFILE DD DISP=(NEW,CATLG,DELETE),
                                      // UNIT=disk_unit,VOL=SER=disk_volser, <===UPDATE
                                      // DSN=basepref.NLSSUPP, <===UPDATE
                                      // SPACE=(CYL,(ppp,ss,dd)) <===UPDATE
                                  *************************** Bottom of Data ****************************

      In the preceding UNTERSE job:

      • basepref represents your choice of prefix for the base libraries, which are described in Loading ICE.

      • ppp,ss,dd represents the space requirements for the basepref.NLSSUPP file, as specified in the INCONTROL for z/OS release notes that accompany this release.

   2. Submit the UNTERSE job.

   3. Verify that the job completes with a return code of 0.

Installing National Language Support

This procedure describes how to install national language support.

Begin

1. Select Customization from the ICE main menu.

2. Select an environment.

3. Specify product IOA.

4. Select Product Customization.

5. Select step 19 (Install National Language Support).

6. Select minor step 1 (Select additional languages).

7. Select minor step 2 (Apply the National Language Support).

   These steps build the NLSINST job in the IOA INSTWORK library.

8. The NLSINST job is tailored according to the languages selected in minor step 1. In the following steps, lng represents the language selected for the installation, where

   • FRA or FR represents the French national language

   • GER or GE represents the German national language

   • JPN or JP represents the Japanese national language

   The following table describes the jobs used to install national language support.

   Table 179 National language Support Installation Steps

   Step name	Description
   ALLOCT	This job allocates the target and distribution language libraries, as follows: The target language libraries names are: ilprefa.ISMSGlng ilprefa.MSGlng ilprefa.PANELlng The distribution language libraries names are: spdpref.AISMSGlng spdpref.AMSGlng spdpref.APANELlng
   ADDDDEF	Adds SMP/E DDDEFs for language target and distribution libraries.
   RCV*	Performs the RECEIVE operation for the language FMIDs and PTFs, which are located in the lang8000 member in the BASEPREF.NLSSUPP library. The asterisk in the final character of the step name represents F - if the French national language has been selected G - if the German national language has been selected J - if the Japanese national language has been selected
   APPLCHK	Performs the APPLY CHECK operation for the language FMIDs and PTFs.
   APPLY	Performs the APPLY operations for the language FMIDs and PTFs.
   ACPTCHK	Performs the ACCEPT CHECK operation for the language FMIDs and PTFs.
   ACCEPT	Performs the ACCEPT operation for the language FMIDs and PTFs.

Japanese and French Screen Display Considerations

In order to complete the installation of Japanese or French language support, the Japanese and French version of IOAX037 (IOA user Exit 37) should be installed. This version is used to translate specific hexadecimal values. To install, follow the steps below.

Begin

1. Enter ICE.

2. Select Customization.

3. Select an environment.

4. In the Customization screen, set the Product ID to IOA.

5. Select Product Customization.

6. Select Step 4 (User EXITS Installation).

7. Select Minor Step 2 (EXITs Customization).

8. In the select Exit field, specify either the source of sample exit IOAX037J or IOAX037F is tailored to support the Japanese or French language support that you have installed.

9. Press PF3 to continue.

   Review the IOAX037 translation exit to verify that special characters of the selected language are translated correctly.

10. Submit JOB UMAX037J or IOAX037F to install this version of Exit 37 in your system.

    The first time that you run this job, it will complete with a condition code of 12. Examine the SMPOUT for this step, and verify that the only SMP/E command which completed with a condition code of 12 is the REJECT command. All other SMP/E commands should complete with a completion code of 0 (zero).

    For further information on modifying this exit, refer to the description of Exit IOAX037 in the Exits chapter of the INCONTROL for z/OS Administrator Guide.

Language Selection

Language selection is specified by the LANG parameter during the installation of INCONTROL. For further information on language selection, refer to Step 4.2 – IOA Operational Parameters, and "Step 2.4.2, IOA Operational Parameters", of the INCONTROL Installation and Customization Engine (ICE).

General Parameter Descriptions

Table 180 General Data Set Allocation Parameters

Installation Guide Planning Sheets

Installation planning sheets are included for the following types of installations:

• Express Installation

• Customized Installation

Express Installation

Installation planning sheets for the Express installation are located in the following section.

For additional details about parameters, see the installation process described for each specific product.

Express Installation Sheet

JOBNAME=IOAINS01
                                    JOBPOS=15
                                JOBCARD=,IOAINST,CLASS=A,MSGCLASS=X

//IOAINS01    JOB ,IOAINST,CLASS=A,MSGCLASS=X

Customized Installation

Detailed installation planning sheets are included for the following INCONTROL products:

• IOA Installation Sheet

• Control-M Installation Sheet

• Control-M JCL Verify Installation Sheet

• Control-M/Restart Installation Sheet

• Control-D Installation Sheet

• Control-V installation sheet

• Control-O Installation Sheet

• Control-M/Analyzer Installation Sheet

• Control-M/Tape Installation Sheet

• IOAGATE Installation Sheet

IOA Installation Sheet

Control-M Installation Sheet

Control-M JCL Verify Installation Sheet

Control-M/Restart Installation Sheet