[Home] [Table of Contents] [Previous Section] [Next Section]
Breck Carter
Last modified: October 21, 1999
mail to: bcarter@bcarter.com


Tip 90: UltraLite Lite


9 - Write the C and ESQL Source Code

This section presents the source code written as a combination of C and Embedded SQL in one single module. There is no need to separate the Embedded SQL into a separate file unless you want to, and in this application it is simpler to see all the code in one place.

Comments in the code describe each SDK and UltraLite function call; here's a quick overview of the program structure:

  • Palm interfaces consist of forms (windows) and objects on forms (fields, buttons, etcetera).

  • Objects have IDs (numbers like 1000, 1001). They can also be manipulated via pointers and indexes.

  • The three functions GetObjectPtr(), SetFieldText() and GetFieldText() take care of some of the low-level tasks required when manipulating objects on forms.

  • ULLdemo1FormHandleEvent() process two kinds of events. When it sees the "form open" event, it executes a SQL SELECT to fill the text field from the embedded database. When it sees a tap on the Exit button, it stops the application.

  • AppHandleEvent() is called from PilotMain(). If it sees a request to load a form, it loads the application's only form and sets up ULLdemo1FormHandleEvent() as that form's event handler.

  • PilotMain() is the main entry point. It contains the application initialization code, an event-handling loop, and application termination logic. The initialization and termination steps include handling the HotSync download and upload streams respectively. In this application the termination logic save the database changes before the upload stream is produced.

Here is the source code file c:\amisc\ull\SRC\ULLDemo1.sqc:

/* DO NOT MODIFY ULLDemo1.c !!! ONLY EDIT ULLDemo1.sqc !!! */

/************************************************************
ulldemo1.sqc
Modification History...
1999 09 10 BC Date begun as ulldemo1.sqc.
1999 09 21 BC Comments added.
************************************************************/

#include <Pilot.h>
#include <SysEvtMgr.h>
#include "ULLDemo1_res.h"

/************************************************************
Pilot.h is a header file provided with CodeWarrior.
SysEvtMgr.h is a header file provided with CodeWarrior.
ULLDemo1_res.h is the header file created by the Constructor
  for the ULLDemo1 form.
************************************************************/

EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
  long sql_id;
  char sql_hello[100];
EXEC SQL END DECLARE SECTION;

/************************************************************
These EXEC SQL commands are ESQL declarations.
************************************************************/

static VoidPtr GetObjectPtr( FormPtr frmP, Word objectID )
{
  if( frmP == NULL ) {
    frmP = FrmGetActiveForm();
  }
  return( FrmGetObjectPtr( frmP,
    FrmGetObjectIndex( frmP, objectID ) ) );

  /************************************************************
  FrmGetActiveForm is a Palm SDK function which returns a pointer
    to the current active form.
  FrmGetObjectIndex is a Palm SDK function which returns an object
    index corresponding to an object id.
  FrmGetObjectPtr is a Palm SDK function which returns a pointer
    to an object given its object id.
  ************************************************************/

} // GetObjectPtr

static void SetFieldText( Word fieldId, CharPtr text, Word size )
{
  FieldPtr fieldP;
  Handle  textH;
  CharPtr textP;
  fieldP = (FieldPtr)GetObjectPtr( NULL, fieldId );
  FldDelete( fieldP, 0, 1000 );
  textH= (char**)MemHandleNew( size );
  textP= (char*)MemHandleLock( textH );
  StrCopy( textP, text );
  MemHandleUnlock( textH );
  FldSetTextHandle( fieldP, textH );
  FldDrawField( fieldP );

  /************************************************************
  GetObjectPtr is a local function which returns a pointer
    to a field given its object id.
  FldDelete is a Palm SDK function which deletes characters
    from a field and redraws it.
  MemHandleNew is a Palm SDK function which allocates a new movable
    chunk of memory in the dynamic heap and returns a handle to it.
  MemHandleLock is a Palm SDK function which locks a chunk and
    returns a pointer to the data.
  StrCopy is a Palm SDK function which copies the string data
    from the second parameter to the first.
  MemHandleUnlock is a Palm SDK function which unlocks a chunk.
  FldSetTextHandle is a Palm SDK function which sets the text value
    of a field to the string associated with the specified handle.
  FldDrawField is a Palm SDK function which draws a field.
  ************************************************************/

} // SetFieldText

static CharPtr GetFieldText( Word fieldId )
{
  FieldPtr fieldP;
  CharPtr textP;
  fieldP = (FieldPtr)GetObjectPtr( NULL, fieldId );
  textP=FldGetTextPtr( fieldP );
  return textP;

  /************************************************************
  GetObjectPtr is a local function which returns a pointer
    to a field given its object id.
  FldGetTextPtr is a Palm SDK function which returns a locked
    pointer to a field's text string.
  ************************************************************/

} // GetFieldText

static Boolean ULLdemo1FormHandleEvent( EventPtr eventP )
{
  Boolean  handled = false;
  EventType newEvent;
  FormPtr  frmP;
  switch( eventP->eType )
    {
    case ctlSelectEvent:
      if( eventP->data.ctlSelect.controlID
      == ulldemo1ExitButton ) {
        MemSet( &newEvent,
          sizeof( EventType ),
          0 );
        newEvent.eType = appStopEvent;
        EvtAddEventToQueue( &newEvent );
        handled = true;
      }
      break;
    case frmOpenEvent:
      frmP = FrmGetActiveForm();
      sql_id = 1;
      EXEC SQL SELECT hello
        INTO :sql_hello
        FROM ULLDemo1
        WHERE id = :sql_id;
      if( SQLCODE == SQLE_NOERROR ) {
        SetFieldText( ulldemo1HelloField,
          sql_hello,
          100 );
      }
      else {
        SetFieldText( ulldemo1HelloField,
          "SQL SELECT failed",
          100 );
      }
      FrmDrawForm ( frmP );
      handled = true;
      break;
    default:
      break;
    }
  return handled;

  /************************************************************
  EventPtr is a Palm SDK pointer to EventType.
  FormPtr is a Palm SDK pointer to FormType.
  eventP->eType is a Palm SDK type of event.
  ctlSelectEvent is a Palm SDK event which is sent when the
    pen is put down and lifted on a control.
  eventP->data.ctlSelect.controlID is a Palm SDK ID of the
    control causing the ctlSelectEvent.
  MemSet is a Palm SDK function  which sets a range of bytes
    in the dynamic heap to a byte value.
  appStopEvent is a Palm SDK event which requests the current
    application to terminate.
  EvtAddEventToQueue is a Palm SDK function  hich adds an
    event to the event queue.
  frmOpenEvent is a Palm SDK event which requests an
    application to initialize and draw a form.
  FrmGetActiveForm is a Palm SDK function which returns
    a pointer to the current active form.
  SQLCODE is an UltraLite macro referring to SQLCA.sqlcode.
  SQLE_NOERROR is an UltraLite constant.
  SetFieldText is a local function which displays a string in
    a form field.
  ulldemo1HelloField is a constant defined in the header
    file ULLDemo1_res.h.
  FrmDrawForm is a Palm SDK function which draws all the
    objects in a form and the frame around the form.
  ************************************************************/

} // ULLdemo1FormHandleEvent

static Boolean AppHandleEvent( EventPtr eventP)
{
  Word formId;
  FormPtr frmP;
  if( eventP->eType == frmLoadEvent )
    {
    // Load the form resource.
    formId = eventP->data.frmLoad.formID;
    frmP = FrmInitForm( formId );
    FrmSetActiveForm( frmP );
    switch( formId )
      {
      case Ulldemo1Form:
        FrmSetEventHandler
          ( frmP,
          ULLdemo1FormHandleEvent );
        break;
      default:
        break;
      }
    return true;
    }
  return false;

  /************************************************************
  EventPtr is a Palm SDK pointer to EventType.
  FormPtr is a Palm SDK pointer to FormType.
  eventP->eType is a Palm SDK type of event.
  frmLoadEvent is a Palm SDK event which requests that the
    application load a form into memory.
  eventP->data.frmLoad.formID is a Palm SDK ID of the form
    causing the frmLoadEvent.
  FrmInitForm is a Palm SDK function which loads and
    initializes a form resource.
  FrmSetActiveForm is a Palm SDK function which sets the active
    form and directs all input and drawing to that form.
  Ulldemo1Form is a constant defined in the header file
    ULLDemo1_res.h.
  FrmSetEventHandler is a Palm SDK function which registers
    the event handler callback routine for the specified form.
  ULLdemo1FormHandleEvent is a local event handler callback
    routine.
  ************************************************************/

} // AppHandleEvent

DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
{
  Word     error;
  EventType event;
  FormPtr  frmP;
  if( cmd == sysAppLaunchCmdNormalLaunch ) {
    if( ULPalmLaunch( &sqlca, ULPalmDBStream() ) ) {
      db_init( &sqlca );
      EXEC SQL CONNECT "dba" IDENTIFIED BY "sql";
    }
    FrmGotoForm( Ulldemo1Form );
    do {
      EvtGetEvent( &event, evtWaitForever );
      if(! SysHandleEvent( &event ) ) {
        if(! MenuHandleEvent(0, &event, &error ) ) {
          if(! AppHandleEvent( &event ) ) {
            FrmDispatchEvent( &event );
          }
        }
      }
    } while( event.eType != appStopEvent );
    frmP = FrmGetActiveForm();
    sql_id = 1;
    StrCopy( sql_hello, GetFieldText( ulldemo1HelloField ) );
    EXEC SQL UPDATE ULLDemo1
      SET hello = :sql_hello
      WHERE id = :sql_id;
    if( SQLCODE == SQLE_NOERROR ) {
      EXEC SQL COMMIT;
      SetFieldText( ulldemo1HelloField,
        "SQL UPDATE OK",
        100 );
    }
    else {
      EXEC SQL ROLLBACK;
      SetFieldText( ulldemo1HelloField,
        "SQL UPDATE failed",
        100 );
    }
    FrmDrawForm ( frmP );
    SysTaskDelay( 1 * SysTicksPerSecond() );
    ULPalmExit( &sqlca,
      UL_TEXT( "ULLDemo1" ),
      ULPalmDBStream() );
  }
  return 0;

  /************************************************************
  PilotMain is name which must be used for the main entry point
    to a Palm application.
  sysAppLaunchCmdNormalLaunch is the launch code received
    when the application is started normally.
  ULPalmLaunch is an UltraLite library function which restores 
    the application state and processes the download stream
    prepared by HotSync.
  ULPalmDBStream is an UltraLite library function which defines a
    stream under the Palm Computing Platform suitable for HotSync.
  db_init is an UltraLite library function which initializes the
    UltraLite runtime library.
  FrmGotoForm is a Palm SDK function which loads a form.
  Ulldemo1Form is a constant defined in the header file
    ULLDemo1_res.h.
  EvtGetEvent is a Palm SDK function which returns the next
    available event.
  SysHandleEvent is a Palm SDK function which provides default
    behaviour for system events.
  MenuHandleEvent is a Palm SDK function which handles events
    for the current menu.
  AppHandleEvent is a local function which handles events
    specific to this application. 
  FrmDispatchEvent is a Palm SDK function which dispatches the
    event to the current form's event handler.
  SysTaskDelay is a Palm SDK function which puts the processor
    into doze mode for the specified number of ticks. 
  SysTicksPerSecond is a Palm SDK function which returns the
    number of ticks per second.
  ULPalmExit is an UltraLite library function which saves the
    application state of a Palm application and writes the
    upload stream for HotSync. 
  ************************************************************/

} // PilotMain


[Home] [Table of Contents] [Previous Section] [Next Section] [mail to: bcarter@bcarter.com]