Send database event

Command group Flag affected Reversible Execute on client Platform(s)
Apple events YES NO NO macOS

Syntax

Send database event {message (parameters)}

Messages

Does field exist
Get field type
Get field size
Set Field
Get field
Does table exist
Use table
Define Returns
Next
Previous
Insert
Delete
Update

Description

This command sends one of the database events to the current event recipient. The flag is set if the event is accepted by the recipient. These events let you send and receive data from other applications that contain fields and row/column database structures (tables; file class names, for Omnis), provided they implement the Database events. They use the standard terminology of "Table" where Omnis uses file classes.

You can run Omnis as a networked data server for any other application on the network and in this configuration would be Client/server.

Database events

The following tables show the Omnis event messages used with Send Database event. The name in the first column is the Apple term for the event. CRB is Current Record Buffer. RSN is Record Sequence Number.

General Database events

The following table shows the Omnis event messages used with Send Database event, and the parameters for each message. These general commands are used to interrogate or set values in a database. The last two columns show the results when Omnis is the target and when it is the source of the events.

Apple Event name Omnis Database command message Command parameters to send event Action when event received by Omnis Action when event sent by Omnis
Get Structure Get field type FieldName, ResultField Returns field type of FieldName to client Sets text in ResultField to be field type of FieldName
Does Object Exist Does field exist FieldName Returns Boolean (0 /1) if FieldName does not /does exist Sets Omnis flag to true / false if FieldName does / does not exist at the server
Get Data Get field FieldName, ResultField Returns value from CRB corresponding to FieldName Gets data from FieldName and return data into ResultField (CRB)
Set Data Set field Value, FieldName Sets data in Omnis CRB field 'FieldName' to be Value Sets the data of FieldName in the remote server to be Value
Get Data Size Get field size FieldName, ResultField Returns data size in bytes for FieldName Returns the data size of FieldName in bytes into ResultField

Record events

The following database events are used with complete Omnis records (records or rows in other applications). The Send Database event {Define Returns ('FIELD1','FIELD2','FIELD3' . . .)} allows Omnis to define fields as the source and destination of "Next", "Previous", "Insert" and "Update".

Apple Event name Omnis Database command message Database command parameters to send event Action when event received by Omnis Action when event sent by Omnis
Does Object Exist (none) N/A Returns true/false if RSN. N/A
Get Data Next and Previous ... Returns record with requested RSN (or nearest following/previous RSN) Returns next/ previous sequenced record into previously defined Omnis fields
Set Data Update ... Sets requested RSN to data specified. Sets server record with Omnis defined fields
Delete Element Delete record ... Deletes Omnis record with RSN specified by client. Delete record as defined by defined fields from server table.

Table events

A table is simply described as a collection of rows and columns in a database or spreadsheet. For Omnis, this equates to the combination of an Omnis file class and corresponding data file, and takes the name of the file class as a parameter. Omnis keeps a "table index" (record pointer) for the table currently in use for database events so record (row) operations can be performed.

The Send Database event{Use table ('TABLENAME')} command must be issued with a valid table name (file class name for Omnis) that will be used for all subsequent record (row) operations. This Omnis command sends the Does Object Exist event before setting the current active table to ensure that there is such a valid table, and also resets the "table index" to point to the first record in that table. Use Table may also be used to reset the table index to the first record in a table.

Apple Event name Omnis Database command message Database command parameters to send event Action when event received by Omnis Action when event sent by Omnis
Does Object Exist Does table exist TableName. (File class name when sent to Omnis) Returns Boolean (1/ 0) if TableName does/does not exist Sets Omnis flag to true / false if TableName does / does not exist at the server
New Element Insert ... Inserts Omnis record with values specified by event issued by client Adds record to server table with values defined by defined fields

Example

; Data Entry Example
; This set of methods shows how you can hande data entry remotely. Several pushbuttons are
; put on the local window to mimic the standard Omnis buttons, with methods behind them to
; handle data entry in the server library with file class 'f2'.
; The following commads are demonstrated:
Send database event {Define Returns ('source1')}
Send database event {Use table ('thatFormat')}
Send database event {Insert}
Send database event {Previous}
Send database event {Next}
Send database event {Update}
; define class variable cEditType of type Short Integer (0 to 255)
Set main file {f2}
Send database event {Define Returns ('iCol1','iCol2')}
; define local fields for values from table f2
Send database event {Use table ('f2')}
; $control ;; window control method
On evOK
  If cEditType=1
    Send database event {Insert}
  Else If cEditType=2
    Send database event {Update}
  End If
  Calculate cEditType as 0
 If len(iCol1)=0
    Do $cwind.$objs.Field1.$enabled.$assign(kTrue)
    Do $cwind.$objs.Field2.$enabled.$assign(kTrue)
  Else
    Do $cwind.$objs.Field1.$enabled.$assign(kFalse)
    Do $cwind.$objs.Field2.$enabled.$assign(kFalse)
  End If
Do $cwind.$objs.Field1.$redraw()
  Do $cwind.$objs.Field2.$redraw()
; The following methods run behind pushbuttons
; Example of 'Next' pushbutton
On evClick
  Send database event {Next}
  Do $cwind.$redraw()
  If flag false
    OK message {No more records}
  End If
  Quit event handler
; Example of Insert pushbutton
On evClick
  Calculate cEditType as 1
  Calculate iCol1 as ''
  Calculate iCol2 as ''
  Do $cwind.$redraw()
  Enter data
  Quit event handler
; The following example prompts for a recipient library and then changes the value of a field; in the current record buffer
; The following commands are demonstrated
Send database event {Does field exist ('fieldname')}
Send database event {Set Field ('myfieldName','yourField')}
; declare local variable lTemp of type Character
On evClick
  Calculate lTemp as 'Not Known'
  Prompt for event recipient {Betas}
  Send database event {Does field exist ('iContact')}
  If flag true
    OK message {Contact Name [iContact] found; Press OK to change to 'Not Known'}
  Else
    OK message {Sorry, cannot find Contact; quitting method}
    Quit method
  End If

  Send database event {Set Field ('iContact',lTemp)}
  If flag true
    OK message {Contact now changed to [lTemp]}
  Else
    OK message {Failed to set remote field}
  End If
  Quit event handler
; The following additional commads are shown:
Send database event {Does table exist ('fileClass')}
Send database event {Get field ('yourField','myField')}
  Send database event {Does table exist ('Beta Sites')}
If flag false
  OK message {Sorry, 'Beta Sites not found'}
Else
  ; note use of quotes around local variable lTemp
  Send database event {Get field ('Co_Name','lTemp')}
  OK message {Returned value is [lTemp]}
End If
; The following method fragments demonstrate two further commands:
Send database event {Get field size ('fieldName','fieldsize')}
Send database event {Get field type ('fieldName','datatype')}
; declare local variables lDataSize and lDataType both of type Character
Send database event {Get field size ('charField','lDataSize')}
OK message {Field 'charField' has room for [lDataSize] characters}
Send database event {Get field type ('charField','lDataType')}
OK message {Field 'charField' is of type [lDataType]}
; Finally the Current record Buffer is deleted by
Send database event {Delete}
; Example of 'Delete' pushbutton
On evClick
  OK message {Are you sure you want to delete the current record?}
  If flag true
    Send database event {Delete}
    If flag true
      OK message {Current record deleted}
    Else
      OK message {Delete event not accepted}
    End If
  End If
  Quit event handler