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

Start of changeThis command can be used to rebind a package for advanced triggers. However, issuing the REBIND PACKAGE command with a trigger created prior to the activation of function level 500 or higher, or with a basic trigger, results in an error.End of change

Start of changeFor a trigger package for an advanced trigger, you can use REBIND PACKAGE for the following activities:End of change

Start of change
  • 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
End of change

Start of changeYou can use REBIND PACKAGE to change the default rest service version for an existing REST service.End of change

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

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

Start of change

Phase-in of package copies for REBIND PACKAGE

FL 505

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

End of change

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.

The package owner must be a role to execute REBIND PACKAGE in a trusted context with role ownership.

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
Start of change

Syntax for REBIND PACKAGE

Read syntax diagramSkip visual syntax diagram REBIND PACKAGE ID-blockOWNER( authorization-id)QUALIFIER( qualifier-name) enable-block plan-management-block acceleration-block CONCENTRATESTMT(NOYES)CURRENTDATA(YESNO)DBPROTOCOL(DRDADRDACBF)DEFER(PREPARE)DEFER(INHERITFROMPLAN)NODEFER(PREPARE)DEGREE(1ANY)DESCSTAT(NOYES)DYNAMICRULES(RUNBINDDEFINEINVOKE)ENCODING(ASCIIEBCDICUNICODEccsid)ACCELERATOR( ' accelerator-name' )EXPLAIN(YESNOONLY)FLAG(IWEC)IMMEDWRITE(INHERITFROMPLANNOYES)ISOLATION(RRRSCSURNC)KEEPDYNAMIC(NOYES)REOPT(NONE1ALWAYS2ONCEAUTO)OPTHINT(' hint-id')PATH(,schema-nameUSER) PATHDEFAULT3 ROUNDING(CEILINGDOWNFLOORHALFDOWNHALFEVENHALFUPUP)RELEASE(COMMITDEALLOCATEINHERITFROMPLAN)RESTSERVICEDEFAULT4(YES)SWITCH(PREVIOUSORIGINAL)VALIDATE(RUNBIND)EXTENDEDINDICATOR(NOYES)
Notes:
  • 1 NOREOPT(VARS) can be specified as a synonym of REOPT(NONE)
  • 2 REOPT(VARS) can be specified as a synonym of REOPT(ALWAYS)
  • 3 The PATHDEFAULT keyword is mutually exclusive with the PATH keyword. Do not specify both keywords in the same REBIND command.
  • 4 The RESTSERVICEDEFAULT option is only valid for local REST service packages.
Read syntax diagramSkip visual syntax diagramCONCURRENTACCESSRESOLUTION(USECURRENTLYCOMMITTEDWAITFOROUTCOME)GENERIC( ' string' )BUSTIMESENSITIVE(YESNO)SYSTIMESENSITIVE(YESNO)ARCHIVESENSITIVE(YESNO)APPLCOMPAT( applcompat-level)

ID-block

Read syntax diagramSkip visual syntax diagram(,location-name.collection-id*.package-id*.(version-id*)*)

enable-block

Read syntax diagramSkip visual syntax diagramENABLEDISABLE(,BATCHDLIBATCHDB2CALLCICSIMSIMSBMPIMSMPPREMOTERRSAF)ENABLE(*)DLIBATCH(,connection-name)CICS(,applid)IMSBMP(,imsid)IMSMPP(,imsid)

plan-management-block

Read syntax diagramSkip visual syntax diagram PLANMGMT1(BASICEXTENDEDOFF) APREUSE1(NONEERRORWARN)APREUSESOURCE(CURRENTPREVIOUSORIGINAL)APCOMPARE1(NONEWARNERROR)APRETAINDUP1(YESNO)
Notes:
  • 1 This option is not supported for trigger packages.

acceleration-block

Read syntax diagramSkip visual syntax diagramGETACCELARCHIVE(NOYES)QUERYACCELERATION(NONEENABLEENABLEWITHFAILBACKELIGIBLEALL)

acceleration-block

Read syntax diagramSkip visual syntax diagramacceleration-blockQUERYACCELERATION(NONEENABLEENABLEWITHFAILBACKELIGIBLEALL)GETACCELARCHIVE(NOYES)ACCELERATIONWAITFORDATA( ' nnnn.m' )ACCELERATOR( ' accelerator-name' )
Read syntax diagramSkip visual syntax diagramQUERYACCELERATION(NONEENABLEENABLEWITHFAILBACKELIGIBLEALL)GETACCELARCHIVE(NOYES)ACCELERATIONWAITFORDATA( ' nnnn.m' )ACCELERATOR( ' accelerator-name' )
End of change

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.
Start of changePhase-in of package rebindsEnd of change
Start of changeFL 505With 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.End of change
Rebinding a package for a native SQL procedure
Start of changeIf 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.End of change 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.
Start of changeRebinding a packages for triggersEnd of change
Start of changeAlthough DBCS characters are generally allowed in trigger names, trigger names that contain DBCS characters cannot be used in REBIND TRIGGER PACKAGE operations. End of change
Start of changeRebinding packages for advanced triggersEnd of change
Start of change

If you issue a REBIND PACKAGE command against a package for an advanced trigger, the only bind options that you can change are EXPLAIN (but EXPLAIN(ONLY) is not accepted), 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.

End of change
Start of changeRestrictions for trigger packagesEnd of change
Start of changeA 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.End of change
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)