## PgAccess developer API

Starting with PgAccess 0.98 I am planning to make available a complete API for the PgAccess developers. I plan to make PgAccess not just an administrative tool, but also a tool for easy build of small applications.

That's why PgAccess 0.98 has been internally restructured, every main module of PgAccess has became a namespace (see Tcl namespaces) in order to hide the variables and internal procedures to the user. Also, all the global variables that have been used before were grouped under a single big associative array called PgAcVar (PgAccess variables) so they should not interfere with user defined global variables.

Global variables available

PgAcVar | The main global associative array that hold together various information needed by PgAccess. User should NOT alter it under any circumstances.
CurrentDB | The handler of the current opened database. Can be used for database operations as selects or command execution.
Messages | The associative array that holds the translation for the current language. Loaded from the appropriate language file from lib/languages directory
PGACCESS_HOME | Keep the system directory of PgAccess root installation

Window naming convention

Every toplevel window defined by PgAccess has the following naming convention. Every window name starts with `.pgaw` (PgAccess window) followed by a colon and a name. Example:

> `.pgaw:User , .pgaw:About , .pgaw:ImportExport`

Namespaces available

For every tab from the main database window there is a namespace defined (Tables, Queries, Views, Functions, Sequences, Reports, Forms, Scripts, Users, Schema). Every namespace has by default the following procedures:

- `new` , no parameter needed
- `open` , need a single parameter, the object name
- `design` , need a single parameter, the object name

You can use these procedures if you want to produce the same efects as clicking on the desired tab and then on the "New", "Open" or "Design" buttons from the main database window.
Example:

> `Tables::open "customers"`
> `Queries::open "Invoices received"`
> `Forms::open "Add new invoice"`

The `Tables::open` procedure accepts two optional parameters, filter and order.
Example:

> `Tables::open "phonebook" "name ~* 'joe'" "age desc"`

will open a table view window with predefined filter "name ~* 'joe'" and ordered by descending age.

There is also a special namespace called Database. Here are some procedures and functions defined for this namespace available to the user:

Name | Parameters | Type | Returns | Description
vacuum | none | procedure | nothing | vacuums the current database
getTablesList | none | function | list | returns the list of tables from the current database
executeUpdate | sqlcmd | function | integer | execute the sqlcmd command on the current database returning 1 if no errors ocurred or 0 if the command failed

Global functions available

Name | Parameters | Description
setCursor | type | Set the cursor for all PgAccess windows, type of cursor can be WAIT or CLOCK or WATCH for the hourglass , anything else (or none) to return to the normal cursor shape
parameter | msg | Shows a modal input dialog with the msg message, wait for user to enter the data and returns it as a string
showError | msg | Shows a modal dialog window with an error message