PmaAdo - Deatiled object description

See: the PmaAdo object, PmaAdo - Practical examples

The PmaAdo object contains a single database connection (ADO Connection). The database connection is executed by the DbOpen method. The following actions can then be executed over the database:

1) SQL statements not returning data in the form of the AdoRecordset object: by the DbExecute method, for example INSERT, UPDATE, DELETE, CREATE TABLE, etc.

2) SQL statements returning data in the form of the AdoRecordset object: by the RsOpen method, for example SELECT, etc.

Each query that creates the AdoRecordset object (RsOpen or DbExecute) can have unigue text identifier (sId), that is used to store the result of the query by the PmaAdo object. If the unique identifier is used, then the corresponding AdoRecordset object can be obtained by the RsGet method, or it can be closed by the RsClose method. The PmaAdo object may simultaneously contain multiple SQL query results in the form of AdoRecordset objects.

Wrapper object:
The way of implementing methods and properties (e.g. AdoRecordset.Update) for all ADO objects (e.g. AdoRecordset, AdoField, AdoRecord) causes instant halt of the script on any error(s) in the script that called the method. This is unfavourable behavior. Therefore the PROMOTIC wrapps automatically each ADO object with own security layer (the Wrapper object). The Wrapper allows to call all properties and methods of any object that is inside the Wrapper. The Wrapper catches possible errors in the original object and remembers the code of the last error. It prevents the halt of the script caused by error that may occure by calling the method ADO object. The object wrapped in the security layer Wrapper object is best observed as the original object because the layer allows to access all properties and methods of the wrapped object. It also adds new properties used for testing the results of last operation with the object (success/failure).
If any method or property of the original object returns another object, then the Wrapper of the original objects wrapps the reffered object with a new Wrapper object. This way it is secured that all ADO objects in the hierarchy are wrapped with the security layer automatically.

Properties added by the Wrapper object to the methods and properties ADO object (e.g. AdoRecordset, AdoField):

- Pm_LastErr - Returns the numeric error code of the last executed method (property) of the object (the 0 value means no error).

- Pm_LastTextErr - Returns the text error description of the last executed method (property) of the object.

Accordingly, it is possible to read the result of the last operation for DbExecute and RsOpen by the LastErr and LastTextErr properties directly in the PmaAdo object.
Reading the result of the last operation (over the object PmaAdo, AdoRecordset, AdoField) is handy if there is no way to estimate the result of the operation and while the method itself does not return the result of the operation. For example DbExecute, RsOpen, AdoRecordset.Update. See Example.

The ADO Record object:
Depending on the specific ADO Provider it is possible, that a single row result of the SQL query will not be returned in the form of the AdoRecordset object containing a single record, but in the form of the AdoRecord object (represents the single row). However, this is not typical of the most commonly used ADO Providers. The AdoRecord object is usually returned by explicit operations, when the specific AdoRecord is returned from the existing AdoRecordset object. The AdoRecord object consists of multiple AdoField objects, the same way as the AdoRecordset object. The difference is that the methods for moving the current record position are not supported (e.g. MoveFirst).
In order to keep the documentation PROMOTIC simple, it will be referred only to the commonly returned AdoRecordset object, although in some special cases the system may also return the AdoRecord object.

Asynchronous programming:
Some operations over the database can also be executed asynchronously.
Caution: Asynchronous programming frequently causes comlications and therefore it is recommended to use the synchronous attitude.
If there is a chance, that the synchronous requests may take too much time or there is a possibility of timeout, then it is better to execute all operations in the worker thread (see the PmaSequencer object").

For additional information regarding the ADO technology see http://msdn.microsoft.com/en-us/library/ms679836(v=VS.85).aspx, http://www.w3schools.com/asp/ado_intro.asp or http://www.connectionstrings.com.