An instance is an identifier that represents the unique connection by a user to an Omnidex Environment Catalog. It is a signed integer that is returned to the instance parameter of the Status array. This value is then passed to other api routines subsequently called.

The instance establishes not only the data in the environment, but the type of access (read, read/write, or exclusive) that user has to the data. Each instance also contains information about the connection such as the type of access and other configuration options.

To establish an instance, call oaconnect and specify a compiled Omnidex Environment Catalog filespec (or TurboIMAGE database name) through the environment parameter. Specify the connect options through the options parameter, including user and password, as appropriate.

It is possible to open several catalogs concurrently and thereby establish several environment instances in the same application. This is useful when data is organized in several separate environment catalogs.

Close an Instance

When an application no longer requires access to an Omnidex Environment Catalog, it should close the instance before terminating.

If the instance remains open after the application terminates, it may interfere with other applications and users trying to access the environment catalog. Although this is unlikely, it is a good practice to close instances when the application finishes using them.

Omnidex Client applications should close instances to free up memory on the PC and to close socket connections to the server.

To close an instance, call oadisconnect and pass the value returned to the instance parameter of oaconnect. Closing an instance automatically closes any cursors open for the environment established for that instance. When performed from a client application, it also closes any socket connections between a client and server.

Open a Cursor

A cursor defines a working area of the Omnidex environment for a given environment instance. For example, sixty-three rows are qualified using Omnidex indexes and the twenty-fourth row has been fetched. The cursor lets oaselect hold this place so when oafetch is called to retrieve the next row, it retrieves the twenty-fifth row.

To establish a cursor, call oaopencursor. Pass the instance value returned to oaconnect's instance parameter, to oaopencursor's instance parameter.

When a cursor is established, a signed integer value is returned to the cursor parameter. This value is then passed to many OmniAccess routines (like oaselect and oafetch) so that they may reference or modify the current cursor.

Multiple Cursors

By opening multiple cursors, a program can retrieve or update on one cursor without affecting another. This supports simultaneous updates and retrievals on the same table, or simultaneous retrievals of different subsets of rows from the same table.

Cursor numbers are unique across multiple instances. This means a cursor number is not reused between instances. For example, if instance 1 produces cursor 1, no other instance will use the number 1 for its cursor, as long as the original cursor 1 remains open.

Close a Cursor

While multiple cursors support a variety of transactions being performed simultaneously, they each require system resources to be maintained. For example, cursor 1 may be holding a place in a list of 350 rows whose identifiers are stored in memory. To free the system resources associated with a cursor, the cursor should be closed when it is no longer needed.

To close a cursor, call oaclosecursor. Specify the number of the cursor to close by passing it as the cursor parameter to oaclosecursor. Remember, this is the number established for the cursor when it was opened by calling oaopencursor.

All open cursors associated with a particular instance are closed automatically when that instance is closed by a call to oadisconnect.

Client Applications

Client applications in a client/server environment can use the OmniAccess API. All API functions must be prefixed with a CL before the function name.

There are several other things to consider when writing Omnidex Client applications that use the OmniAccess API:

Parameters and buffers have certain limits based on the routine to which they apply.
The byte ordering may not be the same on the server as it is on the client.
The byte boundaries for binary integers vary across server operating systems.
The instance number returned by oaconnect for a Client application may differ from the instance number being used on the server.
The CHAR=n option automatically converts between alphanumeric and numeric data, thus eliminating any concern for byte-ordering and integer conversion across hardware platforms.

Parameter And Buffer Sizes

The maximum size of parameters and data buffers for OmniAccess routines directly accessed by Omnidex Client applications depends on the version of Omnidex Client that you are running. Consult your Omnidex Client API's online help for more information.

Byte Ordering

Byte ordering and integer alignment differ across hardware platforms. Integers may be read from left to right (big endian) or right to left (little endian), depending on server architecture. When transporting integer data across systems in buffers defined in the application, it may be necessary to reorder it to accommodate different architectures.

OmniAccess handles all integer parameters automatically.

Byte Boundaries

Integers may also observe different boundaries on different machines. It may be necessary to pad integer variables on one machine to accommodate the observed boundaries on another machine.

This is further complicated by different meanings of integer types across operating systems. What is considered an "int" on one operating system may be longer or shorter than an "int" on another operating system. Using offsets and lengths when defining variables in client applications ensures that integer definitions mean the same thing across operating systems. Use structures that explicitly define the data type and length. For example, use int32 instead of long. This makes applications more portable across operating systems by preventing ambiguous interpretations of data types.

Because the boundaries for binary numbers differ across platforms, when defining a data buffer structure for binary integers, observe the boundaries enforced for the operating system and data management platform the will be accessed.

Instance Numbers In Client Applications

The instance number returned by oaconnect for a Client application may differ from the instance number being used on the server. A single Omnidex Client application may connect to several environments on the server. To address a specific environment (identified by instance) on a server (identified by node), create a permanent buffer to contain the instance value. This buffer can be referenced from Client applications.

CHAR=n

The CHAR=n option automatically converts between alphanumeric and numeric data, thus eliminating any concern for byte-ordering and integer conversion across hardware platforms.

For example, when a client application on a PC requests numeric data using the CHAR=n, OmniAccess automatically converts the data from its numeric format to character data.

Conversely, when a client application sends information to a server, the character representation of the number is converted to a numeric type and byte order appropriate for the server operating system.

When you pass CHAR=n in the options parameter, the buffer parameter must reflect the length of the ASCII character representation, not its binary storage format, and should be padded with blanks up to length n.

The CHAR=n option supports ASCII representations of numeric values that contain a leading + or -. It also supports exponential values, like 6.02e23, for numeric columns defined as TYPE FLOAT.

Character representations of floating point data may lose precision.

Top


Development	OmniAccess API
Connect Open a Cursor Multiple Cursors Close a Cursor Disconnect Client Applications OmniAccess API Programming Basics Managing Data Functions Development	Programming Basics All OA and CLOA applications must: Connect to an Omnidex Environment (establish an instance) either directly or indirectly through an Omnidex Data source. Open a Cursor To terminate an OmniAccess API application, the application must: close all open cursors close all instances Connect to an Omnidex Environment When connecting to an Omnidex Environment, an instance is established. An instance is an identifier that represents the unique connection by a user to an Omnidex Environment Catalog. It is a signed integer that is returned to the instance parameter of the Status array. This value is then passed to other api routines subsequently called. The instance establishes not only the data in the environment, but the type of access (read, read/write, or exclusive) that user has to the data. Each instance also contains information about the connection such as the type of access and other configuration options. To establish an instance, call oaconnect and specify a compiled Omnidex Environment Catalog filespec (or TurboIMAGE database name) through the environment parameter. Specify the connect options through the options parameter, including user and password, as appropriate. It is possible to open several catalogs concurrently and thereby establish several environment instances in the same application. This is useful when data is organized in several separate environment catalogs. Close an Instance When an application no longer requires access to an Omnidex Environment Catalog, it should close the instance before terminating. If the instance remains open after the application terminates, it may interfere with other applications and users trying to access the environment catalog. Although this is unlikely, it is a good practice to close instances when the application finishes using them. Omnidex Client applications should close instances to free up memory on the PC and to close socket connections to the server. To close an instance, call oadisconnect and pass the value returned to the instance parameter of oaconnect. Closing an instance automatically closes any cursors open for the environment established for that instance. When performed from a client application, it also closes any socket connections between a client and server. Open a Cursor A cursor defines a working area of the Omnidex environment for a given environment instance. For example, sixty-three rows are qualified using Omnidex indexes and the twenty-fourth row has been fetched. The cursor lets oaselect hold this place so when oafetch is called to retrieve the next row, it retrieves the twenty-fifth row. To establish a cursor, call oaopencursor. Pass the instance value returned to oaconnect's instance parameter, to oaopencursor's instance parameter. When a cursor is established, a signed integer value is returned to the cursor parameter. This value is then passed to many OmniAccess routines (like oaselect and oafetch) so that they may reference or modify the current cursor. Multiple Cursors By opening multiple cursors, a program can retrieve or update on one cursor without affecting another. This supports simultaneous updates and retrievals on the same table, or simultaneous retrievals of different subsets of rows from the same table. Cursor numbers are unique across multiple instances. This means a cursor number is not reused between instances. For example, if instance 1 produces cursor 1, no other instance will use the number 1 for its cursor, as long as the original cursor 1 remains open. Close a Cursor While multiple cursors support a variety of transactions being performed simultaneously, they each require system resources to be maintained. For example, cursor 1 may be holding a place in a list of 350 rows whose identifiers are stored in memory. To free the system resources associated with a cursor, the cursor should be closed when it is no longer needed. To close a cursor, call oaclosecursor. Specify the number of the cursor to close by passing it as the cursor parameter to oaclosecursor. Remember, this is the number established for the cursor when it was opened by calling oaopencursor. All open cursors associated with a particular instance are closed automatically when that instance is closed by a call to oadisconnect. Client Applications Client applications in a client/server environment can use the OmniAccess API. All API functions must be prefixed with a CL before the function name. There are several other things to consider when writing Omnidex Client applications that use the OmniAccess API: Parameters and buffers have certain limits based on the routine to which they apply. The byte ordering may not be the same on the server as it is on the client. The byte boundaries for binary integers vary across server operating systems. The instance number returned by oaconnect for a Client application may differ from the instance number being used on the server. The CHAR=n option automatically converts between alphanumeric and numeric data, thus eliminating any concern for byte-ordering and integer conversion across hardware platforms. Parameter And Buffer Sizes The maximum size of parameters and data buffers for OmniAccess routines directly accessed by Omnidex Client applications depends on the version of Omnidex Client that you are running. Consult your Omnidex Client API's online help for more information. Byte Ordering Byte ordering and integer alignment differ across hardware platforms. Integers may be read from left to right (big endian) or right to left (little endian), depending on server architecture. When transporting integer data across systems in buffers defined in the application, it may be necessary to reorder it to accommodate different architectures. OmniAccess handles all integer parameters automatically. Byte Boundaries Integers may also observe different boundaries on different machines. It may be necessary to pad integer variables on one machine to accommodate the observed boundaries on another machine. This is further complicated by different meanings of integer types across operating systems. What is considered an "int" on one operating system may be longer or shorter than an "int" on another operating system. Using offsets and lengths when defining variables in client applications ensures that integer definitions mean the same thing across operating systems. Use structures that explicitly define the data type and length. For example, use int32 instead of long. This makes applications more portable across operating systems by preventing ambiguous interpretations of data types. Because the boundaries for binary numbers differ across platforms, when defining a data buffer structure for binary integers, observe the boundaries enforced for the operating system and data management platform the will be accessed. Instance Numbers In Client Applications The instance number returned by oaconnect for a Client application may differ from the instance number being used on the server. A single Omnidex Client application may connect to several environments on the server. To address a specific environment (identified by instance) on a server (identified by node), create a permanent buffer to contain the instance value. This buffer can be referenced from Client applications. CHAR=n The CHAR=n option automatically converts between alphanumeric and numeric data, thus eliminating any concern for byte-ordering and integer conversion across hardware platforms. For example, when a client application on a PC requests numeric data using the CHAR=n, OmniAccess automatically converts the data from its numeric format to character data. Conversely, when a client application sends information to a server, the character representation of the number is converted to a numeric type and byte order appropriate for the server operating system. When you pass CHAR=n in the options parameter, the buffer parameter must reflect the length of the ASCII character representation, not its binary storage format, and should be padded with blanks up to length n. The CHAR=n option supports ASCII representations of numeric values that contain a leading + or -. It also supports exponential values, like 6.02e23, for numeric columns defined as TYPE FLOAT. Character representations of floating point data may lose precision. Top
	Omnidex Version 4.1 Build 1 - F20.05 - Dynamic Information Systems Corporation - Copyright © 2005