home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0090 - 0099 / ibm0090-0099 / ibm0099.tar / ibm0099 / CDBASE-1.ZIP / CLIP_NDX.DOC < prev    next >
Encoding:
Text File  |  1992-05-29  |  11.1 KB  |  285 lines
  1.  
  2.  
  3.  
  4.       clip_ndx.doc (c)Copyright Sequiter Software Inc., 1990-1992.
  5.       All rights reserved.
  6.       
  7.       ---------------------------------------------------------------
  8.       
  9.          CODEBASE 4.5 CLIPPER AND DBASE III VERSION INFORMATION
  10.       
  11.       I.   Creating a Clipper or dBASE III version of CodeBase 4.5
  12.       
  13.       II.  Clipper or dBASE III Tag and Index definitions
  14.       
  15.       III  Using the Clipper or dBASE III version of CodeBase 4.5
  16.       
  17.       IV.  Extra Documentation
  18.       
  19.       V.   Manually Creating Group Files
  20.       
  21.       VI.  Example Clipper or dBASE III version programs.
  22.       
  23.       ----------------------------------------------------------------
  24.       
  25.       I.   Creating a Clipper or dBASE III version of CodeBase 4.5
  26.       
  27.          The Clipper file format is similar to the dBASE III format,
  28.       and therefore share common instructions of use.
  29.       
  30.          To create a Clipper or dBASE III version of CodeBase 4.5, rebuild
  31.       the CodeBase 4.5 library with 'S4CLIPPER or S4NDX' defined.  Whenever
  32.       you compile your application you will also have to define 'S4CLIPPER
  33.       or S4NDX' .
  34.  
  35.          When using the Clipper or dBASE III version of CodeBase, all
  36.       memo files are created and assumed to be in the Clipper or dBASE
  37.       III compatible format. It is possible to use the dBASE IV memo
  38.       file format by commenting out line 92 in 'D4DATA.H' before compiling
  39.       the library. (i.e. comment out the line that defines S4MNDX, which
  40.       sets CodeBase to use dBASE III style memo files).
  41.       
  42.       ----------------------------------------------------------------
  43.       
  44.       II.  Clipper or dBASE III Tag and Index definitions
  45.       
  46.          To effectively use the Clipper or dBASE III version of CodeBase
  47.       4.5, you will need to understand the following interpretations:
  48.       
  49.       1. Tag - A tag corresponds to any given '.NTX or .NDX' index file,
  50.          and has a file handle associated with it.
  51.       
  52.       2. Index - An index consists of one or more tags, along with (in
  53.          some cases) a CodeBase ".CGP" group file.  The purpose of the
  54.          group file is to keep a list of all tags corresponding to a
  55.          given index object.  The group file is created when the CodeBase
  56.          i4create() function is called to create a set of index tags.
  57.       
  58.       ----------------------------------------------------------------
  59.  
  60.       III. Using the Clipper or dBASE III version of CodeBase 4.5
  61.       
  62.          You must always define S4CLIPPER or S4NDX when writing your
  63.       application program, to ensure that the correct CodeBase header
  64.       definitions are used. 
  65.  
  66.          The Clipper or dBASE III version is implemented such that a
  67.       Tag corresponds to a single '.NTX or .NDX' index file.  For example,
  68.       you would use d4tag_select( "IND1" ) to select the open index
  69.       file "IND1.NTX". 
  70.  
  71.          There are two methods for using the Clipper or dBASE III compatible
  72.       version of CodeBase 4.5.
  73.       
  74.          The first method is to create your index files in CodeBase.
  75.        This will create an index group file (.CGP) which corresponds
  76.       to the auto-open features of ".MDX" AND ".CDX" index files.  Every
  77.       time a database file is opened in the Clipper or dBASE III compatible
  78.       version, CodeBase looks for a ".CGP" file in the same directory
  79.       and with the same name as the database file.  If it finds such
  80.       a file, it assumes that the files contains a list of tags that
  81.       should be opened for the database file.  Using this method your
  82.       programs will be completely portable between different index formats,
  83.       so you will not have to modify your programs if you switch to
  84.       ".MDX" or ".CDX" formats.  Database files that have no associated
  85.       index files will not have an associated .CGP file.  Therefore,
  86.       if you want to open a database file such as this, set the CodeBase
  87.       setting 'auto_open' (see pg. 45) to '0' before opening the database
  88.       file.  This will also work for database files that do have associated
  89.       index files, but do not have associated .CGP files.      
  90.  
  91.          The alternative method is to use your existing index files
  92.       by opening them as tags using the t4open() command documented
  93.       in section IV.  This command will open a given ".NTX" tag, and
  94.       create an index object to correspond one to one with the tag.
  95.       You can also use the t4create() function to create a new tag file
  96.       without a corresponding group file. 
  97.  
  98.          If you plan to use dBASE III with the CodeBase .NDX files,
  99.       please note the switch, 'S4USE_COUNT'.  When using dBASE III to
  100.       perform deletions, zaps or other operations which should force
  101.       a physical shrinking of the database file, dBASE does not always
  102.       perform the shrinking.  This will cause problems when using CodeBase,
  103.       or any other dBASE III compatible product with the  database file.
  104.        However, if you set this switch when compiling your CodeBase
  105.       .NDX library, CodeBase will automatically detect and correct the
  106.       database file.  The switch is set similar to the CodeBase conditional
  107.       compilation switches found at page 17 in the manual.  The switch
  108.       has been set in the supplied CodeBase .NDX dll. 
  109.  
  110.       ----------------------------------------------------------------
  111.       
  112.       IV.  Extra Documentation
  113.       
  114.       T4TAG *S4FUNCTION t4open( D4DATA *d4, I4INDEX *i4ndx, char *file_name )
  115.       
  116.          This function is used to open a given '.NTX or .NDX' tag file.
  117.        If the 'i4ndx' parameter is equal to 0 ( which you should set
  118.  
  119.       it to ), an I4INDEX structure is created internally along with
  120.       the T4TAG structure that is returned to you.  The I4INDEX structure
  121.       can be accessed with the d4index() function, using the tag name
  122.       as the name parameter.  This function otherwise acts similarly
  123.       to the i4open() function in the CodeBase manual. 
  124.       
  125.       T4TAG *S4FUNCTION t4create( D4DATA *d4, T4TAG_INFO *tag_data,
  126.                                               I4INDEX *i4ndx ) 
  127.  
  128.          This function is used to create a tag file without a corresponding
  129.       group file.  If the I4INDEX parameter is set to 0 ( which you
  130.       should do ), an index object will be created for your use, and
  131.       can be accessed with the d4index() command with the tag name as
  132.       the name parameter.  
  133.  
  134.          The tag_data parameter contains all relevant information for
  135.       the tag, including the tag file name (the name parameter).
  136.       
  137.          Also note that index filters and descending key orderings are
  138.       not available in Clipper or dBASE III-compatible index files.
  139.       
  140.       ----------------------------------------------------------------
  141.       
  142.       V.   Manually Creating Group Files
  143.       
  144.          If you want to create a group file for your index files, you
  145.       can easily do it manually.  The structure of the group file is
  146.       as follows: 
  147.  
  148.       {
  149.          int num_files ;   /* the # of tag files corresponding with
  150.                               the group  for each tag file we have: */
  151.          {
  152.             int len ;   /* the length of the file name */
  153.             char *name ; /* the actual file name, the length of which
  154.                             is len */    }
  155.       }
  156.       
  157.       For example, a simple group file with 2 index files "NAME" and
  158.       "PHONE" would be as follows: ( and remember reverse byte order,
  159.       65="A" ) 
  160.  
  161.       hex:                                   ascii: ( . means undefined )
  162.       
  163.       02 00 04 00 4E 41 4D 45 05 00 50 48 4F 4E 45         ....NAME..PHONE
  164.       
  165.       All file names should be in capital letters. (ascii 65-90)
  166.       
  167.       ----------------------------------------------------------------
  168.       
  169.       VI.  Example Clipper or dBASE III version programs.
  170.       
  171.       1. You can examine any of the programs in the test directory since
  172.          they all work with the CLIPPER or dBASE III version of CodeBase 4.5.
  173.       
  174.       2. Here are some extra Clipper examples:
  175.       
  176.  
  177.       
  178.                       ---------------------------------
  179.       /*
  180.          NTXEXAM1.C
  181.       
  182.          This program will manually create and use standard .NTX files
  183.          ( i.e. no group file )
  184.       
  185.       */
  186.       
  187.       #include "d4all.h"
  188.       
  189.       #ifdef __TURBOC__
  190.          extern unsigned _stklen = 10000 ;
  191.       #endif
  192.       
  193.       F4FIELD_INFO fields[] =
  194.       {
  195.          { "NAME",  'C', 20, 0 },
  196.          { "PHONE", 'C', 15, 0 },
  197.          { "ZIP",   'C',  6, 0 },
  198.          { 0,0,0,0 },
  199.       } ;
  200.       
  201.       T4TAG_INFO tags[] =
  202.       {
  203.          { "NAME",  "NAME",  0,0,0 },
  204.          { "PHONE", "PHONE", 0,0,0 },
  205.          { "ZIP",   "ZIP",   0,0,0 },
  206.          { 0,0,0,0,0 },
  207.       } ;
  208.       
  209.       main()
  210.       {
  211.          C4CODE c4 ;
  212.          D4DATA *d4 ;
  213.          T4TAG *name_tag ;
  214.          T4TAG *phone_tag ;
  215.          T4TAG *zip_tag ;
  216.       
  217.          d4init( &c4 ) ;
  218.       
  219.          /*
  220.             Alternatively, you can create the database and index group
  221.             file and tags all at once using:
  222.                d4 = d4create( &c4, "ADDRESS", fields, tags ) ;
  223.          */
  224.       
  225.          c4.auto_open = 0 ;  /* no group file */
  226.          d4 = d4create( &c4, "ADDRESS", fields, 0 ) ;
  227.       
  228.          name_tag = t4create( d4, &tags[0], 0 ) ;  /* optional if .ntx */
  229.          phone_tag = t4create( d4, &tags[1], 0 ) ;   /* create second tag */
  230.          zip_tag = t4create( d4, &tags[2], 0 ) ;
  231.       
  232.          d4tag_select( d4, name_tag ) ;  /* select name-ordering */
  233.       
  234.  
  235.          /* ... rest of program ... */
  236.       
  237.          d4close( d4 ) ;  /* this will automatically close everything */
  238.       }
  239.       
  240.                       ---------------------------------
  241.       /*
  242.          NTXEXAM2.C
  243.       
  244.          This program will manually open and use some existing .NTX
  245.       files created with Clipper.
  246.       
  247.       */
  248.       
  249.       #include "d4all.h"
  250.       
  251.       #ifdef __TURBOC__
  252.          extern unsigned _stklen = 10000 ;
  253.       #endif
  254.       
  255.       main()
  256.       {
  257.          C4CODE c4 ;
  258.          D4DATA *d4 ;
  259.          T4TAG *name_tag ;
  260.          T4TAG *phone_tag ;
  261.          T4TAG *zip_tag ;
  262.          I4INDEX *name_ind ;   /* suppose I need to access the name 
  263.                                   tag's index */
  264.       
  265.          d4init( &c4 ) ;
  266.       
  267.          c4.auto_open = 0 ;  /* no group file */
  268.          d4 = d4open( &c4, "ADDRESS" ) ;
  269.       
  270.          name_tag = t4open( d4, 0, "NAME.NTX" ) ;  /* optional if .ntx */
  271.          phone_tag = t4open( d4, 0, "PHONE" ) ;
  272.          zip_tag = t4open( d4, 0, "ZIP" ) ;
  273.       
  274.          name_ind = d4index( d4, "NAME.NTX" ) ;  
  275.       
  276.          d4tag_select( d4, name_tag ) ;  /* select name-ordering */
  277.       
  278.          i4reindex( name_ind ) ;  /* suppose my name tag is out of date,
  279.                                      so reindex */ 
  280.          /* ... rest of program ... */
  281.       
  282.          d4close( d4 ) ;  /* this will automatically close everything */
  283.       }
  284.  
  285.