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