What are SQL packages?
SQL packages are permanent objects used to store information related to prepared SQL statements. They are used by database middleware drivers (such as the IBM i Access for Windows ODBC driver) when the "extended dynamic" box is checked on a data source or specified as a connection property. Extended dynamic packages are also supported by the IBM i Access OLE DB provider and the Toolbox JDBC driver. They are also used by applications that use the QSQPRCED and QxdaProcessExtDynEDRS API interfaces. The SQL packages created using any of these interfaces are called extended dynamic SQL packages and are the subject of the following questions and answers. DRDA also uses SQL package objects, but they are considerably different in behavior and are not covered below.
What applications use the QSQPRCED and QxdaProcessExtDynEDRS API interfaces?
The API interfaces are available to any IBM i programmer. Examples of applications that use these APIs include Oracle J D Edwards EnterpriseOne and many SAP components.
When do SQL packages get created?
In the case of database middleware, the existence of the package is checked when the client application first prepares an eligible statement. If the package does not exist, it is created at that time. In the case of the QSQPRCED or QxdaProcessExtDynEDRS APIs, creation of the package is controlled by the application.
How are SQL packages named?
SQL packages used by the IBM i Access database middleware are named by taking the application name specified in the data source configuration and appending three letters that are an encoded set of the package configuration attributes. For the API interfaces, the name of the package is provided by the application. For example, J D Edwards EnterpriseOne creates SQL packages which correspond to the names of UBE's.
What library does the SQL package go into? Is there a preferred library for SQL packages?
For database middleware, this is part of the driver and connection configuration. For the API interfaces, the library is provided by the application. For IBM i, there isn't really a preferred library for SQL packages and there aren't any functional or performance differences based on the containing library. This choice should be made based either on application specific guidelines, ease of management for the application environment, or maximizing their reuse. For example, placing SQL packages in the library QTEMP will result in an SQL package for each job which cannot be referenced by other jobs.
What are the advantages of using SQL packages?
Because SQL packages are a shared resource, the information built when a statement is prepared is available to all the users of the package. This saves processing time, especially in an environment when many users are using the same or similar statements. Because SQL packages are permanent, this information is also saved across job initiation/termination and across IPLs. By comparison, dynamic SQL will use additional processor and memory resources each time the statement is used by another job.
SQL packages also allow the system to accumulate statistical information about the SQL statements that result in better decisions about how long to keep cursors open internally and how to best process the data needed for the query. As above, this information is shared across users and retained for future use. In the case of dynamic SQL, this information must be "relearned" by every job and every user.
Do all prepared statements go into an SQL package?
Not all SQL statements can be prepared, consult the DB2 for i SQL Reference for a complete list. Here's a list of some SQL statements that can be prepared:
|ALTER TABLE||CREATE PROCEDURE||LOCK TABLE|
|CREATE SCHEMA||INSERT||SET TRANSACTION|
|CREATE TABLE||LABEL ON||UPDATE|
In the case of database middleware, the driver managers make further restrictions about the statements that can go into a package. An SQL statement goes into the package only if one of the following is true:
QSQPRCED packages do not have these restrictions and will contain any of the statements listed above when they are prepared using function '2' or '9'.
How can I tell what statements are in an SQL package?
The PRTSQLINF command can be used to produce a formatted report showing the SQL statement and information about the access plan used to access the data.
You can also run an "Explain SQL" operation on an SQL package using IBM i Navigator.
What is the maximum size of an SQL package?
Since Version 5, the size limit for an SQL package have been approximately 500MB or 16,384 statements, whichever occurs first. Since V5R2, a new Query Options File (QAQQINI) option SQL_INCREASE_PKG_LIMIT has been available to provide a way to optionally increase the maximum size of extended dynamic SQL packages to approximately 1GB. IBM i also contains enhancements to better manage SQL package size including some changes on what information is retained and automatic compression.
Can the same statement appear multiple times in the same SQL package?
Every PREPARE operation checks to see if there is already a prepared statement with all of the same statement text and attributes. If there is, a new statement name entry (about 80 bytes) is allocated, but it just points to the corresponding duplicate information already in the package.
How can I tell if the SQL package is being used?
The database monitor can be used to log information about SQL processing on the system. It includes the name of the package in the SQL summary records. The following SQL statement will show the package, the SQL operation, and the statement text.
SELECT qqc103, qqc21, qq1000 from ‹db monitor file›
For the IBM i Access middleware, you can also look in the job log for the message "Extended Dynamic has been disabled" to determine if the driver was unable to use an SQL package.
This information is also provided under the "Analyze" function for SQL Performance Monitors using the IBM i Navigator.
What data is stored in an SQL package?
The SQL package contains all the necessary information to execute the prepared statement. This includes registry of the statement name, the statement text, the internal parse tree for the statement, definitions of all the tables and fields involved in the statement, and the query access plan information needed to access the tables at run time.
For environments which make use of the SQL Query Engine (SQE), SQL packages no longer contain the entire access plan which is instead stored in the SQL Plan Cache. Even in these environments, the information in the SQL package provides better reuse of SQL statement information.
How big is an SQL package?
Prior to V4R3, SQL packages were limited to 16MB. Furthermore, ODBC packages had additional restrictions on the number of statements allowed. In V4R3, the maximum size of a package was increased to 16,384 statements or approximately 500MB, whichever comes first. In V4R3, ODBC package size limits have also been removed. Note that the SQL package must be created on V4R3 to be capable of this new larger size, they are not converted automatically. If you are upgrading to V4R3, extended dynamic SQL packages should be deleted if you wish to take advantage of the larger size.
Are there any performance considerations for the new bigger packages?
Internally DB2 uses internal hash tables to improve performance of package searches by either statement name or by statement text. As a result, there are no significant performance impacts for using relatively large SQL packages.
Is there an optimal size for bigger packages?
Because of the hash tables, there are no significant performance impacts for using relatively large packages.
What happens when SQL packages get full?
This behavior depends on the interface that is using the SQL Packages In the case of the IBM i Access for Windows ODBC driver, the driver detects the package full condition (SQL0904, reason code 7) and then starts using dynamic SQL for newly prepared statements. This has some negative performance consequences as indicated above. Statements that were previously prepared in the SQL package continue to be used. Although the IBM i Access ODBC data source configuration offers to clear the SQL package when it is full, this is only done at connect time and is of limited use. In the case of the API interfaces, an SQL code of -904 is returned to the application and the application must decide how to proceed.
Are there other times when an SQL package can become unusable?
SQL packages have some attributes that are stored at the package level and must be compatible with the application. For example, SQL packages used by IBM database middleware allow specification of a default collection for unqualified table names. If the SQL package already exists and its default collection does not match that of the client application, the package will not be used and the user will use dynamic SQL. The same thing can happen when the CCSID specified when the SQL package was created is different from the environment where the SQL package is to be used.
When should I delete SQL packages?
Since Version 5, there is considerably less need to delete SQL packages, but it is still reasonable to delete them when you've made substantial changes to the database (which could necessitate access plan rebuilds) and whenever you are advised to do so by appropriate system or application service personnel. Because extended dynamic SQL packages are recreated when the application is run, there is little harm in deleting them.
How do I delete SQL packages?
Before deleting SQL packages, you must first quiesce the application to prevent errors during the deletion. To delete a specific SQL package, you can use the DLTSQLPKG command. To locate and delete SQL packages, you can use the WRKOBJ command and select option 4 to delete them. The command syntax is as follows:
WRKOBJ OBJ(*ALL/*ALL) OBJTYPE(*SQLPKG)
Only extended dynamic SQL packages are automatically recreated by the application, so it is important that you do not delete IBM-supplied SQL packages (whose names start with "Q"), or DRDA packages. If you are unsure about whether a specific SQL package is used by DRDA, use the PRTSQLINF command and look at the first page of the report. DRDA packages will contain an RDB keyword entry identifying the relational database for DRDA.
Why would service personnel recommend deleting SQL packages? Are they corrupted?
SQL package corruption is actually not a common occurrence, and there is rarely a need to delete them, especially with the recent IBM i enhancements. In releases prior to V5R1, deletion was often recommended based on the size constraints but this has become much less frequent with the increases in SQL package size. If you do have functional problems with SQL packages, use normal support channels to provide additional information. It is especially helpful to save a copy of the SQL package for additional analysis.