Configuring HCI for a new install

This topic will assist you to customize the mainframe components needed to support the host communication from the mainframe. You do not need to configure an HCI or its started tasks unless you are using BMC AMI Strobe, Topaz, or any of BMC's Eclipse-based plug-ins.

Task 1: Defining journals

This task will assist you to allocate HCI and SSAS journal data sets. These journals are used by the HCI and SSAS jobs to log processing requests and to provide trace information that may be required by BMC for problem determination and resolution. The SSAS journals are only necessary if you are going to deploy the SSAS address space, to enable BMC DDIO file support in Topaz or the Code Coverage/Eclipse plug-in for BMC AMI DevX Workbench for Eclipse . See Configuring-BMC-AMI-DevX-Workbench-for-Eclipse.

1. Modify the sample JCL member HCIJOURN, located in library SLCXCNTL, to define the VSAM journals. The job will use IDCAMS to define and initialize the journal data sets. We recommend defining three journals for HCI use and two journals for SSAS use, as specified in the sample JCL.
2. Update the JCL:
   1. Add a job card.
   2. On the ALLOCJH step’s DEFINE statements, provide fully qualified data set names. We recommend you change all occurrences of "CPWR" to a specific high-level qualifier.
   3. On the ALLOCJC step’s DEFINE statements, provide fully qualified data set names. We recommend you change all occurrences of "CPWR" to a specific high-level qualifier.
3.  Submit the job and review the output to verify successful completion.

Task 2: Implementing HCI procedures

1. Modify the sample JCL member HCIPROCS, located in library SLCXCNTL, to create three PROCS to start HCI and to provide support to the HCI.

   Important

   The three PROCs that will be created are:

   • The HCIPROC — is the HCI started task procedure. Optionally, the HCI can be run via a batch job, typically to verify configuration. We recommend that the HCIPROC run as a started task that is managed by the CMSC.
   • The CXSSAS PROC — is the BMC AMI Common Shared Services (CSS) Address Space procedure. The CXSSAS PROC is primarily used for DDIO processing and for BMC AMI DevX Code Coverage  analysis. This PROC is designed to execute unauthorized.
   • The CXSS0000 PROC — is the CSS TP procedure. The CXSS0000 PROC is used to support File-AID and BMC AMI Strobe  processing. This PROC is designed to execute authorized.
2. Update the JCL:
   
   1. Add a job card.
   2. On the HCIPROC step’s SYSUT2 DD statement, specify a system PROCLIB where the job will write the three PROCs. In the sample JCL, SYS1.PROCLIB is specified, but can be changed to an appropriate PROCLIB for your installation.
   3. For the HCIPROC member, on the STEP1 step’s STEPLIB DD statement, update the SLCXAUTH library to your installation’s fully qualified data set name and specify a proc name.
   4. For the CXSSAS member, on the IEFPROC step’s STEPLIB DD statement, update the SLCXLOAD library to your installation’s fully qualified data set name and specify a proc name.
   5. For the CXSSAS member, the parameter &TPNAME is a value generated by the CSS TP internally and should not be modified.
   6. For the CXSS0000 member, on the IEFPROC step’s STEPLIB DD statement, update the SLCXAUTH library and proc to your installation’s fully qualified data set name.
3. Submit the job and review the output to verify successful completion.

Task 3: Customizing HCI parameters

BMC provides a default HCI PARMLIB member (HCI00), located in SLCXCNTL, that includes the core parameters for getting a viable HCI started. BMC provides a second HCI PARMLIB member (HCIALL) that includes all the possible parameters defined for use by HCI, and may include parameters with default values. The HCI Parameter member (default: HCI00) contains the customization parameters for HCI, CSS TP and (optionally) BMC AMI DevX DevEnterprise .

1. Copy the sample HCI PARMLIB member (HCI00), located in library SLCXCNTL, to your BMC PARMLIB data set.

2. Edit the copied member (HCI00) to provide values for the following parameters:

   SYSID=HCI0

   This parameter specifies your subsystem ID. SYSID must be four characters in length and start with an alpha character or #, $, @. The SYSID is used by the HCI initialization routines to dynamically create a z/OS subsystem. It must be unique among all subsystems running on this LPAR and must not be defined in a system PARMLIB.

   JOURNALn=HCI.&SYSNAME..JOURNALn. 
   These parameters (one for each HCI journal defined in Task 1: To define journals) specify journal data sets that allow for logging of HCI activity. The HCI uses the Journaling Facility to write out diagnostic information that may then be provided to BMC.

   Example:

   JOURNAL1=HCI.&SYSNAME..JOURNAL1

   Important

   Journal data sets cannot be shared across multiple HCI instances. Each HCI instances requires its own set of journal data sets.

   HCI_CONNECTION

    – PORT=16196

   This parameter specifies a port number in which the HCI listens for incoming connection requests. Check with your network administrator for an available port number.

   PORT_CONFIG=16196

   This parameter denotes the start of a CSS TP port configuration and must come after any required HCI parameter statements.

   Warning

   All parameters added to the HCIxx PARMLIB member need to come after the corresponding PORT_CONFIG for which they pertain.

   NOTIFY=YES

   This parameter enables the job notification feature. This feature provides for end-of-job notifications that are generated by the NOTIFY=userid JCL parameter to be sent to the user. The NOTIFY=userid JCL parameter is used on JOB statements.

   Normally, end-of-job notifications are sent to the TSO user. This remains in effect, regardless of whether the NOTIFY feature is enabled or disabled. Enabling the feature allows a copy of the same end-of-job notification to be sent to the user’s BMC AMI DevX Workbench for Eclipse instance, if started.

   NOTIFY_PURGE=2

   This parameter provides an automatic mechanism to purge messages that cannot be delivered to a Workstation user after a set period of days. Messages might be undeliverable because the user ID associated with the message never uses BMC AMI DevX Workbench for Eclipse, or the user ID has not used BMC AMI DevX Workbench for Eclipse for a period longer than the purge duration period. Purging undeliverable messages reduces overhead and keeps the storage required to maintain the undelivered messages to a reasonable level. The NOTIFY_PURGE duration value is in days.

   STASK=CXSS0000

   This parameter specifies the CSS TP Started Task procedure name. The STASK is required for CA-Endevor, BMC AMI DevX Data Studio's Data Privacy and/or File-AID/Eclipse plug-in support.

   SSAS_PROC=CXSSAS

   This parameter is the Shared Services Address Space procedure name. The SSAS_PROC parameter identifies the JCL procedure name used by the BMC AMI Common Shared Services Address Space (SSAS).

   SSAS_NAME=CXSSAS00

   This parameter is the Shared Services Address Space. The SSAS_NAME identifies the address space name to be used by the BMC AMI Common Shared Services Address Space (SSAS). This address space is intended to run unauthorized functions on behalf of BMC AMI DevX Workbench for Eclipse.

   LOCAL_ENV

    – PORT=16196

   This parameter identifies the port number of the HCI that owns this configuration section. The port number example of 16196 is the port number of the TP assigned to service BMC AMI DevX Workbench for Eclipse plug-in connections for this HCI image. This should be the same port number that is specified on the corresponding PORT_CONFIG statement.

    – HOST=HOST.NAME

   This parameter identifies the host name or the IP address of the HCI that owns this configuration section. If you use an IP address it must be in IPV4 format.

    – ZIIP=YES

   This parameter can enable the zIIP processor of the HCI that owns this configuration section. This parameter is set to YES by default, but can be changed to NO to disable the CSS TP to execute selected portions of TP activity on an available zIIP processor.

   HCI_ENV

    – PORT=16196

   This parameter is the port number of the CSS TP for this HCI image.
   
   You must code only one HCI_PORT statement in order to support Host Explorer connections to this LPAR, and it is the same HCI as that coded for LOCAL_* statements.

    – HOST=HOST.NAME

   This parameter specifies the host name or IP address of the operating system image where the HCI executes. If you use an IP address it must be in IPV4 format.

    – SYSNAME=CPWR-TP-&SYSNAME

   This parameter is the user-specified description for the HCI connection point for a given LPAR.
   You must code only one HCI_SYSNAME statement in order to support Host Explorer connections to this LPAR, and it is the same HCI as that coded for LOCAL_* statements.

    – LPAR=&SYSNAME

   This parameter is the name of the LPAR that this HCI image will be executing.

   You must code only one HCI_LPAR statement in order to support Host Explorer connections to this LPAR, and it is the same HCI as that coded for LOCAL_* statements.

   Important

   For a complete list of HCI parameters, see HCI-configuration-parameters.

3. If you changed your HCI PARMLIB member name from the default HCI00 (for example: HCI0005), update your CMSC PARMLIB member to contain the suffix of the new HCI PARMLIB member, HCI=0005.

Example HCI PARMLIB member configured for two Code Pipeline instances

Task 4: Verifying

1. Modify the sample JCL member HCITEST, located in library SLCXCNTL, to execute the verification job. The job will attempt to ping the HCI to validate the connection.
   1.  Add a job card.
   2. On the IVP step’s STEPLIB DD statement, update the SLCXLOAD library to your installation’s fully qualified data set name.
   3. On the IVP step’s SYSIN DD for both the HOSTIP and PORT:
      1. HOSTIP – Must contain the value of the host address in which the HCI is executing. It can be the host DNS name or the host IP address.
      2. PORT – Must represent the port on which the HCI is listening.
2. Submit the job and review the output.

   1. If a connection was established, the output should resemble:

      BMC AMI HCI TP Connection Verification Utility
      Control statement specification:
      HOSTIP=MVS1.XYZCORP.COM
      PORT=16196
      
      OPEN connection     RC = 00, ERRNO=00000
      SEND data           RC = 00, ERRNO=00000
      RECV data           RC = 00, ERRNO=00000
      SEND data           RC = 00, ERRNO=00000
      RECV data           RC = 00, ERRNO=00000
      
      Connection to the port was successfully validated.
      Valid BMC mainframe product license verified.

   2. If a connection cannot be established, or there are error conditions present, the output resembles:

      BMC AMI HCI TP Connection Verification Utility
      
      Control statement specification:
      HOSTIP=MVS1.XYZCORP.COM
      PORT=16196
      
      OPEN connection     RC = 00, ERRNO=00000
      SEND data           RC = 00, ERRNO=00000
      RECV data           RC = 28, ERRNO=00054
      
      The connection was unexpectedly terminated. Possible causes:
      * HCI configuration macros HCICNPCB or HCICNTPT are not correctly set.
      * The PORT number specified is a secure port via AT-TLS.
      * The PORT number specified is an active port, but is in use by another kind of application.
      
   3. Different messages could be in the output depending on the exact return code received during execution.

   4. If a connection to the HCI is established, messages will be issued and will be visible in the HCI job log. The messages might resemble:

      CXTPMAI009I 0001 Init CXTP01   HOBB24DD
      CXTPCFG019I 0001 Configuration file CXTP01   successfully processed
      CXTPMAI043I 0001 Ping from 10.10.0.200
      CXTPMAI007I 0001 Term RC=00000000 FDBK=0 Reason=00000000

      Important

      It is recommended that once the HCI is implemented, it should be set up to run as a started task and included in the IPL startup sequence.

We do not recommend that the CMSC control the HCI when an automated procedure such as a JES3 reader file, or an automated operations product, is being used to shut down both the CMSC and HCI.

Where to go from here?

If you do not have BMC AMI products that require HCI on this LPAR to perform the tasks in this section, continue to Configuring-CMSC-for-a-new-install.