Developing with SQLWindows : Messages

Messages
This chapter explains:
About messages
SQLWindows sends a message to an object when an event happens. An application processes a message by taking an action.
Messages drive a SQLWindows application. Actions are associated with objects (such as dialog boxes, push buttons, and check boxes). At runtime, actions execute based on the messages that the objects receive.
Messages are triggered by:
Types of messages
There are three types of messages:
Message names and numbers
Messages are identified by a name and number. The message name is a constant that represents the message number. You can refer to a message by its name or its number. Use message names, not numbers.
About SAM_* messages
SAM events
Examples of events that cause SAM_* messages are:
Where SQLWindows sends SAM_* messages
SQLWindows sends messages to all objects, except for background text, group boxes, lines, and frames. SQLWindows also sends messages to the Application Actions section of the outline.
Not all messages are sent to all types of windows. For example:
For a complete list of the SAM_* messages that each object receives, read SAM_* summary on page 9-44
Application-defined messages
The application itself can also send messages to its objects or to other applications by calling SalSendMsg, SalPostMsg, and SalSendMsgToChildren.
Messages can be posted or sent:
Posted (queued) messages are placed in an application's message queue. If there are other messages in the application's queue, the object does not receive the message until the application processes the messages ahead of it.
Sent (nonqueued) messages are sent to an object directly. You send a nonqueued message when you want the application to do something immediately.
SalPostMsg queues the message and returns immediately. SalSendMsg sends the message directly to an object and returns only after the receiver processes the message.
For more about these functions, read the SQLWindows Function Reference or the online help.
Define values for application-defined messages in the User part of Constants in Global Declarations. Constants you define with the PM_* or PAM_* prefix appear automatically in Coding Assistant. (“PM” means Program Message and “PAM” means Program Application Message.)
Constants that you define for messages must be greater than the SAM_User constant. Define message constants like this:
Global Declarations
System
...
User
Number: PAM_Ok = SAM_User + 2
Number: PAM_Cancel = SAM_User + 4
Microsoft Windows messages
Microsoft Windows messages are defined in WINDOWS.H. These messages have a WM_ prefix, such as WM_Close or WM_Paint. You can process these messages in SQLWindows applications; to do this, you need a Microsoft Windows development tool.
Define values for Windows messages in the System part of Constants in Global Declarations. Constants you define with the WM_* prefix appear automatically in Coding Assistant.
Processing messages
Most objects have a Message Actions section where you code statements to process messages. For example, a SAM_Validate message—sent when the user changes a value in a field and then clicks or tabs out of it—can invoke field validation actions in the Message Actions section under an On SAM_Validate statement.
An event can cause several messages to be sent, but not all of them are relevant to an application. For example, when the user moves the input focus after editing a data field or table window column, SAM_Validate, SAM_KillFocus, and SAM_SetFocus are all sent, although an application does not process all of them.
You code On statements in the Application Actions section and in Message Actions sections.
The statements under an On statement process a message. The example below shows how the On statement processes the SAM_Click message in the Message Actions section of a push button. Each time the user clicks the push button, the actions under SAM_Click execute:
Data Field: df1
...
Pushbutton: pb1
...
Message Actions
On SAM_Click
Set df1= ’Hello World’
For more about the On statement, read On on page 7-23
For some SAM_* messages, SQLWindows expects you to Return a value to control processing. After executing a Return statement, message processing ends. In other words, SQLWindows ignores any statements after a Return statement.
System variables
You use these system variables to process messages:
hWndForm
This system variable contains the handle of the top-level window (form window, dialog box, or table window) that received the message.
You can use this variable to pass a window handle to a function.
hWndItem
This system variable contains the handle of the child object that received the message. For example, when an application processes the SAM_Click message for a push button, hWndItem contains the handle of the push button.
You can use this variable to pass a window handle to a function.
wParam and lParam
These system variables are used by some SAM messages. You use these variables as defined by the message. Some messages do not use the wParam and lParam variables.
SAM reference
The sections on the following pages describe each SAM_* message.
SAM_Activate
Sent to
Top-level windows and MDI windows
Event
When the window is activated or deactivated. The wParam indicates whether the window is being activated or deactivated.
Message Variables
TRUE = Activated
FALSE = Deactivated
Example
None
SAM_AnyEdit
Sent to
Data field, combo box, multiline field, and table window column
Event
The user changes the field's value. For example, an editable data field receives one SAM_AnyEdit message for each keystroke as the user enters data.
Processing
Check the value of the field as the user enters it.
Message Variables
For a data field or multiline field:
For a column of a table window:
Example
 
Data Field: dfCompanyId
...
Message Actions
On SAM_AnyEdit
! Check if last character the user entered is a valid number.
! If not valid, strip it off and let user re-enter the character.
If SalIsValidInteger( dfCompanyId ) = FALSE
! StripLastCharacter is an internal function that
! discards any invalid characters that the user entered.
Call StripLastCharacter( dfCompanyId )
SAM_AppExit
Sent to
Application Actions section of the outline
Event
After all of the application's windows have been destroyed (closed).
When the user exits an application or you go from user mode to design mode, the application's form windows, table windows, and dialog boxes are destroyed. After the windows are destroyed, SQLWindows sends SAM_AppExit.
This is the last message SQLWindows sends to an application.
Processing
Perform cleanup tasks such as disconnecting from the database.
Important: SQLWindows sends SAM_AppExit after destroying all windows. Do not refer to windows in the message processing statements.
Message Variables
Example
Application Actions
On SAM_AppExit
! Leaving application. Disconnect Sql Handle.
Call SqlDisconnect( hSql )
SAM_AppStartup
Sent to
Application Actions section of the outline
Event
Before the application's windows are created, including those created automatically at runtime.
This is the first message SQLWindows sends to an application.
Processing
Perform initialization tasks such as displaying a dialog box where the user logs on to a database.
Message Variables
Example
Application Actions
On SAM_AppStartup
Set SqlDatabase = 'CLIENTS'
Set SqlUser = 'SYSADM'
Set SqlPassword = 'SYSADM'
When SqlError
Call SalMessageBox( 'Could not connect to database',
'Customer List', MB_Ok )
Return FALSE
If NOT SqlConnect( hSql )
Call SalQuit
SAM_CacheFull
Sent to
Table window
A table window receives SAM_CacheFull when a user scrolls if Maximum Rows in Memory is less than the number of rows to display and Discardable is No. The minimum value for rows in memory is 78, regardless of the setting of Maximum Rows in Memory.
Event
A row is to be fetched, but the table window cache is full and no rows can be discarded.
Processing
The meaning of SAM_CacheFull depends on whether the table window has a discardable cache:
If the cache is discardable, SAM_CacheFull means that there are too many rows of modified data and that they must be saved
Message Variables
Example
Table Window: twTabWinEmployee
...
Message Actions
On SAM_CacheFull
! Cache is full! User cannot change any more rows in
! the table window.
Call SalMessageBox(
'Please save changes to Table Window.',
'Customer List', MN_Ok | MB_IconHand )
Return FALSE
SAM_CaptionDoubleClick
Sent to
Table window and column
Event
The user double-clicks a column title.
Processing
Retrieve the window handle of the column in the wParam with SalNumberToWindowHandle.
Message Variables
For a table window:
For a column:
Example
 
Table Window: tbl1
...
Message Actions
On SAM_CaptionDoubleClick
Set hWndCol = SalNumberToWindowHandle( wParam )
Call SalTblSetColumnFlags( hWndCol, COL_Selected, TRUE )
Set nMaxLength = 15
Set nColLength = SalTblGetColumnTitle( hWndCol, sColTitle, nMaxLength )
Call SalMessageBox( 'You double-clicked the title ' || sColTitle,
'Info', MB_Ok )
Call SalTblSetColumnFlags( hWndCol, COL_Selected, FALSE )
SAM_Click
Sent to
Table window, table window column, push button, radio button, check box, option button, combo box, list box, and picture
Table Windows and Columns
SQLWindows sends SAM_Click to both the table window and to the column. If a user clicks an editable column, SQLWindows also sends SAM_SetFocus.
SQLWindows sends SAM_Click to a table window when a user double-clicks it. If a user double-clicks a non-editable column, both the table window and the column receive two SAM_Click messages and one SAM_DoubleClick message.
List Box
SQLWindows sends SAM_Click to a list box when a user:
Clicks an entry, even if the list box entry is already selected
SQLWindows does not send SAM_Click when a user clicks:
Combo Box
SQLWindows sends SAM_Click to a combo box when a user clicks an entry in the list box, even if the entry is already selected. SQLWindows does not send SAM_Click to a combo box when a user clicks the:
Radio Button
SQLWindows sends SAM_Click to a currently-unselected radio button when a user clicks it. If the radio button is already selected, SQLWindows does not send SAM_Click.
Event
The user clicks the object with the mouse or performs a keyboard action (such as pressing an arrow key) that simulates a mouse click.
Message Variables
For a table window or table window column:
For a picture:
For a push button, radio button, list box, option button, or combo box:
Example
 
Pushbutton: pbAddNewCustomer
...
Message Actions
On SAM_Click
! Push button to add a new customer to the database
Call SqlImmediate( 'INSERT INTO company (name,address,phone )
VALUES ( :CompanyName, :CompanyAddress, :PhoneNumber ) ' )
Call SalMessageBox( 'Customer has been added!', ’Customer List', MB_Ok )
SAM_Close
Sent to
Form window, dialog box, top-level table window, and MDI window
Event
The user chooses the Close command from the window's system menu or double-clicks the window's system menu.
A form window, dialog box, or top-level table window receives SAM_Close when the user closes it with the Close item in the system menu. A child table window does not receive SAM_Close.
SQLWindows does not send SAM_Close when you call SalQuit, SalEndDialog, or SalDestroyWindow.
Processing
Warn the user or perform other tasks. For example, check a form window or table window to see if there is data that needs to be saved in a database.
Call SalMessageBox when a modal or system modal dialog box receives SAM_Close to prevent a user from accidentally closing the dialog box. Default processing closes the dialog box.
If a user selects the Close menu item in a dialog box’s system menu and the application does not process SAM_Close, SQLWindows implicitly calls SalEndDialog( hWnd, 0 ).
Message Variables
Example
 
Dialog Box: dlgEmployees
...
Contents
Data Field: dfCompanyName
...
Message Actions
On SAM_Close
Set nRetValue = SalMessageBox(
'Are you sure you want to close this window?',
'Customer List', MB_YesNo )
If nRetValue = IDNO
! Return FALSE to prevent the window from being destroyed
Return FALSE
SAM_ColumnSelectClick
Sent to
Table window and column
Event
The user selects or deselects a column by clicking the column title.
To receive this message, you must set TBL_Flag_SelectableCols to TRUE by calling SalTblSetTableFlags (it is FALSE by default).
Processing
Retrieve the window handle of the column in wParam with SalNumberToWindowHandle.
Message Variables
Example
 
Table Window: tbl1
...
Message Actions
On SAM_ColumnSelectClick
Set hWndCol = SalNumberToWindowHandle( wParam )
Set nMaxLength = 15
Set nColLength = SalTblGetColumnTitle( hWndCol, sColTitle, nMaxLength )
Call SalMessageBox( 'You selected the title ' || sColTitle,
'Info' , MB_Ok )
SAM_ContextMenu
Sent to
Window
Event
The user right-clicks a top-level or child window, or presses Shift+F10. Note: Most applications do not need to process this message. Instead, call SalContextMenuSetPopup to define a popup menu that displays automatically when a window receives SAM_ContextMenu.
Process this message by calling SalTrackPopupMenu to display a popup menu. Use the TPM_ContextMenu flag with SalTrackPopupMenu for this purpose.
Message Variable
No Example
 
SAM_CornerClick
Sent to
Table window
Event
The user clicks the title of a row header. The row header is a non-editable column on the left side of a table window.
Message Variable
Example
 
Table Window: tbl1
...
Message Actions
On SAM_CornerClick
Set nContextRowLength = SalNumberToStr( lParam, 0, sContextRow )
Call SalMessageBox( 'You clicked the row header title context row: ' ||
sContextRow ,'Info' , MB_Ok )
SAM_CornerDoubleClick
Sent to
Table window
Event
The user double-clicks the title of a row header. The row header is a non-editable column on the left side of a table window.
Message Variables
Example
 
Table Window: tbl1
...
Message Actions
On SAM_CornerDoubleClick
Set nContextRowLength = SalNumberToStr( lParam, 0, sContextRow )
Call SalMessageBox(
'You doubled-clicked the row header title context row: ' ||
sContextRow ,'Info' , MB_Ok )
SAM_CountRows
Sent to
A table window with a dynamic scroll range
Event
The user scrolls to the last row in a table window (such as by pressing the End key).
Processing
Return the number of rows in the table window. For example, count the number of rows in the result set.
If the application does not process this message, SAM_FetchRow messages are used to determine the last row in the table with a TBL_NoMoreRows return from the message. However, the application performs better if you process SAM_CountRows.
Message Variables
Example
Table Window: tblEmployee
...
Message Actions
On SAM_Create
Call SqlPrepare( hSqlPrimary, strSqlTableWindow )
Call SqlExecute( hSqlPrimary )
Call SalTblReset( hWndForm )
Call SalTblSetRange( hWndForm, 0, TBL_MaxRow )
On SAM_CountRows
! Count the number of rows in the result set.
Call SqlGetResultSetCount( hSqlPrimary, nRowCount )
Return nRowCount
SAM_Create
Sent to
Top-level window and its children; MDI window
Event
After the top-level window and its children have been created, but before the windows are made visible.
For example, SQLWindows follow these steps to create a form window that has data fields:
1.
2.
After SQLWindows creates all the windows, but before making them visible, SQLWindows sends SAM_Create to the objects in this order:
1.
2.
After SQLWindows sends the SAM_Create messages, SQLWindows makes the form window and data fields visible.
Processing
Perform initialization tasks such as setting data fields or populating table windows and list boxes with data from a database.
Message Variables
Example
Data Field: dfCompanyName
...
Message Actions
On SAM_Create
! Fill company name data field when window is created
Set dfCompanyName = 'Gupta Technologies LLC'
SAM_CreateComplete
Sent to
Windows with contents: top-level windows and child table windows
Event
After creating the window’s children and displaying the window and its children.
Processing
Perform initialization tasks such as setting data fields or populating table windows and list boxes with data from a database.
Message Variables
Example
None
SAM_CustControlCmd
Sent to
Custom control
Event
When the parent window receives a notification message (WM_COMMAND) from the custom control.
Processing
SQLWindows ignores any value that you Return when you process this message.
Message Variables
Example
None
SAM_Destroy
Sent to
Top-level window and its children; MDI window
Event
Just before the windows are destroyed.
SQLWindows sends SAM_Destroy messages after sending SAM_Close to the top-level window. For example, if a form window has data fields, SQLWindows sends the messages to the objects in this order:
1.
2. SAM_Destroy to the form window
3. SAM_Destroy to each of the form window's child windows
After sending the SAM_Destroy messages, SQLWindows destroys the top-level window and child windows.
Message Variables
Example
Table Window: twTabWinEmployee
...
Message Actions
On SAM_Destroy
! Set a global Boolean variable informing the
! application this window is no longer active
Set bEmployeeWinDestroyed = TRUE
SAM_Dock
Sent to
MDI window, form window, top-level table window
Event
Sent to a top-level window just before a child dialog box changes its current docking orientation to the parent window. This message precedes SAM_DockChange, which is sent to the dialog box.
Processing
None.
Message Variables
Contains two items. The low-order word of lParam contains the dialog’s current docking status/orientation and the high-order word of lParam contains the new docking status/orientation.
 
See also
For detailed discussions of docking capabilities and orientations, read the SQLWindows Function Reference manual, referring to functions SalDlgSetDockStatus and SalWindowGet DockSettings. Also read about the docking attributes of top-level windows in Chapter 5, SQLWindows Objects.
 
SAM_DockChange
Sent to
Dialog box
Event
This message is only sent to a dialog box if that dialog box has attribute "docking enabled" TRUE. Sent to a dialog box after a docking change orientation is completed.
Processing
Does not apply. Returning FALSE or TRUE will have no effect.
Message Variables
Contains two items. The low-order word of lParam contains the current docking status/orientation and the high-order word of lParam contains the new docking status/orientation.
 
Note: When processing the actions of this message, do not call SalModalDialog or SalSetWindowSize. Calls to these functions will cause an event loop that will freeze your application.
See also
For detailed discussions of docking capabilities and orientations, read the SQLWindows Function Reference manual, referring to functions SalDlgSetDockStatus and SalWindowGetDockSettings. Also read about the docking attributes of top-level windows in Chapter 5, SQLWindows Objects.
SAM_DockResize
Sent to
A dockable dialog box or dockable toolbar
Event
SAM_DockResize is sent to a dockable dialog box or toolbar when it is changing its docking orientation, or when it is about to be resized programmatically or through user action. This message gives the developer an opportunity to request a specific size for the object.
This message is only sent to dialog boxes or toolbars that have the Docking Enabled attribute set to Yes.
Message Variables
The size of the object prior to resizing. The low-order word contains the width in pixels, and the high-order word contains the height in pixels.
The proposed size of the object after resizing. The low-order word contains the width in pixels, and the high-order word contains the height in pixels.
 
Return value
None: Resizing will continue as proposed.
True (1): Resizing will continue as proposed.
False (0): Resizing is negotiated, using the last value for size when the object was in a floated state.
Positive number greater than 1: Resizing is negotiated, using the return value. In that value, the low-order word contains the requested width in pixels, and the high-order word contains the requested height in pixels. Function VisNumberMakeLong is helpful in constructing such a value.
Negotiating object sizes
Negotiation does not guarantee that the size you requested will be granted. There may be competing requests for space from other objects that are located inside the same dock bar as the object you wish to resize. For example, it’s common for two or more toolbars to share the same dock bar. There may also be other dock bars active in the parent window, with other objects inside them.
All of the docked objects in a dock-bar share the same height. If two objects request different heights in a dock bar the bar sizes itself to fit the larger of the requests. (Height refers to the vertical dimension if the dock bar is on the top or bottom edge of the parent window, and the horizontal dimension if the dock bar is on the left or right edge of the parent window.)
When a size is requested for a given width the dock bar must fit all of the objects’ widths in the row. If the dock bar does not have enough space to honor the all of the requests for widths (plus other non-requesting dockable object widths) the requesting windows are given priority when the hosting dock bar is divided up. All non-size-requesting windows are first minimized and if there is still not enough to honor all of the requested space then each object is given a percentage of the space they requested. That is, if there is available only 75% of the total space requested then each object will only get 75% of the space they requested. For example, a dialog that requested 100 pixels will get 75 and a dialog that requested 200 pixels will get 150.
Cautions when calling functions within SAM_DockResize
Some SAL functions related to window layout will fail (return FALSE) when called from within the context of this message. This is to be expeected, because an ongoing window layout is already in progress and has not yet completed. Such functions include:
SalSetWindowLoc
SallDlgSetStatus
SalGetWindowLoc
SalMoveWindow
SalSetWindowSize
See also
See also
SAM_DockResizeNotify
SAM_DockResizeNotify
Sent to
A dockable dialog box or dockable toolbar.
Event
SAM_DockResizeNotify is sent to a docking dialog box or toolbar when it has finished resizing itself in response to changes in its docking orientation, or in response to resizing programmatically or through user action. This message gives the developer an opportunity to make changes to the contents of the dialog box or toolbar to compensate for the new object size.
This message is only sent to dialog boxes or toolbars that have the Docking Enabled attribute set to Yes.
Message Variables
The size of the object prior to resizing. The low-order word contains the width in pixels, and the high-order word contains the height in pixels.
The proposed size of the object after resizing. The low-order word contains the width in pixels, and the high-order word contains the height in pixels.
 
Return value
The return value is ignored.
Cautions when calling functions within SAM_DockResizeNotify
Some SAL functions that deal with window layout should be used with care from within the context of this message, because of the risk of creating an endless loop of events. They include:
SalDlgSetDockStatus
SalSetWindowLoc
SalSetWindowSize
SalHideWindow
SalShowWindow
As mentioned in the documentation for SAM_DockResize, there are sometimes competing demands for space in dock bars that contain multiple objects, and an object may get assigned a smaller size than it requested. If, for example, your code tries to insure that an object always has at least a minimum width, you may set off another resizing event, ending with your object again not getting its requested size due to negotiation, resulting in another SAM_DockResizeNotify message, thus causing an endless loop.
See also
See also
SalNumberHigh
SalNumberLow
SAM_DockResize
SAM_DoubleClick
Sent to
List box, combo box, table window, column, and picture
SQLWindows only sends SAM_DoubleClick to a combo box when you set its Always Show List property to Yes in the Attribute Inspector.
Event
The user double-clicks the object.
When the user double-clicks a row in a table window or list box, SQLWindows sends the messages in this order:
1.
2.
3.
Processing
A double-click can select a row in a list box or table window and then start an action for that row. For example, a list box can contain a list of file names. When the user double-clicks a name in the list box, the application opens the file.
Message Variables
For a combo box and list box:
For a table window:
For a table window column:
For a picture:
Example
 
List Box: lbEmployee
...
Message Actions
On SAM_DoubleClick
! When user double-clicks a row, get the index of that
! row and put row text in dfEmployeeName
Set nIndex = SalListQuerySelection( lbEmployee )
Call SalListQueryText( lbEmployee, nIndex, dfEmployeeName )
SAM_DragCanAutoStart
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
SQLWindows sends this message to ask a window whether it wants auto dragging.
Processing
Return TRUE to enable auto dragging. If you do not process this message or you return FALSE, then SQLWindows does not enable auto dragging.
SQLWindows starts drag mode automatically when the application returns TRUE from SAM_DragCanAutoStart. This is the minimum that an application does to let a user drag from a window. However, you must write additional code to do something when the user drops in a window.
Message Variables
Example
List Box: lb1
...
Message Actions
On SAM_DragCanAutoStart
If SalListQuerySelection( hWndItem ) != LB_Err
Return TRUE
Else
Return FALSE
SAM_DragDrop
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
The user drops the mouse on a target window.
Message Variables
Example
Data Field: df1
...
Message Actions
On SAM_DragDrop
Set hWndSrc = SalNumberToWindowHandle( wParam )
If hWndSrc != hWndItem
AND SalParentWindow( hWndSrc ) = hWndForm
Call SalGetWindowText( hWndSrc, sSource, 1000 )
Call SalSetWindowText( hWndItem, sSource )
SAM_DragEnd
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
Drag mode has ended.
Message Variables
Example
None
SAM_DragEnter
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
The user moved the mouse into this target window while in drag mode.
Processing
Change the mouse pointer to an appropriate symbol.
Message Variables
Example
None
SAM_DragExit
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
The user moved the mouse out of this target window while in drag mode.
Message Variables
Example
None
SAM_DragMove
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
The user moved the mouse within this target window while in drag mode.
Message Variables
Example
None
SAM_DragNotify
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
A mouse action happened in drag mode.
Message Variables
SAM_DragEnter The user moved the mouse into a target window
SAM_DragDrop The user dropped the mouse in a target window
SAM_DragExit The user moved the mouse out of a target window
SAM_DragMove The user moved the mouse within a target window
Example
 
Global Declarations
...
Class Definitions
Picture Class: clsDragPict
...
Message Actions
On SAM_DragNotify
Set hWndTarget = SalNumberToWindowHandle( wParam )
Select Case lParam
Case SAM_DragEnter
If SalGetType( hWndTarget ) = TYPE_Picture
Call SalDragDropEnableDrop( )
Else
Call SalDragDropDisableDrop( )
Break
Case SAM_DragDrop
If hWndTarget != hWndItem AND
SalGetType( hWndTarget ) = TYPE_Picture
Set nColorSource =
SalColorGet( hWndItem, COLOR_IndexWindow )
Set nColorTarget =
SalColorGet( hWndTarget, COLOR_IndexWindow )
Call SalColorSet( hWndTarget, COLOR_IndexWindow, nColorSource )
Call SalColorSet( hWndItem, COLOR_IndexWindow,nColorTarget )
Break
SAM_DragStart
Sent to
Top-level window, data field, multiline field, list box, combo box, and picture
Event
Drag mode has started.
Message Variables
Example
 
List Box: lb1
...
Message Actions
On SAM_DragStart
! Store the current selection as window text so we can
! use it on the drop
Call SalListQueryText( hWndItem, SalListQuerySelection( hWndItem ),
sList )
Call SalSetWindowText( hWndItem, sList )
SAM_DropDown
Sent to
Combo box
Event
The user clicks the down arrow. SQLWindows sends this message before the list box of the combo box drops down.
Message Variables
Example
None
SAM_DropFiles
Sent to
Column, data field, multiline field, list box, combo box, picture, and custom control
SQLWindows only sends this message to windows that have enabled file dropping.
Event
The user dropped a file or files from Explorer or File Manager on the object.
Processing
Call the SalDropFilesQueryFiles function to get the names of the files dropped on the object. SalDropFilesQueryFiles returns the number of files that were dropped or 0 if the function fails. You can only call SalDropFilesQueryFiles during SAM_DropFiles message processing.
Call the SalDropFilesQueryPoint function to get the location of the mouse in the window where the user dropped the file or files.
By default, file dropping is enabled for editable picture objects. To avoid this default processing, execute a Return statement in the SAM_DropFiles message processing for a picture object and do not perform any other processing. For example, when a user drops on a picture, you can call SalDropFilesQueryFiles or SalDropFilesQueryPoint in the SAM_DropFiles message processing and decide whether to process what the user is dropping or to ignore it by executing a Return statement with no other processing.
You can completely disable file dropping for an editable picture by calling the SalDropFilesAcceptFiles function. The default for editable picture windows is TRUE. The default for all other window types is FALSE.
Message Variables
Example
None
SAM_EndCellTab
Sent to
Table window
Event
The user tries to tab past the last editable cell.
Processing
You can use this message to automate row insertion. When the table window receives this message, add a blank row.
By default, if you do not explicitly return a value, SQLWindows returns FALSE and selects the row. Return TRUE to prevent this behavior.
Message Variables
Example
 
On SAM_EndCellTab
If IDYES = SalMessageBox( ’Move to next row?’,
’What Do You Want to Do?’,
MB_IconQuestion | MB_YesNo )
Set nNewRow = SalTblInsertRow( hWndTbl, TBL_MaxRow )
Call SalTblSetFocusCell( hWndTbl, nNewRow, col1, 0, 0 )
Return TRUE
Else
! Null leg:
! If we don’t explicitly return a value, SQLWindows returns
! FALSE and selects the current row.
SAM_FetchDone
Sent to
Table window
Event
SalTblPopulate, using the TBL_FillAllBackground population method, has completed populating the table window.
Message Variables
Example
None
SAM_FetchRow
Sent to
Table window
Event
Before a row must be copied into the table window cache. When you populate a table window, SQLWindows sends SAM_FetchRow for every row in the table window that needs to be displayed. When the user scrolls the table window, SQLWindows sends more SAM_FetchRow messages to the table window for rows not in the cache that need to be displayed.
Note: SQLWindows sends SAM_FetchRow before populating the row and SAM_FetchRowDone after populating the row.
Processing
You usually call SqlFetchRow to fetch the row into the table window based on the row number in lParam.
Note: Setting a breakpoint on a statement that executes while processing SAM_FetchRow can cause incomplete painting of a table window.
Return a value based on the fetch result:
Message Variables
Example
Table Window: twTabWinEmployee
...
Message Actions
On SAM_FetchRow
! The table window needs a row from the database
If SqlFetchRow( hSql, lParam, nFetch )
If nFetch = FETCH_Delete
Return TBL_RowDeleted
Else
Return TBL_RowFetched
Else
Return TBL_NoMoreRows
SAM_FetchRowDone
Sent to
Table window
Event
After SQLWindows has populated a row.
Note: SQLWindows sends SAM_FetchRow before populating the row and SAM_FetchRowDone after populating the row.
Processing
SQLWindows ignores any value you return.
Message Variables
Example
None
SAM_FieldEdit
Important: Use SAM_Validate instead of SAM_FieldEdit. SAM_FieldEdit is provided for compatibility with earlier SQLWindows versions.
Sent to
A table window, column, data field, combo box, and multiline field
Event
The user changes the value and then moves the focus away from the item. For example, if a user enters a value in a data field and then presses the Tab key or clicks the mouse to move to another field, SQLWindows sends SAM_FieldEdit to the data field.
Processing
SAM_FieldEdit is different from SAM_AnyEdit:
SAM_AnyEdit is sent for every change that the user makes to an object
SAM_FieldEdit is sent once when the user tries to leave an object that has been changed
Message Variables
For a data field or multiline field:
For a table window column:
Example
None
SAM_Help
Sent to
Top-level window and MDI window
Event
The user pressed the F1 key.
Processing
Call SalWinHelp to start an application help system that you created. The wParam contains the handle of the child object that has the focus that you can use for a context-sensitive help system.
Message Variables
Example
None
SAM_KillFocus
Sent to
Table window, data field, multiline field, push button, radio button, check box, option button, combo box, list box, column, and horizontal and vertical scroll bar
When the focus changes, SQLWindows first sends SAM_KillFocus to the object losing the focus and then sends SAM_SetFocus to the object getting the focus.
For focus changes in table windows:
The wParam of SAM_KillFocus is the window handle of the column getting the focus and the lParam is the row number getting the focus
The wParam of SAM_SetFocus is the window handle of the column losing the focus and the lParam is the row number losing the focus
Event
As the user moves the focus off an object.
SQLWindows sends this message whether or not the used changed data in the object.
Processing
Warning: You cannot call SalSetFocus in SAM_KillFocus processing because of a Windows limitation.
Message Variables
Example
Data Field: dfHireDate
...
Message Actions
On SAM_KillFocus
! When user exits this data field, disable push button
! pbPartialSearch
Call SalDisableWindow( pbPartialSearch )
SAM_Print
Sent to
Form window, data field, multiline field, combo box, and push button
Event
SQLWindows is printing the object.
Processing
Some applications supplement window painting by drawing on the display. To perform the same drawing when printing an object, call SalPrtExtractRect to draw on the object that is printing.
SQLWindows does not have window painting functions. You must define the Windows DLL GDI32.EXE as an external library and call its functions.
Message Variables
Example
This example draws a diagonal line when a form window is printing. The MoveTo and LineTo functions are in the DLL GDI.EXE.
On SAM_Print
Call SalPrtExtractRect( hWndForm, lParam, nLeft, nTop, nRight, nBottom )
Call MoveTo( wParam, nLeft, nTop )
Call LineTo( wParam, nRight, nBottom )
SAM_ReportFetchInit
Sent to
Top-level window or MDI window that started a report
Event
When Report SQLWindows is ready to format the first page of a report. Report SQLWindows sends SAM_ReportFetchInit after sending SAM_ReportStart.
SAM_ReportFetchInit means that Report SQLWindows is ready to receive data from the application.
Processing
If the report contains data from a database, call SqlExecute. If SqlExecute returns TRUE, then Return TRUE.
If you Return FALSE, the report stops. If you do not Return a value, or you do not process the message, the report continues.
Message Variables
Example
Form Window: frmMain
...
Message Actions
On SAM_ReportFetchInit
If NOT SqlPrepare( hSql, SQL_Select )
Return FALSE
Else
If NOT SqlExecute( hSql )
Return FALSE
Else
Return TRUE
SAM_ReportFetchNext
Sent to
Top-level window or MDI window that started a report
Event
When Report SQLWindows is ready for the next row of data from the application. Report Builder sends SAM_ReportFetchNext after SAM_ReportFetchInit.
Processing
If an application fetches data from a database for a report, call SqlFetchNext to get the next row. If the fetch is successful, return TRUE. If there is no more data, return FALSE.
Message Variables
Example
Form Window: frmMainForm
...
Message Actions
On SAM_ReportFetchNext
! Get next row from database and
! send it to Report Builder
If SqlFetchNext( hSql, nRetVal )
Return TRUE
Else
Return FALSE
SAM_ReportFinish
Sent to
Top-level window or MDI window that started a report
Event
Report Builder sends SAM_ReportFinish when the report is finished.
Processing
Perform cleanup tasks.
Report Builder ignores any value you Return in SAM_ReportFinish processing.
Message Variables
Example
Form Window: frmMainForm
...
Message Actions
On SAM_ReportFinish
Call SqlDisconnect( hSql )
SAM_ReportNotify
Sent to
Top-level window or MDI window that started a report
Event
Report Builder is ready to format a part of a report.
Processing
Check the lParam to find the part of the report Report Builder is ready to format. For more, read RPT_Err* constants on page 14-8.
Report Builder ignores any value that you return during SAM_ReportNotify processing.
Message Variables
Example
This example checks the lParam to find if Report Builder is ready to process the first break header:
On SAM_ReportNotify
If lParam = RPT_BeforeBreakHeader1
! strPic contains an image. Set the report variable
! named PICTURE to the contents of strPic.
Call SalReportSetObjectVar( frmMain, 'PICTURE', strPic )
SAM_ReportStart
Sent to
Top-level window or MDI window that started a report
Event
Report Builder sends SAM_ReportStart after the application calls SalReportView or SalReportPrint. SAM_ReportStart means that the report is starting. Report Builder sends SAM_ReportStart before the report prints or displays.
Processing
Perform initialization tasks that are needed before the application can send data to Report Builder.
Report Builder ignores any value that the application returns.
Message Variables
Example
 
Form Window: frmMainForm
...
Message Actions
On SAM_ReportStart
! Prepare SQL statement for Report Builder
Call SqlPrepare( hSql, 'SELECT name, address, phone
from customer into :CompanyName, :Address, :phone' )
SAM_RowHeaderClick
Sent to
Table window
Event
The user clicks a row header.
SQLWindows only sends this message when TBL_RowHdr_Visible is TRUE (which is the default). If TBL_RowHdr_Visible is FALSE, you can set it to TRUE by calling SalTblDefineRowHeader.
Message Variables
Example
 
Table Window: tbl1
...
Message Actions
On SAM_RowHeaderClick
Set nContextRowLength = SalNumberToStr( lParam, 0, sContextRow )
Call SalMessageBox( 'You clicked the row header Context row: ' ||
sContextRow ,'Info' , MB_Ok )
SAM_RowHeaderDoubleClick
Sent to
Table window
Event
The user double-clicks a row header.
SQLWindows only sends this message when TBL_RowHdr_Visible is TRUE (which is the default). If TBL_RowHdr_Visible is FALSE, you can set it to TRUE by calling SalTblDefineRowHeader.
Message Variables
Example
 
Table Window: tbl1
...
Message Actions
On SAM_RowHeaderDoubleClick
Set nContextRowLength = SalNumberToStr( lParam, 0, sContextRow )
Call SalMessageBox( 'You double-clicked the row header Context row: ' ||
sContextRow ,'Info' , MB_Ok )
SAM_RowValidate
Sent to
Table window
Event
The user tries to move the focus off a row.
SQLWindows only sends this message when the user tries to change the row focus within the table window, not when the user moves the focus off the table window.
SQLWindows sends SAM_RowValidate regardless of the row flag and cell-edit flag settings.
Processing
Validate the contents of the row and return one of these values:
Message Variables
Example
Table Window: tbl1
...
Message Actions
On SAM_RowValidate
If SalIsNull( col1 )
Call SalMessageBox( 'You must enter a value',
'Validation Error', MB_Ok )
Return VALIDATE_Cancel
Else
Return VALIDATE_Ok
SAM_ScrollBar
Sent to
Horizontal and vertical scroll bar
Event
The user scrolls using the mouse or keyboard.
Processing
To find the scrolling action, check the wParam:
Scroll box moved to new position. Use SB_ThumbTrack when you want the client area updated each time the user drags the scroll box.
Important: Avoid processing SAM_ScrollBar when wParam is SB_ThumbTrack, since tracking is dynamic and can send many messages.
Message Variables
Example
Vertical Scroll Bar: sbScrollBar
...
Message Actions
On SAM_ScrollBar
! Show scroll bar position in data
! field 'dfScrollBarPos'
If wParam = SB_ThumbTrack
Set dfScrollBarPos = lParam
SAM_SessionError
Sent to
Application Actions section of the outline
Event
A SQL function fails within an OLE DB session.
This message is quite similar to SAM_SqlError, which is sent when a SQL function fails outside the scope of an OLE DB session.
Processing
Control how the application responds to SQL errors on a global level instead of using the default error processing which displays a dialog with the error number and error text.
Call SqlExtractArgs to get the error code, error position, and Session Handle from the wParam and lParam.
Message Variables
Handle of top-level window that executed the Sql* statement that failed except when code in applications actions calls a Sql* function and it fails when hWndForm is null (hWndNULL)
SAM_SetFocus
Sent to
Table window, data field, multiline field, push button, radio button, check box, option button, combo box, list box, column, and scroll bar
When the focus changes, SQLWindows first sends SAM_KillFocus to the object losing the focus and then sends SAM_SetFocus to the object getting the focus.
For focus changes in table windows:
The wParam of SAM_KillFocus is the window handle of the column getting the focus and the lParam is the row number getting the focus
The wParam of SAM_SetFocus is the window handle of the column losing the focus and the lParam is the row number losing the focus
Event
The user moves the focus to the object.
Processing
Start actions which take place when the user enters an object.
Important: Do not call functions that can change the focus (such as SalMessageBox, SalModalDialog, and SalSendMsg) while processing SAM_SetFocus.
Message Variables
Example
PushButton: pbPartialSearch
Data Field: dfDate
...
Message Actions
On SAM_SetFocus
! When user enters this field, enable push button
! pbPartialSearch
Call SalEnableWindow( pbPartialSearch )
SAM_SqlError
Sent to
Application Actions section of the outline
Event
A SQL function fails. Note that if the SQL function is called within the scope of an OLE DB session, message SAM_SessionError will be sent instead of SAM_SqlError.
Processing
Control how the application responds to SQL errors on a global level instead of using the default error processing which displays a dialog with the error number and error text.
Call SqlExtractArgs to get the error code, error position, and Sql Handle from the wParam and lParam.
You can also use When SqlError in any actions section of the outline to process an error at a local level. For more, read SQL error handling on page 12-17.
Message Variables
Example
 
The code below shows the SAM_SqlError processing in the Application Actions section. These statements are only executed when the When SqlError statements for local processing do not return a value:
SqlExtractArgs gets the error number (nErr).
SalNumberToStr converts nErr to a displayable string.
SqlGetErrorText gets the error message text for nErr.
The code displays a message box with the error number, error message, and a message saying to report the error. The user clicks the OK push button to quit the application.
The code returns a value to tell SQLWindows not to invoke the default error processing.
Application Actions
On SAM_SqlError
!
! If processing gets to here on a SQL error, there is
! little to do except report the error and gracefully quit
!
Call SqlExtractArgs( wParam, lParam, hSqlError, nErr, nPos )
Call SqlGetErrorText( nErr, strErrmsg )
Call SalNumberToStr( nErr, 0, strNum )
!
Call SalMessageBox( strNum || ' - ' || strErrmsg || '.
Please report to your system administrator.
Click OK to quit the application.',
'Database Error', MB_Ok | MB_IconStop )
!
! The Return statement tells SQLWindows **not** to invoke
! default error processing
!
Return FALSE
SAM_Timer
Sent to
Application Actions, top-level window and its children; MDI window
Event
Every n milliseconds, as specified by SalTimerSet.
Processing
Check the wParam to find the identifier of the timer that sent the message. This way, one object can process SAM_Timer messages from more than one timer.
Important: Timers are a limited resource in Windows, so use as few of them as possible.
Message Variables
Example
Form Window: frmMainForm
...
Contents
Data Field: dfDateTime
...
Message Actions
On SAM_Timer
! Use SalTimerSet to set timer to send SAM_Timer
! messages once every minute. Update time display
! on screen.
Set dtDateTime = SalDateCurrent( )
SAM_Validate
Sent to
Data field, multiline field, combo box, and column
Event
The user changes the value of the object and then moves the focus away from the object.
The user can move the focus by several actions such as tabbing to another object, clicking another object, or using a mnemonic or accelerator to activate another object.
When a user changes one of these objects, the object's field edit flag changes to TRUE. You can get and set the field edit flag using SalQueryFieldEdit and SalSetFieldEdit.
Processing
Validate the data that the user entered or changed.
Whenever the user changes an object, SQLWindows sends SAM_Validate. If an object is valid, return VALIDATE_Ok (this resets the field edit flag to FALSE).
The value you return from SAM_Validate processing controls whether the focus changes.
SQLWindows does not send SAM_Validate when the user selects a menu item (a menu selection does not change the focus). You can force SQLWindows to send SAM_Validate by calling SalSendValidateMsg in the menu actions of a menu item. This forces field validation before processing a menu selection (without changing the focus). SalSendValidateMsg returns the value that the SAM_Validate message processing returns.
To control the action that happens, return one of these values:
Does not let the attempted action take place and returns the focus to the current edited item if the item has lost the focus (validation failed).
Lets the attempted action take place. This is the default action if you do not process SAM_Validate or do not Return a value when processing SAM_Validate.
Note: Unless you return VALIDATE_Cancel, SQLWindows also sends SAM_FieldEdit to the object.
Message Variables
For a table window column:
Handle of column getting the focus; zero if the focus is not changing (such as when calling SalSendValidateMsg in menu actions)
For all other objects:
Handle of object getting the focus; zero if the focus is not changing (such as when calling SalSendValidateMsg in menu actions)
Example
Data Field: dfName
...
On SAM_Validate
If SalIsNull( dfName )
Call SalMessageBox( 'You must enter a value',
'Data Error', MB_Ok )
Return VALIDATE_Cancel
Else
Return VALIDATE_Ok
SAM_XMLRowDone
Sent to
Table window
Event
After SQLWindows has populated a row from an XML document.
Processing
SQLWindows ignores any value you return.
Message Variables
Example
None
SAM_* summary
In the table below:









Message
 
Developing with SQLWindows

Unify Corporation