home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Product / Product.zip / viper092.zip / REXXAPI.TXT < prev    next >
Text File  |  1995-09-20  |  18KB  |  659 lines
  1. VIPER Database Engine (TM) (PREVIEW RELEASE 0.9.2)
  2.  
  3.  
  4. REXX Language API  
  5. Copyright (c) - 1995 by Douglas A. Bebber
  6.  
  7.  
  8.  
  9. This document provides a brief function reference for the VIPER Database Engine - REXX API.
  10. Detailed information will be provided in the VIPER Database Engine (version 1.0.0) Technical
  11. Reference Manual. 
  12.  
  13. NOTE:  The complete VIPER Database Engine source code will be made freely available in a 
  14. subsequent release.
  15.  
  16. This PREVIEW RELEASE of the VIPER Database Engine for OS/2 is being made available in
  17. an effort to accelerate the version 1.0.0 general release. Consider this PREVIEW RELEASE to
  18. be similar to a beta test period. I would like to obtain as much feedback as possible concerning
  19. bug reports and general usage in an effort to make any necessary changes prior to the version
  20. 1.0.0 general release.
  21.  
  22. Technical information for this PREVIEW RELEASE 0.9.2 concerns only the REXX API. Similar
  23. information concerning the C-Language API will be made in the PREVIEW RELEASE 0.9.5 .
  24.  
  25. Library Registration of all VIPER functions can be performed by calling the SysLoadViperFuncs
  26. call in the VIPER.DLL. Previous releases used SysLoadFuncs call. The SysLoadViperFuncs replaces
  27. the older SysLoadFuncs.
  28.  
  29. Please send any suggested additions or corrections to:
  30.  
  31. Douglas A. Bebber
  32.  
  33. CompuServe: 72123,3661
  34. Internet: 72123.3661@compuserve.com
  35.  
  36. -----------------------------------------------------------------------------
  37.              VIPER Database Engine for OS/2 REXX API Function Reference
  38. -----------------------------------------------------------------------------
  39. NOTE: All functions return 1 if successfull, 0 if an error resulted. Search functions are the
  40. exception. See the Search function descriptions for the details.
  41.  
  42. RxViperAddRecord
  43.  
  44. Description:
  45.  
  46. This function adds a record to a database. All database indexes are updated.
  47.  
  48. Syntax:
  49.  
  50. rc = RxViperAddRecord(DatabaseName, IndexName, FieldValues.)
  51.  
  52. where:
  53.         DatabaseName is a string containing the filename for the new database.
  54.         IndexName specifies a database index.
  55.         FieldValues. is a REXX stem variable containing the record information.
  56.         Each element of the REXX stem variable constitues a field. The first
  57.         element (FieldValues.0) contains the number of fields in the record.
  58.  
  59. Example:
  60.                 CREATEDB.CMD
  61.  
  62. -----------------------------------------------------------------------------
  63.  
  64. RxViperCloseDatabase
  65.  
  66. Description:
  67.  
  68. This function closes an open database.
  69.  
  70. Syntax:
  71.  
  72. rc = RxViperCloseDatabase(DatabaseName)
  73.  
  74. where:
  75.                 DatabaseName is a string containing the filename of the open database.
  76.         
  77. Example:
  78.                 CREATEDB.CMD
  79.  
  80. -----------------------------------------------------------------------------
  81.  
  82.  
  83. RxViperCopyDatabase
  84.  
  85. Description:
  86.  
  87. This function copies a database and its associated indexes.
  88.  
  89. Syntax:
  90.  
  91. rc = RxViperCopyDatabase(CurrentName, NewName, RefIndex, BlockSize)
  92.  
  93. where:
  94.                 CurrentName is a string containing the filename of the source database.
  95.                 NewName is a string containing the filename of the new database.
  96.                 RefIndex is the source index to reference during the copy process.
  97.                 BlockSize (specifying 0 uses the default block size).
  98.         
  99. Example:
  100.                 COPYDB.CMD
  101.  
  102. -----------------------------------------------------------------------------
  103.  
  104.  
  105. RxViperCreateDatabase
  106.  
  107. Description:
  108.  
  109. This function creates and opens a database for use.
  110.  
  111. Syntax:
  112.  
  113. rc = RxViperCreateDatabase(DatabaseName, FieldDefinition.)
  114.  
  115. where:
  116.         DatabaseName is a string containing the filename for the new database.
  117.         FieldDefinition is a REXX stem variable containing the database field definition.
  118.         FieldDefinition.0 contains the number of fields. FieldDefinition.1 - FieldDefinition.X
  119.         contain the field names.
  120.  
  121. Example:
  122.                 CREATEDB.CMD
  123.  
  124. -----------------------------------------------------------------------------
  125.  
  126.  
  127. RxViperCreateIndex
  128.  
  129. Description:
  130.  
  131. This function creates an index for the specified database.
  132.  
  133. Syntax:
  134.  
  135. rc = RxViperCreateIndex(DatabaseName, IndexName, KeyFields.)
  136.  
  137. where:
  138.         DatabaseName is a string containing the filename of the database.
  139.       
  140.         IndexName specifies the name of the new index.
  141.         
  142.         KeyFields. is a REXX stem variable containing the index key fields.
  143.         KeyFields.0 contains the number of key fields in the index. KeyFields.1 - KeyFields.X
  144.         contain the key field names.
  145.  
  146. Example:
  147.                 CREATEDB.CMD
  148.  
  149.  
  150. -------------------------------------------------------------------------------
  151.  
  152.  
  153. RxViperCreateNewIndexFile
  154.  
  155. Description:
  156.  
  157. This function creates a new index file for the specified database.
  158.  
  159. Syntax:
  160.  
  161. rc = RxViperCreateNewIndexFile(DatabaseName, BlockSize, OverWriteFlag)
  162.  
  163. where:
  164.         DatabaseName is a string containing the filename of the database.
  165.       
  166.         Block size for the new index file (0 uses default).
  167.         
  168.         OverWriteFlag specifies whether or not to overwrite an existing index file
  169.         if it exists. 0 = no overwrite, 1 = yes overwrite.
  170.  
  171.  
  172.  
  173. -------------------------------------------------------------------------------
  174.  
  175.  
  176. RxViperDeleteRecord
  177.  
  178. Description:
  179.  
  180. This function deletes the current database record using the specified index for the
  181. specified database.
  182.  
  183. Syntax:
  184.  
  185. rc = RxViperDeleteRecord(DatabaseName, IndexName )
  186.  
  187. where:
  188.                 DatabaseName is a string containing the filename of the open database.
  189.         
  190.                 IndexName is the name of the index to position realitive to.
  191.  
  192.                 
  193. Example:
  194.                 DELREC.CMD
  195.  
  196.  
  197. -------------------------------------------------------------------------------
  198.  
  199.  
  200. RxViperDestroyDatabase
  201.  
  202. Description:
  203.  
  204. This function deletes the current database and index files.
  205.  
  206. Syntax:
  207.  
  208. rc = RxViperDestroyDatabase(DatabaseName )
  209.  
  210. where:
  211.                 DatabaseName is a string containing the filename of the open database.
  212.         
  213.                 
  214.  
  215.                 
  216. Example:
  217.                 DESTRYDB.CMD
  218.  
  219.  
  220. -------------------------------------------------------------------------------
  221.  
  222.  
  223. RxViperDestroyIndex
  224.  
  225. Description:
  226.  
  227. This function deletes the specified index.
  228.  
  229. Syntax:
  230.  
  231. rc = RxViperDestroyIndex(DatabaseName, IndexName )
  232.  
  233. where:
  234.                 DatabaseName is a string containing the filename of the open database.
  235.         
  236.                 IndexName is a string containing the name of the index to destroy.
  237.                 
  238.  
  239.                 
  240.  
  241.  
  242. -------------------------------------------------------------------------------
  243.  
  244.  
  245. RxViperFlushDatabaseBuffers
  246.  
  247. Description:
  248.  
  249. This function writes buffered database changes to disk. The info is written to disk during the call.
  250.  
  251. Syntax:
  252.  
  253. rc = RxViperFlushDatabaseBuffers(DatabaseName)
  254.  
  255. where:
  256.                 DatabaseName is a string containing the filename of the open database.
  257.         
  258.  
  259. -----------------------------------------------------------------------------
  260.  
  261.  
  262. RxViperGetFieldNames
  263.  
  264. Description:
  265.  
  266. This function gets the names of the fields present in the specified database.
  267.  
  268. Syntax:
  269.  
  270. rc = RxViperGetFieldNames(DatabaseName, FieldNames. )
  271.  
  272. where:
  273.                 DatabaseName is a string containing the filename of the open database.
  274.  
  275.                 FieldNames. is a REXX stem variable that will contain the name of every
  276.                 database field upon return.
  277.  
  278. Note:           FieldNames.0 will contain the number of fields in the database. If you need
  279.                 to know the names of the fields as well as the number of fields in a database,
  280.                 you can use this single call to get the desired info. You do not need to make a
  281.                 separate call to GetNFields in this case.
  282.         
  283. Example:
  284.                 DBINFO.CMD
  285.  
  286.  
  287. -------------------------------------------------------------------------------
  288.  
  289.  
  290.  
  291. RxViperGetIndexDescription
  292.  
  293. Description:
  294.  
  295. This function gets the description of the the specified index for the specified database.
  296.  
  297. Syntax:
  298.  
  299. rc = RxViperGetIndexDescription(DatabaseName, IndexName, IndexDescription. )
  300.  
  301. where:
  302.                 DatabaseName is a string containing the filename of the open database.
  303.  
  304.                 IndexName is the name of the index to be described.
  305.  
  306.                 IndexDescription. is a REXX stem variable that will contain the name of every
  307.                 database field which makes up the index. IndexNames.0 will contain the total 
  308.                 number of fields which make up the index. The ordering of the stem variable is
  309.                 the same as the index field order.
  310.  
  311.         
  312. Example:
  313.                 DBINFO.CMD
  314.  
  315.  
  316. -------------------------------------------------------------------------------
  317.  
  318.  
  319. RxViperGetIndexNames
  320.  
  321. Description:
  322.  
  323. This function gets the names of the indexes available for the specified database.
  324.  
  325. Syntax:
  326.  
  327. rc = RxViperGetIndexNames(DatabaseName, IndexNames. )
  328.  
  329. where:
  330.                 DatabaseName is a string containing the filename of the open database.
  331.  
  332.                 IndexNames. is a REXX stem variable that will contain the name of every
  333.                 database index upon return. IndexNames.0 will contain the total number of
  334.                 indexes defined for the database.
  335.  
  336.         
  337. Example:
  338.                 DBINFO.CMD
  339.  
  340.  
  341. -------------------------------------------------------------------------------
  342.  
  343.  
  344.  
  345. RxViperGetNFields
  346.  
  347. Description:
  348.  
  349. This function gets the number of fields present in the specified database.
  350.  
  351. Syntax:
  352.  
  353. rc = RxViperGetNFields(DatabaseName )
  354.  
  355. where:
  356.                 DatabaseName is a string containing the filename of the open database.
  357.         
  358. Example:
  359.                 GETNFLDS.CMD
  360.  
  361.  
  362. -------------------------------------------------------------------------------
  363.  
  364.  
  365. RxViperGetRecord
  366.  
  367. Description:
  368.  
  369. This function gets the current database record using the specified index for the
  370. specified database.
  371.  
  372. Syntax:
  373.  
  374. rc = RxViperGetRecord(DatabaseName, IndexName, Fields.)
  375.  
  376. where:
  377.                 DatabaseName is a string containing the filename of the open database.
  378.         
  379.                 IndexName is the name of the index to position realitive to.
  380.  
  381.                 Fields. is the REXX stem variable to contain the returned database record.
  382. Example:
  383.                 GETREC.CMD
  384.  
  385.  
  386. -------------------------------------------------------------------------------
  387.  
  388.  
  389. RxViperMarkRecord
  390.  
  391. Description:
  392.  
  393. This function marks the current record in the database using the specified index. This function
  394. used in conjunction with the MoveToMarkedRecord is for implementing place holders.
  395.  
  396. Syntax:
  397.  
  398. rc = RxViperMarkRecord(DatabaseName, IndexName)
  399.  
  400. where:
  401.                 DatabaseName is a string containing the filename of the open database.
  402.         
  403.                 IndexName is the name of the index to position realitive to.
  404. Example:
  405.                 MARKREC.CMD
  406.  
  407.  
  408. ------------------------------------------------------------------------------
  409.  
  410.  
  411. RxViperMatchKey
  412.  
  413. Description:
  414.  
  415. This function determines if the current record in the database (using specified index) matches
  416. the key specified in the Key. function argument.
  417.  
  418. Syntax:
  419.  
  420. rc = RxViperMatchKey(DatabaseName, IndexName, Key.)
  421.  
  422. where:
  423.                 DatabaseName is a string containing the filename of the open database.
  424.         
  425.                 IndexName is the name of the index to position realitive to.
  426.  
  427.                 Key. is the REXX stem variable to contain the key for matching.
  428.  
  429.  
  430. -------------------------------------------------------------------------------
  431.  
  432.  
  433.  
  434. RxViperMoveToFirstRecord
  435.  
  436. Description:
  437.  
  438. This function moves the database cursor to the first record of the specified index for the
  439. specified database.
  440.  
  441. Syntax:
  442.  
  443. rc = RxViperMoveToFirstRecord(DatabaseName, IndexName)
  444.  
  445. where:
  446.                 DatabaseName is a string containing the filename of the open database.
  447.         
  448.                 IndexName is the name of the index to position realitive to.
  449. Example:
  450.                 GETREC.CMD
  451.  
  452.  
  453. ------------------------------------------------------------------------------
  454.  
  455.  
  456. RxViperMoveToLastRecord
  457.  
  458. Description:
  459.  
  460. This function moves the database cursor to the last record of the specified index for the
  461. specified database.
  462.  
  463. Syntax:
  464.  
  465. rc = RxViperMoveToLastRecord(DatabaseName, IndexName)
  466.  
  467. where:
  468.                 DatabaseName is a string containing the filename of the open database.
  469.         
  470.                 IndexName is the name of the index to position realitive to.
  471. Example:
  472.                 GETREC.CMD
  473.  
  474.  
  475. ------------------------------------------------------------------------------
  476.  
  477.  
  478. RxViperMoveToMarkedRecord
  479.  
  480. Description:
  481.  
  482. This function moves the database cursor to a previously marked record. The specified index 
  483. is referenced for the specified database.
  484.  
  485. Syntax:
  486.  
  487. rc = RxViperMoveToMarkedRecord(DatabaseName, IndexName)
  488.  
  489. where:
  490.                 DatabaseName is a string containing the filename of the open database.
  491.         
  492.                 IndexName is the name of the index to position realitive to.
  493. Example:
  494.                 MARKREC.CMD
  495.  
  496.  
  497. ------------------------------------------------------------------------------
  498.  
  499.  
  500. RxViperMoveToNextRecord
  501.  
  502. Description:
  503.  
  504. This function moves the database cursor to the next record of the specified index for the
  505. specified database.
  506.  
  507. Syntax:
  508.  
  509. rc = RxViperMoveToNextRecord(DatabaseName, IndexName)
  510.  
  511. where:
  512.                 DatabaseName is a string containing the filename of the open database.
  513.         
  514.                 IndexName is the name of the index to position realitive to.
  515. Example:
  516.                 GETREC.CMD
  517.  
  518. ------------------------------------------------------------------------------
  519.  
  520. RxViperMoveToPreviousRecord
  521.  
  522. Description:
  523.  
  524. This function moves the database cursor to the previous record of the specified index for the
  525. specified database.
  526.  
  527. Syntax:
  528.  
  529. rc = RxViperMoveToPreviousRecord(DatabaseName, IndexName)
  530.  
  531. where:
  532.                 DatabaseName is a string containing the filename of the open database.
  533.         
  534.                 IndexName is the name of the index to position realitive to.
  535. Example:
  536.                 GETREC.CMD
  537.  
  538.  
  539. ------------------------------------------------------------------------------
  540.  
  541.  
  542.  
  543. RxViperOpenDatabase
  544.  
  545. Description:
  546.  
  547. This function opens a database and the associated index for use.
  548.  
  549. Syntax:
  550.  
  551. rc = RxViperOpenDatabase(DatabaseName, IndexName)
  552.  
  553. where:
  554.                 DatabaseName is a string containing the filename of the database.
  555.                 IndexName is a string containing the name of the index to use.
  556.         
  557. Example:
  558.                 GETREC.CMD
  559.  
  560. -----------------------------------------------------------------------------
  561.  
  562.  
  563. RxViperRenameDatabase
  564.  
  565. Description:
  566.  
  567. This function renames a database and its associated index file.
  568.  
  569. Syntax:
  570.  
  571. rc = RxViperRenameDatabase(CurrentName, NewName)
  572.  
  573. where:
  574.                 CurrentName is a string containing the filename of the source database.
  575.  
  576.                 NewName is a string containing the new filename of the database.
  577.         
  578.  
  579. -----------------------------------------------------------------------------
  580.  
  581.  
  582. RxViperSearchKey
  583.  
  584. Description:
  585.  
  586. This function searches the database for a specific record using specified index. The search
  587. criteria is placed in the functions KeyFields. parameter.
  588.  
  589. Syntax:
  590.  
  591. rc = RxViperSearchKey(DatabaseName, IndexName, KeyFields. )
  592.  
  593. where:
  594.                 DatabaseName is a string containing the filename of the open database.
  595.         
  596.                 IndexName is the name of the index to search on.
  597.  
  598.                 KeyFields. is a REXX stem variable containing the index key search criteria.
  599.  
  600. Returns:        0 on error.
  601.                 1 if found.
  602.                 2 if not found (moved to the closest matching record).
  603. Example:
  604.                 SEARCHKY.CMD
  605.  
  606.  
  607. ------------------------------------------------------------------------------
  608.  
  609. RxViperSearchRecord
  610.  
  611. Description:
  612.  
  613. This function searches the database on the specified index for the record contained in the
  614. RecordInfo. REXX stem variable argument. 
  615.  
  616. Syntax:
  617.  
  618. rc = RxViperSearchRecord(DatabaseName, IndexName, RecordInfo. )
  619.  
  620. where:
  621.                 DatabaseName is a string containing the filename of the open database.
  622.         
  623.                 IndexName is the name of the index to search on.
  624.  
  625.                 RecordInfo. is a REXX stem variable containing the record search criteria.
  626.  
  627. Returns:        0 if error.
  628.                 1 if found.
  629.                 2 if not found.
  630.  
  631.  
  632. ------------------------------------------------------------------------------
  633.  
  634.  
  635.  
  636.  
  637. RxViperUpdateRecord
  638.  
  639. Description:
  640.  
  641. This function is used to change an existing record in the database.
  642.  
  643. Syntax:
  644.  
  645. rc = RxViperUpdateRecord(DatabaseName, IndexName, FieldValues.)
  646.  
  647. where:
  648.                 DatabaseName is a string containing the filename of the open database.
  649.         
  650.                 IndexName is the name of the index to position realitive to.
  651.  
  652.                 FieldValues. is a REXX stem variable containing the new record information.
  653. Example:
  654.                 UPDATREC.CMD
  655.  
  656.  
  657. ------------------------------------------------------------------------------
  658.  
  659.