home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / FOXPRO / FFAQ / UNDOC.FAQ < prev   
Text File  |  1992-08-12  |  12KB  |  361 lines
  1.     FORCE FAQ (Frequently Asked Questions)   (undoc.faq 1.1)           1
  2.     --------------------------------------------------------------------
  3.  
  4.     Topic:   UNDOCUMENTED FORCE FUNCTIONS           Author: David Holmes
  5.  
  6.     What you'll find here:
  7.  
  8.     ( ) General Discussion
  9.     ( ) Function prototypes for the Undocumented functions
  10.     ( ) Some quick documentation for them.
  11.  
  12.     Examples: Attrs.exe             ( in the SAMPLE directory )
  13.  
  14.     General discussion:
  15.     -------------------------------------------------------------------
  16.  
  17.     At long last, the documentation for the Undocumented FORCE
  18.     functions!  Well, here's a quick list of the ones that I'm going
  19.     to talk about:
  20.  
  21.     FUNCTION LOGICAL    Interrupt
  22.     FUNCTION UINT        Int_w_flags
  23.     PROCEDURE        make_ptr
  24.     FUNCTION UINT        and
  25.     FUNCTION UINT        or
  26.     FUNCTION UINT        xor
  27.     PROCEDURE        dec_hex
  28.  
  29.     And, here's the documentation in an orderly format:
  30.  
  31.     ===================================================================
  32.     Function:    Interrupt()
  33.     ---------
  34.     FORCE Prototype:
  35.     ----------------
  36.         FUNCTION LOGICAL Interrupt PROTOTYPE
  37.            PARAMETERS VALUE UINT int_no,        ;
  38.             VALUE UINT ax,    VALUE UINT bx,    ;
  39.             VALUE UINT cx,    VALUE UINT dx,    ;
  40.             VALUE UINT si,    VALUE UINT di,    ;
  41.             VALUE UINT bp,    VALUE UINT ds,    ;
  42.             VALUE UINT es
  43.  
  44.     Description:
  45.     ------------
  46.     This is the function that everyone thinks about when they hear
  47.     "Undocumented FORCE functions."  Well, it's about time to remove
  48.     that "Undocumented" part.
  49.  
  50.     First, a REALLY quick assembly language primer:
  51.  
  52.     An Interrupt is exactly what you think it is.  It "interrupts"
  53.     the CPU and has it attend to some task.  To call an interrupt
  54.     (in assembly language), you say
  55.  
  56.         INT    21h        ; The major DOS interrupt
  57.  
  58.  
  59.     --------------------------------------------------------------------
  60.                                                          (undoc.faq)   1
  61.     FORCE FAQ (Frequently Asked Questions)                             2
  62.     --------------------------------------------------------------------
  63.  
  64.     This tells the CPU to stop and save what it's doing, and jump
  65.     to some location specified at 0000:0084.  From there, it looks
  66.     at the register AX, specifically the "top half," AH, and does
  67.     a CASE statement on it.  For example, if AH were 4C, it would
  68.     terminate the current program and return to DOS.  In assembly
  69.     that would look like:
  70.  
  71.         MOV    AX,4C00h    ; The little h means Hexidecimal
  72.         INT    21h
  73.  
  74.  
  75.     To accomplish the same thing in FORCE, you would do:
  76.  
  77.         VARDEF
  78.             UINT    ax,bx,cx,dx,si,di,bp,ds,es
  79.         ENDDEF
  80.  
  81.         AX = 0x4c00
  82.         Interrupt( 0x21, ax, bx, cx, dx, si, di, bp, ds, es )
  83.  
  84.     That would effectively kill your program, and you'd just have
  85.     to hope that DOS closed all of your file handles for you.  I
  86.     don't recommend this method of shutting down.
  87.  
  88.     Another example:  if AH was 09, the interrupt would mean "print
  89.     out a string pointed to by DS:DX."  This would be a little
  90.     tougher in FORCE, but you could do it.
  91.  
  92.         String_to_Print = "Must End with a Dollar Sign! $"
  93.         make_ptr( ds, dx, String_to_Print )
  94.         ax = 0x0900
  95.         Interrupt( 0x21, ax, bx, cx, dx, si, di, bp, ds, es )
  96.  
  97.     Note that the Interrupt() function will change the "register"
  98.     values to what they were immediately after the interrupt
  99.     returned.  Suppose that you wanted to know the free disk space
  100.     on your C drive.  There's an interrupt service that will tell
  101.     you: Int 21h/36h.  Here are the specs:
  102.  
  103.     Registers on Entry:
  104.     ------------------
  105.     AH = 36h
  106.     DL = Drive code        ; 1 = A, 2 = B, 3 = C, etc
  107.  
  108.     Registers on Return:
  109.     -------------------
  110.     AX = Sectors per cluster    ; or 0xFFFF if error
  111.     BX = Available clusters
  112.     CX = Bytes per sector
  113.     DX = Clusters per drive
  114.  
  115.     So, to get all of this information, you would do:
  116.  
  117.         ax = 0x3600
  118.         dx = 0x0003
  119.     --------------------------------------------------------------------
  120.                                                          (undoc.faq)   2
  121.     FORCE FAQ (Frequently Asked Questions)                             3
  122.     --------------------------------------------------------------------
  123.         interrupt( 0x21, ax, bx, cx, dx, si, di, bp, ds, es )
  124.         if ax = 0xffff
  125.            ? "Error!"
  126.            quit
  127.         endif
  128.  
  129.         *- And to calculate the available space, you do
  130.  
  131.         ? "available space on C:"
  132.         ?? AX * BX * CX
  133.  
  134.     Interrupt() returns TRUE if the interrupt returned without the
  135.     carry flag set.  Usually, the carry flag after an interrupt means
  136.     that there was some kind of error.  If the carry flag was set,
  137.     FALSE is returned.
  138.  
  139.     ===================================================================
  140.     Function:    Int_w_Flags
  141.     ---------
  142.     FORCE Prototype:
  143.  
  144.         FUNCTION UINT Int_w_Flags PROTOTYPE
  145.            PARAMETERS VALUE UINT int_no,    ;
  146.             VALUE UINT ax,    VALUE UINT bx,    ;
  147.             VALUE UINT cx,    VALUE UINT dx,    ;
  148.             VALUE UINT si,    VALUE UINT di,    ;
  149.             VALUE UINT bp,    VALUE UINT ds,    ;
  150.             VALUE UINT es
  151.  
  152.     Description:
  153.     ------------
  154.         This function is exactly the same as Interrupt, but
  155.     instead of returning TRUE or FALSE, this returns the state
  156.     of the flags immediately after the interrupt.  Since Int_w_Flags()
  157.     returns the flags as a UINT, you must use the function BITTEST()
  158.     to test the flags.  For example, let's say you wanted to some
  159.     Direct Console I/O (INT 21h/06).  The interrupt will return with
  160.     the Zero flag set if there was no character in keyboard buffer.
  161.     You would test that like this:
  162.  
  163.         AX = 0x0600
  164.         DX = 0x00FF    ; Fetch, don't write
  165.  
  166.         do while .T.
  167.            flags = Int_w_Flags( 0x21,ax,bx,cx,dx,si,di,bp,ds,es)
  168.            *---
  169.            * To test the zero flag, use BITTEST() on the 6th bit
  170.            *---
  171.            if BitTest( flags, 6 )    ; Did we get a character?
  172.               continue;            ; No, so continue.
  173.            else
  174.               exit
  175.            endif
  176.         enddo
  177.  
  178.  
  179.     --------------------------------------------------------------------
  180.                                                          (undoc.faq)   3
  181.     FORCE FAQ (Frequently Asked Questions)                             4
  182.     --------------------------------------------------------------------
  183.  
  184.     ===================================================================
  185.     Function:    make_ptr()
  186.     ---------
  187.     FORCE Prototype:
  188.     ----------------
  189.         PROCEDURE make_ptr
  190.            PARAMETERS UINT segment, UINT offset, UNTYPED thing
  191.  
  192.     Description:
  193.     ------------
  194.         make_ptr() is pretty self explanatory.  It takes the
  195.     address of something, and returns its SEGMENT and OFFSET.  I
  196.     find this function particularly useful when I'm using the
  197.     Interrupt() and Int_w_Flags() functions.  They often need a pointer
  198.     to a structure or a buffer, so you can use make_ptr() to get
  199.     that pointer.  See the example code for Interrupt() above for its
  200.     usage.
  201.  
  202.     ===================================================================
  203.     Function:    Addr
  204.     ---------
  205.     FORCE Prototype:
  206.  
  207.         FUNCTION ULONG Addr PROTOTYPE 
  208.            PARAMETERS UNTYPED something
  209.  
  210.     Description:
  211.     ------------
  212.         Addr() returns the address of the "something."  This is
  213.     useful if you need to pass a pointer to a C function, or just
  214.     need the address of any data type.  It is similar to make_ptr(),
  215.     but returns the address as a ULONG value instead of splitting it
  216.     to a segment and offset, as make_ptr() does.
  217.  
  218.     ===================================================================
  219.     Function:    And(), Or(), Xor()
  220.     ---------
  221.  
  222.     FORCE Prototypes:
  223.     -----------------
  224.  
  225.         FUNCTION UINT and PROTOTYPE
  226.            PARAMETERS VALUE UINT word1, VALUE UINT word2
  227.  
  228.         FUNCTION UINT or PROTOTYPE
  229.            PARAMETERS VALUE UINT word1, VALUE UINT word2
  230.  
  231.         FUNCTION UINT xor PROTOTYPE
  232.            PARAMETERS VALUE UINT word1, VALUE UINT word2
  233.  
  234.     Description:
  235.     ------------
  236.  
  237.         These functions implement three bitwise operations,
  238.     Logical AND, OR, and XOR.  They each take two integer values,
  239.     --------------------------------------------------------------------
  240.                                                          (undoc.faq)   4
  241.     FORCE FAQ (Frequently Asked Questions)                             5
  242.     --------------------------------------------------------------------
  243.     and perform their logical function upon the two.  The result
  244.     of that operation is returned.
  245.  
  246.     For those of you not familiar with the logical operands, here's
  247.     a table, in binary, so that you can see how they work.
  248.  
  249.         01001010        01001010        01001010
  250.     AND 00001010         OR    00101010        XOR 00101010
  251.         --------        --------        --------
  252.         00001010        01101010        01100000
  253.  
  254.     If you can't figure it out, here it is in english:
  255.  
  256.     AND will test two bits at a time, one from each word.  The
  257.     resulting bit will be 1 if the first bit AND the second bit
  258.     are both 1.
  259.  
  260.     OR will test two bits at a time, one from each word.  The
  261.     resulting bit will be 1 if the first bit OR the second bit
  262.     OR both are 1.  Known as the Inclusive-Or.
  263.  
  264.     XOR will test two bits at a time, one from each word.  the
  265.     resulting bit will be 1 if 1 and only 1 of the bits is 1.
  266.     If both are 1, the result is 0.  If both are 0, the result
  267.     is 0.  It is one or the other.  Known as the Exclusive-Or.
  268.  
  269.         *- Examples:
  270.  
  271.         ? and( 1, 3 )    && prints 1, because 1 and 3 look like:
  272.                 && 00000001 AND 00000011 ->
  273.  
  274.         ? or( 1, 4 )    && prints 5, because 1 and 4 look like:
  275.                 && 00000001 OR 00000100 -> 00000101
  276.  
  277.         ? xor( 1, 3 )    && Prints 2, because:
  278.                 && 00000001 XOR 00000011 -> 00000010
  279.  
  280.     ===================================================================
  281.     Function:    Dec_Hex
  282.     ---------
  283.     FORCE Prototype:
  284.     ----------------
  285.         PROCEDURE Dec_Hex PROTOTYPE
  286.            PARAMETERS CONST CHAR result_buffer, VALUE LONG number
  287.  
  288.     Description:
  289.     ------------
  290.         Dec_Hex() is a strange procedure, but can sometimes be
  291.     useful.  It takes a string buffer, and a LONG value, and prints
  292.     the value in Hexidecimal into the string buffer.
  293.  
  294.     PROCEDURE Force_Main
  295.  
  296.         VARDEF
  297.             CHAR        buffer
  298.         ENDDEF
  299.     --------------------------------------------------------------------
  300.                                                          (undoc.faq)   5
  301.     FORCE FAQ (Frequently Asked Questions)                             6
  302.     --------------------------------------------------------------------
  303.  
  304.         Dec_Hex( buffer, Addr( Force_Main )
  305.         ? buffer    && prints the address of FORCE_MAIN
  306.     ENDPRO
  307.  
  308.     Note:  This function is in the library, but with the leading
  309.     underscore (_).  So I wrote a wrapper function called _dec_hex()
  310.     and included it in the COMMON.LIB.  It does nothing more than
  311.     push the values on to the stack and call dex_hex().
  312.     ===================================================================
  313.  
  314.  
  315.     Final Comments:
  316.     -------------------------------------------------------------------
  317.         I always get nervous talking about the undocumented FORCE
  318.     functions.  They have a strange air of mystery about them, and
  319.     sometimes I wonder why they are undocumented.  I have a feeling
  320.     it's because they don't really "fit in" with the general scheme
  321.     of the other functions in the library.
  322.  
  323.         Nearly all of them deal with lower-level programming that
  324.     the designers probably wanted to hide from the user.  Of course,
  325.     people found out about them, and many FORCE programmers don't
  326.     mind going low-level when it makes more sense.  I suppose that's
  327.     why they're FORCE programmers.
  328.  
  329.         If anyone thinks they know of any other undocumented
  330.     FORCE functions that they'd like to see tested and documented,
  331.     I'd be more than happy to oblige.  Be sure that check out the
  332.     README.1ST in your \FORCE\BIN directory.  It lists several
  333.     undocumented functions (which are in the header files).
  334.  
  335.         Oh, don't bother to ask about the factorial() function.
  336.     It's not even supposed the be in the library, and calls some
  337.     functions that don't exist.
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.     --------------------------------------------------------------------
  360.                                                          (undoc.faq)   6
  361.