




DM PROGRAMMER'S DOCUMENTATION


DM VERSION 8.0A


October, 1988


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 7.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 8.0 begins the series for VMS V5.x.

Version 7.3A 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.

Additions include an interactive "tree" diagram and the capability to 
detect "fake" .DIR files.

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


Known Bugs


Structure of DM

DM consists of a lot of Fortran code, plus two Macro routines 
(File_Utilities.MAR and Read_Header.MAR).  The Macro routines are used 
to get file and image 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 DM:

To add new options to the DM 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 similar 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 7.3A or subsequent).


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.


Writerm.For Package

The subroutine package WRITETERM.FOR includes the writeterm subroutine 
(previously described), and a number of subroutines designed to save, 
reset, and restore the logical state of the terminal.

DM wants to run in the SET TERM/NOLINE_EDIT mode.  This mode is set on 
entry, restored (if necessary) for the subprocess, and restored (if 
necessary) upon exit.  However, this mode inhibits recall.  Therefore, 
each time DM gets ready to accept a command, the mode is changed so that 
command recall will work. SMG$Read_Composed_Line is used to implement 
20-line command recall.


WPE and MORE Editors

See DM_Installer_Doc for concept information.  WPE and MORE are special 
symbols, and cause the use of callable TPU.  If you need to change the 
behavior in this area, all of the logic is in ENVOKE.FOR


VMS Mail

See DM_Installer_Doc for concept information.  All of the logic is in 
the 'M' section of GOLD_KEYS.FOR


Integration with SD

The capability to string SD commands after typing DM is implemented in 
DM.COM


Tree Functions

DM_Tree implements the interface between DM and SDTree_Subs, which does 
most of the work for the tree function.

In DM_Tree, you will find DM_Print_Tree which implements printing of the 
tree.  There is a list of "DEC Standard" printers which recognize 
line-drawing character set for printing the tree.  If you have other 
printers, you may want to modify this routine.
