Click above to get retro games delivered to your door ever month!

           INTRODUCTION TO ASSEMBLER LANGUAGE FUNCTIONS


     Firstly, it is recommended that this section be read in
     conjunction with the Clipper Extend System documentation for
     Assembly Language programming.  It is also recommended that the
     include files supplied with 'The Library' and Clippers
     EXTENDA.INC is close at hand for perusal.

     Many of the functions of 'The Library' were written in Assembler
     Language as can be seen from the source code provided.

     Assembly Language programs, by their very nature, are extremely
     fast. The Assembler converts the assembly language mnemonics into
     machine code which is the .lowest. level at which the Central
     Processing Unit (CPU) can be addressed.  All of the tools we use
     to inspect and examine the contents of memory display and
     represent that information in hexadecimal notation because it is
     far easier to deal with than binary notation. However, as far as
     the CPU is concerned each memory location contains nothing but a
     series of binary digits regardless of what that location
     represents to us!

     Put another way, when programming in assembler language we are
     effectively programming in the CPU.s native tongue.

     Assembly Language programming is not without its disadvantages.
     It is said to be difficult to learn because of its low level
     nature and code development frequently takes considerably longer
     than when using other high level languages.  But learning
     assembly language programming can be made easier by obtaining
     copies of good reference material and example programs.  This is
     often easier said than done but much more information is
     available now than before.


     The DOS Technical Reference Manual and DOS Programmer.s Reference
     Manual are essential. They contain information generally needed
     about DOS when programming in Assembly Language rather than how
     to program in Assembler.

     Many potential assembler language programmers may not be aware of
     the fact that 20% of the assembler instructions are used 80% of
     the time. Only a relatively small subset is needed to get
     started.  This can be confirmed by examining some of the source
     code provided.

     Assembly language programming offers maximum speed and small code
     size and it is for this reason that they were written in
     Assembler.


     The Extend System

     Examination of the source code for the functions written in
     assembler would reveal that they all follow a very similar
     pattern in the way they were written.  As expected, they all make
     use of Clipper.s Extend System.

     The Extend System is the mechanism by which C and Assembly
     Language may interface to Clipper.  Clipper maintains its own
     internal data storage space or stack and this is not directly
     available to C or Assembler.  If it were it could/would be easily
     corrupted!  The functions which constitute the Extend System
     allow data to be passed between Clipper and Microsoft.s FORTRAN,
     PASCAL, C and Assembler.

     Whilst not intending to duplicate the contents of the Clipper
     manual, the functions for the checking of data types take the
     form:-

          __ISxxxxx() where xx denotes the data type to be checked.

     Please note the double underscore (__) which precedes the
     function names above.

     Most usefully, Clipper provides a facility for determining the
     number of parameters which were passed to a function from
     Clipper.  This is by way of a variable named pcount.

     The functions for receiving data from Clipper into Assembler all
     take the form:-

          __PARxx() where xx is used to denote the type of data
     received from Clipper. i.e Integer, Long, Double, Character, Log,
     arrays etc.  A function is provided for each type.

     Clipper also provides a set of functions which returns to Clipper
     different data types.  A function is also provided for each data
     type and takes the form:-

          __RETxx() where xx denotes the data type.


     Include files

     Of especial interest to the Assembly Language programmer is the
     file, mentioned earlier, called EXTENDA.INC.

     This file, which is provided with the Summer .87 version of
     Clipper, makes assembly language programming for Clipper far
     easier than before.  EXTENDA.INC, with its definitions of macros,
     allow the programmer to concentrate on the desired aspects of the
     function rather than getting involved in the processes of
     receiving and returning of values to and from Clipper.  This was
     mandatory with the Autumn .86 version of Clipper.

     EXTENDA.INC makes it mostly unnecessary to get involved at all
     with the __PAR, __RET or __IS functions provided.  This of course
     depends upon the type of functions which are being developed but
     most of the work is taken care of by the macros in this file.

     The following macros listed below with a brief description of
     their function are all defined in EXTENDA.INC.  These macros are
     used in each of the assembler functions provided.  CLstatic and
     pcount were the exceptions as they were not always required.

          CLpublic  Makes functions publicly accessible.
          CLfunc    Specifies input and return variables if any.
          CLcode    Specifies the start of code.
          CLret     Indicates variables/registers to be returned.
          CLstatic  Specified variables to be used locally.
          pcount    Contains the number of parameters passed.
                    This variable is created by the CLcode macro.

     Other include files were developed when writing the assembly
     language functions provided here and also have a file extension
     of .INC.  The include files are referenced at the start of each
     function and there is one include file for each of the areas that
     the assembly language programs cover.

     Each function will make reference to these two include files
     like:-
               include global.inc
               include extenda.inc

     For the record, include files are simply files of text which may
     contain any number of valid assembler instructions or directives.

     A typical directive might instruct the Assembler to assemble the
     function to the large memory model specification which Clipper
     expects.  Inspection of EXTENDA.INC will reveal many such
     directives which are usually easily identified because they tend
     to be prefixed with a period (.).  Not all directives are
     prefixed with a period though.  The above two instructions,
     include global.inc and include extenda.inc, are directives which
     instruct the Assembler to load the contents of global.inc and
     extenda.inc into memory.  If any reference is made to any macro
     definitions or declared constants within the .INC files by the
     current function, those macros and/or constants would be inserted
     into the program being generated at the point they were
     referenced.

     The source file containing the directives is not affected.

     As the contents are simply inserted into the code each time an
     include directive is encountered the contents of the include
     files must be relevant.

     GLOBAL.INC is the only include file which mainly contains those
     constants which are required by all the assembly language
     functions.

     All the other include files contain macros.


     Macros

     In assembly language parlance macros are simply a sequence of
     instructions surrounded by the two keywords MACRO and ENDM and
     must be named.

     terminate MACRO
               XOR       AX,AX
               INT       21h
               ENDM

     The above is a simple example of a macro named terminate and is
     typical of what is contained in an include file.  The example
     below gives an example of a macro to which a parameter must be
     passed.

     display        MACRO     string
               MOV  AX,9
               LDS  DS,string
               INT  21h
               ENDM

     To use a macro the file containing the macro definition must ,of
     course, be included

     When the program is assembled and compiled the contents of the
     include files are loaded into memory and any reference to either
     display or terminate would cause the code between MACRO and ENDM
     to be inserted into the program being produced.  As a result of
     this only those macros referenced will be included in the program
     being produced thus keeping code size to a minimum.


     Assembling using MASM.EXE

     To assemble a program type the following from the DOS prompt
     ensure that MASM.EXE,  the Macro Assembler, in the current
     directory or can be found in the DOS path..

          MASM example;

     This command will cause the file example.asm to be compiled
     producing a file called example.obj.

     A representation of the final code produced can also be generated
     if necessary by typing the following from the DOS prompt.

          SET MASM=/L

     This sets a DOS environment variable which instructs the
     Assembler what to do when compiling.  Compiling again with the
     above example would cause a file called example.lst to be
     produced.  Remember to turn off this facility if it is no longer
     needed by typing:-

          SET MASM=

     For more information on using MASM please consult your Macro
     Assembler Reference Manual.


     Summary

     The Assembler Language functions were written with consistency
     and, without doubt, an element of education in mind.  There is
     also no doubt that many of the functions could be written
     differently, simplified or improved but probably so could any
     other program.

     If the incorrect number of parameters are passed to a function or
     if the type of parameters passed are of the wrong type syntax
     error, -1 , is returned.  For those functions which return a
     logical value false is returned.