RSTS/E Guide to Writing Command Procedures
Total Page:16
File Type:pdf, Size:1020Kb
E ide to Writing Command Procedures No. AA-CF03A-TC RSTS/E Guide to Writing Command Procedures Order No. AA-CF03A-TC June 1985 This manual presents concepts and techniques for developing command pro cedures using the RSTS/E DIGITAL Command language (DCl). OPERATING SYSTEM AND VERSION: RSTS/E V9.0 SOFTWARE VERSION: RSTS/E V9.0 digital equipment corporation, maynard, massachusetts 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 be used or copied only 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 © 1985 by Digital Equipment Corporation. All rights reserved. The postage-paid READER'S COMMENTS form on the last page of this docu ment requests your critical evaluation to assist us in preparing future documenta tion. The following are trademarks of Digital Equipment Corporation: DIBOL ReGIS ~D~DDmD ™ FMS-11 RSTS DEC LA RSX DECmail MASSBUS RT DECmate PDP UNIBUS DECnet P/OS VAX DECtape Professional VMS DEC US Q-BUS VT DECwriter Rainbow Work Processor CONTENTS PREFACE CHAPTER 1 Introduction What are Command Procedures? . · . 1 - 1 Creating Command Procedures ..... · . 1 - 2 Formatting Command Procedures . · . 1 - 3 Executing Command Procedures . • • • 1 - 4 Executing Command Procedures at Login • 1 - 4 Executing Command Procedures at Interactive Level ..................... 1-5 Executing Command Procedures in Batch Mode ... 1-7 Executing Nested Command Procedures . .. 1-8 Executing Command Procedures with the RUN Command . 1 - 8 Chaining to Command Procedures from a Program . 1-8 Executing Command Procedures with CCLs . .. 1-9 Command Procedures and System Management ..... 1-9 CHAPTER 2 using Symbols in Command Procedures Symbols in DCL . · . 2 - 1 Symbol Names . 2-2 Symbol Values · . • .2- 3 Symbol Types . • • . • • •• .2- 4 Symbol Assignment · . .. ... 2 - 4 String Assignment . • • • . • • . .2- 5 Symbol Tables · . 2 - 6 Symbol Substitution · . 2 - 8 Command Synonyms . · . 2 - 8 Apostrophes in Symbol Substitution • • • • • • 2 - 9 Automatic Evaluation . · . 2 - 10 Undefined Symbols . 2-11 Verifying Symbol Substitution · . 2 - 11 Displaying Symbols ... 2-12 Deleting Symbols . 2-14 CHAPTER 3 Expressions and Operators Operands in Expressions . .. 3-1 Strings . .. ... .... 3-2 Integers . .. ... 3 - 3 DCL Functions . .. ........ 3-3 Symbols . .. ...... ...... 3 - 4 Value Type Conversion in Expressions.. .. 3-4 iii Converting Strings to Integers . • 3-6 Converting Integers to Strings . • 3-6 Operators in Expressions . • 3-7 Arithmetic Operations ...... · 3-9 Logical Operations . · 3-9 Arithmetic Comparisons . 3-10 String Comparisons . 3-10 String Concatenation . 3-11 CHAPTER 4 DCL Functions in Command Procedures Format of DCL Functions . · 4-1 DCL Functions . .. .. • 4 - 2 F $ACCES S . ....... ...... • 4 - 5 F$ASCII ........ .. • 4 - 6 F $ CHR . .. ...... • 4-7 F$CVTIME . .. .. · 4-9 F$EDIT ..... ... 4-10 F$ INSTR . 4-12 F$INTEGER . 4-14 F$JOB . .. ... 4-15 F$LEFT . .. ... ..... 4-16 F$LENGTH . 4-17 F$MESSAGE . 4-18 F$MID . 4-19 F$NODE .... 4-20 F$PARSE . .. .... ... 4-21 F$PRIVILEGE . .. .. 4-30 F$RIGHT . .. .. 4-34 F$SEARCH . 4-35 F$STRING ............... 4-37 F$TERMINAL .............. 4-38 F$TIME . 4-39 F$TYPE .. ............. 4-40 F$USER ..... ..... 4-41 F $VERI FY .... ... ...... 4-42 CHAPTER 5 Interacting with Command Files pa~sing Data . .. .... • 5 - 1 Passing Parameters . • • • 5 - 2 Prompting for Symbol Values . • 5 - 4 Returning Data ......... · 5-7 Displaying Data . .. .. · 5-8 Supplying Data to a Program . · 5-8 Reading Data in a Program . · 5-8 Supplying Data to a Program from a Terminal 5-10 Signaling the End of a Data List . 5-12 Exiting from a Program in a Command File . 5-12 Detaching Programs in a Command Procedure 5-13 iv Passing Symbol Values to a Program. 5-14 CHAPTER 6 File Input and Output Opening Files • 6 - 2 Reading Files • 6 - 5 Writing Files • 6-8 Closing Files 6-11 CHAPTER 7 Controlling Execution Flow in Command Procedures The IF Command. .. ......... 7-1 Command Line Labels . ... 7-3 The GO TO Command . .. .. 7-4 Nesting Command Procedures . ... 7-6 Exiting from a Command Procedure ......... 7-8 The EXIT Command. 7-8 The STOP Command. .. ... 7-10 CHAPTER 8 Controlling Error Conditions and CTRL/C Interrupts Error Condition Handling. ... 8-1 $STATUS and $SEVERITY Symbols ......... 8-1 The ON Command. .. ...... 8-4 Enabling and Disabling Error ~hecking ... 8-6 CTRL/C Interrupt Handling . • . 8-7 Setting a CTRL/C Action Routine .. .. .. 8-8 Disabling and Reenabling CT~L/C Interruptions . 8-9 CHAPTER 9 Controlling Terminal Output SET [NO]ECHO Command . 9 - 1 SET [NO]VERIFY Command • • . • • . • .9- 3 'Creating a Log File of a Terminal Session .... 9-3 OPEN/LOG_FILE . •. .... 9 - 4 CLOSE/LOG_FILE . 9 - 6 SET LOG FILE . • • . .9- 6 APPENDIX A Sample Command Procedures APPENDIX B RSTS/E and VAX/VMS Command Processor Differences v APPENDIX C RSTS/E Error Messages APPENDIX D ASCII Character Codes INDEX FIGURES 1-1 Executing a Command Procedure at Interactive Level 1-6 7-1 Command Levels in Nested Command Procedures ... 7-7 TABLES 3-1 Rules for Determining Expression Types . 3-5 3-2 Summary of Operators in Expressions • • . • • 3 - 8 4-1 Summary of DCL Functions . • • 4 - 3 4-2 Summary of F$EDIT Functions . • 4 - 11 4-3 Status Word Values . • • • 4 - 23 4-4 Flag Word Values . 4 - 25 4-5 Summary of Privileges . 4 - 30 8-1 Severity Values ... • • • • •• 8 - 2 8-2 ON Command Keywords and Actions · • . • • •• 8 - 5 C-l RSTS/E Error Messages . · . • • . C -1 D-l ASCII Character Codes . • • • • • • • • • D - 1 vi Preface Objectives This guide presents concepts and techniques for developing command procedures using the DIGITAL Command Language (DCL) on RSTS/E. Various examples, including complete command procedures, demonstrate applications of the concepts and techniques that this guide discusses. Audience All RSTS/E users can benefit from using command procedures. For example, you can place frequently used command sequences into a command procedure and thereby save keystrokes; you can also write sophisticated command sequences that pass parameters, test status values, process files, and perform similar program-like tasks. Although you do not have to be a computer expert to use this guide, you will have an easier time if you are familiar with programming concepts such as loops, logical values, and so forth. Document structure Each chapter in this guide builds on material from earlier chapters. If command procedures are new to you, study this guide chapter by chapter beginning with Chapter 1. If you already have some knowledge of command procedures, you may want to skim the Table of Contents and Index for the specific topics you need. This manual contains nine chapters and four appendixes: Chapter 1 Defines command procedures and describes how to develop them. Chapter 2 Describes how to define and manipulate symbols. Chapter 3 Describes the use of expressions and operators. Chapter 4 Shows how to use the DCL functions to obtain information about the status of a process and to manipulate character strings. Chapter 5 Describes how to control input to and output from command procedures. Chapter 6 Explains how to manipulate files using command procedures. vii Chapter 7 Describes how to control the sequence in which command procedure lines are executed. Chapter 8 Shows how to set up error handling routines based on the severity of errors encountered during command procedure execution and how to handle CTRL/C interrupts that occur during command procedure execution. Chapter 9 Describes commands for displaying command procedure output. Appendix A Contains sample command procedures that illustrate the techniques described in Chapters 1 through 9. Appendix B Lists some of the major differences between the RSTS/E and VAX/VMS command processors. Appendix C Lists the numeric values associated with RSTS/E error messages. Appendix D Lists the ASCII character codes. Related Documents This guide refers you to the following manuals for more detailed information: o RSTS/E System User's Guide o RSTS/E System Manager's Guide. viii Conventions This manual uses the following symbols and conventions: [ ] Square brackets show the optional parts of a command in format statements. For example: DIRECTORY [file-spec[, ... ]] The square brackets in this example indicate that you can include a file specification ([file-spec]), or more than one ([, ... ]), if you choose. Square brackets also indicate the choice you have in using a command. For example: /[NO]DELETE This means you can type either /DELETE or /NODELETE, depending on the form of the qualifier you select. Do not confuse the square brackets in command formats with the square brackets in project-Programmer numbers (PPNs), as in [52,20]. <CTRL/x> The control key, which you use,in combination with another key. For example, enter CTRL/U by holding down the CTRL key and pressing the keyboard key labeled "U." RSTS/E displays, or echoes, CTRL/U at your terminal, as ... U. <RET> The key labeled RETURN on your terminal. You press the RETURN key to complete lines and commands that the system will process. color In examples, black characters are data produced by the computer. Red characters indicate information that you type. ix Chapter 1 Introduction This chapter introduces command procedures and tells you how to develop them. What are Command Procedures? Command procedures are files that contain DCL commands. To execute these commands, you run the procedure. Use command procedures to execute sequences of commands you use during interactive terminal sessions or to execute commands you submit for batch processing.