User's Instructions For The PROTO System --------------------------------------- Frequently, a programmer must develop a domain definition, record layout, and an edit/update procedure. Since UCC has the policy of using forms in any applicable new systems, the programmer may have to develop a form. PROTO was developed to ease this process. When certain conditions are met, the PROTO system can reduce the number of steps and time involved. The PROTO system creates an edit/update procedure from an FMS form and, optionally, can create record and domain definitions. User's instructions can be created if desired. The file must be indexed and not allow duplicate values for the primary key. While the procedure and domain created can be used "as is", the record definition will need extensive modification to include query names, edit strings and "COMPUTED BY" and "VALID IF" clauses. The PROTO system is written in DCL and uses FMS, EDT, and Datatrieve. Before Running PROTO -------------------- You must do the following before running PROTO: (1) Develop an FMS form containing fields. (2) The FMS field names must EXACTLY match the field names or query names in the record layout IF you already have a Datatrieve record. (3) The last field on the form must be an alphanumeric, one character field called "XANS". The message associated with this field is "DO YOU WANT TO SAVE (Y/N)?". (4) The form must be placed in a forms library. If a forms library does not exist, use the following command: $ FMS/LIB/CREATE libraryname/FORM=formname formname If the library already exists, enter: $ FMS/LIB/INSERT libraryname/FORM=formname formname To Run PROTO ------------ PROTO is run from the DCL level by entering: $ @DRA2:[BOWDEN]PROTO at the "$" prompt. The procedure will then prompt you for the form name, the library name, the domain name, the key name, and the key length. You will be asked whether domain and record definition should be generated. This procedure generates many messages on your screen while it creates the necessary files. You can ignore most of these. At one point, PROTO will ask you to use GOLD E once you are in EDT. You will be in EDT when your screen enters into full screen mode (as opposed to line editing mode). Enter GOLD E (i.e. PF1 and then "E"). After Running PROTO ------------------- When PROTO has finished, the following message will appear: To place the procedure in DTR, enter: DTR @domname.DTR at the DTR> prompt. When you do this, the generated Datatrieve commands will be in your default directory. The edit/update procedure will be called "STORE_domainname" and can be executed by ":STORE_domainname". Common Errors ------------- The most common errors are: (1) FMS field name do not exactly match the Datatrieve field or query names. (2) The last field in the form is not called "XANS". (3) The record definition was not modified to suit your special needs. (4) The file is not indexed or allows duplicate key values. Appendix A The following is the PROTO command procedure and other files used by PROTO: $! This procedure, "PROTO.COM", was written by Beth Bowden on 6/13/85. $! It will create a simple DATATRIEVE edit/update from a FMS form. The $! procedure will almost always need to be modified. $! $ PUTEDT :== WRITE EDTFILE $ PUT :== WRITE SYS$OUTPUT $ TYPE SYS$INPUT ***************************************************************************** * Before running this procedure, you MUST have created an FMS form. * * In this form, the last field must be "XANS" and be defined as an one * * character alphanumeric field. * * The field NAMEs in the form must exactly match the field NAMEs in the * * record or the query NAMEs. * ***************************************************************************** $!******GET VARIABLES $ASKDOMAIN: $ INQUIRE DOMNAME "Enter the domain name" $ IF ("''DOMNAME'" .EQS. "") THEN $GOTO ASKDOMAIN $ASKFORM: $ INQUIRE FRMNAME "Enter the form name" $ IF ("''FRMNAME'" .EQS. "") THEN $GOTO ASKFORM $ASKFLB: $ INQUIRE FLBNAME "Enter the form library name" $ IF ("''FLBNAME'" .EQS. "") THEN $GOTO ASKFLB $ASKKEY: $ INQUIRE KEYNAME "Enter the name of the key" $ IF ("''KEYNAME'" .EQS. "") THEN $GOTO ASKKEY $ASKPIC: $ INQUIRE KEYPIC "Enter the picture clause of the key (ex. x(10))" $ IF ("''KEYPIC'" .EQS. "") THEN $GOTO ASKPIC $ASKDOMANS: $ INQUIRE DOMANS "Do you want a domain and record generated (Y/N)" $ IF ("''DOMANS'" .EQS. "") THEN $GOTO ASKDOMANS $ASKDOCANS: $ INQUIRE DOCANS "Do you want baseline documentation generated (Y/N)" $ IF ("''DOCANS'" .EQS. "") THEN $GOTO ASKDOCANS $!******GET INFO FOR DOCUMENTATION (ACCOUNT NAME AND TIME) $ PGMNAME :== 'F$PROCESS() $ PGMTIME :== 'F$TIME() $!******GET DEFAULT DIRECTORY $ FULLFLBNAME :== 'F$LOGICAL("SYS$DISK")''FLBNAME'.FLB $ FULLDOMNAME :== 'F$LOGICAL("SYS$DISK")''DOMNAME'.DAT $!******RUN FMS TO GET THE DECLARATIONS FROM THE FORM $ FMS/DESC/DECL 'FLBNAME/FORM='FRMNAME $ IF ("''DOMANS'".EQS."N" .or."''DOMANS'".EQS."n") THEN $GOTO A100EDT $ TYPE SYS$INPUT ******************************************************************************* * Note: The record layout will need to be modified for for query names, edit * * strings, validation tests, and other miscellaneous things * ******************************************************************************* $ INQUIRE/NOPUNC X "Press return to continue" $A100EDT: $ OPEN/WRITE/ERROR=Z999 EDTFILE SCRTCH.EDT $ PUTEDT "SET QUIET" $ PUTEDT "DELETE WHOLE" $ PUTEDT "INCLUDE ''FLBNAME'.TXT" $ PUTEDT "DELETE 1 THRU 2" $ PUTEDT "RESEQ WHOLE/SEQU:5:5" $ PUTEDT "I 1; DEFINE DOMAIN ''DOMNAME' USING ''DOMNAME'_REC" $ PUTEDT "I 2; ON ''FULLDOMNAME';" $ PUTEDT "I 3; DEFINE RECORD ''DOMNAME'_REC USING" $ PUTEDT "I 4; 01 ''DOMNAME'_REC." $ PUTEDT "DELETE 'ANS'" $ PUTEDT "I 9999; ;" $ PUTEDT "EXIT" $ CLOSE EDTFILE $ EDIT/COM=SCRTCH.EDT SCRTCH.QQQ $!******'FLBNAME.TXT CONTAINS THE OUTPUT FROM THE ABOVE FMS/DESC/DECL COMMAND $!******"PROTO.EDT" EXTRACTS THE FIELD NAMES $ TYPE SYS$INPUT ***************************************************************************** * Once in EDT, use GOLD E immediately * ***************************************************************************** $ INQUIRE/NOPUNC X "Press return to continue" $ ASSIGN/USER TT: SYS$INPUT $ EDIT/COMMAND=DISK$USERDISK2:[BOWDEN]PROTO.EDT 'FLBNAME.TXT $!******CREATE AN EDT INITIALIZATION FILE THAT WILL EDIT "flbname.TXT" AND $!******REPLACE THE VARIABLES WITH THE ACTUAL INFORMATION $ OPEN/WRITE/ERROR=Z999 EDTFILE SCRTCH.EDT $ OPEN/READ/ERROR=ENDPUT FIELDFILE 'FLBNAME.TXT $ PUTEDT "SET QUIET" $ PUTEDT "DELETE WHOLE" $ LINECTR = 0 $WRITEPUT: $ READ/ERROR=ENDPUT/END_OF_FILE=ENDPUT FIELDFILE FREC $ IF (F$LOCATE("''KEYNAME'","''FREC'") .NE. F$LENGTH("''FREC'")) THEN - $ GOTO WRITEPUT $ LINECTR = 'LINECTR + 1 $ PUTEDT "I=PUTFIELDS ''LINECTR'; PUT_FORM ''FREC' = ''FREC'" $ GOTO WRITEPUT $ENDPUT: $ CLOSE FIELDFILE $ LINCTR = 0 $ OPEN/READ/ERROR=ENDGET FIELDFILE 'FLBNAME.TXT $WRITEGET: $ READ/ERROR=ENDGET/END_OF_FILE=ENDGET FIELDFILE FREC $ IF (F$LOCATE("''KEYNAME'","''FREC'") .NE. F$LENGTH("''FREC'")) THEN - $ GOTO WRITEGET $ LINECTR = 'LINECTR + 1 $ PUTEDT "I=GETFIELDS ''LINECTR'; ''FREC' = GET_FORM ''FREC'" $ GOTO WRITEGET $ENDGET: $ CLOSE FIELDFILE $ PUTEDT "=MAIN" $ PUTEDT "INC DRA2:[BOWDEN]PROTO.DTR" $ PUTEDT "SUBS/keypic/''KEYPIC'/WHOLE/NOTYPE" $ PUTEDT "SUBS/keyNAME/''KEYNAME'/WHOLE/NOTYPE" $ PUTEDT "SUBS/frmNAME/''FRMNAME'/WHOLE/NOTYPE" $ PUTEDT "SUBS/flbNAME/''FULLFLBNAME'/WHOLE/NOTYPE" $ PUTEDT "SUBS/pgmTIME/''pgmTIME'/WHOLE/NOTYPE" $ PUTEDT "SUBS/pgmNAME/''pgmNAME'/WHOLE/NOTYPE" $ PUTEDT "SUBS/domNAME/''DOMNAME'/WHOLE/NOTYPE" $ PUTEDT "DEL'***PUT_FORM'" $ PUTEDT "COPY =PUTFIELDS WHOLE TO =MAIN ." $ PUTEDT "DEL'***GET_FORM'" $ PUTEDT "COPY =GETFIELDS WHOLE TO =MAIN ." $ PUTEDT "DEL'***GET_FORM'" $ PUTEDT "COPY =GETFIELDS WHOLE TO =MAIN ." $ IF ("''DOMANS'".EQS."Y" .or."''DOMANS'".EQS."y") THEN - $ PUTEDT "INC SCRTCH.QQQ END" $ PUTEDT "EXIT" $ CLOSE EDTFILE $ EDT/COM=SCRTCH.EDT 'DOMNAME.DTR $ DELETE SCRTCH.EDT; $GENERATEDOC: $ IF ("''DOCANS'".EQS."N" .or."''DOCANS'".EQS."n") THEN $GOTO Z999 $!******RUN FMS TO GET THE DECLARATIONS FROM THE FORM $ FMS/DESC/IMAGE/OUTPUT='FRMNAME.DOC 'FLBNAME/FORM='FRMNAME $ OPEN/WRITE/ERROR=Z999 EDTFILE SCRTCH.EDT $ PUTEDT "SET QUIET" $ PUTEDT "INCLUDE DRA2:[BOWDEN]PROTO.DOC" $ PUTEDT "SUBS/domNAME/''DOMNAME'/WHOLE/NOTYPE" $ PUTEDT "SUBS/keyNAME/''KEYNAME'/WHOLE/NOTYPE" $ PUTEDT "INC ''DOMNAME'.DTR END" ! INCLUDE PROCEDURE $ IF ("''DOMANS'".EQS."N" .or."''DOMANS'".EQS."n") THEN $ PUTEDT "INC SCRTCH.QQQ END" ! INCLUDE RECORD $ PUTEDT "EXIT" $ CLOSE EDTFILE $ EDIT/COM=SCRTCH.EDT 'DOMNAME.DOC $Z999: $ PUT " " $ PUT "*******************************************************" $ PUT "* To place the procedure in DTR, you should enter: *" $ PUT "* *" $ PUT "* DTR *" $ PUT "* @''domname'.DTR *" $ PUT "* *" $ PUT "* at the DTR> prompt. *" $ PUT "*******************************************************" $ PUT " " $ PUT "*******************************************************" $ PUT "* The documentation is in file, ''domname'.DOC *" $ PUT "*******************************************************" $ PUT " " $!******CLEAN UP $ SET MESSAGE/NOTEXT/NOFACI/NOSEVE/NOIDENT $ PURGE 'FRMNAME.DOC; $ DEL SCRTCH.EDT;* $ DEL SCRTCH.QQQ;* $ DEL 'FLBNAME.TXT; $ DEL 'FLBNAME.TXT; $ SET MESSAGE/TEXT/FACI/SEVE/IDENT $ EXIT "PROTO.DTR": DELETE STORE_domname; DEFINE PROCEDURE STORE_domname READY domname SHARED WRITE ! THIS PROCEDURE EDIT UPDATES THE domname RECORDS ! AN X PRECEDING A VARIABLE NAME INDICATES THE USE OF A WORKING STORAGE AREA ! THIS PROCEDURE WAD DEVELOPED BY pgmname ON pgmtime. DECLARE XANS PIC X VALID IF XANS = "Y", "N", "y", "n". !ACCEPTS USER INPUT DECLARE Xkeyname PIC keypic. DECLARE XUPDATE PIC X VALID IF XUPDATE = "A","a","C","c","D","d", "E", "e". !TYPE OF UPDATE:A=ADD;C=CHANGE;D=DELETE DECLARE FOUNDFLAG PIC 9. !MATCHING domname RECORD !*******END OF DECLARATIONS XUPDATE = *."A for add, C for change, D for delete, or E to exit (A/C/D/E)" WHILE XUPDATE NOT = "E", "e" BEGIN Xkeyname = *."the keyname" !*******GET KEY !*****CHECK FOR MATCHING domname RECORD FOUNDFLAG = 0 FOR FIRST 1 domname WITH keyname = Xkeyname BEGIN FOUNDFLAG = 1 END IF XUPDATE = "C" AND FOUNDFLAG = 1 THEN BEGIN FOR ALL domname WITH keyname = Xkeyname BEGIN DISPLAY_FORM frmname IN flbname USING BEGIN PUT_FORM keyname = Xkeyname ***PUT_FORM here END RETRIEVE USING BEGIN XANS = GET_FORM XANS IF (XANS = "Y", "y") THEN MODIFY USING BEGIN ***GET_FORM here END END END END IF XUPDATE = "D", "d" AND FOUNDFLAG = 1 THEN BEGIN FOR ALL domname WITH keyname = Xkeyname BEGIN ERASE; PRINT "Record erased" END END IF (XUPDATE = "D", "d", "C", "c" AND FOUNDFLAG = 0) PRINT "RECORD NOT FOUND - REENTER" IF XUPDATE = "A", "a" AND FOUNDFLAG = 0 BEGIN DISPLAY_FORM frmname IN flbname USING BEGIN PUT_FORM keyname = Xkeyname END RETRIEVE USING BEGIN XANS = GET_FORM XANS IF XANS = "Y", "y" THEN STORE domname USING BEGIN keyname = Xkeyname ***GET_FORM here END END END IF (XUPDATE = "A", "a" AND FOUNDFLAG = 1) PRINT "RECORD ALREADY EXISTS - REENTER" XUPDATE = *."A for add, C for change, D for delete, or E to exit (A/C/D/E)" END END-PROCEDURE "PROTO.DOC": OVERVIEW -------- This system allows designated people to add, change, or delete DOMNAME data. The rest of the guide will explain how to use menus and how to use the system. LOGGING ONTO THE SYSTEM ----------------------- In order to use the STORE_DOMNAME program, you must log onto the computer. To log on, press the "BREAK" key and after a short pause (counting to five usually is long enough) press "RETURN". The computer will prompt you for what class. Enter "VAX" and press "RETURN". The system will then prompt you for your username. Enter your username. You will be prompted for your password; enter it and press "RETURN". If the computer does not prompt you with class, go back and try "BREAK" and "RETURN" again. If it doesn't work after 3 times, turn the terminal off and wait for a few minutes and try again. If it does not work after you turn it back on, call the HOT LINE at 295-3778 for assistance. If you do not know the password for your account or your account name, contact UCC to learn it. For security reasons, it is not listed here. If you have any difficulties using the system, call the HOT LINE at 295-3778. The users terminal area in room G007 gives help on a walk-in basis. You should find the system easy to learn and use. USING THE SYSTEM ---------------- Once you have logged on, enter Datatrieve and run the program with the following commands: $ DTR DTR> :STORE_DOMNAME The first prompt will be: Enter A for add, C for change, D for delete, or E to exit (A/C/D/E) Enter the first letter of your choice. You will then be asked: Enter KEYNAME Enter the key and press RETURN. If you are adding a record, that record cannot already exist. If you are changing or deleting a record, that record must exist. If it does not, you will get an error message and be asked to re-enter and the process will repeat from: Enter A for add, C for change, D for delete, or E to exit (A/C/D/E) If you entered A to add a record and that record was not found, a screen will appear on your screen. The screen format is included at the end of this documentation. You can then enter your data. If you entered C to change a record and that record was found, a form will appear on your screen with all the data stored in that record. You can then change any or all fields. Note that KEYNAME cannot be changed. At the bottom of the menu will be the question: DO YOU WANT TO SAVE (Y/N)? Enter Y to save any changes or to save a new record. Entering N means no data will be changed or saved. Note that you must always enter this field. If you enter D to delete a record and that record is found, the record will be deleted and the message, "Record erased", will appear. The process will now repeat from: Enter A for add, C for change, D for delete, or E to exit (A/C/D/E) Enter E to exit when you are finished. HOW TO USE MENUS ___ __ ___ _____ The edit/update in this system is menu-driven. A menu may have one or more fields in which you enter data. In this system, most fields will be underlined. When a menu first appears on the screen, the cursor will be located at the start of a field. Now, you may enter data in that field. If you want more information about that field, press "F2" on the numeric keypad. "F2", or the HELP will cause a message to display at the bottom of the screen. You should always enter leading zeros in numeric fields. Within a field, you may use the "DELETE" key to delete the character to the left of the cursor or you may use the left and right arrows to move one character left or right. When you are in a field, you may erase the contents of that field by pressing "LINEFEED". Once you have entered data in a field, you can get to the next field by pressing "TAB". You also press "TAB" to skip a field. To move the cursor to a previous field, press "BACKSPACE". By using "TAB" and "BACKSPACE", you can move the cursor around the screen. After you have entered all fields in one menu, press "RETURN". The use of "TAB" and "RETURN" in menus are often confused. "TAB" moves the cursor to the next field while "RETURN" tells the computer you have entered all fields on a menu. Once you have pressed "RETURN", the computer checks the fields you entered. If the information has an error, an error message will appear at the bottom of the screen, the field in error will be blanked, and the cursor will move to the beginning of that field. For example, if you entered "X98GD" in a date field, an error will occur because "X98GD" is not a date. You would then enter the correct date. Note that when you are asked to re-enter a field, you cannot move the cursor to other fields by using "TAB" or "BACKSPACE". AFTER YOU ARE DONE _____ ___ ___ ____ To logout off the computer, enter "EXIT" at the "DTR>" prompt and then enter "LO" from the "$" prompt. You will then be logged off of the computer. APPENDIX A LIST OF ALL USABLE KEYS ----------------------- 1. Left and Right arrows: Moves the cursor to the left and right, respectively, within the field you are in. 2. PF2 or F2: This key is the help key. It is located at the top right of the key pad. It is used to give you an example or an explaination of what is required in the field where you are at. 3. Tab: Moves you forward from one field to the next thru the menu. 4. Back-space: Move you back one field in the menu. 5. Line-feed: Erases everything in the field where the cursor is located. 6. Return: Tells the computer that you have entered all the data that you wish to on that menu. 7. Delete: Deletes the character to the left of the cursor. APPENDIX B Appendix B consists of the record layout, forms layout, and Datatrieve edit/update procedure. "PROTO.EDT": DELETE 1 THRU 2 DELETE "ANS" S/05//WHOLE /NOTYPE DEFINE KEY GOLD E AS "TOP999('PIC'SELELCUTSR)TOPEXT S/ //WHOLE/NOTYPE;EX." SET MODE CHANGE