ddlAttach() - attach to another Thunderbolt database

ddlAttach() - attach to another Thunderbolt database ddlAttach() - attach to another Thunderbolt database

Prototype:

   void ddlAttach(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList);

Permitted values in OptnStr: NA

Form of ArgList:

<db-path-name> <table-name-1>[ AS <table-alias-1>] ...

Where:

<db-path-name> is a full-path database name. The <db-name> portion of the <db-path-name> is from the DATA BASE NAME Statement of the data base definition. The <db-name> portion of the <db-path-name> is also known as the <attach-handle>; the <attach-handle> must be unique across multiple instances of ddlAttach() within the primary database.

The <table-name-n> are the names of the tables to be attached. If token mapping is in effect, <table-name-n> are the internal table names.

The table names within the primary database must remain unique after the ddlAttach() is completed. For this reason, an optional <table-alias-n> parameter is defined to allow a non-ambiguous alternative table name. If token mapping is in effect, <table-alias-n> may include a schema name. Of course, the <table-alias-n> can also be used for cosmetic purposes.

Values returned in Control Structure:

Control.Ans3str[]

If token mapping is in effect, Ans3str[] contains the string that is prepended to all internal table names and column names of the attachee.

Description:

The ATTACH command allows an application to attach itself to as many as 120 additional databases besides the one that is currently open. With each attach you can specify multiple tables to attach to, with the maximum of attached tables being 40.

A database can ATTACH to either permanent or temporary tables. A database remains attached until a ddlDetach(), ddlOpen() or ddlClose() API function is executed.

A token mapped database can ATTACH only to other token mapped databases.

A non-token mapped database can ATTACH only to other non-token mapped databases.

A database cannot ATTACH to itself.

For example, suppose your database has a table named CUSTOMERS in it and you wanted to attach to the CUSTOMERS and PARTS tables in the EXAMPLE database:

                ATTACH C:\THUNDER\APPS\EXAMPLE CUSTOMERS AS CLIENTS PARTS

Note the use of the alias so that your procedures will know which customers you are talking about. After attaching, the table name CLIENTS refers to the customers that come from the EXAMPLE database.

Also note that the database name was the full-path internal name of the database, that is, the name you will find on the DATA BASE NAME IS statement in the DBD of the EXAMPLE database.

The attached databases can be resident on other servers. So from the point of view of your application the logical database open for processing at any one time can consist of tables from different physical databases distributed across multiple servers.

[Note that temporary tables that are created by the ddlCreateTempTable() function are treated as ATTACHed tables; with the ddlCreateTempTable() parameter <TempTableHandle> being the <attach-handle>. The primary difference between ddlCreateTempTable() and ddlAttach() is that, in the token mapping case, ddlCreateTempTable() does not modify the internal names as does ddlAttach().

Similarly, ddlDestroyTempTable() is functionally identical to ddlDetach().]

Commands and Attached Tables

All commands, except as noted below, perform transparently with respect to ATTACHed tables.

USERS: An attached user displays a plus (+) sign immediately following the user number in the Users Report.

The Following commands operate transparently on ATTACHed tables in table-specific form; but in global form, they operate only on the global table collection of the primary database:

                FIND
                CONSTRUCT
                DESTRUCT
                RAZE
                STRUCTURE
                UNDELETE

SHOW, VERIFY UNIQUE: The SHOW and VERIFY UNIQUE functions apply by default to the structures of the primary database. However, they can be made to apply to the attached structures by supplying the name of the attached database (without path and in parenthesis) as a qualifier. For example:
          SHOW keyname (<attach-handle>)
          VERIFY UNIQUE keyname (<attach-handle>)

SORT and RELATE: The ATTACH command discards all current open SORTs and RELATEs but raw collection content is preserved. So that you don't have to worry about this, the best bet is to get all your ATTACHing done once and early: say, as part of your Application Procedure rather than doing a lot of dynamic ATTACHing and DETACHing when collection usage abounds.

SORT, RELATE and MATCH: These functions use the TB API Cross Data Types standard for resolving conflicting data types.