home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 5 / ctrom5b.zip / ctrom5b / PROGRAM / ASM / ALIB30A / ALIB1.DOC < prev    next >
Text File  |  1994-12-18  |  16KB  |  439 lines
  1.         
  2.                             ALIB Version 3.0
  3.                            ==================
  4.                Copyright (C) 1994 Owens Consulting and
  5.                          Jeff Owens,  10-09-94
  6.                           24551 Metzler Park
  7.                           Estacada, OR 97023
  8.  
  9.                           kowens@teleport.com
  10.                                   
  11.  
  12.         What is it?
  13.         -------------
  14.  
  15.         ALIB is a library of common functions needed by assembly
  16.         language programmers.  Some of the functions included in
  17.         ALIB are:
  18.  
  19.            * Database   * Compression   * Memory Manager
  20.            * Menuing    * Floating Math * Hyper text
  21.            * Windowing  * Hardware analysis
  22.  
  23.  
  24.         For years assembly language has been regarded as somewhat
  25.         tedious and difficult, but its small size, unlimited
  26.         freedom, and performance have kept it very much alive.
  27.         This library attempts to remove some of the tedium by
  28.         adding a set of high level functions to the programmers
  29.         arsenal.  With ALIB it is possible to write DOS programs
  30.         in a few minutes.
  31.  
  32.  
  33.         Why was it written?
  34.         -------------------
  35.  
  36.         ALIB was written because the author enjoys Assembler
  37.         and the sharing of code.  Some of the code could be
  38.         improved, but it was felt that a free exchange or code
  39.         is more important than having perfect code.  The author
  40.         encourages communication and questions from anyone who
  41.         shares these beliefs.
  42.  
  43.  
  44.         What hardware and software is needed?
  45.         -------------------------------------
  46.  
  47.         For use with IBM PS/2, XT, PC and compatibles with DOS 2.1
  48.         or greater capability.  The following software will be
  49.         needed to make use of ALIB:
  50.  
  51.         1.  Assembler for 8088,8086,80386, etc.  Known assemblers
  52.             are:  A86 (Shareware), MASM (Microsoft), TASM
  53.             (Borland), OPTASM (SLR Systems).
  54.  
  55.         2.  Linker to handle the .OBJ file produced by
  56.             the assembler.  Linkers are usually sold
  57.             with the assembler except in the case of
  58.             A86.
  59.  
  60.         3.  Debugger for testing.  Many assemblers have
  61.             a companion debugger which is sold separately.
  62.             All of these debuggers are adequate.  The
  63.             old standby DOS DEBUG program will work, but
  64.             it needs symbolic capability for serious
  65.             work.  The independently produced Periscope
  66.             debuggers are also very good.
  67.             
  68.  
  69.         How do I install it?
  70.         --------------------
  71.  
  72.         To initially explore ALIB it is best to place it in a
  73.         separate directory and work with it there.  No special
  74.         installation process is necessary.  Eventually, the
  75.         library itself (ALIB.LIB) can be placed in a common
  76.         directory of assembly tools and the remaining files
  77.         archived.
  78.  
  79.         What files make up ALIB?
  80.         ------------------------
  81.     
  82.         ALIB.LIB         Library of functions
  83.         ALIB1.DOC        General information
  84.         ALIB2.DOC        Summary of library functions 
  85.         ALIB3.DOC        Detailed description of library functions
  86.         TEMPLATE.ASM     Sample format for most programs
  87.         COMMON.INC       Inputs for sample programs
  88.         MAC.INC          Macros for sample programs
  89.         LOAN.ASM         Sample program, computes loan parameters
  90.         LOAN.EXE
  91.         COMPRES.ASM      Sample program, compress a file
  92.         COMPRES.EXE
  93.         RESTOR.ASM       Sample program, uncompress a file
  94.         RESTOR.EXE
  95.         DISKINFO.ASM     Sample program to display DOS disk info.
  96.         DISKINFO.EXE
  97.         EDREC.ASM        Sample program & library utility (see file)
  98.         EDREC.EXE        
  99.         HYPER.ASM        Sample program to demonstrate hyper text
  100.         HYPER.DAT        Hyper text data for HYPER.EXE
  101.         HYPER.EXE        Sample program and tutorial
  102.         SCAN.ASM         Sample program to scan disk files
  103.         SCAN.EXE
  104.         SORT.ASM         Sample program to sort data in a file
  105.         SORT.EXE
  106.         TIMER.ASM        Sample program to time code or programs
  107.         TIMER.EXE
  108.         MEMORY.ASM       Sample program to show memory status
  109.         MEMORY.EXE
  110.         QUOTE.ASM        Sample program to display a random quote
  111.         QUOTE.EXE
  112.         FILE_ID.DIZ      Short description for BBS usage
  113.  
  114.         What files help with understanding ALIB?
  115.         ----------------------------------------
  116.  
  117.         Assembly language programmers can get started by looking at
  118.         TEMPLATE.ASM and then using ALIB2.DOC, ALIB3.DOC and the sample
  119.         programs as reference maternal.  Novice programmers should probably
  120.         execute the sample program called HYPER and study the material,
  121.         then study the sample programs, starting with TEMPLATE.ASM.  
  122.         
  123.  
  124.         Is registration necessary?
  125.         --------------------------
  126.          
  127.         Registration of ALIB is not required for personal or
  128.         commercial use.  However, ALIB will not grow and improve
  129.         without some support.  If you have a useful piece of code
  130.         or comment, please send it to the author for future updates.
  131.           
  132.          
  133.                   Program and Manual by Jeff Owens
  134.                        Owens Consulting, 24551 Metzler Park
  135.                        Estacada Oregon  97023
  136.  
  137.                        kowens@teleport.com
  138.          
  139.  
  140.         Can I distribute ALIB to others?
  141.         --------------------------------
  142.  
  143.         You are free to distribute this program, provided that
  144.         neither the program nor this document are changed, and the
  145.         program and this document are kept together.  Only a
  146.         marginal fee may be asked for shipment and handling when
  147.         distributing.  You are not allowed to sell this program.
  148.                  
  149.  
  150.         What if problems occur?
  151.         -----------------------
  152.  
  153.         Problems?  What problems?  After two years of work no
  154.         programmer wants to talk about problems.  But, the truth
  155.         is that problems will occur.  Either the documentation
  156.         will not be adequate, bugs will be found, or necessary
  157.         features will be missing.  The answer to all these
  158.         problems is the same, either discard ALIB or support it.
  159.         My pledge is to support ALIB without any monetary gain as
  160.         long as there is a reasonable interest level. 
  161.  
  162.  
  163.         Legal disclaimer
  164.         ---------------
  165.       
  166.         THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  167.         KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  168.         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  169.         FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO
  170.         THE QUALITY AND PERFORMANCE OF THE PRODUCT IS WITH YOU.
  171.         SHOULD THE PRODUCT PROVE DEFECTIVE, YOU ASSUME THE COST OF
  172.         ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  173.  
  174.         IN NO EVENT WILL OWENS CONSULTING, OR ANY OTHER PARTY WHO
  175.         MAY HAVE REDISTRIBUTED THE PRODUCT AS PERMITTED ABOVE, BE
  176.         LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  177.         INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
  178.         OR INABILITY TO USE THE PRODUCT (INCLUDING BUT NOT LIMITED
  179.         TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
  180.         LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
  181.         THE PRODUCT TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
  182.         SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
  183.         POSSIBILITY OF SUCH DAMAGES.
  184.  
  185.  
  186.  
  187.         Limitations:
  188.         -------------
  189.  
  190.         ALIB is definitely not for everyone.  If you are interested in
  191.         graphic screens, buttons, etc. then look elsewhere.  This
  192.         library is not for graphic applications.  On the other
  193.         hand, lack of graphics greatly increases compatibility,
  194.         speed, and reduces code size.
  195.  
  196.         ALIB is not designed to be accessed from other languages.
  197.         It is possible, but not advised.  The use of registers,
  198.         memory, and display all are designed as if ALIB is the
  199.         main program.
  200.  
  201.         ALIB is not designed for use with TSR (Terminate and
  202.         Stay Resident) programs.  Most of the functions will
  203.         work with TSR's but those calling the memory manager
  204.         will not function.
  205.         
  206.         And last but not least, the documentation for ALIB is
  207.         very breif and does not explain some of the more complicated
  208.         functions in sufficient detail for all audiences.
  209.  
  210.  
  211.  
  212.                           COMPRES & RESTOR
  213.                           ----------------
  214.  
  215.      Purpose:
  216.      --------
  217.  
  218.      COMPRES and RESTOR are sample program to show how huffman
  219.      compression works.  Single files can be compressed by the
  220.      COMPRES program, then decompressed by the RESTOR program.
  221.  
  222.      Using COMPRES & RESTOR
  223.      ----------------------
  224.  
  225.      To compress a file type "COMPRES file1 file2".  The first
  226.      file (file1) is the file to be compressed and the
  227.      second file is what to call the result.  RESTOR works
  228.      in the reverse.  "RESTOR file1 file2" will decompress
  229.      file1 and put at file2.
  230.  
  231.      Compression Overview
  232.      --------------------
  233.  
  234.      The compression/decompression engines are initiated with a
  235.      pointer to two routines.  One routine will feed data to the
  236.      engine and the other will store the output.  Next, one call
  237.      to the compression entry point will continue compressing
  238.      until the input (feed) routine runs out of data.
  239.      
  240.      Performance
  241.      -----------
  242.  
  243.      Compression speed and size is respectable, but not competative
  244.      with programs such as PKZIP and ARJ.  For most compression jobs
  245.      of less than a megabyte the speed will be acceptable.
  246.  
  247.  
  248.  
  249.                                 DISKINFO
  250.                                 --------
  251.  
  252.      Purpose:
  253.      --------
  254.  
  255.      DISKINFO displays information which DOS is using to manage
  256.      disks.  It may be useful for debugging a disk problem, but
  257.      will not be of interest to most programmers.
  258.      
  259.  
  260.      Using DISKINFO
  261.      --------------
  262.  
  263.      DISKINFO does not have any parameters, and can be executed
  264.      simply by typeing "DISKINFO"
  265.  
  266.  
  267.                              LOAN Payments
  268.                              -------------
  269.  
  270.      Purpose:
  271.      --------
  272.  
  273.      LOAN is a sample program to show how floating point math can
  274.      be performed.  It will calculate a 12 month table showing
  275.      what portions of payments go to principal and interest.
  276.  
  277.      Using LOAN
  278.      ----------
  279.  
  280.      To calculate the loan parameters, type "LOAN"<Enter> and
  281.      enter the loan amount, principal, and interest.  The
  282.      program will do the rest.
  283.  
  284.      Floating Point Overview
  285.      -----------------------
  286.  
  287.      LOAN operates by first allocating 8 floating variables.  Then,
  288.      three of the variables are set to the payment amount, principal,
  289.      and interest respectivly.  Each of the 8 allocated variables
  290.      are referenced by a number or token.  The first variable is #1,
  291.      the second #2 etc.  This makes it vary easy to add two variables
  292.      by just saying add #1 to #2.  When, the calculations are done,
  293.      they are extracted by calling "text_out" to convert from 
  294.      floating point format to a printable ascii text string.
  295.  
  296.  
  297.  
  298.                          EDREC (Edit Records)
  299.                          --------------------
  300.  
  301.      Purpose
  302.      -------
  303.  
  304.      EDREC is both a sample program and ALIB utility program.  Files
  305.      created by EDREC use ALIB database format which is also used by
  306.      hyper message and error displays.  This greatly simplifies the
  307.      process of creating a file of error messages or help screens.
  308.  
  309.      Using EDREC
  310.      -----------
  311.  
  312.      EDREC can be started by typing EDREC or by typing EDREC followed
  313.      with a file name.  If the file exists, EDREC will display the first
  314.      record and wait for input.  If the file does not exist the record
  315.      window will be blank.
  316.  
  317.      The data entered using EDREC is probably going to be displayed in
  318.      a window someday, so the window size should be selected to make
  319.      data entry easier.  The record window size is set by the "Config"
  320.      menu option.
  321.  
  322.      After setting the window size, select "Edit" to add or modify
  323.      records.
  324.      
  325.      Database Format
  326.      ---------------
  327.  
  328.      EDREC creates records in a window which can be configured to any size.
  329.      Each record is variable length and terminated by a null (hex 00 char).
  330.  
  331.  
  332.                                 SORT
  333.                              -------------
  334.      Purpose:
  335.      --------
  336.  
  337.      Sort disk file using the "merge sort" algorithm.
  338.  
  339.      Using sort
  340.      ----------
  341.      SORT <file> <starting column> <length of sort field>
  342.  
  343.      SORT reads the given file, sorts the records using the specified
  344.      column.  One line ending with cr/lf is assumed to be one record.
  345.      
  346.      Example:  To sort all TEST.DAT using columns 1-5.
  347.  
  348.                SORT test.dat 1 5
  349.  
  350.  
  351.  
  352.                                 SCAN
  353.                              -------------
  354.      Purpose:
  355.      --------
  356.  
  357.      Scan disk for string.
  358.  
  359.      Using newscan
  360.      ----------
  361.      SCAN <files/path> <pattern>
  362.  
  363.      SCAN starts searching from the current directory and checks each
  364.      each file which matches the <files/path> specification for the
  365.      <pattern>
  366.  
  367.      Example:  To scan all .ASM files in the current directory
  368.                for include files:
  369.  
  370.                      SCAN *.asm include
  371.  
  372.                To scan all the files in the current and its subdirectories
  373.                for include files:
  374.  
  375.                      SCAN *.* include             
  376.  
  377.      The <files/path> parameter applies to both files and subdirectories.
  378.      Thus, if you type "SCAN X*.* include" it will look in the current
  379.      directory and all subdirectories which begin with "X" for files
  380.      which begin with "X"
  381.  
  382.  
  383.                              HYPER.ASM 
  384.                              ---------
  385.      Purpose:
  386.      --------
  387.  
  388.      HYPER.ASM is intended to demonstrate a simple hyper database
  389.      which describes ALIB.LIB use.
  390.  
  391.      Using HYPER.ASM
  392.      ---------------
  393.  
  394.      The files HYPER.EXE and HYPER.DAT must be in the same directory.
  395.      HYPER is started by typing "HYPER"<cr> without any parameters.
  396.  
  397.      
  398.                              QUOTE.ASM 
  399.                              ---------
  400.      Purpose:
  401.      --------
  402.  
  403.      QUOTE.ASM is intended to demonstrate calling a random generator
  404.      and finding files located in same directory as executable.
  405.      It will display a random quote each time it is called.
  406.  
  407.      Using QUOTE.ASM
  408.      ---------------
  409.  
  410.      The files QUOTE.EXE and QUOTE.DAT must be in the same directory.
  411.      QUOTE is started by typing "QUOTE"<cr> without any parameters.
  412.  
  413.      
  414.                              MEMORY.ASM
  415.                              ----------
  416.      Purpose:
  417.      --------
  418.  
  419.      MEMORY.ASM display the memory information available from
  420.      ALIB.  Include are the MCB chain, and the size of DOS,
  421.      XMS, and EMS memory.
  422.  
  423.  
  424.                              TIMER
  425.                              -----
  426.      Purpose:
  427.      --------
  428.  
  429.      TIMER is a sample program to show how the timer funcitons can
  430.      be used.  The unmodified program will time the execution of
  431.      programs, but it can be modified to time code segments.
  432.  
  433.      Using TIMER
  434.      ----------
  435.  
  436.      To time a program, type "TIMER <program name>"<Enter>
  437.      TIMER will execute the program and display the elapsed
  438.      time when the program exits.
  439.