Datatrieve Menu Interface (DMI) Table of Contents contents page SECTION 1 History and Functional Requirements 1.1 Introduction . . . . . . . . . . . . . . . . 1-1 1.2 Interface to Datatrieve . . . . . . . . . . . . 1-1 1.3 Easily Adapted to Changing Database Requirements 1-2 SECTION 2 USER'S GUIDE 2.1 Introduction . . . . . . . . . . . . . . . . 2-1 2.2 Restrictions . . . . . . . . . . . . . . . . 2-1 2.3 Calling DMI . . . . . . . . . . . . . . . . 2-2 2.4 Using DMI . . . . . . . . . . . . . . . . 2-2 SECTION 3 PROGRAMMER'S GUIDE 3.1 Datatrieve UDK's . . . . . . . . . . . . 3-1 3.2 DMI Method of Operation . . . . . . . . . . . . 3-1 3.3 Programming DMI . . . . . . . . . . . . . . . . 3-2 3.4 Complete Syntax . . . . . . . . . . . . . . . . 3-2 3.4.1 MENU . . . . . . . . . . . . . . . . 3-2 3.4.1.1 /TITLE . . . . . . . . . . . . . . . . 3-2 3.4.1.2 /DICTIONARY . . . . . . . . . . . . . . . . 3-3 3.4.2 ITEM . . . . . . . . . . . . . . . . 3-3 3.4.2.1 /TEXT . . . . . . . . . . . . . . . . 3-3 3.4.2.2 /KEY . . . . . . . . . . . . . . . . 3-3 3.4.2.3 /MENU . . . . . . . . . . . . . . . . 3-3 3.4.2.4 /ACTION . . . . . . . . . . . . . . . . 3-3 3.5 Example . . . . . . . . . . . . . . . . 3-4 SECTION 4 BUILD INSTRUCTIONS SECTION 5 MAINTENANCE OVERVIEW DRAFT 1 (REV 0) 16 JUN 89 SECTION 1 History and Functional Requirements 1.1 INTRODUCTION In late 1988, during regular layered product updating, the CDDplus product was brought on line as ASDU. This product uses an RDB interface to access the Common Data Dictionary (CDD). One result of this upgrade was a significant increase in machine resources required to activate images that used CDDplus. ASDU uses the Datatrieve database management product which, in turn, makes use of this Common Data Dictionary. A menu-driven user interface has been in use at ASDU for several years, implemented in DCL with calls to Datatrieve. With the increased waiting time for Datatrieve activation, users would wait for up to two minutes to have their menu selection begin execution. During the implementation of the Datatrieve Forms Interface (DFI), enough expertise was gained to suggest a better, faster and more efficient method of implementing menus in Datatrieve. 1.2 INTERFACE TO DATATRIEVE There are several menu driven applications to be migrated forward, but none of them are in native Datatrieve. This will be a new capability to serve an old requirement. 1.3 EASILY ADAPTED TO CHANGING DATABASE REQUIREMENTS Since Datatrieve applications tend to be somewhat dynamic, changing over time (as do many other 4GL applications), the menu system should be readily adaptable and easy to change to meet ongoing user requirements. 1-1 SECTION 2 USER'S GUIDE 2.1 INTRODUCTION The Datatrieve Menu Interface (DMI) is a product of the ASDU Production Support Software cell and is intended to provide the members of ASDU with a capability to develop and maintain menu-driven applications in Datatrieve. DMI will allow the user to create and use a menu/sub-menu tree where each menu entry will either pass control to another menu or will pass a single pre-defined command line to Datatrieve. Here is how to use it: Programmer: 1. Create the application and procedures; 2. Create a .DMI file of directives describing the menu items and menu tree; User: 3. Enter Datatrieve; 4. DMI ; and 5. Select menu items as required. Steps 1 and 2 are covered in Section 3, the DMI Programmer's Guide. Steps 3 to 5 are here, in the DMI User's Guide. 2.2 RESTRICTIONS: Command lines passed to Datatrieve are currently restricted to a length of 80 characters. 2-1 2.3 CALLING DMI At the DTR> prompt or in a procedure, DMI is called using the following conventions: DTR> DMI "filename.ext" The filename must be a quoted string. If the file resides in the current sub-directory, then the filename may be used without quotes and an extension of .DMI will be assumed. If the filename is the same file as the last time DMI was called it will use the information already in memory and avoid having to re-read and re-interpret the directives file. DTR> DMI assumes that you wish to use the same menu as you did on the last call. Example: DEFINE PROCEDURE MENU READY PERSONNEL MODIFY DMI "DISK$USER:[ADMIN.DATABASES]PERSONNEL.DMI" END_PROCEDURE 2.4 USING DMI The menu screen is roughly divided into four sections. The top part of the screen displays the route through the menu tree taken to arrive at this menu. Right below this is the menu itself. Each line of the menu consists of a key letter followed by a description. To select a menu item, press the indicated key. No carriage return is needed. The next thing on the screen is the prompt line. This reads "Enter selection" when the menu is awaiting user input. When a selection is being processed, this line is erased. Below this is where Datatrieve I/O takes place. The command line associated with the menu selection will be echoed and all output and prompts associated with it will start here. The menu system makes no attempt to keep the screen stable. Datatrieve output or unusually long menus may cause the screen to scroll. This is normal but if you wish to read the screen before the menu is re-written all over it, you may use the NO SCROLL key. The first element of each menu is X EXIT. This means that the X key will cause the menu driver to retrace its steps backwards through the menus it took to get there in the first place. When you are in the top menu, X will return you to Datatrieve. CONTROL/C (^C) will interrupt a Datatrieve command and return control to the menu system. 2-2 SECTION 3 Programmer's Guide 3.1 DATATRIEVE UDK'S The Datatrieve Menu Interface (DMI) is implemented as a User Defined Keyword (UDK) in VAX Datatrieve. For complete information concerning the definition and use of UDKs, refer to the Datatrieve Guide to Programming and Customizing. To let you get on with the manual, I'll give you a quick overview of UDKs in Datatrieve. A UDK is implemented by writing a program that uses callable Datatrieve. The program then repeatedly gets an input line and passes it to Datatrieve, then gives Datatrieve control of everything until it reaches one of the specified stallpoints. This has the effect of looking (to the user) just like Datatrieve. To implement a UDK, the program calls the function that tells Datatrieve to look for the newly defined keyword and set the stall point mask to include the UDK stallpoint. When Datatrieve detects the new keyword, it stalls at that UDK stallpoint and returns control to the program. The program detects this stall point and then parses the rest of the line and uses callable Datatrieve to supplement its own logic to resolve the UDK. 3.2 DMI METHOD OF OPERATION Thus, the program behaves just like normal Datatrieve until it detects a UDK. At that point the custom programming takes over and retains control until the UDK's function is complete, after which control appears to return to Datatrieve. When DMI is invoked, it does the following: - all information needed to configure the menus is stored in a directives file (filename.DMI). This file must be read but first it has to be identified. - DMI is invoked from within Datatrieve. Any arguments (parameters) are processed by DMI. The first parameter is the Menu Directives File. - The DMI directive file is read and parsed. Any errors in parsing result in an error message and a return to Datatrieve. - The menu driver now has control. The user gives it single letter commands (menu choices) to which it associates a Datatrieve command line. It then passes this command line to Datatrieve and calls the DTR$DTR terminal driver. Flags are set to cause Datatrieve to return to the menu driver for its next command. 3-1 3.3 PROGRAMMING DMI The DMI directives file is like a programming language. It is read in when DMI is first called and "compiled" to control how DMI will behave. The syntax is based on the CLI parser available as part of the run time library on a VAX. Any line that is too long can be wrapped using the same convention as DCL (i.e. the last character is a minus "-" sign). The total length of all wrapped lines cannot exceed 255 characters. There can be up to 40 menus in the tree with a maximum of fifteen (15) items in each menu. Each menu and sub-menu can be associated with a particular CDD dictionary. Each menu item may link to another menu or perform a datatrieve command line of up to eighty (80) characters. A typical layout for the directive file is: MENU 1 /TITLE="MAIN MENU"/DICTIONARY=CDD$TOP.OPSO.LIB$ACCESS ITEM/TEXT="PERSONNEL"/MENU=2/KEY="P" ITEM/TEXT="LOCKS"/MENU=3/KEY="L" MENU 2 /TITLE="PERSONNEL" ITEM/TEXT="READY PERSONNEL"/KEY=R/ACTION="READY PERSONNEL SHARED" ITEM/TEXT="ADD PERSON"/KEY="A"/ACTION=":STOREP_DFI" . . . 3.4 COMPLETE SYNTAX 3.4.1 MENU number Valid menu numbers are 1 through 40. The menus do not have to appear in numeric order, but menu number 1 will always be the root menu. 3.4.1.1 /TITLE="quoted string" This will be the title of the sub-menu. It will appear at the top of the menu or in the menu stack. The title may be up to 70 characters long. 3-2 3.4.1.2 /DICTIONARY=CDD$TOP.SUB_DICTIONARY This establishes the sub-dictionary context for this sub-menu. Whenever control is passed to this sub-dictionary, a SET DICTIONARY command is passed to Datatrieve. All sub-menus below it in the tree will inherit this dictionary. Returning to the calling sub-menu will re-establish the dictionary that was previously in effect. 3.4.2 ITEM This establishes an item line in a menu. The first item is automatically an EXIT line. Items will appear in the menu in the same order as they appear in the directives file. 3.4.2.1 /TEXT="quoted string" This is the descriptive text for the menu line. It may be up to seventy (70) characters in length. It is strongly suggested that there be some mnemonic association between this description line and the KEY used to select it (i.e. E EDIT or R READY). 3.4.2.2 /KEY=character This establishes the keystroke associated with the menu line. It may only be one character in length. In case of duplicates within a menu, the one that appears first will be used, but both will be displayed. 3.4.2.3 /MENU=number This establishes a sub-menu to go to when this line is selected. There is no requirement for the number to be greater than the current menu and backward or referencing is legal. Recursive referencing, however, is disallowed. 3.4.2.4 /ACTION="quoted string" This is the command line that will be issued when the item is selected. It may be up to eighty (80) characters in length. If a more complex command is required, it may be put in a procedure and the procedure called from the menu driver. DCL commands may be executed in similar manner by using the FN$DCL function. 3-3 3.5 EXAMPLE This is an example directives file. MENU 1 /TITLE="SCRTP USER MENU"/DICTIONARY="CDD$TOP.OLAO.SCR$TP" ITEM/TEXT="READY SCRTP"/KEY=R/ACTION="READY SCRTP SHARED READ" ITEM/TEXT="READY SCRTP MODIFY"/KEY=M/ACTION="READY SCRTP MODIFY" ITEM/TEXT="FIND SCRTP ..."/KEY=F/MENU=3 ITEM/TEXT="EDIT SCRTP ..."/KEY=E/MENU=4 ITEM/TEXT="UPDATE SCRTP"/KEY=U/MENU=5 MENU 2 /TITLE="SHOW" ITEM/TEXT="BRIEF STATUS"/KEY=B - /ACTION="PRINT SCRNUM(-),TITLE(-),ORIG(-),CURSTAT(-),STATDATE(-) OF CURRENT" ITEM/TEXT="PROBLEM"/KEY=P/ACTION="PRINT P13_PROBLEM OF CURRENT" ITEM/TEXT="REQUIREMENTS DOCS"/KEY=R/ACTION="PRINT P19_REQMTS_DOCS OF CURRENT" ITEM/TEXT="USER DOCS"/KEY=U/ACTION="PRINT P20_USER_DOCS OF CURRENT" ITEM/TEXT="OPERATIONAL AMPLIFICATION"/KEY=O - /ACTION="PRINT P23_OP_AMP OF CURRENT" ITEM/TEXT="PROPOSED SOLUTION"/KEY=S/ACTION="PRINT P24_PROPOSAL OF CURRENT" ITEM/TEXT="DESIGN DOCS"/KEY=D/ACTION="PRINT P26_DESIGN_DOCS OF CURRENT" ITEM/TEXT="ENGINEERING IMPACT"/KEY=E/ACTION="PRINT P28_ENGIN_IMPACT OF CURRENT" ITEM/TEXT="ASDU COMMENTS"/KEY=A/ACTION="PRINT P29_ASDU_COMMENTS OF CURRENT" ITEM/TEXT="MAGHQ COMMENTS"/KEY=M/ACTION="PRINT P30_MAGHQ_COMMENTS OF CURRENT" ITEM/TEXT="AIRCOM COMMENTS"/KEY=C/ACTION="PRINT P31_AIRCOM_COMMENTS OF CURRENT" ITEM/TEXT="NDHQ COMMENTS"/KEY=N/ACTION="PRINT P32_NDHQ_COMMENTS OF CURRENT" MENU 3 /TITLE="FIND SCRTP" ITEM/TEXT="FIND SCRTP WITH SCRNUM="/KEY=S/ACTION="FIND SCRTP WITH SCRNUM=*" ITEM/TEXT="FIND SCRTP WITH TITLE CONTAINING "/KEY=T - /ACTION="FIND SCRTP WITH TITLE CONTAINING *" ITEM/TEXT="FIND SCRTP WITH ORIG CONTAINING "/KEY=O - /ACTION="FIND SCRTP WITH ORIG CONTAINING *" ITEM/TEXT="DISPLAY"/KEY=D/ACTION=":D" ITEM/TEXT="PRINT SPECIFIED FIELD"/KEY=P/MENU=2 ITEM/TEXT="BRIEF STATUS (LIST OF CURRENT)"/KEY=B - /ACTION="PRINT SCRNUM(-),TITLE(-),ORIG(-),CURSTAT(-),STATDATE(-) OF CURRENT" ITEM/TEXT="EDIT"/KEY=E/ACTION="DFI SCRTP" MENU 4 /TITLE="EDIT SCRTP" ITEM/TEXT="HELP"/KEY=H/ACTION=":HELP_EDIT" ITEM/TEXT="EDIT SCR (I/A BEGINS ON PAGE 4)"/KEY=E/ACTION=":SCRTPUSER_EDIT" MENU 5 /TITLE="UPDATE SCRTP (PAT GRAY ONLY)" ITEM/TEXT="READY SCRTPUSER"/KEY=R/ACTION="READY SCRTPUSER WRITE" ITEM/TEXT="LIST SCRS READY TO TRANSFER"/KEY=L - /ACTION="PRINT SKIP,SCRNUM(-),TITLE(-) OF SCRTPUSER" ITEM/TEXT="TRANSFER ONE SCR"/KEY=T/ACTION="@OLAO$UDISK:[OLAO]SCRTPUSER_TO_DB" 3-4 SECTION 4 The Datatrieve Menu Interface (DMI) is incorperated as part of the Datatrieve Forms Interface (DFI) and is built with it. See Section 4 of the DFI manual for build instructions. 4-1 SECTION 5 Datatrieve Menu Interface (DMI) - Maintenance 5-1