The Keyed File CDCzLog Publisher Agent configuration (.cab) file is created and maintained by the SQDCONF utility with JCL similar to sample member SQDCONVP 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 and referenced by SQDPARM DD. See SQDCONF Utility Reference for a full explanation of each command, their respective parameters and the utility's operational considerations.
Syntax
sqdconf create <cab_file_name>
--type=zlog
--zlog=<log_stream_name>
[--encryption | --no-encryption]
[--auth-keys-list="name"]
Keyword and Parameter Descriptions
| 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/KFILEPUB/kfilepub.cab. |
| --type=<type> | Agent type, in the case of the CDCzLog Publisher, is zlog. |
| --zlog=<log_stream_file> | The z/OS System Logger Dataset created earlier. In our example 'SQDATA.FILECDC.LOG1' |
| [--encryption | --no-encryption] |
Enables or disables NaCL encryption of the published CDC record payload. See Encryption of Published Data for more details. 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 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. |
Next, the configuration file must be updated by adding an entry for each Keyed file captured using the add command. Note, only one command can be executed at a time.
Syntax
sqdconf add <cab_file_name>
--key=<name>
--datastore=<url>
[--active | --inactive]
Keyword and Parameter Descriptions
| Keyword | Description |
|---|---|
| <cab_file_name> |
Must be specified and must match the name specified in a previous create command. |
| --key=<name> |
Source object name. That will be the RECALIAS parm from the Keyed FIle Compare Capture. |
| --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
In the following example the transport method is TCP/IP. The final step executes the display command to output the current content of the configuration file:
//SQDCONFP JOB 1,MSGLEVEL=(1,1),MSGCLASS=H,NOTIFY=&SYSUID
//*
//*--------------------------------------------------------------------
//* Create CAB File for zLOGC Publisher Agent
//*--------------------------------------------------------------------
//* Note: 1) Parameter Keywords must be entered in lower case
//*
//* 2) Parameters Values are Case Sensitive.
//*
//* 3) Engine Name should be in Upper Case for z/OS JCL
//*
//* Steps: 1) (optional) delete the existing Capture CAB File
//* 2) Create a new Publisher CAB File
//* 3) Add VSAM files 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/SQD/kfilepub1/KFILEPUB1.cab'
//*
//*-------------------------------------------
//* Create New zLog Publisher CAB File
//*-------------------------------------------
//CRCONF EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
create /home/SQD/kfilepub1/kfilepub1.cab
--type=zlog
--zlog='SQDATA.FILECDC.LOG1'
//*
//*--------------------------------------------------------------------
//* Register/Add Files Files to the zLOGC Publisher CAB File
//* and Set the Target Subscription
//*--------------------------------------------------------------------
//*
//*-----------------------------------------------
//* Publish File FILEA to Subscription KFITOKFI
//*-----------------------------------------------
//ADDFI1 EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
add /home/SQD/kfilepub1/KFILEPUB1.cab
--key=FILEA
--datastore=cdc:////KFITOKFI.
--active
//*
//*-----------------------------------------
//* Display the Publisher CAB File
//*-----------------------------------------
//DISPLAY EXEC PGM=SQDCONF
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SQDPARMS DD *
display /home/SQD/kfilepub1/KFILEPUB1.cab
//*Note:
- The SQDCONF create command defines the location of the Publisher's configuration file. Once created, this command should never never be run again unless you want to destroy and recreate the Publisher agent. After the initial creation apply should not be used unless changes have been made and you want them to take effect on the start. It is possible to add/modify over time preparing for the next release without affect current configuration. Note: apply and start can be done in different SQDCONF jobs.
- 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. You cannot delete a cab file if the Publisher is mounted. And a create on an existing configuration file will fail.
- 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 [SQD] 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.