home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / progm / advbas.zip / ADVBAS.DOC < prev    next >
Text File  |  1988-04-02  |  116KB  |  5,357 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                 Advanced Function Library for the BASIC Compiler
  9.  
  10.  
  11.                               ADVBAS v99, 04/02/88
  12.  
  13.                    Copyright (C) Thomas Hanlin III, 1985-1988
  14.  
  15.                               1712 Maple Hill Place
  16.                               Alexandria, VA 22302
  17.  
  18.  
  19.  
  20.  
  21.  
  22.      Requirements:
  23.  
  24.           An  IBM  PC  or compatible with the IBM BASIC Compiler v2.x or any
  25.      Microsoft  QuickBASIC  Compiler.   PC-DOS/MS-DOS versions 2.0 or higher
  26.      should  be  used.   Some  functions  may require a PC AT or compatible,
  27.      as noted.  Please read the Operation Notes.
  28.  
  29.           NOTE  that  this  is  the  final release of ADVBAS.  There will be
  30.      no  further  releases.   As  of  August  1, 1988, I will not accept any
  31.      further  contributions,  so  if you want the source code, get it before
  32.      then.   I  have  decided  to  abandon  shareware entirely, for a number
  33.      of reasons...
  34.  
  35.           While  ADVBAS  is  full-featured  and  is not crippled in any way,
  36.      I'd  like  you  to  consider  it as a sample of the commercial library,
  37.      ProBas.   You  may  use  ADVBAS  subject to the restrictions below, but
  38.      you  will  be  much better off by upgrading to ProBas.  ProBas contains
  39.      nearly  twice  the  routines in ADVBAS, and comes with a printed manual
  40.      of  nearly  600  pages,  with tutorial and reference sections.  See the
  41.      PROBAS.DOC file for further information on ProBas.
  42.  
  43.  
  44.      Copying and Distribution:
  45.  
  46.           ADVBAS  may  be  copied  and  distributed  freely  EXCEPT  FOR THE
  47.      ASSEMBLY  SOURCE  CODE.   If  you  distribute  ADVBAS on communications
  48.      systems  such  as  BBSes  or  CompuServe,  the  Source, et al, you must
  49.      include  a  minimum  of  the following unmodified files as a set (using
  50.      ARC   or  an  equivalent  archive  utility):   ADVBAS.EXE,  ADVBAS.LIB,
  51.      ADVBAS.DOC,   ADVBAS.NEW,   ADVBAS.QRF,  ADVBAS.ERR,  CONTRIB.DOC,  and
  52.      PROBAS.DOC.   No  fee  other  than a disk and handling charge (of up to
  53.      $10) may be charged.
  54.  
  55.           The  copyright  is to preserve my options, and to protect you from
  56.      the  untoward  modifications  of others.  It is not intended to prevent
  57.      the public distribution of ADVBAS, subject to the above limitations.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.      Introduction:
  75.  
  76.           The  BASIC  Compiler  is  a  powerful and flexible tool.  However,
  77.      it  suffers  from  a  number of limitations.  It is hard to access many
  78.      of  the  capabilities of DOS; any feature which requires error trapping
  79.      cannot  be  used  in  a  subprogram; the memory requirements are fairly
  80.      substantial;  and  the  speed  is not all that it might be, for all its
  81.      improvement  over  interpreted  BASIC.   To reduce these problems, I've
  82.      designed  a  number of assembly language routines which perform various
  83.      functions,  and  put  them  in a library which the compiler can access.
  84.      Since  I  have  found  these functions to be useful, I thought I'd pass
  85.      them  on  to other people.  You may use ADVBAS functions in any of your
  86.      programs.   I'd appreciate it if you acknowledged use of these routines
  87.      in your program or documentation.
  88.  
  89.           If  you  find  ADVBAS useful, please support the author's efforts!
  90.      A minimum contribution of $25 will get you a disk containing the latest
  91.      version  of  ADVBAS,  including  source  and object code, PROVIDED THAT
  92.      YOU  SEND  IT  IN  BEFORE  AUGUST  1,  1988!  After then, I will not be
  93.      accepting any further contributions.
  94.  
  95.  
  96.  
  97.      Support:
  98.  
  99.           Please  read  this  manual  before  calling  me with any problems.
  100.      You can probably find the answer here, and save us both trouble. 
  101.           If  you  are  a  contributor  (bless you!), I'll certainly be glad
  102.      to  help  you  with  any  difficulties you may encounter.  U.S. Mail is
  103.      the  preferred  method  of  exchange,  but  feel  free  to  call if the
  104.      situation gets out of hand.
  105.  
  106.           If  you  are  not  a  contributor  (sigh), please send a SASE, and
  107.      I'll  get  back to you.  PLEASE do not phone!  If you don't care enough
  108.      to  contribute  the minimal fee I ask, you should not expect me to pro-
  109.      vide services.  TANSTAAFL!  (There Ain't No Such Thing As A Free Lunch)
  110.  
  111.  
  112.  
  113.      Caveats:
  114.  
  115.           These  functions  have  not  caused  me  any problems, and seem to
  116.      be  fully debugged.  However, I will not be responsible for any damages
  117.      caused by use, misuse, or inability to use ADVBAS.
  118.  
  119.           If  you run into problems, please read through the first few pages
  120.      of the manual.  All the information you need to use ADVBAS is in there.
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.      Misc. Notes:
  141.  
  142.           This  is  the  final shareware release of ADVBAS.  I will continue
  143.      to  support  it,  but I will not be releasing any new versions.  ADVBAS
  144.      is  being  replaced  by  the  ProBas  library,  which is being marketed
  145.      through commercial channels.
  146.  
  147.           ProBas  contains  about  twice  as many routines as ADVBAS.  Among
  148.      other goodies: sorting, expanded memory support, dynamic array support,
  149.      improved mouse routines, new equipment detection and control functions,
  150.      more  flexible  screen  handling,  an improved pop-up window generator,
  151.      controllable  field  input  with  editing,  "long" number support (even
  152.      if  you  don't  have  QuickBASIC 4.0!), and much more.  One of the more
  153.      powerful  capabilities  provided  by ProBas lies in a full set of func-
  154.      tions  to  support  "virtual  screens".  These are screens which can be
  155.      set  up  in memory, and then displayed (entirely or in part) instantly.
  156.      Using  conventional  or  expanded  memory,  you  can  store hundreds of
  157.      screens  in  memory  for instant recall.  This is similar to the paging
  158.      ability  of  EGA  and most CGA displays, but will work with any system,
  159.      and is not limited to just a few screens of information.
  160.  
  161.           An  extensive  (600-page)  printed  user  manual contains detailed
  162.      information  on  the  routines  in  a  format that is equally suited to
  163.      the  novice  or  the professional.  Fully documented demonstration code
  164.      in BASIC is also provided.
  165.  
  166.           ProBas  is  priced  at  $99.00.   Shipping is $3.00.  Sales tax is
  167.      applicable   for  Maryland  residents.   There  is  an  order  form  in
  168.      PROBAS.DOC, or you may address your ProBas order to:
  169.  
  170.           HCSI
  171.           8008 Sandy Spring Rd
  172.           Laurel, MD 20707
  173.  
  174.           For  more  information,  write  to  the  above address, or you can
  175.      call  (301)  953-2191.   C.O.D. orders  are  accepted,  and credit card
  176.      orders will hopefully be accepted in the near future.
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.      Using ADVBAS with QuickBASIC 4.0:
  207.  
  208.           Note  the  list  of  bugs  in  QuickBASIC  4.0  at the end of this
  209.      manual!  Some of them affect ADVBAS functions, so read up!
  210.  
  211.           If  you  use  QuickBASIC  in the programming environment, you need
  212.      to  have  a copy of ADVBAS.QLB in the drive/subdirectory where you keep
  213.      your  library  files  (like BRUNxx.LIB).  When you start up QuickBASIC,
  214.      you  need  to  tell  it  to  load the ADVBAS library so you can use its
  215.      features.   Run  QuickBASIC  with the following syntax: "QB /L ADVBAS".
  216.      You  may  also  specify a program to load: "QB MYPROG /L ADVBAS".  Note
  217.      that  you  are  not  meant  to  type in the quotes, which are there for
  218.      guidance  only.   You  may  also  need to include a drive/path spec for
  219.      ADVBAS  if  it  is  in  a  different drive/path than the default (which
  220.      is  either  the current area, or the area specified by the DOS environ-
  221.      ment  variable  "LIB").   That might look something like the following:
  222.      "QB /L C:\LIB\ADVBAS"
  223.  
  224.  
  225.  
  226.      Using ADVBAS with QuickBASIC 2.0 - 3.0:
  227.  
  228.           If  you  use  QuickBASIC  in the programming environment, you need
  229.      to  have  a copy of ADVBAS.EXE in the drive/subdirectory where you keep
  230.      your  library  files  (like BRUNxx.LIB).  When you start up QuickBASIC,
  231.      you  need  to  tell  it  to  load the ADVBAS library so you can use its
  232.      features.   Start  up  QuickBASIC using the syntax: "QB /L ADVBAS.EXE".
  233.      You  may  also  specify  a program to load: "QB PROGRAM /L ADVBAS.EXE".
  234.      Note  that  you  are  not  meant to type in the quotes, which are there
  235.      for  guidance  only.   You  may  also need to include a drive/path spec
  236.      for  ADVBAS  if it is in a different drive/path than the default.  That
  237.      might look something like "QB /L C:\LIB\ADVBAS.EXE".
  238.  
  239.  
  240.  
  241.      Using IBM or Microsoft BASIC compilers (command-line mode):
  242.  
  243.           Copy  ADVBAS.LIB to the disk on which you keep your BASIC Compiler
  244.      library files.  For programs which use ADVBAS functions, specify ADVBAS
  245.      when  LINK  asks  you  which  libraries to use.  That is, at the LINKer
  246.      prompt  "Libraries  [.LIB]:"  you  should  say  "ADVBAS"  (without  the
  247.      quotes!).   You  may  need to provide a drive/path spec if your program
  248.      is  not  in  the  same area that ADVBAS is, and if you don't have a SET
  249.      LIB  in  your  autoexec  file to tell the compiler where the library is
  250.      (only newer versions of the compilers have this feature). 
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.      Other languages:
  273.  
  274.           A  library  for  Microsoft  C is available under the name of ADVC.
  275.      It  is  in  C  source  format, so you can convert any nonstandard func-
  276.      tions  to  your  own  variety of C.  If you can't find it on your local
  277.      BBS,  I'll  send  you  a  copy for the recommended minimum contribution
  278.      of  $15,  IF  YOU  SEND  IT  IN BEFORE AUGUST 1, 1988.  Updates are not
  279.      anticipated.
  280.  
  281.           Commercial  versions  of  the  ADVBAS library to support languages
  282.      other  than  BASIC  will  be  shipping  in early 1988.  Languages to be
  283.      supported  are  Microsoft  C,  Pascal,  and  FORTRAN compilers, as well
  284.      as assembly language.  There will be no support for Borland's languages
  285.      until they come up with a decent way to handle libraries.
  286.  
  287.  
  288.  
  289.  
  290.      Advantages of ADVBAS:
  291.  
  292.           1) Adds abilities which are not otherwise available.
  293.           2) Is faster than the corresponding Compiled BASIC code.
  294.           3) Usually takes up less space in the resulting EXEcutable file.
  295.           4) Often leaves more free programming space.
  296.           5) Provides a useful library of tested low-level routines.
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.                                  Operation Notes
  339.  
  340.  
  341.  
  342.  
  343.      Function Requirements:
  344.  
  345.           Numeric  variables  used in function calls must be integers unless
  346.      specified  otherwise.   Either declare them using DEFINT, or add a per-
  347.      cent sign "%" to the end of the variable name.
  348.  
  349.           Strings  must  sometimes  be  defined to a certain minimum length,
  350.      due  to  limitations  on  what  assembly  language routines are allowed
  351.      to do to strings. 
  352.  
  353.           Dynamic Arrays cannot be used interchangeably with normal (Static)
  354.      arrays.   Use  only  static arrays with functions which require arrays.
  355.      Note  that  functions  requiring  static  arrays  cannot be used in the
  356.      QuickBASIC  4.0  environment,  due to a QB bug.  However, you may still
  357.      use them in the stand-alone version of the compiler, BC. 
  358.  
  359.  
  360.  
  361.      Compatibility:
  362.  
  363.           These  functions  vary in what they demand of your PC.  Some func-
  364.      tions  will  work only on IBM PCs or clones, some will work on compati-
  365.      bles,  and  some  will  work  on any MS-DOS machine.  The compatibility
  366.      level  of each function is now listed, using the categories CLONE (will
  367.      work  on  hardware  compatibles  only),  BIOS  (close compatibles), DOS
  368.      (any  MS-DOS  machine), and ANY (hardware independent).  Be warned that
  369.      the  BASIC  Compiler  itself  does  not produce particularly compatible
  370.      code (BASIC video routines seem to be BIOS-compatible, etc).
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.                                 Routine Reference
  405.  
  406.  
  407.  
  408.  
  409.      Disk:
  410.           CopyFile:  copy a file
  411.           DelSub, GetSub, MakeSub, SetSub:  subdirectory handling
  412.           DiskStat:  assorted disk status information
  413.           DrvSpace:  space left on a given drive
  414.           Exist:  see if a file exists
  415.           Fclose, Fcreate, Fopen, Fread, FsetEnd, FsetRec, Fclose:
  416.              file i/o
  417.           FindFirstF, FindNextF:  handle file(s) with wildcards
  418.           GetDrv, SetDrv:  get/set the default drive
  419.           GetFdate, GetFtime, SetFTD, GetFattr, SetFattr:  file info control
  420.           GetNameF, GetDateF, GetTimeF, GetAttrF, GetSizeF: file dir control
  421.           Mload:  a BLOAD routine
  422.           SubExist:  see if a subdirectory exists
  423.  
  424.      Input:
  425.           ClrKbd:  clear the keyboard buffer of pending keys
  426.           DosInkey:  get a key using DOS standard input
  427.           GetKbd, SetKbd:  get/set the status of the keyboard toggles
  428.           GetKey:  get one of a list of valid keys
  429.           KeyPress:  see if a key has been pressed
  430.  
  431.           MMcursorOn, MMcursorOff:         mouse cursor control
  432.           MMgetloc, MMsetloc, MMsetrange:  mouse display control
  433.           MMbutton, MMcheck, MMclick:      mouse status info
  434.  
  435.      String:
  436.           Bsq, BusqLen, Busq:  text compression/decompression
  437.           Checksum, CRC:  error checking (for telecomm and other uses)
  438.           Crunch:  remove duplicates of a character from a string.
  439.           DateN2S, DateS2N:  convert the date (numbers <--> string)
  440.           Extract:  take delimited substrings from a string using an index
  441.           Locase, Upcase:  case conversion
  442.           MultiAnd, MultiOr, MultiXor:  bit manipulations on strings
  443.           Strip, StripBlanks, StripRange:  deletion of chars from a string
  444.           LRotate, RRotate, Reverse:  reorder chars in a string
  445.           Soundex:  return the Soundex code of a string
  446.           TimeN2S, TimeS2N:  convert the time (numbers <--> string)
  447.           Tinstr:  find a given type of char within a string
  448.           Xlate:  run the chars of a string through a translation table
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.                                 Routine Reference
  471.  
  472.  
  473.  
  474.  
  475.      Array:
  476.           AddMatI, SetMatI:  integer array manipulation
  477.           ReadBitF, WriteBitF:  handle arrays of arbitrary bit length
  478.  
  479.      Video:
  480.           CalcAttr:  calculate attribute from fore and background colors
  481.           ClrEol, BkSpace, DelChr, InsChr, MDelChr, MInsChr:  screen control
  482.           DMprint, Mprint, MprintC, Qprint, XQprint:  various print routines
  483.           GetCRT:  get display type (mono or color)
  484.           MakeWindow:  make pop-up windows
  485.           Mwindow, Scroll, BkScroll:  display window control
  486.           PrintScreen:  print out the display to the default printer
  487.           ScrSave, ScrRest, GetLine:  save/restore the contents of a screen
  488.           ScrSaveP, ScrSavePD, ScrRestP, ScrRestPD:  variants on the above
  489.           GetScreen, PutScreen:  new flexible screen save/restore routines
  490.           ReColor: change any screen color to another w/o clearing screen
  491.           ResetPoint, SetPoint, TestPoint:  low-res graphics in text mode
  492.  
  493.      Miscellaneous:
  494.           Any2Dec, Dec2Any:  radix conversion (decimal <--> another base)
  495.           BlockMove:  move data from one area of memory to another
  496.           Carrier:  check modem Carrier Detect signal
  497.           DataSeg:  return the value of the default Data Segment
  498.           Date2int, Int2date:  date compression
  499.           Delay, Delay18th:  delay for a given amount of time
  500.           DTR:  turn the communications line "DTR" on or off
  501.           Equipment:  get hardware info about memory and installed ports
  502.           GetDOSv:  get the version number of the MS-DOS being used
  503.           GetExtM:  return the amount of extended memory (AT systems only)
  504.           GetLIMM:  get the status of expanded memory in the system
  505.           Month:  given a month number, returns the name of the month
  506.           SetComm:  set up any comm port to any baud, without closing comm
  507.           ShiftL, ShiftR:  bit shifts for integers
  508.           Speaker:  turns sound effects on or off
  509.           Time2int, Int2time:  time compression
  510.           WeekDay:  returns the day of the week, Sunday through Saturday
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.                                Compatibility Chart
  537.  
  538.  
  539.  
  540.  
  541.      Works on ANY machine:
  542.  
  543.           ADDMATI,   ANY2DEC,   BLOCKMOVE,  BSQ,  BUSQ,  BUSQLEN,  CALCATTR,
  544.      CHECKSUM,  CRC,  CRUNCH,  DATASEG, DATE2INT, DEC2ANY, EXTRACT, GETLINE,
  545.      INT2DATE,   INT2TIME,   LOCASE,   LROTATE,  MONTH,  MULTIAND,  MULTIOR,
  546.      MULTIXOR, READBITF, REVERSE, RROTATE, SETMATI, SHIFTL, SHIFTR, SOUNDEX,
  547.      STRIP,  STRIPBLANKS,  STRIPRANGE,  TIME2INT, TINSTR, UPCASE, WRITEBITF,
  548.      XLATE
  549.  
  550.  
  551.  
  552.      Works on DOS compatibles:
  553.  
  554.           COPYFILE,  DELSUB,  DISKSTAT,  DMPRINT, DOSINKEY, DRVSPACE, EXIST,
  555.      FCLOSE, FCREATE, FINDFIRSTF, FINDNEXTF, FOPEN, FREAD, FSETEND, FSETREC,
  556.      FWRITE,   GETATTRF,  GETDATEF,  GETDOSV,  GETDRV,  GETFATTR,  GETFDATE,
  557.      GETFTIME, GETNAMEF, GETSIZEF, GETSUB, GETTIMEF, MAKESUB, MLOAD, SETDRV,
  558.      SETFATTR, SETFTD, SETSUB, SUBEXIST, WEEKDAY
  559.  
  560.  
  561.  
  562.      Works on BIOS compatibles (* if it requires the AT BIOS):
  563.  
  564.           BKSCROLL,  BKSPACE,  CARRIER,  CLRKBD,  CLREOL,  DATEN2S, DATES2N,
  565.      DELAY,   DELAY18TH,   EQUIPMENT,  GETCRT,  GETEXTM*,  GETKEY,  GETLIMM,
  566.      KEYPRESS,  MDELCHR,  MINSCHR,  MMBUTTON, MMCHECK, MMCLICK, MMCURSOROFF,
  567.      MMCURSORON,  MMGETLOC,  MMSETLOC, MMSETRANGE, MPRINT, MPRINTC, MWINDOW,
  568.      PRINTSCREEN, RESETPOINT, SETPOINT, SCROLL, TESTPOINT, TIMEN2S, TIMES2N,
  569.      XMPRINT
  570.  
  571.  
  572.  
  573.      Works on CLONEs (hardware compatibles):
  574.  
  575.           DELCHR,  DTR,  GETKBD,  GETSCREEN,  INSCHR, MAKEWINDOW, PUTSCREEN,
  576.      QPRINT,  RECOLOR,  SCRREST,  SCRRESTP,  SCRRESTPD,  SCRSAVE,  SCRSAVEP,
  577.      SCRSAVEPD, SETCOMM, SETKBD, SPEAKER, XQPRINT, XQPRINTD
  578.  
  579.  
  580.  
  581.           Note  that  routines  from  higher  sections will work on machines
  582.      from  lower  sections  (DOS-level  routines  will  work  on  BIOS-  and
  583.      CLONE-level   machines).    It   doesn't  work  the  other  way  around
  584.      (CLONE-level routines may not work on a DOS-level machine).
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.      Name: ADDMATI
  603.  
  604.      Type: Miscellaneous / ANY
  605.  
  606.      Description:
  607.           Adds a scalar (integer) value to the first SIZ elements of an
  608.      integer  array.   You  can  subtract  by  adding a negative number.  If
  609.      the  results  of  the calculation ever go outside integer range (-32768
  610.      to  32767),  the  overflow flag is set on return.  See SETMATI for more
  611.      information.
  612.  
  613.      Example:
  614.           OPTION BASE 1: DIM ACK%(10000): SIZ%=10000
  615.            .
  616.            .
  617.           ADDVAL%=-6: ARLOC%=VARPTR(ACK%(1))
  618.           CALL ADDMATI(ARLOC%,SIZ%,ADDVAL%,OVFLOW%)
  619.           IF OVFLOW% THEN PRINT"Uh oh, overflowed somewhere..."
  620.           REM  we just subtracted six from each element of the array ACK.
  621.  
  622.  
  623.  
  624.  
  625.      Name: ANY2DEC
  626.  
  627.      Type: Miscellaneous / ANY
  628.  
  629.      Description:
  630.           Converts  a  number  (in  string  form)  from any base (2-35) to a
  631.      decimal integer (base 10).  The number to be converted may be in either
  632.      signed  integer  range  (-32768  to 32767) or unsigned integer range (0
  633.      to  65535).   It  is  converted  to a signed integer, which is the only
  634.      integer type BASIC supports.
  635.  
  636.      Example:
  637.           INPUT"Number, base of number";ANUM$,NBASE%
  638.           CALL ANY2DEC(ANUM$,NBASE%,DNUM%,ERCD%)
  639.           IF ERCD% THEN PRINT"Bad number!" ELSE PRINT"Decimal: ";DNUM%
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.      Name: BKSCROLL
  669.  
  670.      Type: Video / BIOS
  671.  
  672.      Description:
  673.           The  same  as  SCROLL  (q.v.),  but  scrolls lines in the opposite
  674.      direction (Back Scroll).
  675.  
  676.      Example:
  677.        
  678.           CALL BKSCROLL(LEFTCOL%,TOPROW%,RTCOL%,BOTROW%,NUMLINES%)
  679.  
  680.  
  681.  
  682.  
  683.      Name: BKSPACE
  684.  
  685.      Type: Video / BIOS
  686.  
  687.      Description:
  688.           Move  cursor back one space, destroying the character on the space
  689.      moved  to.   Will  wrap  from one line to the next higher if necessary.
  690.      If  at  the  top  left  corner  of  the screen, no action is performed.
  691.      Two  arguments  return  the  new  cursor coordinates.  Works with 40 or
  692.      80 column screens in text mode.
  693.  
  694.      Example:
  695.           CALL BKSPACE(COL%,ROW%): LOCATE ROW%,COL%
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.      Name: BLOCKMOVE
  736.  
  737.      Type: Miscellaneous / ANY
  738.  
  739.      Description:
  740.           Copies information from one area of memory to another.  You supply
  741.      the  source  segment and offset, destination segment and offset, number
  742.      of  bytes  to  move (0 - 65535), and direction (zero, forward; nonzero,
  743.      backward).   This  can  be  used,  for  instance,  to duplicate numeric
  744.      arrays. including dynamic arrays.
  745.  
  746.      Example:
  747.      CALL BLOCKMOVE(FROMSEG%,FROMOFFSET%,TOSEG%,TOOFFSET%,BYTES%,DIRECTION%)
  748.  
  749.  
  750.  
  751.  
  752.      Name: BSQ
  753.  
  754.      Type: String / ANY
  755.  
  756.      Description:
  757.           Uses  several  techniques to compress blank spaces out of an ASCII
  758.      string.   Savings  range  from  16% (reliable, for ordinary text) to up
  759.      around 50% or more for space-intensive info, such as lines in an assem-
  760.      bly  source  file.   BSQ  cannot  handle  more than 127 spaces in a row
  761.      on  a  single  line,  or  lines  which contain ASCII characters greater
  762.      than  127  (which  are  IBM-specific  graphics characters).  Do not use
  763.      BSQ  on  lines  which  may  contain  such information!  BSQ compression
  764.      is  designed  to  produce printable (if odd-looking) text which you may
  765.      read/write to ordinary sequential files.
  766.  
  767.      Example:
  768.           INPUT"String to squeeze";ST$: CALL BSQ(ST$,SLEN%)
  769.           PRINT"Squeezed string: ";LEFT$(ST$,SLEN%)
  770.  
  771.  
  772.  
  773.  
  774.      Name: BUSQ
  775.  
  776.      Type: String / ANY
  777.  
  778.      Description:
  779.           Decompresses  a  line  squeezed  by  BSQ.  Use BUSQLEN before this
  780.      routine to find out how long the unsqueezed line will be!
  781.  
  782.      Example:
  783.           see BUSQLEN
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.      Name: BUSQLEN
  802.  
  803.      Type: String / ANY
  804.  
  805.      Description:
  806.           Tells  how  long  a  line  squeezed  with  BSQ  will  be once it's
  807.      unsqueezed.  You must use this before unsqueezing the line with BUSQ.
  808.  
  809.      Example:
  810.           CALL BUSQLEN(ST$,SLEN%)
  811.           IF SLEN%<0 THEN line not squeezed, or damaged-- exit!
  812.           ELSE UNSQ$=SPACE$(SLEN%): CALL BUSQ(ST$,UNSQ$)
  813.  
  814.  
  815.  
  816.  
  817.      Name: CALCATTR
  818.  
  819.      Type: Video / ANY
  820.  
  821.      Description:
  822.           Calculates  the  color  attribute  for  such  routines as XQPRINT.
  823.      Unlike  the  BASIC  formula  it  replaces,  CALCATTR  allows use of the
  824.      "blink" attribute.
  825.  
  826.      Example:
  827.           REM  old formula was  ATTR% = (BACKGND% AND 7)*16 + FOREGND%
  828.           CALL CALCATTR(FOREGND%,BACKGND%,ATTR%)
  829.  
  830.  
  831.  
  832.  
  833.      Name: CARRIER
  834.  
  835.      Type: Miscellaneous / BIOS
  836.  
  837.      Description:
  838.           Returns  the  status  of the modem Carrier Detect signal.  You may
  839.      specify communications port one or two.
  840.  
  841.      Example:
  842.           COMMPORT% = 1
  843.           CALL CARRIER(COMMPORT%,CDSTATUS%)
  844.           IF CDSTATUS% THEN PRINT "Carrier detected" ELSE PRINT "No carrier"
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.      Name: COPYFILE
  868.  
  869.      Type: Disk / DOS
  870.  
  871.      Description:
  872.           Copies a file.  This is faster than the corresponding DOS command,
  873.      and  doesn't  have  the  overhead of using the SHELL command.  Note: to
  874.      avoid  possibly  wiping  out  an  existing file on the destination end,
  875.      you may wish to use the EXIST function before this one.
  876.           The  copy  will  usually  fail  for one of two reasons: the source
  877.      file  doesn't  exist,  or  there is not enough room on the disk for the
  878.      destination file.
  879.  
  880.      Example:
  881.           SOURCE$="A:EXAMPLE.TXT"+CHR$(0)
  882.           DESTINATION$="C:\DOCUMENT\EXAMPLE.TXT"+CHR$(0)
  883.           CALL COPYFILE(SOURCE$,DESTINATION$,ERRCODE%)
  884.           IF ERRCODE% THEN PRINT"The copy failed"
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.      Name: CHECKSUM
  934.  
  935.      Type: Miscellaneous / ANY
  936.  
  937.      Description:
  938.           Calculates  a  checksum  for  a  record.   Can be used with Xmodem
  939.      or Ymodem.
  940.  
  941.      Example:
  942.           CALL CHECKSUM(REC$,CHKSM%)
  943.  
  944.  
  945.  
  946.  
  947.      Name: CLREOL
  948.  
  949.      Type: Video / BIOS
  950.  
  951.      Description:
  952.           Clears  from  the  cursor  position to the end of the line without
  953.      moving the cursor.
  954.  
  955.      Example:
  956.           CALL CLREOL
  957.  
  958.  
  959.  
  960.  
  961.      Name: CLRKBD
  962.  
  963.      Type: Input / BIOS
  964.  
  965.      Description:
  966.           Clears any pending keys from the keyboard buffer.
  967.  
  968.      Example:
  969.           CALL CLRKBD
  970.           INPUT"File not found.  Continue (Y/N)";ANS$
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.      Name: CRC
  1000.  
  1001.      Type: Miscellaneous / ANY
  1002.  
  1003.      Description:
  1004.           Calculates  a  cyclical redundancy check value for a record.  This
  1005.      is  useful  for  error  detection,  and  can be used with Xmodem CRC or
  1006.      Ymodem CRC modem transfer protocols.
  1007.  
  1008.      Example:
  1009.        Sending a record:
  1010.           REC$=REC$+STRING$(2,0) : CALL CRC(REC$,HICRC%,LOCRC%) :
  1011.           MID$(REC$,LEN(REC$)-1,2) = CHR$(HICRC)+CHR$(LOCRC%)
  1012.           REM  we're set to send an Xmodem record
  1013.        Receiving a record:
  1014.           CALL CRC(REC$,HICRC%,LOCRC%) : IF HICRC%=0 AND LOCRC%=0
  1015.                THEN record is fine, save it
  1016.                ELSE record is bad, request it to be sent again
  1017.  
  1018.  
  1019.  
  1020.  
  1021.      Name: CRUNCH
  1022.  
  1023.      Type: String / ANY
  1024.  
  1025.      Description:
  1026.           Crunches  duplicates  of  a  given  character  in a string down to
  1027.      a single character.
  1028.  
  1029.      Example:
  1030.           ST$="This####is#a##test"
  1031.           CH$="#"
  1032.           CALL CRUNCH(ST$,CH$,SLEN%)
  1033.           ST$=LEFT$(ST$,SLEN%)
  1034.           REM  the result here will be "This#is#a#test"
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.      Name: DATASEG
  1066.  
  1067.      Type: Miscellaneous / ANY
  1068.  
  1069.      Description:
  1070.           Returns  BASIC's  data  segment.   This  is  useful for BLOCKMOVE,
  1071.      among other things.
  1072.  
  1073.      Example:
  1074.           CALL DATASEG(DSEG%)
  1075.  
  1076.  
  1077.  
  1078.  
  1079.      Name: DATE2INT
  1080.  
  1081.      Type: Miscellaneous / ANY
  1082.  
  1083.      Description:
  1084.           Compresses  a  date  down  to  a single integer, to reduce storage
  1085.      requirements.   The  date  is  assumed to be valid.  The year should be
  1086.      within  the  range  1900-2026  (0-99  is  ok,  and  is  assumed  to  be
  1087.      1900-1999).  See also INT2DATE.
  1088.  
  1089.      Example:
  1090.           CALL DATE2INT(MONTH%,DAY%,YEAR%,SQZDATE%)
  1091.  
  1092.  
  1093.  
  1094.  
  1095.      Name: DATEN2S
  1096.  
  1097.      Type: String / ANY
  1098.  
  1099.      Description:
  1100.           Converts the date from numeric form to a string.  You must reserve
  1101.      at least eight characters for the string.
  1102.  
  1103.      Example:
  1104.           MONTH% = 3: DAY% = 2: YEAR% = 1987
  1105.           REM  We could use YEAR%=87 instead
  1106.           DAT$ = SPACE$(8)
  1107.           CALL DATEN2S(MONTH%,DAY%,YEAR%,DAT$)
  1108.           REM  From this, we will get DAT$ = "03/02/87"
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.      Name: DATES2N
  1132.  
  1133.      Type: String / ANY
  1134.  
  1135.      Description:
  1136.           Converts  the date from a string to numeric form.  The date string
  1137.      may   be  in  either  BASIC  format  ("03-15-1987")  or  normal  format
  1138.      ("03/15/87").
  1139.  
  1140.      Example:
  1141.           CALL DATES2N(MONTH%,DAY%,YEAR%,DATE$)
  1142.  
  1143.  
  1144.  
  1145.  
  1146.      Name: DEC2ANY
  1147.  
  1148.      Type: Miscellaneous / ANY
  1149.  
  1150.      Description:
  1151.           Converts  a  number  from  decimal  (base  10)  to  any other base
  1152.      (2-35).   The  number  will be converted to an unsigned integer (signed
  1153.      range of -32768 to 32767 is converted to unsigned range of 0 to 65535),
  1154.      to  conform with the built-in BASIC conversion functions HEX$ and OCT$.
  1155.      ANUM$  must be initialized to the maximum size you expect the resultant
  1156.      number  to  be;  this  is recommended to be 16 characters, which is the
  1157.      maximum  length  possible.   The result is right-justified in the field
  1158.      you  provide,  so  if  you want to keep leading zeroes, just ignore the
  1159.      actual-length specification ALEN%.
  1160.  
  1161.      Example:
  1162.           INPUT"Decimal number, to base";DNUM%,NBASE%
  1163.           ANUM$ = STRING$(16,"0"): CALL DEC2ANY(DNUM%,NBASE%,ANUM$,ALEN%)
  1164.           IF ALEN%<0 THEN PRINT"Bad base or ANUM$ initialized too short"
  1165.           ELSE PRINT"Result: ";RIGHT$(ANUM$,ALEN%)
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.      Name: DELAY
  1198.  
  1199.      Type: Miscellaneous / BIOS
  1200.  
  1201.      Description:
  1202.           Delays for a given number of seconds.  This is based on the system
  1203.      clock,  and  will  delay  for  the  same  amount  of time on an 8088 or
  1204.      80286-based  computer.   It  is  normally  accurate to within about one
  1205.      percent.
  1206.  
  1207.      Example:
  1208.           SECONDS%=60
  1209.           CALL DELAY(SECONDS%)
  1210.           REM  sit and "do nothing" for one minute
  1211.  
  1212.  
  1213.  
  1214.  
  1215.      Name: DELAY18TH
  1216.  
  1217.      Type: Miscellaneous / BIOS
  1218.  
  1219.      Description:
  1220.           Delays  for  a given number of eighteenths of seconds.  Otherwise,
  1221.      this is identical to DELAY (see).
  1222.  
  1223.      Example:
  1224.           MINIDELAY%=9
  1225.           CALL DELAY18TH(MINIDELAY%)
  1226.           REM  delay for half a second (9/18 = 1/2 second)
  1227.  
  1228.  
  1229.  
  1230.  
  1231.      Name: DELCHR
  1232.  
  1233.      Type: Video / CLONE
  1234.  
  1235.      Description:
  1236.           Deletes  a  character  from  the specified location on the screen.
  1237.      The  character  at  that  location  will  disappear, and all characters
  1238.      to  the  right  of  it on the same screen line will be shifted left one
  1239.      space.   The  first  page  only  (on  color monitors) is supported, and
  1240.      text mode is required.
  1241.  
  1242.      Example:
  1243.           COL%=POS(0): ROW%=CSRLIN
  1244.           CALL DELCHR(ROW%,COL%)
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.      Name: DELSUB
  1264.  
  1265.      Type: Disk / DOS
  1266.  
  1267.      Description:
  1268.           Deletes  a  subdirectory.   Parameters  used  are  the  same as in
  1269.      SETSUB.   Note  that  you  may  not delete a subdirectory if it has any
  1270.      files  left  in  it,  or  if  it is the main directory, or if it is the
  1271.      current default subdirectory.
  1272.  
  1273.      Example:
  1274.           TMP$=SUB$+CHR$(0)
  1275.           CALL DELSUB(TMP$,ERRCODE%)
  1276.           IF ERRCODE% THEN couldn't delete subdir ELSE subdir deleted
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.      Name: DISKSTAT
  1330.  
  1331.      Type: Disk / DOS
  1332.  
  1333.      Description:
  1334.           Returns  status  information  for  a  given disk drive.  The drive
  1335.      spec should be a letter, or use "@" for the default drive.  Information
  1336.      returned  will  be  Free  Clusters,  Total  Clusters, Bytes per Sector,
  1337.      and  Sectors  per Cluster.  This will enable you to calculate the total
  1338.      space  on  the  disk,  free  space  left on the disk, the actual amount
  1339.      of  space  a  file  takes up, and so forth.  A "cluster" is the minimum
  1340.      block  of  space  that  can  be allocated on a disk.  The actual amount
  1341.      of  space  taken  up  by  a  file  depends on the cluster size.  If the
  1342.      cluster  size  is  1024 bytes, any file that is listed as being between
  1343.      1  and  1024  bytes  will  take  up 1024 bytes of disk space.  Any file
  1344.      listed  as  having  1025  -  2047 bytes will take up 2048 bytes (1024 *
  1345.      2), and so on.
  1346.  
  1347.      Example:
  1348.           DRIVE$ = "@":  REM  Use the default drive
  1349.           CALL DISKSTAT(DRIVE$,FRE.CLUST%,TOT.CLUST%,BYTES.SEC%,SECS.CLUST%)
  1350.           CLUSTER.SIZE# = CDBL(BYTES.SEC%) * CDBL(SECS.CLUST%)
  1351.           FREE.DISK.SPACE# = CDBL(FRE.CLUST%) * CLUSTER.SIZE#
  1352.           TOTAL.DISK.SPACE# = CDBL(TOT.CLUST%) * CLUSTER.SIZE#
  1353.           PRINT "There are";FREE.DISK.SPACE#;" bytes free out of";
  1354.           PRINT TOTAL.DISK.SPACE#;" with";CLUSTER.SIZE#;" bytes per cluster"
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.      Name: DMPRINT
  1396.  
  1397.      Type: Video / DOS
  1398.  
  1399.      Description:
  1400.           Displays  a string at the current cursor position, using DOS calls
  1401.      for  output  (so  device  drivers  such  as  ANSI.SYS will work).  This
  1402.      routine  is  faster  than  MPRINT  (q.v.),  but offers fewer amenities.
  1403.      Character  translation  is  limited to what DOS provides, meaning that,
  1404.      for  instance,  Backspace  just  moves  the  cursor back without wiping
  1405.      out  the previous character.  Other control codes may not be translated
  1406.      as  you  might  hope,  either.   Finally,  since DOS provides no way of
  1407.      finding  the  current  print position, you have to figure out where the
  1408.      cursor  will  be  yourself if you need it (like other display routines,
  1409.      DMPRINT  does  not  update  the  BASIC  cursor position).  You can gain
  1410.      control  of  such  things  by  using the ANSI.SYS driver.  See your DOS
  1411.      manual for more information on that.
  1412.  
  1413.      Example:
  1414.           CALL DMPRINT(ST$)
  1415.  
  1416.  
  1417.  
  1418.  
  1419.      Name: DOSINKEY
  1420.  
  1421.      Type: Keyboard / DOS
  1422.  
  1423.      Description:
  1424.           Gets  a  key  from  the  standard  input device.  This is normally
  1425.      the  keyboard,  but  redirection  is  allowed  (to a file, or to a port
  1426.      via  CTTY).  Two parameters are returned: the first gives the key code,
  1427.      if  any,  and  the  second gives status information.  If the CHRTYPE is
  1428.      zero,  there  is  no  key  pressed.   If it is one, the key returned is
  1429.      a  normal  keypress.   If  it  is  two, the key returned is the code of
  1430.      an Extended ASCII key (like a function key or arrow key).
  1431.  
  1432.      Example:
  1433.           REM  This is an INKEY$-oriented routine to get a keypress.
  1434.           KY$ = ""
  1435.           WHILE KY$=""
  1436.               KY$ = INKEY$
  1437.           WEND
  1438.           IF LEN(KY$)=2 THEN EXTCODE=-1: KY$=RIGHT$(KY$,1) ELSE EXTCODE=0
  1439.           RETURN
  1440.  
  1441.           REM  This is the same routine, using DOSINKEY.
  1442.           CHRTYPE% = 0
  1443.           WHILE CHRTYPE%=0
  1444.               CALL DOSINKEY(CHRCODE%,CHRTYPE%)
  1445.           WEND
  1446.           KY$ = CHR$(CHRCODE%)
  1447.           IF CHRTYPE%=2 THEN EXTCODE%=-1 ELSE EXTCODE%=0
  1448.           RETURN
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.      Name: DRVSPACE
  1462.  
  1463.      Type: Disk / DOS
  1464.  
  1465.      Description:
  1466.           Returns  the  amount  of  free  space  left on a given disk drive.
  1467.      The  drive  string  may  be  any legal disk drive, or "@" (AT sign) for
  1468.      the default drive, and must be at least one character long.  An illegal
  1469.      drive or other error will cause free space to be returned as a negative
  1470.      value.  See also DISKSTAT.
  1471.  
  1472.      Example:
  1473.           DRV$="A:"
  1474.            .
  1475.            .
  1476.           CALL DRVSPACE(DRV$,A%,B%,C%)
  1477.           FREE# = CDBL(A%)*CDBL(B%)*CDBL(C%)
  1478.           PRINT"Free space on drive ";DRV$;" is";FREE#;"bytes."
  1479.  
  1480.  
  1481.  
  1482.  
  1483.      Name: DTR
  1484.  
  1485.      Type: Miscellaneous / CLONE
  1486.  
  1487.      Description:
  1488.           Switches  the  communications  signal  DTR  (Data  Terminal Ready)
  1489.      on  or  off.   Turning the DTR off has the effect of making most modems
  1490.      drop  carrier  (hang  up  the  phone).   The comm port should be one or
  1491.      two.  Use zero to turn the DTR off, or nonzero to turn it back on.
  1492.  
  1493.      Example:
  1494.           COMMPORT% = 1
  1495.           TOGGLE% = 0   : REM  turn the DTR off
  1496.           CALL DTR(COMMPORT%,TOGGLE%)
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.      Name: EQUIPMENT
  1528.  
  1529.      Type: Miscellaneous / BIOS
  1530.  
  1531.      Description:
  1532.           Returns  basic  information  about  the  hardware configuration of
  1533.      the  computer: memory  installed,  in  kilobytes;  number  of  parallel
  1534.      (printer)  ports,  0-3;  number  of RS232 serial (comm) ports, 0-7; and
  1535.      number of game ports, 0-1.
  1536.  
  1537.      Example:
  1538.           CALL EQUIPMENT(MEMORY%,PARALLEL%,SERIAL%,GAME%)
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.      Name: EXIST
  1594.  
  1595.      Type: Disk / DOS
  1596.  
  1597.      Description:
  1598.           Tells  you  if  a  given  file already exists.  Returns zero if it
  1599.      doesn't,  or  a  nonzero  value if it does.  Requires an ASCIZ filename
  1600.      without  wildcards.   If  you  need  to use wildcards, or are operating
  1601.      in a network environment, use the FINDFIRSTF function instead.
  1602.  
  1603.      Example:
  1604.           FIL$="TEST.TXT"+CHR$(0)
  1605.           CALL EXIST(FIL$,FILEXISTS%)
  1606.           IF FILEXISTS% THEN PRINT "File already exists"
  1607.  
  1608.  
  1609.  
  1610.  
  1611.      Name: EXTRACT
  1612.  
  1613.      Type: String / ANY
  1614.  
  1615.      Description:
  1616.           Extracts  a  delimited  substring  from  a  string given an index.
  1617.      Requires  a  string  of  any  length,  a  delimiter of one character in
  1618.      length,  and  an  index value from 1-256; returns the starting location
  1619.      and  length  of  the  substring.   If the delimiter is null (an error),
  1620.      the  substring  length  will  be returned as -1.  If the index value is
  1621.      greater  than  the  number  of  delimited  substrings, a length of zero
  1622.      will be returned.
  1623.  
  1624.      Example:
  1625.           ST$="John Doe/15 Maple Rd/Hometown, CA 99199/(300) 111-1111"
  1626.           INDEX%=2
  1627.           DELIMITER$="/"
  1628.           CALL EXTRACT(ST$,DELIMITER$,INDEX%,START%,SLEN%)
  1629.           PRINT MID$(ST$,START%,SLEN%)
  1630.           REM  This will print the second substring (INDEX%=2) of the string
  1631.           REM  (ST$) delimited by "/" (DELIMITER$), which in this case
  1632.           REM  will be "15 Maple Rd".
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.      Name: FCLOSE
  1660.  
  1661.      Type: Disk / DOS
  1662.  
  1663.      Description:
  1664.           Closes a file opened by MOPEN (q.v.)
  1665.  
  1666.      Related functions: MCREATE, MOPEN, MREAD, MSETEND, MSETREC, MWRITE.
  1667.  
  1668.      Example:
  1669.           CALL FCLOSE(HANDLE%)
  1670.  
  1671.  
  1672.  
  1673.  
  1674.      Name: FCREATE
  1675.  
  1676.      Type: Disk / DOS
  1677.  
  1678.      Description:
  1679.           Opens  a  file  with  a  given  attribute for read/write access in
  1680.      normal  mode.   If  the  file  doesn't exist, it's created; if it does,
  1681.      it's  set  to  zero  bytes in length.  A "handle" is returned, which is
  1682.      used  to  identify  the  file  (like  BASIC's file numbers).  See FOPEN
  1683.      for  an  explanation  of  modes.   For more information, see the end of
  1684.      this manual.
  1685.  
  1686.      Related functions: FOPEN, FREAD, FSETEND, FSETREC, FWRITE.
  1687.  
  1688.      Example:
  1689.           FIL$="TEST.TXT"+CHR$(0)
  1690.           ATTR%=0
  1691.           CALL FCREATE(FIL$,ATTR%,TEST.HANDLE%,ERRCODE%)
  1692.           IF ERRCODE% THEN PRINT "Couldn't create file"
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.      Name: FINDFIRSTF
  1726.  
  1727.      Type: Disk / DOS
  1728.  
  1729.      Description:
  1730.           Given  a  filename  (which  may contain the wildcards "*" and "?",
  1731.      and  a  drive  and  path  spec  if you like), this searches the default
  1732.      (or  specified)  directory  to  find  the first matching file.  Further
  1733.      matches  can  be  obtained  through  the  FINDNEXTF routine (q.v.).  If
  1734.      there  is  a  match,  ERCD%  will return zero, otherwise it will return
  1735.      a  positive  value  (unless  you entered a null filename, in which case
  1736.      ERCD%  will be -1 to flag an error).  You can retrieve various informa-
  1737.      tion  about  the  matched file via a number of supplementary functions:
  1738.      GETNAMEF  to  get  the filename, GETATTRF to get the attribute (there's
  1739.      a  page  at  the end of this document on file attributes), GETDATEF and
  1740.      GETTIMEF  to  get the date and time, and GETSIZEF to get the file size.
  1741.      You  may  specify  a search attribute as well: 0 (zero) to match normal
  1742.      files, 2 to match hidden files, 4 for system files, and 16 for subdirec-
  1743.      tories.   Attributes  other  than zero will return normal files as well
  1744.      as  the  specified  type,  and  you  can match on more than one kind of
  1745.      attribute (for instance, to get all kinds of files, you'd use an attri-
  1746.      bute  of 22, or 2+4+16).  You can read the volume label using an attri-
  1747.      bute  of  8,  which  is  supposed  to return only the volume label, but
  1748.      may not (see notes in the File Attribute info at the end of this file).
  1749.  
  1750.           This  function can be used to duplicate the DOS directory command,
  1751.      or to allow filename wildcards in your program, among other things.
  1752.  
  1753.      Example:
  1754.           FIL$=FIL$+CHR$(0)
  1755.           CALL FINDFIRSTF(FIL$,ATTR%,ERCD%)
  1756.           IF ERCD% THEN PRINT"No matching files"
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.      Name: FINDNEXTF
  1792.  
  1793.      Type: Disk / DOS
  1794.  
  1795.      Description:
  1796.           This  is  used  after  the  FINDFIRSTF function (q.v.) in order to
  1797.      find further matching files.
  1798.  
  1799.      Example:
  1800.           CALL FINDNEXTF(ERCD%)
  1801.           IF ERCD% THEN PRINT"No more matching files"
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.      Name: FOPEN
  1858.  
  1859.      Type: Disk / DOS
  1860.  
  1861.      Description:
  1862.           Opens  an  already-existing  file.   If  you  want to create a new
  1863.      file,  use  the  FCREATE  function.   You  tell  it the ASCIZ filename,
  1864.      ACCESS%  method,  and  MODE%; it gives back a HANDLE% or ERRCODE%.  The
  1865.      ACCESS%  method  is  how  you want to open the file: 0, read; 1, write;
  1866.      2, read/write.  The MODE% controls access to the file by other programs
  1867.      operating  at  the same time, and is hence only useful for multitasking
  1868.      or  networking.   MODE%  is: 0, normal (no multitasking or networking);
  1869.      1,  exclusive  (no  other  program  can access the file); 2, deny write
  1870.      (no  other program may change the file); 3, deny read (no other program
  1871.      may  look  at  the  file);  4,  deny none (any other program may access
  1872.      the  file).   To  activate  handling of nonzero modes, you must execute
  1873.      the  DOS  utility  SHARE, which is included on your DOS disk.  For more
  1874.      information, see the end of this manual.
  1875.  
  1876.      Related functions: FCLOSE, FCREATE, FREAD, FSETEND, FSETREC, FWRITE.
  1877.  
  1878.      Example:
  1879.           FIL$="TEST.TXT"+CHR$(0)
  1880.           FACCESS%=2  : REM  Open the file with read/write access
  1881.           FMODE%=0    : REM  Normal mode, not networking or multitasking
  1882.           CALL FOPEN(FIL$,FACCESS%,FMODE%,TEST.HANDLE%,ERRCODE%)
  1883.           IF ERRCODE% THEN PRINT "Unable to open the file"
  1884.  
  1885.      Example:
  1886.           FIL$="C:\DOCUMENT\TEST.TXT"+CHR$(0)
  1887.           FACCESS%=2  : REM  Open the file for read access
  1888.           FMODE%=2    : REM  Deny Write mode, for networking/multitasking
  1889.           REM  We "deny write" so nobody else can change the file while
  1890.           REM
  1891.                we're reading it.  We'll let others read from the file while
  1892.           REM  we are, though.  (This works like Normal mode if SHARE wasn't
  1893.           REM  executed)
  1894.           CALL FOPEN(FIL$,FACCESS%,FMODE%,TEST.HANDLE%,ERRCODE%)
  1895.           IF ERRCODE% THEN PRINT "Unable to open file"
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.      Name: FREAD
  1925.  
  1926.      Type: Disk / DOS
  1927.  
  1928.      Description:
  1929.           Reads  information  from  a  file opened by FOPEN or FCREATE.  You
  1930.      tell  it  which  file  to  read  from by giving it the handle which was
  1931.      returned  when  you  opened  the  file.   You give it a buffer location
  1932.      to read into, which can be either an array (for use, say, with SCRREST)
  1933.      or  a string (for more usual purposes).  You are responsible for seeing
  1934.      that  the  buffer  is  large enough to hold all the bytes that you want
  1935.      to read!
  1936.           FREAD  returns  a  nonzero  ERRCODE%  if  anything went wrong.  If
  1937.      ERRCODE% is -1, it was able to read only part of the information before
  1938.      hitting  an  end  of  file.  In that case, BYTESREAD% will tell you how
  1939.      many  bytes  were  actually  read  in.   See the end of this manual for
  1940.      info on error codes.
  1941.  
  1942.      Related functions: FCLOSE, FCREATE, FOPEN, FSETEND, FSETREC, FWRITE
  1943.  
  1944.      Example:
  1945.           OPTION BASE 1: DIM ARRAY%(2000): REM  Set up the array buffer
  1946.            .
  1947.            .
  1948.           REM  Do a FOPEN to open the file
  1949.           BUFFER%=VARPTR(ARRAY%(1)): REM  Use first element of array here
  1950.           BYTES%=4000: REM  Read in 4000-byte saved screen into the array
  1951.           CALL FREAD(HANDLE%,BUFFER%,BYTES%,BYTESREAD%,ERRCODE%)
  1952.           IF ERRCODE% THEN PRINT "Error reading file..."
  1953.           REM  Do a SCRREST to put the info on the screen
  1954.  
  1955.      Example:
  1956.           BYTES%=128          : REM  Read in 128 bytes/characters
  1957.       
  1958.           BUF$=SPACE$(BYTES%) : REM  Set up the string buffer
  1959.           V%=VARPTR(BUF$)
  1960.           BUFFER%=PEEK(V%+2)+PEEK(V%+3)*256
  1961.           CALL FREAD(HANDLE%,BUFFER%,BYTES%,BYTESREAD%,ERRCODE%)
  1962.           IF ERRCODE% THEN PRINT "Error reading file..."
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.  
  1991.      Name: FSETEND
  1992.  
  1993.      Type: Disk / DOS
  1994.  
  1995.      Description:
  1996.           For  use  with  files  opened with FOPEN / FCREATE.  This function
  1997.      sets  the  file pointer to the end of the file, so that any information
  1998.      written using FWRITE will be appended to the file.
  1999.  
  2000.      Related functions: FCLOSE, FCREATE, FOPEN, FREAD, FSETREC, FWRITE
  2001.  
  2002.      Example:
  2003.           CALL FSETEND(HANDLE%)
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.      Name: FSETREC
  2058.  
  2059.      Type: Disk / DOS
  2060.  
  2061.      Description:
  2062.           For  use  with  files  opened with FOPEN / FCREATE.  This function
  2063.      sets  the  file  pointer to a given record in the file, so that it will
  2064.      be the next record read or written.
  2065.  
  2066.      Related functions: FCLOSE, FCREATE, FOPEN, FREAD, FSETEND, FWRITE
  2067.  
  2068.      Example:
  2069.           RECSIZE%=128: REM  Number of bytes in a record in our file
  2070.           RECNO%=34: REM  Record number (starting from 1, as in BASIC)
  2071.           CALL FSETREC(HANDLE%,RECSIZE%,RECNO%)
  2072.  
  2073.  
  2074.  
  2075.  
  2076.      Name: FWRITE
  2077.  
  2078.      Type: Disk / DOS
  2079.  
  2080.      Description:
  2081.           Allows  you  to  write  to a file opened by FOPEN or FCREATE.  The
  2082.      parameters  are  the same as in FREAD (q.v.), except for BYTESWRITTEN%,
  2083.      which replaces BYTESREAD%.
  2084.  
  2085.      Related functions: FCLOSE, FCREATE, FOPEN, FREAD, FSETEND, FSETREC
  2086.  
  2087.      Example:
  2088.           REM  Do a SCRSAVE to save a screen into ARRAY%()
  2089.           BUFFER%=VARPTR(ARRAY%(1))
  2090.           BYTES%=4000: REM  4000 bytes = 2000 integer array elements
  2091.           CALL FWRITE(TEST.HANDLE%,BUFFER%,BYTES%,BYTESWRITTEN%,ERRCODE%)
  2092.           IF ERRCODE% THEN PRINT "Unable to write to file..."
  2093.           REM  See FREAD for an example of how to set up a string buffer
  2094.           REM  as the setup is different than when using an array buffer
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.      Name: GETATTRF
  2124.  
  2125.      Type: Disk / DOS
  2126.  
  2127.      Description:
  2128.           Returns  the  actual  attribute of a file matched using FINDFIRSTF
  2129.      or  FINDNEXTF.   See  the  end of this document for information on file
  2130.      attributes.
  2131.  
  2132.      Example:
  2133.           REM  use this AFTER calling FINDFIRSTF / FINDNEXTF to initialize
  2134.           REM  the appropriate file information!
  2135.           CALL GETATTRF(ATTR%)
  2136.  
  2137.  
  2138.  
  2139.  
  2140.      Name: GETCRT
  2141.  
  2142.      Type: Video / BIOS
  2143.  
  2144.      Description:
  2145.           Tells  you what kind of display is being used.  The returned value
  2146.      will be reset if it's monochrome, or set if color.
  2147.  
  2148.      Example:
  2149.           CALL GETCRT(COLORDISPLAY%)
  2150.           IF COLORDISPLAY% THEN PRINT"Color" ELSE PRINT"Monochrome"
  2151.  
  2152.  
  2153.  
  2154.  
  2155.      Name: GETEXTM
  2156.  
  2157.      Type: Miscellaneous / AT BIOS
  2158.  
  2159.      Description:
  2160.           Tells  you  how  much extended memory is available.  This function
  2161.      requires  the  AT  BIOS,  and  shouldn't  be  used  with PCs.  See also
  2162.      GETLIMM.
  2163.  
  2164.      Example:
  2165.           CALL GETEXTM(KBYTES%)
  2166.           PRINT KBYTES%;" kilobytes of extended memory"
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.      Name: GETKBD
  2190.  
  2191.      Type: Input / CLONE
  2192.  
  2193.      Description:
  2194.           Gives  the  status  of  the  keyboard  toggles.  The variable will
  2195.      be set if the toggle is on, and reset if it is off.  See also SETKBD.
  2196.  
  2197.      Example:
  2198.           CALL GETKBD(INSERT%,CAPSLOCK%,NUMLOCK%,SCROLLLOCK%)
  2199.           IF INSERT% THEN PRINT"Insert mode is on"
  2200.           IF CAPSLOCK% THEN PRINT"Caps Lock is on"
  2201.           IF NUMLOCK% THEN PRINT"The keypad is in numeric mode"
  2202.           IF SCROLLLOCK% THEN PRINT"Scroll Lock is on"
  2203.  
  2204.  
  2205.  
  2206.  
  2207.      Name: GETDATEF
  2208.  
  2209.      Type: Disk / DOS
  2210.  
  2211.      Description:
  2212.           Returns the date associated with the file matched using FINDFIRSTF
  2213.      or FINDNEXTF.
  2214.  
  2215.      Example:
  2216.           CALL GETDATEF(MONTH%,DAY%,YEAR%)
  2217.  
  2218.  
  2219.  
  2220.  
  2221.      Name: GETDOSV
  2222.  
  2223.      Type: Miscellaneous / DOS
  2224.  
  2225.      Description:
  2226.           Gets  MS-DOS  version.  The major version is returned in the first
  2227.      parameter,  the minor version in the second (e.g., MS-DOS v. 2.11 would
  2228.      return MAJ% = 2, MIN% = 11).
  2229.  
  2230.      Example:
  2231.           CALL GETDOSV(MAJ%,MIN%)
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.      Name: GETDRV
  2256.  
  2257.      Type: Disk / DOS
  2258.  
  2259.      Description:
  2260.           Returns  the  letter  of the default drive.  The drive string must
  2261.      be at least one character long.
  2262.  
  2263.      Example:
  2264.           DRV$="x:": CALL GETDRV(DRV$)
  2265.  
  2266.  
  2267.  
  2268.  
  2269.      Name: GETFATTR
  2270.  
  2271.      Type: Disk / DOS
  2272.  
  2273.      Description:
  2274.           Gets  the attribute of a file.  See the section on file attributes
  2275.      at the end of this manual.
  2276.  
  2277.      Example:
  2278.           FIL$=FIL$+CHR$(0)
  2279.           CALL GETFATTR(FIL$,ATTR%)
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.      Name: GETFDATE
  2322.  
  2323.      Type: Disk / DOS
  2324.  
  2325.      Description:
  2326.           GETFDATE  returns  the  file  creation date, that is, the date you
  2327.      see  on  a  file  when  you  get  a  DIRectory.   The file name must be
  2328.      terminated  with  a NUL character.  If there is an error, such as there
  2329.      being no such file, the month will be set to -1.
  2330.  
  2331.      Example:
  2332.           FIL$="TESTFILE.TXT"+CHR$(0)
  2333.           CALL GETFDATE(FIL$,MONTH%,DAY%,YEAR%)
  2334.  
  2335.  
  2336.  
  2337.  
  2338.      Name: GETFTIME
  2339.  
  2340.      Type: Disk / DOS
  2341.  
  2342.      Description:
  2343.           This  function complements GETFDATE, and returns the file creation
  2344.      time.   The  hour is in 24-hour (military) format, and will be returned
  2345.      as  -1  if  there  is no such file or a bad file name.  The seconds are
  2346.      rounded  to  the next lower even number, due to the DOS storage format.
  2347.      The file name must be terminated with a NUL character.
  2348.  
  2349.      Example:
  2350.           FIL$="ANYFILE.EXT"+CHR$(0)
  2351.           CALL GETFTIME(FIL$,HOUR%,MINUTE%,SECOND%)
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.      Name: GETKEY
  2388.  
  2389.      Type: Keyboard / BIOS
  2390.  
  2391.      Description:
  2392.           Waits  until  one  of  a  list of keys is pressed, and returns it.
  2393.      The  key  list  (any  length)  should be uppercase.  If the key list is
  2394.      null,  the  first  key pressed will be returned.  The key returned will
  2395.      be  capitalized.   The  variable  to return the key in must be at least
  2396.      one  character  long.   This  function is designed for returning one of
  2397.      a menu of choices, for example.
  2398.  
  2399.      Example:
  2400.           PRINT "Would you like to try again (Y/N)? ";
  2401.           GOODKEYS$="YN" : REM  Allow Y or N
  2402.             .
  2403.             .
  2404.           KY$="x": CALL GETKEY(GOODKEYS$,KY$)
  2405.  
  2406.  
  2407.  
  2408.  
  2409.      Name: GETLIMM
  2410.  
  2411.      Type: Miscellaneous / BIOS
  2412.  
  2413.      Description:
  2414.           Returns  the  status  of  expanded memory, in total pages and free
  2415.      pages  (where  a  page  is  16k bytes).  GETLIMM should only be used on
  2416.      systems with EMS or EEMS memory installed.  See also GETEXTM.
  2417.  
  2418.      Example:
  2419.           CALL GETLIMM(TOTPAGES%,FREEPAGES%)
  2420.           PRINT TOTPAGES%;"pages of expanded memory are installed."
  2421.           IF TOTPAGES%>0 THEN PRINT FREEPAGES%;"pages of that are free."
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.      Name: GETLINE
  2454.  
  2455.      Type: Video / ANY
  2456.  
  2457.      Description:
  2458.           Returns  a  selected  line  from  a screen saved via SCRSAVE, with
  2459.      the  trailing  spaces  removed.   The  line  string must be at least 80
  2460.      characters  long.   This  will  also  return a line from a screen saved
  2461.      with GETSCREEN, as long as full 80-column lines were saved.
  2462.  
  2463.      Example:
  2464.           OPTION BASE 1: DIM SCR%(2000)
  2465.           WHERE%=VARPTR(SCR%(1)): CALL SCRSAVE(WHERE%): CLS
  2466.           LINENR%=10: LIN$=SPACE$(80): WHERE%=VARPTR(SCR%(1))
  2467.           CALL GETLINE(WHERE%,LINENR%,LIN$,LLEN%)
  2468.           PRINT"Line 10 was:": PRINT LEFT$(LIN$,LLEN%)
  2469.  
  2470.  
  2471.  
  2472.  
  2473.      Name: GETNAMEF
  2474.  
  2475.      Type: Disk / DOS
  2476.  
  2477.      Description:
  2478.           Returns  the  filename  of  the  file  matched using FINDFIRSTF or
  2479.      FINDNEXTF.   The FIL$ string must be initialized to at least 12 charac-
  2480.      ters  in  length.  The actual length of FIL$ will be returned in FLEN%,
  2481.      which  will  be  -1  if  you  didn't initialize FIL$ long enough.  Note
  2482.      that the filename will not contain a drive or path spec.
  2483.  
  2484.      Example:
  2485.           FIL$=SPACE$(12)
  2486.           CALL GETNAMEF(FIL$,FLEN%)
  2487.           FIL$=LEFT$(FIL$,FLEN%)
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.      Name: GETSCREEN
  2520.  
  2521.      Type: Video / CLONE  (not with QuickBASIC 4.0 or BC)
  2522.  
  2523.      Description:
  2524.           Allows  you  to  save  any  part  of a text screen display (on any
  2525.      page,  active  or  inactive,  if  you  have  a color graphics adapter).
  2526.      You  need  to  specify  an  integer array where the information will be
  2527.      stored,  the  coordinates  of  the  upper  left corner and bottom right
  2528.      corner  of  the  part  of the screen to save, the display page to save,
  2529.      and the screen mode.
  2530.           The  screen  mode  should  be  zero for flicker-free screen saving
  2531.      if  you  have  a  low quality color graphics adapter and are saving the
  2532.      currently-active  display  page.   Otherwise, set it to 1 or -1 for the
  2533.      fastest save speed.
  2534.           You  specify  the  area  of  the screen to save as a rectangle, by
  2535.      giving  the  locations of the upper leftmost corner and lower rightmost
  2536.      corner  of  the  area  to save.  This can range from a single character
  2537.      to  the entire screen.  Make sure that the coordinates do not get mixed
  2538.      up, or you will get unpredictable results.
  2539.           To  figure  out  how  many array elements you need to save an area
  2540.      of the screen, use the following calculation:
  2541.      ELEMENTS%=(BOTTOMROW%-TOPROW%+1)*(RIGHTCOLUMN%-LEFTCOLUMN%+1)
  2542.      You  can  store  multiple  screen  areas in one array by specifying the
  2543.      proper  starting  element,  which  must be one after the previous saved
  2544.      area.   You'll  have  to  keep track of where each saved area is in the
  2545.      array yourself.
  2546.           If you have a monochrome adapter, or are not using unusual display
  2547.      pages, you should set the page specification to zero.
  2548.           Note  that  you don't have to restore the saved area of the screen
  2549.      (see  PUTSCREEN)  to  the same area it was taken from.  This allows you
  2550.      to move windows around, change the shape of windows, and other interes-
  2551.      ting tricks...
  2552.           See  also  PUTSCREEN,  to  restore a given area of the screen; and
  2553.      SCRSAVE, SCRREST, SCRSAVEP, SCRRESTP, SCRSAVEPD, and SCRRESTPD, earlier
  2554.      versions  of  similar  functions.  Note that if you save/restore a full
  2555.      80-column,  25-row  screen,  the  information in the save/restore array
  2556.      is    identical    whether    you're   using   GETSCREEN/PUTSCREEN   or
  2557.      SCRSAVExx/SCRRESTxx.   On  that  level,  the  routines  are  completely
  2558.      compatible.
  2559.  
  2560.      Example:
  2561.      CALL GETSCREEN(SCRN%(0),TOPROW%,LFCOL%,BOTROW%,RTCOL%,PAGE%,SCRNMODE%)
  2562.        REM  SCRN%(0) is the location in the array to save the area to.
  2563.        REM  TOPROW%,LFCOL% and BOTROW%,RTCOL% are the corners of the area.
  2564.        REM  PAGE% is the display page number (0-3 if Color, 0 if Mono).
  2565.        REM  SCRNMODE% is screen access mode: 0, snowless; 1 / -1, fast.
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.  
  2585.      Name: GETSIZEF
  2586.  
  2587.      Type: Disk / DOS
  2588.  
  2589.      Description:
  2590.           Returns  the size of the file matched via FINDFIRSTF or FINDNEXTF.
  2591.      Since  the  file  size  may  be  outside  integer bounds, there is some
  2592.      additional code you will have to add which uses double-precision values
  2593.      (see  the example).  You can modify the example to use single-precision
  2594.      instead,  but  really large file sizes will then lapse into exponential
  2595.      notation.
  2596.  
  2597.      Example:
  2598.           CALL GETSIZEF(SIZELOW%,SIZEHIGH%)
  2599.           SIZELOW#=CDBL(SIZELOW%)
  2600.           IF SIZELOW%<0 THEN SIZELOW#=SIZELOW#+65536#
  2601.           FILESIZE#=SIZELOW#+CDBL(SIZEHIGH%)*65536#
  2602.  
  2603.  
  2604.  
  2605.  
  2606.      Name: GETSUB
  2607.  
  2608.      Type: Disk / DOS
  2609.  
  2610.      Description:
  2611.           Gets  the  default  subdirectory.   The  subdirectory  string must
  2612.      be  64  characters  long,  and it is recommended that you set it to NUL
  2613.      characters.   Note  that  the  returned  string  will NOT be started by
  2614.      a backslash "\" character-- you should add one if appropriate.
  2615.  
  2616.      Example:
  2617.           SUB$=STRING$(64,0)
  2618.           CALL GETSUB(SUB$,SLEN%)
  2619.           SUB$="\"+LEFT$(SUB$,SLEN%)
  2620.  
  2621.  
  2622.  
  2623.  
  2624.      Name: GETTIMEF
  2625.  
  2626.      Type: Disk / DOS
  2627.  
  2628.      Description:
  2629.           Returns  the  time  associated with the file matched by FINDFIRSTF
  2630.      or FINDNEXTF.  The hour is returned in military (24-hour) format.
  2631.  
  2632.      Example:
  2633.           CALL GETTIMEF(HOUR%,MINUTE%,SECOND%)
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.  
  2649.  
  2650.  
  2651.      Name: INSCHR
  2652.  
  2653.      Type: Video / CLONE
  2654.  
  2655.      Description:
  2656.           Inserts  a  space at the specified screen location.  The character
  2657.      previously  at  that  position  and  all  characters to the right of it
  2658.      on  the  same  screen  line  will  be shifted right one space.  Subject
  2659.      to the same limitations as DELCHR (q.v.).
  2660.  
  2661.      Example:
  2662.           COL%=POS(0): ROW%=CSRLIN
  2663.           CALL INSCHR(ROW%,COL%): PRINT"*";
  2664.  
  2665.  
  2666.  
  2667.  
  2668.      Name: INT2DATE
  2669.  
  2670.      Type: Miscellaneous / ANY
  2671.  
  2672.      Description:
  2673.           Decompresses  a  date  squeezed  using  DATE2INT (q.v.).  The year
  2674.      will be a four-digit value (1900-2026).
  2675.  
  2676.      Example:
  2677.           CALL INT2DATE(MONTH%,DAY%,YEAR%,SQZDATE%)
  2678.  
  2679.  
  2680.  
  2681.  
  2682.      Name: INT2TIME
  2683.  
  2684.      Type: Miscellaneous / ANY
  2685.  
  2686.      Description:
  2687.           Decompresses  a  time squeezed using TIME2INT (q.v.).  The seconds
  2688.      will be an even value (rounded down) due to the storage format.
  2689.  
  2690.      Example:
  2691.           CALL INT2TIME(HOUR%,MIN%,SEC%,SQZTIME%)
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.  
  2715.  
  2716.  
  2717.      Name: KEYPRESS
  2718.  
  2719.      Type: Keyboard / BIOS
  2720.  
  2721.      Description:
  2722.           Tells  you  whether  a  key is waiting in the keyboard buffer (for
  2723.      use  with  INKEY$  routines,  etc).   KYHIT is set if a key is waiting,
  2724.      cleared otherwise.
  2725.  
  2726.      Example:
  2727.           100 CALL KEYPRESS(KYHIT%)
  2728.               IF KYHIT% THEN KY$=INKEY$ ELSE 100
  2729.  
  2730.  
  2731.  
  2732.  
  2733.      Name: LOCASE
  2734.  
  2735.      Type: String / ANY
  2736.  
  2737.      Description:
  2738.           Converts a string to all lowercase characters.
  2739.  
  2740.      Example:
  2741.           MSG$="THis IS a test OF tHe lowercase CONVERTER!"
  2742.             .
  2743.             .
  2744.           CALL LOCASE(MSG$)
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.      Name: LROTATE
  2784.  
  2785.      Type: String / ANY
  2786.  
  2787.      Description:
  2788.           Rotates  the  characters  in a string left.  That is, the leftmost
  2789.      character  is  removed,  and  tacked  onto the end of the string.  This
  2790.      is  useful  for  rotating  queues and for character-graphics animation.
  2791.      If the string is of length one or less, it is returned unchanged.
  2792.  
  2793.      Example:
  2794.           ST$="12345"
  2795.           CALL LROTATE(ST$)
  2796.           REM  ST$ will end up being "23451"
  2797.  
  2798.  
  2799.  
  2800.  
  2801.      Name: MAKESUB
  2802.  
  2803.      Type: Disk / DOS
  2804.  
  2805.      Description:
  2806.           Makes  a  subdirectory.   Use  a  NUL-terminated string to specify
  2807.      the  subdirectory.   An  error  code  will  be returned if there was an
  2808.      error.
  2809.  
  2810.      Example:
  2811.           TMP$=SUB$+CHR$(0)
  2812.           CALL MAKESUB(TMP$,ERRCODE%)
  2813.           IF ERRCODE% THEN couldn't make subdir ELSE subdir created
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.  
  2849.      Name: MAKEWINDOW
  2850.  
  2851.      Type: Video / CLONE
  2852.  
  2853.      Description:
  2854.           Creates  a  pop-up  window  on the screen.  You specify the window
  2855.      by  giving  the  upper left corner and lower right corner of the inside
  2856.      of  the  window.   The  frame  is  drawn  -outside-  the  window you've
  2857.      specified, so be sure to allow room for the frame!  For normal windows,
  2858.      the  frame  takes up only one column or row on each side.  For shadowed
  2859.      windows,  the  frame  will  instead  take  up three columns on the left
  2860.      and three rows on the bottom.
  2861.  
  2862.           There are four types of window:
  2863.      0, Normal:   the window pops onto the screen.
  2864.      1, Growing:  the window "grows" from a spot to a full-sized window.
  2865.      2,  Shadowed:  the  window  is shadowed on the left and bottom for a 3D
  2866.         effect.
  2867.      3, Growing/Shadowed: the window is shadowed and grows.
  2868.  
  2869.           You may also choose five types of frames:
  2870.      0, None: composed of spaces.
  2871.      1, Single: composed of a single line.
  2872.      2, Double: composed of a double line.
  2873.      3,  Double/Single:  made with a double vertical and a single horizontal
  2874.         line.
  2875.      4,  Single/Double:  made with a single vertical and a double horizontal
  2876.         line.
  2877.  
  2878.           You  must select fore and background colors.  A label is optional.
  2879.      If  you  give  one, it is bracketed within the top of the frame, on the
  2880.      left side.  The screen page is selectable on color monitors.
  2881.  
  2882.      Example:
  2883.           LCOL%=5:  TROW%=5:  REM  top left corner
  2884.           RCOL%=79: BROW%=20: REM  bottom right corner
  2885.           LABEL$="Test Window"
  2886.           FORE%=7: BACK%=0:   REM  color/attributes
  2887.           PAGE%=0:           REM  screen display page
  2888.           FRAME%=1:          REM  single-line frame
  2889.           TYPE%=3:           REM  growing, shadowed window
  2890.           CALL MAKEWINDOW(LCOL%,TROW%,RCOL%,BROW%,LABEL$,
  2891.                           FRAME%,TYPE%,FORE%,BACK%,PAGE%)
  2892.           REM  the above line shouldn't be divided in your program!
  2893.           REM  it's separated like that to accommodate my word processor.
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.      Name: MDELCHR
  2916.  
  2917.      Type: Video / BIOS
  2918.  
  2919.      Description:
  2920.           Deletes  the  character  at the current cursor position.  It obeys
  2921.      the  window  defined  by  MWINDOW.   It's  more compatible than DELCHR,
  2922.      but much slower.
  2923.             Note  that  this  routine  can  be  used to scroll a window left
  2924.      by  doing an MDELCHR at the first location of each line to be scrolled.
  2925.      To scroll right, do the same using MINSCHR instead.
  2926.  
  2927.      Example:
  2928.           CALL MDELCHR
  2929.  
  2930.  
  2931.  
  2932.  
  2933.      Name: MINSCHR
  2934.  
  2935.      Type: Video / BIOS
  2936.  
  2937.      Description:
  2938.           Inserts a space at the current cursor position, obeying the window
  2939.      defined by MWINDOW.  See notes at MDELCHR.
  2940.  
  2941.      Example:
  2942.           CALL MINSCHR
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.      Name: MMBUTTON
  2982.  
  2983.      Type: Input / BIOS
  2984.  
  2985.      Description:
  2986.           Returns  which  mouse  buttons are currently being held down.  See
  2987.      also MMCLICK.
  2988.  
  2989.      Example:
  2990.           CALL MMBUTTON(LFT%,RGT%)
  2991.           IF LFT% THEN PRINT"The left button is being pressed."
  2992.           IF RGT% THEN PRINT"The right button is being pressed."
  2993.  
  2994.  
  2995.  
  2996.  
  2997.      Name: MMCHECK
  2998.  
  2999.      Type: Input / BIOS
  3000.  
  3001.      Description:
  3002.           Returns  whether  a  mouse  is  installed, and how many buttons it
  3003.      has if it is installed.
  3004.  
  3005.      Example:
  3006.           CALL MMCHECK(MOUSE%)
  3007.           IF MOUSE% THEN PRINT"A mouse with ";MOUSE%;" buttons is present."
  3008.  
  3009.  
  3010.  
  3011.  
  3012.      Name: MMCLICK
  3013.  
  3014.      Type: Input / BIOS
  3015.  
  3016.      Description:
  3017.           Returns  which  mouse  buttons  have  been  clicked since you last
  3018.      used this function.  See also MMBUTTON.
  3019.  
  3020.      Example:
  3021.           CALL MMCLICK(LFT%,RGT%)
  3022.           IF LFT% THEN PRINT"The left button was pressed."
  3023.           IF RGT% THEN PRINT"The right button was pressed."
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.      Name: MMCURSORON
  3048.  
  3049.      Type: Input / BIOS
  3050.  
  3051.      Description:
  3052.           Makes  the  cursor  associated  with  the  mouse visible.  This is
  3053.      normally  a  blinking  block,  and  shows  where the mouse is currently
  3054.      pointing.  See also MMCURSOROFF.
  3055.  
  3056.      Example:
  3057.           CALL MMCURSORON
  3058.  
  3059.  
  3060.  
  3061.      Name: MMCURSOROFF
  3062.  
  3063.      Type: Input / BIOS
  3064.  
  3065.      Description:
  3066.           Makes  the  cursor  associated with the mouse invisible.  See also
  3067.      MMCURSORON.
  3068.  
  3069.      Example:
  3070.           CALL MMCURSOROFF
  3071.  
  3072.  
  3073.  
  3074.  
  3075.      Name: MMGETLOC
  3076.  
  3077.      Type: Input / BIOS
  3078.  
  3079.      Description:
  3080.           Gets  the  current location of the mouse cursor.  This is returned
  3081.      as  a  value  from  0-639 for columns, and 0-199 for rows.  You need to
  3082.      adjust  this  for  the  current screen format.  If you're in text mode,
  3083.      divide  the  columns  by eight and the rows by eight.  If you're in low
  3084.      res  graphics  mode,  divide the columns by two.  If you're in high res
  3085.      graphics, the numbers are fine.
  3086.  
  3087.      Example:
  3088.           CALL MMGETLOC(COL%,ROW%)
  3089.           LOCATE ROW%,COL%: PRINT "!";
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.      Name: MMSETLOC
  3114.  
  3115.      Type: Input / BIOS
  3116.  
  3117.      Description:
  3118.           Sets  the current value of the mouse cursor.  Uses the same format
  3119.      as MMGETLOC (q.v.).
  3120.  
  3121.      Example:
  3122.           COL%=40*8-8: ROW%=24*8-8: REM  middle of the text-mode screen
  3123.           CALL MMSETLOC(COL%,ROW%)
  3124.  
  3125.  
  3126.  
  3127.  
  3128.      Name: MMSETRANGE
  3129.  
  3130.      Type: Input / BIOS
  3131.  
  3132.      Description:
  3133.           Sets  the  range  of  locations  where the mouse cursor is allowed
  3134.      to  be.   This  is  done  by specifying the upper left corner and lower
  3135.      right  corner  of  the  edges  of  the mouse input field.  Use the same
  3136.      format as MMGETLOC (q.v.).
  3137.  
  3138.      Example:
  3139.           LFTCOL%=20*8-8: TOPROW%=1*8-8
  3140.           RGTCOL%=60*8-8: BOTROW%=10*8-8
  3141.           CALL MMSETRANGE(LFTCOL%,TOPROW%,RGTCOL%,BOTROW%)
  3142.           REM  sets up a text-mode input field
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.      Name: MLOAD
  3180.  
  3181.      Type: Disk / DOS
  3182.  
  3183.      Description:
  3184.           Works  the  same  way  as  the  BLOAD statement does.  This is for
  3185.      use  with older compilers, which don't have the BLOAD statement.  MLOAD
  3186.      restores the information to the same place it was when BSAVEd.
  3187.  
  3188.      Example:
  3189.           FIL$="SCRNSAVE.BIN"+CHR$(0)
  3190.           CALL MLOAD(FIL$)
  3191.  
  3192.  
  3193.  
  3194.  
  3195.      Name: MONTH
  3196.  
  3197.      Type: Miscellaneous / ANY
  3198.  
  3199.      Description:
  3200.           Given  the  number  of  a  month  (1-12), this routine returns the
  3201.      name  of  the  month  (January  -  December).  You must supply a string
  3202.      of at least nine spaces in length to hold the month.
  3203.  
  3204.      Example:
  3205.           MONTH$=SPACE$(9)
  3206.           CALL MONTH(MONTH$,MLENGTH%,MONTHNUMBER%)
  3207.           MONTH$=LEFT$(MONTH$,MLENGTH%)
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244.  
  3245.      Name: MPRINTC
  3246.  
  3247.      Type: Video / BIOS
  3248.  
  3249.      Description:
  3250.           Using  this  function,  you  can  access  device  drivers  such as
  3251.      ANSI.SYS.   This  is  a video output function which goes through MS-DOS
  3252.      function   calls.   It  prints  a  single  character  to  the  display.
  3253.      MPRINTC allows use of ANSI.SYS and similar video drivers, and windowing
  3254.      via  MWINDOW,  but is slower and takes more memory that the usual PRINT
  3255.      statement.
  3256.  
  3257.      Example:
  3258.           CALL MPRINTC(CH$,COL%,ROW%): LOCATE ROW%,COL%
  3259.  
  3260.  
  3261.  
  3262.  
  3263.      Name: MPRINT
  3264.  
  3265.      Type: Video / BIOS
  3266.  
  3267.      Description:
  3268.           Same  as  MPRINTC  (q.v.),  only  it  allows you to send an entire
  3269.      string out to the display, rather than just a single character.
  3270.  
  3271.      Example:
  3272.           CALL MPRINT(ST$,COL%,ROW%): LOCATE ROW%,COL%
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.      Name: MULTIAND
  3312.  
  3313.      Type: String / ANY
  3314.  
  3315.      Description:
  3316.           This is a flexible function with many possible uses.  Every charac-
  3317.      ter  in  a  given  string  is ANDed with a value you supply.  One thing
  3318.      this  could  be  used for is translating Wordstar files to ASCII files,
  3319.      by  using  a bit mask (the value that will be ANDed with the character)
  3320.      of  &H7F,  which strips off the high bit of each character.  The string
  3321.      may  be  any length; the bit mask is an integer, with only the low byte
  3322.      in use (value of 0-255).
  3323.  
  3324.      Example:
  3325.           ST$ = ""
  3326.           FOR X%=65 TO 70: ST$=CHR$(X%)+CHR$(X%+128): NEXT
  3327.           PRINT ST$
  3328.           BITMASK%=&H7F
  3329.           CALL MULTIAND(ST$,BITMASK%)
  3330.           PRINT ST$
  3331.  
  3332.  
  3333.  
  3334.  
  3335.      Name: MULTIOR
  3336.  
  3337.      Type: String / ANY
  3338.  
  3339.      Description:
  3340.           Does  the  exact  opposite  of MULTIAND-- instead of stripping off
  3341.      bits,  it  turns  on  bits.   It ORs instead of ANDs.  One possible use
  3342.      for  this would be to encode a text string by ORing with 128, and later
  3343.      decoding  by  ANDing with 128.  This would allow you to save the string
  3344.      to  disk  using  text files, even if the string included control codes,
  3345.      although  that  won't  work right if the string has graphics characters
  3346.      (using  ExtASCII codes, which are codes from 128-255) in it.  The para-
  3347.      meters are the same as for MULTIAND.
  3348.  
  3349.      Example:
  3350.           ST$ = "ABCDE": PRINT ST$
  3351.           SETBITS%=&H80
  3352.           CALL MULTIOR(ST$,SETBITS%)
  3353.           PRINT ST$
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.      Name: MULTIXOR
  3378.  
  3379.      Type: String / ANY
  3380.  
  3381.      Description:
  3382.           An  exclusive-or  operation  for strings.  Bits in the string will
  3383.      be  set  only  if they are set in the string byte or mask byte, but not
  3384.      in  both  of them.  Note that this can be used as a "MULTINOT" function
  3385.      by  using  a  mask  of  &HFF or 255.  In this case, all bits are set in
  3386.      the  mask, so the result of the XOR will be the same as a NOT operation
  3387.      on  the  string.   Note  that XORing a string with the same value twice
  3388.      will  return  the  original  string-- it can thus be used to encode and
  3389.      decode strings.
  3390.  
  3391.      Example:
  3392.           CALL MULTIXOR(ST$,MASK%)
  3393.  
  3394.  
  3395.  
  3396.  
  3397.      Name: MWINDOW
  3398.  
  3399.      Type: Video / BIOS
  3400.  
  3401.      Description:
  3402.           Sets  up  a  window  for the MPRINT and MPRINTC routines.  Windows
  3403.      are  defined  by  their  upper left corner and lower right corner.  The
  3404.      default  window  is  thus (1,1,80,24), which leaves out the bottom line
  3405.      (BASIC's  status  line).   To  use  the  full screen, call this routine
  3406.      with  values  (1,1,80,25).   Note  that the cursor should be positioned
  3407.      inside  the window before using MPRINT/MPRINTC.  Note also that windows
  3408.      should be defined to contain at least two rows.
  3409.  
  3410.      Example:
  3411.           LFCOL%=20: TOPROW%=5: RTCOL%=60: BOTROW%=15
  3412.           CALL MWINDOW(LFCOL%,TOPROW%,RTCOL%,BOTROW%)
  3413.           LOCATE TOPROW%,LFCOL%
  3414.           REM  sets up a window (of 40 cols x 10 rows)
  3415.           REM  in the middle of the screen.
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  
  3440.  
  3441.  
  3442.  
  3443.      Name: PRINTSCREEN
  3444.  
  3445.      Type: Miscellaneous / BIOS
  3446.  
  3447.      Description:
  3448.           This  sends  an  image  of  the  current screen display out to the
  3449.      first  printer  device.   It  works  exactly in the same way as doing a
  3450.      Shift-PrtSc  from  the  keyboard,  so  it  can display graphics as well
  3451.      as text if you have the DOS GRAPHICS program installed.
  3452.  
  3453.  
  3454.  
  3455.  
  3456.      Name: PUTSCREEN
  3457.  
  3458.      Type: Video / CLONE   (not with QuickBASIC 4.0 or BC.EXE)
  3459.  
  3460.      Description:
  3461.           This  restores  an  area  of  the  screen that was saved using the
  3462.      GETSCREEN  function  (q.v.).   You need not restore an area to the same
  3463.      screen coordinates or to the same display page.
  3464.           It  is  possible  to  change  the shape of an area by changing the
  3465.      coordinates  specified.   For  instance,  suppose  you  had saved a six
  3466.      character,  one  line  message,  "FOOBAR",  at coordinates (1,1)-(1,6).
  3467.      You  could  restore it as a three char by two line message, "FOO" "BAR"
  3468.      by specifying the coordinates (1,1)-(2,3).  Note that these coordinates
  3469.      are  in Microsoft's mixed up form of (ROW,COLUMN), not the normal alge-
  3470.      braic format.
  3471.           It  is  also  possible to restore only part of the screen that was
  3472.      saved.   For  instance,  suppose  you had saved the entire screen in an
  3473.      array SCRN starting at element 0, and only wanted to restore the bottom
  3474.      half  of  the  screen.  Using the calculation for screen elements given
  3475.      in  GETSCREEN,  you  would  find that 2000 elements were needed for the
  3476.      whole  screen, or only 1000 elements for the bottom half of the screen.
  3477.      That  means  that  in  the  array,  elements 0-999 hold the top half of
  3478.      the  screen,  and  1000-1999  hold  the bottom half (assuming a default
  3479.      OPTION  BASE=0).   So,  you  would  tell  PUTSCREEN to start with array
  3480.      element  SCRN%(1000),  and  give it the starting and ending coordinates
  3481.      of the corners of the lower half of the screen.
  3482.           Parameters specifications are the same as they are for GETSCREEN.
  3483.  
  3484.      Example:
  3485.      CALL PUTSCREEN(SCRN%(0),TOPROW%,LFCOL%,BOTROW%,RTCOL%,PAGE%,SCRNMODE%)
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.  
  3506.  
  3507.  
  3508.  
  3509.      Name: QPRINT
  3510.  
  3511.      Type: Video / CLONE
  3512.  
  3513.      Description:
  3514.           This  function  bypasses  the  usual  video routines, and prints a
  3515.      string directly on the screen, at a -much- higher speed than the normal
  3516.      PRINT  statement  does.   It also contains a built-in LOCATE statement,
  3517.      and  doesn't  affect the cursor position.  Note that control characters
  3518.      will  show  up  as graphics characters instead of having their original
  3519.      functions,  and  the  color/attributes  used  will  be the ones already
  3520.      on  the  screen.   Display  page zero is used with color adapters.  See
  3521.      also XQPRINT.
  3522.  
  3523.      Example:
  3524.           ST$="This is a test of fast screen printing"
  3525.           ROW%=10: COL%=20
  3526.           CALL QPRINT(ST$,ROW%,COL%)
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.      Name: READBITF
  3576.  
  3577.      Type: Miscellaneous / ANY
  3578.  
  3579.      Description:
  3580.           Reads  a  word  from  an  array  of arbitrary bit length, given an
  3581.      index.   The  words  in  the  array  may  be made of one to eight bits.
  3582.      Indices  begin  at  zero  and are limited by integer range.  That is up
  3583.      to  &HFFFF,  subject  to  memory constraints-- the index is taken to be
  3584.      an  unsigned integer value.  This function allows very memory-efficient
  3585.      storage  of  arrays  of  numbers,  provided that the numbers are within
  3586.      a  restricted  range.   The  simulated  array  is  held within a normal
  3587.      integer  array,  which  must  be  dimensioned  large enough to hold all
  3588.      of  the arbitrary-length words (will depend on bits per word and number
  3589.      of words desired).
  3590.  
  3591.      Example:
  3592.           OPTION BASE 0: DIM INTARRAY%(50): BITFSIZE%=8
  3593.             .
  3594.             .
  3595.           ARRAYLOC%=VARPTR(INTARRAY%(0))
  3596.           CALL READBITF(ARRAYLOC%,NDX%,BITFSIZE%,VALUE%)
  3597.           REM  Returns a value from the array location indexed by NDX%,
  3598.           REM  where the array is composed of bytes (8-bit words).
  3599.           REM  See the disk file BITFTEST.BAS in the source files
  3600.           REM  for a working example program.
  3601.  
  3602.  
  3603.  
  3604.  
  3605.      Name: RECOLOR
  3606.  
  3607.      Type: Video / CLONE
  3608.  
  3609.      Description:
  3610.           Takes everything on the screen that's of a given color and changes
  3611.      its  color to whatever you like.  This can be used for special effects,
  3612.      or  just to change the screen color without having to clear the screen.
  3613.      This will work only in text mode.  The color attributes must be defined
  3614.      from the foreground and background colors using the CALCATTR routine.
  3615.  
  3616.      Example:
  3617.           CALL CALCATTR(FOREGND%,BACKGND%,OLDCOLR%)
  3618.           CALL CALCATTR(NEWFORE%,NEWBACK%,NEWCOLR%)
  3619.           CALL RECOLOR(OLDCOLR%,NEWCOLR%)
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.      Name: RESETPOINT
  3642.  
  3643.      Type: Video / BIOS
  3644.  
  3645.      Description:
  3646.           Resets a point on a text screen.  This is the opposite of SETPOINT
  3647.      (see).
  3648.  
  3649.      Example:
  3650.           ROW%=0
  3651.           FOR COLUMN%=0 to 79
  3652.              CALL RESETPOINT(COLUMN%,ROW%)
  3653.           NEXT COLUMN%
  3654.           REM  this clears a line from the top of the screen
  3655.           REM  (undoes the line from the SETPOINT example)
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.      Name: REVERSE
  3708.  
  3709.      Type: String / ANY
  3710.  
  3711.      Description:
  3712.           Reverses  the  order  of  characters  in  a  string.   This can be
  3713.      combined with the XLATE function and a judiciously-designed translation
  3714.      table  to provide mirror images of strings for character-graphics-based
  3715.      displays.   It  can also be used with INSTR to provide a function which
  3716.      returns the last occurrence of a given substring within a string.
  3717.  
  3718.      Example:
  3719.           MSG$="This is a test"
  3720.           CALL REVERSE(MSG$)
  3721.           PRINT MSG$
  3722.  
  3723.  
  3724.  
  3725.  
  3726.      Name: RROTATE
  3727.  
  3728.      Type: String / ANY
  3729.  
  3730.      Description:
  3731.           Rotates  the  characters  in  a string right.  This is the same as
  3732.      LROTATE, only in reverse.  See LROTATE for further details.
  3733.  
  3734.      Example:
  3735.           ST$="12345"
  3736.           CALL RROTATE(ST$)
  3737.           REM  ST$ will end up being "51234"
  3738.  
  3739.  
  3740.  
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.      Name: SCROLL
  3774.  
  3775.      Type: Video / BIOS
  3776.  
  3777.      Description:
  3778.           Scrolls  any  selected  portion of the screen as many times as you
  3779.      like
  3780.      (or  use  0 to clear that part of the screen entirely).  There are five
  3781.      parameters  to  this  function: coordinates (LFCOL,TOPROW) of the upper
  3782.      left  corner  of  the  area  to be scrolled, coordinates (RTCOL,BOTROW)
  3783.      of  the  lower  right corner of the area to be scrolled, and the number
  3784.      of  times  to scroll the area.  This routine may be used to create win-
  3785.      dows.   Note  that  RTCOL  must  be at least one greater than LFCOL (no
  3786.      single-line  scrolling,  obviously).   Note  also  that  you should not
  3787.      try  to  scroll  more  times  than  there  are  lines in the area to be
  3788.      scrolled  (use  0  instead).  Parameters are not checked, so be careful
  3789.      not to use illegal screen coordinates.
  3790.  
  3791.      Example:
  3792.           CALL SCROLL(LFCOL%,TOPROW%,RTCOL%,BOTROW%,NUMLINES%)
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.      Name: SCRREST
  3840.  
  3841.      Type: Video / CLONE
  3842.  
  3843.      Description:
  3844.           Restores  the  screen  display  from an image put into an array by
  3845.      SCRSAVE.  Same requirements and limitations of SCRSAVE.
  3846.  
  3847.      Example:
  3848.           WHERE%=VARPTR(SCR%(1))
  3849.           CALL SCRREST(WHERE%)
  3850.           LOCATE OLDROW%,OLDCOL%
  3851.  
  3852.  
  3853.  
  3854.  
  3855.      Name: SCRSAVE
  3856.  
  3857.      Type: Video / CLONE
  3858.  
  3859.      Description:
  3860.           Stores  the  current  screen  display  (page  0 only) in an array.
  3861.      Text  modes  only.   Requires  an  array  of 4000 bytes, and an integer
  3862.      which  points  to  the  location  of the array.  The cursor position is
  3863.      not saved.
  3864.  
  3865.      Example:
  3866.           OPTION BASE 1: DIM SCR%(2000)
  3867.            .
  3868.            .
  3869.           WHERE%=VARPTR(SCR%(1))
  3870.           CALL SCRSAVE(WHERE%)
  3871.           OLDCOL%=POS(0): OLDROW%=CSRLIN
  3872.           REM  Dim of 2000 w/ option base 1 gives us 2000 integers,
  3873.           REM  which gives us 4000 bytes of storage space.
  3874.           REM  Note: you can store more than one screen in an array by
  3875.           REM  dimensioning it large enough.  Use WHERE%=VARPTR(SCR%(2001))
  3876.           REM  to locate the second screen, and so forth.
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.  
  3905.      Name: SCRRESTP, SCRRESTPD, SCRSAVEP, SCRSAVEPD
  3906.  
  3907.      Type: Video / CLONE
  3908.  
  3909.      Description:
  3910.           These  functions  are  variations  of SCRREST and SCRSAVE.  All of
  3911.      them  allow  specification  of a page number, for color monitors.  They
  3912.      will  save  or restore text to a given page.  When used with monochrome
  3913.      monitors,  the  page  specification  should  always be zero.  SCRRESTPD
  3914.      and  SCRSAVEPD  write  directly to the screen at high speed.  This will
  3915.      cause  "snow"  if  you  have  an  old  or poorly designed color display
  3916.      adapter  and  are  writing  to  the  active  screen  page.  Under those
  3917.      conditions, you should use SCRRESTP/SCRSAVEP or SCRREST/SCRSAVE.
  3918.  
  3919.      Example:
  3920.           WHERE%=VARPTR(SCR%(1)): SCRNPAGE%=0
  3921.           CALL SCRRESTP(WHERE%,SCRNPAGE%): LOCATE OLDROW%,OLDCOL%
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.      Name: SETCOMM
  3972.  
  3973.      Type: Miscellaneous / CLONE
  3974.  
  3975.      Description:
  3976.           Sets   communications   parameters  on  an  opened  communications
  3977.      device.  This allows you to set the baud rate higher than BASIC normal-
  3978.      ly  allows,  and  to change the comm parameters without having to close
  3979.      the comm device.
  3980.           Why  is  it  bad  to  have to close the comm device?  Because that
  3981.      will  make  the  DTR  signal drop, which will cause many modems to drop
  3982.      the  carrier and lose your connection.  In fact, for Hayes-type modems,
  3983.      that's  a  much  more reliable way to end communications than using the
  3984.      ATH "hang up modem" command.
  3985.           If  you  try  to  set  a  comm port which does not exist, the port
  3986.      number  will  be set to zero after the call.  If you give illegal para-
  3987.      meters  elsewhere,  the port will be set to a default of 300 baud, Even
  3988.      parity,  Seven-bit  words,  and  One  stop  bit (any of the parms which
  3989.      were legal will be used).
  3990.  
  3991.      Example:
  3992.           OPEN"R",1,"COM1:300,E,7,1,RS,CS,DS"
  3993.           COMMPORT%=1: BPS%=6: PARITY%=0: WORDLENGTH%=8
  3994.           STOPBITS%=1
  3995.           CALL SETCOMM(COMMPORT%,BPS%,PARITY%,WORDLENGTH%,STOPBITS%)
  3996.           REM  sets the port to 19200 baud, No parity, 8 bit words
  3997.           REM  and 1 stop bit.
  3998.  
  3999.      Settings:
  4000.           COMMPORT% may be 1 - 2, and will be returned as 0 if the specified
  4001.      port doesn't exist.
  4002.           BPS%  ("baud  rate")  is  specified  by  a number from 0 - 7.  Use
  4003.      0  for  300  bps,  1 for 600, 2 for 1200, 3 for 2400, 4 for 4800, 5 for
  4004.      9600,  6  for  19200,  and  7  for 38400 bps.  Whether you can actually
  4005.      get speeds over 9600 will depend on the quality of your comm port.
  4006.           PARITY% is a number 0-2.  Use 0 for None, 1 for Odd, 2 for Even.
  4007.           WORDLENGTH% may be 7 or 8.
  4008.           STOPBITS% may be 1 or 2.
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.      Name: SETDRV
  4038.  
  4039.      Type: Disk / DOS
  4040.  
  4041.      Description:
  4042.           Sets  the  default  drive.   The drive string must be at least one
  4043.      character long, and start with a letter specifying a disk drive.
  4044.  
  4045.      Example:
  4046.           DRV$="B:"
  4047.             .
  4048.             .
  4049.           CALL SETDRV(DRV$)
  4050.  
  4051.  
  4052.  
  4053.  
  4054.      Name: SETFATTR
  4055.  
  4056.      Type: Disk / DOS
  4057.  
  4058.      Description:
  4059.           Sets  the attribute of a file.  See the section on file attributes
  4060.      at the end of this manual.
  4061.  
  4062.      Example:
  4063.           FIL$=FIL$+CHR$(0)
  4064.           CALL SETFATTR(FIL$,ATTR%)
  4065.  
  4066.  
  4067.  
  4068.  
  4069.      Name: SETFTD
  4070.  
  4071.      Type: Disk / DOS
  4072.  
  4073.      Description:
  4074.           Sets  file  time/date stamp.  The filename must be terminated with
  4075.      a  NUL  character.   The  year  may be either a four digit or two digit
  4076.      number  (e.g.,  either  1986  or  just 86).  DOS will round the seconds
  4077.      value  off  to  the next lower even number.  If there is a problem with
  4078.      the  filename,  the  month  will be returned as -1.  Note that midnight
  4079.      is 24:00, not 00:00 (which tells DOS not to display the file's time).
  4080.  
  4081.      Example:
  4082.           FIL$=FIL$+CHR$(0)
  4083.           CALL SETFTD(FIL$,MONTH%,DAY%,YEAR%,HOUR%,MINUTE%,SECOND%)
  4084.           IF MONTH%=-1 THEN PRINT "No such file"
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.      Name: SETMATI
  4104.  
  4105.      Type: Miscellaneous / ANY
  4106.  
  4107.      Description:
  4108.           Sets  the  first  SIZ%  elements  of  an  integer array to a given
  4109.      (scalar)  value,  INITVAL%.   It will work on multi-dimensional arrays,
  4110.      in  which  case  the leftmost dimension increments first (unless you've
  4111.      set  the  compiler  option  telling  it to do otherwise).  See examples
  4112.      for clarification.
  4113.  
  4114.      Example:
  4115.           OPTION BASE 0: DIM BANANA%(9)
  4116.           SIZ%=10: INITVAL%=-3: ARLOC%=VARPTR(BANANA%(0))
  4117.           CALL SETMATI(ARLOC%,SIZ%,INITVAL%)
  4118.           REM  we have just initialized all 10 elements of the array to
  4119.           REM  the value -3.
  4120.  
  4121.      Example:
  4122.           OPTION BASE 1: DIM FOO%(3,5)
  4123.           SIZ%=5: INITVAL%=20000: ARLOC%=VARPTR(FOO%(1,1))
  4124.           CALL SETMATI(ARLOC%,SIZ%,INITVAL%)
  4125.           REM  we have just set the first five elements of the array to
  4126.           REM  20000.  The first five elements are FOO%(1,1), FOO%(2,1),
  4127.           REM  FOO%(3,1), FOO%(1,2), FOO%(2,2).  If you want to initialize
  4128.           REM  the whole array to 20000, set SIZ%=3*5 for OPTION BASE 1
  4129.           REM  or SIZ%=(3+1)*(5+1) for OPTION BASE 0.
  4130.           REM  By changing the first element (in the ARLOC% assignment), you
  4131.           REM  can set any part of the array, not just the first elements.
  4132.           REM  See SCRSAVE/SCRREST if you need to clear up that last point.
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.      Name: SETKBD
  4170.  
  4171.      Type: Input / CLONE
  4172.  
  4173.      Description:
  4174.           Sets  the  status  of  the keyboard toggles.  The toggle is set on
  4175.      if  the  value  is  nonzero,  and off if the value is zero.  Good style
  4176.      suggests  that,  before  using  this  function  for the first time, you
  4177.      should  get  the  toggles  with GETKBD (see) and save them.  You should
  4178.      then  restore  the  keyboard  to that original state before exiting the
  4179.      program.
  4180.  
  4181.      Example:
  4182.           REM  Let's turn off Insert, Caps Lock, and Scroll Lock
  4183.           REM  and put the keypad into numeric mode by turning on Num Lock
  4184.           INSERT%=0: CAPSLOCK%=0: NUMLOCK%=1: SCROLLLOCK%=0
  4185.           CALL SETKBD(INSERT%,CAPSLOCK%,NUMLOCK%,SCROLLLOCK%)
  4186.  
  4187.  
  4188.  
  4189.  
  4190.      Name: SETPOINT
  4191.  
  4192.      Type: Video / BIOS
  4193.  
  4194.      Description:
  4195.           Sets  a  point  on  a  text  screen.   This  allows low-resolution
  4196.      graphics  on  monochrome  as  well  as color monitors.  Normal text can
  4197.      also  be  mixed  with  the graphics.  Resolution is 80x50 (0-79 columns
  4198.      by 0-49 rows).  See also RESETPOINT and TESTPOINT.
  4199.  
  4200.      Example:
  4201.           ROW%=24
  4202.           FOR COLUMN%=0 TO 79
  4203.              CALL SETPOINT(COLUMN%,ROW%)
  4204.           NEXT COLUMN%
  4205.           REM  this draws a line across the middle of the screen.
  4206.  
  4207.  
  4208.  
  4209.  
  4210.      Name: SETSUB
  4211.  
  4212.      Type: Disk / DOS
  4213.  
  4214.      Description:
  4215.           Sets  the  default  subdirectory.   The  subdirectory  string must
  4216.      be  terminated  by  a  NUL character.  An error will be returned if the
  4217.      specified subdirectory doesn't exist.
  4218.  
  4219.      Example:
  4220.           TMP$=SUB$+CHR$(0): CALL SETSUB(TMP$,ERRCODE%)
  4221.           IF ERRCODE% THEN bad subdir ELSE new default subdir selected
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.  
  4234.  
  4235.      Name: SHIFTL
  4236.  
  4237.      Type: Miscellaneous / ANY
  4238.  
  4239.      Description:
  4240.           Shifts all the bits in an integer left COUNT times, putting zeroes
  4241.      in  the bit positions which have been vacated.  This effectively multi-
  4242.      plies  the  value  by  a power of two in most instances.  This function
  4243.      is  included  for  those  advanced  programmers who know what it's good
  4244.      for...
  4245.  
  4246.      Example:
  4247.           VALUE%=47: COUNT%=3
  4248.           CALL SHIFTL(VALUE%,COUNT%)
  4249.           REM  we just shifted VALUE% left three bits
  4250.           REM  (in this case getting 47 * 2^3, or 376)
  4251.  
  4252.  
  4253.  
  4254.  
  4255.      Name: SHIFTR
  4256.  
  4257.      Type: Miscellaneous / ANY
  4258.  
  4259.      Description:
  4260.           Same  as  SHIFTL, but shifts the bits right instead of left.  This
  4261.      is similar in effect to an integer divide by a power of two.
  4262.  
  4263.      Example:
  4264.           VALUE%=47: COUNT%=3
  4265.           CALL SHIFTR(VALUE%,COUNT%)
  4266.           REM  we just shifted VALUE% right 3 bits
  4267.           REM  (here getting 47 \ 2^3, or 5)
  4268.  
  4269.  
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.  
  4296.  
  4297.  
  4298.  
  4299.  
  4300.  
  4301.      Name: SOUNDEX
  4302.  
  4303.      Type: String / ANY
  4304.  
  4305.      Description:
  4306.           This  routine  returns  the Soundex code for a string you give it.
  4307.      I'm  not sure who invented Soundex, but it's pretty handy.  The Soundex
  4308.      routine  takes  a  word  and returns a string which represents what the
  4309.      word  sounds  like  in  an abstract format.  Similar-sounding words can
  4310.      thus  be  identified  easily  by your program after Soundex processing.
  4311.      This  can  be  useful in applications where a person is not sure of the
  4312.      exact  spelling  of  a  word/name/city,  etc.   To use, put the word in
  4313.      WORD$, initialize the return string SCODE$ to the same length as WORD$,
  4314.      and  execute  the  routine.   SLEN%  will  return  the actual length of
  4315.      SCODE$,  which  may  vary  from zero to the length of WORD$.  If SCODE$
  4316.      is  not  as  long  as  WORD$  when the routine is called, SLEN% will be
  4317.      returned  as  -1  to  flag  an  error.  The Soundex code is returned as
  4318.      a  series  of  digits  in  SCODE$,  although you can represent this any
  4319.      way you choose in your program.
  4320.  
  4321.      Example:
  4322.           WORD$="AnyWord": SCODE$=WORD$
  4323.           CALL SOUNDEX(WORD$,SCODE$,SLEN%)
  4324.           PRINT"The Soundex code for ";WORD$;" is ";LEFT$(SCODE$,SLEN%);"."
  4325.           REM  Try this routine a few times to get a feel for it.
  4326.  
  4327.  
  4328.  
  4329.  
  4330.      Name: SPEAKER
  4331.  
  4332.      Type: Miscellaneous / CLONE
  4333.  
  4334.      Description:
  4335.           This  function  allows  you  to  turn the speaker on or off.  This
  4336.      allows you to disable sound effects for a program.  Your sound routines
  4337.      will  still  be  executed,  but  will not produce any sound if you have
  4338.      turned  the  speaker off.  Thus, your routines will execute at the same
  4339.      speed  whether  or  not  sound is turned on, and the timing will remain
  4340.      the same.  Note that you should turn the speaker back on before exiting
  4341.      the program!
  4342.           Use zero to turn off the speaker, nonzero to turn it back on.
  4343.           NOTE: This  function  appears  to be erratic, especially when used
  4344.      with  slightly  incompatible  machines  such as the AT.  It is unlikely
  4345.      to work on a PCjr.  Test it to see if it works for you.
  4346.  
  4347.      Example:
  4348.           SPKR% = 0
  4349.           CALL SPEAKER(SPKR%)
  4350.           REM  turn the speaker off
  4351.  
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.      Name: STRIP
  4368.  
  4369.      Type: String / ANY
  4370.  
  4371.      Description:
  4372.           Strips  all  occurrences  of a given target character from a given
  4373.      source  string.   The  target  string must be at least one character in
  4374.      length (if more, the first character will be used).
  4375.  
  4376.      Example:
  4377.           MSG$="12 - 2 =   10"
  4378.             .
  4379.             .
  4380.           CH$=" ": CALL STRIP(MSG$,CH$,MLEN%): MSG$=LEFT$(MSG$,MLEN%)
  4381.  
  4382.  
  4383.  
  4384.  
  4385.      Name: STRIPBLANKS
  4386.  
  4387.      Type: String / ANY
  4388.  
  4389.      Description:
  4390.           Strips  blanks  (and  control  characters) from either the left or
  4391.      right  side of a string, or both sides.  Specify 0 (zero) for no strip,
  4392.      1 to strip left, 2 to strip right, or 3 to strip both sides.
  4393.  
  4394.      Example:
  4395.           STRIPWHICH=3: REM strip both sides of blanks
  4396.           CALL STRIPBLANKS(ST$,STRIPWHICH%,SLEN%)
  4397.           ST$=LEFT$(ST$,SLEN%)
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.      Name: STRIPRANGE
  4434.  
  4435.      Type: String / ANY
  4436.  
  4437.      Description:
  4438.           Strips all characters within a given range out of a source string.
  4439.  
  4440.      Example:
  4441.           MSG$="ALL uppercase letters will be G-O-N-E gone"
  4442.           LO%=ASC("A"): HI%=ASC("Z")
  4443.           CALL STRIPRANGE(MSG$,LO%,HI%,MLEN%)
  4444.           MSG$=LEFT$(MSG$,MLEN%)
  4445.  
  4446.  
  4447.  
  4448.  
  4449.      Name: SUBEXIST
  4450.  
  4451.      Type: Disk / DOS
  4452.  
  4453.      Description:
  4454.           Tests  to  see  if  a  given subdirectory exists.  You may include
  4455.      a  drive  spec  in  the  subdirectory name, which must be terminated by
  4456.      a null.
  4457.  
  4458.      Example:
  4459.           SUBDIR$="C:\TEMP"+CHR$(0)
  4460.           CALL SUBEXIST(SUBDIR$,VALID%)
  4461.           IF VALID% THEN PRINT"Subdirectory exists"
  4462.           ELSE PRINT"No such subdirectory"
  4463.  
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.      Name: TESTPOINT
  4500.  
  4501.      Type: Video / BIOS
  4502.  
  4503.      Description:
  4504.           Tests  a  pixel  on  a  text  screen to see if it's on or off (see
  4505.      SETPOINT  for  information  about  text  graphics).  The value returned
  4506.      will be set if the point is set, or reset if the point is not set.
  4507.  
  4508.      Example:
  4509.           COL%=39: ROW%=24: REM  check a point near the middle of the screen
  4510.           CALL TESTPOINT(COL%,ROW%,STATUS%)
  4511.           IF STATUS% THEN PRINT"The point is lit"
  4512.           ELSE PRINT"The point is not lit"
  4513.  
  4514.  
  4515.  
  4516.  
  4517.      Name: TIME2INT
  4518.  
  4519.      Type: Miscellaneous / ANY
  4520.  
  4521.      Description:
  4522.           Squeezes  the  time  down to a single integer, for reduced storage
  4523.      requirements.   You  will lose some accuracy in the seconds, which will
  4524.      be  converted  to  an  even  number (odd numbers will be rounded down).
  4525.      To  avoid  ambiguity,  it  is  recommended that you specify hours using
  4526.      a 24-hour clock.  See also INT2TIME.
  4527.  
  4528.      Example:
  4529.           CALL(HOUR%,MIN%,SEC%,SQZTIME%)
  4530.  
  4531.  
  4532.  
  4533.  
  4534.      Name: TIMEN2S
  4535.  
  4536.      Type: String / ANY
  4537.  
  4538.      Description:
  4539.           Converts  the  time  from  numbers to a string.  The string should
  4540.      be at least eight characters long.  See also TIMES2N.
  4541.  
  4542.      Example:
  4543.           HOUR%=13: MIN%=30: SEC%=8: TIM$=SPACE$(8)
  4544.           CALL TIMEN2S(HOUR%,MIN%,SEC%,TIM$)
  4545.           REM  From this, we get TIM$="13:30:08"
  4546.  
  4547.  
  4548.  
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.  
  4565.      Name: TIMES2N
  4566.  
  4567.      Type: String / ANY
  4568.  
  4569.      Description:
  4570.           Converts  the  time  from  a  string  to numbers.  The seconds are
  4571.      optional, and will be set to zero if nonexistent.
  4572.  
  4573.      Example:
  4574.           TIM$="13:09:42"
  4575.           CALL TIMES2N(HOUR%,MIN%,SEC%,TIM$)
  4576.           REM  We get HOUR%=13, MIN%=9, SEC%=42
  4577.           TIM$="03:15"
  4578.           CALL TIMES2N(HOUR%,MIN%,SEC%,TIM$)
  4579.           REM  We get HOUR%=3, MIN%=15, SEC%=0
  4580.  
  4581.  
  4582.  
  4583.  
  4584.      Name: TINSTR
  4585.  
  4586.      Type: STRING / ANY
  4587.  
  4588.      Description:
  4589.           Allows  you  to  search  for  a  given  type of character within a
  4590.      string.   You  may  search for any of several character types by adding
  4591.      the  values of the types to search for.  This also allows you to search
  4592.      for  the  opposite  of  a  character type (that is, search for anything
  4593.      other than that type).
  4594.  
  4595.      Character types:
  4596.      1
  4597.           Alphabetic  A-Z, a-z
  4598.      2
  4599.           Numeric     0-9
  4600.      4
  4601.           Symbolic    (anything not covered by other types)
  4602.      8
  4603.           Control     (control codes: ASCII 0-31, 127)
  4604.      16
  4605.           Graphics    (PC graphics codes: 128-255)
  4606.      32
  4607.           Blank       (a blank space, ASCII 32)
  4608.  
  4609.      Example:
  4610.           CHRTYPE%=1+2+4+8+16  : REM search for first non-blank character
  4611.           CALL TINSTR(ST$,CHRTYPE%,PLACE%)
  4612.           IF PLACE%=0 THEN PRINT"The string contains no non-blank chars"
  4613.           ELSE PRINT"The first nonblank character is at location";PLACE%;"."
  4614.  
  4615.      Example:
  4616.           CHRTYPE%=2  : REM search for first numeric character
  4617.           ST$="Springfield, VA 22152"
  4618.           CALL TINSTR(ST$,CHRTYPE%,PLACE%)
  4619.           PRINT"The zip code is: ";MID$(ST$,PLACE%,5)
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.      Name: UPCASE
  4638.  
  4639.      Type: String / ANY
  4640.  
  4641.      Description:
  4642.           Converts a string to all uppercase.
  4643.  
  4644.      Example:
  4645.           MSG$="Four score and seven years ago"
  4646.             .
  4647.             .
  4648.           CALL UPCASE(MSG$)
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.  
  4700.  
  4701.  
  4702.  
  4703.      Name: WEEKDAY
  4704.  
  4705.      Type: Miscellaneous / DOS
  4706.  
  4707.      Description:
  4708.           Returns  an  integer  from  1  - 7 indicating the day of the week,
  4709.      Sunday  through  Saturday.  The example routine turns this integer into
  4710.      the week day.
  4711.  
  4712.      Example:
  4713.           CALL WEEKDAY(DAY%)
  4714.           DLEN%=VAL(MID$("3346535",DAY%,1))
  4715.           DLOC%=ASC(MID$("ADGKQVY",DAY%))-64
  4716.           REM  The above string MUST be in uppercase!
  4717.           PRINT"Today is";
  4718.           PRINT MID$("SunMonTuesWednesThursFriSatur",DLOC%,DLEN%);"day."
  4719.  
  4720.  
  4721.  
  4722.  
  4723.      Name: WRITEBITF
  4724.  
  4725.      Type: Miscellaneous / ANY
  4726.  
  4727.      Description:
  4728.           Allows  a value to be written into a given location of a simulated
  4729.      array  of  words  of  arbitrary  bit  length (1-8 bits per word).  This
  4730.      goes  with  the  READBITF function above.  The "BITF" is for Bit Field,
  4731.      because  the  functions work by creating fields of arbitrary bit length
  4732.      within what is actually an integer array.
  4733.  
  4734.      Example:
  4735.           CALL WRITEBITF(ARRAYLOC%,INDEX%,BITFSIZE%,VALUE%)
  4736.           REM  See the READBITF function, and see the BITFTEST.BAS if you
  4737.           REM  have the ADVBAS contributor disk, to better idea of what's
  4738.           REM  going on.  This function is not for novice programmers!
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.  
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.  
  4758.  
  4759.  
  4760.  
  4761.  
  4762.  
  4763.  
  4764.  
  4765.  
  4766.  
  4767.  
  4768.  
  4769.      Name: XLATE
  4770.  
  4771.      Type: String / ANY
  4772.  
  4773.      Description:
  4774.           This  function  translates a string, character by character, using
  4775.      a  table  you supply.  The character's ASCII value is used as the index
  4776.      to  the  table, and the value at that location replaces the character's
  4777.      current  value.   The  character  may  be  one byte in length, in which
  4778.      case  it  will be translated, or zero bytes, in which case nothing will
  4779.      happen.   The  translation  string  must  be  256 bytes long (remember,
  4780.      strings  may  be  longer  than  255 bytes in Compiled BASIC, so this is
  4781.      ok).
  4782.  
  4783.      Example:
  4784.           XLT$=""
  4785.           FOR X%=0 TO 255: XLT$=XLT$+CHR$(X%): NEXT
  4786.           MID$(XLT$,1,5)="ABCDE": CH$=CHR$(0)
  4787.           CALL XLATE(CH$,XLT$)
  4788.           PRINT CH$
  4789.           REM  CH$ ends up "A", since the start of the table + zero bytes
  4790.           REM      contains "A".  We add zero bytes, because CH$ was
  4791.           REM      originally equal to CHR$(0).
  4792.  
  4793.  
  4794.  
  4795.  
  4796.      Name: XMPRINT
  4797.  
  4798.      Type: Video / BIOS
  4799.  
  4800.      Description:
  4801.           This  routine  combines the XLATE and MPRINTC functions.  It takes
  4802.      a  character,  runs  it  through  a translation table, and prints it to
  4803.      the  screen  unless  the translated value is NUL (ASCII zero).  If it's
  4804.      NUL,  no  printing  takes  place.   MS-DOS calls are used for printing,
  4805.      so  ANSI.SYS will work.  See the XLATE and MPRINTC routines for further
  4806.      information.
  4807.  
  4808.      Example:
  4809.           CALL XMPRINT(CH$,XLATE$,COL%,ROW%): LOCATE ROW%,COL%
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835.      Name: XQPRINT
  4836.  
  4837.      Type: Video / CLONE
  4838.  
  4839.      Description:
  4840.           This  function  is  an  extended  version  of  QPRINT.  It is more
  4841.      flexible,  and  only  a trifle slower.  XQPRINT has two advantages over
  4842.      QPRINT: it  allows  you  to  choose  a color/attribute to use, and lets
  4843.      you  choose  a  display  page  (color/graphics  adapters  only!).   The
  4844.      attribute  ATTR  must  be  set up using the CALCATTR routine.  The page
  4845.      argument is ignored for monochrome adapters.
  4846.  
  4847.      Example:
  4848.           ST$="This is a test of fast screen printing"
  4849.           ROW%=10: COL%=20: PAGE%=0
  4850.           CALL CALCATTR(FOREGND%,BACKGND%,ATTR%)
  4851.           CALL XQPRINT(ST$,ROW%,COL%,ATTR%,PAGE%)
  4852.  
  4853.  
  4854.  
  4855.  
  4856.      Name: XQPRINTD
  4857.  
  4858.      Type: Video / CLONE
  4859.  
  4860.      Description:
  4861.           This  function  is  identical  to  XQPRINT, with the one exception
  4862.      that  it  writes  directly  to  the  screen.  That makes it even faster
  4863.      than  XQPRINT, but means that it will cause snow on some color monitors
  4864.      when printing to the active display page.
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.  
  4893.  
  4894.  
  4895.  
  4896.  
  4897.  
  4898.  
  4899.  
  4900.  
  4901.                                  File Attributes
  4902.  
  4903.  
  4904.  
  4905.  
  4906.           Every  file  has  an  "attribute byte" which tells something about
  4907.      the  file.   This  can  be  modified to some extent.  For instance, any
  4908.      file  can  be  made  "hidden", in which case it will be invisible; this
  4909.      includes  subdirectories,  which  can  still  be used even if you can't
  4910.      see  that  they're there.  Some kinds of changes are not possible, how-
  4911.      ever: you can't change a subdirectory into a normal file, for example.
  4912.  
  4913.  
  4914.      Attribute      Code      Description
  4915.  
  4916.      Normal         00h       A normal file.
  4917.      Read-only      01h       File can't be killed or rewritten.
  4918.      Hidden         02h       File disappears from view.
  4919.      System         04h       Like HIDDEN.  For system (DOS, BIOS) files.
  4920.      Volume label   08h       A disk's volume label.  Only one, in the root.
  4921.      Directory      10h       Subdirectory.
  4922.      Archive        20h       Usually set.  May be used for disk backup.
  4923.  
  4924.  
  4925.           Combinations  of  the  codes are possible, as I've mentioned.  For
  4926.      instance,  a  hidden subdirectory would have a code of 10h + 02h = 12h.
  4927.      A  normal  file,  because  of  the archive bit, might show up as either
  4928.      00h  or  20h... and  so on.  Note this is all in hexadecimal, hence the
  4929.      "h"  postfix.   Convert  to  decimal  form  as  necessary  when calling
  4930.      routines  which  use the file attribute.  BASIC has functions to handle
  4931.      this  for  you  if you don't understand hex-- see the HEX$ function and
  4932.      &H prefix in your BASIC manual.
  4933.  
  4934.           NOTE: Reading  the  volume  label is unreliable in versions of DOS
  4935.      prior to MS-DOS 3.1, due to a DOS bug.  The most secure way of handling
  4936.      it  is to do a search with the label attribute (8), then to doublecheck
  4937.      the  actual  attribute  of  the  file  (if any) which was returned.  If
  4938.      it's not the volume label, use FINDNEXTF and try again.
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.  
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.  
  4957.  
  4958.  
  4959.  
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.  
  4966.  
  4967.                               New file I/O routines
  4968.  
  4969.  
  4970.  
  4971.           This  contains  some  general  information  about the new file I/O
  4972.      routines:  FCLOSE, FCREATE, FOPEN, FREAD, FSETEND, FSETREC, and FWRITE.
  4973.  
  4974.           These  routines  duplicate  a  number  of  extant BASIC functions.
  4975.      They  are  useful,  however, for a number of reasons.  They provide you
  4976.      with  low-level  control  over  the  details  of file input and output.
  4977.      They  may  be safely used in subprograms, since they return error codes
  4978.      rather  than  using error trapping (subprograms have severe limitations
  4979.      on  use  of  error  trapping).   They  provide access to the file-level
  4980.      locking  capabilities  of  DOS  2.0 and above, which allows creation of
  4981.      programs  which  work  on normal computers as well as those with multi-
  4982.      tasking  or  networking  (BASIC's  record-level locking is incompatible
  4983.      with normal computers unless SHARE is activated).
  4984.  
  4985.           In  BASIC,  you give the file a number when you open it, and refer
  4986.      to  the  file  by that number from then on.  With the ADVBAS functions,
  4987.      you  are  given  a  "handle"  when  you open the file, which serves the
  4988.      same  purpose.  In BASIC, a file is automatically created (or truncated
  4989.      if  it  exists)  if  you open it for output.  With ADVBAS, you must use
  4990.      FCREATE  to  produce  that  result.  If you have an existing file which
  4991.      you  want  to  modify  (or  read), use FOPEN.  With ADVBAS, like BASIC,
  4992.      you  can  read  or write to a file, or move the file pointer to a given
  4993.      record or to the end of file (to append information).  Also like BASIC,
  4994.      you must close a file when you are finished using it.
  4995.  
  4996.      The error codes returned by these functions are as follows:
  4997.        -1    Unable to read or write the entire record
  4998.         2    File not found
  4999.         3    Path not found
  5000.         4    No handle available
  5001.         5    Access denied
  5002.         6    Invalid handle
  5003.        15    Invalid drive specification
  5004.  
  5005.           If  you  get  "no  handle  available", you have run out of room to
  5006.      open  files.   You  can  fix  this  by not opening so many files at the
  5007.      same  time, or by increasing the FILES=xx statement in your CONFIG.SYS.
  5008.      See your DOS manual for further information.
  5009.  
  5010.  
  5011.  
  5012.  
  5013.  
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.  
  5022.  
  5023.  
  5024.  
  5025.  
  5026.  
  5027.  
  5028.  
  5029.  
  5030.  
  5031.  
  5032.  
  5033.                                    BASCOM Bugs
  5034.  
  5035.  
  5036.  
  5037.      Microsoft QuickBASIC Compiler v1.00:
  5038.  
  5039.           If  there  is  not enough memory when you try to execute the SHELL
  5040.      command, your program will crash.
  5041.           The  error  STRING FORMULA TOO COMPLEX appears erratically in some
  5042.      programs, for no apparently good reason.
  5043.  
  5044.  
  5045.      Microsoft QuickBASIC Compiler v1.02:
  5046.  
  5047.           This  release  solves the SHELL crash problem.  Also, more control
  5048.      characters  are  now  printed out just like BASICA.  Many miscellaneous
  5049.      problems  have  been  fixed... but  not the infamous STRING FORMULA TOO
  5050.      COMPLEX error.
  5051.  
  5052.  
  5053.  
  5054.  
  5055.  
  5056.  
  5057.  
  5058.  
  5059.  
  5060.  
  5061.  
  5062.  
  5063.  
  5064.  
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.                                    BASCOM Bugs
  5100.  
  5101.  
  5102.  
  5103.      Microsoft QuickBASIC Compiler v2.0 and v3.0:
  5104.  
  5105.           If  your  program  uses  error trapping, it must have at least one
  5106.      line  number in the program, even you normally only use labels.  Other-
  5107.      wise the program will crash if it runs into an error.
  5108.           Screen paging doesn't work in v2.0.
  5109.           If  you have a REMark on the same line as a DATA statement, you'll
  5110.      get peculiar error messages.
  5111.  
  5112.           The  programming  environment doesn't work properly with user lib-
  5113.      raries  (such  as  ADVBAS)  under  certain  conditions.  In particular,
  5114.      compiling  to  an  EXE  or  BRUN  file will produce flaky code.  If you
  5115.      run  into  this  problem,  just  compile  the program the old way, from
  5116.      the command line.  Instead of
  5117.           QB PROGRAM.BAS /L ADVBAS.EXE
  5118.      you would use something like
  5119.           QB PROGRAM;
  5120.           LINK PROGRAM,,,ADVBAS
  5121.      to  compile  and  link the program.  You may need to provide additional
  5122.      information,  depending  on whether your program uses things like error
  5123.      trapping or event trapping.  See your QuickBASIC manual for details.
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.  
  5162.  
  5163.  
  5164.  
  5165.      Microsoft QuickBASIC 4.0:
  5166.  
  5167.           ADVBAS  functions  which  require  static  arrays will not work in
  5168.      the  environment,  due  to a bug in QuickBASIC.  You may be able to use
  5169.      them  by  declaring  them in COMMON statements, but do this at your own
  5170.      risk.   You  can  still  use  these  routines in programs compiled with
  5171.      the  stand-alone  version,  BC.EXE,  however,  except for GETSCREEN and
  5172.      PUTSCREEN.   Note  that  this problem does not affect ProBas functions,
  5173.      which  were written to deal with dynamic arrays as well (and the static
  5174.      arrays  in  the  QB4  environment  behave somewhat similarly to dynamic
  5175.      arrays).
  5176.  
  5177.           When  you try to produce an .EXE file from the QuickBASIC environ-
  5178.      ment,  the  compiler  (QB.EXE)  executes the stand-alone version of the
  5179.      compiler  (BC.EXE)  in  order  to  compile your program.  No problem so
  5180.      far,  although  it  means you must have your libraries in both .QLB and
  5181.      .LIB  form.   Then  QB  executes  the  LINK utility (LINK.EXE) in order
  5182.      to  create  the final .EXE file.  Trouble!  For obscure reasons, Quick-
  5183.      BASIC  specifies  the  parameters  for  the  LINK  command in the wrong
  5184.      order.   This  works,  sort  of... that  is, if you're using libraries,
  5185.      it  will  make  your  programs much larger, because it links everything
  5186.      in  the library rather than just the routines you use.  It also ignores
  5187.      your  DOS  environment  setting  for the library location, meaning that
  5188.      you  need  to  have  your  libraries in the current drive/subdirectory.
  5189.      Finally,  it  may not work at all if you have a lot of routines in your
  5190.      library.  This is really a nuisance!
  5191.  
  5192.           Solution: don't  create  .EXE  files  from within the environment.
  5193.      Only  use  the  environment  for  debugging,  and create the final .EXE
  5194.      files  yourself  with  BC  and  LINK,  using the old syntax.  Don't try
  5195.      to add the library to the filename, the way QB tries to do, but instead
  5196.      specify the library name when LINK asks you for libraries.
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.      Notes on Microsoft's QuickBASIC v4.0:
  5232.  
  5233.           You  might  guess  from  the  version  number  that this is merely
  5234.      another  in  a  series  of  improvements  to QuickBASIC.  In fact, this
  5235.      version  represents  an  entire  rewrite  of  the compiler.  The result
  5236.      is  in  general much more powerful than earlier versions of QuickBASIC,
  5237.      but does have its own quirks.
  5238.  
  5239.           Some  of the nice new features: recursive functions and procedures
  5240.      (at  last!),  long integers (with a range of plus or minus two billion,
  5241.      this  numeric  type  is very handy, and is provided in many languages),
  5242.      code  which  can  be  linked  with other languages (subject to a number
  5243.      of  limitations),  and  an  improved compiling environment.  The editor
  5244.      provided  in  the  environment  now  accepts Wordstar-type commands, as
  5245.      well  as  Microsoft's  own  esoteric  commands.  Programs are instantly
  5246.      compiled  into  "p-code"  as  you enter them, which gives you automatic
  5247.      syntax  checking  (can  be  turned  off)  and reformatting (which can't
  5248.      be  turned  off),  and  means  you  never have to wait for your program
  5249.      to  compile.   The reformatter makes all BASIC keywords uppercase, puts
  5250.      spaces  between  parameters  to  a function call, makes all occurrences
  5251.      of  a  given  variable  have the same case as the last time you entered
  5252.      it,  and so forth.  Many people find this a nuisance, but on the whole,
  5253.      I  think  I  like  it.  Input and output now take place through DOS, so
  5254.      you  can easily redirect input or output from the command line.  Output
  5255.      to  the  screen is also faster, if you've got an ANSI driver installed,
  5256.      since  ANSI  is  more  efficient  than  the old BIOS calls.  The screen
  5257.      is  no  longer  automatically  cleared  when your program starts, which
  5258.      is very nice.
  5259.  
  5260.           Problems: there  is  a  new  library  format for the environment--
  5261.      QLB  instead of EXE.  Old assembly routines usually need to be modified
  5262.      to  work  with  QB4 whether or not the environment is used.  Procedures
  5263.      and  functions  are  kept in separate areas from your main program, and
  5264.      it  takes  several  keystrokes  to  get at them.  If you are particular
  5265.      about  the  style  of  your  code,  you may hate the reformatter.  Code
  5266.      produced  is  about  the same size or larger, but is much slower unless
  5267.      you  have  a  numeric  coprocessor  (8087,  80287, or 80387) installed.
  5268.      There  is  less  string  space available than in older compilers, which
  5269.      may cause trouble with large programs.
  5270.  
  5271.           Personally,  I really like most of the changes.  I have been look-
  5272.      ing  for  some  of  these  features  for a long time, and it's great to
  5273.      see  them.   There  are a lot of drawbacks too, though, and many people
  5274.      don't  like the new compiler.  You'll have to draw your own conclusions
  5275.      on  this  one.  It's worth the (painful) wait for the upgrade, though--
  5276.      if  QB4  suits  you,  it  will improve your productivity immensely.  If
  5277.      not... put  it  up for sale, this is going to be a top seller.  Despite
  5278.      its other problems, QB4 is a very convenient environment for beginners,
  5279.      especially  those  moving  from interpreted BASIC.  This is one product
  5280.      that is going to do Real Well.
  5281.  
  5282.  
  5283.  
  5284.  
  5285.  
  5286.  
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.  
  5294.  
  5295.  
  5296.  
  5297.      Notes on Borland's Turbo BASIC v1.0:
  5298.  
  5299.           Turbo  BASIC  is almost completely compatible with BASICA/GWBASIC,
  5300.      and  fairly  compatible  with  QuickBASIC.  It supports recursive func-
  5301.      tions,  local  variables, long integers, and the 8087 chip, among other
  5302.      things.   It  has  a  fairly  slick  windowing programming environment,
  5303.      and features online, context-sensitive help.  The editor is a configur-
  5304.      able  Wordstar-type  editor.   Code  size  and speed seem to be roughly
  5305.      comparable  to QuickBASIC (probably better than QuickBASIC 4.0).  Turbo
  5306.      BASIC's  main  fault  seems  to  be  that it lacks an assembly language
  5307.      interface--  it  uses  a  machine-language  INLINE  format like that in
  5308.      Turbo  Pascal.  This is more than enough to dissuade me from converting
  5309.      ADVBAS  to  work  with  Turbo BASIC.  Otherwise, though, it's nearly as
  5310.      strong  a  product  as  Microsoft's QuickBASIC, and it looks like we're
  5311.      shaping up for some fine marketing battles.
  5312.  
  5313.  
  5314.  
  5315.  
  5316.  
  5317.                                    BASIC Bugs
  5318.  
  5319.  
  5320.  
  5321.  
  5322.           This  is  a  peculiar  one... it seems that BASIC can create files
  5323.      having  names  which  contain blank spaces.  This is a problem, because
  5324.      DOS  considers  the  space  to  be  a delimiter, and thus cannot handle
  5325.      these files.  Such files will not be listed correctly in the directory,
  5326.      and  will  be  impossible  to  manipulate from DOS (can't read, delete,
  5327.      or  otherwise  handle  the  file).  So, be careful to screen out spaces
  5328.      when  creating files from BASIC!  This caveat also applies to subdirec-
  5329.      tories, including those created with the MAKESUB routine of ADVBAS.
  5330.  
  5331.           If  you take the VAL() of a string, you expect the value converter
  5332.      to stop when it runs into the end of the string or a non-numeric charac-
  5333.      ter.   Trouble  is,  BASIC  ignores spaces rather than treating them as
  5334.      non-numeric  characters.   So  if  you  try  A = VAL("256 12") you will
  5335.      not  get  A  =  256, as you thought, but actually A = 25612.  Surprise!
  5336.      Microsoft  does  not  consider  this a bug, although it's hard to think
  5337.      of an application in which this behavior might be appropriate.
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.  
  5352.  
  5353.  
  5354.  
  5355.  
  5356.  
  5357.