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: Called_procs DCL_CHECK DCL_DIET Diagnostics Format Installation Line_counts Modifications Output Problems Version Examples 1 Version This is version V3.0 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" Alternatively, 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 ; Checking for DCL_CHECK$ logicals... No translation for logical name DCL_CHECK$* "DCL_CHECK$SUPPRESS_WCT" = "TRUE" ... 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. For Pass 2, the numbers in the "processing line number xxx" displays will be in increments 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 ; Checking for DCL_CHECK$ logicals... No translation for logical name DCL_CHECK$* "DCL_CHECK$SUPPRESS_WCT" = "TRUE" ... 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. The LINE reported with the DIAGNOSTIC MESSAGE for diagnostics in lines that are continued will be the line number of the original, continued line. 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 -*- The LINE reported with the DIAGNOSTIC MESSAGE for diagnostics in lines that are continued will be the line number of the original, continued line. 1 Line_counts DCL_CHECK displays (or lists to a file) the following line counts. Procedure contains: nnnn total lines nnnn code lines (including nn lines w/ comments) nnn additional continuation lines nn lines w/i $DECK/$EOD pairs nnn comment only lines nnn blank lines nn diagnostics 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 preceded 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.) 2 diagnostics This is the number of diagnostic message output. 1 Problems DCL_CHECK does not and cannot catch all DCL problems. Not all syntax errors are detected. Misspelled 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 Called_procs If you use DCL_CHECK to check a command procedure that is called by another procedure, various diagnostics may be miss-reported. In particular, diagnostics related to file operations can be miss-reported if the OPEN, READ, WRITE and CLOSE commands are in different files. 2 File_Diagnostics DCL_CHECK's file diagnostics, NLN, ONC, INR, ANR, ONW, RNR, WNW, UNU and CNO, operate by matching OPEN, READ, WRITE and CLOSE DCL statements based on the logical name that these statements use. If symbol substitution is used for these logical names, these diagnostics may incorrectly generate warnings. Because DCL_CHECK does not know the order in which a command procedure will actually execute, no attempt is made to ensure that OPEN statements precede and CLOSE statements follow READ and WRITE statements. For the same reason, no attempt is made to sort out the possible errors that may occur if a procedure contains multiple OPEN and or CLOSE statements for the same file. One of the main purposes of these diagnostics is to catch different [miss]spellings of the logical name. 2 Single_quote DCL_CHECK is imperfect in its checking for use of single-quote characters. For this reason it lists 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. Valid uses of a single single-quote (') will be reported as errors. 3 Contractions DCL_CHECK removes the following contractions before checking for single-quotes. Note that this is case sensitive -- upper case, lower case and capitalized (i.e. only first letter in upper case) will be removed. Any other mixed case versions of these contractions will not be removed. (Exception: The personal pronoun "I" is upper case.) aren't he's shouldn't we've can't I'd that's weren't couldn't I'll they'd what's didn't I'm they'll who's doesn't I've they're won't don't isn't they've wouldn't hadn't it's wasn't you'd hasn't she'd we'd you'll haven't she'll we'll you're he'd she's we're you've he'll 3 Possives DCL_CHECK removes the following possessives for common accounting periods before checking for single-quotes. Note that this is case sensitive -- upper case, lower case and capitalized (i.e. only first letter in upper case) will be removed. Any other mixed case versions of these possessives will not be removed. Day's Week's Month's Period's Quarter's Half's Year's 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 preceded 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. 2 Parentheses DCL_CHECK will detect unpaired parentheses within quoted strings. These may or may not be errors. 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. $ @DCL_CHECK MY_COMMAND ERROR.REPORT EXAMPLE 4: This example requests general help $ @DCL_CHECK HELP EXAMPLE 5: This example requests 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. The LINE reported with the DIAGNOSTIC MESSAGE for diagnostics in lines that are continued will be the line number of the original, continued line. Descriptions and explanations are available for all errors. Enter one of the following codes for more details: CODE- Diagnostic Message Severity Errors related to file operations NLN-S An OPEN, READ, WRITE or CLOSE statement has no logical name ONC-E A file that is opened has no close statement INR-E A file that is opened for read is not read ANR-E A file that is opened for append is not written ONW-E A file that is opened for write is not written RNR-S A file that is not opened for read is being read WNW-S A file that is not opened for write or append is being written UNU-S A file that is not opened for read and write is being updated CNO-S A file that is closed has no open statement Errors related to if-then-else-endif INT-S IF statement not terminated EFB-S "=" found between IF and THEN ICO-S invalid comparison or logical operator TML-S too many levels of IF statements TRH-S THEN statement required here TNA-S THEN statement not allowed here ENA-S ELSE statement not allowed here DNA-S ENDIF statement not allowed here WCT-E wrong constant type for comparison MEC-S missing expression for comparison Errors related to subroutines SNT-S SUBROUTINE statement not terminated TMS-S too many levels of IF and SUBROUTINE statements RNA-S ENDSUBROUTINE statement not allowed here Errors related to labels DL--E duplicate label "