                   PROGRAMMER'S DOCUMENTATION
                         DM VERSION 6.7A



Attribution

     Directory Manager was initially submitted in January 1983 by 
John C. Hayre, Texas Instruments (later with Veeco Integrated 
Automation, Dallas).

     Additional extensive improvements and submissions were made 
by Rich Gregory, Pharmaceutical Research Associates, 
Charlottesville, VA.

     The version spun-off in 1986 (Version 6.xA), which 
incorporated an All-In-1-like user interface and use of the SMG$ 
utilities for screen management is by Dale E. Coy, Los Alamos 
National Laboratory, Los Alamos, NM.

     Version 6.7A contains all of the features and improvements 
made through the Rich Gregory version of Decus Spring 86A, 
except:
     1.  Basic and Fortran subsystems were not implemented (this 
would be an easy change to Envoke.For, if desired).
     2.  Set File Owner was not implemented.
     3.  Some functions have slightly different implementation.

     Before making changes to DM, you should be thoroughly 
familiar with all of the documentation (DM_USER_DOC and 
DM_INSTALLER_DOC).


Known Bugs

     1.  The program crashes if you try to access a .DIR;n file 
which is not a VMS Directory File.  This is judged to be 
pathological.  A special macro subroutine would have been 
necessary to check for this case.


Structure of DM

     DM consists of a lot of Fortran code, plus one Macro routine 
(File_Utilities.MAR).  The Macro routine is used to get file 
information.  The one "odd" Fortran routine is Writeterm.For, 
which uses the QIO service to send characters to the terminal.  
This is used where the SMG$ services impede doing something, but 
only for "non-printing" sequences (cursor on/off, etc.).

     DM is "called" through DM.COM, which temporarily defines a 
symbol DM to point to DM.EXE, and then runs DM.  This technique 
is used so that the "%" command can exit to the main process 
level and then return to DM.  Global symbols are used to preserve 
context and variables (see DM.FOR and STACK.FOR).

     Initialization is accomplished by DM.FOR, and then a 
character is solicited from the user (by DM.FOR).  The character 
is processed by one or more "_KEYS.FOR" routines, which call 
subroutines to accomplish the desired action.  Processing returns 
to DM.FOR for subsequent actions.

     Complex processing is sometimes done by sending commands to 
a subprocess.  The subprocess is "retained" for the duration of 
DM execution.

     DM makes heavy use of the SMG$ services for screen 
management and keyboard processing.  The screen display data is 
kept in SMG$ displays which are assigned dynamically.


Making changes to DMM:

To add new options to the DMM shell:

     1.  Decide on a keystroke or combination to do your 
function.  The currently-used keystrokes are documented in 
DM.FOR, but you should test DM to make sure your selection 
currently does nothing.

     2.  Decide which function of DM is closest to your proposed 
function.  Edit, view, FMS, and "@" are implemented in 
ENVOKE.FOR (and you should add your routine there).  Other DM 
functions are implemented by separate subroutines (you should 
copy this and make your own tailored mods).

     3.  Add an appropriate "recognizer" section to the 
NORMAL_KEYS.FOR, GOLD_KEYS.FOR, or FUNCTION_KEYS.FOR subroutines, 
using the pattern in the subroutine.

     4.  Add your Compile command to the two CPL procedures, and 
your Link command to DM_Link.Com.

     5.  Compile, Link, and Test.


     The following sections contain hints and information about 
the internal structure of DM.  Since DM is heavily parameterized, 
consult COMMON.DAT for more information.

----------------------------------------------------------------
Editors:
     There is support for two text editors:
Editor - used for text editing, and 
Viewer - intended to be a read-only function.

     They may be controlled on an individual-user basis, by 
setting the symbols DM$Editor and DM$Viewer.  If this is not 
done, then DM.FOR sets them to default values which are defined 
as parameters just after the PROGRAM statement.

----------------------------------------------------------------- 
WildCard:
     The wildcard used by default may be controlled on an 
individual-user basis by setting the symbol DM$Wildcard.  (Note: 
The symbol must be left-justified).  If this is not done, then 
DM.FOR sets the wildcard to the default value of '*'.

----------------------------------------------------------------- 
Indexes to the DM Display:

Current_Line = Display-relative position of cursor (1-n)

TopLine is the File Reference of the Top line of the screen.

If Cl is the symbol for the screen-relative position of the 
cursor (1-22),
        Current_Line = Cl + TopLine - 1
        Cl = Current_Line - TopLine + 1

----------------------------------------------------------------- 
Other important file/display references:

     First_Dir / Last_Dir = line numbers of the first and last 
.DIR files (if no .DIRs, First_Dir = 0 and Last_Dir = -1).

     First_File / Last_File = line numbers of the first and last 
regular files (if no files, First_File = 0 and Last_File = -1).

     Lastline = the file reference of the last valid entry.

     FirstUsed = the file reference of the first filename (4 if 
the first file is a .DIR, 6 if there is no .DIR and the first 
file is a regular file, and 7 if there 	are no files).  Note:  If 
FirstUsed = 4, then SOMEWHERE below there are two lines:
     	  (Blanks)
     	  Files:        (This will be LastLine if no
     	       regular files)

     	  If FirstUsed = 6, then you don't have to worry about 
anything else before LastLine (Last Line contains a file name)

     	  If FirstUsed = 7, then you don't have to do anything - 
but good code can usually go ahead and execute.

     The first 3 lines are always "garbage"

Misc. File Information:
     FileLine = Position of the "Files:" line in the display.
     NumFiles = Number of regular files in the display.
     NumDirs  = Number of Directories in the display.

---------------------------------------------------------------- 
MENU:  (Indicator for mode which displays file size, owner, prot, 
etc.)
     Normal_Mode = 0 (Fast) (only file names are displayed).
     Info_Mode =   1 (information read as file is selected).
     More_Mode =   2 (all information read and displayed).

---------------------------------------------------------------- 
GLOBAL CONTROL: RELOAD, DO_DCL, EXIT_COM
     The Logicals    ReLoad and Do_DCL
     and Character*255 variable Exit_Com      (all in common) are 
used to communicate from subroutines to the main-line control 
program (DM.FOR).

     ReLoad will force re-reading of the file list before the 
next display.

     Do_DCL will force transfer to the exit-handling segment of 
DM.FOR, which will get to the main process DCL level by exiting 
from DM.FOR.
     If Exit_Com has been set to 'zzzz', then we will quit 
running DM.
     If Exit_Com has been set to anything else, then Exit_Com 
will be executed and DM will be re-entered.

     ....................................................

LINE23_DIRTY, LINE24_DIRTY ,LINE23_LATER (Logicals)

     Set .TRUE. to control cleanup of these lines when we return 
to the main program (DM.FOR).  Sometimes we want to do the 
cleanup immediately with FIX23 and FIX24.  However, usually we 
don't want to cause redundant cleanup, so we just set one of 
these:
     Line23_Later is somewhat unique:  It allows us to leave 
something on Line 23 until AFTER the execution of the next 
command. (not used in Version 6.7A).

     ....................................................
FORWARD (Logical)
     Indicates direction of movement currently selected.  Affects 
the Page and Line functions.  Changed by Advance/Backup, etc.

HAVE_MORE (Logical)
     Indicates that we have the "extended" file information.  
This is set when we load the information (GET_FILENAMES), and is 
reset by anything which can affect the validity of the 
information. (Copy, Purge, Most major functions except Print).  
Anything which fouls up the data (without being able to predict 
the effect) should set Have_More to .FALSE. and ALSO clear out 
(Blank) the Attributes_Display array (because of Info mode).
     If the effects are predictable, then the Attributes_Display 
array should be adjusted to suit (e.g., a single file delete 
should move everything up one line).


---------------------------------------------------------------- 
USEFUL THINGS IN COMMON:         (COMMON.DAT)

BLANKS:  Defined as an empty character string.

ITSA_DIR:  A Logical, not kept in common, but defined for each 
program including common.dat - used in calls to GETNAME.

PARAMETERS:  Lots of useful ones.

---------------------------------------------------------------- 
RESTORING PARTS OF THE SCREEN:

Write-Screen writes lines 1-22 and, if needed (Line23_Dirty or 
Line24_Dirty) fixes lines 23 & 24.

Write22 unconditionally writes that part of the screen.

Fix23 and Fix24 unconditionally write lines 23 and 24 (and reset 
Linexx_Dirty).

WriteTerm(Command) can be used to send something to the terminal.  
It is usually used for commands (see parameters) which are not 
associated with a particular line.


---------------------------------------------------------------- 
MESSAGE UTILITIES:

Mess_Line (String) - Writes a "clean" message to Line 23.

Mess_Wait (String) - Writes the message to Line 23, writes a 
blinking "press any key" message on Line 24.  Restores 23 & 24.  
Used for error messages and informative messages (e.g., return 
from DCL).

Mess_Get1Char (Out-String, In-Char) - Writes a string to Line 23, 
waits for a single character, cleans up and returns the 
character.  Note: the cursor is off while waiting for input.

Get_Answer_Line23
Get_Initial_Line24
Get_Dollar_Line24  -- all of these are used to get lengthy 
responses from the user.

---------------------------------------------------------------- 
Set_CRT, Fix_CRT:
     Set_CRT preserves the entering status of the terminal, and 
sets it the way we want it (22-line scroll, no wrap, etc.).
     Fix_CRT restores the terminal to the entering status before 
exit to DCL.
     These routines are called once: Set_CRT on entry and Fix_CRT 
on exit.

----------------------------------------------------------------
Working with the DCL subprocess:
     DM_DCL.FOR has a number of subroutines for working with the 
subprocess.  There are subtle differences.  See the way they are 
used in DM for guidelines.

----------------------------------------------------------------
Process Exit Handling:
     An AST handler is set up to handle most normal and abnormal 
exits from DM.  
----------------------------------------------------------------

