home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 23 / IOPROG_23.ISO / SOFT / ASM / VALARROW.ZIP / ASM.DOC next >
Encoding:
Text File  |  1995-04-16  |  17.5 KB  |  415 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.  
  67.  
  68.  
  69.  
  70.           Arrowsoft Assembler v1.00                            User's Guide
  71.  
  72.  
  73.  
  74.  
  75.                                     INTRODUCTION
  76.           
  77.           Thank  you  for  trying  out  the  public  domain  version of our
  78.  
  79.           Arrowsoft Assembler.  We feel that the best way to alert you, the 
  80.  
  81.           programmer, to our fine line of professional products is  to  let
  82.  
  83.           you use one.  Once you have experienced the high quality and ease 
  84.  
  85.           of  use  of  this  free product, we hope that you will contact us
  86.  
  87.           regarding our other software (our address is on the cover of this 
  88.  
  89.           manual).  
  90.  
  91.           
  92.           You will no doubt notice that this manual is not  exhaustive;  in
  93.  
  94.           fact,  it  includes  the  least  amount of information we felt we
  95.  
  96.           could include without robbing  the  program  of  its  usefulness.
  97.  
  98.           There  are  two reasons for the brevity of this manual: First, we
  99.  
  100.           have targeted professional software developers with our products, 
  101.  
  102.           and we suspect that an  experienced  professional  will  have  no
  103.  
  104.           trouble  figuring out how to use the Arrowsoft Assembler with the
  105.  
  106.           information given; second, the program is, after all, free and we 
  107.  
  108.           feel that the quality of this assembler will more that compensate 
  109.  
  110.           you for the time you spend learning to use it.  
  111.  
  112.           
  113.           Please note that this is NOT a supported product.  If you contact 
  114.  
  115.           us, we will be happy to discuss our line of software but we  will
  116.  
  117.           NOT answer questions about the Arrowsoft Assembler.  
  118.  
  119.           
  120.           Again, we thank you for giving our product a try.  
  121.  
  122.           
  123.           (NOTE: 'Microsoft' and 'Microsoft Macro Assembler' are trademarks 
  124.  
  125.           of  Microsoft  Corporation.  'Arrowsoft', 'Arrowsoft Professional
  126.  
  127.           Assembler' and 'Super Link' are trademarks of Arrowsoft  Systems,
  128.  
  129.           Inc.) 
  130.  
  131.           
  132.           
  133.           
  134.                                       OVERVIEW
  135.           
  136.           The  Arrowsoft Assembler takes as its input 8086, 8088, 80186 and
  137.  
  138.           80286 assembly language source  files  and  produces  relocatable
  139.  
  140.           object  modules  which may be linked and run under the MS-DOS and
  141.  
  142.           PC-DOS operating systems.  The syntax of the  input  files  is  a
  143.  
  144.           superset  of  that  accepted  by  the  Microsoft  Macro Assembler
  145.  
  146.           (versions 3.0 and later).  In fact, most programs written for the 
  147.  
  148.           Microsoft product should assemble without modification  with  the
  149.  
  150.           Arrowsoft Assembler.  
  151.  
  152.           
  153.           The  remaining sections of this manual will cover, in this order,
  154.  
  155.           assembler command line options,  input  language  specifications,
  156.  
  157.           linking  and execution of assembled object modules, and assembler
  158.  
  159.           error messages.  
  160.  
  161.           
  162.           
  163.           
  164.                           INVOKING THE ARROWSOFT ASSEMBLER
  165.           
  166.           You may run the Arrowsoft  Assembler  interactively  or  directly
  167.  
  168.           from the   DOS   command   line.      To   invoke  the  assembler
  169.  
  170.           interactively, simply type 
  171.  
  172.           
  173.  
  174.  
  175.  
  176.                                          -1-
  177.  
  178.  
  179.  
  180.  
  181.  
  182.           Arrowsoft Assembler v1.00                            User's Guide
  183.  
  184.  
  185.  
  186.  
  187.                    asm
  188.           
  189.           at the DOS prompt and follow the ensuing instructions.    To  run
  190.  
  191.           the assembler non-interactively, use the following syntax: 
  192.  
  193.           
  194.                    asm source [,object] [,list] [,xref] [options] [;]
  195.           
  196.           where  'source'  is  a  filespec  for  the  source  file (default
  197.  
  198.           extension .ASM), 'object' is  a  filespec  for  the  object  file
  199.  
  200.           (default  extension  .OBJ),  'list' is a filespec for the listing
  201.  
  202.           file (default extension .LST) and 'xref' is a  filespec  for  the
  203.  
  204.           cross-reference  file  (default  extension  .CRF).  Note that all
  205.  
  206.           filespecs may consist of a drive letter, a pathname,  a  filename
  207.  
  208.           and an  extension.    If  the  object  file is not specified, the
  209.  
  210.           assembler will use the source filename with the  .OBJ  extension.
  211.  
  212.           If  the  list  and  cross-reference  files are not specified, the
  213.  
  214.           assembler will not produce them.  Finally, the semicolon (;) will 
  215.  
  216.           force the assembler to assume default values for any  unspecified
  217.  
  218.           parameters.  
  219.  
  220.           
  221.           
  222.           
  223.                                     OPTION CODES
  224.           
  225.           The options  list  consists of a sequence of option codes.  These
  226.  
  227.           option codes consist of a slash (/) or dash (-) followed  by  one
  228.  
  229.           or more letters, case being insignificant.  Most of these options 
  230.  
  231.           are compatible with Microsoft conventions.  
  232.  
  233.           
  234.                    /A             Write segments in alphabetical order
  235.                    /Bnumber       Set buffer size
  236.                    /Dsymbol       Define assembler symbol
  237.                    /E             Generate 8087/80287 emulator code
  238.                    /Ipath         Set 'include' search path
  239.                    /ML            Case sensitive internal labels
  240.                    /MX            Case sensitive external and public labels
  241.                    /MU            Convert labels to uppercase
  242.                    /R             Generate 8087/80287 floating point code
  243.                    /S             Write segments in source code order
  244.                    /X             Include false conditionals in listing
  245.                    /Z             Display error lines on screen
  246.           
  247.           
  248.           Many  of  these  command  line  options are self explanatory; for
  249.  
  250.           whose which aren't, see the descriptions below: 
  251.  
  252.           
  253.           
  254.           /B Set Buffer Size 
  255.  
  256.           
  257.           Sets the size of the buffer used to hold the source  file  during
  258.  
  259.           assembly.   The  'number'  is the number of 1K pages reserved for
  260.  
  261.           use as a buffer.  You may  set  the  buffer  size  to  any  value
  262.  
  263.           between  1K  and  63K;  default  buffer  size is 32K. Note that a
  264.  
  265.           larger buffer can speed assembly of large files considerably.  
  266.  
  267.           
  268.           
  269.           /E Generate 8087/80287 Emulator Code 
  270.  
  271.           
  272.  
  273.  
  274.  
  275.                                          -2-
  276.  
  277.  
  278.  
  279.  
  280.  
  281.           Arrowsoft Assembler v1.00                            User's Guide
  282.  
  283.  
  284.  
  285.  
  286.           If you are writing programs for use with the  8087/80287  numeric
  287.  
  288.           processor on a machine which does not have the processor, and you 
  289.  
  290.           have  an  8087/80287  emulator  library  available, the /E option
  291.  
  292.           directs the assembler to generate code for the emulator.  
  293.  
  294.           
  295.           
  296.           /I Set 'include' file search paths 
  297.  
  298.           
  299.           You may direct the assembler to search up to  5  directories  for
  300.  
  301.           'include'  files  by  including  a  '/Ipath'  command for EACH of
  302.  
  303.           them.  For example,  to  set  the  search  paths  '\bin\lib'  and
  304.  
  305.           '\asm\lib',   include   the   following  in  your  options  list:
  306.  
  307.           /I\bin\lib/I\asm\lib.  
  308.  
  309.           
  310.           
  311.           /R 
  312.  
  313.           
  314.           This option directs the assembler to generate floating point code 
  315.  
  316.           for the  8087/80287  numeric  processor.    Note  that   programs
  317.  
  318.           assembled  with  the  '/R' option will run ONLY on machines which
  319.  
  320.           have an 8087/80287 installed.  
  321.  
  322.           
  323.           
  324.           
  325.                              ARROWSOFT ASSEMBLY LANGUAGE
  326.           
  327.           As we mentioned earlier, the Arrowsoft  Assembly  Language  is  a
  328.  
  329.           superset of the well-known Microsoft Macro Assembler Language. We 
  330.  
  331.           modeled  our system after Microsoft's for two reasons: First, the
  332.  
  333.           language has a flexible and moderately powerful  macro  facility;
  334.  
  335.           second,  and for this public domain project most important, there
  336.  
  337.           is a plethora of third-party books which explain how  to  program
  338.  
  339.           using the  Microsoft product.  We recommend that you purchase one
  340.  
  341.           of these guides if  you  are  not  familiar  with  8086  assembly
  342.  
  343.           language.   If  you  would  like  to  take  advantage of the many
  344.  
  345.           extensions to the Microsoft Language we have implemented  in  the
  346.  
  347.           Arrowsoft Assembler, you must do one of two things: Try to figure 
  348.  
  349.           them  out  for  yourself  (using  experimentation, disassembly or
  350.  
  351.           anything else you can think of); or  you  can  contact  us  about
  352.  
  353.           purchasing  the  Arrowsoft Professional Assembler, which includes
  354.  
  355.           the complete documentation.  Again, please DO NOT CALL  us  about
  356.  
  357.           the  Arrowsoft  Assembler;  we  will  not answer any questions or
  358.  
  359.           provide clues as  to  how  to  access  the  assembler's  advanced
  360.  
  361.           features.  
  362.  
  363.           
  364.           
  365.           
  366.                    LINKING AND EXECUTING ARROWSOFT OBJECT MODULES
  367.           
  368.           The Arrowsoft Assembler produces relocatable object modules which 
  369.  
  370.           are  compatible  with  the Microsoft 8086 Object Linker (versions
  371.  
  372.           3.0 and later).   This  means  that  programs  assembled  by  the
  373.  
  374.           Arrowsoft   Assembler   may   be   linked  with  other  Microsoft
  375.  
  376.           Linker-compatible programs  generated  by  other  assemblers  and
  377.  
  378.           compilers.   If  you  need  more  information  on  how to use the
  379.  
  380.           Microsoft 8086 Object Linker, see your DOS or Microsoft  language
  381.  
  382.           manual.  
  383.  
  384.           
  385.  
  386.  
  387.  
  388.                                          -3-
  389.  
  390.  
  391.  
  392.  
  393.  
  394.           Arrowsoft Assembler v1.00                            User's Guide
  395.  
  396.  
  397.  
  398.  
  399.           By the way, we would like you to know about Arrowsofts Super Link 
  400.  
  401.           8086/8086  Object  Link  Utility.  Super  Link  is a full-service
  402.  
  403.           overlaying linker which is fully compatible  with  the  Microsoft
  404.  
  405.           8086  Object  Linker,  yet  much  faster  and far more versatile.
  406.  
  407.           Contact us at the address on the cover of this  manual  for  more
  408.  
  409.           information.  
  410.  
  411.           
  412.           
  413.           
  414.                               ASSEMBLER ERROR MESSAGES
  415.           
  416.           An  Arrowsoft  Assembler  error report consists of three parts: A
  417.  
  418.           source file line number,  an  error  number  and  a  terse  error
  419.  
  420.           description.   In  most  cases,  the  error messages, in spite of
  421.  
  422.           their brevity, are self explanatory.    However,  for  those  few
  423.  
  424.           messages  which  require  addtional  elaboration,  we  offer  the
  425.  
  426.           following explanations: 
  427.  
  428.           
  429.           
  430.           2 Internal error 
  431.  
  432.           
  433.           This message will appear only if an  error  occurred  within  the
  434.  
  435.           assembler itself.    If  you  see  this  message,  please send an
  436.  
  437.           assembly listing of  the  source  file  and  any  other  relevant
  438.  
  439.           information (DOS version, assembler version, etc.) to the address 
  440.  
  441.           on the cover of this manual.  
  442.  
  443.           
  444.           
  445.           68 Can't reach with segment reg 
  446.  
  447.           
  448.           You have not issued the appropriate ASSUME directive.  
  449.  
  450.           
  451.           
  452.           99 Line too long expanding <symbol> 
  453.  
  454.           
  455.           Expanding  an  EQU-defined symbol would result in a line too long
  456.  
  457.           for the assembler to handle.  Check for inadvertent recursion  in
  458.  
  459.           the symbol.  
  460.  
  461.           
  462.           
  463.           Out of Memory 
  464.  
  465.           
  466.           Either  the source file exceeds the 64K limit of the assembler or
  467.  
  468.           the symbol table exceeds  its  allocation.    If  this  condition
  469.  
  470.           occurs,  try  assembling without creating list or cross-reference
  471.  
  472.           files.  If this doesn't work, try dividing your source code  into
  473.  
  474.           several smaller source files and assembling them separately.  The 
  475.  
  476.           resulting code  may  then be linked with a link utility.  (Again,
  477.  
  478.           we can't resist pointing  out  that  the  Arrowsoft  Professional
  479.  
  480.           Assembler  uses ALL available memory for the assembly process; in
  481.  
  482.           fact, it will assemble a file of arbitrary  size,  regardless  of
  483.  
  484.           memory limitations.) 
  485.  
  486.           
  487.           
  488.           Internal Error 
  489.  
  490.           
  491.           See the explanation for error number 2 above.  
  492.  
  493.           
  494.  
  495.  
  496.  
  497.                                          -4-
  498.  
  499.  
  500.  
  501.  
  502.  
  503.           Arrowsoft Assembler v1.00                            User's Guide
  504.  
  505.  
  506.  
  507.  
  508.           
  509.           
  510.                         THE ARROWSOFT PROFESSIONAL ASSEMBLER
  511.           
  512.           Our  real reason for giving you this program free of charge is to
  513.  
  514.           encourage you to purchase our commercial product,  the  Arrowsoft
  515.  
  516.           Professional Assembler. The program you have now differs from the 
  517.  
  518.           full   program  in  only  three  respects:  (1)  It  includes  no
  519.  
  520.           documentation  for  those  language  features  which  extend  the
  521.  
  522.           Microsoft  Macro Assembly Language (although they are implemented
  523.  
  524.           by the public domain version); (2) the maximum input file size is 
  525.  
  526.           limited to 64K bytes; and (3) it is not supported via our 24 hour 
  527.  
  528.           toll-free help line (in fact, it is not supported at all by  us).
  529.  
  530.           With these 3 exceptions, the program you now have is identical to 
  531.  
  532.           the Professional Assembler.  
  533.  
  534.           
  535.           If  you  decide you'd like to purchase the Arrowsoft Professional
  536.  
  537.           Assembler, send a postcard requesting our catalog to the  address
  538.  
  539.           on the  cover  of  this  manual.    Our catalog will show you our
  540.  
  541.           entire line of professional  software  development  products  and
  542.  
  543.           will  convince you that our quality and prices are as competitive
  544.  
  545.           as you will find anywhere.  
  546.  
  547.           
  548.           
  549.           
  550.                            CONCLUDING REMARKS AND CREDITS
  551.           
  552.           Again, we would like to thank you for trying  our  product.    We
  553.  
  554.           hope  that  the  remarks  we've  made  concerning our programming
  555.  
  556.           products (Arrowsoft Professional Assembler and  Super  Link  8086
  557.  
  558.           Object  Linker)  have  piqued  your  curiosity enough that you'll
  559.  
  560.           write to us for more information.  Further, we hope that actually 
  561.  
  562.           using one of our products has convinced you of our dedication  to
  563.  
  564.           quality and  performance.  Finally, we hope to welcome you to our
  565.  
  566.           growing family of satisfied customers.  
  567.  
  568.           
  569.           Even if you don't buy anything from us, you can do  us  a  favor.
  570.  
  571.           We  want you to distribute this product to all of your friends by
  572.  
  573.           any means possible.  You may post it to bulletin boards, offer it 
  574.  
  575.           through your computer club or just copy it and  pass  it  around.
  576.  
  577.           We  only  ask that (1) you charge nothing for the software beyond
  578.  
  579.           reasonable copying and disk costs and (2) that you distribute the 
  580.  
  581.           two  files   (ASM.EXE   and   ASM.DOC)   together   and   without
  582.  
  583.           modification.  
  584.  
  585.           
  586.           The  Arrowsoft Assembler was written by Kaplan 'Kap' Morovitz and
  587.  
  588.           tested by the programming staff at Arrowsoft. Since 'Kap'  writes
  589.  
  590.           only  in assembly language and C, this manual was written by Stan
  591.  
  592.           Goldwyn-Benton.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.                                          -5-
  608.  
  609.  
  610.  
  611. Toad Hall Note, Mar 95
  612.  
  613. A FIDO Echo discussed this package, and someone complained about the
  614. suspicious code in ASM.EXE (it looked like a diskette's boot track!).
  615. Other correspondents thought this suspicious code was the reason VALARROW
  616. wasn't accepted to the SIMTEL20 collection back in the late 80's.
  617.  
  618. Well, I suspected the suspicious text and code was simply an uninitialized
  619. buffer, or something in memory left from a disk read or some such that
  620. had just been left behind during compile.  So I just dove in with a binary
  621. editor and zeroed out all that suspicious code!  And things seem to run
  622. just like always.
  623.  
  624. So let's trying fielding this very useful assembly package again.
  625. Especially since it's getting tough to buy a stand-alone inexpensive
  626. assembler these days :-)
  627.  
  628. David Kirschbaum
  629. Toad Hall
  630. kirschd@hq.ljl.com
  631.