Client Access ODBC Default Libraries Setting

IBM Software Technical Document_______________________________________________________________

Document Information

Document Number: 9951625Functional Area: Client AccessSubfunctional Area: ODBCSub-Subfunctional Area: ConfigurationOS/400 Release: 6.1; 7.1; V5R1M0; V5R2M0; V5R3M0;

V5R4M0; V6R1M0Product: IBM I ACCESS FOR WINDOWS

(5770XE100)IBM ISERIES CLIENT ACCESS EXP(5722XE100)SYSTEM I ACCESS FOR WINDOWS(5761XE100)

Product Release: N/A

_______________________________________________________________

Document TitleClient Access ODBC: Default Libraries Setting

Document DescriptionOverview

Client Access ODBC allows an ODBC application to set several job attributes. This document describesODBC settings that affect how the library used for unqualified SQL requests is resolved. The ODBC settingscovered are as follows:o Default Librarieso Naming Conventiono Use of extended dynamic supportThese settings affect the following behaviors:o The library used to resolve an unqualified object nameo The SQL Path used to resolve unqualified procedures (R510 and later), functions and distinct typeso The library used to create an object that does not have a fully qualified nameo The library list used by the jobo Authorities on newly created objects

Important Note: In 7.1, support was added for long schema names; however, in the ODBC driver, a longname may only be used for the default schema name. All libraries in the library list are limited to their10-character system name which is automatically generated by the system when a schema is created with a

IBM i Support: Software Technical Document : 9951625 http://www-912.ibm.com/s_dir/slkbase.NSF/0/2554db904e5a601b8625...

1 de 5 18/07/2013 02:19 p.m.

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 compatiblewith ODBC. SQL naming has no concept of a library list. Instead, most SQL objects (such as tables andviews) that are not fully qualified are resolved to the default collection. In ODBC terms, a table name can bespecified as qualifier-name qualifier-separator schema-name.table-name. With Client Access ODBC, theoptional qualifier-name is the relational database name defined in the operating system. The optionalschema-name corresponds to a library or collection. An example may help to clarify this. An operatingsystem 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 anunqualified object. If a default collection is defined, the default collection is used to resolve unqualifiedSQL statements. If no default collection is specified, the authorization identifier library will be used as thedefault. In most cases that library will be the library with the same name as the user profile of the ODBC jobis used. The exception to that rule exists when the connection is using extended dynamic support and theSQL statement is one which would be saved in an SQL package. In this case, the authorization identifier isactually the owner of the SQL package. For additional information, refer to Rochester Support Centerknowledgebase document 385570825, Extended Dynamic Support and Resolution of UnqualifiedObjects. To link to document 385570825 immediately, click here . The request fails if the library doesnot exist. The exception to this rule is how stored procedures (R510), user defined functions (UDFs) anddistinct types are resolved. These objects are resolved using the SQL PATH.The operating system also supports "system" (*SYS) naming convention. This naming convention differssignificantly from the ODBC specification. It should be used only with applications specifically designedfor 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 isno default collection, the current library is used. If no current library is specified, the library list is used. Inthe 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 containunqualified SQL names. When a default collection is set all unqualified objects except procedures, functionsand types must reside in the default collection, regardless of naming convention.


2 de 5 18/07/2013 02:19 p.m.

Library List

Each job on the operating system has a library list. The library list is subdivided into four parts that nativeoperating system applications search in the following order: system part, product library, current library, anduser portion. An operating system library list is similar to the PATH environment variable used in DOS andMicrosoft Windows PC operating systems.

Note: When replacing operating system software with a new release, changes made to IBM-supplied objectsin libraries other than QGPL and QUSRSYS are not saved.

System Library ListThe system portion of the library list is intended for IBM-supplied libraries that conform to the operatingsystem naming convention. It should contain only IBM-supplied objects that are part of the base operatingsystem.

Product LibraryThe database host server will add a product library to the library list for the database host server jobs for theQIWS library. Prior to V5R1 the database host server programs resided in this library. Beginning with V5R1there is no real need for this library to be in the library list and it will probably be removed in a future release.

Current LibraryThe 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 DEFAULTCOLLECTION rather than the Current Library. When using ODBC, this parameter typically affects onlystored procedures that use native OS/400 or i5/OS commands and APIs.

User Library ListThe 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(R510 and later).

R450 and earlier of the OS/400 host server set the SQL Path to *LIBL where *LIBL will be the library listset by ODBC. R510 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 , . Otherwise the default SQL path of , is used.

where: is the system path of QSYS, QSYS2 is the library list specified by ODBC. Default collection, if specified, is the firstlibrary in the library list. is a library with the same name as the user profile for the current job.


3 de 5 18/07/2013 02:19 p.m.

ODBC Data Source: Default Libraries Setting

The data source default libraries box is used to specify the default collection and user portion of the operatingsystem library list for jobs connected to this data source. Libraries can be added to the user portion of thelibrary list, or can replace it entirely. To replace the user portion of the library list entirely, specify a list oflibrary 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,LIB3replaces the server job's user portion of the library list with the three libraries specified. The default collectionis LIB1. To have no default collection, start the library list with a comma, followed by the list of libraries. Forexample, ,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 Libraries parameter on the data source, see the

Client Access online help.4 R510 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 beempty, or on versions older than R510, the default libraries setting must start with a comma so that no defaultcollection is defined (for example, ",MYLIB1, MYLIB2"). Note that most commercial applications cannotwork with operating system naming convention. Using system naming convention with most applicationswill 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 R450 and earlier, SQL procedures were resolved like all other SQL objects so only SYS naming couldsearch the library list. Starting in R510 procedures are resolved using the SQL PATH, regardless of namingconvention.

External procedures are slightly more complicated. When an external procedure is called, operating systemfirst 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 hasbeen located the definition is read for the name of the external program object. The name of the externalprogram object can have a specific library name or a library name of *LIBL. If it has a specific name, thatprogram object is used regardless of the naming convention in affect. If the external program objects libraryname is *LIBL then the library list is used to locate the program, regardless of the naming convention for thecaller's job.

The external program name library is set based on the naming convention in affect at the time of theCREATE PROCEDURE statement.


4 de 5 18/07/2013 02:19 p.m.

If the procedure definition is not located by the database, it will attempt to call a program object with thesame name as the procedure. See the SQL Programming Concepts manual in iSeries Information Center fordetails 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 theSQL precompiler options in affect when the program is compiled. Only SQL procedures can be compiledthrough ODBC. The precompiler options used are picked up from the job running the CREATEPROCEDURE statement. If the procedure is created under a job running *SYS naming convention then itwill resolve objects as defined for *SYS.

__________________________________________________________________

PMR Number:Related APARs:

Related Public Documents:IBM disclaims all warranties, whether express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Byfurnishing this document, IBM grants no licenses to any related patents or copyrights. Copyright 1996,1997,1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,2008, 2009, 2010, 2011, 2012, 2013 IBM Corporation. Any trademarks and product or brand names referenced in this document are the property of their respective owners.Consult the Terms of use link for trademark information.


5 de 5 18/07/2013 02:19 p.m.