Icon 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
PropertyDescription
EngineVersion: StringIndicates the current version of ElevateDB being used. This property is read-only.
InTransaction: BooleanUse 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: BooleanIndicates whether the current connection is using read-only access only.
ServerDateTime: DateTimeRetrieves the server date/time in local time.
ServerUTCDateTime: DateTimeRetrieves the server date/time in UTC time.
ServerName: StringRetrieves the remote server name.
ServerDescription: StringRetrieves the remote server description.
RemoteParameters: EDBParameterCollectionUse 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
MethodDescription
Clone: ObjectClones the current connection, including current contents of the ConnectionString property.
BeginTransaction(array of String): DbTransactionStarts a restricted transaction for the current connection. Please see the Transactions topic for more information on restricted transactions.
QuotedSQLStr(Value: String): StringFormats 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): StringConverts 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): StringConverts 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): StringConverts 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): DateTimeConverts 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): DateTimeConverts 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): DateTimeConverts 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): StringConverts 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): BooleanConverts 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): StringConverts 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): DoubleConverts 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): StringConverts 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): DecimalConverts 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): StringConverts 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 ByteConverts 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.

Information 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.
CancelRemoteProcedureCancels any currently-executing remote procedure.

Information 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
EventDescription
OnLogin: EDBLoginEventSetting 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.

Information 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: EDBTimeoutEventSetting 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: EDBReconnectEventSetting 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: EDBCommsProgressEventSetting 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: EDBCommsProgressEventSetting 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: EDBTraceEventSetting 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: EDBProgressEventSetting 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.

Information 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: EDBStatusMessageEventSetting 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: EDBLogMessageEventSetting 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.
Image