-MODIFY DDF (Db2)

The MODIFY DDF command modifies the status and configuration of the Db2 distributed data facility (DDF) and statistics for connections or threads that are controlled by DDF.

Authorization

To execute this command, you must use a privilege set of the process that includes one of the following privileges or authorities:

SYSOPR authority
SYSCTRL authority
SYSADM authority

Db2 commands that are issued from a logged-on z/OS® console or TSO SDSF can be checked by Db2 authorization using primary and secondary authorization IDs. Start of change A logged-on z/OS user ID must be defined in RACF or a similar security server. End of change

Syntax

Option descriptions

ACCTG

Specifies whether Db2 generates an accounting trace record occurrence for every transaction used by a distributed client application.

For existing distributed threads, the specified ACCTG option takes effect only after the thread generates an accounting trace record at a commit or rollback with no open resources. Until then, the previously saved ACCTG option for the thread continues to control when it generates accounting trace records.

(no option value)

Specifies the default behavior.

When this option is set back to its default setting, or if the setting was never changed, Db2 generates an accounting trace record when no open resource exists past a commit or rollback. If any of the following resources remain open and pending, Db2 does not generate an accounting trace record:

Open WITH HOLD cursors
Declared global temporary tables that are not dropped
Unreleased LOB locators
A commit processed by a stored procedure when running with 2-phase commit rules
Allocated RELEASE DEALLOCATE packages (due to the -MODIFY DDF PKGREL(BNDOPT) option)
Allocated KEEPDYNAMIC YES packages

However, if only one the last two preceding resources types, but not both, are open after a commit or rollback, Db2 generates an accounting trace record occurrence after a commit or rollback.

ALLCOMMIT

When this option is set, Db2 generates an accounting trace record occurrence after any commit or rollback. However, Db2 still maintains the WLM enclave that was created by Db2, prior to the initial requested transaction which left open resources. Also, Db2 maintains information so that when the DBAT is terminated after completing the work requests from its client connection, it deletes the enclave and informs WLM of the transactions that were completed.

To use the ACCTG(ALLCOMMIT) option, you must also set the CMTSTAT subsystem parameter value to INACTIVE. Otherwise, Db2 returns the following message to indicate that the default behavior is still being used.

DSNL302I ACCTG IS SET TO COMMIT_WITH_NO_OPEN_RESOURCES

ALIAS

Specifies the creation, changes to, or deletion of a specified location alias.

alias-name

Specifies the name of an alias for a DDF location. An alias is an alternative for the location name that can be used for connection processing. The alias name must meet all of the following requirements:

Contains no more than 16 characters.
Contains only letters (excluding alphabetic extenders), numbers, or the underscore character.

ADD

Creates an alias with the specified name.

DELETE

Deletes the specified alias.

START

Db2 starts accepting connection requests to the specified alias if DDF is started. If DDF is not started, the alias is marked eligible for starting, and Db2 automatically starts accepting connection requests to the alias when DDF is started.

If the subsystem is part of a data sharing group, Db2 registers the alias with WLM and Db2 participates in sysplex workload balancing for connections to the alias.

STOP

Db2 stops accepting new connection requests to the specified alias. Existing database access threads that process connections to the alias remain unaffected. Inactive connections related to the alias are closed.

A stopped alias is marked ineligible for starting and does not start automatically when DDF starts. If the subsystem is part of a data sharing group, Db2 unregisters the alias with WLM and Db2 stops participating in sysplex workload balancing for connections to the alias.

CANCEL

Db2 stops accepting new connection requests to the specified alias. All database access threads that process connections to the alias are canceled and inactive connections that are related to the alias are closed.

A canceled alias is marked ineligible for starting and does not start automatically when DDF starts. If the subsystem is part of a data sharing group, Db2 unregisters the alias with WLM and Db2 stops participating in sysplex workload balancing for connections to the alias.

PORT(port-name)

Adds or replaces an existing port that can be used by DDF to accept distributed requests for the specified alias. The value that is specified for port-name value must be a decimal number in the range 1 - 65535, including 65535, and must be different than the values for the ports of other aliases. Specify a PORT value for an alias when you want to identify a subset of data sharing members to which a distributed request can go.

SECPORT(secport-name)

Adds or replaces an existing secure port that can be used by DDF to accept secure-distributed requests by using SSL for the specified alias. The value that is specified for secport-name must be a decimal number in the range 1 - 65535, including 65535, and must be different than the values for ports of other aliases. Specify a SECPORT value for an alias when you want to identify a subset of data sharing members to which a secure-distributed request can go.

NPORT

Deletes the alias port, if one exists.

NSECPORT

Deletes the alias secure port, if one exists.

IPV4(IPv4-address)

Adds or replaces an existing member-specific IPv4 address. Clients use that address when they use one of the following capabilities for a connection to a dynamic location alias:

Sysplex workload balancing
XA protocols for coordinating distributed transactions

This address must be specified in the dotted decimal form.

IPV6(IPv6-address)

Adds or replaces an existing member-specific IPv6 address. Clients use that address when they use one of the following capabilities for a connection to a dynamic location alias:

Sysplex workload balancing
XA protocols for coordinating distributed transactions

This address must be specified in the colon-hexadecimal form.

NIPV4

Deletes the alias IPv4 address, if one exists.

NIPV6

Deletes the alias IPv6 address, if one exists.

PKGREL

Specifies whether Db2 honors the bind options of packages that are used for remote client processing. Db2 uses the behavior of the COMMIT option before the first MODIFY DDF command is issued with the PKGREL option.

If the CMTSTAT subsystem parameter is set to ACTIVE, the MODIFY DDF command with the PKGREL keyword has no effect, and Db2 always uses the behavior of the COMMIT option.

BNDOPT: The rules of the RELEASE bind option that was specified when the package was bound are applied to any package that is used for remote client processing. The high-performance DBAT that is used by a terminating client connection is deallocated.
BINDOPT is the default PKGREL option if the CMTSTAT subsystem parameter is set to INACTIVE.
BNDPOOL: The rules of the RELEASE bind option that was specified when the package was bound are applied to any package that is used for remote client processing. The high-performance DBAT that is used by a terminating client connection is pooled.
COMMIT: The rules of the RELEASE(COMMIT) bind option are applied to any package that is used for remote client processing.
If the CMTSTAT subsystem parameter is set to ACTIVE, Db2 always uses the behavior of this option.

RQSTWLB

FL 502 Specifies that Db2 returns to the remote client a request to enable sysplex workload balancing. This option can only be specified if the subsystem is part of a data sharing group. This option has group-wide scope. The decision to honor sysplex workload balancing request lies with the client.

Notes:

The RQSTWLB option applies for Db2 for Linux®, UNIX, and Windows 11.5 or later (CLI Db2 code release "SQL11050" and IBM® Data Server Driver for JDBC and SQLJ 4.26.14 or later.)
If RQSTWLB is used, applications might encounter additional communication errors such as SQL codes -30108 and -20542. These errors are removed by default with Db2 11.5.8 or later client drivers, and the client property enableseamlessfailovererrorcodes controls whether they are issued.

*: The option is enabled for entire data-sharing group. This is the default option.
location-name: The option is enabled for remote clients that access the data-sharing group using the location-name as the data source.
alias-name: The option is enabled for remote clients that access the data-sharing group using the specified alias-name as data source.

DFLTWLB

FL 502 Db2 honors the sysplex workload balancing option requested by the client. This option can only be specified if the subsystem is part of a data sharing group. This option has group-wide scope. DFLTWLB is the default installed option.

*: The option is enabled for entire data-sharing group. This is the default option.
location-name: The option is enabled for remote clients that access the data-sharing group using the location-name as the data source.
alias-name: The option is enabled for remote clients that access the data-sharing group using the specified alias-name as data source.

For more information about enabling sysplex workload balancing with client drivers, see:

SESSIDLE(session-idle-limit)

Specifies that number of minutes that applications can remain inactive before the associated session data token becomes invalid because of timeout.

session-idle-limit can be any integer 0 - 999999. When no value was specified, the default value is 1440.

Usage notes

When to use PKGREL options and high-performance DBATs

Start of change During normal production operating hours, you can specify that DDF uses the PKGREL(BNDOPT) or PKGREL(BNDPOOL) options to specify that Db2 uses high-performance DBATs to service remote connections. A high-performance DBAT is a database access thread that stays associated with a remote connection at transaction boundaries, rather than being pooled. With high-performance DBATs, the amount of allocation and deallocation processing is reduced because the copy of the package remains allocated until the DBAT terminates. For more information, see Enabling high-performance DBATs. End of change

For environments where client configurations control the use of packages that are bound with the RELEASE(DEALLOCATE) bind option, BNDOPT might be the preferred value of the PKGREL option. For environments where any client can use packages that are bound with the RELEASE(DEALLOCATE) bind option, BNDPOOL might be the preferred value of the PKGREL option. Either option value offers improved performance by reducing the CPU costs for allocation and deallocation of packages.

However, packages that run under the rules of the RELEASE(DEALLOCATE) bind option are likely to remain allocated and prevent maintenance activities such as objects modifications and bind operations. So, you can specify the PKGREL(COMMIT) option during routine and emergency maintenance periods. For more information, see Controlling deallocation for high-performance DBATs.

Delayed effects of PKGREL(COMMIT)

When you issue the MODIFY DDF command and specify the PKGREL(COMMIT) option, the effects are not immediate. After the command is issued, any database access thread that was running RELEASE(DEALLOCATE) packages is terminated when the connection becomes inactive. At the next unit-of-work from the client, a new database access thread is created in RELEASE(COMMIT) mode. Any DBAT that remains active waiting for a new unit-of-work request from its client because of the RELEASE(DEALLOCATE) rules is terminated by the DDF service task that runs every 2 minutes. So, within approximately 2 minutes, all database access threads run under the rules of the RELEASE(COMMIT) bind option.

Changes to alias attributes

The attributes of an existing alias can be modified only when the alias is stopped. The modified alias attributes take effect when the alias is started. By default, aliases that are created by the DSNJU003 utility are started and aliases that are created by the MODIFY DDF command are stopped. DSNJU004 does not print any information for aliases that are created by the MODIFY DDF command. You can use the output of the DISPLAY DDF command to find the status of aliases created by the MODIFY DDF command.

How Db2 uses the IPV4 and IPV6 values

Db2 does not activate the IP addresses that you specify with the IPV4 or IPV6 parameters. Clients use those addresses for routing purposes only. Db2 does not require that the addresses are dynamic virtual IP addresses (DVIPAs). The IP addresses are used to reach the DVIPA network that serves the Db2 data sharing group. You can specify the IP addresses in the MODIFY DDF command only after the DSNJU003 is run with the IPV4 or IVP6 parameter to specify a member-specific location address. The specified IP addresses are returned in the WLM weighted server list when clients connect to a dynamic location alias, based on the following conditions:

If the client connects uses an IPv6 address, the server list contains the alias IP addresses that were specified with the IPV4 and IPV6 parameters of the MODIFY DDF command. If an IPv4 address was not specified in the MODIFY DDF command, the location IP address that was specified by the IPV4 keyword of the DSNJU003 utility is returned instead. Similarly, if an IPv6 address is not specified in the MODIFY DDF command, the location IP address that was specified by the IPV6 keyword of the DSNJU003 utility is returned instead.
If the client connects uses an IPv4 address, the server list contains the alias IP address that was specified with the IPV4 parameter of the MODIFY DDF command. If an IPv4 address was not specified in the MODIFY DDF command, the location IP address that was specified by the IPV4 keyword of the DSNJU003 utility is returned instead.