home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / IBRARY20.ZIP / IBRARY.DOC < prev    next >
Text File  |  1994-02-28  |  52KB  |  1,297 lines
  1.  
  2.  
  3.  
  4.                III   BBBB    RRRR     AAA    RRRR    Y   Y
  5.                 I    B   B   R   R   A   A   R   R   Y   Y
  6.                 I    B   B   R   R   A   A   R   R    Y Y
  7.                 I    BBBB    RRRR    AAAAA   RRRR      Y
  8.                 I    B   B   R R     A   A   R R       Y
  9.                 I    B   B   R  R    A   A   R  R      Y
  10.                III   BBBB    R   R   A   A   R   R     Y
  11.  
  12.                ===========================================
  13.  
  14.                          A library for ASIC 4.0
  15.  
  16.         IBRARY 2.0  Copyright (c) 1993-1994  Thomas G. Hanlin III
  17.  
  18.                 "Bringing you fine shareware since 1985"
  19.  
  20.  
  21.  
  22.     This is IBRARY, a library of over 200 routines written in assembly
  23.     language for use with 80/20 Software's ASIC compiler. You will
  24.     need ASIC 4.00 or later and a linker to use IBRARY. An assembler
  25.     is not necessary. The IBRARY collection is copyrighted and may be
  26.     distributed only under the following conditions:
  27.  
  28.        All IBRARY files must be distributed together as a unit.
  29.        No files may be altered, added, or deleted from this unit.
  30.        The assembly language sources must NOT be distributed.
  31.  
  32.     YOU USE THIS LIBRARY AT YOUR OWN RISK. I have tested it on my own
  33.     computer, but I will not assume any responsibility for any
  34.     problems which IBRARY may cause you. If you do run into a problem,
  35.     please let me know about it, and I will do my best to verify and
  36.     repair it.
  37.  
  38.     It is expected that if you find IBRARY useful, you will register
  39.     your copy. You may not use IBRARY routines in programs intended
  40.     for sale unless you have registered.
  41.  
  42.     Registration gets you the latest version of IBRARY, complete with
  43.     full source code and printed manual, and the right to use IBRARY
  44.     routines in programs intended for sale. The assembly language code
  45.     is designed for MASM 6.0 and may require changes for use with
  46.     other assemblers. See the ORDER.FRM file for ordering information.
  47.  
  48.     You can contact me by email at CompuServe 71151,3331 or Internet
  49.     71151.3331@compuserve.com, or write to:
  50.  
  51.        Thomas G. Hanlin III
  52.        3544 E. Southern Ave. #104
  53.        Mesa, AZ 85204
  54.  
  55.                            Table of Contents                 page 2
  56.  
  57.  
  58.  
  59.      Synopsis and Legal Info .................................... 1
  60.  
  61.      Table of Contents .......................................... 2
  62.  
  63.      Overview ................................................... 3
  64.  
  65.      Directory Services ......................................... 4
  66.  
  67.      Equipment Info ............................................. 6
  68.  
  69.      Extended Math ............................................. 10
  70.  
  71.      Files ..................................................... 11
  72.  
  73.      Graphics .................................................. 15
  74.  
  75.      Interrupts ................................................ 18
  76.  
  77.      Joystick .................................................. 19
  78.  
  79.      Keyboard .................................................. 20
  80.  
  81.      Memory PEEK/POKE........................................... 21
  82.  
  83.      Mouse ..................................................... 22
  84.  
  85.      Miscellaneous ............................................. 25
  86.  
  87.                                Overview                      page 3
  88.  
  89.  
  90.  
  91.     As of version 4.0, ASIC became a much more powerful language,
  92.     with the introduction of library support. A library is very like
  93.     an extension to a compiler. It provides capabilities which are
  94.     perhaps insufficiently general-purpose to add into the language
  95.     itself, but which may nonetheless be of use to many people.
  96.     Libraries let you customize a language to suit your particular
  97.     needs.
  98.  
  99.     The routines in IBRARY are contained in a library file, which is
  100.     denoted by the extension .LIB. So, the IBRARY library is named
  101.     IBRARY.LIB. How you access this library depends on which version
  102.     of the compiler you use: ASIC.EXE or ASICC.EXE.
  103.  
  104.     In the case of ASICC.EXE, the command to compile a program which
  105.     uses IBRARY looks something like this:
  106.  
  107.        ASICC progname B/OBJ LIB=IBRARY LNK=C:\DOS
  108.  
  109.     Here, "progname" is the name of the program to compile. When you
  110.     use a library, compilation turns into a multi-part process. ASIC
  111.     first turns your .ASI code into an .OBJ file. It then calls your
  112.     LINK.EXE program to combine the .OBJ file with the routines you
  113.     need from IBRARY.LIB, turning the result into an .EXE program.
  114.     In the above command line, the LNK=C:\DOS part tells ASIC that
  115.     it can find LINK.EXE in a directory called C:\DOS. You will need
  116.     to use the appropriate directory for your computer. Note that
  117.     LINK.EXE does not come with ASIC. It is provided with Microsoft
  118.     languages and many DOS versions, though. Borland also has a
  119.     linker, called TLINK.EXE.
  120.  
  121.     IBRARY includes a batch file, ASICMAKE.BAT, to make all this
  122.     easier. You will need to modify it to have the appropriate LNK=
  123.     setting, but once that's done, you can simply type:
  124.  
  125.        ASICMAKE progname
  126.  
  127.     ...in order to compile and link your program.
  128.  
  129.     In the case of the editor/environment, the initial setup is a
  130.     bit different. From the Compiler menu, pick Advanced Options.
  131.     From the Advanced Options menu, do the following:
  132.  
  133.        choose .OBJ output file generation
  134.        set library name to IBRARY
  135.        set link path to wherever your LINK.EXE is (e.g., C:\DOS)
  136.  
  137.     It's as easy as that! You are now set up to use libraries. A
  138.     good first test would be to compile the IBRARY quick demo,
  139.     cleverly entitled DEMO.ASI. Give it a try!
  140.  
  141.                           Directory Services                 page 4
  142.  
  143.  
  144.  
  145.     The directory service routines allow you to duplicate the basic
  146.     functionality of the DOS command, DIR. You can search for files
  147.     with wildcard filespecs and file attributes. For matching files,
  148.     you can get the filename, attributes, size, time, and date. The
  149.     two basic routines are FindFirstF, which is used to set the
  150.     search specifications and search for the first matching file,
  151.     and FindNextF, which is used to search for additional matches:
  152.  
  153.        CALL SUB "FindFirstF" FileSpec$ Attr ErrCode
  154.        CALL SUB "FindNextF" ErrCode
  155.  
  156.     The FileSpec$ may include a full path, with drive, subdirectory,
  157.     and filename with "*" and/or "?" wildcards. The attribute tells
  158.     what kinds of files you want to search for, and may be any of
  159.     the following, used individually or added together:
  160.  
  161.        0    normal files
  162.        2    hidden files
  163.        4    system files
  164.        8    volume labels
  165.       16    subdirectories
  166.  
  167.     Since normal files have an attribute of 0, they are always
  168.     included in the search. So, searching for an attribute of 6, for
  169.     example, would result in finding normal, hidden, and system
  170.     files (4 + 2 + 0 = 6). Labels are a bit different-- they are
  171.     only present in the root directory, so your search spec should
  172.     be "\*.*" (maybe with a drive spec) to search for a volume
  173.     label. When you search for a label, you "should" get only a
  174.     label in return, but some versions of DOS are buggy and return
  175.     normal files as well-- so you should check the attribute, just
  176.     as you would in any other kind of file search.
  177.  
  178.     The ErrCode returned will be 0 until you run out of matches or
  179.     there is an error. An error code of 18 means you've run out of
  180.     matches, but (for most practical purposes) you can treat any
  181.     non-zero error code as meaning "no more matching files".
  182.  
  183.     When ErrCode returns zero, you know you have a valid match. You
  184.     can get additional information about the resulting match, so:
  185.  
  186.        CALL SUB "GetAttrF" FileAttr
  187.        CALL SUB "GetNameF" FileName$
  188.        CALL SUB "GetSizeF" FileSize&
  189.        CALL SUB "GetTimeF" Hour Minute Second
  190.        CALL SUB "GetDateF" Month Day Year
  191.  
  192.     Remember that you need to set a compiler switch to use long
  193.     integers in ASIC-- see your ASIC docs for details. Note that the
  194.     filename will not contain a drive or path specification. Hours
  195.     are returned in 24-hour format (0-23, or midnight-11pm). Seconds
  196.     are rounded down to even numbers, due to the DOS storage format.
  197.  
  198.                           Directory Services                 page 5
  199.  
  200.  
  201.  
  202.     File attributes may be any or all of the following, added
  203.     together (the ZBIT function, provided by ASIC, will be useful in
  204.     decoding this info):
  205.  
  206.        0    normal files
  207.        1    read-only files                bit 0
  208.        2    hidden files                   bit 1
  209.        4    system files                   bit 2
  210.        8    volume labels                  bit 3
  211.       16    subdirectories                 bit 4
  212.       32    archive files (back-up bit)    bit 5
  213.  
  214.     Putting all this together, a simple program to display all of
  215.     the filenames in the current directory might look like this:
  216.  
  217.        PRINT "Files in this directory:"
  218.        CALL SUB "FindFirstF" FileSpec$ Attr ErrCode
  219.        WHILE ErrCode = 0
  220.           CALL SUB "GetNameF" FileName$
  221.           PRINT FileName$
  222.           CALL SUB "FindNextF" ErrCode
  223.        WEND
  224.        PRINT "End of list"
  225.  
  226.                             Equipment Info                   page 6
  227.  
  228.  
  229.  
  230.     The equipment routines give you information about the computing
  231.     environment. This includes both installed software and hardware.
  232.  
  233.     The first function allows you to determine if an "enhanced"
  234.     keyboard (101-key) is installed. It may not be able to figure
  235.     out what the keyboard is on some older not-quite-clone PCs, in
  236.     which case it will take the safe way out and report that there
  237.     is no enhanced keyboard. This routine returns -1 if there is an
  238.     enhanced keyboard present, 0 if not.
  239.  
  240.        CALL SUB "KbdType" Enhanced
  241.  
  242.     Want to know the type of processor (CPU) being used? Can do!
  243.  
  244.        CALL SUB "Processor" CPUType
  245.  
  246.     The results will be returned as a number which can be decoded as
  247.     follows:
  248.  
  249.        0    NEC V20
  250.        1    8088 or 8086
  251.        2    80186
  252.        3    80286
  253.        4    80386
  254.        5    80486
  255.  
  256.     The processor speed can also be determined, although the results
  257.     may not be exact, especially if multitasking is going on. Note
  258.     that it may take up to several seconds to determine the speed on
  259.     8088-class processors.
  260.  
  261.        CALL SUB "ProcSpeed" MHz
  262.  
  263.     You can also see whether a numeric coprocessor is installed, and
  264.     what kind it is. This is done by checking for the coprocessor
  265.     directly, rather than examining the BIOS setting or switches,
  266.     and is quite reliable.
  267.  
  268.        CALL SUB "NumProc" NumProcType
  269.  
  270.     The results will be returned as a number which can be decoded as
  271.     follows:
  272.  
  273.        0    no coprocessor installed
  274.        1    8087
  275.        2    80287
  276.        3    80387
  277.  
  278.     I expect that a 486DX chip will appear to have an 80387
  279.     coprocessor, so you should be able to tell the difference
  280.     between a 486SX and a 486DX by checking for a math chip. I
  281.     haven't been able to verify this, though-- let me know if you
  282.     can tell me for sure!
  283.  
  284.                             Equipment Info                   page 7
  285.  
  286.  
  287.  
  288.     The number of floppy drives installed is retrieved like this:
  289.  
  290.        CALL SUB "Floppies" Drives
  291.  
  292.     There may be up to four floppy drives in a system; however, the
  293.     AT CMOS data area only directly supports two. This makes it easy
  294.     to find out what kind of drives the first two are, but not the
  295.     second two. Oh well, guess we'll have to settle for what we can
  296.     get, right?
  297.  
  298.        CALL SUB "FloppyType" Drive1 Drive2
  299.  
  300.     The results from FloppyType are returned as follows:
  301.  
  302.        0    no drive
  303.        1    5 1/4"    360K
  304.        2    5 1/4"    1.2M
  305.        3    3 1/2"    720K
  306.        4    3 1/2"    1.44M
  307.  
  308.     Result codes of 5-7 are available, but not yet defined. One
  309.     might guess that the 2.88M drive supported by DOS 5.0 will be
  310.     drive type 5. Has anybody seen one of those puppies yet?
  311.  
  312.     Maybe you'd like to check for a CD-ROM drive:
  313.  
  314.        CALL SUB "CDROM" Drives
  315.  
  316.     This tells you how many logical drives exist, if there is a
  317.     CD-ROM available. If not, it will return 0. Note that the CD-ROM
  318.     installation check conflicts with the GRAPHICS.COM installation
  319.     check for DOS 4.0, due to some screw-up at IBM or Microsoft.
  320.  
  321.     You can get the letter of the current default drive, or set the
  322.     current default drive, with the following routines:
  323.  
  324.        CALL SUB "GetDrive" Drive$
  325.        CALL SUB "SetDrive" Drive$
  326.  
  327.     New memory types sure have burgeoned over the years... expanded,
  328.     extended, and now XMS. There are routines to check all of these:
  329.  
  330.        REM get total extended memory installed
  331.        CALL SUB "AllExtMem" AllExt&
  332.  
  333.        REM get BIOS extended memory installed
  334.        CALL SUB "GetExtM" BiosExt&
  335.  
  336.        REM get expanded (EMS) memory installed
  337.        CALL SUB "GetEMSm" TotalPages FreePages
  338.  
  339.        REM get XMS memory installed
  340.        CALL SUB "GetXMSm" BigFree& TotalFree&
  341.  
  342.                             Equipment Info                   page 8
  343.  
  344.  
  345.  
  346.     When you're dealing with extended memory, whether it be
  347.     BIOS-type or using the XMS standard, the results are returned in
  348.     kilobytes. Multiply 'em by 1024 to convert to bytes. When you're
  349.     dealing with expanded memory (EMS), the results are in pages of
  350.     16,384 bytes.
  351.  
  352.     I might note, by the way, that Microsoft seems to have
  353.     intentionally crippled the XMS standard. It can only support a
  354.     maximum of 64 megabytes. This may seem like a lot now, but it'll
  355.     seem cramped soon enough. I remember when 640k seemed like an
  356.     empty football stadium, best used to make a 360k RAMdisk!
  357.  
  358.     A few more routines to get the versions of EMS and XMS, if any:
  359.  
  360.        CALL SUB "GetEMSv" MajorV MinorV
  361.        CALL SUB "GetXMSv" MajorV MinorV
  362.  
  363.     These return the major and minor version numbers as two separate
  364.     integers. For example, EMS 4.0 would return major version 4,
  365.     minor version 0.
  366.  
  367.     It's nice to know a little about the operating environment. With
  368.     the below routines, you can find out what the DOS version is;
  369.     what version of 4DOS, if any, is in use; and whether Microsoft
  370.     Windows is running.
  371.  
  372.        CALL SUB "GetDOSv" MajorV MinorV
  373.        CALL SUB "Get4DOSv" MajorV MinorV
  374.        CALL SUB "WinCheck" MajorV MinorV
  375.  
  376.     These return results as major and minor version numbers, as
  377.     discussed on the previous page. The Get4DOSv and WinCheck
  378.     routines return zeroes if 4DOS and Windows, respectively, are
  379.     not available.
  380.  
  381.     There are a couple of curious features of GetDOSv to keep in
  382.     mind. If the version is 10 or higher, you're running in OS/2
  383.     compatibility mode. DOS version 10 is actually OS/2 1.0, version
  384.     20 is OS/2 2.0, and so on. Secondly, if you're using DOS 5.0,
  385.     the version reported may not be 5.0-- DOS 5.0 can be told to
  386.     reply with a lower version number to allow some older software
  387.     (which checks for a specific DOS version) to run properly.
  388.  
  389.     Another routine that may be of some value is the one that allows
  390.     you to find out what kind of display is available. It tells you
  391.     the specific adapter and whether the display is monochrome or
  392.     color. There are two cases in which it can be confused, however.
  393.     If the adapter is CGA, the display is assumed to be color, since
  394.     there is no way for the computer to know any differently. Also,
  395.     some laptops lie about their mono VGA displays, and claim that
  396.     they're color. So, although this routine provides a good idea of
  397.     what is available, it would be a good idea to provide an option
  398.     to tell the program that a monochrome display is attached.
  399.     Microsoft normally uses "/B" for this purpose, so that might be
  400.     a good standard to stick with.
  401.  
  402.                             Equipment Info                   page 9
  403.  
  404.  
  405.  
  406.        CALL SUB "GetDisplay" Adapter Mono
  407.  
  408.     This returns Mono = -1 for a monochrome display, or Mono = 0 for
  409.     a color display. The Adapter may be any of the following:
  410.  
  411.        1    MDA
  412.        2    Hercules
  413.        3    CGA
  414.        4    EGA
  415.        5    MCGA
  416.        6    VGA
  417.  
  418.     Aside from some of the oldest semi-clones, it's possible to find
  419.     out what sort of machine you're using by looking at a specific
  420.     data byte. You can access this as follows:
  421.  
  422.        CALL SUB "PCType" PcType
  423.  
  424.     The result will need decoding. Here are some known values:
  425.  
  426.        255   PC or XT          250   PS/2 Model 30
  427.        254   XT                249   PC Convertible
  428.        253   PCjr              248   PS/2 Model 70 or 80
  429.        252   PC AT             154   Compaq Portable
  430.        251   XT                 45   Compaq Portable
  431.  
  432.     Likewise, all but some of the oldest semi-clones maintain a BIOS
  433.     date value which tells you how old the BIOS ROM is. This can be
  434.     retrieved with the following routine:
  435.  
  436.        CALL SUB "PCDate" PCDate$
  437.  
  438.     If your program is running on one of the rare old machines which
  439.     don't maintain a valid BIOS date, this routine will return "No
  440.     Date " instead of an actual date.
  441.  
  442.     As far as a program is concerned, DR DOS is essentially the same
  443.     as MS-DOS. Still, it's always nice to know what sort of
  444.     operating environment you have. You can find out whether your
  445.     program is running under DR DOS with the following function:
  446.  
  447.        CALL SUB "DrDos" DrDos
  448.        IF DRDOS = 0 THEN
  449.           PRINT "MS-DOS"
  450.        ELSE
  451.           PRINT "DR DOS"
  452.        ENDIF
  453.  
  454.     The number of serial and parallel ports available can be readily
  455.     obtained:
  456.  
  457.        CALL SUB "CommPorts" CommPorts
  458.  
  459.        CALL SUB "PrtPorts" PrtPorts
  460.  
  461.                              Extended Math                  page 10
  462.  
  463.  
  464.  
  465.     The extended math routines provide a number of simple binary
  466.     functions which operate on an integer as a stream of bits. You
  467.     may shift or rotate the bits in an integer by an arbitrary
  468.     amount in either direction.
  469.  
  470.     Note that the normal ASIC integer has a length of 16 bits.
  471.  
  472.        CALL SUB "LShift" Number ShiftCount
  473.  
  474.        CALL SUB "RShift" Number ShiftCount
  475.  
  476.        CALL SUB "LRotate" Number ShiftCount
  477.  
  478.        CALL SUB "RRotate" Number ShiftCount
  479.  
  480.     An identical set of routines is provided for long integers,
  481.     which have a length of 32 bits. You need to specify a compiler
  482.     option to use long integers, as explained in the ASIC manual.
  483.  
  484.        CALL SUB "LShiftL" Number& ShiftCount
  485.  
  486.        CALL SUB "RShiftL" Number& ShiftCount
  487.  
  488.        CALL SUB "LRotateL" Number& ShiftCount
  489.  
  490.        CALL SUB "RRotateL" Number& ShiftCount
  491.  
  492.     For picking out specific bits, check out ASIC's extension to the
  493.     BASIC function set, ZBIT.
  494.  
  495.                                  Files                      page 11
  496.  
  497.  
  498.  
  499.     For sheer flexibility, it's hard to beat DOS file handling. It's
  500.     not always as convenient as BASIC file handling, but it offers
  501.     many compensating advantages. It allows up to 15 files to be
  502.     open at a time (or more, under some circumstances), instead of
  503.     ASIC's paltry 3. It provides binary access, allows you to read
  504.     large chunks of data at a time (even entire arrays!), and offers
  505.     both sequential and random-access techniques at once. IBRARY has
  506.     built-in critical error handling, so you can treat all errors
  507.     the same way (no fear of "R>etry, A>bort, I>gnore, F>ail?").
  508.  
  509.     The IBRARY file routines are designed for binary files. You can
  510.     read text files too, of course-- all files are the same to DOS--
  511.     but there is no provision for stopping at a carriage return (or
  512.     control-Z, if you're dealing with CP/M-format text files). You
  513.     can interpret such yourself, if you wish. Additional routines
  514.     will be added to the next revision of IBRARY, of course.
  515.  
  516.     When opening a file with IBRARY, you do not give it a file
  517.     number. Instead, IBRARY passes you back a file handle, if the
  518.     file was opened successfully. This file handle serves the same
  519.     purpose as a file number and is used to identify the file any
  520.     time you want to access it. It has an advantage over ASIC file
  521.     numbers in that you don't have to worry about whether you've
  522.     used a number before-- IBRARY will always give you a unique
  523.     handle for a successful open.
  524.  
  525.     Files may be opened in either of two ways. FOpen opens an
  526.     existing file, and may include an open mode (read, write, or
  527.     read/write) and sharing mode (allowing network support). FCreate
  528.     creates a new file, or wipes out and recreates an existing file,
  529.     with a specified file attribute. Generally, you will want to
  530.     take one of two approaches:
  531.  
  532.       1) If the file is expected to exist, try FOpen to open it. If
  533.       there is an error opening the file, you must decide whether to
  534.       abort the operation and tell the user "file not found" or to
  535.       create a new file with FCreate.
  536.  
  537.       2) If you are creating a new file, you may wish to try FOpen
  538.       to see if the file exists. If FOpen succeeds, you should close
  539.       the file and prompt the user "File exists: overwrite? abort?"
  540.       and act accordingly. Also, although FCreate will create a
  541.       file, it does so in a mode which is not network-friendly.
  542.       Unless you are sure your program will never run on a network
  543.       or in a multitasking situation, you should immediately close a
  544.       file created by FCreate, and use FOpen to reopen it with the
  545.       appropriate sharing mode.
  546.  
  547.     The FOpen and FCreate calls look like so:
  548.  
  549.        CALL SUB "FOpen" FileName$ OpenMode Sharing Handle ErrCode
  550.        CALL SUB "FCreate" FileName$ Attribute Handle ErrCode
  551.  
  552.                                  Files                      page 12
  553.  
  554.  
  555.  
  556.     If the file is opened or created successfully, the ErrCode will
  557.     be zero, and a valid handle will be returned. You *MUST* close
  558.     such files with FClose when you are done with them, or they will
  559.     not be updated properly on disk, and your program will lose
  560.     access to the handle involved. Do not use FClose on a file if
  561.     the FOpen or FCreate call returned a non-zero ErrCode.
  562.  
  563.     Note that there are five system handles which are provided to
  564.     every program. You can use these without having to open (or
  565.     close) them:
  566.  
  567.        0   CON   stdin    standard input, normally the keyboard
  568.        1   CON   stdout   standard output, normally the display
  569.        2   CON   stderr   standard error, almost always display
  570.        3   AUX   stdaux   auxiliary device, generally COM1
  571.        4   PRN   stdprn   standard printer, generally LPT1
  572.  
  573.     In fact, if you need more than the usual 15 handles available,
  574.     you can gain a few handles by closing these system handles. Do
  575.     not do this if your program relies on the device in question!
  576.     You can safely close AUX, though, since IBRARY uses the BIOS to
  577.     provide comm support, rather than DOS. You can probably also
  578.     close PRN without any problem (certainly if you don't use the
  579.     printer in your program). The CON handles should generally be
  580.     left alone, unless you're very sure of what you're doing.
  581.  
  582.     For FOpen, the OpenMode may be one of the following, depending
  583.     on what you intend to do with the file:
  584.  
  585.        0   Read
  586.        1   Write
  587.        2   Read and Write
  588.  
  589.     Also for FOpen, you must choose an appropriate Sharing mode. You
  590.     should normally try to use a network mode, so your program will
  591.     work well on networks and under multitasking situations. IBRARY
  592.     is smart enough to ignore the network mode if your program is
  593.     run on a DOS version below 3.0, which doesn't support network
  594.     modes. A good general guideline is to use "deny write" (or
  595.     "exclusive" if you want to be really secure) on files you expect
  596.     to write to, and "deny none" on files you expect only to read.
  597.     The Sharing mode may be one of the following:
  598.  
  599.        0   Normal       compatibility mode: no file sharing
  600.        1   Exclusive    no one else may access the file
  601.        2   Deny Write   no one else may write to the file
  602.        3   Deny Read    no one else may read from the file
  603.        4   Deny None    anyone else may read from or write to file
  604.  
  605.                                  Files                      page 13
  606.  
  607.  
  608.  
  609.     For FCreate, you may select a file attribute to apply to the
  610.     created file. This may be one or more of the following, added
  611.     together:
  612.  
  613.        Normal          0      (nothing special)
  614.        Read Only       1      file can be read, but not written to
  615.        Hidden          2      file is "invisible"
  616.        System          4      special DOS system file
  617.  
  618.     Don't use the System attribute unless you know what you're
  619.     doing. It is not appropriate for ordinary files. Files created
  620.     by FCreate are opened in Read and Write mode, with Normal
  621.     sharing. For best compatibility, you should close the file and
  622.     re-open it with FOpen, using an appropriate Sharing mode.
  623.  
  624.     The FClose routine has been mentioned several times, because
  625.     it's important. If a file was opened successfully with FOpen or
  626.     FCreate, you *MUST* close it (when you're done with it) with
  627.     FClose, or the file may be left in an indeterminate state.
  628.  
  629.        CALL SUB "FClose" Handle
  630.  
  631.     If you are writing particularly important data, you may want to
  632.     make sure its information is committed to disk at periodic
  633.     intervals. Otherwise, a system crash or power failure could
  634.     cause loss of data due to DOS disk buffering. The FFlush routine
  635.     will make sure the current data is sent to disk. Note that
  636.     FFlush works with DOS alone. If an external disk cache is in
  637.     use, it may delay the disk update beyond DOS' control.
  638.  
  639.        CALL SUB "FFlush" Handle ErrCode
  640.  
  641.     If you are dealing with files that require heavy access by many
  642.     network nodes, the file-based locking supported by FOpen is
  643.     likely to be too crude. You can lock and unlock independent
  644.     areas of a file too-- but be careful. You must unlock all locks
  645.     in the reverse order you apply them, and using the exact same
  646.     parameters (like a stack: the last lock applied must be the
  647.     first lock to be removed). All locks *MUST* be removed before
  648.     you close a file, or the file is left in an indeterminate state
  649.     and may not be recoverable. Microsoft is vague in its warnings,
  650.     but it sounds like a good place to be careful...
  651.  
  652.        CALL SUB "FLock" Handle Posn& Bytes& ErrCode
  653.        CALL SUB "FUnlock" Handle Posn& Bytes& ErrCode
  654.  
  655.     Positions start at 1, the first byte. Remember that you need to
  656.     use a special switch to get ASIC to handle long integers-- see
  657.     the ASIC manual for details.
  658.  
  659.                                  Files                      page 14
  660.  
  661.  
  662.  
  663.     You may read a byte, integer, long, or string from a file.
  664.     Better yet, you may read an array of bytes, array of integers,
  665.     or array of longs from a file-- not arrays of strings, though,
  666.     due to the different format involved. In the case of single
  667.     values, pass the variable to the call. In the case of arrays,
  668.     pass the first element of the array to the call. Note that an
  669.     integer takes up two bytes, and a long integer takes up four.
  670.  
  671.        CALL SUB "FReadB" Handle Value Bytes ErrCode
  672.        CALL SUB "FReadI" Handle Value Integers ErrCode
  673.        CALL SUB "FReadL" Handle Value& Longs ErrCode
  674.        CALL SUB "FReadS" Handle Value$ Bytes ErrCode
  675.  
  676.     Of course, you can also write values, in much the same fashion:
  677.  
  678.        CALL SUB "FWriteB" Handle Value Bytes ErrCode
  679.        CALL SUB "FWriteI" Handle Value Integers ErrCode
  680.        CALL SUB "FWriteL" Handle Value& Longs ErrCode
  681.        CALL SUB "FWriteS" Handle Value$ Bytes ErrCode
  682.  
  683.     NOTE NOTE NOTE!!! The count variable (Bytes, Integers, or Longs,
  684.     depending on the routine) is RETURNED as well as being passed to
  685.     the routine-- it tells you how many bytes were actually written
  686.     or read, in case your entire request couldn't be processed.
  687.     Don't use constants for these values, since ASIC treats
  688.     constants somewhat like variables-- the constant would be
  689.     altered throughout your program!
  690.  
  691.     Normally, when you read or write a value, the file pointer will
  692.     be updated to the next position, so you will read or write the
  693.     next area on subsequent calls. You can find out where the file
  694.     pointer is, so:
  695.  
  696.        CALL SUB "FWhere" Handle Posn&
  697.  
  698.     The file pointer can also be set to the start of the file, end
  699.     of the file, or a specified point in the file, so:
  700.  
  701.        CALL SUB "FSetStart" Handle
  702.        CALL SUB "FSetEnd" Handle
  703.        CALL SUB "FLocate" Handle Posn&
  704.  
  705.     And, finally, you can get the size of the file, or set the size
  706.     of the file:
  707.  
  708.        CALL SUB "FSize" Handle Bytes&
  709.        CALL SUB "FSetSize" Handle Bytes& ErrCode
  710.  
  711.     Being able to set the size of the file lets you trim off
  712.     unwanted material from the end of a file, or to expand a file in
  713.     advance of needing space (in order to improve the odds of
  714.     allocating contiguous disk space, for best speed).
  715.  
  716.                                Graphics                     page 15
  717.  
  718.  
  719.  
  720.     Much of the design of ASIC appears to be oriented on the notion
  721.     of creating the smallest possible programs. In that respect, it
  722.     is perhaps not surprising that ASIC doesn't include strong
  723.     graphics support. IBRARY provides support for EGA and VGA modes
  724.     which ASIC doesn't. A future version of IBRARY will include
  725.     advanced support for many more video modes.
  726.  
  727.       Mode   Description
  728.       ====   ================================================
  729.         8    640x200,  16 colors, 80x25 text, EGA or better
  730.        11    640x480,   2 colors, 80x25 text, VGA or better
  731.        12    640x480,  16 colors, 80x25 text, VGA or better
  732.        13    320x200, 256 colors, 40x25 text, VGA or better
  733.        N0    360x480, 256 colors, 45x60 text, VGA or better
  734.        N1    320x400, 256 colors, 40x25 text, VGA or better
  735.  
  736.     The graphics routines all use the same nomenclature: a G,
  737.     followed by a mode number, followed by the specific name. This
  738.     generic naming convention is used so that this chapter can refer
  739.     to all available modes. For example, if I say "G#Color" and
  740.     you're using mode 12, you'd actually use "G12Color" in your
  741.     program. Ok?
  742.  
  743.     You just use G#Mode with a non-zero value to enter graphics
  744.     mode, or zero to restore text mode. The text mode is assumed to
  745.     be the normal 80x25 color mode. If you'd prefer to reset to
  746.     another mode, you can safely use the ASIC SCREEN statement to
  747.     pick setting that's more to your liking.
  748.  
  749.     Typical handling of one of the non-SVGA modes (in this case,
  750.     mode 12) would go something like this:
  751.  
  752.        CALL SUB "G12Mode" 1
  753.        REM *** your main program goes here ***
  754.        CALL SUB "G12Mode" 0
  755.  
  756.                                Graphics                     page 16
  757.  
  758.  
  759.  
  760.     One difference between ASIC and IBRARY is that, instead of each
  761.     "draw" command requiring a color parameter as in ASIC, IBRARY
  762.     provides a separate color command:
  763.  
  764.        CALL SUB "G#Color" Foreground Background
  765.  
  766.     The foreground color is used by all graphics routines. The
  767.     background color is used by the G#Cls routine. Both foreground
  768.     and background colors are used in by G#Write and G#WriteLn.
  769.  
  770.     Here is a list of the corresponding routines, first ASIC, then
  771.     IBRARY (replace the "#" with the appropriate mode number):
  772.  
  773.        REM get the color of a specified point
  774.        colour = POINT(x, y)
  775.        CALL SUB "G#GetPel" x y colour
  776.  
  777.        REM set the color of a specified point
  778.        PSET (x, y), colour
  779.        CALL SUB "G#Color" colour, backgnd
  780.        CALL SUB "G#Plot" x y
  781.  
  782.        REM clear the screen and home the cursor (if any)
  783.        CLS
  784.        CALL SUB "G#Cls"
  785.  
  786.        REM get the current cursor position
  787.        Row = CSRLIN
  788.        Column = POS(0)
  789.        CALL SUB "G#GetLocate" Row Column
  790.  
  791.        REM set the current cursor position
  792.        LOCATE Row, Column
  793.        CALL SUB "G#Locate" Row Column
  794.  
  795.        REM display a string without a carriage return and linefeed
  796.        PRINT St$;
  797.        CALL SUB "G#Write" St$
  798.  
  799.        REM display a string with a carriage return and linefeed
  800.        PRINT St$
  801.        CALL SUB "G#WriteLn" St$
  802.  
  803.     If you need to print a number rather than a string, just use the
  804.     BASIC function STR$ to convert it. If you don't want a leading
  805.     space, you can use the IBRARY routine, StrNB:
  806.  
  807.        CALL SUB "StrNB" Number St$
  808.  
  809.                                Graphics                     page 17
  810.  
  811.  
  812.  
  813.     The IBRARY library has other graphics routines which have no
  814.     ASIC equivalent. Here's a list:
  815.  
  816.        REM get the current colors
  817.        CALL SUB "G#GetColor" Foreground Background
  818.  
  819.        REM draw a line
  820.        CALL SUB "G#Line" x1 y1 x2 y2
  821.  
  822.        REM draw a box (set filled = 0 for frame, = 1 to fill it)
  823.        CALL SUB "G#Box" x1 y1 x2 y2 filled
  824.  
  825.        REM get a VGA palette value
  826.        CALL SUB "GetPalRGB" Colour RedI GreenI BlueI
  827.  
  828.        REM set a VGA palette value
  829.        CALL SUB "SetPalRGB" Colour RedI GreenI BlueI
  830.  
  831.  
  832.     The most obvious aspect of palettes is in the ability to select
  833.     a set of colors suited to a specific application. When showing a
  834.     picture of the sea, you might want mostly blues and greens, for
  835.     instance. There are other implications in the ability to quickly
  836.     change a color across the entire screen, however. It allows for
  837.     simple animation, the ability to fade in or fade out, and other
  838.     interesting effects. Let your imagination run loose and
  839.     experiment a little! You'll be surprised by the power of palette
  840.     manipulation.
  841.  
  842.                                Interrupts                   page 18
  843.  
  844.  
  845.  
  846.     The interrupt routines give you access to some of the more
  847.     common BIOS and DOS interrupts, with a couple of convenience
  848.     features thrown in for good measure.
  849.  
  850.     NOTE that these routines access the computer at a very low
  851.     level. If you don't know what you're doing or make a mistake,
  852.     you could cause serious trouble. Be warned!
  853.  
  854.     Three routines are provided for accessing common interrupts.
  855.     They allow you to set the AX, BX, CX, and DX registers, and
  856.     return the new values of the same, plus the flags.
  857.  
  858.        REM  access to INT 21h, the DOS function handler
  859.        CALL SUB "DosInt" AX BX CX DX Flags
  860.  
  861.        REM  access to INT 10h, the BIOS video handler
  862.        CALL SUB "VidInt" AX BX CX DX Flags
  863.  
  864.        REM  access to INT 16h, the BIOS keyboard handler
  865.        CALL SUB "KbdInt" AX BX CX DX Flags
  866.  
  867.     Each of the 16-bit registers AX, BX, CX and DX can be divided in
  868.     half and accessed as 8-bit values: AH, AL, BH, BL, and so on. To
  869.     make it easier to work with the registers as either 8-bit or
  870.     16-bit quantities, IBRARY includes routines to split a 16-bit
  871.     word into two 8-bit bytes, and vice versa:
  872.  
  873.        CALL SUB "SplitWord" Word HiByte LoByte
  874.  
  875.        CALL SUB "JoinBytes" HiByte LoByte Word
  876.  
  877.     The Flags value is a set of bit flags indicating the value of
  878.     the processor's flag register. Bit 0 contains the carry flag and
  879.     bit 6 contains the zero flag. There are a few other flags
  880.     involved, but you should never need to access them.
  881.  
  882.                                Joystick                     page 19
  883.  
  884.  
  885.  
  886.     The joystick routines allow you to read the positions and
  887.     buttons of up to two joysticks. If only one joystick is
  888.     attached, the results for the second joystick will usually be
  889.     meaningless. In the case of the FlightStick joystick, if only
  890.     one joystick is attached, the value for the Y position of the
  891.     second joystick will indicate the FlightStick throttle setting.
  892.  
  893.     The joysticks are labeled "A" and "B" for these routines, where
  894.     "A" is the first joystick.
  895.  
  896.     You can read the joystick buttons individually or all at once.
  897.     If speed is an issue, you should read the buttons all at once,
  898.     as this is considerably faster than reading them one at a time
  899.     (assuming you wish to read more than one button).
  900.  
  901.        CALL SUB "JButtonA1" Pressed
  902.        CALL SUB "JButtonA2" Pressed
  903.        CALL SUB "JButtonB1" Pressed
  904.        CALL SUB "JButtonB2" Pressed
  905.  
  906.        CALL SUB "JButtons" A1Pressed A2Pressed B1Pressed B2Pressed
  907.  
  908.     The value returned will be -1 if the button is pressed or 0 if
  909.     it is not pressed.
  910.  
  911.     You can also get the position of the joysticks. This is returned
  912.     as a pair of X,Y coordinates for each joystick. The starting and
  913.     ending positions depend on the individual joystick, game
  914.     adapter, and computer, so your program must calibrate itself to
  915.     the individual joystick. I find a range of about 5-140 on my
  916.     FlightStick; your mileage may vary.
  917.  
  918.        CALL SUB "JPos" AX AY BX BY
  919.  
  920.     Note that the joystick routines are BIOS-dependent. They will
  921.     not work on some of the oldest PCs (those made before 1983 or
  922.     thereabouts).
  923.  
  924.                                 Keyboard                    page 20
  925.  
  926.  
  927.     The keyboard routines provide you with information about the
  928.     current state of the keyboard shifts (left and right shift,
  929.     control, and alt keys) and toggles (caps lock, num lock, scroll
  930.     lock, and insert). They also allow you to set the state of the
  931.     keyboard toggles.
  932.  
  933.     To get the state of the left shift, control, or alt keys, you'd
  934.     use one or more of the following:
  935.  
  936.        CALL SUB "LShiftPress" KeyState
  937.        CALL SUB "LCtrlPress" KeyState
  938.        CALL SUB "LAltPress" KeyState
  939.  
  940.     The corresponding routines for the right keys are:
  941.  
  942.        CALL SUB "RShiftPress" KeyState
  943.        CALL SUB "RCtrlPress" KeyState
  944.        CALL SUB "RAltPress" KeyState
  945.  
  946.     Finally, you can tell whether either set of shift, control, or
  947.     alt keys is pressed with these routines:
  948.  
  949.        CALL SUB "ShiftPress" KeyState
  950.        CALL SUB "CtrlPress" KeyState
  951.        CALL SUB "AltPress" KeyState
  952.  
  953.     The KeyState returned will be 0 if the key is not pressed, or -1
  954.     if it is. Please note that the results for LAltPress, RAltPress,
  955.     LCtrlPress, and RCtrlPress will not be meaningful with older AT
  956.     or XT keyboards. They require "enhanced" keyboard support. Older
  957.     keyboards only have a single set of Ctrl and Alt keys, anyway.
  958.  
  959.     You can read the current state of the keyboard toggles, thus:
  960.  
  961.        CALL SUB "GetCapsLock" ToggleState
  962.        CALL SUB "GetInsert" ToggleState
  963.        CALL SUB "GetNumLock" ToggleState
  964.        CALL SUB "GetScrollLock" ToggleState
  965.  
  966.     The result will be 0 if the toggle is off, or -1 if it's on. You
  967.     can set the toggle state using the same conventions, so:
  968.  
  969.        CALL SUB "CapsLock" Status
  970.        CALL SUB "Insert" Status
  971.        CALL SUB "NumLock" Status
  972.        CALL SUB "ScrollLock" Status
  973.  
  974.     If you change the state of a keyboard toggle, the corresponding
  975.     keyboard LED will change as well, except on some of the oldest
  976.     keyboards (or, of course, on keyboards that lack status LEDs).
  977.     Note that it is good practice to save the original states and
  978.     restore them before your program ends-- unless the entire goal
  979.     of your program is to set the keyboard toggles to a desired
  980.     state! Otherwise, you're likely to mess up the user's keyboard
  981.     preferences.
  982.  
  983.                            Memory PEEKs/POKEs               page 21
  984.  
  985.  
  986.     For direct memory access, nothing beats good ol' PEEK and
  987.     POKE... especially when they're extended to cover all common
  988.     variable types! IBRARY lets you read or write blocks of memory
  989.     ranging from bytes to strings.
  990.  
  991.        REM read a byte from memory into an integer
  992.        CALL SUB "PeekB" Segment Offset Value
  993.  
  994.        REM read an integer from memory
  995.        CALL SUB "PeekI" Segment Offset Value
  996.  
  997.        REM read a long integer from memory
  998.        CALL SUB "PeekL" Segment Offset Value&
  999.  
  1000.        REM read up to 80 bytes from memory into a string
  1001.        CALL SUB "PeekS" Segment Offset Bytes Value$
  1002.  
  1003.        REM write a byte to memory from an integer
  1004.        CALL SUB "PokeB" Segment Offset Value
  1005.  
  1006.        REM write an integer to memory
  1007.        CALL SUB "PokeI" Segment Offset Value
  1008.  
  1009.        REM write a long integer to memory
  1010.        CALL SUB "PokeL" Segment Offset Value&
  1011.  
  1012.        REM write up to 80 bytes to memory from a string
  1013.        CALL SUB "PokeS" Segment Offset Bytes Value$
  1014.  
  1015.     Note that strings can handle only up to 80 bytes, due to an ASIC
  1016.     limitation. Also, the results of PeekS may not be a normal ASIC
  1017.     string, if it contains null characters (CHR$(0), which marks the
  1018.     end of a traditional ASIC string). There is nothing wrong with
  1019.     this, as such, but remember that the string ends at the first
  1020.     CHR$(0) as far as ASIC is concerned-- so it won't see any
  1021.     characters which come after the first CHR$(0).
  1022.  
  1023.     For experimentation-- note that MDA video screens begin at
  1024.     segment -20480, offset 0; color video screens begin at segment
  1025.     -18432, offset 0. An 80x25 text-mode screen takes up 4000 bytes
  1026.     in either case (80x25 characters + 80x25 color/attribute codes).
  1027.     An assortment of useful information can be read from the BIOS
  1028.     data area, which begins at segment 64, offset 0-- check your
  1029.     local BBS for a good PEEK/POKE list! The old PEEKPOKE.TXT or the
  1030.     MEMORY.LST file provided with the INTER##.ZIP files would be a
  1031.     good place to start.
  1032.  
  1033.                                  Mouse                      page 22
  1034.  
  1035.  
  1036.     The mouse routines provide full-featured mouse support. You can
  1037.     see if a mouse is available and how many buttons it has, get the
  1038.     cursor position (either the current position or the position at
  1039.     the last press or release of a specified button), set the cursor
  1040.     position, change the cursor, set the mouse range, get hardware
  1041.     information about the mouse, and so on.
  1042.  
  1043.     There are two unusual mouse modes to be aware of. One is text
  1044.     mode, which is mapped to a 640x200 virtual display. So, to
  1045.     convert the results to text format, you need to divide the
  1046.     cursor position by eight and add one. To convert from text
  1047.     format, subtract one and multiply by eight.
  1048.  
  1049.     The second unusual mode is 320x200 CGA mode, which is also
  1050.     mapped to 640x200. To convert the coordinates to this mode,
  1051.     divide X by two. To convert from this mode, multiply the X
  1052.     coordinate by two.
  1053.  
  1054.     All other modes use the actual display coordinates instead of a
  1055.     bizarro virtual screen. Why the peculiar CGA and text modes?
  1056.     Well, evidently Microsoft never thought there'd be any video
  1057.     adapters besides MDA and CGA, and decided to create a single
  1058.     virtual screen size that worked for all modes. Not a bad idea, I
  1059.     guess, but rather shortsighted. Oh well.
  1060.  
  1061.     One other nuisance that you may run into is that the mouse
  1062.     cursor can't be directly turned on or off. A "cursor visibility"
  1063.     count is maintained-- if the mouse cursor was turned on twice,
  1064.     you'll need to turn it off twice before it will actually
  1065.     disappear.
  1066.  
  1067.     Before using the mouse, you must initialize it. The
  1068.     initialization routine also checks to make sure that a mouse is
  1069.     installed and tells you how many buttons it has. It's best to
  1070.     initialize the mouse after setting the screen mode, so the mouse
  1071.     driver understands what mode you're using. Not all mouse drivers
  1072.     support all screen modes, but you can reasonably expect any
  1073.     current mouse driver to support MDA, CGA, EGA, and VGA. Hercules
  1074.     graphics mode is rarely supported, as it must be set through
  1075.     direct hardware access rather than the standard techniques, so
  1076.     the mouse driver has little way of knowing that you've changed
  1077.     the mode.
  1078.  
  1079.     The mouse routines will work equally well with two-button or
  1080.     three-button rodents. The middle button functions will return 0
  1081.     with two-button mice.
  1082.  
  1083.                                  Mouse                      page 23
  1084.  
  1085.  
  1086.  
  1087.     I won't go into great detail on these routines, because they're
  1088.     pretty much self-explanatory. The mouse is a fairly easy device
  1089.     to deal with, despite the quirks of Microsoft's driver.
  1090.  
  1091.     You can initialize the mouse driver like so:
  1092.  
  1093.        CALL SUB "MInit" Buttons
  1094.  
  1095.     This returns the number of mouse buttons available. If there is
  1096.     no mouse, zero will be returned. Initialize the mouse AFTER
  1097.     setting the screen mode, so it knows what the screen is like.
  1098.  
  1099.     You can make the mouse cursor visible or invisible. It will
  1100.     function just as well in either state. See the previous page for
  1101.     some quirks.
  1102.  
  1103.        CALL SUB "MShow"
  1104.        CALL SUB "MHide"
  1105.  
  1106.     There are many ways to get the mouse cursor position. You can
  1107.     get the current position, the position at which the mouse was
  1108.     located when a particular button was pressed, or the position
  1109.     when a button was released. If you choose a past position, you
  1110.     can also find out how many presses or releases of the button
  1111.     have taken place since you last checked.
  1112.  
  1113.        REM current coordinates
  1114.        CALL SUB "MWhereX" X
  1115.        CALL SUB "MWhereY" Y
  1116.  
  1117.        REM number of presses of a given button
  1118.        REM and mouse position at last press
  1119.        CALL SUB "MLClick" Count X Y
  1120.        CALL SUB "MMClick" Count X Y
  1121.        CALL SUB "MRClick" Count X Y
  1122.  
  1123.        REM number of releases of a given button
  1124.        REM and mouse position at last release
  1125.        CALL SUB "MLRelease" Count X Y
  1126.        CALL SUB "MMRelease" Count X Y
  1127.        CALL SUB "MRRelease" Count X Y
  1128.  
  1129.                                  Mouse                      page 24
  1130.  
  1131.  
  1132.  
  1133.     If you'd prefer to find out which buttons are currently pressed,
  1134.     no problem:
  1135.  
  1136.        CALL SUB "MLButton" IsDown
  1137.        CALL SUB "MMButton" IsDown
  1138.        CALL SUB "MRButton" IsDown
  1139.  
  1140.     Of course, you can also set the cursor location:
  1141.  
  1142.        CALL SUB "MLocate" X Y
  1143.  
  1144.     The mouse cursor range can be restricted to a given area of the
  1145.     screen. This area is expressed by giving the upper left corner
  1146.     and lower right corner of the rectangular area to which to
  1147.     restrict the cursor.
  1148.  
  1149.        CALL SUB "MWindow" X1 Y1 X2 Y2
  1150.  
  1151.     There are a variety of cursor shapes available for graphics
  1152.     mode:
  1153.  
  1154.         0    hourglass ("please wait, program is working" symbol)
  1155.         1    pointing arrow (default)
  1156.         2    pointing hand
  1157.         3    crosshair
  1158.         4    target (box in a box)
  1159.         5    grabbing hand
  1160.  
  1161.     If you have ideas for more, let me know and I'll see what I can
  1162.     do. Cursor shapes are not unduly difficult to define, although
  1163.     it's technical enough so that I decided to avoid confusion by
  1164.     leaving direct handling out of IBRARY.
  1165.  
  1166.        CALL SUB "MCursorG" CursorNr
  1167.  
  1168.                              Miscellaneous                  page 25
  1169.  
  1170.  
  1171.  
  1172.     If there are not (yet) enough routines in a category to give
  1173.     them their own classification, they come to roost here, in good
  1174.     ol' Miscellaneous. At the moment, this consists of a string
  1175.     routine and some DOS output routines.
  1176.  
  1177.     The StrNB routine works like ASIC's built-in STR$ function, but
  1178.     strips all leading blanks from the result. It works on plain
  1179.     integers.
  1180.  
  1181.        CALL SUB "StrNB" Number Result$
  1182.  
  1183.     The DOS output routines allow you to send output to the default
  1184.     DOS device-- normally the screen, although it can be redirected
  1185.     by the user to another device or to a file. We start with a
  1186.     generic PRINT replacement:
  1187.  
  1188.        CALL SUB "DosPrint" St$
  1189.  
  1190.     That sends a string to standard output. If you want a carriage
  1191.     return and linefeed, you must add them yourself:
  1192.  
  1193.        CrLf$ = CHR$(13) + CHR$(10)
  1194.        St$ = St$ + CrLf$
  1195.  
  1196.     The rest of the DOS output routines require ANSI.SYS or another
  1197.     ANSI driver to be loaded. They send the appropriate ANSI codes
  1198.     to standard output.
  1199.  
  1200.        CALL SUB "DosCls"
  1201.  
  1202.        CALL SUB "DosColor" Foreground Background
  1203.  
  1204.        CALL SUB "DosLocate" Row Column
  1205.  
  1206.     It's now possible to get and set the state of the cursor, too.
  1207.     This is based on BIOS routines and is meant for use in text
  1208.     mode. The size and shape of the cursor is given in scan lines,
  1209.     which may range from about 8-16 depending on the display adapter
  1210.     and the size of your character font (which is related to the
  1211.     number of text rows on the screen).
  1212.  
  1213.        CALL SUB "CursorInfo" Visible StartLine EndLine MaxLine
  1214.  
  1215.     The VISIBLE variable will return zero if the cursor is not
  1216.     visible. The others return scan lines, which start at zero and
  1217.     end at whatever MAXLINE returns. You can set the cursor size and
  1218.     shape with:
  1219.  
  1220.        CALL SUB "SetCursor" StartLine EndLine
  1221.  
  1222.     Use a value of 32 for STARTLINE to make the cursor invisible. If
  1223.     you call SetCursor, you should also use CursorInfo, and set the
  1224.     original cursor shape back before ending your program.
  1225.  
  1226.                              Miscellaneous                  page 26
  1227.  
  1228.  
  1229.  
  1230.     Ibrary supports simple pop-up windows, too. You select the upper
  1231.     left corner and lower right corners of the window frame, a frame
  1232.     type, the color to use, and a title. If you don't want a title,
  1233.     just use a null string (""). Frame types may be any of:
  1234.  
  1235.        0     no frame
  1236.        1     single lines
  1237.        2     double lines
  1238.        3     single horizontal lines, double vertical lines
  1239.        4     double horizontal lines, single vertical lines
  1240.  
  1241.     The COLOUR value may include both foreground and background
  1242.     colors, using the formula: Colour = Backgnd * 16 + Foregnd.
  1243.  
  1244.        CALL SUB "PopWindow" TRow LCol BRow RCol Frame Colour Title$
  1245.  
  1246.     You can save (or restore) an 80x25 text screen, for either a
  1247.     mono or color display, with ScrSave and ScrRest. You'll need to
  1248.     specify the first element of a 2000-element integer array, the
  1249.     screen page (normally zero), and the video type (normally -1 for
  1250.     top speed; use 0 only if you're working with a CGA display and
  1251.     experience irritating "snow" during the save/restore.
  1252.  
  1253.        CALL SUB "ScrSave" ScreenArray(1) PageNr FastVideo
  1254.        CALL SUB "ScrRest" ScreenArray(1) PageNr FastVideo
  1255.  
  1256.     Want to delay for a while? IBRARY provides rock-solid delay
  1257.     routines that were designed to cope with multitasking and
  1258.     crossing the midnight boundary-- areas which can often cause
  1259.     havoc with homebrew delay routines. You can delay for a
  1260.     specified number of seconds or eighteenths of seconds:
  1261.  
  1262.        CALL SUB "Delay" Seconds
  1263.        CALL SUB "Delay18th" SplitSeconds
  1264.  
  1265.                              Miscellaneous                  page 27
  1266.  
  1267.  
  1268.  
  1269.     While ASIC provides a perfectly useful SOUND statement, it's not
  1270.     compatible with the one in Microsoft BASICs. This sound routine
  1271.     works just like the MS BASIC version, with the exception of
  1272.     taking a integer duration in 1/18th seconds.
  1273.  
  1274.        CALL SUB "Sound" Frequency Duration
  1275.  
  1276.     Useful frequencies run from around 50-4000. If you aim to make
  1277.     music using this service, the following table may prove of some
  1278.     use. You can move down an octave by halving the frequency for a
  1279.     given note. About seven octaves are available on the usual PC
  1280.     compatible.
  1281.  
  1282.        Note     Frequency (highest octave)
  1283.        =====    =========
  1284.          A         3520
  1285.        A#,B-       3714
  1286.          B         3952
  1287.          C         4186
  1288.        C#,D-       4434
  1289.          D         4698
  1290.        D#,E-       4978
  1291.          E         5274
  1292.          F         5588
  1293.        F#,G-       5920
  1294.          G         6272
  1295.        G#,A-       6644
  1296.  
  1297.