isread(S)                      6 January 1993                      isread(S)


 Name

    isread - read records in an ISAM file

 Syntax


    cc  . . .  -lisam


    isread(isfd, record, mode)
    int isfd;
    char *record;
    int mode;


 Description

    The isread function reads a record from an ISAM file into a buffer for
    further processing.  You can use the following arguments with this rou-
    tine:


    _________________________________________________________________________
    Argument                         Description
    _________________________________________________________________________
    isfd                             File descriptor identifying the ISAM
                                     file to be read.  The file must already
                                     be open.
    record                           Buffer holding the record after the call
                                     is executed.  For random accesses,
                                     record is filled with the search value
                                     before the call is executed.
    mode                             Integer identifying which record is read
                                     and whether random or sequential access
                                     is used.  Also can be used to lock the
                                     record manually.  The possible values
                                     are described below.

    If isread executes successfully, the current record position pointer and
    isrecnum are set to the record just read.

    The mode parameter determines which record is read.  The possible values
    depend on whether you want sequential or random access.

    The values of mode for sequential access are specified in the isam.h
    header file as:

    _________________________________________________________________________
    Read Mode              Description
    _________________________________________________________________________
    ISFIRST                first record
    ISLAST                 last record
    ISNEXT                 next record
    ISPREV                 previous record
    ISCURR                 current record

    During random access, the function compares a value stored in the record
    parameter to the corresponding data in the records.  The mode parameter
    determines the comparison logic as follows:

    _________________________________________________________________________
    Read Mode   Description
    _________________________________________________________________________
    ISEQUAL     record equal to search value
    ISGREAT     record greater than search value
    ISGTEQ      record greater than or equal to search value

    The search value is placed in the appropriate byte positions in the
    record buffer.  The record that first satisfies the condition (in the
    order of the index currently in use) is then copied to the record buffer.

    A special use of isread allows access by a previously set isrecnum.
    First, isstart is called with the knparts member of the keydesc parame-
    ter set to zero.  This turns off the primary index and causes the file to
    be read in physical order.  Then isread is called with the mode parameter
    set to ISEQUAL.  This causes isread to read the record located at the
    isrecnum position.

    The record to be read can also be locked by specifying the ISLOCK option
    for manual locks or ISSLOCK for shared locks.  The lock is effective only
    if the isopen function was called with a mode parameter that included
    ISMANULOCK.  The record stays locked until an isrelease call is issued on
    the file.

    On success, isread returns 0.  Otherwise, it returns -1 and sets iserrno
    to indicate the error.

 Example

    This example reads a record that matches the search value contained in
    the buffer:

       isread( bookfd, buffer, ISEQUAL ) ;


 See also

    isstart(S)

 Standards conformance

    isread is not part of any currently supported standard; it is an exten-
    sion of AT&T System V provided by the Santa Cruz Operation.