KI_CONNECT

Connect to named database

CALL KI_CONNECT dbase$, connection, dsn$, uid$, pwd$ TO status

status = 'ki_connect( dbase$, connection, dsn$, uid$, pwd$ )

KI_CONNECT

This uses a connection number conn, previously allocated with KI_ALLOC_CONNECT, to establish a connection with a database of type dbase$ which currently can be one of the following

Some connections may require extra information such as a user name and password for login security and these can be supplied with uid$ and pwd$ respectively. Other databases may need connection information to specify the server or database and this can be passed in dsn$. If not applicable, these options should be left as empty strings.

A status of KE_FILENOTFOUND indicates that KCML cannot find the shared library corresponding to the connection (e.g. koracle.dll). This library should be in the same directory as the KCML binary. This error is also possible if the shared library cannot load dependent shared libraries, e.g. oci.dll in the case of Oracle. This may require the database binary directory to be on the path.

A status of KE_NOLOGIN implies a failure to log in on an authenticated database and you should use KI_ERROR_TEXT passing the negative connection number as the first argument to get the reason for the failure.

Oracle considerations

The dsn$ parameter is used for the SQL*NET connection string which has the form //server[:port][/service]. If blank then the default connection will be used.

To connect with SYSDBA or SYSOPER status append " AS SYSDBA" or " AS SYSOPER" to the uid$ string.

If the database is set up for external authentication and KCML is executing on the same server as the database then you can pass an empty or blank uid$ to have KCML use external authentication.

Conventionally all the tables in a KCML Oracle database will be owned by one user in a single schema. That user will be authenticated by a password and to avoid exposing the database password, you can set it to a default value of "kcc123" but pass "!" for pwd$ when you connect. KCML will then use a secret password generated uniquely for the KCML instance. If this fails to connect it reverts to the default and if this then connects, it set the password to the secret one again. This protects the database as the password is never exposed. For other applications like sql*plus to be able to access the data they either have to run as the DBA or under an account that has been GRANTed appropriate privileges by the DBA or the schema owner.

For an Oracle RAC database with more than one database server in a cluster you can pre-connect to a backup server by specifying a comma separated list of connections strings. The first in the list will be the primary, provided a connection is possible. In the event of the primary failing KCML will transparently switch to the next connection in the list. If the secondary later fails then it will connect to the next entry or the first again if there are only two entries. Preconnecting a primary and a secondary will slow the initial connection but will avoid saturating the secondary server if a large number of connects fail over together. You can defer connecting to the secondary server by prefixing its connect string with a $ sign and KCML will wait until an actual failover before attempting to connect. The servers are separated by a comma.

Optionally the server list may be followed by a semi-colon and a squence of comma separate integers. These integers represent times to delay when attempting to reconnect. Thus "1,4,16" means an attempt will be made to connect to the server instantly, followed by further attempts after 1 second, then a further 4 seconds and finally a further 16 seconds.

Compatibility

The use of connection handles was introduced in KCML 5.0. To simplify porting programs written before this time, a programmer can use the connection handle KDB_DEFAULT_CONNECTION in subsequent calls to KI_ALLOC_HANDLE and skip the call to KI_CONNECT.

History

See Also: