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 the following 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)​

  • IBM Developer for z/OS​

  • IMS Explorer for Development (part of IBM Explorer for z/OS)

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.

  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.

  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 lib directory.

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

  4. Set the permissions of ims_server.sh to 744 so it will be able to run (can be done with chmod).

  5. Create a keyring in racf with the server certificate.

  6. Create a keyring in racf with the client certificate for CERTAUTH usage.

  7. Edit the file server.properties file to set the configuration of the server.

  8. Run ims_server.sh from a JCL job to start the server.

Creating certificates and keyrings for the server and client

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('ims.cert')
RACDCERT ADDRING(server_keyring)
RACDCERT CONNECT(LABEL('ims.cert') RING(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('ims.cert')) DSN('ims.cert') FORMAT(CERTB64)
OPUT 'ims.cert' '<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

This example shows how to create a certificate using OpenSSL on a Linux/Windows machine and copying 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:

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

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

```
openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem
```

You will be prompted to provide a password for the certificate.

Copy the 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 cert.pem "//'ims.client.cert'"
```

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

```
RACDCERT ADD('ims.client.cert') WITHLABEL('ims.client.cert') TRUST
RACDCERT ADDRING(client_keyring)
RACDCERT CONNECT (LABEL('ims.client.cert') RING(client_keyring) USAGE(CERTAUTH))
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
```

Server configuration

The file server.properties contains the following fields:

  • server.address: The listening interface (defaults to 0.0.0.0 which means all interfaces).

  • server.port: The listening port of the 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.

JCL Example

```
	//STEP1    EXEC PGM=BPXBATCH,PARM='SH /u/qlik/ims/ims_server.sh'
	//STDOUT DD SYSOUT=*
```

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.

This can be done by changing the logging.properties file and setting 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:

  • MVS Logstream Creation

  • 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.

Managing the MVS Logstream

The provided ATYLOGR program is used to manage MVS logstreams. It provides the following options:

  • Delete all events

  • Delete events before a specific timestamp

  • Print events between two timestamps

  • Print all events from the oldest to a selected timestamp

  • Print all events from the newest to a selected timestamp

  • Print all events

A sample job for managing MVS Logstreams called ATTUNITY.CDC.VSAMBTCH is supplied in the <HLQ>.USERLIB(RUNLOGR) member.

Update the IMS environment

  1. Copy R4IMSEXI from <HLQ>.LOAD 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 the IMS LOGWRT EXIT defaults

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

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