% Librarian A09-23d fg 5dDCLDIET DCL_CHECKbVDCL_DIET' Diagnostics$ExamplesFormate Installation Line_counts` Modifications |OutputProblemsVersion 0 1 DCL_CHECKH The DCL_CHECK procedure detects a variety of DCL coding errors andH displays diagnostic messages that allow you to correct theH problems. See "Diagnostics" for a list of the types of errors thatH DCL_CHECK can detect. See "Problems" for information on the limits of DCL_CHECK.H When you execute DCL_CHECK with "HELP" as the first parameter,H DCL_CHECK invokes the DCL Help utility. If you provide additional6  parameters, they are passed to the Help utility.H To exit the Help utility, press Return one or more times until the1 prompt "enter name of file:" is displayed.# Additional information available:: DCLDIET DCL_CHECK DCL_DIET Diagnostics: Examples Format Installation Line_counts6 Modifications Output Problems VersionwwV 1 Version6 This is version V3.3 of the DCL_CHECK help file.ww V1 FormatH DCL_CHECK is a DCL command procedure. It is executed by the following DCL command:C $ @[:][]DCL_CHECK.COM [ []]B $ @[:][]DCL_CHECK.COM HELP [...]H and/or may be omitted; the current defaults will be used.H The file DCL_CHECK.HLB must be in the same directory asH DCL_CHECK.COM if you use the HELP function in DCL_CHECK. The f iles< may be in any directory to which you have read access.H If you use DCL_CHECK frequently, you may wish to assign a symbolH in your LOGIN.COM file to execute DCL_CHECK. For example, if theH DCL_CHECK.COM and .HLB files are in you login default directory,4 you might put the following in your LOGIN.COM:0 $ DCL_CHECK :== "@SYS$LOGIN:DCL_CHECK"H Alternatively, if you put DCL_CHECK.COM and DCL_CHECK.HLB inH SYS$SYSTEM, you might put the following in your SYS$SYLOGIN (which+ is normally SYS$MANAGER:SYLOGIN.COM):1 $ DCL_CHECK :== "@SYS$SYSTEM:DCL_CHECK" 2 ParametersH Parameters may be entered on the command line; if there are noH parameters on the command line, the procedure will display the prompt for parameters.H The first parameter is either the file-name of a command procedureB file to be checked, or one of the keywords "HELP" or "EXIT".H If a file name is entered, it will be checked. If a device andH directory are not supplied, the current default is used. If a file0 extension is not supplied, ".COM" is used.H If a file name is entered, the second parameter may provide theH name of a listing file to contain the list of errors detected. IfH a device and directory are not supplied, the current default isH used. If a file extension is not supplied, ".LIS" is used. IfH second parameter is not suppli ed, errors are listed on sys$output.H If the first parameter contains "HELP", the DCL Help utility isH used to provide information about the DCL_CHECK utility. Any; additional parameters are passed to the HELP utility.H If the first parameter contains "EXIT", any additional parameters* are ignored and the procedure exits.wwB1 OutputH If the second parameter (see HELP FORMAT PARAMETERS) is blank, allH output of DCL_CHECK is  displayed on the terminal. If the secondH parameter is a listing file name, some output is displayed on theH terminal and diagnostic information is written to the listing file.2 Terminal_outputH Terminal output depends on whether or not there is a listing file.3 Listing_fileD If there is a listing file, output similar to the following is displayed:E -*- Charlie Hammond's unsupported DCL checker (Version 1.0) -*- Checking file ;) Checking for DCL_CHECK$ logicals...1 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 -- ...0 Creating errors listing in ; H For Pass 1,  the numbers in the "processing line number xxx", displays will be in increments of 500.H For Pass 2, the numbers in the "processing line number xxx"- displays will be in increments of 1000.D If no errors are found, the last two lines will be replaced to indicate this: No errors found0 ...listing file not created 3 No_listing_fileE If there is no listing file, output similar to the following is displayed:E -*- Charlie Hammond's unsupported DCL checker (Version 1.0) -*- Checking file ;) Checking for DCL_CHECK$ logicals...1 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 linesL nnnn code lines (including nn lines w/ comments)3 nnn continuation lines; nn lines w/i $DECK/$EOD pairs3 nnn comment only lines, nnn blank lines) LINE CODE --DIAGNOSTIC MESSAGE-- . . .6 -*- END OF LISTING -*- 13-OCT-1997 10:57:28.07H For Pas s 1, the numbers in the "processing line number xxx"H displays will be in increments of 500. Occasionally they will not be exact multiples of 500.H For Pass 2, the numbers in the "processing line number xxx"H displays will be in approximate increments of 1000. Because pass 2H is processing an abbreviated file (comment lines removed) the line5 numbers will seldom be exact multiples of 1000.H The LINE reported with the DIAGNOSTIC MESSAGE fo r diagnostics inH lines that are continued will be the line number of the original, continued line. 2 File_outputF If a listing file is being used, it contains information similar to the following.F -*- Charlie Hammond's unsupported DCL checker (Version R1.0 -*-)8 Checking file WORK8:[HAMMOND]DCL_CHECK.COM_SOURCE; , Procedure contains: nnnn total linesL nnnn code lines (including nn lines w/ comments)3 nnn continuation lines; nn lines w/i $DECK/$EOD pairs3 nnn comment only lines, nnn blank lines) LINE CODE --DIAGNOSTIC MESSAGE-- . . . -*- END OF LISTING -*-G The LINE reported with the DIAGNOSTIC MESSAGE for diagnostics inG lines that are continued will be the line number of the original, continued line .ww; 1 Line_countsH DCL_CHECK displays (or lists to a file) the following line counts., Procedure contains: nnnn total linesL nnnn code lines (including nn lines w/ comments)> nnn additional continuation lines; nn lines w/i $DECK/$EOD pairs3 nnn comment only lines, nnn blank lines, nn dia gnostics0 There is an explanation for each of these. 2 total_linesE Total lines is a count of every physical line in the file beingD checked. It is the same as the number of records in the file. 2 code_linesH Code lines is a count of lines of code. It does not includeH continuation lines, lines within a $DECK/$EOD pair, comment lines or blank lines.H Immediately following the count of code lines is a count of theH number of code lin es that also include comments. Note that this is* included in the count of code lines.2 continuation_linesH Continuation lines is a count of the number of lines of code thatH are continued from a code line. A continued code line ends with aH hyphen (-) that is not a comment (i.e., not preceded by an "!");H lines following continued line are continuation lines.H Continuation lines may be continued. i.e. a code line may be2 continued on t wo or more continuation lines. 2 deck_linesH Deck lines is a count of lines that are within a $DECK/$EOD pair.H These lines are input to programs or utilities. They may be6 commands or text used by the program or utility.2 comment_linesH Comment lines are lines that are not within $DECK/$EOD pairs whichH contain only comments. i.e. the first non-blank following theH dollar sign ($) is an exclamation point (!). Comments may alsoH appear on code lines following DCL commands; these comments are not counted. 2 blank_linesH Blank lines are lines which are totally blank (which also generateH diagnostic messages) or which contain only a blank comment. (BlankH comments are often used to insert white space to improve readability.) 2 diagnostics6 This is the number of diagnostic message output.ww  1 Problems; DCL_CHECK does not and cannot catch all DCL problems. - Not all syntax errors are detected.B Misspelled commands and variable names are not detected.* Logic errors cannot be detected.D 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 "$".H In addition, the detection of one problem may obscure one or mo reH other problems -- or may cause problems to be erroneouslyH detected. For this reason, you should always re-run DCL_CHECK after correcting errors.2 Called_procsH If you use DCL_CHECK to check a command procedure that is calledH by another procedure, various diagnostics may be miss-reported. InG particular, diagnostics related to file operations can beH miss-reported if the OPEN, READ, WRITE and CLOSE commands are in diff erent files.2 File_DiagnosticsH DCL_CHECK's file diagnostics, NLN, ONC, INR, ANR, ONW, RNR, WNW,H UNU and CNO, operate by matching OPEN, READ, WRITE and CLOSE DCLH statements based on the logical name that these statements use. IfH symbol substitution is used for these logical names, these4 diagnostics may incorrectly generate warnings.H Because DCL_CHECK does not know the order in which a commandH procedure will actually execute, no atte mpt is made to ensure thatH OPEN statements precede and CLOSE statements follow READ and WRITEH statements. For the same reason, no attempt is made to sort outH the possible errors that may occur if a procedure contains> multiple OPEN and/or CLOSE statements for the same file.H One of the main purposes of these diagnostics is to catchF different [miss]spellings of the logical name used for the file.2 Single_quoteH DCL_CHECK is imperfe ct in its checking for use of single-quoteH characters. For this reason it lists such errors as "probable" or "possible".H Some syntactically invalid lines may be missed. Lines containing0 an even number of errors may "cancel out".H If one single-quote is used to start symbol substitution within aH quoted string (instead of two single-quotes) DCL_CHECK will reportH this as an error, and will also flag the single-quote used to endH the symbol ! substitution. Although this may seem like a singleC error, DCL_CHECK sees it as two possible single-quote errors.H Some valid uses of a single single-quote (') will be reported as errors.3 ContractionsH DCL_CHECK removes the following contractions before checking forH single-quotes. Note that this is case sensitive -- upper case,H lower case and capitalized (i.e. only first letter in upper case)H will be removed. Any other mixed " case versions of these' contractions will not be removed.B (Exception: The personal pronoun "I" is always upper case.)> aren't he'd shouldn't we've@ can't he'll they'd weren't> couldn't I'd they'll won'tA didn't I'll they're wouldn't> doesn't I'm they've you'd? don't I've # wasn't you'll? hadn't isn't we'd you're? hasn't she'd we'll you've/ haven't she'll we're 3 PossessivesH Within a quoted string, DCL_CHECK considers the string "'s "H (upper or lower case -- note the trailing space) as valid+ possessives and does not report them.2 Angle_bracketsH DCL_CHECH will detect angle brackets ("<" and ">") u $sed toH delineate directories as invalid comparison operators. You canH either ignore this error or change the angle brackets to square brackets ("[" and "]"). 2 LexicalsH DCL_CHECK assumes that every instance of "F$" that is notH immediately preceded by a letter or a digit introduces a lexicalH function. If "F$" is used as part of a symbol or logical name,H this may be reported as a possible truncated or possible miss%pelled lexical. 2 ParenthesesH DCL_CHECK may detect unpaired parentheses within quoted strings.% These may or may not be errors.ww 1 ExamplesH EXAMPLE 1: This example checks the file MY_COMMAND.COM in the currentN default directory and displays any errors found on the terminal. $ @DCL_CHECK MY_COMMANDI EXAMPLE 2: This example checks the file MY_COMMAND.TEST in a directoryK "TEST" located under the users login dir&ectory, and creates aM file TEST.LIS in the current directory if any errors are found.7 $ @DCL_CHECK SYS$LOGIN:[TEST]MY_COMMAND.TEST TESTG EXAMPLE 3: This example check the file MY_COMMAND.COM in the currentL default directory and creates a file ERROR.REPORT in the users6 login directory if any errors are found.* $ @DCL_CHECK MY_COMMAND ERROR.REPORT0 EXAMPLE 4: This example requests general help $ @DCL_CHECK HELP'9 EXAMPLE 5: This example requests help on know problems $ @DCL_CHECK HELP PROBLEMSG The following shows how the above examples could be entered by typingM only @DCL_CHECK at the DCL prompt and then answering the procedures prompt.8 Note that line-wrap will occur differently than shown. Example 1:J 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):J ( 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:D enter name of procedure file to be checked (or HELP or EXIT): HELP Example 5:M enter name of procedure file to be checked (or HELP or EXIT): HELP PROBLEMSwwl 1 DiagnosticsH Diagnostic messages are identified by a three character code.G )The LINE reported with the DIAGNOSTIC MESSAGE for diagnostics inG lines that are continued will be the line number of the original, continued line.H Descriptions and explanations are available for all errors. Enter2 one of the following codes for more details:& CODE- Diagnostic Message Severity. Errors related to file operationsJ NLN-S An OPEN, READ, WRITE or CLOSE statement has no logical name; ONC-E A file th*at is opened has no close statement9 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 readM WNW-S A file that is not opened for write or append is being writtenL 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 stateme +nt: OCE-I OPEN or CLOSE statement with /END qualifier1 Errors related to if-then-else-endif* INT-S IF statement not terminated, EFB-S "=" found between IF and THEN5 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 here1 , WCT-E wrong constant type for comparison0 MEC-S missing expression for comparison* Errors related to subroutines2 SNT-S SUBROUTINE statement not terminated> TMS-S too many levels of IF and SUBROUTINE statements7 RNA-S ENDSUBROUTINE statement not allowed hereC LNS-S referenced label "