Skip to main content Skip to complementary content

Controlling the CDC process

Qlik Replicate uses ECSA memory structures - called R4Z CDC services - which are formed during CDC processing. Each z/OS LPAR may contain several such R4Z CDC services. To form the R4Z CDC services, a special utility program, R4ZCTL, is provided.

This program can also be used for managing the state of CDC processing, as well as the level of traffic on the z/OS side.

From Replicate 6.1, the CDC services (known as R4Z environment in previous versions), do not need to be “activated” prior to invocation of the CDC reader UDTF. The CDC services are “auto-activated” by the UDTF (when inactive). This means that the R4Z control program is no longer responsible of activating the service. It is, however, required for the following purposes: checking CDC and reporting the CDC service’s status, pausing CDC processing, resuming a paused CDC, and terminating the CDC process, either normally or forcefully.

The command parameters available when running the R4ZCTL program are:

Information note

If you run the command without any parameters, it will return the current status of the CDC service.

  • CHECKCONFIG - Verifies that configuration parameters are valid
  • PAUSE_TASK - Stops the service of a specific CDC task
  • PAUSE_CDC - Stops the entire activity of a CDC service
  • RESUME_TASK - Enables a paused task to continue
  • RESUME_CDC - Enables a paused CDC service to continue
  • TERMINATE - Stops the CDC service, and, once stopped – releases its resources
  • FORCE - same as TERMINATE, when task holding resources “hangs”

As the R4ZCTL programs requires APF-authorization, all libraries in the STEPLIB must be APF- authorized.

When running R4ZCTL with no parameter, its completion-code is set based on whether the environment was initialized (CC=0) or not initialized (CC=1).

Control program invocation syntax

The R4ZCTL program is invoked as a job step, i.e. EXEC PGM=R4ZCTL, and accepts instructions via the invocation parameter of the job step.

The R4ZCTL invocation parameter is a string that can contain optional sub-parameters, separated by a comma as follows:

[SERVICE=CDC-service-qualifier,][MSGLVL={0 | 1},][action]

Information note

The order of the sub-parameters in the string is not important.


SERVICE=CDC-service-qualifier designates the logical scope of Replicate activity, upon which the control program is to act.

For more information on CDC services, see Prerequisites.


MSGLVL={0 | 1 | 2} designates the level of notifications to be displayed in the message file during the operation of the control program.

  • 0 = No notifications
  • 1 = Moderate
  • 2 = Maximum


action-verb can be one of the following:

  • PAUSE_TASK(*|ALL|task-qualifier)

    Suspends CDC retrieval for the task(s) designated in parentheses.


    Suspends CDC retrieval for entire CDC service. Replication tasks suspended for more than a certain time are stopped will attempt recovery multiple times. No new tasks will be served.

  • RESUME_TASK(*|ALL|task-qualifier)

    Resumes CDC retrieval for the task designated by task-qualifier.


    Resumes CDC retrieval for all instances matching the session-limits qualifier.

  • DUMP_TASK(*|ALL|task-qualifier)

    Requests formatted dumping of the control information in the resident memory structures. ALL designates all sessions; SUMMARYONLY designates only the anchor.


    Frees all the R4Z resident memory structures, terminates all active instances and deletes associated resources. From this point on, all CDC requests will return the inactive status until CDC service is auto-activated by an incoming call to the CDC reader UDF.


Syntax elements reference

The elements used in the syntax descriptions above are as follows:

  • CDC-service-qualifier

    A 4-character name (first character alphabetic, rest alphanumeric), which designates a CDC service.

    “CDC service” refers to a group of resources – memory structures, a user-defined table-function (UDTF) defined in DB2 and an application environment (APPLENV) defined in the WLM policy. R4Z lets you specify properties – memory limits and processing thresholds – per each CDC service. It may be necessary to manage several CDC services also for another reason: provide for more than one Replicate release being used in a single LPAR, each maintain its memory structures independently on others.

  • task-qualifier

    A 4-digit identifier being assigned upon initiation of the task. This identifier is aimed mainly for controlling and tracking CDC traffic of a specific task (defined in the client’s endpoint definitions). It is being used to form the CORRID (Correlation-ID) of the DB2 thread serving CDC – it occupies bytes 9-12 there.

Control program completion codes

  • 0 – Normal completion
  • 1 – Environment does not exit the session-limits qualifier (when no action is specified)
  • 4 – Warning
  • 8 – Error

Sample jobs (in the INSTALL library)

IV1CHECK – Checks the configuration of all CDC services

XMDUMP – Dumps all sessions

XMPAUSE – Pauses a session

XMRESUME – Resumes a session

XMTERMIN – Terminates all sessions

Enabling the CDC process (auto-activation)

To enable the CDC reader UDTF function to work, this function needs to be able to allocate and pre-format memory structures in ECSA when the UDTF is called and the first time after the z/OS system was started; it also needs to access the configurations set for the CDC service the UDTF is serving (or the “default” configurations, for values not specified at the CDC service level).

To account for this, the installation process ensures that:

  1. A special UDTF is created to serve the CDC service. The created UDTF has its name suffixed with a double-underscore (“__”) followed by the CDC-service-qualifier, forming a name as such: <schema>.R4Z_UDTF__<CDC-service-qualifier>.
  2. A WLM APPLENV is created to execute invocations of the above UDTF. The created APPLENV may also have its name suffixed with the CDC service qualifier, to ensure uniqueness of the APPLENV name – which is recommended; however, multiple UDTFs may use a single APPLENV.
  3. A JCL procedure is created to “host” the WLM APPLENV executions. This JCL procedure differs from a usual WLM STC procedures in that a special DDNAME, R4ZCNFG, must be specified, its DSN referring to the CONFIG library of the R4Z product. In this library, there MUST be an existing member named “CDCS”, specifying the default CDC service configurations. There MAY also exist a member named “CDCS<CDC-service-qualifier>” with the configuration values you want to apply for this CDC service.
  4. The content of each of the CDCS* members in the CONFIG library is a list of assignment statements, one per card, in the format “keyword=value”. The statement may follow spaces, and are space-terminated; no spaces are allowed with the statement. Cards beginning with a hyphen (‘-‘) are treated as comment cards; and the content following the terminating space is also treated as comment.

    Keywords, max values, min values, and default values
    Keyword Description Minimum Maximum Default


    The maximum number of CDC sessions.





    The number of seconds after which session is timed out.





    The maximum buffer size allowed for IFI reads, in Kbytes.





    The maximum size in Mbytes for the accumulated result set to reach; when reached, the result set is returned.





    The maximum time interval, in seconds, for accumulating the result set; when reached, the result set is returned.




    Establishing R4Z CDC services

    Deciding on the CDC services: Based on predicting the need for independent replication processes (to allow different versions, to ensure sufficient ECSA memory, to account for different latencies allowed, etc.), determine which R4Z CDC services are to exist in each LPAR. For each service, choose the CDC service qualifiers (4 characters). You also need to decide whether each CDC service is to have its own WLM APPLENV (application environment), or a single APPLENV to serve all CDC services.

    You need to set variable DEFWLMAE (DEFine WLM Applic. Env.) in DFSYMLST member to either PER (first option) or ONE (second option). Once set, you can proceed with the installation:

    Information note
    • If you select ONE for DEFWLMAE, jobs DO2* and DO3SRVTF should be run one time ; if you select PER , these jobs should be run for each CDC service, after the JCL SET variable CDCSRV is set to the CDC service’s qualifier.

    • Job DO3SRVDF creates a CONFIG library, and places a member named “CDCS”, which serves as the default configuration file. After running job DO3SRVTF the library will contain the configuration of all CDC services, making it possible to edit them and change the configurations of a specific CDC service.

    • If ONE is used for DEFWLMAE, then the product defaults are used instead of the CONFIG library members.

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 – let us know how we can improve!