VPW Version 4.0 The VAX Professional Workstation User's Guide by James G. Downward KMS Fusion, Inc. Ann Arbor, Mich. 48104 December 12, 1984 1 CHAPTER 1 INTRODUCTION TO THE VAX PROFESSIONAL WORKSTATION 1.1 Introduction The VAX Professional Workstation (VPW) is a collection of programs and procedures designed to provide an integrated workstation environment for the staff at KMS Fusion's research laboratories(1). This manual documents the various features of Version 4.0 of the VAX Professional Workstation and provides an introduction to using them. While not providing as high a level of integration as Digital's All-In-One (TM) office automation system, VPW provides many of the same features at a moderate CPU overhead, and even lower software cost. Since VPW was first introduced at KMS over a year ago, numerous capabilities have been added including support for Office Graphic Workstations, editing "windows", and additional desk utilities and services. 1.2 Implementation Considerations KMS uses VAXes for program development work, scientific data analysis and modeling, image analysis, word processing, and various standard business applications. The users of our systems have a wide range of computer skills from novice to systems programmer. A major consideration in implementing VPW was to allow even casual users to productively use our VAX network and to present our technical staff with a simple, consistant user interface, providing a "Personal Computer" like environment. A basic design philosophy of the system is that the user should have to type the least amount of keyboard input and make the fewest decissions necessary to get the job done. Where possible, default values which require the user to simply press carriage return are employed. In general, designing procedures and (1) Work supported by the U.S. Department of Energy under Contract No. DE-AC08-82DP40152. 1-1 INTRODUCTION TO THE VAX PROFESSIONAL WORKSTATION applications for a workstation environment requires sensitivity to the needs and mental state of the end user. The initial design goals were for VPW to be; 1. User-friendly. Computer jargon should be minimized. If an error occurs, the error should be simply explained and the system should provide a means for the user to recover from it. VMS error messages should never occur as they are confusing to the casual user. 2. Easy to learn and consistent. By providing a consistent user interface for all procedures and images, experience gained in learning how to use a given VPW service is easily transfered to new services. 3. Self-Teaching. Experience shows it is far faster to add new functionality than it is to document the new functionality by publishing an updated user manual. Moreover, busy staff may avoid reading existing documentation/manuals prior to trying to use some feature for the first time. Consequently, sufficient HELP must must be available from within VPW so that with minimal training the system becomes self teaching. 4. Easily tailorable to individual user needs. Both personal workstations and user defined functions must be supported. 5. Easily expandable to provide new functionality. In a research environment, needs change rapidly and the system must be able to respond to these needs. 6. The system should be menu-driven but provide methods for bypassing excessive menu displays. To meet these goals, VPW was implemented as a shell of elaborate, modular command procedures integrating a large number of VPW and application specific VMS images. Version 4.0 of VPW continued this effort by; 1. Increasing modularity of command procedures to simplify support, allow new services to be added more easily, and decrease menu to menu switching time. 2. Providing more extensive on-line HELP. 3. Providing window services from any menu, many application specific images, and from the editor. 4. Providing support for a wider variety of terminals including, VT125's, VT220's, VT240's, and a foreign word processing system which "almost" emulates a VT100. 1-2 INTRODUCTION TO THE VAX PROFESSIONAL WORKSTATION 5. Providing a framework for integrating a growing range of graphic services for the technical staff. The VAX Professional Workstation currently provides simple, menu driven access to: o The KMS Data Bases o Desk Management Services o Individual Personal Workstations o Data analysis capabilities o Office Graphic workstations o Computer Aided Instruction o Many VAX utilities The menus and the various functions which may be performed from them will be discussed in subsequent chapters. 1.3 Assumptions The VAX Professional Workstation is designed to work primarily on VT100 (ANSI mode) compatible terminals with the advanced video option. VPW will not work on hard copy terminals. Since VPW is menu-driven, the terminal baud rate should be at least 2400 baud. During the system wide login procedure, TERM.COM is invoked to identify the terminal type for later use by VPW. Because the users terminal must be polled to discover its type, typeahead is disabled during logon until the "$" prompt first appears. A limited number of functions may be done from NBI Word Processing workstations in VT100 emulation mode or from Tektronix 4014 terminals. This NBI support is provided mainly so that documents can be transfered between the VAX and the NBI word processor. Tektronix 4014 support is provided so those terminals can be used as graphic workstations. It is assumed that each VAX user accessing the VAX Professional workstation has a separate, unique account/directory. This assumption is necessary because from time to time the VAX Professional Workstation creates temporary files. These files would not be unique if multiple users were using VPW on the same account. 1-3 CHAPTER 2 COMMON VPW SUPORT SERVICES 2.1 Introduction Supporting VPW's infrastructure are a wide range of modular service procedures and images which handle menus, user prompting, terminal recognition, error display and recovery, help displays, terminal independent text display and screen erasure, menu bypassing, broadcast services, window editing (with clip boards), mail and appointment notification, compressed directory and library index displays, privileged command procedures, and exit cleanup. For the user, this means that VPW's behavior is predictable as on goes from one function to another. Modularity also allows new functionality to be added very easily to VPW and provides the framework by which many VMS services, and applications are integrated into a simple-to-use system. 2.2 Menu Displays The VAX Professional Workstation's menus have a standard, self-explanatory format. Keywords appear on the left with the minimum acceptable abbreviation displayed in bold letters. On the right of each keyword is a description of the function to be performed. At the bottom of each menu, the user is prompted for a "Choice:". If an invalid choice is entered, a warning message is displayed at the user's terminal, and the user is again prompted for a choice. Direct cursor addressing is used by all tasks and command procedures to provide a consistent, form-like display and to minimize the amount of I/O to the user's terminal screen. Standardized code blocks exist to accept user input, validate it, and dispatch commands or activate functions as appropriate. A command is valid if it either matches the highlighted 'n' character sequence, or if it translates into a valid DCL Foreign command. However, excess input is not flagged as an error as long as it can be interpreted correctly. If a command is not recognized, an error message appears at the bottom of the screen explaining that the command is not valid and requesting the user to try again. 2-1 COMMON VPW SUPORT SERVICES Control-Y is always allowed as an immediate exit from the current menu except when so doing would leave the users process or a database in an undeterminate state. Control-Z on an input is taken to mean that the user wants to quit what is currently being done and to return to the previous logical function. Because getting mail notification invariably happens at the most inconveneint times, a MAIL option is available from all primary and secondary menus even though it may not be displayed as an explict selection. 2.3 User Prompting The VMS INQUIRE command is far too limited in its ability to input terminal data to be used within the VPW command procedures. A seperate image, ASK, is used to prompt the user (or terminal) for input. ASK can prompt and input standard text or escape sequences, force defaults if no data is input, force upper case, distinguish between a null input and Control-Z, or timeout if there is no input within a specified time period. 2.4 Terminal Recognition VPW must know the type of terminal it is running on. Allowed terminals are VT100 terminals with the advanced graphic board, VT100 "emulators", VT200 series terminals, and Tektronix 4014 terminals. When a user logs on the system, the type of terminal the user is using is identified either from the permanently set terminal characteristics for foreign and hardcopy terminals, or by a procedure (TERM.COM) which runs as part of the system-wide login procedure and which querries the terminal to discover its terminal type. Depending on the type of terminal, the global symbols TERMINAL_TYPE and TERMINAL_FLAVOR are defined. TERMINAL_TYPE defines whether or not the terminal supports standard VT100 escape sequences and Terminal_Flavor allows the different "flavors" of VT100 compatible terminals (ie. VT220, VT240, VT125, or attached word processor in VT100 emulation mode) to be identified. In addition to DEC VTxxx terminals, VPW also supports, to a limited extent, Tektronix 4014 terminals and non-DEC word processing workstations having a VT100 emulation mode. At present only support for NBI word processing systems exists. 2-2 COMMON VPW SUPORT SERVICES 2.5 Terminal Control Services Where possible, many VPW internal functions support a degree of terminal independent terminal control and cursor addressing. For example the PAGE function, erases the screen (or ejects page) on any of the terminals supported on our VAX. Likewise, cursor positioning and control symbols are established when VPW first starts up. This allows terminal independent command procedures to be developed in a very straight forward manner. 2.6 Error Display And Recovery Extreme care is taken to avoid situations which will result in DCL error messages appearing on the user's terminal. If a given input could lead to an error, the input is first checked for reasonableness and then explicit DCL error trapping is used to allow the user to be reprompted in the event an error occurs. The same philosophy is followed both for command procedures and images. If any action could lead to an error message, it is trapped. When serious problems occur, the user is told in English what the problem is, and what to do. The display of error messages relating to non-problems (deleting a non-existant file for example) should never occur. If a user observes strange error messages appearing while using VPW, more than likely an error exists somewhere in one of the VPW service modules which should be looked into. To insure that such errors get fixed, the user noticing the problem should submit a VAX Problem Report (VPR). Use of VPR is described later in this manual. 2.7 Menu Bypassing Two forms of menu bypassing are provided to fill two somewhat different needs. The first need is to be able to drop into an application menu without ever displaying the main menu and to also exit from the that menu without returning to the main menu. This can be accomplished in two ways. First, the input line to the VPW DCL command is parsed to extract a command line (if any). The command line (if any) is then taken as the "Choice:" input instead of prompting the user. For example, if VPW is started up with the command $ VPW [Menu_Keyletters] (where the Menu_Keyletters is optional), and if the Menu_Keyletters correspond to a valid "Choice:", VPW will bypass the primary menu 2-3 COMMON VPW SUPORT SERVICES display and drop the user into the requested secondary menu. For example, the DCL command VPW DESK will invoke the Desk Management Menu and the command VPW PERSONAL will activate the Personal Workstation menu without displaying the main menu. After the specifically activated menu function has been completed, VPW immediately exits rather than return to displaying the main menu. If the Menu_Keyletters entered does not correspond to a valid menu selection, VPW will exit immediately. As an alternate method of bypassing the main menu, on can also activate each menu as a foreign command. In this event, each menu will appear and on exit, there will be no return to the main menu. This method can also be used within VPW to jump from menu to menu without traversing the built in menu tree structure. Since each command is checked to see if it is a valid Foreign command, and since most menus can be activated as a Foreign command, typing the menu-activating Foreign command to the "Choice:" prompt will result in the selected menu being activated. Menu activation Foreign Commands include; DATABASE - Invoke the KMS Data Base menu DESK - Invoke the VPW Desk Management menu GRFmaster - Invoke the Graphics Work Station menu INSTRUCT - Invoke the VAX Instructor menu RESEARCH - Invoke the Research Assistant menu TOOLBOX - Invoke the VAX Tool Box menu TVGmaker - Invoke the TVGmaker menu VPR - Invoke the VAX Problem Report menu VPW - Invoke the VPW main menu WP - Invoke the VAX Document Preparation System menu 2.8 HELP Displays VMS HELP is used to provide help for the user at the menu level. Pressing PF2 displays help appropriate to the the menu PF2 currently being used. After displaying primary help information, available additional topics are displayed and the user is prompted for additional requests. The user may likewise access HELP information from within a number of the VPW specific images. For example both the Notebook probram and the Desk Top Calendar program provide help which is context sensitive to the function currently being performed by the user. 2-4 COMMON VPW SUPORT SERVICES 2.9 Window Services There is nothing more frustrating when using a computer workstation than being interrupted in the middle of doing something. There you are after answering all the menu questions, and waiting (and waiting) for the EDT to read in your 500 block file, finally ready to do some constructive work. Needless to say, fate immediately queues up an interruption. Typical situations include, "Beep","New mail from XYZABC" or "Beep, Beep", "XYZABC is phoning you on ZEUS::", or "Pardon me, but I don't understand this error message. What's DCL?". VPW tries to minimize the frustration caused by such interruptions. So that it is not as often necessary to loose the context of what one is doing to handle an interruption, VPW provides a new command window from any menu, the editor, or from a number of the utility tasks. When one presses the PF4 (or F20 on the LK201 keyboard) key, the current display vanishes, and a window banner appears followed by a DCL prompt. For example, you are in the editor, and "Beep" you are notified of incoming mail. Press the window key (GOLD V on VT100s and F20 on LK201 keyboards) and presto, you have a new DCL window. Then you read the mail and realize you have to dash off a quick memo in answer to the problem presented you. No problem. Enter VPW again and access the document preparation menu, create the memo, transmit it to the secretary, and exit. At this point, the window banner returns to remind you that you are in your alternate window and since you have completed work on the memo, you exit it (Control-Z) and immediately return to editing your original document. The window services are provided by a customized version of EDT V3.0 (VPWEDIT) and window procedures used both by EDT and VPW command procedures. As a related service, VPWEDIT also supports a clipboard in which the output of any single-shot DCL command can be pasted into a clipboard buffer for use. 2.9.1 Establishing VPWEDIT As The Default Editor On the KMS VAX, the default editor is VPWEDIT which is a version of DEC's standard EDT V3.0. It supports windows. If for some reason your default editor gets changed back to standard EDT, VPWEDIT can easily be restored as your default editor at any time by issuing the command $ DEFINE SYS$VPWFILES:VPWEDIT EDT (local) or $ DEFINE/SYSTEM SYS$VPWFILES:VPWEDIT EDT (system) Once this is done, VPWEDIT will become the default editor for your 2-5 COMMON VPW SUPORT SERVICES process (or all users). To activate its new features (windows, clipboards), a number of keypad definitions must be made. These definitions should be placed in SYS$SHARE:EDTSYS.EDT. The relevent definitions include; DEFINE KEY GOLD H AS "EXT SET HELP HELPLIB ;- HELP ?*'System HELP Topic: '; SET HELP EDTHELP." DEFINE KEY GOLD V AS "XLATEVPW>^Z." DEFINE KEY FUNCTION 33 AS "EXT SET HELP HELPLIB ;- HELP ?*'System HELP Topic: ';- SET HELP EDTHELP." DEFINE KEY FUNCTION 34 AS "XLATEVPW>^Z." DEFINE KEY GOLD CONTROL D AS "XLATE?*'DCL to CLIPBOARD command: '^Z." Note the two wrapped lines. For the real EDTSYS.EDT file, the "-" should be missing and the wrapped line, one continuous line. With these keypad definitions; GOLD H Access VMS system HELP from within EDT HELP Access VMS system HELP from within EDT GOLD Control D Issue a DCL command the output of which will be included into the Clipboard buffer. F20 Start up a window (VT2xx). GOLD Control-V Start up a window (VT1xx). 2.9.2 VPW Window Display Format The window display for a VPW window is the same whether or not it is activated from within VPW or the editor. At the top of the display is a header showing the current process name along with instructions on how to exit from the window. The top three lines of the display are reserved for this header. The bottom of the display acts as a normal VT100 terminal from which one can issue commands, edit a program, or even invoke a new VPW function. Each time a commmand is entered to the "$" prompt, the command is executed and the I/O for the command is restricted to the lower 21 lines of the display window. In order to maintain the window no matter what the user does, it is necessary to read the cursor position before reading each command. Consequently, typeahead does not work quite normally in "window" mode. Window mode typeahead is covered in the next section. The VPW Notebook Program which handles phonelists, the drawing file, etc., also has limited functionality windows which bears mention. Again the PF4 key activates the "Command Screen". However, until a substantial rewrite of Notebook is done, full functionality (and full screen) windows (which will permit video editing) will not be available. 2-6 COMMON VPW SUPORT SERVICES 2.9.3 Window Typeahead Because the window procedure must query the terminal to discover the current cursor location, it is difficult, but barely possible, to keep the user input and the terminal input separate if the user is typing ahead. To do so requires the window procedures to extract the cursor position output from its current input line, store any excess (the user's input) in an internal typeahead buffer, and finally merge the internal typeahead buffer with the typeahead buffer received from the terminal driver. The window procedures attempt to do this and typeahead seems to work almost normally at least one command level deep(and probably more). However, nothing is for free. Additional code had to be added to the window procedures which may decrease response time slightly. Also once input has been entered into the procedures typeahead buffer (but a RETURN has not yet been pressed) a Control-U will not cancel the input. Now this is somewhat confusing (sorry folks) because if one is entering data at the prompt, a Control-U will cancel the input (it is still in the Terminal Drivers typeahead buffer, not the procedures). However, if one has issued a command, and while it is executing, enters a new command, that new command will get placed into the window procedure's typeahead buffer and be displayed on the terminal following the next prompt. This text can not be canceled with Control-U. To flush the procedure typeahead buffer, enter Control-Y to abort the command or press the REMOVE key on the VT2xx terminal keyboards. Either action will flush the buffer and you will be prompted for a new command. 2.9.4 Editing Windows By themselves, the minor improvements in window handling by VPW would not be significant. However, users can access full function windows from within our standard EDT editor by using VPWEDIT. This means that while editing, one may temporarily halt the editing session in progress, create a new window, answer or send mail, request help, issue VMS commands, access VPW, or even start editing a new file. 2.9.4.1 Creating An Editing Window - To create a window while in the editor the user should press GOLD V on a VT100 style keyboard or F20 on the newer VT2xx keyboard. When this is done, the screen will erase, and the window banner will appear at the top of the screen. The process name displayed at the top of the screen tells which window level you are currently in. In response to the "$" prompt, users may enter any valid VMS command. However, continuation lines are not yet 2-7 COMMON VPW SUPORT SERVICES allowed. The user may return to the editor by typing either Control-Z, EXIT, or LOGOUT. Typeahead does not work within a window because the system must request from the terminal its current cursor location after each operation. If EXIT, or LOGOUT is typed, the current window is deleted and the user is returned to the editor. However, if Z is typed, the window is retained for subsequent use. Since creating a window involves creating an VMS subprocess (a rather time consuming process), if the window is to be used again soon, leaving it around between uses is advantageous. However, if inactive windows are left around, AUTOLOG will issue warnings that the subprocess (window) is idle. If left idle long enough, AUTOLOG will delete the subprocess. This will have no effect on your work since the next time you need it, it will be recreated again. 2.10 Document Orientated Directory Displays A goal of VPW is to "hide" VMS from the user. For example, file name extensions are hidden from the user using the Document Preparation System. Since the procedures know what file name extensions they need, there is absolutely no reason why the user should be subjected to them without reason. VPW knows about document files, file folders, graph files, viewgraph files, SPRs and Problem Reports, etc. And while each of these is a VMS file having both a file name and a file extension, when asked to display a brief directory of these entities, VPW presents only the names of each entity in a display listing four entities per row. Likewise, when prompted for a name (document, file folder, viewgraph, problem report), the file extension is never required. 2.11 Protected, Privileged Command Procedures It is often desireable to allow a user to perform a function for which they do not have sufficient privilege. It is easy to do on a per image basis image by installing the image with the required privilege. However, because VMS does not explicitly provide this service for command procedures, it was necessary for VPW to provide this functionality. On a system account, SYS$COMFILE:, a catalog of allowed command procedures exists (SYSCOMCAT.FIL). To invoke a command procedure with privilege, VPW invokes an installed privileged image with SETPRV privilege which in turn spawns a subprocess which reads the catalog, and if a match is found invokes the command procedure with the required privilege. Because only system logical names are carried over to the spawned subprocess, it is not possible for a non-privileged user to misuse this facility to invoke command procedures other than those cataloged in the system catalog. This 2-8 COMMON VPW SUPORT SERVICES facility is used as part of a problem reporting system which takes problem reports submitted by a user and deposits them in a system owned data base. 2.12 Uniform Exit Cleanup Different images and procedures may at different times place the terminal in a wide variety of states (Scroll regions set, smooth scroll, 132 column mode). Also a number of open or temporary files may exist at any one time. Regardless of which menu or image in which the user elects to exit from VPW, uniform exit procedures insure that the terminal is returned to its a initial state and all files are closed. 2-9 CHAPTER 3 THE VPW MENUS 3.1 Introduction Menus are organized in a tree structure branching off of the main menu. The main menu procedure sets up required symbols needed by both it and subsequent menus. However, since each menu can also be independently activated as a foreign command, each procedure tests to see if the required set up has been performed, and if not does its own initialization. Because each menu can be activated as a foreign command, it is possible to invoke any menu at any point from within VPW by entering the menu name at the choice prompt. 3.2 The VPW Main Menu To invoke the VAX Professional Workstation from any VT100 compatible terminal, type $ VPW [Menu_Keyletters] The Menu_Keyletters is optional but if provided, will bypass the primary menu display and drop the user into the requested secondary menu. For example, VPW DESK will invoke the desk menu. When VPW is invoked without a command line,the main menu is displayed along with the number of scheduled appointments for that day and the number of unread mail messages. On an NBI workstation or Tektronix 4014 terminal the menu is slightly different and reflects those functions which are allowed from those terminals. For example, on a VT100 terminal a user with two unread mail messages and one appointment scheduled would have the following menu displayed. 3-1 THE VPW MENUS The VAX Professional Workstation The VAX Professional Workstation Choose: DAtabase - The VAX Databases DA DEsk - The VAX Electronic Desk (2 messages 1 appointment) DE 2 1 Instruction The VAX Instructor I LOGoff - Logoff the VAX LOG PErsonal - The VAX Personal Workstation PE Research - The VAX Research Assistant R UTility - The VAX Utility Tool Box UT Exit - Exit E PF2 / PF4 - HELP / New Window PF2 PF4 Choice: Each option in the primary menu (except LOGoff, PF2, PF4, and Exit) drops the user into a secondary menu. Once in a secondary menu, the user stays there until either Exit, Control-Z, or carriage return is depressed in response to the "Choice:" prompt. Each of the main menu options is explained in a subsequent section. 3.2.1 NBI Workstation Support Secretaries accessing the VAX Professional Workstation from the word processors access a slightly different menu, allowing them to transfer documents between the VAX and their word processors. To send or receive a document to or from a VAX user, a secretary does not need to know anything about using the VAX except how to log on from their workstation. When an NBI workstation accesses VPW, the following menu is displayed. The VAX Professional Workstation You may choose: Calculate - Use the VAX calculator DTC - Use the VAX Desk Top Calendar Exit - Exit menu and use VAX directly Logoff - Logoff the VAX Mail - Use the VAX Electronic Mail Phonebook - Use the Phonebook System Send - Send a document from the NBI to the VAX Reminder - Send a Reminder TOday - Check DateBook for today's events TRansfer - Transfer a file from the VAX to NBI Choice: All functions except "Send" and "Transfer" are discussed as part of the VPW Desk Management Menu or the Research Assistant Menu. The Send and Transfer options are unique for NBI terminals. 3-2 THE VPW MENUS For the transfer option to work, the document for transfer must must have been prepared for transmission to the NBI using the VAX Document Preparation System (Option WP on in the Electronic Desk menu). The reasons for this requirement are twofold. First, the Document Preparation System sets the correct margins for transmitting the document to the NBI. If the margins are not set correctly, a significant amount of work is required by the secretaries in reediting the document after it has been transmitted. Second, when a document is prepared for transmission to the NBI, a special index file is updated, placing that document in a queue for the NBI. When the transfer option is selected, the file for transfer can not be found if the index has not had the file name placed in it. When the NBI user requests to transfer a document from the VAX, the user is prompted for the name of the individual to transfer a document for. If the name entered is correct, and that user has submitted a document for transmission, each document name available for transmission by that user is displayed and the NBI user is asked if it is the desired document. If it is, the NBI user is told how to setup the NBI and to "Hit RETURN when ready". Setting up the NBI involves exiting from communication mode temporarily (hit the MODE key), turning logging on, and returning to communication mode (hit CANCEL key). When a carriage return is pressed while in communication mode, the file is transmitted to the NBI and captured in -COMLOG on the user's NBI directory. Following transmission, the user is told to turn Press MODE, Turn Logging off, return to conversational mode and to "Press Carriage Return when ready". The operator is then asked if the file was transmitted correctly. If it was, the entry requesting transmission in the index file is deleted and the sender of the document is notified that the secretary has removed the document from the transfer queue. If the file was not transmitted and captured, the operator is given another chance to get it. When the NBI operator requests to Send a document to a user, a temporary document is created on the NBI operator's VAX account and that document is MAILed to the VAX user. The temporary document is then deleted from the account. 3.2.2 Available VPW Foreign Commands Many facilities of the VAX Professional Workstation may either be accessed via the menu system, or individually via foreign commands. During the system wide login command procedure, the procedure SYS$SYSVPWFILES:SETVPWSYM.COM is invoked. Once logged on, the user has the following foreign commands available. ALIST - Display a phone number and address 3-3 THE VPW MENUS BROADCAST - Broadcast a message to a user BROWSE - A EDT V3 keypad file browser CALC - Use the VAX Calculator DATABASE - Invoke the KMS Data Base menu DECALC - Use DECALC DESK - Invoke the VPW Desk Management menu DTC - Use the VAX Desk Top Calendar GRFmaster - Invoke the Graphics Work Station menu INSTRUCT - Invoke the VAX Instructor menu KLIST - KMS Phone Extension List LARGE - Switch terminal to 80 column mode MLIST - Display name and address in mailing list format NOTEBOOK - Use the VAX NoteBook PAGE - Erase any terminal screen PHONEBOOK - Use the VAX PhoneBook PLIST - Display a phone number REMINDER - Send a reminder message RESEARCH - Invoke the Research Assistant menu SMALL - Switch terminal to 132 column mode TEKgraph - Use TEKgraph TVG - Use TVG for making a viewgraph TVGmaker - Use the TVG viewgraph design procedure TOOLBOX - Invoke the VAX Tool Box menu VPR - Submit/Answer a VAX Problem Report VPW - Invoke the VPW main menu WP - Invoke the VAX Document Preparation System menu Usage of some of these Foreign commands is explained in the appropriate following chapters. Other commands (LARGE, PAGE, SMALL) are sufficiently simple that trying them out is the best way to learn how to use them. 3.3 The VAX Databases Menu The Databases menu provides users with easy access to a variety of KMS-specific data bases relating to different aspects of our operations. In addition to the KMS-specific data bases, however, staff also has access to our on-line VAX Problem Reporting System and SPR Data Base. When selected from the main menu, the following menu appears. The VAX Databases The VAX Databases You may choose: DMs - The DMS Databases DM DRawing - The Drawing file DR DTr - VAX Datatrieve DT MIS - The MIS Reporter MI Problem - Submit/Read a VAX Problem Report P SPR - VAX SPR (Bug Report) index SP 3-4 THE VPW MENUS STaff - Staff phone directory ST Exit - Exit menu to DCL E - Return to previous menu PF2 / PF4 - HELP / New VPW Window PF2 PF4 Choice: The DMS Databases are described in a separate memo by Fred Schebor. Non-DMS users do not have access to these data bases. The Drawing file data base is implemented as a Notebook function. Any VAX user is allowed to use it to search for drawings, however, only Engineering and Drafting are allowed to update and modify the database. The DTR option drops the user int VAX Datatrieve The MIS option drops the user into the MIS Reporter procedure. From the MIS Reporter, managers can browse financial reports relating to the status of projects they are managing. The VAX Problem Reporter provides VAX users with a simple method of reporting and receiving answers to problems they encounter using the VAX system. When a problem report is added to the problem report data base, the problem manager is automatically notified that the problem exists. When the problem is solved and the problem report is answered, the original sender is automatically notified that the answer exists. An index of all problem reports and their disposition is kept by the system. The use of the VAX Problem reporter is described in a subsequent chapter. The SPR option allows users to browse the SPR index to look for problems which might relate to their own, to read the SPR problem submittal, and to read DEC's answer, if any. The Staff phone directory provides a similar function to the Phonebook system except that instead of providing a personal phonebook, this phone directory contains information only relating to KMS Staff, their home address and phone number, their work phone extensions, their department, and their location. All staff have access to the directory for updating it as they see fit. 3-5 THE VPW MENUS 3.4 The VPW Desk Management Menu VPW Desk Management menu provides users with a selection of standard office automation tools. When the VPW Desk Management menu is selected the following menu is displayed. VPW Desk Management VPW Desk Management (2 messages, 1 appointment) 2 1 You may choose: Calculator - Desk Calculator SU - Spreadsheet and Utilities C SU DTC - Desk Top Calendar TAlk - Terminal Teleconference D TA KMS - KMS Staff Directory TOday - Check for today's events K TO MAIl - Electronic MAIL Wp - VAX Document Preparation MAI W MASs11 - Mass-11 WP Exit - Exit menu to DCL MAS E Phonebook - Personal phone book - Return to previous menu P Reminder - Send a Reminder PF2 - Help R PF2 Spreadsheet - DECalc Spreadsheet PF4 - New VPW Window S PF4 Choice: At the top of the menu display, the number of unread mail messages and the number of half hour appointments scheduled that day are displayed. Each of the menu options will be discussed in subsequent sections. 3.4.1 Calculate Calculate The Calculate option invokes the VAX calculator program which signifies its presence with the prompt CALC>. Exit from calculator mode by entering Control-Z. A list of valid commands may be obtained by typing ? to the CALC> prompt. The use of the VAX Calculator program is explained in detail in a subsequent chapter of this manual. 3.4.2 DTC DTC The DTC option invokes the VAX Desk Top Calendar. DTC replaces the Datebook procedure which kept a personal calendar in the previous version of VPW. DTC provides very comprehensive calendar management services including Day-At-A-Glance, Week-At-A-Glance, Month-At-A-Glance, and Year-At-A-Glance displays. In addition, context sensitive HELP is available for all of its functions by pressing the PF2 key or the HELP key on LK201 keyboards. A subsequent chapter is devoted to a detailed explanation of how to use DTC and its services. 3-6 THE VPW MENUS 3.4.3 KMS KMS The KMS command invokes the KMS Staff Directory program which in operation is very similar to Phonebook. Both programs provide information on phone numbers and addresses. However, the Staff Directory is a public data base which any staff member may access either interactively (from this menu) or by using the KLIST command from DCL or a VPW window. The KLIST command has the format $ KLIST name where name is the name of the KMS staff member you are looking for. If the name is found the phone extensions for that staff member are displayed. In addition to storing the work extensions for each staff member, the Staff Directory also stores the employee's home address and phone number, their department, and the building in which they work. The first time one wants to enter a new employee into the system, it must be done by the VAX staff. However, any time after that, any KMS VPW user may modify any entry in the staff directory. Consequently, staff should take care to only update their own record. Users can gain information on how to use the Staff Directory program by reading the chapters on using Notebook and Phonebook in this manual. 3.4.4 Mail Mail At the top of the menu, the number of unread mail messages is displayed. The MAIL command can be used to either read these messages or to send mail to users connected to VAXs anywhere on our network. A detailed description of the VPW interface to VMS mail is presented in a subsequent chapter. The MAIL menu is first displayed and presents those options which exist (for example HELP, EXIT, SEND, and READ) and then you are prompted for input. When you are done using MAIL, enter a Control-Z to exit it and return to the Desk Management Menu 3.4.5 MASS11 MASS11 Mass-11 is a high performance, "what you see is what you get" word processor for VAX systems. If a system is licensed to use Mass-11, this selection will invoke Mass-11 and load the scientific character fonts into VT200 series terminals. If a system is not licensed for use of Mass-11, a message to that effect will be displayed. 3-7 THE VPW MENUS 3.4.6 Phonebook Phonebook The PhoneBook option allows the user to create and access a list of phone numbers and addresses in a data file on their login directory. PhoneBook is implemented using the VAX NoteBook. Phonebook's use is documented in Chapter 9. Pressing the PF2 key on VT100 terminals when Phonebook is requesting input will produce a HELP display. The program is practically self teaching. However, users are should read Chapter 9 for more details. 3.4.7 Reminder Reminder The Reminder option allows the user to send dated and time-stamped reminder messages to users on the VAX. Based on user input, the user submits messages to the reminder queue for delivery at a later time and date. At the appointed date and time, the message is dequeued and the Broadcast utility finds the user and displays the message at any terminal on which the user is logged on. If the user is not logged on at any terminal, Reminder mails the message to the user. A full description of the Reminder option is presented in a subsequent chapter. 3.4.8 Spreadsheet Spreadsheet The Spreadsheet option invokes DECalc. VPW checks to see if a private DECalc initialization file exists. If a initialization file SYS$LOGIN:DECALC.INI, DECalc is invoked using that file. Otherwise it is invoked without an initialization file. 3.4.9 SU SU The SU option invokes a Spreadsheet and Utilities menu. Several DECalc utilities exist. The first is DTRwhiz which allows users to convert Datatrieve data into data used by DECALC. The second utilitiy is a DECalc directory repair utility. 3.4.10 TAlk TAlk The TAlk command allows the user to access the VMS PHONE utility which allows users on different terminals (VT100's) to converse with each other using their terminals. When PHONE prompts, type HELP to get help in learning the commands for PHONE. Information on how to use PHONE can be found in a chapter in the VMS Utilities manual 3-8 THE VPW MENUS 3.4.11 TOday TOday Typing TOday will cause Desk Top Calendar (DTC) to display all meetings/appointments scheduled for the current day. The use of DTC is documented in Chapter 6 in this manual. 3.4.12 WP WP The WP command (for Word Processor) drops the user into the VAX Document Preparation System menu. The VAX Document Preparation system provides users not running MASS-11 with a very complete word processing system using EDT and Runoff. The VAX Document Preparation system is described in a subsequent chapter in this manual. 3.5 The VAX Instructor When the Instruction is selected, the VAX Instructor menu is displayed: The VAX Instructor The VAX Instructor You may choose to learn about: DAtatrieve Introduction to VAX Datatrieve DA DElete The VMS Delete Command DE DIrectory The VMS Directory Command DI EDit The VMS Edit command ED File Specifier The VMS File Specifier F Introduction Introduction to VMS I Purge The VMS Purge Command P Runoff The VMS Runoff Command R TOouch Typing Learn to Touch Type TO Type The VMS Type Command T EXit Exit from this menu EX Choice: The Edit and the Introduction choices invoke the DEC's CAI (Computer Aided Instruction) courses for the DEC Standard Editor and for an Introduction to VMS respectively. The other CAI courses were developed in house and provide a very good introduction to the basic VMS commands which are necessary for general use by every VAX user. All of the CAI courses let you see what the correct working of the commands is, and most provide for testing to see if you have learned the course material. All the courses are entertaining and provide a rapid, nearly painless way to learn how to use the VAX. As an aid in learning to use the VAX we also have a number of 3-9 THE VPW MENUS introductory books, including a VAX/VMS Primer and the VAX/VMS Users Introduction. 3.6 The VAX Personal Workstation To avoid the problem of having to create a multitude of command procedures for users requiring different functionality, each user is permitted to have one personal menu option per directory. When the Personal Workstation option is selected for the first time a menu template file, VPWUSER.MNU, is created. Initially the only entries in this menu are to Exit and to return to the VAX Professional Workstation main menu. Users wishing to add a personal menu should edit VPWUSER.MNU to add lines of the following form: key - Text....Text|Key:=@cmdprocedure.MNU Two features are important here. First the vertical bar, "|", must be used to separate the menu text to display from the foreign command. Second, the foreign command must be of the form Cmdverb:=@command_file_name.MNU Note that the file type of the specified command file must be .MNU. This special extension (for menu) is used so that VPW knows whether or not the foreign command belongs to the menu. An example of setting up the menu is: MYreport - Text 1|MY*report:=@MYREPORT.MNU MY Targets - Text 2|T:=@TARGLST.MNU T VIsicalc - Text 3|VIsicalc:=@VCALC.MNU VI : When the menu is displayed the following will appear: You many choose: MYreport - Text 1 MY Targets - Text 2 T VIsicalc - Text 3 VI VPW - The VAX Professional Workstation VPW EXit - Exit EX Choice: The VPW and Exit command are automatically inserted by VPW. Bold text can be inserted with the editor using VT100 escape sequences. [1m turns on bold mode and [0m turns off all special attributes. However, it is not necessary to make any characters appear bold. Do it only for personal convenience. Note the use of the "*" in defining the foreign commands. This allows the foreign command to be recognized if more than the minimum 3-10 THE VPW MENUS number of characters are entered. 3.7 The Research Assistant Menu The Research Assistant menu, serves as focal point for those workstation functions explicitly designed to support the research activities of our staff. When the Research Assistant Menu is requested, the following menu is displayed. The VAX Research Assistant The VAX Research Assistant You may choose: Calculate - Use the VAX Calculator C Journals - Use the VAX Reference Library J Graph - Graphics entry and display system G Report - Use the Target Shot Analysis System R Tape - Read/Write IBM/VAX interchange tapes T Exit - Exit menu and use VAX system directly E PF2 / PF4 - HELP / New VPW window PF2 PF4 Choice: The following sections describe the capabilities offered by these options. 3.7.1 Calculate Calculate The Calculate option invokes the VAX calculator program which signifies its presence with the prompt CALC>. Exit from calculator mode by entering Control-Z. A list of valid commands may be obtained by typing ? to the CALC> prompt. The use of the VAX Calculator program is explained in detail in a subsequent chapter of this manual. 3.7.2 Graph Graph Graphics workstation support is provided for two classes of terminals, Tektronix 4014 terminals, and DEC ReGIS terminals (VT125/VT24x). The menu displayed depends on the graphics protocol(s) supported by the invoking terminal. For example, only at the proper Tektronix 4014 terminal, can a user is access the graphics tablet input program. Graphics workstation support functions provide the user with the ability to; 3-11 THE VPW MENUS 1. Use a spread sheet like graphics data editor on ANSI compatible terminals. Binary X-Y graphics data sets used by TekGraph, Datatrieve and the graphics tablet may be created or modified. A line mode editor also exists for hardcopy and Tektronix terminals. 2. Enter data via a graphic tablet (Tektronix 4014 terminal only). 3. Create simple plots with DATATRIEVE or DECgraph on ReGIS terminals or elaborate plots with TEKGRAPH on ReGIS or Tektronix terminals. 4. Explicitly design the format for elaborate or composite graphs with a simple to use high level graph control language. 5. Curve fit the X-Y data in a variety of ways and display the fitted data versus the original data. 6. Create and display viewgraphs on either ReGIS or 4014 terminals 7. Process images via a remote image processors for display on local television monitors. 8. Prepare a high resolution graph from a any VT100/VT200 terminal for later spooling to a Tektronix 4014 terminal. A central assumption in the design of the workstation support is that a user probably will be working with a single data set in a number of different ways. The user will first create (or import a data set from an external program) or modify an existing data set to reflect new data. Then the user will want to display the data and possibly design (or modify) the manner in which that data is to be displayed. Based on the display of the data the user may either go back to modify the data, change the plot display method or try curve fitting the data. This process will continue until the final graph or analysis satisfies the user's needs. To simplify workstation use for our staff, the menu system is designed to minimize the amount of typing. Once a graphics data set is selected for use, it becomes the default data set to be displayed in subsequent prompts by the images activated from the menu. A detailed description of the functions provided from the graphics workstation menu is presented in a seperate chapter. 3-12 THE VPW MENUS 3.7.3 Journals Journals The Journals option allows the user to create and access a list of journal articles and references. Journals is Notebook program and in operation behaves similarly to Phonebook except that the data requested, displayed and stored is different. Pressing the PF2 key on VT100 terminals when Journals is requesting input will produce a HELP display. The program is practically self teaching. However, users are urged to read the chapter on Notebook creating and using a private journals data base with the Journals option. 3.7.4 Report Report The REPORT option provides the staff with easy access to the Target Shot Analysis System which is used in analyzing the data acquired in our Laser Fusion experiments. The data is filed by experiment number and may be stored either on a PDP-11 system (connected via DECnet), off-line on a removable disk cartridge, or on any one of a number of subdirectories on an RA81 disk. The Target Shot Analysis System either locates where the data is stored and allows the user to run the report programs (over the DECnet, if required) or informs the user which removable disk the data is on so that the disk can be loaded on to the system. 3.7.5 Tape Tape The TAPE option allows the user to transfer source and data files between our IBM and and our VAX. After answering a few questions as to which files to put on the tape, the files (including wildcard selections) are placed on the tape in a format in which the IBM can extract all transfered files from the tape without knowing what is on the tape to start with. This is accomplished by making the first file on each transfer tape contain all the required JCL for removing the rest of the files from the tape. 3.8 The VAX Tool Box Menu The VAX Tool Box provides the user with access to a wide variety of less frequently used utilities and procedures which do not do not belong as part of some other menu. Because a great many items could potentially exist as part of the Tool Box menu, the system allows for an unlimited number of pages of menu display through which the user can scroll with either the Up/Down arrow keys or the PREV/NEXT keys on the LK201 keyboard. 3-13 THE VPW MENUS When a page containing the item sought is found, the user enters the choice and that function is activated. As each item is added to the menu, Help for that topic is placed within a Tool Box help file. Hence, when the PF2 (or HELP) key is pressed, the user is easily able to get help on using the application of interest. Items found on the Tool Box menu include such diverse topics as converting error codes to error messages, converting RMS error codes to a discription of the error, creating UDK load files for the VT2xx terminals, access to VAXnet, compact display of the print and batch queues, resequencing Fortran source files, verifying tapes for reliability, and many, many more. 3-14 CHAPTER 4 THE VAX DESK TOP CALENDAR 4.1 Introduction DTC (Desk Top Calendar) is a fast, simple-to-use, desk top calendar system. With it the user can schedual appointments, meetings, or events months in advance and automatically get notified on the day they occur that there is an event that day to deal with. One can view ones desk top calendar, a day at a time, a week at a time, a month at a time, or a year at a time. DTC is integrated with VPW so that appointments scheduled with DTC are known about when VPW is activated. 4.2 DTC Replaces Datebook In VPW DTC is faster and easier to use than DATEBOOK ever was and doesn't require VAX Datatrieve to use. Consequently, it replaced DATEBOOK in VPW V4.0 Hooks are also provided by the QCHECK command to update a symbol DTC_APMT with the number of appointments for that day. This is so menu displays can show the number of appointments for the day without the user having to invoke DTC. The inclusion of DTC in VPW involved three changes; 1. When VPW is invoked, it only checks the DTC calendar. 2. The VPW TODAY command, uses DTC not DATEBOOK. 3. VPW automatically displays the number of appointments scheduled as part of the menu display so that a constant reminder is present. 4-1 THE VAX DESK TOP CALENDAR 4.3 Overview Of DTC The DTC program provides an on-line, appointment scheduler and calendar facility. The program currently supports four major functions: 1. Day-At-a-Glance 2. Month-At-A-Glance 3. Week-At-A-Glance, and 4. Year-At-A-Glance. DTC is defined as a foreign command for each user by SYS$VPWFILES:SETVPWSYS.COM. DTC may either be used from within VPW or the program may be invoked by: $DTC ! Use DTC interactively $DTC [[option] [date]] ! Send commands to DTC directly Numrous commands (including D for Day, W for Week, M for Month, etc.) exist. If no option is given, the a menu is displayed. A command is then requested after each menu display, until the user types EX to exit. The basic date format is mm/dd/yy for Day and Week command, and mm/yy for the Month command. Time is specified in HH:MM format but appointments can only be made for half hour time slots. For example, the command D 1/03/84 displays appointments for January third, 1984. Then entering 9:00 at the Command: prompt, would insert the appointment specified by Command: the appointment string into the 9:00 time slot on the specified date. When DTC starts up, the default date is set to the current day's date. Subsequently, any date entered as a DTC command sets the default date to the newly entered date. The I command (for initialize) may be used to reset the default date back to the current date. Appointments can be made interactively from within DTC or directly via a DCL command. A DCL command to enter an appointment in one's calendar might be: $DTC D 010183 9:00 Fred Taylor interview 4-2 THE VAX DESK TOP CALENDAR 4.4 Terminal Requirements DTC runs only on VT100 compatible terminals (VT100 and VT200 terminals). Because the NBI word processor has an "almost" VT100 compatible emulation mode, DTC "almost" runs correctly on the NBI. The major exception is that the year display is not operational for the NBI. 4.5 Time Format The basic time format is HH:MM. Calendar entries may be made from 8:00 am to 4:30 pm in half hour increments. Since a meeting or appointment may last longer than a single half hour time block it is also possible to enter schedule a block of time by entering range of times in HH1:MM1>HH2:MM2 format where HH1:MM1 represents the first time slot the appointment uses and HH2:MM2 represents the last time slot the appointment uses. Times outside the range from 8:00 am to 4:30 pm are treated as evening appointments and are posted as if they occured at 5:00 pm. 4.6 Date Format Dates may be given as mmddyy, mm/dd/yy, or dd-mmm-yy. For example, June 6, 1984 could be represented by: 6/6/84 060684 6-Jun-84 If the forms without either '/' or '-' is used, then each component number of mm, dd, and yy must be a two digit number. Leading zeros must be inserted if necessary into the date string. It is also possible to change the default date incrementally from its current value by 'nn' units. The syntax of this command is + or - nnU where nn = interval U = D for Day = Y for Week = M for Month = Y for Year 4.7 HELP DTC has a built in help facility. Help may be obtained by pressing the PF2 key. On VT2xx terminals in 7 bit mode, HELP may also be obtained by pressing the HELP hey. The Help information displayed depends on the previous command given to DTC. For 4-3 THE VAX DESK TOP CALENDAR example, if the DAY command was just used, DTC will display HELP on the DAY command by default. The first time the PF2 key is pressed, the current default help information is displayed. The second time, the key is pressed, DTC prompts for a topic, and you can request any DTC Help which is available. If you enter a carriage return to a request for a HELP topic, DTC resets the help information to introductory HELP information. 4.8 DTC Data File The DTC appointment records are kept in SYS$LOGIN:DTC.DAT. This is an ASCII file with fixed length records. DTC tries to keep appointments in its calendar file in chronological order. Since appointments can be made in any order for any date and time, it is necessary for DTC to sort the appointments into chronological order after new appointments are added. When this occurs, a message is displayed that the appointment file is being sorted. The process of sorting involves creating a new file, sorting records into it, and deleting the old file. For best performance, DTC's file size should be kept as small as possible (improves sorting speed). So it is important to purge old appointments (past weeks, months) from one's calendar when they are no longer needed. 4.9 Commands When DTC is invoked a menu displaying a list of the major commands is displayed. D [mm/dd/yy] - Appointment Schedule for dd/mm/yy D EV [Text] - Add/change Evening Appointment EV W [mm/dd/yy] - Week-At-A-Glance for week of dd mm yy W M [mm/yy] - Month-At-A-Glance for mm yy M Y [yy] - Year at a Glance Y PR [mm/dd/yy..]- Print list of appointments PR PU [mm/dd/yy] - Purge appointments prior to mm/dd/yy PU I - Reset default date to today. I PF2 - Display Help information PF2 PF4 - VPW Command Screen PF4 EX - Exit EX Command: These commands and several others will be discussed in subsequent sections. 4-4 THE VAX DESK TOP CALENDAR 4.9.1 Day At A Glance Command The basic command for entering an appointment or viewing a days events is the Day command. The format for the Day command is (brackets enclose optional entries) D [mm/dd/yy] [HH:MM[>hh2:mm2] Text...Text...] The date string can be in any of the allowed formats. If the date is not present, it defaults to the current or default day. The appointment string is optional and if present is entered as the appointment for that day and time. If not present, the current day's appointments are displayed, and DTC waits for a command to be input. The format of an appointment string is either HH:MM Text.....Text (60 characters worth of text) to make an entry for time HH:MM, or HH:MM>hh2:mm2 Text.....Text (60 characters worth of text) to reserve a block of time from HH:MM to hh2:mm2. The appointment text string may be omitted entirely in which case DTC positions the terminal cursor to the proper appointment time and allows the user to input the appointment message at the proper position. If a carriage return is entered at this point, any previous appointment string at that time is deleted. This makes it easy to remove appointments which were previously scheduled. If a Control-Z is entered, no changes are made and DTC returns to the main menu. When an appointment string is entered, the day's appointments will be updated, and DTC will again wait for another command. If RETURN is entered, DTC will return to the main menu. 4.9.2 Evening Command An evening appointment is any appointment outside of normal working hours (8:00 am to 4:30 pm inclusive). All evening appointments are assigned a time of 17:00 (5:00 pm) for display purposes. The EV command can be used to enter an appointment. When EV is typed, the calendar for the current day is displayed and the cursor moves to the Evening entry location. 4-5 THE VAX DESK TOP CALENDAR 4.9.3 Week At A Glance Command The format for the Week command is W [mm/dd/yy] The date string can be in any of the allowed formats. If it is not present the date defaults to the current or default day. The week containing the specified day will be displayed. Every day on which an appointment exists, will have those appointment times displayed. After the weeks appointments are displayed, DTC will wait for a RETURN (return to main menu) or command string to be entered. 4.10 Month At A Glance Command The format for the Month command is W [mm/yy] If no date string is given, the display will default to the current or default month and year. Three month calender displays are presented, the previous month, the selected month, and the next month. If the current date corresponds to any day in the month display, that day is highlighted. Any date in the selected month which has calender entries, will be flagged with a highlighted asterix ('*'). When DTC finishes displaying the month, it waits for input (with the calender dispalyed). Enter a RETURN, to return to the the main menu, or a valid DTC command to perform some other function. 4.11 Year At A Glance Command The format for the Year command is Y [yy] If no year is given, the display will default to the current display. The current date in the year display will be displayed highlighted on VT100 compatible terminals. The year display can not work on NBI terminals in VT100 emulation mode because the NBI emulation does not support 132 column video display. 4-6 THE VAX DESK TOP CALENDAR 4.11.1 Initialize Command The I[nitialize] command is used to reset the default date back to the current date. 4.11.2 Locate Command The L[ocate] command is used to locate a block of half hour periods during the week including the optional date which can be used in scheduling a meeting. The format of the command is L [mm/dd/yy] n where n is the number of contiguous half hour time slots to look for and the optional date selects the week interval to search in. When the command is issued, a standard week display will appear. However, each time printed on the screen does not represent an appointment. Rather, the times represent starting times available for scheduling a meeting of the required length. Note that no evening times will be scheduled (17:00 or later). 4.11.3 Print Command The Print command is used to print the appointments for a given date or a range of dates either on the line printer, the letter quality printer, a scratch file or the user's terminal. By default output goes to the fast line printer (SYS$PRINT). The format of the command is PR[int] [MM/DD/YY[>mm/dd/yy]] [Output] where Output may be one of LQ - Letter Quality Printer PRINTER - Current printer (SYS$PRINT) SCRATCH - SCRATCH.FIL TERM - User's Terminal TT: - User's Terminal The dates if present may be in any of the allowed formats. If no date is specified, the current default date is used. If only one date is specified, only entries for that date will be printed. If two dates are specified, all entries from the first date specified to the last date specified will be printed. 4-7 THE VAX DESK TOP CALENDAR 4.11.4 Purge The Purge command is used to remove old appointments from the calendar so that they do not clutter the calendar needlessly. The DTC calendar is not purged automatically, rather it is only purged of old appointments when the Purge command is used. Note that the first two letters, PU, of the Purge command are required to distinguish this command from the Print command. The format of the Purge command is PU[rge] [mm/dd/yy] If the optional date is not speciified, all appointments prior to the current date are removed from the current calendar file. If the optional date is specified, all appointments prior to that date are purged from the calendar file. The process of purging files, involves creating a new appointment file, copying just the records to be retained to it, and finally deleting the old appointment file. In the event of an error (out of disk quota or some such), DTC attempts to retain the original file. 4.11.5 Check Command The CHECK command is designed to be used in DCL command mode. If the command $DTC CHECK is given (for example, it is in the user's LOGIN.COM file), DTC will check to see if any appointments are scheduled for that day. If they are, DTC will issue a message saying how many appointments exist for that day. 4.11.6 QCheck Command QCHECK requests DTC to perform a quiet check for the number of appointments the user has that day. DTC prints no messages but sets the DCL symbol DTC_APMT to be the number of half hour appointments scheduled for that day. For example, $ DTC QCHECK $ WRITE SYS$OUTPUT "You have ''DTC_APMT' today" 4-8 THE VAX DESK TOP CALENDAR 4.11.7 Today Command The T[oday] command is designed for use as a DCL command. If the command DTC TODAY is given (and DTC is a foreign command), the appointment list for the current day is displayed, and DTC exits back to DCL without disturbing the display. For example, the TODAY command may be used in a user's LOGIN.COM to automatically present a list of the day's activities when the user logs on. $ ! Display the activities today $ DTC TODAY 4.11.8 Calendar Command The C[alendar] command is designed for use as a DCL command. If the command DTC Calendar is given (and DTC is a foreign command), the calendar for the current year is displayed, and DTC exits back to DCL without disturbing the display. This command will not work on NBI terminals in VT100 mode. 4.12 Installation Of DTC To install DTC on a VMS system three things must be done. 1. Copy DTCVAX.EXE to SYS$SYSVPWFILES. 2. Insert DTC.HLP into SYS$SYSVPWFILES:VPW.HLB 3. Define a foreign command (DTC:==$SYS$SYSVPWFILES:DTCVAX). This is done automatically by VPW. 4-9 CHAPTER 5 THE VAX DOCUMENT PREPARATION SYSTEM 5.1 Introduction One of the overriding goals of the VPW system is to provide a casual VAX user with friendly, yet easy access to the the many productivity tools available on the VAX system. As much as possible, the casual user should not have to understand how to talk "computer" with the VAX to be able to use some of its basic services. The VAX system provides many services similar in concept to those found on dedicated word processing systems, ie directories, a full screen video editor, and a document formatter. The Document Preparation System is used to tie these capabilities into a coherent whole and to keep track of the documents produced. 5.2 Assumptions And Goals This version of the VAX Document Preparation System tries to provide a complete environment for the creation, editing, revision, formatting, printing, filing and retreiving of documents. The user is not expected to be familiar with VAX terminology (or at least not much). Its use is targeted toward professional staff who find it convenient to prepare memos, letters and papers prior to transmission to the secretarial word processing system. The system assumes the user wants to work with documents. A document is defined as a text file with a .RNO type. The user, .RNO however, never should have to worry about this. All documents should be referenced by 1-9 character names ONLY. The sole ONLY exception to this is that when a document is formatted for tranmission to the NBI word processors, an additional temporary formatted text file is created with an extension .NBI. This .NBI document is created in a special subdirectory [.NBI] and is automatically deleted after successful transmission to the NBI. 5-1 THE VAX DOCUMENT PREPARATION SYSTEM 5.3 New Concepts This version of the system introduces several new concepts. The user's current directory becomes the working desk. This desk can contain two types of documents: 1. ACTIVE. Active documents are currently out on top of the desk ACTIVE and are available to be worked on. 2. FILED. Filed documents are stored in a named file folder on FILED the desk. Also on the desk is an index of all documents known to the the VAX Document Preparation System. In addition to the document name, it keeps track of to whom it was sent, the document type, creation date, filed or active status, and the subject matter. This index can be rapidly searched by subject, document type, or file folder to locate documents. 5.4 Requirements For Using The Document Preparation System The Document Preparation system only runs on VT100 compatible type terminals with the advanced video option. It is assumed that the user has enough disk space available for the system to use. Prior to editing any document it checks the current disk quota and does not allow editing to occur if the available disk space is too low. However, for performance reasons, it is not possible to monitor disk quota allocation continually. Users with small disk quotas should not attempt to store documents in file folders unless the file folders are periodically copied to tape and deleted from the user's account. It is assumed that accounts with small quotas exist solely to prepare documents to the secretarial Word Processor and that, once the documents are transmitted, they can be deleted. 5.5 Available Training And Manuals For Using The System To use the Document Preparation System effectively, the user should understand how to use the DEC Standard Editor (EDT) in video mode. The user is urged to take the EDT Computer Aided Instruction (CAI) course offered on the VAX. The user also should learn basic document formatting commands (RUNOFF). A brief primer on using the document formatter (RUNOFF) is also available on the VAX as a mini-CAI course. Both courses may be accessed from the VAX Professional Workstation as follows: 1. Type VPW to start up the VAX Professional Workstation 5-2 THE VAX DOCUMENT PREPARATION SYSTEM 2. Type I to enter the Instruction menu. Manuals for both the editor (EDT) and document formatter (RUNOFF) may be ordered: 1. EDT manual from DEC Direct Sales Catalog AA-M476A-TK 2. EDT Pocket guide from DEC Direct Sales Catalog AA-M477A-TK 3. RUNOFF manual from DEC Direct Sales Catalog AA-J268B-TK 4. RUNOFF pocket guide from DEC Direct Sales Catalog AA-M548A-TE For the editor (EDT) course, a special keypad overlay exists and may be obtained. 5.6 First Time Use Of The System The first time one uses the Document Preparation System, the user must establish certain default settings (which may be changed later). These default settings are used to minimize typing while using the system. Generally, once a document has been specified to work on, one or two keystrokes and a carriage return may be used to go from one word processing function to another in a rapid manner. The user also may elect to select a special word processing directory or to specify that their terminal is to be reset to its original settings when VPW exits. Remember, the system is supposed to be "Bomb Proof." If it isn't, you found a "BUG", so please report it. Getting out of the system can always be accomplished by typing a Control-Y. Exiting from any prompt without performing any action can generally be accomplished by typing Control-Z (which should return operations to the previous logical function (menu). 5.6.1 Setting Document Defaults The first time user is asked for a first and last name, for prefix codes for letters and memos, and for a default file folder name for storing documents. In addition, each user is requested to specify the name of a secretary to notify when a document is ready to be picked up. The prefix codes are used to assign names automatically for each letter or memo sent. The prefix codes must be different. A good choice is the users three initials plus M for memos and L for letters. A good choice for a file folder might be MEMOS, or LETTERS or your initials prefixing the word FOLDER. 5-3 THE VAX DOCUMENT PREPARATION SYSTEM 5.6.2 Selecting A Word Processing Directory When the Document Preparation System starts up, it checks to see if the logical name WP_DIRECTORY exists. If it does, the user's default directory is set to the directory specified. For example the command $ ASSIGN ddcu:[USER.RUNOFF] WP_DIRECTORY would switch the user to device DDCU: on directory [USER.RUNOFF] for the duration of the session. When the Document Preparation System exited, the user is returned to his/her initial device/directory. 5.6.3 Setting Default Terminal Characteristics When VPW is invoked, it establishes terminal characteristics best suited for its displays. If a terminal is set by default for inverse video, VPW will reset it to normal video. If the terminal is a VT200 series terminal, on exit, VPW will reset the terminal to its power up settings. However, if the terminal is a VT100, the reset sequence, c, is not sent because it produces such a bizzaar, time consuming display. Hence, the terminal will be left in normal video mode when VPW exits unless the user elects to tell VPW that the terminal should be returned to Inverse Video mode. If it is desired that VT100 terminals be reset to Inverse Video (regardless of power up settings), the user should add the line $ Reset_Inverse_Video:=="T" ! Set to inverse video to his/her LOGIN.COM file. 5.6.4 Selecting A Secretary The Document Preparation System assumes the ultimate goal for each document is to be transmitted to a secretary for insertion into the company Word Processing system. As such it is important that each user's secretary know when a document is ready to be picked up. While the non-DEC word processors do not automatically receive mail, several times a day, each secretary should access the VAX system just long enough to see if they received any mail telling them that a document is ready. The secretaries to whom one may send a document are defined in SYS$SYSVPWFILES:SECRETARY.LIS. The format of this file is a 20 character VAX User_Name (with trailing spaces if needed) followed by the secretary's full name (upper and lower case). When selecting a secretary to notify, the user must select one of the secretaries in this file even if the user has no intention of ever 5-4 THE VAX DOCUMENT PREPARATION SYSTEM sending a document to a secretary. 5.6.5 Verify Your Disk Quota The document preparation system will not let you do much of anything (ie edit a document) unless you have more than 100 unused blocks in your disk quota allocation. The disk you are editing on must have a disk quota file and it must have a quota for your account. Whether or not you have EXQUOTA privileges does not matter to the system. If your quota is not large enough, you may not create files. The quota is checked using the program SYS$UTILITY:GETQUOTA as taken from a VAX SIG tape. The reason for the stringent quota checks, is that for normal users, nothing is more upsetting (and I mean absolutely nothing) than to be editing for an hour, then go to exit, and find all one's work has been lost due to lack of adequate disk quota. 5.6.6 Your Initial Desk Contents When you first invoke the Document Preparation System, your desk (whatever VMS directory you are on) has, at a minimum, two files on it, DOCDFLT.CTL and LASTDOC.COM. DOCDFLT.CTL is an ASCII text file containing your default parameters. LASTDOC.COM is an ASCII command file used to record the last document number the user used. Each time a new memo or letter is created the next higher number is used and the file is updated. When you create your first document, you also create a document index file, DOCINDEX.FIL. This file is updated every time the status of a document is changed by the system. 5-5 THE VAX DOCUMENT PREPARATION SYSTEM 5.7 Using The VAX Document Preparation System. The VAX Document Preparation System provides an integrated word processing package which lets users create and file letters, memos, papers, and reports, check them for spelling errors, and either prepare them for transmission to the NBI word processor or print them on a VAX printer. When the Document Preparation system starts up, the following menu is displayed. VAX Document Preparation VAX Document Preparation Default document name: NOT set NOT You may choose: ACtive - Active document list Spell - Spell check document AC S ANalyze - Analyze English use Spell Word - Add word to spell. dict. AN S W CLean - Clean up your desk Transmit - Transmit document to WP CL T CReate - Create a document View - View formatted document CR V Directory - Unfiled document list WAStebasket - Throw away a document D WAS EDit - Edit a document ED Filer - Document Filer Menu F Kill - Kill a print job EXit - Exit menu to DCL K EX Modify - Modify WP defaults - Return to previous menu M Print - Print/Format document PF2 / PF4 - HELP / New VPW Window P PF2 PF4 Choice: Below the title line information about the default document name is displayed. When the system is first started, no default name exists. The default name is set the first time you enter a choice and it prompts for a document name. Thereafter, it remembers that document name and will operate upon it by default if a carriage return is entered when it prompts for a document name. At the bottom of the menu, the system prompts you to select a "Choice:". The choice can be abreviated to one or two characters. The intensity highlighting on the terminal shows which characters to input. The system will not let you input an invalid response. You may exit to DCL by typing EX at the "Choice:" prompt, or Control-Y at any time. You may return to the previous menu by typing Control-Z or pressing RETURN at the "Choice:" prompt. 5.7.1 Default File Types The system keeps track of the current name and type of the document being worked on. At the start, a default type of .RNO is assumed. Each time the menu is displayed, the current value of the default document name is shown. The default document name is used to simplify the input process. Once defined, all that is generally 5-6 THE VAX DOCUMENT PREPARATION SYSTEM needed when prompted for a name is a carriage return and the Document Preparation System will use the default document specification. Likewise, when the system prompts for a name it is never necessary to append a document type as the default type (.RNO) will be used. However, appending a document type is legal and will change the default type to the specified type. For example, if the default document type is .RNO, entering a JGD54 when a name is requested for editing will result in JGD54.RNO being edited. 5.7.2 The Phantom Directory In order to enable automatic deletion of documents following successful transmission to the NBI, a special phantom (and somewhat temporary) subdirectory is created which provides delete access for the world. Formatted output documents waiting transmission are placed in this subdirectory ([.NBI]). If all documents have been transfered from this directory, the VAX Document Preparation system may delete this directory, so do not place anything in it. Its use is reserved solely for the VPW system. 5.8 Document Preparation System Options 5.8.1 The ACtive Option ACtive There are two ways of viewing the contents of your desk. First one can look at all documents, junk and otherwise. This is done with the DIR command. Documents listed with the DIR command are on your desk, but they may not have been created by the Document Preparation System. Rather, they may have been imported from some other account and hence not be entered in the document index. The second way of viewing the contents of your desk is with the ACTIVE command. The Active command only lists those documents which are shown to be ACTIVE in the document index. Note that the ACTIVE command does not check to see if documents which are displayed as being active are indeed on your desk (account). 5.8.2 The ANalyze Option ANalyze Along with the Dennison University spelling checker, is a program which will analyze a document for English errors. After selecting a document, you are presented with a menu of options for checking that document. You can check for passive voice, deadwood phrases, sexist language, sentence beginnings, or spelling errors 5-7 THE VAX DOCUMENT PREPARATION SYSTEM and interactively correct text you do not like. 5.8.3 The Clean Option Clean Every time a document is edited, a new version of the document is created. After each editing session, the Document Processing System purges your documents to keep the most recent four copies of work in progress. Even so, if numerous documents are being worked on, your "Desk" can become cluttered with previous drafts of documents. Since desk space is always at a premium (and so is disk space) the Clean option can be used to delete all documents waiting for transmission to the NBI (.NBI documents) but not sent, and to remove all documents (.RNO documents) except for the latest versions. The Clean option has no effect on any other files in your directory. Users comfortable with using DCL can drop out of the Document Processing System at any time and selectively purge work in progress. After the Clean option is entered, the system prints a warning message and asks if you want to continue. Any response other than one starting with an upper or lower case "Y" will immediately return you to the Document Preparation Menu. The way the Clean option works with NBI documents deserves some mention. The formatted documents waiting for transmission to the NBI reside in a special subdirectory ([.NBI]) on the user's account. Only the .NBI type documents within this "Phantom" directory are deleted. After deleting all the .NBI type documents, the subdirectory itself is deleted. Now, when a document is created for transmission to the NBI, an entry is also made in a special index of documents awaiting transmission to the NBI, SYS$SYSVPWFILES:DOCXFER.IDX. So that the VPW system will not think these documents are still awaiting transfer, these entries in this index are also deleted. If an error message occurs saying that SYS$SYSVPWFILES:DOCXFER.IDX is missing, contact the system manager since this index file is required for successful transmission of the documents to the NBI. 5.8.4 The Create Option Create Before editing, a document must be created and entered into the system. Five types of documents are allowed: Letters, Memos, Papers Reports and Scratch. The Create option will automatically insert the proper document formatting control commands (for use by RUNOFF) so that the document will be properly formatted. The exact commands depend on the type of document being created, and the current pitch defined for the letter quality printer (SYS$LQ_PITCH_1) defined by the system manager. Formatting commands for either 10 or 12 pitch are automaticlly inserted. 5-8 THE VAX DOCUMENT PREPARATION SYSTEM However, pitch changes should be done infrequently (if at all) by the system manager since previously created documents will not reflect the pitch changes. The Create option keeps track of the last Memo or Letter number that was created and assigns one higher number each time you create a new document. Documents are named based on the document prefix you assign and a document number you input. The Document Preparation System keeps an index of all documents so that they can be retrieved easily. The document name, together with the topic of the document, the recepient, and the document type are filed in DOCINDEX.FIL, as appropriate. If you wish, you may enter in any document number when the system prompts for it. In the event that that document already exists, you are asked if you want to delete the old one and edit a new one with that number. If you don't want to delete the old document you are allowed to edit the old one and modify it. However, in this case no new entries are made in the document index. Scratch documents are special in that when one is created, no entry is made in the document index. At any time during the document's life cycle, the Document option can be used to modify the contents of the document index. However, for simple tasks, the Document Filer Menu handles most tasks in a manner transparent to the user. 5.8.5 The Directory Option Directory The Directory option displays all documents currently on your "Desk" and all documents waiting for transmission to the NBI (if any). Only the highest version number of a document is ever shown, so it is periodically necessary to use the Clean option to recover disk space. 5.8.6 The Edit Option Edit The first time a document is edited, the Create option should be used. Thereafter, use the Edit option. When the system prompts, enter the name of the document you want to edit. Since a default document type is always defined, you must enter only the document name. Entering a complete document specifier (name and document type) will result in the default document type being modified. The Edit option invokes the DEC standard editor (EDT) with a special initialization file so that text entry will start at the appropriate place and so that word wrapping is enabled. 5-9 THE VAX DOCUMENT PREPARATION SYSTEM 5.8.6.1 Guarding Against Errors - Errors If you are engaged in using the system and either run out of disk space or the system crashes, Do Not PANIC. Your work in Do Not PANIC progress probably can be saved if you report the problem at once. If an error occurs and you continue to use the system, you may eventually destroy all copies of the good versions of your documents leaving only the corrupted ones. If your disk allocation is so small that the editor will not let you exit, try issuing a QUIT/SAVE command. Whether the the command succeeds or fails, then get help. Do not Control-Y out of the editor. 5.8.7 The Exit Option Exit When done with processing a document, use the type Control-Z or simply RETURN. It will return you to the previous menu or the VAX command level depending on how the menu was entered. A Control-Y or EXIT can be used to return you directly to DCL. 5.8.8 The Filer Option Filer The Filer option invokes the Document Filer menu. Documents may be thought of as being either ACTIVE (on your desk) or FILED ACTIVE FILED away in a file folder. The Document Filer allows one to move documents in and out of file folders and to manage the Document Index. Specifically, the Document Filer menu allows one to: DIsplay - Display an index of past documents DI DOcument - Use The Document Manager DO Folder - List active file folders F Index - Index contents of file folder I Store - Store a document in a file folder S Recall - Recall a document from a file folder R Exit - Return to DCL E - Return to the previous menu PF2 / PF4 - HELP / New VPW Window PF2 PF4 5.8.8.1 The Document Filer Display Option - Display An index of all past documents is kept in DOCINDEX.FIL on your current VAX directory. The Display option can be used to display the documents in that index. You are prompted for a search string. A carriage return will result in all documents being displayed. A control-Z will return you to the main menu. If something is known about the document (document type, to whom, subject, etc) a search string (or multiple 5-10 THE VAX DOCUMENT PREPARATION SYSTEM search strings separated with "|"s) can be entered to display only part of the index. 5.8.8.2 The Document Filer Document Option - Document The Document option allows one to access the document index directly. Entries can be added, deleted or modified. The index can be searched for topics or keywords, and the results displayed either on your terminal or printed on the line printer. The document index represents a log of all documents processed by the Document Processing System. Where reasonable, the index tracks the status of the document. When a document is filed, the index is updated to show where the document is. However, some documents are just printed, filed in a regular file cabinet and thrown in the wastebasket. These documents will still appear in the index as a log of when they were written, to whom they were sent, and the topic. If it is desired to eradicate all traces of the document, the Document option must be used to delete the document. The Document option uses the VAX NoteBook utility to maintain the document index which is discussed in subsequent chapter. Perhaps the most useful feature of Document option is the ability to search the document index for selected topics. For example you could produce a list of all documents in a certain named file folder, or a list of all documents sent to a person relating to a given subject. 5.8.8.3 The Document Filer Index Option - Index The Index option allows you to see the Index of a specific file folder so that you can tell what document names are stored in that folder. When invoked, it requests the name of a file folder. If you input a valid name, it displays the current contents of that folder in a formatted fashion. If the name is invalid, it warns you and prompts to see if you wish to see a list available file folders. When the Index option prompts for a name, a single "?" (followed by a carriage return) will also display a list of available file folders and again prompt for a name. 5.8.8.4 The Document Filer Recall Option - Recall The Recall option lets you remove a document from a file folder and place it in active status. You may not retrieve a document from a file folder if an active document of the same name is on your desk. If the desired document is not on your 5-11 THE VAX DOCUMENT PREPARATION SYSTEM desk, you may choose either to extract the orignial document or make a copy of it. If the original document is removed from the folder, the active document on your desk becomes the only copy of that document. If you request a copy of the document in the folder, the original copy of the document in the folder is retained. When the Recall option prompts for input (document name, file folder name), a "?" will produce either a listing of your ACTIVE documents or an index of the available folders. 5.8.8.5 The Document Filer Store Option - Store When the document is no longer being actively used, it is useful to place the document in a file folder. Not only is your "Desk" less cluttered, but the one or two disk blocks are saved for each document placed in a folder. The file folders are VMS Text Libraries, but this should be transparent to users. The Folder option displays all currently active folders. You can store and retrieve documents only from currently active folders. When a document is filed away in a file folder, the document index is updated to reflect its new location. At any time, you can search your index (Display option) to see where a document is. The Store option prompts you for the name of a document to store, the name of a file folder to use, and whether or not to store the original or a copy of the document. If either the document or folder name is not known, a "?" may be entered to display a list of active documents or folders, respectively. If the document name does not exist, a display of current documents is produced. If the folder does not exist you are asked if a folder with the new name should be created. At the prompt for the folder name, you have the option of just hitting carriage return and using the default folder name (it will have to be created the first time you use it.) Great care has been taken to insure that important documents are not inadvertantly destroyed. You are not allowed to place a document in a folder if a document of the same name is already there. You must either not place the document in that folder or agree to overwrite the existing document. When placing a document in a file folder, you either place the original document or a copy there. If the original is placed there, the original ceases to exist on your desk. If a copy is placed there, the original document is still left active on your desk. 5-12 THE VAX DOCUMENT PREPARATION SYSTEM 5.8.9 The Kill Option Kill The Kill Option can be used to stop ("Kill") a print job. When invoked it prompts you for a job number. If you do not know the number, enter a question mark ("?"). It then will use QD to produce a formatted display of all print jobs in the queue, and then prompt you for the number of the job to kill. 5.8.10 The Modify Option Modify The Modify option is used if you wish to change any of the default parameter settings for use by the Document Filer. These settings include the default file folder name, the default prefix name for memos and letters, and the default name for the sender. The first time the Document Filer is used, these parameters are prompted for. Thereafter, the Modify option can be used to change these parameters. When modifying parameters, a return leaves the current entry alone. 5.8.11 The Print Option Print The Create option automatically places format control commands in the document. The Print and View options will use these embedded control commands to format the document for output. Output may either either be displayed on your terminal, sent to the line printer, or the letter quality printer. All other output is automatically deleted after printing. One option the system gives you is to print only a range of pages. This option should be selected only if you do not need to format the entire document. This can happen if a minor correction was done on one page of the document which didn't change the pagination. In this event, it is faster to format only the modified page, print that page, and merge it with the previously printed pages. If, during the course of answering questions for the Print option an error is made and it is desired to give up and return to the main menu, type Control-Z. 5.8.12 The Spell Option Spell The Spell option will check the user's document for spelling errors using the Dennison University Spelling Checker utility. The spelling program is rather complex and has considerably more options for use than used by VPW. The interested user is directed to the documentation on this program and the English Analysis 5-13 THE VAX DOCUMENT PREPARATION SYSTEM program on the Decus [VAX83C.DENNISON] directory. Each user can have a private dictionary (DEFAULT.WRD) of words not normally recognized as correctly spelled words (names, places and technical words) which would otherwise be flagged as incorrect. If a user does not have such a file on their document processing account, a private dictionary will be created (from the system default dictionary) the first time the spelling program is used. The Spell Word option on the main menu can be used to add words to this private dictionary. The Document Processing System can check for spelling errors in two ways, interactively or batch. In interactive mode, SPELL will inform you of each suspect word as it is encountered and give you the option to change it. If you elect to change it, it will drop you into EDT in a section of text containing the offending word and allow you to change that word. When you exit any changes made are merged into a new, corrected document. In batch mode any errors or suspicious words found will be displayed on the screen in a formatted manner. After each run of the spelling program, a document SPELLING.ERR is created listing all errors. It may be used to include into the file being checked a listing of all the errors. The spelling program is not perfect. It misses spelling errors, does not catch words which are spelled correctly but are the wrong word for the context, and sometimes flags correctly spelled words as being incorrect. Be warned. Perhaps, be thankful -- people are still useful. 5.8.13 The Spell Word Option Spell Word The Spell Word option will allow you to add words to your private dictionary word file, DEFAULT.WRD. The format of the private dictionary word file, is one upper case word per line. The list of valid words is terminated with a "[". Words the system does not think are valid follow the "[". When you invoke the Spell Word option, the system will prompt you for words to add, one word at a time. When you are done, type a carriage return. Your new words will then be merged with your existing dictionary (if any) and the system dictionary (if any) into a new verion of DEFAULT.WRD. Your old dictionary will be purged. At this time the only way of correcting an incorrectly spelled word is to use the editor to edit DEFAULT.WRD and remove the offending line. 5-14 THE VAX DOCUMENT PREPARATION SYSTEM 5.8.14 The Transmit Option Transmit or alternatively formatted for transmission to the NBI word processor. The document type for output formatted for sending to the NBI is .NBI. NBI formatted documents will be automatically deleted folowing transfer. Documents for transmission to the NBI are created on a special, "Phantom," subdirectory [.NBI] which has NO protection. . NO Any document in this subdirectory can be deleted by ANYONE. You ANYONE must not place documents in this subdirectory. It is used only by the VPW System. When documents are created for transmission, an entry is also made in SYS$SYSVPWFILES:DOCXFER.IDX specifying the file name for transfer, and the user's name (Logon name) requesting the file be transfered. This index file is used by the VAX Professional Workstation to simplify transmission of documents to the NBI. If you get an error message saying the file is missing, contact the system manager at once. Document transmission cannot take place until this index file exists and the document to be transfered is entered in it. 5.8.15 The View Option View The View option will display a formatted document at the user's terminal. It provides a simpler access to getting formatted output to the terminal than the Print option. If the document type is .RNO it formats and displays the document. Otherwise, it displays the document without formatting. 5.8.16 The Wastebasket Option Wastebasket The Wastebasket option is used for permanently destroying a document. When invoked, the Document Preparation System will display all unfiled documents and prompt for which files are to be deleted. All copies of a document selected for the wastebasket are destroyed. 5-15 CHAPTER 6 THE VAX PHONEBOOK SYSTEM 6.1 Introduction The VAX PhoneBook System is implemented as a VAX NoteBook function. PhoneBook is accessed either as a foreign command (defined automatically by @SYS$SYSVPWFILES:SETVPWSYM.COM during the logon process), or via the VAX Professional Workstation. In addition the commands PLIST (for phone list), ALIST (for address list), and MLIST (for mailing list) are also defined which can be used to in the following way: PLIST Enter interactive mode with PhoneBook. PLIST search_string Display all phone numbers belonging to entries with the specified name_string. ALIST search_string Display all phone numbers and addresses belonging to entries with the specified name_string. MLIST search_string Display addresses in mailing-list format. The following sections describe briefly how to use the various features of the VAX PhoneBook 6.2 Retrieving An Address If the symbol ALIST is defined as a foreign command, the command ALIST search-string will produce the output (if the search string is found) of the form Last_name,First_name Phone # Ext Comment Company Address City, State Zip The Search-String may either be a last name or part of one or any 6-1 THE VAX PHONEBOOK SYSTEM valid unique identifier. If more than one entry match the search input all such entries will be displayed. For example, ALIST Downward might display Downward, James (313)-769-8500 362 Resident DEC guru. KMS Fusion, Inc. 3941 Research Park Dr. Ann Arbor, Mi 48106 6.3 Retrieving A Phone Number If the symbol PLIST is defined as a foreign command the command PLIST search-string will produce the output (if the search string is found) of the form Last_name,First_name Phone # Extension Comment The Search-String may either be a last name or part of one or any valid unique identifier. If more than one entry match the search input all such entries will be displayed. For example, the command PLIST DOWNWARD might produce the output Downward, James (313)-769-8500 362 Resident DEC guru. Note that the search string could also have been DEC or James and this record (with possibly others would have been displayed). 6.4 Interactive Use In its interactive mode, PhoneBook displays a menu giving the user the option to: 1. Add new phone numbers to the list. 2. Display phone numbers/addresses 3. Delete phone number entries. 4. Modify an existing phone number 5. Use a different PhoneBook 6. Exit. Because the VAX PhoneBook system is implemented using the VAX NoteBook, the chapter on using the VAX NoteBook should be read. Interactive mode of the VAX PhoneBook is very easy and friendly to use. At each point that it it requesting input, you can use the keypad keys to get help. The PF1 key will display the keypad 6-2 THE VAX PHONEBOOK SYSTEM layout, and the PF2 key will display help information appropriate to the input being requested. The other keypad keys are described in the chapter on using NoteBook. 6.4.1 Adding An Entry To The PhoneBook When you enter ADD mode PhoneBook prompts for the following information: Last name 15 characters max First name 10 characters max Phone number (xxx)-nnn-mmmm 14 characters max Extension (xxxx) 4 characters max Company name 20 characters max Address 30 characters max City 15 characters max State 2 characters max ZIP 5 characters max Comment 40 characters max If the length of an input exceeds the maximum allowed length, PhoneBook will print a warning message and reprompt for input. If a RETURN is entered in response to the last name entry request, PhoneBook returns to the menu page. When an entry is completed, PhoneBook will display the entry in its entirety and ask if it is correct. If a Y[es] is answered, it will be entered in to the data file. A N[o] returns you to the 'Last Name:' input prompt. The Comment entry allows up to 40 characters of any additional information to be entered for each user. 6.4.2 Deleting A PhoneBook Entry In Delete mode, you are prompted for the last name of an entry to delete. Each entry which matches the entered last name will be displayed together with a prompt asking if that entry should be deleted. If a Y[es] is answered the entry will be deleted. A Y during the delete process will wipe out all deletions made. All deletions become permanent if a RETURN is entered in response to the 'Last Name:' prompt. Deletion is much slower than adding or displaying entries since the entire file must be searched and re-written. 6-3 THE VAX PHONEBOOK SYSTEM 6.4.3 Displaying Phone Numbers Or Addresses In Display mode, the you enter a last name to display and choose whether or not to display the addresses also. Three display modes are possible: Phone list format, address list format, and mailing list format. The name string entered can be just the desired last name, part of the last name, a unique search string (ie a company name) or some combination of search strings, each separated by a vertical bar ("|") from the other search strings. Finally, you have the option of either displaying the information on your terminal, sending it for printing on the line printer, or saving it to a scratch file (SCRATCH.FIL) for inclusion in a document. 6.4.4 Modifying A PhoneBook Entry In Modify mode, first you enter the last name to search for the correct record. The record is displayed and you are allowed to select that record or reject it. If you reject it, another record is searched for and the process is repeated until no more records are found matching the search string. If the record you want is found and selected, you are allowed to change each field by entering new data, or leave the field alone by typing carriage return. As the record is modified, the changes are displayed on the bottom of the screen. When the modifications are done, you are prompted to confirm that the modifications are correct. If you accept them, the record is updated and sorted if you changed the last for first name. 6.4.5 Use A Different PhoneBook Normally PhoneBook accesses SYS$LOGIN:PLIST.FIL. If you have a specialized list of phone numbers or addresses in an alternate PhoneBook file, it can be accessed with the Use option. Be careful U that any file entered with the Use option is a correct PhoneBook U file and not one created for use with some other NoteBook function. 6.4.6 Exiting From PhoneBook If numbers have been added to the phone book, PhoneBook will sort the phone book list upon exiting. This takes a while. Be patient. Otherwise it will just close any open files and exit. 6-4 THE VAX PHONEBOOK SYSTEM 6.5 Use Of Search Strings When used to display phone numbers or addresses, PhoneBook either accepts a search string as part of the command line or prompts for a last name. At this point, either a simple last name (or part of one) or a complex search string may be entered. A complex search string consists of multiple search strings separated by vertical bars ("|"). For example if you know your phone book contains entries for several people named Smith and that the SMITH of interest works for KMS you might enter SMITH|KMS as the search string. Only the data for the entry with the last name Smith, and with the company KMS would be found. Likewise to list all people working for the same company (you forgot the person's name), enter the company name as the search string. 6.6 The PhoneBook Data File The data for PhoneBook is kept in SYS$LOGIN:PLIST.FIL. SYS$LOGIN is the VMS symbol representing the home directory assigned to each user when they log on to the system. Alternate PhoneBook data files may be accessed via the Use option. U 6-5 CHAPTER 7 THE VAX REMINDER SYSTEM 7.1 Introduction Very often it is necessary to remind yourself or someone else that there is a date to be met or something which must be done. Before there were computers the canonical way of remembering to do something was to tie a string around one's finger. Later improvements in information storage technology allowed people to write themselves paper messages to leave pasted on their doors, desks, walls, etc. The problem with this method is that one had to leave the reminder where the person was sure to look and hope that the message looked sufficiently attractive or urgent that it would be read. For users who have office VAX terminals, the VAX Reminder System offers a paper free alternative. The limitations of the method are that the user will not get the reminder if he/she is not logged on to the VAX. The VAX Reminder system allows each user to leave reminder messages for themselves or others which will be posted at the specified date and time. The VAX Reminder system can be accessed in a number of ways. It is available as an integral part of the VPW system as part of the Desk Management menu. REMINDER can also be accessed as a foreign command which is established by the system each time a user logs on by the command file SYS$SYSVPWFILES:SETVPWSYM.COM. Once the command REMINDER is typed, the REMINDER screen is displayed, and REMINDER prompts for a user name to send a reminder to. 7.2 On-Line HELP If you need help using REMINDER, press the PF2 key at any point REMINDER is prompting for input. REMINDER will then display help information pertaining to the information it is requesting. The PF2 key is the standard VPW help key. It is the only operational VPW keypad key at this time. 7-1 THE VAX REMINDER SYSTEM 7.3 Correcting Errors If you make an error in an entered quantity and notice it only after you have gone on to the next question, you can either back up to the previous question by typing the Up Arror key, or enter Control-Y or Control-Z to abort the operation. 7.4 Using REMINDER After issuing the REMINDER command, REMINDER will prompt for someone to remind. If you type carriage return, it defaults to reminding the person logged on the the terminal on which it is running. It will check to see if the VAX knows the person you requested to remind. If it doesn't it will warn you and allow you a chance to remind someone else. If you are unsure of the allowed names of users on the system, it will display a list of all name which it can send reminders to. Assuming the "Remindee" is a VAX user, REMINDER will prompt for the date and time to remind the user and then allow you to input up to 80 characters of text to use as the reminder message. Finally REMINDER asks if you want to send off another reminder to the same person. This allows you to be a nag, and send off reminders scattered throughout some time period. If you do want to send the same person another reminder, REMINDER checks to see if you want to send the message on the same day. If yes, it then prompts for the time to remind and reminder text. If no, it firsts prompts for a reminder date. When the appointed time comes due, REMINDER will start up, grab the message and fire it off to each and every terminal the 'Remindee' is logged on to. If you are not logged on to a VAX terminal when the it attempts to deliver the message, it MAILS the message to you. Hence, as soon as you log on the VAX, VMS MAIL will tell you that you have new mail waiting to be read, and if you read your mail, you will get the reminder (so you will know what you missed). 7.5 System Requirements For the Reminder System to work, the following files must exist. SYS$SYSVPWFILES:BROADCAST.EXE Install with OPER, WORLD privilege SYS$SYSVPWFILES:REMINDER.EXE Install with SYSPRV privilege SYS$SYSVPWFILES:REMINDUSR.COM For dequeuing the reminder messages 7-2 THE VAX REMINDER SYSTEM The REMINDER command requires that the REMINDER image be installed with SYSPRV if it is to be used by all users. 7-3 CHAPTER 8 THE VAX ELECTRONIC MAIL SYSTEM To Be supplied 8-1 CHAPTER 9 THE GRAPHICS WORKSTATION MENU 9.1 Accessing The Graphics Workstation Menu The Graphics Workstaton Menu is invoked in a number of ways. It can be directly accessed from any meny via the GRFmaster command GRF (automatically defined at login). It also can be accessed on VT100 terminals from the Research Assistant Menu, or on Tektronix 4014 terminals from the main menu. 9.2 The Main Menu The Graphics Workstation main menu is the dispatcher for a variety of graphic applications. The menu will appear either on a VT100 compatible or Tektronix 4014 terminals. On a VT100 class terminal the following menu appears. VPW Graphics Workstation VPW Graphics Workstation Graph file: Not Set Not Set You may choose: Convert - Convert graphics data file formats C EDit - Create/Edit a graphics data file ED Fit - Least squares fit data F Graph - Graph a data file G Viewgraph - Create presentation viewgraphs V EXit - Exit menu and use VAX directly EX - Return to the main menu PF2 / PF4 - HELP / New VPW Window PF2 PF4 At the top of the display, the current name of the initial graph data file being worked on is displayed. Initially the file name is NOT SET. The file name is set when either graphics data is NOT SET selected for editing or for graphing (via Datatrieve or TekGraph), and thereafter can be used as a default answer to file name prompts. 9-1 THE GRAPHICS WORKSTATION MENU The display on a Tektronix 4014 terminal is slightly different. On 4014 terminals the TAB option to use a graphics tablet appears and PF2 / PF4 option to request HELP or a new VPW PF2 PF4 window does not. However, the Tab option only works correctly with the terminal connected to the graphics tablet. On other 4014 terminals the program will start up but can not work. The output of TAB will be a data file, GRAPH.DAT, which then becomes the default graphics data file name displayed in the main menu. The first option is to Convert a graphics file between C formats. Different utilities such as DECalc output data in a variety of ways which are generally not compatible with the KMS canonical X-Y data file format. This option provides access to utilities which have been developed to convert between formats and to transpose X and Y data values. The next option is to EDit a graphics file. This option ED allows one to either create a new X-Y graphics data file, or modify an existing one. While many forms of graphics data files are possible, the editor only supports the X-Y graphics data format produced by the graphics data tablet program or by programs for use with our Tektronix Plot-10/Advanced Graphics software. The data file format is documented in the chapter on using TekGraph. The EDit option automatically invokes either the X-Y Graph ED Data Editor for VT100 terminals or PLOTedit for Tektronix 4014 terminals. PLOTedit is a line mode editor suitable for 4014 or hardcopy terminals. The X-Y Graph Data Editor is another NoteBook function. It allows X-Y data files (in our canonical data format) to be created, edited, and displayed. It provides a spreadsheet like ability to move a window through an set of X-Y data, inserting, adding, modifying, or deleting data as required. Its use is documented in a later section of this chapter. The Fit option allows one to do simple curve fits to linear F polynomials, and first order exponential and power series equations. The Graph option provides users with access to three programs G which can be used to display graphic data, DECgraph, TekGraph, and Datatrieve. The format of DECgraph data files is unique to DECgraph (ie not the cannonical X-Y format), but for completness (and eventual integration with Datatrieve and DECalc) access to DECgraph is provided from this menu. Access to TekGraph and DTR are also provided for plotting X-Y data. Details of the Graph G options will be discussed later. The PF2 key or HELP key uses VMS HELP to prompt the user for what help information is desired. 9-2 THE GRAPHICS WORKSTATION MENU The Viewgraph option allows users to prepare presentation V viewgraphs. The viewgraphs are produced on either 4014 terminals or VT240 terminals using TVG. Optionally, users on VT100 terminals may rapidly design prototype viewgraphs (for eventual use with TVG) using the TVG Maker procedure. The use of the Viewgraph option V (TVG and TVG Maker) is documented in a subsequent chapter on "Generating Presentation Viewgraphs". 9.3 Using PLOTedit PLOTedit is invoked automatically, if the EDit option is ED selected and the terminal is not a VT100 compatible terminal. It also may be invoked by the command $UTL PLOTEDIT. When invoked the following appears PLOTEDIT Version 2.0 110483 Type H for HELP PLOTedit> Entering a "H" at the PLOTedit> prompt, produces a listing of available commands. Plot Commands: E - Edit a plot file. H - Print this text. R - Read a plot file. W - Write a plot file. EX - Stop the PLOT program. PLOTedit> The EXit command or Ctrl-Z can be used to exit from PLOTedit. 9.3.1 The Edit Command The edit command allows the values in a graphics data file to be modified. PLOTedit requires that the data file exist prior to editing it. If needed, the Write command may be used to create the file. When the edit command is invoked, PLOTedit will prompt for a file name. After entering a valid file name, PLOTedit displays the first X-Y data pair in the file and prompts for a command with a ">". PLOTedit> E Edit a plot file. Enter the plot file name: GRAPH.DAT Coordinate: 1 X coordinate: -0.21288, Y coordinate: 1.32273 > 9-3 THE GRAPHICS WORKSTATION MENU Entering a "H" at the ">" prompt displays a list of valid editing commands. Edit commands: A - Append coordinates AFTER the displayed coordinates. C - Change the displayed coordinates. D - Delete the displayed coordinates. E - Exit the editor. (Save the changes) H - Print this text. I - Insert coordinates BEFORE the displayed coordinates. J - Jump over coordinates. Q - Quit the editor. (Do not save changes) RETURN - Go to the next coordinates. Coordinate: 1 X coordinate: -0.21288, Y coordinate: 1.32273 >Q PLOTedit> Every time the RETURN key is pressed, the next X-Y coordinate pair in the file will be displayed. Motion through the data file occures in only the forward direction. The EXit command will write the changes made back to the specified filename. The Q command will exit to the PLOTedit> prompt without making any changes. The Jump command repositions the pointer to a higher coordinate point in the file. Once at the appropriate coordinate point, the data may be modified (the Change command) or new data may be added after that point (the Append command) or inserted before (the Insert command) the existing data point. The Delete command removes the currently displayed coordinate pair from the data file. When the A, C, or I command is invoked, PLOTedit will issue a ">>" prompt and request an X-Y data pair which should be entered as two floating point numbers separated with a comma. If data is entered, when the EXit command is invoked, PLOTedit will overwrite the modified data onto the specified data file. A new version of the file is not created, so be careful. 9.3.2 The Read Command When the Read command is selected, PLOTedit prompts for a file name. after entering the name, it displays the data in the file from first to last point and then prompts for a new command. 9-4 THE GRAPHICS WORKSTATION MENU 9.3.3 The Write Command The Write command allows one to create a new plot file. When invoked PLOTedit first prompts for a file name. Next it prompts for the number of points, N, to be entered. Each data pair is entered as an X-Y data pair with the two numbers seperated with a comma. When the N points are entered, PLOTedit, will write out the data file and return with the PLOTedit> prompt. Entry of data points can be terminated before all N points are entered by entering a Ctrt-Z at the prompt. 9.4 Using The X-Y Graph Data Editor When one selects the EDit option on a VT100 compatible ED terminal, first the Graphics Workstation prompts for a graphics data file name. Graphics data files have an extension of ".DAT" by default. If a file type is explicitly entered at the prompt for a file name, that file name becomes the new file type for subsequent use. If one does not know the name of the file, entering a "?" will display a directory of all files with the current default file type. After entering the data file name, the X-Y Graph Data Editor menu appears. X-Y Graph Data Editor X-Y Graph Data Editor (Type Ctrl-Y to exit at any point) You may choose: Display - Display data D EDedit - Edit data ED Use - Use a different data file U Exit - Exit E Choice: The X-Y data editor is based on the VAX NoteBook, so the menu format should be familiar. One is allowed to either display the data in the file, edit an existing file (or create one if none alread exists), or select a different data file name. From this menu the PF2 (or HELP) key will display help information, and the PF4 (or F20) key will bring in a fresh window (VPW command page) for the user to use to communicate with DCL. 9-5 THE GRAPHICS WORKSTATION MENU 9.4.1 The Display Option If one chooses to display the data (Display), the contents of D the current default file are displayed. First the title of the file (if any) is shown, followed by the number of data points in the file (the maximum allowed is 600). Following this, the point number, the x-value, and the y-value are displayed in columnar fashion within a window below the data file information. Pressing any key while the data is being displayed will cause terminate further output of the data to the terminal. When the data has finished being displayed, a message saying to "Press RETURN when ready" will appear. When RETURN is pressed, the Editor menu will appear. 9.4.2 The Edit Option When the EDit option is selected, the current title of the ED graph will be displayed (if any), and the cell pointer will be positioned at the start of the data. To position the cell pointer to some other place in the file, use the GOTO key on the keypad. Actual data entry occurs at the bottom of the screen (Enter value: ) with the data being entered into the highlighted cell pointer when RETURN is pressed. The highlighted cell pointer can be positioned with the arrow keys to select the data one wants to modify. Each time RETURN is pressed (but no data entered) on an X-value cell, the cell pointer is positioned to the next available cell. This continues until the cell pointer is positioned over the last available (and empty) cell in the file. If RETURN is pressed here, the screen is erased and the user is given three choices; to update the data file (answer Y"), not to update the file (answer "N"), or continue (answer "C"). If one chooses to update the file, the new data is output to the existing file (with one higher version number) and the obsolete file is deleted if the update was successful. If one chooses not to update the file (enter anything but "C" OR "Y"), any changes made are lost. If one did not realy want to stop entering/modifying data, enter "C" for continue, and the screen will be repainted and the data entry cell will be repositioned at the first data pair. With the cell pointer positioned over a value one wants to change, one need only enter a new value and the value in the cell will be replaced. Each time data is entered, the cell pointer will automatically move to the next logical place for entering data. If the data being entered is an X-value, after data entry, the pointer will move to the associated Y-value. After a Y-value is entered, the pointer will move to the next available X-value. 9-6 THE GRAPHICS WORKSTATION MENU The keypad can operate in two modes, FUNCTION and NUMERIC. The definitions for the function keys PF1, PF2, PF3, and PF4 are identical for both FUNCTION and NUMERIC mode. However when the keypad is in NUMERIC mode, the other keypad keys are interpreted as standard data entry keys (ie, 0,1....9) rather than performing specific functions. When the edit mode starts up the keypad is initially in FUNCTION mode. The keypad layout may be displayed at any time for either mode by pressing the PF1 key (Display Keypad). The keypad for FUNCTION mode is shown in Figure 1. The PF2 key will display help information. The PF3 key is used to toggle between the FUNCTION and NUMERIC keypad modes. When pressed, a bell will sound when the keypad shifts into NUMERIC keypad mode. When the PF3 key changes the keypad back to FUNCTION mode (default mode), no bell sounds. On VT100 keyboards LEDs 1-4 all light when the keypad is in FUNCTION mode (the default) and turn off when in numeric mode. Depending on the mode the keypad is in, the PF1 key will display the corrrect keypad diagram for either the FUNCTION or NUMERIC mode. The Quit key (key 7 if in FUNCTION mode) will abort all editing changes and return to the Graph Data Editor menu. When this happens, the original copy of the graphic data file is left intact. The Done key, will terminate data entry and prompt you to see if you realy want to update the data file. If the answer is "Yes", a new data file with modified values is written out. If the answer is "No", the changes made will be lost. If the answer is "Continue", editing will resume at the first data element. Each X-Y data point is associated with a point number from 1 to 600. The Goto key allows the data entry cell pointer, to be positioned rapidly to any point in the data file (the arrow keys could also be used). When the Goto key is pressed, the editor prompts with Goto:. Entering a value larger than the last data value in the file, will position one at the bottom of the file. ------------------------- ----------------------------- ! ^ ! ! ! ! ! ! PF1 ! PF2 ! PF3 ! PF4 ! ! ! ! V ! <-- ! --> ! !Disply! ! ! ! !Back ! Fwrd! Left!Right! !KeyPad! HELP !Toggle! VPW> ! ------------------------- ----------------------------- ! ! ! ! ! ! Quit ! ! ! Done ! ! ! ! ! ! ----------------------------- PF3 Toggles keypad in/out of ! ! ! ! ! keypad application mode. ! Goto ! Insrt!Delete! Title! ! ! ! ! ! ----------------------------- VT100 LED's 1-4 light when in ! ! ! ! ! keypad application mode. ! ! ! ! E ! 9-7 THE GRAPHICS WORKSTATION MENU ! ! ! ! N ! VT2xx Bell -> Move to numeric ---------------------! T ! mode. Quiet -> move to ! VPW ! ! E ! keypad application mode. ! Main ! ! R ! ! Menu ! ! ! ----------------------------- Figure 1. The Insert key allows one to insert a new X-Y data pair in front of the current cell pointer. If the current cell pointer is at X-Y pair N, pressing the Insert key will position that X-Y pair to point N+1, and prompt for you to enter a new X-Y data for pair N. Likewise, the Delete key will delete the X-Y data pair currently under the cell pointer. When the current X-Y pair is deleted, subsequent points are shifted so that pair N+1 now becomes pair N in the file. Each graph data file has as its first record an optional title line. Pressing the title line allows one to enter text for this title (or remove or modify an existing title). The title can serve as a useful reminder as to what data is in the file. 9.4.3 The Use Option When the Use Option is selected, the name of the current U default data file which will be edited is displayed and the user is prompted to enter a new file name to work on. If the user types RETURN, the name of the default file is left unchanged. 9.5 The Fit Option The Fit option allows one to do simple curve fits to equations F of the form B 1 n Y=A exp(Bx), Y=A x, and Y=A +A x +....+A x 0 1 n .lit It will allow one to select the type of fit, the degree, n, of the polynomial to fit (if a linear fit is selected), display statistics as to the goodness of fit, allow one to graph the results for a selected number of interpolated points, and output the fitted curve to a data file (CURVEFIT.DAT). When invoked it checks to see if the default graph file has been already set from some previous workstation operation. If it has, it uses this 9-8 THE GRAPHICS WORKSTATION MENU data file as the default when it prompts .lit Input data file name ( -> ^*default_name\*): If no data file name has been defined, the prompt will be Input data file name: A control-Z to any prompt will return you to the choice prompt of the Graphics Workstation. At the "data file name" prompt, the default file name type .DAT is assumed and need not be entered. .DAT Once a name (and optionally type) is entered, this name becomes the new default file name for the graphics workstation. Once the data file name is entered, the routine prompts for the type of fit to use (Exponential, Linear Polynomial, or Power). The form of each equation to be fitted is displayed. If Linear Polynomial is used, the order of the polynomial to be fitted is prompted for. It may range from 1-10. The fit is then calculated, and the fitting coeficients and the goodness of fit parameters are displayed. Next the routine gets ready to plot the fitted curve against the calculated data. The routine prompts for the number of points to interpolate for the fitted curve and asks if the fitted curve data points should be output to CURVEFIT.DAT. The user may enter a number of points to interpolate ranging from a minimum corresponding the the number of points in the original data file up to a maximum of 600 X-Y pairs. The graph is then displayed and remains on the screen until the user presses RETURN and is returned to the Graphics Workstation menu. 9.6 The Graph Options When the Graph Option is selected, a secondary menu appears. G Select Graph Program Select Graph Program You may choose: DECgraph - Use DECgraph DE DTR - Plot data via DTR32 DT Tek_Graph - Use TEKGRAPH to plot existing data T Choice: 9-9 THE GRAPHICS WORKSTATION MENU 9.6.1 DECgraph Option The DECgraph option provides an interface into DECgraph. The DE interface is limited, at this time, to just invoking DECgraph. At a future time it is hoped to provide the ability to convert files between DECgraph and TEKgraph. DECgraph only works on ReGIS mode terminals. Because DECgraph has the habit of leaving terminals in wierd configurations, VPW resets the terminals characteristics after using DECgraph. 9.6.2 The DTR Option Datatrieve is able to plot data on VT125/VT240 type terminals. While it is far slower to plot data using Datatrieve rather than using TEK_Graph, in some ways it is simpler in that the user has fewer options which must be supplied to produce a finished graph. Another possible reason to use the DTR option, is that it is DT possible to use DTR to create an output file of X-Y data pairs (real X, real Y) which is not in the cannonical form expected by TEK_Graph. However, the Graphics Workstation checks each data file to see which format the file is in (cannonical TEK_Graph or simple X-Y) and sets Datatrieve to use the data correctly (Note, the X-Y Graphic Data Editor will not work on this form of data file). Initially, Graphics Workstation prompts for a data file name. If the name is not known, a "?" will produce a formatted list of available graphic data files. If a default file has been set by previous work, it will appear in bold and a RETURN will select it. Next the Graphics Workstation prompts for both an X and Y title for the graph. Once a title is set, it becomes the default for subsequent work. Next a list of available plot types is displayed. Available Plot Types LINE Scattergraph with connecting line LR Least squares linear fit to data LOGX-LOGY LOG-LOG plot LOGX-Y LOGX vs Y plot X-LOGY X vs LOGY X-Y X-Y scattergraph Plot type: If either the LINE or LR option is selected, a message saying that a plot type (X-Y, or LOG) must also be selected. Once the plot type is selected, Datatrieve is invoked to read the data and plot it. A message will appear stating the number of records found and shortly thereafter the plot will appear. When you are finished looking at the plot, press RETURN and the Graphics Workstation will prompt for another file to plot. 9-10 THE GRAPHICS WORKSTATION MENU 9.6.3 The TEK_Graph Option If TEK_Graph is selected, the user is prompted for a graph file name. If a current data file has been previously set as the default file it will be displayed in bold (on VT100 compatible terminals) and typing a RETURN is all that is needed unless it is desired to use a different data file. Detailed information on TEK_Graph is supplied in a subsequent chapter. Some care must be used in the naming conventions for data files. First off, to retain compatibility with the original GRAPH program (See the TEK_Graph chapter) the file name GRAPH.DAT is handled in a special way. Consequently, when Graphics Workstation prompts for a file name, if GRAPH.DAT is entered, TEK_Graph will also prompt for the file name (displaying the default name of GRAPH.DAT). If, however, only the name GRAPH is entered at the Graphics Workstation prompt, TEK_GRAPH will still default to using the name GRAPH.DAT, but it will not prompt for the file name to use. TEK_Graph uses (and creates) control files to produce complicate plots. The Graphics Workstation procedure assumes that each data file name (which has a default type of .DAT) may also have a control file of the same name but with a type of .CTL. It checks for the existance of a control file, and if it exists, asks if it is to be used to plot the data. If it is, the workstation procedure invokes TEK_GRAPH specifying the control file name and no further input is required until the graph has been completed. At that time, a RETURN will bring back the Graphics Workstation prompt for a file name to graph with TEK_Graph. If, however, a control file does not exist, TEK_Graph will prompt to ask if a control file should be created. In some cases, data files with a specified name do not exist but control files exist which specify (internally) the names of the data files to be used. In this event, if no data file exists with the specified name (entered at the Graphics Workstation prompt), but a control file of the form .CTL exits, the Graphics Workstation will ask if you want to plot the data using that control file. If the answer is yes, the data is plotted. If the answer is no, a message saying the specified data file does not exist is displayed and Graphics Workstation again prompts for a data file name. On returning to the main menu, after using TEK_graph, the default graph file name will be set. It becomes the default data file for further use of the Graphics editor, or graphic operations. 9-11 CHAPTER 10 TEKGRAPH USERS MANUAL 10-i TEKGRAPH USERS MANUAL Table of Contents 1.0 Introduction . . . . . . . . . . . . . . . . . . . . 2 2.0 Differences Between GRAPH And TEKGRAPH . . . . . . . 3 3.0 Use Of TEKGRAPH . . . . . . . . . . . . . . . . . . 6 4.0 Interactive Use Of TEKGRAPH . . . . . . . . . . . . 7 5.0 Graphics Data File Format . . . . . . . . . . . . . 8 6.0 Graph Control File Format . . . . . . . . . . . . . 9 7.0 Command File Commands . . . . . . . . . . . . . . 10 8.0 AG II Command File Options . . . . . . . . . . . . 11 8.0.1 BINITT . . . . . . . . . . . . . . . . . . . . 11 8.0.2 CHECK . . . . . . . . . . . . . . . . . . . . 11 8.0.3 DSPLAY . . . . . . . . . . . . . . . . . . . . 11 8.0.4 CPLOT . . . . . . . . . . . . . . . . . . . . 12 8.0.5 FRAME . . . . . . . . . . . . . . . . . . . . 12 8.1 DINITX and DINITY . . . . . . . . . . . . . . . 12 8.1.1 DLIMX and DLIMY . . . . . . . . . . . . . . . 13 8.1.2 SLIMX and SLIMY . . . . . . . . . . . . . . . 13 8.1.3 PLACE . . . . . . . . . . . . . . . . . . . . 14 8.2 HBARST and VBARST . . . . . . . . . . . . . . . 15 8.2.1 SIZEL . . . . . . . . . . . . . . . . . . . . 15 8.3 HLABEL . . . . . . . . . . . . . . . . . . . . . 16 8.3.1 VLABEL . . . . . . . . . . . . . . . . . . . . 16 8.3.2 NOTATE . . . . . . . . . . . . . . . . . . . . 17 8.4 LINE . . . . . . . . . . . . . . . . . . . . . . 17 8.4.1 SYMBOL . . . . . . . . . . . . . . . . . . . . 18 8.4.2 SIZES . . . . . . . . . . . . . . . . . . . . 18 8.4.3 STEPL . . . . . . . . . . . . . . . . . . . . 19 8.4.4 STEPS . . . . . . . . . . . . . . . . . . . . 19 8.5 XFRM and YFRM . . . . . . . . . . . . . . . . . 19 8.5.1 XLEN and YLEN . . . . . . . . . . . . . . . . 20 8.5.2 XLAB and YLAB . . . . . . . . . . . . . . . . 20 8.6 XLOC and YLOC . . . . . . . . . . . . . . . . . 20 8.6.1 XTYPE and YTYPE . . . . . . . . . . . . . . . 21 10-ii TEKGRAPH USERS MANUAL Table of Contents 9.0 TCS Command File Options . . . . . . . . . . . . . 22 9.0.1 ERASE . . . . . . . . . . . . . . . . . . . . 22 9.0.2 HDCOPY . . . . . . . . . . . . . . . . . . . . 22 9.1 DRAWA . . . . . . . . . . . . . . . . . . . . . 22 9.1.1 DRAWR . . . . . . . . . . . . . . . . . . . . 23 9.1.2 DRWABS . . . . . . . . . . . . . . . . . . . 23 9.1.3 DRWREL . . . . . . . . . . . . . . . . . . . 23 9.2 MOVEA . . . . . . . . . . . . . . . . . . . . . 24 9.2.1 MOVER . . . . . . . . . . . . . . . . . . . . 24 9.2.2 MOVABS . . . . . . . . . . . . . . . . . . . 24 9.2.3 MOVREL . . . . . . . . . . . . . . . . . . . 25 9.3 SCURSR . . . . . . . . . . . . . . . . . . . . . 25 9.3.1 VCURSR . . . . . . . . . . . . . . . . . . . . 25 9.3.1 VCURSR . . . . . . . . . . . . . . . . . . . . 25 10.0 Internal TEKGRAPH Command File Options . . . . . . 26 10.0.1 BOX . . . . . . . . . . . . . . . . . . . . . 26 10.0.2 CLOSE . . . . . . . . . . . . . . . . . . . . 26 10.1 DATAI . . . . . . . . . . . . . . . . . . . . . 26 10.1.1 DATAO . . . . . . . . . . . . . . . . . . . . 26 10.2 ERRBAR . . . . . . . . . . . . . . . . . . . . . 27 10.3 PRINT . . . . . . . . . . . . . . . . . . . . . 27 10.3.1 PRTABS . . . . . . . . . . . . . . . . . . . . 28 10.4 TITLE . . . . . . . . . . . . . . . . . . . . . 28 10.4.1 TITABS . . . . . . . . . . . . . . . . . . . . 28 10.5 XLIMIT and YLIMIT . . . . . . . . . . . . . . . 29 10.6 WAIT And NOWAIT . . . . . . . . . . . . . . . . 29 11.0 TEKGRAPH Control File Example . . . . . . . . . . 30 12.0 Brief List of Command File Options . . . . . . . . 32 10-iii TEKGRAPH USERS MANUAL 10.1 Introduction As discussed in memo JGDM-137, the PLOT10/TCS/Advanced Graphics subroutine library has been modified to also support graphics on VT125/VT240 terminals (ReGIS graphics devices). The first program to use these new terminal independent graphics subroutines is GRAPH. In addition, GRAPH's functionality has been improved to make it more user friendly. The new version of the program is called TEKGRAPH. The name has been changed to avoid conflict with a new DEC program which is also invoked via the name GRAPH (DEC is building it into the DCL command dispatcher). The first version of GRAPH was written by Dave Danials 5 years ago for our PDP-11/45 computer. Because of the severe address space limitations on a 16 bit machine, it was difficult to use PLOT 10/Advanced Graphics subroutines within a Fortran mainline program. The function of GRAPH was to create a separate graphics display task incorporating the Plot10 Advanced Graphics calls. At its core, GRAPH is a command dispatcher of a limited set of TCS and Advanced Graphics subroutine calls. Since the PLOT10 library on the 11/45 system had many functions dummied out, GRAPH was more limited in functionality than TEKGRAPH which is built against a full function PLOT10 library. For those of you who are familiar with GRAPH, a brief discussion of the differences between GRAPH and TEKGRAPH will be presented. For users not familiar with GRAPH a detailed discussion of how to use TEKGRAPH will be given. Included will be a complete set of TEKGRAPH control file commands as well as detailed examples of how to create and use control files. 10-2 TEKGRAPH USERS MANUAL 10.2 Differences Between GRAPH And TEKGRAPH The majority of differences between GRAPH and TEKGRAPH are enhancements. So that a ready list of behavioral differences is easy to find, the differences between GRAPH and TEKGRAPH are as follows. 1. If invoked as a foreign command, $ TEKGRAPH control_file GRAPH would assume a control file extension of .CMD. TEKGRAPH assumes an extension of .CTL (for control). If an explicit extension is included in the control file name, both GRAPH and TEKGRAPH will use the explicit extension. 2. If TEKGRAPH is invoked with no command line, and the symbol GRAPH_FILE does not exist, TEKGRAPH will assume the file name is GRAPH.DAT. However, TEKGRAPH will first prompt for a file name displaying the current default file name setting (GRAPH.DAT). If a carriage return is typed, TEKGRAPH will now act just the way GRAPH did before, ie it will display a list of options (Delete, Merge, etc.) and line/point options. This mode can be used for graphically editing a graphics data set. If an explicit filename is entered, TEKGRAPH assumes you want to do something special with the file and then asks you if you want to create a graph control file. If you do not, TEKGRAPH behaves like GRAPH and displays the editing option menu. However, if you choose to, TEKGRAPH then proceds to prompt with a large number of questions (axis type, data limits, point type, line type, comments, etc.) which it then uses to display the graph. This mode can be used for producing a polished graph from an existing data set. 3. TEKGRAPH is designed to be used in a subroutine-like fashion from a main calling program. The main program can spawn commands to TEKGRAPH in two ways. First, the main program can create a graph control file, my_file.CTL, containing the appropriate Advanced-Graphics commands. Then the main program can spawn the command $TEKGRAPH my_file.CTL, and the graph will be plotted. If the user does not wish to be bothered with prompting for a data file name, one can set the symbol GRAPH_FILE to be the name of the data file and then spawn off the command, $TEKGRAPH, with no control file name on the command line. In this event, TEKGRAPH will not prompt for a file name but it will prompt for whether or not a control file should be used. 4. When run on a VT125 (also VT240) terminal, TEKGRAPH has the ability to move its cursor (when displayed) via the arrow keys. The movement produced by the arrow keys is rate 10-3 TEKGRAPH USERS MANUAL sensitive. The faster you move the keys, the larger steps the cursor moves. If the interval between hitting an arrow key is faster than .3 seconds, each time a key is hit, the interval the cursor moves increases by 2 (up to 25). If the interval is longer, each time the interval decreases by 5 (down to 1). This allows for fast and accurate positioning of the cursor with the arrow keys. 5. If TEKGRAPH does not know what type of terminal it is on, it will prompt for the terminal type. At this time it only knows about 4014 and VT125 terminals. However, this feature can be used from within an indirect command procedure (or batch) to have TEKGRAPH output data in either 4014 or ReGIS mode to a text file which can be displayed later. At present, TEKGRAPH does not know about VT100's which can emulate a Tektronix 4014. TEKGRAPH knows what terminal device it must output the graph to, by using the information about terminal type set via the SET TERM/DEVICE=XYZ command. Current graphic devices are the VT125 or FT1 (Foreign terminal 1, for Tektronix 4014 terminals). 6. TEKGRAPH has the ERRBAR command. This enables error bars to be plotted at each point. Use of the ERRBAR command assumes the errors can be described by a constant fractional error for the X-data and Y-data. 7. Terminals using GRAPH had to be set for NOWRAP. TEKGRAPH finds the initial terminal WRAP/NOWRAP status, sets the terminal for NOWRAP while it is running, and on exit, restores the terminal's initial WRAP/NOWRAP status. 8. The HDCOPY command can not work on a VT125/VT200 terminal unless a printer is attached to the printer port. Hardcopies may be made using the 8-V MUX and the video hard copy printer. If a command of the form $TEKGRAPH Ctrl_File is issued for a VT125/VT2xx terminal, TEKGRAPH will display the graph and wait for a return to be hit, thus allowing time for a user to signal the 8-V Mux to make a copy of the screen. 9. When aborted with a CTRL/Y, TEKGRAPH erases the screen before returning the user to the DCL level. 10. To insure that a VT125/VT2xx terminal is useable for entering commands, the terminal must always be switched back from graphic format to non-graphic format when a graphic program exits (no matter how). Consequently, when TEKGRAPH exits on a ReGIS terminal, it erases the screen whereas when it exits on a 4014 terminal, it does not erase the screen. To insure adequate viewing time for the graph on a ReGIS terminal, TEKGRAPH waits for the user to hit RETURN before it exits (and erases the screen) when creating a graph from a control file. 10-4 TEKGRAPH USERS MANUAL 11. TEKGRAPH has command line switches /WAIT and /NOWAIT which set (if present) whether TEKGRAPH waits for a return to be hit after plotting a graph in command line mode before exiting. These switches override the default, terminal-dependent settings. Their function is identical to the control file commands WAIT and NOWAIT. 12. TEKGRAPH establishes an exit handler so that when it exits or when CTRL/Y is typed, it will return a ReGIS mode terminal (VT125/VT240) to a defined state. This involves eraseing the graphics screen on ReGIS terminals so that terminal input is again possible. 10-5 TEKGRAPH USERS MANUAL 10.3 Use Of TEKGRAPH TEKGRAPH can be used in three ways; to graph data sets based on commands in a graph control file, to create graph control files, and to interactively edit and merge graphic data files. TEKGRAPH can either be invoked transparently from the Graph Master Menu (the VPW Graphics workstation), or independently by defining the symbol $ TEKGRAPH:=$SYS$UTILITY:TEKGRAPH TEKGRAPH has two primary modes, command line mode, and interactive mode. The interactive mode is started up if the TEKGRAPH command line is empty, ie it is invoked by typing $ TEKGRAPH However, one may also type $ TEKGRAPH Control_File or $ TEKGRAPH/WAIT Control_File $ TEKGRAPH/NOWAIT Control_File If there is no explicit extension on the Control_File name, the extenstion .CTL will be assumed. If the file exists, TEKGRAPH will open it up and read its commands from it. At this time the wait control switches are the only command line switches supported. When TEKGRAPH is first invoked, it requests VMS to tell it what type of terminal it is running on. At this time either VT125's or Tektronix 4014 terminals (FT1 type) are known to TEKGRAPH (PLOT125 subroutines). If the terminal is any other type (or inadvertently set to the wrong type), the following message will appear. Warning -- Terminal type does not support graphics Graphics protocol to simulate (ReGIS/Plot10): At this point either the user should enter either a R for ReGIS (VT-125/VT2xx) or P for Plot10 (Tektronix 4010,4014). 10-6 TEKGRAPH USERS MANUAL 10.4 Interactive Use Of TEKGRAPH If there is no command file on the command line invoking TEKGRAPH, TEKGRAPH will erase the screen and prompt for a data file to plot. Plot file name ( => GRAPH.DAT, ^Z => Exit): If ^Z is entered, TEKGRAPH erases the screen and exits. If a carriage return is hit, TEKGRAPH assumes you do not want to create a control file for plotting the data, and immediately drops into the Graphics Editing Menu. At this point, simply typing a return, will tells TEKGRAPH to prompt for format to display the data (line or point) and to then to produce a basic display of your data. After each graph is displayed, the graphics cursor will display on the screen. Hitting RETURN will return you to the Graphics Editing Menu. Additional graphics editing capabilities will be discussed later. However, if a file name is entered, TEKGRAPH assumes you may want to design a plot control file and prompts Specify the GRAPH plot format [Y/N]: If the first letter of the answer is not "Y", TEKGRAPH drops into the Graphics Editing Menu and behaves as discussed above. However, if the answer is "Y", TEKGRAPH checks to see if a control file already exists. It tests for the existance of a control file by stripping the extension off of the data file specified and adding a .CTL extension. If a control file with that name already exists TEKGRAPH prompts Use the existing graph control file [Y/N]: If the answer is "Y", TEKGRAPH plots the data using the existing control file, waits for you to hit RETURN, erases the screen and exits. If no control file existed initially, or if one does not choose to use the existing control file, TEKGRAPH will display the current data file name and the name of the control file it will create and then procede to ask a series of questions as to the format in which one wishes to plot the data. When these questions are completed, the data will be plotted using that format, TEKGRAPH will wait for a RETURN to be hit, and then will erase the screen. 10-7 TEKGRAPH USERS MANUAL 10.5 Graphics Data File Format TEKGRAPH requires a data file to have a certain format. Data files for TEKGRAPH can be created by a program or interactively created and edited using the graphics data file editor accessed by the Graph Master Menu (see memo JGMD139). The data files are unformatted, sequential access files. For users who plan to create data files as output from their own VAX programs, the following data file format is required. Variable Total type Bytes record 1 Inull,Ctitle I*2 + C*70 = 72 record 2 Isequence,Real_Xval,Real_Yval I*2 + R*4 + R*4 = 10 .... ....... , ........ , ....... I*2 + R*4 + R*4 = 10 record n Isequence,Real_Xval,Real_Yval I*2 + R*4 + R*4 = 10 where Inull INTEGER*2 0 Ctitle CHARACTER*70 Optional title for graph Isequence INTEGER*2 Sequence number of data pair, 1...600 Real_Xval REAL*4 Real X coordinate Real_Yval REAL*4 Real Y coordinate At this time, only 600 pairs of (X,Y) data points are allowed, and the above is the only data file format that is allowed. At some future time, additional data file formats providing for additional capabilities may be added. However, to allow for additional file formats, the value of Inull must be zero. If using Fortran, the data file should be created in the following way. The graphics file title is written to the data file after the file has been opened then the data is written. The following is an example of how to open the file and write the title and data from Fortran : REAL*4 Xval,Yval ! Required data file format C ! INTEGER*2 INULL ! This is the first 2 bytes C ! in the title. INTEGER*2 Isequence ! Required data file format C ! CHARACTER*70 CTITLE ! Remaining 70 bytes in ! the title (total 72 bytes). C ! DATA INULL /0/ ! Load INULL with a 0 DATA LUNF /1/ ! C ! OPEN( Unit = LUNF, ! Open up our - Name = 'file_name', ! data file - Status = 'NEW', ! so we can write - Form = 'UNFORMATTED') ! to it. C ! WRITE(LUNF)INULL,CTITLE ! Write title to file C ! 10-8 TEKGRAPH USERS MANUAL C ! Now we write the data WRITE(LUNF)Isequence,Xval,Yval ! Note. no format stmt WRITE(LUNF)Isequence,Xval,Yval ! Note. no format stmt WRITE(LUNF)Isequence,Xval,Yval ! Note. no format stmt WRITE(LUNF)Isequence,Xval,Yval ! Note. no format stmt C ! Write till we are out C ! of data. 10-9 TEKGRAPH USERS MANUAL 10.6 Graph Control File Format A TEKGRAPH control or command file consists of a sequential ASCII formatted text file with one command per line. Commands are executed sequentially one after the other until the end of the file at which point TEKGRAPH waits for the user to press RETURN and then exits. A control file can input data from multiple data files and plot that data with any axis type, line style, or symbol type at any location of the screen. TEKGRAPH can produce basic control files which can plot a single data set. More elaborite control files can be created by combining control files together. Each line of the control file consists of a command followed by one or more options. The syntax and naming conventions are almost identical with the TCS/Advanced-Graphics subroutine calling conventions. If one had a subroutine XYZ and the call was CALL XYZ(A,B,C) the control file line would read XYZ A,B,C At a minimum, each control file must consist of BINITT ! Initialize TCS DATAI input_file ! Input data file < additional Commands> .............. < additional Commands> CHECK ! check and scale data DISPLY ! Display the data Please note, comment lines (a "!" followed by text) are not allowed in control files and are included above only for clarification. Since TEKGRAPH can be used to generate a prototype control file, it can be used as a starting point for generating your own specialized control file. 10-10 TEKGRAPH USERS MANUAL 10.7 Command File Commands TEKGRAPH can create basic plot control files. However, elaborate control files can be created for plotting many data files on a single plot in a wide variety of ways. For creating a control file and understanding the commands, you will need to get a copy of the TCS manual, and the Advanced Graphics manual. In the appendix of this document is a complete comment list from the suboutine GRAPH in TEKGRAPH and a very brief description of the various calls. 10-11 TEKGRAPH USERS MANUAL 10.8 _AG_II_Command_File_Options_ ____________________________ 10.8.0.1 BINITT - BINITT must be the first command in each control file. It initializes the Advanced Graphics common blocks and finds out which graphics protocol ot use when called the first time. BINITT may be called at any time to reset the table values back to the default values. Command file format: BINITT BINITT 10.8.0.2 CHECK - Prior to displaying data, CHECK is used to scale the data to the graph window and also calculates the width and position of the labels based of the room available plus calculating the grid parameters. Command file format: CHECK CHECK 10.8.0.3 DSPLAY - After the CHECK command the DSPLAY command is issued to plot the data, axis, etc. DSPLAY sets up the window, plots the curve, draws the grid, and labels each set of major tic marks. Command file format: DSPLAY DSPLAY ** NOTE ** CHECK and DSPLAY should be called only once per plot. 10-12 TEKGRAPH USERS MANUAL 10.8.0.4 CPLOT - CPLOT plots a curve using the data window location values currently in COMMON. It does not draw the grid or labels or alter scale factors that determine which data is plotted. For multiple curves on the same graph the user should call DSPLAY for the first curve and CPLOT for all additional curves. If the data vlaues exceed the window boundaries as defined in the COMMON Table, the curve will be clipped. Command file format: CPLOT CPLOT 10.8.0.5 FRAME - FRAME will cause a frame around the window. Normally, if short tic marks have been specified (without grid lines), the sides of the data window opposite the axes will not be framed. In this case, calling FRAME will add these lines. Command file format: FRAME FRAME 10.8.1 DINITX and DINITY DINITX and DINITY are used if one has multiple curves with multiple scales which must occur on the same graph. For example, DINITX will reinitialize the labels on the X axis. This will allow a new curve (with a new scale to be drawn). Command file format: DINITX DINITX DINITY DINITY 10-13 TEKGRAPH USERS MANUAL 10.8.1.1 DLIMX and DLIMY - DLIMX and DLIMY are used to set the minimum and maximum X and Y values to use in plotting the data. It can be used to set the display window or to clip data outside the minimum and maximum range. Command file format: DLIMX RXmin,RXmax DLIMX RXmin,RXmax DLIMY RYmin,RYmax DLIMY RYmin,RYmax where RXmin,RXmax = Minimum X, Maximum X values RYmin,RYmax = Minimum Y, Maximum Y values 10.8.1.2 SLIMX and SLIMY - SLIMX and SLIMY set the screen limits for Xmin, Xmax and Ymin, Ymax. Command file format: SLIMX IXmin,IXmax SLIMX IXmin,IXmax SLIMY IYmin,IYmax SLIMY IYmin,IYmax where IXmin,IXmax = Minimum X, Maximum X screen values IYmin,IYmax = Minimum Y, Maximum Y screen values 10-14 TEKGRAPH USERS MANUAL 10.8.1.3 PLACE - This routine sets the values of the screen minimums and maximums in COMMON to place the screen window at a predefined location on the display area. Command file format: PLACE (LIT) PLACE (LIT) where LIT = is a literal string of three characters specifying the window location desired. (See following table) Location Value Ival Screen Coordinates (literal) I*4 XMIN XMAX YMIN YMAX ---------------------------- Standard (STD) 1 ! 150 900 150 700 Upper Half (UPH) 2 ! 150 850 525 700 Lower Half (LOH) 3 ! 150 850 150 325 Upper Left 1/4 (UL4) 4 ! 150 450 525 700 Upper Right 1/4 (UR4) 5 ! 650 950 525 700 Lower Left 1/4 (LL4) 6 ! 150 450 150 325 Lower Right 1/4 (LR4) 7 ! 650 950 150 325 Upper Left 1/6 (UL6) 8 ! 150 325 525 700 Upper Center 1/6 (UC6) 9 ! 475 650 525 700 Upper Right 1/6 (UR6) 10 ! 800 975 525 700 Lower Left 1/6 (LL6) 11 ! 150 325 150 325 Lower Center 1/6 (LC6) 12 ! 475 650 150 325 Lower Right 1/6 (LR6) 13 ! 800 975 150 325 If preferred, the user may enter the number of the location as represented by Ival in the table above. 10-15 TEKGRAPH USERS MANUAL 10.8.2 HBARST and VBARST Bar charts may be specified using one of two routines, HBARST for horizontal bars or VBARST for vertical bars. The same results could be obtained by using LINE to specify bar chare, XFRM or YFRM to suppress the grid lines parallel to the bars, SYMBL to specify the type of shading lines in the bar, SIZEL to specify the width of the bar, and Sizes to specify the distance between the shading lines. The format of the command is; Command file format: HBARST Ishade,Iwbar,Idbar HBARST Ishade,Iwbar,Idbar VBARST Ishade,Iwbar,Idbar VBARST Ishade,Iwbar,Idbar where Ishade = Shading type (0 - 15) Iwbar = The width of the bar in raster units. The width must be greater than 1, but 0 will result in a default width of 40 raster units. Idbar = The distance between the shading lines in raster units. The distance must be greater than 2, however, if a zero is entered, a default width of 20 raster units results. 10.8.2.1 SIZEL - The SIZEL command sets the width of the bar used for bar charts. Command file format: SIZEL value SIZEL value where Value = real number designating the width in raster units. 10-16 TEKGRAPH USERS MANUAL 10.8.3 HLABEL HLABEL can be used to print a label string on the screen starting at the current position. The format for the HLABEL command is Command file format: HLABEL Lstring HLABEL Lstring where Lstring = Literal ASCII text string of up to 66 characters An example of using HLABEL would be to position the cursor to (200,200) and write the label "I AM A TITLE". To do this the following commands would be used. MOVABS 200,200 HLABEL I AM A TITLE 10.8.3.1 VLABEL - VLABEL can be used to print a label string on the screen starting at the current position. While the HLABEL string is printed out horizontally, the VLABEL string is printed out vertically from top to bottom. The format for the VLABEL command is Command file format: VLABEL Lstring VLABEL Lstring where Lstring = Literal ASCII text string of up to 66 characters An example of using VLABEL would be to position the cursor to (50,500) and write the label "VERTICAL LABEL". To do this the following commands would be used. MOVABS 50,500 VLABEL VERTICAL_TITLE 10-17 TEKGRAPH USERS MANUAL 10.8.3.2 NOTATE - Notate will position the cursor to point IX,IY and place and alphanumeric label there. The label may be up to 54 characters long. In any event, a label of 54 characters is always plotted (although it may be blank/null filled). The command form is Command file format: NOTATE Ix,Iy,Lstring NOTATE Ix,Iy,Lstring where Ix = Screen X location to start writing Iy = Screen Y location to start writing Lstring = Literal ASCII text string of up to 66 characters **NOTE** I have not had much success with this routine and have used the following calls instead: MOVABS Ix,Iy Move to screen coord. Ix,Iy HLABEL Text Write text 10.8.4 LINE Specifies the line type to use in drawing a curve. The format of the command is Command file format: LINE Iline_Type LINE Iline_Type where Iline_Type = 11+ Software Dash 9 Alternate moves/draws between points 4 Dot,dot,dot... 3 Dot,dash,dot,dash.... 2 Dash,dash,...... 1 Long dash,long dash.... 0 Solid -1 No line -2 Vertical Bar -3 Horizontal Bar -4 Point plot -11 User Line 10-18 TEKGRAPH USERS MANUAL 10.8.4.1 SYMBOL - SYMBL is used to select the symbol type for plotting line graphs or symbol type for plotting bar charts. The command format is; Command file format: SYMBL Isymb SYMBL Isymb where Isymb = 1 Circle 2 Cross 3 Triangle 4 Square 5 Star 6 Diamond 7 Vertical Bar 8 Plus sign 9 Up Arrow 10 Down Arrow 11 Reverse Triangle 10.8.4.2 SIZES - The command sizes sets the size of the data point symbol if a symbol has been specified with command SYMBL. Command file format: SIZES Rsize SIZES Rsize where Rsize = the multiplicative factor specifying the size of the data point symbols, or the distance in raster units between the bar chart and shading lines. 10-19 TEKGRAPH USERS MANUAL 10.8.4.3 STEPL - STEPL is used to set the increment between data points which will be connected with a line. Command file format: STEPL Ivalue STEPL Ivalue where Ivalue = 1 Desiginates lines between every data point 2 Desiginates lines between every other point 3 Desiginates lines between every 3rd point ... N Desiginates lines between every Nth point 10.8.4.4 STEPS - STEPS determines the interval between data symbols plotted. Command file format: STEPS Ivalue STEPS Ivalue where Ivalue = 1 Desiginates symbols on every data point 2 Desiginates symbols on every other point 3 Desiginates symbols on every 3rd point ... N Desiginates symbols on every Nth point 10.8.5 XFRM and YFRM XFRM and YFRM sets the format for the major tic marks. The command format is Command file format: XFRM Iform XFRM Iform YFRM Iform YFRM Iform where Iform = 1 No tic marks drawn = 2 Tic on outside of axis = 3 Tic on inside of axis = 4 Tic inside/outside of axis = 5 Arrow from outside to inside = 6 Arrow on inside of axis 10-20 TEKGRAPH USERS MANUAL 10.8.5.1 XLEN and YLEN - XLEN and YLEN are used to set the size of the major x-axis and y-axis tic marks. The format is; Command file format: XLEN Ilength XLEN Ilength YLEN Ilength YLEN Ilength where Ilength = designates the distance in screen units that the tic marks will extend outward from the axis not including grid lines. 10.8.5.2 XLAB and YLAB - XLAB and YLAB are used to set the label format on the x-axis and y-axis. Command file format: XLAB Iform XLAB Iform YLAB Iform YLAB Iform where Iform = 0 No label = 1 Matches transformation type = 2 Logarithemic = 3 Days = 4 Weeks = 5 Periods = 6 Months = 7 Quarters = 8 Years 10.8.6 XLOC and YLOC XLOC and YLOC are used to set the location of the X and Y axis complete with labels and tic marks in relation to the left and lower edges of the screen window. The value to offset the axes, ILOC, may be positive or negative. If positive, the axis is moved inward from the window. If negative, it is moved outward. The command format is; Command file format: XLOC Iloc XLOC Iloc YLOC Iloc YLOC Iloc where 10-21 TEKGRAPH USERS MANUAL Iloc = the integer number of raster units the axes will be offset from the lower edge of the data window. 10.8.6.1 XTYPE and YTYPE - XTYPE and YTYPE is used to define to the Advanced Graphic system the type of data that is represented in the X or Y array. Command file format: XTYPE Itype XTYPE Itype YTYPE Itype YTYPE Itype where Itype = 1 Linear (Default) 2 Logarithmic 3 Days 4 Weeks 5 Periods 6 Months 7 Quarters 8 Years 10-22 TEKGRAPH USERS MANUAL 10.9 _TCS_Command_File_Options_ __________________________ 10.9.0.1 ERASE - ERASE erases the screen of the graphics output device. The amount of delay following the erase varies with the type of terminal being used. Command file format: ERASE ERASE 10.9.0.2 HDCOPY - HDCOPY will make a copy of a 4014 screen on the graphics hardcopy device. At this time, HDCOPY does not work with VT125/VT240 terminals. However, those terminals can use the 8V-Mux. Command file format: HDCOPY HDCOPY 10.9.1 DRAWA DRAWA is used to draw a line (in user's units) from the current position to the specified coordinates. Command file format: DRAWA Rxval,Ryval DRAWA Rxval,Ryval where Rxval = Xvalue line is drawn to (users coordinates) Ryval = Yvalue line is drawn to (users coordinates) 10.9.1.1 DRAWR - DRAWR is used to draw a line from current position a displacement (in users coordinates). Command file format: 10-23 TEKGRAPH USERS MANUAL DRAWR Rxval,Ryval DRAWR Rxval,Ryval where Rxval = Xvalue length of line (users coordinates) Ryval = Yvalue length of line (users coordinates) 10.9.1.2 DRWABS - DRWABS is used to draw a line between the current position on the screen to the location (in screen units) specified by the command. Command file format: DRWABS Ixval,Iyval DRWABS Ixval,Iyval where Ixval = Xvalue line is drawn to (screen coordinates) Iyval = Yvalue line is drawn to (screen coordinates) 10.9.1.3 DRWREL - DRWREL is used to draw a line a displacement (in screen units) from the current position on the screen. Command file format: DRWABS Ixval,Iyval DRWABS Ixval,Iyval where Ixval = Xvalue line is drawn to (screen coordinates) Iyval = Yvalue line is drawn to (screen coordinates) 10.9.2 MOVEA MOVEA is used to move (in user's units) from the current position to the specified coordinates. The coordinates used will be appropriately converted to screen units depending on the scalling factors set. Command file format: MOVEA Rxval,Ryval MOVEA Rxval,Ryval where Rxval = Xvalue to move to (users coordinates) Ryval = Yvalue to move to (users coordinates) 10-24 TEKGRAPH USERS MANUAL 10.9.2.1 MOVER - MOVER is used to move from current position a displacement (in users coordinates). Command file format: MOVER Rxval,Ryval MOVER Rxval,Ryval where Rxval = Xvalue length to move (users coordinates) Ryval = Yvalue length to move (users coordinates) 10.9.2.2 MOVABS - MOVABS is used to move the current position on the screen to the location (in screen units) specified by the command. Command file format: MOVABS Ixval,Iyval MOVABS Ixval,Iyval where Ixval = Xvalue to move to (screen coordinates) Iyval = Yvalue to move to (screen coordinates) 10.9.2.3 MOVREL - MOVREL is used to move a displacement (in screen units) from the current position on the screen. Command file format: MOVABS Ixval,Iyval MOVABS Ixval,Iyval where Ixval = Xvalue length to move (screen coordinates) Iyval = Yvalue length to move (screen coordinates) 10-25 TEKGRAPH USERS MANUAL 10.9.3 SCURSR SCURSOR will display the cursor Inum times. Each time RETURN is hit it will write the cursor coordinates (in Screen units) to the open output file. If an "S" followed by a RETURN is typed, it will stop displaying the cursor prior to entering all Inum times. For the filing to work, the data file must be opened with a DATAO command. Command file format: SCURSR Inum SCURSR Inum where Inum = Number of points desired 10.9.3.1 VCURSR - VCURSOR will display the cursor Inum times. Each time RETURN is hit it will write the cursor coordinates (in Screen units) to the open output file. If an "S" followed by a RETURN is typed, it will stop displaying the cursor prior to entering all Inum times. For the filing to work, the data file must be opened with a DATAO command. Command file format: VCURSR Inum VCURSR Inum where Inum = Number of points desired 10-26 TEKGRAPH USERS MANUAL 10.10 _Internal_TEKGRAPH_Command_File_Options_ ________________________________________ 10.10.0.1 BOX - The BOX command places the terminal in graphic input mode. The cursor is then positioned and return struck to select the first corner of a "BOX". The cursor is then positioned and return struck to select the opposite corner of the "BOX". A frame is drawn around the box described by thes two corners and the X,Y internal limits are set to correspond to the box's coordinates. Command file format: BOX BOX 10.10.0.2 CLOSE - CLOSE is used to close open DATAI and DATAO files so that a new file can be used. Command file format: CLOSE CLOSE 10.10.1 DATAI DATAI is used to specify an input data file specification. Command file format: DATAI file_name DATAI file_name where file_name = an ASCII text string 10.10.1.1 DATAO - DATAO is used to open an output datat file for filing selected data. Command file format: 10-27 TEKGRAPH USERS MANUAL DATAO file_name DATAO file_name where file_name = an ASCII text string 10.10.2 ERRBAR The ERRBAR command is used to plot data with error bars. If the SYMBL command is used to set the symbol type, the ERRBAR command must follow it if error bars are to be drawn. The ERRBAR command assumes that the data to be ploted has a fixed fractional uncertainty for both X and Y data. This uncertainty is specified with the ERRBAR command; Command file format: ERRBAR Xerror,Yerror ERRBAR Xerror,Yerror where Xerror = Fractional uncertainty in X Yerror = Fractional uncertainty in Y If a symbol type is already set (SYMBL command) the error bars will be plotted on top of the symbols. If the SYMBL command is used after the ERRBAR command it will cancel the command to plot the error bar symbol. 10.10.3 PRINT PRINT will cause the cursor to be displayed. After positioning the cursor, hit return or space bar and the coordinates of the cursor (in user coordinates) will be displayed. Type 'S' to stop. Command file format: PRINT PRINT The format for the data values printed is: (1PE11.4,1PE11.4) or (1.2345E67 ,1.2345E67) 10-28 TEKGRAPH USERS MANUAL 10.10.3.1 PRTABS - PRTABS will cause the cursor to be displayed. After positioning the cursor, hit return or space bar and the coordinates for the cursor (in screen coordinates) will be displayed. Type 'S' to stop. Command file format: PRTABS PRTABS The format for the data values printed is: [I4,I4] or [1234,1234] 10.10.4 TITLE TITLE is used to print the title of the data file (as defined in the first record in the data file) on the top of the graph at screen coord. [145,740] (64 characters max). Command file format: TITLE TITLE 10.10.4.1 TITABS - TITABS is used to print the title of data file (as defined in the first record in the data file) at current location on graph. (64 characters max). Command file format: TITABS TITABS 10-29 TEKGRAPH USERS MANUAL 10.10.5 XLIMIT and YLIMIT XLIMIT and YLIMIT are used to write the cursor defined limits to the output file. When XLIMIT/YLIMIT command is encountered, the cursor is displayed and when return is hit, either the x or y value becomes the limit value for filing. If the command is XLIMIT, a line is drawn between the coordinates (Xlim,Ymin) and (Llim,Ymax) and these points are written out to the data file (must be opened with DATAO). Likewise, if the command is YLIMIT, a line is drawn between (Xmin,Ylim) and (Xmax,Ylim) and the points written out to the data file. Command file format: XLIMIT XLIMIT YLIMIT YLIMIT 10.10.6 WAIT And NOWAIT The WAIT and NOWAIT commands determine whether TEKGRAPH will wait or not for the user to press RETURN before exiting. By default, TEKGRAPH waits for the user to press RETURN if it is a ReGIS terminal and does not wait if it is not a ReGIS terminal (ie a Tektronix 4014). Command file format: WAIT WAIT NOWAIT NOWAIT 10-30 TEKGRAPH USERS MANUAL 10.11 TEKGRAPH Control File Example The following is an example of a complicated control file. It is used to plot three seperate data files on the screen. The commands are commented (ie any text following the "!"). However, please note that a normal TEKGRAPH control file does not allow or accept in line comments. ! Screen erases BINITT ! Init common blocks DATAI DRA1:[MARKB.TAB]NEAR.TMP;1 ! Input data file SLIMX 75,450 ! Set X plot window SLIMY 100,400 ! Set Y plot window XLEN 20 ! Set X tic length YLEN 15 ! Set Y tic length XFRM 2 ! Tics outside axis YFRM 2 ! Tics outside axis LINE 0 ! Use Solid line CHECK ! Check/scale data DSPLAY ! Draw graph MOVABS 0,350 ! Move to (0,350) VLABEL MDS UNITS -CM- ! Insert a vertical label MOVABS 180,50 ! Move to (180,50) HLABEL CENTIMETERS [SCAN] ! Horizontal label FRAME ! Frame the graph BINITT ! Re-initialize common DATAI DRA1:[MARKB.TAB]OFFSET.TMP ! Input a new data file SLIMX 575,975 ! Set new graphics window SLIMY 100,400 ! above the first graph XLEN 10 ! Set tic mark lengths YLEN 10 ! XFRM 2 ! and location YFRM 2 ! CHECK ! Check/scale DSPLAY ! Plot data MOVABS 500,325 ! Move to proper place VLABEL LINEARIZED ! and add vertical/horiz MOVABS 690,50 ! labels as necessary HLABEL CENTIMETERS [SCAN] ! FRAME ! draw a frame DATAI DRA1:[MARKB.TAB]AVEO.TMP ! Input another data file? CHECK ! Check/scale CPLOT ! Plot on same axis DATAI DRA1:[MARKB.TAB]AVE1.TMP ! Input yet onother LINE 1 ! Long dash line CHECK ! Check/scale CPLOT ! Plot on same axis DATAI DRA1:[MARKB.TAB]PLTINT.TMP ! Input yet another file LINE 2 ! Draw with dashed line CHECK ! Check/scale data CPLOT ! Plot on same axis BINITT ! Re-init tcs common block DATAI DRA1:[MARKB.TAB]INTGRL.TMP ! Input another file 10-31 TEKGRAPH USERS MANUAL SLIMX 575,975 ! set data limits SLIMY 475,775 ! XLEN 10 ! Tic mark length YLEN 10 ! XFRM 2 ! and position YFRM 2 ! LINE 0 ! Solid line CHECK ! Check/scale DSPLAY ! display graph MOVABS 500,740 ! Move to label area VLABEL RELATIVE ENERGY ! write label MOVABS 690,425 ! move to new place HLABEL CENTIMETERS [SCAN] ! write horiz label FRAME ! Frame the graph. 10.12 Brief List Of Command File Options BINITT AG-2 INITIALIZATION BOX FILE 2 COORDINATE SETS AND ENCLOSE FRAME CHECK SET TABLES WRT PRESENT DATA CLOSE CLOSE DATAI AND DATAO FILES CPLOT CURVE PLOTTING DATAI L1 INPUT DATA FILE SPEC DATAO L1 OUTPUT DATA FILE SPEC. DINITX MULTIPLE CURVES WITH DIFFERRENT SCALES(X) DLIMX R1,R2 SET DATA MIN AND MAX(X) DLIMY R1,R2 SET DATA MINA AND MAX(Y) DRAWA R1,R2 DRAW LINE (USERS UNITS) DRAWR R1,R2 DRAW LINE A DISPLACEMENT (USER UNITS) DRWABS I1,I2 DRAW LINE (SCREEN UNITS) DRWREL I1,I2 DRAW LINE A DISPLACEMENT (SCREEN UNITS) DSPLAY DISPLAY GRAPH ERASE ERASE SCREEN ERRBAR dX,dY Create a basic error bar scatter plot FRAME DRAW FRAME AROUND WINDOW HBARST I1,I2,I3 HORIZIONTA BAR CHART SPEC. HDCOPY HARD COPY SCREEN HLABEL L1 HORIZONTAL LABELING LINE I1 SET LINE TYPE MOVABS I1,I2 MOVE SCREEN CURSOR (SCREEN UNITS) MOVEA R1,R2 MOVE SCREEN CURSOR (USER UNITS) MOVER R1,R2 MOVE SCREEN CURSOR DISPLACEMENT (USER UNITS) MOVREL I1,I2 MOVE SCREEN CURSOR DISPLACEMENT (SCREEN) NOTATE I1,I2,L1 HORIZONTAL LABELING NOWAIT Don't wait till is hit before exiting PLACE LIT SET SCREEN MIN AND MAX TO PREDEFINED VALUES PRINT DISPLAY CURSOR DATA VALS (USER COORDINATES) PRTABS DISPLAY CURSOR DATA VAL (SCREEN COORDINATES) SCURSR I1 FILE CURSOR COORDINATES (SCREEN UNITS) SIZEL R1 SET BAR CHART LINE WIDTH 10-32 TEKGRAPH USERS MANUAL SIZES R1 SYMBOL SIZE SLIMX I1,I2 SET SCREEN LIMITS(X) SLIMY I1,I2 SET SCREEN LIMITS(Y) STEPL I1 SET INCREMENT BETWEEN PLOTTED POINTS STEPS I1 SET INCREMENT BETWEEN SYMBOLS SYMBL I1 DESIGNATE PLOTTED SYMBOL TITABS Display DATA TITLE at current loc. (64 Max) TITLE Display DATA TITLE @ [145,740] (Scrn coor.) TSEND DUMP GRAPHICS BUFFER VBARST I1,I2,I3 VERTICAL BAR CHART PARAMETERS VCURSR I1 FILE CURSOR COORDINATES (USER UNITS) VLABEL L1 VERTICAL LABELING WAIT Wait till is hit before exiting XFRM I1 MAJOR TICK MARK FORM(X) XLAB I1 MAJOR TICK MARK LABEL TYPES(X) XLEN I1 MAJOR TICK MARK SIZE(X) XLIMIT FILE CURSOR DEFINED LIMITS XLOC I1 AXIS LOCATION(X) XTYPE I1 DATA TRANSFORM TYPE YFRM I1 MAJOR TICK MARK FORM(Y) YLAB I1 MAJOR TICK MARK LABEL TYPES(Y) YLEN I1 MAJOR TICK MARK SIZE(Y) YLIMIT FILE CURSOR DEFINED LIMITS YLOC I1 AXIS LOCATION(Y) YTYPE I1 DATA TRANSFORM TYPE 10-33 CHAPTER 11 GENERATING PRESENTATION VIEWGRAPHS USING TVG TVG (Tektronix Viewgraph Generator) may be used to generate presentation quality viewgraphs on Tektronix 4014 terminals. TVG may be used both on Tektronix 4014 terminals and Digital VT240 terminals in 4014 emulation mode. Unfortunately, VT240 graphics in Tek 4014 emulation mode is rather slow, so serious use of TVG (picking and moving text around) is more easily done on a real 4014. Also, the Tektronix 4014 resolution is significantly higher than the VT240, so 4014's should be used for producing the final viewgraph copies. To simplify the creation of simple viewgraphs for processing by TVG, the Graphics Workstation Viewgraph option provides a subsequent "Design" choice which allows users to very rapidly generate a series of proto-type viewgraphs on VT100 compatible terminals. This facility (TVG Maker) will be discussed later. TVG is accessed either by defining it as a foreign command $ TVG:=$SYS$UTILITY:TVG or activating it via the UTL command (UTL TVG), or it is available from the VPW Graphics Workstation menu by selecting Viewgraph as the choice. If the terminal is a Tektronix 4014 terminal, TVG is directly invoked. However, if the terminal is a VT240 (or VT100 compatible), the Viewgraph Menu appears. If you are using a VT240 terminal, selecting the Generate choice, invokes TVG interactively. When TVG is invoked, it tries to determine the type of terminal on which it is running. If the terminal is a VT240, TVG first issues a command for it to emulate a Tektronix 4014 terminal. Then when TVG exits normally, it returns the terminal to normal VT100-like behavior. It is also possible to force an exit from TVG via a Ctrl-Y. In this event, a VT240 is not automatically restored to VT100 mode unless TVG was invoked from the Graphics Workstation menu (which traps the ctrl-Y, and resets the terminal). In the event the terminal is left in 4014 emulation mode the command $ @SYS$SYSVPWFILES:GRAPHDEV VT240 11-1 GENERATING PRESENTATION VIEWGRAPHS USING TVG will restore the VT240 to VT100 mode of operation. This chapter will document the commands to use with TVG to create viewgraphs. 11.1 Starting Out TVG is designed to allow a user sitting at a Tektronix 4014 terminal to interactively create a viewgraph. Straight line shapes can be drawn, and text can be entered and displayed in a variety of text fonts, sizes, and orientations. The viewgraphs can be saved for later use in ASCII text files. These files can be edited to make minor changes in the text or size (without having to use TVG) but the exact format of the file must be preserved because TVG is very intolerant of errors encountered when reading in a saved viewgraph file. Viewgraphs are assumed to have an extension .TVG although this can be overridden by providing an explicit extension. Each TVG object (text string, line segment, shape) has a tag letter associated with it (A-Z, a-z, 0-9). Most TVG commands require the tag to be used to identify the object on which the command acts. After an object is created, by referencing its tag, its character size, character font, orientation, and location may be changed with commands. If you wish to use character size and fonts other than the default it is easiest to change them before creating tagged object. If you are creating an object (via the E command), the tag letter is automatically assigned starting with the letter A and incrementing each time a new object is created. These tag letters stay with the viewgraph when it is saved as an ASCII file, and restored when the file is unsaved. Some care should be taken to avoid conflicting tag values. If you have an object with a tag "A", and then restore a viewgraph file with an object having a tag "A", your original tag is overwritten. However, if the viewgraph file has unique tags, its objects are added to those objects you have already created. After invoking TVG, the screen will erase, axes will be drawn and the TVG> prompt will appear. A message reminding the user that the default file extension is .TVG also appears. If you are generating a standard presentation viewgraph, your first command should be to place the title line and logo on the viewgraph. A standard KMS title/Logo template can be included by typing U SYS$SYSVPWFILES:KMSLOGO.TVG. Your next command should be "R" to display the logo/title line. Next, set the default character type and size for the viewgraph (its easier to do now than later). Character style 17 (Triplex Roman), produces the best presentation viewgraphs but take longer to draw than the default style 3 (Simplex Roman). To change 11-2 GENERATING PRESENTATION VIEWGRAPHS USING TVG the default character set, type MC 17 at the TVG> prompt. You should also use the MS command (Modify Size) to set the default size for your characters. The sizes are specified in inches (relative to 8.5 x 11 page) with the default size of .25 inches. You create TVG viewgraph objects either with the E to enter a line of text, or MB to enter a box or line segment shape An identifying tag letter (beginning with capital A) will be assigned for entry by the E command but must be explicitly specified with the MB command. This tag identifier will be used in subsequent commands to refer to the entry. After either of these commands, the cross-hairs will become visible. For entry of text, position the cross-hairs where you would like the text, and type either L, R, or C (for Left, Right, or Center justified text). If you wish to see this entry, use the R command to re-draw the screen and all existing text string and shapes entered will then be plotted. For entry of boxes or lines, position the cross-hairs at each point in the line or box, and set that point by typing any character except A, C or E. (The space bar is useful here). Line segments will be produced between these points. Use A, C or E (draw Arrow, Close box, or End point) to terminate the entry. To enter additional text strings or figures, use the E or MB commands. You can change the default size, orientation, character set, or alignment by using the commands MS, MO, MC, or MA without specifying an identifying tag. All subsequent entries will have these characteristics. 11.2 TVG Commands Each text string or object created during a TVG session has a tag letter (or number) associated with it. In the command list to follow, the tag is referenced by the letter "l". Uppercase and lowercase letter tags are considered to refer to different objects. The commands to create or modify a view-graph are: BYE Exits TVG (same as Ctrl-Z) CLEAR Clears all text and box definitions; the default values are unchanged. E Enter new text to be associated with the next available identifier. F Plot final viewgraph on your terminal MA [l] d Modify the alignment of TEXT l to d, where D = 0. (LEFT) AND D = 1. (RIGHT). Default: d=0. MB l Make Box. Draw up to 32 connected line segments. MC [l] n Modify the character set of TEXT l to n. Default n=3. 11-3 GENERATING PRESENTATION VIEWGRAPHS USING TVG MO [l] d Modify the orientation of TEXT l to d degrees. Default: d=0. MP l Modify the position of TEXT l to that of the crosshair input. The alignment can also be chosen if either an L, C or R is typed to set point. MS [l] d Modify the size of TEXT l to d inches. Default: d=.25. MT l Replace TEXT l with new text. N n Place n ticks on right side during REDRAW. R Redraw with identifiers. S t Save as file named t. U t Unsave from file named t. *** where [l] is the tag letter identifier (A-Z,a-z,0-9) To generate a final viewgraph and copy (if TVG is a foreign command, type: $TVG filename.ext[/switches] Where "filename.ext" is the name of the file in which the viewgraph description is saved. (The default extension type is .TVG). TVG can specify an indirect command file on its command line of the form TVG @filename or TVG filename[/-FI/MG:N.] where /-FI supresses the filename identifier at bottom right of figure /TE:n means plot on terminal n (*** DOES NOT YET WORK ON VAX) /MG:n.nn is magnification factor 11.2.1 BYE The BYE command (or Ctrl-Z) is used to terminate TVG. Before TVG exits, the question "Have you saved this? [Y,n]" will appear. To exit, type Y. To continue in TVG, type N. This question is designed to remind you to save your new or modified TVG file. 11-4 GENERATING PRESENTATION VIEWGRAPHS USING TVG 11.2.2 CLEAR The CLEAR command is used to wipe all text and box definitions, while remaining in TVG. Any default definitions that have been reset remain reset. 11.2.3 E To enter new text user the E command E The next available tag identifier (beginning with capital A through lower-case z) will be assigned; and is used to reference that text in subsequent commands. (i.e., the MT B command is used to modify the text string tagged 'B'.) The default characteristics for entry are character set 3, orientation of 0 degrees with the X axis, left-justified alignment, and letter size of 0.25 inches. To change these characteristics, see the MC, MO, MA, and MS commands. 11.2.4 F The F command is used to draw the viewgraph in final form (without tags or axes). After the F command is used, typing a will cause the screen to blank, and the TVG> prompt to re-appear. 11.2.5 MA The command MA is used to modify the alignment of text strings. Alignment is defined as either 0 (left-justified) or 1 (right-justified). If the command is used with a specific tag identifier (eg. MA B 1), only that string is re-aligned. If the command is used without an identifier (eg. MA 1), the default alignment is changed. The initial default alignment is 0 (left justified) 11.2.6 MB The command, MB l, is used to enter or modify an existing box with the tag identifier l. The tag letter must be specified. After the MB command is used, the cross-hairs will appear on the screen. Position these at the first point of the box or line, and type any character except A, C or E (the space bar is useful here). Re-position the cross-hairs to the next point and type another character. The first line segment will appear on the screen. To 11-5 GENERATING PRESENTATION VIEWGRAPHS USING TVG terminate entry, type A (draw arrow to point), E (end of shape), or C (close box). If a C is typed, a line will be drawn between the current point and the initial point of the box or shape. 11.2.7 MC The command, MC n, is used to change the current default character set to set n. The command, MC l n, is used to modify the character set of an entry specific text string. 11.2.8 MO The command, MO a, is used to modify the default orientation of text. The command, MO l a, is used to modify the orientation of the specified text string. The initial default orientation is 0 degrees with respect to the X-axis. 11.2.9 MP The command, MP l, is used to modify the position of a string or box. When the MP command is used, the cross-hairs will become visible. Position the crosshairs and type L to use this point as the lower left-hand corner of the text R to use this point as the lower right-hand corner of the text C to use this point as the center point of the text Each tag has a tic mark associated with it which can be used for reference purposes with the cross hair when moving objects. 11.2.10 MS The command, MS s, is used to modify the default lettering size. The command MS l s, is used to modify the lettering size for the specific text string. The size s is entered in floating point inches. The initial default lettering size is 0.25 inches. 11.2.11 MT The command, MT l, is used to modify (replace) the text string specified by tag l with the new text. If MT l is used, that string is eliminated and the tag identifier released for re-use. 11-6 GENERATING PRESENTATION VIEWGRAPHS USING TVG 11.2.12 N The command, N m, is used to generate m tic marks along the right side of the graph when it is next re-drawn. 11.2.13 R The R command is used to re-draw the graph with the latest modifications and additions included. The tic'ed axes are included, as well as the identifying tag letters associated with each string or figure. 11.2.14 S The save command, S fnam, is used to save the current set of TVG commands as a file. The extension .TVG is automatically appended to the file name if an extension is not specified. TVG does not update the version number of the file, so if you are planning to use both the unmodified and modified versions of a file, make a copy before entering TVG. Once the file is saved, it may be recalled for modification by using the unsave command, U fnam. 11.2.15 U The unsave command, U fnam, is used to read in a previously saved file of TVG commands. The extension .TVG is assumed if no extension is specified. TVG's parsing of a saved viewgraph file is far from robust. If you have edited the file to make modifications, and the format is changed, TVG will probably abort while the file is being read in. 11.3 TVG Maker The Graphics Workstation Viewgraph Menu provides a option to design a TVG viewgraph file using TVG Maker. This option may be used by anyone using a VT100 compatible terminal. Rather than engaging in an interactive TVG session to create the viewgraph, the assumption is made that the user desires to rapidly create a prototype viewgraph with a Logo, title, and 13 equally spaced, left-justified lines. Once the viewgraph is created, TVG may be used to recall the viewgraph, modify text, text size, orientation, or position as appropriate. 11-7 GENERATING PRESENTATION VIEWGRAPHS USING TVG TVG Maker is designed to be very easy to use. First one is prompted for a viewgraph file name. The extension will default to .TVG so it may be omitted. At the filname prompt, both the TVG Window key and the TVG Help key is active. Control-Z at any input will terminate processing of this procedure. TVG will warn you if you try and use the name of an existing viewgraph file and give you the chance to select a new name. If you forget what viewgraph files are present, you also can elect to display a list of all .TVG files present on your current directory. Next you are prompted for a title for the viewgraph which may be up to 35 characters long. If your title must be longer, create your viewgraph with a shorter title, and modify it (and the character size) afterwards. Next you are prompted for 13 text strings (up to 55 characters long each). If any strings do not exist, simply type return. If you make a mistake entering a text string, press up-arrow to back up to the previous entry. To create a "Bullet" in front of each text line, precede the text you enter with a "$. " or a "$* ". When the last text string is entered, TVG Maker, merges your data with a template TVG file, to create prototype TVG file. It may then be necessary to use TVG directly to position text strings (space them out if do not need all 13), change character size (smaller size -> more text on line), create shapes, change character fonts or orientation. 11.4 Embedded Text Commands Entered text strings can contain both textual and control information. A "$" indicates that the following character is a control character. In addition the ">" and the "<" are taken to mean "shift to upper case", and "shift to lower case" respectively. When preceeded with the "$" control character, the following characters produce the following results. A Shift above the division line ($/). B Shift below the division line ($/). C Advance to the next line, single spacing. D Shift down to the first level subscript. E Shift up to exponent level. G Change to Gothic text. I Shift down to index level. J Jump back to last level command position. L Shift down to second level subscript. M Change to Math character set. N Shift to normal level. O Advance to next line, one and a half spacing. R Restore position S Save Position T Advance to next line, double spacing. 11-8 GENERATING PRESENTATION VIEWGRAPHS USING TVG U Shift up to superscript level. V Generate a vector/mean bar between occurrences ($V......$V). W Change to script character set. X Return to entry character set. Generate a half-space 3-17 Change to character set 3-29 . Generate a "Bullet". * Generate a five pointed star "Bullet". / Generate a division line between occurrences, ($/....$/). - Underline between occurrences, ($-....$-). = Double underline between occurrences, ($=....$=). < < > > $ $ Entry conditions are always set to the last font used at the normal level with upper case letters displayed in upper case fonts. However, if lower case text is entered, it is displayed in a lower case font. If no character sets are activated, the terminal character set is used and none of the control characters are interpretted. Also, when character set 9 is activated within a line, only one character is used from that set before TVG returns automatically to the entry character set. Hence to produce and integral sign, on need only type "$9I" not "$9I$X". 11.5 Character Sets Some 17 different character sets can be drawn by TVG. A program called SETS can be used to generate a complete display of the specified character sets with the exception of the character. The is a space in all sets except in character set 9 where it is a half-. The available character sets are designated by a set number which runs from 3-20. The sets are. Set Number Style 0 All sets deactivated 3 Simplex Roman 4 Simplex Greek 5 Duplex Roman 6 Complex Roman 7 Complex Greek 8 Complex Italic 9 Special and math characters 10(M) Math and special characters 11(G) Gothic English 12(W) Simplex Script 13 Complex Script 11-9 GENERATING PRESENTATION VIEWGRAPHS USING TVG 14 Gothic Italian 15 Gothic German 16 Cyrillic 17 Triplex Roman 18 Triplex Italic 20 Miscellaneous characters When using character set 9, as $9 (in a text command), only one character is accessed before the style automatically returns to the entry character set. 11-10 CHAPTER 12 THE VAX/IBM TAPE TRANSFER FACILITY 12.1 Introduction As a direct result of the well-nigh unrelenting efforts of the As a direct result of the well-nigh unrelenting efforts of the tape drives (and their masters) in VAX-land and IBM-land to tape drives (and their masters) in VAX-land and IBM-land to communicate, VPW now has the ability to transfer ASCII text files communicate, VPW now has the ability to transfer ASCII text files from the VAX to the IBM and have the IBM automatically take the from the VAX to the IBM and have the IBM automatically take the files off the tape without any input from the user!! Yes, you files off the tape without any input from the user!! Yes, you heard correctly. You can place all your VAX listing files on a heard correctly. You can place all your VAX listing files on a tape and the IBM will find them without your having to write a tape and the IBM will find them without your having to write a single line of JCL. single line of JCL. 12.2 History And Credits 12.2 History And Credits For some time a number of us have experienced extreem For some time a number of us have experienced extreem frustration at not being able to transfer data easily to the IBM frustration at not being able to transfer data easily to the IBM via tape. Sporadic attempts were made at solving the problem for a via tape. Sporadic attempts were made at solving the problem for a number of years with little success. One vendor offered a $8,000 number of years with little success. One vendor offered a $8,000 solution which would only work on with tapes generated on our RSX. solution which would only work on with tapes generated on our RSX. The stiff price tag, forced a survey of what various DECUS VAX The stiff price tag, forced a survey of what various DECUS VAX users had done. A program called AVATU (Amhdal/IBM to VAX Tape users had done. A program called AVATU (Amhdal/IBM to VAX Tape Utility) was discovered which MOSTEK had written to generate tapes Utility) was discovered which MOSTEK had written to generate tapes on their VAX in an IBM acceptable format. The program had a few on their VAX in an IBM acceptable format. The program had a few bugs, but they were fixable. bugs, but they were fixable. What remained was creating a method of generating the tape What remained was creating a method of generating the tape which did not involve significant user effort, and in creating a which did not involve significant user effort, and in creating a tape with sufficient embedded information so that the IBM could tape with sufficient embedded information so that the IBM could read all the files on the tape without the user having to write any read all the files on the tape without the user having to write any JCL. This latter is accomplished by having the first file on the JCL. This latter is accomplished by having the first file on the tape be a JCL data set whose function is to read all the rest of tape be a JCL data set whose function is to read all the rest of the files off the tape. The VAX command procedure creates this the files off the tape. The VAX command procedure creates this file on the fly as the user creates a list of files to transfer to file on the fly as the user creates a list of files to transfer to tape. It then initializes the tape and writes this file out as the tape. It then initializes the tape and writes this file out as the first tape data set. The other requested files are written out to first tape data set. The other requested files are written out to the tape as unique IBM data sets with names identical to the VAX the tape as unique IBM data sets with names identical to the VAX name (or at least close). name (or at least close). 12-1 THE VAX/IBM TAPE TRANSFER FACILITY This tape transfer facility would not be possible except for This tape transfer facility would not be possible except for the efforts of Rod Hiddleston and Carl Evans on the IBM. Carl the efforts of Rod Hiddleston and Carl Evans on the IBM. Carl Evans deserves special credit for convincing the IBM that it could Evans deserves special credit for convincing the IBM that it could read all the files on the tape, if we just primed its pump a read all the files on the tape, if we just primed its pump a little. little. 12.3 Using The Tape Transfer Facility 12.3 Using The Tape Transfer Facility To access the tape transfer facility, type VPW. At the To access the tape transfer facility, type VPW "Choice: " prompt, type "R" to access the Research Assistant menu. R On this menu is a choice labeled "Tape". Type "T". The VAX/IBM T T VAX/IBM Tape Transfer Facility menu now appears. Four choices exist; "W" Tape Transfer Facility W to write a VAX to IBM transfer tape and "R" to read the tape back R or to read a tape generated by the IBM; the PF2 key (or the HELP key) provides help information; The PF4 key accesses the command screen. 12.3.1 Writing A Tape Writing A Tape To create a tape to be read by the IBM, get a scratch VAX scratch tape. The process of placing data on the tape for the IBM will overwrite any data existing on the tape. Place the tape on the overwrite tape drive and press LOAD and ON-Line to move the tape to the Load Point. Access the tape transfer Facility and at the "Choice:" prompt type "W". The facility will ask you to mount a tape and W press RETURN when ready. If the tape can not mount for some RETURN reason, you will be warned and the process will terminate. If the tape mounts correctly, first you must select the type of VAX to IBM transfer you wish to make. Files can be transfered to individually named IBM files, or they can be incorporated into an IBM partitioned data set, or the can be directly printed (on the line printer) on transfer. Next, you will be prompted for the name of a file to transfer. The name may either be a specific file name, or it may be a wild card file name. Examples of valid file names are, FOO.FOR *.FOR FOO.* Please note that version numbers are not allowed, and only the version numbers are not allowed highest version number file will be transferred. This is because only one version of an IBM data set can exist at at time. IBM data set names will try and follow the same convention as the DEC names with the following exception. DEC file names can be 1-9 characters followed by a period, followed by a three letter extension. IBM names can be 1-8 characters followed by a period, etc. In the event that a DEC name is nine characters long the DEC name is split up to an 8 character name followed by a period followed by the one remaining character. 12-2 THE VAX/IBM TAPE TRANSFER FACILITY The existence of each requested file is verified and if it does not exist you are warned. As each file is correctly processed, a message is displayed saying the processing is being done. This message is displayed since processing a wild card (.FOR) file specifier can take a while. During this processing two files are being created. The first file is an IBM JCL file which will become the first data set on the tape. This JCL file contains instructions for getting all other files off the tape. The second file is a command file which will control the operation of AVATU in placing all the files on the tape and giving them the correct IBM data set names. When there are no more files to transfer, type a RETURN to the RETURN prompt for a file name. When this occurs, the system will tell you that it has started processing the files to tape. Be patient, it takes a while. Finally, when the operation is complete, the tape facility will tell you to remove the tape from the drive and to give it to the IBM operator with the instruction that it is DEC-TRANSFER tape. A file, IBMJCL.DAT is printed at the end of the procedure to be used if the IBM has problems. 12.3.2 Reading A Tape Reading A Tape At this time, the transfer facility directly invokes the program AVATU to read the tape. AVATU is not very "User Friendly" and if you wish to use it you should get a copy of the micro-manual we have for it. At this time no serious use of AVATU in reading IBM tapes has been made, and no attempt has been made to create a simple user interface to writing the tape at the IBM end. 12.4 Tape Transfer Restrictions Tape Transfer Restrictions Do to the inherent differences between the IBM and VAX, some limitations and restrictions in the tape transfer facility exist. 1. Only 1600 BPI tapes can be read/written by the VAX. 2. Only ASCII text files can be transferred. No binary data files allowed. 3. The IBM can not print out lowercase text. If your file has lowercase characters in it, and you try and print it out, they will be missing. This problem is fixable if you petition the IBM support group to put in an upper/lowercase band in their line printer. However, so doing will slow down print jobs which require only upper case text. 12-3 THE VAX/IBM TAPE TRANSFER FACILITY 4. The IBM doesn't have hardware TABs on its printer or terminals. A common practice on the DEC machines is to use TAB formatting when coding Fortran sources. The TAB is accepted but is counted as a single character occupying one space on printout. This makes for a very funny looking listing. I suspect that Fortran source files would have to be edited to replace TABS with spaces before compiling them. 5. No procedure yet exists on the IBM for creating tapes to be read by the VAX. One could be created, but sufficient interest must be shown to warrent the effort. 12-4 CHAPTER 13 THE VAX TOOL BOX 13.1 Introduction The VAX Tool Box provides a place where infrequently used utility functions and functions which do not belong as part of any other menu may be placed. The Tool Box menu differs from any other menu in the VPW system in that it is a "Rubber Band" menu. Conceivably, it can be as long as a given site wants, ie hundreds of lines of selections. However, only 11 lines are displayed at a time, and the user is allowed to move forward and backward in the menu by either pressing the Up/Down arrow keys or the Prev/Next keys (LK201 keyboards). 13.2 The Tool Box Menu When the Tool Box menu is first invoked, a display similar to the folowing appears. The VAX Tool Box The VAX Tool Box BAckup - Backup files to tape BA CErtify - Certify Tape CE CLock - Terminal alarm clock CL DDT - Draw Directory Tree structure DD ERrors nn - Translate VMS error codes to english ER IWQ - Insert file into WP Transfer Queue IW Open^Files - Show process's open files O F PRoblem - Submit a VAX System Problem Report PR QDisplay - Compact display of Print/Batch Queues QD RESequence - Resequence a Fortran source file RES More ... More ... Exit / - Exit to DCL / Return to previous menu E PF2 / PF4 - HELP / New VPW Window PF2 PF4 Prev / Next - Previous / Next menu screen Prev Next Choice: 13-1 THE VAX TOOL BOX The exact contents of the Tool Box menu depend on what utilities have been made available through it. The More ... in More ... bold indicates that more items are available for selection. Pressing the Next Screen or down arrow key, will "roll in" the next Next Screen page of menu items each time that key is pressed. When no more items exist, a No More ... will be displayed. Likewise, one can No More ... go backward in the menu by pressing Prev Screen or the up arrow Prev Screen key. When one reaches the top of the list of entries, a No More ... will be displayed at the top of the screen. No More ... The minimum number of key strokes to enter is highlighted in bold. Enter a selection at the "Choice: " prompt. If you are unsure how to use some function, try pressing the PF2 key for HELP. There is a good chance that HELP exists for the function you are interested in. 13.3 Adding A New Entry To The Tool Box Menu To add a new entry, two changes must be made. First, the text to be displayed in the menu must be added to SYS$SYSVPWFILES:TOOLMENU.TXT. By convention, the minimum number of allowed keystrokes required to activate a menu item are bolded by enclosing that text with the [1m/[m pair. Next, one edits VPWTOOLBX.COM to add that entry to the dispatch table of the form "IF ...... THEN GOTO My_Function". At some appropriate place in the body of VPWTOOLBX.COM add a line "$My_Function:" followed by several lines to activate the new command procedure and then return to the start of the Tool Box menu. For example $ IF Option2 .EQS. "PR" THEN GOTO Submit_VPR ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... $Submit_VPR: $ ON ERROR THEN CONTINUE $ @SYS$SYSVPWFILES:VAXPRBLM $ GOTO Start Note that the parsing of the "Choice" prompt is already done for you. The Symbols Option, Option2 and Option3 contain 1, 2, and 3 characters of the choice prompt respectively. 13-2 CHAPTER 14 VAX PROBLEM REPORTING VPW V4.0 has a new facility to report the problems our staff encounter while using the VAX. The previous, canonical methods of reporting a problem was for the person encountering the problem to walk to the system manager's office with the problem in hand, call the system manager on the phone, or have the system manager paged. While this is undoubtedly the most direct and straight forward method of reporting a problem and getting help, it has its drawbacks. At times there was no one available to report the problem to. At other times, lines existed outside of the system manager's office and some persons with problems had to wait for a considerable time for someone to get around to them. No log was kept of the number of problems worked on, so no solid information was generated as to how much staff support is necessary for running the VAX and solving problems when they occur. Moreover, since no record was kept as to what problems were encountered and solved, the solutions discovered for a particular person could not be directly transferred to another person with a similar problem. Finally, there was no way of splitting up the work between our more knowledgeable staff. The first person cornered was the one stuck with providing a solution. The VAX Problem Reporting facility tries to address these problems. 14.1 Introduction The VAX Problem Reporting Facility (VPR) may be accessed from VPW from either the VAX Data Base Menu or from the VPW Utility Tool Box menu. VPR should be useful both for those of us who have problems to be answered and for those of us interested in finding answers before encountering problems. It provides the VAX user with the ability to; 14-1 VAX PROBLEM REPORTING 1. Submit a problem report. 2. Supply new information (Update) for an existing problem report. 3. Obtain an index of all problem reports or just those reports concerning specific topics/keywords. 4. Read an answer to a problem report. In addition, VAX operators can use VPR to answer a VPR submitted by VAX user. The design of VPR is such that it can provide a centralized problem reporting and solution services across our entire VAX network and will tie SPR answers (DEC's problem solutions) into our internal problem reporting/answering system. When a problem is encountered, the VAX user should first determine how serious it is. If the computer has caught fire, a loud, screaching noise is coming from a disk drive, the terminal is smoking, or some condition is preventing you from doing something critical or getting any useful work done (your disk quota went to zero), then don't worry about VPR. Go find a person who can provide HELP in real time. For most other non-life threatening situations, it is preferable for you to submit a VPR. When you submit a VPR, the following things happen. 1. The person(s) in charge of answering VAX Problems are immediately notified (via MAIL) that you have submitted a problem report. 2. The problem report is entered into our VAX's VPR data base. 14.2 Using The VAX Problem Reporter When VPR starts up the following menu is displayed. VAX System Problem Report VAX System Problem Report Choose: Submit - Submit a problem report S Answer - Answer a problem report A Data Base - VPR Data Base Manager D B Index - Index of problem reports I Read - Read a problem report and its answer R STatus - View status of a VPR(s) ST Update - Update an existing problem report U Exit - Exit E PF2 / PF4 - HELP / New VPW Window PF2 PF4 Choice: 14-2 VAX PROBLEM REPORTING The PF2 (or HELP key on VT2xx terminals) will provide help in using VPR and the PF4 (or F20 key on VT2xx terminals) will provide you with a new window in case you want to temporarily exit from VPR (answer mail, send mail, etc.). The Answer and Data Base options A D B only appears in the display for VAX operators who are allowed to answer problem reports. Problem reports can exist in three major states. When an index of problem reports is done, the state and impact of the reports is displayed. 1. The state/impact may be OPEN. When a report is first submitted it is marked as being open (unless FYI only). This means that a solution, or final solution has not yet been supplied. Either work will (or should) continue in supplying a solution, or the problem has been submitted to DEC (via an SPR) for a solution. Four subcatagories of OPEN exist. They are OPEN/URG, OPEN/SEV, OPEN/MOD, and OPEN/MIN depending on whether the problems impact on the staff is rated as Urgent, Severe, Moderate, or Minor. 2. The state may be CLOSED. When an operator supplies a "final" solution for an outstanding OPEN problem, the operator should mark the problem report as being closed. No further action is scheduled on CLOSED problem reports. 3. The state may be SPR_SENT. If analysis of the problem report indicates that the problem is caused by a problem inherent in DEC's software (i.e. a BUG), a problem report known as an SPR (Software Performance Report) is sent to DEC. If this happens, SPR_SENT is marked as the status of the VPR and the local SPR submittal code is set in the VPR index to cross reference the SPR answer when it arrives from DEC. The SPR Database option may be selected from the VPW Data Base menu and this facility used to track the status and answer to the SPR. 14.2.1 The Submit Option When you elect to submit a VPR, the system prompts you for a statement of the problem. Briefly summarize your problem in a single line of up to 70 characters. Include keywords which will help others know what software/hardware component caused your problem. This is important for using the Index function because it can be used to search for specific topics. For example, if you encounter a problem with DECALC when reproducing cells within a spreadsheet the statement "DECALC fails when reproducing cells" is far, far more useful than, "Reproducing does not work" and is far, far less likely to get a somewhat funny answer requesting additional details on the problem. 14-3 VAX PROBLEM REPORTING After entering your statement of the problem, you will be asked to rate the severity level of the problem. The choices are Urgent, Severe, Moderate, Minor and Closed (FYI). If the severity level of the problem is greater than Moderate, please explain why when VPR asks you edit in the description of your problem. Next you will be dropped into the editor at the bottom of a prototype problem report. It is assumed that you know how to use our editor, VPWEDIT. You can do anything you can do normally in the editor including incorporating text files into your VPR which illustrate your problem. For example, you have a short Fortran program which does not work. Well, it can be included. In general though, if you have a long program, or a listing, or a copy of the terminal screen which is relevant to your VPR, include in the VPR the information necessary to access this external information. For example, you have a Fortran program which just will not compile. In the VPR include a line to the effect that "my file KMS$FEDUSR1:[DOWNWARD]FOOBAR.FOR will not compile". Then leave that file alone. Do not delete it since the person answering you VPR will undoubtedly want to look at it. Or if you have a listing or screen copy, mark on the listing or screen copy the number assigned to the VPR. Include in the VPR a statement to the effect that the listing has been left in the Mail Box of VPR$MANAGER. You can find out who VPR$MANAGER is by typing the command $ SHOW LOGICAL VPR$MANAGER When, VPR mails you notification that your VPR has been submitted, the message tells you whom the problem was submitted to. When you have finished typing in a description of your problem (and please give as much detail as possible), exit from the editor by typing PF1 7 EXIT (GOLD Command Exit). When you do this, VPR PF1 7 EXIT will prompt you and ask you if you really want to send it. If you answer "Y" or "y" or some form of "Yes", the report will be added to the VPR data base (on VPR$FILES), the VPR index will get updated, and VPR$MANAGER will get sent a mail message saying that you just submitted VPR Number xx. VPR will also send you a mail message saying that you submitted VPR Number xx. This is for your records. 14.2.2 The Answer Option Only system operators may use the answer option. It does not display on the standard menu. When selected, the operator is prompted for a VPR Number to answer. Just as with the read option, the VPR and leading "0"s may be omitted. If the operator has just read a VPR, that VPR number becomes the default VPR number for 14-4 VAX PROBLEM REPORTING answering and simply typing a return will select answering that VPR. At other times, a RETURN will simply return the operator to the main menu. When the operator selects a VPR number to answer, the operator is first asked the name of the component (software program) causing the problem and the length of time required to solve the problem. The operator should implicitly add in the length of time required for editing in the answer to the VPR. The operator is then dropped into the editor and may type in an answer. When the operator exits the editor, VPR prompts to ask if the operator wants to send the VPR answer. If the answer is "Yes", the operator is asked for the VPR's disposition (Open, Closed, SPR_Sent). At any prompt for O C S input, sending the VPR answer may be aborted by typing Control-Z, except, of course, while you are in the editor. Finally, the VPR answer is placed in the VPR$FILES, the VPR index is updated to reflect the date of answer, VPR's status, and the disposition of the VPR and the user submitting the VPR is mailed a message stating that the VPR has been answered. 14.2.3 The Data Base Option The Data Base option drops an operator into the VPR flavor of NOTEBOOK. This option is only available to system operators. At this point the operator can directly manipulate the records in the VPR index file VPR$FILES:VPRLST.FIL. If desired the operator can modify the abstract (statement of the problem) or any other record in the index. The use of Notebook is documented in the VPW users manual. 14.2.4 The Index Option If you select the Index option, you are prompted for a search string. If you just hit RETURN, you will get the index of all existing VPRs. However, you may enter a search string obeying all the rules for NOTEBOOK searches. You can search on just on topic, ie enter, OPEN, and get a list of all OPEN reports (and any reports specifying problems with OPEN), or you can specify multiple search strings separated with "|" (vertical bar). To obtain an index of all problems for which an SPR was sent which related to DCL one would enter SPR_SENT|DCL. When the index is complete, you are asked to "Press RETURN when ready" and when you do, you return to the main menu. 14-5 VAX PROBLEM REPORTING 14.2.5 The Read Option When you select the READ option, you are prompted for a VPR number to read. A simple RETURN or Control-Z at this point returns you to the main menu. If you don't know which one, use the INDEX option. You also can enter a "?" to get a directory of all existing VPRs. Enter a valid VPR number. You may enter this number exactly as in the index, or you may omit the leading "VPR" or any of the leading "0"s in the VPR number. If you do not enter a valid VPR number, the system will tell you and ask you again to enter a number. If you enter a valid VPR number, first the VAX problem report is typed out to your terminal. Next, if an answer exists, the answer is displayed. If the answer does not exist, the status of the VPR is displayed. Finally, when the displaying of the report and its answer(s) (if any) are complete, you are asked to "Press RETURN when ready". If you do so, you return to the prompt asking for a VPR report number to read. However, at this point system operators may choose to type ANSWER, and immediately drop into VPR answering mode. If they do so at this point, the last VPR read becomes the default VPR to answer. When a VPR answer is typed to your terminal, you should note several things. First, at the top of the VPR answer is the name of the person answering your problem. If you do not understand the answer, or if the answer just does not work, or if you have a comment on the answer, you should consider mailing that person a message stating your problem (maybe even phone them if the problem is seriously hindering your work). You might also consider updating the VPR which again marks it as OPEN. and notifies VPR$MANAGER that the VPR has been updated. Next, you should note the length of time which was spent in answering your problem. We currently do not have any staff whose primary function is VAX user support. Time spent solving problems, is it time not spent doing their primary function. If your problems are caused by software just not working properly, they should be reported at once as they will affect everybody's work. On the other hand, if the problems are caused by not having read the appropriate manual or documentation, perhaps it would serve both the company's and your interest for you to get the appropriate manual or documentation and read it. 14.2.6 The Status Option The Status option is similar to the Index option except that all status information on a VPR or a collection of VPRs is displayed. When chosen, you are prompted for Selection Criteria. At the prompt enter the selection criteria separated by vertical bars. Useful criteria might be the VPR number, the keywords OPEN, 14-6 VAX PROBLEM REPORTING CLOSED, or SPR_SENT, the name of the user submitting the VPR, or even a possible topic of interest such as VPW. For example at the selection prompt one could enter VAVRA|OPEN|VPW to find out the status of any open VPRs sent by VAVRA which were either marked as having VPW as the problem component or for which the keyword VPW appeared in the VPR problem statement. 14.2.7 The Update Option The Update option exists for those of you who enter a VPR and later discover that you have more information available which should be added to the original. It can also be used to update and request that the VPR be reopened if the answer to the original VPR does not meet your needs. Please note, any user on the VAX can update an existing VPR with additional information. However, only the original user will be notified by VPR$MANAGER of answers to the VPR and any of its updates. When you request an update, you will be prompted for a number of a VPR to update. You may only update an existing VPR. If you select an existing one, you will be dropped into the editor to edit in your information. When done, exit from the editor and you will be asked if you want to complete updating the VPR. If you answer yes, you will be asked to restate the severity/impact of the VPR and then the VPR will be updated. If you answer anything but yes, you will be informed that the VPR was not updated, and you will be returned to the menu. 14-7 CHAPTER 15 THE VAX DESK CALCULATOR 15.1 Introduction This chapter documents the use of CALC, the VAX Desk Calculator. CALC may either be accessed from the VAX Professional Workstation menu or as a foreign command (defined by SYS$SYSVPWFILES:SETVPWSYM.COM during SYSLOGIN.COM) by typing CALC. CALC is a calculator designed to evaluate arithmetic expressions. In its basic form, expression evaluation is similar to that used by ANSI FORTRAN with calculations performed on INTEGER4 and REAL8 constants. Variables may also be invoked but 4 8 are limited to single alphabetic characters. It is assumed that the reader is familiar with FORTRAN data types, constants, expression syntax, operator precedence, and the syntax for assigning values to variables. Additional features include octal, hexadecimal, and multiple precision arithmetic capabilities. Commonly used commands and expressions can be placed in a file and executed when convenient. 15.2 Getting Started When invoked, CALC prompts for input with CALC> Try typing 123+456 followed by a carriage return. CALC will evaluate the expression and output the answer 579 It then prompts for further input. Try other expressions such as 12.0 - 99. (answer=-87.00000000000000) 15-1 THE VAX DESK CALCULATOR -(-32767+(6-2)**8-(512/(409-401))) (answer=-32705) 3*5/7 (answer=2) 3*(5/7) (answer=0) Mixed mode is legal, for example 1977/50. is evaluated as 39.54000000000000 Reals may be expressed using D or E format. For example 1.2E10*2.D0**3-1.D-8 is evaluated as 0.95999999999999992D+11 Variables may also be used to retain values for later use. CALC allows variables consisting of a single alphabetic character. As in FORTRAN, variable A through H and O thru Z default to type real, I thru N to type integer. To set I to a value use the usual FORTRAN syntax, for example: I=2**10-1 Try typing the single character 'I'. CALC will respond with its value. We can now use I in various expressions such as J=I-I/3*3 % is a special variable that retains the value of the last expression evaluated. For example, to add up the numbers 1, 2, 3, 4, 5, and 6 successively, we could enter 1 %+2 %+3 %+4 %+5 %+6 Note that you can examine the value of the variables by typing the appropriate single character followed by a carriage return. Such an examination does not change the value of %. To exit from CALC, type *E (or *EXIT) or *S (or *STOP) or Control-Y 15-2 THE VAX DESK CALCULATOR 15.3 Special Functions CALC recognizes a variety of special functions. For example, to calculate the square root of 2, we can type SQRT(2.) CALC responds with the value 1.41421356237310 Each function may have an expression for its argument. For example, A=2.0*SQRT(ALOG(9.)+3.) sets A to 4.55948443459838 The following special functions are available: FUNCTION NAME ARGUMENT TYPE FUNCTION VALUE DESCRIPTION -------------------------------------------------------------------------- ABS REAL REAL absolute value DABS REAL REAL absolute value IABS INTEGER INTEGER absolute value IFIX REAL INTEGER convert REAL to INTEGER AINT REAL REAL REAL truncation INT REAL INTEGER convert REAL to INTEGER IDINT REAL INTEGER convert REAL to INTEGER EXP REAL REAL e**X DEXP REAL REAL e**X ALOG REAL REAL natural logarithm DLOG REAL REAL natural logarithm ALOG10 REAL REAL logarithm base 10 DLOG10 REAL REAL logarithm base 10 SQRT REAL REAL square root DSQRT REAL REAL square root SIN REAL REAL trigonometric sine DSIN REAL REAL trigonometric sine COS REAL REAL trigonometric cosine DCOS REAL REAL trigonometric cosine TANH REAL REAL hyperbolic tangent DTANH REAL REAL hyperbolic tangent ATAN REAL REAL arc tangent DATAN REAL REAL arc tangent 15.4 Working In Octal And Hexadecimal You may change the base used to specify constants by using the B command. Legal forms are B command action ------- ------ 15-3 THE VAX DESK CALCULATOR *B displays current default base *B 8 changes default base to octal *B 10 changes default base to 10 *B 16 changes default base to 16 Suppose we have changed the default base to octal. Then adding 7 + 1 we obtain the result 00000000010 (BASE 8) If the default base is hexadecimal, we can enter 9 + 1 which is evaluated as 0000000A (BASE 16) Suppose we have assigned A=1 then 1+A gives 2.000000000000000 even when the default base is 16. If we wish to add the hexadecimal digit 'A' to 1, enter 1+0A We now obtain the desired 0000000B (BASE 16) This leading 0 is only necessary when the first hexadecimal digit is greater than 9. If constants are entered with digits that are not legal for the base being used, the entire number is converted using a more appropriate base. For example, if we have set the default base to octal and type 1+9 the 9 is not an octal number so it is converted to base 10. If a base 16 15-4 THE VAX DESK CALCULATOR number is involved, the result will be in base 16. You may temporarily change the base for a single integer constant by preceeding it with ^8 for octal ^10 for base 10 ^16 for base 16 For example, if the default base is 10, 100+^840 gives 132 a base 10 integer. I=100+^1610 gives 116 also a base 10 integer. Note that the '^' can only be used to specify the base of constants and that expressions such as ^16I are illegal. To declare variables to be integers of a specific base, we can use the commands *INTEGER (base 10) *OCTAL (base 8) *HEX (base 16) For example, *INTEGER A declares variable A to be a base 10 integer. *HEX B,Z,F declares variables B, Z, and F to be base 16 integers. *DECIMAL lists all the variables that have been declared to be of type DECIMAL. To summarize, there are three distinct ways of making base declarations when using CALC. The first is to use the B command to B designate the base default value. This is used to determine the base for constants when they occur in expressions. It does not in any way influence the type of any variables found in an expression. The only way to change the type of a variable is with a specific CALC command such as *INTEGER A,B 15-5 THE VAX DESK CALCULATOR Suppose for example that the default base is 10 and we enter *OCTAL A A=100 then CALC responds with 00000000144 (BASE 8) Finally, the last way to change a base is to use the explicit base specifiers for a constant, for example ^10 123 ^8 777 ^16 AB 15.5 Multiple Precision Normally integer arithmetic (base 8, 10, and 16) is done internally with INTEGER4 variables. To allow for larger numbers, 4 CALC has multiple precision capabilities that allow numbers up to 99 digits to be manipulated. Constants are converted to a multiple precision data type when the number of digits specified exceeds a certain value. This value depends upon the specified base. Leading zeroes are included in this count and can be used to force constants to be of type multiple precision. base maximum number of digits before conversion ---- ------------------------------------------ 8 10 10 9 16 7 Suppose we type (with the default base of 10) the number 1234567890 then CALC echoes with 1,234,567,890 (BASE 10) The commas indicate that % now has type multiple precision base 10. Similarly, typing 1234ABCD results in 15-6 THE VAX DESK CALCULATOR 1234,ABCD (BASE 16) Notice that base 16 multiple precision numbers are separated by commas every 4 digits, octal and base 10 numbers every 3 digits. You may perform the usual operations of addition, subtraction, multiplication, division, and exponentiation. As of version 1.0, exponentiation of a multiple precision number may only be to a non-negative integral power. To declare variables of type multiple precision, use *M8 (multiple precision base 8) *M10 (multiple precision base 10) *M16 (multiple precision base 16) for example, *M8 A,B declares A and B to be multiple precision octal variables. Then typing A=32768 results in CALC responding with 100,000 (BASE 8) 15.6 Additional Commands All commands to CALC (as distinguished from expressions to be evaluated) begin with an asterisk. To obtain a list of all possible commands, type a question mark followed by a carriage return. Most of the commands have already been described. The following section gives an explanation of the remaining commands. COMMAND DESCRIPTION ------- ----------- *@filename Where filename is the name of a file of CALC commands. CALC reads the file and executes the commands. Up to 5 nested calls can be made. Recursive calls are not allowed. CALC prompts with CALC before each command line is executed, where n is the calling level. You may optionally follow the file name with a blank followed by a single variable name (a single alphabetic character or %). CALC will then execute the file until 15-7 THE VAX DESK CALCULATOR the value of that variable is zero or negative. The test of this variable is made before the file is executed and not during execution of commands within the file. If the variable's value is not positive when the command is initially encountered, the file will not be opened for execution. See the section on command file examples for ways to use this option. *ASCII Declares a list of variables to be of type ASCII. This is useful when decoding ASCII characters. For example, if we set A to be of type ASCII, then typing A=77 results in the character 'M' being output. The inverse operation is the single quote. It allows us to specify a single ASCII constant. For example, if we type 'M then the character 'M' is echoed and indicates that % holds that character and has data type ASCII. Suppose that the variable I has data type INTEGER. Then we can output the base 10 code for the ASCII character 'M' by entering I='M which results in 77 being output. Notice that you may not be able to enter certain control characters that are intercepted by your operating system. Characters whose value is less than 32. are output by printing the character '^' followed by the equivalent ASCII character of that number plus 32. For example, A=10 results in ^* being output since 42 is the ASCII code for the character '*'. See apendix A for a table of the characters output by CALC to represent such non-printable characters. *C COMMENT line. The characters that follow are ignored by CALC. This is useful when documenting files containing CALC commands. 15-8 THE VAX DESK CALCULATOR *N NOVIEW. Prevents CALC from outputting the value of the expressions evaluated. This is especially useful when executing files containing CALC commands that initialize variables to special values. Equivalent to *V 1 *V VIEW. Controls CALC's printing options: command output class ------------- -------------- *V 0 error messages *V 1 error messages command lines read from files *V 2 error messages value of expressions evaluated *V 3 error messages command lines read from a file value of expressions evaluated *V same as *V 3 The default setting is *V 3. Notice that other legal forms are *VIEW 1 and *V2 *R READ. Allows a single line to be read from the terminal. Useful in files of CALC commands to allow additional commands to be entered (like *S to exit from that file) or simply as a way to halt terminal output until the carriage return key is pressed. *REAL declares specified variables to be REAL*8. When the values of such variables are output, FORTRAN's D format is used. *DECIMAL Declares specified variables to be REAL*8. When the values of such variables are output, FORTRAN's F format is used. Variables A-H and O-Z default to type DECIMAL. *S STOP. Same as *E *E EXIT. Terminates CALC session unless it is used within a file of CALC commands. In this case, CALC closes the file and continues with the next command. *Z ZERO. Zeroes all variables except %. Data types are not 15-9 THE VAX DESK CALCULATOR changed. 15.7 Additional Features CALC has a HELP command. When CALC is prompting (CALC>) you may type either HELP or ? followed optionally by a keyword. If no keyword is present, a list of available keywords for obtaining help will be displayed. HELP works just like getting normal HELP from the VAX system. If a given keyword has help under several sub-topics, you can request HELP on specific sub-topics by typing HELP etc. CALC is similar to FORTRAN with respect to operator precedence. Blanks may occur anywhere on a command line without effect except after a single quote mark used to specify a single ASCII character constant. CALC extends the ANSI FORTRAN syntax by allowing the following: 1. Multiple assignments on one line. For example, I=J=K=812 2. Unary + and unary - are allowed. For example, 2*-3 +2+-7 -2**4 are all legal. The last expression evaluates to 16 because the unary - has a higher precedence than exponentiation. 3. exponentiation may be indicated by using ! as well as ** If any of the declarations are entered (such as INTEGER or M8) I M and no argument to this command is given, then CALC will print out the variables that have been assigned that data type. Note that a variable can be assigned to different data types using such commands and still not be assigned a value. If you attempt to output the value of such a variable, an error message will result. 15.8 Command File Examples EXAMPLE 1: PROBLEM: Be able to enter the coefficients of a second degree polynomial and have the roots output. Solution: Create the following file and call it ROOT: *CALCULATES THE ROOTS OF A 2ND DEGREE EQUATION 15-10 THE VAX DESK CALCULATOR *C YOU WILL BE ASKED TO ENTER THE VALUES OF *C A,B AND C WHERE *C *C 2 *C A X +B X + C = 0 *C *C *C ENTER THE VALUE OF A *R A=% *C ENTER THE VALUE OF B *R B=% *C ENTER THE VALUE OF C *R C=% *C THE ROOTS ARE: X=(-B+SQRT(B*B-4.*A*C))/2.*A Y=(-B-SQRT(B*B-4.*A*C))/2.*A *C *C AS YOU CAN SEE BECAUSE A*X*X+B*X+C A*Y*Y+B*Y+C Then run the procedure by entering CALC and typing *@ROOT 15-11 THE VAX DESK CALCULATOR EXAMPLE 2: PROBLEM: Suppose we are working on a problem that requires us to convert many decimal 16 bit word addresses to octal byte address. We would like to be able to simply enter the decimal word address and have CALC respond with the octal byte address. SOLUTION: Create a file of the following commands and call it BYT: *C *C *C *C *C ENTER DECIMAL WORDS *R A=%+% Then we enter CALC and type the following: *OCTAL A (to make A an octal variable) 1 (to set % to a non-zero number) *@BYT % (to execute the file of conversion commands) We will then repeatedly execute the file BYT until we enter a zero as the number to be converted. 15-12 THE VAX DESK CALCULATOR EXAMPLE 3: PROBLEM: We wish to set up a command file called SIGN that allows us to enter a number, and then execute the files MINUS, ZERO, and PLUS according to the value entered. SOLUTION: Create the file SIGN consisting of: *C ENTER THE NUMBER WHOSE SIGN IS TO BE DETERMINED *R I=J=% I=-I K=1 *C K STAYS AT 1 IF NUMBER IS NON-ZERO *@MINUS I *@PLUS J *@ZERO K The file MINUS: *C THE NUMBER IS NEGATIVE I=K=0 The file PLUS: *C THE NUMBER IS POSITIVE J=K=0 and the file ZERO: *C THE NUMBER IS ZERO K=0 Notice that K is used to control the execution of the file ZERO by initializing it to 1 and resetting it to zero if either of the files PLUS or MINUS are executed. 15-13 THE VAX DESK CALCULATOR EXAMPLE 4: PROBLEM: Enter the number N and calculate the numbers 1!, 2!, 3!, 4!, ... N! where N! = N*(N-1)*(N-2)*...*3*2*1 SOLUTION: Since the numbers may grow very large, we will use a multiple precision variable. Create the following files: MFACT: *C INPUT THE LIMIT OF THE FACTORIAL LIST *V 0 *R N=% *M10 A I=0 *@MF1 N *C SET VIEW AND TYPE FOR VARIABLE A AT DEFAULT VALUES *DECIMAL A *V MF1: A=1 N=N-1 I=I+1 J=I *@MF2 J *V2 A *V0 MF2: A=A*J J=J-1 We then enter CALC and type *@MFACT A typical run of this procedure would look like: 15-14 THE VAX DESK CALCULATOR >CAL CALC>*@MFACT CALC<2>*C INPUT THE LIMIT OF THE FACTORIAL LIST CALC<2>*V 0 CALC<2>4 1 (BASE 10) 2 (BASE 10) 6 (BASE 10) 24 (BASE 10) CALC> 15-15 THE VAX DESK CALCULATOR EXAMPLE 5: PROBLEM: We wish to specify a default base and successively add numbers into a sum. SOLUTION: Create the following files of CALC commands: ADD: *V *C ENTER DEFAULT BASE *R *C CHANGE DATA TYPE OF SUM *C BY SPECIFYING THE DATA TYPE FOR I AND J *R *C TO EXIT, TYPE 0 TO ZERO OUT, ADD -I *V0 I=0 1 *@ADD1 % *V ADD1: *V *R *V0 J=% I=I+% *V2 I *V0 %=IABS(J) Then we invoke the procedure by typing *@ADD A typical run follows: CALC>*@ADD CALC<2>*V CALC<2>*C ENTER DEFAULT BASE CALC<2>*R CALC<2>*B 8 DEFAULT BASE IS 8 CALC<2>*C CHANGE DATA TYPE OF SUM CALC<2>*C BY SPECIFYING THE DATA TYPE FOR I AND J CALC<2>*R 15-16 THE VAX DESK CALCULATOR CALC<2>*OCTAL I,J CALC<2>*C TO EXIT, TYPE 0 TO ZERO OUT, ADD -I CALC<2>*V0 CALC<3>177 00000000177 (BASE 8) CALC<3>1 00000000200 (BASE 8) CALC<3>0 00000000200 (BASE 8) CALC> 15.9 Usage Notes Version 1.0 1. When you iterate on a file by a call such as *@REPEAT X then note that A) X must have been set to a positive value when the command is executed or else the file will not be executed. B) If the file of commands does not change the value of the variable X you will enter an infinite loop. You can explicitly set X to a non-positive value, use the *Z command to zero it (if it is not %), or include a *R command to give you a chance to reset the variable and get out of the loop. C) *E and *S will allow you to exit from the command file REPEAT but will not of themselves prevent repetitions. D) Entering constants echo on the terminal (assuming *V is properly set) and can change the value and type of the variable %. This is important to remember when using % to control the iteration of a file. 2. When you first enter CALC, the variable % has type INTEGER and holds the version number of the program. 3. In practice, multiple precision arithmetic may be limited to less than 99 digits because of your terminal's inability to print that many characters. 4. No implicit conversion is made to multiple precision when operations with reals or integers cause an overflow. This was done in version 1.0 in case the multiple precision routines have to be removed when 15-17 THE VAX DESK CALCULATOR creating a small task image for some operating system. 5. In FORTRAN, -A**2 is the same as -(A**2) with CALC, -A**2 is the same as (-A)**2 (just like SNOBOL!) 6. If R and A are positive reals and I is a positive integer, some compilers like RSX-11M's F4P won't allow (at run time) evaluation of (-I)**R (-A)**R 7. Under RSX-11M F4P you will find 2**.5 to have value 1 while 2.**.5 has value 1.41421356237310 8. 10E10 is a hexadecimal constant (integer) while 10.E10 is a real. 15-18 THE VAX DESK CALCULATOR 15.10 Appendix A ASCII CALC ASCII CALC ASCII CALC ASCII CALC CODE PRINTS CODES PRINTS CODE PRINTS CODE PRINTS ---- ------ ----- ------ ---- ------ ---- ------ 0 ^ 32 64 @ 96 ` 1 ^! 33 ! 65 A 97 a 2 ^" 34 " 66 B 98 b 3 ^# 35 # 67 C 99 c 4 ^$ 36 $ 68 D 100 d 5 ^% 37 % 69 E 101 e 6 ^& 38 & 70 F 102 f 7 ^' 39 ' 71 G 103 g 8 ^( 40 ( 72 H 104 h 9 ^) 41 ) 73 I 105 i 10 ^* 42 * 74 J 106 j 11 ^+ 43 + 75 K 107 k 12 ^, 44 , 76 L 108 l 13 ^_ 45 - 77 M 109 m 14 ^. 46 . 78 N 110 n 15 ^/ 47 / 79 O 111 o 16 ^0 48 0 80 P 112 p 17 ^1 49 1 81 Q 113 q 18 ^2 50 2 82 R 114 r 19 ^3 51 3 83 S 115 s 20 ^4 52 4 84 T 116 t 21 ^5 53 5 85 U 117 u 22 ^6 54 6 86 V 118 v 23 ^7 55 7 87 W 119 w 24 ^8 56 8 88 X 120 x 25 ^9 57 9 89 Y 121 y 26 ^: 58 : 90 Z 122 Z 27 ^; 59 ; 91 [ 123 { 28 ^< 60 < 92 \ 124 | 29 ^= 61 = 93 ] 125 } 30 ^> 62 > 94 ^ 126 ~ 31 ^? 63 ? 95 _ 127 15-19 CHAPTER 16 THE VAX NOTEBOOK 16.1 Introduction The VAX NoteBook is designed to handle small, personal, user defined data bases. NoteBook V2.6 has a number of new features. These include 1. Support for editing binary X-Y graphic data files. 2. Support for multiple graphic data file types (for future use). 3. Support for VT240 terminals. 4. Limited support for binary data (Integer*2, Integer*4, Real*4). 5. Support for command line processing of keywords. Special keywords now exist to set the data file name and bypass the main menu so as to immediatly perform some function (make NoteBook act like an external subroutine). The VAX NoteBook assumes that one wishes to do a limited number of things with a private data base. These include; o Create the data base. o Add records to the data base. o Modify records in the data base. o Delete records in the data base. o Display selected records in the data base. o Use alternate data files o Provide extensive on-line help at each step. The VAX NoteBook's behavior is table driven: Menus, prompts, and display format are all controlled by external modules in a text library. To create a new data base all that is necessary is to give it a name, create the control tables and add them to the text library which either may be the system text library or a private one. This makes it exceptionally easy to change a database to add 16-1 THE VAX NOTEBOOK functionality or to add a new one. For the present time, only the system text library is supported but private databases can easily be designed on request. Eventually a user bombproof design tool for creating private data bases could be provided. Currently supported applications include: o The VAX Document Manager o The VAX Phonebook o The KMS Staff Directory o The VAX Problem Report Manager o The VAX Reference Library o The VAX SPR Manager o The VAX Security File Manager o The VAX Drawing File o The X-Y Graph Data Editor The VAX NoteBook is not intended to be a full fledged data base manager or even a DATATRIEVE. It is designed for those applications which do not need the sophistication of DATATRIEVE, do not need ISAM files, do not desire to store information in binary format, but which do need form-driven screen data entry and the ability to modify and delete records simply from the data base. Possible applications might include: o Slide and Graphic Arts drawing files. o Local departmental inventory lists inventory control easier. o Log of purchase orders sent, date expected, etc. o Data base for selected target shot results. o Project planning data base to keep track of tasks, target dates, completion dates, and drop dead dates. o Departmental or company document inventory. o KMS library list. What we have, who has what. o Daily logs of activities for inclusion in monthly reports. As noted above, NoteBook also provides support for editing a binary X-Y Graphic data files. The format of these files is documented in the chapter which discusses TEKgraph. In this mode, NoteBook works completely differently than in its other modes to proved a spread-sheet like editor for graphics data. At present a NoteBook data file (except for graphics file) has the following limitations: o Data is generally stored as ASCII character data although limited support for Integer*2, Integer*4, and Real*4 data exists. o NoteBook data files are sequential. o NoteBook stores data as fixed length records whether or not all input fields are filled. o Search and delete operations require reading all records up to the desired record. Binary data can not be searched for. For large files, ISAM files might be better. 16-2 THE VAX NOTEBOOK o Each record is limited to a maximum fo 512 bytes. o The record can contain up to 20 separate data input fields. o Output report formats are limited to formats which can be stored in a 132 character Fortran format array. o A maximum of 10 display formats may exist for any given program This chapter will describe generically how to use NoteBook. For help with a given NoteBook program, type HELP Program_Name. Most of the HELP information is available interactively from within NoteBook. 16.2 Accessing NoteBook The command $NOTEBOOK:=="$SYS$SYSVPWFILES:NOTEBOOK" is defined automatically when the user logs on (in SYSLOGON.COM via SYS$SYSVPWFILES:SETVPWSYM.COM). To use it, type NOTEBOOK and it will prompt, "NoteBook Program: ". Enter an allowed program name (ie PhoneBook, Journals, Security, etc), and the requested program will start up. NoteBook allows its known programs to be more simply accessed however. You can define a specific NoteBook program as a command by $PROGRAM:=="$SYS$SYSVPWFILES:Notebook Program" NoteBook can be used non-interactively, ie to search a file for a string and print it out in a given display format, by defining the command $PROGRAM:=="$SYS$SYSVPWFILES:NoteBook Program Form_Number " where Form_Number is a number from 1-10, and is a recognized display format number for the NoteBook program. Each NoteBook program has a number of display formats which were defined when the NoteBook program was created. Now if you type $PROGRAM Search_String all records containing the Search_String in the database will be displayed using the output form Form_Number. NoteBook gets its control information from SYS$VPWFILES:VPW.TLB and its HELP information from SYS$VPWFILES:VPW.HLB. Hence if you wish a private data base which NoteBook can access, you can create private copies of VPW.TLB and VPW.HLB and assign SYS$VPWFILES to the directory on which they reside. 16-3 THE VAX NOTEBOOK $ASSIGN [directory_name] SYS$VPWFILES Somewhat more elaborite command strings to notebook can make use of command line keywords to set the default file name and start execution immediately in the selected menu. Additional documentation on how the parsing works is included in the NoteBook subroutine GETPRGROM.FOR. The reserved command line keywords are $FILE=fname and $BYPASS=menu_key If a $FILE=fname is found, the file name become the default data $FILE=fname file name. If a $BYPASS=Menu_Name is found, VPW bypasses the main $BYPASS=Menu_Name menu and starts up immediately in the specified menu. GRFMASTER uses this feature to invoke the X-Y Graphic Editor for a specific file. 16.3 Existing NoteBook Programs The following commands define the existing NoteBook programs. $ALIST: =="$SYS$SYSVPWFILES:NOTEBOOK PHONEBOOK 1 " $DOCUMENTS:=="$SYS$SYSVPWFILES:NOTEBOOK DOCUMENTS" $DRAWFILE:== "$SYS$SYSVPWFILES:NOTEBOOK DRAWING" $GRAPHXY: =="$SYS$VPWFILES:NOTEBOOK GRAPHXY $FILE=fname" $JOURNALS: =="$SYS$SYSVPWFILES:NOTEBOOK JOURNALS" $KLIST: =="$SYS$SYSVPWFILES:NOTEBOOK KMSBOOK 2 " $NOTEBOOK: =="$SYS$SYSVPWFILES:NOTEBOOK" $PHONEBOOK:=="$SYS$SYSVPWFILES:NOTEBOOK PHONEBOOK" $PLIST: =="$SYS$SYSVPWFILES:NOTEBOOK PHONEBOOK 2 " $SECURITY: =="$SYS$SYSVPWFILES:NOTEBOOK SECURITY" $SPR: =="$SYS$SYSVPWFILES:NOTEBOOK SPR" 16.4 Terminal Requirements NoteBook was designed to run on VT100 terminals with the advanced video option. However, an attempt was also made to insure that it would run, albeit not very nicely, on hard copy terminals or (shudder) NBI pseudo-terminals. The convenience of being able to use the keypad to drop into VPW> command mode, get help, backup to previous records, and dynamically view a record being modified, strongly suggest that it is best to find a VT100 terminal if one wishes to use its features interactively. 16-4 THE VAX NOTEBOOK 16.5 The NoteBook Keypad Many features of NoteBook can be controlled from the keypad of a VT100 terminal. The keypad layout is: ------------------------- ----------------------------- ! ^ ! ! ! ! ! Key ! ! ! ! ! ! ! ! ! ! ! ! HELP ! Togle! VPW> ! !Back ! ! ! ! ! Pad ! ! ! ! ------------------------- ----------------------------- ! ! ! ! ! ! Quit ! ! ! Done ! ! ! ! ! ! ----------------------------- ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ----------------------------- ! ! ! ! ! ! ! ! ! E ! ! ! ! ! N ! ---------------------! T ! ! ! ! E ! ! Menu ! ! R ! ! ! ! ! ----------------------------- The keypad for the X-Y Graphic Data Editor is slightly different. It will be discussed as part of the chapter on the Graphics Workstation. The KeyPad and the HELP and the Menu keys, can normally be used to terminate any input not requiring a Yes/No answer. When the Keypad key is pressed, NoteBook will display the keypad layout in a scrolling region below the current input line. The terminal will drop into slow scroll mode so the keypad can be viewed. At the end of the display a message requesting you to "Press RETURN" will appear. When you press RETURN, the screen will clear, and NoteBook will continue where it left off. The HELP Key will display any help information which has been defined for the requested input. Each possible input and each NoteBook mode can have defined HELP information. If it exists, it is displayed in a scrolling region below the last input line using the VT100 slow scroll mode. If it does not, a blank area is shown. In any event, when the help text (or lack thereof) is complete, a message saying to "Press RETURN to continue" will appear. Do so and the HELP text will vanish and NoteBook will continue to prompt for input where you left off. 16-5 THE VAX NOTEBOOK The Togle key toggles the keypad between application and numeric mode. On a VT100, the four LEDs all light when the keypad is in application mode and turn off in numeric mode. On a VT200 series terminal, the keyboard bell sounds when the keypad is toggled into numeric mode. In numeric mode, the numeric keys are not interpreted as commands. The VPW> key will interrupt work in progress and drop you into VPW Command Screen mode. When VPW> is prompting, you may issue normal VAX commands to preform some other function with the restriction that the terminal will behave as a DUMB video terminal. This means that video editing and the PHONE utility can not work. When one no longer wishes to use the VPW> command mode, enter Control-Z, the Command Screen will erase, and NoteBook will continue to prompt for input where you left off. The DONE key is used to terminate input without having to process the entire input list. For example, if you are in Modify mode, and have just modified the desired entry, the DONE key tells NoteBook not to check to see if other entries are to be modified but just to proceed with the update verification check. The DONE key is only used in Add and Modify mode. The QUIT key operates the same way as the Control-Z terminator. Either inputs tell NoteBook to abort the current operation and return to the Menu. The Up-Arrow key, tells Notebook to backup to the previous entry on the screen. This is useful if you have entered data on a line, gone to the next line and then have observed that the input is faulty and you want to change it. The ENTER key behaves the same as the RETURN key. Either may be used to terminate data input. The MENU key is used to return to the VAX Professional Workstation menu. For answers requesting a Yes/No answer, a RETURN by itself is considered to be a No. At minimum, a "Y" or "y" is required if one wishes to indicate "Yes". Other inputs fall into two categories. Some inputs are required. The prompt must be answered with something. For these inputs, typing just a RETURN will produce an error message saying what is required. Most data inputs, however, are optional. For those inputs, a RETURN by itself is interpreted as, "Leave the current data value alone." However, deleting erroneous data from any input field is easy. Simply enter a single space to null out the previous data in it. 16-6 THE VAX NOTEBOOK 16.6 NoteBook's Basic Functions For each NoteBook program, the following functions MAY be defined. o Records may be added to a data base o Records may be modified in the data base o Records may be deleted from the data base o Reports may be generated from selected data fields. o Data bases other than the default may be selected. It is not necessary that each program allow for every possible function because allowed functions may be selected on a program by program basis. When the program's menu appears it is only necessary to enter the minimum number of characters required for a unique identification of function. On VT100 terminals with the advanced video option, the minimum number of characters required will appear in BOLD letters. A Control-Z or Control-Y to this prompt will force NoteBook to exit. Note there are no specific functions for either creating the database or sorting the resultant file. If the data base does not exist, it is created the first time one tries to add data to it. Sorting the data file also occurs automatically if sort fields for the data file have been defined. If sorting has been enabled, every time one exits from Add Mode the file is sorted if records have been added. If one exits from Modify Mode, the file is sorted if any of the sort fields have been modified. 16.6.1 Add Mode When the user enters Add mode, NoteBook starts prompting for input using the prompts stored from the PROMPT module in the text library. As data is entered, the record is displayed at the bottom of the screen if one has a VT100 terminal. If one is unsure what to do at any time, the HELP key provides help on the nature of the input being prompted for, Control-Z or the QUIT key will abort the input. If the user either presses the DONE key or enters data for the last prompt, the record in its entirety is displayed and the user is allowed to choose whether or not that record is added to the file. Prior to adding or modifying any record, NoteBook always prompts to see if it alright to do so. In Add mode, if the answer is Y (Yes), the record is added, the file being created if necessary, and the user is then prompted to enter data for the next record. If the answer is N (No) or just RETURN, one drops back into ADD mode prompting for each record again. However, the data as first entered becomes the default and a simple RETURN will leave it unaltered. Changing any entry will cause the displayed record 16-7 THE VAX NOTEBOOK to be updated if one is using a VT100 terminal. Eventually if one gets the record correct (or hits the DONE key), the user again gets the chance to accept the record for insertion into the data file. Once in ADD mode, it is simple to get out. Type Control-Z, press the QUIT key, or type RETURN to any required (match type 1) input to return to the menu. Generally, the first field of each record is required and a return is effected if a RETURN is hit. If one is unhappy with data entered for a previous prompt, one can back up a record at a time by pressing the Up-Arrow key. The current value for the record being created is displayed at the bottom of the screen on VT100 terminals. If the program has sorting enabled, the data file will be sorted each time Add Mode is exited, if data has been added to the file. Be sure to watch to see if any error messages appear in case you are tight on disk space. Please read the cautions on sorting problems at the end of this document prior to adding data to a file. 16.6.2 Delete Mode In Delete mode NoteBook prompts for a string to "Search for: ". Either a single or a compound search string (separated with a vertical bar) may be used. Once found, a record is displayed, and the NoteBooK asks if the record may be deleted. Unless the answer is "Y" (Yes) the search continues for another match. The search proceeds until either another record is found or until the end of file, at which point a message saying that the search string was not found is produced, and again NoteBook prompts with "Search for: ". The delete process involves copying the input to the output file, stopping each time it encounters a record containing the search string to see if the record should be deleted. If the record is selected for deletion, it is not copied to the new file. Now, initially the old file is opened for keeping and the new file is opened for deletion on closing. This is to protect the original file in the event of an error or abort. However, if the process is successful, the new file is saved and the old file is deleted. 16.6.3 Display Mode Display mode displays a menu of possible display formats if more than one exists. Enter a number from the allowed list of selections, or Control-Z or RETURN to return to the menu. Next NoteBook prompts for a search string. Enter a simple or compound search string or a "*" to indicate that all records are to be included in the report. NoteBook returns to the menu if a RETURN 16-8 THE VAX NOTEBOOK with no input is input for the search string. The Up-Arrow key on a VT100 may be used at any time to go back and redo a previous question. The search string may be a simple string or a compound string separated by vertical bars. The strings may be words or entire phrases. If compound search strings are entered, one must be careful about requesting that the search be over selected fields. If one desires to search over selected fields, the entire compound search string must be contained in one of the specified fields. Next, NoteBook asks if the output should be printed or go to a scratch file (SCRATCH.FIL). If the answer is "P", the output is sent to the line printer and deleted following printing. If the answer is "S", it is written to the scratch file, SCRATCH.FIL. Only one version of SCRATCH.FIL is ever allowed to exist at a time. Each subsequent output to SCRATCH.FIL overwrites data previously written to it. The output appears on the user's terminal if any other response is entered. Next, NoteBook asks if the searching is to be done on selected fields. If the answer is not "Y", the search proceeds without further input from the user, either displaying the selected records on the terminal or the line printer using the selected format. When the search is complete, NoteBook prompts the user to "Press RETURN to continue" and then prompts for another string to search for. If the user elects to search only selected fields, NoteBook prompts for each possible input field to see if that field is to be searched. The process of selecting fields to search is terminated either when there are no more fields or when the DONE key is hit. In either case, the search then proceeds as above with the exception that only the selected parts of each record are checked for a match with the selected search string. At any time during the input process, the Up-Arrow key can be used to backup to the answer in the previous record and change it. This is useful for changing the form for display without returning to the menu. 16.6.4 Modify Mode Modify mode is similar to Add mode. When one enters Modify mode one is prompted with "Search for: ". Enter a unique string for identifying the record. This may be a simple string like a last name or a compound search string containing two or more strings separated with vertical bars. A match is declared if the simple search string is located within the record or if each of the multiple search strings is contained within the record. If a match is declared, the record is displayed, and the user is asked if this 16-9 THE VAX NOTEBOOK is the record to modify. If it is, answer Y (Yes), otherwise NoteBook will continue to search through the file for another match. If at any point it searches the file to the end and does not find a match, it will display a message that the search string was not found and again prompt with "Search for: ". If a RETURN is entered for this prompt, NoteBook returns to the menu and the file is sorted if any sort fields have been modified. If the record is accepted, the contents of the record are displayed and the user is prompted with each field input just as if it was Add Mode. A RETURN leaves each field unchanged, a control-Z or QUIT key aborts the process, returning to the menu, and a DONE key or completion of responding to all prompts will display the resultant record and NoteBook will ask if the modified record is correct. If the answer is "Y" (Yes), the data file record will be updated, and NoteBooK will prompt again for a record to "Search for: ". If the answer is not "Y" (Yes), the modification of tha record is aborted and NoteBook again prompts for a new record to "Search for: ". Modify mode does not change the size of your data file or use additional disk space unless sorting is done. Records are updated in place within the file. This means, however, that the modified record length must be identical with that of the initial record. 16.6.5 Use Mode When NoteBook starts up, it assumes the user will be accessing the default data file for the NoteBook program being used. You may elect to USE a different data file. If the NoteBook Program supports the Use mode, typing U to the "Choice: " prompt will cause the current data base file name to be displayed, along with a prompt for a new file name. If a carriage return is hit, the existing data file name will be retained. One must be careful using this option as it is possible to select an existing data base created via a different NoteBook function, and try and access it via the current NoteBook function. If this happens, the record selection fields would be wrong and the existing data base could be damaged. In general, the following rule must be observed: if you wish to access an alternate data base for a NoteBook program, that data base must have been created using that NoteBook Program. 16-10 THE VAX NOTEBOOK 16.7 NoteBook Control Modules Each "Program" supported by NoteBook is controlled by four text modules contained in SYS$VPWFILES:VPW.TLB and the HELP text in VPW.HLB. If the VPW program name is PROGRAM then text modules exist in VPW.TLB with the following names. 1. PROGRAM. 2. PROGRAM_PROMPTS 3. PROGRAM_FORMS 4. PROGRAM_SORT It is not intended that these modules be created by hand. The information to be presented is for use by someone familiar with the internal workings of the NoteBook subroutines as an aid in remembering the structure which is to be supported. A command procedure, CRENOTBOK.COM, exists which can be used for designing prototype control modules and it should generally be used. If a control module does not have the correct format, NoteBook will not initialize correctly and will die with elaborate error messages. 16.7.1 The PROGRAM Module The PROGRAM module contains the menu for the NoteBook Program function and a list of allowed responses to the menu. The format of the module is You may choose: Choice 1 - Text Choice 2 - Text ... .... / Chs1 Chs2 Chs3 ... Chsn This text is created with an editor and the choices have embedded escape sequences to turn bolding on and off around the minimum number of letters to enter to select the choice. The menu is terminated with a "/" which is immediately followed by an allowed choice list, each item of which is separated by spaces. So that the menu can be used on terminals which do not recognize the BOLD/UNBOLD escape sequences, the menu display module converts these escape sequences to ASCII nulls prior to printing. 16-11 THE VAX NOTEBOOK 16.7.2 The PROGRAM_PROMPTS Module The PROGRAM_PROMPTS module contains the program title, the name of the data file to use, and information on each field of the data base. Up to twenty different fields may be defined within the record. This data includes: 1. The input field prompt. 2. The length (in bytes) of the data field. 3. The HELP information keywords used to access HELP from VPW.HLB for the data field. 4. The data match type (optional). 5. Data match type check fields (if data match type is defined). Each item of data is separated from the rest by a vertical bar. The order of items in the prompt list and each previous field length determines the location of the next data field within the record. For example: Last Name|15|PHONEBOOK NAME Social Security #|11|SECURITY SOC_SECURITY_NUMBER|4|___-__-____ Married [Y/N]|1|SECURITY STATUS!8!Y N In the first example, the prompt is "Last Name" and the length of the input field is 15 characters. The "Last Name" field begins at the first character in the record. If help is requested, it is looked for in VPW.HLB using the keywords PHONEBOOK NAME. In the second example, the user would be prompted for "Social Security #". This field begins after the "Last Name" field at position 16 within the record. The field length is 11 characters wide, and data may only be be entered where the underlines, "_", are present. If HELP is requested, it is requested with the keywords SECURITY SOC_SECURITY_NUMBER. In the third example, NoteBook prompts to see if the user is married. The allowed answers are only "Y" or "N". Match type is indicated by a number. The values represent powers of 2, i.e., 0,1,2,4,8,16,32,64,128,256 so that, where logical, match types can be added to require both conditions to be true. The following match types are defined. 1. 0 -> No data type checking required. 2. 1 -> Return to the menu on null input in Add mode. 3. 2 -> Required input. Data or Control-Z must be entered 4. 4 -> Protected field input. New data may be entered only in areas where an underline exists. All other areas must be entered as shown. The "4" is followed by a vertical bar and 16-12 THE VAX NOTEBOOK the input field as in the previous example for Social Security Number. 5. 8 -> Match one of list. The "8" is followed by a vertical bar and a list of items to match each separated by a single space as in the above example for marital status. Note that the matching is sensitive to the case of the input data. If the allowed list of input strings is in upper case, allowed answers must also be in upper case. 6. 16 -> Verify the input is in VAX date format (DD-MMM-YYYY). 7. 32 -> Check the input to see if it lies within the range of numbers from the low value to the high value. The "32" is followed by a vertical bar followed by two numbers separated by a "/". The first number is the low value, the second the high value. The numbers are treated as ASCII representations of single precision floating point numbers. 8. 64 -> Integer*2 data. To date use of binary data is mostly experimental. 9. 128 -> Integer*4 data. 10. 256 -> Real*4 data. Match types fall into three groups, the required input type 1 or 2, the type of input represented by values 4,8,16 and 32, and the three binary data types, 64,128,256. Types 1 and 2 can logically be added to the second group. Type 4, 8, 16, and 32 can not be logically added to each other. The binary data can not be logically added with any other data type. 16.7.3 The PROGRAM_FORMS Module The PROGRAM_FORMS module is composed of triads of entries. Up to ten report formats may be defined. The controlling format specifiers may be up to 132 characters long. The first item of each triad is a title for the report format which may be displayed in the Display Mode Menu. The title is only displayed if there is more than one output form present in the form module. Each NoteBook program must have at least one report form defined. The first triad in the list of formats is the default report format for the program. This is the format which is used to display the record during Add, Modify, and Delete mode verification. Following the title in each triad is the format statement. It must be an acceptable RUN time Fortran format statement, starting with a "(" and ending with a ")". The length of the format statement is limited to 132 characters. Each field to be displayed is character data, so Fortran "A" format must be used. The last 16-13 THE VAX NOTEBOOK item of each triad is a list of numbers separated by commas. The first number is the total number of fields to be output. It must be one or more. The other items represent a list of the order of the items to be displayed at that position. If PROGRAM_PROMPTS has defined five input fields, up to 5 items may be output, and these fields (numbered 1 to 5) may appear in any order. For example: My Private List (' ',A,T20,A,T32,A,T50,A,'/',' ',T50,A) 5,1,4,3,2,5 would create a form with the title "My Private List" which would be output on two lines per record in "A" format. The string "5,1,4,3,2,5" means that all five items would be printed, the first field is the first output, the fourth field the second output, the third field the third output, the second field the fourth output, and the fifth field the fifth output. 16.7.4 The PROGRAM_SORT Module The module PROGRAM_SORT defines if and how to sort the file. PROGRAM_SORT consists of a single line of numbers. The first number indicates how many sort fields exist and may be from 1 to 10. If it is zero, the file will not be sorted. The first number is followed by up to ten sets of numbers, 4 numbers/set. The sets of four numbers each consist of: 1,0/1,Field_position,Field_length The first number in each set must always be "1" to indicate that the data is character data. The second number is a "0" or a "1" to indicate that the data is to be sorted into ascending or descending order. The third number is the starting location in the record where the sort field begins, and the last number is the length (in bytes) of the field to sort). 16.8 Designing A Data Base To help in designing a data base, a procedure CRENOTBOK.COM exists which will create prototype control modules and help file. The prototype text modules are designed to be a start to the final format, but CRENOTBOK.COM does not create a final, polished NoteBook program which sorts nicely, has a customized menu, and has many useful report formats. Also, it does not support binary data types yet (which are still experimental). For any reasonable output format for Display mode, the PROGRAM_FORMS module must be edited to tailor the basic format for readability and to add new formats. Some knowledge of Fortran 16-14 THE VAX NOTEBOOK Format statements is needed to do this. Likewise, the PROGRAM_SORT module must be tailored (and for now PROGRAM.SRT). The prototype menu, PROGRAM.TXT, should be edited to customize it and remove any unwanted features. Finally, the prototype HELP module must be edited to add the appropriate HELP text for the program. 16.8.1 Using CRENOTBOK.COM To Be Supplied at Some Later Date (a year later and still counting...) 16.9 Possible Problems A VAX may run with user disk quotas which are not large. It is possible, but not probable, if one is short on disk space to destroy one's data file by being careless. For example, if the delete function or sorting fail in some hither-to unpredicted way (both require disk space to create new files) one could be left with a new 0 length file (containing nothing) and an old file containing the information prior to the failure. Both the sort and delete routines try to handle such problems correctly. For example, if the sort fails for any reason, the new (and sorted) file is deleted, and the old (unsorted) file is kept, and an error message is produced telling you what happend and to check your disk quotas. However, after such a warning, it pays to be very cautious and check your file. If any VAX function is preformed (PURGE, etc) which would result in purging the data base files and if a corrupted file accidently exists, the old file with the data would get deleted and the new corrupted file would be retained. Every attempt has been made to prevent this from happening, and any time anything goes wrong an error message is displayed. If an error message is displayed, write it down BEFORE pressing return. Better yet, type Control-Z instead of return, and issue a $DIR/SIZE=ALL Data_File_Name If the most recently created data file is zero blocks long, you have problems and you should get assistance from someone who knows their way around the VAX. Another time to be careful is when you are deleting or sorting entries. Do not try exiting by typing Control-Y. You could wind up with a corrupted or null data base again and no error message 16-15 THE VAX NOTEBOOK would result. 16-16 APPENDIX A INSTALLING VPW AND RELATED FILES Installing VPW should be relatively straightforward. A number of directories are required. They may be on any disk. They are 1. SYS$COMFILE. Here go the system wide command procedures 2. STS$UTILITY. Here go the general purpose, images developed for the system or obtained from DECUS. 3. ENGL$. Herer go the files required by the Dennison University Spelling checker. 4. SYS$SYSVPWFILES. Here goes the body of all VPW files. 5. SYS$VPW_WPFILES. Here got the subroutines for the Document Preparation Facillity procedure. 6. SYS$VPWCAI. Here go our in-house developed CAI procedures and courses. Installing VPW requires about 2000 blocks of disk space for the files on SYS$SYSVPWFILES, SYS$VPWCAI and SYS$VPW_WPFILES. In addition, an additional 1000 blocks are needed on SYS$UTILITY for optional executable images (TEKGRAPH, TVG, ect.) and 200 blocks on SYS$COMFILE. Finally, 3000 blocks are needed on ENGL$ for the Dennison University Spelling checker and support tasks. The following can be tailored to install VPW on a new VAX system. $ SET NOON ! Continue no matter what $ VERIFY:='F$VERIFY(0) ! Do not echo on TI: $Start: $ ! $ ! $ ! Assign logical names for the utilities $ ! A-1 INSTALLING VPW AND RELATED FILES $ ASSIGN/SYSTEM SYS$SYSROOT:[SYSMGR.CMDFIL] SYS$COMFILE ! $ ASSIGN/SYSTEM SYS$SYSDEVICE:[SYSUTL] SYS$UTILITY ! $ ASSIGN/SYSTEM SYS$SYSDEVICE:[VPW] SYS$VPWFILES ! For VPW $ ASSIGN/SYSTEM SYS$SYSDEVICE:[VPW] SYS$SYSVPWFILES! $ ASSIGN/SYSTEM SYS$SYSDEVICE:[VPW.WP] SYS$VPW_WPFILES! $ ASSIGN/SYSTEM SYS$SYSDEVICE:[VPW.CAI] SYS$VPWCAI ! $ @SYS$SYSROOT:[SYSMGR.SYSBOOT]SETTERM ! Set terminal types/speeds $ @SYS$SYSROOT:[SYSMGR.SYSBOOT]SPCLTERMS ! Set terms needing spcl treat $ ASSIGN/SYSTEM "''Boot_Time'" KMS$Boot_Time ! For CHKERRORS $! $! Assign help libraries $! $ ASSIGN/SYSTEM SYS$SYSDEVICE:[SYSUTL]SYSUTL.HLB HLP$LIBRARY $ ASSIGN/SYSTEM SYS$SYSDEVICE:[VPW]VPW.HLB HLP$LIBRARY_1 $! There is a word for management, $! so use it $! $ ASSIGN/SYSTEM xyzabc VAX$MANAGER ! System manager $ ASSIGN/SYSTEM "user1,user2" VAX$MANAGER_2 ! alternate $ ASSIGN/SYSTEM xyzabc VPR$MANAGER ! Prblm Reports $! Remember to also create the directory $ ASSIGN/SYSTEM KMS$SYSTEMUSR1:[VAXVPR] VPR$FILES ! where to store $! $! Assign logical names for user root directories $! $ ASSIGN/SYSTEM dev: SYS$SYSUSER1: ! dev: needs a name $ @SYS$SYSROOT:[SYSMGR.SYSBOOT]ROOTDIR SYS$SYSUSER1 USR1 ! and directories $! $! Install images needed by VPW, must rebuild SETUIC each release $! $ WRITE SYS$OUTPUT - ! "INSIMAGES -- Installing VPW images linked with SYS.STB" $ RUN SYS$SYSTEM:INSTALL ! SYS$SYSROOT:[SYSEXE]SETUIC /PRIVILEGE=(CMKRNL) $ WRITE SYS$OUTPUT - ! "INSIMAGES -- Installing site specific non-privileged images" $ RUN SYS$SYSTEM:INSTALL SYS$SYSDEVICE:[VPW]ASK/OPEN/HEADER_RESIDENT/SHARE SYS$SYSDEVICE:[VPW]BROADCAST/PRIVILEGE=(OPER,WORLD) SYS$SYSDEVICE:[VPW]MAILMSG/PRIVILEGE=(SYSPRV)/OPEN SYS$SYSDEVICE:[VPW]PRVCOMFIL/PRIVILEGE=(SETPRV)/OPEN SYS$SYSDEVICE:[VPW]REMINDER/PRIVILEGE=(SYSPRV) SYS$SYSTEM:WHO /PRIV=(SYSPRV) ! From VMS V2.x system SYS$SYSDEVICE:[VPW]VPWEDIT/OPEN/HEADER_RESIDENT $ EXIT Once all the required logicals have been assinged, when each user logs on the system, the system wide login procedure should 1. Invoke SYS$COMFILE:TERM.COM A-2 INSTALLING VPW AND RELATED FILES 2. Invoke SYS$VPWFILES:SETVPWSYM.COM Some site tailoring will probably have to be done to remove references to images not needed or available at any given site. A-3 APPENDIX B THE VAX BROADCAST UTILITY BROADCAST allows any user to send a one line notice to another user on the system. Its syntax is BROADCAST[/BOT] TTuu:"message...message...message" or BROADCAST[/BOT] TXuu:"message...message...message" (DMF-32) or BROADCAST[/BOT] OPA0:"message...message...message" or BROADCAST[/BOT] Username:"message...message...message" If the form using the Username is specified (and it must be a proper user's logon name), BROADCAST will send a notification message to all terminals the user is logged on to. Alternatively, using the form specifying the terminal number, the message will be sent to the terminal regardless of the user at the terminal. BROADCAST can not work if the user has set the terminal /NOBROADCAST. Unless the /BOT switch is used, a message broadcast to a VT100 type terminal will erase the top 6 lines of the display, sound the bell, and display the message down two lines from the top. The /BOT switch forces the message to be displayed as if the terminal were a hard copy terminal (ie the message appears at the bottom of the screen or at the current text entry location). To use BROADCAST, define the symbol BROADCAST:==$SYS$SYSVPWFILES:BROADCAST This symbol is automatically defined by SYSLOGIN.COM when it executes @SYS$SYSVPWFILES:SETVPWSYM.COM during the logon process. To work, BROADCAST must be installed with OPER, and WORLD privilege. Messages sent to DEC CRT terminals will erase the top 6 lines of the screen and display the notice 2 lines down from the top. B-1 THE VAX BROADCAST UTILITY BROADCAST is useful in communicating messages from a batch procedure to an interactive process. If the batch procedure is passed the user's name or terminal ID when it is started up, at some later time it can notify that user or terminal of it's current status. B-2 APPENDIX C THE VAX DATEBOOK SYSTEM C.1 Introduction The VAX DateBook System is accessed either through the VAX Professional Workstation or directly by typing DateBook. The DateBook system is now considered obsolete because DTC (Desk Top Calendar) performs the same functions faster and in a more user friendly manner. When you start up DateBook the following menu is displayed. Personal Date/Meeting Book (Type ^Y to exit at any Point) You may choose: Add - Add a new date to remember DElete - Delete all entries between two dates DIsplay - Display a selected list of dates Exit - Exit from DateBook Help - Help on using DateBook Month - Display a Month-at-a-Glance Print - Print date list on printer Remove - Remove selected entries on a given date Set - Set the default DateBook Choice: C.1.1 ADD When you enter ADD mode, DateBook starts prompting you for input. It asks you for DATE, TIME, ATTENDEE, and TOPIC. After you have entered all items, it displays what you have entered and asks you if it is OK. If no mistakes were made, type Y or YES. If you type N, NO, or just hit carriage return (, RETurn), the entry will not be made in the DateBook. During the prompting for DATE and TIME a carriage return (, RETurn) entered at the prompt will return the user to the main menu. The top line of the add C-1 THE VAX DATEBOOK SYSTEM display shows the current DateBook the user is using. C.1.1.1 Attendee ATTENDEE may be used several ways. If a secretary is using the DateBook to keep track of appointments for a number of users, this DateBook entry field is used to specify which user the entry is for. If a given user is using DateBook for him or herself alone, this entry can be used to specify the meeting attendees, or any other convenient item of interest. When DateBook prompts for ATTENDEE, you may enter up to a 14 character string to enter in this field. If you are unsure what a 14 character string is, STRING, is an item you can request HELP on. Valid ATTENDEE entries might be J. Downward P. Vavra VAX Wrk Grp but VAX Working Group is too long. C.1.1.2 Date Format The date format is DD-MMM-YYYY. The years must be entered as four digits, ie 1982 not 82. The months are entered as JAN...DEC. The "-" in the date is required syntax. Examples of date entries are: VALID INVALID 1-JAN-1982 1/JAN/1982 01-JAN-1982 1-JAN-82 25-FEB-1982 2/25/82 30-NOV-1982 30-NEV-1982 Normally, the days must lie between 0...31, but if you specify too large a day on a certain month (ie 29 days in February) it will be flagged with an error. At this time, the last day in February in LEAP year will not work. C-2 THE VAX DATEBOOK SYSTEM C.1.1.3 Time Time is kept using a 24 hour clock. The day starts at 00:00 and runs through 23:59. Morning hours are < 12:00. The format for the entry is HH:MM. The ":" is required syntax. Valid time intries include: 00:01 One minute past midnight 9:30 Nine thirty in the morning 09:30 " " " " " 14:30 Two thirty in the afternoon C.1.1.4 Topic Each meeting/appointment/deadline can have a TOPIC. For a meeting the TOPIC entry might be the topic to be discussed. It also might include the people asked to attend. For a formal meeting it might specify the meeting name and paper to be presented. Anything may be entered for topic, as long as it is 40 or fewer characters long. Valid topics are: Discuss Vax maintance contract DECUS, VAX to RSX Migration Paper If more than 40 characters are input, an error is reported. C.1.2 Default Answers The very first time a user uses DateBook, it prompts for information it will need for all future use. It gets the user's first and last name and the default user name (attendee) for whom DateBook entries are to be made. This information is stored in DATEDFLT.COM. If at any time you are unhappy with your default answers, enter DCL mode, type DELETE DATEDFLT.COM;, and reenter , DateBook. DateBook will then prompt again for first and last name and the default datebook entry name. C.1.3 Default Datebook By default, DateBook always uses the DateBook data file on the user's directory. When in any of the specialized modes (ADD, DELETE, REMOVE, or DISPLAY) DateBook will display at the top of the screen the DateBook file currently being accessed. You can change the default file with the SET command. To access another's datebook, however, the other user must first give you RWED privilege to their DateBook data file. C-3 THE VAX DATEBOOK SYSTEM C.1.4 DELETE DELETE is used if you want to delete all entries in the DateBook from one date up to and includeing a second date. If you hit the terminal key RETURN (, RETurn, type RETurn), DateBook will return to the main menu. DateBook will ask for the starting date on which to delete entries. If you enter a valid date (DD-MMM-YYYY) for the first day, DateBook will ask you for the ending date to delete. If the second date entry is valid, DateBook will print a message showing the range of dates which will be deleted. It will then ask if it should proceed to delete the entries. If any answer but Y or YES is given, DateBook will return to the delete menu without deleting any entries. If a Y or a YES is entered, DateBook will delete all those entries and then return to the delete menu to see if you have more to delete. C.1.5 Display The user can display DateBook entries for a single specific day, the current day, or all days. When the user types DISPLAY, DateBook prompts for the date to display. If the user hits the carriage return (, RETurn), any DateBook entries for the current day are displayed. If the user types ALL, all entries in the file are displayed. If the user enters a specific day (DD-MMM-YYYY), just the entries for that day are displayed. The Display command only outputs to the user's terminal. Use the Print command to output a hard copy. Whether or not any entries occur in the file for a given day, a header will be displayed. If no entries occur, no entries will follow the header. C.1.6 Print The Print option is identical to the Display option with the exception that a data file is written which is printed either on the line printer or the letter quality printer. The user is prompted for where to send the output. Only LP and LQ are allowed inputs. Typing LP will send output to the line printer, and typing LQ will send the output to the letter quality printer. Whether or not any entries occur in the file for a given day, a header will be displayed. If no entries occur, no entries will follow the header. C-4 THE VAX DATEBOOK SYSTEM C.1.7 Month The Month option allows the user to have displayed (VT100 terminals only) the number of appointments for each day within a given month. The display is in calendar format and appointments, if present, are highlighted. C.1.8 REMOVE If you make a mistake and want to remove/delete a sepcific entry on a given day, type REMove to menu prompt. DateBook will then prompt you for what day to search for. Enter it as DD-MMM-YYYY. DateBook will then read all the entries. Each entry for that date will be displayed and DateBook will ask you if you wish to remove that entry. If you type Y or YES the entry will be deleted. Any other response and the entry will be saved and DateBook will check to see if more entries on that date exist. When it is done processing a given day, it will return to the prompt mode and request another date to be entered. If you do not want to remove any other DateBook entries, hit the terminal's return key (, RETurn). The top line of the REMOVE page will display the current DateBook file being accessed. C.1.9 SET The SET option is used to change the default DateBook data file being used by DateBook. When the SET option is issued, first the current directory being accessed is displayed. Next a new directory string is prompted for. No error checking is done to insure that a legal directory string is entered. If one wants to return to the directory on which DateBook was first started up, type RETURN to the second prompt instead of a new directory string. C.1.10 Special Commands DateBook has two special in-line commands for use in a user's LOGIN.COM file or directly at the terminal command level. The commands are TODAY and CHECK. The command DATEBOOK TODAY will display all meetings/appointments/deadlines that will occur that day. Nothing will be displayed if there are no datebook entries. The command DATEBOOK CHECK C-5 THE VAX DATEBOOK SYSTEM will just check to see if any DateBook entries for the current day exist, and if they do, broadcast a message to the user that the DateBook has entries for the present day. Since only a check for entries is done, DATEBOOK CHECK is much FASTER than DATEBOOK TODAY. To use the CHECK function in your LOGIN.COM file, either just add a line $ DATEBOOK CHECK or execute the DateBook checking in parallel with logging on by submitting DateBook to run in BATCH mode. To do this, include the command $ SUBMIT SYS$SYSVPWFILES:DATEBOOK/PARAM=CHECK/NOIDENT/NOLOG and DateBook will start checking your DateBook while you are logging on. C.1.11 System Requirements DateBook requires the following command procedures, executable images and data files. SYS$SYSVPWFILES:PAGE.COM Define with SETVPWSYM.COM SYS$SYSVPWFILES:TERM.COM during SYSLOGIN.COM SYS$SYSVPWFILES:TESTFILE.COM SYS$SYSROOT:[SYSEXE]DTR.EXE DATATRIEVE SYS$SYSVPWFILESBROADCAST.EXE Broadcast message to user SYS$SYSVPWFILES:DATEBOOK.DTT Prototype data file SYS$DISK:[]DATEBOOK.DAT User's DateBook SYS$SYSROOT:[SYSMSG]QUERY.DIC DATATRIEVE dictionary When DateBook starts up, it looks for the existence of the file DATEBOOK.DAT on the login directory. If no such file is present, it copies SYS$SYSVPWFILES:DATEBOOK.DTT to DATEBOOK.DAT on the users directory. If the template file can not be copied, a warning message is displayed for 4 seconds. If neither DATEBOOK.DAT nor DATEBOOK.DTT exist and the user is privileged, the user has the opportunity to create the DATEBOOK.DTT template data file and make the appropriate DATATRIEVE entries in QUERY.DIC by issuing the CREATE command, which exists although it is not in the menu. C-6