- Call oaconnect, specifying an environment catalog.
- Call oaconnect with the DBUSER option, specifying an environment
catalog and a valid database user name and password.
- Call oaconnect with no options, specifying a TurboImage
root file and valid TurboImage password.
oaconnect on the Server
When calling oaconnect on the server, pass the name of the
environment catalog (or TurboImage root file, if using DBDirect)
through the environment parameter. Pass read/write privileges,
caching specifications, modes and precedence order through
the options parameter.
Enter values for user and password only for those database
management systems that provide access to a subset of tables
based on user/password combinations and only if the user must
have access to that subset.
For example, to connect to a database whose environment catalog
is called WYORD.ENV and to declare EAPRELOAD on the CONTACT
table in this database, the oaconnect declaration on the server
would look like the following:
oaconnect ("WYORD.ENV;","'EAPRELOAD=CONTACT';",
status,";";,";", instance)
CLoaconnect on the Client PC
When calling CLoaconnect on a client PC, pass the name of
the DataSource file through the environment parameter. Pass
read/write privileges, caching specifications, modes and precedence
order through the HOSTOACONNECTOPTIONS= option.
For example, to connect to a database defined in the Data
Source file C:\ODXCLNT\DS\WEST.INI, and to declare EAPRELOAD
on the CONTACT table in this database and an EACACHE of 1024K,
the oaconnect declaration on the client PC would look like
the following:
CLoaconnect ("C:\ODXCLNT\DS\WEST.INI;","",
HOSTOACONNECTOPTIONS='EAPRELOAD=CONTACT,EACACHE=1024';",
status,";";,";", instance)
Note that the code is the same whether connecting through
an environment catalog or using DBDirect. The DataSource object
contains all the information OmniAccess needs to connect to
the database, including the environment catalog or TurboImage
root file specifications.
Connecting to a TurboImage Root File
Opening a TurboImage root file directly through oaconnect
is called direct TurboImage access or DBDirect. oaconnect
can distinguish a TurboImage root file from an environment
catalog. When it tries to open a TurboImage root file, it
ignores the user parameter and uses the value passed in the
password parameter to open the database.
To call oaconnect using DBDirect from within a server-based
application, enter a valid TurboImage root file name (instead
of an environment catalog name) in the environment parameter
and the password for the database in the password parameter.
Connecting to a TurboImage root file from a client application
in a client server environment is exactly the same as when
connecting to an environment catalog.
For example, to connect to a TurboImage database called WYORD.WST.DAT
with the password RODEO, and to declare EAPRELOAD on the CONTACT
table in this database, the oaconnect declaration on the server
would look like the following:
oaconnect ("WYORD.WST.DAT;","'EAPRELOAD=CONTACT';",
status,";";,"RODEO;", instance)
Syntax
oaconnect (environment, options, status, username, password,
instance)
environment -- Environment
is the full path name of a valid Omnidex Environment Catalog
or TurboImage Root File. This is a character value passed
by reference, with a maximum length of 256 bytes, including
a semicolon or null terminator. When connecting directly out
of an Omnidex Client application, this parameter contains
the full path of the Client DataSource file to which to connect.
options -- Options define
the type of access allowed for this connection to the environment
catalog. This is a character value passed by reference, with
a maximum length of 256 bytes, including a semicolon or null
terminator. For server based applications, these options must
be passed through the options parameter of oaconnect. Client-based
applications pass the connect options through the Access Options
statement of the Data Source file.
status -- Indicates the success
of the oaconnect routine. A zero in status word 1 means the
catalog was opened successfully. The status structure is passed
by reference and contains fourteen 32-bit signed integers,
followed by a 36-character buffer.
username -- Is only recognized
when you specify the DBUSER option. It contains a valid user
name terminated by a null character, or a semicolon.
password -- Is reserved for
Direct TurboImage Access, or when you have specified the DBUSER
option. Otherwise, password is ignored. For Direct TurboImage
Access, password must contain a valid TurboImage password
passed by reference and terminated by a null character or
a semicolon.
For DBUSER access, password must contain the password that
corresponds to the user specified in the user parameter, passed
by reference and terminated by a null character or a semicolon.
instance -- Instance identifies
a unique connection to the catalog. This is a 32-bit signed
integer, passed by reference from oaconnect. If the connection
to the catalog is not successful, instance contains a zero.
Any other number that oaconnect assigns to instance means
a successful catalog connection. This instance number is used
to call other OmniAccess routines like oaopencursor, oainsert
and oainsertindex.
top
Options
Server Options
READ -- permits multiuser
read-only access to the underlying data files and index files.
WRITE -- permits multiuser
read/write access (the default) to the underlying data files
and index files
DBACCESS='mode' -- passes
a DBOPEN mode when directly accessing TurboImage databases.
DBUSER -- overrides the DEFAULT
USERCLASS statement by letting you pass a user name (through
user) and password (through password) to access the underlying
data management system.
DA -- causes all subsequent
OmniAccess calls to affect only the underlying data files.
ENVACCESS={W | R} -- governs
the type of access to the environment catalog for OmniAccess:
W -- allows OmniAccess to write TIDMAP and
other information into the open environment catalog. This
is the default and recommended setting.
R -- prohibits OmniAccess from writing TIDMAP
and other information into the open environment catalog.
DACACHE={ n | DEFAULT | ON | OFF |
MIN | MAX} -- governs the threshold of the DataAccess
cache, which stores information about connections to your
native data as discussed below.
EACACHE={ n | DEFAULT | ON | OFF |
MIN | MAX} -- governs the threshold of the EnvironmentAccess
cache, which stores metadata about the organization of your
native data, based on the open environment catalog.
IACACHE={ n | DEFAULT | ON | OFF |
MIN | MAX}
n -- represents a number (in Kb)
to reserve for the cache. This number can range from 0 to
4194304 Kb.
DEFAULT -- sets the size of the cache to
the default size of 128 Kb. This is the size of the cache
if no caching option is passed through the options parameter.
The default setting works for most applications.
ON -- sets the size of the cache to the default
size of 128 Kb, the same as DEFAULT.
OFF -- disables caching by setting the size
of the cache to 0.
MIN -- disables caching by setting the size
of the cache to its minimum, which is 0.
MAX -- sets the size of the cache to the
maximum size of 4194304 Kb.
EAPRELOAD={ table | " table1,
table2... tablen"} -- specifies which tables
are preloaded at connect time into the EnvironmentAccess cache.
MAXFOPENS={ n | DEFAULT | MIN | MAX
| OFF} -- controls the maximum number of files to
be opened by the operating system (assuming that the operating
system offers such controls at the process level).
PRECEDENCE = {NOTANDOR | NOTORAND}
-- The precedence you set through this option affects only
oaqualifys.
NOTANDOR -- evaluates AND
operations before OR operations in Boolean searches.
NOTORAND -- evaluates OR
operations before AND operations in Boolean searches.
Client Options
CLoaconnect
DATASOURCENAME=<dsname>
-- This option tells Cloaconnect which datasource to use out
of the specified datasource file. Each datasource file may
contain one or more datasource entries. Since only one connection
is established to one of the possible many datasources, contained
in the file, this option indicates which one to use. In its
absence, the first datasource encountered in the file is connected.
$LOCAL -- This option indicates
that the datasource filename passed in is actually an oa environment
catalog name. All further calls for this connection are made
locally to OmniAccess. (This option may not be used with libodxCLnt).
HOSTOACONNECTOPTIONS=<oaconnect
options> -- This option, when connecting to a
remote environment via a datasource file, will cause these
options to be appended to any other options configured for
this dictionary in the datasource file when the oaconnect
call on the server is made.
PRECONNECT -- This option
indicates that the server listening has already spawned a
waiting child process and this child connection is expecting
to connect to it. Passing this option overrides the Preconnect
setting that may already be established in the datasource
file for this datasource. This option must be used with an
odxsrvr listener and may not be used with $LOCAL or oa locally.
NOPRECONNECT -- This option
allows a particular oaconnect to insure that a new process
is established for the client on the server by odxsrvr at
connect time. This option is mainly used to override any Preconnect
setting that may be established in the datasource file for
this datasource.
top
Example
top
|
