The IMS CDCzLog Publisher Agent configuration (.cab) file is created and maintained by the SQDCONF utility with JCL similar to sample member SQDCONIP included in the distribution. While this section focuses primarily on the initial configuration of the Publisher, sequences of SQDCONF commands to create and configure the Publisher agent can and should be stored in parameter files in case they need to be recreated. See SQDCONF Utility Reference for a full explanation of each command, their respective parameters and the utility's operational considerations.
sqdconf create <cab_file_name>
--type=zlog
--zlog=<log_stream_name>
[--cache-count=<number>]
[--cache-size=<number>]
[--encryption | --no-encryption]
[--auth-keys-list="name"]
[--exclude-program=<program_name>]| Keyword | Description |
|---|---|
| <cab_file_name> |
Path and name of the Publisher Configuration (.cab) file. The directory must exist and the user-id associated with the agent must have the right to create and delete files in that directory. Precisely recommends including the Capture Agent alias as the third node in the directory structure and first node of the file name, for example, /home/sqdata/imspub/imspub.cab. |
| --type=zlog |
Type of the storage agent configuration file. The zlog Publisher works exclusively with z/OS System LogStreams |
| --zlog=<log_stream_file> | The z/OS System LogStream Dataset created earlier. In our example 'SQDATA.IMSCDC.LOG1' |
| [--cache-count=<number] |
Caching transactions in memory while waiting for a commit, avoids having to re-read the zLog and can improve performance. When the cache is full (too little cache compared to the number of in-flight transactions or a given transaction is too large to fit in one cache), a cache miss occurs, and the zlog will have to be re-read to acquire the data instead of using the cache to publish. This parameter specifies the number of individual transactions the capture is allowed to cache. Also see --cache-size. On relevant captures, displaying the capture status will indicate the cache-miss count, due to an insufficient number or size of cache. The objective is to keep the cache-miss count at zero. The Default value is 50. |
| [--cache-size=<size>] |
The size of each individual transaction cache (in KB). While the Default value is 100, depending on the size of transactions in your environment you may watnt to consider 500 to 1000 KB. |
| [--encryption | --no-encryption] |
Enables or disables NaCL encryption of the published CDC record payload. Precisely recommends zIIP processors be used to enhance CPU cycle efficiency and reduce CPU cost associated with NaCL software encryption. |
| [--auth-keys-list="<name>"] |
Required for NaCL software encrypted CDC record payload. File name must be enclosed in quotes and must contain public key(s) of only the subscribing Engines requiring encryption of the CDC record payload. See --encryption option. |
| [--exclude-program=<program_name>] |
While any program can be excluded, SQDATAI would be used if excluding the SQData Apply Engine. |
The configuration file must be updated by adding an entry for each target Engine using the add command.
sqdconf add <cab_file_name>
--key=<DBD> | <DBD.segment> | < DBD.Area> | < DBD.Partition> | < PSB.DBD> | < SSID.DBD>
--datastore=<url>
[--active | --inactive]| Keyword | Description |
|---|---|
| <cab_file_name> | Must be specified and must match the name specified in a previous create command. |
| --key=<name> - | Source object name.
|
| --datastore=<url> | -d <url> | While most references to the term datastore describe physical entities, a datastore URL represents a target subscription and takes the form: cdc://[localhost]/[<agent_alias>]/<subscriber_name> where:
|
| [--active | --inactive] | This parameter marks the added source active or inactive for publishing when the change is applied and the agent is (re)started. The default is --inactive. |
Example
//SQDCONIP JOB 1,MSGLEVEL=(1,1),MSGCLASS=H,NOTIFY=&SYSUID
//*
//*--------------------------------------------------------------------
//* Create CAB File for IMS zLOGC Publisher Agent
//*--------------------------------------------------------------------
//* Note: 1) Parameter Keywords Must be Entered in lower case
//*
//* 2) Parameters Values are Case Sensitive
//*
//* Steps: 1) (optional) delete the existing Publisher CAB File
//* 2) Create a new Publisher CAB File
//* 3) Add IMS Database(s) to the new Publisher CAB File
//* 4) Display the contents of the new CAB File
//*
//*********************************************************************
//*
//JOBLIB DD DISP=SHR,DSN=SQDATA.V400.LOADLIB
//*
//*-------------------------------------------
//* Optional - Delete existing CAB File
//*-------------------------------------------
//*DELETE EXEC PGM=IEFBR14
//*SYSPRINT DD SYSOUT=*
//*CONFFILE DD PATHDISP=(DELETE,DELETE),
//* PATH='/home/sqdata/imspub.cab
//*
//*-------------------------------------------
//* Create a New Publisher CAB File
//*-------------------------------------------
//CRCONF EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
create /home/sqdata/imspub.cab
--type=zlog
--zlog='SQDATA.IMSCDC.LOG1'
//*
//*--------------------------------------------------------------------
//* Add Database(s) and Subscription(s) to the zLOG Publisher CAB File
//* --key: Specifies the IMS Database
//* --datastore: Specifies the Subscription
//* --active | --inactive : Specifies whether to publish or not
//*
//* Add additional Databases and Subscriptions later via Batch Job
//* (a subset of this Job) or via the ISPF Interface
//*--------------------------------------------------------------------
//*---------------------------------------------------
//* Publish Database IVP1 to Subscription IMSTOIMS
//*---------------------------------------------------
//ADD1 EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
add /home/sqdata/imspub.cab
--key=IVP1
--datastore=cdc:////IMSTOIMS
--active
//*
//*---------------------------------------------------
//* Publish Database IVP2 to Subscription IMSTOORA
//*---------------------------------------------------
//ADD2 EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
add /home/sqdata/imspub.cab
--key=IVP2
--datastore=cdc:////IMSTOORA
--active
//*
//*---------------------------------------------------
//* Display the Contents of the Publisher CAB File
//*---------------------------------------------------
//DISPLAY EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
display /home/sqdata/imspub.cab
//*Destroying the Publisher cab file means that the current position in the LogStream and the relative location of each engine's position in the LogStream will be lost. When the Publisher is brought back up it will start from the beginning of the LogStream and will resend everything. After initial configuration, changes in the form of add and modify commands should be used instead of the create command.
While there is a one-to-one relationship between LogStreams and Publishers, there can be a one-to-many relationship between Publishers and Engines as seen later in an example of the sqdconf modify command. An Engine however can be configured to do any number of things including apply captured data to multiple target datastores. Directory path references to [home] and a "user" named [sqdata] can be modified to conform to the operating environment but must match the zFS Directories previously created. The <subscriber_name> is case sensitive in that all references should be either upper or lower case. Because references to the "Engine" in z/OS JCL must be upper case, references to the Engine in these examples are all in upper case for consistency.