EDBConnection Class

The EDBConnection class implements the DbConnection abstract class, providing an encapsulation of an ElevateDB local or remote session connected to a given ElevateDB database. A session acts like a "virtual user" and each new EDBConnection instance used in an application maintains its own database connections, table buffers, table/view/query result set cursors, etc. Because of the unique requirements of a multi-threaded application, ElevateDB requires that you use a separate EDBConnection component for each thread in use, thus treating each thread as a separate "virtual user".

Namespace: Elevate.ElevateDB.Data

Inherits From System.Data.Common.DbConnection

Implements ICloneable

Constructors

(<No Parameters>)
(ConnectString: String)

Properties

Property

Description

EngineVersion: String	Indicates the current version of ElevateDB being used. This property is read-only.
InTransaction: Boolean	Use the InTransaction property at run-time to determine if a transaction is currently in progress for the current connection. The InTransaction property is True if a transaction is in progress and False if a transaction is not in progress. The value of the InTransaction property cannot be changed directly. Calling the EDBConnection BeginTransaction method sets the InTransaction property to True. Calling the EDBTransaction Commit or EDBTransaction Rollback methods sets the InTransaction property to False.
ReadOnly: Boolean	Indicates whether the current connection is using read-only access only.
ServerDateTime: DateTime	Retrieves the server date/time in local time.
ServerUTCDateTime: DateTime	Retrieves the server date/time in UTC time.
ServerName: String	Retrieves the remote server name.
ServerDescription: String	Retrieves the remote server description.
RemoteParameters: EDBParameterCollection	Use the RemoteParameters property at runtime to specify the parameters to be used with the CallRemoteProcedure when calling a custom server procedure. This property can also be used to retrieve any return values from the custom server procedure (parameter Direction property of ReturnValue).

Methods

Method

Description

Clone: Object	Clones the current connection, including current contents of the ConnectionString property.
BeginTransaction(array of String): DbTransaction	Starts a restricted transaction for the current connection. Please see the Transactions topic for more information on restricted transactions.
FreeCachedStatements(DatabaseName: String)	Frees any cached SQL statements for the specified open database. If a database is not specified, then any cached SQL statements in the open databases for the connection will be freed. Please see the Buffering and Caching topic for more information on caching SQL statements.
FreeCachedProcedures(DatabaseName: String)	Frees any cached functions/procedures for the specified open database. If a database is not specified, then any cached functions/procedures in the open databases for the connection will be freed. Please see the Buffering and Caching topic for more information on caching functions/procedures.
QuotedSQLStr(Value: String): String	Formats a string constant so that it can properly used as a literal constant in an SQL statement. This method converts escapes all single quotes and converts all characters less than #32 (space) into the #<ASCII value> syntax.
DateToSQLStr(Value: DateTime): String	Converts a DateTime value to an SQL 2003 standard date constant string. All SQL and filter expressions in ElevateDB require standard date constants which use the 'yyyy-mm-dd' format.
TimeToSQLStr(Value: DateTime; MilitaryTime: Boolean): String	Converts a DateTime value to an SQL 2003 standard time constant string. All SQL and filter expressions in ElevateDB require standard time constants which use the 'hh:mm:ss.zzz am/pm' format. Use the MilitaryTime parameter to indicate whether the time should be returned in 24-hour format instead of 12-hour format with an am/pm indicator.
DateTimeToSQLStr(Value: DateTime; MilitaryTime: Boolean): String	Converts a DateTime value to an SQL 2003 standard timestamp constant string. All SQL and filter expressions in ElevateDB require standard timestamp constants which use the 'yyyy-mm-dd hh:mm:ss.zzz am/pm' format. Use the MilitaryTime parameter to indicate whether the time should be returned in 24-hour format instead of 12-hour format with an am/pm indicator.
SQLStrToDate(Value: String): DateTime	Converts a string that contains an SQL 2003 standard date constant to an actual TDateTime value. All SQL and filter expressions in ElevateDB require standard date constants which use the 'yyyy-mm-dd' format.
SQLStrToTime(Value: String): DateTime	Converts a string that contains an SQL 2003 standard time constant to an actual TDateTime value. All SQL and filter expressions in ElevateDB require standard time constants which use the 'hh:mm:ss.zzz am/pm' format.
SQLStrToDateTime(Value: String): DateTime	Converts a string that contains an SQL 2003 standard timestamp constant to an actual TDateTime value.All SQL and filter expressions in ElevateDB require standard timestamp constants which use the 'yyyy-mm-dd hh:mm:ss.zzz am/pm' format.
YearMonthIntervalToSQLStr(Value: Int32; YearMonthIntervalType: EDBYearMonthIntervalType): String	Converts a native year-month value to an SQL 2003 standard year-month interval constant string. All SQL and filter expressions in ElevateDB require standard year-month interval constants which use the general 'yyyy-mm' format. Use the YearMonthIntervalType parameter to indicate how the year-month interval should be formatted.
SQLStrToYearMonthInterval(Value: String; YearMonthIntervalType: EDBYearMonthIntervalType): Int32	Converts a string that contains an SQL 2003 standard year-month interval constant to a native year-month value. All SQL and filter expressions in ElevateDB require standard year-month interval constants which use the 'yyyy-mm' format.
DayTimeIntervalToSQLStr(Value: Int64; DayTimeIntervalType: EDBDayTimeIntervalType): String	Converts a native day-time value to an SQL 2003 standard day-time interval constant string. All SQL and filter expressions in ElevateDB require standard day-time interval constants which use the general 'dd hh:mm:ss.zzz am/pm' format. Use the DayTimeIntervalType parameter to indicate how the day-time interval should be formatted.
SQLStrToDayTimeInterval(Value: String; DayTimeIntervalType: EDBDayTimeIntervalType): Int64	Converts a string that contains an SQL 2003 standard day-time interval constant to a native day-time value. All SQL and filter expressions in ElevateDB require standard day-time interval constants which use the 'dd hh:mm:ss.zzz am/pm' format.
BooleanToSQLStr(Value: Boolean): String	Converts a Boolean value to an SQL 2003 standard boolean constant string. All SQL and filter expressions in ElevateDB require standard boolean constants, which are TRUE and FALSE (case-insensitive).
SQLStrToBoolean(Value: String): Boolean	Converts a string that contains an SQL 2003 standard boolean constant to an actual Boolean value. All SQL and filter expressions in ElevateDB require standard boolean constants, which are TRUE and FALSE (case-insensitive).
FloatToSQLStr(Value: Double): String	Converts a Double value to an SQL 2003 standard float constant string. All SQL and filter expressions in ElevateDB require standard float constants which use the period (.) as the decimal separator.
SQLStrToFloat(Value: String): Double	Converts a string that contains an SQL 2003 standard float constant to an actual Double value. All SQL and filter expressions in ElevateDB require standard float constants which use the period (.) as the decimal separator.
DecimalToSQLStr(Value: Decimal; Scale: Integer): String	Converts a Decimal value to an SQL 2003 standard decimal constant string. All SQL and filter expressions in ElevateDB require standard decimal constants which use the period (.) as the decimal separator. Use the Scale parameter to specify the number of decimal places to use for the output string, or 0 to specify that the number of decimal places in the output string will depend upon the Decimal value being converted.
SQLStrToDecimal(Value: String): Decimal	Converts a string that contains an SQL 2003 standard decimal constant to an actual Decimal value. All SQL and filter expressions in ElevateDB require standard decimal constants which use the period (.) as the decimal separator.
BinaryToSQLStr(Value: array of Byte): String	Converts a byte array value to an SQL 2003 standard binary constant string. All SQL and filter expressions in ElevateDB require standard binary constants, which are represented by the binary value in hexadecimal format.
SQLStrToBinary(Value: String): array of Byte	Converts a string that contains an SQL 2003 standard binary constant to an actual byte array value. All SQL and filter expressions in ElevateDB require standard binary constants, which are represented by the binary value in hexadecimal format.
CallRemoteProcedure(NameOfProcedure: String)	Use the CallRemoteProcedure method along with the RemoteParameters property to call a custom server procedure in a remote ElevateDB Server. The parameters that are sent along with the custom server procedure call are completely user-defined. It is up to the calling remote session to define all necessary parameters, including output or result parameters for getting data back from the custom server procedure.
CancelRemoteProcedure	Cancels any currently-executing remote procedure. This method is simply an indication that the client application wants to cancel the remote procedure. The actual server procedure may or may not send progress messages that allow for cancellation, and it may or may not actually respond to a cancellation attempt. It is entirely up to the developer of the server procedure as to how the procedure behaves in the face of a cancellation/abort attempt.

Events

Event

Description

OnLogin: EDBLoginEvent	Setting this event adds an event handler to the list of event handlers listening for the OnLogin event when the connection is first opened. The arguments for the event handler are defined in the EDBLoginEventArgs class. The OnLogin event is used to augment the login process and programmtically supply the user name and password used with the login. It can also be used to display a custom interactive login dialog whenever a connection is first opened. The OnLogin event is only triggered when either the user name (UID keyword) or password (PWD keyword) are missing from the connection string used with the connection. Please see the Connection Strings topic for more information on the UID and PWD connection string keywords.
OnTimeout: EDBTimeoutEvent	Setting this event adds an event handler to the list of event handlers listening for the OnTimeout event while the current connection is connected to an ElevateDB Server. The arguments for the event handler are defined in the EDBTimeoutEventArgs class. The OnTimeout event is used to deal with situations where the connection is waiting on a response from an ElevateDB Server, and the wait time has exceeded the timeout (TIMEOUT keyword) defined for the connection in the connection string. Setting the StayConnected property of the event arguments to False will cause the connection to disconnect from the ElevateDB Server, whereas leaving the StayConnected property of the event arguments to True will keep the connection connected to the ElevateDB Server. Please see the Connection Strings topic for more information on the TIMEOUT connection string keyword.
OnReconnect: EDBReconnectEvent	Setting this event adds an event handler to the list of event handlers listening for the OnReconnect event while the current connection is connected to an ElevateDB Server. The arguments for the event handler are defined in the EDBReconnectEventArgs class. The OnReconnect event is called whenever the connection needs to be re-established automatically due to a drop in the connection or a timeout (see OnTimeout event above). This event usually only occurs when the connection was not configured to ping the ElevateDB Server at regular intervals in the connection string (PING keyword set to False). In such a case, the ElevateDB Server may timeout the connection and disconnect it (but not remove it), resulting in the OnReconnect event being triggered the next time the connection tries to send a request to the ElevateDB Server. Please see the Connection Strings topic for more information on the PING connection string keyword.
OnSendProgress: EDBCommsProgressEvent	Setting this event adds an event handler to the list of event handlers listening for the OnSendProgress event while the current connection is connected to an ElevateDB Server. The arguments for the event handler are defined in the EDBCommsProgressEventArgs class. The OnSendProgress event is called whenever the connection needs to send a request to an ElevateDB Server, and may be called multiple times for a single request, depending upon the size of the request.
OnReceiveProgress: EDBCommsProgressEvent	Setting this event adds an event handler to the list of event handlers listening for the OnReceiveProgress event while the current connection is connected to an ElevateDB Server. The arguments for the event handler are defined in the EDBCommsProgressEventArgs class. The OnReceiveProgress event is called whenever the connection receives a response to a request from an ElevateDB Server, and may be called multiple times for a single response, depending upon the size of the response.
OnTrace: EDBTraceEvent	Setting this event adds an event handler to the list of event handlers listening for the OnTrace event while the current connection is connected to an ElevateDB Server. The arguments for the event handler are defined in the EDBTraceEventArgs class. The OnTrace event is called whenever the connection sends a request to an ElevateDB Server or receives a response to a request from an ElevateDB Server. It is useful for tracing the activity for a connection to help determine performance bottlenecks, especially over WANs (wide-area networks) like the Internet.
OnRemoteProgress: EDBProgressEvent	Setting this event adds an event handler to the list of event handlers listening for the OnRemoteProgress event during the execution of a remote server procedure. The arguments for the event handler are defined in the EDBProgressEventArgs class. The OnRemoteProgress event is used to retrieve the progress of the currently-executing procedure and, optionally, to cancel the execution of the procedure. The actual server procedure may or may not send progress messages that allow for cancellation, and it may or may not actually respond to a cancellation attempt. It is entirely up to the developer of the server procedure as to how the procedure behaves in the face of a cancellation/abort attempt.
OnRemoteStatusMessage: EDBStatusMessageEvent	Setting this event adds an event handler to the list of event handlers listening for the OnRemoteStatusMessage event during the execution of a remote server procedure. The arguments for the event handler are defined in the EDBMessageEventArgs class. The OnRemoteStatus event is used to retrieve the status of the currently-executing procedure.
OnRemoteLogMessage: EDBLogMessageEvent	Setting this event adds an event handler to the list of event handlers listening for the OnLogMessage event during the execution of a remote server procedure. The arguments for the event handler are defined in the EDBMessageEventArgs class. The OnRemoteLogMessage event is used to retrieve any log messages for the currently-executing procedure.

More Support Options

Support Forums

Frequently Asked Questions

Technical Bulletins

Technical Articles

Incident Reports

Roadmap