Phrases must be defined in the dictionary of the file that the phrase is used (or in the account's master dictionary). Line one of the phrase definition must be an H. Line two of the phrase definition contains the words that make up the phrase.
Phrases may contain any legal AQL words and constructions except commands and file names. This includes output attributes, headings, footings, selection criteria, modifiers (id-supp, dbl-spc, and so on), even explicit item-IDs. Phrases may contain other phrases. Circular phrase references are not permitted and result in an error message.
It is possible to store a collection of phrases in a file and reference them by means of a remote phrase definition. A remote phrase definition contains an R on line 1, the phrase file name on line 2, and the phrase item-ID on line 3. The item in the remote phrase file must be a phrase definition (H on line 1), and the file and item must exist. A special phrase may exist in the file dictionary (or in the account's master dictionary if the dict modifier is specified) that defines the default output attribute list when no explicit attribute names have been included for output. The item-ID of this special phrase is the at (@) sign followed by the file name (@file.name) or, optionally, just the at sign. This phrase defines the default output attribute list in the case where no output attributes are specified in the sentence. This is used in place of the conventional numbered output attributes (1,2,3...). If the @file.name phrase is missing, then the @ phrase is assumed to define the default output attributes. Using this method, dictionaries that define several data files may use different output attribute list phrases.
The @ phrase may have an H or R on line 1, in which case numbered attribute names are illegal. If line 1 is an H or R, all un-quoted words that consist of numeric digits are treated as values. That is, if a user's master dictionary contained the @ phrase with an H or R on line 1, the sentence list md 1 2 3 would list only items 1, 2, and 3, using the default output attribute list (from the @ phrase).
Alternatively, if line 1 of the @ phrase contained an HZ or RZ, numbered attribute names are allowed and are only considered as values if they do not exist as attribute definitions. For example, if a user's master dictionary contained the @ phrase with an HZ or RZ on line 1, the sentence list md 1 2 3 lists the entire master dictionary displaying attributes 1, 2, and 3 (provided that 1, 2, and 3 were attribute definitions in the master dictionary).
Example(s)
By definition a phrase may be any syntactically complete portion of an AQL sentence except commands and file names. For example, a phrase named address.list in the file client could be used to display the name and the address:
address.list 001 h 002 name street city state zip |
Once defined in the dictionary of the file client, this phrase may be used in an AQL query such as:
sort client with status = active by zip address.list lptr |
This sentence would produce a report of clients defined as active in the data file and using the phrase definition address.list as the output specification. Please note that the selection value active is not enclosed in quotation marks; another feature of the AQL pre-processor. A heading sentence could have been included in the phrase address.list, however, a more effective method may be the use of a remote phrase. For example a remote phrase file called staff could be created containing heading phrases for each staff member. To use remote phrases an R type phrase is required in the dictionary of the file client, as well as, a phrase in the data file staff.
dict of client Jim 001 R 002 staff 003 jim.jones data of staff jim.jones 001 H 002 heading "Page 'P' prepared for Jim Jones 'CTLL'" |
The AQL sentence below produces the same report as in the previous example, however, the R type phrase Jim in the dictionary of client captures the heading from the staff file:
sort client with status = active by zip jim address.list lptr |
Multiple remote phrase files may be used (that is, FROM could be a file of desired footings).
NOTE |
If a code of a is stored in the data file of client as the method of indicating a client as active, the above example requires that the sentence be entered as:
|
This is because "a" is defined in the master dictionary as a throwaway connective and the quotation marks are needed to resolve any ambiguity. This also applies to other words that are defined in the master dictionary.
Another type of phrase that may be used is the @file.name phrase. The @file.name phrase is used to define the default output attributes when no output specification are included in the AQL sentence. For example, the @file.name phrase for the file client, would be created in the dictionary of client under the name @client:
@client 001 H 002 name city phone contact |
If the list or sort commands are used to query the file client, the attributes name, city, phone, and contact are the output for sentences such as:
list client heading "page 'p' client default list 'ctl'" |
or
sort client by name with type = var |
The above sentences contain no output specification, therefore, the @client phrase is used to determine the output. If the sentence was entered as below, then the default output attributes defined in @client are ignored and the output list requested is used:
sort client by name name street city state zip |
NOTE |
If line 001 is defined as HZ or RZ (remote) then attribute numbers (for example, 1, 2, 5, 7, 8) may be used on line 002 to extract the data in those attribute-count IDs, provided that those AMC numbers are defined in the file dictionary. |
The @file.name phrase may also be just the @ sign and the file.name is assumed. Also, if a Q-pointer exists for the file, the @file.name for the actual file is used to determine the output attributes. For example, if cust is a Q-pointer to the file client, and the AQL sentence below is entered, then the @client default attribute phrase is used. In other words, @cust is not required and is not valid:
list cust |
A special use of the @file.name phrase occurs in the case when multiple data sections are defined in a dictionary. For example, if in the dictionary of our client file, a data section for active and another for inactive are defined, then a separate @file.name phrase may also be defined for each data section.
dict of client @active 001 H 002 name city phone |
dict of client @inactive 001 H 002 name city state zip |
If the client file was queried in the example below, the pre-processor uses the @active file name phrase to determine the default output attributes:
list client,active |
If the file was queried in the example below, the pre-processor uses the @inactive file name phrase to determine the default output attributes:
list client,inactive |
This example shows a mutually exclusive set of selection criteria connected with an or. Either condition evaluating to true accepts the item for processing. That is, if the name attribute begins with ar, or the city attribute begins with irv, the item is selected for output.
list entity with name "ar]" and with city "irv]" or with city "san]" and with contact "[joe]" |
This example lists those items that meet one of two criteria: a name starting with ar and with a city starting with irv, or, a city starting with san and a contact containing the string joe.
See Also