home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / asmutl / arrowasm.arc / ASM.DOC next >
Text File  |  1980-01-01  |  17KB  |  395 lines
  1.           
  2.           
  3.           
  4.           
  5.           
  6.           
  7.           
  8.           
  9.           
  10.           
  11.           
  12.           
  13.                                THE ARROWSOFT ASSEMBLER
  14.                                           
  15.                              Public Domain Version 1.00D
  16.                                           
  17.                                           
  18.                                     User's Guide
  19.                                           
  20.                                           
  21.                                           
  22.                                           
  23.                                           
  24.                                           
  25.                                           
  26.                                           
  27.                                           
  28.                                           
  29.                  The Arrowsoft Assembler Program and Manual are both
  30.                     Copyright (C) 1986 by Arrowsoft Systems, Inc.
  31.                                 554 West Sixth Avenue
  32.                                  Larkview, MO  66069
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.           Arrowsoft Assembler v1.00                            User's Guide
  67.  
  68.  
  69.                                     INTRODUCTION
  70.           
  71.           Thank  you  for  trying  out  the  public  domain  version of our
  72.           Arrowsoft Assembler.  We feel that the best way to alert you, the 
  73.           programmer, to our fine line of professional products is  to  let
  74.           you use one.  Once you have experienced the high quality and ease 
  75.           of  use  of  this  free product, we hope that you will contact us
  76.           regarding our other software (our address is on the cover of this 
  77.           manual).  
  78.           
  79.           You will no doubt notice that this manual is not  exhaustive;  in
  80.           fact,  it  includes  the  least  amount of information we felt we
  81.           could include without robbing  the  program  of  its  usefulness.
  82.           There  are  two reasons for the brevity of this manual: First, we
  83.           have targeted professional software developers with our products, 
  84.           and we suspect that an  experienced  professional  will  have  no
  85.           trouble  figuring out how to use the Arrowsoft Assembler with the
  86.           information given; second, the program is, after all, free and we 
  87.           feel that the quality of this assembler will more that compensate 
  88.           you for the time you spend learning to use it.  
  89.           
  90.           Please note that this is NOT a supported product.  If you contact 
  91.           us, we will be happy to discuss our line of software but we  will
  92.           NOT answer questions about the Arrowsoft Assembler.  
  93.           
  94.           Again, we thank you for giving our product a try.  
  95.           
  96.           (NOTE: 'Microsoft' and 'Microsoft Macro Assembler' are trademarks 
  97.           of  Microsoft  Corporation.  'Arrowsoft', 'Arrowsoft Professional
  98.           Assembler' and 'Super Link' are trademarks of Arrowsoft  Systems,
  99.           Inc.) 
  100.           
  101.           
  102.           
  103.                                       OVERVIEW
  104.           
  105.           The  Arrowsoft Assembler takes as its input 8086, 8088, 80186 and
  106.           80286 assembly language source  files  and  produces  relocatable
  107.           object  modules  which may be linked and run under the MS-DOS and
  108.           PC-DOS operating systems.  The syntax of the  input  files  is  a
  109.           superset  of  that  accepted  by  the  Microsoft  Macro Assembler
  110.           (versions 3.0 and later).  In fact, most programs written for the 
  111.           Microsoft product should assemble without modification  with  the
  112.           Arrowsoft Assembler.  
  113.           
  114.           The  remaining sections of this manual will cover, in this order,
  115.           assembler command line options,  input  language  specifications,
  116.           linking  and execution of assembled object modules, and assembler
  117.           error messages.  
  118.           
  119.           
  120.           
  121.                           INVOKING THE ARROWSOFT ASSEMBLER
  122.           
  123.           You may run the Arrowsoft  Assembler  interactively  or  directly
  124.           from the   DOS   command   line.      To   invoke  the  assembler
  125.           interactively, simply type 
  126.           
  127.  
  128.  
  129.                                          -1-
  130.  
  131.  
  132.           Arrowsoft Assembler v1.00                            User's Guide
  133.  
  134.  
  135.                    asm
  136.           
  137.           at the DOS prompt and follow the ensuing instructions.    To  run
  138.           the assembler non-interactively, use the following syntax: 
  139.           
  140.                    asm source [,object] [,list] [,xref] [options] [;]
  141.           
  142.           where  'source'  is  a  filespec  for  the  source  file (default
  143.           extension .ASM), 'object' is  a  filespec  for  the  object  file
  144.           (default  extension  .OBJ),  'list' is a filespec for the listing
  145.           file (default extension .LST) and 'xref' is a  filespec  for  the
  146.           cross-reference  file  (default  extension  .CRF).  Note that all
  147.           filespecs may consist of a drive letter, a pathname,  a  filename
  148.           and an  extension.    If  the  object  file is not specified, the
  149.           assembler will use the source filename with the  .OBJ  extension.
  150.           If  the  list  and  cross-reference  files are not specified, the
  151.           assembler will not produce them.  Finally, the semicolon (;) will 
  152.           force the assembler to assume default values for any  unspecified
  153.           parameters.  
  154.           
  155.           
  156.           
  157.                                     OPTION CODES
  158.           
  159.           The options  list  consists of a sequence of option codes.  These
  160.           option codes consist of a slash (/) or dash (-) followed  by  one
  161.           or more letters, case being insignificant.  Most of these options 
  162.           are compatible with Microsoft conventions.  
  163.           
  164.                    /A             Write segments in alphabetical order
  165.                    /Bnumber       Set buffer size
  166.                    /Dsymbol       Define assembler symbol
  167.                    /E             Generate 8087/80287 emulator code
  168.                    /Ipath         Set 'include' search path
  169.                    /ML            Case sensitive internal labels
  170.                    /MX            Case sensitive external and public labels
  171.                    /MU            Convert labels to uppercase
  172.                    /R             Generate 8087/80287 floating point code
  173.                    /S             Write segments in source code order
  174.                    /X             Include false conditionals in listing
  175.                    /Z             Display error lines on screen
  176.           
  177.           
  178.           Many  of  these  command  line  options are self explanatory; for
  179.           whose which aren't, see the descriptions below: 
  180.           
  181.           
  182.           /B Set Buffer Size 
  183.           
  184.           Sets the size of the buffer used to hold the source  file  during
  185.           assembly.   The  'number'  is the number of 1K pages reserved for
  186.           use as a buffer.  You may  set  the  buffer  size  to  any  value
  187.           between  1K  and  63K;  default  buffer  size is 32K. Note that a
  188.           larger buffer can speed assembly of large files considerably.  
  189.           
  190.           
  191.           /E Generate 8087/80287 Emulator Code 
  192.           
  193.  
  194.  
  195.                                          -2-
  196.  
  197.  
  198.           Arrowsoft Assembler v1.00                            User's Guide
  199.  
  200.  
  201.           If you are writing programs for use with the  8087/80287  numeric
  202.           processor on a machine which does not have the processor, and you 
  203.           have  an  8087/80287  emulator  library  available, the /E option
  204.           directs the assembler to generate code for the emulator.  
  205.           
  206.           
  207.           /I Set 'include' file search paths 
  208.           
  209.           You may direct the assembler to search up to  5  directories  for
  210.           'include'  files  by  including  a  '/Ipath'  command for EACH of
  211.           them.  For example,  to  set  the  search  paths  '\bin\lib'  and
  212.           '\asm\lib',   include   the   following  in  your  options  list:
  213.           /I\bin\lib/I\asm\lib.  
  214.           
  215.           
  216.           /R 
  217.           
  218.           This option directs the assembler to generate floating point code 
  219.           for the  8087/80287  numeric  processor.    Note  that   programs
  220.           assembled  with  the  '/R' option will run ONLY on machines which
  221.           have an 8087/80287 installed.  
  222.           
  223.           
  224.           
  225.                              ARROWSOFT ASSEMBLY LANGUAGE
  226.           
  227.           As we mentioned earlier, the Arrowsoft  Assembly  Language  is  a
  228.           superset of the well-known Microsoft Macro Assembler Language. We 
  229.           modeled  our system after Microsoft's for two reasons: First, the
  230.           language has a flexible and moderately powerful  macro  facility;
  231.           second,  and for this public domain project most important, there
  232.           is a plethora of third-party books which explain how  to  program
  233.           using the  Microsoft product.  We recommend that you purchase one
  234.           of these guides if  you  are  not  familiar  with  8086  assembly
  235.           language.   If  you  would  like  to  take  advantage of the many
  236.           extensions to the Microsoft Language we have implemented  in  the
  237.           Arrowsoft Assembler, you must do one of two things: Try to figure 
  238.           them  out  for  yourself  (using  experimentation, disassembly or
  239.           anything else you can think of); or  you  can  contact  us  about
  240.           purchasing  the  Arrowsoft Professional Assembler, which includes
  241.           the complete documentation.  Again, please DO NOT CALL  us  about
  242.           the  Arrowsoft  Assembler;  we  will  not answer any questions or
  243.           provide clues as  to  how  to  access  the  assembler's  advanced
  244.           features.  
  245.           
  246.           
  247.           
  248.                    LINKING AND EXECUTING ARROWSOFT OBJECT MODULES
  249.           
  250.           The Arrowsoft Assembler produces relocatable object modules which 
  251.           are  compatible  with  the Microsoft 8086 Object Linker (versions
  252.           3.0 and later).   This  means  that  programs  assembled  by  the
  253.           Arrowsoft   Assembler   may   be   linked  with  other  Microsoft
  254.           Linker-compatible programs  generated  by  other  assemblers  and
  255.           compilers.   If  you  need  more  information  on  how to use the
  256.           Microsoft 8086 Object Linker, see your DOS or Microsoft  language
  257.           manual.  
  258.           
  259.  
  260.  
  261.                                          -3-
  262.  
  263.  
  264.           Arrowsoft Assembler v1.00                            User's Guide
  265.  
  266.  
  267.           By the way, we would like you to know about Arrowsofts Super Link 
  268.           8086/8086  Object  Link  Utility.  Super  Link  is a full-service
  269.           overlaying linker which is fully compatible  with  the  Microsoft
  270.           8086  Object  Linker,  yet  much  faster  and far more versatile.
  271.           Contact us at the address on the cover of this  manual  for  more
  272.           information.  
  273.           
  274.           
  275.           
  276.                               ASSEMBLER ERROR MESSAGES
  277.           
  278.           An  Arrowsoft  Assembler  error report consists of three parts: A
  279.           source file line number,  an  error  number  and  a  terse  error
  280.           description.   In  most  cases,  the  error messages, in spite of
  281.           their brevity, are self explanatory.    However,  for  those  few
  282.           messages  which  require  addtional  elaboration,  we  offer  the
  283.           following explanations: 
  284.           
  285.           
  286.           2 Internal error 
  287.           
  288.           This message will appear only if an  error  occurred  within  the
  289.           assembler itself.    If  you  see  this  message,  please send an
  290.           assembly listing of  the  source  file  and  any  other  relevant
  291.           information (DOS version, assembler version, etc.) to the address 
  292.           on the cover of this manual.  
  293.           
  294.           
  295.           68 Can't reach with segment reg 
  296.           
  297.           You have not issued the appropriate ASSUME directive.  
  298.           
  299.           
  300.           99 Line too long expanding <symbol> 
  301.           
  302.           Expanding  an  EQU-defined symbol would result in a line too long
  303.           for the assembler to handle.  Check for inadvertent recursion  in
  304.           the symbol.  
  305.           
  306.           
  307.           Out of Memory 
  308.           
  309.           Either  the source file exceeds the 64K limit of the assembler or
  310.           the symbol table exceeds  its  allocation.    If  this  condition
  311.           occurs,  try  assembling without creating list or cross-reference
  312.           files.  If this doesn't work, try dividing your source code  into
  313.           several smaller source files and assembling them separately.  The 
  314.           resulting code  may  then be linked with a link utility.  (Again,
  315.           we can't resist pointing  out  that  the  Arrowsoft  Professional
  316.           Assembler  uses ALL available memory for the assembly process; in
  317.           fact, it will assemble a file of arbitrary  size,  regardless  of
  318.           memory limitations.) 
  319.           
  320.           
  321.           Internal Error 
  322.           
  323.           See the explanation for error number 2 above.  
  324.           
  325.  
  326.  
  327.                                          -4-
  328.  
  329.  
  330.           Arrowsoft Assembler v1.00                            User's Guide
  331.  
  332.  
  333.           
  334.           
  335.                         THE ARROWSOFT PROFESSIONAL ASSEMBLER
  336.           
  337.           Our  real reason for giving you this program free of charge is to
  338.           encourage you to purchase our commercial product,  the  Arrowsoft
  339.           Professional Assembler. The program you have now differs from the 
  340.           full   program  in  only  three  respects:  (1)  It  includes  no
  341.           documentation  for  those  language  features  which  extend  the
  342.           Microsoft  Macro Assembly Language (although they are implemented
  343.           by the public domain version); (2) the maximum input file size is 
  344.           limited to 64K bytes; and (3) it is not supported via our 24 hour 
  345.           toll-free help line (in fact, it is not supported at all by  us).
  346.           With these 3 exceptions, the program you now have is identical to 
  347.           the Professional Assembler.  
  348.           
  349.           If  you  decide you'd like to purchase the Arrowsoft Professional
  350.           Assembler, send a postcard requesting our catalog to the  address
  351.           on the  cover  of  this  manual.    Our catalog will show you our
  352.           entire line of professional  software  development  products  and
  353.           will  convince you that our quality and prices are as competitive
  354.           as you will find anywhere.  
  355.           
  356.           
  357.           
  358.                            CONCLUDING REMARKS AND CREDITS
  359.           
  360.           Again, we would like to thank you for trying  our  product.    We
  361.           hope  that  the  remarks  we've  made  concerning our programming
  362.           products (Arrowsoft Professional Assembler and  Super  Link  8086
  363.           Object  Linker)  have  piqued  your  curiosity enough that you'll
  364.           write to us for more information.  Further, we hope that actually 
  365.           using one of our products has convinced you of our dedication  to
  366.           quality and  performance.  Finally, we hope to welcome you to our
  367.           growing family of satisfied customers.  
  368.           
  369.           Even if you don't buy anything from us, you can do  us  a  favor.
  370.           We  want you to distribute this product to all of your friends by
  371.           any means possible.  You may post it to bulletin boards, offer it 
  372.           through your computer club or just copy it and  pass  it  around.
  373.           We  only  ask that (1) you charge nothing for the software beyond
  374.           reasonable copying and disk costs and (2) that you distribute the 
  375.           two  files   (ASM.EXE   and   ASM.DOC)   together   and   without
  376.           modification.  
  377.           
  378.           The  Arrowsoft Assembler was written by Kaplan 'Kap' Morovitz and
  379.           tested by the programming staff at Arrowsoft. Since 'Kap'  writes
  380.           only  in assembly language and C, this manual was written by Stan
  381.           Goldwyn-Benton.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                          -5-
  394.  
  395.