KI_ALLOC_CONNECT
| Argument | Enumeration | Purpose |
|---|---|---|
| connection | Current database connection | |
| bDefault | Optional boolean flag TRUE if default connection | |
| newConnection | Connection to new database | |
| status | KDB_ERROR_ENUM | Return status |
KI_ALLOC_CONNECT
This must be called to allocate a connection handle for use in connecting to a named database, e.g. a KDB or an Oracle database, using KI_CONNECT. Connection numbers are small integers less than _KDB_MAX_CONNECT and greater than 1 so at most _KDB_MAX_CONNECT-1 databases can be connected simultaneously in a program.
A connection need not be established for direct ISAM access to uncataloged files in legacy applications as a pseudo connection allowing this is considered to be open on connection _KDB_LEGACY_CONNECTION. In this case the filename used in KI_OPEN must be fully qualified or must be with respect to the current working directory of the operating system.
If connection is _KDB_AUTO_HANDLE then KCML will allocate a handle number and return it in newConnection. If non-zero then KCML will close any connection open on that number and assign it as a connection handle returning it again in newConnection.
The optional second argument can be set to TRUE if this handle is to become the new default connection. If missing or FALSE then the default is unchanged. Defining a default connection removes the requirement to specify a connection number on WHILE TRANS and THROW ROLLBACK statements. Only the default connection supports cached tables.
Handles allocated with this call should have their resources freed with KI_FREE_CONNECT.
To convert the opaque token returned by KI_ALLOC_CONNECTION into a small integer compatible with KCMLs prior to version 6.20, use the internal KCML functions 'KCML_DecodeMagicToValue() and 'KCML_DecodeMagicToType() e.g.
oldValue = 'KCML_DecodeMagicToValue(connect) magicType = 'KCML_DecodeMagicToType(connect) IF magicType != _KDB_MAGIC_CONNECT THEN STOP