Troubleshooting
Problem
This document describes how the iSeries Access for Windows ODBC driver configuration controls how operating system objects are resolved to a library. This includes the setting of the job library list, the SQL naming convention, SQL path, and SQL Default collection.
Resolving The Problem
Overview
Client Access ODBC allows an ODBC application to set several job attributes. This document describes ODBC settings that affect how the library used for unqualified SQL requests is resolved. The ODBC settings covered are as follows:
| o | Default Libraries |
| o | Naming Convention |
| o | Use of extended dynamic support |
| o | The library used to resolve an unqualified object name |
| o | The SQL Path used to resolve unqualified procedures (V5R1 and later), functions and distinct types |
| o | The library used to create an object that does not have a fully qualified name |
| o | The library list used by the job |
| o | Authorities on newly created objects |
Important Note: In 7.1, support was added for long schema names; however, in the ODBC driver, a long name may only be used for the default schema name. All libraries in the library list are limited to their 10-character system name which is automatically generated by the system when a schema is created with a long name.
Naming Convention
The operating system supports the following naming conventions. SQL naming convention and "system" naming convention. SQL naming convention conforms to the ANSI SQL standards and is fully compatible with ODBC. SQL naming has no concept of a library list. Instead, most SQL objects (such as tables and views) that are not fully qualified are resolved to the default collection. In ODBC terms, a table name can be specified as qualifier-name qualifier-separator schema-name.table-name. With Client Access ODBC, the optional qualifier-name is the relational database name defined in the operating system. The optional schema-name corresponds to a library or collection. An example may help to clarify this. An operating system file named QCUSTCDT can be qualified in one of the following ways:
select * from S10TR014.QIWS.QCUSTCDT /* relational database name.libraryname.file name */
select * from QIWS.QCUSTCDT /* library name.file name */
select * from QCUSTCDT /* file name only will use the default collection */
With SQL naming convention, the operating system does not perform a library list search to locate an unqualified object. If a default collection is defined, the default collection is used to resolve unqualified SQL statements. If no default collection is specified, the authorization identifier library will be used as the default. In most cases that library will be the library with the same name as the user profile of the ODBC job being used. The exception to that rule exists when the connection is using extended dynamic support and the SQL statement is one which would be saved in an SQL package. In this case, the authorization identifier is actually the owner of the SQL package. For additional information, refer to Rochester Support Center knowledgebase document N1019084, Extended Dynamic Support and Resolution of Unqualified Objects. To link to document N1019084 immediately, click here
. The request fails if the library does not exist. The exception to this rule is how stored procedures (R510), user defined functions (UDFs) and distinct types are resolved. These objects are resolved using the SQL PATH. The operating system also supports "system" (*SYS) naming convention. This naming convention differs significantly from the ODBC specification. It should be used only with applications specifically designed for operating system naming convention. This naming convention uses a form of [Library-name]/file-name. For example:
select * from QIWS/QCUSTCDT /* library name/file name */
select * from QCUSTCDT /* file name only uses default collection, current lib or lib list */
With the *SYS naming convention, the unqualified SQL statements go to the default collection. If there is no default collection, the current library is used. If no current library is specified, the library list is used. In the latter case, new objects are created in library QGPL.
Default Collection
A job attribute set by ODBC that determines the library used when processing SQL statements that contain unqualified SQL names. When a default collection is set all unqualified objects except procedures, functions and types must reside in the default collection, regardless of naming convention.
Library List
Each job on the operating system has a library list. The library list is subdivided into four parts that native operating system applications search in the following order: system part, product library, current library, and user portion. An operating system library list is similar to the PATH environment variable used in DOS and Microsoft Windows PC operating systems.
Note: When replacing operating system software with a new release, changes made to IBM-supplied objects in libraries other than QGPL and QUSRSYS are not saved.
System Library List
The system portion of the library list is intended for IBM-supplied libraries that conform to the operating system naming convention. It should contain only IBM-supplied objects that are part of the base operating system.
Product Library
The database host server will add a product library to the library list for the database host server jobs for the QIWS library. Prior to V5R1 the database host server programs resided in this library. Beginning with V5R1 there is no real need for this library to be in the library list and it will probably be removed in a future release.
Current Library
The current library is the library used for creating native operating system objects.
Note: ODBC jobs running with the default naming convention of *SQL create objects in the DEFAULT COLLECTION rather than the Current Library. When using ODBC, this parameter typically affects only stored procedures that use native OS/400 or i5/OS commands and APIs.
User Library List
The user portion of the library list is intended to contain libraries used by application programs.
SQL Path
The SQL Path is used to resolve unqualified functions and distinct types (all releases) and stored procedures (V5R1 and later).
V4R5 and earlier of the OS/400 host server set the SQL Path to *LIBL where *LIBL will be the library list set by ODBC. V5R1 OS/400 with APAR SE03585 or later set the SQL path as follows:
If the user specifies a library list the database server sets the SQL PATH to <system>, <specified-library-list>. Otherwise the default SQL path of <system>, <authorization identifier> is used.
where:
<system> is the system path of QSYS, QSYS2
<specified-library-list> is the library list specified by ODBC. Default collection, if specified, is the first library in the library list.
<authorization identifier> is a library with the same name as the user profile for the current job.
ODBC Data Source: Default Libraries Setting
The data source default library box is used to specify the default collection and user portion of the operating system library list for jobs connected to this data source. Libraries can be added to the user portion of the library list, or can replace it entirely. To replace the user portion of the library list entirely, specify a list of library names. To add to the existing user portion of the library list, add *USRLIBL to the list of libraries.
The first library specified in this list of libraries is the default collection. For example, LIB1,LIB2,LIB3 replaces the server job's user portion of the library list with the three libraries specified. The default collection is LIB1. To have no default collection, start the library list with a comma, followed by the list of libraries. For example, ,LIB1,LIB2,LIB3.
Notes:
1 | If you blank out the default libraries box, the driver will default to using QGPL library. If you intend to specify no default collection, use a comma. |
2 | ODBC does not modify the system portion of the library list. The current library is set to the current library parameter of the user profile being serviced. |
3 | For additional examples of setting up the Default Library parameter on the data source, see the Client Access online help. |
4 | V5R1 and later of Client Access Express ODBC separated the default collection and library list into two different settings. |
Common Questions
How can I get ODBC to search the library list?
As explained above, edit the ODBC data source and set system naming to *SYS. The default library must be empty, or on versions older than V5R1, the default libraries setting must start with a comma so that no default collection is defined (for example, ",MYLIB1, MYLIB2"). Note that most commercial applications cannot work with operating system naming convention. Using system naming convention with most applications will result in an SQL syntax error SQL5016 - Qualified object name &1 not valid.
Can the library list be searched to locate a stored procedure?
In V4R5 and earlier, SQL procedures were resolved like all other SQL objects so only SYS naming could search the library list. Starting in V5R1 procedures are resolved using the SQL PATH, regardless of naming convention.
External procedures are slightly more complicated. When an external procedure is called, operating system first resolves the procedure definition in the catalog tables. The name resolution works as described above (for example, based on naming convention, default collection, and so on). Once the procedure definition has been located the definition is read for the name of the external program object. The name of the external program object can have a specific library name or a library name of *LIBL. If it has a specific name, that program object is used regardless of the naming convention in affect. If the external program objects library name is *LIBL then the library list is used to locate the program, regardless of the naming convention for the caller's job.
The external program name library is set based on the naming convention in affect at the time of the CREATE PROCEDURE statement.
If the procedure definition is not located by the database, it will attempt to call a program object with the same name as the procedure. See the SQL Programming Concepts manual in iSeries Information Center for details on this special situation.
Can a stored procedure search the library list?
The naming convention and default collection used by a program with embedded dynamic SQL is set by the SQL precompiler options in affect when the program is compiled. Only SQL procedures can be compiled through ODBC. The precompiler options used are picked up from the job running the CREATE PROCEDURE statement. If the procedure is created under a job running *SYS naming convention then it will resolve objects as defined for *SYS.
Related Information
[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"Platform":[{"code":"PF012","label":"IBM i"}],"Version":"6.1.0"}]
Historical Number
9951625
Was this topic helpful?
Document Information
Modified date:
18 December 2019
UID
nas8N1010026