Upgrading to new Version 11.4 function levels (z/OS)

With Q Replication Version 11.4 on z/OS®, you can choose when and where to add replication enhancements and also continue to apply fixes without having to adopt new feature function until you are ready to do so.

With this new model based on function levels, you can control the levels of your source and target replication programs, ensure their interoperability when the programs are at different levels, and ensure that the replication control tables are at the correct level to support your desired level of function.

Function levels and related levels

New Q Replication features are enabled for use when you activate function levels.

IBM recommends that you upgrade to the latest control table level and activate the latest function level by running the asncatm utility.

A function level enables a particular set of new Q Replication capabilities and enhancements. It includes code that supports new capabilities, defect fixes, and preventive service items. Before you can use the new capabilities of a function level, you must activate the function level, or a higher function level.

Function levels are specified in the format vvvv.fff, where vvvv represents the version (for example 1140 for V11.4) and fff represents the function level within that version. Table 1 shows the available function levels.

Table 1. Q Replication function levels and corresponding release-maintenance levels
Function level	Release and maintenance level
1140.103	11.4 APAR PH16629
1140.100	11.4 APAR PH13496 11.4 APAR PH08369 11.4 APAR PH06478 11.4 APAR PH02537 11.4 APAR PI99238
1140.0	11.4 GA
1021.0	Version 10.2.1 at any PTF level

Other levels related to function level

The Q Replication programs use the following levels to store information about which functions are activated at the source and target servers. Each Q Capture program knows the level of its target Q Apply programs, and each Q Apply knows the level of the Q Capture programs that it works with. These levels are negotiated by the exchange of messages between Q Capture and Q Apply when a queue is started.

Possible level: The level of the installed engine code (essentially, this level is the same as function level). This value is updated each time the Q Capture or Q Apply programs start and is stored in the POSSIBLE_LEVEL column of the IBMQREP_CAPPARMS and IBMQREP_APPLYPARMS tables. For a fix-only PTF that has no control table or external changes, the possible level stays the same. Fixes that require control table changes or new parameters might introduce a new function level/possible level. The replication APAR number is still reported in the job log and is also returned by using the status command.
Current level: The current level of function that was activated for the Q Capture or Q Apply instance. This value must be equal to or lower than the possible level and control tables level. It is stored in the CURRENT_LEVEL column of the IBMQREP_CAPPARMS and IBMQREP_APPLYPARMS tables. The asncatm utility sets this level when you specify the activate parameter.
Control tables level: The level of the control tables. The value is stored in the CONTROL_TABLES_LEVEL column of the IBMQREP_CAPPARMS and IBMQREP_APPLYPARMS tables. This level must match the function level/possible level. The control tables level can be higher than the current level, but the engine programs query the control tables at the current level. For example, if the value of CONTROL_TABLES_LEVEL is 1140.100 but the value of CURRENT_LEVEL is 1140.0, the Q Capture or Q Apply program interacts with the control tables as if they were at level 1140.0. A new control tables level can add new tables, new columns to existing tables, or change data types. The asncatm utility sets this level when you specify the control tables level parameter.
Apply level: The current functional level of the Q Apply program that a send queue works with. The value is stored in the APPLY_LEVEL column of the IBMQREP_SENDQUEUES table. Q Apply program sends its current level to the Q Capture program when it starts, each time the receive queue is activated, and when a new function level is activated at the target. Upon receiving the function level message from Q Apply, Q Capture updates the APPLY_LEVEL column and starts sending messages in the new format. This value is also stored in the CURRENT_LEVEL column of the IBMQREP_APPLYPARMS table.
Capture level: The current functional level of the Q Capture program that a receive queue works with. This value is stored in the CAPTURE_LEVEL column of the IBMQREP_RECVQUEUES table. Q Capture sends its current level when it starts, each time a send queue is activated, and when a new function level is activated at the source. Upon receiving the function level message from Q Capture, Q Apply updates the CAPTURE_LEVEL column. This value is also stored in the CURRENT_LEVEL column of the IBMQREP_CAPPARMS table.

The Q Capture and Q Apply log files always report the current value of these levels when the programs start. For example:

2018-06-24-13.04.44.842907 ASN0732I  "Q Capture" : "ASN" : "Initial" : The program started running with the following levels:
POSSIBLE_LEVEL: "1140.0". CURRENT_LEVEL: "1140.0". CONTROL_TABLES_LEVEL: "1140.0". Current maintenance: ”APAR pi97455".

Enabling different function levels for Q Capture-Q Apply pairs

If Q Capture has multiple send queues that feed multiple Q Apply programs, Q Capture can send different versions of messages depending on the APPLY_LEVEL value for a send queue. This feature enables Q Capture to work with Q Apply programs at different function levels.

With this ability, you can upgrade your Q Apply programs one at a time and test new function before upgrading the other programs. For example, if your Q Apply programs are at Version 10.2.1, you can upgrade one Q Apply to a Version 11.4 function level and leave the others at V10.2.1.

When the upgraded Q Apply program starts, it checks to make sure Q Capture is at V11.4 and then sends a message through the administration queue to Q Capture declaring its function level.
Q Capture updates the APPLY_LEVEL column in the IBMQREP_SENDQUEUES table for the send queue that works with this Q Apply program.
Q Capture starts sending messages in the new format on this send queue.
For all other send queues, APPLY_LEVEL remains at 1021.0 so Q Capture continues sending that level of message.

Because the programs can make this distinction, you could use a new replication feature on only the configuration that is operating at the V11.4 function level.

ARCH_LEVEL and COMPATIBILITY

For versions before V11.4 with the PTF for APAR99238, the Q Capture and Q Apply ARCH_LEVEL parameter was used to represent the engine code level. The Q Capture program used its COMPATIBILITY parameter to determine the lowest level of Q Apply program that it worked with.

Starting with V11.4 with the PTF for APAR99238, the replication programs use the function level and its related levels to represent the engine code level and the levels of Q Apply programs.

The ARCH_LEVEL value will continue to be used by the ASNCLP command-line program and Replication Center to determine the level of the control tables that is active for backward compatibility. The ARCH_LEVEL value will remain at 1140.

When the ARCH_LEVEL of all Q Apply programs is at 1140, Q Capture will no longer use the COMPATIBILITY parameter.