1 DCL_CHECK The DCL_CHECK procedure detects a variety of DCL coding errors and displays diagnostic messages that allow you to correct the problems. See "Diagnostics" for a list of the types of errors that DCL_CHECK can detect. See "Problems" for information on the limits of DCL_CHECK. When you execute DCL_CHECK with "HELP" as the first parameter, DCL_CHECK invokes the DCL Help utility. If you provide additional parameters, they are passed to the Help utility. To exit the Help utility, press Return one or more times until the prompt "enter name of file:" is displayed. Additional information available: DCL_CHECK Diagnostics Examples Format Installation Line_counts Modifications Output Problems Version 1 Version This is version B2.1 of the DCL_CHECK help file. 1 Format DCL_CHECK is a DCL command procedure. It is executed by the following DCL command: $ @[:][]DCL_CHECK.COM [ []] $ @[:][]DCL_CHECK.COM HELP [...] and/or may be omitted; the current defaults will be used. The file DCL_CHECK.HLB must be in the same directory as DCL_CHECK.COM if you use the HELP function in DCL_CHECK. The files may be in any directory to which you have read access. If you use DCL_CHECK frequently, you may wish to assign a symbol in your LOGIN.COM file to execute DCL_CHECK. For example, if the DCL_CHECK.COM and .HLB files are in you login default directory, you might put the following in your LOGIN.COM: $ DCL_CHECK :== "@SYS$LOGIN:DCL_CHECK" Alternativevly, if you put DCL_CHECK.COM and DCL_CHECK.HLB in SYS$SYSTEM, you might put the following in your SYS$SYLOGIN (which is normally SYS$MANAGER:SYLOGIN.COM): $ DCL_CHECK :== "@SYS$SYSTEM:DCL_CHECK" 2 Parameters Parameters may be entered on the command line; if there are no parameters on the command line, the procedure will display the prompt for parameters. The first parameter is either the file-name of a command procedure file to be checked, or one of the keywords "HELP" or "EXIT". If a file name is entered, it will be checked. If a device and directory are not supplied, the current default is used. If a file extension is not supplied, ".COM" is used. If a file name is entered, the second parameter may provide the name of a listing file to contain the list of errors detected. If a device and directory are not supplied, the current default is used. If a file extension is not supplied, ".LIS" is used. If second parameter is not supplied, errors are listed on sys$output. If the first parameter contains "HELP", the DCL Help utility is used to provide information about the DCL_CHECK utility. Any additional parameters are passed to the HELP utility. If the first parameter contains "EXIT", any additional parameters are ignored and the procedure exits. 1 Output If the second parameter (see HELP FORMAT PARAMETERS) is blank, all output of DCL_CHECK is displayed on the terminal. If the second parameter is a listing file name, some output is displayed on the terminal and diagnostic information is written to the listing file. 2 Terminal_output Terminal output depends on whether or not there is a listing file. 3 Listing_file If there is a listing file, output similar to the following is displayed: -*- Charlie Hammond's unsupported DCL checker (Version 1.0) -*- Checking file ; Starting Pass 1 -- ... ...processing line number xxx... ... Starting Pass 2 -- ... ...processing line number xxx... ... Starting Pass 3 -- ... Creating errors listing in ; For Pass 1, the numbers in the "processing line number xxx" displays will be in increments of 500. Occasionally they will not be exact multiples of 500. For Pass 2, the numbers in the "processing line number xxx" displays will be in approximate increments of 1000. Because pass 2 is processing an abbreviated file (comment lines removed) the line numbers will seldom be exact multiples of 1000. If no errors are found, the last two lines will be replaced to indicate this: No errors found ...listing file not created 3 No_listing_file If there is no listing file, output similar to the following is displayed: -*- Charlie Hammond's unsupported DCL checker (Version 1.0) -*- Checking file ; Starting Pass 1 -- ... ...processing line number xxx... ... Starting Pass 2 -- ... ...processing line number xxx... ... Starting Pass 3 -- ... Procedure contains: nnnn total lines nnnn code lines (including nn lines w/ comments) nnn continuation lines nn lines w/i $DECK/$EOD pairs nnn comment only lines nnn blank lines LINE CODE --DIAGNOSTIC MESSAGE-- . . . -*- END OF LISTING -*- 13-OCT-1997 10:57:28.07 For Pass 1, the numbers in the "processing line number xxx" displays will be in increments of 500. Occasionally they will not be exact multiples of 500. For Pass 2, the numbers in the "processing line number xxx" displays will be in approximate increments of 1000. Because pass 2 is processing an abbreviated file (comment lines removed) the line numbers will seldom be exact multiples of 1000. 2 File_output If a listing file is being used, it contains information similar to the following. -*- Charlie Hammond's unsupported DCL checker (Version R1.0 -*-) Checking file WORK8:[HAMMOND]DCL_CHECK.COM_SOURCE; Procedure contains: nnnn total lines nnnn code lines (including nn lines w/ comments) nnn continuation lines nn lines w/i $DECK/$EOD pairs nnn comment only lines nnn blank lines LINE CODE --DIAGNOSTIC MESSAGE-- . . . -*- END OF LISTING -*- 1 Line_counts DCL_CHECK displays (or lists to a file) the following line counts. Procedure contains: nnnn total lines nnnn code lines nn of the code lines include comments nnn continuation lines nn deck lines nnn comment lines nnn blank lines There is an explanation for each of these. 2 total_lines Total lines is a count of every physical line in the file being checked. It is the same as the number of records in the file. 2 code_lines Code lines is a count of lines of code. It does not include continuation lines, lines within a $DECK/$EOD pair, comment lines or blank lines. Immediately following the count of code lines is a count of the number of code lines that also include comments. Note that this is included in the count of code lines. 2 continuation_lines Continuation lines is a count of the number of lines of code that are continued from a code line. A continued code line ends with a hyphen (-) that is not a comment (i.e., not preceeded by an "!"); lines following continued line are continuation lines. Continuation lines may be continued. i.e. a code line may be continued on two or more continuation lines. 2 deck_lines Deck lines is a count of lines that are within a $DECK/$EOD pair. These lines are input to programs or utilities. They may be commands or text used by the program or utility. 2 comment_lines Comment lines are lines that are not within $DECK/$EOD pairs which Contain only comments. i.e. the first non-blank following the dollar sign ($) is an exclamation point (!). Comments may also appear on code lines following DCL commands; these comments are not counted. 2 blank_lines Blank lines are lines which are totally blank (which also generate diagnostic messages) or which contain only a blank comment. (Blank comments are often used to insert white space to improve readability.) 1 Problems DCL_CHECK does not and cannot catch all DCL problems. Not all syntax errors are detected. Miss-spelled commands and variable names are not detected. Logic errors cannot be detected. Errors that result from execution time symbol substitution cannot be detected. See help on diagnostics LND additional_information for information on problems detecting lines that do not start with "$". In addition, the detection of one problem may obscure one or more other problems -- or may cause problems to be erroneously detected. For this reason, you should always re-run DCL_CHECK after correcting errors. 2 Single_quote DCL_CHECK is imperfect in its checking for use of single-qoute characters. For this reason it list such errors as "probable" or "possible". Uses of a single-quote (') as an apostrophe within a quoted string, for possessives ("The car's exhaust.") will be detected as possible errors. It is also possible that some syntactically invalid lines may be missed. (Lines containing an even number of errors may "cancel out". If one single quote is used to start symbol substitution within a quoted string (instead of two single quotes) DCL_CHECK will flag this as an error, and will also flag the single quote used to end the symbol substitution. Although this may seem like a single error, DCL_CHECK sees it as two possible single quote errors. 3 Contractions DCL_CHECK removes the following contractions before checking for single-quotes. Note that this is case sensative -- only lower case versions of these contractions are removed. Upper case and capitalized or other mixed case version of these contractions will not be removed. (Exception: The personal pronoun I" is upper case.) aren't he'll she's we've can't he's shouldn't weren't couldn't I'd that's what's didn't I'll they'd who's doesn't I'm they'll won't don't I've they're wouldn't hadn't isn't wasn't you'd hasn't it's we'd you'll haven't she'd we'll you're he'd she'll we're you've 2 Angle_brackets DCL_CHECK will detect angle brackets ("<" and ">") used to delineate directories as invalid comparison operators. You can either ignore this error or change the angle brackets to square brackets ("[" and "]"). 2 Lexicals DCL_CHECK assumes that every instance of "F$" that is not immediately preceeded by a letter or a digit introduces a lexical function. If "F$" is used as part of a symbol or logical name, this may be reported as a possible truncated or possible misspelled lexical. 1 Examples EXAMPLE 1: This example checks the file MY_COMMAND.COM in the current default directory and displays any errors found on the terminal. $ @DCL_CHECK MY_COMMAND EXAMPLE 2: This example checks the file MY_COMMAND.TEST in a directory "TEST" located under the users login directory, and creates a file TEST.LIS in the current directory if any errors are found. $ @DCL_CHECK SYS$LOGIN:[TEST]MY_COMMAND.TEST TEST EXAMPLE 3: This example check the file MY_COMMAND.COM in the current default directory and creates a file ERROR.REPORT in the users login directory if any errors are found. Detection of lines not starting with "$" is suppressed. $ @DCL_CHECK MY_COMMAND ERROR.REPORT $ EXAMPLE 4: This example request general help $ @DCL_CHECK HELP EXAMPLE 5: This example request help on know problems $ @DCL_CHECK HELP PROBLEMS The following shows how the above examples could be entered by typing only @DCL_CHECK at the DCL prompt and then answering the procedures prompt. Note that line-wrap will occur differently than shown. Example 1: enter name of procedure file to be checked (or HELP or EXIT): MY_COMMAND Example 2: enter name of procedure file to be checked (or HELP or EXIT): SYS$LOGIN:[TEST]MY_COMMAND.TEST TEST Example 3: enter name of procedure file to be checked (or HELP or EXIT): MY_COMMAND ERROR.REPORT $ Example 4: enter name of procedure file to be checked (or HELP or EXIT): HELP Example 5: enter name of procedure file to be checked (or HELP or EXIT): HELP PROBLEMS 1 Diagnostics Diagnostic messages are identified by a three character code. Descriptions and explainations are available for all errors. Enter one of the following codes for more details: CODE Message Errors relate to if-then-else-endif INT IF statement not terminated EFB "=" found between IF and THEN ICO invalid comparison or logical operator TML too many levels of IF statements TRH THEN statement required here TNA THEN statement not allowed here ENA ELSE statement not allowed here DNA ENDIF statement not allowed here WCT wrong constant type for comparison MEC missing expression for comparsion Errors related to subroutines SNT SUBROUTINE statement not terminated TMS too many levels of IF and SUBROUTINE statements RNA ENDSUBROUTINE statement not allowed here Errors related to labels DL duplicate label "