TOPS-20 User Utilities Guide | Electronically Distributed This manual describes utility programs available to both privileged and nonprivileged users of the TOPS-20 operating system. Operating System: TOPS-20 (KS/KL Model A) V4.1 TOPS-20 (KL Model B) V6.1 Software: MAIL Version 6 RDMAIL Version 6 FILCOM Version 22 CREF Version 53B MAKLIB Version 2B DUMPER Version 5 PLEASE Version 5 digital equipment corporation maynard, massachusetts | TOPS-20 Update Tape No. 04, November 1990 First Printing, January 1980 Updated, January 1982 Updated, December 1982 Updated, September 1985 | Updated, November 1990 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies. | Copyright C 1980, 1982, 1985, 1990 Digital Equipment Corporation All Rights Reserved. The following are trademarks of Digital Equipment Corporation: CI DECtape LA50 SITGO-10 DDCMP DECUS LN01 TOPS-10 DEC DECwriter LN03 TOPS-20 DECmail DELNI MASSBUS TOPS-20AN DECnet DELUA PDP UNIBUS DECnet-VAX HSC PDP-11/24 UETP DECserver HSC-50 PrintServer VAX DECserver 100 KA10 PrintServer 40 VAX/VMS DECserver 200 KI Q-bus VT50 DECsystem-10 KL10 ReGIS DECSYSTEM-20 KS10 RSX d i g i t a l CONTENTS PREFACE CHAPTER 1 INTRODUCTION TO TOPS-20 USER UTILITIES 1.1 INVOKING THE UTILITIES . . . . . . . . . . . . . . 1-1 1.2 TYPING FILE SPECIFICATIONS . . . . . . . . . . . . 1-2 CHAPTER 2 THE MAIL PROGRAM 2.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 2-1 2.2 RUNNING MAIL . . . . . . . . . . . . . . . . . . . 2-1 2.3 OPTIONS TO THE MAIL PROCEDURE . . . . . . . . . . 2-4 2.4 MAIL MESSAGES . . . . . . . . . . . . . . . . . . 2-7 2.5 TECHNICAL NOTES . . . . . . . . . . . . . . . . 2-10 CHAPTER 3 THE RDMAIL PROGRAM 3.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 3-1 3.2 RUNNING RDMAIL . . . . . . . . . . . . . . . . . . 3-2 3.2.1 Reading Mail Using RDMAIL Switches . . . . . . . 3-4 3.3 RDMAIL MESSAGES . . . . . . . . . . . . . . . . . 3-8 CHAPTER 4 THE FILCOM PROGRAM 4.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 4-1 4.2 RUNNING FILCOM . . . . . . . . . . . . . . . . . . 4-1 4.2.1 Comparing ASCII Files . . . . . . . . . . . . . 4-3 4.2.2 Comparing Binary Files . . . . . . . . . . . . . 4-9 4.3 FILCOM SWITCHES . . . . . . . . . . . . . . . . 4-12 4.4 FILCOM MESSAGES . . . . . . . . . . . . . . . . 4-14 CHAPTER 5 THE CREF PROGRAM 5.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 5-1 5.2 RUNNING CREF . . . . . . . . . . . . . . . . . . . 5-1 5.2.1 Creating .CRF Files with COMPILE . . . . . . . . 5-1 5.2.2 Producing Cross-Reference Listings . . . . . . . 5-2 5.3 CREF EXAMPLES . . . . . . . . . . . . . . . . . . 5-6 5.4 CREF MESSAGES . . . . . . . . . . . . . . . . . 5-10 5.5 TECHNICAL NOTES . . . . . . . . . . . . . . . . 5-15 iii CHAPTER 6 THE MAKLIB PROGRAM 6.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 6-1 6.2 RUNNING MAKLIB . . . . . . . . . . . . . . . . . . 6-3 6.2.1 Running MAKLIB to Obtain Information About Libraries . . . . . . . . . . . . . . . . . . . 6-4 6.2.2 Running MAKLIB to Manipulate Libraries . . . . . 6-7 6.2.3 Running MAKLIB to Modify Libraries . . . . . . 6-18 6.2.4 Running MAKLIB to Edit Libraries . . . . . . . 6-19 6.3 MAKLIB SWITCH OPTIONS . . . . . . . . . . . . . 6-26 6.4 MAKLIB MESSAGES . . . . . . . . . . . . . . . . 6-27 6.5 TECHNICAL NOTES . . . . . . . . . . . . . . . . 6-44 6.5.1 Format of TRACE Block Data (REL Block Type 1060) . . . . . . . . . . . . . . . . . . . . 6-44 6.5.2 Format of Code Insertion . . . . . . . . . . . 6-45 CHAPTER 7 THE DUMPER PROGRAM 7.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 7-1 7.2 FEATURES . . . . . . . . . . . . . . . . . . . . . 7-2 7.3 USING TAPES WITH AND WITHOUT TAPE DRIVE ALLOCATION 7-3 7.4 RUNNING DUMPER . . . . . . . . . . . . . . . . . . 7-7 7.5 THE NONPRIVILEGED USER . . . . . . . . . . . . . . 7-7 7.5.1 Setting the Status of Operation . . . . . . . . 7-8 7.5.2 Positioning the Tape . . . . . . . . . . . . . 7-20 7.5.3 Interacting with Tape Files . . . . . . . . . 7-23 7.5.4 Marking Files to be Archived . . . . . . . . . 7-33 7.6 THE PRIVILEGED USER . . . . . . . . . . . . . . 7-33 7.6.1 Backing Up System Files and/or Other Users' Files . . . . . . . . . . . . . . . . . . . . 7-35 7.6.2 Restoring Files and Directories from System Backup Tapes . . . . . . . . . . . . . . . . . 7-37 7.6.3 Archiving Marked Files . . . . . . . . . . . . 7-38 7.6.4 Migrating Files . . . . . . . . . . . . . . . 7-39 7.6.5 Retrieving or Restoring Archived and Migrated Files . . . . . . . . . . . . . . . . . . . . 7-40 7.7 DUMPER COMMANDS . . . . . . . . . . . . . . . . 7-42 7.8 DUMPER MESSAGES . . . . . . . . . . . . . . . . 7-50 CHAPTER 8 PLEASE 8.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 8-1 8.2 SWITCHES USED WITH PLEASE . . . . . . . . . . . . 8-1 8.3 MESSAGE TERMINATORS USED WITH PLEASE . . . . . . . 8-1 8.4 RUNNING PLEASE . . . . . . . . . . . . . . . . . . 8-2 8.5 PLEASE MESSAGES . . . . . . . . . . . . . . . . . 8-3 INDEX iv FIGURES 6-1 Figure Generation of an .EXE File . . . . . . . . 6-1 6-2 Generation of a Library . . . . . . . . . . . . . 6-2 6-3 Function of /APPEND . . . . . . . . . . . . . . . 6-8 6-4 Function of /DELETE . . . . . . . . . . . . . . 6-10 6-5 Function of /EXTRACT . . . . . . . . . . . . . . 6-12 6-6 One Function of /INSERT . . . . . . . . . . . . 6-14 6-7 One Function of /INSERT . . . . . . . . . . . . 6-15 6-8 Function of /REPLACE . . . . . . . . . . . . . . 6-17 6-9 Order of Pseudo-ops in a .FIX File . . . . . . . 6-23 TABLES 3-1 RDMAIL Switches . . . . . . . . . . . . . . . . . 3-4 4-1 Special File Types Recognized by FILCOM . . . . . 4-2 4-2 FILCOM Switches . . . . . . . . . . . . . . . . 4-13 4-3 Reasons for File Access Errors . . . . . . . . . 4-17 5-1 CREF Switch Options . . . . . . . . . . . . . . . 5-4 5-2 Reasons for File Access Errors . . . . . . . . . 5-14 5-3 Error Status Codes . . . . . . . . . . . . . . . 5-15 5-4 Beginning and Ending Control Characters . . . . 5-16 5-5 Symbol-Definition Control Characters . . . . . . 5-17 5-6 Character-Count-Definition Characters . . . . . 5-19 6-1 MAKLIB Switches . . . . . . . . . . . . . . . . 6-26 7-1 Status-Setting Commands . . . . . . . . . . . . . 7-8 7-2 Tape-Positioning Commands . . . . . . . . . . . 7-21 7-3 Action Commands . . . . . . . . . . . . . . . . 7-24 7-4 File Descriptor Block (FDB) Entries Checked by DUMPER . . . . . . . . . . . . . . . . . . . . . 7-29 vi PREFACE The TOPS-20 User Utilities Guide is intended for both the privileged and the nonprivileged user who needs information on utility programs that run on the TOPS-20 operating system. Before you use this manual, you should be familiar with the information contained in Getting Started with TOPS-20, the TOPS-20 User's Guide, and the TOPS-20 Commands Reference Manual. This document provides detailed information on the following TOPS-20 utility programs: MAIL, RDMAIL, FILCOM, CREF, MAKLIB, DUMPER, and PLEASE. The manual contains tutorial and reference material in each chapter to accommodate both the novice and the experienced user. The following conventions are used throughout the TOPS-20 User Utilities Guide: Indicates when you should press the RETURN key (on some terminals the key labeled CR) Indicates when you should press the ESC key (on some terminals the key labeled ALT) Indicates when you should press the DELETE key Indicates when you should hold down the CTRL key and at the same time type the letter x file spec Indicates a file specification __________ ____ | underlined text Indicates anything you type or are expected to type | on your terminal. vii The current version of the following TOPS-20 documents are referenced in this manual: Getting Started With TOPS-20 TOPS-20 User's Guide TOPS-20 Commands Reference Manual TOPS-20 Operator's Guide TOPS-20 Monitor Calls Reference Manual TOPS-20 LINK Reference Manual TOPS-20 MACRO ASSEMBLER Reference Manual TOPS-20 System Manager's Guide TOPS-10/TOPS-20 Batch Reference Manual 8 CHAPTER 1 CHAPTER 1 INTRODUCTION TO TOPS-20 USER UTILITIES INTRODUCTION TO TOPS-20 USER UTILITIES This manual describes utility programs available to any user of the TOPS-20 operating system. The following utility programs are covered in this manual: o The MAIL program, which allows you to send messages to other users of the system (Chapter 2) o The RDMAIL program, which allows you to read messages sent to you via the MAIL program (Chapter 3) o The FILCOM program, which allows you to compare two ASCII files or two binary files (Chapter 4) o The CREF program, which produces cross-reference listings of symbols used in MACRO, FORTRAN, and ALGOL programs (Chapter 5) o The MAKLIB program, which performs various functions on libraries of relocatable object modules (Chapter 6) o The DUMPER program, which allows you to save files and directories on tape, and restore these files and directories to disk (Chapter 7) o The PLEASE program, which allows you to communicate with the system operator (Chapter 8). 1.1 INVOKING THE UTILITIES 1.1 INVOKING THE UTILITIES To invoke these utilities, you should be familiar with the TOPS-20 log-in procedure. Type the name of the program after the TOPS-20 prompt @ and press RETURN. The utility then prompts you for input. Thus, the general format is: 1-1 INTRODUCTION TO TOPS-20 USER UTILITIES INTRODUCTION TO TOPS-20 USER UTILITIES _______ _________ @Utility Name Utility prompt 1.2 TYPING FILE SPECIFICATIONS 1.2 TYPING FILE SPECIFICATIONS Many of the utilities accept file specifications as arguments. There are two forms of file specifications. The MAIL, RDMAIL, and DUMPER utilities accept file specifications in the following format: dev:name.typ.gen;att...;att where: dev: Indicates a device name, a file structure name, or a defined logical name Indicates a directory name name Indicates the filename of a particular file in the directory .typ Indicates a file type that helps identify the contents of the file .gen Indicates a generation number that shows the number of times a file has been changed ;att Indicates a file attribute such as a file protection or an account string. If you omit the dev: field of the file specification, the system assumes that you mean your connected structure. When you omit the field of the file specification, the system assumes that you mean your connected directory. When you omit the .gen field of the file specification, the system assumes that you mean the highest generation (largest generation number) for source files. For Destination files, the system assumes that you mean the highest generation plus one. You can use recognition on file specifications in this format. You can use wildcards only in the DUMPER program. (Refer to Chapter 7.) For more information on file specifications, refer to the TOPS-20 User's Guide. The FILCOM, CREF, and MAKLIB utilities accept file specifications in a slightly different format as follows: dev:name.typ[PPN] 1-2 INTRODUCTION TO TOPS-20 USER UTILITIES INTRODUCTION TO TOPS-20 USER UTILITIES In this form of a file specification, filenames are restricted to six characters. File types are restricted to three characters. You cannot use recognition, and file generation numbers are not allowed. Therefore, the highest generation of a file is always used. You can use wildcards only in the MAKLIB program. (Refer to Chapter 6.) The PPN is a project-programmer number, which you use instead of a directory name. To find out the PPN associated with a specific directory, give the TRANSLATE command. For example, if you wish to find out the PPN associated with the directory on PS: you do the following: _________ _______________ @TRANSLATE PS: PS: PS:[4,305] @ You can avoid using PPN's in file specifications by defining a logical name that represents the directory you wish to access. Do the following procedure: 1. Give the DEFINE command to define a logical name as the directory. 2. Use the logical name in place of the device name and the PPN when you type the file specification. The following is an example of defining a logical name for a directory and using it with the FILCOM program: ______ ____ ____________ @DEFINE (LOGICAL NAME) ADL: (AS) ___________ @FILCOM ____________________________________ *TTY:=ADL:TEST.MAC,ADL:TEST2.MAC You can also define logical names to reference long filenames or particular file generation numbers. This is especially useful with the FILCOM program when you wish to compare two similar files with different generation numbers. For example: ______ __ ______________ @DEFINE (LOGICAL NAME) A: (AS) FOO.BAR.3 ______ __ ______________ @DEFINE (LOGICAL NAME) B: (AS) FOO.BAR.4 ___________ @FILCOM _______________ *TTY:=A:,B: 1-3 2-1 CHAPTER 2 CHAPTER 2 THE MAIL PROGRAM THE MAIL PROGRAM 2.1 INTRODUCTION 2.1 INTRODUCTION You can use the MAIL program to send messages to other users of the system. You can send mail to a single user or to a group of users who are either logged in or not logged in. 2.2 RUNNING MAIL 2.2 RUNNING MAIL To run MAIL, type MAIL after the TOPS-20 prompt @ and press the RETURN key. The program responds with the To: prompt as follows: _________ @MAIL To: Type the name of the user to whom you are sending the message, and press RETURN. If you are sending a message to a group of users, type the names, separating them with commas, and press RETURN. For example: ____________________________ To: Adley,Sartini,McElmoyle The program then prompts: CC: Now list any secondary recipients of your message. Type the name or names (separated by commas) and press RETURN. If you do not want to send a copy to others, simply press RETURN after the CC: prompt. If you type an invalid (nonexistent) user name, the program responds with: ?Invalid user name 2-1 THE MAIL PROGRAM THE MAIL PROGRAM MAIL returns with either the To: prompt or the CC: prompt. Type CTRL/H after either prompt. This retrieves only the names up to the error, and you can type any additional valid names. You cannot send more than one copy of a mail message to a user. If you type a user name more than once after either the To: or the CC: prompt, the program prints a warning message. For example: __________ To: Adley __________ CC: Adley %Duplicate name purged - ADLEY The MAIL program continues after it prints the warning message; however, the program removes the duplicate name from the list of users. The program then prompts with: Subject: Type a description of the message and press RETURN. For example: ________ __ ______ _______ ____________ Subject: Location of weekly writers meeting If your description exceeds one line, you cannot continue the description on a second line; you must continue typing when you reach the end of a line. The system automatically continues your description on the second line by responding with a carriage return line feed sequence. When you have completed typing your description, press RETURN. For example: ________ __ ______ _______ ___ ______ __ ________ Subject: Location of weekly meeting and change in software _______ __________ release date. NOTE The system may interpret a character in the Subject: line (such as a question mark) as a special character. To avoid this, precede the character with a CTRL/V. MAIL then prompts with: Message (Terminate with ESC or CTRL/Z): and waits for you to enter your message. Once you have terminated your message by typing ESC or CTRL/Z, the program informs you that it has processed your message: Processing mail... No errors. 2-2 THE MAIL PROGRAM THE MAIL PROGRAM -DONE- and returns you to TOPS-20 command level. If you send a message to a user who is logged in and accepting links and system messages, that user is informed immediately as follows: [You have a message from SENDER] If you send a message to a user who is not logged in, that user is informed the next time he logs in: _____ _____ ________ @LOGIN (USER) ADLEY (PASSWORD) (ACCOUNT) 341 Job 54 on TTY33 23-Apr-79 09:46:05 You have a message @ If you make an error in sending mail to a user, you receive one of the following messages: [USER NAME] not sent BECAUSE: Invalid directory number or Invalid simultaneous access or No such file type (or some other reason related to why the recipient's MAIL.TXT file could not be found) or [USER NAME] not sent BECAUSE: Disk quota exceeded NOTE For additional information on these error messages, refer to Section 2.4, MAIL Messages. You can use a recovery procedure to resend mail after receiving some of the MAIL error messages. This recovery is particularly helpful when your message is long and you do not want to retype it. The procedure is as follows: 1. Undelete the MAIL.CPY file in your logged-in directory. This file contains the message that could not be sent. 2-3 THE MAIL PROGRAM THE MAIL PROGRAM 2. Rename the MAIL.CPY file; for example, ERROR.TXT. This prevents MAIL from deleting the file a second time during message processing. 3. After the TOPS-20 prompt @, type: ___ _____________ @GET SYS:MAIL 4. The system gives the TOPS-20 prompt once again, and you type: ____________ @REENTER 5. After you press RETURN, the system prompts: File name of message file: Now type the new file spec of the renamed MAIL.CPY file, and press RETURN: _____ __________ File name of message file: (file spec) The MAIL program now proceeds as though you had just typed ESC or CTRL/Z after the message. 2.3 OPTIONS TO THE MAIL PROCEDURE 2.3 OPTIONS TO THE MAIL PROCEDURE The procedure in Section 2.2 describes the most common use of MAIL. Options to this basic procedure are as follows: 1. You can use the TALK command as an alternative to the MAIL program to communicate with a user who is logged in. (For more information on the TALK command, refer to the TOPS-20 Commands Reference Manual.) 2. You can use the INFORMATION MAIL command to check on the status of new mail, either your own or that of other users. (For more information on this command, see the TOPS-20 Commands Reference Manual.) 3. If you send mail often to a group of users, you can create a file containing these names. Then, instead of typing all the names each time you send a message, you can type the filename, preceded by an @, after the To: prompt or the CC: prompt. For example, if the file NAME.FIL.1 contains the user names ADLEY, CRUGNOLA, LYONS, type: ________________ To: @NAME.FIL.1 The filename can also be combined with other user names following the prompt. However, the file must follow the list of additional user names. For example: 2-4 THE MAIL PROGRAM THE MAIL PROGRAM __________________________________ To: Sartini,McElmoyle,@NAME.FIL.1 4. You can use the contents of an indirect file as your message or Subject: line text. The indirect file you use in the Subject: line can contain only one line. You cannot type any additional text on this line with the indirect file. To send the contents of an indirect file as mail, type an @ followed by the name of the file, and press RETURN. You cannot type any additional text before or after the indirect file. For example: _________ @MAIL _____________ To: Crugnola _____ CC: _____ __________ Subject: Macro files Message (Terminate with ESC or CTRL/Z): ________________ @MACRO.CMD.1 Processing mail... No errors. -DONE- @ In this case, you do not terminate the message with ESC or CTRL/Z, because you are using an indirect file as your message. However, you terminate the file spec by pressing RETURN. If you terminate your message with CTRL/Z, MAIL responds with: ___________ ________ @MACRO.CMD.1 (CTRL/Z) ?Not confirmed To recover, type CTRL/H immediately to retrieve the indirect file spec. Then, press RETURN. 5. Normally, you send mail to other users. However, you can also send mail to any non-files-only directory on PS:. The most common non-files-only directories are PS: and PS:. PS: can be used for recording information and problems that the system staff should be aware of. For example, use PS: to record any system difficulties, hardware/software problems, or other related items. To send a message to this directory, type REMARKS after the To: prompt. For example: 2-5 THE MAIL PROGRAM THE MAIL PROGRAM _________ @MAIL ____________ To: REMARKS _____ CC: _____________ Subject: Supplies Message (Terminate with ESC or CTRL/Z): _________ __ ____ ___ ____ __________ _____ __ ______ ____ Terminals in Room 216 need additional boxes of paper, size _ ___ _ ___ _____ 9 7/8 x 11. Processing mail... No errors. -DONE- @ Generally, to send messages to all users of the system, you enable your WHEEL or OPERATOR capabilities and run MAIL. These messages are called Messages-of-the-Day. You can also send Messages-of-the-Day by connecting to the directory PS:. However, most systems are not set up to allow users to connect to this directory. The following example shows an enabled user running MAIL to send a Message-of-the-Day. _________ $MAIL ___________ To: SYSTEM _____ CC: ______ ______________ Subject: System shut-down Message (Terminate with ESC or CTRL/Z): ___ ______ ____ __ ____ ____ ________ __ _ ____ ___ The system will be shut down tomorrow at 5 p.m. for __________ ____________ _____ preventive maintenance. Processing mail... No errors. -DONE- $ If you attempt to send mail to PS: and do not enable WHEEL or OPERATOR capabilities, MAIL prints the following error message: Processing mail...SYSTEM not sent BECAUSE: WHEEL or OPERATOR capability required To resend the mail, you can follow the recovery procedure described in Section 2.2 after you enable WHEEL or OPERATOR capabilities. 2-6 THE MAIL PROGRAM THE MAIL PROGRAM When you send a message to PS:, the following message appears on all terminals that are receiving system messages: [New Message-of-the-Day available] Users not logged in to the system at the time you send the message automatically receive new Messages-of-the-Day the next time they log in. 6. You can use MAIL to inform yourself that your batch job is completed. Place commands to MAIL in your control file as shown in the following example. Note that a period is used as the reply to the To: prompt. This character replaces a user name and informs MAIL that the message is to be sent to you. For example: ______ _____________ @CREATE (FILE) TEST.CTL _____________ INPUT: TEST.CTL ____________ 00100 @FILCOM _____________________________________ 00200 *TEST.FOR=DIFFER.FOR,ADDEM.FOR/A ______ _____________ 00300 @PRINT TEST.FOR __________ 00400 @MAIL _______ 00500 *. ______ 00600 * ______ ___ __ _________ 00700 *BATCH JOB IS DONE ___ 00800 *^Z _____ 00900 _ *E @ NOTE Use of a period in place of your user name when you run MAIL is not a feature unique to batch. You can use it any time in the MAIL program when you wish to specify yourself as a recipient of mail. 2.4 MAIL MESSAGES 2.4 MAIL MESSAGES The most common MAIL messages, their descriptions, and suggested user responses follow. Fatal errors are preceded by a question mark (?). Warning messages are preceded by a percent sign (%). %Duplicate name purged - [USER NAME] Description: You attempted to send a user more than one copy of a mail message. Suggested User Response: None. MAIL continues automatically, and eliminates the duplicate name. 2-7 THE MAIL PROGRAM THE MAIL PROGRAM ?Invalid user name Description: You typed an invalid (nonexistent) user name as a recipient of your message. Suggested User Response: Type CTRL/H after either the To: prompt or the CC: prompt to retrieve only the names up to the error. Type any additional valid names. ?MAIL.CPY Failure Entire file structure full Description: The public structure (PS:) is full, and therefore MAIL cannot operate. You receive this message immediately after invoking the program. Suggested User Response: Delete and expunge some files from your logged-in directory, or wait until some space is freed. ?MAILER is not running. Messages not sent. Description: Your message was not sent because the MAILER program is not functioning. Suggested User Response: Send a message to the operator with the PLEASE program (refer to Chapter 8) to report that MAILER is not functioning. Then, once MAILER is functioning, use the recovery procedure described in Section 2.2 to resend your message. ?Not confirmed Description: You did not press RETURN immediately after typing an indirect file spec. Suggested User Response: TYPE CTRL/H immediately after the error message to retrieve the indirect file spec. Then, press RETURN to confirm the indirect file spec. ?Processing errors occurred. No mail sent. Description: There is a problem with you MAIL.CPY file; either MAILER cannot find it, or the file is not in correct format. Suggested User Response: Check to see if there is another program updating MAIL.CPY. If not, contact your Software Specialist or send a Software Performance Report (SPR) to DIGITAL. SYSTEM not sent BECAUSE: WHEEL or OPERATOR capability required Description: You attempted to send mail to PS: and did not enable WHEEL or OPERATOR capabilities. 2-8 THE MAIL PROGRAM THE MAIL PROGRAM Suggested User Response: You must enable WHEEL or OPERATOR capabilities before sending mail to PS:. To resend the mail, you can follow the recovery procedure described in Section 2.2 after you enable WHEEL or OPERATOR capabilities. %Too many user names. 100 is maximum. Description: You specified too many users as recipients of your message. MAIL only allows up to 100 user names as recipients of a message; it sends your message to the first 100 names but ignores all that exceed the first 100. Suggested User Response: Send your message to the first 100 names. Next, edit your MAIL.CPY file to retrieve the message text. Then, run MAIL to send the message to the additional names, using "@" to send the edited MAIL.CPY file as the message text. [USER NAME] not sent BECAUSE: Invalid directory number Description: You attempted to send mail to a nonexistent user directory. Suggested User Response: You cannot send mail to a user who does not have a directory. [USER NAME] not sent BECAUSE: Invalid simultaneous access Description: Another user has the receiver's MAIL.TXT file open for writing. Suggested User Response: Follow the recovery procedure described in Section 2.2 to resend the message. [USER NAME] not sent BECAUSE: No such file type (or some other related reason) Description: The intended receiver of your message has no MAIL.TXT file. Suggested User Response: Ask the user to create a MAIL.TXT file to receive mail messages. 2-9 THE MAIL PROGRAM THE MAIL PROGRAM [USER NAME] not sent BECAUSE: Disk quota exceeded Description: The receiver's directory exceeds its working quota. Suggested User Response: Some files must be deleted from the directory before mail can be received. You can also enable WHEEL or OPERATOR capabilities to ignore the user's quota. If the user is logged in, you can use the TALK command as an alternative. 2.5 TECHNICAL NOTES 2.5 TECHNICAL NOTES MAIL works with another program called MAILER when it handles messages. When you type a mail message, MAIL creates a file, MAIL.CPY, in your logged-in directory. This file is closed when you complete your message input. At this point, MAIL sends an IPCF (Inter-Process Communication Facility) packet to the MAILER program to inform it that you want to send a message. (For more information on IPCF, refer to the TOPS-20 Monitor Calls Reference Manual.) MAILER processes the message by appending the contents of MAIL.CPY in your logged-in directory to the file MAIL.TXT in the recipient's logged-in directory. Then it sends an IPCF packet back to MAIL, which notifies you of the status of your message (sent or not sent). At this point, the MAIL.CPY file is deleted from your logged-in directory. 2-10 CHAPTER 3 CHAPTER 3 THE RDMAIL PROGRAM THE RDMAIL PROGRAM 3.1 INTRODUCTION 3.1 INTRODUCTION The RDMAIL program prints messages that have been sent to you by other users of the system through the MAIL program. Your MAIL.TXT file in your logged-in directory on PS: contains these messages. NOTE If your MAIL.TXT file contains mail sent by Version 4 of the MAIL program, you must use Version 4 of RDMAIL to read it. There are various ways that the system notifies you whenever there is mail that you have not read. If another user sends you mail while you are not logged in, you receive the following message the next time you log in: _____ _____ ________ @LOGIN (USER) DBELL (PASSWORD) (ACCOUNT) 341 Job 35 on TTY42 29-Aug-79 16:14:12 You have a message @ Another user may send you a message while you are logged in. In this case, the system types [You have a message from SENDER] on your terminal. Messages-of-the-Day sent to you when you are not logged in are printed on your terminal automatically after you log in. However, if your directory is set to REPEAT LOGIN-MESSAGES, you receive all Messages-of-the-Day every time you log in. For more information on the REPEAT LOGIN-MESSAGES subcommand, refer to the BUILD command description in the TOPS-20 Commands Reference Manual. If a system 3-1 THE RDMAIL PROGRAM THE RDMAIL PROGRAM message is sent while you are logged in and you are receiving system messages, you are notified immediately: [New Message-of-the-Day available] You can give the SET MAIL-WATCH command to keep informed of any new mail you receive, especially if you have given the REFUSE SYSTEM-MESSAGES command. (For more information on these two commands, refer to the TOPS-20 Commands Reference Manual.) You can add the SET MAIL-WATCH command to your COMND.CMD file, if you have one, or type it each time you log in. When you give this command, it tells the system to notify you when you have new mail. You receive this notification only when you are at TOPS-20 command level. At intervals of approximately five minutes, the TOPS-20 Command Processor informs you that you have new mail whenever it prompts you for a new command. This message appears on your terminal: [You have new mail] You may give the INFORMATION MAIL command, even if you are not logged in, to check on the status of new mail for yourself or other users. To do this, type the following: ___________ ____ _________ @INFORMATION (ABOUT) MAIL (FOR USER) name The system returns with one of the following responses: New mail exists or No new mail exists or Mailbox protected 3.2 RUNNING RDMAIL 3.2 RUNNING RDMAIL To start RDMAIL, type RDMAIL after the TOPS-20 prompt @ and press the RETURN key. The program responds with the date and time prompt as follows: ___________ @RDMAIL Date and time (/HELP for help) If you have enabled WHEEL or OPERATOR capabilities, RDMAIL first asks you whether you want to read your own mail or that of another user. For example: 3-2 THE RDMAIL PROGRAM THE RDMAIL PROGRAM ___________ $RDMAIL Special user (y or n)? If you type y, you are indicating that you wish to read another user's mail. Type y and press RETURN. RDMAIL then prompts you to type the name of the user whose mail you wish to read. Type the user name and press RETURN. RDMAIL then prompts you for date and time input. For example: ___________ $RDMAIL ______ Special user (y or n)? y __________ User name: DNeff Date and time (/HELP for help) If you type n, you are indicating that you wish to read your own mail. Type n and press RETURN. RDMAIL then prompts you for date and time input. For example: ___________ $RDMAIL ______ Special user (y or n)? n Date and time (/HELP for help) RDMAIL allows you to read your messages several ways: o By giving a date and/or time o By giving a program switch or combination of switches o By giving a date and/or time combined with one or more program switches. To read any new messages, simply press RETURN. You can define a time period of mail you wish to read. To do this, type a date and/or a time. A common TOPS-20 format is: MMM DD,YYYY HH:MM:SS For example, a valid date and time is May 22,1979 17:00:00. If you type only a date, RDMAIL assumes the time 00:01:00. If you type only a time, the program assumes the present date. RDMAIL responds by displaying all messages you received on and after the date and/or time you typed. If you type an invalid date or time, you receive an error message. Three of the most common ones are: ?Invalid date format or ?Invalid time format 3-3 THE RDMAIL PROGRAM THE RDMAIL PROGRAM or ?Day of month too large After the error message RDMAIL returns with the prompt for you to type a valid date and/or time. Table 3-1 describes the RDMAIL switches you can use after the prompt, either alone or combined with date/time input. Table 3-1: RDMAIL Switches Table 3-1: RDMAIL Switches ______________________________________________________________________ Switch Function ______________________________________________________________________ /ALL Types all messages, regardless of date. /HELP Types the program help text, outlining the time/date format and program switches and their functions. /LIST Outputs messages to the line printer, rather than to your terminal. /MESSAGE-OF-THE-DAY Types messages from the system Message-of-the-Day file, rather than from your own message file. /PERUSE Allows you to peruse messages, and gives only the following information for each message: Date: From: To: CC: and Subject. /STOP Instructs RDMAIL to stop after each message it types. At the end of each message, the system prompts you to type RETURN for more output. ______________________________________________________________________ 3.2.1 Reading Mail Using RDMAIL Switches 3.2.1 Reading Mail Using RDMAIL Switches You type RDMAIL switches immediately following the prompt, and may or may not combine them with a date and/or time. You have the options of combining switches and preceding each switch with a space. To use RDMAIL switches, type a slash (/) followed by the switch name. 3-4 THE RDMAIL PROGRAM THE RDMAIL PROGRAM /HELP - HELP Switch Type /HELP to get information on running RDMAIL. For example: ___________ @RDMAIL __________ Date and time (/HELP for help) /HELP After the help text prints on your terminal, the system returns with the prompt for you to type date/time information and/or another switch. NOTE HELP overrides all other switches that you may combine with it. The system ignores all other specified switches in the combination, and prints the full RDMAIL help text. /ALL - ALL Switch Type /ALL when you wish to read all messages in the mail file, regardless of date. /ALL may be combined with all other program switches except /HELP. If you type /ALL after the prompt, ___________ @RDMAIL ________ Date and time (/HELP for help) /ALLRET> RDMAIL accesses all messages in your file. /LIST - LIST Switch Type /LIST when you want messages output to the line printer rather than to your terminal. /LIST can be combined with date/time input, and/or with /ALL. For example, ___________ @RDMAIL ___ ___ ____ ________ __________ Date and time (/HELP for help) May 13, 1979 12:00:00 /LIST Prints all messages in your file on and after 12:00:00 of May 13, 1979 on the line printer. If you type only /ALL /LIST after the prompt, RDMAIL prints all messages in your file on the line printer. /MESSAGE-OF-THE-DAY - System Message Switch Type /MESSAGE-OF-THE-DAY to print mail from the system Message-of-the-Day file (PS:MAIL.TXT), rather than from your own message file. Since new entries in the Message-of-the-Day file are typed on your terminal when you log in, you normally use this switch when a new Message-of-the-Day becomes available while you are logged in. /MESSAGE-OF-THE-DAY 3-5 THE RDMAIL PROGRAM THE RDMAIL PROGRAM may be combined with date/time input. It may also be combined with all other program switches except /HELP. For example: [New Message-of-the-Day available] ___________ @RDMAIL ________________________ Date and time (/HELP for help) /MESSAGE-OF-THE-DAY -------- Date: 25 Jun 79 0853-EDT From: OPERATOR To: SYSTEM Subject: STAND-ALONE AT NOON SYSTEM IS GOING DOWN AT NOON FOR NEW MONITOR TO BE LOADED. ======== @ In this case, the system prints the Messages-of-the-Day since June 25, 1979 on your terminal. When you type /MESSAGE-OF-THE-DAY after the prompt, RDMAIL outputs all new Messages-of-the-Day since you last logged in, whether or not you have read them. /PERUSE - PERUSE Switch Type /PERUSE when you want to peruse messages in your file. Only the following lines for each message are printed: Date:, From:, To:, CC:, and Subject: /PERUSE can be combined with date/time input and all other program switches except /HELP. A sample output of /PERUSE is as follows: ___________ @RDMAIL ___ _______ ____________ Date and time (/HELP for help) Apr 12,1979 /PERUSE -------- Date: 12 Apr 79 0900-EDT From: OSMAN To: ADLEY -------- Subject: your files -------- Date: 12 Apr 79 1452-EDT From: HARAMUNDANIS To: PORADA CC: ADLEY,HARAMUNDANIS -------- Subject: DUMPER 3-6 THE RDMAIL PROGRAM THE RDMAIL PROGRAM -------- Date: 17 Apr 79 1451-EDT From: LYONS To: ADLEY -------- Subject: Re: TEST OF MAIL PROGRAM The system continues to output messages from April 12, 1979 to the present date. /STOP - STOP Switch Type /STOP to cause RDMAIL to stop after each message that it types. Following each message, the program prompts you to press RETURN for more output. /STOP can be combined with date/time input and all other program switches except /HELP and /LIST. A sample output of /STOP and /PERUSE is as follows: ___________ @RDMAIL ___ ______ _____ ____________ Date and time (/HELP for help) May 1,1979 /STOP /PERUSE -------- Date: 1 May 79 1335-EDT From: OSMAN To: ADLEY -------- Subject: MAILER _____ [Type for more] -------- Date: 1 May 79 1844-EDT From: LYONS To: ADLEY -------- Subject: Your account on System 2116 _____ [Type for more] The system continues to output messages from May 1, 1979 to the present date, allows you to peruse them, and stops after each message. If you type an invalid switch in RDMAIL, you receive the following message: ?Does not match switch or keyword The system returns with the prompt for you to type a valid switch. 3-7 THE RDMAIL PROGRAM THE RDMAIL PROGRAM 3.3 RDMAIL MESSAGES 3.3 RDMAIL MESSAGES The most common RDMAIL messages, their descriptions, and suggested user responses follow. Fatal errors are preceded by a question mark (?). A warning message is preceded by a percent sign (%). ?Day of month too large Description: You typed an invalid day of the month after the program prompt, Date and time (/HELP for help). Suggested User Response: Enter a valid day of month when the program returns with the prompt following the error message. ?Does not match switch or keyword Description: You typed an invalid switch after the program prompt, Date and time (/HELP for help). Suggested User Response: Type one or more valid RDMAIL switches. %MAIL.TXT File contains updated entries or improper format Description: Your MAIL.TXT file is in the wrong format, possibly from being edited with a text editor. Suggested User Response: Copy the file so you have a record of any current messages. Then, delete the file. ?Invalid date format Description: You made an error in the date format following the program prompt, Date and time (/HELP for help). This error differs from an invalid day of the month; the error might be, for example, misspelling of the month or an incorrect year. Suggested User Response: Type a valid date format when the program returns with the prompt after the error message. ?Invalid time format Description: You typed an invalid time after the program prompt, Date and time (/HELP for help). For example, a possible error is a nonexistent time such as 26:00:00. Suggested User Response: Type a valid time when the program returns with the prompt after the error message. 3-8 THE RDMAIL PROGRAM THE RDMAIL PROGRAM ?LPT: not available for output Description: This message appears in response to /LIST. Either you defined a logical name for LPT: that points to an unavailable device. RDMAIL ignores /LIST, and prints the mail on your terminal. Suggested User Response: Wait for the line printer to become available, or redefine the logical name to point to an available device (such as DSK:). 3-9 4-1 CHAPTER 4 CHAPTER 4 THE FILCOM PROGRAM THE FILCOM PROGRAM 4.1 INTRODUCTION 4.1 INTRODUCTION The FILCOM program compares two files and prints any differences between them. With FILCOM, you can compare either ASCII files (text files and source programs) or binary files (relocatable binary files and save files). The comparison is line by line for ASCII files, and word by word for binary files. 4.2 RUNNING FILCOM 4.2 RUNNING FILCOM To run FILCOM, type FILCOM, and press the RETURN key. The program prompts you for input with an asterisk: ___________ @FILCOM * After the prompt, enter a FILCOM command string in the following format: Destination file spec=Source file spec1,Source file spec2/Switches where: Destination file spec is the output file that contains the differences between the two Source files. If you do not specify a Destination filename, FILCOM uses the name of the file in Source file spec2. If you omit the name in Source file spec2, the program uses the filename from Source file spec 1. If there is no filename in Source file spec 1, then the filename FILCOM is used. The default for the Destination file type is .SCM for ASCII files and .BCM for binary files. If you completely omit the Destination file spec, FILCOM writes the output to the device TTY:. 4-1 THE FILCOM PROGRAM THE FILCOM PROGRAM Source file spec1 is the first input file you wish to compare. You must completely specify this file spec in the command string. Source file spec2 is the second input file you wish to compare. If you omit the filename in Source file spec2, FILCOM uses the filename in Source file spec1. If you omit the file type in Source file spec2, FILCOM uses the file type in Source file spec1. To indicate a null file type, simply type a period (.) at the end of the filename in either Source file spec1 or Source file spec2. NOTE FILCOM does not accept file generation numbers. You can compare two files with the same name and type but different generation numbers (for example, FOO.BAR.1 and FOO.BAR.2) by defining logical names for these files. For more information on defining logical names, refer to the TOPS-20 User's Guide. FILCOM accepts six characters for a name and three characters for type. If more than nine characters are used, FILCOM truncates to nine characters. You can enter switches after the two input file specs. These switches tell FILCOM how to compare the specified files. However, you don't always need to give switches, because FILCOM often determines the type of comparison by the file types. If either of the input files is of a type listed in Table 4-1, the files are compared in binary mode; otherwise they are compared in ASCII mode. Table 4-1: Special File Types Recognized by FILCOM Table 4-1: Special File Types Recognized by FILCOM ______________________________________________________________________ File type Extension ______________________________________________________________________ .APL .DMP .RIM .ATR .MSB .RMT .BAC .OVL .RTB .BIN .OVR .SCH Binary Files: .BUG .QUC .SFD .CAL .QUD .SYM .CHN .QUE .SYS .DAE .QUF .UFD .DBS .REL .UNV .DCR .XPN Sharable Save Files: .EXE 4-2 THE FILCOM PROGRAM THE FILCOM PROGRAM Nonsharable Save Files: .LOW .SAV .SVE Offset Address Files; word 0 of the file treated as if it was word 400000. .HGH .SHR ______________________________________________________________________ NOTE If FILCOM cannot determine the mode for comparison from the input file type or switches, it compares the files in ASCII mode. For more information on sharable and nonsharable save files and the control words used in them, refer to the TOPS-20 Monitor Calls Reference Manual. After you enter the command string specifying the mode for comparison, the two input files, and any necessary switches, press RETURN. When FILCOM has finished the comparison, it notifies you of the status: %files are different or No differences encountered The program then prints a second asterisk for you to enter another command string. For example: ___________ @FILCOM _________________________________ *COMPAR.FIL=EXFILE.1,EXFILE.2 %files are different * If you wish to stop the program, type CTRL/C to return to TOPS-20 command level. 4.2.1 Comparing ASCII Files 4.2.1 Comparing ASCII Files In ASCII mode, FILCOM compares the characters in each line of the two files, always ignoring nulls. Comments and spacing can be selectively ignored, based on the switches you type. FILCOM contains the following switches that you use in the command string to compare ASCII files. 4-3 THE FILCOM PROGRAM THE FILCOM PROGRAM /A Instructs FILCOM to compare the two input files in ASCII mode. It treats both files as if they contain ASCII characters, searches the files for text differences, and ignores similar lines. /A is useful if the input files are ASCII files but have one of the file types listed in Table 4-1. /B Considers blank lines in the comparison. If you do not specify /B in the command string, FILCOM normally ignores blank lines in the two files. /C Instructs FILCOM to ignore comments and spacing in the files. Comments are defined as text on a line following a semicolon. Spacing is defined as spaces and tabs. FILCOM normally considers comments and spaces in the comparison. This switch is useful when you compare assembly language source files (MACRO Assembler source files). /H Prints a FILCOM help text, which contains a description of the program and all switches, on your terminal. You can type /H by itself immediately after the FILCOM prompt, or in a command string. NOTE /H overrides all other switches that you may combine with it. The system ignores all other specified switches in the combination, and prints the full FILCOM help text. /nL Defines the number of lines that end a match. When FILCOM finds that number of successive lines that are the same in both input files, it prints all differences found up to the time of the match. The FILCOM output includes the first line of the match for easy reference. FILCOM normally uses the value "3" for the number of lines (the value of n). /O Instructs FILCOM to include a label and offset in the differences listing for ASCII files. There are three types of messages: [;At top of file + nL] where nL is a decimal number representing the number of lines between the top of the file and the line where the difference occurs. If a difference occurs at the top of the file, nL is not listed. [;At Label + nL] where Label is the MACRO-style label immediately preceding the difference and nL represents the decimal number of lines away from the label that the difference occurs. If the difference occurs at the label, nL is not listed. 4-4 THE FILCOM PROGRAM THE FILCOM PROGRAM [;At Label + nL following label name] for PDP-11 files, where label is the local label name in the form nn$, nL represents the decimal number of lines from the local label that the difference occurs and label name is the name of the last preceding block label. The block label name is listed as further help in locating the difference, since local label names are not always unique. If the difference occurs at the label, nL is not listed. If the difference occurs before FILCOM sees a label, the difference is listed as [;At label + nL] where label is the block label. The label name for all labels must be in the first ten characters of the line. Labels refer to file 1, not file 2. /Q Instructs FILCOM to print only the status of the comparison (either ?files are different or No differences encountered). FILCOM does not enumerate the differences between the files. It stops reading the files after it discovers the first difference. /S Ignores spaces and tabs in the comparison of two ASCII files. FILCOM normally considers spaces and tabs in the comparison. /T Instructs FILCOM to generate an output file even if no differences are found. If the /T switch is omitted and there are no differences in the files, no output file is generated. /U Compares your two input files in update mode. This means that FILCOM creates an output file, which is the second input file, with change bars in the left margin next to the lines that differ from those in the first input file. Deleted lines are indicated by a change bar on the next common line. /U is helpful when you are comparing two versions of text. To obtain a meaningful comparison, type the latest version of the file as the second input file in the command string. It is recommended that /nL be used with the /U switch. The output file in ASCII mode comparison includes a header for each input file that contains the following information: o the file number o the file spec o the date and time the input file was created. The following is an example of a header that would appear in an ASCII output file: File 1) DSK:FORLIB.TXT[4,244] created: 1052 26-JUL-1979 4-5 THE FILCOM PROGRAM THE FILCOM PROGRAM File 2) DSK:FORTEX.TXT[4,244] created: 1155 26-JUL-1979 NOTE If you use /U in the FILCOM command string (compare in update mode), this header does not appear. Each time FILCOM finds differences between two ASCII input files, it outputs a number corresponding to a page number in the first file, and the differences. At the end of the list of differences, the program prints a common line between the two files. The program then prints four asterisks, a number corresponding to the second input file, and the differences. Then FILCOM repeats the set of differences until all the differences between the two files are found. A row of 14 asterisks (*) marks the end of a difference. For example, you have two text files named FIL1.TXT and FIL2.TXT. Use the TYPE command to examine the contents of both files: ____ _____________ @TYPE FIL1.TXT this is line 1 this is line 2 this is line 3 this is line 4 this is line 5 this is line 5.5 this is line 6 this is line 7 this is line 8 this is line 9 ;this is a comment this is line 10 ____ _____________ @TYPE FIL2.TXT this is line 1 this is line 2 this is line 3 this is line 4 this is line 5.5 this is line 6 this is line 7 this is line 8 this is line 9 this is line 10 this is line 11 this is line 12 this is line 13 this is line 14, which is the end. @ Run FILCOM to compare these files and name the output file DIFFER.SCM. Type the following: 4-6 THE FILCOM PROGRAM THE FILCOM PROGRAM ___________ @FILCOM _________________________________ *DIFFER.SCM=FIL1.TXT,FIL2.TXT %files are different * The program informs you that the files are different, and then gives you the asterisk prompt for more input. To see the differences that FILCOM found between the two files, return to TOPS-20 command level (type CTRL/C) and use the TYPE command. %files are different ______ *CTRL/C ____ _______________ @TYPE DIFFER.SCM FILE 1) DSK:FIL1.TXT[4,67] created: 1212 25-Jul-1979 File 2) DSK:FIL2.TXT[4,67] created: 1616 25-Jul-1979 1)1 this is line 5 1) this is line 5.5 **** 2)1 this is line 5.5 ************** 1)1 this is line 9 ;this is a comment 1) this is line 10 **** 2)1 this is line 9 2) this is line 10 2) this is line 11 2) this is line 12 2) this is line 13 2) this is line 14, which is the end. ************** @ The output shows the differences between the two files. Line 5 was deleted, line 9 was changed, and lines 11-14 were inserted. The two blank lines in FIL2.TXT are ignored, because /B was not specified in the command string. The number "1" that appears beside 1) and 2) in the output is the page number of the file where the differences were found. Text pages are delimited by formfeeds. Now, compare FIL1.TXT and FIL2.TXT using /C in the command string. ___________ @FILCOM ________________________ *TTY:=FIL1.TXT,FIL2.TXT/C File 1) DSK:FIL1.TXT[4,67] created: 1212 25-Jul-1979 File 2) DSK:FIL2.TXT[4,67] created: 1616 25-Jul-1979 1)1 this is line 5 4-7 THE FILCOM PROGRAM THE FILCOM PROGRAM 1) this is line 5.5 **** 2)1 this is line 5.5 ************** 2)1 this is line 11 2)1 this is line 12 2)1 this is line 13 2)1 this is line 14, which is the end. %files are different * The output is different because /C causes FILCOM to ignore comments and spacing in the files. Using the same two text files, now compare them in update mode, and write the output to the device TTY: (your terminal). Because FIL2.TXT is the latest version of the two text files, type it as the second input file in the command string. The command string is: ___________ @FILCOM _____________________________ *TTY:=FIL1.TXT,FIL2.TXT/U this is line 1 this is line 2 this is line 3 this is line 4 | this is line 5.5 this is line 6 this is line 7 | | | this is line 8 | this is line 9 | this is line 10 | this is line 11 | this is line 12 | this is line 13 | this is line 14, which is the end. %files are different * As mentioned previously, in update mode comparisons, the output file is the second input file (latest version) with change bars inserted next to the differences found between the two files. The example above shows such an output file. Note that the program also types the "%files are different" status on your terminal. Following this, FILCOM gives another prompt for another command string. 4-8 THE FILCOM PROGRAM THE FILCOM PROGRAM 4.2.2 Comparing Binary Files 4.2.2 Comparing Binary Files FILCOM automatically determines that a file is binary if it has one of the file types listed in Table 4-1. Sharable and nonsharable save files represent the location of data in memory. In FILCOM, expanding the files before comparing them means to compare the data as it would appear if the files were loaded into memory. Comparing the files without expanding them means to compare each word in the files regardless of the usual meaning of the files' control words. You can list a binary file with FILCOM. To do this, simply omit the comma and the second input file spec in the command string. FILCOM contains the following switches that you use in the command string to compare binary files. Switches control what part of the binary file you see. /E Forces FILCOM to consider both input files as sharable save files regardless of the file types given. Normally, FILCOM selects its comparison according to the file types of the files. /H Prints the FILCOM help text. Refer to the description of /H in Section 4.2.1. /nL Compares a binary file starting at word "n". The number "n" is an octal number. Refer to /nU, below. /Q Instructs FILCOM to print only the status of the comparison. It does not list the actual differences, and causes FILCOM to stop reading the files after it discovers the first difference. Refer to the description of this switch in Section 4.2.1. /nU Compares a binary file up through word "n". The value "n" is an octal number as in /nL. If you combine /nU with /nL in the command string, the input files are compared only within these limits. /T Instructs FILCOM to generate an output file even if no differences are found. If the /T switch is not used, FILCOM produce no differences listing if there are no differences in the files. /W Compares two binary files that have nonstandard file types. (Standard file types are listed in Table 4-1.) The files are not expanded before FILCOM compares them. /W compares the files' internal control words in addition to data, reading the files one word at a time. 4-9 THE FILCOM PROGRAM THE FILCOM PROGRAM /X Instructs FILCOM to expand nonsharable save files before comparing them in binary mode. The program ignores control words and compares only the code in the files. All FILCOM binary switches apply when you dump a file. Expanding a file shows how it would appear in memory. Dumping a file without expanding it shows the file's internal format. The output file of a binary mode comparison contains the same header as output files for ASCII comparisons. (Refer to Section 4.2.1.) However, the comparison differs because it is done word by word. If the left halves of the two words being compared are the same, FILCOM prints the absolute difference between the two words. Otherwise, FILCOM prints the logical exclusive OR (XOR). For example, you want to compare two binary files. They are FIL3.BIN and FIL4.BIN. First you use FILCOM to dump them and examine their contents. The output is written to your terminal: ___________ @FILCOM __________________ *TTY:=FIL3.BIN 000000 201400 000000 000001 202400 000000 000002 202600 000000 000003 203400 000000 000004 203500 000000 000005 203600 000000 000006 203700 000000 000007 204400 000000 000010 204440 000000 000011 204500 000000 %files are different __________________ *TTY:=FIL4.BIN 000000 201400 000000 000001 202400 000000 000002 202600 000000 000003 203400 000000 000004 203540 000000 000005 203600 000000 000006 203700 000000 000007 204420 000000 000010 204440 000000 000011 204500 000000 %files are different * 4-10 THE FILCOM PROGRAM THE FILCOM PROGRAM Now compare the files. Note that since both file types are .BIN, the program automatically compares them in binary mode without you specifying any switches. Again, the output is written to your terminal: ___________ @FILCOM ___________________________ *TTY:=FIL3.BIN,FIL4.BIN File 1) DSK:FIL3.BIN[4,67] created: 1419 10-Sep-1979 File 2) DSK:FIL4.BIN[4,67] created: 1419 10-Sep-1979 000004 203500 000000 203540 000000 000040 000000 000007 204400 000000 204420 000000 000020 000000 %files are different * Compare the files once more, but specify a quick comparison (/Q) in the command string. This causes FILCOM to merely report the status of the comparison. If there are differences, the status message prints with a question mark, ?, instead of a percent sign, %, for error detection in batch jobs. (Refer to Section 4.4, FILCOM Messages.) The command string for this comparison is as follows: ___________ @FILCOM _____________________________ *TTY:=FIL3.BIN,FIL4.BIN/Q File 1) DSK:FIL3.BIN[4,67] created: 1419 10-Sep-1979 File 2) DSK:FIL4.BIN[4,67] created: 1419 10-Sep-1979 ?files are different * Do a third comparison of these two files, but now restrict the range with /nU and /nL: ___________ @FILCOM _________________________________ *TTY:=FIL3.BIN,FIL4.BIN/5L/6U No differences encountered In the following example, you are comparing two executable files. FILCOM automatically expands them because of the .EXE file type: 4-11 THE FILCOM PROGRAM THE FILCOM PROGRAM ___________ @FILCOM ___________________________ *TTY:=FIL1.EXE,FIL2.EXE File 1) DSK:FIL1.EXE[4,67] created: 1426 10-Sep-1979 File 2) DSK:FIL2.EXE[4,67] created: 1427 10-Sep-1979 000141 600000 000000 255000 000000 455000 000000 002112 000004 015062 000004 015063 000001 %files are different * In this last example, you compare both .EXE files without expanding them first. Any differences that exist in the files' internal directory pages appear in the output. The command string for this comparison is as follows: ___________ @FILCOM _____________________________ *TTY:=FIL1.EXE,FIL2.EXE/W File 1) DSK:FIL1.EXE[4,67] created: 1426 10-Sep-1979 File 2) DSK:FIL2.EXE[4,67] created: 1427 10-Sep-1979 000000 001776 000003 001776 000007 000004 000002 002000 000000 000000 000000 002000 000000 000003 001775 000003 000000 000002 001775 000001 000004 000000 254000 000000 000001 253777 000005 000000 000140 300000 000003 300000 000143 000006 001777 000001 000000 000002 001777 000003 000007 000000 000000 001775 000003 001775 000003 000010 000000 000000 000000 254000 254000 000011 000000 000000 000000 000140 000140 000012 000000 000000 001777 000001 001777 000001 001141 600000 000000 255000 000000 455000 000000 003112 000004 015062 000004 015063 000001 %files are different * 4.3 FILCOM SWITCHES 4.3 FILCOM SWITCHES Table 4-2 contains all the FILCOM switches in alphabetical order. It also lists the mode of comparison and description for each switch. 4-12 THE FILCOM PROGRAM THE FILCOM PROGRAM Table 4-2: FILCOM Switches Table 4-2: FILCOM Switches ______________________________________________________________________ Switch Comparison Description ______________________________________________________________________ /A ASCII Compares files in ASCII mode /B ASCII Considers blank lines in the comparison /C ASCII Ignores comments and spacing in MACRO source files /E Binary Considers both files as sharable save files /H ASCII& Prints the FILCOM help text Binary /nL ASCII& Defines the number of lines Binary that end a match in ASCII comparisons; determines the lower limit where a partial comparison begins in binary comparisons /nU Binary Determines the upper limit where a partial binary comparison stops /O ASCII Includes a label name and offset in the differences listing /Q ASCII& Prints only the status of the Binary comparison; does not enumerate the differences /S ASCII Ignores spacing and tabs in the comparison /T ASCII& Produces an output file even Binary if no differences are found /U ASCII Compares the files in update mode and inserts change bars next to the differences /W Binary Compares binary files with nonstandard file types, ignoring control words (if any) /X Binary Expands nonsharable save files before comparing them ______________________________________________________________________ 4-13 THE FILCOM PROGRAM THE FILCOM PROGRAM 4.4 FILCOM MESSAGES 4.4 FILCOM MESSAGES Some of the messages printed by FILCOM contain information that is dependent on the exact command string, switch, or file you specified. The key to these message variables follows: [device] A device name. [file] A file spec. [n] A designator for the first or second input file. [reason] The reason for a file access failure. These are listed in Table 4-3 at the end of this section. The most common FILCOM messages are listed below alphabetically. They are all fatal errors that are preceded by a question mark (?). ?Buffer capacity exceeded and no core available Description: You attempted to compare two text files with a difference so large that FILCOM cannot obtain enough memory to store the differences. Suggested User Response: Check that you are comparing two files that are reasonably similar; or, use /nL with n larger than the value 3. ?Command error Description: You typed an invalid command. You may not have typed a second file specification. You may have included an invalid line terminator or a nonalphanumeric character in a file specification. Suggested User Response: Retype the correct command syntax. ?Command error -- Unknown switch X Description: You typed an invalid switch. The invalid switch is specified by the X character in the message. Suggested User Response: Retype the correct switch and reissue the command. ?Command error -- Double filename illegal Description: You typed a double filename in your command string. Suggested User Response: Retype the correct command syntax and reissue the command. 4-14 THE FILCOM PROGRAM THE FILCOM PROGRAM ?Command error -- Double file type illegal Description: You typed a double file type in your command string. Suggested User Response: Retype the correct command syntax and reissue the command. ?Device [device] Not available Description: The device you specified is not available. In other words, someone may be using it, or there may be no such device on your system. Suggested User Response: Specify a device available to you. ?FILE [n] NOT IN CORRECT EXE FORMAT Description: The first or second input file in the command string is not a correctly formatted sharable save file (.EXE file type). You may have specified a file that is in nonsharable save file format (a result of the TOPS-20 CSAVE command, rather than the SAVE command). Suggested User Response: Do not use nonsharable save files. They are less efficient than regular sharable save files. Bring the program into memory with the TOPS-20 GET command, save it again with the SAVE command, and then reissue the commands. You can also look at the files as nonsharable save files or pure binary files. ?File [n] not in SAV format Description: Your first or second input file is not in proper nonsharable save file format. Suggested User Response: Specify the correct file or look at the files as sharable save files or pure binary files. ?File [n] read error Description: Your first or second input file contains an error. Suggested User Response: Try the operation again. If it still fails, ask the operator to check the device for errors. ?Input error for input file [n]- [file] [reason] Description: FILCOM could not access your first or second input file for the reason specified. (Refer to Table 4-3 for the exact reason.) Suggested User Response: The particular reason in Table 4-3 gives corrective action. 4-15 THE FILCOM PROGRAM THE FILCOM PROGRAM ?NOT ENOUGH CORE AVAILABLE TO HOLD DIRECTORY Description: FILCOM is attempting to compare your sharable save files, but cannot get enough memory to hold the file's internal directory. Suggested User Response: Re-create the .EXE file. If the error persists, contact your Software Specialist, or send a Software Performance Report (SPR) to DIGITAL. ? Output device error Description: FILCOM received an error while writing your file. Suggested User Response: The device may be faulty. If the problem persists, contact your operator to fix the problem. ?Output device error- [device] cannot do output Description: You specified a device that is unable to do output, such as a card reader. Suggested User Response: Specify a device that is capable of producing output. ?Output ENTER error for [file] [reason] Description: FILCOM is unable to write the file for the reason specified. Suggested User Response: Refer to Table 4-3 for corrective action that applies to the reason for the error. Table 4-3 contains the various reasons for file access errors that can appear in FILCOM messages. 4-16 THE FILCOM PROGRAM THE FILCOM PROGRAM Table 4-3: Reasons for File Access Errors Table 4-3: Reasons for File Access Errors ______________________________________________________________________ Error Reason ______________________________________________________________________ (0) File not found You specified a file that does not exist. Specify an existing file. (1) Nonexistent UFD You specified a directory that does not exist. Specify an existing directory. (2) Protection failure You do not have sufficient privileges to access the named file. Negotiate the needed privileges with the system operator or the owner of the file. (3) File being modified Another job is currently modifying the named file. Try to access the file at another time or use a different filename. (14) No room or quota exceeded You exceeded the quota of the named directory or the entire capacity of the named file structure. Delete and expunge some of your files, or specify a directory or structure with sufficient space. (15) Write-lock error You requested an output file on a write-locked device, such as a magnetic tape. Either write-enable the device and try again, or specify another device. ______________________________________________________________________ 4-17 5-1 CHAPTER 5 CHAPTER 5 THE CREF PROGRAM THE CREF PROGRAM 5.1 INTRODUCTION 5.1 INTRODUCTION The CREF program generates cross-reference listings from .CRF files. You produce .CRF files with LOAD-class commands. (Refer to the TOPS-20 Commands Reference Manual.) A cross-reference listing is one that contains your source program (from either the ALGOL or FORTRAN compilers, or the MACRO assembler) plus a list of all the symbols used and the line numbers on which they are used. As such, the CREF program is a helpful tool for debugging and modifying programs written in these languages. NOTE You do not need to run CREF for COBOL programs. The COBOL compiler automatically generates CREF listings. 5.2 RUNNING CREF 5.2 RUNNING CREF Because CREF reads only .CRF format files, you must first create these files before you run CREF. These files are created when your program is compiled. Section 5.2.1 describes how to create .CRF files. Once you create .CRF files, you can run CREF to produce cross-reference listings. Section 5.2.2 describes how to run CREF. 5.2.1 Creating .CRF Files with COMPILE 5.2.1 Creating .CRF Files with COMPILE To create a .CRF file, you must compile your program. To do this, type COMPILE after the TOPS-20 prompt @, followed by /CREF and the name of the program you want to compile; then press the RETURN key. After you press RETURN, the system compiles your program and then returns you to TOPS-20 command level. For example: 5-1 THE CREF PROGRAM THE CREF PROGRAM ____________ ___________ @COMPILE/CREF BE.MAC MACRO: BE EXIT @ Compiling a program does not automatically create a .CRF file. This is why you specify /CREF in the command string. For more information on the COMPILE command, refer to the TOPS-20 Commands Reference Manual. You can create .CRF files of two programs in the same command string. For example: ____________ _____________________ @COMPILE/CREF BE.MAC,CREFA.MAC MACRO: BE MACRO: CREFA EXIT @ Note that this one command string is equivalent to creating .CRF files of both programs separately, as in the example below: ____________ ___________ @COMPILE/CREF BE.MAC MACRO: BE EXIT ____________ ______________ @COMPILE/CREF CREFA.MAC MACRO: CREFA EXIT @ If your program has already been compiled, the above procedure will not work. You will immediately return to TOPS-20 command level after typing the command string. To create a .CRF file of an already compiled program, you must recompile the program. Type the COMPILE command followed by /COMPILE, /CREF, the program name, and press RETURN. For example: ____________________ ___________ @COMPILE/COMPILE/CREF BE.MAC MACRO: BE EXIT @ 5.2.2 Producing Cross-Reference Listings 5.2.2 Producing Cross-Reference Listings Once you create a .CRF file, you can run CREF to generate the actual 5-2 THE CREF PROGRAM THE CREF PROGRAM cross-reference listing. There are four types of tables that you can get in these listings. The four types of tables are: o Regular Symbols - This table contains user-defined symbols, labels, address tags, and assignments. o OPDEF and Macro Names - This table contains user-defined operators such as macro calls and OPDEFs. o Op Codes - This table contains hardware machine mnemonics and assembler pseudo-ops, such as MOVE and XALL. o Procedure Nesting Levels - This table contains the names of procedures and numbers of blocks, indented to show their nesting in the program. Only the ALGOL compiler generates this table in a CREF listing. You produce cross-reference listings by running CREF and giving a command string with switches to specify the type of listing you desire. The general command string format is: Destination file spec=Source file spec1/Switches,Source file spec2/Switches... where: Destination file spec is the output file that contains the cross-reference listing. If you omit the device and the filename in the Destination file spec, CREF uses the device LPT:. If you omit the device but do specify a filename, CREF uses the device DSK:. If you do not specify a filename in the Destination file spec, CREF uses the filename in Source file spec1. If you do not specify a file type in the Destination file spec, CREF uses the type .LST. If you omit the equal sign (=) in the command string, CREF uses all defaults for the Destination file spec (you only specify the Source file specs). Source file spec1,Source file spec2...are the input files. These are the .CRF files you produced from compiling your programs. If you omit the device in any of the Source file specs, CREF uses the device DSK:. If you omit a filename in any Source file spec, CREF uses the filename CREF. If you omit a file type in any Source file spec, CREF uses the file type .CRF, then .LST, .TMP, and null. If you omit a PPN or a logical name for a PPN in either the Destination file spec or any of the Source file specs, CREF assumes that you mean your connected directory. As mentioned, you can type CREF program switches in the command string after each input file spec. These switches and their functions are 5-3 THE CREF PROGRAM THE CREF PROGRAM described in Table 5-1. Table 5-1: CREF Switch Options Table 5-1: CREF Switch Options ______________________________________________________________________ Switch Function ______________________________________________________________________ /A Advances magnetic tape reel by one file. You can type this switch more than once in the command string. /B Backspaces magnetic tape reel by one file. You can type this switch more than once in the command string. /C Cancels the processing of any switches in your SWITCH.INI file. /D Restores the processing of any default switches in your SWITCH.INI file. /H Types the CREF help file. /H is illegal in a SWITCH.INI file. /K Suppresses Regular Symbol Table in the CREF listing. /M Suppresses OPDEF/Macro Table in the CREF listing. /O Includes the Op Code Table in the CREF listing. /P Preserves an input file with the file type .CRF or .LST. These types of input files are normally deleted. /R Requests the line number at which the CREF listing is to start. CREF types out "RESTART LISTING AT LINE:", after which you type the line number and press RETURN. If you use an indirect file, CREF looks for the number in the indirect file. /R is most useful for physical (non-spooled) line printers, and is illegal in a SWITCH.INI file. /S Suppresses the program listing and lists only the tables you select. /T Skips to the logical end of the magnetic tape. /W Rewinds the magnetic tape. /Z Zeros the DECtape directory. This is a historical switch, and is illegal. ______________________________________________________________________ 5-4 THE CREF PROGRAM THE CREF PROGRAM If you always want to use specific switches when you run CREF, you can put these switches in a SWITCH.INI file. Then, each time you run CREF, it automatically reads these switches from the SWITCH.INI file. You can use all CREF switches in your SWITCH.INI file except /H and /R. For more information on creating a SWITCH.INI file, refer to the TOPS-20 User's Guide. You can use an indirect file in CREF to reference a file within a command string. The indirect file can contain a complete or partial CREF command string (filenames and switches). For more information on using indirect files, refer to the TOPS-20 User's Guide. You can produce cross-reference listings by typing CREF as a command or as a program name after the TOPS-20 prompt @. To run CREF as a command, type CREF after the TOPS-20 prompt @ and press RETURN. This causes CREF to produce a cross-reference listing of any .CRF files you created in that particular terminal session. For example, if you create .CRF files for BE.MAC and CREFA.MAC and then run CREF, type the following: _________ @CREF CREF: BE CREF: CREFA @ Because you did not specify a switch, the default is for CREF to give you a cross-reference listing that contains a Regular Symbols Table and an OPDEF/Macro Table for each of the two .CRF files. If you only specify switches with this format, these switches apply to all files CREF processes. If one of your CRF files is an ALGOL program, the listing also includes the Procedure Nesting Level Table. If you create .CRF files for several programs, but want a cross-reference listing of just one file, type CREF after the TOPS-20 prompt @ followed by a CREF command string. For example, you have .CRF files for BE.MAC and CREFA.MAC, but you only want a cross-reference listing for BE.MAC. Type the following: ____ _________________________ @CREF BE.LST=BE.CRF/Switch CREF: BE @ This command string causes CREF to produce a cross-reference listing for BE.MAC that includes any tables you specify with the switch. To run CREF as a program, type R CREF after the TOPS-20 prompt @ and press RETURN. The program prompts you with an asterisk. Now type a CREF command string. For example, you create a .CRF file for BE.MAC and then run CREF as a program, specifying /O in the command string. Type the following: _ _________ @R CREF 5-5 THE CREF PROGRAM THE CREF PROGRAM ________________ *BE.LST=BE/O [CRFXKC 5K CORE] * This command string causes CREF to produce an cross-reference listing for BE.MAC that contains a Regular Symbols Table, an OPDEF/Macro Table, and the Op Code Table (/O appears in the command string). NOTE For an explanation of the program message in square brackets that appears in the last example, refer to Section 5.5, CREF Messages. You can also run other programs from CREF. To do this, type R CREF after the TOPS-20 prompt @ and press RETURN. After the asterisk prompt, type the filespec for the second program you wish to run, then type an exclamation point (!) and press RETURN. 5.3 CREF EXAMPLES 5.3 CREF EXAMPLES First, type your SWITCH.INI file to see that /O is included for CREF. Then define the logical name LPT: so that the CREF output goes to the disk, where you can type it. Without the logical name, the output is spooled to the line printer. ____ _______________ @TYPE SWITCH.INI CREF/O RUNOFF/CRETURN/MESSAGE:(NOPREFIX,FIRST) MAKLIB/MESSAGE:(NOPREFIX,FIRST) ______ ____ _________ @DEFINE LPT: DSK: @ Now, compile a MACRO assembler program and request a CREF listing. Process MACRO's listing file with CREF to get the final listing. Note that because of the /O on the CREF line in SWITCH.INI, CREF automatically includes the Opcode Table. ____________________ __________ @COMPILE/COMPILE/CREF CREFA MACRO: CREFA EXIT _________ @CREF CREF: CREFA ____ ______________ @TYPE CREFA.LST LCREFA CREF Example MACRO %53A(1152) 10:39 10-Sep-79 Page 1 CREFA MAC 11-Jul-79 11:54 Show What CREF Does 5-6 THE CREF PROGRAM THE CREF PROGRAM 1 TITLE CREFA CREF Example 2 SUBTTL Show What CREF Does 3 4 SEARCH MACSYM, MONSYM 5 SALL 6 NOSYM 7 8 000000 T0=0 9 000016 L=16 10 000017 P=17 11 12 000017 CONST=17 13 ENTRY TIMES. 14 15 000000' 201 00 0 00 000017 TIMES.: MOVX T0,CONST 16 000001' 220 00 1 16 000000 IMUL T0,@(L) 17 000002' 263 17 0 00 000000 RET 18 19 END NO ERRORS DETECTED PROGRAM BREAK IS 000003 CPU TIME USED 00:00.872 67P CORE USED ^LCONST 12# 15 L 9# 16 P 10# T0 8# 15 16 TIMES. 13 15# ..MX1 15# 15 16 ..MX2 15# 16 .PSECT 15 16 ^LMOVX 15 RET 17 ^LEND 19 ENTRY 13 IFDEF 15 IFE 15 16 IFNDEF 16 IMUL 16 MOVEI 15 NOSYM 6 PURGE 16 SALL 5 SEARCH 4 SUBTTL 2 TITLE 1 5-7 THE CREF PROGRAM THE CREF PROGRAM .IF 15 .IFN 15 .PSECT 15 16 @ Now, compile a FORTRAN program. Generate the CREF listing and type the result. ____________________ __________ @COMPILE/COMPILE/CREF CREFB FORTRAN: CREFB TIMES _________ @CREF CREF: CREFB ____ ______________ @TYPE CREFB.LST ^LTIMES CREFB.FOR FORTRAN V.5A(621) /KI/C 10-SEP-79 10:39 PAGE 1 00001 FUNCTION TIMES(ARG) 00002 00003 PARAMETER CONST = 17 00004 INTEGER TIMES, ARG 00005 00006 10 TIMES = CONST*ARG 00007 RETURN 00008 00009 END SUBPROGRAMS CALLED SCALARS AND ARRAYS [ "*" NO EXPLICIT DEFINITION - "%" NOT REFERENCED ] TIMES 1 ARG 2 TEMPORARIES ^LARG 1# 4# 6 CONST 3# 6 TIMES 1# 4# 6# 10P 6# TIMES [ NO ERRORS DETECTED ] @ Finally, compile an ALGOL program. Generate the CREF listing as before and type the result. Note the Procedure Nesting Table. 5-8 THE CREF PROGRAM THE CREF PROGRAM ____________________ __________ @COMPILE/COMPILE/CREF CREFC ALGOL: CREFC EXIT _________ @CREF CREF: CREFC ____ ______________ @TYPE CREFC.LST DECsystem 10 ALGOL-60, Version 6A(654) 10-SEP-79 10:39:35 Command string: CREFC,CREFC/C=MISC:CREFC.ALG 1 000005 B1 1 BEGIN REAL X, Y; 2 000005 2 3 000012 3 REAL PROCEDURE SQUAREROOT(X,L); 4 000012 4 5 000016 5 VALUE X; REAL X; LABEL L; 6 000016 6 7 000021 B2 7 BEGIN REAL Y, Z; 8 000025 8 IF X < 0 THEN GOTO L; 9 000027 9 Y := (1 + X)/2; 10 000043 10 IT: Z := (X/Y + Y)/2; 11 000060 11 IF ABS(Z - Y) < 1&-6 THEN GOTO OK; 12 000063 12 Y := Z; GOTO IT; 13 000074 13 OK: SQUAREROOT := Z; 14 000076 E2 14 END; 15 000076 15 16 000115 16 NG: WRITE("Number please: "); BREAK.OUTPUT; 17 000117 17 READ(X); 18 000122 18 Y := SQUAREROOT(X,NG); 19 000127 19 WRITE("The square root of "); 20 000132 20 PRINT(X); 21 000135 21 WRITE(" is "); 22 000140 22 PRINT(Y); 23 000143 23 BREAK.OUTPUT; 24 000145 E1 24 END; NO ERRORS ^LE----1 PROGRAM B----1 1 B----2 7 E----2 14 E----1 24 ^LABS 11 BREAKOUTPUT 16 23 IT 10# 12 L 3# 5# 8 5-9 THE CREF PROGRAM THE CREF PROGRAM NG 16# 18 OK 11 13# PRINT 20 22 READ 17 SQUAREROOT 3# 13 18 WRITE 16 19 21 X 1# 3# 5# 8 9 10 17 18 20 Y 1# 7# 9 10 11 12 18 22 Z 7# 10 11 12 13 @ 5.4 CREF MESSAGES 5.4 CREF MESSAGES The messages printed by CREF fall into three general categories: informational messages, warning messages, and fatal errors. Informational messages are enclosed in square brackets [ ], and merely inform you of CREF's progress in processing your file. Warning messages are preceded by a percent sign (%) and indicate that something unexpected occurred, but that CREF was able to recover. In this case, verify that your output is correct. Fatal errors are preceded by a question mark (?), and indicate an occurrence that CREF could not handle. In this case, CREF aborts its operation. You must fix the problem before reissuing your command string. The % and the ? preceding the message are easily detected in Batch jobs. Some of the messages contain variable information that is dependent on the exact command string, switch, or file you specified. These variables are as follows: [access] An octal code associated with a file access failure. For possible access failures, refer to Table 5-2 at the end of this section. [device] A device name. [file] A file spec. [memory] A memory size, such as 30K. [status] An octal code associated with a read or write error while processing a file. The meaning of this code is described in Table 5-3 at the end of this section. [switch] A switch name. The most common CREF messages are listed below alphabetically. ?CRFCDN Can't get command file device [device] 5-10 THE CREF PROGRAM THE CREF PROGRAM Description: CREF cannot access the named device in your indirect file command. Suggested User Response: Specify an existing or available device. ?CRFCEF Cannot ENTER file, [access] [file] Description: CREF could not create the specified file for the reason associated with the printed access code. (Refer to Table 5-2.) Suggested User Response: Refer to Table 5-2 for corrective action that applies to the reason for the error. ?CRFCFE Command file INPUT error, [status] [file] Description: An input error occurred reading the named command file. For the meaning of the specified status code, refer to Table 5-3. Suggested User Response: Refer to Table 5-3 for corrective action that applies to the reason for the error. ?CRFCFF Cannot find file, [access] [file] Description: CREF cannot find the specified file for the reason associated with the printed access code. (Refer to Table 5-2.) Suggested User Response: Refer to Table 5-2 for corrective action that applies to the reason for the error. ?CRFCFI Cannot find input file, [file] Description: CREF cannot find the specified file. The reason can be any of those listed in Table 5-2. Suggested User Response: Refer to Table 5-2 for corrective action that applies to the reason for the error. ?CRFCLC Can't LOOKUP command file [access] [file] Description: CREF cannot find the specified command file for the reason associated with the printed access code. (Refer to Table 5-2.) Suggested User Response: Refer to Table 5-2 for corrective action that applies to the reason for the error. ?CRFCME Command error - type /H for help Description: You typed an invalid command. 5-11 THE CREF PROGRAM THE CREF PROGRAM Suggested User Response: Retype the correct command or type /H for help. ?CRFDNA Device not available, [file] Description: You specified a device in the file specification that is not available to your job. It may be in use by another job. Suggested User Response: Specify a device that is available to your job. ?CRFIBP Input buffer size phase error - 0 [file] Description: The size of the buffer area set up by the system is larger than the size expected by CREF. Suggested User Response: This is an internal error, and not expected to happen. If it does, contact your Software Specialist or send a Software Performance Report (SPR) to DIGITAL. %CRFIDC Improper input data at line [decimal], continuing Description: CREF detected incorrect data in your input file. This is most likely a problem with the compiler that generated the CREF input file. Suggested User Response: First, be sure that you are processing a valid CREF input file. If so, this is an internal error, and not expected to happen. Try to re-create the .CRF file, since the data in the original one may have been corrupted. If the problem persists, contact your Software Specialist or send a Software Performance Report (SPR) to DIGITAL. ?CRFIMA Insufficient memory available Description: Your input file is too large for CREF to handle. Suggested User Response: Divide your program into smaller files and try again. ?CRFINE INPUT error, [status] [file] Description: An input error occurred reading the named file. For the meaning of the specified status code, refer to Table 5-3. Suggested User Response: Refer to Table 5-3 for corrective action that applies to the reason for the error. ?CRFOUE OUTPUT error, [status] [file] Description: An output error occurred writing the named file. For the meaning of the specified status code, refer to Table 5-3. 5-12 THE CREF PROGRAM THE CREF PROGRAM Suggested User Response: Refer to Table 5-3 for corrective action that applies to the reason for the error. %CRFPUE Please use "=" rather than "_" Description: Older versions of CREF allowed only the use of an underbar ("_") to separate the input files from the output file. CREF currently allows either "=" or "_", but it is preferable for you to use "=". CREF acts as if you typed "=". Suggested User Response: Use "=" in the future. %CRFRLL Restart listing at line: Description: You specified /R to continue a listing. CREF is requesting the line number of the line to resume printing. Suggested User Response: Type the desired line number. %CRFSIH "/H" or "/R" switch illegal in SWITCH.INI defaulting Description: You specified /H or /R illegally in the CREF line in your SWITCH.INI file. CREF ignores these switches. Suggested User Response: Remove /H or /R from your SWITCH.INI file. %CRFSII Syntax error in SWITCH.INI defaults Description: The CREF commands in your SWITCH.INI file are invalid. CREF ignores them. Suggested User Response: Correct the invalid switches in your SWITCH.INI file. ?CRFSIO I/O error while reading SWITCH.INI Description: An input error occurred reading SWITCH.INI switch defaults. The reason for the failure can be any of those listed in Table 5-3. Suggested User Response: Refer to Table 5-3 for corrective action that applies to the reason for the error. ?CRFUKS Unknown switch "[switch]" {in DSK:SWITCH.INI} Description: You specified a nonexistent switch. Suggested User Response: Respecify the command string with a valid switch, or fix your SWITCH.INI file. [CRFXKC [memory] [core] 5-13 THE CREF PROGRAM THE CREF PROGRAM Description: CREF finished its processing, and is informing you how much memory it used to process your CREF file. The octal codes listed in Table 5-2 appear in various CREF error messages, wherever [access] is used. The explanation beside each octal code describes the reason for the failure. Appropriate corrective action for each failure follows the explanation. Table 5-2: Reasons for File Access Errors Table 5-2: Reasons for File Access Errors ______________________________________________________________________ Octal Code Explanation/Action ______________________________________________________________________ 0 File not found. The named file was not found by CREF. Specify an existing file. 1 You specified a directory that does not exist. Specify an existing directory. 2 Protection failure. You do not have sufficient privileges to access the named file. Negotiate the needed privileges with the system operator or the owner of the file. 3 File being modified. Another job is currently modifying the named file. Try to access the file at another time or use a different filename. 14 No room or quota exceeded. You exceeded the quota of the named directory, or the entire capacity of the file structure. Delete and expunge some of your files, or specify a directory or structure with sufficient space. 15 Write-lock error. You requested an output file on a write-locked device, such as a magnetic tape. Either write-enable the device and try again, or specify another device. ______________________________________________________________________ The status code in various CREF error messages is an octal number that is best interpreted as bits. For example, if a CREF message prints the status code 40001, this means that you have exceeded your disk quota. The status code printed by CREF is the logical "OR" of all 5-14 THE CREF PROGRAM THE CREF PROGRAM applicable bit values. Table 5-3 contains these status codes, their meanings, and the corresponding remedial action. Table 5-3: Error Status Codes Table 5-3: Error Status Codes ______________________________________________________________________ Status Code Meaning/Action ______________________________________________________________________ 400000 The device is write-locked. Either specify a write-enabled device or ask the system operator to write-enable your device. 200000 A hardware error occurred. The hardware is in error and should be fixed if the problem persists. 100000 A parity error occurred. The data on the device is incorrect. Correct the data and try again. 40000 Quota exceeded or structure full. You either exceeded your directory's quota or the entire capacity of the structure. Delete and expunge some files or specify a structure or directory with sufficient space. ______________________________________________________________________ NOTE All other bit values (such as 20000 or 10) are simply status bits and do not indicate an error. Only those listed above indicate an error. Any other code simply indicates the status. 5.5 TECHNICAL NOTES 5.5 TECHNICAL NOTES The information in this section is primarily for users who write their own compilers (such as MACRO, ALGOL, or FORTRAN) and users who create .CRF files. It describes the .CRF input file format and the various control characters that you use. The control characters in Tables 5-4 and 5-5 appear in the CREF input file produced by MACRO, FORTRAN and ALGOL. At the beginning of each line of the listing, CREF input data is enclosed by DELETE B and 5-15 THE CREF PROGRAM THE CREF PROGRAM DELETE C. The symbol or instruction types and the number of their component characters are defined by control characters. The set of control characters defining symbols and instructions is the same as the set defining the number of symbol or instruction characters. A control character's position determines its function. For example, in the input CREF data B^C^CENDc, the B indicates the beginning of the data. The first CTRL/C (^C) defines the instruction END as a pseudo-op code. The second CTRL/C (^C) defines the number of characters in the instruction END as 3, and the C terminates the CREF data. Symbols referenced in a block-structured language such as ALGOL should assign a unique number to each symbol name. This ensures that symbols with the same name but defined in different blocks have different numbers. Then, the number for each symbol should be referenced in CREF data rather than the name. After the last use of a symbol (usually at the end of its block), use CTRL/I to associate the symbol's name with the unique number assigned to it. Control characters that require two symbols (such as CTRL/I) should have two adjacent length character and symbol name pairs. The control characters that begin and end the CREF input data are described in Table 5-4: Beginning and Ending Control Characters Table 5-4: Beginning and Ending Control Characters ______________________________________________________________________ Character ASCII Codes Meaning ______________________________________________________________________ A 177, 101 Terminates the CREF data on (prints as A) (Octal) each line and adds a horizontal tab to the line of the listing. B 177, 102 Signals beginning of the CREF (prints as B) data on each line. C 177, 103 Terminates the CREF data on (prints as C) each line. A line number is incremented and printed. This is the line number referenced in the CREF tables. D 177, 104 Identical to DELETE A, except (prints as D) that DELETE D does not increment or print line numbers. 5-16 THE CREF PROGRAM THE CREF PROGRAM E 177, 105 Causes CREF to print its (prints as E) tables immediately, and reinitializes the tables for another program. FORTRAN uses this function between subroutines. F 177, 106 Identical to DELETE C, except (prints as F) that DELETE F does not increment or print line numbers. ______________________________________________________________________ Table 5-5 contains the control characters that define symbols, instruction types, and macros. Except for CTRL/B and CTRL/G, each of these characters precedes the symbol name being referenced. Table 5-5: Symbol-Definition Control Characters Table 5-5: Symbol-Definition Control Characters ______________________________________________________________________ Character ASCII Code Meaning ______________________________________________________________________ CTRL/A (^A) 001 Declares a reference to a user-defined symbol (such as a regular MACRO symbol or a FORTRAN variable). CTRL/B (^B) 002 Declares a defining occurrence of a user-defined symbol. This character immediately follows the symbol name. CTRL/C (^C) 003 Declares a reference to a MACRO pseudo-op or a hardware-defined op code. CTRL/D (^D) 004 Declares a defining occurrence of a MACRO pseudo-op or a hardware-defined op code. CTRL/E (^E) 005 Declares a reference to a MACRO or OPDEF. CTRL/F (^F) 006 Declares a defining occurrence of a MACRO or OPDEF. CTRL/G (^G) 007 Causes CREF to delete the last symbol that it read. 5-17 THE CREF PROGRAM THE CREF PROGRAM CTRL/H (^H) 010 Combines two symbols that are defined at different block levels and are then found to be the same. The second symbol specified becomes the name for both. For example, in a one-pass block-struc