Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 283.lha / ReSource_v3.01_Demo / Reference.doc < prev next >

Wrap

Text File | 1989-09-07 | 80.8 KB | 1,854 lines

Reference ReSource (C) 1988 Glen McDiarmid The documentation for ReSource is in two parts. This is the specifications for each function, in the order in which they appear in the menus, the other is the introduction. PROJECT/Abort: Use this to abort out of searches and macros. This is the only function in ReSource which should NOT be bound to a different key. It is permanently bound to right-Amiga A, for "Abort". PROJECT/Open load file: ReSource will request you for the name of a file to open. When you select a file and press "return" or click on the "okay" gadget, ReSource will attempt to load the file as an executable, or "load" file. If there is any debug symbols in the executable, these will be stored, and will become labels, at the appropriate places in the file. Relocation is performed where required. If the file has overlays, the load will fail, as overlays are NOT supported in this release of ReSource. For each debug symbol encountered, it is attached to the appropriate byte in the file, and for those debug symbols (labels) that are nine characters long, and start with "lb", immediately followed by 'A', 'B', 'C', 'L', or 'W', the data type at the appropriate byte will be set to Ascii, Bytes, Code, Longwords, or Words, respectively. Any BSS hunks or uninitialized data areas found are expanded fully. Where relocation has been performed, you can have hilited, by selecting "DISPLAY/ Hiliting/Reloc32". You are limited to files smaller than 16 Megabytes, and further limited by how much memory you have. To disassemble a 100K file, you will require approximately 850K or memory, of which at least 400K must be continuous. If the file has large BSS hunks, this will greatly increase the memory requirements. If you intend to load a file, do some zaps, then save it and later run it, use "PROJECT/Open binary file" instead, otherwise the file will get saved with the loader information stripped out of it. PROJECT/Open binary file: Similar to "PROJECT/Open load file", except that no translation of the file is performed, the file is read in "as is". This allows you to see the loader information in executables, object files, etc. You can also load in text files, data base files, in fact any file whatsoever, memory permitting. If you select "PROJECT/Open load file" for a non-executable file, the file will be loaded as a binary image instead, therefore "PROJECT/Open binary file" is not really required except when you wish to force an "as is" load for an executable file. If you wish to do some zaps (small modifications) to an executable file, without going through the disassemble-edit-reassemble-link cycle, you could load the file with this function, do the zaps (see "SPECIAL FUNCTIONS/Zap"), then use "SAVE/Save binary image/ All" to save the modified program. PROJECT/Restore: Useful only when the current buffer was loaded using "PROJECT/Open binary file" or "PROJECT/Open load file". This function will attempt to load a file, with the same name as the current file, using the same function that loaded the current file originally. Do not use this function if the current buffer was loaded from tracks, or directly from memory. PROJECT/Dismble memory: Disassembles a block of memory directly. You will be requested to supply a start and end address, for the memory region to be disassembled. The memory is NOT copied to a seperate buffer, it is disassembled as-is, which means that you if you hold the left mouse button down, in some areas, you can see the memory being dynamically updated. It also means that you can make modifications directly to anywhere in memory. For each address that you supply, if the number starts with a "$", the number is assumed to be hexadecimal. If it starts with "%", it is assumed to be a binary number. If neither, decimal is assumed. If you wish to disassemble a copy of a block of memory, disassemble the memory directly, use the "PROJECT/Save .RS" function, and then use "PROJECT/Open load file" to load the .RS file. PROJECT/Read tracks: You will be requested to supply the parameters for the track read. The first parameter is either "DF0:", "DF1:", "DF2:", or "DF3:" (lower case is okay). This represents the drive that holds the disk to be read from. The second parameter is the number of the cylinder to start reading from. The third parameter is the number of the last cylinder to be read, plus one. For example, if you wanted to read the first cylinder from the disk in DF0:, the parameters would be "DF0: 0 1". The fourth parameter is optional, and represents the number of extra sectors to read. For example, if you wished to read only the very first sector from DF1:, the parameters would be "DF1: 0 0 1". If you wished to read the first sector from the directory track of DF2:, the parameters would be "DF2: 40 40 1". The fifth parameter is also optional, and it represents the sector offset, to start the read. For example, if you wished to read sectors nine and ten on cylinder 79 of the disk in DF3:, the parameters would be "DF3: 79 79 2 9". PROJECT/Save .RS: Use this function to save what you are currently working on, regardless of how far you have gone in disassembling it. EVERYTHING is saved, even your current position within the file. Actually, if you disassemble the Amiga operating system directly, the .RS file that you create will NOT contain the executable, therefore the .RS files can be legally distributed, as they contain no copyrighted material. This is not the case for other .RS files, as the executable will be saved along with other information. PROJECT/About: Get information about the version number, author, agents, and people that helped in the development of ReSource. PROJECT/Quit: Asks you for confirmation, then quits without saving. If used within an executing macro, will NOT ask the operator for confirmation. DISPLAY/Hiliting/None: Use the hiliting functions to select attributes for which the data with those attributes will be shown with the foreground/background colors inverted. Selecting this function will disable all types of hiliting. DISPLAY/Hiliting/BSS hunks: Data within BSS hunks and uninitialized data areas will be hilited. DISPLAY/Hiliting/Data hunks: Data within data hunks will be hilited. Data hunks often will contain only data constants, but may also contain code. DISPLAY/Hiliting/Code hunks: Data within code hunks will be hilited. Code hunks often will contain only code, but may also contain data constants. DISPLAY/Hiliting/Chip load hunks: Data within code or data hunks that MUST be loaded into chip memory (only) will be hilited. Data falling into this category will usually be graphics or sound data, to be accessed directly by the blitter, copper or DMA. DISPLAY/Hiliting/Fast load hunks: Similar to the above function, except that the data is forced to load into FAST memory only. DISPLAY/Hiliting/Reloc32: Being able to see where relocation has been performed is extremely useful when disassembling a program. If it were not for the relocation information, disassembling programs would be many times harder. ReSource makes use of this information internally, especially when filling in data types. DISPLAY/Hiliting/Symbol scan: When you use the "LABELS/Create single/Label - fwd ref" or "LABELS/Create multiple/All", all data scanned for references are marked as being scanned. Use this function to hilite data falling into this category. DISPLAY/Hiliting/Data type uncertain: For most labels that ReSource creates automatically, it is certain of the data type that it assigns. Sometimes though, it cannot be 100% sure, and this function will hilite all lines that fall into this category. DISPLAY/Hiliting/Data type known: Similar to above function, only the lines where the ReSource WAS certain of the data type, will be hilited. DISPLAY/Hiliting/Internally produced refs: All lines which have a label that was created by ReSource, rather than directly by the user, will be hilited. DISPLAY/Set data type: When you are certain of which type of data that you are looking at, select from one of the submenu items: Code - Ascii - Bytes - Words - Longwords DISPLAY/Set numeric base: By default, all numbers are shown in hexadecimal (base 16). You can change this to ASCII, DECIMAL or BINARY on any line by selecting from the appropriate sub-menu item, or back to HEXADECIMAL. It is possible to change the default to decimal for numbers less than 16, or less than 10, using the decimal conversion function (see below). DISPLAY/Decimal conversion: By default, all numbers are shown in hexadecimal. You can have numbers less than 16, or numbers less than 10, shown in decimal throughout the file, by selecting one of the appropriate sub-menu items. DISPLAY/Blank lines/: To better define subroutines, and logical blocks of code, ReSource can insert a blank line after each conditional branch or unconditional branch. DISPLAY/Cursor address/Relative: The cursor address will be shown in hexadecimal in the title bar, as an offset from the start of the file. DISPLAY/Cursor address/Absolute: The cursor address will be shown in hexadecimal in the title bar, as an absolute machine address. This allows you to quickly find the cursor position in memory with other utilities, such as Metascope, perhaps to carry out large scale modifications. DISPLAY/Titlebar info/Filename: Information displayed in the title bar is in several fields. The first, from the left, is the program name. The second is a decimal number, representing the cursor position, relative to the file size, and is a percentage. The next field is a hexadecimal number, representing the cursor position, and can be shown either as an offset from the start of the file, or as an absolute memory location. The next field is the one that this function relates to. By selecting this function, the current file name will be shown. If user feedback is ON, informative messages will sometimes be shown in this field also. DISPLAY/Titlebar info/Attributes: The third field of the title bar will display information representing the current attributes of the cursor byte. This information is NOT required for general program usage, and was originally included for debugging purposes only, and left in to satisfy those that want to know how the attributes table in ReSource works. The attributes table is four times the size of the current file, plus 16 bytes. It is used internally as a large bitmap, to store information about each and every byte in the current file. Because it is four times the size, 32 bits are available for each byte in the current file. For each character in the string displayed, if lower case, the bit that that character represents is clear, if upper case, the bit is set. Going from the left, the bit definitions are: S : Start of a line of code/data B : Bss hunk D : Data hunk C : Code hunk R : Reloc32 area F : First byte of reloc32 area L : Label attached to this byte S : Symbol attached to this byte F : Full-line comment attached to this byte E : End-of-line comment attached to this byte P : Parsed previously (symbol scan) I : Internally referenced L : Low priority. The data type has been set, but can be overridden by internal routines. The data type can always be overridden by the user. This bit is generally set when ReSource has to decide on a data type to set for a byte, but when it does so, it wasn't really sure that it was correct. A : Show numeric operands as ASCII if possible. Decimal conversion is on a higher priority than this bit. B : Show numeric operands as Binary. Decimal conversion is on a higher priority than this bit. D : Show numeric operands as Decimal if possible. F : Data in this hunk is to be loaded into FAST memory only. C : Data in this hunk is to be loaded into CHIP memory only. (next 4 bits are reserved for future use) U : User should check the data type that has been set, as ReSource wasn't really sure that it chose the correct one. Use "CURSOR/Relative/Next unsure D/T" to find the next occurrence, if the cursor is already over one when you use that function, it will clear this bit. H : High priority. The data type has been set either by the user, of by ReSource, when it was quite certain that it set the data type correctly. This does not mean that it cannot make mistakes, it simply means that if some operation attempts to set the data type for this byte, it will NOT override the currently set data type. This does not stop the user from redefining the data type, however. C : Code. dddd : Data type hasn't been set yet ddDd : Data type is bytes dDdd : Data type is words dDDd : Data type is longwords Dddd : Data type is bytes, within a BSS hunk or uninitialized data area. DddD : Data type is ASCII DDDd : Data type is words, within a BSS hunk or uninitialized data area. DDDD : Data type is longwords, within a BSS hunk or uninitialized data area. DISPLAY/Titlebar info/Accumulator: The third field of the title bar will display information representing the contents of the ACCUMULATOR. This is a 240 byte buffer, used as a central number and string processor, which will find most of its uses within macros. Only the first 30 characters or so can be shown in the title bar, however often the string will not be any longer than that anyway. For more information on the accumulator, see the functions within the STRINGS menu. DISPLAY/Wrap/ON: Any lines longer than the current display width will be shown on several lines, much the same way that text editors allow you to use word wrap. DISPLAY/Wrap/OFF: Any lines longer than the current display width will be truncated. DISPLAY/Block-fill: Some background information is required here: ReSource internally keeps a stack of cursor locations. The current cursor location is "pushed" onto this stack with the following functions: CURSOR/Remember CURSOR/Absolute/End of file CURSOR/Absolute/Start of file CURSOR/Absolute/Forward reference CURSOR/Absolute/Second forward reference CURSOR/Absolute/Backward reference To "pop" a cursor location, you use the function "CURSOR/ Absolute/Previous location". The stack is cleared when you load a new file. The stack is NOT stored within .RS files. Block-fill uses the cursor location stored on the top of this cursor location stack, finds out what the data type at that location has been set to, and copies that data type to all locations between there and the current cursor location. It has several disadvantages, and should be used only when special display effects are required. For example, if you wish to display a file as bytes throughout, even though much of it is actually code or ascii, this function may come in handy. DISPLAY/Fill-in data types: This function has several uses, and will be one of the most- used functions. To understand what this function does, you will need to know how ReSource keeps track of data types. Suffice it to say, when you set the data type anywhere within a file, that data type is immediately echoed forward, to a maximum of several hundred bytes, but will not change any other places where the data type has already been set, or where there is a label on a line. Where there is large areas of a file where the data type has not been set, this function attempts to set the data type where appropriate. All of the above is done in the first pass. On the second pass, the length of each line is set, this is particularly useful where there is large areas of ASCII. This function should always be used before saving a file as source code. DISPLAY/Fill-in D/T Fwd: Similar to the above function, except that both passes will start from the current cursor location, and NOT the start of the file. DISPLAY/Set counter: If cursor address has been set to "relative", the current offset in a file is shown in the title bar, in hexadecimal. This is normally zero at the start of the file. You can change this, so that it is zero at somewhere other than the start of the file, by using this function. You may use this function to measure the size of a hunk, for example. To "reset" the counter, use the function "DISPLAY/Reset counter". If cursor address has been set to "absolute", it will correctly display the current address of the cursor, regardless of this function. DISPLAY/Reset counter: Similar to the above function, except that the cursor position is assumed to be at the start of the file. DISPLAY/Flip case - code: If code is currently being displayed using upper case, it will be instead shown in lower case, and vice versa. Note that all searches are case sensitive. DISPLAY/Flip case - data: If data is currently being displayed using upper case, it will be instead be shown in lower case, and vice versa. SYMBOLS: Some background information is required here: When you assemble a program, you will use symbols such as "_LVOAllocMem", "MEMF_CHIP", "Open", "MODE_OLDFILE", etc. When you disassemble a program, you see only the numbers that equate to the symbols that you used. To convert these numbers back into strings, you basically tell ReSource what the "symbol base" is, and it will do the rest. For example, in the following line: JSR -$0228(A6) the number "-$0228" could be interpreted in many different ways. If you happened to know that the A6 register at that point in the program was pointing to the Exec library base, you should interpret that line as: JSR _LVOOpenLibrary(A6) To make ReSource do this automatically, you would scroll so that this line became the cursor line, and then select the function "SYMBOLS 1/Libraries/Exec", or "SYMBOLS 2/E-G/Exec library. There are hundreds of other symbol bases that are available, including libraries, devices, structures, parameters, and error code names. By default, the number used to find the string will come from the cursor line. You can instead have ReSource get the number from the accumulator, by selecting "SYMBOLS 1/Object/Accumulator". In this case, the output string will be placed back into the accumulator. Examine the following line of code: MOVE.L #-$0228,$0022(A6) If you wished to create a symbol for the second number in this line ("$0022"), you should first select "SYMBOLS 1/ Select field/Second". The setting of "Select field" will go back to "First" with virtually any function you use, therefore when creating a symbol for the second field in a line of code, use "SYMBOLS 1/Select field/Second" only just prior to actually creating the symbol. Some special symbol bases are in the "SYMBOLS 1" menu, the rest are in alphabetical order in the "SYMBOLS 2" menu. CURSOR/Remember: ReSource keeps a stack of cursor locations internally. Using this function will "push" the current cursor location onto the top of this stack. Other functions that call this function are: CURSOR/Remember CURSOR/Absolute/End of file CURSOR/Absolute/Start of file CURSOR/Absolute/Forward reference CURSOR/Absolute/Second forward reference CURSOR/Absolute/Backward reference To "pop" a cursor location, you use the function "CURSOR/ Absolute/Previous locations". The stack is cleared when you load a new file, or when you select "CURSOR/Clear loc stack". The stack is NOT stored within .RS files. CURSOR/Clear loc stack: See above function. CURSOR/Relative/Next byte: The cursor location is incremented. If at the last location within the current file, a macro "fail" will result. CURSOR/Relative/Previous byte: The cursor location is decremented. If at the first location within the current file, a macro "fail" will result. CURSOR/Relative/Next line: Scroll forward one line of code/data. If at the last line of code/data in the file already, a macro "fail" will result. The speed at which this scroll is done is set by the "CURSOR/Scrolling speed" settings. CURSOR/Relative/Previous line: Scroll backwards one line of code/data. If at the first line of code/data in the file already, a macro "fail" will result. The speed at which this scroll is done is set by the "CURSOR/Scrolling speed" settings. CURSOR/Relative/Next label: Move cursor to the next location that has a label attached to it. If one cannot be found, a macro "fail" will result. CURSOR/Relative/Previous label: Move cursor to the previous location that has a label attached to it. If one cannot be found, the start of the file will become the new cursor position. CURSOR/Relative/Next symbol: Move cursor to the next location that has a symbol attached to it. If one cannot be found, a macro "fail" will result. Note that this location may be in the middle of a line of code. Where the actual operand is stored, that will become the new cursor position. CURSOR/Relative/Previous symbol: Move cursor to the previous location that has a symbol attached to it. If one cannot be found, the start of the file will become the new cursor position. Note that this location may be in the middle of a line of code. Where the actual operand is stored, that will become the new cursor position. CURSOR/Relative/Next section: Move cursor to the start of the next section (hunk). If this is the last section in the file, a macro "fail" will result. CURSOR/Relative/Previous section: Move cursor to the start of this section (hunk). If already at the start of a section, move to the start of the previous section. CURSOR/Relative/Next reloc32: Move cursor to the start of the next relocated longword. If one cannot be found, a macro "fail" will result. Note that this may be in the middle of a line of code. CURSOR/Relative/Previous reloc32: Move cursor to the start of the previous relocated longword. Note that this may be in the middle of a line of code. If one cannot be found, the start of the file will become the new cursor position. CURSOR/Relative/Next page: Move cursor forward 24 lines. CURSOR/Relative/Previous page: Move cursor backwards 24 lines. CURSOR/Relative/Skip forward: Move cursor forward approximately 4K. CURSOR/Relative/Skip backward: Move cursor backward approximately 4K. CURSOR/Relative/Next unparsed code: Move cursor forward to the next location that satisfies both of the following conditions: 1> The data type has been set to CODE 2> This location has NOT been scanned for forward references previously. This function is useful when combined with the "LABELS/Create multiple/All" function. CURSOR/Relative/Next D/T change: Move cursor to the next location that has it's data type set differently to the current cursor location. CURSOR/Relative/Previous D/T change: Move cursor to the previous location that has it's data type set differently to the current cursor location. CURSOR/Relative/Next backward reference: Once you have used the "CURSOR/Absolute/Backwards reference" function, you can use this function to get to other backward references. CURSOR/Absolute/End of file: Move cursor to the start of the last line of the file. CURSOR/Absolute/Start of file: Move cursor to the start of the file. CURSOR/Absolute/Forward reference: If there is a reference to a position in the current file, within the current line of code, move cursor to the location being referenced. If there is two forward references within the current line, the first is used. CURSOR/Absolute/Second forward reference: If there is two references to a position with the current file, within the current line of code, move cursor to the second location being referenced. If there is only one forward reference, a macro "fail" will result. CURSOR/Absolute/Backward reference: Starting from the start of the file, search for references to the cursor location. If there is several references, you can use "CURSOR/Relative/Next backward reference" to get to successive references. CURSOR/Absolute/Previous location: "Pop" the cursor location from the top of the cursor location stack. If the stack is empty, a macro "fail" will result. CURSOR/Absolute/Specify offset: You will be requested to supply an offset representing how far from the start of the file, the cursor location should be. The number may be specified in hexadecimal, decimal, or binary. If hexadecimal, the string must start with "$", if binary, it must start with "%". If the given offset is not within the current file, this function will fail. CURSOR/Absolute/Specify label: You will be requested to supply the name of a label. If the label is used within the current file, where it is will become the new cursor location. Note that this may be in the middle of a line of code. CURSOR/Absolute/Specify symbol: You will be requested to supply the name of a symbol. If the symbol is used within the current file, where it is will become the new cursor location. Note that this may be in the middle of a line of code. CURSOR/Absolute/Specify percentage: You will be requested to supply a number between 0 and 99, representing a percentage into the current file, where the cursor will be positioned. Note that this may be in the middle of a line of code. The actual positioning will not be exact, it will be generally be placed a little before the required percentage. CURSOR/Copy/: Some background information is required here: ReSource has 3 internal cursor "clipboards". You can copy a cursor location to any of these, and then later "paste" one of these locations, which in effect moves the cursor to where it was when you used the "copy" function. Also, you can swap cursor locations, between the current, and a stored cursor location. The contents of these cursor "clipboards" are cleared when you load a new file, or restore the current one. CURSOR/Paste/: See "CURSOR/Copy/". CURSOR/Swap/: See "CURSOR/Copy/". CURSOR/Scrolling speed/Very fast: Whenever you use either "CURSOR/Relative/Next line" or "CURSOR/Relative/Previous line" functions, the text on the display will move 8 display lines (NOT text lines) at a time. This is how most text editors, word processors, etc., scroll text. CURSOR/Scrolling speed/Fast: Whenever you use either "CURSOR/Relative/Next line" or "CURSOR/Relative/Previous line" functions, the text on the display will move 4 display lines (NOT text lines) at a time. CURSOR/Scrolling speed/Normal: Whenever you use either "CURSOR/Relative/Next line" or "CURSOR/Relative/Previous line" functions, the text on the display will move 2 display lines (NOT text lines) at a time. This will give reasonably smooth scrolling, allowing you to read text fairly easily WHILE it is scrolling. CURSOR/Scrolling speed/Slow: Whenever you use either "CURSOR/Relative/Next line" or "CURSOR/Relative/Previous line" functions, the text on the display will move 1 display line (NOT text line) at a time. This gives extremely smooth scrolling, allowing you to easily read text WHILE it is scrolling. CURSOR/Scrolling speed/Very Slow: Whenever you use either "CURSOR/Relative/Next line" or "CURSOR/Relative/Previous line" functions, the text on the display will move 1 display lines (NOT text line) at a time, with a short delay after each move. This gives exceptionally smooth scrolling, and is excellent for slowly browsing through a file. CURSOR/Normal search/Set search string: You will be requested to supply a string, which will be used in future searches. Like all other string requests, you may instead supply a two byte string, starting with escape, and followed by either another escape character, or a letter a- m, representing a string buffer where the string should be copied from. If you supply escape-escape as the string, the string currently in the accumulator will be copied into the search string buffer. CURSOR/Normal search/Find next occurrence: Using the currently defined search string, search forward for the next occurrence of that string. The string is searched for as-is, including question marks, asterisks, etc., which in a pattern search take on special meaning. CURSOR/Normal search/Find previous occurrence: Similar to the above function, except that the search proceeds backwards. CURSOR/Normal search/Find nearest occurrence: Similar to the above function, except that the search proceeds in both directions at the same time. The search is done line-for-line, and the first line that contains the search string, whether it be before the current cursor or after, will become the new cursor location. This function is handy when you know that a string is somewhere close, but you're not sure whether it may be just past, or just before, the current cursor location. CURSOR/Normal search/Search this line: This function is useful in macros, for determining whether a given string is within the current line. If the search string is not found in the current line, a macro "fail" will result, and unless your macro has prepared for this condition with an "End conditional" directive, the macro will abort. CURSOR/Normal search/Search accumulator: Similar to the above function, except that the accumulator is searched. CURSOR/Pattern search/: These functions are identical to their counterparts above, except that normal ARP wildcard characters take on their true meaning: ************************************************************ ARP and Wildcards ARP has an extensive set of wildcards, and most ARP programs allow them to be used. ARP supports ALL of the AmigaDOS set of wildcards, as well as the more standard Unix* style of wildcards. ARP supports the following wildcard characters, note that these are valid inside or out of quotes: (a|b|c) Will match one of a, b or c. These can be patterns. ? Matches any single character #<pat> Pattern repeated 0 or more times, in particular, #? matches anything. [char] A set of characters, for example, [abc] or [a..c] specify the same set. [^char] Match everything but this set of characters. * 0 or more occurrences of any character. These can be used in combination, of course, so that *.(c|h) or *.[ch] will match any filenames ending in either .c or .h preceded by any number of characters, including no characters. *********************************************************** LABELS/Create single/End-of-line comment: You will be requested to supply a string of less than 240 characters, which will become a comment to be attached to the end of the cursor line. Only one end-of-line comment is allowed per line, if you create one on a line that has already got one, it will replace the old comment. LABELS/Create single/Full-line comment: You will be requested to supply a string of less than 240 characters, which will become a comment to be attached to the start of the cursor line. Multiple full-line comments are allowed, and successive comments will be displayed AFTER previously-defined full-line comments. Normally, full-line comments will be displayed starting with a semicolon (";"). However, if you start the string with a semicolon, the logic is reversed, and it becomes an extra line of code/data. Thus, you can insert extra lines of code/data, even before saving the source code to a text file. By creating a label that starts with a semicolon for a given line, when that code is assembled, that line of code/data is effectively treated as a comment only, therefore you can both insert and effectively remove code/data using ReSource, during the disassembly process. LABELS/Create single/Label: You will be requested to supply a string of less than 240 characters, which will become a label to be attached to the cursor line. Duplicate labels are NOT allowed, unless they start with a semicolon (";") or an asterisk ("*"). In this case, they effectively make the rest of the line a comment. If this function is used within a macro, duplicate labels WILL be accepted. LABELS/Create single/Label - fwd ref: The current line of code will be searched for references to positions within the current file. If any are found, ReSource will make a decision on which type of data is at the position referenced, it will then set the data type (unless it has already been set), and create a label at that offset (unless a label has already been defined for that address). This new label will be immediately used for all references to that location, which of course includes the reference within the current line. If there is no references, or there is a reference, but it is outside of the range of the current file, then this function will do nothing. Normally, this function will only be used within macros, as it is easier and quicker to hold down the left Amiga key, while holding down the left mouse button, possibly while scrolling also. LABELS/Create single/Symbol: You will be requested to supply a string, which will replace the first encountered number in the current line. For example, if you supplied the string "MyColdStartData", the following line: MOVE.L D0,4(A0) would become: MOVE.L D0,MyColdStartData(A0) If there is more than one number mentioned in the current line, the first is used. If there is no numbers in the current line, a macro "fail" will result. LABELS/Create single/Symbol - dest: Similar to the above function, except that the second number in the current line will be replaced with the string that you supply. If there is only one number, or if there is no numbers in the current line, a macro "fail" will result. LABELS/Edit single/: Similar to their above counterparts, except that if there is already a label/symbol/comment defined, you will have the chance to edit that string, rather than type the entire new string into the requester. Like all requests for a string, you can use indirection, so that ReSource gets the string from either the accumulator, or from one the buffers A-M. See the section on the STRINGS menu for more details. LABELS/Replace single/Label: Create a "shop" label at the cursor position. LABELS/Remove single/Label: Removes the label from the cursor position. LABELS/Remove single/Symbol: Removes any symbols in the current line. LABELS/Remove single/End-of-line comment: Removes the end-of-line comment from the current line, if any. LABELS/Remove single/Full-line comment: Removes the first full-line comment attached to the current line. LABELS/Remove single/All: Removes any label, symbols, comments from the current line. Also, the data type for the current cursor position is set to 'undefined', and the 'start of line' bit is cleared. LABELS/Create multiple/Reloc32: For each reloc32 pointer within the current file, determine the data type being referenced, set the data type, and create a label at that address. This function should be used with caution, as when it makes a decision on the data type, it does not have the same information available as when creating labels normally. This function should be most useful after creating labels from all code in a program, where there is one or more large tables of pointers. LABELS/Create multiple/All: Starting at the current address, the "LABELS/Create single/ Address symbol dest" function is executed, and if ReSource thinks that there was valid code in the current line, the "CURSOR/Relative/Next line" function is executed, and the entire function loops, otherwise the "PROJECT/-=Abort=-" function is executed. This function can make the disassembly process very fast, the disadvantage being that there is a very slight chance that what ReSource thinks is valid code, is really ascii, and invalid labels will be created. LOCAL MACROS/ and GLOBAL MACROS/: Much background information is required here: The macro facilities available in ReSource are quite extensive. There is a maximum of 38 macros available 'on tap'. These are divided into two banks of 19 macros, called "LOCAL MACROS" and "GLOBAL MACROS". The idea here is that the 'local' macros are for your own personal use, and global macros are meant to be distributed to others. Therefore, you can load a 'global macros' file, and use them, but still have access to your own personal macros. The 19th local macro is special, in that it is executed when you first run ReSource, after the first file is loaded. This macro will often contain functions to set the various options to your personal tastes, but may contain anything you care to put into it. When you first create a macro, you will be requested to supply a name for the macro that you are just about to create. This name will be shown in the menus immediately after, and if you save that bank of macros to a file, the names of the macros are also saved. The functions "LOCAL MACROS/Execute/-unused-" and "GLOBAL MACROS/Execute/-unused- " are used to give each bank of macros a name. These names are also saved when you save a bank of macros, and when you load the macro file later, these names will immediately appear in the menus, making it much easier to remember what previously created macros did. The size of a macro is determined only by how much memory you have. To create a macro, select one of the sub-menu items in "LOCAL MACROS/Create/End/" or "GLOBAL MACROS/ Create/End/". If the current name for the macro is "-empty- ", you will be requested to supply a new name for the macro. If you create a macro of zero length, the name for that macro will go back to being "-empty-". To execute the macro, simply select the appropriate sub-menu item in "LOCAL MACROS/Execute/" or "LOCAL MACROS/Execute/". You have control over the speed at which macros execute. If you select "LOCAL MACROS/Execution speed/Fast", the macro will execute with no delays in between executing functions. The display will be refreshed (updated) after each and every function executed. If you want the macro to execute without the display being refreshed, select "LOCAL MACROS/Execution speed/Very fast". If you select "LOCAL MACROS/Execution speed/Slow", the display will be refreshed after each function executed, and there will be a delay for approximately one tenth of a second also. By selecting "LOCAL MACROS/Execution speed/Very slow", this delay will be increased to around one half second. To have complete control over execution of the macro, select "LOCAL MACROS/ Execution speed/Wait on mouse". With this selected, you must press and release the left mouse button for each and every function within the macro to be executed. This is an excellent way to find bugs in a macro that you (or someone else) has created. Macros may be nested within macros, provided that the nesting depth does not exceed (approx.) 30. While you are creating a macro, you might find that you have to execute some functions to continue the macro definition, but you don't want them included in the macro itself. When this occurs, select "LOCAL MACROS/Suspend learn/suspend", select the various functions that need to be done, then select "LOCAL MACROS/Suspend learn/Normal" to continue the macro definition. There are many functions that will make a macro fail, when it is executed. For example, using a cursor movement function that would place the cursor outside of the current file, will cause a macro fail. A failed search will also cause a macro 'fail'. When executing a macro, if ReSource detects a macro fail, it searches forward in the macro definition for a "Conditional end" directive. Is none is found, all macro processing aborts immediately. If one IS found, macro processing continues normally from that point in the macro definition. If, while searching for a "End conditional" directive, a "Start conditional" directive is found, the next "End conditional" is skipped. Thus, conditional macro processing may be nested. There is five macro labels available. These are placed into the macro definition, and you can insert "goto previous macro label" and "goto next macro label" directives into the macro definition, which when found, will start a search either forwards or backwards, for the appropriate macro label. When found, macro processing will proceed normally from that point forward. Thus, you can loop a macro. If a search is made backwards for a macro label that is non- existent, macro processing will continue from the start of the macro definition. If a search is made forwards for a macro label that is non-existent, the macro will exit, possibly to another macro that called this one. For example, the following macro will continuously scroll forward to the end of the file, then scroll backwards, one line at a time, to the start of the file, then forwards to the end of the file again, etc., indefinitely, stopping only when you select "PROJECT/Abort": LOCAL MACROS/Set macro label/#1 CURSOR/Relative/Next line LOCAL MACROS/Previous macro label/#1 LOCAL MACROS/Directives/End conditional LOCAL MACROS/Set macro label/#2 CURSOR/Relative/Previous line LOCAL MACROS/Previous macro label/#2 LOCAL MACROS/Directives/End conditional LOCAL MACROS/Previous macro label/#1 Notice that the directive "Start conditional" was not required in the above example, as conditional sections were NOT nested. When you are creating a macro, and you are requested for a string (even the name of a file to load), if you select "okay" or press return after supplying a string, the string will be stored in the macro definition, and will be used when the macro is later executed, unless at the time that you execute the macro, "LOCAL MACROS/Interactive/" has been set to "ON". In this case, you will be prompted for any strings that are requested during the execution of the macro. Normally, this will not be required, but it does give you more control over an executing macro, especially if it was created by someone other than yourself. If, when creating a macro, you are requested for a string, and you want to force the user to input a string during the execution of the macro, you should select the "cancel" gadget in the string requester. Any string that you typed into the requester will still be used while creating the macro, however when the macro is executed, the user is forced to input a new string each time, even though 'Interactive' may be set to "OFF". Instead of actually supplying a string literal to a string requester, you may instead use indirection, to force the string to get copied from either the accumulator, or from one of the buffers A-M. For example, if the accumulator contains the string "MOVE", and you wish to create a label called "MOVE", select "LABELS/Create single/Label", and when requested for the label name, press the escape key twice, and select the "okay" gadget, or press "return". If the required string was in buffer C, instead of pressing the escape key twice, you would press it once, followed immediately by "C". Buffers A-M are simply 13 seperate 240-byte string buffers, which you can store any strings in that you like. A more appropriate name might be 'text registers'. Buffers L and M are special, in that if you select "STRINGS/Define string/ M", if buffer L is not empty, the string contained in it will be used as the prompt, in the requester. This is handy during macros, where you want to get a string from the user, the user can see what the string is required for. Normally, every function that you put into a macro definition, will be executed. This does not have to be the case always. The "LOCAL MACROS/Commentary/" functions set the commentary level. When creating a macro, if you set the commentary level to "None", it is like specifying "The functions following are absolutely essential to the execution of this macro". If you set the commentary level to "Full" during the creation of a macro, you are specifying "The functions following are by no means required, they are simply running commentary, perhaps explaining what the hell is happening in the macro at this point". Thus, by setting the commentary level during the creation of a macro, you are letting ReSource know how important the functions are, that follow. The commentary level may be changed many times during a macro, and for tutorial macros, such as showing someone how to disassemble/zap a particular program, the commentary level should be set appropriately. When it comes time to execute the macro, if the commentary level is set to "Full" by the user before the macro starts executing, ALL functions within the macro will be executed normally. If the commentary level was set to something other than "Full", only those functions in the macro that were set to a commentary level lower than that presently set, will be executed; the rest will be skipped over. Examine the following example macro: LOCAL MACROS/Commentary level/Full CURSOR/Relative/Next line LOCAL MACROS/Commentary level/Heavy CURSOR/Relative/Next line LOCAL MACROS/Commentary level/Normal CURSOR/Relative/Next line LOCAL MACROS/Commentary level/Light CURSOR/Relative/Next line LOCAL MACROS/Commentary level/None CURSOR/Relative/Next line If you set the commentary level to "None" and execute this macro, the cursor will move down one line. If you set the commentary level to "Light", and execute this macro, the cursor will move down two lines. If you set the commentary level to "Full" and execute this macro, the cursor will move down five lines. Using the "SPECIAL FUNCTIONS/Dos command" function, you can use the "SAY" command, to add speech to macros, to give excellent running commentary to tutorial macros. While executing a macro, if you have set the execution speed to "Wait on mouse", you can use other functions, perhaps to scroll backwards or forwards, to see what effect the last function had on the file. When you press the left mouse button to single-step the next function in the macro, the cursor address is restored, in case you didn't return the cursor to the appropriate place within the file. If this was not done, macro processing would not proceed normally from that point on. When you load a macro file, only one bank of macros are affected. If the macro file only contains one macro, then only one macro in that bank will be overwritten, the rest will remain untouched. Thus, it is possible for a macro in the "LOCAL MACROS" bank to load other local macro files, giving an "overlay" effect. STRINGS/Get/Label: If there is a label defined at the cursor location, it will be copied into the accumulator. STRINGS/Get/Symbol: Copy the first symbol on the current line to the accumulator. STRINGS/Get/Symbol - dest: Copy the second symbol on the current line to the accumulator. STRINGS/Get/Symbol value: Get the value of the first number in the current line, and write text into the accumulator, representing that value, in hexadecimal. The 'operand size' will be set by this function. STRINGS/Get/Symbol value - dest: Get the value of the second number in the current line, and write text into the accumulator, representing that value, in hexadecimal. The 'operand size' will be set by this function. STRINGS/Get/End-of-line comment: Copy the end-of-line comment attached to the current line, to the accumulator. STRINGS/Get/Full-line comment: Copy the first full-line comment attached to the current line, to the accumulator. STRINGS/Get/Search string: Copy the current search string into the accumulator. STRINGS/Get/Filename: Copy the current filename into the accumulator. STRINGS/Get/Save .asm name: If the current file has already been saved as source code (to a ".asm" file), copy the filename used to the accumulator. If the current file has not already been saved, the name will be the same as the current filename, with ".asm" appended. STRINGS/Get/Save .RS name: If the current file has already been saved to a .RS file, copy the filename used to the accumulator. If the current file has not already been saved, the name will be the same as the current filename, with ".RS" appended. STRINGS/Get/Macros filename: Copy the current macros filename to the accumulator. STRINGS/Get/Keytable filename: Copy the current keytable filename to the accumulator. STRINGS/Get/Cursor value: The contents of the memory where the cursor is, is written into the accumulator, in hexadecimal. This may be a byte, word, or longword, depending on the setting of 'operand size'. STRINGS/Get/Cursor offset: The currently displayed cursor position is written into the accumulator, in hexadecimal, as a longword (the "operand size" is set to longwords). STRINGS/Get/Accumulator length: The length of the string currently in the accumulator is written into the accumulator, in hexadecimal. The 'operand size' setting is not affected, but is used to decide how many leading zeroes to use. STRINGS/Get/Partial save size: The number representing the difference between the partial save end and the partial save start is written into the accumulator, in hexadecimal. The 'operand size' is set to longwords. STRINGS/Get/File: You will be requested to supply the name of a file, of which up to 240 characters will be copied into the accumulator. The data is copied as-is, no hex to ascii translation is performed. STRINGS/Put label: If the string within the accumulator is not used as a label anywhere within the current file, it will be used as a label on the current line. If it is already used as a label, then a digit is appended to it, and again it is tested to see if a label already exists of that name. This continues until a unique label is created, then that label is attached to the current line. This is a safe way of creating labels during macros. STRINGS/Edit functions/Clip start: You will be requested to supply a string. Starting from the left, each character in the supplied string is compared to the character in the accumulator at that position, and if they are equal, the next bytes are compared, and so on. When either the end of one of the strings is found, or when a mismatch is found, the characters in the accumulator that matched are deleted. The question mark ('?') is used as a wildcard, and you can use the asterisk once only, to "delete everything until and including" the following character. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- MOVE.L M OVE.L MOVE.L MUVE.L OVE.L MOVE.L MOV.L E.L MOVE.L move.l MOVE.L MOVE.L M?V E.L MOVE.L ??? E.L MOVE.L *. L MOVE.L *M OVE.L MOVE.L ?MOVE.L OVE.L _LVOAllocMem _LVO AllocMem $00000004 $000000 04 STRINGS/Edit functions/Clip end: Similar to the above functions, except clipping is performed on the end of the accumulator. The question mark is still used as a wildcard, but the asterisk does not have a special meaning in this function. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- MEMF_PUBLIC ?PUBLIC MEMF MEMF_PUBLIC ??? MEMF_PUB MEMF_PUBLIC ?LC MEMF_PUBLI meMcollAOVL_ OVL_ meMcollA STRINGS/Edit functions/Prepend: You will be requested to supply a string, which will be prepended (added to the start of) the accumulator, providing that the resulting string is no longer than 240 characters. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- PUBLIC MEMF_ MEMF_PUBLIC AllocMemSUB _ _AllocMemSUB PUBLIC CHIP CHIPPUBLIC STRINGS/Edit functions/Append: You will be requested to supply a string, which will be appended (added to the end of) the accumulator, providing that the resulting string is no longer than 240 characters. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- PUBLIC MEMF_ PUBLICMEMF_ AllocMemSUB _ AllocMemSUB_ PUBLIC CHIP PUBLICCHIP AllocMem SUB AllocMemSUB STRINGS/Edit functions/Reverse: The contents of the accumulator are reversed. Examples follow: Accumulator Resulting accumulator ---------------------------------------- PUBLIC CILBUP AllocMemSUB BUSmeMcollA AllocMem meMcollA STRINGS/Edit functions/Lower case: Any upper case characters in the accumulator are changed to their lower case counterparts. Examples follow: Accumulator Resulting accumulator ---------------------------------------- PUBLIC0123 public01243 All0cMemSUB all0cmemsub All0cMem all0cmem STRINGS/Operand size/: Some background information is required here: Some functions in ReSource require to know whether to work at the byte, word, or longword level. For example, STRINGS/Get/ Cursor value could get a byte, word, or longword from the cursor position, and this is your way of specifying at which level you wish those functions to work. Generally, they specify the size of the numeric operand in the accumulator. Some functions that write a numeric value into the accumulator will set the operand size themselves, others that get the value out of the accumulator need to know the operand size. STRINGS/Maths functions/Increment: Some background information is required here: All maths functions make some change to the number within the accumulator. If the string within the accumulator is not a valid number (hex, decimal or binary), the function will fail. Some functions are immediate, others will request the user for a required operand, such as what to add to the accumulator. The increment function adds one to the accumulator. If the resulting number develops a carry (using the current operand size), a macro 'fail' will result. Thus, loops in macros can exit after a given number of iterations, rather than a failed search, etc. STRINGS/Maths functions/Decrement: Similar to the above function, except that one is subtracted from the accumulator. If a carry results, a macro 'fail' will occur. Thus, loops in macros can exit after a given number of iterations, rather than a failed search, etc. STRINGS/Maths functions/Add: You will be requested for a number, to be added to the accumulator. If a carry results, a macro 'fail' will occur. STRINGS/Maths functions/Subtract: You will be requested for a number, to be subtracted from the accumulator. If a carry results, a macro 'fail' will occur. STRINGS/Maths functions/Multiply: You will be requested for a number, to be multiplied by the number within the accumulator. If a carry results, a macro 'fail' will occur. Full 32-bit multiplies are supported, however the setting of 'operand size' is used when determining the size of the operands. STRINGS/Maths functions/Divide: You will be requested for a number. The contents of the accumulator will be divided by the number that you specify. The divide function does NOT operate on 32-bit operands, but otherwise will work at the currently set operand size. If the current operand size is set to longwords, the divide will be performed on the lower 16 bits only. STRINGS/Maths functions/Negate: The number within the accumulator is negated, using the currently set operand size. If the result is zero, a macro 'fail' will result. STRINGS/Maths functions/Logical NOT: The number within the accumulator is NOTed, using the currently set operand size. If the result is zero, a macro 'fail' will result. STRINGS/Maths functions/Logical AND: You will be requested to supply a number, which will be ANDed with the contents of the accumulator, and the result is stored back into the accumulator. If the result is zero, a macro 'fail' will result. STRINGS/Maths functions/Logical OR: You will be requested to supply a number, which will be ORed with the contents of the accumulator, and the result is stored back into the accumulator. If the result is zero, a macro 'fail' will result. STRINGS/Maths functions/Exclusive OR: You will be requested to supply a number, which will be exclusively ORed with the contents of the accumulator, and the result is stored back into the accumulator. If the result is zero, a macro 'fail' will result. STRINGS/Define string/: These functions allow to you define the contents of either the accumulator, or one or the string buffers A-M. Whenever you are requested for a string using the simple string requester (NOT the large file requester), you can either type in a string literal, or input an escape character (just press the escape key), followed by either another escape character, or one of the letters A-M inclusive. If the second character is the escape character, the string being requested will be copied from the accumulator instead. If the second character that you typed (after the escape character) is one of the letters A-M, then the string being requested will instead be copied from the appropriate buffer A-M. This applies even when you define the contents of one of the string buffers. This method of using indirection should be particularly handy in sophisticated macros. The maximum string length in any buffer (including the accumulator) is 240 characters. STRINGS/Swap with buffer/: The contents of the accumulator is swapped with the contents of the buffer that you select. SPECIAL FUNCTIONS/Repeat last command: Repeat the last function used. Cursor movement functions are not repeated, excepting the search functions. This function should be bound to a high-priority key, such as the space bar, for best effect. SPECIAL FUNCTIONS/Dos Command: You will be requested for a string, which will be given as the operand to the Dos "execute" function. Anything that you normally type into a CLI window, you can give as a command. Any output will go to the CLI window that you started ReSource from, unless you redirect the output elsewhere. SPECIAL FUNCTIONS/Zap: You will be requested for a number/string, which will overwrite the byte/word/longword/characters at the cursor position. The current setting of 'operand size' is used. Using PROJECT/Open binary file, then this function, followed by "SAVE/Save binary image/ALL", you can quickly modify a program, without having to completely disassemble it, edit the source code, and reassemble and link. You are restricted using this method of modification however, to the size of modifications that can be done. For example, you cannot insert extra code or data. If the string that you supply starts with a single open quote ("'"), the following characters are treated as a string, and are copied to the cursor position as-is. If the string that you supply starts with "$", the following number is assumed to be hexadecimal. If the string that you supply starts with "%", the number that follows is assumed to be binary, otherwise it is assumed to be a decimal number. SPECIAL FUNCTIONS/Screen/Front: Move ReSource's screen in front of all other screens. SPECIAL FUNCTIONS/Screen/Back: Move ReSource's screen behind all other screens. SPECIAL FUNCTIONS/Set task priority: You will be requested for a number, representing the priority at which to set the current task. For example, if you have a program being assembled in the background, and you don't want it to slow the operations of ReSource down, you might set the task priority to one or two. Negative numbers are not supported. Sorry! SPECIAL FUNCTIONS/Convert xx(A4) EA's These functions were specifically designed to be used when disassembling 'C' programs, in which the A4 register is used as a base register for accessing data, throughout all or most of the program. Let's use an example program here: SECTION test000000,CODE LEA START+$11E,A4 LEA 0(A4),A1 MOVE.L $000C(A4),D0 .... rest of code SECTION test00011E,DATA dc.b 'dos.library',0 dc.l $00010001 END In the above example program, the A4 register will point to the start of the data segment. There are three ways to tell ReSource where the A4 register will point to; in the above example, the "This operand" function could be used with the cursor at start of file, or the "This address" function could be used with the cursor at offset $00011E, or the "Specify" function could be used, supplying a parameter of "$11E". Basically, with this function, you are telling ReSource where, relative to the start of the program, the A4 register can be assumed to be pointing. After you do this, any effective address that involves a word offset to the A4 register, will be shown as an absolute address. Thus, the example program above will appear as: SECTION test000000,CODE LEA START+$011E,A4 LEA START+$011E,A1 MOVE.L START+$012A,D0 .... rest of code SECTION test00011E,DATA dc.b 'dos.library',0 dc.l $00010001 END The advantage here is that labels can automatically be created where they could not before. If this conversion process is not used, it is likely that the program will not successfully re-assemble, as different assemblers assemble the same source code into different opcodes. For example, the assembler that I normally use does virtually no optimizing, and so the resulting program is often larger than the original, even if I did not modify the source code. For example: MOVE.L 4,A6 If absolute long addressing is used, the instruction above will be 6 bytes long, whereas if absolute short addressing is used, it will be only 4 bytes long. Where you wish to do EA conversions in only a portion of a program, you can set the lower and upper limits. Changing to absolute EA's will increase the size of the resulting program, unless you convert back to relative addressing, within the source code. I believe that one of the features of BLINK (from the Software Distillery) can help to make this conversion, during the link process. SPECIAL FUNCTIONS/Convert specific EA's: Please read and understand the "SPECIAL FUNCTIONS/Convert xx(A4) EA's" functions first! Where you want to do specific EA (Effective Address) conversions, use "Set base #1" (or #2, or #3), when the cursor is the same as where the base register (whatever that is, it does not have to be A4 this time) can be assumed to point to. Assuming that you set base #1, and it is the A5 register that is being used as a base register, you will then use the "Convert W/Base #1" function to convert lines like: MOVE.L $0032(A5),A6 .. into: MOVE.L lbL0014AC(A5),A6 Note here that there has not actually been an EA conversion, but a label has been created, the data type at label "lbL0014AC" has been determined and set, and a symbol ("lbL0014AC") has been created for this line. It is up to you then to make the necessary changes to the resulting source code, if re-assembling is required. Whereas the "Convert xx(A4) EA's" function converts immediately and automatically, you must use the "Convert W/Base #1" function on each line that you want converted. If you wish to convert a destination address, use the "SYMBOLS 1/Set field/ Second" function first. SPECIAL FUNCTIONS/Data type set/: These functions affect how the "SPECIAL FUNCTIONS/Convert specific EA's" functions work. When the data type must be determined, it can be automatic, or you can force it to be set to Bytes/Words/Longwords/Ascii/Code. SPECIAL FUNCTIONS/Convert to../: The setting here will determine the type of symbol created when the "SPECIAL FUNCTIONS/Convert specific EA's" functions are used. SAVE/O/P Directory: You will requested to supply the name of a directory. Whenever you are requested to supply the name of a file to save source code to, the name will have this directory name prepended to it. For example, if you supply the string "RAM:" as the output directory name, and the current filename is "c:stack", when you select "SAVE/Save .asm/ALL", the default name to save to will be "RAM:stack.asm". SAVE/Partial save/Set start: For any partial saves, the current cursor position (as it is NOW) will be where the save will start from. By default, this position is equivalent to the start of the file. SAVE/Partial save/Set end: For any partial saves, the current cursor position will be where the save will end. If this happens to be the last line in the file, any partial save will include the last line. Normally, the partial save will NOT include the line where the partial save end is set. SAVE/Save binary image/ALL: Save the current buffer contents as-is, to a file. If the file was loaded with "PROJECT/Open load file", and was NOT loaded as a binary image file, the resulting saved file will NOT be the same as that originally loaded, as the loader information, and relocation information, has been stripped. If you wish to load a file, and then save it exactly as it was loaded, you must use "PROJECT/Open binary file". Even though you may have disassembled memory directly, or read tracks from a floppy disk, it does NOT stop you from saving the binary image. Once something is loaded into ReSource, it can be saved as source code, as a binary image file, directly to memory, or it can be written directly to a floppy disk, to a specific sector or track. This gives fantastic flexibility for general hacking, for as little as one byte of the current buffer can be saved to memory, to a binary image file, or as source code. Track writes must be in multiples of 512 bytes, however the clipping is done for you. SAVE/Save binary image/Partial: Similar to the above function, except only the data between the partial save start and the partial save end is saved. SAVE/Save .asm/ALL: You will be requested to supply the name of a file to save source code to, for the entire current buffer contents. The output will be very similar to how you see it on the display. SAVE/Save .asm/Partial: Similar to the above function, except only the code/data between the partial save start and the partial save end is disassembled. SAVE/Calculate .asm size/ALL: Calculates the size of the source code file that would result if you had used the "SAVE/Save .asm/ALL" function. SAVE/Calculate .asm size/Partial: Calculates the size of the source code file that would result if you had used the "SAVE/Save .asm/Partial" function. SAVE/Save to memory/ALL: You will be requested to supply a memory address to save the contents of the current buffer. The buffer will be saved as-is, it is NOT disassembled. Care should be taken with this function, as a system crash will likely result if you supply the wrong address. By finding out where the current buffer is in memory, it is possible to copy one part of the current buffer to another part. SAVE/Save to memory/Partial: Similar to the above function, except that only the data between the partial save start and the partial save end is saved. SAVE/Save tracks/ALL: You will be requested for a string representing where to start writing tracks. The first parameter you give must be either "DF0:", "DF1:", "DF2:", or "DF3:". The second parameter is the starting cylinder to save to. The third parameter is optional, and represents an offset, in sectors, where the track write is to start. For example, to save the sector #3 on cylinder 5 on DF2:, the parameters required would be "DF2: 5 3". To save to the first sector on DF0:, the parameters required would be "DF0: 0". Whole sector writes ONLY are done, clipping is performed automatically. SAVE/Save tracks/Partial: Similar to the above function, except that only the data between the partial save start and the partial save end is saved. Furthermore, only even multiples of 512 bytes will be written. For example, if the partial save size is 1027 bytes, only two sectors (1024 bytes) will be written to the disk. SAVE/Tabs/: Use to select between real tabs (ASCII value 9) and spaces being used in the output source code as separators. SAVE/Symbol table/: When creating symbols, either automatically, or manually, if the setting of this function is to something other than "None", the value and name of the symbol is stored, so that when the source code is saved, an equate table, or XREF table can be generated. If this function is set to "EQUate", a symbol table similar to the following will preceed the source code in the output file: AG_OpenLib EQU $00030000 AO_DOSLib EQU $00008007 AT_Recovery EQU $00000000 _LVOAlert EQU $FFFFFF94 _LVOClose EQU $FFFFFFDC _LVOCreateProc EQU $FFFFFF76 _LVOCurrentDir EQU $FFFFFF82 If, instead, this function is set to "XREF", a symbol table similar to the following will preceed the source code in the output file: XREF AG_OpenLib XREF AO_DOSLib XREF AT_Recovery XREF _LVOAlert XREF _LVOClose XREF _LVOCreateProc XREF _LVOCurrentDir OPTIONS 1/Show offsets/: For lines displayed without labels, the current offset (relative from the start of the file) can be displayed where the label is usually displayed. OPTIONS 1/Display beep/: Many functions demand attention from the user, and a display beep is used for this purpose. Normally, this will make the screen flash. However, if you have run the program "addbeep", you will hear an audible "beep" instead. If you don't appreciate the beep, then switch it off. OPTIONS 1/User feedback/: Many functions will give informative messages, to let the user know what is happening internally. If you don't appreciate the feedback, then switch it off. OPTIONS 1/Feedback Delays/: If you have User feedback set to "OFF", then the setting of this function is not important. If feedback is ON, you may occasionally find that feedback message are being displayed too fast for you to read them. This is especially so when opening a load file, for as many as thirty informative messages can be displayed in between raster scans, which means that you don't actually get to see any of the messages at all. If normal text rendering were used, this would probably not be a problem, as the writing of the text itself would be done much slower, and you would probably get time to read at least some of the messages. If you set feedback delays to "ON", there will be a one second delay after each message is displayed, which should be plenty to read each message. While you hold the menu button down, feedback messages are skipped altogether. OPTIONS 1/Labels/: If this option is set to ON, labels will be displayed. This is the default. OPTIONS 1/Hidden labels/: If this option is set to ON, hidden labels (labels attached to a byte in the middle of a line of code/data) will be displayed. This is the default. OPTIONS 1/Symbols/: If this option is set to ON, symbols will be displayed. This is the default. OPTIONS 1/End-of-line comments/: If this option is set to ON, end-of-line comments will be displayed. This is the default. OPTIONS 1/Full-line comments/: If this option is set to ON, full-line comments will be displayed. This is the default. OPTIONS 1/Chip-load info/: If this option is set to ON, where a section statement is displayed, and that section either is forced to load into chip memory, or is forced to load into fast memory, a ",CHIP" or ",FAST" will be appended to the section statement. Not all assemblers support this parameter for the section statement, so you may want to switch this option OFF if your assembler can't handle it. OPTIONS 1/Section statements/: If this option is set to ON, section statements will be displayed. This is the default. OPTIONS 1/End statement/: If this option is set to ON, the "END" statement will be displayed as the last line in the file. This is the default. OPTIONS 1/DCB statements/: If this option is set to ON, "dcb" type statements will be used where appropriate. This is NOT the default. For example, the following data: dc.b 0 dc.b 0 dc.l 7 dc.l 8 dc.l 8 dc.l 8 dc.l 8 dc.l 8 dc.l 8 will be shown as: dcb.b 2,0 dc.l 7 dc.l 6,8 This is useful for shrinking the required .asm file size, especially where there is large areas of zeroes. OPTIONS 1/Reference recognition/: If this option is set to ON, references to memory locations within the current file are recognized. This is the default. OPTIONS 2/ASCII longs/: If this option is set to ON, where longword operands are recognized as all ASCII characters, they will be displayed as such. This is the default. OPTIONS 2/Short branches/: If this option is set to ON, any short branches will be displayed as such, with the ".S" appended to the opcode. This is the default. KEY BINDINGS/: Every function in ReSource can be found in the menus. You do not need to use any keys at all, but you probably will want to. You can bind any function to any key, however there is just one function that makes no sense to rebind, and that is the "PROJECT/Abort" function. Both Amiga keys are supported, you may use shift, alt, ctl, lAmiga, rAmiga, shift-alt, shift-ctl, alt-ctl, or shift-alt-ctl in combination with any non-qualifier key, as a distinct key to bind a function to. Thus, you have complete control over which keys do what. After re-binding some keys, you will probably want to save the keytable. If you save the keytable as "S:RS.keytable", it will be loaded every time you run ReSource. You may want to create several keytables, suitable for doing differing program types (C, assembler, etc.). If a keytable file is loaded, ALL current key bindings will be overwritten by the bindings present in the keytable. If you don't load any keytable, and ReSource couldn't find "S:RS.Keytable" when you first ran it, some keys will still be bound: right-Amiga Q.............PROJECT/Quit right-Amiga O.............Open load file up arrow..................CURSOR/Relative/Next line down arrow................CURSOR/Relative/Previous line right arrow...............CURSOR/Absolute/Fwd reference left arrow................CURSOR/Absolute/Previous location shift-up arrow............CURSOR/Relative/Previous page shift-down arrow..........CURSOR/Relative/Next page To rebind a key, select "KEY BINDINGS/Rebind key", and follow the prompts in the title bar. *********************************************************** Amiga, AmigaDOS, and Kickstart are registered trademarks of Commodore-Amiga, Inc. ***********************************************************