DM PROGRAMMER'S DOCUMENTATION DM VERSION 7.3A April, 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 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). 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.