Configuring IBM Db2 AI for z/OS

The configuration of IBM Db2 AI for z/OS (Db2ZAI) involves a script-driven sequence of interactive tasks. Make sure that you follow the step-by-step instructions and successfully complete each task.

Before you begin

This task requires a TSO ID with OMVS access authority.

In order for bash to process the .profile file properly, the file should be created and tagged as text, in code page IBM-1047.

To check that the file is tagged correctly, issue the following command from the user's home directory: cd ~ ; ls -alT .profile

You should see:
t IBM-1047    T=on  -rw-r--r--   1 DB2ZAI   SPKGRP       262 May 22 10:14 .profile

If you need to change the tagging, issue the following: chtag -tc IBM-1047 ~/.profile

To watch the configuration of network ports for a sample Db2ZAI setup, see Configuring Db2ZAI example.

Procedure

To configure IBM Db2 AI for z/OS:

  1. Update the .profile file:
    • Add the following five lines, then modify JAVA_HOME, BASH_HOME, and their bin directories to point to the actual locations in your installation. Customize the DB2ZAI_INSTALLATION variable (for example: /usr/lpp/IBM/db2zaiv1r6) in the following and add to your .profile:
      
export DB2ZAI_INSTALLATION=/usr/lpp/IBM/db2zaiv1r6    #Note: Customize this directory for your environment
export JAVA_HOME=/java8_64/J8.0_64                    #Note: This is your Java installation path
export BASH_HOME=$DB2ZAI_INSTALLATION/bash            #Note: Bash is provided by Db2ZAI in this directory
export PATH=$JAVA_HOME/bin:$BASH_HOME/bin:$PATH
export LIBPATH=/usr/lib
export _BPXK_AUTOCVT=ON
    Note: If the above export statements were not previously specified, source the .profile using ". ~/.profile" (alternatively, log out and log back in again).
  2. Run the script to configure Db2ZAI:
    1. Customize and run the job hlq.SCOYSAMP(COYGMSID) to assign Db2ZAI metadata Db2 table privileges to the ID running the configuration script.
    2. In a bash session, change to the $DB2ZAI_INSTALLATION/configuration/scripts directory and execute the configuration script by issuing the following command:
      ./config.sh -a deploy
      Note: By default, the config.sh script will connect to the metadata Db2 using a PassTicket. If this is not allowed for whatever reason (for instance, a PROTECTED ID is the only ID allowed to generate PassTickets and is also the owner of the Db2ZAI started tasks), you can connect to the metadata Db2 using a user ID and password. Alternatively, you can create an ID that is a surrogate of the PROTECTED ID and can become the PROTECTED ID for the purpose of running the config.sh script. For example:
      ./config.sh -a deploy --password [password | passticket]
      Note: Write authority on the Db2ZAI Home directory (DB2ZAI_HOME) is required in order to run the config.sh script.
      Note:

      PH60101 applies a new version of the JDBC driver that encrypts the user ID and password by default. Decrypting the user ID and password requires a fully configured ICSF with an available Cryptographic Express Coprocessor.

      If a Cryptographic Express Coprocessor is not available in your environment, when running the config.sh script, add the following additional property (when prompted):

      securityMechanism=3;

      This tells the JDBC driver to pass the user ID and password in the clear, which removes the requirement for ICSF.

    3. For each prompt, respond by entering the requested information or accepting the default:
    Table 1. Information for which you will be prompted by the Db2ZAI configuration script
    Requested information Example
    Enter the Db2ZAI Home directory /u/home/DB2ZAI/db2zai-home
    Confirm or enter the Java home path. /java80/J8.0_64/
    Confirm or enter the Timezone value. PST8PDT
    Enter the User ID of the key ring owner. OMVSKERN
    Enter the key ring name. DB2ZAIRING
    Enter the Personal Certificate label. Db2ZAI Personal Cert
    Are you using a third-party root certificate authority (CA) to sign the Db2ZAI personal certificate (for example, GoDaddy or DigiCert)? If you used a CA certificate created by RACF to sign the personal certificate, answer "No". Yes or No
    Are you enabling multiple Db2ZAI instances for failover support? (Yes/No)
    Note: If you are enabling failover support, the config.sh script must be run on every system that is part of the failover environment.
    Note:

    You need to set up the sysplex distributor so that it includes the IP address of each Db2ZAI environment. Specify the ports assigned to the Db2ZAI Liberty server and user interface on the sysplex distributor definition.

    The ports used by each Db2ZAI environment must be the same.

    		 No
    Enter the Db2ZAI hostname or IP address. db2zai.company.com
    Enter the Db2ZAI user interface port. 7000
    Enter the Db2ZAI Liberty server port. 7001
    Specify the local Spark starting port number or press Enter to let Spark choose randomly available ports.
    Note: You can choose to specify the starting Spark port number as well as the size of the range of Spark ports in the $DB2ZAI_HOME/config/assessconfig.json file. See Changing the Db2ZAI Spark settings for instructions.
    		 7002
    Specify the number of Spark port max retry attempts. (Press Enter to use 16 as the default maxRetries). 16
    Enter the metadata Scheduler ID. ZAISCH
    Enter the user ID to be used for password authentication:
    Note: You will only see this prompt if you used the password option to invoke the script.
    		 zai
    Enter the password associated with the ID zai.
    Note: The password text you enter will not be displayed.
    		 <zai_password>
    Enter the metadata Db2 GENERICLU/IPNAME (datasharing) or LU name (non-datasharing). APPLDB1A
    Enter the hostname or IP address of the metadata Db2 system. db1a.company.com
    Enter the metadata Db2 TCPIP port. 446
    Enter the metadata Db2 LOCATION name. DB1A
    (Optional) Enter any additional connection properties for the metadata Db2 connection. ClientApplicationInformation=DB2ZAI_APP_UI7000;
    Enter the metadata Db2 schema name. ZAI7100
    Enter the Db2ZAI job name prefix, or press Enter to use the default (ZAI). ZAI

    If the configuration is successful, the message "IBM Db2 AI for z/OS configuration completed" will be displayed.

    Alternatively, you can add the above configuration details to an INI file and pass this file to Db2ZAI. For example:
    ./config.sh -a deploy -f /path/to/deploy.ini
    Note: The option to use password authentication is not available when running the installation using an INI file.
    Sample INI file contents:
    [environment]
; Specify the path for Java home directory
java.home = /usr/lpp/java/java180/J8.0_64
; Specify the POSIX format time zone of the system running Db2ZAI services
; Examples: 
;  PST8PDT,M3.2.0/2:00:00,M11.1.0/2:00:00 - Los Angeles
;  EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00 - New York
;  GMT0BST,M3.5.0/1,M10.5.0 - London
;  BRT3 - Sao Paulo (does not observe daylight savings time)
timezone = PST8PDT,M3.2.0/2:00:00,M11.1.0/2:00:00

[metadata]
; Specify the metadata connection scheduler ID
schedulerID = ZAISCH
; Specify the Db2 metadata connection location name
location = STLEC1
; Specify the hostname or IP address of the metadata Db2 system           
host = db2.domain.com
; Specify the Db2 metadata connection TCPPORT or SECPORT         
port = 44444             
; Specify the Db2 metadata connection GENERICLU/IPNAME (datasharing) or 
;  LUNAME/IPNAME (non-datasharing).  Note: If both are defined, 
;  use the IPNAME.    
applname = APPLNAME 
; Specify the schema name for the metadata Db2           
schema = DSNML            
; (Optional) Specify any additional connection properties for the Db2 metadata
;  connection by uncommenting the "additional.props = " line below.  If 
;  multiple properties are needed, separate them with a semi-colon.
; Example: additional.props = clientUser=ZAIUSER;sslConnection=true;  
; If a crypotgraphic processor is not available, you will need the following: 
;   additional.props = securityMechanism=3;
; If you are using the SECPORT of Db2, you will need the following:
;  additional.props = sslConnection=true;
;additional.props =  

[db2zai]
; Specify the Db2ZAI Home directory ( example: /u/home/DB2ZAI/db2zai-home )
home = /u/home/DB2ZAI/db2zai-home
; Specify the system specific hostname or IP address for the system where
;  Db2ZAI is running           
host = 9.9.9.9
; Specify the Db2ZAI user interface port                  
frontend.port = 7100
; Specify the Db2ZAI Liberty port         
server.port = 7101
; Specify the local Spark port number to use or specify 'random' to use a random 
;  port
spark.start.port = 7102
; Specify the port max retry attempts. This allows Spark to try a range of ports 
;  from the start port specified to port + maxRetries. A small value (ex. 3) is 
;  usually adequate, but if you plan to run several to many concurrent system 
;  assessments across multiple Db2 datasharing groups, a larger value may be required.
spark.max.retries = 16

; Are you enabling (or have already enabled) multiple Db2ZAI instances for
;  failover support?     
is.ha = No
; Specify the sysplex distributor hostname for Db2ZAI.  This is only needed
;  when failover support is enabled (i.e is.ha=Yes).
; Example: "sysplex.distributor = 7.7.7.7"                      
;sysplex.distributor =

; Specify the prefix for Db2ZAI job names (max four characters)   
job.prefix = ZAI

; Below are Db2ZAI default started task name suffixes.                                                                             
node.start.suffix = ND                                                          
node.stop.suffix = ND                                                           
monitor.start.suffix = MON                                                      
monitor.stop.suffix = MON                                                       
liberty.suffix = LBTY              

[keyring]
; Specify the user ID of key ring owner
owner = OMVSKERN
; Specify the key ring name       
name = DB2ZAIRING
; Specify the personal certificate label                   
cert.name = Db2ZAI personal certificate label
; Are you using a third-party root Certificate Authority (CA) such as 
;  GoDaddy or DigiCert to sign the Db2ZAI personal certificate? 
; Note: if you used a CA certificate generated by RACF to sign the personal 
;  certificate, please answer 'No'.)
using.3rd.party.ca = No