Connection Procedures

This topic discusses the PeopleTools connection procedures in alphabetical order.

ODBC uses an abstraction that maps a single name (called the data source name or DSN) to all the necessary underlying software components required to access the data. The data source name is chosen by an end user or a system administrator and should express the kind of data that the DSN represents. ODBC data source mapping information is maintained in the registry in Microsoft Windows.

In order to connect to a PeopleSoft data source, several pieces of information are needed. With the introduction in PeopleTools of multiple sign-on capabilities, users must be prompted for required log in information. By default, PeopleTools installs an ODBC data source with the name PeopleSoft PeopleTools. This DSN has no references to PeopleSoft connection information. It is in effect an empty data source. Using this data source forces the underlying PeopleSoft security mechanisms to present the user with a sign-on dialog box. The user completes this as for a normal PeopleSoft application.

As per the ODBC standard, the PeopleSoft driver enables the user to create a data source that provides the information necessary to log in. If the information matches a current session, the user is not prompted to log in again.

The connection environment is affected by the workstation settings for PeopleSoft Process Scheduler. The values for the DBBIN and TOOLBIN are searched for the necessary support files required to log in to a database. Hence these values need to be valid. In the case of a three-tier logon, the value for DBBIN should be set empty.

Note: ODBC supports three connection functions: SQLConnect, SQLDriverConnect, and SQLBrowseConnect. SQLBrowseConnect is not supported by the PeopleSoft Open Query ODBC driver.

Syntax

RETCODE SQLConnect(hdbc,szDSN,cbDSN,szUID,cbUID,szAuthStr,cbAuthStr)

Description

SQLConnect loads a driver and establishes a connection to a data source. The connection handle references storage of all information about the connection, including status, transaction state, and error information.

This function assumes that a connection may be completed by supplying only a DSN, user, and password. It further assumes that the application will either prompt the end user for security information, the security information is hard-coded, or the security information can be obtained from a centralized security server, such as Kerberos.

Parameters

This table describes the parameters:

Argument

Type

Use

Description

hdbc

HDBC

Input

Connection handle.

szDSN

UCHAR FAR*

Input

Data source name.

cbDSN

SWORD

Input

Length of szDSN.

szUID

UCHAR FAR*

Input

User identifier.

cbUID

SWORD

Input

Length of szUID.

szAuthStr

UCHAR FAR*

Input

Authentication string (typically the password).

cbAuthStr

SWORD

Input

Length of szAuthStr.

Syntax

RETCODE SQLDriverConnect(hdbc,hwnd,szConnStrIn,cbConnStrIn,szConnStrOut,cbConnStrOutMax,pcbConnStrOut,fDriverCompletion)

Description

SQLDriverConnect handles the entire connection process for an application, prompting the end user for any information to complete the connection. The programmer can specify as much or as little about the connection as necessary. The following example illustrates the simplest case, in which the application does not specify any information at all about the connection. It supplies the connection handle returned from SQLAllocConnect, a window handle, and option specification of SQL_DRIVER_COMPLETE, and zero or NULL for the rest of the arguments. 

rc = SQLDriverConnect(hdbc, hwnd, NULL, 0, NULL, 0, 0, SQL_DRIVER_COMPLETE);

The following keywords are used and supported by the PeopleSoft ODBC driver:

  • DSN: Data source name required by ODBC.

  • APPNAME: Application server name used for three-tier logon only.

  • DBTYPE: Database type of login can be any of the following values:

    • DB2: Db2 using Centura SQL network.

    • DB2400: Db2 on AS/400 using client access.

    • DB2ODBC: Db2 using the IBM ODBC driver.

    • DB2UNIX: Db2 UNIX driver.

    • ORACLE: Oracle using the OCI interface.

    • MICROSFT: SQL Server using ODBC.

    • APPSRV: Used to indicate that the database name is actually an application server name.

  • DBNAME: Name of the database or alias.

  • DBQ: Used to combine values separated by a slash (/), such as APPNAME/DBTYPE/DBNAME. The APPNAME value and the following slash are dropped when not in three-tier.

  • UID: PeopleSoft user ID.

  • PWD: Password associated with the PeopleSoft user.

The driver uses any information it retrieves from the ODBC.INI file or registry to augment the information passed to it in the connection string. If the information in the ODBC.INI file or registry duplicates information in the connection string, the driver uses the information in the connection string.

The existing PeopleSoft database connection dialog box prompts the user for any required connection information.

Parameters

This table describes the parameters:

Argument

Type

Use

Description

hdbc

HDBC

Input

Connection handle.

hwnd

HWND

Input

Window handle. The application can pass the handle of the parent window, if applicable, or a null pointer if either the window handle is not applicable or if SQLDriverConnect does not present any dialog boxes.

szConnStrIn

UCHAR FAR*

Input

A full connection string, a partial connection string, or an empty string.

cbConnStrIn

SWORD

Input

Length of szConnStrIn.

szConnStrOut

UCHAR FAR*

Output

Pointer to storage for the completed connection string. Upon successful connection to the target data source, this buffer contains the completed connection string. Applications should allocate at least 255 bytes for this buffer.

cbConnStrOutMax

SWORD

Input

Maximum length of the szConnStrOut buffer.

pcbConnStrOut

SWORD FAR*

Output

Pointer to the total number of bytes returned in szConnStrOut. If the number of bytes is greater than or equal to cbConnStrOutMax, the completed connection string in szConnStrOut is truncated to cbConnStrOutMax -1.

fDriverCompletion

UWORD

Input

Flag that indicates whether the Driver Manager or the driver must prompt for more connection information: SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED, or SQL_DRIVER_NOPROMPT.