@Section(Overview)
A few utilities are provided on APM.  One of them which concern dictionary 
operations is fully discribed in the software tools section and 
IMP include files containing specifications of the routines described there
may be found in INC:DICT.

@NewPage
@IndexSecondary(Primary="DICTIONARY", Secondary="Operations")
@Section(SOFTWARE TOOLS)
@SubSection(Dictionary operations)
@Label(DICT)

Command symbols, external objects, and certain "system" objects are currently
managed using a grammar-based dictionary scheme with the properties that:
@Begin(Itemize)

Times for insertion and search operations are (roughly) linear in the length
of the name, irrespective of the number of items in the dictionary.

Search operations can succeed on leading substring matches.

Dictionary size requirement is 8 bytes per entry plus 4f bytes per character,
where the compression factor f is less than one, depending
on the extent to which leading substrings can be commoned up.
@End(Itemize)

@IndexSecondary(Primary="DICTIONARY", Secondary="Descriptors")
@Paragraph(Dictionary descriptors)
 
Dictionaries are contiguous areas of (aligned) memory, accessed through
4-longword descriptors.  These descriptors are records with the layout:

@b[%recordformat f (%integer beg,pos,lim,alt)], where
@Begin(Description, LeftMargin +6, Indent -6)
@IndexSecondary(Primary="DICTIONARY", Secondary="BEG")
BEG
@\is the address of the start of the contiguous area.

@IndexSecondary(Primary="DICTIONARY", Secondary="POS")
POS 
@\is the address of the first unused word within the contiguous area,
BEG<=POS<=LIM.  The dictionary is full when POS=LIM.

@IndexSecondary(Primary="DICTIONARY", Secondary="LIM")
LIM 
@\is the address of the end (=start+size) of the contguous area.

@IndexSecondary(Primary="DICTIONARY", Secondary="ALT")
ALT 
@\is the address of a descriptor of an alternative dictionary to be searched
when an item is not found in the original dictionary. (Or Zero)
@End(Description)

@IndexSecondary(Primary="DICTIONARY", Secondary="Operations")
@Paragraph(Dictionary operations)
 
There are three primitive operations:
@Begin(FileExample, LeftMargin +0)
DEFNAME   inserts a name into a dictionary
REFNAME   searches a dictionary for an occurrence of a name
TRANSNAME translates a name-reference (as supplied by DEFNAME or 
          REFNAME) back into a name-string.
@IndexSecondary(Primary="DICTIONARY", Secondary="TRANSNAME")
@IndexSecondary(Primary="DICTIONARY", Secondary="REFNAME")
@IndexSecondary(Primary="DICTIONARY", Secondary="DEFNAME")
@End(FileExample)

@b(Defname)
@Begin(FileExample, LeftMargin +0) 
@b[%integerfnspec(16_117c)defname(%string(255)s,%record(f)%name d,
                                             %integer size)]
@End(FileExample)                        

The name S is inserted into the dictionary described by D, additionally
reserving SIZE bytes for information to be associated with S.  The result
is the address of a SIZE-byte area within the dictionary area.
@Begin(FileExample, LeftMargin +0)

Special cases:

RESULT=0:  The dictionary is too full for S to fit.
RESULT<0:  The name S is already in the dictionary.  In this case, 
           the result is the sign-bit plus the address of the SIZE-byte 
           area originally associated with S.
@End(FileExample)
@b(Refname)
 
@b[%integerfnspec(16_1180)refname(%string(255)s,%record(f)%name d)]

Dictionary D is searched for an occurrence of name S.  The result is the
address of the area associated with S when it was defined.
@Begin(FileExample, LeftMargin +0)

Special cases:

RESULT=0:  S is not in D.
RESULT<0:  S is not in D, but T is, and S is a leading substring 
           of T.  In this case, the result is the sign bit plus 
           the address of the area associated with T when it was 
           defined.  T may be identified by performing a TRANSNAME 
           operation (qv).
@End(FileExample)

@b(Transname)
 
@b[%routinespec(16_1184)transname(%integer x,%string(255)%name s)]

X should be the address of some area associated with a dictionary entry.
The name is extracted from the dictionary and put into string S, which
should be big enough to accomodate it.

@Paragraph(Fixed-site descriptors)
 
The system knows (or will know) about four built-in dictionaries.  At present
their descriptors live at fixed sites in the Boot Processor's local memory,
though at least some of them will require to be moved into main memory at
some stage.

@IndexSecondary(Primary="DICTIONARY", Secondary="Command dictionary")
@b(Command dictionary)
 
@b[%record(f)%spec(16_3fb0)comdict]

The entries in this dictionary are the "command symbols" used by the
command interpreter.  The areas associated with each entry are 8 bytes
long and contain two longwords.  The first is a reference into the
file dictionary (qv), the second contains information relevant to the
command interpreter (flag symbols).

@IndexSecondary(Primary="DICTIONARY", Secondary="File dictionary")
@b(File dictionary)
 
@b[%record(f)%spec(16_3fc0)fildict]

The entries in this dictionary are filenames, which the command interpreter
has associated with command symbols.  The associated areas are 8 bytes long.
When the file has not yet been loaded, the two longwords are both zero,
otherwise the first longword is the address of the start of the file, the
second longword is the address of the end (start+size) of the file.

@IndexSecondary(Primary="DICTIONARY", Secondary="External dictionary")
@b(External dictionary)
@Begin(FileExample, LeftMargin +0)
@b[%record(f)%spec(16_3fd0)extdict      <Not actually used yet>]
@End(FileExample)
This dictionary is  used by compiled programs to establish
linkage of external objects (procedures, variables, ...?).  The associated
area is 8 (? cross-ref with DEFEXT) bytes long.  The first longword is the
address of the object, the second is the address of type information relevant
to that object.

@IndexSecondary(Primary="DICTIONARY", Secondary="System dictionary")
@b(System dictionary)
@Begin(FileExample, LeftMargin +0)
@b[%record(f)%spec(16_3fe0)sysdict      <Not actually used yet>]
@End(FileExample)
This dictionary will contain entries relevant to the multi-process system,
such as process names, semaphore names, server queue names and the like,
if and when it is desirable for these to be described other than through the
external linkage mechanism.

@Paragraph(Dictionary Display Commands)
@IndexSecondary(Primary="DICTIONARY", Secondary="DICTS")

@b(DICTS  : Dump contents of one or more Dictionaries)

Parameters:
@Begin(FileExample)
-System  : Display system dictionary
-Command : Display command symbol dictionary
-External: Display External dictionary
-File    : Display File dictionary
-Memory  : Display memory bounds
@IndexSecondary(Primary="DICTIONARY", Secondary="-Memory")
@IndexSecondary(Primary="DICTIONARY", Secondary="-File")
@IndexSecondary(Primary="DICTIONARY", Secondary="-External")
@IndexSecondary(Primary="DICTIONARY", Secondary="-Command")
@IndexSecondary(Primary="DICTIONARY", Secondary="-System")
@End(FileExample)
Options are inclusive.
@Begin(FileExample, LeftMargin +0)
@IndexSecondary(Primary="DICTIONARY", Secondary="-Output")
-Output  : File to which output is to be sent (Default console)
@End(FileExample)
Parameters are handled by PAM


@b(SHOWSYM: Show symbol translation)

Parameter: Symbol to be translated

Additional parameters:
@Begin(FileExample, LeftMargin +0)
-s:  Look symbol up in system dictionary
-c:  Look symbol up in command symbol dictionary (default)
-e:  Look symbol up in external dictionary
-f:  Look symbol up in file dictionary
@IndexSecondary(Primary="DICTIONARY", Secondary="-f")
@IndexSecondary(Primary="DICTIONARY", Secondary="-e")
@IndexSecondary(Primary="DICTIONARY", Secondary="-c")
@IndexSecondary(Primary="DICTIONARY", Secondary="-s")
@End(FileExample)
Options are exclusive.
                                                                                                                                                                                                                                                                                                                                     