-MODIFY DDF command (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 for -MODIFY DDF

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 for -MODIFY DDF

Option descriptions for -MODIFY DDF

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. You can use the MODIFY DDF command with the ALIAS option to define and manage as many as 40 location aliases dynamically. You can start, stop, cancel, change, and delete dynamic location aliases without stopping either DDF or Db2.

Start of change The MODIFY DDF command cannot be used to manage static location aliases. For more information, see Member-specific location aliases. End of change

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 for the INADDR_ANY method of TCP/IP group access. Clients use the 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.

Start of change Do not specify IPV4(IPv4-address) if the BINDSPECIFIC method is used for TCP/IP group access. End of change

IPV6(IPv6-address)

Adds or replaces an existing member-specific IPv6 address for the INADDR_ANY method of TCP/IP group access. Clients use the 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.

Start of change Do not specify IPV6(IPv6-address) if the BINDSPECIFIC method is used for TCP/IP group access. End of change

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. The decision to honor sysplex workload balancing request lies with the client.

Start of change The RQSTWLB option applies only to dynamic location aliases. For more information, see Member-specific location aliases. End of change

The RQSTWLB option can only be specified if the subsystem is part of a data sharing group, and it has group-wide scope.

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. DFLTWLB is the default installed option.

The DFLTWLB option can only be specified if the subsystem is part of a data sharing group and it has group-wide scope.

*: 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 for -MODIFY DDF

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.

Binding a location alias port to a different IP address for a standalone Db2 subsystem

A Db2 subsystem that is not a member of a Db2 data sharing group can create a single listen socket for a location alias port by requesting that the socket is bound to INADDR_ANY. If a PROFILE.TCPIP PORT statement also specifies an IP address in the BIND parameter for the alias port, then TCP/IP binds the listen socket to the specified address.

In most cases, if the PORT statement BIND parameter specifies an IP address for the alias port, it should specify the same IP address that Db2 displays for TCPPORT or SECPORT in the DSNL084I message in DISPLAY DDF command output.

However, if the PORT statement BIND parameter for the alias port specifies a different IP address than Db2 displays for its main TCPPORT or SECPORT, then TCP/IP binds the alias listen socket to the IP address that was specified in the PORT statement BIND parameter. The result is that the alias port can only be reached by targeting that specific IP address. Db2 does not learn or display any information about the IP address for the alias port.