home *** CD-ROM | disk | FTP | other *** search
/ Shareware 1 2 the Maxx / sw_1.zip / sw_1 / PROGRAM / BFAST.ZIP / BFAST.DOC next >
Text File  |  1992-03-19  |  12KB  |  416 lines
  1. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  2.                       bFAST version 1.0
  3.  
  4.            C++ class library for Btrieve file manipulation
  5.  
  6.                   Copyright (c) 1992 by Chaolin Chang
  7.  
  8.            Chaolin Chang
  9.            34 Bettina Street, Clayton,
  10.            Vic., Australia, 3168
  11.  
  12.            Voice: +61 3 565-2360
  13.            Fax  : +61 3 565-5159
  14.  
  15.            Internet: chaolin@fcit-m1.fcit.monash.edu.au
  16.  
  17.           This library is distributed as is. The author assumes no
  18.           liability for any damages resulting from its use.
  19. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  20. COMMERCIAL
  21. ----------
  22. This library is distributed as shareware.
  23. Since it is only used for evaluation,
  24. a message "Unregistered bFAST copy" will be displayed on screen
  25. whenever a date file is opened.
  26.  
  27. You may make copies of it for evaluation and distribution
  28. but if you would like to use the library for your project
  29. you should register it.
  30.  
  31. The cost is US$36/user. (or A$36 if you are in Australia/N.Z.)
  32.  
  33. Registered users will receive a disk containing the library without
  34. the "Unregistered bFAST copy" message.
  35.  
  36. Please feel free to distribute the library.  But no charge
  37. should be incurred on the person you distribute the library to.
  38.  
  39.  
  40. FILES INCLUDED
  41. --------------
  42. The library included here is compiled by Borland C++ 3.0.
  43. If you are using different compiler, let me know.
  44. I see if I can create a specific library for you.
  45.  
  46. BFAST.DOC       // Documentation
  47. BFAST.LIB       // Borland C++ 3.0 library
  48. RDBMS.HPP       // where the class Rdbms is defined
  49. FIELD.HPP       // where the class Field is defined
  50. BTRIEVE.HPP     // where the class Btrieve is defined
  51.  
  52. DEMO.CPP        // demo file
  53. ORDER.DEF       // demo field definition file
  54. ORDER.DAT       // demo order data file
  55. ORDER.HPP       // demo field symbol file
  56. DEMO.EXE        // demonstration program
  57.  
  58. BROWSE.CPP      // demo of browse
  59. BROWSE.EXE      // browse demo program
  60.  
  61.  
  62. WHAT IS bFAST?
  63. --------------
  64. bFAST is not developed to meet the market needs.
  65. Instead, it is here because I need such a library for my project.
  66. My project has 10+ executable files and 100+ source files.
  67. This small library works fine for my project.
  68. So, I think it should work for your project as well.
  69. This library, by no means, has included all the functions offered by Btrieve.
  70. Yet, it is sufficient for almost any project.
  71. Given that you are not using transaction or external index.
  72.  
  73. If you happen to use those functions not included.
  74. Luckily, now we are in the world of C++.
  75. You can easily create a derived class from the class Btrieve to do whatever
  76. bFAST has not implemented.
  77.  
  78. bFAST has the following class hierarchy
  79.  
  80. Rdbms         Field
  81.    └─────┬──────┘
  82.       Btrieve
  83.  
  84. If you like, you can use the base class Rdbms to derive another class
  85. for accessing Xbase files.  In this way, you will be able to access
  86. different data files using the same source code.
  87.  
  88. I would like to share bFAST with anyone who is interesting in it.
  89. Any of your comments will be greatly appreciated.
  90.  
  91. --------------------------------------------------------------------------
  92. To use bFAST is simple, just follow the 4 steps below.
  93.  
  94. 4 STEPS TO USE bFAST
  95.  
  96. Step 0 - acquire rdbms.hpp field.hpp btrieve.hpp bfast.lib
  97. Step 1 - create file definition file            *.def
  98. Step 2 - create field symbol file               *.hpp
  99. Step 3 - include bFAST.LIB in your project file
  100.  
  101. Step 0
  102. I assume that you know where to put the *.hpp file and *.lib file.
  103. Therefore, let's skip the step 0.
  104.  
  105. Step 1
  106. CREATE FILE DEFINITION FILE     *.DEF
  107.  
  108.     structure for each field
  109.  
  110.     typedef struct
  111.     {
  112.         char* FldName;  // field title
  113.         char  FldType;
  114.         int   offset;
  115.         int   FldLen;
  116.     }Field;
  117.  
  118.     Eg. contents of a .def file
  119.  
  120.     #include "field.hpp"
  121.  
  122.     #define  ORDER_FIELD        17
  123.  
  124.     Field cord[]={
  125.     {"Order Reference"   ,'c',0                                         ,13},
  126.     {"Customer"          ,'c',13                                        ,13},
  127.     {"Date Ordered"      ,'c',13+13                                     ,9 },
  128.     {"Note"              ,'c',13+13+9                                   ,49},
  129.     {"Open/Close"        ,'c',13+13+9+49                                ,2 },
  130.     {"Customer branch"   ,'c',13+13+9+49+2                              ,13},
  131.     {"Time Ordered"      ,'c',13+13+9+49+2+13                           ,9 },
  132.     {"Personal contact"  ,'c',13+13+9+49+2+13+9                         ,21},
  133.     {"Service type"      ,'c',13+13+9+49+2+13+9+21                      ,13},
  134.     {"Contract reference",'c',13+13+9+49+2+13+9+21+13                   ,13},
  135.     {"Sales tax number"  ,'c',13+13+9+49+2+13+9+21+13+13                ,13},
  136.     {"Customer account"  ,'l',13+13+9+49+2+13+9+21+13+13+13             ,4 },
  137.     {"Salesman"          ,'c',13+13+9+49+2+13+9+21+13+13+13+4           ,13},
  138.     {"Sales area"        ,'c',13+13+9+49+2+13+9+21+13+13+13+4+13        ,13},
  139.     {"Sales code"        ,'c',13+13+9+49+2+13+9+21+13+13+13+4+13+13     ,13},
  140.     {"Deduct forecast"   ,'c',13+13+9+49+2+13+9+21+13+13+13+4+13+13+13  ,2 },
  141.     {"Text"              ,'c',13+13+9+49+2+13+9+21+13+13+13+4+13+13+13+2,59},
  142.     };
  143.  
  144. Step 2
  145. CREATE FIELD SYMBOL FILE        *.HPP
  146.  
  147. The field symbol file is used to accessed a field, either
  148. replace the contents of a field or retrieve the contents of a field.
  149. You can find example in the end of the function lists.
  150.  
  151.     eg. contents of a .hpp file
  152.  
  153.     #define ORDER_REFERENCE          0
  154.     #define CUSTOMER                 1
  155.     #define DATE_ORDERED             2
  156.     #define NOTE                     3
  157.     #define OPEN_CLOSE               4
  158.     #define CUSTOMER_BRANCH          5
  159.     #define TIME_ORDERED             6
  160.     #define PERSONAL_CONTACT         7
  161.     #define SERVICE_TYPE             8
  162.     #define CONTRACT_REFERENCE       9
  163.     #define SALES_TAX_NUMBER         10
  164.     #define CUSTOMER_ACCOUNT         11
  165.     #define SALESMAN                 12
  166.     #define SALES_AREA               13
  167.     #define SALES_CODE               14
  168.     #define DEDUCT_FORECAST          15
  169.     #define TEXT                     16
  170.  
  171.  
  172. FUNCTION LISTS
  173. --------------------------------------------------------------------------
  174. //
  175. // after any function call, you can always use
  176. // Err()
  177. // to check if the operation is successful.
  178. //
  179. Open a file
  180.     Btrieve(char* path, char *filename,Field xfld[],int fldNo,int keyNo=0);
  181.  
  182.     eg.
  183.         Btrieve f("", "ORDER.DAT", cord, ORDER_FIELD);
  184.  
  185.         This statement open file ORDER.DAT in current working directory.
  186.         Its field definition is defined in cord.
  187.         It has ORDER_FIELD number of fields.
  188.         The defualt key is used, whihc is key 0.
  189.  
  190.  
  191.         Btrieve f("C:\\DAT", "ORDER.DAT", cord, ORDER_FIELD);
  192.  
  193.         this statement open file ORDER.DAT in directory C:\DAT
  194.  
  195.  
  196. Deconstructor
  197.     ~Btrieve();
  198.  
  199.     ~Btrieve will automatically close a file
  200.  
  201. --------------------------------------------------------------------------
  202. FILE STATUS
  203. -----------
  204. Get the file name
  205.         char* FileName(void);
  206.  
  207. Get the current working directory
  208.         char* Path(void);
  209.  
  210. Return the error code
  211.         int Err(void);
  212.  
  213. Length of a index key
  214.     int KeyLength(int keyNo);
  215.     int KeyLength(void);
  216.  
  217. Index key currently used
  218.     int IndexNo(void);
  219.  
  220. Change index key
  221.     int UseIndex(int key=0);
  222.  
  223. Current index key value
  224.     char * KeyValue();
  225.  
  226. Length of record buffer
  227.     int DataLen(void);
  228.  
  229. Open a file (internal use)
  230.     int Open(void);
  231.  
  232. Close a file
  233.     int Close(void);
  234.  
  235. Check if end of a file
  236.     int Eof(void);
  237.  
  238. Check if beginning of a file
  239.     int Bof(void);
  240.  
  241. Check if a empty file
  242.     int Empty(void);
  243.  
  244. Unlock a record
  245.     int Unlock(void);
  246.  
  247.  
  248. ----------------------------------------------------------------------------
  249. RECORD ACCESSING
  250. ----------------
  251. Indexed file
  252. Get the first record
  253.     int GetFirst(int lock=0);
  254.  
  255. Get the record which the key is equal to specified value
  256.     int GetEqual(char* keyvalue, int lock=0);
  257.  
  258. Get the last record
  259.     int GetLast(int lock=0);
  260.  
  261. Get the next record
  262.     int GetNext(int lock=0);
  263.  
  264. Get the previous record
  265.     int GetPrev(int lock=0);
  266.  
  267. Get the record which the key is greater or equal to a specified value
  268.     int GetGEqual(char* keyvalue, int lock=0);
  269.  
  270.  
  271. Get the record which the key is greater to a specified value
  272.     int GetGreater(char* keyvalue, int lock=0);
  273.  
  274. Get the physical position of current record
  275.     long GetPost(int lock=0);
  276.  
  277. Go to specified physical position
  278.     int GoTo(long,int lock=0);
  279.     
  280. Sequential file
  281. ---------------
  282. Get the first record
  283.     int StepFirst(int lock=0);
  284.  
  285. Get the last record
  286.     int StepLast(int lock=0);
  287.  
  288. Get the next record
  289.     int StepNext(int lock=0);
  290.  
  291. Get the previous record
  292.     int StepPrev(int lock=0);
  293.  
  294. --------------------------------------------------------------------------
  295. FILE UPDATION
  296. -------------
  297. Rewrite the record
  298.     int Rewrite(void);
  299.  
  300. Inser a new record
  301.     virtual int Write(void);
  302.  
  303. Delete the current record
  304.     int Delete(void);
  305.  
  306.  
  307. --------------------------------------------------------------------------
  308. FIELD MANIPULATION
  309. ------------------
  310. //
  311. // In field manipulation, every field can be referenced either by
  312. //
  313. // 1. using its field name, which is defined in the structure Field
  314. //
  315. // eg.
  316. //    f.fReplace("Order Reference", "123456789012");
  317. //
  318. // 2. using its relative position from the first field, which is defined
  319. //    to zero.
  320. //
  321. // eg.
  322. //
  323. //    #define SALES_ORDER_REF   0
  324. //    #define CUSTOMER          1
  325. //
  326. //
  327. //    f.fReplace(SALES_ORDER_REF, "123456789012");
  328. //    f.fReplace(CUSTOMER,        "ABC Co.");
  329. //
  330. //
  331. UPDATE A FIELD
  332. --------------
  333. //
  334. // All fReplace() return
  335. // 1 - successful
  336. // 0 - error
  337. //
  338. Replace a string field
  339.     int fReplace(int ,char *  );
  340.     int fReplace(char* ,char *  );
  341.  
  342. Replace an integer field
  343.     int fReplace(int ,int  );
  344.     int fReplace(char*,int  );
  345.  
  346. Replace a long field
  347.     int fReplace(int ,long );
  348.     int fReplace(char*,long );
  349.  
  350. Replace a float field
  351.     int fReplace(int ,float);
  352.     int fReplace(char*,float);
  353.  
  354. Replace a double field
  355.     int fReplace(int ,double);
  356.     int fReplace(char*,double);
  357.  
  358. GET THE CONTENTS OF A FIELD
  359. ---------------------------
  360. //
  361. Get every type of field in string format
  362.  
  363.     char* fStr(int i=0, const char *ptemplate="%s");
  364.     char* fStr(char * str, const char *ptemplate="%s");
  365.  
  366.     eg.
  367.          #define SALES_ORDER_REF   0
  368.          #define CUSTOMER          1
  369.  
  370.          char salesOrder[13];
  371.  
  372.          strcpy(salesOredr, f.fStr(SALES_ORDER_REF));
  373.  
  374.          or
  375.  
  376.          strcpy(salesOredr, f.fStr("Order Reference"));
  377.  
  378.  
  379.  
  380. Get a character field
  381.  
  382.     char   fChar(int);
  383.     char   fChar(char *  );
  384.  
  385.     #define ORDER_REFERENCE     0
  386.     #define CUSTOMER            1
  387.     #define DATE_ORDERED        2
  388.     #define NOTE                3
  389.     #define OPEN_CLOSE          4
  390.  
  391.     if (f.fChar(OPEN_CLOSE)=='Y')
  392.        ...
  393.  
  394.  
  395. Get an integer field
  396.  
  397.     int   fInt(int);
  398.     int   fInt(char *  );
  399.  
  400.  
  401. Get a long field
  402.  
  403.     long  fLong(int);
  404.     long  fLong(char * );
  405.  
  406. Get a float field
  407.  
  408.     float fFloat(int);
  409.     float fFloat(char *);
  410.  
  411. Get a double field
  412.  
  413.     double  fDouble(int);
  414.     double  fDouble(char *);
  415.  
  416.