THE ARROWSOFT ASSEMBLER Public Domain Version 2.00c User's Guide The Arrowsoft Assembler Program and Manual are both Copyright (C) 1986, 1987 by Arrowsoft Systems, Inc. 554 West Sixth Avenue Larkview, MO 66069 Arrowsoft Assembler v2.00 User's Guide INTRODUCTION Thank you for trying out the public domain version of our Arrowsoft Assembler. We feel that the best way to alert you, the programmer, to our fine line of professional products is to let you use one. Once you have experienced the high quality and ease of use of this free product, we hope that you will contact us regarding our other software (our address is on the cover of this manual). You will no doubt notice that this manual is not exhaustive; in fact, it includes the least amount of information we felt we could include without robbing the program of its usefulness. There are two reasons for the brevity of this manual: First, we have targeted professional software developers with our products, and we suspect that an experienced professional will have no trouble figuring out how to use the Arrowsoft Assembler with the information given; second, the program is, after all, free and we feel that the quality of this assembler will more that compensate you for the time you spend learning to use it. Please note that this is NOT a supported product. If you contact us, we will be happy to discuss our line of software but we will NOT answer questions about the Arrowsoft Assembler. Again, we thank you for giving our product a try. (NOTE: 'Microsoft' and 'Microsoft Macro Assembler' are trademarks of Microsoft Corporation. 'Arrowsoft', 'Arrowsoft Professional Assembler' and 'Super Link' are trademarks of Arrowsoft Systems, Inc.) OVERVIEW The Arrowsoft Assembler takes as its input 8086, 8088, 80186 and 80286 assembly language source files and produces relocatable object modules which may be linked and run under the MS-DOS and PC-DOS operating systems. The syntax of the input files is a superset of that accepted by the Microsoft Macro Assembler (versions 3.0 and later). In fact, most programs written for the Microsoft product should assemble without modification with the Arrowsoft Assembler. The remaining sections of this manual will cover, in this order, assembler command line options, input language specifications, linking and execution of assembled object modules, and assembler error messages. INVOKING THE ARROWSOFT ASSEMBLER You may run the Arrowsoft Assembler interactively or directly from the DOS command line. To invoke the assembler interactively, simply type -1- Arrowsoft Assembler v2.00 User's Guide asm at the DOS prompt and follow the ensuing instructions. To run the assembler non-interactively, use the following syntax: asm source [,object] [,list] [,xref] [options] [;] where 'source' is a filespec for the source file (default extension .ASM), 'object' is a filespec for the object file (default extension .OBJ), 'list' is a filespec for the listing file (default extension .LST) and 'xref' is a filespec for the cross-reference file (default extension .CRF). Note that all filespecs may consist of a drive letter, a pathname, a filename and an extension. If the object file is not specified, the assembler will use the source filename with the .OBJ extension. If the list and cross-reference files are not specified, the assembler will not produce them. Finally, the semicolon (;) will force the assembler to assume default values for any unspecified parameters. OPTION CODES The options list consists of a sequence of option codes. These option codes consist of a slash (/) or dash (-) followed by one or more letters, case being insignificant. Most of these options are compatible with Microsoft conventions. /A Write segments in alphabetical order /Bnumber Set buffer size /Dsymbol Define assembler symbol /E Generate 8087/80287 emulator code /F Generate 8087/80287 floating point code /H Command help summary /Ipath Set 'include' search path /ML Case sensitive internal labels /MX Case sensitive external and public labels /MU Convert labels to uppercase /P Include Pass1 listing /S Silent; no screen output unless error /X Include false conditionals in listing Many of these command line options are self explanatory; for whose which aren't, see the descriptions below: /B Set Buffer Size Sets the size of the buffer used to hold the source file during assembly. The 'number' is the number of 1K pages reserved for use as a buffer. You may set the buffer size to any value between 1K and 63K; default buffer size is 32K. Note that a larger buffer can speed assembly of large files considerably. /E Generate 8087/80287 Emulator Code -2- Arrowsoft Assembler v2.00 User's Guide If you are writing programs for use with the 8087/80287 numeric processor on a machine which does not have the processor, and you have an 8087/80287 emulator library available, the /E option directs the assembler to generate code for the emulator. /F This option directs the assembler to generate floating point code for the 8087/80287 numeric processor. Note that programs assembled with the '/F' option will run ONLY on machines which have an 8087/80287 installed. /I Set 'include' file search paths You may direct the assembler to search up to 5 directories for 'include' files by including a '/Ipath' command for EACH of them. For example, to set the search paths '\bin\lib' and '\asm\lib', include the following in your options list: /I\bin\lib/I\asm\lib. ARROWSOFT ASSEMBLY LANGUAGE As we mentioned earlier, the Arrowsoft Assembly Language is a superset of the well-known Microsoft Macro Assembler Language. We modeled our system after Microsoft's for two reasons: First, the language has a flexible and moderately powerful macro facility; second, and for this public domain project most important, there is a plethora of third-party books which explain how to program using the Microsoft product. We recommend that you purchase one of these guides if you are not familiar with 8086 assembly language. If you would like to take advantage of the many extensions to the Microsoft Language we have implemented in the Arrowsoft Assembler, you must do one of two things: Try to figure them out for yourself (using experimentation, disassembly or anything else you can think of); or you can contact us about purchasing the Arrowsoft Professional Assembler, which includes the complete documentation. Again, please DO NOT CALL us about the Arrowsoft Assembler; we will not answer any questions or provide clues as to how to access the assembler's advanced features. LINKING AND EXECUTING ARROWSOFT OBJECT MODULES The Arrowsoft Assembler produces relocatable object modules which are compatible with the Microsoft 8086 Object Linker (versions 3.0 and later). This means that programs assembled by the Arrowsoft Assembler may be linked with other Microsoft Linker-compatible programs generated by other assemblers and compilers. If you need more information on how to use the Microsoft 8086 Object Linker, see your DOS or Microsoft language manual. -3- Arrowsoft Assembler v2.00 User's Guide By the way, we would like you to know about Arrowsofts Super Link 8086/8086 Object Link Utility. Super Link is a full-service overlaying linker which is fully compatible with the Microsoft 8086 Object Linker, yet much faster and far more versatile. Contact us at the address on the cover of this manual for more information. ASSEMBLER ERROR MESSAGES An Arrowsoft Assembler error report consists of three parts: A source file line number, an error number and a terse error description. In most cases, the error messages, in spite of their brevity, are self explanatory. We have tried to keep the error numbers as close to the ones produced by the Microsoft assembler as possible, however there are a few differances. We offer the following explainations of our error messages: 0 Block nesting error You have nested some structure (segments, procedures, structures, macros etc.) and have not terminated them in the proper (reverse) order. 1 Unexpected data on line You have extra (non-comment) characters on the end of an input line that is not required by the instruction on that line. 2 Internal error This message will appear only if an error occurred within the assembler itself. If you see this message, please send an assembly listing of the source file and any other relevant information (DOS version, assembler version, etc.) to the address on the cover of this manual. 3 Invalid symbol type You have given an incorrect size/type for a symbol. ASM is expecting BYTE, WORD, NEAR, FAR etc. 4 Symbol already defined You have multiple symbols declared with the same name. This error occurs on PASS1 an all duplicates AFTER the first symbol is processed. 5 Duplicate symbol You have multiple symbols declared with the same name. This error occurs in the listing for ALL occurances of the duplicated name. -4- Arrowsoft Assembler v2.00 User's Guide 6 Phase error You have an instruction somewhere in the program that even though it is valid, does not have enough information to correctly assemble during the first pass. The error occurs because the assembler gets "out of sync" after it generates different code on the second pass than it assumed on the first pass. The offending instruction is usually shortly before the phase error occurs. 7 ELSE is already active You have used ELSE when the assembler is already processing an ELSE clause. You could not have another ELSE without a nested IF. 8 No conditional active You have used ENDIF or ELSE without a preceeding IF 9 Undefined Symbol You are referenceing a symbol that has not been defined. 10 Syntax error Your source line does not follow the assembler source syntax rules. 11 Illegal type for use The type/size of an operand is incompatible with the way in which you are using it. 12 GROUP name expected The assembler was expecting a group name but none was found. 13 Undefined in first pass A symbol referenced during PASS1 was not defined until after the referance. 14 Misuse of PUBLIC symbol You have used this symbol in a way that is incompatible with its declared type. -5- Arrowsoft Assembler v2.00 User's Guide 15 Mismatch in redeclared symbol You are attempting to redefining a symbol differently than it was originally declared. 16 Illegal use of keyword You have used an assembler keyword in a way it does not function. eg: declaring an instruction name as a label. 17 Illegal forward reference You are attempting to forwardc referance a symbol with a directive that is evaluated during PASS1. 18 Use a register A register name is required by this instruction. 19 Register type invalid You have specified a register which is incompatible with the instruction to which it is an operand. 20 Segment/Group expected The assembler was expecting a segment or group name, but none was found. 21 Segment unknown You have applied the operator to a variable that has no defined segment. 22 Invalid symbol type The assembler was expecting a type (WORD, BYTE, etc.) but none was found. 23 Symbol is defined LOCAL You are attempting to define as EXTRN a symbol that has already been defined as LOCAL. 24 Mismatched SEGMENT parameters The parameters to a SEGMENT directive do not match those that were used when the segment was first used. -6- Arrowsoft Assembler v2.00 User's Guide 25 SEGMENT parameters incorrect The aling and/or combine types for this SEGMENT directive are incorrect. 26 Unresolvable reference You are referencing a symbol which exists, but cannot be resolved by the assembler. Check for errors in the declaration of the symbol. 27 Operand expected The assembler was expecting an operand but none was found. 28 Operator expected The assembler was expecting an operator but none was found. 29 Overflow or zero division You have used an expression that either overflows the largest number that the assembler can handle, or contains a division by 0. 30 Negative shift count You have specified a shift operation with a negative count. Shift counts must always be positive. 31 Unmatched operand types You have used arguments which differ in size or type in an instance where they must be the same. 32 External use illegal You have used an external symbol in a place where it must be resolved at assembly time. The assembler must know the address/value of the symbol, and therefore cannot process the instruction. 33 Record field name needed The assembler was expecting a record field name but none was found. -7- Arrowsoft Assembler v2.00 User's Guide 34 Record/field name required The assembler was expecting a record name or a field name but none was found. 35 Operand requires size You have attempted an operation where the assmbler need to know the size of the operand, but the operand did not have an implicit size, and none was specified (Use ' PTR'). 36 Var/Label/Constant expected The assembler was expecting a variable, label or constant but none was found. 37 Structure field name needed The assembler was expecting a structure field name but none was found. 38 Left operand needs segment A segment must be specified in the left operand. 39 Constant operand required You are attempting an operation which requires a constant value as its operand. 40 Const. or abs. operand needed You are attempting an operation which requires a constant value, or a expression involving absolute addresses that can be resolved to a constant value (eg: symbol2 - symbol1). 41 Incorrect operand type The operand specified is incorrect for the operation being performed. 42 Constant expected You have used an expression than cannot be evaluated to a constant value in a place where the assembler must have a constant value. -8- Arrowsoft Assembler v2.00 User's Guide 43 Operand requires segment You are performing an operation which requires a segment, and none can be determined. 44 Applies to data only You are attempting to perform an operation on code that can only be applied to data types. 45 Applies to code only You are attempting to perform an operation on data that can only be applied to code types. 46 Multiple base registers You have specified more than one base register in an address operand. 47 Multiple index registers You have specified more than one index register in an address operand. 48 Index or base register needed You have use a register which is neither an index or base register where one was expected. (ie: within []) 49 Register use incorrect The operation you are attempting cannot be applied to a register. 50 Value out of range You have attempted to use a constant value that is outside of the limits of acceptable values. 51 Operand not in IP segment The operand must be in the current IP segment, and it is not. 52 Invalid operand type You have used an operand which does not apply to the instruction. -9- Arrowsoft Assembler v2.00 User's Guide 53 Rel. jump is out of range You have attempted a short jump (JZ, JNZ, etc.) to a target address which is more than -128 to +127 bytes away from the current program counter address. 54 Displacement must be constant You have attempted to use a non-constant as the offset in an indexed addressing mode. 55 Register value invalid You have specified a register which cannot be used in this addressing mode. 56 No immediate form This instruction cannot operate on immediate data. 57 Item size is illegal You are attempting an operation on an object having a size that the instruction set does not handle. 58 Illegal use of byte reg. You are attempting to use an 8 bit register in a way that only 16 bit registers can be used. 59 Illegal use of CS reg. You are attempting an operation on the Code Segment register than cannot be performed on it. 60 AX or AL needed This instruction requires the 8 or 16 bit accumulator. No other register can be used. 61 Cannot use a segment register You are attempting an operation that cannot be performed on a segment register. 62 No or unreachable CS The label specified in this jump instruction is not in an accessable code segment. -10- Arrowsoft Assembler v2.00 User's Guide 63 Illegal operand combination The two operands you have specified are incompatible with one another. 64 Near JMP/CALL must be same CS You are attempting to near jump to a label which is not in the current code segment. 65 Can't seg. override a label You cannot override the segment of this label. 66 Opcode must follow prefix You have used a repeap prefix without supplying an instruction opcode immediately after it. 67 Illegal ES override You have attempted to override the ES register in an instruction where this cannot be done. 68 Unreachable with segment reg This label is not accessable with the currently ASSUMed segment registers. 69 No segment block active Attempt to generate code or data when no segment is active. 70 Illegal alignment of BYTE seg. You have attempted to word align (EVEN) within a segment which is defined as having byte alignment. 71 Override or far needed You cannot access this symbol without a segment override or FAR modifier. 72 DUP count is illegal The DUP count specified evaluates to either zero or a negative value. DUP counts must be non-zero positive values. -11- Arrowsoft Assembler v2.00 User's Guide 73 Symbol is defined EXTERNAL You are attempting to define as LOCAL a symbol that has already been defined as EXTRN. 74 DUP count is too large The DUP count value specified would result in generation of a larger record than the assembler/linker can handle. 75 Incorrect use of '?' You have used the undefined operand '?' in an incorrect way (eg: ?+10). 76 Too many data values You have specified more data values than there are elements in a record or structure. 77 Initialize list required Use of a STRUC name required an initialize list (with <> angle brackets) 78 Illegal use inside STRUC You have attempted to use a statement other than DB, DW etc. inside of a structure block. 79 Illegal DUP in override You are attemptin to use a DUP in an override within a structure initilize list. This is not allowed. 80 Cannot override field You are attempting to place a value in a structure initialze list field that cannot be overridden. 81 Wrong type of override You are using the wrong type/size for the given field in a structure initialize list. 82 Cannot forward reference seg. You cannot make a forward referance to a segment. -12- Arrowsoft Assembler v2.00 User's Guide 83 Self-referencing EQU chain The EQU symbol cannot be resolved because it references its own value (This may be indirectly through several EQU's). 84 Cannot emulate 8087 opcode. You are using an 8087 operation that the emulator cannot perform. 85 Premature end of file The assembler encountered the physical end of input before an END statement was found. Ie: Missing END statement. Out of Memory Either the source file exceeds the 64K limit of the assembler or the symbol table exceeds its allocation. If this condition occurs, try assembling without creating list or cross-reference files. If this doesn't work, try dividing your source code into several smaller source files and assembling them separately. The resulting code may then be linked with a link utility. (Again, we can't resist pointing out that the Arrowsoft Professional Assembler uses ALL available memory for the assembly process; in fact, it will assemble a file of arbitrary size, regardless of memory limitations.) -13- Arrowsoft Assembler v2.00 User's Guide THE ARROWSOFT PROFESSIONAL ASSEMBLER Our real reason for giving you this program free of charge is to encourage you to purchase our commercial product, the Arrowsoft Professional Assembler. The program you have now differs from the full program in only three respects: (1) It includes no documentation for those language features which extend the Microsoft Macro Assembly Language (although they are implemented by the public domain version); (2) the maximum input file size is limited to 64K bytes; and (3) it is not supported via our 24 hour toll-free help line (in fact, it is not supported at all by us). With these 3 exceptions, the program you now have is identical to the Professional Assembler. If you decide you'd like to purchase the Arrowsoft Professional Assembler, send a postcard requesting our catalog to the address on the cover of this manual. Our catalog will show you our entire line of professional software development products and will convince you that our quality and prices are as competitive as you will find anywhere. CONCLUDING REMARKS AND CREDITS Again, we would like to thank you for trying our product. We hope that the remarks we've made concerning our programming products (Arrowsoft Professional Assembler and Super Link 8086 Object Linker) have piqued your curiosity enough that you'll write to us for more information. Further, we hope that actually using one of our products has convinced you of our dedication to quality and performance. Finally, we hope to welcome you to our growing family of satisfied customers. Even if you don't buy anything from us, you can do us a favor. We want you to distribute this product to all of your friends by any means possible. You may post it to bulletin boards, offer it through your computer club or just copy it and pass it around. We only ask that (1) you charge nothing for the software beyond reasonable copying and disk costs and (2) that you distribute the two files (ASM.EXE and ASM.DOC) together and without modification. The Arrowsoft Assembler was written by Kaplan 'Kap' Morovitz and tested by the programming staff at Arrowsoft. Since 'Kap' writes only in assembly language and C, this manual was written by Stan Goldwyn-Benton. -14-