Dataphor.org

Native CLI

Modified: 2009/07/02 12:26 by Bryn - Uncategorized
Although it enables an extremely rich frontend application experience, the standard Dataphor CLI requires a large footprint, in terms of deployment dependencies, memory usage, and processing power. In addition, because it hosts an embedded local instance, it is not possible to use the standard CLI to enable cross-instance communication. To address these issues, a new Native CLI was introduced in 2.2.

The Native CLI is intended to be used as a lightweight, potentially stateless communication path to a Dataphor server. For applications that do not need the extra functionality enabled by the standard CLI, the Native CLI provides a functional alternative.

Edit

Usage

The Native CLI can be used in two ways: 1) By establishing a session and executing calls against that session, or 2) By executing directly without maintaining any state information.

Edit

Session Information

Both access mechanisms use the same set of session information to establish communication with a Dataphor server. In addition to the host name, instance name, and optional port number, the NativeSessionInfo structure defined in the Alphora.Dataphor.DAE.NativeCLI namespace is used to provide credentials and session-specific settings for the connection.

Edit

Instance Identification

To specify the instance to be used, the Native CLI requires a host name, an instance name, and an optional port number override. Similar to out-of-process aliases in the Standard CLI, if an override port number is provided, it will be used instead of consulting the listener to obtain the port number.

Edit

NativeSessionInfo

The NativeSessionInfo structure defines the following settings:
  • UserID - The Dataphor UserID used to connect.
  • Password - The password used to connect.
  • DefaultLibraryName - The default library name for the session.
  • DefaultUseDTC - Whether or not to use the Distributed Transaction Coordinator on the session.
  • DefaultUseImplicitTransactions - Whether or not to use implicit transactions on the session.
  • DefaultIsolationLevel - The default isolation level for transactions initiated on the session.
  • DefaultMaxStackDepth - The default max stack depth for processes running on the session.
  • DefaultMaxCallDepth - The default max call depth for processes running on the session.
  • UsePlanCache - Whether or not to use the plan cache for the session.

Edit

Session Based Usage

In order to allow the Native CLI to be used to coordinate transactional changes with a Dataphor server, a session is established, and a session handle is used to invoke calls on that session.

To use the session-based CLI, create an instance of the NativeCLISession class defined in the Alphora.Dataphor.DAE.NativeCLI namespace. This is a disposable class that manages the session handle, as well as the remoting aspects of communicating with the Dataphor server.

Note that in addition to establishing a session, the Native CLI starts a process for use with that session. All execution and transaction management calls invoked on the session use this same process.

The NativeCLISession class provides the following methods:

Edit

BeginTransaction

void BeginTransaction(IsolationLevel AIsolationLevel)
Begins a new transaction at the specified isolation level.

Note that the isolation level is a System.Data.IsolationLevel. The following list shows the corresponding Dataphor isolation level for each System.Data.IsolationLevel:
  • ReadUncommitted: Browse
  • ReadCommitted: CursorStability
  • RepeatableRead,Serializable: Isolated
  • Chaos, Snapshot, Unspecified: Not supported. It is an error to specify these isolation levels.

Edit

PrepareTransaction

void PrepareTransaction()
Prepares a transaction for committal by performing all the outstanding constraint checks.

Edit

CommitTransaction

void CommitTransaction()
Commits a transaction.

Edit

RollbackTransaction

void RollbackTransaction()
Rolls back a transaction in progress.

Edit

GetTransactionCount

int GetTransactionCount()
Returns the current transaction nesting level.

Edit

Execute

NativeResult Execute(string AStatement, NativeParam[] AParams)
NativeResult Execute(string AStatement, NativeParam[] AParams, NativeExecutionOptions AOptions)
NativeResult[] Execute(NativeExecuteOperation[] AOperations)
Executes a D4 statement, optionally with the given parameters and execution options.

AStatement may contain only one D4 statement (a block is considered a single statement). The statement may refer to the parameters defined in AParams. If the statement is an expression, the result of evaluating the expression will be returned in the NativeResult.

Multiple statements may be executed at once using the NativeExecuteOperation structure. When this overload is used, each statement is executed in succession.

Edit

Stateless Usage

When transactional control is not required, completely stateless access is enabled by the Native CLI as well. To use the stateless CLI, create an instance of the NativeStatelessCLI class defined in the Alphora.Dataphor.DAE.NativeCLI namespace. This class manages the remoting aspects of communicating with the Dataphor server, but does not manage any state associated with the connection.

The NativeStatelessCLI class provides the following methods:

Edit

Execute

NativeResult Execute(NativeSessionInfo ASessionInfo, string AStatement, NativeParam[] AParams, NativeExecutionOptions AOptions)
NativeResult[] Execute(NativeSessionInfo ASessionInfo, NativeExecuteOperation[] AOperations)
Establishes a session using the given session information and executes a D4 statement, optionally with the given parameters and execution options.

AStatement may contain only one D4 statement (a block is considered a single statement). The statement may refer to the parameters defined in AParams. If the statement is an expression, the result of evaluating the expression will be returned in the NativeResult.

Multiple statements may be executed at once using the NativeExecuteOperation structure. When this overload is used, each statement is executed in succession.

Note that the server-side implementation of the Native CLI may cache sessions for performance reasons, but the client is guaranteed that a stateless execution will happen within a controlled transaction. In other words, any transaction still open when the stateless execution returns will be committed or rolled back according to Transactional Control Protocol as defined in the Dataphor User's Guide.

ScrewTurn Wiki version 2.0.36. Some of the icons created by FamFamFam.