home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / database / isam / isam.autodocs < prev    next >
Text File  |  1995-02-27  |  40KB  |  1,212 lines
  1. ===============================================================================
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. isam.library/CountISAMRecords
  6. isam.library/CloseISAMFile
  7. isam.library/CreateISAMFile
  8. isam.library/DeleteISAMFile
  9. isam.library/DeleteISAMRecord
  10. isam.library/DeleteISAMRecords
  11. isam.library/GetFirstLastISAMKeyValues
  12. isam.library/ISAMWhy
  13. isam.library/LockISAMFile
  14. isam.library/LockISAMRecord
  15. isam.library/ModifyISAMRecord
  16. isam.library/OpenISAMFile
  17. isam.library/ReadISAMRecord
  18. isam.library/ReadUniqueISAMRecord
  19. isam.library/ReadNextISAMKey
  20. isam.library/ReadNextISAMRecord
  21. isam.library/ReIndexISAMFile
  22. isam.library/ReportISAMStatus
  23. isam.library/SetUpISAMIterationRange
  24. isam.library/SetUpISAMIterationKey
  25. isam.library/SetUpISAMIterationPrefix
  26. isam.library/ShutDownISAM
  27. isam.library/StoreISAMRecord
  28. isam.library/UnLockISAMFile
  29. isam.library/UnLockISAMRecord
  30. isam.library/UnLockAllISAMRecords
  31.  
  32.  
  33.  
  34. ===============================================================================
  35.  
  36. isam.library/CountISAMRecords                     isam.library/CountISAMRecords
  37.  
  38.    NAME
  39.         CountISAMRecords -- count the number of records in an iteration
  40.  
  41.    SYNOPSIS
  42.         error = CountISAMRecords ( ISAMHandle, KeyNo, CountMax, Count )
  43.  
  44.         long CountISAMRecords ( ULONG, UWORD, ULONG, ULONG * );
  45.  
  46.    FUNCTION
  47.         This function counts the number of records that meet the criteria
  48.         of an iteration set up previously by SetUpISAMIteration(Range|Key|
  49.         Prefix).
  50.         (In effect, the function calls ReadNextISAMKey repeatedly until
  51.         ERROR_NO_MORE_RECORDS is returned).
  52.         If CountMax is zero, the counting will continue until the last record
  53.         meeting the criteria SetUp is found.
  54.         If CountMax is not zero, the counting will stop when the count equals
  55.         CountMax.  (Count will then == CountMax).
  56.  
  57.    NOTES
  58.         If no iteration is set up for the specified key, Count will be set to
  59.         zero.
  60.  
  61.         When this function finishes counting, it sets up the iteration again
  62.         at its starting point.  Since the iteration is re-set, it follows that
  63.         this function should only be called at the beginning of the iteration,
  64.         before any records/keys have been read.
  65.  
  66.    WARNINGS
  67.         Keep in mind that if any of the records whose keys match the
  68.         iteration are locked by another user, they may change between the
  69.         time you Count them and ReadNext them, and may not be in the iter-
  70.         ation any more (and may in fact have been deleted), so unless you are
  71.         able to lock the file prior to the Count, the number of records you
  72.         subsequently ReadNext may NOT match the Count.
  73.  
  74.         This is MUCH faster (and easier) than doing a SetUp/ReadNext loop
  75.         just to count records.  HOWEVER, if many records are involved, this
  76.         will NOT be instantaneous, and other users will be kept waiting.  If
  77.         counting many records is necessary, and there are always going to be
  78.         other users, then it would be preferable to "go the long route" of
  79.         doing a SetUp/ReadNext loop to count the records, as other users would
  80.         be able to "get in through the cracks" (between ReadNext calls).
  81.         
  82.    INPUTS
  83.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  84.  
  85.         KeyNo - the key number of the key upon which an iteration was set.
  86.  
  87.         CountMax - the maximum number of records to count, or zero.
  88.  
  89.         Count - a pointer to the location where the count will be returned.
  90.  
  91.    RESULTS
  92.         error - returns OK (#define'd as 0L), or an errorcode.
  93.  
  94.    BUGS
  95.  
  96.    SEE ALSO
  97.         SetUpISAMIteration(Range|Key|Prefix), ReadNextISAM(Record|Key)
  98.  
  99. ===============================================================================
  100.  
  101. isam.library/CloseISAMFile                           isam.library/CloseISAMFile
  102.  
  103.    NAME
  104.         CloseISAMFile -- close an ISAM file
  105.  
  106.    SYNOPSIS
  107.         error = CloseISAMFile ( ISAMHandle )
  108.  
  109.         long CloseISAMFile ( ULONG );
  110.  
  111.    FUNCTION
  112.         This function closes an ISAM file previously opened by OpenISAMFile.
  113.  
  114.    NOTES
  115.         When this function is called, all records in the file locked by the
  116.         user will be unlocked, and if the file was locked by the user, it
  117.         will be unlocked as well.  All iterations set up by the user will
  118.         be removed.  If the user was the only user, all memory constructs
  119.         tracking the file will be freed, the index header written back to the
  120.         index file, and the index and data files closed.
  121.  
  122.    INPUTS
  123.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  124.  
  125.    RESULTS
  126.         error - returns OK, or an errorcode.
  127.  
  128.    BUGS
  129.  
  130.    SEE ALSO
  131.         OpenISAMFile
  132.  
  133. ===============================================================================
  134.  
  135. isam.library/CreateISAMFile                         isam.library/CreateISAMFile
  136.  
  137.    NAME
  138.         CreateISAMFile -- create an ISAM file
  139.  
  140.    SYNOPSIS
  141.         error = CreateISAMFile ( SpecsFileName )
  142.  
  143.         long CreateISAMFile ( char * );
  144.  
  145.    FUNCTION
  146.         This takes the information describing the ISAM file from the Specs
  147.         File named and creates an ISAM file.  The Data File will be empty;
  148.         the Index File will contain the Index Header.
  149.         If the Data and/or Index Files exist already, they will be deleted.
  150.  
  151.    NOTES
  152.         The Specs file consists of a minimum of 4 (four) lines:
  153.            1. Data File path/name
  154.            2. Index File path/name
  155.            3. record size
  156.            4  key #0 specs
  157.           [5. key #1 specs]
  158.           [6. key #2 specs]
  159.              ...
  160.  
  161.    INPUTS
  162.         SpecsFileName - null-terminated path/name of the Specs File
  163.  
  164.    RESULTS
  165.         error - returns OK, or an errorcode.
  166.  
  167.    BUGS
  168.  
  169.    SEE ALSO
  170.         ReIndexISAMFile, ISAM.doc (for full description of Specs File)
  171.  
  172. ===============================================================================
  173.  
  174. isam.library/DeleteISAMFile                         isam.library/DeleteISAMFile
  175.  
  176.    NAME
  177.         DeleteISAMFile -- Delete an ISAM file
  178.  
  179.    SYNOPSIS
  180.         error = DeleteISAMFile ( SpecsFileName )
  181.  
  182.         long DeleteISAMFile ( char * );
  183.  
  184.    FUNCTION
  185.         This function deletes an ISAM file, from the information stored in
  186.         the Specs File.
  187.  
  188.    NOTES
  189.         This deletes both data and index files named in the Specs File.
  190.         The Specs File itself is NOT deleted.
  191.  
  192.    INPUTS
  193.         SpecsFileName - null-terminated path/name of the Specs File
  194.  
  195.    RESULTS
  196.         error - returns OK, or an errorcode.
  197.  
  198.    BUGS
  199.  
  200.    SEE ALSO
  201.  
  202.  
  203. ===============================================================================
  204.  
  205. isam.library/DeleteISAMRecord                     isam.library/DeleteISAMRecord
  206.  
  207.    NAME
  208.         DeleteISAMRecord -- delete an ISAM record
  209.  
  210.    SYNOPSIS
  211.         error = DeleteISAMRecord ( ISAMHandle, RecNo )
  212.  
  213.         long DeleteISAMRecord ( ULONG, ULONG );
  214.  
  215.    FUNCTION
  216.         This function deletes the specified record from the specified ISAM file.
  217.  
  218.    NOTES
  219.  
  220.    INPUTS
  221.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  222.  
  223.         RecNo - the record number of a record in the specified ISAM file
  224.  
  225.    RESULTS
  226.         error - returns OK, or an errorcode.
  227.  
  228.    BUGS
  229.  
  230.    SEE ALSO
  231.         DeleteISAMRecords
  232.  
  233. ===============================================================================
  234.  
  235. isam.library/DeleteISAMRecords                   isam.library/DeleteISAMRecords
  236.  
  237.    NAME
  238.         DeleteISAMRecords -- delete a sequence of ISAM records
  239.  
  240.    SYNOPSIS
  241.         error = DeleteISAMRecord ( ISAMHandle, KeyNo, Count )
  242.  
  243.         long DeleteISAMRecords ( ULONG, UWORD, ULONG * );
  244.  
  245.    FUNCTION
  246.         This function deletes all records matching the criteria previously
  247.         established by SetUpISAMIteration(Range|Key|Prefix) for the 
  248.         specified Key in the specified ISAM File.
  249.  
  250.         This is often used when multiple related files exist.  For instance,
  251.         an Invoice Header file, and an Invoice Line Items file, with its key
  252.         the Invoice Number.  To delete an Invoice, one needs to delete both
  253.         the Invoice Header record and all Invoice Line Items with that same
  254.         Invoice Number.  One would set up an iteration on the invoice number
  255.         in the Invoice Line Items file, and call this function; then the 
  256.         Invoice Header record would be deleted.
  257.  
  258.    NOTES
  259.         OK will be returned even if no records meet the criteria, or if
  260.         SetUp... was not called for the Key in question (the idea being not
  261.         to have any records which meet the criteria, if there were none to
  262.         begin with, the objective IS achieved).
  263.         Any other iterations set up for the specified ISAM file will be
  264.         deleted (as a consequence of deleting the first record).
  265.  
  266.    WARNINGS
  267.         Deleting all records which meet certain criteria CANNOT be done
  268.         by setting up an iteration and repeatedly calling DeleteISAMRecord
  269.         from a ReadNextISAM(Key|Record) loop, as the first Delete will kill
  270.         the iteration (along with all others for that file).  Either this
  271.         function or the technique described in IMPLEMENTATION (below) must
  272.         be used.
  273.  
  274.         This function will not return until all records meeting the criteria
  275.         are deleted.  Any other users will be forced to wait.  If there
  276.         are always other users, then use the technique described in
  277.         IMPLEMENTATION.
  278.  
  279.    IMPLEMENTATION
  280.         ISAM does the equivilent of ReadNextISAMKey until ERROR_NO_MORE_RECORDS
  281.         is returned, storing the record numbers in memory as it does so.
  282.         Then it deletes the records from the list in memory.
  283.  
  284.    INPUTS
  285.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  286.  
  287.         KeyNo - the Key Number of a key on which an iteration is set up
  288.  
  289.         Count - a pointer to a variable which will contain the count of 
  290.                 records deleted
  291.  
  292.    RESULTS
  293.         error - returns OK, or an errorcode.
  294.  
  295.    BUGS
  296.  
  297.    SEE ALSO
  298.         DeleteISAMRecord
  299.  
  300. ===============================================================================
  301.  
  302. isam.library/GetFirstLastISAMKeyValues   isam.library/GetFirstLastISAMKeyValues
  303.  
  304.    NAME
  305.         GetFirstLastISAMKeyValues -- retrieve the first and last key values
  306.                                      for a particular key
  307.  
  308.    SYNOPSIS
  309.         error = GetFirstLastISAMKeyValues ( ISAMHandle, KeyNo, 
  310.                                             FKeyValue, FRecNo,
  311.                                             LKeyValue, LRecNo )
  312.  
  313.         long GetFirstLastISAMKeyValues ( ULONG, UWORD, void *, ULONG *,
  314.                                                        void *, ULONG * );
  315.  
  316.    FUNCTION
  317.         This function returns the first and last key values for the specified
  318.         key in the specified ISAM File.  It also returns the corresponding
  319.         record numbers of the first and last key values.
  320.  
  321.    NOTES
  322.  
  323.    IMPLEMENTATION
  324.  
  325.    INPUTS
  326.         ISAMHandle
  327.               - the ISAM Handle identifying the desired ISAM file
  328.  
  329.         KeyNo - the Key Number of a key of the specified ISAM file
  330.  
  331.         FKeyValue
  332.               - a pointer to the area of memory into which the first key
  333.                 value will be read (Note: this is memory owned by the USER,
  334.                 not ISAM)
  335.  
  336.         FRecNo
  337.               - a pointer to a variable which will contain the record 
  338.                 number of the first key value
  339.  
  340.         LKeyValue
  341.               - a pointer to the area of memory into which the last key
  342.                 value will be read (Note: this is memory owned by the USER,
  343.                 not ISAM)
  344.  
  345.         LRecNo
  346.               - a pointer to a variable which will contain the record 
  347.                 number of the last key value
  348.  
  349.  
  350.    RESULTS
  351.         error - returns OK, or an errorcode.
  352.  
  353.    BUGS
  354.  
  355.    SEE ALSO
  356.  
  357. ===============================================================================
  358.  
  359. isam.library/ISAMWhy                                       isam.library/ISAMWhy
  360.  
  361.    NAME
  362.         ISAMWhy -- return an Error string corresponding to an Error number
  363.  
  364.    SYNOPSIS
  365.         string = ISAMWhy ( ErrNo )
  366.  
  367.         char *ISAMWhy ( long );
  368.  
  369.    FUNCTION
  370.         This function returns a string corresponding to an ERROR_ error define.
  371.  
  372.    NOTES
  373.         This function does not use the server, and hence may be used when ISAM
  374.         is not installed.
  375.  
  376.    INPUTS
  377.         ErrNo - an error number
  378.  
  379.    RESULTS
  380.         string - a NULL-terminated string containing the "ERROR_" message
  381.                  corresponding to the error ErrNo, or NULL if ErrNo
  382.                  is not currently an ISAM error number
  383.    BUGS
  384.  
  385.    SEE ALSO
  386.  
  387. ===============================================================================
  388.  
  389. isam.library/LockISAMFile                             isam.library/LockISAMFile
  390.  
  391.    NAME
  392.         LockISAMFile -- Lock an ISAM file (limit/deny access to other users)
  393.  
  394.    SYNOPSIS
  395.         error = LockISAMFile ( ISAMHandle, LockType )
  396.  
  397.         long LockISAMFile ( ULONG, char );
  398.  
  399.    FUNCTION
  400.         This function locks the specified ISAM file with the specified lock
  401.         type, limiting or denying other users access to it.
  402.         
  403.    NOTES
  404.         If the lock type is 'W', then no other user may access the file
  405.         or any records in the file in any way.  If the lock type is 'R',
  406.         then other users may perform Read operations on the file, but may
  407.         not make any changes to the file.
  408.  
  409.         Since it is not considered an error to lock an already locked file,
  410.         this function may also be used to change the lock type of a locked
  411.         file.
  412.  
  413.         If the value ALLFILES is given for ISAMHandle, then an attempt will
  414.         be made to lock all of the files that the user has open.  Any fail-
  415.         ure will result in any files locked by this function being unlocked
  416.         again.
  417.  
  418.    INPUTS
  419.         ISAMHandle - the ISAM Handle identifying the desired ISAM file, or
  420.                      the value ALLFILES (#define'd as 0L)
  421.  
  422.         LockType   - 'W' (exclusive) or 'R' (shared)
  423.  
  424.    RESULTS
  425.         error - returns OK, or an errorcode.
  426.  
  427.    BUGS
  428.  
  429.    SEE ALSO
  430.         UnlockISAMFile
  431.  
  432. ===============================================================================
  433.  
  434. isam.library/LockISAMRecord                         isam.library/LockISAMRecord
  435.  
  436.    NAME
  437.         LockISAMRecord -- Lock an ISAM record
  438.  
  439.    SYNOPSIS
  440.         error = LockISAMRecord ( ISAMHandle, RecNo, LockType )
  441.  
  442.         long LockISAMRecord ( ULONG, ULONG, char );
  443.  
  444.    FUNCTION
  445.         This function locks the specified record in the specified ISAM file,
  446.         limiting or denying other users access to to it.
  447.  
  448.    NOTES
  449.         If the lock type is 'W', then no other user may access the record
  450.         in any way.  If the lock type is 'R', then other users may perform
  451.         Read operations, but may not make any changes to the record.
  452.  
  453.         Since it is not considered an error to lock an already locked record,
  454.         this function may also be used to change the lock type of a locked
  455.         record.
  456.  
  457.    INPUTS
  458.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  459.  
  460.         RecNo      - the record number of the record to be locked
  461.  
  462.         LockType   - 'W' (exclusive) or 'R' (shared)
  463.  
  464.    RESULTS
  465.         error - returns OK, or an errorcode.
  466.  
  467.    BUGS
  468.  
  469.    SEE ALSO
  470.         UnLockISAMRecord
  471.  
  472. ===============================================================================
  473.  
  474. isam.library/ModifyISAMRecord                     isam.library/ModifyISAMRecord
  475.  
  476.    NAME
  477.         ModifyISAMRecord --  replace a record with an altered record
  478.  
  479.    SYNOPSIS
  480.         error = ModifyISAMRecord ( ISAMHandle, RecNo, Record )
  481.  
  482.         long ModifyISAMRecord ( ULONG, ULONG, void * );
  483.  
  484.    FUNCTION
  485.         This function removes record RecNo from the specified ISAM file,
  486.         and replaces it with the specified Record.  The record number 
  487.         remains the same.  If any keys are changed, their old key values
  488.         are removed from the Index file, and their new key values are then
  489.         added.
  490.  
  491.    NOTES
  492.         ISAM has no way of knowing how drastically the record might be
  493.         changed, so has no way of knowing if the RecNo provided is the
  494.         correct one (other than knowing it is outside the acceptable
  495.         range or refers to a deleted record).  So long as the RecNo
  496.         provided is valid, the operation will proceed.  If the wrong
  497.         RecNo is provided, the old record is gone.  Be careful.
  498.  
  499.    INPUTS
  500.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  501.  
  502.         RecNo      - the record number of the record to be modified
  503.  
  504.         Record     - a pointer to the record to replace that of RecNo
  505.                      Normally this will be the address of a struct
  506.                      (example: "&AddrRec" ). 
  507.  
  508.    RESULTS
  509.         error - returns OK, or an errorcode.
  510.  
  511.    BUGS
  512.  
  513.    SEE ALSO
  514.         StoreISAMRecord
  515.  
  516. ===============================================================================
  517.  
  518. isam.library/OpenISAMFile                             isam.library/OpenISAMFile
  519.  
  520.    NAME
  521.         OpenISAMFile -- Open an ISAM file
  522.  
  523.    SYNOPSIS
  524.         error = OpenISAMFile ( SpecsFileName, LLock, LockType, SaveHead, 
  525.                                ISAMHandle )
  526.  
  527.         long OpenISAMFile ( char *, BOOL, char, BOOL, ULONG * );
  528.  
  529.    FUNCTION
  530.         This function opens the ISAM file specified in the Specs File.
  531.  
  532.    NOTES
  533.         If LLock is TRUE, an attempt will be made to lock the file.
  534.         If another user has the file locked, or has records in the file
  535.         locked, this function will fail, with ERROR_FILE_LOCKED or ERROR_
  536.         RECORDS_LOCKED, respectively.
  537.         If LLock is FALSE, but the file/records are locked, this function
  538.         will succeed.  Subsequent functions may fail, depending on the 
  539.         lock type and function.
  540.  
  541.         Certain vital information about the file is stored in the Index File
  542.         Header.  A duplicate of this header is kept in memory, and it is this
  543.         memory-Header that is affected whenever a record is stored, modified
  544.         or deleted.  If SaveHead is TRUE, this Header  will be saved back to
  545.         the file each time a record is stored, modified, or deleted.  The
  546.         index file will therefore be updated more often.  A bit more time is
  547.         consumed diring those operations.  If SaveHead is FALSE, the header
  548.         will be saved back to the file only when the file is closed.  Of
  549.         course, if another user has this file open with SaveHead = TRUE, the
  550.         header will be saved whenever THAT user stores/modifies/deletes a
  551.         record...
  552.  
  553.    INPUTS
  554.         SpecsFileName - null-terminated path/name of the Specs File
  555.  
  556.         LLock - TRUE / FALSE
  557.  
  558.         LockType - 'W' (exclusive) or 'R' (shared)
  559.  
  560.         SaveHead - TRUE / FALSE
  561.  
  562.         ISAMHandle - a pointer to the variable into which the ISAM Handle
  563.                      identifying the ISAM file will be placed
  564.  
  565.    RESULTS
  566.         error - returns OK, or an errorcode.
  567.  
  568.    BUGS
  569.  
  570.    SEE ALSO
  571.  
  572. ===============================================================================
  573.  
  574. isam.library/ReadISAMRecord                         isam.library/ReadISAMRecord
  575.  
  576.    NAME
  577.         ReadISAMRecord -- Read an ISAM record
  578.  
  579.    SYNOPSIS
  580.         error = ReadISAMRecord ( ISAMHandle, RecNo, LLock, LockType, Record )
  581.  
  582.         long ReadISAMRecord ( ULONG, ULONG, BOOL, char, void * );
  583.  
  584.    FUNCTION
  585.         This function reads record RecNo from the specified ISAM file.
  586.         If LLock is TRUE, an attempt will be made to lock the record with
  587.         lock type LockType.
  588.  
  589.    NOTES
  590.         This function is normally called after a series of ReadUnique- or
  591.         ReadNext- operations, at which times only certain data were kept,
  592.         including the record number.  Later, the record numbers alone are
  593.         used to read the records again (using this function) to perform some
  594.         other action.
  595.  
  596.         Also, records may be read in sequential order (first to last in the
  597.         data file) by a loop similar to: for ( ul=0L; ;ul++ ) using "ul" as
  598.         the RecNo.   Ultimately, ERROR_RECORD_TOO_HIGH will be returned,
  599.         indicating the last record has been read.
  600.  
  601.         NOTE: if more records have been deleted then subsequently stored,
  602.         there will be "holes" in the data file, and you will encounter them
  603.         when attempting to sequentially read the records as described above.
  604.         ERROR_DELETED_RECORD will be returned for each "hole" you attempt to
  605.         read. Design your code with this in mind, and EXPECT to get this
  606.         error if you read the records sequentially.
  607.  
  608.    INPUTS
  609.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  610.  
  611.         RecNo - the record number of the record to be read
  612.  
  613.         LLock - TRUE / FALSE
  614.  
  615.         LockType - 'W' (exclusive) or 'R' (shared)
  616.  
  617.         Record - a pointer to the area of memory into which the record will
  618.                  be read
  619.                  NOTE: as with all references to "Record", this is a pointer
  620.                  to memory owned by the USER, not ISAM.
  621.                  Normally this will be the address of a struct
  622.                  (example: "&AddrRec" )
  623.  
  624.    RESULTS
  625.         error - returns OK, or an errorcode.
  626.  
  627.    BUGS
  628.  
  629.    SEE ALSO
  630.         ReadUniqueISAMRecord, ReadNextISAMRecord
  631.  
  632. ===============================================================================
  633.  
  634. isam.library/ReadUniqueISAMRecord             isam.library/ReadUniqueISAMRecord
  635.  
  636.    NAME
  637.         ReadUniqueISAMRecord -- read an ISAM record with a specific key value
  638.  
  639.    SYNOPSIS
  640.         error = ReadUniqueISAMRecord ( ISAMHandle, KeyNo, KeyValue, LLock,
  641.                                        LockType, RecNo, Record )
  642.  
  643.         long ReadUniqueISAMRecord ( ULONG, UWORD, void *, BOOL, char,
  644.                                     ULONG *, void * );
  645.  
  646.    FUNCTION
  647.         This function reads the record from the specified ISAM File that
  648.         has a specified unique key value.
  649.  
  650.    NOTES
  651.         ERROR_KEY_NOT_UNIQUE will be returned if key KeyNo is not a unique key.
  652.         ERROR_NO_SUCH_RECORD will be returned if there is no record in the
  653.         file containing the key value specified.
  654.  
  655.    INPUTS
  656.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  657.  
  658.         KeyNo - the key number of the key whose value is being sought
  659.  
  660.         KeyValue - the key value being sought
  661.  
  662.         LLock - TRUE / FALSE
  663.  
  664.         LockType - 'W' (exclusive) or 'R' (shared)
  665.  
  666.         RecNo - a pointer to the variable into which the record number of
  667.                 the record being read will be placed (example: &RecNo )
  668.  
  669.         Record - a pointer to the area of memory into which the record will
  670.                  be read.  Normally this will be the address of a struct
  671.                  (example: "&AddrRec" ). 
  672.  
  673.  
  674.    RESULTS
  675.         error - returns OK, or an errorcode.
  676.  
  677.    BUGS
  678.  
  679.    SEE ALSO
  680.  
  681. ===============================================================================
  682.  
  683. isam.library/ReadNextISAMKey                       isam.library/ReadNextISAMKey
  684.  
  685.    NAME
  686.         ReadNextISAMKey -- Read the next key value of an iteration
  687.  
  688.    SYNOPSIS
  689.         error = ReadNextISAMKey ( ISAMHandle, KeyNo, RecNo, KeyValue )
  690.  
  691.         long ReadNextISAMKey ( ULONG, UWORD, ULONG *, void * );
  692.  
  693.    FUNCTION
  694.         This function reads the next key value of an iteration.
  695.         If there are no more records meeting the criteria of the iteration,
  696.         then the code ERROR_NO_MORE_RECORDS is returned.  
  697.  
  698.    NOTES
  699.         Unlike ReadNextISAMRecord, no error is returned if the record RecNo
  700.         is locked.
  701.  
  702.    INPUTS
  703.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  704.  
  705.         KeyNo - the key number of the iteration
  706.  
  707.         RecNo - a pointer to the variable into which the record number of
  708.                 the record containing the key being read will be placed
  709.                 (example: &RecNo )
  710.  
  711.         KeyValue - a pointer to the area of memory into which the key value
  712.                    will be read (Note: this is memory owned by the USER,
  713.                    not ISAM.
  714.  
  715.    RESULTS
  716.         error - returns OK, or an errorcode.
  717.  
  718.    BUGS
  719.  
  720.    SEE ALSO
  721.         SetUpISAMteration(Range|Key|Prefix)
  722.  
  723. ===============================================================================
  724.  
  725. isam.library/ReadNextISAMRecord                 isam.library/ReadNextISAMRecord
  726.  
  727.    NAME
  728.         ReadNextISAMRecord -- Read the next record of an iteration
  729.  
  730.    SYNOPSIS
  731.         error = ReadNextISAMRecord ( ISAMHandle, KeyNo, LLock, Locktype,
  732.                                      RecNo, Record )
  733.  
  734.         long ReadNextISAMRecord ( ULONG, UWORD, BOOL, char, ULONG *, void * );
  735.  
  736.    FUNCTION
  737.         This function reads the next record of an iteration.
  738.         If there are no more records meeting the criteria of the iteration,
  739.         then the code ERROR_NO_MORE_RECORDS is returned.  
  740.  
  741.    NOTES
  742.         If the record RecNo is locked, the code ERROR_RECORD_LOCKED is
  743.         returned, and the record is NOT READ.  The iteration is left intact,
  744.         and the next call to this function will get the next record (unless
  745.         it, too, is locked, etc.)
  746.         RecNo will be set even if the record is locked.
  747.  
  748.    INPUTS
  749.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  750.  
  751.         KeyNo - the key number of the iteration
  752.  
  753.         LLock - TRUE / FALSE
  754.  
  755.         LockType - 'W' (exclusive) or 'R' (shared)
  756.  
  757.         RecNo - a pointer to the variable into which the record number of
  758.                 the key being read will be placed (example: &RecNo )
  759.  
  760.         Record - a pointer to the area of memory into which the record will
  761.                  be read.  Normally this will be the address of a struct
  762.                  (example: "&AddrRec" ). 
  763.  
  764.  
  765.    RESULTS
  766.         error - returns OK, or an errorcode.
  767.  
  768.    BUGS
  769.  
  770.    SEE ALSO
  771.         SetUpISAMIteration(Range|Key|Prefix)
  772.  
  773. ===============================================================================
  774.  
  775. isam.library/ReIndexISAMFile                       isam.library/ReIndexISAMFile
  776.  
  777.    NAME
  778.         ReIndexISAMFile -- generate a new index file for a data file
  779.  
  780.    SYNOPSIS
  781.         error = ReIndexISAMFile ( SpecsFileName, Counter )
  782.  
  783.         long ReIndexISAMFile ( char *, BOOL );
  784.  
  785.    FUNCTION
  786.         This function re-creates an index file for a data file, from the
  787.         information stored in the specified Specs File.
  788.  
  789.    NOTES
  790.         Any existing index file will be deleted.
  791.         This function is usually called when the original index file is 
  792.         accidentally deleted or becomes corrupt, or when a key length is
  793.         changed, or a key is added or removed.
  794.         It may also be used to create an ISAM file from a fixed-length
  795.         record-seqential data file (run "SeqToISAM" first (see ISAM.doc).
  796.  
  797.         This function CANNOT be used to change a record length, or change
  798.         the position or length of any data in the record.
  799.  
  800.         The data file will not be altered, except for a portion of the space
  801.         occupied by deleted records.  This means that if it is found that the
  802.         new specifications are wrong, just change them and ReIndex again.
  803.  
  804.         If Counter is TRUE, a small window is opened on the Workbench screen
  805.         showing the count of records being processed.  This helps in gaining
  806.         an idea of the length of time the re-indexing will take.
  807.         So that you don't have to constantly watch the screen, when the
  808.         ReIndexing is complete, the screen will flash, and the highest RecNo
  809.         processed will remain in the window for 5 seconds, after which the
  810.         window will close, and the function will return.
  811.  
  812.    WARNINGS
  813.         Changing a repeatable key to a unique key may obviously cause problems.
  814.         If a record with a duplicate key value is found for a unique key, NONE
  815.         of the keys for that record will be stored, and the record will become
  816.         inaccessible, and unlike deleted records, the space taken up in the
  817.         data file by records ignored in this way will NOT be reclaimed.
  818.  
  819.         This function will not return until all records are re-indexed.
  820.         Any other users will be forced to wait.
  821.         This can be a slow process.  If the data and index files will fit
  822.         into RAM:, place them there.  If they must be on floppy, some time
  823.         may be gained by having the data and index files on separate disks
  824.         (if the system has two floppy drives).
  825.  
  826.         When figuring whether or not you have enough memory/disk space, note
  827.         that if you're changing the number or size of keys, the new index
  828.         file will DIFFER in size from the old one.
  829.  
  830.    INPUTS
  831.         SpecsFileName - null-terminated path/name of the Specs File
  832.  
  833.         Counter - TRUE / FALSE
  834.  
  835.    RESULTS
  836.         error - returns OK, or an errorcode.
  837.  
  838.    BUGS
  839.  
  840.    SEE ALSO
  841.         ISAM.doc, for information re: changing the record length, or the
  842.         position or length of any data in a record
  843.         
  844. ===============================================================================
  845.  
  846. isam.library/ReportISAMStatus                     isam.library/ReportISAMStatus
  847.  
  848.    NAME
  849.         ReportISAMStatus -- cause a file to be created describing the current
  850.                             status of the ISAM server
  851.  
  852.    SYNOPSIS
  853.         error = ReportISAMStatus ( )
  854.  
  855.         long ReportISAMStatus ( void );
  856.  
  857.    FUNCTION
  858.         This function causes the server to create the file RAM:ISAMStatus,
  859.         which contains information on the current status of ISAM: how many
  860.         users/files, which files for which users, the stack size and largest
  861.         stack amount used so far, etc.
  862.         
  863.    NOTES
  864.  
  865.    INPUTS
  866.         none
  867.  
  868.    RESULTS
  869.         error - returns OK, or an errorcode.
  870.  
  871.    BUGS
  872.  
  873.    SEE ALSO
  874.  
  875. ===============================================================================
  876.  
  877. isam.library/SetUpISAMIterationRange       isam.library/SetUpISAMIterationRange
  878.  
  879.    NAME
  880.         SetUpISAMIterationRange -- set up an iteration to range between two
  881.                                    key values
  882.  
  883.    SYNOPSIS
  884.         error = SetUpISAMIterationRange ( ISAMHandle, KeyNo, IterType,
  885.                                           KeyFrom, KeyTo )
  886.  
  887.         long SetUpISAMIterationRange ( ULONG, UWORD, UBYTE, void *, void * ); 
  888.  
  889.    FUNCTION
  890.         This function sets up an iteration to range between two key values
  891.         for key KeyNo, for the specified ISAM File.
  892.  
  893.    NOTES
  894.         Subsequent ReadNextISAM(Key|Record) calls will result in records
  895.         being found with key values ranging between KeyFrom and KeyTo.
  896.  
  897.         The iteration type determines whether the keyvalues will take on
  898.         all key values, one key value, or a range of values, and one or both
  899.         of the end points (KeyFrom, KeyTo) may be excluded from the range.
  900.  
  901.            Type  KeyFrom  KeyTo  Meaning
  902.            ----  -------  -----  -------
  903.             0       -       -    ALL key values
  904.             1       X       -    ONE key value
  905.             2       - ----> O    all key values               to      KeyTo
  906.             3       - ----> X    all key values               through KeyTo
  907.             4       O ----> O    all key values after KeyFrom to      KeyTo
  908.             5       X ----> O    all key values from  KeyFrom to      KeyTo
  909.             6       O ----> X    all key values after KeyFrom through KeyTo
  910.             7       X ----> X    all key values from  KeyFrom through KeyTo
  911.             8       O ----> -    all key values after KeyFrom
  912.             9       X ----> -    all key values from  KeyFrom
  913.  
  914.             where: - means the key value pointer should be NULL.
  915.                    X means the key value specified will be included.
  916.                    O means the key value specified will be excluded.
  917.  
  918.             KeyFrom should be BEFORE or AFTER KeyTo, depending on whether
  919.             the key is an ascending or descending key.
  920.             If KeyFrom and KeyTo are in the wrong order,
  921.             ERROR_KEY_IS_ASCENDING or ERROR_KEY_IS_DESCENDING will be
  922.             returned.
  923.  
  924.    INPUTS
  925.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  926.  
  927.         KeyNo - the key number of the iteration
  928.  
  929.         IterType - the type of iteration range  (currently, 0-9)
  930.  
  931.         KeyFrom - a pointer to the key value from which to range, or NULL
  932.  
  933.         KeyTo - a pointer to the key value to which to range, or NULL
  934.  
  935.    RESULTS
  936.         error - returns OK, or an errorcode.
  937.  
  938.    BUGS
  939.  
  940.    SEE ALSO
  941.         ReadNextISAM(Key|Record), CountISAMRecords, DeleteISAMRecords,
  942.         ISAM.doc (for a complete discusson on itertypes and ranges)
  943.  
  944. ===============================================================================
  945.  
  946. isam.library/SetUpISAMIterationKey           isam.library/SetUpISAMIterationKey
  947.  
  948.    NAME
  949.         SetUpISAMIterationKey -- set up an iteration on one key value.
  950.  
  951.    SYNOPSIS
  952.         error = SetUpISAMIterationKey ( ISAMHandle, KeyNo, KeyValue )
  953.  
  954.         long SetUpISAMIterationKey ( ULONG, UWORD, void * );
  955.  
  956.    FUNCTION
  957.         This function sets up an iteration on one key value for key KeyNo,
  958.         for the specified ISAM File.
  959.  
  960.    NOTES
  961.         Subsequent ReadNextISAM(Key|Record) calls will result in records
  962.         being found with key values matching KeyValue.
  963.  
  964.         This is equivilent to calling SetUpISAMIterationRange with IterType
  965.         being set to 1.
  966.  
  967.         If the given key is unique, using the single function ReadUniqueISAM-
  968.         Record will achieve the same result with less code.
  969.  
  970.    INPUTS
  971.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  972.  
  973.         KeyNo - the key number of the iteration
  974.  
  975.         KeyValue - a pointer to the key value being sought
  976.  
  977.    RESULTS
  978.         error - returns OK, or an errorcode.
  979.  
  980.    BUGS
  981.  
  982.    SEE ALSO
  983.         ReadNextISAM(Key|Record), CountISAMRecords, DeleteISAMRecords,
  984.         ISAM.doc
  985.  
  986. ===============================================================================
  987.  
  988. isam.library/SetUpISAMIterationPrefix     isam.library/SetUpISAMIterationPrefix
  989.  
  990.    NAME
  991.         SetUpISAMIterationPrefix -- set up an iteration on a key value prefix
  992.  
  993.    SYNOPSIS
  994.         error = SetUpISAMIterationPrefix ( ISAMHandle, KeyNo, Prefix, Len )
  995.  
  996.         long SetUpISAMIterationPrefix ( ULONG, UWORD, void *, UWORD );
  997.  
  998.    FUNCTION
  999.         This function sets up an iteration on a key value prefix, for key
  1000.         KeyNo, for the specified ISAM File.
  1001.  
  1002.    NOTES
  1003.         Subsequent ReadNextISAM(Key|Record) calls will result in records
  1004.         being found with all key values having the given prefix.
  1005.  
  1006.         This function is only valid for keys of type A, T, and UI, as a
  1007.         "prefix" on a floating-point or signed-integer key is meaningless,
  1008.         and type C is of length 1 and hence can't HAVE a prefix.  Code
  1009.         ERROR_INVALID_TYPE will be returned if the wrong type is used.
  1010.         
  1011.         Len is used with non-text keys, whose length cannot be determined
  1012.         by strlen(), and for those situations when the prefix is stored in
  1013.         the middle of something else (and hence has no \0).  If the prefix
  1014.         IS a string, Len may be set to zero, and strlen() will be used to
  1015.         set the true length.
  1016.  
  1017.         If the length of the prefix is equal to the length of the key, then
  1018.         this function is the equivilent of SetUpISAMIterationKey.
  1019.  
  1020.    INPUTS
  1021.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  1022.  
  1023.         KeyNo - the key number of the iteration
  1024.  
  1025.         Prefix - a pointer to the prefix
  1026.  
  1027.         Len - the length of the prefix, or zero
  1028.  
  1029.    RESULTS
  1030.         error - returns OK, or an errorcode.
  1031.  
  1032.    BUGS
  1033.  
  1034.    SEE ALSO
  1035.         ReadNextISAM(Key|Record), CountISAMRecords, DeleteISAMRecords,
  1036.         ISAM.doc
  1037.  
  1038. ===============================================================================
  1039.  
  1040. isam.library/ShutDownISAM                             isam.library/ShutDownISAM
  1041.  
  1042.    NAME
  1043.         ShutDownISAM -- shuts down the ISAM server
  1044.  
  1045.    SYNOPSIS
  1046.         error = ShutDownISAM ( )
  1047.  
  1048.         long ShutDownISAM ( void );
  1049.  
  1050.    FUNCTION
  1051.         This function shuts down the ISAM server.
  1052.  
  1053.    NOTES
  1054.         The code ERROR_ISAM_SHUTTING_DOWN will be returned by this function,
  1055.         and by all other functions already waiting to be processed.
  1056.         Shutting down ISAM will annoy other users, so this should be avoided.
  1057.  
  1058.         This function unlocks all locked records and [unlocks]/closes
  1059.         all open files for all users before the server goes away.
  1060.  
  1061.    INPUTS
  1062.         none
  1063.  
  1064.    RESULTS
  1065.         error - returns ERROR_ISAM_SHUTTING_DOWN.
  1066.  
  1067.    BUGS
  1068.  
  1069.    SEE ALSO
  1070.  
  1071. ===============================================================================
  1072.  
  1073. isam.library/StoreISAMRecord                       isam.library/StoreISAMRecord
  1074.  
  1075.    NAME
  1076.         StoreISAMRecord -- store a record
  1077.  
  1078.    SYNOPSIS
  1079.         error = StoreISAMRecord ( ISAMHandle, Record, LLock, LockType, RecNo )
  1080.  
  1081.         long StoreISAMRecord ( ULONG, void *, BOOL, char, ULONG * );
  1082.  
  1083.    FUNCTION
  1084.         This function stores a record in the specified ISAM file.
  1085.         If LLock is TRUE, an attempt will be made to lock the record with
  1086.         lock type LockType.
  1087.         
  1088.    NOTES
  1089.         If the file contains a unique key, and the record being stored 
  1090.         has a key value for that key that already exists in the file,
  1091.         the code ERROR_RECORD_EXISTS will be returned.
  1092.  
  1093.    INPUTS
  1094.         ISAMHandle - the ISAM Handle identifying the desired ISAM file
  1095.  
  1096.         Record - a pointer to the area of memory in which the record is
  1097.                  stored
  1098.                  Normally this will be the address of a struct
  1099.                  (example: "&AddrRec" ). 
  1100.  
  1101.         LLock - TRUE / FALSE
  1102.  
  1103.         LockType - 'W' (exclusive) or 'R' (shared)
  1104.  
  1105.         RecNo - a pointer to the variable into which the record number of
  1106.                 the record being stored will be placed (example: &RecNo )
  1107.  
  1108.    RESULTS
  1109.         error - returns OK, or an errorcode.
  1110.  
  1111.    BUGS
  1112.  
  1113.    SEE ALSO
  1114.  
  1115. ===============================================================================
  1116.  
  1117. isam.library/UnLockISAMFile                         isam.library/UnLockISAMFile
  1118.  
  1119.    NAME
  1120.         UnLockISAMFile -- unlock an ISAM file
  1121.  
  1122.    SYNOPSIS
  1123.         error = UnLockISAMFile ( ISAMHandle )
  1124.  
  1125.         long UnLockISAMFile ( ULONG );
  1126.  
  1127.    FUNCTION
  1128.         The specified ISAM file is unlocked.
  1129.  
  1130.         If the value ALLFILES is given for ISAMHandle, then all of the files
  1131.         that the user has locked will be unlocked.
  1132.         
  1133.    NOTES
  1134.         No error is returned if the file wasn't locked.
  1135.  
  1136.    INPUTS
  1137.         ISAMHandle - the ISAM Handle identifying the desired ISAM file, or
  1138.                      ALLFILES
  1139.  
  1140.    RESULTS
  1141.         error - returns OK, or an errorcode.
  1142.  
  1143.    BUGS
  1144.  
  1145.    SEE ALSO
  1146.         LockISAMFile
  1147.  
  1148. ===============================================================================
  1149.  
  1150. isam.library/UnLockISAMRecord                     isam.library/UnLockISAMRecord
  1151.  
  1152.    NAME
  1153.         UnLockISAMRecord -- unlock a record
  1154.  
  1155.    SYNOPSIS
  1156.         error = UnLockISAMRecord ( ISAMHandle, RecNo )
  1157.  
  1158.         long UnLockISAMRecord ( ULONG, ULONG );
  1159.  
  1160.    FUNCTION
  1161.         This function unlocks the specified record in the specified ISAM file.
  1162.  
  1163.    NOTES
  1164.         No error is returned if the file wasn't locked.
  1165.  
  1166.    INPUTS
  1167.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  1168.  
  1169.         RecNo - the record number of the record being unlocked.
  1170.  
  1171.    RESULTS
  1172.         error - returns OK, or an errorcode.
  1173.  
  1174.    BUGS
  1175.  
  1176.    SEE ALSO
  1177.         LockISAMRecord, UnLockAllISAMRecords
  1178.  
  1179. ===============================================================================
  1180.  
  1181. isam.library/UnLockAllISAMRecords             isam.library/UnLockAllISAMRecords
  1182.  
  1183.    NAME
  1184.         UnLockAllISAMRecords -- unlock all locked records
  1185.  
  1186.    SYNOPSIS
  1187.         error = UnLockAllISAMRecords ( ISAMHandle )
  1188.  
  1189.         long UnLockAllISAMRecords ( ULONG );
  1190.  
  1191.    FUNCTION
  1192.         This function unlocks all locked records in the specified ISAM file.
  1193.  
  1194.         If the value ALLFILES is given for ISAMHandle, then all of the locked 
  1195.         records for all of the files that the user has open will be unlocked.
  1196.  
  1197.    NOTES
  1198.  
  1199.    INPUTS
  1200.         ISAMHandle - the ISAM Handle identifying the desired ISAM file.
  1201.  
  1202.  
  1203.    RESULTS
  1204.         error - returns OK, or an errorcode.
  1205.  
  1206.    BUGS
  1207.  
  1208.    SEE ALSO
  1209.         UnLockISAMRecord
  1210.  
  1211. ===============================================================================
  1212.