       PROGRAMMER'S DOCUMENTATION     DM VERSION 7.1A      Attribution   E Directory Manager was initially submitted in January 1983 by John C.  B Hayre, Texas Instruments (later with Veeco Integrated Automation,  Dallas).  D Additional extensive improvements and submissions were made by Rich A Gregory, Pharmaceutical Research Associates, Charlottesville, VA.   C The version spun-off in 1986 (Version 7.xA), which incorporated an  F All-In-1-like user interface and use of the SMG$ utilities for screen B management is by Dale E. Coy, Los Alamos National Laboratory, Los  Alamos, NM.   H Version 7.1A contains all of the features and improvements made through 5 the Rich Gregory version of Decus Spring 86A, except:   H 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.  F Additions include an interactive "tree" diagram and the capability to  detect "fake" .DIR files.   H Before making changes to DM, you should be thoroughly familiar with all 8 of the documentation (DM_USER_DOC and DM_INSTALLER_DOC).    
 Known Bugs     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  I information.  The one "odd" Fortran routine is Writeterm.For, which uses  H the QIO service to send characters to the terminal.  This is used where F the SMG$ services impede doing something, but only for "non-printing"   sequences (cursor on/off, etc.).  H DM is "called" through DM.COM, which temporarily defines a symbol DM to G point to DM.EXE, and then runs DM.  This technique is used so that the  G "%" command can exit to the main process level and then return to DM.   F Global symbols are used to preserve context and variables (see DM.FOR  and STACK.FOR).   B Initialization is accomplished by DM.FOR, and then a character is H solicited from the user (by DM.FOR).  The character is processed by one G or more "_KEYS.FOR" routines, which call subroutines to accomplish the  E desired action.  Processing returns to DM.FOR for subsequent actions.   > Complex processing is sometimes done by sending commands to a A subprocess.  The subprocess is "retained" for the duration of DM  
 execution.  B DM makes heavy use of the SMG$ services for screen management and G 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:   C 1.  Decide on a keystroke or combination to do your function.  The  H currently-used keystrokes are documented in DM.FOR, but you should test 6 DM to make sure your selection currently does nothing.  G 2.  Decide which function of DM is closest to your proposed function.   G Edit, view, FMS, and "@" are implemented in ENVOKE.FOR (and you should  I add your routine there).  Other DM functions are implemented by separate  C subroutines (you should copy this and make your own tailored mods).A  D 3.  Add an appropriate "recognizer" section to the NORMAL_KEYS.FOR, F GOLD_KEYS.FOR, or FUNCTION_KEYS.FOR subroutines, using the pattern in  the subroutine.o  F 4.  Add your Compile command to the two CPL procedures, and your Link  command to DM_Link.Com.y   5.  Compile, Link, and Test.    H The following sections contain hints and information about the internal H structure of DM.  Since DM is heavily parameterized, consult COMMON.DAT  for more information.f     Editors:  & There is support for two text editors:$ Editor - used for text editing, and - Viewer - intended to be a read-only function.   C They may be controlled on an individual-user basis, by setting the AH symbols DM$Editor and DM$Viewer.  If this is not done, then DM.FOR sets F them to default values which are defined as parameters just after the  PROGRAM statement.    	 WildCard:o  E The wildcard used by default may be controlled on an individual-user  D basis by setting the symbol DM$Wildcard.  (Note: The symbol must be H left-justified).  If this is not done, then DM.FOR sets the wildcard to  the default value of '*'.n     Indexes to the DM Display:  8 Current_Line = Display-relative position of cursor (1-n)  < TopLine is the File Reference of the Top line of the screen.  C If Cl is the symbol for the screen-relative position of the cursor h (1-22),d$      Current_Line = Cl + TopLine - 1$      Cl = Current_Line - TopLine + 1    ( Other important file/display references:  I First_Dir / Last_Dir = line numbers of the first and last .DIR files (if u+ no .DIRs, First_Dir = 0 and Last_Dir = -1)."  D First_File / Last_File = line numbers of the first and last regular 7 files (if no files, First_File = 0 and Last_File = -1).e  6 Lastline = the file reference of the last valid entry.  E FirstUsed = the file reference of the first filename (4 if the first bF file is a .DIR, 6 if there is no .DIR and the first file is a regular F file, and 7 if there 	  are no files).  Note:  If FirstUsed = 4, then $ SOMEWHERE below there are two lines:  
      (Blanks) 8      Files:  (This will be LastLine if no regular files)  C If FirstUsed = 6, then you don't have to worry about anything else o0 before LastLine (Last Line contains a file name)  I If FirstUsed = 7, then you don't have to do anything - but good code can   usually go ahead and execute.u  & The first 3 lines are always "garbage"     Misc. File Information:.=      FileLine = Position of the "Files:" line in the display. 7      NumFiles = Number of regular files in the display.a5      NumDirs  = Number of Directories in the display.s    F 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  F 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).   F ReLoad will force re-reading of the file list before the next display.  I 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.  A If Exit_Com has been set to 'zzzz', then we will quit running DM.   A If Exit_Com has been set to anything else, then Exit_Com will be r# executed and DM will be re-entered.e    3 LINE23_DIRTY, LINE24_DIRTY ,LINE23_LATER (Logicals)a  H Set .TRUE. to control cleanup of these lines when we return to the main H program (DM.FOR).  Sometimes we want to do the cleanup immediately with D FIX23 and FIX24.  However, usually we don't want to cause redundant % cleanup, so we just set one of these:t  E Line23_Later is somewhat unique:  It allows us to leave something on nD Line 23 until AFTER the execution of the next command. (not used in  Version 7.1A).     FORWARD (Logical)o  F Indicates direction of movement currently selected.  Affects the Page 4 and Line functions.  Changed by Advance/Backup, etc.     HAVE_MORE (Logical)R  E Indicates that we have the "extended" file information.  This is set  G when we load the information (GET_FILENAMES), and is reset by anything oE which can affect the validity of the information. (Copy, Purge, Most tA major functions except Print).  Anything which fouls up the data dC (without being able to predict the effect) should set Have_More to iI .FALSE. and ALSO clear out (Blank) the Attributes_Display array (because r of Info mode).  I If the effects are predictable, then the Attributes_Display array should =G be adjusted to suit (e.g., a single file delete should move everything u
 up one line).     - USEFUL THINGS IN COMMON:         (COMMON.DAT)a  . BLANKS:  Defined as an empty character string.  G ITSA_DIR:  A Logical, not kept in common, but defined for each program b0 including common.dat - used in calls to GETNAME.  ! PARAMETERS:  Lots of useful ones.f     RESTORING PARTS OF THE SCREEN:  ? Write-Screen writes lines 1-22 and, if needed (Line23_Dirty or (" Line24_Dirty) fixes lines 23 & 24.  7 Write22 unconditionally writes that part of the screen.u  A Fix23 and Fix24 unconditionally write lines 23 and 24 (and reset e Linexx_Dirty).  I WriteTerm(Command) can be used to send something to the terminal.  It is eI usually used for commands (see parameters) which are not associated with b a particular line.     MESSAGE UTILITIES:  9 Mess_Line (String) - Writes a "clean" message to Line 23.N  F Mess_Wait (String) - Writes the message to Line 23, writes a blinking G "press any key" message on Line 24.  Restores 23 & 24.  Used for error p: messages and informative messages (e.g., return from DCL).  H Mess_Get1Char (Out-String, In-Char) - Writes a string to Line 23, waits H for a single character, cleans up and returns the character.  Note: the & cursor is off while waiting for input.   Get_Answer_Line23h Get_Initial_Line24E Get_Dollar_Line24  -- all of these are used to get lengthy responses s from the user.     Set_CRT, Fix_CRT:h  G Set_CRT preserves the entering status of the terminal, and sets it the  / way we want it (22-line scroll, no wrap, etc.).w  H Fix_CRT restores the terminal to the entering status before exit to DCL.  E These routines are called once: Set_CRT on entry and Fix_CRT on exit.       Working with the DCL subprocess:  I DM_DCL.FOR has a number of subroutines for working with the subprocess.   C There are subtle differences.  See the way they are used in DM for D guidelines.L     Process Exit Handling:  G An AST handler is set up to handle most normal and abnormal exits from D DM.)     Writerm.For Packageo  G The subroutine package WRITETERM.FOR includes the writeterm subroutine  F (previously described), and a number of subroutines designed to save, 5 reset, and restore the logical state of the terminal.e  G DM wants to run in the SET TERM/NOLINE_EDIT mode.  This mode is set on dD entry, restored (if necessary) for the subprocess, and restored (if G necessary) upon exit.  However, this mode inhibits recall.  Therefore, aI each time DM gets ready to accept a command, the mode is changed so that  ' command recall will work (1 line only).i     WPE and MORE Editors  H See DM_Installer_Doc for concept information.  WPE and MORE are special G symbols, and cause the use of callable TPU.  If you need to change the x8 behavior in this area, all of the logic is in ENVOKE.FOR     VMS Mail  F See DM_Installer_Doc for concept information.  All of the logic is in   the 'M' section of GOLD_KEYS.FOR