The Hacker's Encyclopedia 1998

home *** CD-ROM | disk | FTP | other *** search

/ The Hacker's Encyclopedia 1998 / hackers_encyclopedia.iso / zines / phrack2 / phrack35.007 < prev next >

Wrap

Text File | 2003-06-11 | 53.5 KB | 1,314 lines

==Phrack Inc.== Volume Three, Issue Thirty-five, File 7 of 13 <:=--=:><:=--=:><:=--=:><:=--=:>\|/<:=--=:><:=--=:><:=--=:><:=--=:> <:=--=:> <:=--=:> <:=--=:> >>>>>=-* Users Guide to VAX/VMS *-=<<<<< <:=--=:> <:=--=:> <:=--=:> <:=--=:> Part I of III <:=--=:> <:=--=:> <:=--=:> <:=--=:> Part A: Basic Information <:=--=:> <:=--=:> Part B: Programming the VAX/VMS <:=--=:> <:=--=:> <:=--=:> <:=--=:> By: Black Kat <:=--=:> <:=--=:> <:=--=:> <:=--=:><:=--=:><:=--=:><:=--=:>/|\<:=--=:><:=--=:><:=--=:><:=--=:> Index ~~~~ Part A contains information on the following topics: o Background o Logical Names o Terminal Control Keys o System Default Logical Names o Logging in o Logical Name Tables o Digital Command Language (DCL) o User Environment o Error Messages o Terminal Characteristics o Command Line Editing o File Security o Files and Directories o EDT Text Editor o File Operations o EDT Help manual Part B contains information on the following topics: o Programming VAX/VMS o Parameters o DCL Expressions o Terminal I/O o Command Procedures o File I/O o Writing Command Procedures o Redirecting Command Procedure I/O o Comments o Branching and Conditionals o Labels o Loops o Debugging o Subroutines o Invoking Command Procedures o Error Handling o Symbols o Termination o Lexical Functions o Example Command Procedures <:=- Part A : Basic Information -=:> Introduction ~~~~~~~~~~~ VAX is an acronym for Virtual Address eXtension, a 32-bit computer developed by Digital in the 1970's. The VAX architecture supports multiprogramming, where many users running different programs can use the VAX simultaneously and each appears to have full control of the computer's resources. The multiprocessing VAX functions vary differently from the old timesharing systems, which would allocate a slice of CPU time to each user of the system in a rotating fashion, whether the time slice was required or not. The VAX/VMS environment, however, provides each user an allocation of processor time based on the user's needs and priority. If a user does not need his quantum of time, or a portion of it, it is given to the next user. This scheduling method is very efficient when compared to the old method of timesharing. The VAX is capable of addressing more than four billion addresses, through a method known as virtual memory addressing. Because the memory is virtual however, there is no need to have four billion bytes of physical memory. The VAX executes programs by a technique known as paging, whereby a single "page" of the program is read into memory at a time, and when a new page is needed, the old one is "swapped" back out to disk to make room for the new one. The VMS operating system ties everything together. The user interacts with VMS (Virtual Memory System) through a Command Language Interpreter (CLI), usually the Digital Command Language (DCL). When you use VAX/VMS, you are known to the system as a process, which is created when you log in to the system and deleted when you log out. This process carries with it various attributes to identify you from other system users (process name, identification, user identification code, privileges, etc). Terminal Control Keys ~~~~~~~~~~~~~~~~~~~ Ctrl-A Allows you to insert, rather than overstrike, characters on a DCL command line that you're editing. Ctrl-B Displays DCL commands that you've previously entered. Ctrl-C Interrupts the coessed or the program being executed. Ctrl-E Positions the cursor at the end of the line. Ctrl-H Positions the cursor at the beginning of the line. Ctrl-I Tab Ctrl-O Alternately suppresses and continues the display of the output terminal. Ctrl-Q Enables (toggles on) output to the display after CTRL-S. Ctrl-R Retypes the current input line and repositions the cursor atthe end of the retyped line. Ctrl-S Disables (toggles off) output to the display until CTRL-Q is pressed. Ctrl-T Displays process statistics. Ctrl-U Discards the current input line and performs carriage return. Ctrl-W Refreshes the screen. Ctrl-X Flushes the type-ahead buffer. Ctrl-Y Interrupts command or program execution and returns control to the DCL command line interpreter. Ctrl-Z Indicates end of file for data entered from terminal. Logging in ~~~~~~~~ Most VAX systems prompt you with something like this: Welcome to VAX1 Username: Type your username and press <enter>. You'll then be prompted for your password. If you enter the correct username/password combination, you'll be given something like the following: Welcome to VAX/VMS V4.4 Last interactive login on Monday, 16-JUL-87 16:12 Last non-interactive login on Friday, 13-JUL-87 00:14 $ If you entered an incorrect username and password, you'll receive the message: User authorization failure Just hit <enter> and you'll be prompted for your username again. Once you're logged in, you'll be given the DCL prompt ($). This indicates that the system is ready to accept interactive commands. To log out, use the command: $ LOGOUT The Digital Command Language (DCL) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DCL is comprised of more than 200 commands called verbs. Each DCL verb acts on a parameter or assumed parameter, and the action of these verbs and the scope of their parameters can be modified with qualifiers. The basic command structure is: $ LABEL: COMMAND-NAME PARAMETER(S) /QUALIFIER(S) !COMMENT | | | | | | | | | +-- Optional Comment | | | | | | | +-------------- Command modifier(s) | | | | | +---------------------------- Object of the Command | | | +-------------------------------------- DCL command verb | +-------------------------------------------------- Optional Label A label is an optional, user-specified string with a maximum length of 255 characters. It is most commonly used in command procedures. A DCL command verb defines the action the VAX will take when the command line is interpreted. Parameter(s) specify the object or a list of objects the DCL command verb will act upon. Multiple parameters may be specified but must be separated from one another by a space, multiple spaces, or a tab. If you enter a DCL command that requires parameters, but you don't enter them on the command line, the DCL interpreter will prompt you for them automatically. Qualifiers further define or modify the function the DCL command will perform. They consist of a keyword followed by a value or a list of values. The qualifier keyword must be preceded by a slash (/). Multiple qualifiers may be specified, but each must be preceded with a slash. Qualifiers usually aren't required. There are three kinds of qualifiers: parameter, positional, and command. A command qualifier applies to the whole command. Generally, these are placed at the end of the command. For example: $ DIRECTORY [BYNON],[BYNON.DECPRO]/FULL This displays a full listing of two directories, using the /FULL qualifier of the DIRECTORY command. A positional qualifier takes on a different meaning based on where it is located in the command. If a positional qualifier is placed after the command verb, but before the first parameter, the qualifier will affect the entire command. If the same positional qualifier is placed after a parameter, only that parameter will be affected. For example: $ PRINT/COPIES=3 MEMO1.TXT,MEMO2.TXT $ PRINT MEMO1.TXT/COPIES=2,MEMO2.TXT The first command prints three copies of each file. The second command prints two copies of the first file, but only one copy of the second. A parameter qualifier affects only the parameter it follows. In the following example, MEMO1.TXT is sent to the queue LASER and MEMO2.TXT is sent to queue FAST_PRINT: $ PRINT MEMO1.TXT/QUEUE=LASER,MEMO2.TXT/QUEUE=FAST_PRINT A comment is an optional, user-specified comment about the command. It is commonly used in command procedures to document the command. Error Messages ~~~~~~~~~~~~ Generally, error messages are of the format: % FACILIT-L-IDENT, TEXT | | | | | | | | | +-- explanation of the error message | | | | | | | +--------- abbreviated message text, for reference | | | | | +------------- error severity | | | +------------------- Vax/VMS facility or component (error source) | +----------------------- message number: "%" = first, "-" = subsequent A percent sign (%) indicates the first error message for a given command. All subsequent errors for that command are preceded with a hyphen (-). The facility indicates the source of the error. The source may be the DCL command line interpreter, one of the various VMS utilities, or a program image. The severity level indicator (L) will have one of the following values: S (successful completion), I (information), W (warning), E (error), or F (fatal or severe error). The ident is an abbreviation of the error message text. It can be referenced in the VAX/VMS System Messages manual. The text provides an explanation of the error message. Command line editing ~~~~~~~~~~~~~~~~~~ DCL stores the last 20 command lines entered. You can display a list of them with: $ RECALL /ALL The resulting display might look like: 1 DIR 2 COPY VAX1::$1$DUA5:[BYNON]LOGIN.COM LOGIN.COM;1 3 EDIT LOGIN.COM $ To recall a specific command from the recall buffer, use the DCL RECALL command with a command line number as a parameter. For example: $ RECALL 2 $ COPY VAX1::$1$6DUA5:[BYNON]LOGIN.COM LOGIN.COM;1 Files and Directories ~~~~~~~~~~~~~~~~~~~~ Files are organized much like MS-DOS, with a directory-tree structure. The user's default directory (assigned by the system administrator) is the "root" directory. Up to seven subdirectories may be created, each containing as many subdirectories as you like. The complete file specification looks like: VAX1 :: DUA0 : [BYNON.PROGRAMMING.FORTRAN]WINDOWS.FOR;3 | | | | | | | | | | | | node device directory filename | version type The node name identifies a computer system in a network. If no node name is specified, VMS assumes the file is located on the local node where you're logged in. The device name is the physical device where the file is stored. It is a four-character alphanumeric code which identifies the device type, hardware controller to which it is attached, and the unit number of the device on the controller. If you omit the device name from a file specification, VMS assumes you are referring to your default device. The directory entry is enclosed in brackets, and is the name of the directory that contains the file. If you omit the directory name from a file specification, VMS will assume you are referring to your default directory. The filename may consist of up to 39 alphanumeric characters. The file type is a code consisting of up to 39 alphanumeric characters, and it generally indicates the type of information supplied in the file. Some system programs and utilities supply a three character default file type. The version number is a 1 to 5 digit number the system assigns to every file by default. When a file is created, it is assigned a version number of 1. Each time the file is edited or another version of it is created, the version number is automatically incremented by 1. Alternatively, you may specify a version number of your choice. No blank spaces are allowed within any portion of a file specification. In VMS Version 4.x, the maximum lengths are as follows: node name up to 6 characters device name four characters directory name up to 39 characters subdirectory name up to 39 characters file name up to 39 characters file type up to 39 characters version number up to 5 decimal digits with a value between 1 and 32,767 File specifications must be unique; no two files can have completely identical specifications. It's conceivable to have many copies of NOTES.TXT in a subdirectory, but only one NOTES.TXT;8 may exist in the same subdirectory. Wildcards are similar to those in MS-DOS, with an asterisk (*) representing a filename or filetype, and a percent sign (%) indicating a single character. File operations ~~~~~~~~~~~~~~ Creating and modifying files: $ CREATE TEMP.DAT TEMP 1 TEMP 2 <CTRL-Z> Renaming files: $ RENAME TEMP.DAT NEW.DAT $ RENAME TEMP.DAT [BYNON.PROG]TEMP.DAT Note: you cannot rename files across devices, just directories. Copying files: $ COPY TEMP.DAT NEW.DAT $ COPY TEMP.DAT,TEST.DAT NEW.DAT Appending files: $ APPEND TEMP.DAT NEW.DAT Deleting files: $ DELETE TEMP.DAT;1 $ DELETE *.DAT;* $ DELETE /CONFIRM .DAT;* (confirm each file) Displaying files: $ TYPE /PAGE TEMP.DATE (one page at a time) Directories: $ DIRECTORY $ DIRECTORY DJA1:[BYNON.PROG] Printing files: $ PRINT TEMP.DAT Purging files: $ PURGE *.DAT (erase all but latest version of .DAT files) Create a dir: $ CREATE/DIRECTORY [.BUDGET] Set default dir: $ SET DEFAULT [BYNON.PROG] $ SET DEFAULT [.PROG] Delete a dir: $ SET DEFAULT [BYNON.PROG] $ DELETE *.*;* $ SET DEFAULT [BYNON] $ SET PROTECTION=(0:D) PROG.DIR;1 $ DELETE BUDGET.DIR;1 Logical Names ~~~~~~~~~~~~ A logical name is a substitute for a file specification, portion of a file specification, or another logical name. They provide two primary functions: file and device independence and file specification shorthand. File and device independence means that you are not constrained by a physical element, such as a disk or printer name. If you use files nested deeply in subdirectories, with long names, or on devices or nodes other than your default, you can define a meaningful logical name to represent it. These shorthand names are faster to type and easier to remember. To define a logical name: $ DEFINE PARTS_DBF DJA2:[DATABASES]PARTS.DAT This example will associate the logical name PARTS_DBF with the file specification DJA2 : [DATABASES]PARTS.DAT. Now, PARTS_DBF may be used anywhere as a substitute for the complete file specification. Other commands also can be used to assign logical names. Assign : Associates equivalence names with a logical name Mount : Mounts a disk or tape volume and assigns a system logical for the volume. Allocate: Allocates a system device for private use and optionally (command qualifier) assigns a logical name to the device. Open : Opens a file for read or write operations and assigns a logical name to the file specification. To display the logical name translations: $ SHOW LOGICAL PARTS_DBF will display: "PARTS_DBF" = "DJA2:[DATABASES]PARTS.DAT" (LNM$PROCESS_TABLE). To deassign a logical name: $ DEASSIGN PARTS_DBF System default logical names ~~~~~~~~~~~~~~~~~~~~~~~~~~~ SYS$COMMAND The initial file, or input stream, from which the DCL command line interpreter reads input data. The logical name SYS$COMMAND is equated to your terminal for interactive processes. SYS$DISK Your default disk as assigned in the UAF. SYS$ERROR The device on which the system displays all error and informational messages. By default, SYS$ERROR is assigned to your terminal for interactive processes, and to the batch job log file for any batch processes. SYS$INPUT The default file or input stream from which data and commands are read by either the DCL command line interpreter or programs executing in your account. By default, SYS$INPUT is equated to your terminal for interactive processes and to the batch job stream (or command procedure) for batch processes. Logical Name Tables ~~~~~~~~~~~~~~~~~ Logical names are stored in system files called logical name tables. The following are the four most commonly used: Group table : Contains the logical names available to all users in your UIC (User Identification Code) group. Job table : Contains the logical names available to your process and any subprocess it creates. Process table: Contains the logical names available to your process only. System table : Contains the logical names that may be used by all users of the system. User Environment ~~~~~~~~~~~~~~ The User Authorization File (UAF) is a system file controlled and modified by the system manager. A record for each system user is contained in the UAF. A User Identification Code (UIC) is an identifier used by VAX/VMS to identify users and groups of users. It is used to identify processes, directories, files, and other objects in the system. A UIC may be specified numerically or alphanumerically, and is made up of two parts, a group and a member, specified in the format: [group,member]. For example, UIC [10,14] identifies group 10, user 14. The group number is an octal number in the range 1-37776, and the member is an octal number in the range 0-177776. An alphanumeric UIC contains a member name and optionally, a group name in the format: [member] or [group,member]. The group and member names in an alphanumeric UIC may contain 1 to 31 alphanumeric characters (A-Z, 0-9, underscore, dollar sign). Each user of the system is limited in the consumption of system resources, and these limits control the rate at which your process or any subprocesses you create may consume a resource. There are 32 levels of priority in the VAX/VMS system, 0 through 31, the highest being 31. The priorities are divided into two ranges: timesharing (0-15) and real-time (16-31). The default user priority is 4. Depending on how heavily the system is being used, your priority may be raised above the default, but never lowered below it. VAX/VMS maintains 35 privileges, divided into the following seven categories classified by how much damage could be done to the system by possessing them: None No privileges. Normal The minimum privilege needed to use the system effectively. Group The ability to effect members of the same UIC group. Devour The potential to consume noncritical system-wide resources. System The ability to interfere with normal system operation. File The potential to bypass file protection security. All The ability to take over the entire system. VAX/VMS systems keep a record of overall computer system use by account holder in a system file called ACCOUNTING.DAT. The system manager uses this file to produce reports with the Accounting Utility. This can be used to learn more about how the system is being used, how it performs, and how a particular user is using the system. It can also be used to bill users for system time. Terminal Characteristics ~~~~~~~~~~~~~~~~~~~~~~ Setting display width: $ SET TERMINAL/WIDTH=132 Shutting messages off: $ SET TERMINAL/NOBROADCAST This prevents other users from phoning you, sending mail messages, and some system messages from appearing on your screen. If you just want mail and phone messages screened, use: $ SET BROADCAST=(NOMAIL,NOPHONE). Increasing type-ahead buffer: $ SET TERMINAL/ALTYPEHD/PERMANENT Line editing modes: $ SET TERMINAL/INSERT or $ SET TERMINAL/OVERSTRIKE Defining keys: $ DEFINE/KEY PF1 "SET DEFAULT DUA3:[INV.SUP]" % DCL-I-DEFKEY, DEFAULT key PF1 has been defined Showing keys: $ SHOW KEY PF1 (or $ SHOW KEY ALL) DEFAULT keypad definitions: PF1 = "SET DEFAULT DUA3:[INV.SUP]" Deleting keys: $ DELETE/KEY PF1 (or $ DELETE/KEY ALL) % DCL-I-DELKEY, DEFAULT key PF1 has been deleted Changing prompt: $ SET PROMPT = "What now?" Displaying process information: $ SHOW PROCESS (add a qualifier) Changing process information: $ SET PROCESS/NAME="Bob" $ SET PROCESS/PRIVILEGES=OPER File Security ~~~~~~~~~~~~ UIC-based protection permits access to be granted or denied based on protection codes that reflect four user categories: System: system manager Owner : account owner Group : users in same UIC group World : all users of system, regardless of UIC Four type of file access can be granted or denied to members of these user categories: Read (R): read the file Write (W): create or modify the file Execute (E): run a program Delete (D): delete the file Generally, any category of user can be granted or denied file access with this protection scheme. However, you can read a file in a subdirectory with EXECUTE access if you know its filename and filetype. Also, since SYSTEM privileges include the ability to bypass all file protection, anyone within the SYSTEM category can read a file. CONTROL access, or the ability to change the protection and ownership of a volume, is never specified in the UIC-based protection code. This is the fifth type of protection that can be specified in an access control list (ACL). It's automatically granted to two user categories when VMS examines UIC-based protection. Users in the SYSTEM and OWNER categories receive CONTROL access by default while GROUP and WORLD categories are denied CONTROL access. File protection defaults are as follows: System: RWED Owner : RWED Group : RE World : No access To determine the existing or default protection of a file, use the SHOW PROTECTION command. The default in the previous example would be: $ SHOW PROTECTION SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD=NO ACCESS If you want to see file protection in directories, use the /PROTECTION qualifier with the DIRECTORY command. To change the protection of a file, use the command: $ SET PROTECTION=(O:RWE,G,W) LOGIN.COM In this example, the account owner has READ, WRITE, and EXECUTE access to his LOGIN.COM file. The GROUP and WORLD categories have no access and SYSTEM access remains unchanged. Rules for specifying protection codes: 1. Access types must be abbreviated with one letter: R, W, E, or D. 2. User categories may be spelled out or abbreviated. 3. Each user category must be separated from its access types with a colon. 4. If you specify multiple user categories, separate each with a comma and enclose the entire code in parenthesis. 5. User categories and access types may be specified in any order. 6. If you include a user category, but do not specify an access type for that category, access is automatically denied. 7. If you omit a user category entirely, protection for that category is unchanged. Remember that VAX/VMS evaluates directory protection before file protection. If you grant WORLD:R access to a file, but the file is in a directory without WORLD:R access, another user couldn't read the file. EDT Text Editor ~~~~~~~~~~~~~~ When you enter EDT, you automatically enter line mode, indicated by the EDT prompt, an asterisk (*). All line mode commands are made at the asterisk prompt and terminated by pressing <Return>. Lines that you input are numbered sequentially by the editor. You can reference a line or group of li^S^Qnes based on the line number or range of line numbers. A list of basic EDT commands follows. Each command may be abbreviated to the characters in parenthesis. Complete information on all EDT line mode commands can be found through the use of the line mode EDT HELP command. Commands Function ~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Change (C) Change from line to keypad mode. To switch back from keypad mode to line mode, press <Ctrl-Z>. Copy (CO) Copy a line or group of lines from one place to another. If you enter the command CO 5 to 10, line 5 will be copied to the line immediately preceding line 10. The command CO 5:10 to 20 would copy the contents of lines 5 through 10 into the area immediately preceding line 20. Delete (D) Delete a line or group of lines. The command D13 would delete line 13, while D13:20 will delete lines 13 to 20. Exit (EX) Terminates the EDT session, saving all changes. This also creates a new version of the file being edited. Help (H) Display on-line help on all EDT line mode commands. The help messages will not be included in the file being edited. Include (INC) Copy text from an external file into the file being edited. When the EDT command INCLUDE FILENAME.TYPE is executed, the contents of FILENAME.TYPE are copied into the file being edited. Insert (I) Inserts specified text directly before the current position in the file. While inserting text, you will not receive the EDT "*" prompt. Press <Ctrl-Z> to return to the "*" prompt when you're finished inserting. Move (M) You can't cut and paste with a line-oriented editor. Text will be moved to the area immediately preceding a specified line. The command M 10:15 to 50 would move lines 10 through 15 to the area immediately preceding line 50. Quit (QUI) Exit the EDT editor without saving changes. Replace (R) Deletes a specified line or group of lines and enters the INSERT mode so you can add text in that place. The command R5:10 would delete lines 5 through 10 and switch to the INSERT mode to permit you to enter new text. To exit the INSERT mode, press <Ctrl-Z>. Resequence (RES) Numbers all of the lines in the file that you're editing in increments of 1. This is useful because text insertion, movement, or deletion causes the file to lose numeric sequence. Substitute (S) Substitute a new text element for an old one in the format s/oldtext/newtext/range. The old and new text elements must be enclosed in angle bracket (< >) delimiters and the range must be specified. Write (WR) Write a given range of text to a new file. WRHISTORY.TXT 50:100 would write lines 50 through 100 to a new file called HISTORY.TXT. EDT Help Manual ~~~~~~~~~~~~~ To dump the entire EDT Help file to disk, enter the following DCL command during a terminal session: $ ASSIGN EDTHELP.FIL SYS$OUTPUT. Now, enter line mode EDT and type: * HELP *. Now exit EDT and enter the DCL command: $ ASSIGN TTnn: SYS$OUTPUTT (TTnn: is your terminal number). <:=- Part B : Programming VAX/VMS -=:> Introduction ~~~~~~~~~~~ A symbol is a name chosen to represent a string of characters, a numeric value, or a logical (true/false) value. A symbol may be used wherever the value it represents would normally be found, and can be up to 255 characters long. Symbols must begin with a character, dollar sign, or underscore, and are not case-sensitive. Symbols are created like this: symbol_name = value (local symbol) symbol_name == value (global symbol) A global symbol may be used at any command level, but local symbols are lost when command procedures are finished. For example: $ WIDE = "SET TERMINAL/WIDTH=132" Now, anytime you type WIDE at the DCL command line, the terminal width will be changed to 132 characters. To show the contents of a symbol: $ SHOW SYMBOL ANSWER ANSWER = 1584 HEX = 00000630 OCTAL = 000000003060 The SHOW SYMBOL command uses the local symbol table by default. To show the value of a global symbol, use the /GLOBAL qualifier. To show all symbols, use the /ALL qualifier (or /GLOBAL/ALL). To delete symbols, use: $ DELETE/SYMBOL symbol_name command (with /GLOBAL if it's global). When a DCL command is executed, symbols in the following positions are automatically translated: o the beginning of the command o in a lexical function o in a WRITE or IF statement o on the right side of an = or == assignment statement o inside brackets on the left side of an assignment statement when you're preforming string substitution If none of these cases fits, apostrophes will force the translation: $ DIRECTORY 'PARTS' (after $ PARTS = "DJA2:[DBA]PARTS.DAT") Symbols are commonly used for shorthand. For example, to clear the screen: $ ESC[0,8] == 27 $ CLEAR == "[J" $ HOME == "[H" $ CLR == WRITE SYS$OUTPUT ESC,HOME,ESC,CLEAR Now, anytime you enter CLR, the screen will be cleared. Symbols can also be used to execute command procedures: $ NETBACK == "@SYS$LOGIN:NETBACKUP" Finally, foreign commands unknown to DCL can be executed by using symbols: $ KERMIT == RUN SYS$$SYSTEM:KERMIT DCL Expressions ~~~~~~~~~~~~~~ Expressions are built by combining data elements with operators. A logical comparison evaluates the relationship between two components as true or false (True = 1, False = 0). Lexical functions are VAX/VMS routines that return process or system information, or manipulate user-supplied data. Lexical functions are unique because the result is returned in the function name, allowing it to be used as a symbol (much like Pascal). Lexical functions are called with the following format: F$function_name(parameter, parameter...) For example, the following lexical function manipulates user-supplied data: $ STRING = "Go home right now!" $ STRING = F$EDIT(STRING, "COMPRESS, UPCASE") $ SHOW SYMBOL STRING STRING = "GO HOME RIGHT NOW!" Command Procedures ~~~~~~~~~~~~~~~~~ A command procedure is a file consisting of a sequence of DCL commands which can be executed interactively or as a batch job (like a .BAT file in MS-DOS or a REXX EXEC in VM/SP). Command procedures are used in VAX/VMS to perform repetitive or complex tasks and to save time. With a command procedure, you can execute many DCL commands with a single statement. Command procedures aren't bound by simple lists of DCL commands executed in sequence. They can take advantage of labels, lexical functions, symbols and relational operators to build sophisticated procedures which act like VAX/VMS programs. Command procedures are flexible. They can be written to take specific actions based on responses to questions, or even to perform a given function depending on the time or date. Writing Command Procedures ~~~~~~~~~~~~~~~~~~~~~~~ A text editor such as EDT or EVE is used to create and edit command procedures, which should be named "PROCEDURE_NAME.COM". The file type ".COM" is the default procedure file type, and if a different file type is included, it must be included when the procedure is invoked. Each new command line must begin with a dollar sign ($). Multiple spaces or tabs may be included after the "$" for readability, and command lines may be extended past a single line by ending the previous line with a hyphen (-) and not starting the next line with a dollar sign. Data input to programs, such as responses, must be entered without the dollar sign. Data lines are used by the program running and are not processed by the DCL command line interpreter. For example: $ MAIL <--- invokes the Mail Utility SEND <--- Mail SEND command JONES, BOB <--- response to Mail prompt "To:" Memo <--- response to Mail prompt "Subj:" Bob, <--- Mail message How's it going?'? Joe $ <--- terminates Mail program $ EXIT <--- terminates command procedure Comments ~~~~~ Comments may be included by preceding them with an exclamation point (!), which causes everything to the right of it to be ignored by the DCL command interpreter. Comments make command procedures easier to debug and modify later. Spelling DCL commands out rather than using the abbreviations also makes the command procedure more readable. Labels ~~~ Labels are used by the DCL command line interpreter for conditional processing and repetitive looping. Labels should be placed on separate lines, making them easier to find. Labels can be 255 characters long, may not contain blanks, and must be terminated with a colon (:). Debugging ~~~~~~ The SET VERIFY command tells DCL to display each command as it processes it. This allows you to see where errors are generated, and how strings are translated. SET NOVERIFY turns the verify mode off. The SHOW SYMBOL command displays the contents of defined symbols, and is used to show the contents of a symbol in a command procedure as it is being executed. Invoking Command Procedures ~~~~~~~~~~~~~~~~~~~~~~~~~~ Command procedures may be invoked interactively by typing the "at" sign (@) followed by the procedure name. The file type must also be included if it is not ".COM" (the default). Command procedures may be invoked at the command line or from within another command procedure, called nesting. The DCL SUBMIT command will place your command (job) in a batch queue with other jobs waiting to be run. Command procedures are generally submitted as batch jobs when you want them to execute at a specific time, they will take a long time to run, or when a job must run at a reduced priority. The following command submits the command procedure ACCOUNT.COM to the VAX/VMS batch processor: $ SUBMIT ACCOUNT Job ACCOUNT (queue SYS$BATCH, entry 103) started on SYS$BATCH The SYS$BATCH queue is the default and is used unless otherwise specified with the /QUEUE qualifier. When VAX/VMS runs this job, a process with your rights and privileges will be created and the procedure executed within that process. Symbols ~~~~~~ Symbols may be local (single equal sign) or global (double equal sign). Local symbols are recognized by DCL only at the command level at which it was defined and more deeply nested levels (subsequently called command procedures). Global symbols are recognized at any command level. Local symbols should be used when the symbols is only needed for the duration of the command procedure employing it. You should only define global symbols if you're going to use them in other command procedures or for the duration of your login session. An asterisk can be used to tell the command line interpreter (CLI) to accept abbreviations. For example: $ NO*TES == "@SYS$LOGIN:NOTES" This tells the CLI to accept NO, NOT, NOTE, or NOTES as a valid abbreviation for the NOTES command. This notation is usevul for long symbol names. Lexical Functions ~~~~~~~~~~~~~~~~ Lexical functions allow you to obtain basically the same information as DCL SHOW commands. However, it's easier to manipulate information which comes from a lexical function. As an example, the following two command give the same information: $ SHOW TIME ! DCL SHOW TIME command 12-JUN-1989 14:29:23 $ WRITE SYS$OUTPUT F$TIME() ! lexical function 12-JUN-1989 14:29:25.17 The second command is more usable, however: $! Show_Date.COM $! $ TIME&DATE = F$TIME() $ DATE = F$EXTRACT(0,11,TIME&DATE) $ WRITE SYS$OUTPUT DATE This procedure displays only the date portion of the string returned by the lexical function F$TIME(). (Use @SHOW_DATE to invoke it) VAX/VMS supports lexical functions to manipulate text strings, convert data types, and return information about the system, your process, symbols, files and devices. Parameters ~~~~~~~~~ Eight reserved symbols (P1 through P8) are available to command procedures to supply data to process. By using these parameters in a command procedure, different data can be specified each time it's run. Parameter specification is done on the command line where the procedure is called. Unless designed to, the command procedure will not prompt for parameters. Parameters are separated with spaces and may be character strings, integers, or symbols. If you want to skip a parameter, us a null string (" "). $! Add.Com $! command procedure to demonstrate passing parameters $! (add the first and third parameter) $! $ WRITE SYS$OUTPUT P1+P3 $ @ADD 12 " " 14 26 If a command procedure requires multiple letters or words as a single parameter, enclose it in quotes and it will be treated as one parameter and not converted to uppercase. Terminal Output ~~~~~~~~~~~~ The WRITE and TYPE commands send data to the terminal. TYPE is used to display the contents of a file, but may also be used to print lines of text from within a command procedure. TYPE may only be used to output text strings. Since the WRITE command is processed be DCL, expressions, symbols and lexical functions are evaluated before the data is sent to the terminal. The output expression must translate to a string and be sent to the logical device SYS$OUTPUT, but may be a string, lexical function, symbol, or any combination of the three. Here's an example of a command procedure that uses terminal output: $! Writing a simple text string $! $ WRITE SYS$OUTPUT "This is a test..." $! $! Displaying multiple lines at the terminal $! $ TYPE SYS$OUTPUT Warning! It's been 30 days since you changed your password. Change it now! $! $! Writing a string with a lexical function $! $ WRITE SYS$OUTPUT " "HI' You are in directory "F$DIRECTORY()' " Terminal Input ~~~~~~~~~~~ The INQUIRE command's default device is the terminal keyboard, while the READ command must be told where to accept data from. The INQUIRE command prompts for input, reads data and assigns it to a symbol. All data is accepted as a character string and is converted to uppercase and compressed (extra blanks removed). The READ command prompts for input if the /PROMPT qualifier is used, accepts data from a specified source and assigns it to a symbol. The data is accepted with no string conversion or compression occurring. Here's an example of a command procedure that uses terminal input: $! Puts whatever you type in the symbol NAME $! the /NOPUNCTUATION qualifier will suppress the colon $! and space INQUIRE puts at the end of the prompt $! $ INQUIRE /NOPUNCTUATION NAME "What is your name? " $! $! Example of READ using SYS$INPUT (terminal) for data $! $ READ /PROMPT = "First value: " SYS$INPUT VALUE_1 $ READ /PROMPT = "Second value: " SYS$INPUT VALUE_2 $ WRITE SYS$OUTPUT VALUE_1," + ",VALUE_2," = ",VALUE_1+VALUE_2 File I/O ~~~~~~~ The basic steps to read and write files from within command procedures are similar to most other languages. Use the OPEN command to open the file. If it does not exist, OPEN will create it. Use the READ or WRITE commands to read or write text records from the file. Use the CLOSE command to close the file when you're done. To open a file for writing, you must use the /APPEND or /WRITE qualifier. The /WRITE qualifier creates a new file and places the record pointer at the beginning of the file. If the file already exists, a new version will be created by OPEN/WRITE. The /APPEND qualifier is used to add records to the end of an existing file. The file must already exist before using the OPEN/APPEND command, and when the file is opened, the record pointer is placed at the end of the file. To open a file for reading, use the /READ qualifier (the default for the OPEN command). A file opened for reading may not be written to, and the record pointer will initially be placed at the first record in the file. Each time a record is read, the pointer is moved down to the next record. The WRITE/UPDATE must be used to write over an existing record. Here's an example of a command procedure using file input and output: $ OPEN/APPEND OUTPUT_FILE NEW.DAT $ OPEN/READ INPUT_FILE OLD.DAT $ READ INPUT_FILE RECORD $ WRITE SYS$OUTPUT "First record from OLD.DAT - ",RECORD $ WRITE OUTPUT_FILE "First record from OLD.DAT - ",RECORD To open a file for both reading and writing, use both the /READ and /WRITE qualifiers. The record pointer will be placed at the first record in the file. Using this method, however, you can only overwrite the record you most recently read, and records you replace must be the same length. Redirecting Command Procedure I/O ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Command procedures often invoke VAX/VMS utilities, and these programs will normally get input from the logical device SYS$INPUT. While executing a command procedure, SYS$INPUT is directed to the command procedure itself, and this is why you can put command and data lines for a utility or program directly in the procedure. SYS$COMMAND defaults to the terminal from where a command procedure is being executed, and by redirecting SYS$INPUT to SYS$COMMAND you can use utilities and other programs interactively from command procedures: $ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND: $ EDIT JUNK.DAT The /USER_MODE qualifier causes the re-assignment to be in effect only for the next command. Normally command procedure output is displayed at your terminal. You may redirect output to a file by using the /OUTPUT qualifier: $ @SHOW_TIME/OUTPUT = TIME.DAT By default, DCL error and severe error messages are directed to the file represented by the logical name SYS$ERROR, which usually points to your terminal. If you want to log error messages, simply redirect SYS$ERROR to a file. If you redirect SYS$ERROR without also redirecting SYS$OUTPUT, DCL will send error messages to both, and you'll receive the error messages twice -- at your terminal and in the file. To completely suppress error messages you can redirect both SYS$ERROR and SYS$OUTPUT to the null device (NL:) or you can use the SET MESSAGE command to turn off all message output. To suppress all messages, use: SET MESSAGE/NOTEXT/NOIDENTIFICATION/NOFACILITY/NOSEVERITY. Branching and Conditionals ~~~~~~~~~~~~~~~~~~~~~~~~~ You can use the DCL IF/THEN statements and conditional operators withing command procedures to cause the execution of a command based on the evaluation of a condition. The basic use is: $ IF condition THEN command. The condition is a Boolean expression (True or False) and the command is any legal DCL command. The following is a list of conditional operators: Operator Function ~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .EQ. / .EQS. Determines if two numbers/character strings are equal .GE. / .GES. Tests to see whether the first number/character string is greater than or equal to the second .GT. / .GTS. Determines if the first number/character string is greater than the second .LE. / .LES. Tests to see if the first number/character string is less than or equal to the second .LT. / .LTS. Determines if the first number/character string is less than the second .NE. / .NES. Tests to see whether the two numbers/character strings are not equal .AND. Combines two numbers with a logical AND (boolean algebra) .OR. Combines two numbers with a logical OR (boolean algebra) .NOT. Logically negates a value The following is a command procedure using conditional branching: $! Time.Com $! $ TIME = F$TIME() $ HOUR = F$EXTRACT(12,2,TIME) $ IF HOUR .LT. 12 THEN GOTO MORNING $ IF HOUR .LT. 17 THEN GOTO AFTERNOON $ IF HOUR .LT. 18 THEN GOTO EVENING $ GOTO END $ MORNING: $ WRITE SYS$OUTPUT "Good morning!" $ AFTERNOON: $ WRITE SYS$OUTPUT "Good afternoon!" $ EVENING: $ WRITE SYS$OUTPUT "Good evening!" $ END: $ EXIT Loops ~~ Loops are used to repeat a statement or group of statements until a given condition is met. DCL supports both DO WHILE and DO UNTIL loops. The DO WHILE loop tests the condition before evaluation: $ LOOP: $ IF .NOT. condition THEN GOTO END . . . $ GOTO LOOP $ END: $ EXIT The DO UNTIL loop executes the statement(s) and then tests the condition: $ LOOP: . . . $ IF condition THEN GOTO LOOP $ EXIT Subroutines ~~~~~~~~ The DCL command GOSUB transfers execution control to a label and the RETURN command terminates subroutine execution, returning control to the statement after the GOSUB command. Subroutines are useful where you need to do the same series of commands repeatedly in different parts of a command procedure. They also make procedures easier to read and more compact. The DCL commands GOSUB and RETURN are not supported in VAX/VMS versions before VAX/VMS Version 4.4. The following is an example procedure using a subroutine: $! Personal.Com $! $! opens the personal info file $! $ OPEN/WRITE OUTPUT_FILE PERINFO.DAT $! $! collect info $! $ INQUIRE RECORD "Enter full name" $ GOSUB WRITE_FILE $ INQUIRE RECORD "Enter address" $ GOSUB WRITE_FILE $ INQUIRE RECORD "Enter phone number" $ GOSUB WRITE_FILE $ CLOSE OUTPUT_FILE $ EXIT $! $! subroutine WRITE_FILE $! $ WRITE_FILE: $ WRITE OUTPUT_FILE RECORD $ RETURN Error Handling ~~~~~~~~~~~~~ The command interpreter will execute an EXIT command if a severe error occurs, terminating the procedure and returning control to the previous command level, unless the DCL ON command is used to specify an action for the command interpreter to take. The ON command supports the three keywords WARNING, ERROR, and SEVERE_ERROR. To override error handling for procedure warnings, for example, use something like this: $ ON WARNING THEN EXIT or $ ON WARNING THEN GOTO label WARNING causes the command procedure to take action if a warning, error, or severe error occurs. ERROR causes the action if an error or severe error occurs, and SEVERE_ERROR causes the action only if a fatal error occurs. $STATUS and $SEVERITY are reserved DCL global symbols, and each time a command is executed, values are assigned to these symbols. $STATUS holds the full condition code of the last statement and $SEVERITY holds an error severity level. The condition code in $STATUS is valid to the VAX/VMS MESSAGE facility and can be used in conjunction with F$MESSAGE to obtain the actual text message associated with the code: $ SET DEFAULT DUB1:[BYNON] $ WRITE SYS$OUTPUT $STATUS $X00000001 $ WRITE SYS$OUTPUT F$MESSAGE(%X00000001) % SYSTEM-S-NORMAL, normal successful completion All DCL commands will return a condition code, but not all condition codes have text messages. Condition codes without text messages will return the message "%NONAME-E-NOMSG Message number (8-digit code)". The message text isn't very useful for making conditional decisions though, so $SEVERITY is used. It contains one of five possible values extracted from the first three bits of $STATUS. Here are the codes: Code Definition ~~~ ~~~~~~~~~~ 0 Warning 1 Success 2 Error 3 Information 4 Severe Error Odd values (1,3) indicate success while even values (0,2,4) indicate failure. There are basically two ways to use the status and severity codes to handle errors. The first is to treat $STATUS as a Boolean value: $ SET NOON $ command ! a DCL command $ IF $STATUS THEN GOTO NO_ERR ! test $STATUS for T or F . . ! handle the error . $ NO_ERR ! continue processing . . . $ EXIT The second method is to trap the error with the ON WARNING command, then use the severity level to determine an appropriate course of action: $ SET NOON $ ON WARNING GOTO ERR_TRAP $ command ! a DCL command $ command ! a DCL command . . . $ EXIT $! $! error trap code $! $ ERR_TRAP: $ SEVERITY = $SEVERITY ! save the error code $ IF SEVERITY = 0 THEN command ! if warning... $ GOTO DONE $ IF SEVERITY = 2 THEN command ! if error... $ GOTO DONE $ IF SEVERITY = 4 THEN command ! if severe error... $ DONE: . . . $ EXIT Error checking can be completely disabled with the SET NOON command. When this is in effect, the command interpreter continues updating the condition code, but does not perform any error checking. The DCL command SET ON restors error checking to normal. For example: $ SET NOON ! turn off error checking $ command ! a DCL command $ SET ON ! restor error checking Termination ~~~~~~~~~~ The EXIT command will terminate the current command procedure and return control to the command level that called it while the STOP command terminates all command procedures (if nested) and returns control to DCL. Example Command Procedures ~~~~~~~~~~~~~~~~~~~~~~~~~ The following are two example command procedures to demonstrate some of the previously discussed techniques. Login.Com ~~~~~~~~ $! Login.Com - executed each time you log in $! $! Check for a network or batch login $! $ IF F$MODE() .EQS. "NETWORK" THEN GOTO NETWORK $ IF F$MODE() .EQS. "BATCH" THEN GOTO BATCH $! $! Define process permanent symbols for convenience $! $ SD == "SET DEFAULT" $ SH == "SET HOST" $ WI*DE == "SET TERMINAL/WIDTH=132" $ NA*RROW == "SET TERMINAL/WIDTH=80" $ DIR*ECTORY == "DIRECTORY/SIZE" $ PU*RGE == "PURGE/LOG/KEEP=2" ! keep latest 2 version $ HO*ME == "SET DEFAULT SYS$LOGIN:" $ WHO == "SHOW USERS" $ EVE == "EDIT/TPU" $ EDT == "EDIT/EDT/COMMAND=SYS$LOGIN:EDTINI.EDT" $ BR*OWSE == "TYPE/PAGE" $! $! Define special keys $! $ DEFINE/KEY/NOLOG/TERM PF1 "DIR" ! term ends with <enter> $ DEFINE/KEY/NOLOG PF2 "EDIT" $ DEFINE/KEY/NOLOG/TERM/NOECHO PF3 "LOGOUT" $ DEFINE/KEY/NOLOG/TERM/NOECHO HELP "SHOW KEY/ALL" $! $! Modify terminal characteristics $! $ SET TERMINAL/INSERT ! insert mode $ SET PROMPT = "[BYNON]> " $! $! Show time and quit $! $ SHOW TIME $ EXIT $! $! If it's a network login, we can now $! perform some other commands if desired. $! Just quit for now though. $! $ NETWORK: $ EXIT $! $! If it's a batch job login, set verification on and quit. $! $ BATCH: $ SET VERIFY $ EXIT Subdir.Com ~~~~~~~~~ $! Subdir.Com - how to search and parse character strings $! $ WRITE SYS$OUTPUT F$DIRECTORY()+ " Subdirectories:" $ WRITE SYS$OUTPUT " " $! $! Search for subdirectory names and display them on the terminal $! $ DIR$LOOP: $ FILE = F$SEARCH("*.DIR") $! $! If DCL returns a null string (" ") we're done $! $ IF FILE .EQS. " "THEN GOTO END$DIR$LOOP $! $! Find the position of the period $! $ DOT = F$LOCATE(".",FILE) $! $! Find the position of the right bracket $! $ BRACKET = F$LOCATE("]",FILE) $! $! Extract the string between the dot and bracket $! $ FILE = F$EXTRACT(BRACKET+1,DOT-BRACKET-1,FILE) $! $! Display the subdirectory name and start over $! $ WRITE SYS$OUTPUT " ' 'FILE' " $ GOTO DIR$LOOP $ END$DIR$LOOP: $ EXIT <END PART I> ______________________________________________________________________________