access.phrases Definition/Access: Verbs

access.phrases

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).
Syntax
Options
Example
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.
Purpose
Related access.pre-processor