isbuild(S)                     6 January 1993                     isbuild(S)


 Name

    isbuild - create an ISAM file

 Syntax


    cc  . . .  -lisam


    isbuild (filename, recordlength, keydesc, mode)
    char *filename;
    int recordlength;
    struct keydesc *keydesc;
    int mode;


 Description

    The isbuild function creates a new ISAM file.  It creates and initializes
    the necessary files on the disk to hold the data and index files.  You
    can use the following arguments with this routine:


    _________________________________________________________________________
    Argument                           Description
    _________________________________________________________________________
    filename                           Null-terminated character string
                                       identifying the name of data file
                                       being created.  Maximum of 10 charac-
                                       ters for the filename.  The filename
                                       extension should not be specified.
    recordlength                       Number of bytes in a record.  Equals
                                       the sum of the field lengths.
    keydesc                            Pointer to the structure defining the
                                       primary index of the file.
    mode                               Access mode in effect while the file
                                       is open as a result of isbuild.
                                       Arithmetic sum of a lock mode value
                                       and a read/write mode value.  The
                                       values are described later in this
                                       section.

    If isbuild executes successfully, it returns a file descriptor of the new
    ISAM file.  The file remains open for further processing. Use the isclose
    function to close the file.

    The isbuild function must include an index structure for the primary
    index.  However, if you set knparts in the structure keydesc to zero,
    then there is effectively no primary index.  Additional indexes may be
    added with the isaddindex function.

    The mode parameter specifies the lock mode and the read/write mode in
    effect while the file is open as a result of isbuild.  The value of the
    mode parameter is the arithmetic sum of a lock mode value and a
    read/write mode value.

    The lock mode values are defined in isam.h as:

    _________________________________________________________________________
    Lock Mode           Description
    _________________________________________________________________________
    ISAUTOLOCK          automatic record lock
    ISMANULOCK          manual lock
    ISEXCLLOCK          exclusive file lock

    These modes have the following effects:

    +  When ISAUTOLOCK is used, each record is locked when it is accessed for
       read, write, delete, or update, and unlocked after the next function
       call is made.

    +  When ISMANULOCK is used, you can perform both optional file locking
       and record locking.  Files may be locked and unlocked multiple times
       by using the islock and isunlock functions. You can perform record-
       locking by isread with an ISLOCK option. Locked records may be
       released with an isrelease call.

    +  When ISEXCLLOCK is used, the entire file is locked. Other users cannot
       read, write, or open the file.  The file is unlocked when it is closed
       with isclose.

    The read/write mode values are defined in isam.h as:

    _________________________________________________________________________
    Build Option      Description
    _________________________________________________________________________
    ISOUTPUT          open for writing only
    ISINOUT           open for reading and writing

    On success, isbuild returns a non-negative value.  Otherwise, it returns
    -1 and sets iserrno to indicate the error.

 Example

    This example creates an ISAM file named books, with record length of 52
    and a primary key contained in key.

       isbuild("books", 52, &key, ISINOUT + ISEXCLLOCK) ;


 See also

    iserase(S), isopen(S), isrename(S)

 Standards conformance

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