Early Access: The content on this website is provided for informational purposes only in connection with pre-General Availability Qlik Products.
All content is subject to change and is provided without warranty.
Skip to main content Skip to complementary content
Qlik Resources
Loading SearchUnify's search If you need assistance with your product, please contact Qlik Support.
Qlik Customer Portal
Loading SearchUnify's search If you need assistance with your product, please contact Qlik Support.
Qlik Customer Portal

Prerequisites

Before you begin to work with an IBM IMS database as a source in Qlik Replicate, make sure that all of the prerequisites have been met.

z/OS platform​

  • Java 17​

  • z/OS versions 2.5 and higher​

  • IMS versions 15.x

Metadata design platform (Windows/Linux)​

If the IMS segment metadata is not exclusively sourced from IMS Catalog, the following tools are needed:

Replicate prerequisites

  1. Download the IMS universal drivers jar 15.166 or later from https://mvnrepository.com/artifact/com.ibm.ims/udb and copy it to <Replicate INSTALL>endpoint_srv/externals.

    Information noteReplicate requires the non-redistributable IBM IMS Java client.

  2. Restart the Qlik Replicate Server service.

Installing the Replicate IMS components on z/OS

The section describes how to install the required Replicate IMS components on z/OS server.

  1. Untar R4IMS-<version>.tar on the mainframe to directory /u/qlik/ims.

    Example:

    $ mkdir -p /u/qlik/ims
$ tar -xvf R4IMS-<version>.tar -C /u/qlik/ims

  2. Download the IMS universal drivers jar 15.166 or later from https://mvnrepository.com/artifact/com.ibm.ims/udb and copy it to the /u/qlik/ims/server/lib directory. This is the same file that was downloaded in Step 1 of Replicate prerequisites above.

  3. Set the owner and group of the files using chown -R to the desired owner.

    Example:

    $ chown <user>:<group> -R /u/qlik/ims

  4. Create a keyring in RACF with the server certificate.

  5. Create a keyring in RACF with the client certificate for CERTAUTH usage.

  6. Edit the JCL job using the properties described in Server configuration below.

  7. Submit the JCL job that you created in Step 6 to start the server.

Creating certificates and keyrings for the server and client

The Qlik IMS Server serves its client using HTTPS; therefore, a trusted TLS certificate need to be configured. The certificate generated in the examples below is a self-signed certificate. This is completely secure since a matching public certificate will be configured in the Replicate IMS source endpoint so that it can trust the server. The TSO commands in the examples below assume that z/OS system is using the IBM RACF security system. For other cases, consult the vendor documentation.

Information noteBoth of the examples below contain a RACDCERT ADDRING command, with example keyring names. You can skip this command if the ring already exists. If the ring does not exist, you can replace the example keyring names with your own names, and even use the same keyring for both the client and the server keyrings.

Example of a server self-signed certificate and keyring

This example assumes the same user runs the commands and the server.

To allow other users to run the server, the RACF commands should specify `ID(USERNAME)`, `SITE`, or `MACHINE`.


RACDCERT GENCERT SUBJECTSDN(CN('<host-name>')) SIZE(384) NISTECC WITHLABEL('qlik.ims.hostcert') 
RACDCERT ADDRING(qlik.ims.server.keyring) 
RACDCERT CONNECT(LABEL('qlik.ims.hostcert') RING(qlik.ims.server.keyring) USAGE(PERSONAL)) 
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

To export the certificate to a .pem file, run the following TSO commands:


RACDCERT EXPORT(LABEL('qlik.ims.hostcert')) DSN('qlik.ims.hostcert') FORMAT(CERTB64) 
OPUT 'qlik.ims.hostcert' '<filename>.pem' TEXT

Copy the .pem file to the Replicate machine as a text file. It will be used by the endpoint to authenticate the server.

Example of a client self-signed certificate and keyring

The Replicate IMS source endpoint identifies itself to the Qlik IMS Server.

This example shows how to create a certificate using OpenSSL on a Linux/Windows machine and how to copy the certificate and public key to the z/OS machine:

To create a certificate using OpenSSL on a Linux/Windows machine, run the following command:

Information noteOn Windows, you needs to install OpenSSL as this command does not exist on Windows.

$ openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -keyout qlik-ims-client-key.pem -out qlik-ims-client-cert.pem -sha256 -days 365 -nodes

The certificate expires in 365 days. It will need to be replaced before it expires to ensure that the server remains trusted by the client.

To export the certificate as pkcs12 format, run the following command:


$ openssl pkcs12 -export -out qlik-ims-client-cert.p12 -inkey qlik-ims-client-key.pem -in qlik-ims-client-cert.pem

You will be prompted to provide a password for the certificate. Make sure you have it saved somewhere safe so it can be used in the Replicate IMS source endpoint configuration as well.

Copy the qlik-ims-client-cert.pem file to the z/OS machine as text. Then run the following command from a UNIX shell to copy the file to a dataset:


cp qlik-ims-client-cert.pem "//'qlik.ims.clntcert'"

Run the following TSO commands to complete the process of adding the client certificate and keyring:

RACDCERT ADD('qlik.ims.clntcert') WITHLABEL('qlik.ims.client.cert') TRUST 
RACDCERT ADDRING(qlik-ims-client-keyring) 
RACDCERT CONNECT (LABEL('qlik.ims.client.cert') RING(qlik-ims-client-keyring) USAGE(CERTAUTH)) 
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

Server configuration

The SRVPRM DD card in the Qlik IMS Server JCL file contains the following configuration properties:

  • server.address: The listening interface for the Qlik IMS server (defaults to 0.0.0.0 which means listening on all interfaces).
  • server.port: The listening port of the Qlik IMS server (defaults to 50051).
  • server.maxParallelRequests: The total number of requests the server can handle in parallel (defaults to 100).
  • server.mtls.keyring.userId: The name of the user that owns the keyring referred to in server.mtls.keyring.name.
  • server.mtls.keyring.name: The name of the keyring that will be used as a Key Manager with the certificate chain of the server.
  • client.mtls.keyring.userId: The name of the user that owns the keyring referred to in client.mtls.keyring.name.
  • client.mtls.keyring.name: The name of the keyring that will be used as a Trust Manager for the server to validate the client's certificate
Information noteThe user ID of the client and server keyrings can be the same.

JCL Example


//STEP1 EXEC PGM=BPXBATCH,PARM='SH /u/qlik/ims/ims_server.sh SRVPARAM' 
//STDOUT DD SYSOUT=*
//SRVPARAM DD *
# Listening TCP address (default 0.0.0.0)
server.address = 0.0.0.0 
# Listening TCP port (default 50051)
server.port = 50051
# UserID of the server keyring
server.mtls.keyring.userId = <SERVER-KEYRING-USER-ID>
# Name of the server keyring
server.mtls.keyring.name = qlik.ims.server.keyring
# UserID of the client keyring
client.mtls.keyring.userId = <CLIENT-RING-USER-ID>
# Name of the client keyring
client.mtls.keyring.name = qlik.ims.client.keyring
/*

Server logging

To diagnose errors such as TLS certificate problems, change the level of the logger in the server from INFO to FINE.

You should only do this if you encounter internal errors, and you should revert to normal logging as soon as possible to avoid flooding stderr.

To change the logging level, edit the logging.properties file and set both the .level and java.util.logging.ConsoleHandler.level to FINE.

After changing the logging level, you must restart the server.

CDC prerequisites

CDC works by reading z/OS logstream to which the Qlik LOGWRT EXIT function writes log data.

This means that you need to install the EXIT function, as described below.

Installing and configuring LOGWRT EXIT

The LOGWRT Exit function is required for CDC. To use the LOGWRT EXIT, carry out the following procedures:

  • Create the MVS Logstream

    Information noteIf you already have a LOGSTREAM configured for the legacy ARC product, you can use that LOGSTREAM as is.

  • Update the IMS Environment

  • Adjust the DBD for the Relevant Databases

MVS Logstream Creation

A sample job for the creation of the DASD MVS logstream called ATTUNITY.IMS.DCAPDATA is supplied in the <HLQ>.USERLIB(LOGCRIMS) member. For additional information, see z/OS MVS Setting Up a Sysplex.

Information notez/OS does not delete records from the logstream unless instructed to do so. Deletion of unneeded records is critical for preserving DASD space. Best practice for deleting logstream records is as follows: When you create the logstream, set AUTODELETE to YES and EXPDT to the number of days that you want to keep the records for. In most cases, a few days should be a good balance between recovering a stopped Replicate task and DASD space.

Building the Qlik IMS User Exit

The EXIT comes with defaults. If you need to change any of these defaults, do the following:

  1. Edit <HLQ>.USERLIB(R4IPARMS). Make any required changes to the property values. Here is a sample R4IPARMS:

    R4IPARMS CSECT PRINT GEN,ON R4IMAC LOGSTREAM=ATTUNITY.IMS.DCAPDATA, X BUFFER_NUM=100, X ENABLE=YES, X DATASHARING=NO, X SEQUENCE=YES, X DEBUG=NO END

  2. Edit <HLQ>.USERLIB(R4IREPL). Verify that the JCL is correct and submit the job. It should end with RC=0. Here is a sample R4IREPL:

    //IMSPARMS JOB 'IMS CDC',MSGLEVEL=(1,1),MSGCLASS=A,NOTIFY=&SYSUID //COMP EXEC PGM=ASMA90 //SYSIN DD DSN=HLQ.USERLIB(R4IPARMS),DISP=SHR //SYSLIB DD DSN=HLQ.USERLIB,DISP=SHR //SYSLIN DD DSN=&&OBJ(R4IPARMS),DISP=(,PASS),SPACE=(TRK,(1,1,1)),UNIT=VIO //SYSPRINT DD SYSOUT=* // IF (RC = 0) THEN //LINK EXEC PGM=HEWL //SYSLMOD DD DSN=your.reslib,DISP=SHR <=VERIFY THAT THIS IS //RESLIB DD DSN= your.reslib,DISP=SHR <=WHERE THE EXIT RESIDES //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=*.COMP.SYSLIN,DISP=(OLD,DELETE) //SYSLIN DD * INCLUDE RESLIB(R4IMSEXI) REPLACE -IMMED,R4IPARMS(R4IPARMS) ENTRY R4IMSEXI NAME R4IMSEXI(R) // ENDIF

Setting up the Qlik IMS User Exit

  1. Copy /u/qlik/ims/exit/R4IMSEXI to the IMS RESLIB (or any other PDS in the IMS control region STEPLIB concatenation).

  2. Either create or update your DFSDFxxx in the IMS PROCLIB as follows:

    \<SECTION=USER_EXITS\>

EXITDEF=(TYPE=LOGWRT, /\* LOGWRT USER EXIT \*/ EXITS=(R4IMSEXI)) /\*
EXIT LIST \*/

  3. If you do not have a DFSDFxxx member loaded at IMS startup, add this line to your DFSPByyy member:

    DFSDF=xxx

    Where xxx is the suffix you gave to your DFSDF member.

    Information noteIf you already have a LOGWRT in use, code the EXITS statements as follows: EXITS=(R4IMSEXI,YOUREXIT). The EXITs will be called in this order.

  4. Recycle IMS, or if applicable, dynamically load the EXIT using the following IMS type-2 command:

    REFRESH USEREXIT TYPE(LOGWRT)

Changing LOGWRT property values dynamically

You can change some of the EXIT properties without recycling IMS. This is implemented by following the steps described in Update the IMS Environment. The properties that can be changed dynamically are: LOGSTREAM, BUFFER_NUM, DEBUG, and ENABLE.

After you recompile R4IPARMS as described above and refresh the EXIT using the IMS command, the changes will be triggered the next time the EXIT is invoked by a captured segment change. When this happens, you will see something like this in the IMS control region job log:

R4ZI020I current runtime parameters are: 054 Logstream name is: ATTUNITY.IMS.DCAPDATA Number of blocks: 100 Sequencing : YES Enabled : YES Datasharing : NO Debug: YES

If you change the logstream name, the following message (perhaps several times) is normal:

R4ZI035D Qlik LOGWRT Logger RC=8 - will wait

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – please let us know!

Leave your feedback here