ADD_MIRROR_VERSION procedure

The ADD_MIRROR_VERSION procedure registers version information for a specific feature or function in the Mirror Versioning List (MVL). Version information can be registered in either a pending or an applied state. Registered version information in an applied state is used to determine the common active version that is used by both nodes in the Db2® Mirror pair.

A warning is issued if an identical version entry already exists within the MVL.

When state is PENDING, the addition of the version entry has no effect on either the active version or the node's version in the MVL. The pending state provides the ability to make multiple changes to the version-group and version-name entries before committing them into production.

When state is APPLIED with an activation-time of IMMEDIATE and the addition causes the active version to be increased, the Db2 Mirror exit point for generic versioning (QIBM_QMRDB_VERSION) will be invoked. This exit point allows version entries to be refreshed with the latest version.

Authorization: For the authority needed to use this procedure, see Authorization.

The schema is QSYS2.

version-group

A character or graphic string expression that provides a name for version entries that are associated and should be grouped together.

version-name

A character or graphic string expression that identifies a version within a version-group.

version-identifier

A character or graphic string expression that contains the identifier for a distinct version. version-identifier must be in the form xxx.yyy.zzz with each piece of the version containing the digits 0-9. Each segment of the version can contain one to three digits. If less than three digits are used, the value is logically padded on the left with leading zeros. The meaning of the three pieces is user-defined.

version-identifier can be specified using only one or two parts of the version identifier. For example, xxx.yyy or xxx. Any omitted parts of a version identifier use an implicit value of zero for comparisons.

state

A character or graphic string expression that identifies the apply state of the version entry being added.

APPLIED: This version entry will be added to the MVL with a STATE of APPLIED ADD. An entry in an applied state is eligible to be activated into an active state at the time indicated by the activation-time parameter.; This is the default.
PENDING: This version entry will be added to the MVL with a STATE of PENDING ADD. An entry in a pending state must be applied before it can be activated into an active state . Entries in a pending state have no impact on the QSYS2.CHECK_MIRROR_VERSION function.; Version entries that are added in a pending state with the same version-group, or version-group and version-name combination are applied as a group, using the QSYS2.PROCESS_PENDING_MIRROR_VERSION procedure.

activation-time

A character or graphic string expression that identifies when Db2 Mirror should attempt to evaluate an applied version and promote it to the active version.

This parameter defines the activation rule for when this version should be promoted to the applied state.

IMMEDIATE

Db2 Mirror should attempt to immediately activate this applied version entry as the active version.

If Db2 Mirror is unable to activate this entry because replication has been suspended for maintenance, this entry will remain in an applied state and have its ACTIVATION_TIME set to RESUME.

This is the default.

RESUME

Db2 Mirror will attempt to activate this applied version entry to the active version the next time replication is resumed.

text-description

A character or graphic string that contains descriptive text associated with this version entry. It can be up to 50 characters long.

Examples

Add two version entries to the SOFTVEND01 version group to the MVL. The first entry is to indicate that this node supports version 1.4.7 of APPLICATION_LIBRARY_01, and the second entry does the same for version 2.0.0 of APPLICATION_LIBRARY_02. Both entries are applied immediately if the mirrored pair is not suspended for maintenance.
The first call achieves this by using the default values for state and activation-time, whereas the second statement calls out the APPLIED and IMMEDIATE values explicitly. If the mirrored pair is suspended for maintenance, then the ACTIVATION_TIME value in the MVL will be changed to RESUME, and the entry will be applied the next time mirroring is resumed.
```
CALL QSYS2.ADD_MIRROR_VERSION(VERSION_GROUP      => 'SOFTVEND01',
                              VERSION_NAME       => 'APPLICATION_LIBRARY_01',
                              VERSION_IDENTIFIER => '1.4.7');

CALL QSYS2.ADD_MIRROR_VERSION(VERSION_GROUP      => 'SOFTVEND01',
                              VERSION_NAME       => 'APPLICATION_LIBRARY_02',
                              VERSION_IDENTIFIER => '2.0.0',
                              STATE              => 'APPLIED',
                              ACTIVATION_TIME    => 'IMMEDIATE',
                              TEXT_DESCRIPTION   => 'Support latest major revision');
```

Add a version entry to the SOFTVEND01 version group for version 123.456.789 of APPLICATION_LIBRARY_03. This entry will be applied upon the next resume of mirroring.

CALL QSYS2.ADD_MIRROR_VERSION(VERSION_GROUP      => 'SOFTVEND01',
                              VERSION_NAME       => 'APPLICATION_LIBRARY_03',
                              VERSION_IDENTIFIER => '123.456.789',
                              STATE              => 'APPLIED',
                              ACTIVATION_TIME    => 'RESUME',
                              TEXT_DESCRIPTION   => ‘Enabled once replication is resumed');

Add a pending version entry to the SOFTVEND02 version group for version 6.2.25 of APPLICATION_LIBRARY_01 to the MVL. Version entries in a pending state have no impact on the active version in the MVL. The changes are committed into production by using a subsequent QSYS2.PROCESS_PENDING_MIRROR_VERSION procedure. A sample text description is included, showing how it could be used to indicate what this entry represents for the given version group and version name.
```
CALL QSYS2.ADD_MIRROR_VERSION(VERSION_GROUP      => 'SOFTVEND02',
                              VERSION_NAME       => 'APPLICATION_LIBRARY_01',
                              VERSION_IDENTIFIER => '6.2.25',
                              ACTIVATION_TIME    => 'IMMEDIATE',
                              TEXT_DESCRIPTION   => ‘Critical fix was applied');
```