CD Actual 13/CDA13.ISO/cdactual/demobin/share/program/Asm/AMSCLS.ZIP/AMSCLS.DOC

Text File | 1991-06-09 | 16.4 KB | 555 lines

              "A-MACROS"
 Control Logic Structure Macros for MASM
                Ver.2.10
      written by Hortens S. Endoh
        06/Jun/1986 17/Jul/1987
               13/Feb/1991

  Copyright (C) Jun.1986 Hortense S. Endoh

--------------------------------------------

       Modified by H.Yoshizaki for
     correcting conditional $_break
        and optimizing $_until.
               11/Feb/1991

--------------------------------------------

1. AMSCLS. BRIEF HISTORY
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This Assembler Macro set is an include file for Microsoft's Macro
 Assembler MASM to write control structures easier in source code.
 The first part of it appeared originally on October issue of a Japanese
 Computer Magazine ASCII as a series of articles.
 Mr.Takuya Nishimura has succeeded the article after November. Later, the
 Macro-set was sold as a part of Disk Service from ASCII Cooperation with
 the title "Assembler Macro-Programming Techniques/A-MACROS".
   This Macro Set is a minor version ups of the version originally in
 the Disk version, and the speed of assembling is improved 40 to 50 percent
 less than the time needed in the original version.
   The Original Disk service from ASCII has almost sold out recently.
 We have heard frequent requests for the reproduction and told by many
 people that the MACRO set has been used continuously. Hence we have
 made a negotiation with ASCII cooperation so that we may distribute the
 package as a free-ware from January 1991. Two macros $_ldptr and $_stptr
 are contributed by Mr.T.Nishmura.

   After ver 2.01a, the macro set is revised by Haruyasu Yoshizaki
 for the bugs in the codes generated by $_break blknm,stmt,cnd Macros,
 and the routine for $_until is optimized.



2. Environments.
   ~~~~~~~~~~~~~
 This Macro-set is supported for MSDOS ver 2.11 or later with MASM ver 1.27.
 We recommend you to use it with MASM ver 5.1 for we has made an extensive
 tests with this version. If you are familiar with OPTASM from SLR Co.,
 then you had better use the macro-set with it. We are quite sure that
 this set will work well with all the versions of OPTASM. There should be no
 conflicts with TASM from Borland International, though if anything wrong
 should happen with TASM please let us know. PASM from Phoenix Co. is not
 compatible with our Macro package.

 To use the control structure in you program, please include the set
 near the top of your source code.

        include    amscls.inc            This is where you include.
        $_init GEN                       Initialize Macro Set.
        :
        :
code    segment
        assume    cs:code
        org    0100h
        :
        :
        $_for <mov AX, 1>, <<cmp AX, 255>, LE>, <inc AX>   Macro is used here.
            $_if <cmp CH, 2>, E
                mov    CH, 0
            $_else
                $_if <cmp CH, 4>, E
                    mov    CL, test_data[BX]
                    mov    CH, 08h
                $_endif
            $_endif
            :
        $_enddo
        :
        :
code    ends
        end


3. Usage and Definitions.
   ~~~~~~~~~~~~~~~~~~~~~~

 We have carefully designed that the macro package should not generate any
 unexpected codes in your objects. You will have no difficulty understanding
 the control structures. The examples are self-explanatory we hope.

 Here begins the description of each Control Structures.


 $_INIT Initialize.
 ==================

 SYNTAX:

    $_init [ GEN ] [, { COM| NEAR | FAR } ]

 SUMMARY:  You must first call this routine before you use any macro
 -------   in the set. The first parameter 'GEN' if specified, you will
           get expanded listfile. The second parameter is to specify
           models. The default is 'NEAR'. You don't need to specify any
           if you are calling this macro set in a block.

 NOTE:     ALL the parameters must be specified in UPPER_CASE.
 -----



 $_IF,  $_C, $_ENDIF conditional branch.
 =======================================

 SYNTAX:
 ------

    $_if  condition_1
    [ $_c condition_2 ]
          :
    [ $_c condition_n ]
          :
    [ $_else ]
          :
    $_endif

  SUMMARY:    Checks each condition associated with an $_if and $_c
  --------    directive until a true (nonzero) expression is
              found, then processes the : <text-block> associated with
              that test expression. If there is a $_else clause, the
              : <text-block> associated with it is processed only if no
              test expression in the $_if clauses has a nonzero
              value. $_c is the combined condition directive.


  EXAMPLE:
  --------

    $_if <cmp flag, 0>, E, AND
    $_c <cmp AX, 0>, L
        neg    AX
        mov    flag, 1
    $_else
        mov    flag, 0
    $_endif


 $_WHILE repeating block structure 1.
 ====================================

 SYNTAX:
 -------
    $_while condition_1  [ ,block ]
      [ $_c condition_2 ]
         :
      [ $_c condition_n ]
         :
         [ $_break [ block ] ]
         :
    $_enddo

  SUMMARY:   Execute block repeatedly until condition_1 etc
  -------    become false. If the condition_s are not true
             the control moves to the line after $_enddo.
             By using $_break macro, you may exit from the block.


  EXAMPLE:
  -------
    mov    CX, 100
    $_while <cmp CX, 1>, GE
        mov    tbl[BX], word ptr 0
        $_if <cmp BX, 8000h>, GE
            xor   BX, BX
            $_break
        $_endif
        inc    BX
        inc    BX
        dec    CX
    $_enddo

  NOTE:  Please note the following example is an endless loop,
  ----   less you should use $_break exit.

    $_while <TRUE>
           :
           :
        $_if <cmp AX, 1>, E
            $_break
        $_endif
           :
    $_enddo


  $_DO repeating block 2.
  ======================
   SYNTAX:
   --------

    $_do [ block ]
                :
               [$_break [ block ]]
                :
                :
    $_until condition_1 [ , block ]
      [ $_c condition_2 ]
       :
      [ $_c condition_n ]

   SUMMARY: $_until structure checks the exit condition from the loop
   -------  at the end, and hence the loop is executed at least once.
            $_break enables exiting from the block.

 EXAMPLE:
 -------
    mov    BX, 0
    $_do
        mov    AL, tbl[BX]
        $_if <cmp AL, 00h>, E
            $_break
        $_endif
        inc    BX
    $_until <cmp BX, 100h>, GE

 NOTE: As a condition any one of the following directives
 ----  may be specified. LOOP,LOOPE,LOOPNE,LOOPNZ,LOOPZ.


    mov   CX, 32
    $_do
         :
         :
    $_until <LOOP>

 NOTE:  Next example shows a loop executed only once. Jump to the preceding
 -----  block may be expressed by this way. There is no essential difference
        with simple Jumps.

    $_do
           :
           :
        $_if <cmp AX, 255>, E
            $_break
        $_endif
           :
    $_enddo


 $_FOR repeating structure 3.
 ============================

  SYNTAX:
  -------
     $_ for <init-expr>, <cond-expr>, <loop-expr> [,block ]
            :
            :
          [ $_break [ block ] ]
            :
     { $_endfor | $_enddo }

 SUMMARY: Same as ' for' in C.   Executes <statement> repeatedly.
 -------- First, the initialization (<init-expr>) is evaluated.
          Then, while the conditional expression (<cond-expr>) consisting
          of command directive pair, holds true, <statement> is executed
          and the loop expression (<loop-expr>) is evaluated.
          When <cond-expr> become false, control passes to the statement
          following the $_endfor or $_enddo.

 EXAMPLE:
 --------
    $_for <mov AX, 1>, <<cmp AX, 255>, LE>, <inc AX>
        $_if <cmp CH, 2>, E
            mov    CH, 0
        $_else
            $_if <cmp CH, 4>, E
                mov    CL, test_data[BX]
                mov    CH, 08h
            $_endif
        $_endif
        call test_proc
    $_endfor

 $_SWITCH Multiple branches.
 ===========================
 SYNTAX:
 -------

    $_switch [ register ] [,block ]
        $_case condition_1-1
        [ $_c condition_1-2 ]
          :
        [ $_c condition_1-n ]
                :
                :
            [ $_break [ block ] ]
        $_case condition_2-1
        [ $_c condition_2-2 ]
           :
        [ $_c condition_2-n ]
                :
                :
            [ $_break [ block ] ]
            :
         $_case condition_m-1
         [ $_c condition_m-2 ]
            :
         [ $_c condition_m-n ]
                 :
                 :
             [ $_break [ block ] ]
         [$_default]
                 :
                 :
       $_endswitch



 SUMMARY:    Evaluates <$_c condition_j-k> and executes any line(s)
 -------     associated with <$_c condition_j> whose value matches
             the initial expression. If there is no match with a
             condition(s), the lines associated with the $_default
             is executed. If the $_default is not given, control passes
             to the block following the $_endswitch block. You may
             execute only one of the block which fits your condition
             by inserting $_break.

             Use of a register enables fast branching with the use of
             address conversion table. You may specify one of these
             registers:
                 BX,BP,SI,DI
             with conditions call by parameters like "<3,5ah,7>", without
             using $_c macro. The value of the parameters must be less
             than 128. You must prepare $_table, data macro, inside the
             block.


 EXAMPLE:
 -------
    $_switch
        $_case <cmp AH, 0>, E
            mov    BH, ON
            $_break
        $_case <cmp AH, 1>, E
            mov    AX, 0200h
            $_break
        $_default
            inc    tbl_ptr
    $_endswitch

 EXAMPLE: Use of a register for multiple selection. You must use
 -------  UPPER CASE for the name of the register.
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    $_switch  BX
        $_case <0, 2, 4, 6>
            mov    CX, 1
            $_break
        $_case <1, 3, 5, 7>
            mov    CX, 0
            $_break
        $_default
            mov    CX, 0ffffh
    $_endswitch
    :
    :
    $_table                 ; you must supply a table in the data area.
    :


 $_BREAK Exit from Repeating or Selection structures.
 ====================================================

 SYNTAX:
 -------

   $_break [ block ] [,< cmd>, operator ]

 SUMMARY:  You can exit from the control structure where your
 -------   control is presently resides, with $_break, in any
           type of control structure described above.
           If you supply block name after $_break, control is passed to
           the block. Or you may specify an operator following a command
           which decides the exit.




 $_C Conditional.
 ===============
 SYNTAX:
 ------
    Macro < Command >, Operator,[ Logical Operator ]

 SUMMARY: Describe conditions for branch on condition or selection
 -------- by condition. You may execute a line before the evaluation
          of the condition, else you will evaluate the result of
          the preceding block.
 EXAMPLE:
 --------
    :                ;this is the line preceding before evaluation
    $_if <>, GE
       :
       :
    $_endif

 NOTE:    The following operators can be used as comparison operators:
 ----     A,AE,B,BE,C,E,G,GE,L,LE,NA,NAE,NB,NBE,NC,NE,NG,NGW,NL,NLE
          NO,NP,NS,NZ,O,PE,PO,S,Z.

          Logical operators are to be used for the logical relations
          among multiple conditions. You can use AND and OR.
          Always AND is evaluated first and the OR 's are evaluated.
          Associative laws of Boolean algebra can be applied with
          Logical ORs and ANDs. You must use UPPER CASE for OPERATORS.
                                             ^^^^^^^^^^^^^^^^^^^^^^^^

 EXAMPLE.
 -------

    $_if < command line >, OPERATOR, AND --+---------------------*
    $_c  < command line >, OPERATOR, OR  --*                     +
    $_c  < command line >, OPERATOR, AND -------*                |
    $_c  < command line >, OPERATOR, AND        +---------------=:
    $_c  < command line >, OPERATOR, OR  -------*                +
    $_c  < command line >, OPERATOR, ----------------------------*
         :
         :
    $_endif

  NOTE:  Combined conditions are expressed by $_c Macros.
         You may call $_c Macro after evaluating a condition with logical
         operators, including $_c macro may be.
         A line or lines may be executed between $_c Macros.


    $_if <cmp AX, 1>, NE, AND
    mov    BX, test_idx               ; line executed before next $_c.
    $_c <cmp test_data[BX], 10h>, E
        :
        :
    $_endif

 $_MACRO_ Offset for conditional Branch.
 ======================================
 SYNTAX:
 -------
     $_macro  -----> $_macro_ .

 SUMMARY:  Macros defined and explained above will generate labels and
 --------  branch or jump on condition(s). Since branch and jump are
           all relative jumps in 8086 processor, you must supply some
           information for the relative jumps of offset more than 128
           in size. The information is specified by adding  trailing '_'
           to a macro.

 EXAMPLE:
 --------

    $_if_ <cmp AX, 0>, E
            :
            :
            :
            :
            :
    $_else_
            :
            :
            :
            :
    $_endif_

 NOTE:   If you use SLR's OPTASM, you will not need this trailing
         underscore. OPTASM will take all the care of large offset
         above 128.


 RESTRICTION.
 ============
   The depth of nesting in AMSCLS is at most 16, where you count
   each branch 1, each repeating structure 2. To the best of my
   knowledge, the number of a label in a code segment has no
   restriction from our macro set structure. There is definitely
   an upper limit from MASM it self.


 $_PUSH,$POP ,store and restore registers.
 =========================================

 SYNTAX:
 -------
    $_push < registers > [, identifier ]
       :
       :
       :
    $_pop [ identifier ]

 SUMMARY: A group of parameter values on specified registers is pushed
 -------- in with identifier. There is no need to use an identifier if
          you are in a simple situation. If you nest PUSH and POPs in
          a block, you had better assign an identifier. The parameter
          values are restored by calling a $_pop macro with the same
          identifier.

 EXAMPLE:
 --------

    $_push    <ax, bx, cx, di, ds>, 01
    xor    bx, bx
    mov    ds, bx
    :
    :
    :
    $_pop 01


 4. REMARKS.
  ~~~~~~~~~
    This macro set was programmed when I was just started to program
  Micro-Computers. Cap!Niss, Takuya Nishimura wrote an article for this
  macro set with three structures of his own contribution. Similarly,
  this document itself is a revision of his original document in the
  disk service version from ASCII cooperations.
    I have done a similar macro-package for MACRO-80 assembler.
  I can supply the MACRO-80 version, source code only upon request.


  5. Distribution and Copyright.
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This package, amscls.doc and amscls.inc, is under the protection of
 Copyright. You may use this software for the programming with any language
 on the condition that you add the following copyright to your product.


   A-MACROS / Control Logic Structure Macros.
   AMSCLS.INC (c) Hortense S. Endoh 1986, 1987


 You may copy and redistribute this software through BBS. We would
 appreciate if you would continue to upload the future revisions.
 You must distribute this document with the Macro Package, too.


 6. How to contact us :
 ~~~~~~~~~~~~~~~~~~~~~~
 Hortense S. Endoh  ASCII-NET (PCS) pcs17331
                    NIFTY-SERVE GGH03436
                    Nikkei-MIX  hortense

 Or E-mail K.OKUBO at 74100,2565 compuserve
                      K.OKUBO Genie
                      [e-mail]
 12/Feb/1991