++========================================++ || || || || || I S I S - I I || || ------------- || || || || S O F T W A R E || || --------------- || || || || T O O L B O X || || ------------- || || || || || ++========================================++ 121727-001 Rev. A Copyright 1980 Intel Corporation 3065 Bowers Avenue, Santa Clara, California 95051 Intel Corporation has carefully reviewed this Vendor Supplied Product for its suitability and operational characteristics when used with Intel products, and believes that the product will operate and perform according to its published user manuals. HOWEVER, INTEL MAKES NO WARRANTIES WITH RESPECT TO THE OPERATION AND USE OF THIS PRODUCT. Successful use depends solely on customer's ability to install and use this product. This Product is licensed on an "as is" basis, and Intel Corporation does not guarentee any future enhancements or extensions to this product. The existence of this product does not imply its adaptation in any form as an Intel standard, nor its compatibility with any other Intel product, except as specifically stated in the published user manuals. In addition, if a problem is encountered which the user diagnosis indicates is caused by a defect in the Product, the user is requested to fill out a Problem Report form, and mail it to: Intel Corporation MCSD, Marketing 3065 Bowers Avenue Santa Clara, CA 95051 ++==============================================++ || || || ISIS-II SOFTWARE TOOLBOX || || VERSION 1.0 || || PREFACE || || || ++==============================================++ This manual defines and describes the use of the ISIS-II Software Toolbox. The Toolbox is a collection of utilities which enhance the ISIS-II operating system to improve programmer productivity. The manual is organized as follows: QUICK REFERENCE SUMMARY The following section contains a "quick reference" summary of what each tool does. EXPLANATION OF SOURCE MANAGEMENT SYSTEM An explanation of the philosophy behind the Source Management System, and a description of how the Source Management tools work together, is given in Source Management Overview chapter. The appropriate tools are described immediately after the overview. OVERVIEW OF CONDITIONAL SUBMIT CONTROL A brief description of conditional Submit execution, plus an example using most of the tools, is contained in the Submit File Control Overview. The individual Submit tools follow the overview. OTHER TOOLS Those tools not associated with Submit Control or Source Management are listed alphabeticallly, following those two sections. IDENTIFYING THE TOOLS The version numbers of the programs constituting the Software Toolbox can be ascertained through the Software Toolbox tool, "Which". ++=============================================++ || || || ISIS-II SOFTWARE TOOLBOX || || VERSION 1.0 || || TABLE OF CONTENTS || || || ++=============================================++ QUICK REFERENCE SUMMARY ............................ 1 SOURCE MANAGEMENT OVERVIEW ......................... 3 XLATE2 ...................................... 4 MRKOBJ ...................................... 7 CHKLOD ...................................... 9 CLEAN ...................................... 13 LATEST ..................................... 14 SUBMIT FILE CONTROL OVERVIEW ...................... 16 IF ......................................... 18 ELSE ....................................... 22 ENDIF ...................................... 22 GOTO ....................................... 23 RETURN ..................................... 24 EXIT ....................................... 24 LOOP ....................................... 25 RESCAN ..................................... 26 WAIT ....................................... 27 NOTE ....................................... 28 OTHERS: COMPAR ..................................... 29 CONSOL ..................................... 34 DCOPY ...................................... 36 DSORT ...................................... 41 ERRS ....................................... 43 GANEF ...................................... 44 GENPEX ..................................... 49 HDBACK ..................................... 54 LAST ....................................... 57 LOWER/UPPER ................................ 58 MERG80 ..................................... 60 MERG86 ..................................... 62 PACK/UNPACK ................................ 64 PASSIF ..................................... 68 RELAB ...................................... 74 SORT ....................................... 75 STOPIF ..................................... 78 WHICH ...................................... 79 ISIS-II SOFTWARE TOOLBOX, V1.0 page 1 ++==============================================++ || || || ISIS-II SOFTWARE TOOLBOX || || VERSION 1.0 || || QUICK REFERENCE SUMMARY || || || ++==============================================++ Related programs are indicated by indentation. SOURCE MANAGEMENT XLATE2 -- submit-like tool with intelligent parameter substi- tution (for version control) MRKOBJ -- "marks" object modules with source version numbers CHKLOD -- lists source versions put in load modules by Mrkobj CLEAN -- deletes all old versions off a specified disk LATEST -- displays latest version numbers of specified files PROGRAM DEVELOPMENT AND DEBUGGING ERRS -- fast display of program errors in PLM80, PLM86, and ASM86 listings MERG80 -- merges debug data from locate maps into PLM80 listings MERG86 -- merges debug data from symbol maps into PLM86 or Pasc86 listings GENPEX -- produces include file for PLM external declarations (source level) PASSIF -- general purpose assertion checking and reporting tool OPERATING SYSTEM FUNCTIONS CONSOL -- reassigns console input and console output as directed DSORT -- alphabetically sorts floppy and hard disk directories RELAB -- changes disk name to specified name SUBMIT FILE EXECUTION CONTROL IF -- conditional submit file execution based on file ELSE existence, program errors, pattern matching, plus ENDIF several other conditions. GOTO -- causes execution to resume at a given "label" LOOP -- causes execution to resume at the beginning of the submit file (like a "GOTO start") NOTE -- allows "progress report" messsages to be displayed to the cold boot console WAIT -- displays a message, and waits for user input to continue or abort RETURN -- causes execution of the last line of a Submit file causing immediate return to the "submitter." RESCAN -- allows submit file to be "started up" in the middle EXIT -- halts submit file execution DISK RECOVERY GANEF -- interactively reads and writes disk data blocks ISIS-II SOFTWARE TOOLBOX, V1.0 page 2 DISK BACKUP AND FILE PROCESSING DCOPY -- fast track by track diskette copying HDBACK -- sophisticated hard disk to floppy disk backup program PACK -- compacts text files UNPACK -- reconstitutes "packed" files TEXT PROCESSING COMPAR -- performs line-oriented text file comparison (shows souce code changes) UPPER -- changes all letters in a file to uppercase LOWER -- changes all uppercase letters to lowercase LAST -- displays the last 512 bytes of a file SORT -- sophisticated line-oriented text file sorting tool PROGRAM IDENTIFICATION WHICH -- displays version number of Software Toolbox Programs ISIS-II SOFTWARE TOOLBOX, V1.0 page 3 ++==============================================++ || || || ISIS-II SOFTWARE TOOLBOX || || VERSION 1.0 || || SOURCE MANAGEMENT OVERVIEW || || || ++==============================================++ The central feature of the Source Management System is that all source modules have a wholly numeric filename extension consisting of exactly three ascii decimal digits; e.g., "003", "057", "671", etc. The utilities which comprise the Source Management System interpret these numeric extensions as being version numbers. A numerically greater version number is deemed to indicate a more recent version of a given file. The Source Management System can mark object modules with the version number of the source file from which it was generated. The 8080 and 8086 linkers and locators pass this information all the way through to the load module, allowing the Chklod program to display and process it. The utilities comprising the Source Management System are: XLATE2 -- like submit except that it can pick up the "latest" version of a given filename, and substitute it into the Command Sequence File it is building MRKOBJ -- "marks" object modules with the name of the source file from which they were produced. Mrkobj works on both 8080 and 8086 object modules. CHKLOD -- examines load modules; finds, processes, and displays the source version information previously placed there by Mrkobj CLEAN -- gets rid of all the old versions of all the files on a specified disk LATEST -- displays latest version numbers of specified files ISIS-II SOFTWARE TOOLBOX, V1.0 page 4 +=================================+ | | | XLATE2 | | v1.0 | | | +=================================+ SUMMARY Xlate2 is a part of the source-management family of tools. It is much like the Submit cusp, but has "intelligent parameter substitution" capability. It can determine the greatest numeric extension of a particular file on a particular disk, and substitute the filename plus extension into the Command Sequence file. This program WILL work with the NDS-1 Remote Hard Disks. SAMPLE INVOCATION XLATE2 compil.tpl 5 MAIN PARSE GEN TOKENS SAMPLE ACTIONS PERFORMED Given that the "template" file (compil.tpl) looks like TEMPLATE FILE +---------------------------------------------------------+ | | | :f1:plm86 :f?:#0 print(:f1:%0.lst) debug xref | | | +---------------------------------------------------------+ And :f5:main has numeric extensions 001 002 and 006 :f5:parse has numeric extension 000 :f5:gen has numeric extension 531 :f5:tokens has numeric extension 211 Then XLATE2 will create a Command Sequence file (shown below), with filename :f1:xlate2.cs, and transfer control to it: ISIS-II SOFTWARE TOOLBOX, V1.0 page 5 COMMAND SEQUENCE FILE +----------------------------------------------------------------+ | | | :f1:plm86 :f5:main.006 print(:f1:main.lst ) debug xref | | :f1:plm86 :f5:parse.000 print(:f1:parse.lst ) debug xref | | :f1:plm86 :f5:gen.531 print(:f1:gen.lst ) debug xref | | :f1:plm86 :f5:tokens.211 print(:f1:tokens.lst) debug xref | | | | xlate2 RESTORE (:VI:) ( 0, 0) | | | +----------------------------------------------------------------+ After the command sequence file has been executed, control will return to the caller, via the the final "xlate2 RESTORE" command. Xlate2 has fairly different parameter substitution than Submit in that it only passes file names, yet has the capability to retrieve the latest version of a particular file. The best of both worlds may be realized by including Xlate2 commands within Submit files, and utilizing the extended parameter passing capability of Submit. FORMAL SYNTACTIC SPECIFICATION The invocation syntax for XLATE2 is : XLATE2 [?] [HALT!] is the name of a template file, the function of which is described later. is a decimal digit from 0 to 9 , giving the device_number from which numeric filename extensions should be taken. Only one such device is allowed per invocation of xlate2. is a list of isis-II filenames separated by blanks, (NOT commas). Additionally, filenames of the form namepart dot (no extension, but a dot) are allowed and have an interpretation given below. Note that the device can be respecified but this will be ignored. Continuation is allowable by the use of & as the last non-blank character on a line. ** , the standard prompt, will be issued after continued lines. ? causes xlate2 to print its version number and exit. HALT! causes the consol file to be created but not executed, allowing verification. The consol file ISIS-II SOFTWARE TOOLBOX, V1.0 page 6 created will be xlate2.cs on the drive from which xlate2 was invoked. The template file uses the following substitution: substitution signs: substitutions are of the form %0 or #0. the substitution matrix: don't get confused here, all you probably want is %0.ext and #0 in the template and a with name parts only (no dot, no extension) on the command line. foo foo. foo.abc +-------------------------------------------+ | | %0 | foo foo. foo.abc | | | %0. | foo foo foo | | | %0.ext | foo.ext foo.ext foo.ext | | | #0 | foo.#xt foo foo.#xt | | | +-------------------------------------------+ foo.#xt is the greatest numeric extension of foo found in isis.dir on the device_number. If no numeric extension of foo is found then a warning will be issued and foo. will appear in place of foo.#xt in the consol file. In the above example it is assumed that ext is <= 3 characters. If not then a warning will be given. Note: In all the template substitutions it is wise to ---- follow them with a blank. Note: additionally :fn: will ---- preserve the n in the template substitution, at least for 0 <= n <= 9. Furthermore for :f?: , the will be substituted for the ?. Note: Warnings will be printed to both the cold-boot ---- console and to the current console if different. ISIS-II SOFTWARE TOOLBOX, V1.0 page 7 +=================================+ | | | MRKOBJ | | v1.0 | | | +=================================+ SUMMARY This program is a member of the PL/M Source Management Family. It "marks" object modules with the name of the source file from which it was produced. Mrkobj works on both 8080 and 8086 object modules. The program name "mrkobj" is intended to be a mnemonic for "mark object module". The version number information within the "marked" object module will be used later, by the Chklod program, which will perform source program version determination and checking. This program WILL work with the NDS-1 Remote Hard Disks. SAMPLE PROGRAM INVOCATION MRKOBJ :f1:main.obj WITH :f1:main.003 SAMPLE ACTIONS PERFORMED The object module ":f1:main.obj" will be marked with the source file name ":f1:main.003". TYPICAL USE ENVIRONMENT Mrkobj is intended to be used in conjunction with the xlate2 tool, since xlate2 can automatically determine the latest version of the source file, avoiding errors that could occur with manual invocations of Mrkobj. A sample "xlate2-type" submit file which uses Mrkobj is: +---------------------------------------------------+ | | | PLM86 :f?:#0 print(:f1:%0.lst) | | | | MRKOBJ :f1:%0.obj WITH :f?:#0 | | | +---------------------------------------------------+ ISIS-II SOFTWARE TOOLBOX, V1.0 page 8 ACTIONS PERFORMED The object modules are marked by the insertion of extra records. RECORDS USED For the 8086, a comment record is used. For the 8080, a debug record is used. Both types of records are purgable. ERROR CONDITIONS TARGET OBJECT MODULE IS LIBRARY If the object module is a library, then Mrkobj will print: *** IS AN 8080 LIBRARY *** or *** IS AN 8086 LIBRARY *** to the console output device, and exit. TARGET OBJECT MODULE IS SEQUENCE If the object module specified is a sequence, then Mrkobj will print *** CANNOT MARK OBJECT MODULE SEQUENCE *** to the console output device, and exit. FORMAL SYNTACTIC SPECIFICATION Mrkobj is invoked by: MRKOBJ WITH ISIS-II SOFTWARE TOOLBOX, V1.0 page 9  +=================================+ | | | CHKLOD | | v1.0 | | | +=================================+ SUMMARY Chklod is a member of the PL/M Source Management Family. It examines 8080 or 8086 loadable object modules for source file version number information. The version numbers were previously placed in the object modules (by the Mrkobj Software Toolbox program) befor being linked. Using the version information, and examining a program source disk directory or directories, Chklod ascertains whether the source files used to produce the load module, are the most "recent" source modules. Chklod can also produce a "listing" of a specified load module. The listing is a formatted, human-readable compendium of the source version information found in the load module. This program WILL work with the NDS-1 Remote Hard Disks. SAMPLE INVOCATIONS WITH SAMPLE ACTIONS PERFORMED: CHKLOD :f1:prog the load module ":f1:prog" is checked against the corresponding source files in drive 1 (which is the default "drive to be searched" if none is specified). CHKLOD :f1:prog 1 2 3 1 :f1:prog is checked against the corresponding source files found on drives 1, 2, and 3. Chklod pauses and prints a prompting message before searching the diskettes. Notice that drive 1 will be searched twice. CHKLOD :f1:prog LISTING TO :f1:prog.arc NOSORT In case three Chklod dumps a formatted listing of the source version number information to the file ":f1:prog.arc". The source version information is listed in the same order in which it appeared in ISIS-II SOFTWARE TOOLBOX, V1.0 page 10 the load module. CHKLOD :f1:prog LT In case four Chklod sorts the listing, and dumps it to the default output device, which is the console output. ACTIONS PERFORMED LOAD MODULE CHECKING AND INTERPRETATION DUPLICATE SOURCE VERSION INFORMATION IN A SINGLE LOAD MODULE If Chklod finds that the source version information, for a single source file, has been specified more than once in a single load module, then the message: "WARNING: respecification of source version information encountered" SOURCE PROGRAM NAME: " LOAD MODULE VERSION LEVELS: . . . etc. will be output to the console output device. In these cases, Chklod will choose the source file with the highest numeric extension as being correct, in performing its subsequent checking. EXPLICIT DEVICE SPECIFICATION CAUSES A PAUSE AND PROMPT When the disk drives to be searched for source files are explicitly specified in Chklod's command tail, then, before reading the specified disk directory, Chklod will halt and write: "insert source disk in drive n and type to continue --" to the console output, and then wait until is typed. SOURCE VERSION DISCREPANCIES For source filenames where the greatest numeric extension gleaned from disk is different than the numeric ISIS-II SOFTWARE TOOLBOX, V1.0 page 11 extension found in the load module, the the message(s): VERSION DISCREPANCY FOUND SOURCENAME: LOAD MODULE VERSION LEVEL: nnn SOURCE MODULE VERSION LEVEL: nnn SOURCENAME: LOAD MODULE VERSION LEVEL: nnn SOURCE MODULE VERSION LEVEL: nnn . . . etc. will be written to the console output. (nnn is a three- digit numeric extension.) If there is more than one numeric extension entry in either the directory or the load module, then the above error message(s) refer to the largest ones found. EXPECTED SOURCE MODULE NOT FOUND If there is no file in the source disk(s) which corresponds with a numeric extension record in the load module, then the form of discrepancy listing is: SOURCENAME: LOAD MODULE VERSION LEVEL: nnn SOURCE MODULE VERSION LEVEL: (NONE) If the greatest numeric extension gleaned from disk is equal to the numeric extension found in the load module, then no discrepancy message is produced. If Chklod finds no discrepancies of any kind, including doubly marked load modules, then the message: NO DISCREPANCIES FOUND will be output to the system console. INVALID LOAD MODULE If the object module is a library then Chklod will print "SPECIFIED LOAD MODULE IS A LIBRARY" to the console output, and exit. ISIS-II SOFTWARE TOOLBOX, V1.0 page 12 ------------------------------------------------------------ LOAD MODULE LISTING PRODUCTION The keyword "LISTING", or its abbreviation "LT", appearing in the command tail causes Chklod to produce a formatted listing of the source program version level information found in the specified load module. If no output device is specified, then the listing goes to the console output device. The listing will be sorted, unless the NOSORT option is specified. A sample listing follows: LISTING OF ARITHM.003 MAIN .015 PARSE .227 RMATH .004 ------------------------------------------------------------- FORMAL SYNTACTIC SPECIFICATION Chklod is invoked with the command: CHKLOD [ ] :== | :== [ {ascii_decimal_digit} [ {ascii_decimal_digit} ]] :== ( LISTING | LT ) [ TO ] [NOSORT] :== [ {} ] :== 020H ISIS-II SOFTWARE TOOLBOX, V1.0 page 13 +=================================+ | | | CLEAN | | v1.0 | | | +=================================+ SUMMARY Clean, is one of the Source Management Tools. It gets rid of all the "old" versions of a file on the specified disk. An old file is one with the same name part as another file, but with a lesser numeric extension. This program WILL work with the NDS-1 Remote Hard Disks. SAMPLE INVOCATION clean 1 ACTIONS PERFORMED The single decimal digit specifies which device Clean is to operate upon. Clean reads in the directory, and determines which files with numeric extensions are not the most recent versions of that file. Clean then deletes all the old versions of the file. Clean also deletes all files with extensions "tmp", and "bak". EXAMPLE If the files main.003,main.004,main.005 pars.009 token.bak appear on the same drive, the Clean will delete files main.003,main.004 token.bak SYNTAX Clean ISIS-II SOFTWARE TOOLBOX, V1.0 page 14 +=================================+ | | | LATEST | | v1.0 | | | +=================================+ SUMMARY Latest is a tool which, given a list of filenames, lists the greatest numeric extension for each. Latest is one of the family of source management tools. This program WILL work with the NDS-1 Remote Hard Disks. SAMPLE INVOCATION WITH OUTPUT Given the command: :f1:latest 5 main filnam & prog & errs and assuming that :f5:main has numeric extensions 001 002 and 006 :f5:filnam has numeric extension 000 :f5:prog has numeric extension 531 :f5:errs has numeric extension 211 then LATEST will report main has greatest numeric extension main.006 filnam has greatest numeric extension filnam.000 prog has greatest numeric extension prog.531 errs has greatest numeric extension errs.211 FORMAL SYNTACTIC AND SEMANTIC SPECIFICATION LATEST | is a decimal digit from 0 to 9, giving the device_number from which numeric filename extensions should be taken. Only one such device is allowed per invocation of latest. is a list of isis-II filenames separated by blanks, (NOT commas). Additionally, filenames of the form namepart dot (no extension, but ISIS-II SOFTWARE TOOLBOX, V1.0 page 15 just a dot) are allowed and have an interpretation given below. Note that the device can be respecified but the respecification will be ignored. Continuation is allowable by the use of an ampersand as the last non-blank character on a line. Two asterisks, the standard continuation line prompt, will be issued before continued lines. ? Causes LATEST to print its version number and exit. WARNINGS AND ERRORS Warnings will be printed to both the cold boot console and to the current system console, if different. ISIS-II SOFTWARE TOOLBOX, V1.0 page 16 ++==============================================++ || || || ISIS-II SOFTWARE TOOLBOX || || VERSION 1.0 || || SUBMIT FILE CONTROL OVERVIEW || || || ++==============================================++ Structured programming has finally arrived for the submit file user. It is now possible to structure your command files to make them more readable, more managable, and more meaningful. The package of commands will allow you to make decisions and branches within a command file. The "IF" family of tools contains a series of commands which work together to provide this total capability: IF, ELSE, ENDIF, GOTO, LOOP, RETURN, RESCAN, EXIT, WAIT and NOTE. As an example, the following Submit file will compile a program, and if there are no errors, link and locate the object. IF NOT PLM80 THEN WAIT; Put the PLM80 disk in drive 0 LOOP; ENDIF; ;; RECOMP PLM80 %0.PLM NOLIST IF ' 0 PROGRAM ERROR' IN %0.LST THEN LINK %0.OBJ,SYSTEM.LIB,PLM80.LIB TO %0.LNK LOCATE %0.LNK MAP PURGE ELSE EDIT %0.PLM NOTE; Enter a '1' if you want to recompile %0.PLM IF '1' = :VI: THEN GOTO RECOMP; ENDIF; ENDIF; Line 1 of the example is a test to see if the file PLM80 exists on the disk on drive 0, if it does not, then the WAIT command will be executed, and wait for the user to enter a carriage-return at the console. Then the file- existence test is repeated until the file "PLM80" is detected on drive 0. Line 5 is a comment line, but it is of the format (two consecutive leading semicolons) that the GOTO command uses for declaring labels. Next comes the compile itself. Line 7 is to check if the compilation has errors by looking for the string ' 0 PROGRAM ERROR' in the program listing. If the string is in the listing, then no errors were detected and it is OK to link and locate. (The 'THEN' after the condition is treated as a comment.) If the condition is not ISIS-II SOFTWARE TOOLBOX, V1.0 page 17 met, the editor is invoked, and the user can edit the source and recompile. Finally, the NOTE command tells the user what (s)he can do to cause the modified source program to be recompiled. The next IF command allows the user to interactively control the flow of the commands. This example illustrates almost all the features of the IF family of tools. The individual commands are explained in the following sections. ISIS-II SOFTWARE TOOLBOX, V1.0 page 18 +===================================+ | | | IF | | v1.0 | | | +===================================+ SUMMARY The IF command is the most powerful command of the package. It ascertains the conditions that are most likely used: string comparison, file comparison, string in file, and file existance. There are six types of assertions. The syntax of the IF command is: IF [NOT] = [comment] IF [NOT] = [comment] IF [NOT] IN [comment] IF [NOT] IN [comment] IF [NOT] = [comment] IF [NOT] [comment] 1. STRING COMPARISON The first form, string comparison, allows conditional Submit file execution based on submit parameters. One compares a fixed string with a string defined by a submit parameter. An example: ;copy files from :F3: to :F2:, IDISK first if desired. IF NOT '%0' = '' THEN IDISK :F2:NONSYS.DSK ENDIF; COPY :F3:*.SRC TO :F2: Q ^E The two strings being compared are both converted to upper-case first, and the length of the two strings must be the same. Otherwise they are considered unequal. Note that the command syntax allows optional comments after the conditional expression. The word 'THEN' is treated as a comment by the IF command. 2. STRING = FILE The second form of the IF command is most often used for interactive control. It tests if the given string exactly matches the first part of the specified file, the remainder of the file, if any, is ignored. An example: NOTE; select the compiler to use by typing '1' when desired IF '1' = :VI: THEN /* PASCAL */ PASC86 %0 ISIS-II SOFTWARE TOOLBOX, V1.0 page 19 ELSE IF '1' = :VI: THEN /* PLM86 */ PLM86 %0 ELSE IF '1' = :VI: THEN /* FORTRAN */ FORT86 %0 ELSE IF '1' = :VI: THEN /* ASM86 */ ASM86 %0 ELSE NOTE; You didn't select any compile, & type '1' if you want to start over again. IF '1' = :VI: THEN LOOP /* Start over again */ ENDIF; ENDIF; This example also shows how nested IF commands and ELSE IF commands (which are explained later) are used. IF commands can be nested to an arbitrary depth. * CAUTION * Be careful not to use :CI: as the input file, because it will cause the next command line to be swallowed. Note that the input file is opened for read. Therefore when :VI: is specified, there is no echoing, and no indication that the system is waiting for input is given; so it is best to limit the input to a single character, and to provide a note to the user Also, IF does does not do any parity checking, so PARITY MAY BE CAUSING IMPROPER CONDITIONAL EXECUTION. If the parity is either odd, even, or always 1, improper comparisons may take place. To avoid this, MAKE SURE PARITY IS SET TO ZERO ON THE INPUT DEVICE. 3. STRING IN STRING The third form of the IF command allows a list of options to be specified in only one parameter. The following command sequence will compile, link and locate, and optionally run a program depending on the parameter input. IF 'C' IN '%1' THEN /* Compile it first */ PLM80 %0.PLM IF NOT ' 0 PROGRAM ERROR' IN %0.LST THEN EXIT; /* Skip the rest of the commands */ ENDIF; ENDIF; IF 'L' IN '%1' THEN /* Link and locate the object */ LINK %0.OBJ,SYSTEM.LIB,PLM80.LIB TO %0.LNK LOCATE %0.LNK PURGE ENDIF; IF 'G' IN '%1' THEN /* Go run it */ %0 ENDIF; ISIS-II SOFTWARE TOOLBOX, V1.0 page 20 SUBMITting the above command file with the parameters (:F3:FOO, CLG) will cause the program :F3:FOO.PLM to be compiled, linked and located, and executed. However, the parameters (:F3:FOO, CL) will not run the final program. (:F3:FOO, C) will only compile it. 4. STRING IN FILE The fourth form of the IF command is used to test the presence of a particular string in a file. The typical use is to detect compilation errors, "unresolved externals" in a Link, etc. Note that when doing this, be careful to put a blank before the '0', otherwise you will think there are no errors when there may be 10 or 20 errors detected. It also works if the NOLIST option is used to cut down on the size of the listing file. This form is slightly different from the second form (explained above) when used for interactive control. Although the test for the presence of a string will work if the input file is a disk file, it will take forever if input is coming from an interactive terminal. That's because the IN form of the command will try to fill the buffer completely before starting the scan, the buffer is about 50K bytes. The second form, on the other hand, only reads in as many bytes as the length of the string, allowing interactive input. 5. FILE COMPARISON The fifth form of the IF command is to compare two files. The comparison is a byte by byte comparison. If the two file names are exactly the same, then the files are considered the same, even if they don't exist. However, if the file names are not the same, then the files are considered the same only if their contents are exactly the same. It is possible to use 'NOT' as the first file name. 6. FILE EXISTENCE The final form of the IF command is used to test the existence of a particular file. Sometimes it is useful to make sure that all the files are available before starting a long complicated job. Also, the existence or absence of files can be used as "boolean variables" vis-a-vis the "IF" family. With this form, since the 'NOT' may actually be a file name, be very careful with the trailing comments; if the word 'NOT' is there, then either follow it with a file name before the comments, or else make sure that 'NOT' is the last item on the command line. STRINGS Strings are character sequences enclosed in single or double quote characters. Non-printable charaters are ISIS-II SOFTWARE TOOLBOX, V1.0 page 21 allowed. If a string is enclosed in single quotes, then the single quote character cannot appear in the string. Double-quoted strings cannot contain a double- quote character. Unfortunately, because the :CI: file is line edited, several characters are not permitted in the string - -CR, LF, ESC, rubout, CNTL-X, or CNTL-Z. The strings are always converted to upper-case first, so looking for a lower-case string in a file will not work. Also since the '&' is used to denote line continuation, it cannot appear in the string either. Continuation lines work like this: the first '&' encountered on a line signals continuation, the rest of the line is discarded and the '&' is replaced with a space. Therefore it is possible to have a string of arbitrary length, so long as it is all upper case and does not contain CR/LF. Null strings are allowed. In the string comparison, null strings are handled like any other string. In the IN conditions, if the first string is a null string, then the condition is automatically true, no matter what the right operand (either another string or a file) is. If the right operand of the IN is a null string, then the condition is also true by default. The IF command evaluates the condition specified. The NOT reverses this condition. If the condition is true, then the sequence of commands following the IF command are executed. If the condition is false, then it will skip the following commands until either an ELSE command or an ENDIF command is encountered. Because of this skipping action, if an ELSE command or an ENDIF command is not found, then it is possible to read past the end of the command file and cause an ISIS error 29. The commands that are skipped are printed (by ISIS, because :CI: automatically echoes to :CO:), but they will be prefixed with an '#' instead of the normal CLI prompt. Imbedded CNTL-E's will cause a break, even if they are in commands that won't be executed. ISIS-II SOFTWARE TOOLBOX, V1.0 page 22 +====================================+ | | | ELSE | | v1.0 | | | +====================================+ The ELSE command is a part of the IF command, the syntax of the ELSE command is: ELSE [IF command] The ELSE command can have an optional IF clause on the same line. If the initial IF command evaluates to false, then it will skip forward looking for the ELSE part. If an ELSE IF command is encountered while skipping, then the second IF condition is evaluated, end interpreted the same as the original IF. This is used to eliminate nesting IF command structures too deeply, it is also quicker because the IF program does not need to be reloaded. If the ELSE command is encountered while executing the commands in the true part of the initial IF command (or the true part of an ELSE IF command), then it will skip all other commands until an ENDIF command (explained below) is encountered. As with the IF command, all the commands that are skipped will be prefixed with '#' instead of the normal CLI prompt. +====================================+ | | | ENDIF | | v1.0 | | | +====================================+ The ENDIF command is also a part of the IF command. It only serves to designate the end of an IF statement. The ENDIF command is required for the semantic integrity of the IF and ELSE commands. However, when loaded and executed, it immediately exits. ISIS-II SOFTWARE TOOLBOX, V1.0 page 23 +===================================+ | | | GOTO | | v1.0 | | | +===================================+ The GOTO command is used to transfer control to any arbitrary point in a command file. The syntax of the GOTO command is: GOTO