home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / C / CROUTE / TABLE.DOC < prev    next >
Text File  |  1988-12-07  |  17KB  |  448 lines
  1.  
  2.  
  3.             Paradox "C" Language Table Routines
  4.  
  5.                                 1. Overview
  6.                                 -----------
  7.  
  8.     These routines define a simple interface to allow non-indexed Paradox
  9.     tables to be accessed from outside of the Paradox environment.
  10.  
  11.     Terminology: instead of "file", "table"; and instead of "record", "row".
  12.  
  13.     Calls are provided to open or create (and automatically open) a table.
  14.     These calls return a pointer to a structure of type TABLE, which
  15.     contains basic information about the table.  This pointer is then used in
  16.     all subsequent calls to the other table routines.  The user names a
  17.     table by providing an optional pathname followed by a one to eight
  18.     character table name that meets DOS naming conventions.  The extensions
  19.     used (such as .db) are hidden.  In the create call the user defines the 
  20.     name of the table, the number of the fields, and for each field its
  21.     type (one of D, $, N, S, or Annn) and name.  Fields are numbered
  22.     from one.
  23.  
  24.     Once a table is opened, calls are provided to position to a row, called
  25.     the current row, and then get or put fields in that row.  Rows are 
  26.     numbered from one to the number of rows in the table.  Row numbers
  27.     are longs, not ints.  New rows are created by appending a row with empty 
  28.     fields to the end of the table.  That row then becomes the current row.  
  29.     Rows may not be inserted or deleted.  Changed fields are automatically 
  30.     written to the table.    
  31.         
  32.     The data in the fields is seen by the user in display representation
  33.     (that is, a null terminated ascii string).  The underlying data structure
  34.     is deliberately hidden with the exception of four routines that allow
  35.     the user to translate between Paradox numeric formats and "C" numeric
  36.     formats.
  37.  
  38.     In the event of an error return the global int tError contains
  39.     a detailed error code.  The codes are documented in table.h.
  40.     The routine tErrMsg returns an ascii interpretation of the error number.  
  41.     The tError variable is set after every call to a table routine where 0 
  42.     indicates no error.
  43.  
  44.     At this time indexed and encrypted files are not supported.  The create
  45.     call has a parameter reserved for the number of indexed fields, allowing
  46.     for eventual indexed file support.  Encryption will be supported through
  47.     a separate call once the table is open. 
  48.  
  49.                     2. Synopsis of routines
  50.                     -----------------------
  51.     
  52.     ----------------------------- tExist -----------------------------------
  53.  
  54.     tExist tells whether a table exists.  It is useful as an error check 
  55.     before defining a new table. tExist returns TRUE if table exists; 
  56.     FALSE if it does not or there was an error.
  57.  
  58.         int tExist(tName);
  59.     char *tName;            ** asciiz table name, optionally preceded 
  60.                             ** by a path name.  
  61.  
  62.     ----------------------------- tDelete -----------------------------------
  63.  
  64.     tDelete deletes a table.  tDelete returns TRUE if table was successfully
  65.     deleted; FALSE if there was an error.
  66.                                         
  67.         int tDelete(tName);
  68.     char *tName;            ** asciiz table name, optionally preceded 
  69.                                 ** by a path name.  
  70.  
  71.     ----------------------------- tEmpty -----------------------------------
  72.  
  73.     tEmpty deletes all records in a table but retains the table's structure.
  74.     tEmpty returns TRUE if table was successfully emptied; FALSE if there was
  75.     an error.  The table MUST NOT be open when this function is called.
  76.                                         
  77.         int tEmpty(tName);
  78.     char *tName;            ** asciiz table name, optionally preceded 
  79.                                 ** by a path name.  
  80.  
  81.     ----------------------------- tCreate ----------------------------------
  82.  
  83.     tCreate creates and opens a table named by tName.
  84.     The user must specify the number of fields, their names, and their data
  85.     types.  Any existing table with the same name is deleted.
  86.  
  87.     Field names are represented as asciiz strings with up to twenty-five
  88.     characters that meet the Paradox rules for a field name.
  89.  
  90.     Field types must also meet Paradox rules; they are one of "D",
  91.     "$", "N", "S", or "Annn" where "nnn" is 1 to 255.
  92.  
  93.     tCreate returns a pointer to a structure of type TABLE or NULL (for
  94.     an error condition).
  95.  
  96.         TABLE *tCreate(tName,nFields,nameList,typeList,nIdxFields);
  97.     char *tName;                ** asciiz table name, optionally preceded 
  98.                                     ** by a path name.
  99.     int nFields;                ** number of fields (1 to 255)
  100.     char *nameList[];           ** array of pointers to field names
  101.     char *typeList[];           ** array of pointers to field types
  102.     int nIdxFields;             ** number index fields, 0 for now
  103.  
  104.  
  105.                     2. Synopsis of routines (cont'd)
  106.                     --------------------------------
  107.     
  108.  
  109.     ----------------------------- tOpen ------------------------------------
  110.                                 
  111.     tOpen opens an existing table named by tName and returns a pointer 
  112.     to a structure of type TABLE or NULL (for an error condition).
  113.     The current row is set to 1.
  114.  
  115.         TABLE *tOpen(tName);
  116.     char *tName;                ** asciiz table name, optionally preceded 
  117.                                     ** by a path name.
  118.  
  119.     ----------------------------- tNextRow ---------------------------------
  120.  
  121.     tNextRow moves the current row in the table associated with tablePtr 
  122.     to the next row.  Trying to move past the last row in the table
  123.     is an error.  The new row number or (long)ERROR is returned.
  124.  
  125.         long tNextRow(tablePtr);
  126.     TABLE *tablePtr;          
  127.  
  128.     ----------------------------- tPrevRow ---------------------------------
  129.  
  130.     tPrevRow moves the current row in the table associated with tablePtr 
  131.     to the previous row.  Trying to move before the first row in the table
  132.     is an error.  The new row number or (long)ERROR is returned.
  133.  
  134.         long tPrevRow(tablePtr);
  135.     TABLE *tablePtr;          
  136.  
  137.     ----------------------------- tTell ---------------------------------
  138.  
  139.     tTell gets the current row number in the table associated with tablePtr.
  140.     tTell returns the current row number, zero if the table is empty, or 
  141.     (long)ERROR.
  142.  
  143.         long tTell(tablePtr);
  144.     TABLE *tablePtr;          
  145.  
  146.     ----------------------------- tNumRows ---------------------------------
  147.  
  148.     tNumRows gets the number of rows in the table associated with tablePtr.
  149.     The number of rows (including zero for an empty table) or (long)ERROR 
  150.     is returned.
  151.  
  152.         long tNumRows(tablePtr);
  153.     TABLE *tablePtr;          
  154.  
  155.     ----------------------------- tAppend ---------------------------------
  156.  
  157.     tAppend creates an empty row after the last row in the table associated 
  158.     with tablePtr, and moves the current row in the table to that row.
  159.     The new row number or (long)ERROR is returned.
  160.  
  161.     tAppend is the only way provided to create new rows.
  162.  
  163.         long tAppend(tablePtr);
  164.     TABLE *tablePtr;          
  165.  
  166.                     2. Synopsis of routines (cont'd)
  167.                     --------------------------------
  168.  
  169.  
  170.     ----------------------------- tSeek ------------------------------------
  171.  
  172.     tSeek moves the current row in the table associated with tablePtr 
  173.     to a new row that is offset rows from origin.  Origin must be one
  174.     of the following constants:  
  175.  
  176.             Origin  Definition
  177.             ------  --------------------    
  178.  
  179.                 0   Beginning of table (first row in table)
  180.                 1   Current row in table
  181.                 2   End of table (last row in table)
  182.  
  183.     The new row number or (long)ERROR is returned.
  184.  
  185.         long tSeek(tablePtr,offset,origin);
  186.     TABLE *tablePtr;          
  187.     long offset;                ** number of rows from origin
  188.     int origin;                 ** initial position
  189.  
  190.     ----------------------------- tClose -----------------------------------
  191.  
  192.     tClose closes the table associated with tablePtr.  If the close was
  193.     successful, 0 is returned; otherwise ERROR.
  194.  
  195.         int tClose(tablePtr);
  196.     TABLE *tablePtr;          
  197.  
  198.     ----------------------------- tNumFlds -------------------------------
  199.  
  200.     tNumFlds returns the number of fields in the table associated with 
  201.     tablePtr or ERROR.
  202.  
  203.         int tNumFlds(tablePtr);
  204.     TABLE *tablePtr;          
  205.  
  206.     ----------------------------- tFldType ---------------------------
  207.  
  208.     tFldType copies the type of field fieldNum in the table associated
  209.     with tablePtr to the variable fieldType.  Values will be one of "D",
  210.     "$", "N", "S", or "Annn" where "nnn" is 1 to 255.
  211.  
  212.     tFldType returns a pointer to fieldType, or NULL (for an error).
  213.  
  214.         char *tFldType(tablePtr,fieldNum,fieldType);
  215.     TABLE *tablePtr;          
  216.     int fieldNum;               ** filed number, from one
  217.     char *fieldType;            ** user supplied array for field type;
  218.                                     ** must be at least 5 bytes
  219.  
  220.                     2. Synopsis of routines (cont'd)
  221.                     --------------------------------
  222.     
  223.  
  224.     ----------------------------- tFldName ---------------------------
  225.  
  226.     tFldName copies the name of field fieldNum in the table associated
  227.     with tablePtr to the variable fieldName.  
  228.  
  229.     tFldName returns a pointer to fieldName, or NULL (for an error).
  230.  
  231.         char *tFldName(tablePtr,fieldNum,fieldName);
  232.     TABLE *tablePtr;          
  233.     int fieldNum;               ** filed number, from one
  234.     char *fieldName;            ** user supplied array for field name;
  235.                                     ** must be at least 26 bytes
  236.  
  237.     ----------------------------- tFldNum ---------------------------
  238.  
  239.     tFldNum returns the field number for the field name in fieldName,
  240.     in the table associated with tablePtr, or ERROR.
  241.  
  242.     tFldNum allows the user to identify the fields in a table by name
  243.     instead of number.
  244.  
  245.         int tFldNum(tablePtr,fieldName);
  246.     TABLE *tablePtr;          
  247.     char *fieldName;            ** user supplied field name;
  248.  
  249.     ----------------------------- tFldPut ---------------------------
  250.  
  251.     tFldPut puts the value specified in fieldVal into field fieldNum in the
  252.     table associated with tablePtr.  If the routine fails, FALSE is
  253.     returned; else TRUE.
  254.  
  255.     tFldPut first validates the data, and then translates it into the Paradox
  256.     data representation.
  257.  
  258.         int tFldPut(tablePtr,fieldNum,fieldVal);
  259.     TABLE *tablePtr;          
  260.     int fieldNum;               ** field number for the value
  261.     char *fieldVal;             ** user supplied value as asciiz string.
  262.  
  263.     ----------------------------- tFldValidate ---------------------------
  264.  
  265.     tFldValidate validates the value specified in fieldVal against the
  266.     type specified in fieldType.  If successful, TRUE is returned, else
  267.     FALSE.
  268.  
  269.         int tFldValidate(fieldVal,fieldType);
  270.     char *fieldVal;             ** user supplied value as asciiz string.
  271.     char *fieldType;            ** user supplied field type
  272.  
  273.  
  274.                     2. Synopsis of routines (cont'd)
  275.                     --------------------------------
  276.     
  277.  
  278.     ----------------------------- tFldGet ---------------------------
  279.  
  280.     tFldGet gets the value from field fieldNum into fieldVal in the
  281.     table associated with tablePtr.  If the routine fails, FALSE is
  282.     returned; else TRUE.
  283.  
  284.     The value is returned as an asciiz string; the user must ensure
  285.     that the array fieldVal is large enough.  See the routine tMaxTypeSize
  286.     below.
  287.  
  288.         int tFldGet(tablePtr,fieldNum,fieldVal);
  289.     TABLE *tablePtr;          
  290.     int fieldNum;               ** field number for the value
  291.     char *fieldVal;             ** user supplied value as asciiz string.
  292.  
  293.     ----------------------------- tMaxTypeSize ----------------------
  294.  
  295.     tMaxTypeSize returns the maximum size in the internal representation 
  296.     for a given type, or ERROR.
  297.  
  298.         int tMaxTypeSize(fieldType);
  299.     char *fieldType;            ** field type; i.e. "D", "$", "N", "S",
  300.                                     ** or "Annn"
  301.  
  302.     ----------------------------- tErrMsg ---------------------------
  303.  
  304.     tErrMsg places an ascii interpretation of the current error number
  305.     in tError into errMsg and returns a pointer to errMsg.
  306.  
  307.     The caller must ensure that errMsg has a size of at least 65 bytes.
  308.  
  309.         char *tErrMsg(errMsg);
  310.     char *errMsg;           ** user supplied array with size >= 65 bytes
  311.     
  312.     ----------------------------- tShortPut -----------------------------
  313.  
  314.     tShortPut puts the value specified in shortVal into field fieldNum
  315.     in the table associated with tablePtr.  If the routine fails, FALSE
  316.     is returned, otherwise TRUE.
  317.  
  318.     tShortPut checks to see that the field specified by fieldNum is a
  319.     Paradox short (S) field.  If it is, the value in shortVal is stored in
  320.     the field and TRUE is returned.  If fieldNum is not a short field, no
  321.     values are updated and FALSE is returned.
  322.  
  323.         int tShortPut(tablePtr,fieldNum,shortVal);
  324.     TABLE *tablePtr;
  325.     int fieldNum;            ** field number for the value
  326.     int shortVal;            ** user supplied data value
  327.  
  328.  
  329.                     2. Synopsis of routines (cont'd)
  330.                     --------------------------------
  331.  
  332.     ----------------------------- tNumPut -----------------------------
  333.  
  334.     tNumPut puts the value specified in doubleVal into field fieldNum
  335.     in the table associated with tablePtr.  If the routine fails, FALSE
  336.     is returned, otherwise TRUE.
  337.  
  338.     tNumPut checks to see that the field specified by fieldNum is a
  339.     Paradox number (N) or dollar ($) field.  If it is, the value in
  340.     doubleVal is stored in the field and TRUE is returned.  If fieldNum is
  341.     neither a number nor a dollar field, no values are updated and FALSE
  342.     is returned.
  343.  
  344.         int tNumPut(tablePtr,fieldNum,doubleVal);
  345.     TABLE *tablePtr;
  346.     int fieldNum;            ** field number for the value
  347.     double doubleVal;        ** user supplied data value
  348.  
  349.     ----------------------------- tShortGet -----------------------------
  350.  
  351.     tShortGet gets the value from field fieldNum in the table associated
  352.     with tablePtr into shortVal.  If the routine fails, FALSE is returned.
  353.     If the routine succeeds but the value in field fieldNum is null, ERROR
  354.     is returned, otherwise TRUE.
  355.  
  356.     tShortGet checks to see that the field specified by fieldNum is a
  357.     Paradox short (S) field.  If it is, the value in field fieldNum is
  358.     stored in shortVal and TRUE is returned.  If fieldNum is not a short
  359.     field or contains a null value, shortVal remains unchanged and FALSE
  360.     or ERROR, respectively, is returned.
  361.  
  362.         int tShortGet(tablePtr,fieldNum,shortVal);
  363.     TABLE *tablePtr;
  364.     int fieldNum;            ** field number for the value
  365.     int *shortVal;            ** user supplied data area
  366.  
  367.     ----------------------------- tNumGet -----------------------------
  368.  
  369.     tNumGet gets the value from field fieldNum in the table associated
  370.     with tablePtr into doubleVal.  If the routine fails, FALSE is
  371.     returned.  If the routine succeeds but the value in field fieldNum is
  372.     null, ERROR is returned, otherwise TRUE.
  373.  
  374.     tNumGet checks to see that the field specified by fieldNum is a
  375.     Paradox number (N) or dollar ($) field.  If it is, the value in field
  376.     fieldNum is stored in doubleVal and TRUE is returned.  If fieldNum is
  377.     neither a number nor a dollar field or it contains a null value,
  378.     doubleVal remains unchanged and FALSE or ERROR, respectively, is
  379.     returned.
  380.  
  381.         int tNumGet(tablePtr,fieldNum,doubleVal);
  382.     TABLE *tablePtr;
  383.     int fieldNum;            ** field number for the value
  384.     double *doubleVal;        ** user supplied data area
  385.  
  386.  
  387.                     3. Sample code fragment
  388.                     -----------------------
  389.     
  390.     The sample code below shows the creation of a data base
  391.     that contains average weekly cookie consumptions for selected Ansa
  392.     employees.
  393.  
  394.         static char *names[] = {
  395.             "Employee Name",
  396.         "Cookies/Week"
  397.     };
  398.  
  399.     static char *types[] = {
  400.         "A25",
  401.         "N"
  402.     };
  403.  
  404.     TABLE *cookie;
  405.  
  406.     /* symbolic field definitions */
  407.  
  408.     #define EMPLOYEE    1
  409.     #define COOKIES     2
  410.  
  411.     if ( (cookie = tCreate("cookie",2,names,types,0)) == NULL)
  412.             errorExit();
  413.  
  414.     tAppend(cookie);
  415.     tFldPut(cookie,EMPLOYEE,"Gorman");
  416.     tFldPut(cookie,COOKIES,"17");
  417.  
  418.     tAppend(cookie);
  419.     tFldPut(cookie,EMPLOYEE,"Nielsen");
  420.     tFldPut(cookie,COOKIES,"19");
  421.  
  422.     .
  423.     .
  424.  
  425.     tClose(cookie);
  426.  
  427.  
  428.     Compilers supported
  429.     -------------------
  430.  
  431.         Library name            Compiler
  432.     ------------            --------
  433.  
  434.     TABLETS.LIB*            Turbo "C" verrsion 1.5 small model
  435.     TABLETL.LIB*            Turbo "C" verrsion 1.5 large model
  436.  
  437.     TABLETS2.LIB            Turbo "C" verrsion 2.0 small model
  438.     TABLETL2.LIB            Turbo "C" verrsion 2.0 large model
  439.  
  440.     TABLEMS.LIB            Microsoft "C" version 4.0 small model
  441.     TABLEML.LIB            Microsoft "C" version 4.0 large model
  442.  
  443.     TABLEMS5.LIB            Microsoft "C" version 5.0 small model
  444.     TABLEML5.LIB            Microsoft "C" version 5.0 large model
  445.  
  446.  
  447.     * not compatible with Turbo "C" 2.0 libraries
  448.