OACONNECT
oaconnect opens an Omnidex Environment Catalog or client/server data
source file. The server-only oaconnect and the client/server CLoaconnect
function similarly. However, the server-only oaconnect connects to an
Environment Catalog, while CLoaconnect connects to a data source file.
oaconnect opens an environment catalog for queries or update transactions
through the OmniAccess API.
oaconnect on the Server
When calling oaconnect on the server, pass the name of the environment
catalog 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 Data Source
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 Data Source object contains all the information
OmniAccess needs to connect to the database, including the environment
catalog or TurboImage root file specifications.
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 Data Source 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.
Options
READ -- permits multi-user read-only
access to the underlying data files and index files.
WRITE -- permits multi user 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 data source to use out of the specified
data source file. Each data source file may contain one or more data source
entries. Since only one connection is established to one of the possible
many data sources, contained in the file, this option indicates which
one to use. In its absence, the first data source encountered in the file
is connected.
$LOCAL -- This option indicates that
the data source 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 data source
file, will cause these options to be appended to any other options configured
for this dictionary in the data source 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 data source
file for this data source 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
data source file for this data source
Example
Visual Basic
'OA routine execution status. 0 = success, 1 =
failure
Public glReturn As Long
'Instance number variable
Public glOAInstanceNo As Long
'Allocate storage for the Status Array by declaring
a variable
Private gtOAStatus As tOaStatusArray
'Connect to the environment
glReturn = oaconnect("/usr/ffl_orders.env",, gtOAStatus,
"", "", glOAInstanceNo)
'Check for successful connection
If glReturn <> 0 Then
 'There
was some error connecting so call oaerror to see what happened
glReturn
= oaerror(gtOAStatus, "", gsMessageText)
'handle
the error
...
End If
...
Top
|
