Tips and Tricks (Advantage Extended Procedures)

Advantage Concepts

AEP Permissions

Data operations performed inside interface version 2 or greater Advantage Extended Procedures will not check user privileges. This allows you to hide tables or other database objects from the user(s), yet still provide controlled access to them through AEPs.

Utilize the Features of the Advantage Data Architect (ARC)

The database management features of ARC make it very easy to register and maintain Advantage Extended Procedures. It is possible to add/remove procedures through SQL statements, but if you’d prefer a visual approach, open the database in ARC and maintain your procedures this way.

TDataSet Descendant Users: Utilize the AEP template provided

Select New from the File menu. Select the Advantage tab. You will see an AEP template project. Use this template to accelerate your AEP development.

If you choose not to use the template, be sure to set the global VCL variable "IsMultiThread" to TRUE somewhere in your DLL startup code. This variable is used by the Delphi VCL memory manager to decide if it needs to be thread-safe. Because the Advantage server, which loads your DLL, is multi-threaded, this variable must be set to TRUE in order to avoid random exceptions in your AEPs.

Visual Basic .NET and Visual C# .NET Users: Utilize the AEP template provided

Select New->Project from the File menu. Select AdvantageAEP from the list of project templates.

Updating an Advantage Extended Procedure

By default, AEP containers can be updated without stopping the Advantage Database Server or disconnecting dictionary users. This is possible through the DLL Caching functionality that leaves the original AEP container available for replacement. If Advantage detects a change in the AEP container, it will automatically transition users of the old container to a copy of the new one. However, if DLL Caching is disabled and there are connected users that are using, or who have used, the AEP, they must disconnect before the AEP can be replaced. Be sure to update the Advantage Data Dictionary if exported procedures have been added or removed (see Register Your Procedure with a Data Dictionary).

 

Note to Linux users In Linux you can replace the AEP even while it is in use. Keep in mind, clients will not use the new AEP until the Advantage Database Server has unloaded the current version and re-loaded the AEP from disk. If DLL Caching is enabled (the default setting), this will happen once the Advantage Database Server detects a change in the AEP container. If DLL Caching is disabled, this will happen once all users that have called functions in the AEP have disconnected.

 

Note to .NET users The .NET environment keeps assemblies loaded in memory until the application that was using them terminates. Because the Advantage Database Server is the application using the AEPs, it must be stopped before .NET AEPs can be updated.

DOs and DON’Ts of Advantage Extended Procedures

DO

DON’T

COM and .NET AEP Notes

NetWare AEP Notes

Because AEPs run against a NetWare server scaled back to the client, any error codes returned from inside an AEP will not be included as a "native error" inside of a 7200 error code (as they will when run against other operating systems). If your code parses error strings you need to be aware of this difference when scaling to other operating systems.

If an AEP will run against a NetWare server, you must write to the __error and __output tables using navigational commands (as opposed to SQL) because the SQL processed on the server will not know about the AEP that is running locally on the client. You can change the exception handling code in the default AEP template to look similar to the code below:

except

on E : EADSDatabaseError do

begin

{* ADS-specific error, use ACE error code *}

tblError := tadstable.create(nil);

tblError.Databasename := DM1.tblInput.databasename;

tblError.TableName := '__error';

tblError.Open;

tblError.Append;

tblError.Fields[0].asinteger := e.aceerrorcode;

tblError.Fields[1].AsString := e.Message;

tblError.Post;

tblerror.Free;

end;

on E : Exception do

begin

{* other error *}

tblError := tadstable.create(nil);

tblError.Databasename := DM1.tblInput.databasename;

tblError.TableName := '__error';

tblError.Open;

tblError.Append;

tblError.Fields[1].AsString := e.Message;

tblError.Post;

tblerror.Free;

end;

 

Transaction Tips

Version 2 AEPs (which you will most likely be writing unless you are maintaining compatibility with an older version of Advantage) cannot start new transactions, or rollback or commit transactions using the connection handle that they are passed. You can, however, declare a new connection inside of your AEP and use transactions on that connection if necessary.

Keep in mind that all operations performed inside your AEP using the connection passed in are done under the context of the existing transaction (if one exists). This means if the client rolls back the transaction all operations performed by the AEP will also be rolled back.

Other AEP Tips

While a data dictionary is required to register an AEP, the tables that the AEP works on do NOT have to be bound to the data dictionary. An AEP can open and update tables that are not part of the data dictionary that the AEP belongs to.