.number page 1
.chapter ^*Appendices\*
.title DBAG Users' Manual 
.subtitle Appendices
.sp 2
.spr 4,1,3
.pg
	^*A. Commonly used terms in interactive commands\*
.b
	Some interactive commands can contain definitions of the scope of the
command, the data base to be acted on, "for" expressions, and instructions for
sorting the output.
.b
	For example, if you wish to see the fields NAME and BIRTH_DATE of 
all records in the data base "personnel" that have the field SEX = 'M', in
alphabetical order of the NAME, you would use the command:
.nf
.nj
.b
	"DISPLAY
.b
	 ALL                        ; SCOPE    
.b
	 DATABASE personnel         ; DATABASE 
.b
	 FOR sex = 'M'              ; FOR      
.b
	 FIELDS name birth_date     ; FIELDS  
.b
	 SORT ON name A"            ; SORT ON  (in ascending order)
.f
.j
.b
	Following is a list of ways in which the above terms can be used
in DBAG commands.
.b 2
.tp 14
	^*A.1 SCOPE \*
.b
	The specification of a SCOPE key-word is optional. More than one 
should be separated by commas:
.nf
.nj
.b
	TOP           the first record of a data base
	BOTTOM        the last recordo 
	ALL           all records in the data base
	RECORD 80     just record number 80
	80            just record number 80
	CURRENT       the record currently being examined
	NEXT 20       20 records beginning with the current one, inclusive
	You can indicate limits with a colon, ":"
	TOP:128       from the first to the 128th record, inclusive.
	^*Example:\* top, 120, 200:bottom
.f
.j
.b 2
.tp 14
	^*A.2 FOR \*
.b
	FOR expressions are made up of one or more conditions imposed on the 
fields  of a data base by .OR. or .AND. logical operators.
.b
	A logical condition relates a particular field with a value, set of
values or a scope of values for that field. Any such condition can be negated
with a .NOT. operator.
.b
	A "for" expression is calculated in the normal fashion from left to
right, with the following precedence order for the logical operators: .NOT.,
 .AND. and .OR. Parentheses may be used to force a particular evaluation.
.b
	Logical operators:
.nf
.nj
.b
	.OR.       or     (union)
.b
	.AND.      and    (intersection)
.b
	.NOT.      not    (null)
.f
.j
.b
	Arithmetical operators
.nf
.nj
.b
	=    or   .EQ.    equal
.b
	<_>       .NE.    unequal
.b
	_>        .GT.    greater than
.b
	_>=       .GE.    greater than or equal to
.b
	<        .LT.     less than
.b
	<=       .LE.     less than or equal to
.b
	:                 between two values (e. g. 10:20)
.b 2
	^*Examples\* (2, 3 and 4 are equivalent):
.b
	1) FOR sex = 'M' .OR. birth_date = 1-jan-60
.b
	2) FOR   %4 = 'M' .OR.
	         birth_date = 1-jan-60, 2-jan-60, 3-jan-60
.b
	(%4 = field no. 4)
.b
	3) FOR sex = 'M' .OR. %3 = 1-jan-60 : 3-jan-60
.b
	4) FOR   %4 = 'M' .OR.
	        ( %3 <= 3-jan-60 .and. %3 _>= 1-jan-60 )
.f
.j
.b
	There is an operator that does string searchs.
.nf
.nj
.b
	$                searches#for#strings
.f
.j
.b
	^*Example:\*#FOR#'LOUIS'$name (the records whose NAME field
contains louis,LOUIS,Louis, etc: the search is case-insensitive)
.b
	^*N.B.\* Often, a logical condition that uses a list of values
as in example 2 above, can be handled more easily if the list is located in 
a disk file and the file referred to in the command. If the three dates had been
put in a file called data.chk (one value per line) you could then use:
.b
	2a)#FOR###%4#=#'M'#.OR.#birth_date#=#@datas.chk
.b
	Note that the operator "@" was used to substitute the contents of
data.chk into the command, as a list of values separated by commas.
.b
	A variation of this technique is to use a file created by a "SAVE SEARCH
TO file" command. Actually, the "SAVE SEARCH..." command writes the record
numbers of the current search  to a file in a directly readable form.
.b
	In other words, you can select certain record numbers with a SEARCH
command and write them to a file with a SAVE. They can then be used in a 
subsequent FOR expression by using the "@" operator.
.b
	Finally, recall that if a field is indexed with a key-word (INDEX KWIC),
and a condition such as "FOR name = 'Billy', 'Bob'" is set, your search will
yield records which have either Billy or Bob in their NAME fields.
.b
	^*Example:\*
	If you have a data base with three records, in which the field NAME
has been loaded with "Billy Bob" in the first record, "Billy" in the second,
and "Bob Smith" in the third, and for which the NAME field has NOT been KWIC
indexed, the command "SEARCH ALL FOR name = 'Billy' will only find the first
record.
	If the field had been KWIC indexed, you would have found the first
and second entries. In this particular case, if you were to use the string
search operator, "$", you would get this same result. However, you would not be 
able to do a search with "$" like you can with "SEARCH ALL FOR name =
'Billy, 'Bob'" and get the three records. The only way to do this is to
index the field NAME with key-words.
.b 2
.tp 14
	^*A.3 FIELDS\*
.b
	The list of fields can contain mnemonics or
field numbers, separated by commas. The record number, which can be considered
like a "field" when being displayed, is represented by the symbol _# (cardinal)
.b
	^*Example:\*#FIELDS#code,#sex,#%2,#code
	(%2#=#field#no.#2)
.b 2
	^*A.4 SORT ON\*
.b
	A sorting list is comprised of a list of fields (mnemonics or field 
numbers), each flagged with an "A" for ascending order, or a "D" for descending
order, according to the needs of the sort.
.b
	^*Example:\* SORT#ON#name#A,#birth_date#D
(sort by field NAME in ascending order; within this list sort by field
birth_date in descending order)
.b
	Sorts are done in ascending order by default so the preceding
example could have been written as 
"SORT ON name, birth_date D".