*************************************
                    *                                   *
                    *          DB/C Newsletter          *
                    *            March 1996             *
                    *                                   *
                    *************************************

                               Editor's Notes

     DB/C 9.0 is now available.  DB/C 9.0 information is being mailed to all
customers the week of March 4.  Prices and the DB/C 9.0 announcement brochure
are included in the mailing.  The DB/C 9.0 announcement brochure is available
in PDF file format at ftp.swc.com as the file named /pub/dbcinfo/dbc9annc.pdf.

     There was a technical error in last month's DB/C Newsletter.  To output
Postscript print files, you should specify "L=PS" in the last operand of the
splopen statement, not "L=POSTSCRIPT".

     The creation of a PL/B USENET newsgroup on the Internet has been proposed
by Stuart Floyd.  It is currently in the discussion phase.  The proposed news
group is comp.lang.plb.  If you are interested, you can read the original
Request For Discussion (RFD) in the file /pub/misc/rfdplb.txt at ftp.swc.com.

     This month's article is an overview of the C functions that are part of
DB/C 9.0.  In the past, programmers have only had access to these C functions
by purchasing one year of support of the C functions for $750.  Starting with
DB/C 9.0, the documentation and the C header files necessary to understand
and use the C functions will be available at ftp.swc.com in the directory
/pub/dbccapi.  Anonymous access to this directory is not allowed.

     Support for the C functions is still available for $750 per year.  This
support includes voice, fax and email support.  If you elect not to purchase
the yearly support, the only support you will receive is via email and only
includes question and answer type queries.  Without the yearly support, we
will not look at programs.  All email should be sent to dbc@swc.com.  Response
time is not guaranteed unless you have purchased the yearly support.

     As before, the C functions are not royalty free.  The use of the code
that is associated with the C functions, even in linked form, is limited to
computers that are licensed to use DB/C.

                                                           don.wills@swc.com



                             DB/C C API Overview

     The DB/C C functions applications programming interface (the DB/C C API)
consists of more than 100 C functions that provide various capabilities.  Some
of these capabilities include:  file processing, keyboard and display handling,
GUI operations, memory management, event handling, queue processing, command
line handling, timers, and other miscellaneous functions.  These functions are
all completely portable.

     The C functions are available in the form of object files or libraries.
In some cases, they are distributed on the standard DB/C distribution media.
In other cases (such as Windows 95), they are included only if the customer
requests that they be included with the DB/C distribution.

     The function prototypes and #defines necessary to compile C programs that
use the DB/C C API are:

     includes.h (base typedefs and operating system definitions)
     mem.h (memory management)
     evt.h (event handling)
     que.h (queue processing functions)
     fio.h (files - records, ISI, AIM, filenames, locking, command line, etc.)
     msc.h (stdout handling, timers, argv/argc handling, etc.)
     vid.h (keyboard and screen display functions)
     gui.h (GUI processing - windows, resources, images, mouse, keyboard)


The include files usage dependencies are:

     includes.h is required for all programs.
     mem.h defines functions starting with 'mem'.
     evt.h defines functions starting with 'evt'.
     que.h defines functions starting with 'que'.
     fio.h defines functions starting with 'fio', 'mio', 'rio', 'xio', 'aio'.
     msc.h defines functions starting with 'msc'.
     vid.h defines functions starting with 'vid'.
     gui.h defines functions starting with 'gui'.

     Certain functions require the use of other C API functions and therefore
need the other C functions to be initialized.  Here is a list of these
dependencies.

     'mem' functions require meminit() to be called first.
     'evt' functions do not require any other functions to be called first.
     'que' functions require meminit(), then fioinit() to be called first.
     'fio', 'mio', 'rio', 'xio', 'aio' functions require meminit(), then
           fioinit() to be called first.
     Some 'msc' functions require meminit(), then fioinit() to be called first.
     Some 'msc' functions require only meminit() to be called first.
     'vid' functions require meminit(), then vidstart() to be called first.
     'gui' functions require meminit(), then guiinit() to be called first.

     For portability, all of the variable types are defined in includes.h.
Here is a list of the variable types:

     UCHAR is an 8 bit unsigned integer.
     BYTE is an 8 bit unsigned integer.
     SHORT is a signed integer, at least 16 bits large, and not larger than
          the size of an INT.
     USHORT is an unsigned integer, at least 16 bits large, and not larger
          than the size of a UINT.
     INT is a signed integer, at least 32 bits large.
     UINT is an unsigned integer, at least 32 bits large.
     LONG is a signed integer, at least 32 bits large, and not smaller than
          the size of an INT.
     ULONG is an unsigned integer, at least 32 bits large, and not smaller
          than the size of a UINT.
     INT32 is a signed 32 bit integer.
     UINT32 is an unsigned 32 bit integer.


     The memory management functions (the 'mem' functions) manage moveable
memory.  Moveable memory is memory that may not remain fixed (that is, its
address may change) across certain function calls.  Access to a block of
moveable memory is through a pointer to a pointer to the actual memory.
The value returned by memalloc() is the pointer to a pointer.  Be sure to
reference moveable memory only through this double pointer.  Do not store
the actual memory address in your programs - only store the pointer to the
address.  In the DB/C C API documentation, those functions that can cause
moveable memory to move are noted.  Functions that can not move moveable
memory do not have the notation.

     The meminit() function initializes the area where the moveable memory 
blocks will be located.  Its first parameter is analogous to the value of
DBC_MEMALLOC.  memalloc() allocates a block of moveable memory.  memfree()
frees a block.  memchange() changes the size of a block.  membuffer() and
membufend() can be used to convert a block of moveable memory into a purgeable
buffer.

     The evtcreate() function creates an event flag.  An event flag is an INT.
An event flag is a simple semaphore that can be used to signal the completion
of an event.  An event flag has two states:  set and clear.  A thread of
execution can wait for one or more event flags to become set.  evtset() sets
an event flag.  evtclear() clears an event flag.  evttest() tests the state
of an event flag.  evtwait() is used to suspend the thread of execution until
one or more event flags of an array of event flags are set.  evtmultiplex()
causes an integer to be modified if any of the event flags of an array of
event flags are set.  evtstartcritical() and evtendcritical() are used to
denote a critical section of code.  This is a high-performance method of
protecting a section of code or data from being used by another thread.

     The quecreate() function creates a queue.  A queue is a QUEHANDLE,
which defined in que.h.  quedestroy() destroys a queue.  quetest() tests
whether a queue is empty or not.  queempty() deletes all messages from a
queue.  queuput() puts a message at the end of the list of messages in a
queue.  queputfirst() puts a message at the beginning of the list of messages
in a queue.  queget() gets a message from the beginning of the list of
messages in a queue.  quegetmsg() gets a message from the beginning of the
list of messages in a queue, while discarding multiple similar messages.
It is useful in dealing with mouse messages, some of which may need to be
discarded when the mouse is being moved quickly.

     The fioinit() function initializes all file functions.  fioopen() opens
a file.  If fioopen() successfully opens a file, it returns a file number.
A file number is an INT.  fioclose() closes a file number.  fiokill() deletes
the file associated with the file number.  fread() and frwrite() read and
write bytes from a file.  fiogetsize() returns the size of a file.  fioname()
returns the actual operating system file name associated with a file number.
fiotouch() and fioclru() manipulate the least recently used file open queue.
fioflush() flushes the OS file buffers to disk.  fiolock(), fiounlock(),
fioflck(), fiofulk(), fiolckpos() and fioulkps() implement file and record
locking.

     The rioopen() functions opens a file for record-oriented I/O.  It returns
a file number that is used in the same manner as with fioopen(), etc.  The
rioclose() and riokill() functions perform functions analogous to fioclose()
and fiokill().  rioget() reads the record at the current record position and
increments the current record position.  rioprev() is similiar except that
the current record position is decremented.  rioput() writes a record at the
current record position and increments the current record position.  The
rioparput() function implements the DB/C equivalent of a partial write.  The
riodelete() function deletes a record.  The riosetpos(), rionextpos(),
riolastpos(), riogrplpos(), and rioeofpos() functions manipulate the current
record position.  rioweof() writes an end of file mark.  rioflush() flushes
the record buffer to disk.  riotype() returns the type of file (standard, text
or data).  riolock() and riounlock() implement record locking.

     The xioopen(), xioclose() and xiokill() functions implement open, close
and delete of an ISAM (.isi) file.  The xiofind() function returns the text 
file record position of a given key.  xionext() returns the text file record
position of the next key sequential record.  xioprev() returns the text file
record position of the previous key sequential record.  xiodelete() deletes
a key from the index file.  The xiogetrec() and xioputrec() functions are used
to implement deleted record space reuse in the associated text file.  The
xioflush() function flushes the buffers to disk.

     The aioopen(), aioclose() and aiokill() functions implement open, close
and delete of an AIM (.aim) file.  The aiomatch() function changes the current
match character.  The aionew() function starts a new lookup sequence.  The
aiokey() function adds a search criteria to the lookup sequence.  aionext()
returns the a text record position of a record that probably matches the
search criteria specified by aiokey().  aiochkrec() checks to see if a text
record actually matches the criteria specified by aiokey().  The aioinsert()
function adds key information to the AIM file.  The aiogetrec() and aioputrec()
functions are used to implement deleted record space reuse in the associated
text file.

     The vidstart() function is used to initialize keyin and display processing
that is done using the 'vid' functions.  videxit() returns the keyboard and
display terminal to the state they were in before vidstart() was called.  The
vidsuspend() and vidresume() functions temporarily restore the terminal to
its initial state.  The vidput() function performs the sequence of commands
specified in its parameter list.  These commands manipulate the display
terminal and its state.  vidreset() resets the terminal's state to a standard
state with a block cursor and standard text display mode.  vidgetpos()
returns the current cursor position.  vidgetsize() returns the size of the
screen.  vidgetwin() returns the corners of the current subwindow.
vidwinsize(), vidstatesize() and vidscreensize() return the number of bytes
necessary to do vidwinsave(), vidstatesave() and vidscreensave().  vidwinsave()
and vidwinrestore() save and restore the current subwindow.  vidstatesave()
and vidstaterestore() save and restore the current video state.
vidscreensave() and vidscreenrestore() save and restore the screen and its
state.  The vidkeyinstart() function starts a keyin process.  vidkeyinend() 
completes a keyin process.  vidkeyinabort() abnormally terminates a keyin
process.  vidkeyinclear() discards all keystrokes in the key-ahead buffer.
vidkeyinvalidmap() sets the valid keystrokes.  vidkeyinfinishmap() sets the
valid keyin process terminating characters.  vidtrapstart(), vidtrapget(),
and vidtrapend() implement keystroke trapping.

     The guiint() function is used to initialize the GUI processing done using
the 'gui' functions.  guiexit() frees the resources allocated by guiinit().
guiabout() sets the text in the About... box.  guimsgbox() displays text in
a dialog with an OK button.  guibeep() causes a beep sound.  guiwincreate()
creates a window.  guiwinmsgfnc() causes messages from a window to be sent
to the function specified.  guiwinchange() changes attributes of a window.
guiwindestroy() erases a window.  guirescreate() and guiresdestroy() create
and destroy a resource.  guimenustart() makes a resource into a menu resource.
guipopupmenustart() makes a resource into a popup menu resource.  All functions
that start with 'guimenu' are used to specify the attributes of a menu or
popup menu.  guipanelstart() makes a resource into a panel resource.
guidialogstart() makes a resource into a dialog resource().  All of the
functions that start with 'guipandlg' are used to specifiy the attributes of
a panel or a dialog.  guitoolbarstart() makes a resource into a toolbar
resource.  All functions that start with 'guitoolbar' are used to specify the
attributes of a toolbar.  guiicon() makes a resource into an icon resource.
guiopenfiledlgstart() makes a resource into an open file dialog.
guisaveasfiledlgstart() makes a resource into a save as file diagog.  The
guifiledlgdefault() and guifiledlgend() functions define the attributes of
an open or save as file dialog.  The functions that start with 'guifontdlg'
define a font dialog resource.  The functions that start with 'guicolordlg'
define a color dialog resource.  guiresquery() and guireschange() query
and alter the attributes of a resource.  guiresshow() and guireshide()
show and hide a resource.  guiresmsgfnc() causes messages from a resource
to be sent to the function specified.  guipixcreate() and guipixdestroy()
create and destory a pixel map.  guipixshow() and guipixhide() show and hide
a pixel map.  The functions that start with 'guipixdraw' write bits to a
pixel map.  The functions that start with 'guicbd' manipulate the clipboard.
guipixtotif(), guitiftopix(), guigiftopix() and guijpgtopix() convert
pixel maps to and from standard file formats.  The guiprtopen() and
guiprtclose() functions open and close a printer.  The other functions that
start with 'guiprt' cause bits to be printed on the printer.

     Whew!  There is a lot of detail in writing C programs.  Hopefully, this
article has given you a feeling for what is available with the DB/C C API.
 


                             DB/C Class Schedule

        Class                        Date                      Location
 DB/C Fundamentals         April 10 through April 12        Oak Brook, IL
 DB/C Advanced Features    April 17 through April 19        Oak Brook, IL

For information, contact Judi Tamkevic at:
     voice  708.572.0240
     fax    708.572.0390
     email  dbc@swc.com