The Application Interface The Application Interface
The Application Interface (AI) establishes a particular "view" of the data base. The view can encompass the entire data base or be very restrictive. There can be many AIs for a given data base.
Before you can create an AI, the data base that it is to plug into must already exist. Before you can OPEN
a data base, an AI must exist.
The AI definition is entered with the Text Editor and saved as a text file. After the source AI is saved, it must be "compiled." The compile process analyses the AI text and creates the files that house the AI and it's associated application catalog (the .PI and .PRS files).
A General Interface Versus the Application Interface
A default AI called the General Interface (GI) is produced automatically at DBD compile time, unless you suppress it by use of the SUPPRESS GI clause. The GI allows access to the entire data base, and does the following two things:
1. Provides an "Interface Name" that is used to OPEN the data base.
2. Provides an application Catalog associated with the GI.
An application Catalog (the .PRS file) contains all of the Procedure, Menu, Screen, and Report definitions that are your application.
A custom AI does five things:
1. Provides an "Interface Name" that is used to OPEN the data base.
2. Provides an application Catalog associated with the specific AI.
3. Provides varying degrees of access to the data base.
4. Provides the means to specify alternate collection names.
5. Provides a place to create Record Descriptions (RD). Record Descriptions
are required by the LOAD and UNLOAD commands to import or export data.
Requirements of the AI
(required) 1. The name of the data base that this AI is to plug into.
(optional) 2. The list of Tables that can be accessed with this AI.
(optional) 3. The EXTRA COLLECTIONS clause.
(optional) 4. As many Record Descriptions (RDs) as you need.
The AI syntax skeleton looks like:
DATA BASE NAME IS data-base-name
[DATA GROUPS ARE tablename ... tablename]
[EXTRA COLLECTIONS ARE collection-name ... collection-name]
[RD rdname [file-type]
data-definition-statement
: (as many RDs as you require)
data-definition-statement]
The following hyperlinks take you to the indicated discussions, the syntax rules and discussion of each statement of the AI occurs below.
When entering text for the AI, the following rules apply:
* At least one space between words
* One statement per line
* No periods at the end of the line
* Blank lines, indentations, and extra spacing are allowed
* Upper or lower case allowed, AIs are case insensitive
* The @ sign indicates that everything after it is a comment, all
text after an @ sign is ignored by the AI compile process.
The DATA BASE NAME IS statement
Syntax:
DATA BASE NAME IS data-base-name
This must be the first statement in any AI text file. The "data-base-name"
can be a full path name, but after the path part is done and you get to the actual name part, the name you use must agree with the name you used in the Data Base Definition's DATA BASE NAME IS statement.
The data base name provides the link between the data base and the AI. It is how the AI knows which data base it is plugging in to.
When you supply a full path name you can use the UNC (Universal Naming Convention). This prevents problems in installations where different workstations have different drive letter mappings.
The DATA GROUPS ARE statement
Syntax:
DATA GROUPS ARE tablename ... tablename
This is an optional statement. If you omit it, then the AI is plugged into the entire data base, that is, any user that OPENs the data base with this AI can see all of the Tables of the data base.
If you include a DATA GROUPS ARE statement, then the user of this AI sees only the Tables mentioned in the list of table names that you supplied with this statement.
The tablename list is a blank delimited list, that is, do not use commas between tablenames. You can use the hyphen (dash) to continue the tablename list onto more than one line. For example:
DATA GROUPS ARE CUSTOMERS SALES INVENTORY PARTS -
ASSEMBLIES ORDERS VENDORS
If you were to bring in a temporary worker to enter CUSTOMERS records for a day, it is perfectly legitimate to provide that worker with an AI that only sees the CUSTOMERS table in the data base. This provides protection for both you and that worker.
The EXTRA COLLECTIONS statement
Syntax:
EXTRA COLLECTIONS ARE collection-name ... collection-name
This is an optional statement used to delete default collection
names or to add new collection names.
The default collection names are A, B, C, D, E, U and V. To delete one of these, just put a minus sign in front of the name. To add collection names, add it to this list. For example:
EXTRA COLLECTIONS ARE -E SHIPS
This statement removes E as a legitimate collection name and adds the word SHIPS as a legitimate collection name. Note that the list of collections is a blank delimited list, so do not use commas to separate collection names. Now any user that plugs into the data base with this AI can do queries as follows:
FIND SHIPS WHERE something-is-true
SHIPS will be recognized as a collection name.
Do not delete the U or V collections as they are used by the Data Menu
.
Record Descriptions
A Record Description (RD) is used to provide the format of an external file so that it can be imported (read) into the data base, or exported (written) from the data base.
Data definition statements are discussed in the Data Base Definition
section, lots of examples can be found in "File Import and Export
," and specific data types are discussed further in "Data Types and Rules for Data Transfer
." So here, on the theory that a picture is worth a thousand words, we present just one example:
RD CMF
name x(30) @ RDs provide the "data picture" of the data
cust# x(6) @ records in an external file. An RD must exist
filler x(15) @ for the LOAD and UNLOAD commands to work.
street x(25) @ You may have as many RDs as you like.
city x(15) @
state x(2) @ Assume that you have an ASCII file named
zip x(9) @ CUST.MAS, and that the RD named CMF
filler x(20) @ accurately describes the records of this file.
discount x(7) @ Assume you want to LOAD this file into the
status x(3) @ CUSTOMERS table in the data base. The LOAD
age n(3) @ command to accomplish it would be:
filler x(12) @
@ LOAD A CUSTOMERS CMF CUST.MAS
RD ....... @ | | |
: @ tablename rdname filename
Lets take a closer look at the relatioship between the RD in the AI and the table description in the data base:
RD CMF TD CUSTOMERS
name x(30) cust# x(6) key
cust# x(6) name x(20) key
filler x(15) street x(20)
street x(25) city x(13) key
city x(15) state x(2) key
state x(2) zip x(5) key
zip x(9) status x(2) key
filler x(20) age n(3) key
discount x(7) discount n(1.3)
status x(3)
age n(3)
filler x(12)
The RD is describing the records in the external file. The rule for data transfer is where names match, data moves. Differences in field size, type, and order are handled automatically when the data transfers.
Note that in this example there is data in the external records that we chose to leave behind (not to load in) by accounting for the space that it occupied with the fieldname "filler."
