|Command||access.phrases Definition/Access: Verbs
Applicable release versions: AP 6.1
|Category||Access: Verbs (152)|
|Description||Phrases must be defined in the dictionary of the file for which the phrase will be 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 which make up the phrase.
Phrases may contain any legal Access words and constructions except verbs and file names. This includes output attributes, headings, footings, selection criteria, modifiers (ID-SUPP, DBL-SPC, etc.), even explicit item-id's. 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) which 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 (_@filename) or, optionally, just the at-sign (_@). This phrase defines the default output attribute list in the case no output attributes are specified in the sentence. This is used in place of the conventional numbered output attributes (1,2,3...). If the _@filename phrase is missing, then the _@ phrase is assumed to define the default output attributes. Using this method, dictionaries which 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 which 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 statement "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 will only be 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 statement "LIST MD 1 2 3" would list the entire master dictionary displaying attributes 1, 2, and 3 (provided that 1, 2, and 3 were attribute definitions in the master dictionary).
By definition a phrase may be any syntactically complete portion of an Access statment except verbs and file names. For example, a phrase named ADDRESS.LIST in the file CLIENT could be used to display NAME and ADDRESS: ADDRESS.LIST 001 H 002 NAME STREET CITY STATE ZIP Once defined in the DICT of the file CLIENT this phrase may be used in an Access query such as: SORT CLIENT WITH STATUS = ACTIVE BY ZIP ADDRESS.LIST LPTR This statement would produce a report of clients defined as ACTIVE in the data file and using the phrase definition ADDRESS.LIST as the output specifications. Please note that the selection value ACTIVE is not enclosed in quote marks; another feature of the Access pre-processor. A HEADING statement 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 DICT 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'" Now the Access statement: SORT CLIENT WITH STATUS = ACTIVE BY ZIP JIM ADDRESS.LIST LPTR Would produce the same report as in the previous example, however, the 'R' type phrase 'JIM' in the DICT of CLIENT will capture the HEADING from the STAFF file. Multiple remote phrase files may be used (i.e. FROM could be a file of desired FOOTINGs). NOTE !!! : If a code of 'A' was stored in the data file of CLIENT as the method of indicating a client as ACTIVE the above example would require the statement be entered as: SORT CLIENT WITH STATUS = "A" BY ZIP JIM ADDRESS.LIST LPTR This is due to the fact that "A" is defined in the MASTER DICTIONARY as a throw away CONNECTIVE and the quote marks are needed to resolve any ambiguity. This would also apply to other words which are defined in the MD. Another type of phrase which may be used is the _@filename phrase. The _@filename phrase is used to define the default output attributes when no output specifications are included in the Access statement. For example, the _@filename phrase for the file CLIENT would be created in the DICT of CLIENT under the name _@CLIENT: _@CLIENT 001 H 002 NAME CITY PHONE CONTACT Now if the LIST or SORT verbs are used to query the file CLIENT the attributes NAME, CITY, PHONE and CONTACT will be the output for statements such as: LIST CLIENT HEADING "Page 'P' CLIENT DEFAULT LIST 'CTL'" or SORT CLIENT BY NAME WITH TYPE = VAR The above statements contain no output specifications, therefore, the _@CLIENT phrase is used to determine the output. If the statement was entered as: SORT CLIENT BY NAME NAME STREET CITY STATE ZIP Then the default output attributes defined in _@CLIENT would be ignored and the output list requested would be used. NOTE !!! : If line 001 is defined as HZ or RZ (remote) then attribute numbers (i.e. 1 2 5 7 8) may be used on line 002 to extract the data in those attribute AMC id's, provided that those AMC numbers are defined in the file dictionary. The _@filename phrase may also be just the _@ sign and the filename will be assumed. Also if Q-pointer(s) exist for the file the _@filename for the actual file will be used to determine the output attributes. For example, if CUST is a Q-pointer to the file CLIENT and the Access statement is entered: LIST CUST Then the _@CLIENT default attribute phrase would be used. In other words, _@CUST is not required and is not valid! A special use of the _@filename phrase occurs in the case when multiple data sections are defined in a dictionary. For example, if in the DICT of our CLIENT file a data section for ACTIVE and another for INACTIVE are defined then a separate _@filename phrase may also be defined for each data section. DICT of CLIENT DICT of CLIENT _@ACTIVE _@INACTIVE 001 H 001 H 002 NAME CITY PHONE 002 NAME CITY STATE ZIP Now if the CLIENT file was querried: LIST CLIENT,ACTIVE the pre-processor would use the _@ACTIVE filename phrase to determine the default output attributes. And if the file was querried: LIST CLIENT,INACTIVE the pre-processor would use the _@INACTIVE filename phrase to determine the default output attributes.