S-C Software Corporation 2331 Gus Thomasson, Suite 125 P.O. Box 280300 Dallas, Texas 75228 (214) 324-2050 S-C Cross Reference Utility The S-C Cross Reference Utility (s-C XREF) generates an alphabetized listing of all labels used in a source file, showing with each label the line number where it is defined along with all line numbers which contain references to the label. Features: * Written in assembly language for Apple ][, Apple ][ Plus or Apple //e computers. Fantastic convenience, speed, and efficiency! * Works with the S-C Macro Assembler, properly handling all directives and operand modes. * Compatible with older versions of the S-C Assembler series, including S-C Assembler II Versions 3.2 and 4.0. * Optional cross reference of all directives and opcddes used in your program. * Optional paginated listing of your source program, for complete documentation packages. * Cross reference of all macro calls listed after all labels. * Easy-to-change page length and width parameters. * Full range of line numbers (from 0 through 65535). * Easily-generated EXEC files allow programs consisting of many separate files to be processed in sequence. * Appropriate changes to two small opc ode tables permit processing of source programs for other CPU chips, in conjunction with most of the S-C Macro Cross Assemblers. * Complete commented source code is available to owners of S-C XREF for only $32.50 additional (or total price of $50.00 if source and object code are purchased together.) [ Requires S-C Macro Assembler ] - 1 - --------------------------------------------------------------------- Using S-C XREF S-C XREF is designed to be used from within the normal S-C Assembler environment. S-C XREF assumes that the source syntax is consistent with the S-C Assembler syntax. We recommend that you assemble the source file before running the S-C XREF, to insure that the source is error-free. Invalid assembler source lines may cause S-C XREF to find strange undefined labels. The S-C XREF program BLOADs into the memory area $800-$FFF. The S-C Assemblers normally load at $1000 with the symbol table area following the assembler, or at $DOOO with the symbol table area starting at $1000. S-C XREF uses the symbol table area for developing the cross reference table. 1. S-C XREF operates on the assembly language source file currently in memory. Therefore the first step is to LOAD your source program: :LOAD filename 2. The next step is to load S-C XREF, if it is not already in memory: :BLOAD S-C XREF 3. If you wish to change any parameters, now is the time to do it. The default values select 55 lines per page, 80 columns per line, no source code listing, and no opoode listing. The parameters are in the five bytes from $806 through $80A: $806: Lines per page. $807: Printer width in columns. $808: Set non zero to produce an opcode cross reference listing. $809: Set non-zero to produce a paginated listing of your source program. $80A: Set to 0 to prevent a Cross Reference listing from being generated. For example, to include the opcodes and directives in the listing, type: :$808:1 4. If you wish for the cross reference listing to be sent to your printer, turn on your printer and type: :PR#slot 5. Now execute S-C XREF by typing: :$800G S-C XREF will scan through your source program for a few seconds and then begin displaying a paginated cross reference listing of all the symbols used in the program. If you selected your printer, the listing will be printed. When the listing is finished, control will return to the S-C Assembler. 6. The listing can be aborted at any time by pressing the RETURN key, or paused/restarted with any other key, just as in the S-C Macro Assembler. You can single step the listing by tapping two keys at once. - 2 - --------------------------------------------------------------------- What You Will Get There are four parts to the cross reference listing: 1. Source listing (if enabled). 2. Opcode mnemonic cross reference (if enabled). 3. Label cross reference. 4. Macro call cross reference. 1. The source listing (enabled by parameter $809) consists of a normal listing, such as produced by the LIST command in the S-C Assemblers. The listing will be paginated with page numbers at the top-right of each page. 2. The opcode mnemonic listing (enabled by parameter $808) is separated from the normal label cross reference listing by a line of dashes. The opcodes will be listed in alphabetical order, with directives first. 3. The cross reference listing (enabled by parameter $80A) includes all symbols used in your source program, in alphabetical order. Here is the format: Columns 1-5 : The line number where a symbol is defined. If a symbol appears in the label field of a line, that line number will be shown here. If the symbol is not defined in the current module then "-----" appears in this field. Columns 8-n : The symbol name (up to 32 characters). Columns n-end: The line numbers in the current source module which refer to the symbol. If a symbol has no references in the current module then no line numbers will be printed. Here is an excerpt from a listing: ---- CHRGOT 3340 3830 5570 3210 COLORTBL 3170 1110 SHAPE 1800 1910 2170 2830 2960 3090 3530 4770 7460 11920 12180 12390 ----- SYMBOL.TABLE 2870 12340 12500 ZZ.SIZE If there are too many references to fit on one line, the rest are listed on following lines beginning in column 11. The symbol cross reference listing will include all uses of the indexed addressing modes as references to the symbols "X" and "Y". Any labels "X" or "Y" will also appear in the same reference list with the indexed addressing references. 4. The macro call cross reference listing (also enabled with parameter $80A) follows the symbol cross references. The macro calls are distinguished by a ">" character in front of the name, and are listed in alphabetical order. - 3 - --------------------------------------------------------------------- How S-C XREF Works S-C XREF scans through the source program currently in memory in just one pass. If you have selected a paginated source listing it will be printqd during this pass. S-C XREF parses each source line into a label field, an opcode field, and an operand field. Definitions and references are entered into a symbol table in the same memory area used by the S-C Assemblers for the Assembly Symbol Table. If there is not enough memory for the symbol table below the source program, then a warning message "MEMORY FULL!" is displayed and S-C XREF stops execution. 1. When a label is found in the label field it is added to the symbol table. The current line number is stored in the symbol table entry in the definition position. Local labels (.00 - .99) and private labels (:00 - :99) are ignored. If the label already has been defined then the current line number is entered as a reference to the label (because the listing only has room for one definition line entry). A label can legally have more than one definition only if it is used with a .SE directive, but the Cross Reference program does not enforce this rule. 2. The opcode field is separated from the label field by at least one blank, and ends with a blank or end-of-line. There are five classes of opcodes, and each is handled in a distinct way: * Directives * Macro Calls * Opcodes with no operand field * Opcodes with an optional operand field * Opoodes with a mandatory operand field. Directives are handled by special directive processors, according to the type of data fields which may follow the directive opcode. Some have no possible data fields, some have only one, and others have a list of data items. The .EN directive will terminate the cross reference scan, even if it is not the last line in the source program. The .MA directive DEFINES the label in the data field. Any directives not in the built-in table will be assumed to have no data fields. If the opcode is a macro call it is entered into the symbol table as a reference to the macro. If you have selected the optional opcode cross reference, the opcode reference will be logged. Two tables of opcode names at the end of S-C XREF list the opcodes in categories 3 and 4. Those with no operand field (such as TAX, INY, etc.) are listed first. S-C XREF does nothing further with lines having any of these opcodes. Opcodes which have an optional operand are the four shifts: ASL, ROL, LSR, and ROR. For these ambiguous cases, S-C XREF assumes no operand is present if two or more blanks follow the opcode. 3. Operand fields are scanned to find any references to normal labels. The operand is separated from the opcode by at least one blank, and ends with a blank or end-of-line. The operand scanner skips over constants, parentheses, operators, and other syntax characters to pick out only the normal labels. Local labels (.00 - .99), private labels (:00 - :99), and macro parameters (]O - ]9 and ]#) are ignored. All references to normal labels are duly logged in the symbol table. - 4 - --------------------------------------------------------------------- Using S-C XREF with Multiple-File Programs S-C XHEF can also be used from an EXEC file to generate a Cross Reference for a program too large to be all in memory at once. Each source file can be LOADed in turn and processed. If you elect to generated a source listing at the same time, you can document an entire multiple-file program automatically. For example, the following text file can be EXEC1ed to cross reference a large system program on two diskettes. BLOAD S-C XREF,A$800 PR#1 LOAD EQUATES,D1 $800G LOAD MAIN PROGRAM,D1 $803G LOAD COMMAND HANDLER,D1 $803G LOAD SCAN TEXT,D2 $803G LOAD TABLES,D2 $803G Note that the first call to the S-C XREF is $800G, and each succeeding call is $803G. This causes the page numbers to appear in continuous ascending order, rather than restarting at 0001 with each new source file. If you want a listing and an opcode cross reference of each module, then insert a line like this after the BLOAD S-C XREF command: $808:01 01 This enables the option flags at $808 and $809. Special Entry Points and Parameters There are two entry addresses, to allOw continuous page numbering with successive source files: :$800G -- Main entry point. Page numbers begin at 0001. :$803G -- Successive modules entry point. Page numbers begin at last+1. You can adjust the page length and width with two parameters: $806: Contains the number of lines to be printed on each page. This is normally 55 (hex $37). If you set your printer to 8 lines per inch, you may want to select 76 lines per page (hex $4C). If you are watching it on the screen only, you may wish to select 20 lines per page. S-C XREF prints a formfeed character ($0C) before each page. $807: Maximum number of characters to print on each line (normally 80). You should not set this value below 40. - 5 - --------------------------------------------------------------------- You can select any combination of three optional listings with these three parameters: $808: Opoode cross reference option flag. Default 0. Set non-zero to produce an opcode cross reference. $809: Source code listing option flag. Default 0. Set non-zero to produce a paginated source listing. $80A: Symbol and macro call option flag. Default 1. Set to 0 to omit a Cross Reference listing of symbols and macro calls. About the Source Code Files If you have also ordered the Source Code for the S-C XREF, the disk contains the following additional files: S.ACF Assembly Control File S.XREF.1 Main Code - 1 S.XREF.2 Main Code - 2 S.XREF.6502 6502 Opcode Tables and XREF CONTROL FILE EXEC File to Cross-Reference S-C XREF To assemble S-C XREF just LOAD S.ACF into the S-C Macro Assembler, change the .TI directive in line 1000 as necessary, and assemble it. The .IN directives will load in the other files as they are needed. S.XREF.1 and S.XREF.2 are the body of the code for the program. S.XREF.6502 contains the lists of 6502 opcodes which have no operands, or optional operands. This is the file to change if you want to use S-C XREF with one of the Cross Assemblers. XREF CONTROL FILE is an example of an EXEC file to control the cross reference of a multiple-file source program. It contains the commands to produce a cross reference of the S-C XREF Source Code. - 6 - ---------------------------------------------------------------------