REBIND PACKAGE subcommand (DSN)

The DSN subcommand REBIND PACKAGE rebinds an application package when you make changes that affect the package, but have not changed the SQL statements in the program.

For example, you can use REBIND PACKAGE after you complete the following activities:

Migrate to a new Db2 release
Apply maintenance to Db2
Modify authorizations
Create a new index that statements in the package can use
Collect statistics using the RUNSTATS utility or with another utility by using the STATISTICS keyword

This command can be used to rebind a package for advanced triggers. However, issuing the REBIND PACKAGE for a basic trigger results in an error.

For a trigger package for an advanced trigger, you can use REBIND PACKAGE for the following activities:

Reoptimize SQL statements in the trigger after you create a new index or use the RUNSTATS utility
Change some of the default bind options that were used when the package was created
Make a trigger package valid after it was marked as invalid because an object on which the trigger was dependent was dropped

You can use REBIND PACKAGE to change the default rest service version for an existing REST service.

REBIND PACKAGE is generally faster and more economical than BIND PACKAGE. You should use BIND PACKAGE with the ACTION(REPLACE) option under the following conditions:

When you change the SQL statements
When you recompile the program
When you have previously run BIND PACKAGE with the SQLERROR(CONTINUE) option

When the REBIND PACKAGE(*) command is issued, the only affected trigger packages are those for advanced triggers that the issuer is authorized to rebind.

Phase-in of package copies for REBIND PACKAGE

The REBIND PACKAGE command might create a new current copy of the package, while retaining the existing current copy as a phase-out copy. This is called rebind phase-in. There may be multiple copies of an existing package, but there will only ever be one current copy. There may be one original copy, one previous copy, and multiple phased-out copies.

The current copy, with copy ID 0 (or non-0) is stored in the catalog table SYSPACKAGE. The previous and original copies have copy ID 1 and 2 respectively, and can be found in the SYSPACKCOPY table. All phased-out copies have a copy ID other than 1 and 2 and can be found in SYSPACKCOPY as well.

The package copy that a thread executes can be found in the package accounting trace record. That copy can be either current or phased-out. Db2 might delete the phased-out copies on subsequent executions of the REBIND PACKAGE command. You may want to quiesce threads which execute the phased-out copies and then rebind the package to reduce storage incurred by phased-out copies.

Rebind phase-in is supported for the following options:

APREUSE(NONE) PLANMGMT(EXTENDED)
APREUSE(WARN) PLANMGMT(EXTENDED) APREUSESOURCE(CURRENT)
APREUSE(ERROR) PLANMGMT(EXTENDED) APREUSESOURCE(CURRENT)
The package is not a generated package for a trigger or SQL routine, such as a procedure or user-defined function.

Db2 waits for the duration specified by the IRLMRWT subsystem parameter before it creates package copies for the rebind phase-in operation.

For more information, see Phase-in of package rebinds

Environment for REBIND PACKAGE

You can use REBIND PACKAGE through DB2I, or enter the REBIND PACKAGE subcommand from a DSN session running in foreground or background.

Data sharing scope: Group

Authorization for REBIND PACKAGE

The package owner must have authorization to execute all SQL statements embedded in the package for REBIND PACKAGE to build a package without returning error messages. For VALIDATE(BIND), Db2 verifies the authorization at bind time. For VALIDATE(RUN), Db2 verifies the authorization initially at bind time, but if the authorization check fails, Db2 rechecks it at run time.

When EXPLAIN(ONLY) is specified, you must have the EXPLAIN privilege.

FL 500 The package owner must be a role to execute REBIND PACKAGE in a trusted context with role ownership. If performing a rebind in a trusted context that has a role-as-object owner attribute and the OWNERTYPE rebind option is not specified, the default owner is determined as follows:

If the OWNER option is not specified, there is no change in ownership and the existing owner (with existing OWNERTYPE) remains the default owner.
If the OWNER option is specified, the role that is specified in the OWNER option becomes the owner. In a trusted context, the default owner must be a role. For the rebind to succeed, the binder needs BINDAGENT privilege from the role that is specified in the OWNER option. The binder also receives BINDAGENT privilege if the role that is associated with the binder has BINDAGENT privilege.

The following table explains the authorization required to run REBIND PACKAGE, depending on the options specified.

Table 1. Summary of privileges for REBIND PACKAGE
Option	Authorization required to run REBIND PACKAGE
REBIND PACKAGE with no change in ownership because the OWNER keyword is not specified.	The authorization IDs of the process must have one of the following authorities: Ownership of the package BIND privilege on the package BINDAGENT privilege from the owner of the package PACKADM authority on the collection or on all collections SYSADM or SYSCTRL or System DBADM authority
REBIND PACKAGE with no change in ownership, although the original owner is specified for the OWNER keyword.	The authorization IDs of the process must have one of the following authorities: OWNER authorization-id must be one of the primary or secondary authorization IDs of the binder BINDAGENT privilege from the owner of the package
REBIND PACKAGE with change of ownership. (An authorization ID that is not the original owner is specified in the OWNER keyword.)	The new OWNER must have one of the following authorities: BIND privilege on the package PACKADM authority on the collection or on all collections SYSADM or SYSCTRL or system DBADM authority If any of the authorization IDs or roles of the process has SYSADM authority, SYSCTRL authority, or system DBADM authority, OWNER authorization-id can be any value, when subsystem parameter SEPARATE_SECURITY is set to NO. If any of the authorization IDs has the BINDAGENT privilege granted from the owner, authorization-id can specify the grantor as OWNER. Otherwise, the OWNER authorization-id must be one of the primary or secondary authorization IDs of the binder. If you specify OWNER authorization-id , Db2 first checks the OWNER and then the binder for the necessary bind privilege. If the binder does not have SYSADM, SYSCTRL, or system DBADM authority, the authorization ID or role of the OWNER must have one of the following to add a new package or new version of an existing package to a collection: The BINDADD system privilege and either the CREATE IN privilege or PACKADM authority on the collection or on all collections SYSADM, SYSCTRL, or system DBADM authority

Syntax for REBIND PACKAGE

Notes:

¹ NOREOPT(VARS) can be specified as a synonym of REOPT(NONE)
² REOPT(VARS) can be specified as a synonym of REOPT(ALWAYS)
³ The PATHDEFAULT keyword is mutually exclusive with the PATH keyword. Do not specify both keywords in the same REBIND command.
⁴ The RESTSERVICEDEFAULT option is only valid for local REST service packages.

ID-block

enable-block

plan-management-block

Notes:

¹ This option is not supported for trigger packages.

acceleration-block

Descriptions for REBIND PACKAGE

The following options identify the packages to rebind by specifying the location, collection, package name, and version. You must identify a package name, and you can also supply a version ID.

location-name

The location of the DBMS where the package rebinds and where the description of the package resides. The location name must be defined in the SYSIBM.LOCATIONS catalog table. If that table does not exist or if the DBMS is not in it, you receive an error message. See LOCATIONS catalog table.

The default is the local DBMS.

collection-id or *

Specifies the collection to contain the package to bind, or that already contains the package to rebind. There is no default.

You can use an asterisk (*) to rebind all local packages with the specified package-id in all the collections for which you have bind privileges.

package-id or *

Specifies the name of the package to rebind, as listed in column NAME of catalog table SYSPACKAGE. There is no default. You can use an asterisk (*) to rebind all local packages in collection-id for which you have bind privileges.

The package-id value can be an undelimited or delimited identifier. The delimiter for package-id is double quotation marks ("). If package-id is delimited, Db2 does not convert the value to uppercase.

version-id or *

Specifies the version of the package to rebind, as listed in column VERSION of catalog table SYSPACKAGE.

You can use an asterisk (*) to rebind all local versions of the specified package-id in collection-id for which you have bind privileges.

Using only () rebinds the version of the package that is identified by the empty string.

If you omit version-id , the default depends on the how you specify package-id . If you use * for package-id , then version-id defaults to *. If you explicitly provide a value for package-id , then version-id defaults to the empty string version.

*

Rebinds all local Db2 packages for which the applicable authorization ID has the BIND privilege. Specifying (*) is the same as specifying the package name as (*.*.(*)) or (*.*). The applicable authorization ID is:

The value of OWNER, if you use that option
The primary authorization ID of the process running the bind, if you do not use the option OWNER

Other options for REBIND PACKAGE

For descriptions of the other options in the syntax diagram, see the topic BIND and REBIND options for packages, plans, and services.

Usage notes for REBIND PACKAGE

Rebinding multiple packages

If you rebind multiple packages, Db2 commits each successful rebind before rebinding the next package.

Phase-in of package rebinds

With rebind-phase in, Db2 can rebind a package concurrently with its execution. A rebind operation creates a new copy of the package. When the rebind operation finishes, new threads can use the new package copy immediately, and existing threads can continue to use the copy that was in use prior to the rebind (the phased-out copy) without disruption. For more information, see Phase-in of package rebinds.

Resolving autobind phase-in failures

FL 504 If an autobind phase-in operation fails, Db2 marks the package rebind-advisory status by setting SYSPACKAGE.OPERATIVE='R'. Db2 also issues message DSNT500I with reason code '00E30305'X and resource type '804'X. This failure situation can occur when the maximum number of package copy IDs is reached autobind phase-in generates package copies. After the package is marked in rebind-advisory status, it can still be allocated and executed, and invalid statements continue to be incrementally bound. If an autobind phase-in does not succeed, Db2 retries it a few times. However, an explicit rebind is best for a package that is marked in rebind-advisory status. The explicit rebind can be eligible for rebind phase-in, depending on the PLANMGMT bind option and PLANMGMT subsystem parameter value. For more information, see Autobind phase-in for packages with statement-level invalidation. End of change

Rebinding a package for a native SQL procedure

If you issue a REBIND PACKAGE command against a native SQL procedure package, the only bind options that you can change are EXPLAIN, PLANMGMT, SWITCH, APRETAINDUP, APREUSE, APREUSESOURCE, and APCOMPARE. If you try to change other bind options the command will fail and return message DSNT215I. The REBIND PACKAGE command rebinds only the SQL statements included in the procedure and not the control statements in the procedure definition.

Rebinding a package for an SQL function

If you issue a REBIND PACKAGE command against a package for an SQL function, the only bind options that you can change are EXPLAIN, PLANMGMT, and SWITCH. If you try to change other bind options, the command will fail and return message DSNT215I. The REBIND PACKAGE command rebinds only the SQL statements included in the function and not the control statements in the function definition.

Rebinding a packages for triggers

Although DBCS characters are generally allowed in trigger names, trigger names that contain DBCS characters cannot be used in REBIND TRIGGER PACKAGE operations.

Rebinding packages for advanced triggers

If you issue a REBIND PACKAGE command against a package for an advanced trigger, the only bind options that you can change are EXPLAIN, FLAG, PLANMGMT, and CONCENTRATESTMT. If you try to change other bind options, the command will fail and return message DSNT215I.

The REBIND PACKAGE command rebinds only the SQL statements included in the trigger and not the control statements in the trigger definition.

Restrictions for trigger packages

A trigger package can be explicitly rebound, but it cannot be explicitly bound using the BIND PACKAGE subcommand. A trigger package cannot be explicitly freed using the FREE PACKAGE sub-command or the DROP PACKAGE statement. Use the DROP TRIGGER statement to delete the trigger package. A trigger package cannot be copied, and it can only be rebound locally. Remote rebind of a trigger package is not allowed.

Trace information for data sharing members

When this command with group scope is issued in a Db2 data sharing member, it also runs on all other active members. IFICID 090 trace records for other group members can show that the same command was issued by the SYSOPR authorization ID from the 016.TLPKN5F correlation ID, in addition to the trace records from the member where the original command was issued. See Command scope in Db2 data sharing.

Example for REBIND PACKAGE

Rebind packages TEST.DSN8BC81.(MAY_VERSION) and PRODUCTION.DSN8BC81.(DEC_VERSION), both of which are located at the local location USIBMSTODB22. The packages can run only from the CICS® or the DLIBATCH environments if the connection ID is CON2. This replaces the CON1 that is specified on the BIND PACKAGE command.

REBIND PACKAGE (USIBMSTODB22.TEST.DSN8BC81.(MAY_VERSION),
                USIBMSTODB22.PRODUCTION.DSN8BC81.(DEC_VERSION)) -
  ENABLE (CICS,DLIBATCH) CICS (CON2)