README.1ST

This file contains information concerning usage of the APIs documented 
in the Technical Reference guide, as well as any last minute 
additions.  


1.  This disk contains the following files:

      README.1ST                   This file
      C52API.EXE                   Self-extracting archive containing 
                                   the Technical Reference Norton Guide 
                                   file (C52G03B.NG) 
      INCLUDE\FILESYS.API          File System API header file
      INCLUDE\GT.API               General Terminal API header file
      INCLUDE\ITEM.API             Item API header file
      INCLUDE\RDD.API              RDD API header file
      INCLUDE\VM.API               Virtual Memory API header file
      INCLUDE\FM.API               Fixed Memory API header file
      INCLUDE\EXTEND.API           Extend System API header file
      INCLUDE\ERROR.API            Error System API header file
      INCLUDE\RULES.RMK            Common RMAKE dependencies file 

      SOURCE\SDX\README.SDX        RDD API Sample code
      SOURCE\SDX\SDX.C                  "      "
      SOURCE\SDX\SDXINTER.C             "      "
      SOURCE\SDX\SDXDYN.ASM             "      "
      SOURCE\SDX\SDXINIT.PRG            "      "
      SOURCE\SDX\SDX.H                  "      "
      SOURCE\SDX\SDX.RMK                "      "
                                   
      SOURCE\ERROR\FILEOPEN.C      Error API Sample code
                                   
      SOURCE\FILESYS\FILEOPEN.C    Filesys API Sample code
                                   
      SOURCE\ITEM\CC.C             Item API Sample code
      SOURCE\ITEM\DFUNC.C               "      "
      SOURCE\ITEM\ISDBL.C               "      "
      SOURCE\ITEM\UACLN.C               "      "
      SOURCE\ITEM\UARRY.C               "      "
      SOURCE\ITEM\UEVAL.C               "      "
      SOURCE\ITEM\YESNO.C               "      "
      SOURCE\ITEM\CCTST.PRG             "      "
      SOURCE\ITEM\DFUNCTST.PRG          "      "
      SOURCE\ITEM\ISDBLTST.PRG          "      "
      SOURCE\ITEM\TESTBED.PRG           "      "
      SOURCE\ITEM\UACLNTST.PRG          "      "
      SOURCE\ITEM\UARRYTST.PRG          "      "
      SOURCE\ITEM\UEVALTST.PRG          "      "
      SOURCE\ITEM\CCTST.RMK             "      "
      SOURCE\ITEM\DFUNCTST.RMK          "      "
      SOURCE\ITEM\ISDBLTST.RMK          "      "
      SOURCE\ITEM\UACLNTST.RMK          "      "
      SOURCE\ITEM\UARRYTST.RMK          "      "
      SOURCE\ITEM\UEVALTST.RMK          "      "
                                   
      SOURCE\VM\BOOTSEC.C          VM API Sample code
      SOURCE\VM\CCVM.C                  "      "
      SOURCE\VM\HEXAMP.C                "      "
      SOURCE\VM\VMCOPY.C                "      "
      SOURCE\VM\BOOTREAD.PRG            "      "
      SOURCE\VM\CCVMTST.PRG             "      "
      SOURCE\VM\TESTBED.PRG             "      "
      SOURCE\VM\VCOPYTST.PRG            "      "
      SOURCE\VM\BOOTREAD.RMK            "      "
      SOURCE\VM\CCVMTST.RMK             "      "
      SOURCE\VM\VCOPYTST.RMK            "      "


    We suggest that these files be incorporated into the
    CA-Clipper 5.2 default directory structure as follows:

    \CLIPPER5              Master CA-Clipper 5.2 directory
       \INCLUDE            Header (.API) files
       \SOURCE
          \ERROR   (new)   Error API Sample files
          \FILESYS (new)   Filesys API Sample files 
          \ITEM    (new)   Item API Sample files
          \SDX     (new)   Rdd API Sample files
          \VM      (new)   VM API Sample files 
              
    \NG                    Technical Reference Norton Guide file


    Important:  Before copying the new header files be sure to
    backup the existing .API files so that they can be compared
    against the new ones.  (See item #3 below)


    This disk also includes the files required to update Clipper 
    to 5.2B.  The patch files are located in the \CLIP52B directory.  

      CLIP52B\README.52B           Instructions for applying 5.2B patches 
      CLIP52B\PATCH.EXE            Program for applying 5.2B patches 
      CLIP52B\52BUS.EXE            Patch files to update 5.2 to 5.2B  (US)
      CLIP52B\52ABUS.EXE           Patch files to update 5.2A to 5.2B (US)
      CLIP52B\52BI.EXE             Patch files to update 5.2 to 5.2B  (INTL)
      CLIP52B\52ABI.EXE            Patch files to update 5.2A to 5.2B (INTL) 

2.  The header files listed above replace those delivered with
    the initial release of CA-Clipper 5.2.


3.  A majority of API functions from the initial release of
    CA-Clipper 5.2 remain unchanged and can be used with your
    current version.

    In some instances the new header files contain functions that
    have been added and/or modified since the initial release of
    CA-Clipper 5.2.  To determine what changes have occurred,
    compare the original and new API header files.

    If you wish to take advantage of the added functionality (and
    avoid potential problems using changed functions) these APIs
    should be used with CA-Clipper version 5.2b and higher.


4.  The include RDD sample code uses most of the other APIs
    making it a good example to study even if you have no desire
    to create an RDD.  If you do plan to work with the SDX sample
    code, be sure to read the file README.SDX.


5.  Addendum

    The following functions were omitted from the RDD API
    documentation.

_rddInherit()
=============

ERRCODE _rddInherit( DBFUNCTABLEP table, DBFUNCTABLEP subTable, 
                     DBFUNCTABLEP superTable, BYTEP drvName )

   _rddInherit() copies the super class's table to "table" and
   then copies the non-NULL entries from "subTable" into it. 
   This provides the pseudo-inheritance mechanism.  "drvName"
   determines the name of the driver to inherit from.  If "drvName"
   is NULL the super class will be workarea.
 
   The modified copy of "table" will be used by the system any time
   our driver is used.  Also, "superTable" will now point to the
   unmodified super class's table, and can be used for calls to the 
   super class. 

   Examples of this function are provided in the SDX sample
   driver code.



_rddDisinherit()
================

   ERRCODE _rddDisinherit( BYTEP drvName )

   _rddDisinherit() advises the system that you are no longer 
   inheriting from the super class driver "drvName".  This 
   decrements the super class driver's reference counter by one.
   If you are the last driver inheriting from the super class driver,
   and the driver is not directly in use (by being open in a
   workarea) then a function to unload the driver is called.

   Currently there is no mechanism for actually unloading the
   super class driver (or any driver for that matter), but the
   _rddDisinherit() function will be important in future versions 
   and implementing it in the current version will not produce 
   any adverse effects.
  
   If "drvName" is not the name of a valid driver an error will
   occur. 




rddRegister()
=============

   RDDREGISTER( cDriver, nType )

   This is a CA-Clipper function that is called by the RDD's INIT 
   procedure.  This function registers the RDD with the CA-Clipper
   run-time system.

   "cDriver" is the name of the driver to register.

   "nType" is the RDD driver's type as shown below.  If not supplied
   the RDD type will default to RDD_FULL.

   RDD Types (defined in Rddsys.ch):

   constant      value   meaning
   ========      =====   ============================================
   RDT_FULL         1    Fully functional RDD.  The RDD can be
                         opened in a workarea and supports most of the
                         virtual table functions.

   RDT_TRANSFER     2    RDD capable of transferring records only.  A
                         transfer RDD can not be opened in a workarea. 
                         Example of this type of driver are the SDX
                         and DELIM in CA-Clipper.

   RDT_HIDDEN     255    RDD is only for use by another RDD through
                         inheritance.  This could be a database
                         driver that exists only to be subclassed by 
                         an index driver.  The RDT_HIDDEN flag
                         prevents the driver from being used by
                         itself.


   Example:

   /***
   *
   *  Sdxinit.prg
   *
   *  SDX driver initialization module
   *
   *  Copyright (c) 1993, Computer Associates International, Inc.
   *  All rights reserved.
   *
   */
   
   #include "Rddsys.ch"
   
   ANNOUNCE SDX
   
   INIT PROCEDURE SdxSys()
      REQUEST _SDX
   
      rddRegister( "SDX", RDT_FULL )
   
      RETURN
   




_rddExtendType()
================

   USHORT _rddExtendType( USHORT fieldType )

   Translates an internal field constant to an extend system 
   constant that can be used by the Extend and Item APIs.

   "fieldType" is the internal field type to be translated.
    
   Examples of this function are provided in the SDX sample
   driver code.


_rddFieldType()
===============

   USHORT _rddFieldType( USHORT extendType )

   Translates an extend system constant to an internal field
   constant that is usable by the Clipper runtime.
 
   "extendType" is the extend system type to be translated.
 
   Examples of this function are provided in the SDX sample
   driver code.




goToId()
========

 Position cursor at a specific physical identity

 Prototype

     ERRCODE goToId(
                     WORKAREAP wa,
                     GRIP rowId
                   )


 Arguments

     wa is a pointer to self.

     rowId is the row identifier of the new cursor position.


 Description

     Repositions the workarea cursor for wa to the physical row
     number row.


 Default Behavior

     You must implement the default behavior of this method through a
     subclass.


 Implementation Notes

     In implementations where the database identifier is a record
     number (like with a .DBF file), this function need only check
     the type of the row identifier to be sure it is numeric, and
     call it's GoTo() method.

     If the database does not use record numbers, the goToId()
     repositions the pointer to the row represented by the row
     identifier.  If the row is not in the physical range of rows
     available, you may generate an error or position the pointer at
     the physical end of file.

     See the GoTo() method for more information.


 Files:  Header file is Rdd.api.





orderCondition()
================

 Set the condition for an Order

 Prototype

     ERRCODE orderCondition( 
                             WORKAREAP wa,
                             DBORDERCONDINFOP dbOrderCondInfo
                           )

 Arguments

     wa is a pointer to self.

     dbOrderCondInfo is a pointer to a structure containing
     scoping condition information for the Order.

 Description

     Sets up the information required for creating and maintaining
     conditional (scoped) indexes.


 Default Behavior

     You must implement the default behavior of this method through a
     subclass.


 Implementation Notes

     This method implements the CA-Clipper ORDCONDSET() function.  If
     your Order supports conditional indexing, you must fill in the 
     members of the DBORDERCONDINFOP structure from the parameters
     passed from ORDCONDSET().  If any of the parameters contain a
     valid condition, the "active" member is set to TRUE. 

     This information will be used by the driver later when the index
     is created and maintained.


 Files:  Header file is Rdd.api.



orderDestroy()
==============

 Removes a specified Order from multiple-Order Bags.

 
 Prototype

     ERRCODE orderDestroy(
                           WORKAREAP wa,
                           DBORDERINFOP dbOrderInfo
                         )

 Arguments

     wa is a pointer to self.

     dbOrderInfo is a pointer to a structure containing information
     about the Order to be removed.


 Description

     Removes an Order in a multiple-Order Bag.  This method does not
     need to be implemented if your driver does not support multiple
     Orders.

     orderDestroy() provides the functionality of the CA-Clipper
     ORDDESTROY() function.


 Default Behavior

     You must implement the default behavior of this method through a
     subclass.

 Implementation Notes

     If the driver does not support multiple Orders, this method 
     does not need to be implemented.

     It is the drivers responsibility to remove the Order from the
     active Order List, free the memory used by the Order, and delete
     the Order from the Order Bag.
     
     If the Order does not exist and error should be generated.  If
     a Bag name is specified and the Bag does not exist an error
     should be generated.


 Files:  Header file is Rdd.api.




orderListDelete()
=================

 Deletes an order from the order list in the indicated workarea

 Prototype

     ERRCODE orderListDelete(
                              WORKAREAP wa,
                              DBORDERINFOP dbOrderInfo
                            )


 Arguments

     wa is a pointer to self.

     dbOrderInfo is a pointer to a structure containing information
     about the Order to be deleted.


 Description

     Deletes an Order from the Order List in the workarea.  This
     functionality is not present at the CA-Clipper level at this 
     time, so this method will not called currently.  


 Default Behavior

     Reserved for future use.
     

 Implementation Notes

     Reserved for future use.


 Files:  Header file is Rdd.api.



                           << END >>
