home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 193_01 / deff3.txt < prev    next >
Text File  |  1985-11-14  |  13KB  |  402 lines
  1.                         DEFF3.TXT
  2.                         ---------
  3.  
  4.          I have given, below, a description of each of the functions
  5.          which I have written for the file -
  6.  
  7.                    DEFF3.C
  8.  
  9.          and which may be accessed through -
  10.  
  11.                    DEFF3(.CRL)
  12.  
  13.          when you use the CLINK function with BDS C.   It is not
  14.          necessary to specify "DEFF3" on the command line as BDS C
  15.          will look for any missing functions in the DEFF files,
  16.          automatically, in answer to a RETURN entered when it asks
  17.          you for instructions as to which CRL files it should search
  18.          for the missing functions.
  19.  
  20.          If you intend to use DEFF3 in this way then it should be on
  21.          the same disk as the BDS C DEFF files.   Now, the functions
  22.          I have written and what they do are -
  23.  
  24.  
  25.          BITCOUNT(n)
  26.          unsigned n;
  27.          ----------
  28.  
  29.          Returns the number of set bits ( = 1) in a byte.
  30.  
  31.  
  32.          BINARY(x, v, n)
  33.          int x, v[], n;
  34.          ---------------
  35.  
  36.          Checks whether a binary number (x) occurs in a sorted array
  37.          (v, of n elements) and, if so, returns the binary number or
  38.          else returns -1 if it doesn't occur.
  39.  
  40.  
  41.          CGET()
  42.          ------
  43.  
  44.          Similar to "getchar" in what it does except that it will
  45.          read ANY byte value from the console.  i.e. the value you
  46.          enter doesn't have to be either ASCII or printable.
  47.  
  48.          It returns the value of the byte entry.
  49.  
  50.  
  51.          CLOSE_FILE(fcb)
  52.          char fcb[36];
  53.          ---------------
  54.  
  55.          This will close the file whose name is included in the file
  56.          control block pointed to by "fcb".   It is the companion
  57.          function to "OPEN_FILE" and should be used to close any file
  58.          previously opened with OPEN_FILE.   It returns the same
  59.          values as OPEN_FILE.
  60.  
  61.  
  62.          CLRSCREEN()
  63.          -----------
  64.  
  65.          Will clear the screen and home the cursor, using in-built
  66.          terminal software commands.   It is (probably) only usable
  67.          by Hazeltine family terminals but could be altered to suit
  68.          other terminals provided you know the byte value(s) to send
  69.          to the terminal to activate the clear screen/home function.
  70.  
  71.          Doesn't return anything.
  72.  
  73.  
  74.          CON_STAT()
  75.          ----------
  76.  
  77.          This checks the console status and returns ZERO if there is
  78.          no character waiting, else it returns 0xff....NOT the
  79.          character itself.   It is a useful function for those inputs
  80.          where you tell the user -
  81.  
  82.               "Enter any character to continue."
  83.  
  84.               
  85.          CPUT(c)
  86.          int c;
  87.          -------
  88.  
  89.          Similar to "putchar" except that it will send ANY byte value
  90.          to the console.   Naturally the console will only display
  91.          the "visible" characters.   Doesn't return anything useful.
  92.  
  93.  
  94.          CREATE_FILE(fcb)
  95.          char fcb[36];
  96.          ----------------
  97.  
  98.          This will create the file named in the file control block
  99.          (see open_file for a description of this) an initialise it
  100.          for both read and write functions.   Note particularly that
  101.          it doesn't check to see whether a file of this name already
  102.          exists so you need to do this independently if you want to
  103.          make sure you haven't got two files of the same name in the
  104.          disk directory.
  105.  
  106.          It is supposed to return 0xff (255 decimal) if the disk is
  107.          full and the name can't be created, but I'm not so sure
  108.          that you can rely on it to do so.   Probably the best way
  109.          to be sure is to now try to open the file (with open_file)
  110.          and see what happens then.
  111.  
  112.  
  113.          DIRECTC(duty)
  114.          int duty;
  115.          -------------
  116.  
  117.  
  118.          This is CP/M function No. 6 and it can be used to either get
  119.          a character from the terminal, or to send a character to the
  120.          console.   It depends on the value of "duty" which should be
  121.          either -
  122.  
  123.               0xff                for input from the terminal
  124.          or   the byte value      for output to the console
  125.  
  126.          It returns the input character in the first case or zero in
  127.          the second case.
  128.  
  129.  
  130.          ERASE_FILE(fcb)
  131.          char fcb[36];
  132.          ---------------
  133.  
  134.          Erases from the directory the name of the file in the file
  135.          control block.   For a description of this see open_file.
  136.          It will return 0xff if the file isn't found.
  137.  
  138.  
  139.          GET_CPM()
  140.          ---------
  141.  
  142.          Returns a 16-bit number (in HL) with the details -
  143.  
  144.               H = 0x00 for CP/M  OR  H = 0x01 for MP/M
  145.               L = 0x00 for all releases prior to 2.0
  146.               L = 0x20 for version 2.0, 0x21 for version 2.1, 0x22
  147.                   for version 2.2, and so on.
  148.  
  149.          If you want to use any of this information then you will
  150.          need to mask off H (or L) to find out what it was the
  151.          function returned.
  152.  
  153.  
  154.          GET_DEFAULT()
  155.          -------------
  156.  
  157.          Returns the name for the current default disk.   Note A = 0,
  158.          B = 1....and so on.
  159.  
  160.          
  161.          GET_IOBYTE()
  162.          ------------
  163.  
  164.          Returns the current IOBYTE setting under CP/M 2.2.
  165.  
  166.  
  167.          INDEX(s, t)
  168.          char s[], t[];
  169.          -------------
  170.  
  171.          Returns a pointer to the position of string "t" inside
  172.          string "s", else returns -1 if no match is found.
  173.  
  174.  
  175.          ITOA(n, str)
  176.          int n;
  177.          char s[];
  178.          ------------
  179.  
  180.          Will convert an integer (n) into a printable ASCII string,
  181.          which is placed in "str".   This is one of the obvious
  182.          functions which should already have been included in BDS C.
  183.  
  184.  
  185.          ISALNUM(c)
  186.          char c;
  187.          ----------
  188.  
  189.          Returns TRUE/FALSE whether the character is alpha-numeric.
  190.  
  191.  
  192.          MAKE_RO()
  193.          ---------
  194.  
  195.          Makes the current logical disk read-only status.   I don't
  196.          think it returns anything.
  197.  
  198.  
  199.          OPEN_FILE(fcb)
  200.          char fcb[36];
  201.          --------------
  202.  
  203.          Opens the nominated file, the name of which must be in the
  204.          file control block ("fcb") in the manner required by CP/M.
  205.          Note that the file is opened for BOTH reading and writing.
  206.          Before using this function you should have already made a
  207.          file control block with the function -
  208.  
  209.               setfcb(fcb, filename)
  210.  
  211.          Note particularly "fcb" as used in these functions is a
  212.          pointer to the file control block or, as used in assembly
  213.          language programming, it is the address of the fcb which
  214.          holds the file name.   This should be an external buffer so
  215.          that it is known to all functions in the programme.
  216.  
  217.          This will return 0xff if the open was unsuccessful or a
  218.          number 0, 1, 2 or 3 (which is an offset into the DMA buffer)
  219.          if the open succeeded.   For those who understand the way
  220.          CP/M works, this offset may be used to get the directory
  221.          entry information on the opened file.
  222.  
  223.          To be able to access the DMA buffer you must have first
  224.          created a DMA buffer whose address (the pointer to) is
  225.          known to you.   Do this with the function -
  226.  
  227.               set_dma(dma)
  228.               int dma[128];
  229.  
  230.  
  231.          PRINT_DEC(n)
  232.          int n;
  233.          ------------
  234.  
  235.          Prints a decimal number (n) to the console.
  236.  
  237.          PRT_STR(str)
  238.          char *str;
  239.          ------------
  240.  
  241.          Prints a string (terminated by the character "$") to the
  242.          console.   Doesn't return anything.
  243.  
  244.          Note you shouldn't use this function if you expect to meet
  245.          with the dollar sign other than as the end of line marker.
  246.  
  247.  
  248.          READ_SEQ_SEC(fcb)
  249.          char fcb[36];
  250.          -----------------
  251.  
  252.          Starting from the first available sector (of 128 bytes) it
  253.          will reach each successive sector in the file until the end
  254.          of the file is reached.   Returns zero when the read is
  255.          successful, else returns a non-zero number.   Note that the
  256.          file must already have been opened prior to this function
  257.          being called.
  258.  
  259.  
  260.          READ_STR(str)
  261.          char *str;
  262.          -------------
  263.  
  264.          Will read a RETURN-terminated string from the terminal and
  265.          place it, as a NULL-terminated string, into the str buffer.
  266.          Note, when calculating the size of the string buffer you
  267.          will use, you have to add one for the '\0' character which
  268.          will terminate the string.
  269.  
  270.          e.g. if you want the maximum length of the string to be 80
  271.          characters then specify -
  272.  
  273.                    char str[81];
  274.  
  275.          for the string buffer.
  276.  
  277.  
  278.          RESET_DSK()
  279.          -----------
  280.  
  281.          This resets the disk system and reads the active disk
  282.          details into memory again.   It is typically used in a
  283.          programme after a disk has been changed, or swapped.   It
  284.          doesn't return anything.
  285.  
  286.  
  287.          REVERSE(str)
  288.          char str[];
  289.          ------------
  290.  
  291.          Will reverse a null-terminated string in place.
  292.  
  293.  
  294.          SEARCH_FIRST(fcb)
  295.          char fcb[36];
  296.          -----------------
  297.  
  298.          This searches the disk directory for the first file name
  299.          which matches the name given in the file control block
  300.          pointed to by "fcb".   Note - see OPEN_FILE for a run-down
  301.          on the file control block under CP/M.   The file name you
  302.          choose may be either ambiguous or specific.
  303.  
  304.          If it is ambiguous, this function will return the first
  305.          file name which matches the given name.   When a match has
  306.          occurred, it returns 0, 1, 2 or 3 which is the offset
  307.          into the DMA buffer where the directory information has
  308.          been placed by CP/M.   Knowing the offset (which is a factor
  309.          of 32 bytes) you can now recover the actual directory entry
  310.          as stored by CP/M.
  311.  
  312.          e.g. if the offset is, say, 2 then if you look 2 x 32 = 64
  313.          bytes into the DMA you will find the first byte of the
  314.          directory entry for the matching file name.
  315.  
  316.          If it returns 0xff (255 decimal) then you didn't find any
  317.          file which matched the name you gave.
  318.  
  319.  
  320.          SEARCH_NEXT()
  321.          -------------
  322.  
  323.          Carries on from search_first to locate any further names
  324.          which match the name in the file control block.   Note this
  325.          can only be used after a successful search_first.   It will
  326.          return the same parameters as search_first for both failure
  327.          and success.
  328.          
  329.  
  330.          SELECT_DSK(drive)
  331.          int drive;
  332.          -----------------
  333.  
  334.          This allows you to change the "logical" drive during the
  335.          course of a programme.   Just enter the drive name as A, B,
  336.          C...M, etc and the function converts this to the value
  337.          required by CP/M.   Doesn't return anything.
  338.  
  339.  
  340.          SET_ATTRIBUTES(fcb)
  341.          char fcb[36];
  342.          -------------------
  343.  
  344.          Used to set (or re-set) the attributes for R/O, R/W, DIR,
  345.          SYS and ARC and CPY (in my backup programme) so that CP/M
  346.          will know how to deal with a particular file in the disk
  347.          directory.   To use this function successfully you must
  348.          have first formulated a file control block with the bits
  349.          you want CP/M to recognise either set ( = 1) or re-set to
  350.          zero, as the case may be.   Will return 0xff if the file
  351.          can't be located in the disk directory.
  352.  
  353.  
  354.          SET_DMA(buffer)
  355.          int buffer[128];
  356.          ---------------
  357.  
  358.          Creates a pointer to the DMA (CP/M's direct memory address)
  359.          buffer which can then be used in the read/write and other
  360.          CP/M functions where a DMA is required.   It is probably
  361.          most useful when "buffer" is declared externally.
  362.          
  363.          
  364.          SET_IOBYTE(iob)
  365.          int iob;
  366.          ---------------
  367.  
  368.          Re-sets the IOBYTE to the specified value.   Doesn't return
  369.          anything.
  370.  
  371.  
  372.          SHELL_SORT(v, n)
  373.          int v[], n;
  374.          ---------------
  375.  
  376.          Sorts an array "v" of "n" elements into increasing order.
  377.  
  378.  
  379.          SWAP_POINTERS(px, py)
  380.          char *px[], *py[];
  381.          ---------------------
  382.  
  383.          Will interchange two pointers.
  384.  
  385.  
  386.          USER_ID(code)
  387.          int code;
  388.          -------------
  389.  
  390.          Will either return the current User Number, if code = 255
  391.          (0xff), or will change the User Number if code = 0 to 15.
  392.  
  393.  
  394.          WRITE_SEQ_SEC(fcb)
  395.          char fcb[36];
  396.          ------------------
  397.  
  398.          A companion function to read_seq_sec.   This will write
  399.          successive sectors to the open file named in the file
  400.          control block.   It will return zero if successful or a
  401.          non-zero number if not successful in completing the write.
  402.          ed by CP/M.   Doesn't ret