REMOVE_MIRROR_VERSION procedure

The REMOVE_MIRROR_VERSION procedure removes a user supplied version entry from the Mirror Version List (MVL).

An entry in the MVL can be removed by specifying either version-group, version-name, and version-identifier, or by specifying the entry-number associated with the version entry. If no version entry matches the input parameters, a warning is returned.

A mirror version entry is defined as either being in an applied or a pending state.

When state is PENDING, the removal 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 removal of the version entry causes the active version to change, Db2® Mirror will invoke the Db2 Mirror exit point for generic versioning (QIBM_QMRDB_VERSION). This exit point allows version entries to be refreshed after the active version has been removed.

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

The schema is QSYS2.

version-group

A character or graphic string expression that identifies the group name of the version entry to remove.

When version-group is specified, version-name and version-identifier must also be specified. entry-number cannot be specified.

version-name

A character or graphic string expression that identifies the version name of the version entry to remove.

version-identifier

A character or graphic string expression that identifies the version identifier of the version entry to remove. 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.

entry-number

A numeric value that identifies a specific version entry to remove. This is a system-generated value that is shown in the VERSION_NUMBER column of the QSYS2.MIRROR_VERSION_LIST view.

When entry-number is specified, version-group, version-name, and version-identifier cannot be specified.

When specifying entry-number:

If state is APPLIED and the identified version entry is not the active version, the version entry will be removed immediately from the MVL. The version information can be in an active or a pending state.
If state is APPLIED, activation-time is IMMEDIATE, and the identified version entry is the active version, the active version will be removed and replaced with any active version information present.
If active versions exist that can only be activated during RESUME, the removal of the active version will be deferred. An APPLIED REMOVE version entry with activation-time of RESUME will be added to the MVL.
If state is APPLIED, activation-time is RESUME, and the identified version entry is the active version, the active version will be removed the next time replication is resumed. An APPLIED REMOVE version entry will be added to the MVL.
If state is PENDING, the identified version entry will be used to define a new PENDING REMOVE version entry.

state

A character or graphic string expression that indicates whether this version entry should be removed from the MVL immediately or placed in a pending state.

APPLIED: The version entry will be placed into an active state and will be processed immediately. This is the default.
PENDING: The version entry, identified by a combination of version-group and version-name, will be placed into a pending state.; Version entries that are 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 any changes caused by the removal of this version entry to either the active version or a node's version. This parameter only applies when state is ACTIVE. Otherwise, it is ignored.

IMMEDIATE

Db2 Mirror will attempt to remove the version entry immediately and process any changes to the active version or to a node's version.

If Db2 Mirror is unable to remove the version entry because replication has been suspended for maintenance, this entry will have its APPLY_STATE set to APPLIED REMOVE and will be processed the next time replication is resumed.

This is the default.

RESUME

Db2 Mirror will attempt to remove the version entry the next time replication is resumed. The entry will have its APPLY_STATE set to APPLIED REMOVE.

Examples

Remove active version entries for group name SOFTVEND01. Both procedure calls cause the entries to be removed immediately if the mirrored pair is not suspended for maintenance. The first call for version name APPLICATION_LIBRARY_01 achieves this by using the default values for the state and activation-time parameters. The second statement with version name APPLICATION_LIBRARY_02 explicitly specifies the APPLIED and IMMEDIATE parameter values.

CALL QSYS2.REMOVE_MIRROR_VERSION(VERSION_GROUP      => 'SOFTVEND01', 
                                 VERSION_NAME       => 'APPLICATION_LIBRARY_01', 
                                 VERSION_IDENTIFIER => '1.4.7'); 

CALL QSYS2.REMOVE_MIRROR_VERSION(VERSION_GROUP      => 'SOFTVEND01', 
                                 VERSION_NAME       => 'APPLICATION_LIBRARY_02', 
                                 VERSION_IDENTIFIER => '2.0.0', 
                                 STATE              => 'APPLIED', 
                                 ACTIVATION_TIME    => 'IMMEDIATE');

Immediately remove a version entry from the MVL by its entry-number. Each version entry stored in QSYS2.MIRROR_VERSION_LIST view has an entry number value. To list all the entry-number values for version name APPLICATION_LIBRARY_03 contained in group SOFTVEND01, the SELECT query shown below can be used.
```
SELECT ENTRY_NUMBER FROM QSYS2.MIRROR_VERSION_LIST 
    WHERE VERSION_GROUP = 'SOFTVEND01' AND 
          VERSION_NAME = 'APPLICATION_LIBRARY_03' AND
          STATE = 'ACTIVE';
```
Suppose that the result of the above SELECT statement identifies the ENTRY_NUMBER value of 123, the below call can be used to remove the entry immediately.
```
CALL QSYS2.REMOVE_MIRROR_VERSION(ENTRY_NUMBER    => 123, 
                                 STATE           => 'APPLIED', 
                                 ACTIVATION_TIME => 'IMMEDIATE'); 
```