home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c162_1 / 1.ddi / CLIP_NDX.DOC < prev    next >
Encoding:
Text File  |  1992-08-29  |  13.4 KB  |  349 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.  
  57.          i4create() function is called to create a set of index tags.
  58.       
  59.       ----------------------------------------------------------------
  60.  
  61.       III. Using the Clipper or dBASE III version of CodeBase 4.5
  62.       
  63.          You must always define S4CLIPPER or S4NDX when writing your
  64.       application program, to ensure that the correct CodeBase header
  65.       definitions are used. 
  66.  
  67.          The Clipper or dBASE III version is implemented such that a
  68.       Tag corresponds to a single '.NTX or .NDX' index file.  For example,
  69.       you would use d4tag_select( "IND1" ) to select the open index
  70.       file "IND1.NTX". 
  71.  
  72.          There are two methods for using the Clipper or dBASE III compatible
  73.       version of CodeBase 4.5.
  74.       
  75.          The first method is to create your index files in CodeBase.
  76.        This will create an index group file (.CGP) which corresponds
  77.       to the auto-open features of ".MDX" AND ".CDX" index files.  Every
  78.       time a database file is opened in the Clipper or dBASE III compatible
  79.       version, CodeBase looks for a ".CGP" file in the same directory
  80.       and with the same name as the database file.  If it finds such
  81.       a file, it assumes that the files contains a list of tags that
  82.       should be opened for the database file.  Using this method your
  83.       programs will be completely portable between different index formats,
  84.       so you will not have to modify your programs if you switch to
  85.       ".MDX" or ".CDX" formats.  Database files that have no associated
  86.       index files will not have an associated .CGP file.  Therefore,
  87.       if you want to open a database file such as this, set the CodeBase
  88.       setting 'auto_open' (see pg. 45) to '0' before opening the database
  89.       file.  This will also work for database files that do have associated
  90.       index files, but do not have associated .CGP files.      
  91.  
  92.          The alternative method is to use your existing index files
  93.       by opening them as tags using the t4open() command documented
  94.       in section IV.  This command will open a given ".NTX" tag, and
  95.       create an index object to correspond one to one with the tag.
  96.       You can also use the t4create() function to create a new tag file
  97.       without a corresponding group file. 
  98.  
  99.          If you plan to use dBASE III with the CodeBase .NDX files,
  100.       please note the switch, 'S4USE_COUNT'.  When using dBASE III to
  101.       perform deletions, zaps or other operations which should force
  102.       a physical shrinking of the database file, dBASE does not always
  103.       perform the shrinking.  This will cause problems when using CodeBase,
  104.       or any other dBASE III compatible product with the  database file.
  105.        However, if you set this switch when compiling your CodeBase
  106.       .NDX library, CodeBase will automatically detect and correct the
  107.       database file.  The switch is set similar to the CodeBase conditional
  108.       compilation switches found at page 17 in the manual.  The switch
  109.       has been set in the supplied CodeBase .NDX dll. 
  110.  
  111.          NOTE: If you want to explicitly close a Clipper or dBASE III index
  112.  
  113.       file without closing the database file, use the function i4close().
  114.  
  115.       eg.
  116.          i4close( d4index( <datafile> ) ) ;
  117.  
  118.       ----------------------------------------------------------------
  119.       
  120.       IV.  Extra Documentation
  121.       
  122.       Using the Clipper function descend() in index expressions
  123.  
  124.          Since the CodeBase 4.5 manual was printed we have added the
  125.       Clipper function descend() to the list of dBase expression
  126.       functions in Appendix C of the manual that are supported by
  127.       CodeBase 4.5.  This function is available only when the CodeBase
  128.       4.5 is used with S4CLIPPER defined in the compiler options.
  129.  
  130.          The descend() function has the following syntax
  131.  
  132.            descend(argument)
  133.  
  134.       where 'argument' can be of type (D)ate, (N)umeric, (F)loat, or
  135.       (C)haracter.  Basically descend() just reverses the sorting order
  136.       of the values of 'argument' so that for example "Zebra" comes before
  137.       "Apple" or 99 comes before 12.
  138.  
  139.          We have also added some utility functions to help you construct
  140.       your seek string when using an index file that uses descend() in its
  141.       index expression.  These functions must be used because the
  142.       descend() function modifies the index file entries so that they are
  143.       unrecognizable.
  144.  
  145.          char *u4descend_char ( char *char_string)
  146.          char *u4descend_date ( char *date_string)
  147.          char *u4descend_num  ( char *numeric_string)
  148.          char *u4descend      ( F4FIELD *field_pointer)
  149.    
  150.          Examples:
  151.    
  152.               A. Index expression = "descend(LAST_NAME)" where LAST_NAME
  153.                  is a character field.
  154.    
  155.                  d4seek( d4, u4descend_char( "Jones" ) ) ;
  156.    
  157.               B. Index expression = "descend(BIRTHDATE)" where
  158.                  BIRTHDATE is a date field.
  159.    
  160.                  d4seek( d4, u4descend_date("19920629") ) ;
  161.    
  162.               C. Index expression = "descend(BASE)" where BASE is a numeric
  163.                     field of length 8.
  164.    
  165.                  d4seek( d4, u4descend_num("  1231.32" ) ) ;
  166.    
  167.               D. Index expression = "descend(LAST_NAME) + FIRST_NAME" where
  168.  
  169.                  LAST_NAME and FIRST_NAME are character fields
  170.    
  171.                  strcpy(SeekStr,u4descend_char("Jones");
  172.                  strcat(SeekStr,"Tom");
  173.                  d4seek(d4,SeekStr);
  174.  
  175.  
  176.       Additional Clipper and dBASE III-Specific Function Calls
  177.  
  178.       T4TAG *S4FUNCTION t4open( D4DATA *d4, I4INDEX *i4ndx, char *file_name )
  179.       
  180.          This function is used to open a given '.NTX or .NDX' tag file.
  181.        If the 'i4ndx' parameter is equal to 0 ( which you should set
  182.       it to ), an I4INDEX structure is created internally along with
  183.       the T4TAG structure that is returned to you.  The I4INDEX structure
  184.       can be accessed with the d4index() function, using the tag name
  185.       as the name parameter.  This function otherwise acts similarly
  186.       to the i4open() function in the CodeBase manual. 
  187.       
  188.       T4TAG *S4FUNCTION t4create( D4DATA *d4, T4TAG_INFO *tag_data,
  189.                                               I4INDEX *i4ndx ) 
  190.  
  191.          This function is used to create a tag file without a corresponding
  192.       group file.  If the I4INDEX parameter is set to 0 ( which you
  193.       should do ), an index object will be created for your use, and
  194.       can be accessed with the d4index() command with the tag name as
  195.       the name parameter.  
  196.  
  197.          The tag_data parameter contains all relevant information for
  198.       the tag, including the tag file name (the name parameter).
  199.       
  200.          Also note that index filters and descending key orderings are
  201.       not available in Clipper or dBASE III-compatible index files.
  202.       
  203.       ----------------------------------------------------------------
  204.       
  205.       V.   Manually Creating Group Files
  206.       
  207.          If you want to create a group file for your index files, you
  208.       can easily do it manually.  The structure of the group file is
  209.       as follows: 
  210.  
  211.       {
  212.          int num_files ;   /* the # of tag files corresponding with
  213.                               the group  for each tag file we have: */
  214.          {
  215.             int len ;   /* the length of the file name */
  216.             char *name ; /* the actual file name, the length of which
  217.                             is len */    }
  218.       }
  219.       
  220.       For example, a simple group file with 2 index files "NAME" and
  221.       "PHONE" would be as follows: ( and remember reverse byte order,
  222.       65="A" ) 
  223.  
  224.  
  225.       hex:                                   ascii: ( . means undefined )
  226.       
  227.       02 00 04 00 4E 41 4D 45 05 00 50 48 4F 4E 45         ....NAME..PHONE
  228.       
  229.       All file names should be in capital letters. (ascii 65-90)
  230.       
  231.       ----------------------------------------------------------------
  232.       
  233.       VI.  Example Clipper or dBASE III version programs.
  234.       
  235.       1. You can examine any of the programs in the test directory since
  236.          they all work with the CLIPPER or dBASE III version of CodeBase 4.5.
  237.       
  238.       2. Here are some extra Clipper examples:
  239.       
  240.       
  241.                       ---------------------------------
  242.       /*
  243.          NTXEXAM1.C
  244.       
  245.          This program will manually create and use standard .NTX files
  246.          ( i.e. no group file )
  247.       
  248.       */
  249.       
  250.       #include "d4all.h"
  251.       
  252.       #ifdef __TURBOC__
  253.          extern unsigned _stklen = 10000 ;
  254.       #endif
  255.       
  256.       F4FIELD_INFO fields[] =
  257.       {
  258.          { "NAME",  'C', 20, 0 },
  259.          { "PHONE", 'C', 15, 0 },
  260.          { "ZIP",   'C',  6, 0 },
  261.          { 0,0,0,0 },
  262.       } ;
  263.       
  264.       T4TAG_INFO tags[] =
  265.       {
  266.          { "NAME",  "NAME",  0,0,0 },
  267.          { "PHONE", "PHONE", 0,0,0 },
  268.          { "ZIP",   "ZIP",   0,0,0 },
  269.          { 0,0,0,0,0 },
  270.       } ;
  271.       
  272.       main()
  273.       {
  274.          C4CODE c4 ;
  275.          D4DATA *d4 ;
  276.          T4TAG *name_tag ;
  277.          T4TAG *phone_tag ;
  278.          T4TAG *zip_tag ;
  279.       
  280.  
  281.          d4init( &c4 ) ;
  282.       
  283.          /*
  284.             Alternatively, you can create the database and index group
  285.             file and tags all at once using:
  286.                d4 = d4create( &c4, "ADDRESS", fields, tags ) ;
  287.          */
  288.       
  289.          c4.auto_open = 0 ;  /* no group file */
  290.          d4 = d4create( &c4, "ADDRESS", fields, 0 ) ;
  291.       
  292.          name_tag = t4create( d4, &tags[0], 0 ) ;  /* optional if .ntx */
  293.          phone_tag = t4create( d4, &tags[1], 0 ) ;   /* create second tag */
  294.          zip_tag = t4create( d4, &tags[2], 0 ) ;
  295.       
  296.          d4tag_select( d4, name_tag ) ;  /* select name-ordering */
  297.       
  298.          /* ... rest of program ... */
  299.       
  300.          d4close( d4 ) ;  /* this will automatically close everything */
  301.       }
  302.       
  303.                       ---------------------------------
  304.       /*
  305.          NTXEXAM2.C
  306.       
  307.          This program will manually open and use some existing .NTX
  308.       files created with Clipper.
  309.       
  310.       */
  311.       
  312.       #include "d4all.h"
  313.       
  314.       #ifdef __TURBOC__
  315.          extern unsigned _stklen = 10000 ;
  316.       #endif
  317.       
  318.       main()
  319.       {
  320.          C4CODE c4 ;
  321.          D4DATA *d4 ;
  322.          T4TAG *name_tag ;
  323.          T4TAG *phone_tag ;
  324.          T4TAG *zip_tag ;
  325.          I4INDEX *name_ind ;   /* suppose I need to access the name 
  326.                                   tag's index */
  327.       
  328.          d4init( &c4 ) ;
  329.       
  330.          c4.auto_open = 0 ;  /* no group file */
  331.          d4 = d4open( &c4, "ADDRESS" ) ;
  332.       
  333.          name_tag = t4open( d4, 0, "NAME.NTX" ) ;  /* optional if .ntx */
  334.          phone_tag = t4open( d4, 0, "PHONE" ) ;
  335.          zip_tag = t4open( d4, 0, "ZIP" ) ;
  336.  
  337.       
  338.          name_ind = d4index( d4, "NAME.NTX" ) ;  
  339.       
  340.          d4tag_select( d4, name_tag ) ;  /* select name-ordering */
  341.       
  342.          i4reindex( name_ind ) ;  /* suppose my name tag is out of date,
  343.                                      so reindex */ 
  344.          /* ... rest of program ... */
  345.       
  346.          d4close( d4 ) ;  /* this will automatically close everything */
  347.       }
  348.  
  349.