Piper's Pit BBS/FTP: ibm 0010 - 0019/ibm0010-0019/ibm0010.tar/ibm0010/CODE4-1.ZIP/CB4_MAN.ZIP/CB4_MAN.TXT

Text File | 1990-06-21 | 237.2 KB | 8,626 lines

                  CODE BASE 4

LEARNING CODE BASE

   Code Base is a "C" library for database and screen management. Its
   compatibility with dBASE allows it to work with any other dBASE compatible
   product.

   As Code Base uses the same naming conventions as dBASE, it is easy to
   learn. Anyone who is acquainted with the "C" programining language and
   understands a few database fundamentals will have no trouble learning Code
   Base.

   All users should progress through this section on learning Code Base. The
   part on Code Base Internals should be read even if it is not completely
   understood.

   Anyone who plans to use Code Base in a Multi-User environemnt will need to
   read the chapter "Multi-User Considerations".

   The most important information in the "Routine Descriptions" chapter is in
   the sections on "Database", "Field", "Windowing", "Menuing", and "Get"
   routines.

   Those interested in filtering and relations should refer to the "Extend
   Routines".


BASIC TERMS

   Following are some definitions of terms which are used throughout the Code
   Base manual.

   Database

    A database is a file which stores your data. For example, a mailing
    list database contains the names and addresses of people.


   Record

    Database information is organized into records. Each record in a
    mailing list database contains information on one person.


   Record Buffer

    For each database, Code Base allocates memory for one record worth of
    information. Each of these memory areas is called a 'record buffer'.
    Many of the high level Code Base database routines, such as 'd4go',
    automatically use this memory buffer. A pointer to the record buffer
    can be obtained using routine 'f4record'. The next section on Code
    Base Internals describes the format of the record buffer.


   Record Number

    Each record in a database is assigned a sequential record number
    starting from one. There is a current record number which corresponds
    to the record in the record buffer. The current record number can be
    obtained with routine 'd4recno'.


   Field

    Records are organized into fields. A database field describes one
    category of information in each database record. The fields in a
    mailing list database could be last name, address, city, and phone
    number. LAST_NAME, ADDRESS, CITY, and PHONE_NUM are examples of
    corresponding field names.

    Fields are type Character, Numeric, Floating Point, Logical, Date, or
    Memo. The field type is important because it determines the category
    of information the field stores. Field names and field types are
    deteremined when a database is created.


   Index File

    It may be necessary to examine a database in different orders at
    different times. A mailing list database might need to be sorted by
    the LAST_NAME some times and by the field ADDRESS at others. It would
    take a long time to resort a large database every time a new order
    was required.

    Consequently, index files are created to permanently contain sorted
    information. An index file contains one sort order for one database.
    Index files have a B+ Tree structure. This means that the sorted
    information can be located quickly and efficiently.


   Expression of an Index File

    Index files also contain information on how the database is to be
    sorted. This information is called an expression. LAST_NAME is an
    example of an expression; it means the index file contains a sort by
    the field LAST_NAME.


   Reference Number

    Code Base uses reference numbers for almost everything. Every
    database, index file, field, get entry area, window or menu item used
    by Code Base has a corresponding reference number. These reference
    numbers are used as parameters to many Code Base routines.



DATABASE CONCEPTS

   Following are some basic concepts which the rest of this user's guide
   assumes you under stand.

   By using Code Base, it is possible to save and access hundreds of
   megabytes worth of information. This information is saved on disk in
   database files. Only portions of the total available information is
   manipulated at one time.

   It is possible to have several database files open at once. However, only
   one database file is selected at a time.

   The database routines work with the selected database. Opening and closing
   databases takes a lot of computer time but selecting between open
   databases is almost instantaneous.

   For each open database there is a area in memory called a record buffer.
   the exact format of the record buffer is described in the Appendix on Code
   Base internals. Many of the high level database management routines work
   with the record buffer. For example, routine 'd4go' reads a database
   record from disk into the record buffer. Conversly, routine 'd4write'
   either writes or appends the record in the record buffer to the database
   file.

   To access and modify the record buffer, field routines are available. For
   example, routine 'f4replace' changes the value of a field within the
   record buffer.

   Every database can have a set of open index files. Each index file
   corresponds to a specific database and when the database is modified
   using 'd4write', all corresponding index files are automatically
   maintained. Every database may have its own 'selected' index file. High
   level database management routines such as 'd4seek' and 'd4skip' use the
   currently selected index file of the currently selected database. Low
   level index file routines such as 'i4seek' and 'i4skip' are not normally
   used directly.

   Memo files are used for saving variable length text. For efficiency, every
   field is saved in a fixed amount of space within a database record. A memo
   field takes up exactly ten bytes worth of space within the database record
   and a variable amount of space within a seperate memo file. A memo file
   has the same file name as the corresponding database file except that the
   file name extension is changed from "DBF" to "DBT". The same memo file is
   used for all of the memo fields of a particular database file.


GETTING STARTED

   Complete the following steps before working with Code Base for the first
   time.

    1. Make a working version of the diskettes.

    2. Install Code Base.

    3. Run "d4learn" to experiment with the Code Base routines. Read the
       documentation in the user's guide on a particular routine before
       trying to use it.

    4. Read "Using Code Base with Turbo C", "Using Code Base with Quick
       C", or "Using Code Base with Microsoft C".

    5. Read "Create Your own Code Base Applications.


   Installing Code Base

    To use Code Base it is only necessary to copy the appropriate library
    file, headers files and configuration information. However, to
    compile Code Base routines, it is also necessary to copy the source
    code.

    1. Copy one of the three pre-built library from the appriopate library
       diskette.  If none of these library options are appropriate, refer
       to the appendix on library building.

           File Name      Use

           T4.LIB         A Turbo C compatible large memory model library.

           M4.LIB         A Microsoft C and Quick C compatible large
                  memory model library.

           M4CLIP.LIB     A Microsoft C and Quick C compatible large
                  memory model library. This library was compiled
                  for Clipper NTX file compatibility.


    Turbo C Example:

           COPY A:\T4.LIB  C:\TC\LIB

       The above "COPY" command transfers the Turbo C compatible Code Base
       library from the Code Base TC library diskette in "Drive A:" to the
       library directory "\TC\LIB" on 'Drive C:'.

       As the library "T4.LIB" was constructed using the large memory
       model, all source files in the application must be compiled with the
       large memory model.


    Microsoft C Example:

           COPY A:\M4.LIB  C:\MSC

       In this example, the Microsoft C compatible Code Base library
       M4.LIB" is copied to directory "C:\MSC".  To use Microsoft C with
       OS/2, refer to the appendix on library building.


    Quick C:

       Refer to Microsoft C.  Note that it is impossible to use the Code
       Base prebuilt libraries with the Quick C 1.0 interactive environment
       because it needs medium memory model libraries.  If you need medium
       memory model library, refer to the appendix on library building.


    2. Copy header files from the Header, Example and Source diskette.
       Note that the Turbo C header files are the same as the Microsoft
       and Quick C header files:

       Example:

           COPY  A:\INCLUDE\*.*  C:\TC\INCLUDE

       The above command copies all of the Code Base header files from the
       Header diskette to a Turbo C "Include" directory.  These header
       files are necessary for using Code Base.


    3. If you plan to use the Code Base source files, insert the Code
       Base source diskette in "Drive A:" and copy the source files to
       the appropriate source directory.

       Example:

           COPY  A:\*.C  C:\MSC

       Then place the Header, Example and Source Disk and copy the
       remaining source files from subdirectory "source".

       Example:

           COPY  A:\SOURCE\*.C  C:\MSC

    Run "d4learn"

       To help learn Code Base, program "d4learn" has been included it
       the 'example' subdirectory of the Header, Source and Example
       diskette. Using pulldown menus, a Code Base routine is selected.
       After "d4learn" has prompted for the routine parameters, the
       routine is executed and the result is displayed.

       Hint:

           Source code for program "d4learn.exe" is contained in file
           "d4learn.c" in the same subdirectory. This program, as well as
           the programs in files 'w4example.c', 'x4multi.c',
           'c4convert.c' and 'd4example.c' are good examples of how to
           call Code Base routines. Very high level Code Base routines
           contained in files 'x4list.c', 'x4edit.c', and 'x4.c' can also
           be used as examples.


    Using Code Base with Turbo C

       In order to use the Code Base library "T4.LIB" in Turbo C's
       interactive environment, a "project" file is needed. The project
       file "D4LEARN.PRJ", used to create program "D4LEARN.EXE", is on
       the Code Base TC library diskette. It contains the following two
       lines:

           D4LEARN.C
           T4.LIB

       In addition, there is a file "TURBOC.CFG" which specifies options
       for the "TCC" turbo compiler. This file should contain the
       following line:

           -LC:\TC\LIB  -IC:\TC\INCLUDE   -ml -c -DTURBO -N

       This line specifies the library directory, the include directory,
       the large memory model, to compile only, and defines the "TURBO"
       switch. The "TURBO" switch specifies to use any Turbo C specific
       source code.  Code Base source code uses the "TURBO" switch in
       "#ifef" and "#ifndef" preprocessor directives to the compiler.

       When using the Turbo C interactive environment, make sure to
       specify the correct memory model. If problems, such as obscure
       undefined externals, occur during linking, try rebuilding the Code
       Base library using the same copilation options as you normally use.

       The Turbo C default stack size is 3000 bytes. When working with
       large index files, it is safest to increase the maximum by adding
       the following line of code to the top of your program:

           extern unsigned  _stklen = 1000 ;



    Using Code Base with Quick C

       In order to use the Code Base library "M4.LIB" in Quick C's
       interactive environment, it is necessary to use "MAKE" files. If
       Quick C 1.0 is being used, it is also necessary to build a custom
       Code Base library. To build a make file to compile and link
       program "D4LEARN.EXE", add the files "D4LEARN.C" AND "M4.LIB"
       using the Quick C menu options.

       Make sure that the large memory model is specified and extra stack
       space is allocated. It is safest to use about 10K of stack space.
       These are also menu options in the Quick C interactive environment.

       The Quick C command line compiler "QCL.EXE" is used in the same
       manner as the Microsoft C compiler "CL.EXE". Refer to "Using Code
       Base with Microsoft C".


    Using Code Base with Microsoft C

       When compiling with "CL.EXE" command line compiler, specify the
       large memory model, and extra stack space.

       Example:

           CL  /AL  D4LEARN*.C  /link  M4.LIB  /STACK:1000

       Refer to the compiler's user's guide for compelte information on
       compiling and linking options.


    Creating a Code Base Application

       In Code Base application source files, the following "#include"
       directives are often used:

           #include  <d4base.h>
           #include  <w4.h>

       If you have placed the Code Base header files in your source
       directory rather than your include directory, use the following
       "#include" directives instead:

           #include  "d4base.h"
           #include  "w4.h"

       File 'd4base.h' defines structures and prototypes for Code Base's
       data management routines. 'w4.h' defines the structure and
       prototypes for Code Base's screen management routines.



    Example:

        /* This example is in file "d4example.c" */

        #include    "d4base.h"
        #include    "w4.h"

        #ifdef TURBO
        extern unsigned     _stklen = 1000 ;
        #endif

        main()
        {
        int     j ;
        long    ref ;

        /* Initialize Code Base and clear the screen */
        d4init() ;
        w4clear( -1 ) ;

        /* Open the database */
        if ( d4use( "d4learn" ) < 0 )
            exit ( 1 ) ;

        w4( 0,5, "D4LEARN.DBF  Field Names: " ) ;
        for( j=1; j <= f4num_fields() ; j++ )
        {
            ref = f4j_ref( j ) ;

            /* Display the field name */
            w4( j,8, f4name( ref ) ) ;
        }

        w4cursor( j,0 ) ;

        w4exit( 0 ) ;
        }




ROUTINE DESCRIPITIONS

   There is a description of all of Code Base's exteranl routines which could
   be called from an user's program.

   To use the database management portion of Code Base effectively, it is best
   to be familiar with all the database and field routines, and a few of the
   index file routines.  In addition, the extended routines are important for
   those who wish to use the relations and filters.

   For screen management, consult the windowing, menuing and get routines.
   First learn how to use the windowing routines.  Menuing and get routines
   build upon the windowing to allow capablities such as pulldown menus and
   full screen data entry.

   The 'conversion', 'utility', 'memory handling' and 'expression evaluation'
   routines could be of general use to any applications programmer.

   Those wishing a quick overview of the Code Base routines could read the
   routine section introductions and the experiment with program 'd4learn'.



CONVERSION ROUTIONS

   Conversion routines change information from one format to another.


c4atod

   Usage
          double  c4atod( (char *) str, (int) len_str )

   Description
          'c4atod' converts an ASCII string of a specific length into
          a '(double)'.

   Return
          The converted result.

   Example
          doub_result = c4atod( " 67.3", 5) ;


c4atoi

   Usage
          int  c4atoi( (char *) str, (int)  len_str)

   Description
          'c4atoi' converts an ASCII character sting of a specified
          length into an integer.

   Return
          The converted integer result.


c4atol

   Usage
          int  c4atol( (char *) str, (int)  len_str)

   Description
          A character sting of a specified length into an long integer.

   Return
          The converted long integer result.


c4dtoa

   Usage
          char *  c4dtoa( (double) doub_value, (int) len, (int) dec )

   Description
          'c4dtoa' converts a '(double)' into a character string.
          This string will be formatted according to the specified
          length and number of decimals.  If there is an overflow,
          the string will be filled with asterisks ('*').

   Return
          A pointer to an internal static buffer containing the
          converted string is returned.


c4dtok

   Usage
          int c4dtok( (int) index_ref, (double) doub_val,
                  (char *) key_val )

   Description
          'c4dtok' is used in Clipper compatible programs, when
          working with Numeric keys, to convert a '(double)' into an
          ASCII charater string.  This string will be formatted for
          use with Code Base index file routines such as 'i4seek'.

   Parameters
          Name        Use

          index_ref   The index file reference number.

          double_val  The 'double' to be converted.

          key_val     A pointer to where the converted result should
                  be placed. The buffer length must be greater
                  than the index file key length. In general,
                  this will never be greater than 32 characters.

   Return
          Value       Meaning

           0          Sucess

          -1          Error


c4dt_dbf

   Usage
          void c4dt_dbf( (char *) dbf_date, (double *) index_date )

   Description
          In index files dates are stored as a double and in
          databases they are stored as an ASCII string.

          'c4dt_dbf' converts a date from index file format to
          database format.

   Parameters
          Name        Use

          index_date  Points to the index file format date. This is
                  the julian day as a (double).

          dbf_date    Points to storage where the result is to be
                  placed. The format is "CCYYMMDD" or century,
                  year, month, day. Consequenlty, 8 bytes of
                  memory must be available.


c4dt_format

   Usage
          char *  c4dt_format( (char *) dbf_date, (char *) picture )

   Description
          Converts between the database date format and other date
          formats.

   Parameters
          Name        Use

          dbf_date    This is the database date which is an ASCII
                  string of lenght 8 formatted "CCYYMMDD"
                  (century, year, month, day).

          picture     The picture specifies how the date is to be
                  formatted.

                  Examples:

                  YY.MM.DD
                  CCYY.MM.DD
                  MM/DD/YY
                  DD-MM/YY
                  DD-MM/CCYY
                  MMM DD/YY

                  The 'Y', 'M' and 'D' characters specify the
                  year, month, and day respectively. If there
                  are more than 2 'M' characters, a Character
                  reprensentation of the month is returned.

   Returns
          A pointer to an internal static buffer is returned. This
          buffer contains the converted result.

   Example
          /* '*result_ptr' will contain "88.01.30" */
          result_ptr = cdt_format("19880130", "YY.MM.DD");


c4dt_index

   Usage
          int  cd4t_index( (char *) dbf_date, (double *) index_date )

   Description
          'c4dt_index' is the opposite of routine 'c4dt_dbf'. Dates
          are converted from database format to index file format.

   Parameters
          Name        Use

          dbf_date    Points to database date to be converted. The
                  format is "CCYYMMDD" or century, year, month,
                  day.

          index_date  Points to the index file format date where the
                  result is to be placed. This is the julian_day
                  as a (double).

   Returns
          Value       Meaning

           0          Success.

          -1          Illegal Date (No Error Displayed).

          -2          Null Date (Blank Information).


c4dt_unformat

   Usage
          char *  c4dt_unformat( (char *) date_data, (char *) picture )

   Description
          Converts to the database date format from a specified date
          format. If the supplied date dose not contain complete date
          information, the default century is '1990', the default
          year is '80', the default year is '80', the default month
          is January, and the default day of the month is '1'.

          The database date format is "CCYYMMDD".

   Parameters
          Name        Use

          date_data   This is the date information.

          picture     The picture specifies the format of the date
                  data.

   Returns
          A pointer to an internal static buffer is returned. This
          buffer contains the converted database format date.

   See Also
          c4dt_format


c4encode

   Usage
          void  c4encode( (char *) to, (char *) from, (char *) t_to,
                  (char *) t_from )

   Description
          Characters are moved from the string 'from' to the string
          'to'. The format of the result in 'to' is specified by
          template 't_to'. The format of the source string 'from' is
          specified by the template in 't_from'.

          There are nor predetermined formatting charaters. However,
          if a character in 't_from' matches a character in 't_to',
          the corresponding character in 'from' is moved to the
          corresponding position in 'to'.

   Parameters
          Name        Use

          to          The destination of the converted information.

          form        The information to be converted.

          t_to        A template of the destination formatting.

          t_from      A template of the source inforamtion.

   Example
          /* The result put into 'to' will be " 3 2 1" */
          c4encode( to, "123", "C B A", "ABC" );

   Note
          As in the example, any charaters in 't_to' which do not
          match characters in 't_from' are copied to corresponding
          position in 'to'.


c4ltoa

   Usage
          char *  c4ltoa( (long) long_value, (char *) result_ptr,
          (int) result_len )

   Description
          A '(long)' is converted into character format as specified
          by the length parameter. The result character value is
          right justified inside the allotted space.

   Parameters
          Name        Use

          long_value  The value to be converted.

          result_ptr  A pointer to where the result should be
                  returned. At least 'result_len' bytes worth of
                  storage should be allocated by the caller.

          result_len  This is the length of the result string. If
                  'result_len' is less than zero, any preceding
                  characters are filled by zeros.

   Return
          The return is parameter 'result_ptr' which is a '(char *)'
          pointer to the result.

   Hint
          Other numeric data types can be converted by 'c4ltoa' by
          casting them as a '(long)'.

   Note
          A null terminating character is NOT placed at the end of
          the converted result. Only 'result_len' characters are
          modified.

   Example
          char *  test_routine( value, ptr )
          int     value;
          char *  ptr;
          {
               c4ltoa( (long) value, ptr, 10 );
               return( ptr );
          }



c4key

   Usage
          void  c4key( (char *) in_key, (char *) out_str,
                  (char) key_type )

   Description
          Routine 'c4key' converts the key value returned by 'i4eval'
          into printable character format.

   Parameters
          Name        Use

          in_key      A pointer to the index file key.

          out_str     A pointer to a buffer where the result should
                  be returned. Make sure 'out_str' points to 64
                  (or more) bytes of memory.

          key_type    The type of the index file. This value may is
                  returned by routine 'i4type()'.



c4trim_n

   Usage
          void  c4trim_n( (char *) str, (int) n_ch )

   Description
          Routine 'c4trim_n' trims the blanks off of string 'str'. A
          null character is placed in the last byte in the string to
          ensure it is null terminated.

   Parameters
          Name        Use

          str         A pointer to the string.

          n_ch        The number of bytes of memory declared for the
                  sting.




DATABASE ROUTINES

   The database routines correspond to high level dBASE commands. They are
   use to store and retrive information from database files.

   Database routines use an inplicit selected database. This selected
   database is the last database opened or the database last selected with
   routine "d4select". Consequently, it is possible to have many databases
   open at on time.

   Each database also has a current record number, a record buffer, and a
   selected index file. Whenever a routine uses or changes either the current
   record or the selected index file, it will be noted in the database
   routine documentation.

   The various record positioning routines such as 'd4bottom' and 'd4go' read
   the new current record into the buffer. Routine 'd4write' writes or
   appends the record buffer. To access and modify the record buffer, refer
   to the field routines.

   WORKING WITH MULTIPLE FILES

   To work with more than one database, save the database refernece number
   returned by 'd4use'. Then use 'd4select' to switch between databases with
   the appropriate database reference number as a parameter. Similarily, the
   reference number returned by 'i4open' can be use by routine 'i4select'.


d4bottom

   Usage
          int  d4bottom()

   Description
          Go to the bottom of the database using the selected index
          file. If no index file is selected, go to the last record
          of the database.

   Returns
          Value       Meaning

           0          Success.

           3          End of File.

          -1          Error.


   Locking
          The bottom record and any selected index file are locked.

   Example
          if ( d4bottom() < 0 )
              return -1;


d4close

    Usage
          int  d4close()

    Description
          Closes the selected database and all of its index files.

    Returns
          Value       Meaning

           0          Success.

          -1          There was an error closing one of the files.

   Example
          /*    Source Code for 'd4close_all' */

          d4close_all()
          {
              /*  'v4last_base' is an internal Code Base variable. It
              contains the database reference number of the last
              opened database. If no databases are open, it is
              '(int) -1'.  */

              while( v4last_base >= 0 )
              if ( d4close () < 0 ) return 1;

              return 0;
          }


d4close_all

   Usage
          int d4close_all()

   Description
          All open database, index, and memo files are closed.

   Returns
          Value       Meaning

           0          Success.

          -1          There was an error closing one of the files.

   Locking
          Unlocks the databases and index files.


d4create

   Usage
          int  d4create( (char *) name, (int) n_fields,
                  (FIELD *) fields, (int) safety)

   Description
          A database is created, opened and selected. If the database
          is already open and safety is off, it will be closed,
          deleted, and then created once more according to the
          parameter specifications.

   Parameters
          Name        Use

          name        The file name to be created.

          num_fields  The number of fields in the database.

          fields      A pointer to an array defining the database
                  fields. There are 'num_fields' entries in this
                  array. The 'offset' portion of the field
                  descripition is computed by the 'd4use'
                  routine. Refer to the example.

          safety      A logical (int) specifying whether any existing
                  file with the same name should be removed:
                 0 - Remove existing file.
                 1 - Return with error return if the file
                     exists.

   Note
          As in the example, it is possible to create databases with
          six different field types:

          Type Code   Meaning

            C         Character Field. The number of decimals is
                  always zero. The dBASE maximum field width is
                  255. However, if the greater than 255, the
                  database will still be Clipper compatible.

            N         Numeric Field. This field t;ype has a maximum
                  width of 17. If the number of decimals is
                  greater than zero, is should be at least two
                  less than field width.

            F         Floating Point Field. Code Base treats floating
                  point fields the same as numeric fields.

            D         Date Field. The width of a date filed is
                  always 8.

            L         Logical Field. The width of a logical field is
                  always 1. It can have a true or false value.

            M         Memo Field. The width of a memo field is always
                  10. If the database has one or more memo
                  fields, a separate memo file is created. Memo
                  fields are used to store variable length text.
                  Refer to the memo file moudule.

   Returns
          Value       Meaning

          >= 0        The database reference number corresponding to
                  the database.

          -1          Error.

   Locking
          Locks record one and the record count bytes.

   Example
          #include  <d4base.h>

          static FIELD  fields[] =
          {
              /* Field Name,   Type, Width, Dec, Offset */
               {"FIRST_NAME",  'C',  25,    0,   0},
               {"BIRTH_DATE",  'D',   8,    0,   0},
               {"AMOUNT    ",  'N',  12,    2,   0},
               {"FLOAT_VAL ",  'F',  14,    4,   0},
               {"TRUE_FALSE",  'L',   1,    0,   0},
               {"MEMO_INFO ",  'M',  10,    0,   0}
          };

          int create_base()
          {
              return( d4create( "BASE.DBF", 4, fields, 1) );
          }


d4delete

   Usage
          int  d4delete( (long) record_number)

   Descripition
          Marks the specified record for deletion. The record is
          read, the deletion flag is changed to an asterisk ('*') and
          the record is written.

   Returns
          Value       Meaning

           1          Record Dose Not Exist.

           0          Success.

          -1          Error.

   Locking
          The record is locked.

   Hint
          If the reocrd has already been read into the record buffer,
          and fields have been modified in memory, delete the record
          directly. This is done by changing the first byte of the
          record buffer to an asterisk ('*'). Then record is written
          to disk:

          /*  Read from disk into the record buffer  */
          d4go( record_no );

          /*  Modify a field in memory */
          f4replace( field_ref, "New Data" );

          /*  Mark the record for deletion. 'f4record' returns a
          pointer to the record buffer. The first byte of this buffer
          is the deletion flag.  */

          *f4record() = '*' ;

          /*  Write the record to disk.  */
          d4write( record_no );

   Example
          d4delete(1L) ; /* Mark Record 1 for deletion */


d4deleted

   Usage
          int  d4deleted()

   Description
          Specifies whether the current record is marked for
          deletion. If there is no current record, the result is
          undefined.

   Returns
          Value       Meaning

          0           The record is NOT marked for deletion.

          1           The record is marked for deletion.

   Locking
          No locking.

   Example
          if ( d4deleted() ) delete_work() ;
          /* The above code is equivalent to:
             if ( * (char *) f4record() == '*' )
              delete_work() ;
          */

d4go

   Usage
          int  d4go( (long) record_number )

   Description
          Reads the specified record into the record buffer. This
          record also becomes the current record number. If the
          record does not exist, the record buffer is initialized to
          blanks.

   Returns
          Value       Meaning

           1          The record does not exist.

           0          Success.

          -1          Error.

   Locking
          The record is locked.

   Hint
          The database buffer may be accessed using the "Field"
          routines.

   Example
          rc = d4go( 2L ) ;  /* Go to record 2 */


d4init

   Usage
          int  d4init()

   Description
          'd4init' initializes various Code Base variables. When
          necessay, routines 'd4use' and 'd4create' will call
          'd4init' automactically.

   Note
          The first time one of either 'd4init' or 'w4define' is
          called, a default window is defined. This window, which
          contains the entire screen, is used by 'u4error' to display
          error messages.

   Return
          Value       Meaning

           0          Success.

          -1          Out of Memory.

   Example
          #include <d4base.h>

          main()
          {
              d4init();  /* Initialize memory structures */
              .
              .
              exit(0) ;
          }

d4init_memory

   Usage
          int  d4init_memory( (int) num_base, (int) num_index,
                  num_blocks, eval_space )

   Description
          'd4init_memory' can be used as a sophisticated replacement
          for 'd4init'. Use 'd4init_memory' to explicity specfiy
          inital memory allocation.

          Parameters 'num_base' and 'num_index' are not limits.
          However, if the exact number of index files and databases
          are specifed, no memory will be wasted and memory
          fragmentation will be reduced.

   Parameters
          Name        Use

          num_base    The number of databases to allocate memory for.

          num_index   The number of index files to allocate memroy for.

          num_blocks  The number of index file blocks to allocate
                  memory for. Blocks are used to buffer index
                  file data. If 'i4reindex' or 'i4index' are
                  called, this number should never be below
                  '(int) 10'.

                  For maximum speed, this number can be as high
                  as '(int) 100' when using dBASE index file
                  compatibility and '(int) 50' when using Clipper
                  index file compatibility. Note that these large
                  numbers are only feasable when using the
                  compact, large, or huge memory models.

          eval_space  This is the number of bytes of memory which are
                  allocated for the expression evaluation module.
                  The default 3k of memory is plenty for even
                  most complicated dBASE expressions. The
                  expression evaluation module will generate an
                  error message if too little memory is available.

   Returns
          Value       Meaning

           0          Success.

          -1          Out of memory. Unless 'u4error' is modified,
                  this is a critical error and will never occur.

   Example
          /* These are the defaults supplied by 'd4init' */

          d4init()
          {
              return( d4init_memory( 10, 10, 12, 3000) );
          }

d4lock

   Usage
          int  d4lock( (long) lock_code, (int) do_wait )

   Description
          'd4lock' is used to lock the selected database. The whole
          file may be locked, a specific record may be locked, or the
          record count bytes may be locked. If a record is already
          locked, locking another record automatically unlocks the
          first record.

          If you have already locked the specified portion of the
          database, 'd4lock' will detect this and return immediately
          with a succesfull return. In addition, if 'do_wait' is
          FALSE (0), 'd4lock' will return immediately; or, if
          'do_wait' is TRUE (non-zero), 'd4lock' will wait until the
          specified file portion is available, lock it, and then
          return successfully. For example, when the complete file is
          locked, any call to 'd4lock' will return successfully.

   Parameters
          Name        Value        Meaning

          lock_code   >0           Lock the Specified Record.
                  -1           Lock the Whole File.
                   0           Lock the Record Count Bytes.


          do_wait      0           Do not Wait.
                   1           Wait until Locked.

   Returns
          Value       Meaning

           0          Success.

           1          Record Does not Exist.

          -1          Error.

          -2          Locked by another user and 'do_wait' is zero.

   Example
          /* Wait for the entire file to be locked */
          rc = d4lock( -1L, 1 );

d4pack

   Usage
          int d4pack()

   Description
          'd4pack' removes all the records in the selected database
          which have been marked for deletion.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   Locking
          The database and its index files are locked for the
          duration of the pack and then are all unlocked.

   See Also
          d4delete, d4recall

   Example
          d4delete( 2L );
          d4pack();


d4ptr

   Usage
          BASE *  d4ptr()

   Description
          Returns a pointer to the database structure which describes
          the currently selected database.

          If no database has been opened, '(BASE *) 0' is returned.

   Warning
          If any calls to 'd4use', 'd4close', or 'd4close_all' is
          made, this pointer becomes obsolete and 'd4ptr' must be
          called again.

   Example
          # include <d4base.h>

          /* Get the selected database's record length */
          int buffer_len()
          {
              return( d4ptr() ->buffer_len );
          }


d4recall

   Usage
          int  d4recall( (long) record_number )

   Description
          If the specifed record is marked for deletion, the mark is
          removed. The record is read into the record buffer, the
          deletion flag is changed into a blank character, and then
          the record is written again.

   Returns
          Value       Meaning

           1          No such record.

           0          Success.

          -1          Error reading or writing the database.

   Locking
          The record is locked.

   See Also
          d4delete, d4pack

   Example
          d4recall( 2L );


d4reccount
   Usage
          long  d4reccount()

   Description
          The number of records in the database is returned. This
          value is determined from the size of the file.
          Consequently, Code Base does not need to do any locking to
          do this operation.

   Returns
          Value       Meaning

          >= 0        The number of records in the database.

            -1        No database is selected.

   Locking
          None.

   Example
          /* Dump the contents of the database to the current window */

          for ( rec = 1L; rec <= d4reccount(); rec++ )
              w4( w4row() + 1, 0, f4record() );


d4recno

   Usage
          long  d4recno()

   Description
          The current number is returned.

   Returns
          Value       Meaning

          >= 1        The current record number.

             0        There is no current record number.

   Example
          /* Read the next record */
          d4go( d4recno() + 1L );


d4ref

   Usage
          int  d4ref( (char *) name )

   Description
          Returns a reference integer to a specified database. If no
          file extension is specified, '.DBF' is assumed. This is the
          same reference number which was returned when the database
          was orginally opened.

   Returns
          Value       Meaning

          >= 0        The database reference number.
            -1        The database is not open.

   Example
          d4select( d4ref( "ACCOUNT.DBF" ) );


d4seek

   Usage
          int  d4seek( (void *) search_string )

   Description
          d4seek searches using the selected index file. If no index
          file is selected, the last opened index file for the
          database is used. If the search string is located, 'd4go'
          is called to go to the associated record.

          When searching index files with date keys, a character
          string with a "CCYYMMDD" format is used.

          In addition, if the index file has a numeric key, use a
          pointer to a 'double' as a search parameter. When the
          search value is in character format, covert it into a
          double and then cast it's pointer as a '(void *)'. Refer to
          the examples below.

   Returns
          Value       Meaning

           0          The value was found.

           1          Inexact Find; if the seach value was found but
                  had fewer characters than the index file
                  keys, '(int) 1' is returned.

                  Example:
                 If "Jackson" was the index file key value,
                 'd4seek( "Jack" )' would locate "Jackson"
                 but would return '(int) 1' rather than
                 '(int) 0'.

                  This return is not possible for index files
                  with numeric or date keys.

           2          On Record After; If the search value is not
                  located, the record immediatley after the key
                  will be read and the return will be '(int) 2'.

           3          End of File; If the search value is greater
                  than any value in the index file, '(int) 3' is
                  returned.

          -1          Error.

   Locking
          The current index file and the located record are all locked.

   Examples
          void  search_examples()
          {
              double doub_srch ;
              int    rc ;

              /* Search for a Date Value */
              i4select( i4ref( "DATE.NDX" ) ) ;
              rc = d4seek( "19880130" ) ;

              /* Search for a Numeric value */
              i4select( i4ref( "NUMBER.NDX" ) ) ;
              doub_srch = c4atod( "195.3", 5) ;
              rc = d4seek( &doub_srch ) ;

              /* Search for a Character String. The index file key
             expression could be "UPPER(NAME)". Using the 'UPPER'
             function makes the search case insensitive.
              /*
              i4select( i4ref( "NAME.NDX" ) ) ;
              rc = d4seek( "JACK" ) ;

              /* Search for Last Name plus First Name. In this
             example, the index file key expression is
             "LAST+FIRST". LAST is a 15 character field and FIRST
             is a 10 character field. The complete search key is
             provided. Consequently, 'd4seek' will return with an
             exact find if the record is located.
              /*
              i4select( i4ref( "FULL_NAME" ) ) ;
              rc = d4seek( "SMITH          JOHN      " );
          }

d4select

   Usage
          int  d4select( (int) base_ref );

   Description
          Select the database which the other database routines will
          act on. The 'base_ref' is the reference number which is
          returned by the 'd4use' and 'd4ref' routines. If 'base_ref'
          is '(int) -1', no selection is made. Regardless, the
          previously selected database reference number is returned.

   Returns
          Value       Meaning

          >= 0        The previous database reference number.

            -1        No database was previously selected.

   Example
          /* Initialize some variables */
          invoice_ref = d4use( "INVOICE" ) ;
          invoice_name = f4ref( "NAME" ) ;

          customer_ref = d4use( "CUSTOMER" ) ;
          name_index_ref = i4open( "CUS_NAME" ) ;
              .
              .
          /* Position to the top of "INVOICE.DBF". Save the current
             database's reference number.
          */
          prev_ref = d4select( invoice_ref ) ;
          d4top() ;

          /* Lookup field "NAME" from "INVOICE.DBF" in index file
             "CUS_NAME.NDX" of database "CUSTOMER.DBF".
          */
          d4select( customer_ref ) ;
          i4select( name_index_ref ) ;
          d4seek( f4str( invoice_name ) ) ;

          /* Select the previous database */
          d4select( prev_ref ) ;

d4skip

   Usage
          int  d4skip( (long) num_records )

   Description
          This routine skips 'num_records' from the current record
          number. The selected index file will be used. If no index
          file is selected, record number ordering will be used.

          After the new record is located, it will be read into the
          record buffer and will become the current record.

   Returns
          Value       Meaning

           0          Success.

           1          Skipped to top of the file.

           3          Skipped to the end of the file.

          -1          Error.

   Locking
          The current index file and the new record are locked.

   Example
          rc = d4skip( -1L ) ; /* Skip back one record */


d4top

   Usage
          int  d4top()

   Description
          The top record in the index file is read. If no index file
          is selected, this will be record one.

   Returns
          Value       Meaning

           0          Success.

           3          End of File(The database is empty.)

          -1          Error.

   Locking
          The top record is locked. If and index file has been
          selected, it will also be locked.

   Example
          if ( (rc = d4top() ) < 0 )   return -1 ;
          if ( rc == 3 )  do_eof_action() ;


d4unlock

   Usage
          int  d4unlock( (long) lock_code )

   Description
          'd4unlock' removes locks on the currently selected database
          as specified by the parameter. If the specified locks do
          not exist, 'd4unlock' does nothing and returns 'Success'.

   Parameter
          Value       Meaning

           1          If a specific record is locked, it will be
                  unlocked.

          -1          Unlock all locks on the currently selected
                  database and its index files.

           0          Unlock only the Record Count Bytes.

   Return
          Value       Meaning

           0          Success.

          -1          Error.

   Example
          /* Unlock the selected database and its index files */
          d4unlock( -1L ) ;


d4use

   Usage
          int  d4use( (char *) name )

   Description
          Opens and selects the specified database. If no file
          extension is specified, ".DBF" is assumed.

   Returns
          Value       Meaning

          >= 0        The database reference number corresponding to
                  the database. This number can be used as a
                  parameter to routine "d4select".

            -1        Error.

   Locking
          Unlocked on completion.

   Example
          account_ref = d4use( "ACCOUNT.DBF" ) ;

          /* Note that the two backslashes are interpreted by the 'C'
             compiler as a single backslash.
          */
          cust_ref = d4use( "C:\\data\\customer" );


d4use_excl

   Usage
          int  d4use_excl( (char *) name )

   Description
          This routine is identical to 'd4use' except that it locks a
          database after it has been opened.

   Hint
          If you are writing a single user application, use
          'd4use_excl' rather than 'd4use'.  In response, the program
          will execute slightly faster.

   Example
          d4use_excl( name )
          char *name ;
          {
              int rc ;
              if ( (rc = d4use(name) ) < 0 )  return -1 ;
              if ( d4lock( -1L,1 ) < 0 )  return -1 ;
              return( rc ) ;
          }


d4write

   Usage
          int  d4write( (long) record_number )

   Description
          'd4write' writes the record buffer to the specified record
          number. All opened index files are maintained. If the
          'record_number' is 0L or is greater than the number of
          records in the database, the record buffer is appeneded to
          the database.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

          -2          There was a duplicate key for an unique key
                  index file. Consequently, the record was not
                  written.

                  By default, external variable 'v4unique_error'
                  is set to '(int) 1'. If this variable is
                  changed to '(int) 0', routine d4write will
                  never return '(int) -2'. Instead, the record is
                  written, no entry is made in the unique key
                  index file, and '(int) 0' is returned.

   Locking
          If the record already exists, it is locked; if the record
          is being appended, no locking is necessary. All of the
          index files are locked before they are updated.

   Example
          /*  Append a blank record */

          /* Blank the record buffer */
          d4go( OL ) ;

          /* Append the record in the record buffer to the end of the
             database
          */
          d4write( OL );


d4zap

   Usage
          int  d4zap( (long) start_rec, (long) end_rec )

   Description
          The stated range of records are removed. If "end_rec" is
          less than "start_rec", no records are removed. All index
          files are re-indexed. Record number ordering is always used.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   Locking
          The database and index files are locked while 'd4zap' is
          executing and then are unlocked.

   Warning
          Be careful when using this routine as it can immediately
          remove large numbers of records.

   Example
          /* Zap the entire database */
          d4zap( 1L, d4reccount() );



EXPRESSION EVALUATION ROUTINES

   It is necessary to evaluate dBASE expressions. For Example, 'i4index' is
   passed a dBASE expression as a parameter. The appendices on expressions
   and functions describe dBASE expressions in-depth.

   Code Base evaluates expressions as a two step process. First, the
   expression is pseudo-compiled. The the pseudo-compiled expression is
   executed to return the result. This is efficient when expressions are
   evaluated repeatedly as the pseudo-compiled form only needs to be
   generated once.

   For those who only wish to calculate an expression once, 'e4eval' is
   available. Otherwise, call 'e4parse' to pseudo-compile the expression and
   then call 'e4exec' whenever the pseudo-compiled expression needs to be
   interpreted.

   Hint:
    Avoid using the expression evaluation module to do calcuations which
    might have been done using the field routines. Otherwise, the
    application will execute more slowly than it should. The expression
    evaluation module is more suited for doing calcualtions in response
    to interactive queries.


e4eval

   Usage
          void *  e4eval( (char *) exprt_ptr )

   Description
          'e4eval' evaluates a dBASE expression and returns a pointer
          to an internal static buffer containing the result.

   Parameter
          'expr_ptr' is a pointer to a dBASE expression. This
          expression may contain field names, functions, operators,
          and references to other databases.

          For more information, refer to the appendices on expressions.

   Returns
          The result can be in a different format depending on its
          type:

          Type        Format

          Date        CCYYMMDD (Century, Year, Month, Day).

          Character   ASCII String.

          Numeric     Double.

          Logical     int (0 for false, other for true).

          (void *) 0  Error.

   Note
          The type of the result can be determined by calling 'e4type'.

   Example
          /* AMOUNT - A numeric field of the selected database */
          /* CENTS  - A numeric field of BASE.DBF */
          printf ( "\n Expression Result: %f",
             e4eval( "AMOUNT* (100 + BASE->CENTS)" ) ) ;


e4exec

   Usage
          void *  e4exec( (char *) compile_ptr )

   Description
          The pseudo-compiled expression from the routine 'e4parse'
          is interpreted. A pointer to an internal static buffer
          containing the result is returned.

   Parameters
          'compile_ptr' points to the 'pseudo-compiled' form of the
          expression.

   Returns
          Refer to 'e4eval'. The returns are identical.

   Example
          void exec_amount()
          {
              char *   compile_ptr ;
              char *   result_ptr ;

              e4parse( "AMOUNT", &compile_ptr ) ;
              result_ptr = e4exec( compile_ptr ) ;

              /* Check the type of  *result_ptr */
              if ( e4type() == 'N' )
             printf( "\n Numeric Result:  %f",
                  *((double *) result_ptr) ) ;
              if ( e4type() == 'C' )
             printf( "\n Character Result:  %S",
                  (char *) result_ptr) ;
              /* Free the Memory Allocated by e4parse */
              free( compile_ptr );
          }


e4parse

   Usage
          int  e4parse( (char *) expr_ptr, (char **) &compile_ptr )

   Description
          'e4parse' pseudo-compiles a dBASE expression so that it can
          be efficiently interpreted by 'e4exec'.

          Memory is allocated for the pseudo-compiled expression
          with 'malloc'. Consequently, after the compiled expression
          is no longer needed, it is necessary to free it with a call
          to 'free'.

   Warning
          If a reference database is closed and re-opened, it is
          necessay to pseudo-compile the expression again.

   Returns
          Value       Meaning

          >= 0        The number of bytes in the pseudo-compiled
                  expression.

            -1        Error.

e4priority

   Usage
          int  e4priority( (char) operator_char )

   Return
          'e4priority' returns the numerical priority of a charcater
          operator.

   Note
          This function is intended primarily for use by 'e4parse'.

   Example
          The priority for the operator '*' is greater than the
          priority of the '+' operator.


e4name

   Usage
          char *  e4name( (char) op_code )

   Return
          Returns a pointer to the name of the operator corresponding
          to an internal 'op_code'.

   Note
          This routine is used to generate error information on
          illegal expressions.


e4type

   Usage
          char  e4type()

   Description
          'e4type' returns the type of the last expression evaluated
          by 'e4exec' or 'e4eval'.

   Returns
          Value       Meaning

          'C'         Character

          'N'         Numeric

          'D'         Date

          'L'         Logical



FIELD ROUTINES

   The field routines manipulate the record buffer and return field
   information. Note that there is only one record buffer per database and
   that the database routines read nad write that buffer.

   There are two methods which can be used to manipulate the record buffer.
   First, routines such as 'f4replace' and 'f4ptr' can be used with field
   reference numbers. The advantage of this method is that an executable
   program can work flawlessly after database fields are are added, removed
   or modified. In addition, the programmer does not have to understand the
   internal formatting of a database record buffer.

   If the programmer understands the internal format of record buffer( see
   Code Base Internals), the record buffers can be manipulated directly. The
   best technique is to use 'f4record' to assign a structure pointer to the
   begninning of the internal Code Base record buffer. Structure memebers
   would correspond to the different database fields.

   Hint:
    If field reference numbers are used, it works well to open the
    databases at the beginning of the program and assign field reference
    values to long integer variables immediately. By declaring the field
    reference variables globally, they can be used from any routine! In
    addition, Code Base knows which field reference number corresponds to
    which database. Consequently, it never matters which database is
    selected useing the field routines!!

   Warining:
    Do not assume that the field reference number for the first field is
    zero, and that the field reference number is one for the second
    field, ...  This is only true for the first database which is opened
    and may not be true in subsequent versions of Code Base. Call 'f4ref'
    or 'f4j_ref' to obtain field reference numbers.


f4decimals

   Usage
          int  f4decimals( (long) field_ref )

   Description
          If 'field_ref' corresponds to a numeric field, 'f4decimals'
          returns the number of decimals in the field. Otherwise,
          zero is returned.

   Returns
          Value       Meaning

          >= 0        The number of decimals.

            -1        Illegal Parameter.


f4j_ref

   Usage
          long  f4j_ref( (int) j_field )

   Description
          'f4j_ref' returns a field reference number corresponding to
          the j'th database field. The field reference number will be
          for the selected database.

   Note
          'j_field' must be between one and the number of fields.
          (ie. 1 <= j_field <= f4num_fields() )

   Returns
          Value       Meaning

          >= 0        A field reference number.

            -1        Illegal Parameter.

   Hint
          Field reference numbers are in consecutive order.
          Consequently f4j_ref(j)+1 is equal to f4j_ref(j+1) as long
          as the database has more than 'j' fields.

   Warning
          The field reference number is only valid while the database
          is open. If the database is closed and opened again,
          'f4j_ref' must be called again to obtain the field
          reference number.

   Example:
          /* Print out the Database Field Names */
          for ( j = 1; j <= f4num_fields(); j++ )
              w4( j, 0, f4name( f4j_ref(j) ) ) ;


f4name

   Usage
          char *  f4name( (long) field_ref )

   Description
          'f4name' returns a pointer to the field's name. A null
          pointer is returned if the field reference number is not
          valid.


f4num_fields

   Usage
          int  f4num_fields()

   Description
          'f4num_fields' returns the number of fields in the
          currently selected database. If no datbase is open, -1 is
          returned.


f4ptr

   Usage
          char *  f4ptr( (long) field_ref )

   Description
          'f4ptr' returns a pointer, within the database buffer, to
          the specified field. As the pointer points directly to the
          data, it is not null terminated. The field data is followed
          immediately by the data of the next field. A null pointer
          is returned to indicate an illegal parameter.

   Note
          All data in the record buffer is stored as ASCII
          characters. Numeric fields are formatted according to their
          width and decimal places; logical fields contain 'T','t',
          'Y', or 'y' to represent TRUE or contain 'F','f','N', or
          'n' to represent FALSE; finally, date fields are formatted
          'CCYYMMDD" (Century, Year, Month, Day). For example, the
          buffer for a numeric field with a width of five and two
          decimal places would store '(double) 3.4' as "3.40"; the
          date March 15, 1988 would be stored as "19880315".

   Warning
          If the corresponding database is closed and then reopened,
          the pointer must be reassigned.


f4record

   Usage
          void *  f4record()

   Description
          Routine 'f4record' returns a pointer to the beginning of
          the record buffer.

          The returned pointer could be assigned to a 'C' structure
          pointer for direct data access. As all database fields are
          internally stored in ASCII format, the members of the 'C"
          structure will all be of type 'char' or and array of type
          'char'. Structure members correspond, in order, to the
          database fields. In addition, the number of 'char' array
          elements of each structure member will correspond to the
          widths of each database field.

   Note
          As explained in the Appendix on 'Conde Base Internals', the
          format of the Code Base record buffer is identical to the
          way dBASE stores its record data on disk. All data is in
          ASCII and there are no seperators between fields.

          The first byte of the record buffer is a deletion flag
          which is an asterisk ('*') if the record is marked for
          deletion and is otherwise blank.

   Warning
          If the database is closed and reopened, the pointer must be
          reassigned.

   Example:
          typedef struct
          {
              char deleted ;          /* The deletion flag */
              char last_name[30] ;    /* Field 1.  Width 30 */
              char first_name[20] ;   /* Field 2.  Width 20 */
          } NAME ;

          /*
           This routine directly modifies the internal Code Base
           record buffer and then writes it.
           */

          void append_record()
          {
              NAME  *name_ptr ;

             /*
              'name_ptr' will point to the internal Code Base
              record buffer
              */
              name_ptr = (NAME *) f4record() ;

              /* Initialize the Record */
              memset( name_ptr, (int) ' ', sizeof(NAME) ) ;

              /* Copy the Data */
              memcpy( name_ptr->last_name, "JONES", 5 ) ;
              memcpy( name_ptr->first_name, "FRED", 4 ) ;

              d4write(0L) ;   /* Append the New Record */


f4record_width

   Usage
          int  f4record_width()

   Returns
          'f4record_width' returns the total number of characters in
          the record buffer. This is the sum of the field widths plus
          one for the deletion flag.


 f4ref

   Usage
          long  f4ref( (char *) field_name )

   Description
          'f4ref' returns a field reference number corresponding to
          the field name specified by the parameter. The field name
          can contain upper or lower case. In addition, it may be
          ended by a blank or a NULL.

          The database corresponding to the field name must be
          selected before calling 'f4ref'.

   Warning        The field reference number is only valid while the database

                 is open. If the database is closed and opened again,
          'f4ref' must be called again ot obtain the field reference
          number for a field. In addition, the field's database must
          be selected before calling 'f4ref'.

   Returns
          Value       Meaning

          >= 0        A field reference number.

            -1        Invalid Field Name (No Error Displayed).

   Hint
          Call 'f4ref' once for a particular field and assign the
          result to a variable as a reference to the field. If the
          variables are used throughout several source code files,
          set up an include file to declare all field reference
          variables as externals.

   Example
          #include <d4base.h>

          long m_name, m_address ;  /* Declare Globally */

          main()
          {
               d4use( "MAILING" ) ;
               m_name = f4ref( "NAME" ) ;
               m_address = f4ref( "ADDRESS" ) ;
               f4replace( m_name, "JOHN SMITH" ) ;
               do_work() ;
          }


f4replace

   Usage
          int  f4replace( (long) field_ref, (void *) value )

   Description
          This routine assigns a value to the field of a database
          buffer. The 'value' parameter is a pointer to he field's
          new value. The type of value depends on the type of the
          corresponding field. If the field is of type character or
          date, value should be a '(char *)'; if the field is of type
          numeric, value should be a '(double *)'; finally, if value
          is of type logical, value should be an '(int *)'.

          By convention, null characters are not allowed in database
          data. Consequently, if value is a string with less
          characters than database field, 'f4replace' will supply
          extra blank characters. On the other hand, if value has
          more characters than the database field, the extra
          characters will be ignored.

          Numeric doubles will be formatted in the field buffer
          according to the field's width and decimal specifications.

          Dates should be in the standard database date format:
          "CCYYMMDD" (Century, Year, Month, Day).

          Finally, logicals should be zero for FALSE and non zero for
          TRUE.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

          -2          Illegal date. The date field was set to blank.

          -3          The numeric value was too large or small to fit
                  into the field. The field was filled with
                  asterisks (*'s).

          -4          Null Pointer.

          -5          Illegal field reference number.


f4str

   Usage
          char *  f4str( (long) field_ref )

   Description
          The field's contents are copied to an internal static
          buffer and a pointer to the buffer is returned. The string
          will be terminated by a null character.

   Returns
          A pointer to the field's value is returned. An error is
          indicated by a NULL ((char *) 0) return.

   Hint
          This function is useful when you need the field's value
          ended by a null character.

   Warning
          Each time 'f4str' is called, the static buffer is overlaid
          with data from the nrw field.

   Example
          void  say_field( field_name )
          char *  field_name ;
          {
             char *  ptr ;

             ptr = f4str( f4ref( field_name ) ) ;
             w4( w4row()+1, 0, ptr ) ;
          }

f4true

   Usage
          int  f4true( (long) field_ref )

   Description
          'f4true()' is used to determine if a logical field is true
          or false.

   Returns
          Value       Meaning

           1          The field is true.
           0          The field is false.
          -1          Error.


f4type

   Usage
          char  f4type( (long) field_ref )

   Description
          All fields are of type Character, Numeric, Floating Point,
          Date, or Logical. 'f4type' returns the type of a specified
          field. Floating point fileds are the same as numerice
          fields. To maintain compatibility with dBASE III, avoid
          using floating point fields.

   Returns
          Value       Meaning

          'C'         Character.

          'N'         Numeric.

          'F'         Floating Point.

          'D'         Date.

          'L'         Logical.

          'M'         Memo.

          '\0'        Error.


f4value

   Usage
          double  f4value( (long) field_ref )

   Description
          'f4value' is used to return the value of a numeric field as
          a '(double)'.

   Returns
          The value of the field. If 'field_ref' is not a legitimate
          field reference number, the result is undefined.


f4width

   Usage
          int  f4width( (long) field_ref )

   Description
          All fields have a fixed width in bytes (characters).
          'f4width' returns the width of the specified field.

   Returns
          Value       Meaning

          >= 0        The field width.

            -1        Error.



GET ROUTINES

   The Get Routines build upon the Windowing Routines to interactively enter
   information into any "C" variable or any database field.

   Some features include picture templates, user defined input validation,
   delimiters, special get attributes, and scrolling within any entry area.

   There are serval Get Routine categories:

       Category          Routines in Category

       Get Initialize    g4, g4double, g4field, g4int, g4logical, g4long,
             g4numeric
       Pre-Modifier      g4attribute, g4delimiter
       Post-Modifier     g4call, g4message, g4picture, g4upper, g4valid,
             g4width
       Miscellaneous     g4alloc, g4bell, g4bell_set, g4display, g4read,
             g4release

   To use the Get Routines it is necessay to combine at least one 'Get
   Initialize' routine with 'g4read'. (Remember to call 'w4define', 'd4init',
   'd4use', or 'd4create' to create a window for the entry areas. 'd4init',
   'd4use' and 'd4create' the default window.)

   Get Example:

       g4int( 5,5, &i_value ) ;   /* Define the Get */
       g4read() ;  /* Do the Read */

   In general, a series of Get Initialize routines are called to specify what
   information is to be read from which portions of the selected window.
   Then 'g4read' is called to interact with the user to obtain the
   information specified by the previous Get Initialize routines.
   Post-Modifier routintes are called after a Get Initialize routine and
   effect only the entry area created as a result of that Get Initialize
   call. Pre-Modifier routines are called before the corresponding Get
   Initialize routines. They change settings which effect all entry areas
   created by subsequent Get Initialize calls.

   Saved Get information is attached logically to the currently selected
   window. If the window is closed all of the saved information is released.

   The routine declarations are in header file 'w4.h'.


g4

   Usage
          void  g4( (int) row, (int) column, (char * ) str )

   Get Category
          Get Initialize

   Description
          'g4' specifies an entry area for the read of a character
          buffer.

          By default, 'str' must point to a null terminated character
          string. However, if a picture is specified, the length of
          the picture will specify the length of the buffer.
          Altemately, a call to 'g4width' takes precedence over both
          the picture and the string lengths.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          str         A pointer to the string which is initially
                  displayed in the entry area. This string will
                  be replaced by the final result.


g4alloc

   Usage
          GET *g4alloc( (int) row, (int) column, (void *) data_ptr,
                  (char) type )

   Description
          This is a low level routine which is used by higher level
          Get Initialize routines.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          data_ptr    A pointer to the default value which is
                  initially displayed in the entry area. This
                  default will be overlaid with the result.

          type        A code used to represent the type of data
                  entry. The legitimate codes are as follows:

                 Code      Meaning

                 'C'       Character.
                 'D'       Date.
                 'L'       Logical.
                 'N'       Numeric.
                 'd'       double.
                 'l'       long.
                 'i'       integer.

   Returns
          A pointer to a 'GET' data structure is returned. This
          structure is used to store various pieces of information
          specified by the Get Initialize routine, the Pre-Modifier
          routines, and the Post-Modifier routines.

          '(GET *) 0' is returned if there is no memory left and if
          'u4error' has been modified to return on this error.


g4attribute

   Usage
          long  g4attribute( (long) attribute )

   Get Category
          Pre-Modifier

   Description
          Every entry area can have its own attribute character.
          'g4attribute' sets the 'get attribute' for entry areas
          corresponding to subsequent Get Initialize routines calls.

   Parameter
          The new attribute character is represented as an intger
          between '(int) 0' and '(int) 0xFF'. If the 'attribute'
          parameter is not a legitimate attribute character, the
          current 'get attribute' is not changed.

   Returns
          The current 'get attribute' character is returned.

   See Also
          Refer to 'w4attribute' for more information on attributes.


g4bell

   Usage
          void  g4bell()

   Description
          Causes the computer to sound its bell.

   Note
          'g4bell_set' must be called first to set the bell switch on.


g4bell_set

   Usage
          void  g4bell_set( (int) switch )

   Description
          'g4bell_set' turns the bell switch on or off. If the bell
          is switch on then routine 'g4bell' sounds the bell and
          'g4read' will sound the bell after an entry area is filled.

   Parameter
          'switch' is zero to turn the switch off and is non-zero to
          turn the switch on.


g4call

   Usage
          void  g4call( (GET_ROUTINE *) routine, (int) call_data )

   Get Category
          Post-Modifier

   Description
          The main purpose of 'call' routines is to allow data entry,
          by menus, into entry areas. Code Base supplies two 'call'
          routines for this purpose: 'g4menu' and 'g4menu_help'.
          Refer to these routines and to routine 'n4get_calc'.

          It is possible, although difficult, to write a specialized
          'call' routine or to modify 'g4menu' or 'g4menu_help'. To
          do so, it may be necessary to learn how routine 'g4read'
          works by stepping through it with a debugger. The following
          information defines a 'call' routine:

          'g4call' specifies a routine, corresponding to an entry
          area, which 'g4read' calls before requesting any keyboard
          input from the user. The routine is only called when
          'g4read' is on the entry area which has just been defined.

          A user defined 'call' routine must be of type
          'GET_ROUTINE'. This means the routine follows the following
          calling conventions:

              int  call_routine( (GET *) get_ptr, (char *)
                    data_buffer, (int) call_data )

          Call routine parameter 'get_ptr' points to a structure of
          type 'GET'. This structure stores information about the
          defined entry area.

          Parameter 'data_buffer' points to the currently entered
          information. Regardless of the data type being entered,
          'data_buffer' always contains ASCII characters.

          'call_data' is the integer passed in the call to routine
          'g4call'. The meaning of this integer parameter is defined
          by the specific 'call' routine.

          Depending on the value returned by the 'call' routine,
          'g4read' performs a different action:

          Value       Action

          > 0         'g4read' will take this as input data, exactly
                  as if it was read from the keyboard.
            0         Read the next keyboard character as normal
                  input data.
           -1         Call this call routine again without getting
                  any keyboard data from the user.



g4char

   Usage
          int  g4char()

   Returns
          'g4char' reads a character from the keyboard and returns it
          as an integer.

          A special header file, 'g4char.h', has been provided which
          defines all of the special extended character set key
          codes. For example, F1 is defined to be 0x3B00. This is the
          value returned by 'g4char' when function key 1 is pressed.


g4date

   Usage
          void  g4date( (int) row, (int) column, (char *) date_ptr )

   Description
          'g4date' specifies the entry area for the read of a date.
          When using the default picture of "MMM/DD/YY", the month is
          entered as three characters (ex. "Jan").

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          date_ptr    A pointer to the 'date' which is initially
                  displayed in the entry area. This 'date', of
                  format "CCYYMMDD", will be overlaid with the
                  final result.


g4delimiter

   Usage
          char *  g4delimiter( (char *) delimiter )

   Get Category
          Pre-Modifier

   Description
          Subsequent 'get' calls will use the specified delimiter
          characters.

   Parameter
          'delimiter' points to a string of up to two delimiter
          characters. These characters will appear on each side of
          the corresponding entry area respectively. If the string
          contains a single character, it will be used to delimit
          both ends of the entry area.

   Returns
          A pointer to the two current delimiter characters is
          returned. This string in NOT null terminated.


g4display

   Usage
          void  g4display()

   Description
          All of the default 'get' values will be displayed in their
          entry areas using the current 'get' attribute.


g4double

   Usage
          void g4double( (int) row, (int) column, (double *)
                  double_ptr )

   Get Category
          Get Initialize

   Description
          'g4double' specifies an entry area for the read of a
          double. By default, the entry area is formatted with two
          decimal places and a total width of eight.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          double_ptr  A pointer to the 'double' which is initially
                  displayed in the entry area. This 'double' will
                  be overlaid with the final result.

   Note
          'g4picture' changes the format of a 'double' read.

   Example
          g4double( 5, 5, &value ) ;
          g4picture( "######.###" ) ;
          g4read() ;


g4field

   Usage
          void  g4field( (int) row, (int) column, (long) field_ref )

   Get Category
          Get Initialize

   Description
          'g4field' specifies an entry area for the read of a
          database field.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          field_ref   The field reference number of the field to be
                  entered.

   Example
          g4field( ++r,c, f4ref( "LAST_NAME" ) ) ;
          g4read() ;

   See Also
          Field Routines


g4init

   Usage
          void  g4int( (int) row, (int) column, (int *) int_ptr )

   Get Category
          Get Initialize

   Description
          'g4init' specifies an entry area for the read of an
          integer. By default, the entry will be formatted with be
          formatted with a width of 4.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          int_ptr     A pointer to the 'integer' which is initially
                  displayed in the entry area. This 'integer'
                  will be overlaid with the final result.

   Example
          g4int( r,c, &i_value ) ;
          g4picture( "999999" ) ;   /* Change the Format */
          g4read() ;


g4logical

   Usage
          void  g4logical( (int) row, (int) column,
                  (int *) logical_ptr )

   Get Category
          Get Initialize

   Description
          'g4logical' specifies an entry area for the read of a
          logical character: 'T','t','F','f','Y','y','N' or 'n'.

          The logical value is stored as an integer where zero
          represents false ('F','f','N' and 'n') and a non-zero value
          represents true('T','t','Y' and 'y').

   Parameters
          Name           Use

          row            The entry area's row.

          column         The entry area's column.

          logical_ptr    A pointer to a logical value represented as
                 an 'integer'. This value will be initially
                 displayed in the entry area. The 'integer'
                 will be overlaid with the final result.

   Hint
          The only valid picture characters which may be used
          'g4logical' are 'L' (default) and 'Y'.

          To obtain a logical character result,use routine 'g4' with
          the appropriate picture.


g4long

   Usage
          void  g4long( (int) row, (int) column, (long *) long_ptr )

   Get Category
          Get Initialize

   Description
          'g4long' specifies an entry area for the read of long
          integer. By default, the entry area width is eight.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          long_ptr    A pointer to the '(long)' which is initially
                  displayed in the entry area. This long will be
                  overlaid with the final result.


g4menu

   Usage
          int  g4menu( (GET *) get_ptr, (char *) buffer,
                  (int) window_ref )

   Description
          If 'g4menu' is the call routine for an entry area, a menu
          is used to enter information into the entry area. The only
          entry possibilities will be text descriptions of the
          different menu items.

          'g4menu' is not called directly. It is used as a parameter
          to 'g4call':

              g4call( g4menu, window_ref ) ;

          'window_ref' is the window reference number corresponding
          to the menu. 'g4menu' uses the following algorithm:

              1.   Activate the menu using routine 'n4activate' and
               the window reference number 'window_ref' which has
               been saved by routine 'g4call'.

              2.   Transfer the text from the menu item choice to the
               internal Code Base 'buffer' parameter. 'g4menu'
               knows the format of 'buffer' from the information
               in the structure pointed to by 'get_ptr'.

          Refer to the menuing routines and to routine 'n4get_calc'
          to learn how to easily build the entry menu.

   Returns
          There are some keyboard characters such as SHIT_TAB, TAB,
          CTRL_HOME, CTRL_END, ESC, and CTRL_C which normally cause
          'g4read' to transfer between entry zones or to return. If
          these are pressed while the entry menu is present,
          'n4activate' returns this information to 'g4menu'. 'g4menu'
          then recognizes these characters as commands to 'g4read'
          and passes them along performing no other action.
          Otherwise, the entry data is selected and 'g4menu' returns
          RETURN to instruct 'g4read' to move to the next entry zone.


g4menu_help

   Usage
          g4menu_help( (GET *) get_ptr, (char *) buffer,
                  (int) window_ref )

   Description
          'g4menu_help' is almost identical to 'g4menu'. However, it
          allows the user to either data as normal or to use a menu
          as a set of possible entry choices.

          Specificaly, 'g4menu_help' reads all of the keyboard data
          looking for the press of the F1 help key. If F1 is pressed
          'g4menu_help' calls 'g4menu' so that the data can be
          entered using a menu. Otherwise, the keyboard data is
          returned to 'g4read' so that it can be used as normally
          entered data.


g4message

   Usage
          void  g4message( (char *) message )

   Get Category
          Post-Modifier

   Description
          'g4message' specifies a message corresponding to an entry
          area which has just been created using a 'Post-Modifier'
          routine.

   Parameters
          This a pointer to a message string which is associated with
          the entry area. The message string is automatically
          displayed when the entry area is moved upon.

   See Also
          'g4message_do'


g4message_do

   Usage
          void  g4message_do( (char *) message )

   Description
          This routine is called by 'g4read' to display the message
          strings specified by 'g4message'.

          'g4message_do' immediately displays a text string at the
          absoulte screen coordinates specified by external integer
          variables 'v4get_row' and 'v4get_col'. By default, these
          variables are '(int) 24' and '(int) 0' respectively. If the
          string is not long enough to display to the end of the
          screen, extra blank characters are displayed. If 'ptr' is
          '(char *) 0', the row starting form 'v4get_col', is blanked.

   Parameters
          'message' points to the message string.


g4numeric

   Usage
          void  g4numeric( (int) row, (int) column, (char *) num_str )

   Get Category
          Get Initialize

   Description
          'g4numeric' reads a numeric value as a character string.

          The width and the number of decimals are specified by the
          default value or by a picture.

   Parameters
          Name        Use

          row         The entry area's row.

          column      The entry area's column.

          num_str     A pointer to the string which is initially
                  displayed in the entry area. This string will
                  be replaced by the final result.


g4picture

   Usage
          void  g4picture( (char *) picture )

   Get Category
          Post-Modifier

   Description
          'g4picture' specifies an entry template for the previously
          called Get Initialize routine. The entry template
          identifies which input characters are legitimate for which
          entry positions.

   Parameters
          Characters in the string 'picture' have special meaning:

          Character   Meaning

          !           Convert to Upper Case.

          9           0-9.

          #           +,-,<space>, or 0-9.

          A           Letters Only (A-Z or a-z).

          L           y,Y,n,N,t,T,f, or F Only; Converts to T and F.

          N           Digits or Letters Only.

          X           Any Character.

          Y           y,Y,n, or N Only; Converts to Y and N.

          The character which can be entered into any character
          position is determined by the corresponding character in
          the picture template. If the character in the picture
          template is not a special picture character, it is entered
          as data.

          When entering date information, different picture
          characters apply:

          Character          Meaning

          C                  Second digit of the Century.
          CC                 First two digits of the Century.
          YY                 First two digits of the Year.
          DD                 Numeric Representation of the Day.
          MM                 Numeric Representation of the Month.
          MMM to MMMMMMMMM   Character Representation of the Month.

   Example
          g4( 8,10, telephone_string ) ;
          g4picture( "999-999-9999" ) ;

          /* Get a Date */
          g4( 9,10, date_value ) ;
          g4picture( "MM/DD/CCYY") ;   /* Ex. 01/30/1989 */
          g4read() ;


g4read

   Usage
          int  g4read()

   Description
          'g4read' interacts with the user to enter data using
          previously defined entry areas. These entry areas must have
          previously been defined for the selected window.

          The user can press the following keys to command 'g4read'
          to perform certain actions:

          Key                Action

          <Enter> or <Tab>   Moves to the next entry area. If there
                     is no 'next entry area', the read is
                     completed.

          <Shift Tab>        Moves to the previous entry area if one
                     exists.

          <Left Arrow>       Moves the cursor one position to the left.

          <Right Arrow>      Moves the cursor one position to the
                     right.

          <Ins>              Toggles between replace and insert
                     modes. When in insert mode the cursor is
                     slightly larger.

          <Del>              Deletes the character under the cursor.

          <Back Space>       Deletes the character to the left of the
                     cursor.

          <Esc>              Aborts the 'read'. 'g4read' will
                     immediately return.

          <Home>             Moves the cursor to the first postition
                     in the entry area.

          <End>              Moves the cursor to the end of the
                     entered information.

          <Ctrl Home>        Moves to the first entry area.

          <Ctrl End>         Moves to the last entry area.

          <Ctrl W>           All of these keys complete the read
          <Ctrl Q>           provided the validation routine for the
          <PgDn>             entry area returns a non-zero value.
          <PgUp>
          <Ctrl Left>
          <Ctrl Right>

   Returns
          The control character code pressed to cause an exit from
          the full screen edit. If the edit ended because the maximum
          amount of data was entered, '(int) 13' (carriage return) is
          returned.

   Hint
          Depending on the exiting character, the application could
          perform different actions.


g4release

   Usage
          void  g4release( (int) do_release )

   Description
          'g4release' sets whether 'g4read' can be called serval
          times in a row. By default, after a call to 'g4read' all of
          the 'get' information is released. However, this default
          can be changed.

   Parameter
          If 'do_release' is true (non-zero), all previously saved
          'get' information is immediately released. In addtion,
          'g4read' will release 'get' information before it returns.

          Otherwise if 'do_release' is false (zero), 'g4read' will
          not release 'get' information before it returns.

   Example
          d4learn_append()
          {
              int     row, i, rc ;

              if( d4use( "D4LEARN.DBF" ) 0 ) return -1 ;

              row = 5;

              /* Set up 'get' information */
              for ( i = 1; i <= f4num_fields(); i++ )
              g4field( row++, 20, f4j_ref(i) ) ;

              g4release( 0 ) ;    /* Do not Release */

              /* Append until <Esc> (27) is pressed */
              while( g4read() != 27 )
              d4write( 0L ) ;

              /* Release the 'get' information */
              g4release( 1 ) ;

              return 0;
          }

g4upper

   Usage
          void  g4upper()

   Get Category
          Post-Modifier

   Description
          All characters, for the previously specified entry area,
          will be converted to upper case as they are being entered.


g4valid

   Usage
          void  g4valid( (*routine) () )

   Get Category
          Post-Modifier

   Description
          'g4valid' specifies a validation routine for the previous
          Get Initialize routine. Routine 'g4read' calls the
          validation routine after information has been entered into
          the entry area. The validation routine is passed a pointer
          to the entry area's GET structure.

          If the validation routine returns '(int) 0', this validates
          the entry; if it returns a non-zero value, 'g4read' remains
          on the same entry area. It is the reponsibility of the
          validation routine to display an appropriate error message.

   Hint
          Try studying the examples in file 'w4example.c'

   Example
          #include <w4.h>

          int check_entry( get_ptr )
          GET *get_ptr ;
          {
              int *result_ptr ;

              result_ptr = (int *) get_ptr-> data ;
              if ( *result_ptr != -1 && *result_ptr != 1 )
              {
              w4( 0,0, "Enter -1 or 1 (Press a key) " )
              g4char() ;
              w4repeat( 0,0, (int) ' ', 80) ;
              return -1;      /* Not Valid */
              }

              return 0 ;  /* Vaild */
          }

          void valid_test()
          {
              int  i_data ;

              i_data = 1 ;

              g4int( 10,10, &i_data ) ;
              g4valid( check_entry ) ;
              g4read() ;

              w4( 12,10, "The result is: " ) ;
              w4int( 12, w4col(), i_data ) ;
          }


g4width

   Usage
          void  g4width( (int) width_str, (int) width_screen )

   Get Category
          Post-Modifier

   Description
          'g4width' explicitly specifies data widths and screen
          display widths.

          When entering character data, if there is more data in the
          string than room on the screen, only a subset of the string
          is displayed at one time.

   Parameters
          Name           Use

          width_str      This is the amount of character data in the
                 string parameter specified by Get-Initialize
                 routine 'g4'.

                 The data width is not flexible for 'g4double',
                 'g4int', 'g4field', 'g4logical', 'g4numeric',
                 and 'g4long'. For these cases, 'width_str'
                 should be '(int) 0'.

          width_scrren   This is the width of the entry area defined
                 by the previous Get Initialize routine.



MEMORY HANDLING ROUTINES
   This module provides memory handling for Code Base's Database, Index file,
   Block, Windowing, Menuing and Get memory structures. Using this memory
   handler, there is no Code Base specified limit to the number of opened
   databases or opened index files. In addition, small chunks of memory can
   be allocated and freed with little overhead.

   The first tow integers of each chunk of memory are reserved as pointers.
   These pointers are used to create double linked lists of allocated memory
   chunks.


h4add

   Usage
          int  h4add( (char **) ptr_ref_ptr, (int) mem_ref,
                  (int) add_ref, (int) add_before )

   Description
          'h4add' adds an allocated memory chunk to a double linked
          list.  It should not already be on one.

   Parameters
          Name           Use

          ptr_ref_ptr    A pointer to the base memory pointer. This
                 is the same value as was initially passed to
                 routine 'h4create'.

          mem_ref        A reference integer to the memory chunk.

          add_ref        The reference number to the memory chunk to
                 be inserted into the double linked list
                 either before or after 'mem_ref'.

          add_before     This value is '(int) 1' (true) if the memory
                 chunk is to be before 'mem_ref' and is
                 '(int) 0' (false) if the memory chunk is to
                 be after 'mem_ref'.

   Returns
          The value in parameter 'add_ref'.

   See Also
          'h4remove'


h4alloc
   Usage
          char *  h4alloc( (unsigned int) num_bytes )

   Description
          'h4alloc' allocates 'num_bytes' of memory and returns a
          pointer to allocated memory. The allocated memory is
          completely initialized to zeros.

   Return
          Normally, 'u4error' exits if there is not enough memory.
          However, if 'u4error' has been modified to return rather
          than exit, 'h4alloc' will return '(char *) 0' if no
          additional memory is available.


h4create

   Usage
          int  h4create( (char **) ptr_ref_ptr, (int) units,
                  (int) size, (int) expand_units )

   Description
          'h4create' does the initializing of a memory structure to
          be used with the Code Base memory handler.

   Parameters
          Name           Use

          ptr_ref_ptr    This is a pointer to the base memory pointer
                 for the memory structure.

          units          The number of chunks to be initially
                 allocated.

          size           The number of bytes in the memory structure.

          expand_units   The number of chunks to expand the structure
                 by when there are no more chunks available.

   Returns
          a '(int) -1' is returned to indicate the requested memory
          is not available. This error will only occur if 'u4error'
          has been modified not to exit an out of memory error.


h4free

   Usage
          int  h4free( (char **) ptr_ref_ptr, (int) mem_ref )

   Description
          'h4free' returns a chunk of memory to the pool of available
          memory.

   Parameters
          Name           Use

          ptr_ref_ptr    A pointer to the base memory pointer. This
                 is the value as was initially passed to
                 routine 'h4create'.

          mem_ref        A reference integer to the storage being
                 freed. This is the same integer which was
                 returned by 'h4get'.

   Return
          The reference integer to the previous memory chunk is
          returned. If a previous chunk does not exist, a reference
          integer to the next memory chunk will be returned. If there
          is no next memory chunk, '(int) -1' is returned.


h4free_chain

   Usage
          void  h4free_chain( (char **) ptr_ref_ptr, (int) mem_ref )

   Description
          'h4free_chain' calls 'h4free'repeatedly to free an entire
          chain of memory. This routine can be used as an example
          for 'h4free'.

   Source
          /* Source for 'h4free_chain' */

          void h4free_chain( ptr_ref_ptr, mem_ref)
          char  **ptr_ref_ptr ;
          int   mem_ref ;
          {
            while ( mem_ref = 0 )
                mem_ref = h4free( ptr_ref_ptr, mem_ref ) ;
          }


h4free_memory

   Usage
          void  h4free_memory( (void *) ptr )

   Description
          This routine acts exactly like the 'free' routine in the
          standard library. It is necessary because the 'free'
          routine is not available under the current version of
          Microsoft Windows.


h4get

   Usage
          int  h4get( (char **) ptr_ref_ptr, (int) mem_ref )

   Description
          A chunk of memory is allocated.

   Parameters
          Name           Use

          ptr_ref_ptr    A pointer to the base memory pointer. This
                 is the same value as was initially passed to
                 routine 'h4create'.

          mem_ref        The allocated memory chunk is placed on a
                 double linked list just after the memory
                 chunk specified by 'mem_ref'. If 'mem_ref'
                 is '-1' a new double linked list is created.
                 Otherwise, 'mem_ref' must have previously
                 been returned by 'h4get'.

   Returns
          A memory reference number to the allocated memory chunk is
          returned. This number can be zero or greater.

          A return of '(int) -1' means that no additional memory is
          available. This error only occurs if 'u4error' has been
          modified to return on an out of memory error.


h4remove

   Usage
          int  h4remove( (char **) ptr_ref_ptr, (int) mem_ref )

   Description
          'h4remove' removes a memory chunk from its double linked
          list chain but does not free it.

          'h4remove' can be sued in conjunction with 'h4add' to
          transfer a memory chunk from one linked list to another.
          They can also be used to change the ordering of a linked
          list.

   Parameters
          Name           Use

          ptr_ref_ptr    A pointer to the base memory pointer. This
                 is the same value as was initially passed to
                 routine 'h4create'.

          mem_ref        A reference integer to the memory chunk.

   Returns
          Like 'h4free', the reference to the previous memory chunk
          is returned. If a previous chunk does not exist, a
          reference integer to the next memory chunk will be
          returned. If there is no next memory chunk, '(int) -1' is
          returned.


MEMORY HANDLING EXAMPLES:

    void mem_test()
    {
    struct test
    {
        int     next, prev ;
        char    name[20] ;
        char    city[25] ;
    } *test_ptr ;

    int chain_one, chain_two ;

    h4create( (char **) &test_ptr, 10, sizeof(struct test), 5);

    /* Allocate a chunk for 'chain_one' */
    chain_one = h4get( &test_ptr, -1 ) ;

    /* Allocate another chunk for 'chain_one' */
    chain_one = h4get( &test_ptr, chain_one ) ;

    /* Assign some data */
    strcpy( test_ptr[chain_one].name, "JACKSON" ) ;
    strcpy( test_ptr[chain_one].city, "LONDON" ) ;

    /* Allocate a chunk for 'chain_two' */
    chain_two = h4get( &test_ptr, -1 ) ;

    /* Free the most recently allocated chunk of 'chain_one' */
    chain_one = h4free( &test_ptr, chain_one );
    }



INDEX FILE ROUTINES

   Index files are used to quickly and efficiently create sorted orders for
   database files. Index files contain keys and corresponding record numbers.
   The key of an index file corresponds to a dBASE expression which is
   specified when the index file is created.

   Most routines in this module specify 'index_ref' as a parameter. This is
   an index reference number which is used to specify the index file.

   Many of the index file routines are used indirectly by routines in the
   database module. However, routines
   "i4open","i4close","i4index","i4reindex","i4select", and "i4unlock" will
   be used directly.

   For each index file there is an internal pointer which points to a
   key/record number combination it the index file. A memory structure,
   containing this key/record number combination, can be accessed by calling
   routine 'b4key'. This internal pointer is set by routines 'i4top',
   'i4bottom','i4go', and 'i4seek'. Futhermore, routine 'i4skip' changes the
   internal pointer relative to the current pointer's postion.

   Like database files, index files may be locked or unlocked. Whenever an
   index file routine, which sets the internal pointer, is called, the index
   file will automatically be locked. Index files can be unlocked by higher
   level database routines and certain index file routines like 'i4unlock'
   or 'i4close'. Note that when an index file is unlocked, its internal
   pointer becomes undefined.

   Hint:
       The following routines are usually not needed by the applications
       programmer: 'i4add', 'i4bottom', 'i4go', 'i4remove', 'i4seek',
       'i4skip', 'i4top', and 'i4type'. They are called by higher level
       database routines.


i4add

    Usage
          int  i4add( (int) index_ref, (char *) key_ptr,
                  (long) rec_num)

    Description
          'i4add' adds a key and a corresponding record number to the
          index file.

   Parameters
          Name        Use

          index_ref   The index file reference number.

          key_ptr     The key to be added.

          rec_num     The record number corresponding to the key.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

           1          The key alread exists and this index file must
                  have a unique key. (See i4index).

           2          The record number already exists. Note that
                  'i4add' does not always  detect duplicate
                  record numbers.

   Locking
          If the index file is unlocked, it will be locked.


i4bottom

   Usage
          int  i4bottom( (int) index_ref )

   Description
          Positions the index file's pointer to its last position.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

           3          End of File.(This occours when the index file
                  is empty.)

   Locking
          If the index file is unlocked, it will be locked.


i4check

   Usage
          long  i4check( index_ref )

   Description
          'i4check' is used to verify that an index file is
          completely accurate. This routine is intended to be used as
          a debugging tool.

          Sometimes when databases are updated, not all of the
          corresponding index files are open. Consequently,
          non-opened index files become out-of-date. 'i4check' is
          used to verify that this is not happening.

   Returns
          Value       Meaning

           0          Success, the index file is correct.

          >0          No index file key for this record number.

          -1          Error.

          -2          'i4check' only works for databases with less
                  than 512,000 records. Alternately, there is not
                  enough memory to perform the index file check.

          -3          Index file references a record which does not
                  exist.

          -4          There are two index file entries for the same
                  record.

          -5          The index key for a specific record is out of
                  date.

          -6          Index file keys are out of order.

   Locking
          The index file and the corresponding database are locked.


i4close

   Usage
          int  i4close( (int) index_ref )

   Description
          'i4close' closes the specified index file.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.


i4eval

   Usage
          char *  i4eval( (int) index_ref )

   Description
          'i4eval' evaluates the index file expression corresponding
          to the specified index file and returns a pointer to the
          result. This result is in an internal static buffer. The
          calculation is based on the record currently in the
          database buffer.

          When using Clipper option, the result is formattted as a
          character string. For dBASE, the result will be formatted
          differently depending on the type of the index file
          expression.

          Expression Type          Result Format

              Character            Character String.
              Date                 Double representing Julian Day.
              Numeric              Double.
              Logical              A logical is not legitimate.

   Returns
          Value           Meaning

          Pointer         Pointer to result.

          Null Pointer    Error.


i4free

   Usage
          int  i4free( (int) index_ref )

   Description
          Buffered information associated with the index file is
          written to disk and the available memory is put into a pool
          to be made available to other index files.

   Hint
          It may be worth calling 'i4free' if a particular index file
          is not going to be used for a while.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.


i4go

   Usage
          int  i4go( (int) index_ref, (char *) key_ptr,
                  (long) record_number )

   Description
          Sets the internal pointer of the index file to the key,
          record number combination specified by the parameters.

   Parameters
          Name            Use

          index_ref       The index reference number.

          key_ptr         The key's value.

          record_number   The record number corresponding to the key.

   Returns
          Value       Meaning

           0          Success.

           1          The key was located but the record number was
                  not. The internal pointer will point to the key
                  just after the specified key.

           2          The key was not located. The internal pointer
                  will point to the key just after the specified
                  key.

           3          The key was not located and the end of the file
                  was reached. The internal pointer points to the
                  end of the file.
           4          The key was located but the end of the file was
                  reached before the record could be found.

          -1          Error.

   Locking
          The index file is locked.

   Hint
          This routine is useful for locating a specific database
          record in the index file and then skipping to the next
          record using the index files sorted order.


i4index

   Usage
          int  i4index( (char *) name, (char *) expr, (int) unique,
                  (int) safety )

   Description
          The index file is created, opened, and selected. This index
          file will belong to the currently selected database. If
          safety is off and the file is already open, the file will
          be closed, deleted, and then created once more according to
          the parameter specifications.

          If no file extension is specified, ".NDX" is appended to
          the name.

   Parameters
          Name        Use

          name        The name of the new index file.

          expr        A dBASE expression specifying the sort order.
                  Refer to the appendix on expressions.

          unique      Specifies whether each key in the index file
                  must be unique. When using Clipper option,
                  setting this flag to Unique results in
                  incompatibility with Clipper. 1 - Unique; else,
                  Not Unique.

          safety      Specifies whether any existing file should be
                  removed.
                  1 - Do not remove existing file. Return an
                  error if one exists.
                  0 - Remove any existing file with the same name.

   Returns
          Value       Meaning

          >= 0        The index file reference number.

            -1        Error.

   Locking
          The index file is not locked.

   Example
          i4index( "TEST", "LAST_NAME+FIRST_NAME", 0,0 ) ;
          i4index( "TEST_TWO", "UPPER(NAME)", 0,0 ) ;


i4lock

   Usage
          int  i4lock( (int) index_ref, (int) do_wait )

   Description
          If the index file is already locked an immediate succesful
          return will be made. Otherwise, an attempt is made to lock
          the index file. If 'do_wait' is FALSE (0), and the file is
          locked by another user, '(int) -2' is returned. However,
          if 'do_wait" is TRUE (1), 'i4lock' keeps trying (once per
          second) until it succeeds.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

          -2          Locked by another user.


i4open

   Usage
          int  i4open( (char *) file_name )

   Description
          'i4open' opens and selects the specified index file. The
          corresponding database must be selected.

          If the file name does not have any extension, the '.NDX'
          extension will be provided.

   Returns
          Value       Meaning

          >= 0        The index file reference number associated with
                  the newly opened index file.

            -1        Error.


i4ref

   Usage
          int  i4ref( (char *) name )

   Description
          'i4ref' returns the index file reference number of a
          previously opened index file.  This is the same number
          which was returned when the index file was originally opened.

          If no extension is present in the file name. ".NDX" is
          automatically used.

   Returns
          Value       Meaning

          >= 0        The index file reference number.

            -1        Error; the index file is not currently open.


i4reindex

   Usage
          int  i4reindex( (int) index_ref )

   Description
          'i4reindex' reindexes the specified index file. If
          'index_ref' is negative, all the index files for the
          current database will be reindexed.

          'i4free' is called for all index files. Consequently, all
          current index file positions are lost. Note that this does
          not matter when using high level database routines such as
          'd4skip' and 'd4seek'.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   Hint
          When the contents of a database are changed without the
          corresponding index file being open the index file will not
          be updated. Before using an index file which is not up to
          date, it should be reindexed.


i4remove

   Usage
          int  i4remove( (int) index_ref, (char *) key_ptr,
                 (long) rec_num )

   Description
          'i4remove' removes the key/record number combination from
          the index file.

   Parameters
          Name        Use

          index_ref   The index file reference number.

          key_ptr     The value of the key.

          rec_num     The record number corresponding to the key value.

   Returns
          Value       Meaning

           1          The key was not located and consequently could
                  not be removed.

           0          Success.

          -1          Error.

   Locking
          The index file is locked.



i4seek
   Usage
          int  i4seek( (int) index_ref , (void *) key_ptr 0

   Description
          The internal pointer is positioned to point to the first
          entry corresponding to the specified key value.

   Parameters
          Name        Use

          index_ref   The index reference number.

          key_ptr     The value of the key.

   Returns
          There are several possible returns which indicate the
          result of the search.  For a complete explanation of the
          following returns, refer to 'd4seek'.

          Value       Meaning

           0          Exact find.

           1          Inexact find.

           2          On key after.

           3          End of file.

          -1          Error.

   Locking
          The index file is locked.

   See Also
          'b4key'


i4seek_ref

   Usage
          int  i4seek_ref()

   Description
          'i4seek_ref' returns the index file reference number to the
          index file which would be used by 'd4seek'. This is
          normally the currently selected index file. However, if
          there is no currently selected index file, the reference
          number to the last opened index file is used instead. If
          there are no open index files for the database '(int) -1'
          is returned.


i4selected

   Usage
          int  i4select( (int) index_ref )

   Description
          'i4select' selects the specified index file. Subsequently,
          the database routines 'd4seek','d4top', and 'd4bottom', use
          the selected index file for their logical positioning. If
          'index_ref' is '(int) -1', record number ordering is
          selected.

   Returns
          Value       Meaning

          >= 0        The previously selected index file reference
                  number.

            -1        There was no previously selected index file.
                  Record number ordering was previously selected.

   Locking
          The previously selected index file is unlocked.



i4skip

   Usage
          long  i4skip( (int) index_ref, (long) n )

   Description
          'i4skip' skips the internal pointer the specified number of
          records. This skipping is done using the logical order
          defined by the index file.

          If there is no current position, (ex. the file is unlocked)
          skipping is relative to the top logical position.

          When skipping from an end of file or beginning of file
          position, skipping is done from the bottom or top position
          respectively.

   Parameters
          Name        Use

          index_ref   The index reference number.

          n           The number of records to skip.

   Returns
          'i4skip' returns the number of records actually skipped. If
          this number requested, an end of file or beginning of file
          has been reached.

          If an error occurs, '-n' is returned. Note that 'i4skip'
          returns immediately with a '(long) 0' if zero records and
          requested. Consequently, and error will never occur when
          'n' is '(long) 0'.

   Locking
          The index file is locked.


i4top

   Usage
          int  i4top( (int) index_ref )

   Description
          The index file's internal pointer is set to the top position.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

           3          End of file. (The index file is empty.)

   Locking
          The index file is locked.



i4type

   Usage
          char  i4type( (int) index_ref )

   Description
          The type of index file is returned as a character.

   Returns
          Value       Meaning

          C           Character Type.

          D           Date Type.

          N           Numeric Type.

   Example
          if ( i4type( i_ref) == 'C' ) do_true() ;


i4unlock

   Usage
          int  i4unlock( (int) index_ref )

   Description
          If 'index_ref' is '(int) -1' all of the index files
          corresponding to the currently selected database are
          unlocked. Otherwise, the specified index file is unlocked.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   Locking
          Index files are unlocked as described above.


i4unselect

   Usage
          void  i4unseletect()

   Description
          Record number ordering is chosen for the selected database.

   Returns
          'i4unselet' always returns '(int) 0'

   Locking
          If an index file was selected, it is unlocked.





MEMO ROUTINES

   Memo Routines record variable length test into memo files. Memo file text
   always associated with a memo field or a particular database record.
   Consequently, memo file routines, like the field routines, use a field
   reference number. Refer to the field routines for more information about
   field reference numbers.

   Code Base provides two sets of memo file routines. The first set, as
   documented in this chapter, has routine names starting with 'm4'. The
   other set, has routine names starting with 'm3'. With respect to memo file
   compatibility, dBASE III, dBASE III PLUS, Clipper, and the 'm3' Code Base
   memo file routines are all identical. Likewise, with respect to memo file
   compatibility, dBASE IV and the 'm4' Code Base routines are identical.

   From a functionality point of view, the 'm3' routines and the 'm4'
   routines are indentical. Consequently, the documentation on the 'm4'
   routines also applies to the 'm3' routines. However, due to a more
   sophisticated dBASE IV memo file format, the 'm4' routines always recover
   disk space when re-writing memo file information.

   A special routine, 'm4convert', has been provided to convert dBASE III
   memo files so that they can be used with the 'm4' routines. Another
   special routine, 'm4renamed', is used after renaming dBASE IV memo file.
   Once a converted memo file has been modified using the 'm4' routines, it
   can no longer be used by the 'm3' routines. Before this modification using
   a 'm4' routine, a converted memo file can be used normally with the 'm3'
   routines and can be read with the 'm4' routines.

   All memo file locking and unlocking is automatic.

   Warning

       dBASE IV users should not create memo files using a block size
       different from the default size of 512 bytes. This is because dBASE IV
       has a bug which immediately corrupts memo files, with a greater block
       size, after they have been renamed under DOS. For this reason,
       'd4create' always creates memo files with the default block size,
       explicit file conversion is necessary using 'm4convert', and
       'm4renamed' is used after renameing memo files.


m4check

   Usage
          (long *)  m4check( (long) field_ref )

   Description
          'm4check' analyses the contents of a memo file to determine
          how data is being stored internally. To understand the
          values returned, it is necessary to realize that when memo
          file space is freed, the free entries are chained together.
          The when additional space is needed, the free space can be
          used before additional space is allocated at the end of the
          file.

          Call 'm4check' using 'd4learn'. It is probably not
          necessary to call 'm4check' from your own programs.

   Returns
          A null pointer is returned to indicate that there is a
          problem with the memo file specified by 'field_ref'. Either
          the 'field_ref' parameter is bad, the memo file does not
          exist, the memo file is corrupted, or not enough memory is
          available to perform the check..

          Otherwise, a pointer to an array of 5 long integers is
          returned. These long integers specify the following facts
          respectively:

          Return No.  Meaning

           0          The number of free entries. This number should
                  be as low as possible.

           1          The total number of free blocks (512 bytes per
                  block). There may be more free blocks than free
                  entries as each entry can consist of one or
                  more blocks.

           2          The number of adjacent entries. This number
                  should be as low as possible as it is better to
                  have one large free entry than several small
                  adjacent entries.

           3          The number of lost blocks. This is memo file
                  space which is not used and is not in the free
                  chain.

           4          The number of used blocks.


m4convert

   Usage
          int  m4convert( (char *) file_name )

   Description
          'm4convert' writes some information to a memo file so that
          a dBASE III memo file can be used with the other 'm4'
          routines. It is safe to use 'm4convert' on dBASE III memo
          files or dBASE IV memo files with the default block size.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   See Also
          The memo file routines introduction.


m4edit

   Usage
          int  m4edit( (long) field_ref, (long) rec_num,
                  (char *) editor_name, (int) max_size )

   Description
          The memo file data is copied to a temporary file and a
          program is executed with the temporary file name as a
          parameter. Then the contents of the temporary file are
          copied back to the memo file. The first four characters of
          the temporary file name start with "MEMO" and the last four
          characters change to ensure the temporary file did not
          previously exist.

          Consequently, any editor which accepts a file name as a
          parameter can be used to modify the contents of a memo field.

          This routine is not available under the Unix/Xenix version.

   Parameters
          Value           Meaning

          field_ref       Identifies the memo field.

          rec_num         The database record number.

          editor_name     The name of a program which accepts a file
                  name as a parameter.

          max_size        The maximum length of the memo field. This
                  amount of memory is temporarily allocated
                  to hold the contents of the memo field.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

           1          Not Enough Memory.

                  No error message is displayed.

   Locking
          Record 'rec_num" is locked. The memo file is locked and
          unlocked automatically. As the temporary file is created in
          the current directory, this routines works in a multi_user
          environment provided each user has a different directory.

   Example
          m4edit( f4ref("MEMO_FLD"), 2L, "PROG", 5000 ) ;


m4exist

   Usage
          int  m4exist( (long) field_ref )

   Description
          'm4exist' determines if memo field data is present without
          reading the memo file.

   Returns
          Value       Meaning

           0          No memo field data is present for the current
                  record.

           1          Memo field data is present.

   Note
          The data currently in record buffer is used.


m4read

   Usage
          int  m4read( (long) field_ref, (long) rec_num,
                  (char *) str, (int) str_len )

   Description
          'm4read' reads a memo field into string 'str'. At most,
          'str_len' characters are read. On completion, 'str' is null
          terminated. In addition, routine 'd4go' is called to read
          record 'rec_num' into the record buffer.

   Parameters
          Name        Use

          field_ref   The field reference number of the memo field.

          rec_num     The record number of the memo data.

          str         A pointer to where the memo text is placed.

          str_len     The number of bytes of space declared for
                  string 'str'.

   Returns
          Value       Meaning

          >= 0        The number of characters actually read.

            -1        Error.

   Locking
          Record 'rec_num' is locked. The memo file is locked and
          unlocked automatically.


m4renamed

   Usage
          int  m4renamed( (char *) file_name )

   Description
          'm4renamed' is called after a dBASE IV memo file has been
          renamed under DOS. When renaming a memo file, it is
          important to rename the corresponding database at the same
          time. Memo files should have the same name as the
          corresponding database except for the tile extension which
          is ".DBT" for memo files.

   Parameter
          'file_name' is the name of the memo file which is to be
          renamed.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

m4write

   Usage
          int  m4write( (long) field_ref, (long) rec_num,
                  (char *) str, (int) str_len )

   Description
          Information is written to the memo field specified by
          'field_ref'. In the process, routine 'd4go' is called to
          read the contents of 'rec_num' and then 'd4write' is called
          to write the altered contents.

   Parameter
          Name        Use

          field_ref   The field reference number of the memo field.

          rec_num     The record number of the memo data.

          str         The string to be written.

          str_len     The number of characters to write.

   Returns
          Value       Meaning

          >= 0        The number of characters written.

            -1        Error.

   Locking
          Record 'rec_num' is locked. The memo file is locked and
          unlocked automatically.

   Warning
          The contents of the record buffer are changed.




MENUING ROUTINES

   Using the versatile Code Base Menuing Routines, it is possible to build
   almost any kind of menu. Specifically, pulldown, popup, vertical,
   horizontal, and lotus style menus can all be created.

   Any Code Base menu corresponds to a specific window. The characteristics
   of the menu window, such as the dimensions, all apply to the menu. Each
   menu has a number of menu items. These menu items correspond to the
   possible menu choices. The terms "pulldown menu" and "Lotus menu" are not
   actually a single menu according to the strict definition of a Code BAse
   "menu". Pulldown and Lotus menus actually consist of a main menu and a
   number of sub-menus.

   The following routines provide settings for the menu of the currently
   selected window:

       Routine                Quick Description

       n4attribute            Sets the default attribute for menu items.
       n4horizontal           Specifies a horizontal menu.
       n4item_width           The spacing between horizontal menu items.

   These routines provide settings which apply to a specific menu item:

       Routine                Quick Description

       n4attribute_item       Sets a specific display attribute for a menu
                  item.
       n4message              Specifies a message for the menu item
       n4key                  Sets a specific key to activate the menu item.
       n4skip_over            Specifies whether a menu item may be selected.

   Any menu item can have a corresponding 'action routine' and a 'reaction
   routine'. If a menu item has an action routine, the action routine is
   called when the menu item is activated. The reaction routine is called
   when the menu prompt is moved to the menu item.

   Action and reaction routines all have integer return codes which instruct
   routine 'n4activate', the menu activation routine, to do the following:

       Value      Meaning

       < 0        Return from the menu activation routine 'n4activate' with
          the same value as a return code.
     0        Read a command character from the keyboard.
       > 0        Interpret the value as a command character exactly as if it
          had been read from the keyboard.

   It is important to realize that routine 'n4activate' can be used as both
   an action or a reaction routine. In these cases, 'n4activate' calls itself
   to create a sub-menu. This happens when using Lotus or pulldown menus.

   There are extensive menuing examples in file 'w4example.c'. In addition,
   there is a short, yet complete and standalone, pulldown menu example under
   routine 'n4pulldown'.


n4

   Usage
          int  n4( (char *) label )

   Description
          Routine 'n4' defines a single menu item. Either all menu
          items, for a particular menu, should be defined with
          routine 'n4' or all menu items should be defined with
          routine 'n4item'. If the menu items are defined with
          routine 'n4item', the position of the menu items are
          specified exactly. However, when using routine 'n4' the
          positions are calculated and menu item scrolling is
          possible. Scrolling occurs when there is not enough room in
          the window for all of the menu items at once.

   Parameters
          'label' is a pointr to the menu item text which is
          displayed as part of the menu. The pointer should point to
          permanent rather than temporary memory as 'n4' saves only a
          copy of the pointer. If the text pointed to by 'label'
          changes, the the display text changes.

   Returns
          A menu item reference number, for the new menu item is
          returned.


n4action

   Usage
          int n4action( (ACTION *) action_routine, [p1,] [p2,] ... )

   Description
          'n4action' specifies an action routine for the menu item
          which has just bee created using either 'n4' or 'n4item'.

          It is also possible to call 'n4action' with a null action
          routine and a single integer parameter. In this case,
          'n4activate' will return the integer parameter. In this
          case, 'n4activate' will return the integer parameter if the
          corresponding menu item is chosen:

              n4action( (ACTION *) 0, integer_code ) ;

   Parameters
          'action_routine' is the name of a routine which is to be
          called by 'n4activate' when the menu item is activated.

          Parameters 'p1','p2',... are a variable number of
          parameters of optional type which are passed to the action
          routine when it is called. However, there can be a mazimum
          of four integers worth of parameters. Note if you wish to
          pass non integer data, the effect of this restriction is
          compiler and memory model dependent. That noted, for the
          Quick C, Microsoft C and Turbo C compilers on the IBM PC
          this restriction translates to the following parameter
          maximums:

              1. Four Integers.
              2. Two Pointers (Any memory model).
              3. Two Longs.
              4. One Pointer and Two Integers.
              5. One Long and Two Integers.
              6. One Pointer and One Long.
              7. One Double.

          To be safe with all compiliers, make the restriction one
          integer, one long or one pointer. To make a large amount of
          data available to an action routine, pass a pointer to a
          structure or an array containing the data.

   Hint
          Routine 'n4activate' can be used as an action routine to
          define a sub-menu. In this case 'n4activate' will call
          itself. This is an example of 'recursion'.

   Example
          #include <w4.h>

          typedef  struct
          {
              int     num_pieces ;
              long    piece_info[100] ;
              char    descriptionsp[100][20] ;
          }   MENU_DATA ;

          /* These routines are user defined */
          static  int get_data( MENU_DATA * ) ;
          static  int process_data( MENU_DATA * ) ;
          static  int sub_option_one_routine( void ) ;
          static  int sub_option_two_routine( void ) ;

          main()
          {
              int     main_menu_ref, sub_menu_ref;
              long    action_data[100] ;

              /* 'n4calc' fills in the window dimensions */
              main_menu_ref = w4define( -1,-1,-1,-1 ) ;

              /* Define three menu items */
              n4 ( "Sub Menu" ) ;
              n4action( n4activate, &sub_menu_ref ) ;

              n4( "Get Data" ) ;
              n4action( get_data, &action_data ) ;

              n4( "Process Data" ) ;
              n4action( process_data, &action_data ) ;

              /* Define the sub_menu */
              sub_menu_ref = w4define( -1,-1,-1,-1 ) ;

              n4( "Sub Option One" ) ;
              n4action( sub_option_one_routine ) ;

              n4( "Sub Option Two" ) ;
              n4action( sub_option_two_routine ) ;

              /* Automatically calculate the menu
             coordinates, sizes, and assign a default
             menu border for a vertical menu. */

              n4calc( main_menu_ref, 6,12 ) ;

              /* Activate the constructed system of menus */
              n4activate( &main_menu_ref ) ;

              w4exit (0) ;
          }


n4activate

   Usage
          int  n4activate( (int *) window_ref_ptr )

   Description
          'n4activate' activates a menu. In doing so, the associated
          window is also activated. 'n4activate' is the largest, most
          important, menuing routine. All of the other menu routines
          are called to prepare for the call to 'n4activate'.

          Before 'n4activate' returns, the menu window is deactivated
          and the previously selected window is re-selected.

   Parameters
          A menu is uniquely identified by the window reference
          number of the window which contains it. 'window_ref_ptr' is
          a pointer to the window's window reference number.

   Returns
          'n4activate' returns any negative value returned by an
          action or reaction routine. In addition, if a menu item has
          an action routine integer parameter, but a null action
          routine pointer, the action routine parameter is returned
          when the menu item is activated. Using this techinque, an
          'n4activate' can return an integer code corresponding to a
          menu choice.

          Some characters, when entered from the keyboard, cause
          'n4activate' to exit. If such a character is entered,
          'n4activate' returns it on exit. Characters which cause
          'n4activate' to exit are specified by routine
          'n4key_special'. In addition, for horizontal menus, the up
          and down arrow keys may cause 'n4activate' to return.
          Likewise, for vertical menus, the right and left arrow keys
          may cause 'n4activate' to exit. Refer to routine
          'n4arrow_exit'.

          Positive characters returned by action and reaction
          routines are treated as keyboard input by 'n4activate'.
          Consequently, if a character entered from the keyboard
          causes 'n4activate' to return, the same character returned
          by an action or reaction routine causes 'n4activate' to
          return. In this case, 'n4activate' returns the character
          value causing the exit.

          Finally, 'n4activate' returns zero if there are no menu
          items in the window or if the window is too samll.

   Note
          When using 'n4activate' as a parameter to routine
          'n4action' or 'n4reaction', it is convenient to be able to
          reference menus which have not yet been defined. This is
          why the parameter to 'n4activate' is a pointer to the
          window reference number of the menu's window.

          In the example under routine 'n4action', notice how a
          pointer to the variable 'sub_menu_ref' is passed to
          routine 'n4activate'. Later in the program, 'sub_menu_ref'
          is assigned a specific window reference number.

   See Also
          Menu Routines introduction, 'n4key_special'


n4arrow_exit

   Usage
          void  n4arrow_exit()

   Description
          Normally, <up> and <down> arrows are ignored in horizontal
          menus. In addition, <left> and <right> arrows are ignored
          in vertical menus. By calling 'n4arrow_exit' this default
          is changed for the menu of the currently selected window.
          When an arrow key, which otherwise would have been ignored,
          is pressed, 'n4activate' will return the character key code
          of the arrow key.

   Note
          This feature is necessary for pulldown menus. When a <Left>
          or <Right> arrow key is pressed, when using a pulldown menu
          system, the arrow key command must be returned to the top
          horizontal menu.


n4attribute

   Usage
          void  n4attribute( (long) attribute,
                  (long) attribute_prompt )

   Description
          'n4attribute' sets default attributes for the menu items of
          the currently selected window.

   Parameters
          Name                Use

          attribute           This is the default character for
                      subsequently defined menu items.  The
                      attribute for any particular menu item
                      can be set using routine
                      'n4attribute_item'.  If this routine is
                      not called, the default is F_WHITE.

          attribute_prompt    When interacting with a menu, the menu
                      prompt is always 'on' a particular menu
                      item. This menu item is always
                      displayed with a different attribute to
                      distinguish if from the other menu
                      items. 'attribute_prompt' specifieds
                      that special attribute for the menu of
                      the currently selected window. If this
                      routine is not called, the menu prompt
                      attributes is B_WHITE (inverse video).



n4attribute_item

   Usage
          void  n4attribute_item( (int) item_ref, (long) attribute )

   Description
          'n4attribute_item' assigns an attribute to a specifid menu
          item.

   Parameters
          Name        Use

          item_ref    The menu item reference number.
          attribute   The attribute to be assigned to the menu item.

   Example
          item_ref = n4item( 2,2, "Choice One" ) ;
          n4attribute_item( item_ref, F_BLUE ) ;


n4calc

   Usage
          void  n4calc( (int) w_ref, (int) start_row, (int) start_col )

   Description
          'n4calc' sets the window dimensions for the specified
          window. The window dimensions will be large contain the
          window's menu.

          In addition, 'n4calc' makes the menu window a popup window
          and assigns a single line border.

          If 'n4calc' detects any sub-menus, it calls itself
          recursively to define the window dimensions of the
          sub-menu's windows. The sub-menu's  windows are also made
          popup and assigned single line borders.

   Parameters
          Name        Use

          w_ref       The window reference number.

          start_row   The menu window's starting row.

          start_col   The menu window's starting column. The starting
                  column may be changed by 'n4calc' if the
                  specified value is so large the menu cannot fit
                  on the screen.

   Hint
          If you want the menu to be as far to the right as possible,
          set parameter 'start_col' to '(int) 79'.

          Like 'n4pulldown' and 'n4lotus','n4calc' lets the
          programmer quickly generate impressive looking menus.

   Example
          n4calc( w_ref, 0, 79 ) ;

          /* Replace the single line border set by 'n4calc' with a
             double line border. */
          w4border( DOUBLE, F_BLUE ) ;


n4get_calc

   Usage
          void  n4get_calc( (int) w_ref )

   Description
          It is possible to use menus to enter data into entry zones
          specified by the 'get' rouitnes. This is done using
          routine 'g4call' in conjunction with 'g4menu' or
          'g4menu_help'.

          When using a menu for this purpose, 'n4get_calc' will
          calculate the dimensions and position the menu.

   Parameters
          'w_ref' is the window corresponding to the 'get' entry areas.

   See Also
          Routines 'n4calc', 'n4pulldown' and 'n4lotus' use the same
          concept but calculate window positions and widths for
          different purposes.

   Example
          /* Example for 'n4get_calc' */
          #include "w4.h"

          static  char    last_name[20] ;

          void    enter_data()
          {
              int     get_ref, menu_ref ;

              menu_ref = w4define( -1,-1,-1,-1 ) ;
              n4( "Tim Jones" ) ;
              n4( "Fred Calvert" );
              n4( "Kenneth Powers" );

              get_ref = w4define( 10,15, 14,65 ) ;
              w4activate( get_ref ) ;
              w4( 1, 5, "Enter Last Name: " ) ;

              g4( 1, w4col(), last_name );
              g4width( (int) sizeof(last_name), (int)
                  sizeof(last_name) ;
              g4call( g4menu_help, menu_ref ) ;
              g4message( "Press <F1> for Help" ) ;

              /* 'g4call' saves the pointer to routine 'g4menu_help'
              and the menu reference number 'menu_ref'.
              Routine 'n4get_calc' looks at all of the 'gets'
              scheduled for window 'get_ref'. It recognizes the
              address of call routine 'g4menu_help' and knows
              the saved parameter 'menu_ref' must be a window
              reference number. Then it calculates appropriate
              window dimensions and an appropriate position for
              the menu window identified by 'menu_ref'. */

              n4get_calc( get_ref ) ;
              g4read() ;              /* And so on ... */
          }


n4horizontal

   Usage
          void  n4horizontal()

   Description
          By default, a menu is vertical. 'n4horizontal' changes that
          default to horizontal. The difference between a
          'horizontal' and a 'vertical' menu is that up and down
          arrow keys are used in vertical menus and left and right
          arrow keys are used in vertical menus.


n4item

   Usage
          int  n4item( (int) row, (int) column, (char *) label )

   Description
          'n4item' defines a single menu item within a window. It is
          identical to routine 'n4' except that the two additional
          parameters, 'row' and 'column', specify where the menu item
          is to be placed within the window.

          In order to successfully use 'n4item', all of the menu
          items in the window must be specified with routine
          'n4item'. In addition, every call to 'n4item', for the
          window, must have positive 'row' and 'column' parameters.

   Parameters
          Name        Use

          row         The row, within the selected window, to place
                  the menu item.

          column      The column, within the selected window, to
                  place the menu item.

          label       A pointer to the display text which identifies
                  the menu item to the user.

   Returns
          The menu reference number corresponding to the new menu item.

   Note
          Routine 'n4' calls routine 'n4item' substituting '(int) -1'
          for the row and column parameters.


n4item_text

   Usage
          (char *)  n4item_text( (int) item_ref )

   Description
          'n4item_text' returns a pointer to the text of the menu
          item specified by parameter 'item_ref'.


n4item_width

   Usage
          void  n4item_width( (int) width )

   Description
          'n4item_width' helps determine the appearance of the menu
          defined in the current window. This is only relevant when
          routine 'n4', rather than 'n4item', is used to define the
          menu items.

          'n4item_width' is used mainly to give horizontal menus
          exact column spacing. By default, there is only one column
          per menu. Consequently, it is critical to call
          'n4item_width' for horizontal menus where Code Base
          calculates the menu item positions. In addition, by using
          'n4item_width', it is possible for a menu to have several
          columns and/or rows.

   Parameter
          'width' specifies the number of characters in one menu
          column. The total number of menu columns can be determined
          by dividing the window width by the 'width' parameter.

   Example
          main()
          {
              int     w_ref ;

              /* Defines a Horizontal Menu with 2 rows and 4
              columns */
              w_ref = w4define( 0,0, 1,79 ) ;
              n4horizontal() ;
              n4item_width( 20 ) ;
              .
              .
          }


n4key

   Usage
          void  n4key( (int) chr, (int) activate, (int) highlight_pos )

   Description
          By default, it is possible to actiavte a menu item by
          pressing a key corresponding to the first character of the
          menu item description. In addition, when the description is
          displayed, this same character is displayed with an intense
          attribute.

          'n4key' changes the above defaults.

   Parameters
          Name            Use

          chr             Pressing this character causes the menu
                  prompt to move to the menu item.  If 'chr' is
                  zero, no character will correspond to the
                  menu item.

          activate        If 'activate' is TRUE (non-zero), pressing
                  the menu key activates the menu item.
                  However, if 'activate' if FALSE (zero),
                  pressing the menu key causes the menu prompt
                  to move to the menu item.

          highlight_pos   This number specifies which character of
                  the menu item description is displayed with
                  a F_INTENSE attribute. Zero specifies the
                  first character, on the second, and so on.
                  If 'highlight_pos' is '(int) -1', no
                  character will be highlighted.


n4key_set

   Usage
          void  n4key_set( (int) set_code, (int) ignore_case )

   Description
          'n4key_set' specifies some keyboard input options. These
          options apply to the currently selected menu window.

   Parameters
          Name            Value    Meaning

          set_code        0        Ignore any keyboard input except for
                       the arrow keys, <Return>, <PgUp>,
                       <PgDn>, <Home>, <End>, and the
                       special keys set by routine
                       'n4key_special'.

                  1        Default.  Move the menu prompt to
                       the first menu item which matches
                       the entered key.  Refer to routine
                       'n4key'.

                  2        The user is allowed to search for a
                       menu item by entering a string of
                       characters to search for.  In this
                       case, the menu prompt moves to the
                       item corresponding to the entered
                       characters.  Matching characters are
                       displayed intensely and blinking.

          ignore_case     0        FALSE. Be case sensitive.

                  1        This is the default, TRUE. All
                       characters are considered
                       uppercase for the purposes of
                       search comparison.


n4key_special

   Usage
          void  n4key_special( (int) up_key, (int) exit_key,
                  (int) return_start, (int) return_end )

   Description
          This routine specifies some keyboard characters which, when
          entered, cause 'n4activate' to do something special. These
          special characters apply to subsequently defined menu
          windows. Consequently, each menu window can have its own
          set of special characters.

   Parameters
          Name            Use

          up_key          This key causes 'n4activate' to return.
                  However if 'n4activate' has called itself
                  recursively, creating a submenu only the
                  lowest level submenu returns.  By default,
                  this is the <Esc> key.

          exit_key        This key causes 'n4activate' to return.  If
                  'n4activate' has called itself recursively,
                  creating a submenu, all of the 'n4activate'
                  routines will return the entered 'exit_key'.
                  By default, this key is <Ctrl C>.  In Lotus
                  style menus this key is '/'.

          return_start    This is a range of keys which cause
                  'n4activate' to return. Theses keys are
                  slightly different than the 'up_key' as the
                  only apply if the key otherwise does
                  nothing else.

          return_end      This feature can be useful in pulldown
                  menus when a set of characters, such as
                  the <Alt> keys, could potentially activate
                  menu items in the top horizontal menu.

   Hint
          The numeric value for special keys are in 'g4char.h'. For
          example, ALT_A is defined to be 0x1E00 and ALT_Q is defined
          to be 0x1000. Notice that ALT_Q < ALT_A ! consequently, the
          range ALT_A to ALT_Z does not include ALT_Q. (The original
          designers of the IBM PC assigned these out of order codes. )


n4lotus

   Usage
          n4lotus( (int) window_ref )

   Descripiton
          Once the menu items of a lotus menu have been defined,
          'n4lotus' can be used to calculate the window positions and
          dimensions. It also specifies popup menu windows and
          changes the position 'n4message_do' displays at, to the
          appropriate position.

          If the starting (row, column) position of the main lotus
          menu window has been defined using 'w4define', it will be
          used. This would move the entire menu relative to the new
          starting position.

   Parameters
          'window_ref' is the menu reference number of the main lotus
          menu.

   Example
          #include <w4.h>
          #include <g4char.h>

          main()
          {
              int  main_ref, one_ref ;

              w4clear(-1) ;   /* Clear the screen */

              /* Position the lotus menu at the bottom of the
             screen. ie (23,0) */
              main_ref = w4define ( 23,0, -1,-1 ) ;
              n4( "One" ) ;
              n4message( "Sub Choice 1     Sub Choice 2" ) ;
              n4action( n4activate, &one_ref ) ;

              /* Routine 'two_action' is executed if 'Two' is
             chosen.  */

              n4( "Two" ) ;
              n4message( "Two Action" ) ;
              n4action( two_action ) ;

              /* Define the sub-menu which is displayed if main menu
             choice 'One' is chosen */

              one_ref = w4define( -1,-1,-1,-1 ) ;
              n4( "Sub Choice 1" ) ;
              n4action( w4display, "Sub Choice 1", (char *) 0 ) ;

              n4( "Sub Choice 2")
              n4action( w4display, "Sub Choice 2", (char *) 0 ) ;

              /* Turn the menus into a 'lotus' menu */
              n4lotus( main_ref ) ;

              /* Activate the menuing system */
              while( n4activate( &main_ref ) == (int) '/' ) ;

              w4exit(0) ;
          }


n4message

   Usage
          n4message( (char *) message )

   Description
          'n4message' specifies a message corresponding to the menu
          item which has just been created using 'n4' or 'n4item'.

   Parameters
          Name        Use

          message     This message is associated with the last
                  defined menu item. The message is automatically
                  displayed when the menu prompt is moved to the
                  menu item.

   See Also
          'n4message_do'; An example is under routine 'n4lotus'.


n4message_do

   Usage
          n4message_do( (char *) message )

   Description
          This routine is called by 'n4activate' to display the
          message strings specified by 'n4message'.

          'n4message_do' immediately displays a text string at the
          absolute screen coordinates specified by external integer
          variables 'v4menu_row' and 'v4menu_col'. By default, these
          variables are 24 and 0 respectively. If the string is not
          long enough to display to the end of the screen, extra
          blank characters are displayed. If 'ptr' is '(char *) 0',
          the row, starting from 'v4menu_col', is blanked.

   Parameters
          'message' points to the message string.


n4pulldown

   Usage
          void  n4pulldown( (int) window_ref )

   Description
          Once the windows and menu items for a pulldown menu system
          have been defined, 'n4pulldown' can be used to calculate
          window dimensions and positions. In addition, 'n4pulldown'
          assigns borders, specifies popup menus, specifies the main
          menu as horizontal, and assigns special keys normally
          specified with routines 'n4key_special'.

          If the starting (row,column) position of the main menu
          window has been defined in the call ot 'w4define', those
          coordinates are the top left corner of the pulldown menu.
          Otherwise, the pulldown menu will be positioned at
          coordinates (0,0).

   Parameters
          'window_ref' is the window reference number of the pulldown
          menu's horizontal menu bar.

   Example
          #include <d4base.h>
          #include <w4.h>
          #include <stdlib.h>

          main()
          {
              int     horizontal_ref, sub_one, sub_two ;
              char    no_flds[20], *rec_ptr ;

              /* Open the database */
              if ( d4use( "TEST.DBF" ) < 0 ) exit (1) ;

              w4clear( -1 ) ;         /* Clear the Window */
              w4cursor( -1, -1 ) ;    /* Remove the cursor */

              /* Calculate some display information */
              itoa( f4num_fields(), no_flds, 10 ) ;
              rec_ptr = f4record();

              /* Define the horizontal menu bar. */
              horizontal_ref = w4define( -1,-1,-1,-1 ) ;
              /* Define the main menu items */
              n4( "Position Database" ) ;
              n4reaction( n4activate, &sub_one ) ;

              n4( "Display" ) ;
              n4reaction( n4activate, &sub_two ) ;

              /* Define the 'Display' sub_menu */
              sub_two = w4define( -1,-1,-1,-1 ) ;

              n4( "Database Record" ) ;
              n4action( w4display, rec_ptr, (char *) 0 ) ;

              n4( "Number of Fields" ) ;
              n4action( w4display, no_flds, (char *) 0 ) ;

              /* Turn the menus into a pulldown menu. */
              n4pulldown( horizontal_ref ) ;

              /* Activate the menuing pulldown system */
              n4activate( &horiziontal_ref ) ;

              w4close( horizontal_ref ) ;
              w4close( sub_one ) ;
              w4close( sub_two ) ;

              w4exit(0) ;
          }


n4reaction

   Usage
          n4reaction( (ACTION *) reaction_routine, [p1,] [p2,] [p3,]
                  [p4,] )

   Description
          'n4reaction' specifies a reaction routine for the menu item
          which has just been defined using either 'n4' or 'n4item'.
          The reaction routine is executed when the menu prompt moves
          to the corresponding menu item through arrowing or an
          appropriate key selection. 'n4activate' is used as a
          reaction routine to automatically activate the pulldown
          part of a pulldown menu system.

          'n4reaction' differs from 'n4action' only in that it
          specifies a 'reaction' routine rather than a 'action'
          routine.

   See Also
          Menuing routines introduction and 'n4action'.

   Example
          n4( "Menu Option With a Reaction Routine" ) ;
          n4reaction( n4activate, &menu_window_ref_no ) ;


n4refresh

   Usage
          void  n4refresh( (int) window_ref )

   Description
          This routine is called by action or reaction routines when
          they change the display attribute attribute or label of a
          menu item. It instructs 'n4activate' to refresh the menu
          window after the action or reaction routine returns.

   Parameters
          'window_ref' identifies the window to be refreshed.


n4search

   Usage
          int  n4search( (char *) description_ptr )

   Descripiton
          'n4search' searches within the selected window for a
          particular menu item description.

   Parameters
          'description_ptr' points to a menu item description.
          'n4search' looks for this menu item within the selected
          window.

   Returns
          Value       Meaning

            -1        The description was not located.

          >= 0        The menu item reference number whose menu item
                  descripiton matches 'description_ptr'.

   Note
          'n4search' is called by routien 'g4menu' so that the
          initially active menu item corresponds to the original
          contents of the entry area.

          After calling 'n4search', the returned menu item reference
          number is often used as a parameter to routine
          'n4start_item'.


n4skip_over

   Usage
          int  n4skip_over( (int) menu_ref, (int) flag )

   Description
          'n4skip_over' specifies whether the menu prompt can move to
          a particular menu item. This is useful for menu items which
          are documenting text rather than a valid choice. It is also
          used so that a menu item temporarily cannot be activated.

   Parameters
          Name        Use

          menu_ref    A menu item reference number.

          flag        TRUE (non-zero) if the menu item is to be
                  skipped over  and FALSE (zero) if the menu item
                  is to be used.

   Returns
          The prviously set flag value is returned.



n4start_item

   Usage
          void  n4start_item( (int) start_item_ref )

   Description
          By default, the menu prompt starts on the first menu item.
          However, 'n4start_item' can force the menu prompt to start
          on any menu item.

          As Code Base knows which window correponds to the menu item
          reference number, it does not matter which window is
          selected.

   Parameters
          The menu prompt starts on the menu item specified by the
          menu item reference number 'start_item_ref'.



UTILITY ROUTINES

   The utility routines are low level general purpose routines.


u4error

   Usage
          int  u4error( (int) error_num, (char *) string 1,
                  (char *) string 2, ..., (char *) string n,
                  (char *) 0 )

   Description
          'u4error' is called whenever an error occurs. Normally,
          error information is sent to the default window. However,
          if the 'u4error' has been recompilied with the 'NOIO'
          switch defined, error information is sent to standard out.
          The error information consists of the error number,
          information corresponding to the error number, and all of
          the additional parameters strings.

          Refer to the Appendix on Error Messages for additional
          information on error handling.

   Parameters
          Only the 'error_num' parameter and the last '(char *) 0'
          parameter are required. There is an optional list of error
          strings. The '(char *) 0' is a signal that there are no
          additional parameters.

   Returns
          For critical errors, 'u4error' exits to the operating
          system. For less critical errors, 'u4error' waits until a
          key is pressed and the value of the pressed key is returned.


u4file_first

   Usage
          int  u4file_first( (char *) pattern, (char *) first_match )

   Description
          'u4file_first' works with routine 'u4file_next' to obtain a
          list of file names corresponding to a particluar DOS wild
          card file specification. It is available for DOS users
          only. When using wild cards, an '*' matches any sequence of
          file characters and '?' matches any single file character.
          For more information on wild card file specifications,
          refer to DOS 'dir' command.

          'u4file_first' is used to obtain the first matching file
          name. Subsequent matching names are obtained using routine
          'u4file_next'.

   Parameters
          Name            Use

          pattern         The DOS file pattern which may contain wild
                  card characters.  The Unix/Xenix version of
                  Code Base currently ignores the 'pattern'
                  parameter.

          first_match     This is a pointer to a least 14 characters
                  of data. 'u4file_first' copies the first
                  matching file name to this data space.

   Returns
          'u4file_first' and 'u4file_next' follow the return
          conventions of DOS interrupt 0x211, types 0x4E and 0x4F.

          Value       Meaning

           0          Success.
           2          Invalid File Specification.
          18          No File Match.

   Example
          for ( rc = u4file_first( "*.*",ptr); rc == 0;
                  rc = u4file_next(ptr) )
          {
               w4( w4row()+1,0,ptr) ; /* Display file name */
          }


u4file_next

   Usage
          int  u4file_next( (char *) next_match )

   Description
          'u4file_next' works with 'u4file_first' to find the next
          matching file pattern.

   Parameters
          'next_match' is a pointer to at least 14 characters of
          available data. The next matching file name is copied into
          this data space.

   Returns
          Value       Meaning

           0          Success.

          18          No More File Matches.


u4lock

   Usage
          int  u4lock( (int) dos_file, (long) offset, (long)
                  num_bytes, (int) do_wait )

   Description
          'u4lock' locks a section of any file. If 'do_wait' is TRUE
          (non-zero) 'u4lock' waits as long as necessary to lock
          information. Otherwise, 'u4lock' returns immediately.

   Parameters
          Name        Use

          dos_file    A file handle corresponding to the file to be
                  locked.

          off_set     The byte number, from the beginning of the
                  file, to start the locking at. Offset '(int) 0'
                  corresponding to the first byte of the file.

          num_bytes   The number of bytes to be locked.

          do_wait     Wait if TRUE (non-zero).

   Returns
          Value       Meaning

           0          Success or Single User Environment.
          -1          Error.
          -2          Information locked by another user.


u4name_char

   Usage
          int  u4name_char( (char) test_char )


   Description
          Returns true if the test character is a valid character for
          a file name. Otherwise, false is returned.

   Returns
          Zero represents false; any other return represents true.

   Example
          if ( ! u4name_char( name_char ) )
              printf("\n Illegal Name Chr: %c", name_char ) ;


u4name_full

   Usage
          void u4name_full( (char *) result, (char *) name,
                  (char *) extension )

   Descripiton
          'u4name_full' adds a default file name extension to a file
          name. If the name already has an extension, the original
          name is returned.

   Parameters
          Name        Use

          result      The file name, complete with a file extension,
                  is copied to 'result'. Up to 68 bytes of memory
                  may be required for '* result'.

          name        This is a null terminated string representing
                  the original file name.

          extension   A three character file name extension. It may
                  optionally be preceded by a period ('.').



u4name_part

   Usage
          void  u4name_part( (char *) result, (char *) name,
                  (int) give_dir, (int) give_ext )

   Description
          'u4name_part' takes a file name and removes the directory
          and/or extension part of it.

   Parameters
          Name        Use

          result      This parameter points the an area in memory
                  where the resulting file name should be placed.

          name        The starting file name.

          give_dir    'give_dir' it TRUE (non-zero) if the directory
                  part of the file name is to be part of the
                  resulting file name. Otherwise,
                  'give_directory' should be FALSE (zero).

          give_ext    'give_ext' is TRUE (non-zero) if the extension
                  part of the file name is to be part of the
                  resulting file name. Otherwise, 'give_ext'
                  should be FALSE (zero).


u4open

   Usage
          int  u4open( (char *) file_name, (int) code )

   Description
          'u4open' opens a file.

   Parameters
          Name        Use

          file_name   The name of the file to be opened.

          code        This code specifies how to open the file:

                  0 - Open; the file must already exist.
                  1 - Create; the file must not yet exist.
                  2 - Create; erase any existing file.

   Returns
          Value       Meaning

          >= 0        The file handle of the opened file.

            -1        Error.


u4sort

   Usage
          void  u4sort( (void *) base, (size_t) num, (size_t) width,
                  (int) (*compare) ((void *) el, (void *) e2))

   Description
          'u4sort' is a replacement for the 'qsort' routine in the
          Turbo C and Microsoft C runtime libraries. It is included
          for efficiency reasons. Parameter 'width' cannot be larger
          than the maximum index file key size. This is 100 when
          using dBASE 'NDX' files and 338 when using Clipper 'NTX'
          files.


u4unlock

   Usage
          int  u4unlock( (int) dos_file, (long) offset,
                  (long) num_bytes )

   Description
          'u4unlock' unlocks a section of any file. This section must
          have previously been locked.

   Parameters
          Name        Use

          dos_file    A file handle corresponding to the file to be
                  unlocked.

          off_set     The byte number, from the beginning of the
                  file, to start the unlocking at. Offset
                  '(int) 0' corresponds to the first byte of the
                  file.

          num_bytes   The number of bytes to be unlocked.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   Note
          Success is always returned in a single user environment.




WINDOWING ROUTINES

   Windowing routines are used to send and read information to and from the
   display screen. They also are used to send information to output handles.
   Both the menuing and get routines extensively use the windowing routines.

   Screen windows have a designated rectangular area on the screen, and an
   attribute character. Windows can have borders or titles. They can be
   popup, and can have a memory copy of their contents for restoring
   purposes. All windows have a current (row, column) position.

   the windowing routines allow convenient output of database fields adn the
   various C data types: (long), (double), (int), and (char *). There are
   also routines for cursor manipulation, text centering, and window clearing.

   Only one window can be selected at a time. Many window routines, such as
   'w4popup', specify the characteristics of the selected window. In
   addition, the output routines, such as 'w4int', use the selected window.

   Although it is possible to send output to a window after selecting it, is
   usually best to call 'w4activate' first. This will allow smooth operation
   of popups, automatic border creation, and window deactivation.

   When writing to a window, the top row and leftmost column are numbered zero.

   There are extensive examples of the windowing routines in file
   'w4example.c' on the example diskette.

Window Concepts

   Normally, the programmer displays information in the last activated window.
   However, Code Base 4 does not restrict against selecting a window and
   displaying information in it. Note that if this is donw, 'w4deactivate'
   may not restore the screen as expected.

   Code Base remembers the order in which windows were activated. It is
   possible to re-activate a window using 'w4activate' without ever
   deactivating it. When a window is re-activated, it becomes the last
   activated window. If the last activate window is a memory window (see
   'w4memory'), its contents are saved to memory when another window is
   activated or re-activated. Consequently, the window can be restored from
   memory if it is re-activated later.

   When a popup window is deactivated, the underlying text is easily
   restored. Otherwise, Code Base attempts to restore the screen by
   reactivating all of the active windows in the order in which they were
   originally activated. This only works properly if the windows being
   activated are memory windows.

Note

   1. Several windows may be active at once. A window is activated with
      routine "w4activate".

   2. There is only one "last activated" window. Normally, the programmer
      will only display information if the "last activated" window.

   3. There is only one selected window. A window is selected with routine
      "w4select".

   4. The selected window does not have to be an active window. It can be any
      window.


Windowing Example:

   #include <w4.h>

   main()
   {
       int     window_ref ;

       /* Define the Window */
       window_ref = w4define( 10,30, 14,50 ) ;

       /* Set the window's attribute and border */
       w4attribute( B_BLINK | F_WHITE ) ;
       w4border( DOUBLE, F_BLUE ) ;

       /* Activate the window */
       w4activate( window_ref ) ;

       /* Center the output on row 1 */
       w4centre( 1, "Hello World" ) ;

       /* Wait for a character to be pressed */
       g4char() ;

       /* Deactivate the window */
       w4deactivate( window_ref ) ;

       /* Free the window's allocated memory */
       w4close( window_ref ) ;

       w4exit(0) ;
   }



w4

   Usage
          void  w4( (int) row, (int) column, (char *) str )

   Description
          The null terminated character string is displayed at the
          specified (row,column) coordinates.

   Parameters
          Name        Use

          row         The output row.

          col         The output column.

          str         The output string.

   Example
          w4( 5,2, "Display at row five and column two !" ) ;


w4activate

   Usage
          void  w4activate( (int) window_ref )

   Description
          if the window is currently active and selected, nothing
          happens.

          Otherwise, 'w4activate' selects and displays the window. If
          the window has previously been activated and a memory copy
          of the window has been saved (see 'w4memory'), then this
          memory copy is restored. In addition, if the window is a
          popup window, underlying screen information is saved.

          If the window was not previously active or if it is not a
          memory window, it is cleared.

   Parameters
          'window_ref' is the window reference number of the window
          to activate.

   Example
          w4activate( w4define( 5,10, 20,70 ) ) ;


w4attribute

   Usage
          long  w4attribute( (long) attribute )

   Description
          Every time output is sent directly to an output window on
          an IBM PC or compatible, if has a corresponding attribute
          character. This routine sets which attribute character is
          used for the selected window.

          Attribute characters have the following format:

          Bit Number  Meaning

          0           Foreground blue.
          1           Foreground green.
          2           Foreground red.
          3           Foreground intensity.
          4           Background blue.
          5           Background green.
          6           Background red.
          7           Background blinking.

          Header file 'w4.h' defines attributes for the standard
          colors: F_BLUE, F_GREEN, F_RED, F_INTENSE, F_WHITE, B_BLUE,
          B_GREEN, B_RED, B_BLINK, AND B_WHITE.

   Example
          /* Set to intense white */
          w4attribute( F_WHITE | F_INTENSE ) ;

   Warning
          This routine is specific to IBM PC'S and compatibles.



w4border

   Usage
          void  w4border( (char *) box_chars, (long) attribute )

   Description
          The window border, of the currently selected window, is set
          to the specified box charcters. This border is displayed
          just within the window bounds. Row zero of the window
          becomes the row just below the top border row and column
          zero becomes the column just to the right of the left
          border column.

   Parameters
          Name        Use

          box_chars   A string of eight characters which make up the
                  characters in the box. They are in the
                  following order:

                  Top.
                  Bottom.
                  Left Side.
                  Right Side.
                  Upper Left Corner.
                  Upper Right Corner.
                  Lower Left Corner.
                  Lower Right Corner.

                  Code Base saves a pointer to the 'box_chars'
                  string. Consequently, 'box_chars' should be a
                  static memory variable, a constant, or declared
                  in the 'main' program.

          attribute   This is the attribute character for the border.

   Note
          Header file 'w4.h' defines some strings for common borders:
          SINGLE, DOUBLE, DOUBLE_TOP, and PANEL. It also defines some
          common attributes.

   Example
          w_ref = w4define( 0,0, 24,79 ) ;
          w4border(  SINGLE, F_WHITE ) ;
          w4activate( w_ref ) ;



w4box

   Usage
          void w4box( (char *) box_chars, (int) start_row,
                  (int) start_col, (int) end_row, (int) end_col )

   Description
          'w4box' draws a box in the selected window. The window
          attribute character is used.

   Parameters
          Refer to 'w4border' for the definition of parameter
          'box_chars'. Parameters 'start_row', 'start_col',
          'end_row', and 'end_col' outline the dimensions of the box.

   Example
          /* Outline the complete screen with a box */
          w_ref = w4define( 0,0, 24,79 ) ;
          w4box( SINGLE, 0,0, 24,79 ) ;
          w4close( w_ref ) ;


w4centre

   Usage
          void  v4centre( (int) row, (char *) str )

   Description
          A string is centered on the specified row within the
          selected window.

   Parameters
          Name        Use

          row         The output row.

          str         The output string.


w4clear

   Usage
          void  w4clear( (int) row )

   Description
          The selected window is cleared starting from the specified
          row. In addition, the current (row,column) position is
          changed to (row,0).

          If 'row' is '(int) -1', the entire screen is cleared and
          the current (row,column) position is not changed.


w4close

   Usage
          void  w4close( (int) window_ref )

   Description
          'w4close' frees all of the memory assoicated with the
          window. Once a window is closed, it no longer exists.
          Closing a window, does not effect the screen. If necessary,
          deactivate the window before closing it.

          If the window being closed was previously selected, the
          last activated window is automatically selected. If there
          was no last activated window, the selected window is
          undefined and must be determined with another windowing
          routine such as 'w4select'.

   Parameter
          The window reference number of the window to be closed.


w4col

   Usage
          int  w4col()

   Returns
          The current column is returned.


w4cursor

   Usage
          void  w4cursor( (int) row, (int) column )

   Description
          The cursor is positioned at the specified coordinates
          within the selected window. If either parameter value is
          negative, the cursor will disappear off the screen.

          Calling 'w4cursor' does not effect the current (row,column)
          position within the selected window.

   Warning
          Some computers 'hang' if the cursor is not positioned on
          the screen before programs exit. Refer to routine 'w4exit'
          and the example.

   Example
          /* Following is the source code for 'w4exit' */
          w4exit( rc )
          int   rc ;
          {
              w4select( vdefault_window ) ;
              w4cursor( 23, 0 ) ;
              exit( rc ) ;
          }


w4cursor_size

   Usage
          void  w4cursor_size( (int) start_size, (int) end_size )

   Description
          The cursor size is set.

   Parameters
          Name        Use

          start_size  The top position of the displayable cursor.
                  This value ranges between 0 and the 'end_size'.

          end_size    The bottom position of the displayable cursor.
                  This value ranges between 0 and 7.

   Warning
          This routine is specific to IBM PC's and compatibles.



w4deactivate

   Usage
          w4deactivate( (int) window_ref )

   Description
          If the window is an active, selected, popup window, the the
          window disappears from the screen and the underlying text
          is restored.

          Otherwise, the screen is restored by reactivating other
          windows. This makes use of the fact that, through a call
          to 'w4memory', windows can have a copy of their contents
          saved. Any previously activated window, whose contents had
          been saved, will be reactivated. These windows will be
          reactivated in the order in which they were originally
          activated. It may be impossible to reconstruct the screen
          if there are overwritten windows for which there is not a
          memory copy.

          After a window is deactivated, the last activated window is
          automatically selected.

   Parameter
          The window reference number of the window to be closed.

   Example
          /* Defined a bordered, popup window for the screen's left
             side. */

          w_ref = w4define( 0.,13, 24,79 ) ;
          w4border( DOUBLE, F_WHITE ) ;
          w4popup() ;
          w4activate( w_ref ) ;
          .
          .
          w4deactivate( w_ref ) ;
          w4close( w_ref ) ;



w4define

   Usage
          int  w4define( (int) top_row, (int) left_column,
                  (int) bottom_row, (int) right_column )

   Description
          'w4define' creates a window. It is necessary to do this
          before almost any other routines in the 'Window', 'Get' or
          'Menu' modules can be called.

          After the window is created, it is selected.

   Parameters
          The parameters describe the dimensions of the window. The
          row and column coordinates are relative to the top and left
          side of the screen. Row zero is the top screen row and
          column zero is leftmost column.

   Returns
          A reference number corresponding to the new window is
          returned.

   Note
          'd4init' calss 'w4define' to create a default window with a
          reference number in external integer variable
          'v4default_window'. This window covers the entire screen.
          If 'd4init' has not been called, 'w4define' will create the
          default window.

   Example
          #include <w4.h>

          main()
          {
              int     error_window, main_window, top_window,
                  bottom_window ;
              error_window = w4define( 11,25, 16,55 ) ;
              w4popup() ;
              w4border( DOUBLE, F_RED ) ;
              w4attribute( F_RED | B_BLINK ) ;

              main_window = w4define( 0,0, 24,79 ) ;
              w4memory() ;

              top_window = w4define( 0,0, 12,79 ) ;
              w4memory() ;
              w4border( SINGLE, F_WHITE ) ;

              bottom_window = w4define( 13,0, 24,79 ) ;
              w4memory() ;
              w4border( SINGLE, F_WHITE ) ;

              application() ;
              w4exit(0) ;
          }



w4display

   Usage
          int  w4display( (char *) title, (char *) m1,
                  (char *) m2, ..., (char *) 0 )

   Descripiton
          'w4display' creates a popup window and displays message
          strings in it. The window is created just large enough to
          contain the message strings in an attractive manner. Once
          the message strings have been displayed, 'w4display' waits
          for the user to press a key. Then the popup window is
          deactivated and closed.

   Parameters
          Name        Use

          title       The window's title. If this is the only
                  parameter, the title is displayed in the middle
                  of the window.

          m1,m2,...   An unspecified number of message strings to
                  display.

          (char *) 0  A required parameter.

   Return
          The character pressed.

   Example
          rc = w4display( " Entry Error: ",
                  "Only Blanks were Entered",
                  "",
                  "Continue (Y/N) ?",
                  (char *) 0 ) ;
          if ( rc == (int) 'n' || rc == (int) 'N' )
              w4exit(1) ;


w4double

   Usage
          void  w4double( (int) row, (int) column,
                  (double) double_value, (int) len, (int) dec )

   Description
          A double value is displayed.

   Parameters
          Name            Use

          row             The output row.

          column          The output column.

          double_value    The double to display.

          len             The output length.

          dec             The number of decimals to display.



w4eject

   Usage
          void  w4eject()

   Description
          a form feed character is sent to the current window's
          output handle. In addition, the current (row,column)
          position is set to (0,0).


w4exit

   Usage
          void  w4exit( exit_rc )

   Description
          'w4exit' positions the cursor to row 23 and column 0 of the
          screen and then exits by calling the standard exit routine
          'exit' with a return code of 'exit_rc'.

          'w4exit' is necessary because some computers fo not respond
          normally if a program exits with the cursor off of the
          screen.

   Warning
          Do not use 'w4exit' if the dimensions of the default window
          have been changed or if the default window is closed.


w4field

   Usage
          void  w4field( (int) row, (int) column, (long) field_ref )

   Description
          'w4field' displays the value of a database field.

   Parameters
          Name        Use

          row         The output row.

          column      The output column.

          field_ref   The field reference number of the field to
                  display.


w4handle

   Usage
          int  w4handle( (int) hand )

   Description
          'w4handle' specifies the handle to be associated with the
          selected window. Subsequent output form the windowing
          routines will be written to this handle. If the handle is
          associated with a file, make sure the file has been opened
          in binary mode.

          Menuing and data entry should not be attempted on a window
          associated with an output handle which is not '(int) -1'.

   Parameter
          'hand' can have the following possible values:

          Value       Meaning

             -2       Do not change the handle. Just return the value
                  of the current handle.

             -1       Send output directly to the video memory.

              0       Standard input handle.

              1       Standard output handle.

              2       Standard error handle.

              3       Standard auxiliary handle.

              4       Standard printer.

           >= 5       These handles will normally correspond to
                  opened files.

   Return
          Returns the value of the previous output handle.


w4height

   Usage
          int  w4height( (int) new_height )

   Description
          'w4height'sets and returns the number of rows in the
          selected window.

          Calling 'w4height' does not effect what has been displayed
          on the screen. However, any popup or saved screen memory is
          freed and reallocated. Consequently, it may be best to
          avoid changing a window's height when the selected window
          is active.

          The new height only counts the rows within the window
          borders.

   Parameter
          If 'new_height' is greater than zero, it becomes the new
          number of rows in the window.

   Returns
          The current height is returned.


w4init

   Usage
          int  w4init( (int) num_window, (int) num_get, (int) num_menu)

   Description
          if 'w4init' is not called directly, it is called
          automactically by 'd4init', 'w4define', and 'w4clear(-1)'.
          Consequently, if 'w4init' is called explicitly, it should
          be called before any other Code Base routine is called.

          By calling 'w4init' to exactly specify the number of
          windows, get entry areas and menu item numbers, overall
          memory usage and fragmentation is reduced. Even if 'w4init'
          is called, Code Base will still allocate extra memory for
          additional windows, entry areas, or menu items as required.

          The number of windows in use at any one time is the number
          of times 'w4define' is called minus the number of times
          'w4close' is called plus one for the default window.

          The number of entry areas in use at any one time is
          determined by the number of Get Initialize routines which
          have been called. Memory for an entry area is normally
          released automatically by 'g4read'.

          similarily, the number of menu items in use depends on the
          number of calls to 'n4' and 'n4item'. Menu item memory is
          normally released when a window is closed.

          By default, 'd4init' calls 'w4init' as follows:

              w4init( 5, 0, 0 ) ;

          By default, 'w4define' and 'w4clear' call 'w4init' as
          follows:

               w4init( 10, 0, 0 ) ;

   Returns
          Value       Meaning

           0          Success.

          -1          Out of memory. Unless 'u4error' is modified,
                  this is a critical error and will never be
                  returned.


w4int

   Usage          void  w4int( (int) row, (int) column, (int) int_value,
                  (int) len )

   Descripiton
          An integer is displayed.

   Parameters
          Name        Use

          row         The output row.

          column      The output column.

          int_value   The integer to be displayed.

          len         The output length.

   Example
          w4( w4row() + 1, 2, "Amount:") ;
          w4init( w4row(), w4col(), i_amount, 6 ) ;


w4long

   Usage
          void  w4long( (int) row, (int) column, (long) long_value,
                  (int) len )

   Description
          A long integer is displayed.

   Parameters
          Name        Use

          row         The output row.

          column      The output column.

          long_value  The long to be displayed.

          len         The output length.

   Example
          w4long( ++r,c,l_value, 8 ) ;


w4memory

   Usage
          void  w4memory()

   Description
          'w4memory' causes a copy of the currently selected window
          to be kept in memory. Consequently, when the window is
          re-activated, its image can be restored from memory. In
          addition, if the selected window is overlaid with another
          window which is subsequently deactivated, the selected
          window's contents can be redisplayed.

   Hint
          When different windows of different sizes are randomly
          activated, it is often best to use 'w4memory' so that the
          previous contents of the windows can be restored.

   See Also
          w4deactivate.


w4num

   Usage
          void  w4num( (int) row, (int) column, (char *) str,
                  (int) num )

   Description
          A string of a specified length is displayed.

   Parameters
          Name        Use

          row         The output row.

          column      The output column.

          str         The output string.

          num         The number of characters to output.

   Example
          /* Output five characteres */
          w4num( r,c, str, 5 ) ;


w4num_att

   Usage
          void  w4num_att( (int) row, (int) col, (char *) str,
                  (int) num, (long) attribute )

   Description
          'w4numm_att' is identical to 'w4num' except that it has one
          additional parameter. This parameter, 'attribute',
          specifies the attribute of the display string.

   See Also
          w4attribute.


w4out

   Usage          void  w4out( (char *) str )

   Description
          The string 'str' is displayed at the current (row,column)
          position.


w4popup

   Usage
          void  w4popup()

   Description
          The selected window becomes a popup window. This means that
          when a window is activated and then deactivated the text
          under the window can be restored quickly.

   Note
          Calls to 'n4lotus', 'n4pulldown', 'n4get_calc' and 'n4calc'
          automatically make the relevant windows popup windows.


w4position

   Usage
          void  w4position( (int) row, (int) column )

   Descripiton
          The current (row,column) position is set. If the selected
          window has an output handle, an appropriate number of
          carriage return, line feed, form feed and space characters
          will be sent to position the corresponding file or device
          to the new current position.

          Regardless, 'w4position' does not effect the cursor position.

   Parameters
          Name        Use

          row         The new row position.

          column      The new column position.



w4read

   Usage
          void  w4read( (int) row, (int) col, (char *) data_buffer,
                  (int) len_data )

   Description
          Routine 'w4read' reads information from video memory. The
          information is in video memory format: (character,
          attribute).

   Parameters
          Name            Use

          row             The screen row relative to the top of the
                  screen.

          col             The screen column relative to the top of the
                  screen.

          data_buffer     A pointer to a buffer where the data is to
                  be placed.

          len_data        The number of bytes to read. This is twice
                  the number of screen characters read as the
                  attributes are read as well.

   Portability
          This routine is not available under the Unix/Xenix verison
          of Code Base.

   Example
          static char    scr_data[25*80*2] ;

          char *   read_screen()
          {
             /* Read the entire screen */
             w4read( 0,0, scr_data, sizeof(scr_data) ) ;
             return( scr_data ) ;
          }


w4read_window

   Usage
          void  w4read_window( (int) window_ref, (char *) ptr )

   Description
          Character information, for the entire window, is read from
          video memory. This information is read as (character,
          attribute) pairs. If the window contains a border, the
          border information is not read.

   Parameters
          Name        Use

          window_ref  The reference number of the window to be read.

          ptr         A pointer to where the information is to be
                  stored. Make sure there is enough memory to
                  contain the window.

   Portability
          This routine is not available under the Unix/Xenix verison
          of Code Base.

   Example
          static  char  window_info[200] ;

          read_example_one()
          {
              int     w_ref ;

              w_ref = w4define( 2,2, 11,11 ) ;

              /* Read the 200 bytes of window information */
              /* Note: ( 11-2+1) * (11-2+1) is 100
             characters. This becomes 200 bytes at 2 bytes per
             character */

              w4read_window( w_ref, window_info ) ;

              w4close( w_ref ) ;
          }

          read_example_two()
          {
              int     w_ref ;

              w_ref = w4define( 1,1, 12,12 ) ;
              w4border( SINGLE, F_WHITE ) ;

              /* Read the same 200 bytes of window information as in
             'save_example_one'. The border information is not
             read. */

              w4read_window( w_ref, window_info ) ;

              w4close( w_ref ) ;
          }


w4repeat

   Usage
          void  w4repeat( (int) row, (int) column, (char) chr,
                  (int) num_repeat )

   Desciption
          A character is displayed repeatedly.

   Parameters
          Name        Use

          row         The output row.

          column      The output column.

          chr         The display character.

          num_repeat  The number of times to display 'chr'.


w4row

   Usage
          int  w4row()

   Descripiton
          The current row position is returned.


w4scroll

   Usage
          void  w4scroll( (int) num_lines )

   Description
          The window is scrolled up or down.

   Parameters
          Parameter 'no_lines' specifies the number of lines the
          window is to be scrolled. If 'no_lines' is positive, the
          window is scrolled up. Otherwise, the window is scrolled
          down.

   Portability
          Under Unix/Xenix this routine does not work on windows with
          borders.


w4select

   Usage          int  w4select( (int) window_ref )

   Description
          The specified window becomes the currently selected window.
          If 'window_ref' is less than zero, the currently selected
          window does not change.

   Returns
          'w4select' returns the previously selected window reference
          number.

   Example
          previous_ref = w4select( new_ref ) ;
          w4centre( 1, "Output Window" ) ;
          w4select( previous_ref ) ;

   Example 2
          /* Find the current window reference number */
          current_ref = w4select( -1 ) ;


w4title

   Usage
          void  w4title( (int) row, (int) col, (char *) title,
                  (int) title_attribute )

   Description
          'w4title' specifes a string of character data which is
          automatically displayed when the currently selected window
          is activated. Unlike other window display routines,
          'w4title' ignores the presence of a border for the purposes
          of calculating the (row,col) placement. This makes it
          possible to overlay the window border with title information.

   Parameters
          Name        Use

          row         The title's row.

          col         The window's column. If 'col' is less than
                  zero, the title is centered.

          title       A pointer to the 'title' string.

          attribute   The display attribute of the 'title' string.

   Warning
          Code Base only saves a pointer to the title string.
          Consequently, the 'title' pointer should not point to
          temporay memory. If the information 'title' points to
          changes, the window's title changes.

   Example
          w_ref = w4define( 5,10, 10,20 ) ;
          w4border( DOUBLE, F_WHITE ) ;

          /* Define a title to be centered over the top border row */
          w4title( 0,-1, " Data Entry Window ", B_WHITE ) ;


w4width

   Usage
          int  w4width( (int) new_width )

   Description
          'w4width' sets and returns the number of columns per row
          for the selected window.

          Calling 'w4width' does not effect what has been displayed
          on the screen. However, any popup or saved screen memory is
          freed and reallocated. Consequently, it may be best to
          avoid changing a window's width when the window is active.

          The new width only counts the columns within the window
          borders.

   Parameter
          If 'new_width' is greater than zero, it becomes the new
          number of columns per row.

   Returns
          The current width is returned.

   Example
          void  shrink_window( w_ref )
          {
              int  prev_ref ;

               prev_ref = w4select( w_ref ) ;

               w4width( w4width(-1) -1 ) ;
               w4height( w4height(-1) -1 ) ;

               w4select( prev_ref ) ;
          }


w4write

   Usage
          void  w4write( (int) row, (int) col, (char *) data_ptr,
                  (int) len_data )

   Description
          Routine 'w4write' writes information from a memory buffers
          directly into video memory. The memory buffer information
          must be in video memory format: (character,attribute).

   Parameters
          Name        Use

          row         The screen row relative to the top of the screen.

          col         The screen column relative to the top of the
                  screen.

          data_ptr    A pointer to the data buffer to be written.

          len_data    The number of bytes to write. As the write data
                  contains attributes, there are twice as many
                  bytes as screen characters.

   Note
          This routine is the opposite to 'w4read'. These routines
          are low level and consequently are used by other Code Base
          windowing routines. 'w4write' is not available under the
          Unix/Xenix version of Code Base.

   Example
          /* Code fragment from 'w4write_window' */
          int         i, data_width ;
          WINDOW      *window_ptr ;

          window_ptr = v4window+ window_ref ;
          data_width = window_ptr->width * 2 ;

          for ( i=0; i < window_ptr->height; i++ )
          {
               w4write( window_ptr->start_row+i,
                window_ptr->start_col, ptr, data_width ) ;
              ptr += data_width ;
          }

w4write_att

   Usage
          void  w4write_att( (int) row, (int) col, (char *) data_ptr,
                  (int) len_data, (long) attribute )

   Description
          'w4write_att' is the samne as 'w4write' except the
          data_buffer contains only character data. All of the data
          is displayed with the specified attribute character.

   Parameters
          Name        Use

          row         The screen row relative to the top of the screen.

          col         The screen column relative to the top of the
                  screen.

          data_ptr    A pointer to the display data.

          len_data    The number of data characters to write. This is
                  the same as the number of bytes of data.

          attribute   This is the attribute of all of the characters
                  which are displayed.

   Portability
          This routine is not available under the Unix/Xenix version
          of Code Base.


w4write_window

   Usage
          void  w4write_window( window_ref, ptr )

   Description
          'w4write_window' is used to display information read with
          'w4read_window'. It assumes that the window has not changed
          size. In addition, it assumes that the window has not
          aquired or lost a border.

   Parameters
          Name        Use

          window_ref  The reference number of the window to display.

          ptr         A pointer to where the display information is
                  stored. There should be enough (character,
                  attribute) pairs to fill the entire window.

   Portability
          This routine is not available under the Unix/Xenix version
          of Code Base.

   Example
          #include <w4.h>

          void  copy_window()
          {
               int   w_ref ;

               char  window_data[400] ;

               w_ref = w4define( 0,0, 9,19 ) ;
               w4read_window( w_ref, window_data ) ;
               w4close( w_ref ) ;

               /* Display the information at row 15 */
               w_ref = w4define ( 15,0, 24,19 ) ;
               w4write_window( w_ref, window_data ) ;
               w4close( w_ref ) ;
          }




EXTEND ROUTINES

   The extended routines implement high level database functionality. As they
   use lower level Code Base routines, they can by use as Code Base examples.
   In particular, routines 'x4sum', x4replace', 'x4list' and 'x4edit' are
   good examples. Other extended routines can be used as examples for more
   advanced users.

   Routines 'x4seek', 'x4skip', 'x4top', 'x4go' and 'x4bottom' use filtering
   and relations set by routines 'x4relate' and 'x4filter'.


x4blank

   Usage
          int  x4blank()

   Description
          'x4blank' determines if the current record of the current
          database is blank. This routine is included primarily as an
          example of how to write a routine which works with
          'x4fileter'.

   Returns
          Value       Meaning

          1           The record is blank.

          0           The record is not blank.

   See Also
          'x4filter'.


x4bottom

   Usage
          int  x4bottom()

   Description
          This is the same as 'd4bottom' except filtering and
          relations are used.


x4buffer

   Usage
          int  x4buffer( (long) start_record, (char *) buffer,
          (unsigned int) len_buffer )

   Description
          'x4buffer' sequentially reads as many database records as
          possible into the memory buffer. Once the records have been
          read using 'x4buffer', 'x4buffer_copy' can be called to
          copy individual records into the database's internal record
          buffer. At this point, the record can be accessed and
          modified using the field routines.

   Parameters
          Name            Use

          start_record    This is the starting record number to be
                  read.

          buffer          A memory buffer where the records are to be
                  placed.  This memory is allocated by the
                  programmer.

          len_buffer      The number of bytes of memory allocated
                  for 'buffer'.

   Returns
          'x4buffer' returns number of records which have been read
          into the memory buffer. This will never be more than the
          buffer length divided by the record width.

          If an error occurs, '(int) -1' is returned.


x4buffer_copy

   Usage
          void  x4buffer_copy( (int) i, (char *) buffer )

   Description
          'x4buffer_copy' copies a database record form a large
          memory buffer into the internal database record buffer.
          Then the record can be accessed and modified using the
          field routines.

   Parameters
          Name        Use

          i           A record number offset specifying which
                  database record should be transfered. For
                  example, if 'i' is zero, the first record in
                  the memory buffer is transfered; and if 'i' is
                  one, the second record is transfered.

          buffer      This is the memory buffer containing the
                  database records.

   See Also
          'x4buffer'.


x4edit

   Usage
          int  x4edit()

   Description
          The current database is edited, interactively, one record
          at a time. Initially, the record in the database buffer
          will be displayed for modification.

          If there is a currently selected index file, it will be
          used to determine the record ordering.

          When using 'x4edit', the following keys perform the
          following actions:

          Key         Action

          <Alt A>     Add Record.

          <Alt B>     Move to the bottom record.

          <Alt D>     Mark the record for deletion.

          <Alt I>     Insert a blank record at current record.

          <Alt R>     Move to a specified record.

          <Alt S>     Seek a record.

          <Alt T>     Move to the top record.

          <Alt U>     Undo the record deletion mark.

          <PgUp>      Move to the previous record.

          <PgDn>      Move to the next record.

          <Ctrl W>    Write the displayed record and then exit.

          <Esc>       Exit without writing the displayed record.

          <F1>        Help.

   Note
          The avoe key assignments do not follow any particular
          convetion or standard.

   Returns
          The exit key is returned. The possibilites are currently
          <Esc> and <Ctrl W>. On error, '(int) -1' is returned.

   See Also
          'g4read'.


x4filter

   Usage
          int  x4filter( (*filter_routine) () )

   Description
          Routine 'x4filter' works with routines 'x4seek', 'x4skip',
          'x4top', and 'x4bottom' to make it appear that certain
          records do not exist.

          For example, 'x4top' calls 'd4top' and then linearly skips
          through the database, using 'd4skip', until a record is
          located which should not be filtered.

          When 'x4filter' is called, the specified filter routine is
          added to a list of filter routines attached to the current
          database. Each filter routine should return a logical 'int'
          according to the following conventions:

          Filter Return   Meaning

           1              Filter the record.

           0              Use the record.

          -1              Error.

          For a record to be used, all of the filter routines
          attached to the database must return a '(int) 0' value.

   Parameters
          The parameter is a filter routine.

   Returns
          '(int) -1' is returned to indicate out of memory. Unless
          'u4error' has been modified, this is a critical error and
          will never return to 'x4filter'.

   Warning
          Do not get the return convention of Code Base filtering
          routines backwards. Do not leave in the brackets as in
          "x4filter( d4deleted() )".

   Example
          /* Filter all deleted and blank records */
          x4filter( d4deleted ) ;
          x4filter( x4blank ) ;
              .
          /* Remove the 'x4blank' filtering */
          x4filter_pop() ;
              .
          /* Remove all of the filtering */
          x4filter_reset() ;


x4filter_pop

   Usage
          int  x4filter_pop()

   Desciption
          The last filter routine specified is popped from the list
          of filter routines attached to the current database. It is
          possible to remove several routines from the list by
          calling 'x4filter_pop' repeatedly.

   Returns
          Value       Meaning

           0          Success.

          -1          No filters are attached to the current database.


x4filter_reset

   Usage
          void  x4filter_reset()

   Description
          All of the filter routines attached to the current database
          are removed from the list.

   See Also
          x4filter.


x4filter_do

   Usage
          int  x4filter_do()

   Description
          All of the filtering routines for the current database are
          evaluated to determine whether the current database record
          should be filtered.

          The filtering routine uses the record currently in the
          database buffer.

   Returns
          Value       Meaning

           0          Use the record.

           1          Filter the record.

          -1          Error.


x4go

   Usage
          int  x4go( (long) rec_num )

   Description
          This routine is the same as 'd4go' except relations are used.


x4insert

   Usage
          int  x4insert( (long) rec_num )

   Description
          The record in the record buffer becomes record 'rec_num'.
          All of the previous records from 'rec_num' to the end of
          the database are copied forward one record to insert the
          new record.

          For example, 'x4insert(2L)' would create a new Record 2. If
          the database previously had 3 records, the old Record 2
          becomes Record 3 and the old Record 3 becomes Record 4.

          After the record is inserted, all of the index files for
          the database are reindexed to maintain their correctness.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.

   Warning
          This routine can take a long time to execute for large
          databases.


x4list

   Usage
          int  x4list()

   Descripiton
          The contents of the database are written to the current
          output device. Filtering specified by 'x4filter' is used.

   Returns
          Value       Meaning

           0          Success.

          -1          Error.


    Usage
          int x4relate( (char *) expr, (int) base_ref, (int)
                  index_ref, (long) miss_code )

    Description
          Routine 'x4relate' creates a relation between a controlling
          database and a related database. The selected database
          becomes the controlling database and the specified database
          becomes the related database. Afterwards, when a
          controlling database is repositoned with an extend routine,
          such as 'x4seek' or 'x4top', all of the related database is
          repositioned with an extended routine, such as 'x4seek' or
          'x4top', all of the related databases are repositioned
          automatically.

          When a relation is processed the expression 'expr' is
          evaluated. If an index file was specified for the related
          database, the expression is looked up in the index file to
          move to a record in the related database. However,if no
          index file was specified, the 'expr' should return a
          numeric value  whick is interpreted as a record number.
          This record number specifies a new record in the related
          database.

    Parameter
          Name        Use

          expr        An expression which specifies either a key to
                  be locked up in the index file or  a record
                  number.

          base_ref    The database reference number corresponding to
                  an index file of the related database.

          index_ref   An index file reference number corresponding to
                  an index file of the related database.
                  If 'expr' is to specify a record number, this
                  parameter should be '(int) -1'.

          miss_code   This code determines the action if a record is
                  not located:

                  Code Value   Meaning

                 0         Use a Blank Record.

                -1         Generate an Error Message.

                  >= 1         A default record number.



x4relate_do

    Usage
          int  x4relate_do()

    Description
          All of the relations for the current database are processed.

    Returns
          Value       Meaning

           0          Success.

          -1          Error.

    See Also
          'x4relate'.


x4relate_reset

    Usage
          void  x4relate_reset()

    Description
          All of the relations for the currently selected database
          are removed.

    Returns
          Value       Meaning

           0          Success.
          -1          Error.



x4replace

    Usage
          int  x4replace( (long) field_ref, (long) rec_num,
                  (void *) value )

    Description
          The record is read, the fields value is changed, and then
          the record is written.

    Parameters
          Name        Use

          field_ref   The field reference number.

          rec_num     The record number.

          value       The new value of the field. Refer to
                  'f4replace' for the format of this value.

    Returns
          Value       Meaning

           0          Success.

          -1          Error.


x4seek

    Usage
          int  x4seek( (char *) search_string )

    Description
          This routine is the same as 'd4seek' except filtering and
          relations are used.

x4skip

    Usage
          int  x4skip( (long) num_records )

    Description
          This routine is the same as 'd4skip' except filtering and
          relations are used.


x4sum

    Usage
          double  x4sum( (long) field_ref )

    Description
          The field specified by the field reference number is
          summed. Filtering is used to determine which records are
          used in the summation.

    Returns
          The summation is returned as a double. If an error
          occurs, '(double) 0.0' is returned.


x4top

    Usage
          int  x4top()

    Description
          This routine is the same as 'd4top' execpt filtering and
          relations are used.



MULTI-USER CONSIDERATIONS

    When using Code Base in a single user environment, you may safely ignore
    all the multi-user aspects of Code Base. However, if you plant to use
    Code Base with OS/2 or on a network where there are multiple sessions, it

    is necessary to learn about the multi-user features of Code Base.

    Code Base is also compatible with Clipper locking and unlocking protocol.
    Consequently, if a Clipper application and Code Base application are
    executed at the same time on a network, they understand each others file
    and record locking !!



LOCKING AND UNLOCKING

    In a multi-user enviroment, it is necessary to avoid having users reading
    and writing to and from the same disk record at the same time.
    Consequently, disk information is dedicated to one session before it is
    written or read.

    Dedicating disk information to one session is called "locking" it and
    freeing disk information for general use is called "unlocking" it.

    Code Base routines keep track of what files or portions of files have
    been locked and unlocked. Disk information will automatically be locked
    by Code Base before it is written or read.

    This means that the Code Base user only needs to unlock files at
    appropriate times. Doing so allows other users to access the previoulsy
    locked areas.

    Unlocking a database does not necessarily unlock all of the database's
    index files. It may be necessary to explicitly unlock them with routine
    'i4unlock'.

    Note that Code Base will only lock a single database record or the whole
    database. If it is necessary to lock serval records at once, use routine
    'd4lock' to lock the entire database.

    Hint:

      In a multi-user database enviroment, it is safest to assume any
      disk resident information could immediately be different once it
      has been unlocked.



RECORD COUNT BYTES

    The record count bytes specify how many records are currently in the
    database. These bytes can be locked and unlocked just like a database
    record. However, as Code Base locks and unlocks the record count bytes,
    it is generally not necessary to lock and unlock them in application
    programs.

    Code Base calculates the number of records in the database from the
    length of file. Consequently, the record count bytes are used by Code
    Base only when they are updated after the number of database records has
    been changed.



DEAD LOCK

    Dead lock is a situation to be avoided. It occurs when two sessions wait
    for each other indefinitely.

    A dead lock example is Session One waiting for file 'A' which is locked
    by Session Two and Session Two waiting for file 'B' which is locked by
    Session One. Since each session is waiting for each other, nothing will
    ever happen.

    A simple way to avoid deadlock is to have all sessions execute locks in
    the same order. In the previous deadlock example, file 'A' could always
    be locked before file 'B'. Then Session Two would unlock file 'B' before
    attempting to lock file 'A'. Session One could then lock file 'B',
    complete what it needs to do and then unlock the files for Session Two.

    Hint:

     It is important either explicity unlock index files or to unlock
     with 'd4unlock(-1)'.

    Note:

      Code Base 4 always locks index files before locking database
      records or files. Consequently, in order to avoid deadlock, you
      should make sure the database is not locked when an index file is
      locked.



APPENDIX A - BLOCK ROUTINES

    The block routines are low level routines called by the index file
    routines. Index file information is organized into a hierarchy of blocks.
    Block routines read, write, and manipulate those blocks.

b4add

    Usage
          int  b4add( (int) index_ref, (KEY *) key_ptr )

    Description
          Adds a key to the current block. 'b4add' is designed to
          work with 'i4add' to add a key to an index file.

    Returns
          Value       Meaning

           0          Success.

          -1          Error.


b4down

    Usage
          long  b4down( (int) index_ref, (int) direction )

    Description
          Reads one level deeper down the hierarchy of blocks.

    Parameters
          Name        Use

          index_ref   The index file reference number.

          direction   Specifies which direction to traverse down the
                  tree. If 'direction' is less than zero, the
                  tree is traversed left, and if 'direction' is
                  greater than zero, the tree is traversed right.

    Returns
          Value       Meaning

          >= 0        Block reference number of the new block.

            -1        At the bottom level. Cannot read futher down.

            -2        Read Error.

            -3        Out of Memory.


b4key

    Usage
          KEY *  b4key( (int) index_ref )

    Description
          Returns a pointer to the current key of the current block
          of the specified index file. Refer to 'd4base.h' for a
          definition of the 'KEY' structure.

    Returns
          If '(KEY *) 0' is returned, there is no current key.


b4remove

    Usage
          int  b4remove( (int) index_ref )

    Description
          The current key is removed from the current block. No
          writing is done to disk.

    Returns
          Value       Meaning

          >= 0        Number of Keys left in Block.

             0        Success.

            -1        Error.



b4search

    Usage
          int  b4search( (int)  index_ref, (char *) srch_ptr )


    Description
          The current block of the specified index file is searched
          for the value pointed to by 'srch_ptr'.

    Returns
          Value       Meaning

          0           Complete Match.

          1           Inexact Match.

          2           After the specified key.

          3           After the Block.



b4skip

    Usage
          int  b4skip( (int) index_ref, (long) num_skip )

    Description
          A specified number of keys are skipped. Skipping is
          relative to the current key of the current block.

    Parameters
          Name        Use

          index_ref   The index file reference number.

          num_skip    The number of keys to skip. This can be a
                  negative number.

    Returns
          The number of keys actually skipped. When an error occurs,
          'num_skip' with an opposite sign is returned.


b4up

    Usage
          int  b4up( (int) index_ref )

    Description
          Frees the current block and moves one block up the
          hierarchy of blocks. This is the opposite to routine
          'b4down'.

    Returns
          Value       Meaning

          >= 0        The block reference number of the new block.

            -1        The current block is the root block. Nothing
                  was done.

            -2        No block is present.


b4write

    Usage
          int  b4write( (int) index_ref )

    Description
          The current block of the specified index file is written to
          disk.

    Returns
          Value       Meaning

           0          Success.

          -1          Error.


APPENDIX B - COMPATIBILITY ISSUES

    Code Base can use the data, index and memo files of dBASE III, dBASE III
    PLUS, dBASE IV or Clipper. For Clipper compatible index files, refer to
    the appendix on Library Building. To use dBASE III, dBASE III PLUS or
    Clipper compatible memo files, refer to the chapeter on memo files.

    Consequently, Code Base can be used with any dBASE package which conforms
    to the dBASE file standard. Some popular programs that will work with
    Code Base are as follows:

          1. "dBEditor(TM)" from Sequiter Software Inc.

          2.  "R&R Relational Report Writer from Concentric Data
               Systems Inc.

          3.  "FoxBASE" (data files) from Fox Software.

          4.  "dBXL(TM)" from Wordtech Systems.

          5.  "dSALVATE" from Comtech Publishing Ltd.


OS/2, MICROSOFT WINDOWS

    Code Base contains a OS/2 and Microsoft Windows compatibility switches.
    Refer to the Appendix on Library Building.


dBASE IV

    Code Base is compatible with dBASE IV database (DBF), index (NDX) and
    memo file (DBT) file formats.



UNIX, XENIX

    There is a special version of Code Base for Unix/Xenix.




APPENDIX C - ERROR MESSAGES

    Code Base sends all error messages through a single routine which writes
    the error message and then sets the global error code: 'extern int
    v4error'.

    Consequently, it is easy to customize your own error handling by changing
    the Code Base routine 'u4error'.

    Whenever an error occurs, Code Base calls 'u4error'. Some critical errors
    cause Code Base to immediately halt. However, an error return is usually
    made.

    Following is a completer list of error messages which are organized by
    error number.

    General Disk Access Errors

    100    Creating File.

           This error could be caused by specifying an illegal file name,
           attempting to create a file which is open, or having a full
           directory or a disk problem.


    120    Opening File.

           This problem is usually caused by specifying a file which does
           not exist. Another possible cause is an attempt to open more
           files than the operating system can handle. Up to 20 files can
           be opened under DOS if "FILES=20" is specified in the
           "CONFIG.SYS" file.


    140    Reading File.

           A problem reading a file could be caused by a disk failure.


    160    Writing File.

           This error will occur when the disk is full.


    180    Closing File.

           An error occured while attempting to close a file.



    Database Specific Errors

    200    File is not a Database.

           This error occurs when routine "d4use" attempts to open a file
           which is not a database file.


    240    No Open Database.

           Open a database with "d4create" or "d4use" before calling a
           database routine.


    260    Record Length is Too Large.

           The current maximum record length is 32666.


    Index File Specific Errors

    300    Building Index File.

           Either there was insufficient memory, or there were too many
           records in the database to index. Try using the large memory
           model.


    310    Closing Index File.

           This error indicates that routine "i4close" was passed an
           illegal index reference number or that the index file could
           not be closed.


    320    File is not an Index File.

           This error occures when routine "i4open" attempts to open a
           file which is not a legitimate index file for the
           corresponding database.


    330    Index File is Missing a Key.


           The index file key, corresponding to an existing database
           record, does not exist.


    340    Key is not Unique.

           When an index file is created with the "Unique" flag on, all
           keys in the index file must be unique. An attempt to add a
           second key with the same value, causes this error.


    350    Key Evaluates to a Logical Result.

           Only character, numeric and date keys are allowed for index
           files.


    360    Key Length or Type has Changed.

           Once an index file has been created, the length or type of its
           key should not change. This can happen when the structure of
           the index files database is changed. For example, if an index
           file is indexed on a particular field and the field's type is
           changed from character to numeric, the index file will no
           longer be valid.


    370    Key Length over 100 Characters.

           A maximum of 100 characters are allowed for an index file key.
           This key length is determined by the expressin corresponding
           to the index file's key.


    380    Seek on Database with no Index File.

           Routine "d4seek" can only be made on a database with a
           corresponding index file.

           Routine "i4select" was passed and index reference number which
           does not correspond to an index file.


    Multi-User Errors

    400    Locking a File.

           There was a problem locking a database or index file.

    450    Unlocking a File.

           There was a problem unlocking a database or index file.



    Expression Evaluation Errors

    500    Database not Located while Evaluating Expression

           The database specified in the expression was not located.


    510    Executing Null Expression.

           Routine "e4exec" was passed a null pointer which should have
           been a pointer to a pseudo-compiled expression.


    515    Illegal Date.

           An illegal date was encountered when seeking or evaluating a
           date value.


    520    Expecting "," or ")" while Evaluating Expression.

           The expression is probably missing a comma or a right bracket.


    530    Expression is not Complete.

           The expression could not be evaluated because it is not a
           legitimate dBASE expression.


    540    Overflow while Evaluating Expression.

           The expression was too large or complex for Code Base. Code
           Base exits immediately if this error occurs.


    550    Parameter or Operator has the wrong Type.

           The expression 3+"A" would generate this error message. The
           operator '+' cannot add three to the letter "A". "A" is of
           type character rather than type numeric.

           Expression "SUBSTR(33,1,4)" would also generate this error
           message. In this case, the parameter 33 is the wrong type. The
           first parameter of function SUBSTR should be character.

    560    Right Bracket Missing in Expression.

           Make sure the expression has enough right brackets.


    570    Unrecognized Function in Expression.

           There was an attempt to use a function which is not supported
           by Code Base. Refer to the Appendix on Functions. Carefully
           check the function's spelling.

    575    Unrecognized Operator in Expression.

           Code Base supports a number of operators such as "+" and "/".
           You are attempting to use an operator which is not supported
           by Code Base.


    580    Unrecognized Value in Expression.

           There is a value in the expression which is not recognized as
           a field, string, number, logical value, or function.


    590    Unterminated String in Expression.

           A character sting's left quotes does not have a corresponding
           right quote.


    595    Wrong Number of Parameters in Expression.

           An expression function or operator was given an illegal number
           of parameters.


   Memo File Errors

    600    Editing Memo File with Editor.

           Either the specified editor program is not present or there is
           not enough memory.


    620    Memo File Name Inconsistency.

           You have either renamed a dBASE IV memo file without calling
           'm4renamed' or a non-dBASE IV memo file is being used with the
           dBASE IV memo file routines. Refer to 'm4convert'.


    640    Memo File Entry is over 32767 bytes.

           The maximum memo file entry size is 32767 bytes.




   Windowing and Menuing Errors

    800    Illegal Related Database.

           The related database was the same as the controlling database
           when defining a database 'relation'.


    820    No Controlling Database.

           No valid controlling database was specified when defining a
           database 'relation'.


    840    Relating Databases.

           An error occured while automatically positioning a related
           database.



   Critical Errors

    900    Out of Memory.

           An attempt was made to allocate some memory and no more was
           available.


    920    Memory Allocation.

           An attempt was made to allocate more than 0xFFE0 bytes of
           memory at once. This can be caused by opening too many files,
           or having too many windows, entry areas or index file blocks.


    950    Overwritten Memory.

           Code Base failed on an internal consistency check. This error
           occures when the application program has overwritten memory
           which Code Base uses.


    980    No Error Window.

           A default window is defined when either 'd4init' or 'w4define'
           is called for the first time. This error is reported on
           standard out if 'u4error' is called and the default window has
           not yet been defined.



APPENDIX D - EXPRESSIONS

    In Code Base, expressions are represented as a character string and are
    evaluated in the expression evaluation module.  Expressions are used to
    define the keys of an index file.  They can be useful for other
    purposes such as interactive queries.

   General Expression Information

    All expressions return a value of a specific type.  This type can be
    Numeric, Character, Date or Logical.

    A common form of an expression is the name of a field.  In this case,
    the type of the expression is the type of field.

    Field names, constants, and functions may all be used as parts of an
    expression.  These parts can be combined with other functions or with
    operators.


   Expression Constants

    Expression can onsist of a Numeric, Character or Logical constant.
    However, expressions which are constants are usally not very useful.
    Constants are usually used within a more complicated expression.

    A Numeric constant represents a number. For example. 5, 7.3, and -18
    are all Numeric constants.

    Character constants are letters with quote marks around them. "This
    is data", 'This is data', and "John Smith" are all examples of
    Character constants. If you wish to specify a character constant with
    a single quote or a double quote contained inside it, use the other
    type of quote to mark the Character constant. For example, "Man's"
    and '"Ok"' ar both legitimate Character constants.

    .TRUE., .FALSE. are the only legitimate Logical constants. .T. and
    .F. are legitimate abbreviations.


   Expression Operators

    Operators like '+', '*', or '<' are used to manipulate constants and
    fields. For example, 3+8 is an example of an expression in which the
    Add operator acts on tow numeric constants to return the numeric
    value 11.

    The values an operator acts on must have a type appropriate for the
    operator. For example, the Divide (/) operator acts on two numeric
    values.


    Precedence

    Operators have a precedence which specifies operator evaluation
    order. The precedence of each operator is specified in the following
    tables which describe the various operators. The higher the
    precedence, the earlier the operation will be performed. For example,
    Divide has a precedence of 6 and Plus has a precedence of 5 which
    means Divide is evaluated before Plus. Consequently, 1+4/2 is 3.

    Evaluation order can be made explicit by using brackets. For example,
    1+2 * 3 returns 7 and (1+2) * 3 returns 9.


    Numeric Operators

    The numeric operators all operate on Numeric values.

    Operator Name             Symbol        Precedence

    Add                       +             5
    Subtract                  -             5
    Multiply                  *             6
    Divide                    /             6
    Exponentiation            ** or ^       7


    Character Operators

    There are two character operators, named "Concatenate I" and
    "Concatenate II", which combine two character values into one. They
    are distinguished from the Add and Subtract operators by the types of
    the values they operate on.

    Operator Name             Symbol        Precedence

    Concatenate I             +             5
    Concatenate II            -             5

    Examples:

           "John  "+"Smith"   becomes       "John  Smith"
           "ABC"+"DEF"        becomes       "ABCDEF"


    Concatenate II is slightly different as any spaces at the end of the
    first Character value are moved to the end of the result.

    Examples:

           "John  "-"Smith"   becomes       "JohnSmith  "
           "ABC"-"DEF"        becomes       "ABCDEF"
           "A "-"D "          becomes       "AD  "


    Relational Operators

    Relational Operators are operators which return a Logical result
    (which is either true or false). All operators except Contain operate
    on Numeric, Character or Date values. Contain operates on two values
    of type character and returns true if the first is contained in the
    second.

    Operator Name             Symbol        Precedence

    Equal To                  =             4
    Not Equal To              <> or #       4
    Less Than                 <             4
    Greater Than              >             4
    Less Than or Equal To     < =           4
    Greater Than or Equal To  > =           4
    Contain                   $             4


    Example:

           "CD"$"ABCD"        returns true
           8<7                returns false


    Logical Operators

    Logical Operators return a Logical Result and operate on two Logical
    values.

    Operator Name             Symbol        Precedence

    Not                       .NOT.         1
    Or                        .OR.          2
    And                       .AND.         3

    Examples:

           .NOT. .T.          returns false
           .T. .AND. .F.      returns false.



   Expression Functions

    A function can be used as an expression or as part of an expression.
    Like operators, constants, and fields, functions return a value.
    Functions always have a function name and are followed by a left and
    right bracket. Values (parameters) may be inside the brackets.

    Warning

           These are not C functions to be called directly from C
           programs. These are dBASE functions which are recognized by
           the dBASE expression evaluation module.

   Function List

   CTOD( Char_Value )

    The character to date function converts a character value into a date
    value:

    CTOD( "19881130" )

    The character representation is always in the format "CCYYMMDD".


   DTOC( Date_Value ) and DTOS ( Date_Value )

    The date to character function converts a date value into a character
    value. The format of the resulting character value is "CCYYMMDD".

    DTOC( DATE() )

    returns the character value "19870530" if the date is May 30, 1987.


   DATE()

    The system date is returned.


   DEL()

    Returns "*" if the current record is marked for deletion.
    Otherwise " " is returned.


   DELETED()

    Returns .TRUE. if the current record is marked for deletion.


   IIF( Log_Value, True_Result, False_Result )

    If Log_Value is .TRUE. then IIF returns the True_Result value:
    otherwise, IIF returns the False_Result value.

    Examples:

           1. IIF( VALUE < 0, "Less than zero", "Greater than zero" )
           2. IIF( NAME = "John", "The name is John", "Not John" )

   RECCOUNT()
    The record count function returns the total number of records in the
    database:

    RECCOUNT()

    returns 10 if there are ten records in the database.


   RECNO()

    The record number function returns the record number to the current
    record.


   STR( Number, Length, Decimals )

    The string function converts a numeric value into a character value.
    "Length is the number of characters in the new string, including the
    decimal point. "Decimals" is the number of decimal places desired. If
    the number is too big for the alloted space, "*'s" will be filled in
    instead.

    Examples:

           1. STR( 5.7, 4, 2 )    returns "5.70"

          The number 5.7 is converted to a string of length 4. In
          addition, there will be 2 decimal places.

           2. STR( 5.7, 3, 2 )    returns "***"

          The number 5.7 cannot fit into string of length 3 if it is
          to have 2 decimal places. Consequently, "*'s" are filled in.


   SUBSTR( Char_Value, Start_Position, Num_Chars )

    A substring of the Character value is returned. The substring will be
    Num_Chars long, and will start at the Start_Position character of
    Char_Value.

    Examples:

           1. SUBSTR( "ABCDE", 2, 3 )       returns "BCD"
           2. SUBSTR( "Mr. Smith", 5, 1 )   returns "S"


   TIME()

    The time function returns the system time as a character
    representation. It uses the following format: HH:MM:SS.

    Examples:

           1. TIME()      returns 12:00:00  if it is noon.
           2. TIME()      returns 13:30:00  if it is one thirty PM.


   UPPER( Char_Value )

    A character string is converted to uppercase and the result is
    returned.


   VAL( Char_Value )

    The value function converts a character value to a numeric value.

    Examples:

           1. VAL( "10" )         returns 10
           2. VAL("-8.7" )        returns -8.7



APPENDIX E - LIBRARY BUILDING

   The files used to build the Code Base libraries are included on the
   repective library diskette:

    File      Purpose

    T4.BAT    To compile the files and build Turbo C compatible library
          "T4.LIB".

    M4.BAT    To compile the files and build the Mircosoft C and Quick C
          compatible library "M4.LIB".

    M4        An input file for the library builder 'lib.exe'. This file
          is used by the batch command file 'M4.BAT'.

   These files can be modified to build a custom Code Base library using any
   memory model or floating point option. Just do the following.

   1. Erase all existing Code Base object modules:

    erase ?4*.obj


   2. Copy the Code Base source files from the source diskette to the
      appropriate directory on your hard drive.

    copy a:*.* c:\c


   3. Copy the header files to your hard drive. These files are present on
      the Code base Microsoft library diskette.

    copy a:\include\*.h c:\c\include


   4. Copy file 'w4asm.obj' which is on the Code Base 4 MC library diskette.
      The assembler source code to 'w4asm.obj' is also on the same diskette
      and was compiled with Microsof Macro Assmebler 5.1.


   5. Copy the appropriate command files. These files are present on the Code
      Base library diskettes. Note that the pre-built libraries which are
      used for both Quick C and Microsoft C were generated using the C
      optimizing compiler with full optimization.

    copy a:t4.bat c:\c

           or

    copy a:m4.bat c:\c
    copy a:m4     c:\c


   6. Set the compiler options. Quick C and Microsoft C options are specified
      in the file 'm4.bat'. Turbo C compilations options are specified in
      file 'turbo.cfg'. To compile using Quick C, file 'm4.bat' needs to be
      changed so that the compiler 'QCL.EXE' is excuted rather than Microsoft
      C compiler 'CL.EXE'.

      For more information, refer to the documentation which came with your
      compiler.


   7. Start the compilation and library building.

    t4  (Execute 't4.bat')

           or

    m4  (Execute 'm4.bat')


   8.   Erase the generated object files.


   Codebase Compilation Switches

    Code Base contains several compilation switches. For example, there
    are switches for the OS/2 operating system, the Clipper NTX file
    compatibility option or Turbo C compatibility. The default is
    compatibility with dBASE, DOS ( versions 2.0 through 4.0), and
    Microsoft C (Quick C).

    Switch        Effect

    CLIPPER       This switch is used throughout to make Code Base
              compatiable with Clipper NTX files.  Regardless of how
              this switch is set, Code Base will be compatible with
              both Clipper and dBASE data files.

              When using Clipper Index Files, routines 'i4seek',
              'i4go', 'i4add' and 'i4remove' all expect Numeric Keys to
              formatted as ASCII with leading zeros.  However, the high
              level database routines operate identically.  To call
              'i4seek', 'i4go', 'i4add' or 'i4remove' directly, first
              call routine 'c4dtok' to transform the 'double' to the
              correct format.

    NOIO          This switch removes all references to the screen
              management routines from Code Base.  Instead, the
              standard library routine 'write' sends output to standard
              out.  Currently, the only routines effected are
              'u4error', 'd4init', and 'd4init_memory'.

    OS2           This switch is used in files 'w4.c' and 'g4.c' so Code
              Base uses the OS/2 video I/O calls rather than calls to
              library routine 'int86'.


    SMALL         All references to index file routines are removed from
              Code BASE.  This allows the creation of applications with
              very small EXE files.  If this switch is selected, do not
              use any index file routines, extend routines, and the
              following database routines: d4bottom, d4seek, d4skip,
              and d4top.

    TURBO         This switch makes Code Base compatible with Turbo C.  It
              is necessary slight differences between the Turbo C and
              Microsoft runtime libraries.

    WINDOWS_L     This switch lets the database management routines be
              used from Microsof Windows with the Medium or Small
              memory models. It is used in the memory allocation
              module and the 'u4error' routine.

    WINDOGS_G     This seitch lets the database management routines be
              used from Microsoft Windows with the Large or Compact
              memory models.


    Examples:

           Compiling with Microsoft C and OS/2 using the Large Memory
           Model:

          CL -Ox -Z1 -DOS2  -AL  -c  ?4*.c


           The switches '-Ox' and '-Z1' specify maximum optimization, and
           that there is to be no information relating to automatic
           library loading within the generated object modules. This
           information is not necessary in the Code Base library because
           it will be present in the application object modules.

           Compiling with Microsoft C for Quick C (Medium Memory Model)
           using the Clipper option:

          CL -Ox -Z1 -DCLIPPER -AM -c ?4*.c


           To compile with Turbo C using the small memory model, the
           Clipper compatibility option, and stack overflow logic, the
           file "turbo.cfg" would contain the following:

          -LC:\TC\LIB -IC:\TC\INCLUDE  -ms -c -DTURBO -DCLIPPER -N

           This assumes that the Turbo C library files are in directory
           "C:\TC\LIB" and that the Turbo C header files are in
           directory "C:\TC\INCLUDE".



APPENDIX F - Technical Support

   Before calling Sequiter Software Inc. for technical support on Code Base,
   do the following:

    1. Experiment with program 'd4learn' to learn the routines in question.

    2. Consult the programs on the library diskettes.

    3. Read the appropriate sections of the Code Base manual carefully.
       Make sure you understand what is being explained.

    4. Try writing a short program to illustrate the problem you are
       having. This process often solves the problem.

    5. If you are using Turbo C, make sure the TURBO conditional
       compilation switch is defined.

    6. If you are experiencing errors at link time, make sure that all of
       the object modules and libraries have been compiled in a
       consistent manner. They should all be compiled using the same
       memory model, and the same compilation switches. For example, if
       the Code Base library you are using was compiled using Turbo C 2.0
       with the 'CLIPPER' switch defined, make sure that your own code
       was compiled in the same manner. The 'readme' file on the MC
       library diskette specifies which versions of the supported
       compilers which were used to construct the prebuilt Code Base
       libraries. If there are undefined exteranl messages, note that all
       externals defined by Code Base 4 contain the character '4' in the
       second character position of the external name.

    7. If the trouble stems form a problem with general 'C' programming
       concepts consult your 'C' manuals.

    8. If you have any suggestions on how to improve Code Base, or if you
       have any Code Base applications which you would like to submit as
       freeware, we would like to hear from you. Please mail your
       comments to the address on the back of the manual.


APPEXDIX G - CODE BASE INTERNALS

   To understanding how Code Base operates, it is useful to understand the
   basics of how Code Base operates internally. However, it is not neccessary
   to be familiar with this material to use Code Base. Understanding this
   information should also assist anyone examing Code Base source code or
   those wishing to supplement Code Base library with their own routines.

   Record Buffer Format

    A Code Base record buffer uses the same storage format as the records
    stored on disk. They start with a one character record deletion flag.
    This flag is normally blank and is an asterisk ('*') when the record
    is marked for deletion. Following the deletion flag are all of the
    database fields in consecutive order. There are no special characters
    delimiting the field data. For example, if the first database field
    had a width of three, it would be contained in the second through
    fourth bytes of the record buffer. The second field would be stored
    immediately after the first field.

    All field types are stored as ASCII. For example, a numeric field
    with a width of 5 and 2 decimals could contain ASCII '5.70'. This
    would represent five decimal seven.

           Field Type         Storage Format

           Numeric            Right justified ASCII.

           Floating Point     Same as numeric.

           Date               CCYYMMDD (Ex. '19891231')
                  (Century, Year, Month Day)

           Logicals           'T', 't', 'Y' and 'y' for TRUE
                  'F', 'f', 'N' and 'n' for FALSE

           Memo               Ten characters of ASCII representing a
                  position in the corresponding memo file.


   Field Reference Numbers

    The database structure, of type 'BASE', contains a member which is a
    pointer to a structure array of type '(FIELD *)'. This array, defined
    by 'd4use', contains all of the field information associated with a
    database. The 'FIELD' structure is defined as follows:

           typedef struct
           {
          char        name[11] ;   /* Field Name */
          int         type ;       /* Field Type */
          char        width ;      /* Field Width */
          int         decimals ;   /* Number of Decimals */
          int         offset ;     /* Offset into Record Buffer */
           }  FIELD ;

    A field reference number is a long integer broken into two parts. The
    high order tow bytes contains the corresponding database reference
    number and the low order two bytes are an index into the '(FIELD *)'
    structure array. Consequently, the source code to routine 'f4j_ref'
    is as follows:

           long   f4j_ref( j_ref )
           int    j_ref ;
           {
          if ( j_ref > f4num_fields() || j_ref < 1 )
              return ( -1L ) ;
          else
              return ( (long) v4cur_vbase << 16 |
                  (long) (j_ref -1 ) ) ;
           }


   Code Base Memory Usage

    Code Base external variable names all start with 'v4'. There are
    several important variables which all point to arrays of structures:
    v4base, v4index, v4block, v4window, v4menu and v4get. Each structure
    of these structure arrays correspond to either a database, index
    file, index file B+ Tree node, window, menu item or get entry area
    respectively.

    Each of the Code Base structure arrays are mainpulated with the Code
    Base memory handling routines. This means if there is not enough
    space in a structure array to handle any particular routine call, the
    structure array is reallocated with a larger size. As a result, Code
    Base is built for the use of an unlimited number of databases, index
    files, windows, menus and get entry areas. Note that this memory
    reallocation will not occur very often.

    The Code Base memory handling routines also maintain a set of double
    linked lists for every memory structure. In addition to a double
    linked lists ou unused array structure entries, each structure array
    maintains the following double linked lists:

           Array          Double Linked List Usage

           v4base         Uses a double linked list of open databases.
                  The database reference number to the last
                  opened database is contained in the external
                  integer variable 'v4last_base'. Similarily, the
                  reference number to the currently selected
                  database is contained in external integer
                  variable 'v4cur_base'.

           v4index        There is a double linked list of open index
                  files for every open database which has one or
                  more index files. An index file reference
                  number, for each double linked list, is saved.
                  This reference number is contained in the
                  corresponding database structure. Similarily,
                  the reference number of the currently selected
                  index file is saved. Refer to the structure of
                  type 'BASE' and 'INDEX' which are defined in
                  header file 'd4base.h'.

           v4block        There is a double linked list of index file B+
                  Tree nodes in memory for each index file. The
                  reference number to each of these double linked
                  lists is contained in the corresponding index
                  file structure.

           v4window       There is one double linked list of defined
                  windows. The reference number to the first
                  defined, last defined, and currently selected
                  windows, are defined in external integer
                  variables 'v4first_window', 'v4last_window'
                  and 'v4cur_window' respectively. As windows
                  becomve activated, the ordering of this double
                  linked list changes. It becomes the order in
                  which the windows were activated.

           v4menu         There is a double linked list of menu items for
                  each window containing a menu. The reference
                  number to the first and last defined menu
                  items, of a window, are contained in the
                  corresponding window structure. Refer to header
                  file 'w4.h'.

    All reference numbers, except for field reference numbers, are
    subscripts into the corresponding structure array. For example, the
    first time routine 'd4use' is called, it returns a database reference
    number of '(int) 0'. This means that structure entry v4base[0]
    contains the information about the database. The source code to
    routine 'd4recno' provides insight as to how reference numbers are
    used:

           long  d4recno()
           {
          /* 'v4cur_base' is the currently selected database
             reference number */

          if ( v4base[v4cur_base].rec_num <= 0 )
              return( 0L ) ;
          else
              return( v4base[v4cur_base].rec_num ) ;
           }

    The double linked lists, mentioned above, are easily maitained by
    defining the first two members, of each structure array, to be the
    next and previous reference numbers respectively. As the reference
    numbers are fixed integers, the double linked lists are kept intact
    when a memory structure is reallocated. In addtion, if exact memory
    copies of the memory structures are saved to disk adn then read back,
    the double linked lists will be maintained. Sequiter's dBEditor
    product makes use of this fact.

    A reference number of '(int) -1', means that there is no structure
    entry, For example, if 'v4last_base' is '(int) -1', there are no open
    databases. Similarily, if there is one database open,
    'v4base[v4last_base].prev' is '(int) -1' as the double linked list of
    open databases would only have one entry.