Gupta Sqlwindows Function Reference

GUPTA SQLWindows Function Reference
20-6202-0003
Trademarks
GUPTA, SQLBase, SQLRouter, Team Developer, and SQLTalk are trademarks of Gupta Technologies, LLC registered in the United States and/or other countries. SQLWindows is a registered trademark of Microsoft Corporation, and is used under license to Gupta Technologies, LLC. Centura and Centura Software are registered trademarks of Centura Software Corporation, and are used under license to Gupta Technologies, LLC. Team Object Manager, Web Developer, QuickObjects, Object Nationalizer, Report Builder, Connectivity Administrator, Development Kit, Component Development Kit, SQLBase Resource Manager, and SQLConsole are names of products from Gupta Technologies, LLC. Adobe is a trademark of Adobe Systems, Incorporated. IBM, OS/2, NetBIOS, and AIX are registered trademarks of International Business Machines Corporation. Linux is a trademark of Linus Torvalds. Red Hat is a trademark of Red Hat, Incorporated. Novell and Netware are trademarks of Novell, Inc. SUSE is a trademark of SUSE LINUX AG. Java, JavaScript, and Solaris are trademarks of Sun Microsystems, Incorporated. Microsoft, Outlook, PowerPoint, Visual C++, Visual Studio, Internet Explorer, Internet Information Server, DOS, Win 32, Windows, ActiveX, MSDN, SQL Server, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States of America and/or other countries. Netscape FastTrack and Navigator are trademarks of Netscape Communications Corporation. All other product or service names mentioned herein are trademarks or registered trademarks of their respective owners.
Copyright
Copyright 1998 - 2005 by Gupta Technologies LLC. All rights reserved. GUPTA SQLWindows Function Reference 20-6202-0003 March 2005
SQLWindows/32 Function Reference
Preface
This Preface contains the following sections: Audience What is in this manual Typographical conventions Other helpful resources Send comments to...
-3
Preface
Audience
This manual is an advanced guide for programmers creating complex and sophisticated applications using SQLWindows.
What is in this manual

This manual is included with the Gupta Team Developer documentation set. This manual contains the following chapters: Chapter 1: SQLWindows Function Tables This chapter identifies function categories, provides a brief description of each category, and lists the functions in each category. Chapter 2: SQLWindows Functions This chapter is an alphabetical list of the SQLWindows functions accompanied by detailed information about each function's purpose, its parameters and return value, and an example.
Typographical conventions
Before you start using this manual, it is important to understand the typographical conventions we use in this manual: Formatting Convention bold type italic type Type of Information Menu items, push buttons, and field names. Things that you select. Keyboard keys that you press. Names of books and publications. Placeholders for items you must supply, such as file names. For example, when the manual says to type cd directory name you type the letters cd followed by a space and then the name of a directory. courier type Commands or code you must enter through the keyboard exactly as shown.
Note: We use this Note: convention to call your attention to special information.
-4
Other helpful resources

GUPTA Books Online. The GUPTA document suite is available online. This document collection lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the GUPTA Books Online icon from the Start menu or by double-clicking the launcher icon in the program group. Online Help. This is an extensive context-sensitive online help system. The online help offers a quick way to find information on topics including menu items, functions, messages, and objects. World Wide Web. Gupta Technologiess World Wide Web site contains information about Gupta Technologies LLCs partners, products, sales, support, training, and users. The URL is http://www.guptaworldwide.com. Our Web site is a valuable resource for customers with technical support issues, and addresses a variety of topics and services, including technical support case status, commonly asked questions, access to GUPTAs Online Newsgroups, links to Shareware tools, product bulletins, white papers, and downloadable product updates.
Send comments to...

If you have any comments or suggestions regarding GUPTA documentation, please send them to: Technical Publications Department Gupta Technologies LLC 975 Island Drive Redwood Shores, CA 94065 USA or send email, with comments or suggestions to: techpubs@guptaworldwide.com
-5
SQLWindows Function Reference
Chapter 1
SQLWindows Function Tables

The chapter contains functions tables that are arranged by type.
1-1
Chapter 1
SQLWindows function categories

SQLWindows functions are divided into categories. This section identifies and briefly describes each category in addition to listing the functions in each one. ActiveX client functions Anonymous block functions Array functions Color and font functions Data type conversion functions Date functions Debugging functions Dialog box functions DOS management functions Drag-drop functions Edit functions File management functions Format and validation functions List and combo box functions Manipulating background text functions MDI (Multiple Document Interface) functions Message functions Miscellaneous functions MTS functions Number functions OLE DB Consumer functions Picture functions Print functions Report functions Scroll bar functions SQL functions String conversion functions Table window functions Window management functions XML functions Note: Visual Toolchest functions (functions whose names begin with Vis) are not documented in detail in chapter 2. However, they are fully documented in the SQLWindows online help file.
1-2
ActiveX Client Functions

You can programmatically manipulate an ActiveX container control and its contents at runtime using these functions.
Function Name SalActiveXAutoErrorMode Description Turn off automatic error handling (on by default) by calling this function and specifying FALSE. Closes an object and ends the connection to the application that provided the object. Creates an object given its class descriptor (progID). Recreates an object from binary storage data, in the form of a string. Creates an instance of an ActiveX object. Deletes an instance of an ActiveX object. Opens an object for an operation such as editing. Gets an instance of an ActiveX object when the server application is already up and running. Gets the storage (state and data) associated with the object as a raw blob of bytes. Gets the file name of an ActiveX object that was inserted into a window using the SalActiveXInsertObjectDialog function and the Create from File option. Gives access to the automation dispatch interface of the object in the specified container. Gets the ProgID of an ActiveX object that was inserted into a window using the SalActiveXInsertObjectDialog function and the Create from File option. Displays the standard Insert Object dialog. Returns the status of the object in an ActiveX container control.
SalActiveXClose SalActiveXCreate SalActiveXCreateFromData SalActiveXCreateFromFile SalActiveXDelete SalActiveXDoVerb SalActiveXGetActiveObject
SalActiveXGetData SalActiveXGetFileName
SalActiveXGetObject
SalActiveXGetProgID
SalActiveXInsertObjectDialog SalActiveXOLEType
1-3
Chapter 1
Anonymous Block Functions

These functions have been introduced to provide support for anonymous PL/SQL blocks without changing the behavior of existing features.
Function Name SqlOraPLSQLPrepare Description Compiles the anonymous PL/SQL block. Resembles the regular SqlPrepare function, but the underlying code is meant specifically for handling Oracle PL/SQL blocks. Executes the anonymous PL/SQL block that was prepared using SqlOraPLSQLPrepare. Informs the Oracle router the specific type of the STRING array bind variable that is being used in the prepared anonymous PL/SQL block.
SqlOraPLSQLExecute SqlOraPLSQLStringBindType
Array Functions
These functions manage arrays and compute values.
Function Name SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum VisArrayAppend Description Gets the average of values in an array of numbers Gets the number of dimensions in nValue. Gets the lower bound of an array. Gets the upper bound of an array. Determines if a dynamic array contains any data. Gets the maximum value in an array of numbers. Gets the minimum value in an array of numbers. Sets the upper bound of an array. Computes the sum of an array's elements. Appends one array onto the end of another array.
1-4
Function Name VisArrayCopy VisArrayDeleteItem VisArrayFillDateTime VisArrayFillNumber VisArrayFillString VisArrayFindDateTime VisArrayFindNumber VisArrayFindString VisArrayInsertItem VisArraySort
Description Copies one array into another. Deletes an item from an array. Fills a Date/Time array with a specified date/ time value. Fills a number array with a specified value. Fills a string array with a specified string. Locates a date/time value within an array. Locates a number within an array. Locates a string within an array. Inserts an item into an array. Sorts an array in either ascending or descending order.
Background Text Functions

These functions manipulate background text.
Function Name SalDisableWindowAndLabel Description Disables mouse and keyboard input to a window, including disabling background text. Retrieves a window's background text. Hides a window and its associated label. Sets a window's background text. Shows a window and its associated label.
SalGetWindowLabelText SalHideWindowAndLabel SalSetWindowLabelText SalShowWindowAndLabel
1-5
Chapter 1
Color and Font Functions

These functions get and set window colors and fonts, as well as let you compose new colors.
Function Name SalColorFromRGB SalColorGet SalColorGetSys SalColorSet SalColorToRGB SalFontGet SalFontGetNames SalFontGetSizes SalFontSet VisFontEnum VisFontFree VisFontGet VisFontLoad VisTblSetRowColor VisMenuInsertFont VisMenuSetFont Description Composes a color from red, green, and blue values. Gets a window's color. Gets a system color. Sets a window's color. Decomposes a color into red, green, and blue values. Gets a window's font name, size, and enhancements. Gets the names of available screen fonts. Gets the available sizes for a particularfont. Sets a window's font name, size, and enhancements. Gets the font names and types (printer, true type, etc.). Frees a font loaded into memory with the VisFontLoad function. Gets specifications of a font. Loads a font into memory. Sets the text color for an entire row of a table window. Inserts a menu item into a menu and displays it in the specified font. Displays a menu item in the specified font. VisMenuSetFont operates on SQLWindows menus or menus inserted with the Vis Library.
1-6
Data Type Conversion Functions

These functions manipulate string data by converting to and from other data types.
Function Name SalFormUnitsToPixels SalGetDataType SalGetItemName SalGetMaxDataLength SalHStringToNumber SalPixelsToFormUnits SalSetMaxDataLength Description Computes the number of pixels in the number of SQLWindows form units. Returns an object's data type. Gets the name of a form window or data field. Gets the maximum length of a data field, multiline field, or table window column. Converts a string to a number. Computes the number of SQLWindows form units in the number of pixels. Sets the maximum length of a data field.
Date Functions
These functions manipulate date/time values.
Function Name SalDateConstruct SalDateCurrent SalDateDay SalDateHour SalDateMinute SalDateMonth SalDateMonthBegin SalDateQuarter SalDateQuarterBegin SalDateSecond SalDateToStr Description Constructs a date. Gets the client's current date and time. Gets the day portion of a date. Gets the hour portion of a date. Gets the minute portion of a date. Gets the month portion of a date. Gets the date of the first day of a month. Gets the quarter of the year of a date. Gets the date of the first day of the quarter of a given date. Gets the seconds portion of the date. Converts a date value to a string value.
1-7
Chapter 1
Function Name SalDateWeekBegin SalDateWeekday SalDateYea SalDateYearBegin
Description Gets the date of the previous Monday. Gets the day of the week as a number. Gets the year portion of a date. Gets the date of the first day of the year of a given date.
Debugging Functions
These functions help you debug your application.
Function Name SalCompileAndEvaluate SalContextBreak SalContextCurrent VisDebugAssert VisDebugBeginTime VisDebugEndTime VisDebugGetFlags VisDebugSetFlags VisDebugSetLevel VisDebugSetTime Description Evaluates the data type of an expression and returns its value. Retrieves the context of the most recently executed Break statement. Retrieves the current execution context. Asserts that a condition is true. Begins timing an operation. Stops recording the time and displays all incremental times and the total time. Retrieves the current debug flags. Sets debug flags. Sets the current debug level. Records the time since the last VisDebugSetTime or VisDebugBeginTime call. Writes a string to the debug application window.
VisDebugString
1-8
Dialog Box Functions

These functions provide an interface to Microsoft Windows' standard dialog boxes.
Function Name SalDlgChooseColor SalDlgChooseFont SalDlgOpenFile SalDlgSaveFile Description Displays the Color dialog box. Displays the Font dialog box. Displays the Open File dialog box. Displays the Save File dialog box.
These functions let you create and destroy your own dialog boxes.
Function Name SalEndDialog SalModalDialog SalModalDialogFromStr Description Destroys a modal dialog box. Creates a modal dialog box. Creates a modal dialog box with the specified name.
DOS Management Functions

These functions manage DOS features.
Function Name VisDosBuildFullName Description Builds a file name with drive and full directory based on the location of a running executable. Retrieves all subdirectories for a given directory into a SQLWindows array. Retrieves all subdirectories within a given directory into a SQLWindows array. Retrieves all available drives into a SQLWindows array, including floppy drives, hard disks, CD-ROM, network and RAM drives. Retrieves all files in a given directory into a SQLWindows array, and returns each file's size, date/time, and attributes.
VisDosEnumDirInfo VisDosEnumDirs VisDosEnumDrives
VisDosEnumFileInfo
1-9
Chapter 1
Function Name VisDosEnumFiles VisDosEnumNetConnections VisDosEnumPath VisDosEnumsShortDirInfo
Description Retrieves all file names from a given directory into a SQLWindows array. Retrieves all current network connections. Returns each directory in the DOS PATH environment string.
Retrieves all long and short subdirectory names for a given directory into a SQLWindows array.
Retrieves all long and short subdirectory names for a given directory into a SQLWindows array.
VisDosEnumsShortDirs
VisDosEnumsShortFileInfo
Retrieves all long and short file names for a given directory into a SQLWindows array.
Retrieves all long and short file names for a given directory into a SQLWindows array. Tests for existence of a drive, directory, or file. Returns the current directory of a specified drive. Returns total space and available space on a drive. Gets the type of drive specified. Returns an environment string based on a keyword. Returns the state of DOS flags. Retrieves the network name for the specified device. Returns the MS-DOS version number. Returns the volume label of a specified drive. Return indicator if directory contains subdirectories.
VisDosEnumsShortFiles VisDosExist VisDosGetCurDir VisDosGetDriveSize VisDosGetDriveType VisDosGetEnvString VisDosGetFlags VisDosGetNetName VisDosGetVersion VisDosGetVolumeLabel VisDosIsParent
1-10
Function Name VisDosMakeAllDir VisDosMakePath VisDosNetConnect VisDosNetDisconnect VisDosSetFlags VisDosSetVolumeLabel VisDosSplitPath
Description Creates all directories along the full path specified. Builds a full path from a drive, directory or file name. Connects to a network device. Cancels a network connection. Sets verify, break, or error mode flags. Sets the volume label on a disk drive. Splits a full path specification into drive, directory, and file name.
Drag Drop Functions

These functions enable users to drop files from the File Manager onto a SQLWindows application window at runtime, as well as drag and drop between application objects.
Function Name SalDragDropDisableDrop SalDragDropEnableDrop SalDragDropGetSource Description Disables dropping while in drag mode. Enables dropping while in drag mode. Retrieves the handle of the source window and the location of the mouse when you initiated drag mode. Retrieves the handle of the target window and the location of the mouse. Initiates drag mode. Ends drag mode. Verifies whether a window can accept a file from Windows' File Manager. Retrieves the names of the files dropped on a window. Finds the location of the mouse in a window at the time that the user dropped files onto the window.
SalDragDropGetTarget SalDragDropStart SalDragDropStop SalDropFilesAcceptFiles SalDropFilesQueryFiles SalDropFilesQueryPoint
1-11
Chapter 1
Edit Functions
Most of these functions provide text editing capabilities. Use them for fields that a user edits. Microsoft Windows maintains both an undo buffer that stores previous edits and a paste buffer that it uses for cutting and pasting between text fields. Other functions identify whether a user has selected data and if so, these functions enable Edit menu items.
Function Name SalEditCanCopyTo SalEditCanCut Description Returns TRUE if an editable picture has the focus and contains an object. Returns TRUE if the data in a data field, multiline field, table window column, or editable picture is selected. Returns TRUE if there is data on the Clipboard to paste into the data field, multiline field, table window column, picture with the focus. Returns TRUE if an editable picture has the focus. Returns TRUE if there is any editing to undo. Deletes selected data from the data field, multiline field, table window column, or picture with the focus. Copies selected data from a data field, multiline table window column, or picture and puts it on Clipboard. Copies a string to the Clipboard. Copies an object to a file if the editable picture that contains the object has the focus. Cuts selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard. Pastes data from the Clipboard into the data field, multiline field, table window column, or picture with the focus.
SalEditCanPaste
SalEditCanPasteFrom SalEditCanUndo SalEditClear
SalEditCopy
SalEditCopyString SalEditCopyTo SalEditCut
SalEditPaste
1-12
Function Name SalEditPasteFrom SalEditPasteString SalEditUndo VisWinClearAllFields
Description Copies a file into the editable picture with the focus. Pastes the contents of the Clipboard into the specified string. Undoes the last edit to a data field, multiline field, table window column, or picture. Clears all child fields of a parent window.
File Management Functions

These functions manage file, directory, and drive operations.
Function Name SalFileClose SalFileCopy SalFileCreateDirectory SalFileGetC Closes a file. Copies the contents of one file to another. Creates a directory. Gets the next character from an open file that contains non-ASCII (ANSI) or 16-bit characters. Gets the next character from an open file. Gets the path of the current working directory. Gets a file's modification date and time. Gets the letter of the current disk drive. Gets the next line from an open file. Opens a file. Opens or re-opens a file. Writes a character to an open file. Writes a character to an open file. Writes a string to an open file. Reads from an open file. Description
SalFileGetChar SalFileGetCurrentDirectory SalFileGetDateTime SalFileGetDrive SalFileGetStr SalFileOpen SalFileOpenExt SalFilePutC SalFilePutChar SalFilePutStr SalFileRead
1-13
Chapter 1
Function Name SalFileRemoveDirectory SalFileSeek SalFileSetCurrentDirectory SalFileSetDateTime SalFileSetDrive SalFileTell SalFileWrite VisFileAppend VisFileClose VisFileCopy VisFileCreateTemp VisFileDelete VisFileExpand VisFileFind VisFileGetAttribute VisFileGetSize VisFileGetType VisFileOpen VisFileRead VisFileReadString VisFileRename VisFileSeek VisFileSetAttribute
Description Deletes a directory. Sets the position in an open file. Changes a drive's current working directory. Sets a file's modification date and time. Sets the default disk drive. Gets the current position in an open file. Writes to an open file. Appends one or more files to another. Closes a file opened with the VisFileOpen call. Copies one or more files. Creates a temporary file. Deletes one or more files. Copies a source file to a destination file. Searches for a file in the following locations and returns the full path to the file: Gets the attribute bit values for the specified file. Gets the size of the specified file in bytes. Gets the file type. A file can be only one type. Creates or opens a file. A file must be opened before it can be read or written to. Reads a block of data from a file. Reads a text line from a text file into a string. Renames one or more files. Seeks to a specified offset within a file. Sets the attribute bits for one or more files.
1-14
Function Name VisFileSetDateTime VisFileTell VisFileWrite VisFileWriteString
Description Sets the date and time for one or more files. Returns the current file offset. Writes a block of data to a file. Writes a string to a file.
Format and Validation Functions

These functions format and validate the value of an object.
Function Name SalFmtFieldToStr Description Copies the formatted or unformatted contents of a data field or table window column to a string. Formats a date/time value. Formats a number value. Returns the format of a data field or table window column. Gets the input mask of a data field or table window column. Returns the picture format of a data field or table window column. Validates the contents of a data field or table window column using its profile. Validates an input mask. Validates a number or date/time picture format. Sets whether you keep input mask characters when you copy the value in a data field, table window column, or combo box. Sets the format of a data field or table window column. Sets the input mask of a data field or table window column.
SalFmtFormatDateTime SalFmtFormatNumber SalFmtGetFormat SalFmtGetInputMask SalFmtGetPicture SalFmtIsValidField SalFmtIsValidInputMask SalFmtIsValidPicture SalFmtKeepMask
SalFmtSetFormat SalFmtSetInputMask
1-15
Chapter 1
Function Name SalFmtSetPicture SalFmtStrToField SalFmtUnmaskInput SalFmtValidateField SalIsNull SalIsValidDateTime
Description Sets the picture format of a data field or table window column at runtime. Copies a string's formatted or unformatted contents to an object. Unmasks the input in a masked data field or table window column. Validates and formats the contents of a data field or table window column. Verifies whether a data field, multiline field, or table window column is empty. Verifies whether a data field, multiline field, or table window column contains a valid date/time value. Verifies whether input to a data field, multiline field, or table window column is of a specified precision and scale. Verifies whether the value of a data field, multiline field, or table window column is a valid integer. Verifies whether the value of a data field, multiline field, or table window column is a valid number. Verifies whether the entire string is a valid currency value. Verifies whether the entire string is a valid date/time value. Verifies whether the entire string is a valid number value. Tells SQLWindows that the focus is changing to a custom control so that SQLWindows can perform validation as needed.
SalIsValidDecimal
SalIsValidInteger
SalIsValidNumber
SalStrIsValidCurrency SalStrIsValidDateTime SalStrIsValidNumber SalValidateSet
1-16
List and Combo Box Functions

These functions manage list boxes and combo boxes. Since list boxes can be singleor multiple-selection, and sorted or not sorted, you cannot use all the functions for all list boxes.
Function Name SalListAdd SalListClear SalListDelete SalListFiles SalListGetMultiSelect SalListInsert SalListPopulate SalListQueryCount SalListQueryFile SalListQueryMultiCount SalListQuerySelection SalListQueryState SalListQueryText and SalListQueryTextX SalListQueryTextLength SalListRedraw Description Adds an entry to a list box or combo box. Clears a list box or combo box. Deletes an entry from a list box or combo box. Populates a list box or combo box with a directory listing. Returns the index numbers of selected list box entries. Inserts an entry into a list box or combo box. Populates a list box or combo box with the result set of a query. Returns the number of entries in a list box or combo box. Fetches the selected file name from a list box or combo box. Returns the number of currently selected list box entries. Returns the index of the currently selected list box or combo box entry. Indicates whether the specified list box or combo box entry is selected. Fetches a list box or combo box entry. Returns the length of a list box or combo box entry. Allows changes in a list box or combo box to be redrawn or prevents changes from being redrawn. Finds and selects a particular list box or combo box entry.
SalListSelectString
1-17
Chapter 1
Function Name SalListSetMultiSelect SalListSetSelect SalListSetTabs VisListAddValue
Description Selects or deselects the specified list box entry. Selects the specified list box or combo box index entry. Sets tab stops in a list box. Adds an item to a sorted list box or combo box and associates the specified value with the item. Populates a list box from a string array. Populates a list box from a string array and an array of values. Each item in the string is inserted as an item in the list box. The number of Unselects all selected items in a list box or combo box. Deletes all selected items from a list box or combo box. Finds the first string that matches the specified string in a list box or combo box. This function will locate a value associated with an item based on an index. Determines whether the list box portion of a combo box is visible. Gets the index of the item which has the focus rectangle or the last item to receive the focus frame in a multiple-selection list box. Retrieves the indexes of both the first visible item and the last visible item in a list box. Inserts an item into an unsorted list box or combo box and associates the specified value with the item. Tests a list box to determine if multiple selection is enabled. Scrolls an item into view.
VisListArrayPopulate VisListArrayPopulateValue
VisListClearSelection VisListDeleteSelected VisListFindString VisListFindValue VisListGetDropdownState VisListGetFocusIndex
VisListGetVisibleRange VisListInsertValue
VisListIsMultiSelect VisListScroll
1-18
Function Name VisListSetDropdownState VisListSetFocusIndex
Description Shows or hides the list box portion of a combo box. Sets the focus rectangle to the item at the specified index in a multiple-selection list box. Sets the width by which a list box can be scrolled horizontally.
VisListSetScrollWidth
MDI Functions
These functions support MDI (multiple document interface) windows.
Function Name SalMDIArrangeIcons SalMDICascade SalMDITile Description Arranges minimized child window icons in an MDI window. Cascades child windows of an MDI window. Tiles child windows of an MDI window.
Message Functions
Use these functions to post and send messages to objects.
Function Name SalPostMsg SalSendClassMessage Description Posts a message to a window. Invokes the message actions in the closest ancestor class that implements the given message. Invokes the message actions in the closest ancestor class that implements the given message. Use with a class that is the result of multiple inheritance. Sends a message to a window. Sends a message to all children of a form window. Sends a SAM_Validate message to the current data field, multiline field, or table window column if it has been edited.
SalSendClassMessageNamed
SalSendMsg SalSendMsgToChildren SalSendValidateMsg
1-19
Chapter 1
Function Name VisMessageBox VisMessageFreeButton VisMessageLoadButton VisMessageSetBkgdColor VisSendMsgString
Description Displays a message box with user defined buttons and a user defined icon. Frees memory allocated with VisMessageLoadButton. Establishes a button to be used in userdefined message boxes. Sets the background color for a VisMessageBox dialog box. Sends a message and passes a string in lParam.
Miscellaneous Functions
These functions perform miscellaneous system tasks from within a SQLWindows application.
Function Name SalAbort SalClearField SalCursorSet SalCursorSetFile SalCursorSetString SalDrawMenuBar SalGetProfileInt SalGetProfileString SalGetVersion SalLoadApp SalLoadAppAndWait Description Halts the execution of current actions. Clears the value from a field. Sets a window's cursor. Sets an application-defined cursor for the specified window. Sets a window's cursor from a string variable. Redraws a menu bar. Retrieves the integer value of an entry in the specified section of an initialization file. Retrieves the string value of an entry in the specified section of an initialization file. Returns the SQLWindows version. Loads and starts an application. Loads and starts an application, then waits for it to exit before returning control to the original application.
1-20
Function Name SalLoadAppAndProcessMsgs
Description Loads and starts an application, then waits for it to exit before returning control to the original application; the original application can process messages while the other application runs. Sets the default action of the Enter key (execute default push button or shift focus to next object). Generates a beep. Displays a message box. Checks to see if the variable of a functional, coclass, or interface class is null. Pauses execution for the specified number of milliseconds. Exits the SQLWindows application. If an error occurs during a method, you can call SalSetErrorInfo to set standard error information. Sets the value of an entry in the specified section of an initialization file. Destroys a system timer. Creates a system timer. Creates a pop-up menu at runtime. Displays or removes the hourglass cursor. Invokes the Windows help system. Enables or disables application yielding. Determines whether application yielding is enabled or disabled. Allows yielding and the sending of messages to a window. Stops yielding and the sending of messages to a window.
SalMapEnterToTab
SalMessageBeep SalMessageBox SalObjIsNull SalPause SalQuit SalSetErrorInfo
SalSetProfileString SalTimerKill SalTimerSet SalTrackPopupMenu SalWaitCursor SalWinHelp SalYieldEnable SalYieldQueryState SalYieldStartMessages SalYieldStopMessages
1-21
Chapter 1
Function Name VisErrorRecovery VisGetCopyright VisGetKeyState VisGetSystemMetrics VisGetVersion VisGetWinFlags VisGetWinVersion VisListLoadOutline VisListLoadOutlineFile VisListSaveOutline
Description Displays an error message and allows the user to free resources and retry the operation. Retrieves a copyright string to display in applications that use the Vis Library. Retrieves the state of a specified key. Retrieves widths and heights of various elements displayed by Windows. Gets the Vis Library version number. Retrieves the current Windows system and memory configuration. Returns the Windows version number. Loads an outline from a blob (binary large object) in memory. Loads an outline from a tab indented ASCII file. Compresses and saves a list box or combo box outline into a blob (binary large object) in memory. Retrieves the menu handle of a pop-up menu. Retrieves the system menu handle of a window. Retrieves the text of a menu item. Inserts a menu item into a menu. Uses the Windows check state to test whether a menu item is checked. Uses the Windows enable state to test whether a menu item is enabled. Unchecks a menu item. Clears bit values from a number. Sets bit values in a number.
VisMenuGetPopupHandle VisMenuGetSystemHandle VisMenuGetText VisMenuInsert VisMenuIsChecked VisMenuIsEnabled VisMenuUncheck VisNumberBitClear VisNumberBitSet
1-22
Function Name VisNumberChoose VisStrChoose VisStrFind VisStrFreeTable VisStrLeftTrim VisStrLoadTable VisWaitCursor VisWinClearAllEditFlags VisWinEnumProps VisWinFreeAccelerator
Description Evaluates bExpression. Evaluates bExpression. Locates a string within a string table. Frees all memory associated with a string table. Trims leading blanks from a string. Loads a string table from disk into memory. Turns hourglass cursor on or off. Clears the field edit flags for each data field or multi-line text field of a parent window. Enumerates the property list for a specified window. Clears an accelerator for a window, along with all memory associated with the accelerator. Retrieves window flags for a window. Retrieves a value from the property list of a specified window. Retrieves the Windows style bits for a specified window. Tests to determine if any required field is null. Displays a completion meter within a SQLWindows data field.
VisWinGetFlags VisWinGetProp VisWinGetStyle VisWinIsRequiredFieldNull VisWinSetMeter
MTS Functions
Use these functions to run COM objects across a network. Function Name SalMTSCreateInstance Description Creates a new component as part of the current transaction or in a new, independent transaction.
1-23
Chapter 1
Function Name SalMTSDisableCommit
Description Indicates that the objects transactional updates cannot be committed in their current form (stateful object). Indicates that the objects work is not necessarily done, but that its transactional updates can be committed in their current form (stateful object). Gets the explicit object context (IUnknown). Determines if the components caller is a member of a specified role. Determines if the component is in a transaction. Determines if declarative security is enabled for the component. Indicates that the objects work can never be committed. Indicates that the object has successfully completed its work for the transaction.
SalMTSEnableCommit
SalMTSGetObjectContext SalMTSIsCallerInRoll SalMTSIsInTransaction SalMTSIsSecurityEnabled SalMTSSetAbort SalMTSSetComplete
Number Functions
These functions perform mathematical calculations.
Function Name SalNumberAbs SalNumberArcCos SalNumberArcSin SalNumberArcTan SalNumberArcTan2 SalNumberCos SalNumberCosH Description Computes a number's absolute value. Computes a value's arccosine. Computes a value's arcsine. Computes a value's arctangent. Computes the arctangent of two values. Computes an angle's cosine. Computes an angle's hyperbolic cosine.
1-24
Function Name SalNumberExponent SalNumberHigh SalNumberHypot SalNumberLog SalNumberLogBase10 SalNumberLow SalNumberMax SalNumberMin SalNumberMod SalNumberPi SalNumberPower SalNumberRandInit SalNumberRandom SalNumberRound SalNumberSin SalNumberSinH SalNumberSqrt SalNumberTan SalNumberTanH SalNumberToChar SalNumberToHString SalNumberToStr and SalNumberToStrX
Description Computes a value's exponential function. Returns a number's high-order word value (most significant 16 bits). Computes the length of the hypotenuse of a right triangle. Computes a number's natural logarithm. Computes a number's base-10 logarithm. Returns a number's low-order word value (least significant 16 bits). Returns the greater of two values. Returns the lesser of two values. Returns a number's modulo. Multiplies a number by Pi. Computes a number raised to the power of another number. Sets the starting point for generating a series of pseudorandom numbers. Generates a pseudorandom integer in the range 0 to 32767. Returns a rounded number. Computes an angle's sine. Computes an angle's hyperbolic sine. Computes a number's square root. Computes an angle's tangent. Computes an angle's hyperbolic tangent. Converts an ASCII numeric value to a character. Converts a number to a string handle. Convert a number to a string.
1-25
Chapter 1
Function Name SalNumberToWindowHandle SalNumberTruncate VisNumberHighByte
Description Converts a number to a window handle. Truncates a number. Converts the specified number to a WORD and returns the high order 8 bits of the WORD. Converts the specified number to a WORD and returns the low order 8 bits of the WORD. Creates a double word value (DWORD) from two word values.
VisNumberLowByte
VisNumberMakeLong
See Also: Array Functions
OLE DB Consumer Functions

Use these functions when you use CTD as a consumer to connect to databases. Function Name SqlCloseAllSPResultSets SqlCommitSession SqlCreateSession SqlCreateStatement SqlFreeSession SqlGetCmdOrRowsetPtr Description Closes any result set generated by the execution of a stored procedure. Commits the current transaction associated with a specified session. Creates a new session. Creates a new statement belonging to the specified session. Closes a session. Gives the caller either the ICommand or the IRowset interface pointer of the Command or the Rowset OLE DB object. Gives the caller the IDBInitialize interface pointer of the Data Source OLE DB object or the IDBCreateSession interface pointer of the Session OLE DB object.
SqlGetDSOrSessionPtr
1-26
Function Name SqlGetNextSPResultSet
Description If a stored procedure invoked by calling SqlPrepareSP (and later executed by calling SqlExecute or SalTblPopulate) returns more than one result set, the application should call this function to get the second and subsequent result sets. Returns the error information associated with the specified session. Returns the session handle to which the specified statement handle belongs. Gets the value of the specified session property. Returns the error information associated with the specified statement handle (command/cursor). Prepares a stored procedure invokation statement. Rolls back the current transaction associated with the specified session. Sets the value of the specified session property.
SqlGetSessionErrorInfo SqlGetSessionHandle SqlGetSessionProperty SqlGetStatementErrorInfo
SqlPrepareSP SqlRollbackSession SqlSetSessionProperty
Picture Functions
These functions manipulate the contents of a picture.
Function Name SalPicClear SalPicGetDescription SalPicGetImage SalPicGetString SalPicSet Description Clears the contents of a picture. Retrieves a description of a picture's contents. Copies the contents of a picture to an image without the SQLWindows image header. Copies the contents of a picture to a string. Inserts a resource into a picture.
1-27
Chapter 1
Function Name SalPicSetFile SalPicSetFit SalPicSetImage SalPicSetString VisMenuInsertPicture VisMenuSetPicture VisPicFree VisPicLoad VisTblSetRowPicture
Description Sets the contents of a picture from a file. Sets the fit for a picture. Inserts the contents of a picture to an image without the SQLWindows image header. Sets the contents of a picture from a string. Inserts a menu item into a menu and displays the specified picture with it. Displays a picture in a menu item. Frees a picture from memory. A picture is either a bitmap or an icon. Loads a picture into memory. Sets the picture for a bit flag of a table window.
Print Functions
These functions let you control printing.
Function Name SalPrtExtractRect SalPrtGetDefault SalPrtGetParmNum SalPrtPrintForm SalPrtSetDefault SalPrtSetParmDefaults SalPrtSetParmNum SalPrtSetup Description Extracts the printing rectangle from the SAM_Print message's lParam argument. Gets the default printer. Gets the value of a print parameter. Prints a window. Sets the default printer. Resets print parameters to their defaults. Sets the value of a print parameter. Displays the Printer Setup Dialog Box which lets the user alter the printer setup.
1-28
Report Functions
GUPTA lets you generate reports previously designed with Report Builder. By using
the Report Builder functions listed in the following section, you can create, display, format, and print a report as well as get and set report variables.
Function Name SalReportClose SalReportCmd SalReportCreate SalReportDlgOptions SalReportGetDateTimeVar SalReportGetFileInfo SalReportGetNumberVar SalReportGetObjectVar SalReportGetPrinterSettings SalReportGetStringVar SalReportPrint SalReportPrintToFile SalReportReset SalReportResetPages SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar SalReportSetPrinterSettings SalReportSetPrinterTray SalReportSetStringVar Description Closes a Report Builder window. Sends a command to a report window. Creates a report. Sets the options for the report printing dialog box. Gets the value of a date/time report variable. Gets a comment which is embedded in a report template. Gets the value of a numeric report variable. Gets the value of an object report variable. Gets the characteristics of the currently active printer. Gets the value of a string report variable. Prints a report. Prints a report to a file. Updates the report preview with new data. Sets current page to 1 and total page to the value specific to a particular break group. Sets the value of a date/time report variable. Sets the value of a date/time report variable. Sets the value of an object report variable. Sets specific characteristics of the printer Specifies which printer trays are used for the first page and subsequent pages. Sets the value of a string report variable.
1-29
Chapter 1
Function Name SalReportTableCreate SalReportTablePrint SalReportTableView SalReportView
Description Creates a report from the specified table window. Prints a report created from a table window. Displays, in preview mode, a report created from a table window. Displays a report in preview mode.
Scroll Bar Functions

These functions manage horizontal and vertical scroll bars.
Function Name SalScrollGetPos SalScrollGetRange SalScrollSetPos SalScrollSetRange Description Gets the scroll bar position. Gets values set by SalScrollSetRange. Sets the scroll bar position. Sets the range of a scroll bar.
SQL Functions
Most SQL functions are database-independent. As Gupta Technologies LLC continues to provide connectivity to an ever-increasing number of databases, these functions provide a consistent interface.
Function Name SqlClearImmediate SqlClose SqlCommit SqlConnect SqlContextClear SqlContextSet SqlContextSetToForm Description Disconnects the Sql Handle used by SqlImmediate. Closes a named cursor. Commits the current SQL transaction. Connects a Sql Handle to a database. Clears the context set by SqlContextSet. Sets the context for later compilation and fetching. Sets context to form name.
1-30
Function Name SqlDirectoryByName SqlDisconnect SqlDropStoredCmd SqlError SqlErrorText SqlExecute SqlExecutionPlan SqlExists SqlExtractArgs SqlFetchNext SqlFetchPrevious SqlFetchRow SqlGetCursor SqlGetError SqlGetErrorPosition SqlGetErrorText and SqlGetErrorTextX SqlGetModifiedRows SqlGetParameter SqlGetParameterAll SqlGetResultSetCount SqlGetRollbackFlag
Description Gets the names of databases on a given server. Disconnects a Sql Handle from a database. Deletes a stored command. Gets the most recent error code for the specified Sql Handle. Gets an error code's reason and/or remedy. Executes a SQL statement. Gets the execution plan for a compiled SQL statement. Checks for the existence of a particular row. Extracts error information. Fetches the next row in a result set. Fetches the previous row in a result set. Fetches a specific row from a result set. Returns a cursor handle, which can then be used for calls into the SQLBase API. Turns off backend error mapping and reports real backend errors. Gets the offset of an error within a SQL statement. Gets the message text for a SQL error number. Returns the number of rows changed by an INSERT, UPDATE, or DELETE. Returns a database parameter. Returns a database parameter. Returns the number of rows in a result set. Returns the database rollback flag.
1-31
Chapter 1
Function Name SqlImmediate SqlImmediateContext SqlOpen SqlPLSQLCommand
Description Prepares and executes a SQL statement. Prepares, executes, and fetches the results of a SQL statement. Names a cursor and executes a SQL statement. Executes PL/SQL stored procedures in SQLWindows. Call it once for each invocation of PL/SQL. Prepares a Sql statement for execution. Prepares and executes an Sql statement. Retrieves a stored command. Sets the size of the input message buffer for a specified cursor. Sets the isolation level. Sets the timeout period on waiting for a lock. Sets type of column to bind to. Sets the size of the output message buffer for a specified cursor. Sets a database parameter. Sets a database parameter. Turns a result set mode on and off. Compiles and stores a command. Before SQLWindows performs a SQL execute or fetch operation, it compiles the bind and into variables which is looking up the symbols and generating the code that gets the values (for bind variables) or that fetches the values (for an into variable).
SqlPrepare SqlPrepareAndExecute SqlRetrieve SqlSetInMessage SqlSetIsolationLevel SqlSetLockTimeout SqlSetLongBindDatatype SqlSetOutMessage SqlSetParameter SqlSetParameterAll SqlSetResultSet SqlStore SqlVarSetup
1-32
String Conversion Functions

These functions manipulate string data by changing the form of a string or looking for substrings.
Function Name SalStrCompress SalStrFirstC SalStrGetBufferLength SalStrLeft and SalStrLeftX SalStrLength SalStrLop SalStrLowerand SalStrLowerX SalStrMid and SalStrMidX SalStrProper and SalStrProperX SalStrRepeat and SalStrRepeatX SalStrReplace and SalStrReplaceX SalStrRight and SalStrRightX Description Compresses a string. Returns the first character in a string. Returns the length of a string buffer. Returns a string of specified length, starting with the first character in the string. Returns the length of a string. Returns the ANSI numeric value of the first character of a string. Converts a string to lowercase. Returns a substring. Converts a string to a proper name. Concatenates a string with itself a specified number of times. Replaces characters in one string with characters from another string. Returns a string of specified length, starting with the last or right-most character in the string. Finds a string within a string. Sets the length of the specified string buffer. Converts a string to a date/time value. Parses a string into substrings. Converts a string to a number. Removes white space from a string. Decompresses a string. Converts a string to uppercase.
SalStrScan SalStrSetBufferLength SalStrToDate SalStrTokenize SalStrToNumber SalStrTrim and SalStrTrimX SalStrUncompress SalStrUpper and SalStrUpperX
1-33
Chapter 1
Function Name VisStrExpand VisStrPad VisStrProper VisStrRightTrim VisStrScanReverse VisStrSubstitute VisStrTrim
Description Expands a template string by inserting one or more array elements. Pads a string with trailing blanks and returns the result. Converts a string to mixed case. Trims trailing blanks from a string. Scans a string for a specified sub-string from the last character to the first. Substitutes all occurrences of one string with another string. Trims leading and trailing blanks from a string. It does not adjust embedded brackets.
Table Window Functions

These functions manage table windows.
Function Name SalTblAnyRows SalTblClearSelection SalTblColumnAverage SalTblColumnSum SalTblCopyRows SalTblCreateColumn SalTblCreateColumnEx SalTblDefineRowHeader SalTblDefineSplitWindow SalTblDeleteRow Description Determines whether any rows have certain flags set. Clears the selection of rows in a table window. Computes the average of a column's values. Computes the sum of a column's values. Copies the contents of specified rows to the Clipboard. Creates columns at runtime. Creates columns at runtime, with userspecified datatype. Defines the appearance and behavior of a row header. Defines how a table window is split horizontally. Deletes a row.
1-34
Function Name SalTblDeleteSelected SalTblDestroyColumns SalTblDoDeletes SalTblDoInserts SalTblDoUpdates SalTblFetchRow
Description Applies a DELETE statement to all selected rows. Destroys automatic columns created at runtime. Applies a DELETE statement to all rows with certain flags set. Applies an INSERT statement to all new rows. Applies an UPDATE statement to all edited rows. Sends a SAM_FetchRow message to the table window if the specified row is not in the table window cache. Scans forward looking for a row that has certain flags set. Scans backward looking for a row that has certain flags set. Returns the value in a specified column of the context row. Returns a column's title. Retrieves a column's window handle based on its position in the table window or its column identifier. Inserts a new row. Sets the ROW_Edited flag on a new or changed row. Turns off the focus frame. Returns the part of a table window located at a given coordinate. Pastes the contents of the Clipboard into the specified table window. Populates a table window with a result set.
SalTblFindNextRow SalTblFindPrevRow SalTblGetColumnText SalTblGetColumnTitle SalTblGetColumnWindow
SalTblInsertRow SalTblKillEdit SalTblKillFocus SalTblObjectsFromPoint SalTblPasteRows SalTblPopulate
1-35
Chapter 1
Function Name SalTblPopulateFromXML SalTblQueryColumnFlags SalTblQueryColumnID SalTblQueryColumnPos SalTblQueryColumnWidth SalTblQueryContext SalTblQueryFocus SalTblQueryLockedColumns SalTblQueryRowFlags SalTblQueryRowHeader SalTblQueryScroll SalTblQuerySplitWindow SalTblQueryTableFlags SalTblQueryVisibleRange SalTblReset SalTblScroll SalTblSetCellTextColor SalTblSetColumnFlags SalTblSetColumnPos SalTblSetColumnText SalTblSetColumnTitle SalTblSetColumnWidth SalTblSetContext SalTblSetFlagsAnyRows
Description Clears a table window and then populates it with data from an XML file. Tests the state of a column's flags. Gets a column's identifier. Gets a column's position in the table window. Retrieves a column's width. Gets the current context row. Identifies the cell with the focus. Returns the number of locked columns. Queries a row's flags. Gets the definition of a row header. Gets the current scroll position and range. Specifies how the table window is split horizontally. Tests the state of a table window's flags. Gets the current visible range. Clears a table window. Scrolls to a specified cell. Sets a cell's text color. Sets or clears a column's flags. Moves a column. Sets the value of a specified column in the context row. Sets a column's title. Sets a column's width. Sets the context row. Sets or clears row flags.
1-36
Function Name SalTblSetFocusCell SalTblSetFocusRow SalTblSetLockedColumns SalTblSetRange SalTblSetRow SalTblSetRowFlags SalTblSetTableFlags SalTblSortRows SalTblWriteXMLAndSchema SalTblWriteXMLAndSchemaEx
Description Sets the focus to a specified cell. Sets the focus frame row. Defines the number of columns to lock. Defines the minimum and maximum rows. Sets focus to a row. Sets or clears row flags. Sets or clears table window flags. Sorts the contents of a table window based on the values in a specified column. Writes the contents of a table window to an XML file and/or an XML schema file. Writes the contents of a table window to an XML file and/or an XML schema file. Selects rows with specific flags. Determines whether any rows in the specified table window match certain flags. Performs a best fit on the display contents of a specific column. Clears selection for all columns of a table window. Locates a date/time value within a column. Locates a number value within a column. If VisTblFindNumber does not find a match, it causes the tablewindow context to be set to the last row in the table. Locates a string value within a column. Retrieves the contents of a cell in a table window. Retrieves the contents of a column heading. The row specified will be set to the context row.
VisTblAllRows VisTblAutoSizeColumn VisTblClearColumnSelection VisTblFindDateTime VisTblFindNumber
VisTblFindString VisTblGetCell VisTblGetColumnTitle
1-37
Chapter 1
Window Management Functions

These functions let you manipulate an application's windows.
Function Name SalAppDisable SalAppEnable SalAppFind Description Disables input to open windows. Enables input to open windows. Finds a visible top-level window for the application that you specify and returns its window handle. Brings a specified window to the top of all overlapping windows. Centers a window. Creates a window. Creates a form window, dialog box, or table window as a child of another form window, dialog box, or toolbar at runtime. Destroys a window. Disables mouse and keyboard input to a window. Disables mouse and keyboard input to a window, including disabling background text. Enables keyboard and mouse input to a window. Enables keyboard and mouse input to a window, including enabling background text. Gets information about a form window. Gets information about the current docking orientation of a dialog box. Sets the docking orientation of a dialog box with its parent window. Gets the handle of the default push button. Finds the first child of a window.
SalBringWindowToTop SalCenterWindow SalCreateWindow SalCreateWindowEx
SalDestroyWindow SalDisableWindow SalDisableWindowAndLabel
SalEnableWindow SalEnableWindowAndLabel
SalFormGetParmNum SalDlgGetDockStatus SalDlgSetDockStatus SalGetDefButton SalGetFirstChild
1-38
Function Name SalGetFocus SalGetNextChild SalGetType SalGetWindowLabel SalGetWindowLabelText SalGetWindowLoc SalGetWindowSize SalGetWindowState SalGetWindowText SalHideWindow SalHideWindowAndLabel SalInvalidateWindow SalIsButtonChecked SalIsWindowEnabled SalIsWindowVisible SalMoveWindow
Description Gets the object with the focus. Finds the next child of a window. Returns the type of the specified object. Retrieves the window handle of a background text label. Retrieves a window's background text. Gets a window's current position on the X and Y axes. Gets the current window's size. Gets the current state of a window. Retrieves a window's text. Hides a window. Hides a window and its associated label. Causes a window to be repainted. Determines whether a radio button is set or a check box is checked. Specifies whether a window is enabled for mouse and keyboard input. Specifies whether a window is visible. Moves a window a given number of form units on the X and Y axes relative to its current position. Returns the window handle of a parent or owner window. Returns the setting of the field edit flag for a data field, multiline field, table window column, or picture. Sets the default push button for a form window or dialog box.
SalParentWindow SalQueryFieldEdit
SalSetDefButton
1-39
Chapter 1
Function Name SalSetFieldEdit
Description Sets or clears the field edit flag for a data field, multiline field, table window column, or picture. Sets the focus to a window. Sets a window's background text. Moves a window to a position on the X and Y axes. Resizes a window. Sets a window's text. Makes a window visible. Shows a window and its associated label. Gets the text displayed in a top-level window's status bar. Displays specified text in a top-level window's status bar. Shows or hides a top-level window's optional status bar. Shows or hides a top-level window's tool bar. Updates the client area of a window. Gets information about the docking orientations allowed by a top-level window. Gets the value of a named property for an instance of a QuickObject. The property must have been created at designtime with the QuickObject Editor. Converts a window handle to a number. Converts a window handle to a number. Enumerates the property list for a specified window. Retrieves a value from the property list of a specified window.
SalSetFocus SalSetWindowLabelText SalSetWindowLoc SalSetWindowSize SalSetWindowText SalShowWindow SalShowWindowAndLabel SalStatusGetText SalStatusSetText SalStatusSetVisible SalTBarSetVisible SalUpdateWindow SalWindowGetDockSettings SalWindowGetProperty
SalWindowHandleToNumber SalWindowIsDerivedFromClass VisWinEnumProps VisWinGetProp
1-40
Function Name VisWinIsChild VisWinIsMaximized VisWinIsMinimized VisWinIsRestored VisWinIsWindow VisWinLoadAccelerator VisWinMove VisWinRemoveProp VisWinSetFlags VisWinSetProp
Description Tests whether a specified window is a child or direct descendant of a parent window. Tests whether a specified window is maximized. Tests whether a specified window is minimized. Tests whether a specified window is neither maximized or minimized. Tests whether a specified window is valid. Sets an accelerator keystroke for a window. Moves and resizes a window, based on pixel coordinates. Removes a property list entry for a specified window. Sets flags for a specified window. Adds a new property list entry or changes an existing property list entry for a specified window. Adds a window style to a window. Changes the tab order of a control. Sets a window's visibility state.
VisWinSetStyle VisWinSetTabOrder VisWinShow
XML Functions
These functions handle reading and writing of XML data. Note that there are also many XML-related functions in the optional include library xmllib.apl, described in the chapter Handling XML in Developing with SQLWindows...
Function Name SalTblPopulateFromXML SalTblWriteXMLAndSchema Description Loads XML data into a table window. Writes table window data into an XML data file and/or an XML schema file..
1-41
Function Name SalTblWriteXMLAndSchemaEx
Description Writes table window data into an XML data file and/or an XML schema file..Filters by row flags Reads an XML data file and places its contents into a UDV or array. Gets the error code and description from the last XML operation performed. Writes the contents of a UDV or array into an XML data file.
SalXMLDeserializeUDV SalXMLGetLastError SalXMLSerializeUDV
Obsolete Functions
SalCreateWindowFrmStr SalFmtCopyProfile SalFmtGetParmInt SalFmtGetParmStr SalFmtGetProfile SalFmtSetParmInt SalFmtSetParmStr SalFmtSetProfile SalQueryArrayBounds SalSetArrayBounds SalDDEAddAtom SalDDEAlloc SalDDEDeleteAtom SalDDEExtract SalDDEExtractCmd SalDDEExtractDataText SalDDEExtractOptions SalDDEFindAtom SalDDEFree SalDDEGetAtomName SalDDEGetExecuteString SalDDEPost SalDDERequest SalDDESend SalDDESendAll SalDDESendExecute
Obsolete Functions
SalDDESendToClient SalDDESetCmd SalDDESetDataText SalDDESetOptions SalDDEStartServer SalDDEStartSession SalDDEStopServer SalDDEStopSession
1-43
Chapter 1
1-44
Chapter 2
SQLWindows Functions
This is an alphabetical list of the GUPTA SQLWindows functions accompanied by detailed information about each functions purpose, its parameters and return value, and an example. Function descriptions include: Syntax Description Parameters Return value See also Example
2-1
Chapter 2
SalAbort
Syntax Description bOk = SalAbort ( nExitCode ) Halts processing of the current menu action, message action, or application action. Use SalAbort when you want to terminate the current calling sequence without returning a status. For example, if your application is several layers into internal function calls and an error occurs, SalAbort terminates the current calling sequence of functions and leaves the application in the state it was prior to the first function call of that sequence. Parameters Return Value See Also Example nExitCode Receive Number. The status of the exit performed by SalAbort. SQLWindows ignores this parameter as input.
bOk is TRUE if the function succeeds and FALSE if it fails. SalQuit

If NOT SqlConnect ( hSql ) Call SalAbort ( -1 )
SalActiveXAutoErrorMode
Syntax Description bOK = SalActiveXAutoErrorMode( bOn ) Turn off automatic error handling (on by default) by calling this function and specifying FALSE. Later, you can turn automatic error handling on by calling this function and specifying TRUE. bOn Boolean. Specify FALSE to turn off automatic error handling or specify TRUE to turn on automatic error handling.
Parameters Return Value See Also Example
Always returns TRUE. ActiveX exception handling None
SalActiveXClose
Syntax Description bOK = SalActiveXClose( hwndCntrCtrl, bSave ) Closes an object and ends the connection to the application that provided the object. This function only succeeds on objects that are created using the SalActiveXCreateFromFile function at run time or using the Insert Object dialog at design time. If the object is created at design time using by choosing an ActiveX control from the tool pallette dropdown list, this function will fail.
2-2
SalActiveXCreate
Parameters
hwndCntrCtrl bSave
Window Handle. The ActiveX container control. Boolean. If TRUE, the object's application will do a save before closing the connection.
Return Value See Also Example
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXCreateFromFile

ActiveX: ax1 Call SalActiveXClose( ax1, FALSE )
SalActiveXCreate
Syntax Description Parameters bOK = SalActiveXCreate( hwndCntrCtrl, strBytes ) Creates an object given its class descriptor (progID). hwndCntrCtrl strBytes Return Value See Also Example Window Handle. The ActiveX container control. String. The OLE progID of the class (such as Excel.Sheet.8).
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXCreateFromFile

Data Field: df1 ActiveX: ax1 Call SalActiveXCreate( ax1, df1 )
SalActiveXCreateFromData
Syntax Description Parameters bOK = SalActiveXCreateFromData( hwndCntrCtrl, strBytes ) Creates an object given its class descriptor (progID). hwndCntrCtrl strBytes Return Value See Also Example Window Handle. The ActiveX container control. String. The object's data as a raw blob of bytes.
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXGetData

ActiveX: ax1 String: blob
2-3
Chapter 2
Call SalActiveXCreateFromData( ax1, blob )
SalActiveXCreateFromFile
Syntax Description Parameters bOK = SalActiveXCreateFromFile( objObject, strFile ) Creates an instance of an ActiveX object. objObject strFile Return Value See Also Example Object. A reference to the created object. String. The file name of a valid doc object (such as c:\docs\mywordfile.doc).
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXCreate None.
SalActiveXDelete
Syntax Description bOK = SalActiveXDelete( hwndCntrCtrl) Deletes an instance of an ActiveX object. This function only succeeds on objects that are created using the SalActiveXCreateFromFile function at run time or using the Insert Object dialog at design time. If the object is created at design time using by choosing an ActiveX control from the tool pallette dropdown list, this function will fail. hwndCntrCtrl Window Handle. The window handle of the object to delete.
bOK is TRUE if the function succeeds and FALSE if it fails. None.

ActiveX: ax1 Call SalActiveXDelete( ax1 )
SalActiveXDoVerb
Syntax Description bOK = SalActiveXDoVerb( hwndCntrCtrl, nVerb, bSize) Opens an object for an operation such as editing. Each object can support its own set of verbs. The standard verbs that every object should support are listed in the table below. hwndCntrCtrl Window Handle. The window handle of the object to delete.
Parameters 2-4
SalActiveXGetActiveObject
nVerb Constant salOLEPrimary salOLEShow
Number. A constant that identifies the verb: Description The default action for the object. Activates the object for editing. If the application that created the object supports in place activation, the object is activated within the ActiveX container control. Opens the object in a separate application window. If the application that created the object supports in place activation, the object is activated in its own window. For embedded objects, hides the application that created the object.
salOLEOpen
salOLEHide
salOLEUIActivate If the object supports in place activation, activates the object for in place activation and shows any user interface tools. If the object doesn't support in place activation, the object does not activate and an error occurs. salOLEInPlaceActivateIf the user moves the focus to the ActiveX container control, creates a window for the object and prepares the object to be edited. An error occurs if the object does not support activation on a single mouse click. salOLEDiscardUndoStateIf an object is activated for editing, discards all record of changes that the object's application can undo. bSize Return Value See Also Example If TRUE, sizes the object to the size of the site window upon activation.
bOK is TRUE if the function succeeds and FALSE if it fails. None.

ActiveX: ax1 Data Field: df2 Data Field: df3 Call SalActiveXDoVerb( ax1, SalStrToNumber(df2), SalStrToNumber(df3) )
SalActiveXGetActiveObject
Syntax bOK = SalActiveXGetActiveObject( objObject, strClass)
2-5
Chapter 2
Description
Gets an instance of an ActiveX object when the server application is already up and running. This function searches the OLE Running Object Table to get an existing class instance. The running object table contains references to running objects.
Parameters
objObject strClass
Object. The object that was found. String. The class name of the object to get in appname.objecttype format.
bOK is TRUE if the function succeeds and FALSE if SQLWindows could not find a valid automation dispatch. None. None.
SalActiveXGetData
Syntax Description bOK = SalActiveXGetData( hwndCntrCtrl, strBytes) Gets the storage (state and data) associated with the object as a raw blob of bytes. This provides an alternate runtime persistence mechanism for embedded objects. The second parameter must be a string variable. Other string-based objects such as data fields or table window columns will compile, but will not work successfully at run time. Parameters hwndCntrCtrl strBytes Return Value See Also Example Window Handle. The ActiveX container control. Receive String. The object's data as a raw blob of bytes.
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXCreateFromData

ActiveX: ax1 String: blob Call SalActiveXGetData( ax1, blob )
SalActiveXGetFileName
Syntax Description bOK = SalActiveXGetFileName ( hwndControl, strFileName ) Gets the File Name of the object inserted with the Create From File option using SalActiveXInsertObjectDlg.
2-6
SalActiveXGetObject
Parameters
hwndControl strFileName
Window Handle. The ActiveX container control. Receive String. The object's FileName, if the object was inserted using Create From File Option.
Return value See Also Example
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXInsertObjectDlg

ActiveX: ax1 String: strFileName Call SalActiveXInsertObjectDlg ( ax1 ) Call SalActiveXGetFileName( ax1, strFileName )
SalActiveXGetObject
Syntax Description Parameters bOK = SalActiveXGetObject( hwndCntrCtrl, objObject) Gives access to the automation dispatch interface of the object in the specified container. hwndCntrCtrl objObject Return Value See Also Example Window Handle. The ActiveX container control. Object. The object that was retrieved.
TRUE if a valid automation dispatch interface was found, FALSE otherwise. None
Variant: vOptional Variant: vString Number: n String: tmp Object: sheet Object: range Object: book ActiveX: ax1 If SalActiveXGetObject( ax1, book ) Call book.Invoke("ActiveSheet", INVOKE_GET) Call book.PopObject(-1, sheet) Call vString.SetString("A1:A5") Call sheet.PushVariant(vString)
2-7
Chapter 2
Call sheet.PushVariant(vOptional) Call sheet.Invoke("Range", INVOKE_GET) Call sheet.PopObject(-1, range) Call vString.SetString("Eiger rules") Call range.PushVariant(vString) Call range.Invoke("Value", INVOKE_PUT)
SalActiveXGetProgID
Syntax Description Parameters bOK = SalActiveXGetProgID( hwndControl, strProgID ) Gets the ProgID of the object inserted using SalActiveXInsertObjectDlg. hwndControl strProgID Return value See Also Example Window Handle. The ActiveX container control. Receive String. The object's ProgID.
bOK is TRUE if the function succeeds and FALSE if it fails. SalActiveXInsertObjectDlg

ActiveX: ax1 String: strProgID Call SalActiveXInsertObjectDlg ( ax1 ) Call SalActiveXGetData( ax1, strProgID )
SalActiveXInsertObjectDlg
Syntax Description bOK = SalActiveXInsertObjectDialog( hwndCntrCtrl) Displays the standard Insert Object dialog. When you create a new object, the application associated with the class name (for example, Excel.exe) must be correctly registered with the operating system. (The application setup program should register the application correctly.). Parameters Return Value hwndCntrCtrl Window Handle. The ActiveX container control where the object is created.
bOK is TRUE if the function succeeds and an object was selected and inserted without error and FALSE if an object was selected, but the insert failed. If bOK is -1, no object was selected (such as when a user cancels the dialog). None
ActiveX: ax1
See Also Example
2-8
SalActiveXOLEType
Call SalActiveXInsertObjectDlg( ax1 )
SalActiveXOLEType
Syntax Description Parameters Return Value bOK = SalActiveXOLEType( hwndCntrCtrl) Returns the status of the object in an ActiveX container control. hwndCntrCtrl Window Handle. The ActiveX container control.
Number. The status of the ActiveX container control: Constant salOLEControl Description The ActiveX container contains an ActiveX control.
salOLEEmbedded Embedded. The ActiveX container control contains an embedded object. All the object's data is managed in the SQLWindows application. salOLENone See Also None None. The ActiveX container control does not contain an object.
SalAppDisable
Syntax Description bOk = SalAppDisable ( ) Disables input to all open applications. Use SalAppDisable and SalAppEnable when there are multiple applications running simultaneously and you want to control which application receives user input. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalAppEnable
Call SalAppDisable ( ) Call SalLoadAppAndWait ( 'Excel', '' ) Call SalAppEnable ( )
SalAppEnable
Syntax bOk = SalAppEnable ( )
2-9
Chapter 2
Description
Enables input to all open applications that were disabled by SalAppDisable. Use SalAppDisable and SalAppEnable when there are multiple applications running simultaneously and you want to control which application receives user input. No parameters. bOk is TRUE if the function succeeds and FALSE if you did not previously call SalAppDisable. SalAppDisable
Call SalAppDisable ( ) Call SalLoadAppAndWait ( 'Excel', '' ) Call SalAppEnable ( )
SalAppFind
Syntax Description hWnd = SalAppFind ( strAppName, bActivate ) Finds a visible top-level window for the application that you specify and returns its window handle. SalAppFind first looks for running instances of SQLWindows applications and then for running instances of other Windows applications. If you specify the calling application's name in SalAppFind, SQLWindows can only find another running instance of it. You can use this feature to prevent more than one instance of an application running. If there are multiple instances of a single application, SalAppFind finds and returns the window handle of the first instance it finds. If an application has multiple top-level windows, SalAppFind returns the handle of the first top-level window it finds. Calling SalAppFind multiple times does not always return the handle of the same window. If an application does not have visible windows, then SalAppFind cannot find it. Parameters strAppName String. The name of the application without the extension. For
SQLWindows applications, specify the *.EXE name. For other
Windows applications, specify the value given in the NAME statement in the applications *.DEF file. bActivate Return Value Example 2-10 Boolean. If you set bActivate to TRUE, SalAppFind also activates the application's window.
hWnd is the handle of the window.

On SAM_AppStartup
SalAppFind
If SalAppFind( 'INVOICE', TRUE ) != hWndNULL Call SalQuit( )
2-11
Chapter 2
SalArrayAvg
Syntax Description Parameters Return Value See Also nAvg = SalArrayAvg ( nArrayNum ) Returns the average value of all the numbers in an array. nArrayNum Numeric Array. The name of an array of numbers.
nAvg is the average value in an array of numbers. SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Create Set dfAvg = SalArrayAvg( nArrayNum )
Example
SalArrayDimCount
Syntax Description Parameters bOk = SalArrayDimCount ( aArray, nDim ) Returns the number of dimensions in an array. aArray nDim Return Value See Also Array. The name of the array to query. Receive Number. Number of dimensions in the array.
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Create Set bOk = SalArrayDimCount (aArray, nDim) If nDim = 0 Set bDimTrue = False
Example
2-12
SalArrayGetLowerBound
SalArrayGetLowerBound
Syntax Description Parameters bOk = SalArrayGetLowerBound ( aArray, nDim, nBound ) Returns the lower bound of an array. aArray nDim nBound Return Value See Also Array. The name of the array to query. Number. Number of the dimension to query. The first dimension is one, the second is two, and so on. Receive Number. Lower bound value.
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayDimCount SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Click Set bOk = SalArrayGetLowerBound (aArray, nBound)
Example
SalArrayGetUpperBound
Syntax Description Parameters bOk = SalArrayGetUpperBound ( aArray, nDim, nBound ) Returns the upper bound of an array. aArray nDim nBound Return Value See Also Array. The name of the array to query. Number. Number of the dimension to query. The first dimension is one, the second is two, and so on. Receive Number. Upper bound value.
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound
2-13
Chapter 2
SalArraySum Example
On SAM_Click Set bOk = SalArrayGetUpperBound (aArray, nBound)
SalArrayIsEmpty
Syntax Description Parameters Return Value See Also bData = SalArrayIsEmpty ( aArray ) Determines if a dynamic array contains data. aArray Array. The name of the array to query.
bData is TRUE if the array contains no data and FALSE if it is has data. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Click If Not SalArrayIsEmpty (aArray) Call ...
Example
SalArrayMax
Syntax Description Parameters Return Value See Also nMax = SalArrayMax ( nArrayNum ) Returns the maximum value in an array of numbers. nArrayNum Numeric Array. The name of an array of numbers.
nMax is the maximum value in an array of numbers. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Create
Example 2-14
SalArrayMin
Set dfMax = SalArrayMax( nArrayNum )
SalArrayMin
Syntax Description nMin = SalArrayMin ( nArrayNum ) Returns the minimum value in an array of numbers. nArrayNum Return Value See Also Numeric Array. The name of an array of numbers.
nMin is the minimum value in an array of numbers. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArraySetUpperBound SalArraySum
On SAM_Create Set dfMin = SalArrayMin( nArrayNum )
Example
SalArraySetUpperBound
Syntax Description bOk = SalArraySetUpperBound ( aArray, nDim, nBound ) Sets the upper bound of an array. When you call this function for a dimension other than the first, SQLWindows must copy most of the array's data. There can be a performance cost when you call this function for any dimension but the first one. Parameters aArray nDim nBound Array. The name of the array to query. Number. Number of the dimension to query. The first dimension is one, the second is two, and so on. Number. Upper bound value. Specify -1 to reset a dynamic array to zero elements. Specify AC_Dynamic to change a static array to a dynamic array. (You can make only the first dimension of an array dynamic.)
Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound
2-15
Chapter 2
SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySum Example

On SAM_Click Call SalArraySetUpperBound (aArray, 1, 5)
SalArraySum
Syntax Description Parameters Return Value See Also nSum = SalArraySum ( nArrayNum ) Returns the sum of the elements in an array of numbers. nArrayNum Numeric Array. The name of an array of numbers.
nSum is the sum of the elements in an array of numbers. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound
On SAM_Create Set dfSum = SalArraySum( nArrayNum )
Example
SalBringWindowToTop
Syntax Description Parameters Return Value See Also Example bOk = SalBringWindowToTop ( hWndToExpose ) Brings a window to the top of all overlapping windows. hWndToExpose Window Handle. The handle (or name) of the window to bring to the top.
bOk is TRUE if the function succeeds and FALSE if it fails. SalHideWindow SalShowWindow
If ( hWndCustomer ) Call SalBringWindowToTop ( hWndCustomer )
2-16
SalCenterWindow
SalCenterWindow
Syntax Description Parameters Return Value See Also Example bOk = SalCenterWindow ( hWndCenter ) Centers a window. If the window is a top-level window, SQLWindows centers it on the desktop. If the window is a child window, SQLWindows centers it on top of its parent. hWndCenter Window Handle. The handle (or name) of the window to center.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMoveWindow

Call SalCenterWindow ( pbExample )
SalClearField
Syntax Description Parameters Return Value See Also Example bOk = SalClearField ( hWndFldToClear ) Clears the value from a data field, multiline field, or table window column. hWndFldToClear Window Handle. The handle (or name) of the data field, multiline field, or table window column to clear.
bOk is TRUE if the function succeeds and FALSE if it fails. SalIsNull

If ( dfAge < 0 ) Call SalClearField ( dfAge )
SalColorFromRGB
Syntax Description Parameters nColor = SalColorFromRGB ( nRed, nGreen, nBlue ) Composes a color from red, green, and blue values. nRed nGreen nBlue Return Value See Also Number. A number from 0 to 255. Number. A number from 0 to 255. Number. A number from 0 to 255.
nColor is the color created. SalColorGet SalColorGetSysColor SalColorSet SalColorToRGB 2-17
Chapter 2
Example
Set nRed = 128 Set nGreen = 128 Set nBlue = 128 Set nColor = SalColorFromRGB ( nRed, nGreen, nBlue ) If NOT SalColorSet ( hWndItem, COLOR_IndexWindow, nColor ) ...
SalColorGet
Syntax Description Parameters nColor = SalColorGet ( hWndColored, nColorIndex ) Gets a window's color. hWndColored nColorIndex Window Handle. The handle (or name) of the window whose color you want. Number. The color of a part of the window, represented by one of these constants: COLOR_IndexCellText COLOR_IndexTransparent COLOR_IndexWindow COLOR_IndexWindowText Return Value nColor is the color returned. It can be user-defined or one of the predefined window colors (excluding COLOR_Default and the three COLOR_Sys* constants). If you specify COLOR_IndexTransparent in the second parameter and the transparent color is not set, SalColorGet returns COLOR_None. See Also SalColorFromRGB SalColorGetSysColor SalColorSet SalColorToRGB
Set nColor = SalColorGet ( hWndItem, COLOR_IndexWindow ) If nColor = COLOR_Default Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Magenta )
Example
2-18
SalColorGetSysColor
SalColorGetSysColor
Syntax Description Parameters nColor = SalColorGetSysColor ( nColorIndex ) Gets a system color. nColorIndex Number. The color of a part of the window, represented by one of these constants: COLOR_SysWindow COLOR_SysWindowFrame COLOR_SysWindowText Return Value See Also nColor is the color returned. It can be one of the predefined windows colors (excluding COLOR_Default, COLOR_None, and the three COLOR_Sys* constants). SalColorFromRGB SalColorGet SalColorSet
SalColorToRGB Set nSysColorBckgrnd = SalColorGetSysColor ( COLOR_SysWindow )
Example
SalColorSet
Syntax Description Parameters bOk = SalColorSet ( hWndToSet, nColorIndex, nColor ) Sets a window's color. hWndToSet nColorIndex Window Handle. The handle (or name) of the window whose color you want to set. Number. The color of a part of the window, represented by one of these constants: COLOR_IndexCellText COLOR_IndexTransparent COLOR_IndexWindow COLOR_IndexWindowText nColor Number. A user-defined value, a value formulated using SalColorFromRGB, or any of the predefined windows colors. To turn off the transparent color, specify COLOR_None.
bOk is TRUE if the function succeeds and FALSE if it fails. SalColorFromRGB SalColorGet
2-19
Chapter 2
SalColorGetSysColor SalColorToRGB Example

Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Red )
SalColorToRGB
Syntax Description Parameters bOk = SalColorToRGB ( nColor, nRed, nGreen, nBlue ) Decomposes a color into red, green, and blue values. nColor Number. A user-defined value or any of the predefined window colors (excluding COLOR_Default, COLOR_None, and the three COLOR_Sys* constants). Receive number. A number from 0 to 255 that represents the red value. Receive number. A number from 0 to 255 that represents the green value. Receive number. A number from 0 to 255 that represents the blue value.
nRed nGreen nBlue Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalColorFromRGB SalColorGet SalColorGetSysColor SalColorSet
If NOT SalColorToRGB ( nColor, nRed, nGreen, nBlue ) ... Error ...
Example
SalComCleanupMode
Syntax Description Parameters void SalComCleanupMode ( bLateCleanup ) Determines when unused COM+ thread resources are cleaned up. bLateCleanup Boolean. A value of FALSE causes a thread to be cleaned up as soon as the last object remaining on that thread is destroyed (early cleanup). A value of TRUE postpones cleanup until the COM+ server application ends (late cleanup). Default SQLWindows behavior is early cleanup. Return Value none.
2-20
SalCompileAndEvaluate
Example
Call SalComCleanupMode ( TRUE )
SalCompileAndEvaluate
Syntax Description nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos, nReturn, strReturn, dtReturn, hWndReturn, bInhibitErrors, strContext ) Evaluates an expression and returns the expression's value in the receive parameter appropriate to its data type. SalCompileAndEvaluate lets you access the value of a variable whose name you do not specify until runtime. strExpression nError nErrorPos nReturn strReturn dtReturn hWndReturn bInhibitErrors String. The expression to evaluate. Receive Number. The error number, if one is returned. Receive Number. The position in strExpression at which an error, if any, occurred. Receive Number. This parameter is set if strExpression evaluates to a number. Receive String. This parameter is set if strExpression evaluates to a string. Receive Date/Time. This parameter is set if strExpression evaluates to a date/time value. Receive Window Handle. This parameter is set if strExpression evaluates to a handle. Boolean. If TRUE, SQLWindows does not report compilation or evaluation errors to the user. Specify TRUE if the application processes its own errors. If FALSE, SQLWindows reports compilation and evaluation errors to the user in a dialog box. String. The handle to an execution context, returned by either SalContextBreak or SalContextCurrent.
Parameters
strContext Return Value
nType is equal to one of the following values if the function succeeds: EVAL_Date EVAL_Handle EVAL_If EVAL_Number EVAL_Set EVAL_String EVAL_Template
2-21
Chapter 2
See Also Example
SalContextBreak SalContextCurrent
Set nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos,nReturn, strReturn, dtReturn, hWndReturn, FALSE, strContext ) If nType = EVAL_Number Call SalNumberToStr ( nReturn, 0, strString )...
SalContextBreak
Syntax Description Parameters Return Value See Also Example strContext = SalContextBreak ( ) Retrieves the context of the most recently executed Break statement. Use this function with SalCompileAndEvaluate. No parameters. strContext serves as the last parameter of the SalCompileAndEvaluate function. SalCompileAndEvaluate SalContextCurrent
Set strContext = SalContextBreak ( )
SalContextCurrent
Syntax Description Parameters Return Value See Also Example strContext = SalContextCurrent ( ) Retrieves the current execution context. Use this function with SalCompileAndEvaluate. No parameters. strContext serves as the last parameter of the SalCompileAndEvaluate function. SalCompileAndEvaluate SalContextBreak
Set strContext = SalContextCurrent ( )
SalContextMenuSetPopup
Syntax Description bOk = ( hWnd, strMenuName, nFlags) Defines a named popup menu that displays automatically when a window receives SAM_ContextMenu.
2-22
SalCreateWindow
For some windows, this function also affects how the window processes a right mouse button click: List box Combo box Table window Parameters Right click selects the line under the cursor. If the line is already selected, there is no effect. For a combo box where the list is always displayed, the behavior is the same as for a list box. Right click selects the row under the cursor. If the row is already selected there is no effect. hWnd strMenuName Window Handle. The handle of the lowest level window that processes messages that the popup menu sends. String. A named menu defined in one of the Named Menus section in hWnd, hWnd's MDI window parent, or Global Declarations. Number. Set this to CM_TableCell to replace the default menu that Windows displays when the mouse pointer is in an editable table window cell. Otherwise, set this to zero.
nFlags
Return Value Example See Also
bOk is TRUE if this function succeeds and FALSE otherwise. No example. SAM_ContextMenu
SalCreateWindow
Syntax Description hWndCreated = SalCreateWindow ( tWndToCreate, hWndOwner, Parm1, Parm2, ... ) Creates modeless dialog boxes, MDI windows, form windows, and top-level table windows at runtime. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters. If you specify an owner (hWndOwner), the new window always displays on top of its owner, closes when its owner closes, and hides when its owner is minimized. SalCreateWindow can pass data to and from the window being created by accepting a variable number of parameters. The data types of these parameters must match the parameter data types of the window being created. You define parameters for the window in the Window Parameters section of the application outline.
2-23
Chapter 2
For example, this code passes the variable, nGlobal and the data field, df1 to the form window, frmMain. Before SAM_Create is sent to frmMain, its first window parameter is initialized with the value of nGlobal and its second window parameter is initialized with the value of df1.
Call SalCreateWindow ( frmMain, hWndNULL, nGlobal, df1 )
You can use window parameters to return information from the window being created by using a receive type. However, you can initialize receive window parameters only with variables. This means that you cannot pass a data field or any other window object to a window parameter that was defined as a receive type. In addition, you cannot use an array variable as a receive parameter. Parameters tWndToCreate Template or String. The name of the window to create. Note: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner Window Handle. The handle (or name) of the owner window. Specify hWndNULL if there is no owner window. Note that if you create a toplevel form inside of a MDI window, then that MDI window will always be the owner of this form. Any SQLWindows data type. The (optional) first of a variable number of window parameters. Any SQLWindows data type. The (optional) second of a variable number of window parameters.
Parm1 Parm2 Return Value See Also Example
hWndCreated is the handle of the new window. SalModalDialog SalDestroyWindow

On SAM_Click If NOT SalCreateWindow (frmCustomer, hWndNULL) ...Error...
SalCreateWindowEx
Syntax Description hWndCreated = SalCreateWindowEx( tWndToCreate, hWndOwner, nLeft, nTop, nWidth, nHeight, nFlags ... ) Creates a form, dialog box or table window as a child of another form or dialog box at runtime. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters.
2-24
SalCreateWindowEx
If you specify an owner (hWndOwner), the new window always displays on top of its owner, closes when its owner closes, and hides when its owner is minimized. SalCreateWindowEx can pass data to and from the window being created by accepting a variable number of parameters. The data types of these parameters must match the parameter data types of the window being created. You define parameters for the window in the Window Parameters section of the application outline. For example, this code passes the variable, nGlobal and the data field, df1 to the form window, frmMain. Before SAM_Create is sent to frmMain, its first window parameter is initialized with the value of nGlobal and its second window parameter is initialized with the value of df1.
Call SalCreateWindowEx ( frmMain, hWndNULL, nLeft, nTop,nWidth, nHeight, nGlobal, df1 )
You can use window parameters to return information from the window being created by using a receive type. However, you can initialize receive window parameters only with variables. This means that you cannot pass a data field or any other window object to a window parameter that was defined as a receive type. In addition, you cannot use an array variable as a receive parameter. Parameters tWndToCreate Template or String. The name of the window to create. Note: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner Window Handle. The handle (or name) of the owner window. Specify hWndNULL if there is no owner window. Note that if you create a toplevel form inside of a MDI window, then that MDI window will always be the owner of this form. Position of the window in form units. Size of the window in form units. The following can be combined with the | operator: CREATE_AsChild Create the windows as a child hWndParent. HWndParent must be a form, dialog box or tool bar. When used with CREATE_AsChild, the window will have a border. The window will be created but not shown.
nLeft, nTop nWidth, nHeight nFlags
CREATE_Border CREATE_Hidden Parm1
Any SQLWindows data type. The (optional) first of a variable number of window parameters.
2-25
Chapter 2
Parm2 Return Value See Also
Any SQLWindows data type. The (optional) second of a variable number of window parameters.
hWndCreated is the handle of the new window. SalModalDialog SalCreateWindow SalDestroyWindow

On SAM_Click If NOT SalCreateWindowEx (frmCustomer, hWndNULL, nLeft, nTop, nWidth, nHeight) ...Error...
Example
SalCursorClear
Syntax Description Parameters bOk = SalCursorClear ( hWnd, nType ) Clears a window's cursor. hWnd nType Window Handle. The handle (or name) of a window. Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorSet SalCursorSetFile SalCursorSetString
On SAM_Click Call SalCursorClear (frmMain, Cursor_Windows)
Example
SalCursorSet
Syntax Description Parameters bOk = SalCursorSet ( hWnd, tResource, nType ) Sets a window's cursor. hWnd tResource Window Handle. The handle (or name) of a window. Template. An icon resource from the Resources section of the outline. Specify one of these system-supplied cursors: CURSOR_Arrow 2-26
SalCursorSetFile
CURSOR_Cross CURSOR_IBeam CURSOR_Icon CURSOR_Size CURSOR_SizeNESW CURSOR_SizeNS CURSOR_SizeNWSE CURSOR_SizeWE CURSOR_UpArrow CURSOR_Wait nType Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorClear SalCursorSetFile SalCursorSetString
On SAM_Click Call SalCursorSet (frmMain, Cursor_Arrow, Cursor_Window)
Example
SalCursorSetFile
Syntax Description Parameters bOk = SalCursorSetFile ( hWnd, sFile, nType ) Sets an application-defined cursor for the specified window. Use this function to set the cursor from an image stored in a file. hWnd sFile nType Window Handle. The handle (or name) of a window. String. The name of a cursor or an icon file. Number. The cursor type. Specify one of these constants:
CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window
bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorClear 2-27
Chapter 2
SalCursorSet SalCursorSetString Example

On SAM_Click Call SalCursorSetFile (frmMain, file1.cne, Cursor_Window)
SalCursorSetString
Syntax Description Parameters bOk = SalCursorSetString ( hWnd, sBuffer, nType ) Sets a window's cursor from a string variable. hWnd sBuffer nType Window Handle. The handle (or name) of a window. String. The image of a cursor or an icon file. Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorClear SalCursorSet SalCursorSetFile
On SAM_Click Call SalCursorSetString (frmMain, strCurBuf, Cursor_Window)
Example
SalDateConstruct
Syntax Description dtDate = SalDateConstruct ( nYear, nMonth, nDay, nHour, nMinute, nSecond ) Returns the date/time constructed from the parameters nYear, nMonth, nDay, nHour, nMinute, and nSecond. If you specify invalid parameter values, an unexpected date construction can result. Note: If any of the parameter values has less than the specified number of digits, SalDateConstruct pads the resulting value with leading zeroes (0). For example, if nYear is 92, dtDate begins with 0092. Parameters nYear nMonth Number. A number with a 4-digit year value greater than zero. Number. A number with a 2-digit month value between 01 and 12 inclusive.
2-28
SalDateConstruct
nDay nHour nMinute nSecond Return Value Example
Number. A number with a 2-digit day value between 01 and 31 inclusive. Number. A number with a 2-digit hour value between 0 and 23 inclusive. Number. A number with a 2-digit minute value between 01 and 59 inclusive. Number. A number with a 2-digit second value between 01 and 59 inclusive.
dtDate is the newly constructed date/time value.

On SAM_Create Set dtDeb = SalDateConstruct (1996, 1, 1, 10, 30, 1)
2-29
Chapter 2
SalDateCurrent
Syntax Description dtNow = SalDateCurrent ( ) Returns the PC's current date/time. To get the database server's system date/ time, use a database system keyword (SYSDATE, SYSTIME, or SYSDATETIME ) in a SQL SELECT statement. Parameters Return Value Example No parameters. dtNow is the PC's current date/time.
On SAM_Create Set dfCurrent = SalDateCurrent ( )
SalDateDay
Syntax Description Parameters Return Value See Also nDay = SalDateDay ( dtDateTime ) Returns the day portion (1 to 31) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nDay is a number between 1 and 31. SalDateMonth SalDateYear
Example
Set nDay = SalDateDay ( dtDateTime )
SalDateHour
Syntax Description Parameters Return Value See Also nHour = SalDateHour ( dtDateTime ) Returns the hour portion (0 to 23) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nHour is a number between 0 and 23. SalDateMinute SalDateSecond
Example
Set nHour= SalDateHour ( dtDateTime )
SalDateMinute
2-30
SalDateMonth
Syntax Description Parameters Return Value See Also
nMinute = SalDateMinute ( dtDateTime ) Returns the minute portion (0 to 59) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nMinute is a number between 0 and 59. SalDateHour SalDateSecond
Example
Set nMinute = SalDateMinute ( dtDateTime )
SalDateMonth
Syntax Description Parameters Return Value nMonth = SalDateMonth ( dtDateTime ) Returns the month portion (1 to 12) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nMonth is a number between 1 and 12.
Related Functions SalDateDay SalDateYear Example

Set nMonth = SalDateMonth ( dtDateTime )
SalDateMonthBegin
Syntax Description dtMonthBegin = SalDateMonthBegin ( dtDateTime ) Returns the date of the first day of the month or it returns DATETIME_Null if the value you specify is null. For example, if dtDateTime is December 25, 1992, SalDateMonthBegin returns December 1, 1992. dtDateTime Date/Time. A date/time value.
dtMonthBegin is the date of the first day of the month of dtDateTime. SalDateQuarterBegin SalDateWeekBegin
Set dtMonthBegin = SalDateMonthBegin ( SalDateCurrent ( ) )
2-31
Chapter 2
SalDateQuarter
Syntax Description Parameters Return Value Example nQuarter = SalDateQuarter ( dtDateTime ) Returns the quarter of the year (1 to 4) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nQuarter is a number between 1 and 4.

Select Case ( SalDateQuarter ( dtDate ) ) Case 1 Set strQuarter = 'First Quarter' Break ...
SalDateQuarterBegin
Syntax Description Parameters Return Value See Also dtQuarterBegin = SalDateQuarterBegin ( dtDateTime ) Returns the date of the first day of the quarter of a date/time value or it returns DATETIME_Null if the value you specify is null. dtDateTime Date/Time. A date/time value.
dtQuarterBegin is the first day of the quarter of dtDateTime. SalDateMonthBegin SalDateWeekBegin SalDateYearBegin
Set dtQuarterBegin = SalDateQuarterBegin ( SalDateCurrent ( ) )
Example
SalDateSecond
Syntax Description Parameters Return Value See Also nSeconds = SalDateSecond ( dtDateTime ) Returns the seconds portion (0 to 59) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nSeconds is a number between 0 and 59. SalDateHour SalDateMinute
2-32
SalDateToStr
Example
Set nSeconds = SalDateSecond ( dtDateTime )
SalDateToStr
Syntax Description Parameters nLength = SalDateToStr ( dtDateTime, strDate ) Converts a date/time value to a string value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime strDate Return Value See Also Example Date/Time. The date/time value to convert. Receive string. The resulting string value.
nLength is the length of strDate. SalFmtFormatDateTime SalStrToDate

Call SalDateToStr ( dtDateTime, strDateTime ) ! strDateTime = YYYY-MM-DD-HH.MM.SS.TTTTTT
SalDateWeekBegin
Syntax Description Parameters Return Value See Also dtWeekBegin = SalDateWeekBegin ( dtDateTime ) Returns the date of the previous Monday or the current day if it is a Monday or it returns DATETIME_Null if the value you specify is null. dtDateTime Date/Time. A date/time value.
dtWeekBegin is the date of the previous Monday, or today's date if it is Monday. SalDateMonthBegin SalDateQuarterBegin SalDateYearBegin
Set dtWeekBegin = SalDateWeekBegin ( SalDateCurrent ( ) )
Example
SalDateWeekday
Syntax Description nWeekday = SalDateWeekday ( dtDateTime ) Returns the day of the week as a number between 0 and 6 or returns -1 if you specify DATETIME_Null as a parameter. 0 represents Saturday, 1 represents Sunday, and so on. dtDateTime Date/Time. A date/time value.
Parameters Return Value
2-33
Chapter 2
nWeekday is a number between 0 and 6. Example

Select Case ( SalDateWeekday ( dtDate ) ) Case 0 Set strWeekday = 'Saturday' Break
SalDateYear
Syntax Description Parameters Return Value See Also Example nYear = SalDateYear ( dtDateTime ) Returns the year portion of a date or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nYear is the year portion of a date. SalDateDay SalDateMonth

Set nYear = SalDateYear ( dtDateTime )
SalDestroyWindow
Syntax Description bOk = SalDestroyWindow ( hWndDestroy ) Destroys a form window, a top-level table window, or a modeless dialog box created with SalCreateWindow. In the case of a form window or top-level table window, you can have automatically created it at runtime. hWndDestroy Window Handle. The handle (or name) of the window to destroy.
bOk is TRUE if the function succeeds and FALSE if it fails. SalCreateWindow SalEndDialog
On SAM_Click Call SalDestroyWindow ( hWndForm )
SalDisableWindow
Syntax Description bOk = SalDisableWindow ( hWndDisable ) Disables keyboard and mouse input to a window.
2-34
SalDisableWindowAndLabel
If the window contains text (for example, a push button), the text is grayed. If the window is a data field, it cannot receive the focus. Parameters Return Value See Also hWndDisable Window Handle. The handle (or name) of the window to disable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDisableWindowAndLabel SalEnableWindow SalIsWindowEnabled
On SAM_Create Call SalDisableWindow ( pbUpdate )
Example
SalDisableWindowAndLabel
Syntax Description bOk = SalDisableWindowAndLabel ( hWndDisable ) Disables keyboard and mouse input to a window and grays out its associated label. A label is the background text that immediately precedes the window in the outline. The bacground text must have a mneumonic. If the window contains text (for example, a push button), the text is grayed. If the window is a data field, it cannot receive the focus. Parameters Return Value See Also hWndDisable Window Handle. The handle (or name) of the window to disable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDisableWindow SalEnableWindowAndLabel SalIsWindowEnabled SalGetWindowLabelText SalHideWindowAndLabel SalSetWindowLabelText SalShowWindowAndLabel
Example
Call SalDisableWindow ( dfName )
2-35
Chapter 2
SalDlgChooseColor
Syntax Description bRet = SalDlgChooseColor ( hWndOwner, nColor ) Displays the Windows Color dialog box where the user can either select an existing color or create a new one. See the Control Panel chapter in the Microsoft Windows' User's Guide for a detailed description of the Color dialog box. Parameters hWndOwner nColor Return Value See Also Example Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. Receive Number. The RGB value of the color the user selects.
bRet is TRUE if the user selects a color and FALSE if the user clicks the Cancel push button. SalDlgChooseFont
On SAM_Click Call SalDlgChooseColor ( frmMain, nColor )
SalDlgChooseFont
Syntax Description bRet = SalDlgChooseFont ( hWndOwner, strFontName, nSize, nEnhancements, nColor ) Displays the Windows Font dialog box where the user can choose a font as well as its size, style, enhancements, display color, and so on. See the Control Panel chapter in the Microsoft Windows' User's Guide for a detailed description of the Font dialog box. Parameters hWndOwner strFontName nSize nEnhancements nColor Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. Receive String. The name of the font the user selects. Receive Number. The size of the font the user selects. Receive Number. The font enhancements (italic, bold, and so on), if any, that the user selects. Receive Number. Specify the initial text color. When SalDlgChooseFont returns, nColor is the text color that the user selects.
Return Value
bRet is TRUE if the user chooses a font and FALSE if the user clicks the Cancel push button.
2-36
SalDlgGetDockStatus
See Also Example
SalDlgChooseColor
Call SalDlgChooseFont ( frmMain, strFontName, nSize, nEnhancements )
SalDlgGetDockStatus
Syntax Description Parameters bOk = SalDlgGetDockStatus ( hWndDlg, nOrientation ) Returns information about the current docking orientation of a dialog box. hWndDlg nOrientation Window Handle. The handle (or name) of the dialog box. Receive Number. A docking orientation flags as described below. DOCK_Top: the dialog box is currently docked to the top edge of its parent window. DOCK_Bottom: the dialog box is currently docked to the bottom edge of its parent window. DOCK_Left: the dialog box is currently docked to the left edge of its parent window. DOCK_Right: the dialog box is currently docked to the right edge of its parent window. DOCK_None: the dialog box is not currently docked - it is free floating. Return Value See Also Example bRet is TRUE if the dialog box is found and FALSE if an error occurs. SalDlgSetDockStatus, SalWindowGetDockSettings
Call SalDlgGetDockStatus ( dlgPrompt, nDock )
SalDlgOpenFile
Syntax Description Parameters bRet = SalDlgOpenFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex, strFile, strPath ) Displays a Windows dialog box where the user can select a file to open. hWndOwner strDlgTitle strFilters Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. String. The title of the Open file dialog box. String. An array of file filters and their descriptions. Each filter must have a description that precedes the filter in the array.
2-37
Chapter 2
For example, to enable users to open files with only specific extensions, populate the strFilters array with filters such as:
Set strFilters[0] = 'Executable Files' Set strFilters[1] = '*.exe' Set strFilters[2] = 'Dynamic Link Libraries' Set strFilters[3] = '*.dll' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini'
nFilters
Number. The number of elements in strFilters. The above array of six elements contains three filters. Specify 6 to display all three filters. You can limit the number of filters displayed. For example, to display only the first two filters (*.exe and *.dll), specify 4.
nIndex
Receive Number. The filter that the user chooses. For example, if the user chooses Initialization Files, nIndex is 3. The default filter is always the first filter in strFilters. Receive String. The file name the user chooses. To initialize the combo box in which the file names display, assign a file name to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, SQLWindows ignores your attempt to set the default display value.
strFile
strPath
Receive String. The full path name of the file the user chooses. To initialize the combo box in which the paths display, assign a path to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, SQLWindows ignores your attempt to set the default display value.
bRet is TRUE if the user specifies a file name and FALSE if the user clicks the Cancel push button. SalDlgSaveFile
Message Actions On SAM_Create Set strFilters[0] = 'Dynamic Link Libraries'
2-38
SalDlgSaveFile
Set strFilters[1] = '*.dll' Set strFilters[2] = 'Executable Files' Set strFilters[3] = '*.exe' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini' strFilters, 6, nIndex, strFile, strPath) Call SalDlgOpenFile ( frmMain, 'Open File', strFilters, 6, nIndex, strFile, strPath)
SalDlgSaveFile
Syntax Description bRet = SalDlgSaveFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex, strFile, strPath ) Displays a Windows dialog box where the user can save a file. If you do not specify a file extension, SQLWindows saves the file with the extension displayed by the Save File as Type combo box. Parameters hWndOwner strDlgTitle strFilters Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. String. The title of the Save file dialog box. String. An array of file filters and their descriptions. Each filter must have a description that precedes the filter in the array. For example, to enable users to save files with only specific extensions, populate the strFilters array with filters such as:
Set strFilters[0] = 'Executable Files' Set strFilters[1] = '*.exe' Set strFilters[2] = 'Dynamic Link Libraries' Set strFilters[3] = '*.dll' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini'
nFilters
Number. The number of elements in strFilters. The above array of six elements contains three filters. Specify 6 to display all three filters. You can limit the number of filters that display. For example, to see only the first two filters (*.exe and *.dll), specify 4.
nIndex
Receive Number. The filter that the user chooses. This reflects the format in which SQLWindows saves the file.
2-39
Chapter 2
A file's extension does not imply format. By default, if the user does not specify a file extension, SQLWindows saves the file with the first extension in strFilters. In this case, the default file extension is .EXE. For example, if the user chooses Dynamic Link Libraries, but does not specify a file extension, the file is saved in DLL format but with an .EXE extension. strFile Receive String. The file name the user chooses. To initialize the combo box in which the file names display, assign a file name to a variable prior to calling SalDlgSaveFile. In the subsequent SalDlgSaveFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, SQLWindows ignores your attempt to set the default display value. strPath The full path name of the file the user chooses. To initialize the combo box in which the paths display, assign a path name to a variable prior to calling SalDlgSaveFile. In the subsequent SalDlgSaveFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, SQLWindows ignores your attempt to set the default display value. Example
Message Actions On SAM_Create Set strFilters[0] = 'Dynamic Link Libraries' Set strFilters[1] = '*.dll' Set strFilters[2] = 'Executable Files' Set strFilters[3] = '*.exe' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini' On SAM_Click Call SalDlgSaveFile ( frmMain, 'Save File', strFilters, 6,nIndex, strFile, strPath )
SalDlgSetDockStatus
Syntax Description bOk = SalDlgSetDockStatus ( hWndDlg, nOrientation ) Sets the current docking orientation of a dialog box. For this function to succeed, the dialog box must have been designated as modeless and Allow Dock to Parent = Yes
2-40
at design time. Even dialogs designed this way are initially free-floating when created, and must be explicitly docked using this function if you wish to dock them immediately. The success of this function also depends on whether the parent window permits docking on the edges requested in the nOrientation parameter - see SalWindowGetDockSettings. Parameters hWndDlg nOrientation Window Handle. The handle (or name) of the dialog box. Number. One of the docking orientation flags as described below. DOCK_Top: the dialog box attempts to dock to the top edge of its parent window. DOCK_Bottom: the dialog box attempts to dock to the bottom edge of its parent window. DOCK_Left: the dialog box attempts to dock to the left edge of its parent window. DOCK_Right: the dialog box attempts to dock to the right edge of its parent window. DOCK_None: the dialog box becomes undocked - it is free floating. Return Value See Also Example bRet is TRUE if the docking operation is successful and FALSE if an error occurs. SalDlgGetDockStatus, SalWindowGetDockSettings
Call SalDlgSetDockStatus ( dlgPrompt, DOCK_Top )
SalDragDropDisableDrop
Syntax bOk = SalDragDropDisableDrop ( ) Disables dropping while in drag mode. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropEnableDrop
On SAM_Click Call SalDragDropDisableDrop ()
SalDragDropEnableDrop
2-41
Chapter 2
Syntax Description Parameters Return Value See Also Example
bOk = SalDragDropEnableDrop ( ) Enables dropping while in drag mode. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropDisableDrop
On SAM_Click Call SalDragDropEnableDrop ()
SalDragDropGetSource
Syntax Description Parameters bOk = SalDragDropGetSource ( hWndSource, nX, nY ) Retrieves the handle of the source window and the location of the mouse in that window when you initiated drag mode. hWndSource Receive Window Handle. The handle of the source window. These window types can be source windows: Combo box Data field List box nX nY Return Value See Also Example Multiline field Picture Table window
Receive Number. The position of the mouse on the X axis. Receive Number. The position of the mouse on the Y axis.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropGetTarget

On SAM_Click Call SalDragDropGetSource (hWndSource,nX, nY)
SalDragDropGetTarget
Syntax Description Parameters bOk = SalDragDropGetTarget ( hWndTarget, nX, nY ) Retrieves the handle of the target window and the location of the mouse in that window. hWndTarget Receive Window Handle. The handle of the target window.
2-42
SalDragDropStart
Any SQLWindows window type can be a target window, however windows without actions (such as frames) do not receive SAM_Drag* messages. nX nY Return Value See Also Example Receive Number. The position of the mouse on the X axis. Receive Number. The position of the mouse on the Y axis.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropGetSource

On SAM_Click Call SalDragDropGetTarget (hWndRecv,nX, nY)
SalDragDropStart
Syntax Description Parameters Return Value See Also Example bOk = SalDragDropStart ( hWndSource ) Initiates drag mode. You must have one of the mouse buttons (left, middle, right) depressed. hWndSource Window Handle. The handle (or name) of a window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropStop

On SAM_Click Call SalDragDropStart (frmMain)
SalDragDropStop
Syntax Description Parameters Return Value See Also Example bOk = SalDragDropStop ( ) Ends drag mode. No parameter. bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropStart
Set bOk = SalDragDropStop ( )
SalDrawMenuBar
Syntax bOk = SalDrawMenuBar ( hWndForm )
2-43
Chapter 2
Description
Redraws the menu bar for a given form window or top-level table window. Call this function to cause top-level menu items to be enabled or disabled. For a top-level menu item or pop-up menu, an Enabled when variable is only evaluated when you call SalDrawMenuBar or when the menu bar is redrawn for other reasons.
Parameters Return Value Example
hWndForm
Window Handle. The handle (or name) of the form window or top-level table window whose menu bar you want to redraw.
bOk is TRUE if the function succeeds and FALSE if it fails.

On SAM_Click Call SalDrawMenuBar ( frmMain)
SalDropFilesAcceptFiles
Syntax Description Parameters bOk = SalDropFilesAcceptFiles ( hWnd, bAccept ) Indicates whether a window can accept a file from Windows' File Manager. hWnd bAccept Window Handle. The handle (or name) of a window. Boolean. Specify whether hWnd can accept a file from Windows' File Manager. The default for editable pictures is TRUE; the default for all other window types is FALSE. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalDropFilesQueryFiles SalDropFilesQueryPoint
Set bAccept = SalDropFilesAcceptFiles ( hWnd, TRUR )
SalDropFilesQueryFiles
Syntax Description nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles ) Retrieves the names of the files dropped on a window. Receipt of the SAM_DropFilesmsg_SAM_DropFiles message indicates that the user dropped files onto the window. hWndSource sArrayFiles Window Handle. The handle (or name) of the window on which the files were dropped. Receive String Array. The names of the dropped files.
Parameters
2-44
SalDropFilesQueryFiles
Return Value
nFiles is the number of dropped files if the function succeeds and zero (0) if the function fails. SalDropFilesQueryFiles fails unless it is called as the result of receiving the SAM_DropFiles message. SalDropFilesAcceptFiles SalDropFilesQueryPoint
On SAM_Click Set nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )
See Also Example
2-45
Chapter 2
SalDropFilesQueryPoint
Syntax Description bOk = SalDropFilesQueryPoint ( hWnd, nX, nY ) Finds the location of the mouse in a window at the time that the user dropped files onto the window. Receipt of the SAM_DropFiles message indicates that the user dropped files onto the window. hWnd nX nY Return Value See Also Example Window Handle. The handle (or name) of the window on which files were dropped. Receive Number. The location of the mouse on the X axis. Receive Number. The location of the mouse on the Y axis.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalDropFilesAcceptFiles SalDropFilesQueryFiles
On SAM_Click Call SalDropFilesQueryPoint ( hWnd, nX, nY )
SalEditCanCopyTo
Syntax Description bOk = SalEditCanCopyTo ( ) This function returns TRUE if an editable picture has the focus and contains an object that can be copied to a file. You can use this function in the Enabled When section for a Copy To menu item. No parameters. bOk is TRUE if an editable picture has the focus and contains an object, and FALSE otherwise. bOk is TRUE even when the picture's contents are not the result of a Paste From operation. SalEditCopyTo
Menu Popup Menu: &Edit Menu Item: &Copy To ... Menu Settings Enabled when: SalEditCanCopyTo ( )
See Also Example
2-46
SalEditCanCut
SalEditCanCut
Syntax Description bOk = SalEditCanCut ( ) This function returns TRUE if the data in a data field, multiline field, table window column, or editable picture is selected. You can use this function in the Enabled When section for a Cut menu item. No parameters. bOk is TRUE if data is selected and FALSE otherwise. SalEditCut
Menu Settings Enabled when: SalEditCanCut ( ) ...
SalEditCanPaste
Syntax Description bOk = SalEditCanPaste ( ) This function returns TRUE if there is data on the Clipboard that can be pasted into the editable picture with the focus. You can use this function in the Enabled When section for a Paste menu item.
No Parameters Return Value bOk is TRUE if there is data on the Clipboard to be pasted and FALSE otherwise. See Also Example SalEditPaste
Menu Settings Enabled when: SalEditCanPaste ( )
SalEditCanPasteFrom
Syntax Description Parameters Return Value bOk is TRUE if an editable picture has the focus and FALSE otherwise. See Also SalEditPasteFrom
bOk = SalEditCanPasteFrom ( ) This function returns TRUE if an editable picture has the focus. You can use this function in the Enabled When section for a Paste From menu item. No parameters.
2-47
Chapter 2
Example
Menu Settings Enabled when: SalEditCanPasteFrom ( )
SalEditCanUndo
Syntax Description bOk = SalEditCanUndo ( ) This function returns TRUE if there is any editing of a data field, multiline field, table window column, or picture that can be undone. You can use this function in the Enabled When section for an Undo menu item.
No Parameters Return Value See Also Example bOk is TRUE if there is any editing to undo and FALSE otherwise. SalEditUndo
Menu Settings Enabled when: SalEditCanUndo ( ) ...
SalEditClear
Syntax Description Parameters Return Value Example bOk = SalEditClear ( ) Deletes selected data from the data field, multiline field, table window column, or picture with the focus. SQLWindows places deleted data in Windows' undo buffer. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails.
Menu Settings Enabled when: SalEditCanCut ( )
SalEditCopy
Syntax Description Parameters Return Value Example bOk = SalEditCopy ( ) Copies selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails.
2-48
SalEditCopyString
... Menu Actions Call SalEditCopy ( )
SalEditCopyString
Syntax Description Parameters Return Value See Also Example bOk = SalEditCopyString ( strString ) Copies a string to the Clipboard as text. strString String. The string to copy to the Clipboard.
bOk is TRUE if the function succeeds and FALSE if it fails. SalEditPasteString

Menu Actions Call SalEditCopyString ( mlNotes )
SalEditCopyTo
Syntax Description bOk = SalEditCopyTo ( ) Copies an object to a file from an editable picture. The picture must have the focus. This function only works when the picture's contents are the result of a Paste From operation. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCanCopyTo SalEditPasteFrom
Menu Actions Call SalEditCopyTo ( )
SalEditCut
Syntax Description Parameters Return Value bOk = SalEditCut ( ) Cuts selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails.
2-49
Chapter 2
See Also Example
SalEditCanCut
SalEditPaste
Syntax Description Parameters Return Value See Also Example bOk = SalEditPaste ( ) Pastes data from the Clipboard into the data field, multiline field, table window column, or picture with the focus. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCanPaste
Menu Actions Call SalEditPaste ( )
SalEditPasteFrom
Syntax Description bOk = SalEditPasteFrom ( ) Copies a file to the editable picture with the focus. This function displays the Paste From dialog box where the user can select a file to paste into the picture. The user can retrieve these file types:
Type BMP DIB GIF ICON PCX TIFF JPEG WMF . .dib .gif .ico .pcx .tif *.jpg .wmf File Extension Description Device-Independent Bitmap Device-Independent Bitmap Graphics Interchange Format Icon File Paintbrush Tag Image File Format JPEG format Windows MetaFile
2-50
SalEditPasteString
The user can select a file of any type, even if the file type is not listed above. SQLWindows still pastes it into the picture using a generic document icon for its image. The file contents are available to the application through the SalPicGetString function. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCanPasteFrom
Menu Actions Call SalEditPasteFrom ( )
SalEditPasteString
Syntax Description Parameters Return Value See Also Example bOk = SalEditPasteString ( strString ) Pastes the contents of the Clipboard into the specified string in text format. strString Receive String. The string into which the contents of the Clipboard are pasted.
bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCopyString

Call SalEditPasteString ( strOldClipboard )
SalEditUndo
Syntax Description bOk = SalEditUndo ( ) Undoes the last edit to a data field, multiline field, table window column, or picture. Editing that you can undo includes inserting text, cutting text, clearing text, and pasting text. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCanUndo
Menu Settings Enabled when: SalEditCanUndo ( )
SalEnableWindow
Syntax bOk = SalEnableWindow ( hWndEnable )
2-51
Chapter 2
Description Parameters Return Value See Also
Enables keyboard and mouse input to a window. hWndEnable Window Handle. The handle (or name) of the window to enable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDisableWindow SalEnableWindowAndLabel SalIsWindowEnabled
Call SalEnableWindow ( frmCustomer )
Example
SalEnableWindowAndLabel
Syntax Description bOk = SalEnableWindowAndLabel ( hWndEnable ) Enables keyboard and mouse input to a window and enables its associated label as well. A label is the background text that immediately precedes the window in the outline. Parameters Return Value See Also hWndEnable Window Handle. The handle (or name) of the window to enable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDisableWindowAndLabel SalEnableWindow WindowEnabled
On SAM_Click Call SalEnableWindowAndLabel ( dfName )
Example
SalEndDialog
Syntax Description Parameters bOk = SalEndDialog ( hWndModal, nReturn ) Destroys a modal dialog box and returns control to the caller of SalModalDialog. hWndModal nReturn Return Value See Also Example 2-52 Window Handle. The handle (or name) of the modal dialog box to destroy. Number. The Return Value from the SalModalDialog function.
bOk is TRUE if the function succeeds and FALSE if it fails. SalModalDialog

On SAM_Click
SalEndTrace
Call SalEndDialog ( hWndForm, 0 )
SalEndTrace
Syntax Description Parameters Return Value See Also SalEndTrace ( ) Ends all tracing. Any calls to SalTrace() made after this function is called will be ignored. none none. SalStartTrace SalTrace Example No example
SalEventLogSetName
Syntax Description bOk = SalEventLogSetName ( strName ) Changes the source name in the event log viewer. If the Event Log capability has not yet been initialized, either by SalUseEventLog( ) or SalStartTrace( TRACE_Event ..) then SQLWindows creates an Event Log object with that uses the strName set. The Event Log object will not be used until SalUseEventLog( ) or SalStartTrace( ) with the output set to TRACE_Event are called. The object will remain instantiated until the application is closed or SalUseEventLog(FALSE .) is called. Windows 98, Windows ME, and Linux do not have built in event logging. The name specified in strName will be used as the log file name only if registry key HKEY_CURRENT_USER\Software\Gupta\SQLWindows 4.0\EventLogFile, value LogFilePath has not been set (as described in function SalUseEventLog). Parameters Return Value See Also strName String. The name to use as the source in the event log.
bOk is TRUE if the function succeeds and FALSE if it fails SalStartTrace SalTrace
Example
No example
SalFileClose
2-53
Chapter 2
Syntax Description Parameters Return Value See Also Example
bOk = SalFileClose ( hFile ) Closes a file. hFile Receive file handle. The handle of the file to close. When the function returns, the value of this parameter becomes null.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileOpen

If NOT SalFilePutStr ( hFile, sLine ) Call SalFileClose ( hFile ) Call SalMessageBeep ( 0 )
SalFileCopy
Syntax Description Parameters nStatus = SalFileCopy ( strSourcePath, strDestPath, bOverWrite ) Copies the contents of one file (source) to another file (destination). strSourcePath strDestPath bOverWrite String. The full path name of the source file. String. The full path name of the destination file. Boolean. Specifies whether (TRUE) or not (FALSE) to overwrite the destination file. If the destination file already exists and bOverWrite is FALSE, then SalFileCopy fails, and returns FILE_CopyExist. If the destination file already exists and bOverWrite is TRUE, then SalFileCopy succeeds and the destination file is overwritten. Return Value nStatus is equal to one of the following values: FILE_CopyDest FILE_CopyExist FILE_CopyOK FILE_CopyRead FILE_CopySrc FILE_CopyWrite Example
On SAM_AppStartup Set bLogFileSaved = SalFileCopy ( 'C:\\DB\\APP.LOG', ('C:\\DB\\APP.OLD', TRUE )
2-54
SalFileCreateDirectory
SalFileCreateDirectory
Syntax Description Parameters Return Value See Also Example bOk = SalFileCreateDirectory ( strDir ) Creates a directory. strDir String. The full path name of the new directory.
bOk is TRUE if the function succeeds and FALSE if a directory or file with the specified name already exists, or if the specified path to the directory cannot be found. SalFileRemoveDirectory
Set DirCreated = SalFileCreateDirectory('C:\\NOTES\\REL2' )
SalFileGetC
Syntax Description bOk = SalFileGetC ( hFile, nChar ) Returns the next character in an open file. You must use this function in place of the SalFileGetChar function if the file contains non-ASCII (ANSI) or 16-bit characters. If the character returned is a 16-bit character, the lead byte of the character is in the high-order byte, and the trail byte is in the low-order byte. To get the lead byte, use SalNumberHighand to get the trail byte, use SalNumberLow. Parameters hFile nChar Return Value See Also Example File Handle. The handle of the open file. Receive Number. The next character in hFile.
bOk is TRUE if the function succeeds and FALSE if the function is unable to read the next character from the file, or if an invalid file handle is passed in hFile. SalFilePutC
On SAM_AppStartup Call SalFileOpen ( hFile, 'C:\\DB\\APP.LOG', OF_Read | OF_Binary )
SalFileGetChar
Syntax Description Parameters Return Value nChar = SalFileGetChar ( hFile ) Returns the next character in an open file. hFile File Handle. The handle of the open file.
nChar is a number that represents an ANSI character. At the end of the file, SalFileGetChar returns a -1.
2-55
Chapter 2
See Also Example
SalFilePutChar
If SalFileOpen ( fhDestFile, strDestFile, OF_Create | OF_ReadWrite ) Loop Set nChar = SalFileGetChar ( fhSrcFile ) ...
SalFileGetCurrentDirectory
Syntax Description Parameters Return Value See Also Example bOk = SalFileGetCurrentDirectory ( strPath ) Gets the full path name of the current working directory. strPath Receive String. The full path name, including the drive letter, of the current working directory.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileSetCurrentDirectory

On SAM_AppStartup If NOT SalFileGetCurrentDirectory directory', 'Error', 0 ) (strCurrentDir) Call SalMessageBox ( 'Couldn't get current
SalFileGetDateTime
Syntax Description Parameters bOk = SalFileGetDateTime ( strFilename, dtDateTime ) Gets the modification date and time of the specified file. strFilename dtDateTime Return Value See Also Example String. The name of the file whose modification date you want. Receive Date/Time. The modification date and time of strFilename.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileSetDateTime

Set bOk = SalFileGetDateTime ( 'WIN.INI', gdFileDate )
2-56
SalFileGetDrive
SalFileGetDrive
Syntax Description No Parameters Return Value See Also Example strDriveLetter is a string identifying the current disk drive. The first character is a letter between A and Z, and the second character is a colon(:). SalFileSetDrive
On SAM_AppStartup If SalFileGetDrive ( ) = 'A' Set blsDriveA = TRUE Else Set blsDriveA = FALSE
strDriveLetter = SalFileGetDrive ( ) Gets the letter of the default (current) disk drive.
SalFileGetStr
Syntax Description Parameters bOk = SalFileGetStr ( hFile, strBuffer, nBufferSize ) Returns the next line from an open file. SQLWindows strips off the trailing carriage return/line feed of the returned string. hFile strBuffer nBufferSize Return Value See Also Example File Handle. The handle of the open file. Receive String. The returned string. Number. The maximum number of bytes to read.
bOk is TRUE if the file is successfully read and FALSE otherwise. FALSE is also returned on end of file. SalFilePutStr
If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE ) Call SalFilePutStr ( fhDestFile, strText ) Else Break
2-57
Chapter 2
SalFileOpen
Syntax Description Parameters bOk = SalFileOpen ( hFile, strFileName, nStyle ) Opens, re-opens, creates, or deletes a file. hFile strFileName nStyle Receive File Handle. The handle of the open file. String. The name of the file to open, create, delete, or test. Number. A constant that specifies the style in which to open the file. nStyle can be one or more styles combined using the bitwise OR (|) operator.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileClose

SalListFiles SalFileOpenExt
Example
Call SalFileOpen ( fhSrcFile, strSrcFile, OF_Read )
SalFileOpenExt
Syntax Description Parameters bOk = SalFileOpenExt ( hFile, strFileName, nStyle, strReopen) Opens or re-opens a file. Long filenames up to 260 characters is supported. hFile strFileName nStyle Receive File Handle. The handle of the opened or re-opened file. String. The name of the file to open, create, delete, or test. Number. A constant that specifies the style in which to open the file. nStyle can be one or more styles combined using the OR (|) operator. Receive String. Information used to re-open the file.
strReopen Return Value See Also Example
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileOpenF

On SAM_Create If SalFileOpenExt ( hFile, 'C:\\AUTOEXEC.BAT', OF_Read, strReopen )
2-58
SalFilePutC
SalFilePutC
Syntax Description Parameters bOk = SalFilePutC ( hFile, nChar ) Writes a character to an open file. Use this function instead of SalFilePutChar if the character is a non-ASCII (ANSI) or 16-bit character. hFile nChar Return Value See Also Example File Handle. The handle of the open file. Number. The non-ASCII or 16-bit numeric value of the character to write to hFile.
bOk is TRUE if the function succeeds and FALSE if it is unable to write to hFile. SalFileGetC
Loop Call SalFilePutC ( hFile, nNull ) If nCount = 5 Break Set nCount = nCount + 1
SalFilePutChar
Syntax Description Parameters bOk = SalFilePutChar ( hFile, nChar ) Writes a character to an open file. hFile nChar Return Value See Also Example File Handle. The handle of the open file. Number. The ANSI numeric value of the character to write to hFile.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileGetChar

Call SalFileSeek (fhInFile, nFilePos, FILE,_SeekBegin) Call SalFilePutChar ( hFile, nChar )
2-59
Chapter 2
SalFilePutStr
Syntax Description Parameters bOk = SalFilePutStr ( hFile, strString ) Writes a string to an open file. SQLWindows appends a carriage return/line feed character to the string. hFile strString Return Value See Also Example File Handle. The handle of the open file. String. The string to write.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileGetStr

Loop ! Read each line from the source file and write it to the destination file If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE ) Call SalFilePutStr ( fhDestFile, strText )
SalFileRead
Syntax Description Parameters nResult = SalFileRead ( hFile, strBuffer, nBufferLength ) Reads a buffer of characters from an open file to a string . hFile strBuffer nBufferLength Return Value See Also Example File Handle. The handle of the open file. Receive String. The string to which the data is read. Number. The number of bytes to read.
nResult is the number of bytes read. On end of file, SalFileRead returns a byte count less than the requested amount. SalFileWrite
Call SalFileSeek ( fhInFile, nFilePos, FILE_SeekBegin ) Loop Set nCharsRead = SalFileRead ( fhInFile, strBuffer, nRecSize )
2-60
SalFileRemoveDirectory
SalFileRemoveDirectory
Syntax Description Parameters Return Value See Also Example bOk = SalFileRemoveDirectory ( strDir ) Deletes a directory. strDir String. The full path name of the directory to delete.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileRemoveDirectory also returns FALSE if strDir contains files or other directories. SalFileCreateDirectory
On SAM_AppStartup Set bNotesOldDeleted = SalFileRemoveDirectory (strDir)
SalFileSeek
Syntax Description Parameters bOk = SalFileSeek ( hFile, nBytes, nPosition ) Positions the file pointer in an open file. The next file operation (such as a read or write) takes place at this new location. hFile nBytes File Handle. The handle of an open file. Number. The specific position of the file pointer; the number of bytes from nPosition where the next file operation will take place. Number. The general position of the file pointer; one of the following values:
FILE_SeekBegin FILE_SeekCurrent FILE_SeekEnd
nPosition
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileTell

Call SalFileSeek ( fhInFile, 0, FILE_SeekBegin )
2-61
Chapter 2
SalFileSetCurrentDirectory
Syntax Description bOk = SalFileSetCurrentDirectory ( strPath ) Changes the current working directory. If the specified path does not contain a drive letter, the default drive's current directory is changed. Otherwise, the specified drive's current directory is changed without making that drive current. strPath String. The path name of the new current working directory.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileGetCurrentDirectory SalFileSetDrive
On SAM_AppStartup Set DirOk = SalFileSetCurrentDirectory ('C:\\NOTES\\REL2' )
SalFileSetDateTime
Syntax Description Parameters bOk = SalFileSetDateTime ( strFilename, dtDateTime ) Sets the modification date and time of the specified file. strFilename dtDateTime Return Value See Also Example String. The name of the file whose modification date you want to set. Date/Time. The modification date and time.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileGetDateTime

On SAM_Click Set bOk = SalFileSetDateTime ('SQL.INI', SalDateCurrent ( ))
SalFileSetDrive
Syntax Description Parameters bOk = SalFileSetDrive ( strDriveLetter ) Sets the current disk drive to the specified drive letter. strDriveLetter String.0 The new disk drive letter. The length of this parameter's value is one character. If you specify a value larger than this, SQLWindows reads only the first character.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileGetDrive
2-62
SalFileTell
SalFileSetCurrentDirectory Example
On SAM_AppStartup Set bDriveIsC = SalFileSetDrive ( 'c' )
SalFileTell
Syntax Description Parameters Return Value See Also Example nPos = SalFileTell ( hFile ) Returns the current position in an open file. hFile File Handle. The handle of an open file.
nPos is the current position in hFile. If an error occurs, nPos is equal to -1. SalFileSeek
Set nRecPos = SalFileTell ( fhInFile)
SalFileWrite
Syntax Description Parameters nResult = SalFileWrite ( hFile, strBuffer, nBufferLength ) Writes a string to an open file. hFile strBuffer nBufferLength Return Value See Also Example File Handle. The handle of an open file. String. The string to write to hFile. Number. The number of bytes to write.
nResult is the number of bytes written. SalFileRead

Call SalFileWrite ( fhInFile, strCharBuf, 1 )
SalFmtFieldToStr
Syntax Description Parameters bOk = SalFmtFieldToStr ( hWndField, strValue, bFormat ) Copies the contents of a data field or table window column to a string. This function also lets you copy the format of the data. hWndField Window handle. The handle (or name) of the data field or table window column whose value (and optionally, whose format) you want to copy.
2-63
Chapter 2
strValue
Receive String. The string to which to copy the data field's value. If bFormat is TRUE, the string must be long enough to hold the formatting characters. Boolean. Specifies whether you want to keep the field's format. If TRUE, SQLWindows copies the formatted field contents to the string; if FALSE, SQLWindows copies the unformatted field contents to the string. However, Windows regional settings are still honored even when bFormat is FALSE.
bFormat
bOk is TRUE if the function succeeds and FALSE if it fails. SalFmtStrToField

On SAM_FieldEdit Call SalFmtFieldToStr ( dfDateTime, dfDateString, TRUE )
SalFmtFormatDateTime
Syntax Description strDateTime = SalFmtFormatDateTime ( dtDateTime, strPicture ) Formats a date/time value using a given date/time picture format. If you do not specify a picture format or the one you specify is invalid, SQLWindows uses the default settings in the [INTL] section and the user-defined [GTITOOLS] section of WIN.INI for formatting. Note: SQLWindows does not provide any picture format facility to specify whether or not to display a leading zero for the hour in Date/Time values.The appearance of leading zeros is dependant on the individual operating system settings which can be HH:MM as well as H:MM.
It is possible to distinguish 12-hour from 24-hour clocks.
Parameters
dtDateTime strPicture
Date/Time. The date/time value to format. String. The date/time picture format.
strDateTime is the formatted date/time string. SalFmtFormatNumber SalFmtIsValidPicture

Set dtDateTime = 1992-02-14-00.00.00 Set strFormatted = SalFmtFormatDateTime ( dtDateTime, strPicture )
2-64
SalFmtFormatNumber
SalFmtFormatNumber
Syntax Description strNumber = SalFmtFormatNumber ( nNumber, strPicture ) Formats a number value using a number picture format. If you do not specify a picture format or the one you specify is invalid, SQLWindows uses the default settings in the [INTL] section and the user-defined [GTITOOLS] section of WIN.INI for formatting. nNumber strPicture Return Value See Also Number. The number value to format. String. The number picture format.
Parameters
strNumber is a formatted number string. SalFmtFormatDateTime SalFmtIsValidPicture
Example
Set strNumber = SalFmtFormatNumber ( nNumber, strPicture )
SalFmtGetFormat
Syntax Description nFormat = SalFmtGetFormat ( hWndField ) Returns the current format of a data field or table window column. Note: Some of the Parameters have subparameters. For example, the date format has both a subparameter that specifies a dates separator character and a subparameter that specifies the month/day/year sequence. Parameters Return Value hWndField Window Handle. The handle (or name) of the data field or table window column to format.
nFormat is a number that indicates the format of the field. The return value is one of the following constants. Date fields can be formatted as: FMT_Format_Date FMT_Format_DateTime FMT_Format_Picture FMT_Format_Time FMT_Format_Unformatted Number fields can be formatted as: FMT_Format_Format_Currency FMT_Format_Decimal
2-65
Chapter 2
FMT_Format_Percentage FMT_Format_Picture FMT_Format_Unformatted String fields can be formatted as: FMT_Format_Invisible FMT_Format_Lowercase FMT_Format_Uppercase FMT_Format_Unformatted See Also Example SalFmtSetFormat
Menu Settings Enabled when: Checked when: SalFmtGetFormat ( dfDateTime ) = FMT_Format_Unformatted
SalFmtGetInputMask
Syntax Description bOk = SalFmtGetInputMask ( hWnd, strMask ) Gets the input mask of a data field or table window column. See the Formatting and Validating chapter in Developing with SQLWindows for more about input masks. Parameters hWnd strMask Return Value See Also Window Handle. The handle (or name) of a combo box, data field, or table window column. Receive String. The input mask retrieved.
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle or the object does not have an input mask. SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask SalFmtUnmaskInput
On SAM_Click Set bOk = SalFmtGetInputMask ( df1, df2 )
Example
SalFmtGetPicture
Syntax Description bOk = SalFmtGetPicture ( hWndField, strPicture ) Gets the picture format of a data field or table window column.
2-66
SalFmtIsValidField
Parameters
hWndField strPicture
Window Handle. The handle (or name) of the data field or table window column whose picture format you want. Receive String. The picture format.
bOk is TRUE if the function succeeds, and FALSE if the data field or table window column is not picture-formatted. SalFmtSetPicture
Set bOk = SalFmtGetPicture ( hWndField, strPicture )
SalFmtIsValidField
Syntax Description bValid = SalFmtIsValidField ( hWndField ) Validates the contents of a data field or table window column using the current profile.
SQLWindows strips off formatting characters and validates a field's contents according to type. After that, SQLWindows validates extra picture formatting characters that you enter to ensure that they conform to the profile requirements.
hWndField
Window Handle. The handle (or name) of the data field or table window column whose contents you want to validate.
bValid is TRUE if the field's contents are valid and FALSE if the field's contents are invalid.
On SAM_Validate If SalFmtIsValidField ( dfDateTime ) Call SalFmtValidateField ( dfDateTime, FMT_Validate_None )
SalFmtIsValidInputMask
Syntax Description bOk = SalFmtIsValidInputMask ( strMask ) Validates the input mask of a data field or table window column. See the Formatting and Validating chapter in Developing with SQLWindows for more about input masks. Parameters Return Value See Also strMask String. An input mask.
bOk is TRUE if strMask is a valid input mask and FALSE if it is not valid. SalFmtGetInputMask SalFmtSetInputMask
2-67
Chapter 2
SalFmtKeepMask SalFmtUnmaskInput Example

On SAM_Click If SalFmtIsValidInputMask ( df1 ) Set df2 = 'Is Valid' Else Set df2 = 'Is Not Valid'
SalFmtIsValidPicture
Syntax Description bOk = SalFmtIsValidPicture ( strPicture, nType ) Validates a number or date/time picture format. These are examples of date/time picture formats:
Date/Time Picture d MMMM, yyyy dddd, MMMM d, yyyy M/d/yy dd-MM-yyyy d "of " MMMM, yyyy M/d/yy-hh.mm.ss AMPM Displayed Value 9 January, 1989 Friday, February 7, 1989 3/18/89 18-03-1989 9 of January, 1989 2/3/91-12.23.15 AM
These are examples of number picture formats:

Number Picture 0.00% 0.00e+00 0.00e-00 $#,##0;($#,##0) $#,##0;($#,##0) 0.00 7.00% 3.65e+03 3.65e03 $1,350 ($1,350) 95.00 Displayed Value
Parameters
strPicture
String. The picture string.
2-68
SalFmtKeepMask
nType
Number. Specify whether the format is for a number or date/ time value with one of these constants: FMT_Pic_DateTime FMT_Pic_Number
bOk is TRUE if the picture format is valid and FALSE otherwise. SalFmtGetPicture SalFmtSetPicture
Example
Set strPicture = 'M/d/yy' Set bValid = SalFmtIsValidPicture ( strPicture, FMT_Pic_DateTime )
SalFmtKeepMask
Syntax Description bRet = SalFmtKeepMask ( bKeep ) By default, SQLWindows removes input mask characters when you copy the value in a data field, table window column, or combo box. For example, if you create a data field with the input mask AA-AA and copy its value to another data field, SQLWindows does not copy the hyphen. You can call SalFmtKeepMask to change the default behavior so that SQLWindows keeps the input mask characters when you copy the value in a data field, table window column, or combo box. For example, if you create a data field with the input mask AA-AA and copy its value to another data field, SQLWindows copies the hyphen. The "^" character in an input mask overrides a setting that you make with this function. See the Formatting and Validating chapter in Developing with SQLWindows for more about input masks. Parameters bKeep Boolean. If FALSE (default), SQLWindows removes input mask characters when you copy a value. If TRUE, SQLWindows keeps the input mask characters when you copy a value. Return Value See Also bRet is the value you specified in bKeep. SalFmtGetInputMask SalFmtIsValidInputMask
2-69
Chapter 2
SalFmtSetInputMask SalFmtUnmaskInput Example

Set bRet = SalFmtKeepMask ( bKeep )
SalFmtSetFormat
Syntax Description bOk = SalFmtSetFormat ( hWndField, nFormat ) Sets a data field's or table window column's format. A field's country profile determines a format's characteristics. If the field uses the default format, the profile in WIN.INI determines a format's characteristics. A field's format must agree with the field's data type, so for example, number fields can only be formatted as decimal, percentage, or currency values. Parameters hWndField nFormat Return Value See Also Example Window Handle. The handle (or name) of the data field or table window column whose format you want to set. Number. The format for hWndField.
bOk is TRUE if the function succeeds and FALSE if the format cannot be set such as when the format is not appropriate for the specified field. SalFmtGetFormat
Set bOk = SalFmtSetFormat ( hWndField, nFormat )
SalFmtSetInputMask
Syntax Description bOk = SalFmtSetInputMask ( hWnd, strMask ) Sets the input mask of a data field or table window column. See the Formatting and Validating chapter in Developing with SQLWindows for more about input masks. Parameters hWnd strMask Return Value See Also Window Handle. The handle (or name) of a combo box, data field, or table window column. String. The string that holds the input mask. If strMask is an empty string (''), SQLWindows sets hWnd to be unformatted.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtUnmaskInput
2-70
SalFmtSetPicture
Example
Set bOk = SalFmtSetInputMask ( hWnd, strMask )
SalFmtSetPicture
Syntax Description Parameters bOk = SalFmtSetPicture ( hWndField, strPicture ) Sets the picture format of a data field or table window cell. hWndField Window Handle. The handle (or name) of the data field or table window column whose picture format you want to set. If you specify a table window column, only the cell in that column, and in the current table window context row, is changed. String. The picture format.
strPicture Return Value
bOk is TRUE if the function succeeds and FALSE if it fails. bOk is FALSE if any of the following are true: The window handle is not valid. The field/column is not of date/time or number data type. The picture format is not valid.
See Also Example
SalFmtGetPicture
Set bOk = SalFmtSetPicture ( hWndField, strPicture )
SalFmtStrToField
Syntax Description Parameters bOk = SalFmtStrToField ( hWndField, strValue, bFormat ) Copies a string to a data field or table window column. After copying the string to the field, SQLWindows formats the string. hWndField strValue bFormat Return Value See Also Example Window Handle. The handle (or name) of the data field or table window column to which the string is assigned. String. The string to copy. Boolean. Specify whether (TRUE) or not (FALSE) the string value has the same format as the field.
bOk is TRUE if the string's value has the same format as the data field or table window column. bOk is FALSE if the string's value is unformatted. SalFmtFieldToStr
Message Actions On SAM_FieldEdit
2-71
Chapter 2
Call SalFmtStrToField ( dfDateTime, dfDateString, TRUE )
2-72
SalFmtUnmaskInput
SalFmtUnmaskInput
Syntax Description bOk = SalFmtUnmaskInput ( hWnd, strInput ) Unmasks the contents of a data field or table window column and puts the result in a string. Unmasking involves taking control characters out of a string, but does not include converting characters from lowercase to uppercase and vice versa. See the Formatting and Validating chapter in Developing with SQLWindows for more about input masks. Parameters hWnd strInput Return Value See Also Window Handle. The handle (or name) of a combo box, data field, or table window column. Receive String. The unmasked contents of hWnd.
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle or the object does not have an input mask. SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask
Set bOk = SalFmtUnmaskInput ( hWnd, strInput )
Example
SalFmtValidateField
Syntax Description bOk = SalFmtValidateField ( hWndField, nValidate ) Validates and formats a data field's or table window column's contents.
SQLWindows strips off formatting characters and validates a field's contents according to type. After that, SQLWindows validates picture formatting characters that you enter to ensure that they conform to the profile requirements.
For dates, you must enter the proper separator characters in order for SQLWindows to validate the field successfully. Parameters hWndField nValidate Return Value Example Window Handle. The handle (or name) of the data field or table window column to validate and format. Number. A constant value that indicates what SQLWindows does if a format error occurs and the function returns FALSE:
bOk is TRUE if the function succeeds and FALSE otherwise, such as when the input is invalid. If bOk is FALSE, SQLWindows optionally displays an error dialog box.
If SalFmtIsValidField ( dfDateTime )
2-73
Chapter 2
Call SalFmtValidateField ( dfDateTime, FMT_Validate_None ) Return VALIDATE_Ok
SalFontGet
Syntax Description Parameters bOk = SalFontGet ( hWndFont, strName, nSize, nEnhancement ) Gets a window's font name, size, and enhancements. hWndFont strName nSize nEnhancment Return Value See Also Window Handle. The handle (or name) of the window whose font information you want. Receive String. The name of the font. Receive Number. The size of the font. Receive Number. The font enhancements. To combine two or more of the FONT_Enh* constants, use the OR (|) operator.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFontGetNames SalFontGetSizes SalFontSet
If NOT SalFontGet ( hWndField, strFont, nSize, nEnhancement ) ... Error ...
Example
SalFontGetNames
Syntax Description Parameters nNames = SalFontGetNames ( nGet, strArrayFontNames ) Gets the names of the screen or printer fonts. nGet strArrayFontNames Return Value See Also Number. A constant that specifies whether to get the screen or printer fonts: Receive String Array. The name of an array of strings that contains the font names returned.
nNames is the number of font names returned. SalFontGet SalFontGetSizes SalFontSet

Set nTotal = SalFontGetNames ( FONT_GetScreen, sFontNames )
Example
2-74
SalFontGetSizes
SalFontGetSizes
Syntax Description Parameters nSizes = SalFontGetSizes ( nGet, strFontName, nArrayFontSizes ) Gets the sizes of a screen or printer font. nGet strFontName nArrayFontSizes Return Value See Also Number. Specify whether to get the sizes of a printer or screen font: String. The name of the font. Receive Numeric Array. The name of an array of numbers that contains the font sizes (in points) returned.
nSizes is the number of font sizes returned. SalFontGet SalFontGetNames SalFontSet

Set nTotal = SalFontGetSizes ( FONT_GetScreen, sFont, nSizes )
Example
SalFontSet
Syntax Description Parameters bOk = SalFontSet ( hWnd, strName, nSize, nEnhancement ) Sets a window's font, font size, and font enhancements. hWnd strName nSize nEnhancment Window Handle. The handle (or name) of the window whose font attributes you want to set. String. The name of the font. Number. The size of the font (in points). Number. The font enhancements. To specify two or more of the FONT_Enh* constants, combine them using the OR (|) operator.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFontGet SalFontGetNames SalFontGetSizes
Set bOk = SalFontSet ( hWnd, strName, nSize, nEnhancement )
Example
2-75
Chapter 2
SalFormGetParmNum
Syntax Description Parameters bOk = SalFormGetParmNum ( hWndForm, nParm, nValue ) Returns the value of one of three form window parameters: height, width, or number of pages. hWndForm nParm nValue Return Value Example Window Handle. The handle (or name) of the form window whose parameter value you want. Number. Specify form height, form width, or number of pages to return in nValue: Receive Number. The value of the form parameter requested.

On SAM_Create Call SalFormGetParmNum ( frmMain, FORM_nFormPages, dfPages )
SalFormUnitsToPixels
Syntax Description nNumPixels = SalFormUnitsToPixels ( hWnd, nFormUnits, bVertical ) Computes the number of pixels in the number of SQLWindows form units. SQLWindows form units are a unit of measurement used by functions which move and position SQLWindows objects. SQLWindows computes form units using physical units (pixels) in conjunction with the window's font size. Parameters hWnd nFormUnits bVertical Window Handle. The handle (or name) of a window. Number. The number of form units. Boolean. If the form units are on the X axis, set this parameter to FALSE. If the form units are on the Y axis, set this parameter to TRUE.
nNumPixels is the number of pixels returned if the function succeeds. nNumPixels is zero (0) if hWnd is invalid. SalPixelsToFormUnits
Set nPixels = SalFormUnitsToPixels ( pbExample, nWidth, FALSE )
2-76
SalGetDataType
SalGetDataType
Syntax Description nDataType = SalGetDataType ( hWnd ) Returns a data field's or table window column's data type. Use this function with internal functions that handle data fields and table window columns generically. Such internal functions pass only a window handle; the internal function does not know the data type of the associated window. Parameters Return Value See Also Example hWnd Window Handle. The handle (or name) of a data field or table window column.
nDataType is a number that indicates the data field's or table window column's data type. Its value is one of a predetermined set of constants (excluding DT_Boolean). SalGetType
Set nType = SalGetType ( hWndChild ) If nType = TYPE_DataField Set nDataType = SalGetDataType ( hWndChild )
SalGetDefButton
Syntax Description Parameters Return Value hWndDef = SalGetDefButton ( hWndParent ) Returns the handle of the default push button on a form window or dialog box. The default push button is the one that has the focus by default. hWndParent Window Handle. The handle (or name) of the form window or dialog box.
hWndDef is the handle of the default push button. It equals if hWndParent is not the handle of a valid form window or dialog box, or if the window associated with hWndParent does not have a default push button. SalSetDefButton
Menu Actions Set hWndDef = SalGetDefButton ( frmMain ) Call SalSetDefButton ( frmMain.pb2 ) Set hWndDef = SalGetDefButton ( frmMain )
See Also Example
2-77
Chapter 2
SalGetFirstChild
Syntax Description hWndChild = SalGetFirstChild ( hWndParent, nTypeMask ) Returns the handle of the first child window of the specified type. This function can be used to get MDI child windows. If you want this function to work for background text, lines, and frames, set the system variable bStaticsAsWindows to TRUE. This is a global system variable, so the settiing persists until it is changed. hWndParent nTypeMask Window Handle. The handle (or name) of a form window, dialog box, or table window whose first child handle you want. Number. One or more window types combined (using the OR (|) operator) to create a mask of child window types.
SQLWindows only examines those child windows whose type AND'd with nTypeMask yields a non-zero value.
Parameters
hWndChild is the handle of the first child window of the specified type. hWndChild equals hWndNULL if there is no child window or if hWndParent is invalid. SalGetNextChild SalGetType
Set hWndChild = SalGetFirstChild ( hWndCurrentFW, nTypeMask )
SalGetFocus
Syntax Description Parameters Return Value See Also Example hWndFocus = SalGetFocus ( ) Returns the handle of the window with the focus. No parameters. hWndFocus identifies the window that can currently receive input from the keyboard. SalSetFocus
Set hWndSave = SalGetFocus ( )
SalGetItemName
Syntax Description Parameters bOk = SalGetItemName ( hWnd, strText ) Gets the name of an object. Use SalGetItemName to qualify variables in SQL statements. hWnd strText 2-78 Window Handle. The handle of an object. Receive String. The name of the object.
SalGetMaxDataLength
Return Value Example

Call SalGetItemName ( hWndCurrent, strItemName ) Return strItemName
SalGetMaxDataLength
Syntax Description nDataLength = SalGetMaxDataLength ( hWndObject ) Returns the maximum length of a data field, multiline text field, or table window column. Use this function before assigning a value to any of these objects to ensure that the value fits. hWndObject Window Handle. The handle of a data field, multiline text field, or table window column.
nDataLength is a number that specifies the maximum length of hWndObject. A length of DW_Default (-1) indicates that the object was declared with a length of Default. SalSetMaxDataLength
Set nDataLen = SalGetMaxDataLength ( hWnddfCurrent )
See Also Example
SalGetNextChild
Syntax Description hWndNextChild = SalGetNextChild ( hWndChild, nTypeMask ) Returns the handle of the next child window that matches a specified type. Use this function after calling SalGetFirstChild to get the other child window siblings. If you want this function to work for background text, lines, and frames, set the system variable bStaticsAsWindows to TRUE. This is a global system variable, so the setting persists until you change it. Parameters hWndChild nTypeMask Window Handle. The handle (or name) of a child window. You can specify the return value of SalGetFirstChild. Number. One or more window types combined (using the OR (|) operator) to create a mask of child window types.
SQLWindows only examines those child windows whose type AND'd with nTypeMask yields a non-zero value.
Return Value
hWndNextChild is the handle of the next child window of the specified type. hWndNextChild equals hWndNULL if there is no child window or if hWndChild is invalid. SalGetFirstChild
See Also
2-79
Chapter 2
SalGetType Example
Set hWndChild = SalGetNextChild ( hWndChild, nTypeMask )
SalGetProfileInt
Syntax Description Parameters nValue = SalGetProfileInt ( strSection, strEntry, nDefault, strFileName ) Retrieves the integer value of an entry in the specified section of an initialization file or registry. strSection strEntry nDefault strFileName String. The section heading. String. The entry whose associated value is being retrieved. Number. Specify the default value (0 to 32,767) to return if the function cannot find the entry. String. The name of the initialization file or company name depending on the settings made using the SalUseRegistry function. If you are searching for an INI file and do not specify the full path, SQLWindows searches for the file in the Windows subdirectory.
Return Value
nValue is the integer value of an entry in the specified section of a file or registry, if the function is successful. If the value found is not an integer, nValue is zero (0). If SalGetProfileInt cannot find the specified entry, nValue is the default value of the entry. SalGetProfileString SalSetProfileString SalUseRegistry
Set nValue = SalGetProfileInt ( strSection, strEntry, nDefault, strFileName )
See Also
Example
SalGetProfileString
Syntax Description Parameters nBytes = SalGetProfileString ( strSection, strEntry, strDefault, strValue, strFileName ) Retrieves the string value of an entry in the specified section of an initialization file or registry. strSection strEntry strDefault String. The section heading. String. The entry whose associated value is being retrieved. String. Specify the default value to return if the function cannot find the entry.
2-80
SalGetType
strValue strFileName
Receive String. The value of strEntry. Maximum 1024 bytes. String. The name of the initialization file or company name depending on the settings made using the SalUseRegistry function. If you are searching for an INI file and do not specify the full path, SQLWindows searches for the file in the Windows subdirectory.
Note: Specify the strFileName parameter as a NULL string when a company name is not
necessary.
nBytes is the number of bytes copied to strValue, not including the terminating null character. SalGetProfileInt SalSetProfileString SalUseRegistry
Set nBytes = SalGetProfileString ( strSection, strEntry, strDefault, strValue, strFileName )
Example
SalGetType
Syntax Description nType = SalGetType ( hWnd ) Returns an object's type. Use SalGetType with internal functions that process objects generically. Such internal functions pass only a window handle; the internal function does not know the type of the associated object. Important: For some objects (such as table window scroll bars), SalGetType returns zero. Do
not call SalQueryFieldEdit for any object where SalGetType returns zero.
hWnd
Window Handle. The handle of an object.
nType is a number that indicates the object's type. The value returned is one of a predetermined set of constants. SalGetFirstChild SalGetNextChild
Set nType = SalGetType ( hWndChild ) If nType = TYPE_DataField Set nDataType = SalGetDataType ( hWndChild )
2-81
Chapter 2
If nDataType = nHideDataType Call SalHideWindow ( hWndChild )
SalGetVersion
Syntax Description Parameters Return Value Example nType = SalGetVersion ( ) Returns the SQLWindows version. For example, SalGetVersion returns 300 for SQLWindows v3.0.0. No parameters. nType is a number that indicates the SQLWindows version number.
Message Actions On SAM_Create Set df1 = SalGetVersion ( )
SalGetWindowLabelText
Syntax Description nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength ) Retrieves the background text of a window. Important: The background text does not require a mnemonic for the functions listed above
to operate.
Parameters
hWnd strText nMaxLen
Window Handle. The handle (or name) of a window. Receive String. The window text. Number. The maximum length of the window text.
nLength is a number that indicates the length of strText. nLength is zero (0) if the window has no text.
Set nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )
SalGetWindowLoc
Syntax Description Parameters bOk = SalGetWindowLoc ( hWnd, nX, nY ) Returns a window's current position on the X and Y axes. hWnd nX Window Handle. The handle (or name) of a window. Receive Number. The position of the window on the X axis, specified in SQLWindows form units.
2-82
SalGetWindowSize
nY Return Value See Also Example
Receive Number. The position of the window on the Y axis, specified in SQLWindows form units.
bOk is TRUE if the function succeeds and FALSE if it fails. SalSetWindowLoc

Call SalSetWindowLoc ( pbExample, 0, 0 ) Call SalGetWindowLoc ( pbExample, nX, nY )
SalGetWindowSize
Syntax Description Parameters bOk = SalGetWindowSize ( hWnd, nWidth, nHeight ) Returns a window's size. hWnd nWidth nHeight Return Value See Also Example Window Handle. The handle (or name) of a window. Receive Number. The width of the window, specified in SQLWindows form units. Receive Number. The height of the window, specified in
SQLWindows form units.
bOk is TRUE if the function succeeds and FALSE if it fails. SalSetWindowSize

Call SalGetWindowSize ( pbExample, nWidth, nHeight ) Call SalSetWindowSize ( pbExample, nWidth+1, nHeight+1 )
SalGetWindowState
Syntax Description Parameters nState = SalGetWindowState ( hWnd ) Returns a window's current state. hWnd Window Handle. The handle (or name) of a window. This function fails if you specify a window name that has not been created.
nState is a constant that indicates a window's current state. It is equal to one of a predefined set of values.
On SAM_Click If SalGetWindowState ( fwDataWindow ) != Window_Normal
SalGetWindowLabel
2-83
Chapter 2
Syntax Description
hWndLabel = SalGetWindowText ( hWnd ) Retrieves the window handle of another windows label. Given a window, this function finds the window handle of the label control that precedes it in the outline. For this function to succeed, the label must be a Background Text control and must contain a mnemonic.
hWnd
Window Handle. The handle (or name) of a window.
hWndLabel contains the window handle of the label if the function succeeds. If the function fails, it contains hWndNULL. SalGetWindowLabelText SalTblGetColumnTitle
hWndLabel = SalGetWindowLabel ( dfUser )
SalGetWindowLabelText ( hWnd, sText, nMaxLength )

Syntax Description nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength ) Retrieves the background text of a window. Note: The background text does not require a mnemonic for this function to operate. Parameters hWndWindow Handle. The handle (or name) of a window. strTextReceive String. The window text. nMaxLenNumber. The maximum length of the window text. Return Value No Example nLength is a number that indicates the length of strText. nLength is zero (0) if the window has no text.
SalGetWindowText
Syntax Description nLength = SalGetWindowText ( hWnd, strText, nMaxLen ) Retrieves the text of a window. Window text is the title of a form window, dialog box, table window, radio button, check box, background text, or push button. For a data field, multiline text field, or table window column, window text is the field value in string form, regardless of the object's data type. 2-84
SalHideWindow
Note: Use SalTblGetColumnTitle to get the title of a table window column. Parameters hWnd strText nMaxLen Return Value See Also Example Window Handle. The handle (or name) of a window. Receive String. The window text. Number. The maximum length of the window text.
nLength is a number that indicates the length of strText. nLength is zero (0) if the window has no text. SalSetWindowText SalTblGetColumnTitle
Call SalGetWindowText ( hWndForm, strfrmTitle, 50 )
SalHideWindow
Syntax Description bOk = SalHideWindow ( hWndToHide ) Hides a window. This function does not destroy the window; it only makes the window invisible. Parameters Return Value See Also Example hWndToHide Window Handle. The handle (or name) of a window to hide.
bOk is TRUE if the function succeeds and FALSE if it fails. SalBringWindowToTop SalShowWindow
Call SalHideWindow ( hWndChild )
2-85
Chapter 2
SalHideWindowAndLabel
Syntax Description bOk = SalHideWindowAndLabel ( hWndToHide ) Hides a window and its associated label. A label is the background text that immediately precedes the window in the outline. This function does not destroy the window; it only makes the window invisible. Parameters Return Value hWndToHide Window Handle. The handle (or name) of a window to hide.
bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible. SalBringWindowToTop SalHideWindow SalShowWindowAndLabel
Set bOk = SalHideWindowAndLabel ( hWndToHide )
See Also
Example
SalHStringToNumber
Syntax Description Parameters Return Value See Also Example nHString = SalHStringToNumber ( strString ) Converts a string handle to a number so you can pass it as a message parameter. strString String. The string whose handle you want to change to a number.
nHString is a number that represents the converted string handle. SalNumberToHString

Set nHString = SalHStringToNumber ( strString )
SalIdleKick
Syntax Description bOk = SalIdleKick( ) Once SQLWindows detects an idle state, it does not detect another idle state until some messages have appeared in the message queue. Call SalIdleKick when the you want idle processing to occur even though no messages have been posted. The function is rarely used because idle processing is most often used to detect user input. Since user input causes messages to be posted, an idle state is detected automatically. Usually this function is used when idle processing is needed after another program or a DLL sends a notification message. 2-86
SalIdleRegisterWindow
Parameters ReturnValue See Also
None bOk is TRUE if this function succeeds and FALSE otherwise. SalIdleRegisterWindow SalIdleUnregisterWindow
SalIdleRegisterWindow
Syntax Description bOk = SalIdleRegisterWindow( hWnd, iMsg, wParam, lParam ) Tells SQLWindows to send a message to a specified window whenever SQLWindows detects an idle state. SQLWindows detects an idle state when a window has processed all the messages in its input queue. hWnd iMsg wParam lParam Return Value No Example See Also SalIdleKick SalIdleUnregisterWindow Window Handle. The handle of the window to which to send the message. Number. Message to send to the window. Usually this is a SAM_User message. Number. Standard message parameter that you can set. Number. Standard message parameter that you can set.
Parameters
bOk is TRUE if this function succeeds and FALSE otherwise.
SalIdleUnRegisterWindow
Syntax Description Parameters Return Value No Example See Also SalIdleKick SalIdleRegisterWindow bOk = SalIdleUnRegisterWindow( hWnd, ) Tells SQLWindows to stop sending idle messages to a window for which you have previously called SalIdleRegisterWindow. hWnd Window Handle. The handle of the window on which you called SalIdleRegisterWindow.
2-87
Chapter 2
SalInvalidateWindow
Syntax Description Parameters Return Value See Also Example bOk = SalInvalidateWindow ( hWndToPaint ) Causes a window to be repainted. hWndToPaint Window Handle. The handle (or name) of a window to repaint.
bOk is TRUE if the function succeeds and FALSE if it fails. SalUpdateWindow

Set bOk = SalInvalidateWindow ( hWndToPaint )
SalIsButtonChecked
Syntax Description Parameters Return Value Example bIsSet = SalIsButtonChecked ( hWnd ) Determines whether a radio button is set or a check box is checked. hWnd Window Handle. The handle (or name) of a radio button or check box.
bIsSet is TRUE if hWnd is set or checked and FALSE otherwise.

Set bIsSet = SalIsButtonChecked ( hWnd )
SalIsNull
Syntax Description Parameters Return Value See Also Example bNull = SalIsNull ( hWndIsNull ) Verifies whether a data field, multiline text field, or table window column is null or empty. hWndIsNull Window Handle. The handle (or name) of a data field, multiline text field, or table window column.
bNull is TRUE if hWndIsNull is null or empty, and FALSE otherwise. SalClearField

On SAM_Validate If SalIsNull ( dfDateTime ) Call SalMessageBox ( 'You must enter a value', 'Validate Error', MB_Ok ) Return VALIDATE_Cancel
SalIsValidDateTime
2-88
SalIsValidDecimal
Syntax Description
bOk = SalIsValidDateTime ( hWndField ) Verifies whether a data field, multiline text field, or table window column contains a valid date/time value. For multiline text fields, the date/time value must be the only item in the field. hWndField Window Handle. The handle (or name) of a data field, multiline text field, or table window column.
bOk is TRUE if hWndField contains a valid date/time value and FALSE otherwise.
On SAM_Validate If NOT SalIsValidDateTime ( dfDateTime )
SalIsValidDecimal
Syntax Description bOk = SalIsValidDecimal ( hWndField, nPrecision, nScale ) Verifies whether a data field, multiline text field, or table window column contains a valid decimal value. For multiline text fields, the decimal value must be the only item in the field. hWndField nPrecision nScale Return Value See Also Example Window Handle. The handle (or name) of a data field, multiline text field, or table window column. Number. The number of digits to display. Number. The number of digits to the right of the decimal point.
Parameters
bOk is TRUE if hWndField contains a number of the specified precision and scale, and FALSE if hWndField's value does not match the parameter specifications. SalIsValidInteger SalIsValidNumber
On SAM_Validate If NOT SalIsValidDecimal ( dfDecimal, 5, 2 ) Call SalMessageBox ( 'Invalid decimal value', 'Validate
2-89
Chapter 2
SalIsValidInteger
Syntax Description bOk = SalIsValidInteger ( hWndField ) Verifies whether a data field, multiline text field, or table window column contains a valid integer value. For multiline text fields, the integer value must be the only item in the field. hWndField Window Handle. The handle (or name) of a data field, multiline text field, or table window column.
bOk is TRUE if hWndField contains a valid integer value and FALSE if the number is a fraction, decimal, or any other invalid integer value. SalIsValidDecimal SalIsValidNumber
On SAM_Validate If NOT SalIsValidInteger ( dfInteger) Call SalMessageBox ( 'Invalid integer value', 'Validate Error', MB_Ok ) Return VALIDATE_Cancel
SalIsValidNumber
Syntax Description bOk = SalIsValidNumber ( hWndField ) Verifies whether a data field, multiline text field, or table window column contains a valid numeric value. Valid numbers are integers or floating point numbers, negative and positive. For multiline text fields, the numeric value must be the only item in the field. hWndField Window Handle. The handle (or name) of a data field, multiline text field, or table window column.
bOk is TRUE if hWndField contains a valid SQLBase number and FALSE otherwise. SalIsValidDecimal SalIsValidInteger
On SAM_Validate ! Examples of valid numbers: 100, 100.123, -100 If NOT SalIsValidNumber ( dfNumber) Call SalMessageBox ( 'Invalid number value', 'Validate Error', MB_Ok )
2-90
SalIsWindowEnabled
SalIsWindowEnabled
Syntax Description Parameters Return Value See Also Example bEnabled = SalIsWindowEnabled ( hWndEnabled ) Determines whether a window is enabled for mouse and keyboard input. hWndEnabled Window Handle. The handle (or name) of a window.
bOk is TRUE if hWndEnabled is enabled and FALSE if hWndEnabled is not enabled or is not a valid handle. SalDisableWindow SalEnableWindow
If SalIsWindowEnabled ( pbUpdate ) Call SalDisableWindow ( pbUpdate )
SalIsWindowVisible
Syntax Description Parameters Return Value See Also Example bOk = SalIsWindowVisible ( hWndVisible ) Determines whether a window is currently visible. hWndVisible Window Handle. The handle (or name) of a window. Create a window first before using a window template as a parameter.
bOk is TRUE if the window is visible and FALSE otherwise. SalHideWindow SalShowWindow
Set bOk = SalIsWindowVisible ( hWndVisible )
SalListAdd
Syntax Description nIndex = SalListAdd ( hWndList, strName ) Adds a string to a list box or combo box. If the list box is sorted (the default), SQLWindows inserts the string into the list in the appropriate place. If the list box is not sorted, SQLWindows adds the string to the end of the list box. SQLWindows uses ANSI ascending order in the sort. Parameters hWndList strName Window Handle. The handle (or name) of a list box or combo box. String. The string to add.
2-91
Chapter 2
nIndex is the index of the new list box entry. SalListAdd returns LB_Err on an error and LB_ErrSpace if there is insufficient memory to store the new string. SalListInsert SalListPopulate
Call SalListAdd ( hWndlbCurrent, strLBItem )
SalListClear
Syntax Description Parameters Return Value Example bOk = SalListClear ( hWndList ) Deletes all entries from a list box or combo box. hWndList Window Handle. The handle (or name) of a list box or combo box.

Call SalListClear ( lbProducts )
SalListDelete
Syntax Description Parameters nRemaining = SalListDelete ( hWndList, nIndex ) Deletes a list box or combo box entry. hWndList nIndex Return Value Example Window Handle. The handle (or name) of a list box or combo box. Number. The index of the entry to delete.
nRemaining is the number of rows remaining in the list box or combo box if the function succeeds. SalListDelete returns LB_Err if an error occurs.
Set nCount = SalListDelete ( hWndlbCurrent, nLBIdx )
SalListFiles
Syntax Description Parameters bOk = SalListFiles ( hWndList, hWndPath, strPathName, nFlags ) Populates a list box or combo box with a directory of files. You can create the same kinds of dialog boxes as those displayed by items of the Windows File menu. hWndList hWndPath Window Handle. The handle (or name) of a list box or combo box. Window Handle. The handle (or name) of the data field that displays the current directory and drive of the files listed in hWndList.
2-92
SalListGetMultiSelect
strPathName
Receive String. The path name of the directory whose files are listed. You must specify a field name or variable; you cannot specify a string constant as a receive parameter. Number. The type of file access. You can combine FA_* constants with the OR (|) operator to create this value.
nFlags Return Value See Also Example
bOk is TRUE if the function succeeds and FALSE if it fails. SalFileOpen

Call SalListFiles ( hWndLB, hWndLoadPath, strLoadPath, nFileAttrib )
SalListGetMultiSelect
Syntax Description bOk = SalListGetMultiSelect ( hWndList, nSelectedArray ) Returns an array of index numbers of selected list box entries. Use the SalListQueryMultiCount function to return the number of selected list box entries. Parameters hWndList nSelectedArray Return Value Example Window Handle. The handle (or name) of a list box. Receive Numeric Array. The name of an array of index numbers of selected list box entries.
bOk is TRUE if the function succeeds and FALSE if hWndList or nSelectedArray are not valid, or if no list box entries are selected.
Call SalListGetMultiSelect ( lbExample, nSelectedArray )
SalListInsert
Syntax Description Parameters nIndex = SalListInsert ( hWndList, nIndex, strAdd ) Inserts an entry into a list box or combo box at a specified position. hWndList nIndex strAdd Return Value Window Handle. The handle (or name) of a list box or combo box. Number. The position at which to insert the row. A value of -1 adds the entry to the end of the list box or combo box. String. The string to insert.
nIndex is the index of the new entry. SalListInsert returns LB_Err on an error and LB_ErrSpace if there is insufficient memory to store the new string.
2-93
Chapter 2
See Also Example
SalListAdd
Call SalListInsert ( hWndLB, -1, strInsertStr )
SalListPopulate
Syntax Description bOk = SalListPopulate ( hWndList, hSql, strSelect ) Populates a list box or combo box with a result set. SalListPopulate overrides any settings made with SalListSetTabs. If the SELECT statement returns data from multiple columns, each column's data displayed in a list box is separated by tabs. However, due to a Microsoft Windows limitation, each column's data displayed in a combo box is separated by a single '|' character. There is no space between one column's data, the separator character, and another column's data. Parameters hWndList hSql strSelect Window Handle. The handle (or name) of the list box or combo box to populate. Sql Handle. The handle of a SELECT statement. String. The SELECT statement. The SELECT statement can contain bind variables, but it cannot contain INTO variables. If strSelect is null (''), SQLWindows uses the previously prepared SELECT statement associated with hSql. This avoids re-preparing each time SalListPopulate executes. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if any of the parameters are invalid or if strSelect contains INTO variables. SalListAdd SalListInsert
On SAM_Click Call SalListPopulate ( lbExample, hSql, 'select name, trainer, room ' || 'from guest_roster' )
SalListQueryCount
Syntax Description Parameters nEntries = SalListQueryCount ( hWndList ) Returns the number of list box or combo box entries. hWndList Window Handle. The handle (or name) of a list box or combo box.
2-94
SalListQueryFile
nEntries is the number of entries in hWndList. SalListQueryCount returns LB_Er if an error occurs.
If NOT SalListQueryCount ( hWndlbCurrent ) Return FALSE
SalListQueryFile
Syntax Description Parameters bDirectory = SalListQueryFile ( hWndList, strFileName ) Fetches the selected directory or file name from a list box or combo box. hWndList strFileName Return Value Example Window Handle. The handle (or name) of a list box or combo box. Receive String. The directory or file name being fetched.
bDirectory is TRUE if strFileName is the name of a directory and FALSE if it is the name of a file.
Call SalListQueryFile ( hWndLB, strFileName )
SalListQueryMultiCount
Syntax Description nSelected = SalListQueryMultiCount ( hWndList ) Returns the number of selected entries in a multiple-selection list box. Specify single- or multiple-selection in the list box's Attribute Inspector. Parameters Return Value hWndList Window Handle. The handle (or name) of a multiple-selection list box.
nSelected is the number of selected entries in hWndList if the function succeeds. nSelected equals LB_Err if hWndList is a single-selection list box or is not a valid handle.
Set nSelected = SalListQueryMultiCount ( lbExample )
Example
SalListQuerySelection
Syntax Description nIndex = SalListQuerySelection ( hWndList ) Returns the index of the selected entry in a combo box or single-selection list box. Specify single- or multiple-selection in the list box's Attribute Inspector.
2-95
Chapter 2
Note: For an example of getting a list of selected entries in a multiple-selection list box, see
SalListQueryState.
hWndList
Window Handle. The handle (or name) of a combo box or single-selection list box.
nIndex is the index of the selected entry if the function succeeds. SalListQuerySelection returns LB_Err if no entry is selected or if the list box is a multiple-selection box. SalListGetMultiSelect SalListQueryState
Set nLBIdx = SalListQuerySelection (hWndlbCurrent )
See Also Example
SalListQueryState
Syntax Description Parameters bSelected = SalListQueryState ( hWndList, nIndex ) Determines whether the specified list box or combo box entry is selected. hWndList nIndex Return Value Example Window Handle. The handle (or name) of a list box or combo box. Number. The index of the list box or combo box entry.
bSelected is TRUE if the nIndex entry is selected and FALSE if the entry is not selected or an error occurs.
If SalListQueryState ( hWndlbCurrent, nLBIdx ) Set nCount = SalListDelete (hWndlbCurrent, nLBIdx) Else Set nLBIdx = nLBIdx + 1
SalListQueryText or SalListQueryTextX
Syntax nLength = SalListQueryText ( hWndList, nIndex, strText ) or strText = SalListQueryTextX ( hWndList, nIndex ) Description Parameters Fetches a list box or combo box entry. hWndList nIndex 2-96
Window Handle. The handle (or name) of a list box or combo box. Number. The index of the list box or combo box entry.
SalListQueryTextLength
strText is the fetched list box or combo box entry.

Set strRecv = SalListQueryTextx ( hWnddbCurrent, nLBIdx )
SalListQueryTextLength
Syntax Description Parameters nLength = SalListQueryTextLength ( hWndList, nIndex ) Returns the length of a list box or combo box entry. hWndList nIndex Return Value Example Window Handle. The handle (or name) of a list box or combo box. Number. The index of the list box or combo box entry.
nLength is the length of the string. SalListQueryTextLength returns LB_Err if an error occurs.
Set nLBItemLen = SalListQueryTextLength (hWndlbCurrent, nLBIdx)
SalListQueryTextX
Syntax Description Parameters strText = SalListQueryTextX ( hWndList, nIndex ) Fetches a list box or combo box entry. hWndList nIndex strText Return Value Window Handle. The handle (or name) of a list box or combo box. Number. The index of the list box or combo box entry. Receive String. The string to which the entry is fetched.
nLength is the length of strText. SalListQueryText returns LB_Err if nIndex is invalid. strText is the fetched list box or combo box entry.
Example
Set strText = SalListQueryTextX ( hwndLst, 2 )
SalListRedraw
Syntax Description bOk = SalListRedraw ( hWndList, bRedraw ) Redraws entries in a list box or combo box, or prevents them from being redrawn. For example, use SalListRedraw when populating a list box or combo box to prevent the contents from being redrawn after adding each entry. When SQLWindows finishes populating it, use this function to redraw the list box or combo box .
2-97
Chapter 2
Parameters
hWndList
Window Handle. The handle (or name) of a list box or combo box. bRedraBoolean. If TRUE, SQLWindows redraws the list box or combo box contents; if FALSE, SQLWindows does not.
bOk is TRUE if the function succeeds and FALSE otherwise, such as when hWndList is not a valid handle.
On SAM_Click Call SalListRedraw ( lbList, FALSE )
SalListSelectString
Syntax Description nIndex = SalListSelectString ( hWndList, nIndexStart, strText ) Finds and selects a combo box or single-selection list box entry. Specify single-selection in the list box's Attribute Inspector. SalListSelectString uses search wraps. For example, if SQLWindows starts searching for a string in the middle of a list box and reaches the end of the list box without finding the string, SQLWindows wraps the search to the beginning of the list box. It continues the search until it reaches the middle of the list box where it started the search. Parameters hWndList nIndexStart strText Return Value Example Window Handle. The handle (or name) of a combo box or single-selection list box. Number. The index at which to start the search. The search begins at row nIndexStart + 1. String. The string to search for.
nIndex is the index of the selected string. SalListSelectString returns LB_Err if an error occurs or if hWndList is a multiple-selection list box.
Set nIdx = SalListSelectString ( hWndLB, 0, strFindStr ) If nIdx = LB_Err Call SalListInsert ( hWndLB, -1, strInsertStr ) Else Call SalListInsert ( hWndLB, nIdx + 1, strInsertStr )
SalListSetMultiSelect
Syntax Description bOk = SalListSetMultiSelect ( hWndList, nIndex, bSelect ) Selects or deselects a combo box or multiple-selection list box entry.
2-98
SalListSetSelect
Specify single- or multiple-selection in the list box's Attribute Inspector. Parameters hWndList nIndex Window Handle. The handle (or name) of a combo box or multiple-selection list box. Number. The index of the entry to select or deselect. If you specify -1, SQLWindows selects or deselects all list box or combo box entries. Boolean. Specify whether to select (TRUE) or deselect (FALSE) the nIndex entry.
bSelect Return Value Example

Call SalListSetMultiSelect ( lbExample, 5, TRUE )
SalListSetSelect
Syntax Description bOk = SalListSetSelect ( hWndList, nIndex ) Selects or deselects a combo box or single-selection list box entry. Specify single- or multiple-selection in the list box's Attribute Inspector. Parameters hWndList nIndex Return Value Example Window Handle. The handle (or name) of a combo box or single-selection list box. Number. The index of the entry to select. If you specify -1, SQLWindows deselects the entry.
bOk is TRUE if the function succeeds and FALSE if it fails. bOk is equal to LB_Err if an error occurs.
Call SalListSetSelect ( hWndLB, 0 )
SalListSetTabs
Syntax Description bOk = SalListSetTabs ( hWndList, nArrayTabStops ) Sets tabs in a list box. List boxes use tabs to align columns of data. You need to set tabs when you are using a proportional font. SalListPopulate overrides any settings made with SalListSetTabs. hWndList nArrayTabStops Return Value Window Handle. The handle (or name) of a list box. Numeric Array. The name of an array of numbers that represent tabs. Specify tabs in inches.
Parameters
2-99
Chapter 2
Example
On SAM_Create Set nTabStops[0] = 2 Set nTabStops[1] = 3 Call SalListSetTabs ( hWndItem, nTabStops ) Call SalListAdd ( hWndItem, 'aaa'||TAB||'aaaa'||TAB||'aaaaa' )
SalLoadApp
Syntax Description Parameters bOk = SalLoadApp ( strAppName, strParameters ) Starts an application. strAppName strParameters String. The name of the application to start. String. Optional command line arguments. See the SAL chapter of Developing with SQLWindows for information about command line arguments. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if SQLWindows cannot find the application or cannot start it. SalLoadAppAndProcessMsgs SalLoadAppAndWait
On SAM_AppStartup Call SalLoadApp ( 'DBWINDOW.EXE','' )
SalLoadAppAndWait
Syntax Description Parameters bOk = SalLoadAppAndWait ( strAppName, nMode, nRet ) Starts an application, then waits for it to exit before returning control to the original application. strAppName String. The name of the application to start, separated from command line arguments with a space. See the SAL chapter in Developing with SQLWindows for information about command line arguments. nMode Number. The show mode. Specify one of these Window_* constants: Window_Maximized Window_Minimized Window_Normal
2-100
SalLoadAppAndProcessMsgs
Window_NotVisible nRet Receive Number. The return status. If the function succeeds (bOk is TRUE), nRet is the exit status of the invoked application. A zero exit status usually means successful execution. If bOk is TRUE, but the invoked application exits before entering a message loop, its exit status is not available to SQLWindows. In this case, nRet is zero as though the program exited with a zero exit status. If the function is unsuccessful (bOk is FALSE), nRet is an error code indicating why Windows could not start the application. You can find the meaning of the values in nRet when this function fails in the include file error.h which comes with Microsoft Visual C++. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if SQLWindows cannot find the application or cannot start it. SalLoadApp SalLoadAppAndProcessMsgs
On SAM_AppStartup Call SalLoadAppAndWait (DBWindow.EXE, WINDOW_Normal, nRecstatus)
SalLoadAppAndProcessMsgs
Syntax Description bOk = SalLoadAppAndProcessMsgs ( strAppName, nMode, nRet ) Starts an application, then waits for it to exit before returning control to the original application. However, unlike SalLoadAppAndWait, the original application can continue to process messages. strAppName String. The name of the application to start, separated from command line arguments with a space. See the SAL chapter in Developing with SQLWindows for information about command line arguments. nMode Number. The show mode. Specify one of these Window_* constants: Window_Maximized Window_Minimized Window_Normal Window_NotVisible
Parameters
2-101
Chapter 2
nRet
Receive Number. The return status. If the function succeeds (bOk is TRUE), nRet is the exit status of the invoked application. A zero exit status usually means successful execution. If bOk is TRUE, but the invoked application exits before entering a message loop, its exit status is not available to SQLWindows. In this case, nRet is zero as though the program exited with a zero exit status. If the function is unsuccessful (bOk is FALSE), nRet is an error code indicating why Windows could not start the application. You can find the meaning of the values in nRet when this function fails in the include file error.h which comes with Microsoft Visual C++.
bOk is TRUE if the function succeeds and FALSE if SQLWindows cannot find the application or cannot start it. SalLoadApp SalLoadAppAndWait None
SalMapEnterToTab
Syntax Description bOk = SalMapEnterToTab ( bState ) This function changes the behavior of the Enter key from executing the default button on a window to moving the focus to the next field. This function takes one parameter (TRUE or FALSE) to enable or disable this action. bState Boolean. If TRUE, the Enter key shifts the focus to the next editable object. If FALSE (default), the Enter key executes the default push button on the form window or dialog box. Return Value Example bOk is TRUE if the function succeeds and FALSE if you do not specify a Boolean value.
Set bOk = SalMapEnterToTab ( bState )
Parameters
2-102
SalMDIArrangeIcons
SalMDIArrangeIcons
Syntax Description Parameters Return Value See Also Example bOk = SalMDIArrangeIcons ( hWndMDI ) Arranges minimized child window icons in an MDI window. hWndMDI Window Handle. The handle of an MDI window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMDICascade SalMDITile
Menu Actions Call SalMDIArrangeIcons ( hWndMDI )
SalMDICascade
Syntax Description Parameters Return Value See Also Example bOk = SalMDICascade ( hWndMDI ) Cascades all non-iconized child windows of an MDI window. hWndMDI Window Handle. The handle of an MDI window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMDIArrangeIcons SalMDITile
Menu Actions Call SalMDICascade ( hWndMDI )
SalMDITile
Syntax Description Parameters bOk = SalMDITile ( hWndMDI, bPosition ) Tiles all non-iconized child windows of an MDI window. Windows that are not sizable will not be tiled. hWndMDI bPosition Return Value See Also Window Handle. The handle of an MDI window. Boolean. How to tile the child windows. If TRUE, tile the windows vertically; if FALSE, tile the windows horizontally.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMDIArrangeIcons SalMDICascade
2-103
Chapter 2
Example
Menu Actions Call SalMDITile ( hWndMDI, FALSE )
SalMessageBeep
Syntax Description bOk = SalMessageBeep ( nAlertLevel ) Plays a waveform sound that corresponds to a given system alert level defined in the [sounds] section of WIN.INI. A user can set the sound for each alert level with the sounds application in the Control Panel. nAlertLevel Number. The alert level: 0xFFFFFFFF (-1)Standard beep using the computer speaker. MB_IconAsterisk MB_IconExclamation MB_IconStop MB_IconQuestion MB_Ok Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalMessageBox
Call SalMessageBeep ( -1 )
Parameters
SalMessageBox
Syntax Description nResult = SalMessageBox ( strText, strTitle, nFlags ) Displays a message box and returns a number that indicates the user's response. You can customize the message box push buttons and icons. The active parent window, whose value is hWndForm, creates the message box. Parameters strText strTitle nFlags String. The message text. You can enter multiple lines of text by pressing CTRL-ENTER to start a new line. String. The message box title. Number. The message box style. Create a style by combining style option constants using the OR (|) operator. You can combine at most one constant from each component.
2-104
SalMessageBox
A style has four components: 1. Push buttons 2. Message icons, if any 3. A default button 4. Whether the message box is system modal Push Button Style Constants MB_AbortRetryIgnore MB_Ok(default) MB_OkCancel MB_RetryCancel MB_YesNo MB_YesNoCancel Icon Style Constants MB_IconAsterisk MB_IconExclamation MB_IconHand MB_IconQuestion MB_IconStop Response Button Style Constants MB_DefButton1 MB_DefButton2 MB_DefButton3 MB_NoFocus System Style Constants MB_ApplModal (default) MB_SystemModal Return Value See Also Example nResult is the value of the push button the user clicks. SalMessageBeep
Set nResult = SalMessageBox ( strText, strTitle, nFlags )
2-105
Chapter 2
SalModalDialog
Syntax Description nReturn = SalModalDialog ( tDlgBoxToCreate, hWndOwner, Parm1, Parm2, ...) Creates a modal dialog box. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters. You cannot use receive window parameters as receive function arguments. You can use a temporary variable as the function argument and then assign the temporary variable to the receive function parameter. A modal dialog box suspends the application until the user closes the dialog box. A system modal dialog box disables the entire Windows system. SalEndDialog destroys the modal dialog box and enables all windows that were disabled. SalModalDialog can pass information to the dialog box by accepting a variable number of parameters. The data types of these parameters must match the parameter data types of the dialog box being created. You define parameters for the dialog box in the Window Parameters section of the application outline. You can use window parameters to return information from the window being created by using a receive type. However, you can initialize receive window parameters only with variables. This means that you cannot pass a data field or any other window object to a window parameter that was defined as a receive type. In addition, you cannot use an array variable as a receive parameter. Parameters tDlgBoxToCreate Template or String. The name of the modal dialog box to create. NOTE: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner Parm1 Parm2 Return Value See Also Example 2-106 Window Handle. The handle (or name) of the owner window. Use hWndNULL for a dialog box that does not have an owner. Any SQLWindows data type. The (optional) first of a variable number of window parameters. Any SQLWindows data type. The (optional) second of a variable number of window parameters.
nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created. SalEndDialog SalModalDialogFromStr
Call SalModalDialog ( dlgAboutBox, hWndForm )
SalModalDialogFromStr
SalModalDialogFromStr
Syntax Description nReturn = SalModalDialogFromStr ( strName, hWndOwner, Parm1, Parm2, ... ) Creates a modal dialog box. This function is useful with internal functions that expect to receive a dialog box name in a string parameter. A modal dialog box disables its owner window. A system modal dialog box disables the entire Windows system. SalEndDialog destroys a modal dialog box and enables all windows that were disabled. Parameters strName hWndOwner Parm1 String. The name of the modal dialog box to create. Window Handle. The handle (or name) of the owner window. Use hWndNULL for dialog boxes that do not have owners. Any SQLWindows data type. The (optional) first of a variable number of window parameters. The window parameters must be defined in the dialog. Any SQLWindows data type. The (optional) second of a variable number of window parameters. The window parameters must be defined in the dialog.
Parm2
nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created. SalModalDialog
Set nReturn = SalModalDialogFromStr ( tDlgBoxToCreate, hWndOwner )
SalMoveWindow
Syntax Description Parameters bOk = SalMoveWindow ( hWndToMove, nXOffset, nYOffset ) Moves a window a given number of form units on the X and Y axes relative to its current position. hWndToMove nXOffset nYOffset Return Value See Also Window Handle. The handle (or name) of the window to move. Number. The number of form units to move the window on the X axis. Number. The number of form units to move the window on the Y axis.
bOk is TRUE if the function succeeds, and FALSE if hWndToMove is invalid. SalCenterWindow 2-107
Chapter 2
Example
Call SalMoveWindow ( pbExample, 1,1 )
SalMTSCreateInstance
Syntax Description bOk = SalMTSCreateInstance( oObj ) Creates a new component. Depending on the Transaction settings this component will continue the current transaction, will start a new transaction, or will under nontransactional state. For non-MTS components the SalMTSCreateInstance() will work as Create(). Parameters Return Value Example oObj Object/Interface. The requested interface/object to be instantiated.
Returns TRUE if the object gets successfully instantiated, otherwise returns FALSE.
Variable: Stocks: objStocks Accounts: objAccounts Boolean: bRet Actions: Call SalMTSCreateInstance(objStocks) Call objStocks.Buy(UserID, sTicker, nShares)// changes Transactions table Call SalMTSCreateInstance(objAccounts) Call objStocks.GetPrice(sTicker, nPrice) Call objAccounts.Pay(UserID, nPrice*nShares)// changes Accounts table. // If not enough funds then the Pay method // will call SalMTSSetAbort() and the // whole transaction will be aborted. Call SalMTSSetComplete()
SalMTSDisableCommit
Syntax Description bOk = SalMTSDisableCommit( ) Indicates that the object's transactional updates cannot be committed in the present time until SalMTSEnableCommit() or SalMTSSetComplete() is called. For non-MTS components the SalMTSDisableCommit() will fail (returns FALSE). Parameters Return Value Example None. Returns TRUE if successful, returns FALSE if it fails.
Set bRet = SalMTSDisableCommit()
2-108
SalMTSEnableCommit
SalMTSEnableCommit
Syntax Description bOk = SalMTSEnableCommit( ) Indicates that the objects work is not necessarily done, but that its transactional updates can be committed in their current form (stateful object). EnableCommit is the default state when an object is activated. For non-MTS components the SalMTSEnableCommit() will fail (returns FALSE). Parameters Return Value Example None. Returns TRUE if successful, returns FALSE if it fails.
Set bRet = SalMTSEnableCommit()
SalMTSGetObjectContext
Syntax Description bOk = SalMTSGetObjectContext(Ctx ) Gets the explicit object context Ctx. For non-MTS components the SalMTSGetObjectContext() will fail (returns FALSE). Parameters Return Value Example Ctx Receive Number. The current object context.
Returns TRUE if successful, returns FALSE if it fails.

Number: nCtx Boolean: bRet Set bRet = SalMTSGetObjectContext(nCtx) If bRet Call ExtFunc(nCtx, ...)
SalMTSIsCallerInRole
Syntax Description Parameters bOk = SalMTSIsCallerInRole( strRole, bFound ) This function checks if the current caller is listed in the role strRole. strRole ) bFound Return Value String. The name of the role. Receive Boolean. TRUE if the component's caller is a member of the specified role.
Returns TRUE if the role specified in the strRole parameter is a recognized role and bFound indicates the caller is in that role. Returns FALSE if the role doesn't exist or the call failed.
2-109
Chapter 2
Example
Boolean: bFound Set bRet = SalMTSIsCallerInRole('managers', bFound) If bRet If bFound SalMessageBox('message', 'The caller is a member of the role managers', MB_Ok) Else SalMessageBox('message', 'The caller is not a member of the role managers', MB_Ok) Else SalMessageBox('message', 'The role managers doesnt exist or the call failed', MB_Ok)
SalMTSInTransaction
Syntax Description bOk = SalMTSIsInTransaction( bIsInTransaction ) This method checks if the component is executing in the transaction context. For non-MTS components the SalMTSIsInTransaction() will fail (returns FALSE). Parameters Return Value Example bIsInTransaction Receive Boolean. TRUE if the component is executing in the transaction context.
Returns TRUE if the component is in a transaction; returns FALSE otherwise.

Boolean: bIsInTransaction Call SalMTSIsInTransaction(bIsInTransaction) If (bIsInTransaction) Call SalMTSSetComplete() Else Call SqlCommit()
SalMTSSecurityEnabled
Syntax Description bOk = SalMTSIsSecurityEnabled( bIsSecurityEnabled ) This method checks for the security status. If the object is running in the client's process, there is no security checking and SalMTSIsSecurityEnabled will always return FALSE. For non-MTS components the SalMTSIsSecurityEnabled() will fail (returnS FALSE).
2-110
SalMTSSetAbort
bIsSecurityEnabled
Receive Boolean. TRUE if the security is enabled.
Returns TRUE if declarative security is enabled for the component; returns FALSE otherwise.
Boolean: bIsSecurityEnalbed Boolean: bRet Set bRet = SalMTSIsSecurityEnabled(bIsSecurityEnabled)
SalMTSSetAbort
Syntax Description bOk = SalMTSSetAbort( ) Indicates that the objects work can never be committed. The entire transaction is aborted. The object is deactivated upon return from the method. For non-MTS components the SalMTSSetAbort() will fail (returnS FALSE). Parameters Return Value Example None. Returns TRUE if successful, returns FALSE if it fails.
Set bRet = SqlExecute(hSql) If Not bRet Call SalMTSSetAbort() Else Call SamMTSSetComplete()
SalMTSSetComplete
Syntax Description bOk = SalMTSSetComplete( ) Indicates that the object has successfully completed its work for the transaction. The object is deactivated upon return from the method that first entered the context (stateless object). For non-MTS components the SalMTSSetComplete() will fail (returns FALSE). Parameters Return Value Example None. Returns TRUE if successful, returns FALSE if it fails.
Set bRet = SqlExecute(hSql) If Not bRet Call SalMTSSetAbort()
2-111
Chapter 2
Else Call SamMTSSetComplete()
SalNumberAbs
Syntax Description Parameters Return Value Example nNum = SalNumberAbs ( nValue ) Computes a number's absolute value. nValue Number. The number whose absolute value you want.
nNum is the absolute value of nValue.

On SAM_Click Set nNum1 = SalNumberAbs ( -12 )
SalNumberArcCos
Syntax Description Parameters Return Value Example nArcCos = SalNumberArcCos ( nValue ) Computes the arccosine of a value in the range 0 to 1. The value's domain is -1 to 1. nValue Number. The number whose arccosine you want.
nArcCos is the arccosine of nValue. It is NUMBER_Null if nValue is less than -1 or greater than 1.
On SAM_Click Set nNum1 = SalNumberArcCos ( 1 )
SalNumberArcSin
Syntax Description Parameters Return Value Example nArcSin = SalNumberArcSin ( nValue ) Computes a value's arcsine. The value's domain is -1 to 1. nValue Number. The number whose arcsine you want.
nArcSin is the arcsine of nValue. nArcSin is NUMBER_Null if nValue is less than -1 or greater than 1.
On SAM_Click Set nNum1 = SalNumberArcSin ( 1 )
2-112
SalNumberArcTan
SalNumberArcTan
Syntax Description Parameters Return Value See Also Example nArcTan = SalNumberArcTan ( nValue ) Computes a value's arctangent. nValue Number. The number whose arctangent you want.
nArcTan is the arctangent of nValue. nArcTan is in the range -1 to 1. SalNumberArcTan2

On SAM_Click Set nNum1 = SalNumberArcTan ( 1 )
SalNumberArcTan2
Syntax Description Parameters nArcTan2 = SalNumberArcTan2 ( nValueY, nValueX ) Computes the arctangent of two values. This function uses the signs of both parameters to determine the quadrant of the return value. nValueY nValueX Return Value See Also Example Number. One of two values whose arctangent you want. Number. The other of two values whose arctangent you want.
nArcTan2 is the arctangent of nValueY and nValueX. nArcTan2 is in the range -1/2 to 1/2. SalNumberArcTan
On SAM_Click Set nNum1 = SalNumberArcTan2 ( 1, 0 )
SalNumberCos
Syntax Description Parameters Return Value nCos = SalNumberCos ( nAngle ) Computes an angle's cosine. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose cosine you want.
nCos is the cosine of nAngle. If the angle is large, nCos can reflect a partial loss of significance. If the angle is so large that significance is totally lost, SalNumberCos returns zero (0). SalNumberCosH
On SAM_Click
See Also Example
2-113
Chapter 2
Set nNum1 = SalNumberCos ( 0 )
SalNumberCosH
Syntax Description Parameters Return Value See Also Example nCosH = SalNumberCosH ( nAngle ) Computes an angle's hyperbolic cosine. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose hyperbolic cosine you want.
nCosH is the hyperbolic cosine of nAngle. If the return value is too large, nCosH equals zero (0). SalNumberCos
On SAM_Click Set nNum1 = SalNumberCosH ( 0 )
SalNumberExponent
Syntax Description Parameters Return Value Example nNumExp = SalNumberExponent ( nValue ) Computes a value's exponential function. nValue Number. The value whose exponential function you want.
nNumExp is the result of 'e' to the power of nValue. When there is an underflow or overflow, nNumExp is equal to NUMBER_Null.
On SAM_Click Set nNumExp = SalNumberExponent ( 2.302585093 )
SalNumberHigh
Syntax Description Parameters Return Value See Also nHi = SalNumberHigh ( nValue ) Returns a number's high-order word value (most significant 16 bits). nValue Number. The number whose high-order word value you want. SQLWindows treats nValue as an unsigned 32-bit number.
nHi is the high-order word value of nValue. SalNumberLow VisNumberMakeLong (in Visual Toolchest section of online help)
2-114
SalNumberHypot
Example
On SAM_Click Set nHi = SalNumberHigh ( 0xffffaaaa )
SalNumberHypot
Syntax Description Parameters nHypotenuse = SalNumberHypot ( nX, nY ) Computes the length of the hypotenuse of a right triangle, given the lengths of the other two sides. nX nY Return Value Example Number. The length of one side of a right triangle. Number. The length of another side of a right triangle.
nHypotenuse is the length of the hypotenuse of a right triangle. If the computation of the hypotenuse results in an overflow, nHypotenuse is equal to zero (0).
On SAM_Click Set nHypotenuse = SalNumberHypot ( 3, 4 )
SalNumberLog
Syntax Description Parameters Return Value See Also Example nLog = SalNumberLog ( nValue ) Computes a number's natural logarithm. nValue Number. The number whose natural logarithm you want.
nLog is the natural logarithm of nValue. If nValue is negative or 0, nLog is equal to NUMBER_Null. SalNumberLogBase10
On SAM_Click Set nLog = SalNumberLog ( 1000 )
SalNumberLogBase10
Syntax Description Parameters Return Value See Also nLogBase10 = SalNumberLogBase10 ( nValue ) Computes a number's base -10 logarithm. nValue Number. The number whose base -10 logarithm you want.
nLogBase10 is the base-10 logarithm of nValue. If nValue is negative or 0, nLogBase10 is equal to NUMBER_Null. SalNumberLog
2-115
Chapter 2
Example
On SAM_Click Set nLogBase10 = SalNumberLogBase10 ( 1000 )
SalNumberLow
Syntax Description Parameters Return Value See Also nLo = SalNumberLow ( nValue ) Returns a number's low-order word value (least significant 16 bits). nValue Number. The number whose low-order word value you want. SQLWindows treats nValue as an unsigned 32-bit number.
nLo is the low-order word value of nValue. SalNumberHigh VisNumberMakeLong (in Visual Toolchest section of online help)
Example
On SAM_Click Set nLo = SalNumberLow ( 0xffffaaaa )
SalNumberMax
Syntax Description Parameters nNumMax = SalNumberMax ( nVal1, nVal2 ) Returns the greater of two values. nVal1 nVal2 Return Value See Also Example Number. The first of two values. Number. The second of two values.
nNumMax is the greater of nVal1 and nVal2. SalNumberMin

On SAM_Click Set nNumMax = SalNumberMax ( 1765.2, -2 )
SalNumberMin
Syntax Description Parameters nNumMin = SalNumberMin ( nVal1, nVal2 ) Returns the lesser of two values. nVal1 nVal2 Return Value Number. The first value. Number. The second value.
nNumMin is the lesser of nVal1 and nVal2.
2-116
SalNumberMod
See Also Example
SalNumberMax
On SAM_Click Set nNumMin = SalNumberMin ( 1765.2, -2 )
SalNumberMod
Syntax Description Parameter nNumber nNumberMod Return Value Example Number. The number to divide. Number. The number by which to divide nNumber. nModulo = SalNumberMod ( nNumber, nNumberMod ) Returns a number's modulo. This function divides nNumber by nNumberMod and returns the remainder.
nModulo is the remainder of nNumber divided by nNumberMod.

On SAM_Click Set nNumber = SalNumberMod ( 5, 2 )
SalNumberPi
Syntax Description Parameters Return Value Example nNumPi = SalNumberPi ( nValue ) Multiples a number by Pi. Pi is equal to 3.1415926535979323. nValue Number. The number to multiply by Pi.
nNumPi is nValue multiplied by Pi.

On SAM_Click Set nNumPi = SalNumberSin ( SalNumberPi ( 1 ) /2 )
SalNumberPower
Syntax Description Parameters nNumPower = SalNumberPower ( nX, nY ) Computes nX raised to the power of nY. This function does not recognize integral, floating-point values greater than 2 to the 64th power, such as 1.0E100. nX nY Return Value Number. The number to raise to the power of nY. Number. The exponent.
nNumPower is equal to nX raised to the nYth power, with the following conditions:
2-117
Chapter 2
1. 2. 3. 4. Example
If nX is not 0 and nY is 0, nNumPower is equal to 1. If nX is 0 and nY is negative, nNumPower is equal to zero (0). If both nX and nY are zero (0), or if nX is negative and nY is not a whole number, nNumPower is equal to zero (0), meaning that an error occurred. In instances where an overflow or an underflow occurs, nNumPower is equal to zero (0).
On SAM_Click Set nNumPow = SalNumberPower ( 2, 3 )
SalNumberRandInit
Syntax Description bOk = SalNumberRandInit ( nSeed ) Sets the starting point for generating a series of pseudo-random numbers using SalNumberRandom. Use SalNumberRandInit when you want to generate the same set of pseudo-random numbers over and over again, for example, when doing reproducible experiments. Call SalNumberRandInit followed by numerous calls to SalNumberRandom. To repeat the random number series, call SalNumberRandInit again, specify the same seed value, and follow with numerous calls to SalNumberRandom. Parameters Return Value See Also Example nSeed Number. The starting point. A whole number in the range of 0 to 32767.
bOk is TRUE if the function succeeds and FALSE if it fails. SalNumberRandom

On SAM_Click Call SalNumberRandInit ( 12 )
SalNumberRandom
Syntax Description Parameters Return Value See Also nRandomNum = SalNumberRandom ( ) Generates a pseudo-random number. The numbers generated by this function are integers (whole numbers) in the range 0 to 32767 (0 to 0x7FFF). No parameters. nRandomNum is a pseudo-random number. SalNumberRandInit
2-118
SalNumberRound
Example
On SAM_Click Call SalNumberRandInit ( 12 ) Set nRandNum = SalNumberRandom ( )
SalNumberRound
Syntax Description nResult = SalNumberRound ( nNumber ) Returns a rounded number. If the fractional part of a number is greater than or equal to .5, SQLWindows rounds the number up. For example, the number 124.33 returns 124; the number 124.56 returns 125. Parameters Return Value Example nNumber Number. The number to round.
nResult is nNumber after rounding.

On SAM_Click Set nNumber = SalNumberRound ( 124.5 )
SalNumberSin
Syntax Description Parameters Return Value nSin = SalNumberSin ( nAngle ) Computes an angle's sine. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose sine you want.
nSin is the sine of nAngle. If the angle is large, nSin can reflect a partial loss of significance. If the angle is so large that significance is totally lost, nSin is equal to zero (0). SalNumberSinH
On SAM_Click Set nNum = SalNumberSin ( SalNumberPi ( 1 ) /2 )
See Also Example
SalNumberSinH
Syntax Description Parameters nSinH = SalNumberSinH ( nAngle ) Computes an angle's hyperbolic sine. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose hyperbolic sine you want.
2-119
Chapter 2
nSinH is the hyperbolic sine of nAngle. If the angle is too large, nSinH is equal to zero (0). SalNumberSin
On SAM_Click Set nNum = SalNumberSinH ( 0 )
SalNumberSqrt
Syntax Description Parameters Return Value Example nSqrt = SalNumberSqrt ( nValue ) Computes a number's square root. nValue Number. The number whose square root you want.
nSqrt is the square root of nValue. If nValue is negative, it is out of the domain of valid values and nSqrt is equal to zero (0).
On SAM_Click Set nSqrt = SalNumberSqrt ( 36 )
SalNumberTan
Syntax Description Parameters Return Value nTan = SalNumberTan ( nAngle ) Computes an angle's tangent. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose tangent you want.
nTan is the tangent of nAngle. If the angle is large, nTan can reflect a partial loss of significance. If the angle is so large that significance is totally lost, nTan is equal to zero (0). SalNumberTanH
On SAM_Click Set nNum = SalNumberTan ( SalNumberPi ( 1 ) / 4 ) )
See Also Example
SalNumberTanH
Syntax Description Parameters nTanH = SalNumberTanH ( nAngle ) Computes an angle's hyperbolic tangent. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose hyperbolic tangent you want.
2-120
SalNumberToChar
Return Value
nTanH is the hyperbolic tangent of nAngle. If the angle is large, nTanH can reflect a partial loss of significance. If the angle is so large that significance is totally lost, nTanH is equal to zero (0). SalNumberTan
On SAM_Click Set nNum = SalNumberTanH ( 0 )
See Also Example
SalNumberToChar
Syntax Description Parameters Return Value See Also Example strChar = SalNumberToChar ( nNumber ) Converts a decimal value to an ASCII character. nNumber Number. The number to convert.
strChar is the character converted from nNumber. SalStrFirstC

On SAM_Click Set df2 = SalNumberToChar ( df1 )
SalNumberToHString
Syntax Description Parameters Return Value See Also Example strString = SalNumberToHString ( nHString ) Converts a number to a string handle. nHString Number. The numeric value of the string handle to convert.
strString is a string handle that represents the number converted. SalHStringToNumber

On SAM_Click Set strString = SalNumberToHString ( lParam ) Set nBuffLen = SalStrGetBufferLength (strString)
SalNumberToStr
Syntax Description Parameters nLength = SalNumberToStr ( nNumber, nDecimalPlaces, strString ) Converts a number to a string. nNumber nDecimalPlaces Number. The number to convert. Number. The number of decimal places you want in strString.
2-121
Chapter 2
strString Return Value
Receive String. The string converted from nNumber.
nLength is the length of strString, including the decimal point. strString is the string converted from nNumber.
See Also Example
SalNumberToStrX SalStrToNumber
On SAM_Click Set nLength = SalNumberToStr ( 124.5, 1, strString )
SalNumberToStrX
Syntax Description Parameters strString = SalNumberToStrX ( nNumber, nDecimalPlaces) Converts a number to a string. nNumber nDecimalPlaces strString Return Value Number. The number to convert. Number. The number of decimal places you want in strString. Receive String. The string converted from nNumber.
nLength is the length of strString, including the decimal point. strString is the string converted from nNumber.
See Also Example
SalNumberToStr SalStrToNumber
On SAM_Click Set df2 = SalNumberToStrX ( df1, 2 )
SalNumberToWindowHandle
Syntax Description Parameters Return Value See Also Example hWnd = SalNumberToWindowHandle ( nWnd ) Converts a number to a window handle. nWnd Number. The number to convert.
hWnd is the window handle converted from nWnd. SalWindowHandleToNumber If the tblCustomer table window has been populated, when the user double clicks on a table window row, more information about this customer appears. When the SAM_DoubleClick message is processed, this example creates the frmCustomer form window. SalWindowHandleToNumber converts the table window's handle to a
2-122
SalNumberTruncate
number. SalSendMsg sends the form window the table window's handle as a number. SalNumberToWindowHandle converts the lParam parameter back into the table window's handle.
Table Window: tblCustomer ... Message Actions On SAM_Create Set hWndtblCustomer = hWndForm ! Populate Table Window On SAM_DoubleClick Set hWndfrmCustomer = SalCreateWindow (frmCustomer, hWndNULL ) ! Convert the hWndtblCustomer window handle to a number Set ntblCustomer = SalWindowHandleToNumber (hWndtblCustomer ) ! Send the PASS_HWND message to the form window ! with lParam set to ntblCustomer Call SalSendMsg ( hWndfrmCustomer, PASS_HWND, 0, ntblCustomer ) ! Hide the table window Call SalHideWindow ( hWndForm ) On SHOW_WND Call SalShowWindow ( hWndForm ) Form Window: frmCustomer ... Message Actions On PASS_HWND ! Convert lParam back into the window handle hWndtblCustomer Set hWndtblCustomer = SalNumberToWindowHandle (lParam ) Set strCustomer = tblCustomer.colCustomer ... On SAM_Destroy ! Make table window visible again Call SalSendMsg ( hWndtblCustomer, SHOW_WND, 0, 0 )
SalNumberTruncate
Syntax Description Parameters nResult = SalNumberTruncate ( nNumber, nPrecision, nScale ) Truncates a number. nNumber nPrecision nScale Number. The number to truncate, starting with the leftmost. Number. The number of digits to display, starting with the leftmost. Number. The number of digits to the right of the decimal point. The nPrecision parameter must be large enough to hold the number of digits that you specify in this parameter.
2-123
Chapter 2
nResult is the result of truncating nNumber.

On SAM_Click Set nNum = SalNumberTruncate( 10.0625, 4, 4 ) ! nNum is .0625
SalObjCreateFromString
Syntax Description Parameters: Return Value Example RefObject = SalObjCreateFromString( StrClassName ) Creates an object of a user-defined class. The class name will be determined by the value of StrClassName. StrClassName String. The name of the user-defined class.
Reference. Reference to the object created if the function succeeds, OBJ_Null if the function fails.
Class Definitions Internal Functions Function: GetAnimalObj Description: Returns: CAnimal Parameters: Static Variables Local Variables Actions Return SalObjCreateFromString( CAnimal )
See Also
SalObjIsDerived() SalObjGetType() SalObjIsNull() SalObjIsValidClassName()
SalObjGetType
Syntax Description StrClassName = SalObjGetType( RefObject ) Determine the class name of the object referred to by RefObject. This function call returns the actual type of the object referred to by RefObject, not the declared type of RefObject. RefObject Reference. Reference to the object whose class name is to be determined.
String. Class name of the object referred to by RefObject if successful, STRING_Null if unsuccessful.
2-124
SalObjIsDerived
Example
Call SalMessageBox( "Class type of RefAnimal is: " || SalObjGetType( RefAnimal ), "", MB_Ok )
See Also
SalObjCreateFromString() SalObjIsDerived() SalObjIsNull() SalObjIsValidClassName()
SalObjIsDerived
Syntax Description bDerived = SalObjIsDerived( RefObject, StrClassName ) Determine if the object referred to by RefObject is an instance a certain user-defined class, StrClassName, or an instance of a subclass inherited from the user-defined class. RefObject StrClassName Return Value Reference. Reference to the object in question. String. The name of the class to use for the match.
Parameters
TRUE if RefObject is an instance of the class identified by the value of StrClassName or if RefObject is an instance of a subclass of the class identified by the value of StrClassName; FALSE otherwise.
Example
Functional Class: CAnimal Derived From: Functional Class: CDog Derived From: CAnimal Local Variable: CAnimal: RefAnimal CDog: Ref Dog On Sam_AppStartup If ( SalObjIsDerived( RefAnimal), CAnimal) Call SalMessageBox( RefAnimal is a type of CAnimal object, , MB_Ok ) If( SalObjIsDerived( RefDog ), CAnimal ) Call SalMessageBox( RefDos is a type of CAnimal object, , MB_Ok )
See Also
SalObjCreateFromString SalObjGetType SalObjIsNull SalObjIsValidClassName
2-125
Chapter 2
SalObjIsNull
Syntax Description Parameters Return Value Example bOK = SalObjIsNull( varClassInst ) This function checks to see if the variable of a functional, coclass, or interface class is null. varClassInst A variable of a functional, coclass, or interface class.
Returns TRUE if the parameter is a null reference, and FALSE if it is not.

Functional Class: CAnimal Local Variable: CAnimal: RefAnimal = OBJ_Null On Sam_AppStartup If ( SalObjIsNull( RefAnimal ) ) Set RefAnimal = SalObjCreateFromString( "CAnimal" )
The following are equivalent:

If SalObjIsNull( udvVar )
and
If udvVar = OBJ_Null
See Also
SalObjCreateFromString SalObjGetType SalObjIsDerived SalObjIsValidClassName
SalObjIsValidClassName
Syntax bValidClassName = SalObjIsValidClassName( StrClassName ) Determine whether StrClassName holds a valid user-defined class name. Parameters Return Value Example StrClassName String. Name of the class to check.
TRUE if StrClassName holds a valid user-defined class name, FALSE otherwise.

Functional Class: CAnimal Derived From: Functional Class: CDog Derived From: CAnimal Local Variable: CAnimal: RefAnimal
2-126
SalParentWindow
On Sam_AppStartup: If ( SalObjIsValidClassName( "CDog" ) AND SalObjIsDerived( RefAnimal, "CDog" ) Set RefAnimal = SalObjCreateFromString( "CDog" )
See Also
SalObjCreateFromString SalObjGetType SalObjIsDerived SalObjIsNull
SalParentWindow
Syntax Description hWndParent = SalParentWindow ( hWnd ) Returns the handle of an objects parent window. The following table shows the SalParentWindow behavior with tool bars and MDI windows:
Where called Tool bar child in a top-level object. Tool bar child in an MDI window. Child table window in a tool bar. Parameter hWndItem hWndItem hWndForm Return Handle of the top-level object that contains it (hWndForm). Handle of the MDI window that contains it (hWndMDI). Handle of the top-level object that contains it (hWndForm is the handle of the table window). Handle of hte MDI window that contains it (hWndMDI).
Top-level object in an MDI window.
hWndForm
hWnd
Window Handle. The handle (or name) of the object whose parent window handle you want.
hWndParent is the parent window handle of hWnd. If hWnd is a top-level window, hWndParent is the window handle of the owner window, as passed to SalCreateWindow, otherwise hWndParent is equal to hWndNull.
Set hWndParent = SalParentWindow ( hWnd )
Example
SalPause
Syntax bOk = SalPause ( nMilliseconds )
2-127
Chapter 2
Description Parameters Return Value Example
Causes a non-blocking pause in the application. Use this with caution, especially in COM environments, as it may cause issues with re-entrant code. nMilliseconds Number. The length of the pause, in milliseconds
bOk is TRUE if the function succeeds and FALSE if if fails. Call SalPause (500)
SalPicClear
Syntax Description Parameters Return Value See Also bOk = SalPicClear ( hWndToClear ) Deletes the contents of a picture. hWndToClear Window Handle. The handle (or name) of a picture.
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid picture. SalPicSet SalPicSetFile SalPicSetFit SalPicSetString
Call SalPicClear ( hWndPicture )
Example
SalPicGetDescription
Syntax Description Parameters nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen ) Retrieves a description of a picture's contents. An example of a description is "Microsoft Draw". hWndPict strDesc Window Handle. The handle (or name) of a picture. Receive String. A description of the contents of hWndPict. For a graphic image, SalPicGetDescription returns one of the following values:
Value Gupta:BMP Gupta:GIF Gupta:ICO Gupta:PCX Image Type Device-Independent Bitmap Graphics Interchange Format Icon File Paintbrush
2-128
SalPicGetImage
Gupta:TIFF Gupta:WMF
Tag Image File Format Windows MetaFile
For a file, SalPicGetDescription returns 'Gupta:DOSFILE'. For an OLE object, SalPicGetDescription returns the description of the object class that the server application recorded in the Windows registration database, followed by the word "Object". For example: Package Object Paintbrush Picture Object Sound Object nMaxLength Return Value See Also Example Number. The maximum length of the text to retrieve.
nLength is the length (in bytes) of strDesc. SalPicGetSting

Set nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )
SalPicGetImage
Syntax Description Parameters bOk = SalPicGetImage ( hWndPict, strImageBytes, nType )
Copies the contents of a picture to an image without the SQLWindows image header. You
will be told what kind of image format it is. hWndPict strImageBytes nType Window handle. The handle (or name) of a picture. Receive String. The contents of hWndPict. Receive Number. Receives the format of the picture contents: PIC_ImageTypeNone PIC_ImageTypeBMP PIC_ImageTypeICON PIC_ImageTypeWMF PIC_ImageTypeTIFF PIC_ImageTypePCX PIC_ImageTypeGIF PIC_ImageTypeJPEG
2-129
Chapter 2
PIC_ImageTypeNuVEQ PIC_ImapeTypeOBJECT Return Value See Also nLength is the length (in bytes) of strPict. If the format is not available, nLength is zero. SalPicClear SalPicGetDescription SalPicSet SalPicSetFile SalPicSetFit SalPicSetHandle SalPicSetImage SalPicSetString None
Example
SalPicGetString
Syntax Description Parameters nLength = SalPicGetString ( hWndPict, nFormat, strPict ) Copies the contents of a picture to a string. hWndPict nFormat Window handle. The handle (or name) of a picture. Number. The format of the picture contents:
PIC_FormatBitmap PIC_FormatIcon PIC_FormatObject
strPict Return Value See Also Example
Receive String. The contents of hWndPict.
nLength is the length (in bytes) of strPict. If the format is not available, nLength is equal to zero (0). SalPicGetDescription
Set nLength = SalPicGetString ( hWndPict, nFormat, strPict )
SalPicSet
Syntax Description Parameters bOk = SalPicSet ( hWndPic, tResource, nFormat ) Inserts a resource into a picture. hWndPic Window Handle. The handle (or name) of a picture.
2-130
SalPicSetFile
tResource nFormat
Template. An icon or bitmap in the Resources section of the outline. Number. The resource type. If you specify zero, SQLWindows determines the resource type. Otherwise, specify one of these values: PIC_FormatBitmap PIC_FormatIcon
bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSetFile SalPicSetFit SalPicSetString
Set bOk = SalPicSet ( hWndPic, tResource, nFormat )
Example
SalPicSetFile
Syntax Description Parameters bOk = SalPicSetFile ( hWndPict, strFileName ) Inserts a file's contents into a picture. hWndPict strFileName Window Handle. The handle (or name) of a picture. String. The name of the file whose contents are to be inserted into hWndPict. SQLWindows derives a picture's file type from the file extension. The file extension of a bitmap must be .BMP; the file extension of an icon must be .ICO. Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSet SalPicSetFit SalPicSetString
Set bOk = SalPicSetFile ( hWndPict, strFileName )
Example
SalPicSetFit
Syntax Description bOk = SalPicSetFit ( hWndPict, nFit, nScaleWidth, nScaleHeight ) Sets the fit for a picture.
2-131
Chapter 2
Parameters
hWndPict nFit
Window Handle. The handle (or name) of a picture. Number. The type of fit: PIC_FitBestFit PIC_FitScale PIC_FitSizeToFit
nScaleWidth nScaleHeight Return Value See Also
Number. The width scaling percentage if nFit is PIC_FitScale. Number. The height scaling percentage if nFit is PIC_FitScale.
bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSet SalPicSetFile SalPicSetString
Call SalPicSetFit ( hWndItem, PIC_FitBestFit, 0, 0 )
Example
SalPicSetHandle
Syntax Description Parameters bOk = SalPicSetHandle ( hWnd, nType, nHandle) Sets the picture image of a picture window with the handle of a bitmap (HBITMAP) or icon (HICON). Usually, HBITMAPs and HICONs are loaded from DLLs. hWnd nType nHandle Return Value Example See Also Window handle. The handle (or name) of the picture window. Number. Set this to PIC_FormatIcon if nHandle is an HICON or to PIC_FormatBitmapif nHandle is an HBITMAP. Number. An HBITMAP or HICON.

Set bOk = SalPicSetHandle (hWnd, nType, nHandle)
SalPicClear SalPicGetDescription SalPicGetString SalPicSet SalPicSetFile SalPicSetFit

SalPicSetString
2-132
SalPicSetImage
SalPicSetImage
Syntax Description Parameters bOk = SalPicSetImage ( hWndPict, strImageBytes, nType ) Inserts the contents of a string to a picture object without the SQLWindows image header. hWndPict strImageBytes nType Window handle. The handle (or name) of a picture. Receive String. The contents of hWndPict. Number. The format of the picture contents: PIC_ImageTypeNone PIC_ImageTypeBMP PIC_ImageTypeICON PIC_ImageTypeWMF PIC_ImageTypeTIFF PIC_ImageTypePCX PIC_ImageTypeGIF PIC_ImageTypeJPEG PIC_ImageTypeNuVEQ Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicGetDescription SalPicGetImage SalPicSet SalPicSetFile SalPicSetFit SalPicSetHandle SalPicSetString None
Example
SalPicSetString
Syntax Description Parameters bOk = SalPicSetString ( hWnd, nFormat, strPicture ) Inserts the contents of a string into a picture. hWnd Window Handle. The handle (or name) of a picture.
2-133
Chapter 2
nFormat
Number. The format of the picture contents: PIC_FormatBitmap PIC_FormatIcon PIC_FormatObject
strPicture
String. A memory image of a picture file. You can use SalFileRead to read a bitmap file into a string. You can also SELECT a long varchar database column that contains a bitmap or icon file into a string.
bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSet SalPicSetFile SalPicSetFit
Call SalPicSetString ( hWndPicture, PIC_FormatBitmap, strPicture )
Example
SalPixelsToFormUnits
Syntax Description nFormUnits = SalPixelsToFormUnits ( hWnd, nNumPixels, bVertical ) Computes the number of SQLWindows form units based on the number of pixels. SQLWindows form units is a unit of measurement used by functions that move and position objects. Form units are computed by SQLWindows using physical units (pixels) in conjunction with a window's font sizes. hWnd nNumPixels bVertical Window Handle. The handle (or name) of a window whose form units you want to compute. Number. The number of pixels. Boolean. If the pixels are on the X axis, set this parameter to FALSE. If the pixels are on the Y axis, set this parameter to TRUE.
Parameters
nFormUnits is the number of form units returned if the function call is successful. nFormUnits is equal to zero (0) if hWnd is invalid. SalFormUnitsToPixels
Set nFormUnits = SalPixelsToFormUnits ( pbExample, nPixels, FALSE )
2-134
SalPostMsg
SalPostMsg
Syntax Description Parameters bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam ) Posts the specified message to a window by adding nMsg to hWndReceiver's message queue. hWndReceiver nMsg nMywParam nMylParam Return Value See Also Example Window Handle. The handle (or name) of the window receiving the message. Number. The message number. Number. The wParam for the message. Number. The lParam for the message.
bOk is TRUE if the function succeeds and FALSE if it fails. SalSendMsg SalSendMsgToChildren
Set bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )
SalPrtExtractRect
Syntax Description Parameters bOk = SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom ) Extracts the currently printing rectangle from the SAM_Print message's lParam parameter. nMylParam nLeft nTop nRight nBottom Return Value Example Number. The SAM_Print message's lParam parameter. Receive Number. The position on the X axis of the rectangle's left side. Receive Number. The position on the Y axis of the top of the rectangle. Receive Number. The position on the X axis of the rectangle's right side. Receive Number. The position on the Y axis of the bottom of the rectangle.

On SAM_Print Call SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom )
2-135
Chapter 2
SalPrtGetDefault
Syntax Description Parameters bOk = SalPrtGetDefault ( strDevice, strDriver, strPort ) Returns the default device (printer), the default driver, and the default port. strDevice strDriver strPort Return Value See Also Example Receive String. The default device. Receive String. The default driver. Receive String. The default port.
bOk is TRUE if the function call is successful in getting the default values, and FALSE otherwise. SalPrtSetDefault SalPrtSetup
Message Actions Call SalPrtGetDefault ( strDevice, strDriver, strPort )
SalPrtGetParmNum
Syntax Description bOk = SalPrtGetParmNum ( nParm, nValue ) Gets the value of a print parameter. The print parameters are a set of global variables which are initialized to default values and can be set using SalPrtSetParmNum, retrieved using SalPrtGetParmNum or reinitialized using SalPrtSetParmDefaults. nParm nValue Return Value See Also Example Number. The print parameter whose value you want; one of the PRT_* constants. Receive Number. The print parameter's value. For boolean parameters, nValue is TRUE or FALSE.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalPrtSetParmNum

On SAM_Create Call SalPrtGetParmNum ( PRT_nDraftMode, nPrtValue) If nPrtValue Set rbDraftMode = TRUE Else Set rbProofMode = TRUE
SalPrtPrintForm
Syntax bOk = SalPrtPrintForm ( hWndForm )
2-136
SalPrtSetDefault
Description
Prints a form window, table window, or dialog box, including its contents and row header flags. If a form window or dialog box contains a child table window, list box or combo box, only the rows on screen print. Lines, frames, and pictures print as well. SQLWindows tries to print a window in the font displayed on screen. For best results, use only those fonts supported by your printer. If the window is wider or higher than the paper size, the window prints on as many pages as needed.
hWndForm
Window Handle. The handle (or name) of the window to print.

Call SalPrtPrintForm ( hWndForm )
SalPrtSetDefault
Syntax Description Parameters bOk = SalPrtSetDefault ( strDevice, strDriver, strPort ) Sets the default device (printer), driver, and port. strDevice strDriver strPort Return Value See Also Example String. The default device. String. The default driver. String. The default port.
bOk is TRUE if the function succeeds and FALSE if it fails. SalPrtGetDefault SalPrtSetup
Set strDevice = 'PostScript Printer' Set strDriver = 'PSCRIPT' Set strPort = 'LPT2' Call SalPrtSetDefault ( strDevice, strDriver, strPort )
SalPrtSetParmDefaults
Syntax Description bOk = SalPrtSetParmDefaults ( ) Resets print parameters back to their default values. The print parameters are a set of global variables which are initialized to default values and can be set using SalPrtSetParmNum, retrieved using SalPrtGetParmNum or reinitialized using SalPrtSetParmDefaults. Number of copies: 1
2-137
Chapter 2
Print in draft mode: FALSE Print all pages: TRUE Print from page: 1 Print to page: 1 Left margin: 0 Top margin: 0 Draw a rectangle around the printed form: FALSE Parameters Return Value Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails.
On SAM_Click Call SalPrtSetParmDefaults ( )
SalPrtSetParmNum
Syntax Description bOk = SalPrtSetParmNum ( nParm, nValue ) Sets the value of a print parameter. The print parameters are a set of global variables which are initialized to default values and can be set using SalPrtSetParmNum, retrieved using SalPrtGetParmNum or reinitialized using SalPrtSetParmDefaults. nParm nValue Return Value See Also Example Number. A constant that represents the parameter to set; one of the PRT_* constants. Number. The parameter value.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalPrtGetParmNum

If rbDraftMode Call SalPrtSetParmNum ( PRT_nDraftMode, TRUE)
SalPrtSetup
Syntax Description bOk = SalPrtSetup ( strDevice, strDriver, strPort, bActiveOnly ) Displays the Printer Setup dialog box that lets the user alter the printer setup. Initially, the current default printer is displayed and the user may change the printer. SalPrtSetup returns the user's selections in the Receive Strings. strDevice Receive String. The device (printer).
Parameters 2-138
SalQueryFieldEdit
strDriver strPort bActiveOnly
Receive String. The driver. Receive String. The port. Boolean. Whether to display active and/or inactive printers: if TRUE, all printers display and if FALSE, only active printers display.

Message Actions Call SalPrtSetup ( strDevice, strDriver, strPort, TRUE)
SalQueryFieldEdit
Syntax Description bSet = SalQueryFieldEdit ( hWndField ) Returns the setting of the field edit flag for an editable data field, multiline field, combo box, table window's context row cell, or picture. The field edit flag is set whenever the user changes the value of a data field, multiline text field, or table window column. For a picture, the field edit flag is set whenever an OLE server application is opened for editing. The field edit flag is unset (set to FALSE) if you make the change with a Set statement or a fetch from the database. This function does not clear the field edit flag of hWndField. Parameters Return Value See Also Example hWndField Window Handle. The handle (or name) of a data field, multiline field, combo box table window column, or picture.
bSet is TRUE if hWndField's field edit flag is set and FALSE otherwise. SalSendValidateMsg SalSetFieldEdit
If SalQueryFieldEdit ( SalGetFocus () ) If SalSendValidateMsg ( ) = VALIDATE_Ok ! Process Save.
SalQuit
Syntax Description bOk = SalQuit ( ) Exits an application. If you are in user mode, SQLWindows returns you to design mode. If the application running from SQLRUN.EXE, it exits. Parameters No parameters.
2-139
Chapter 2
bOk is TRUE if the function succeeds and FALSE if it fails. SalAbort

On SAM_Click Call SalQuit ( )
SalReportClose
Syntax Description Parameters Return Value Example bOk = SalReportClose ( hWndReport ) Closes a report window. Call this function when you want to close a report preview window. hWndReport Window Handle. The handle (or name) of a report window.
bOk is TRUE if the function succeeds and FALSE if hWndReport is invalid.

If not SalReportClose ( hWndReport ) Call SalMessageBox ( 'Close Failed', 'SalReportClose', MB_Ok )
SalReportCmd
Syntax Description bOk = SalReportCmd ( hWndReport, nCommand ) Sends a command to an open report window. Use SalReportCmd to control a window that displays a report. When you call SalReportView, its second parameter contains the handle of the window in which the report displays. The application creates that window. Use SalReportCmd to send commands that control the window to Report Builder. If SalReportView's second parameter is null, Report Builder creates its own window in which to display the report, and you cannot use SalReportCmd. Parameters hWndReport nCommand Return Value Example Window Handle. The window handle (or name) of a report window. Number. The command to send to the report. Possible values include any of the RPT_Cmd* commands.

Set bOk = SalReportCmd ( hWndReport, nCommand )
SalReportCreate
2-140
SalReportDlgOptions
Syntax Description Parameters
bOk = SalReportCreate ( strTemplate, strVariables, strInputs, bDefaultReport, nError ) Creates a report template. strTemplate strVariables String. The name of the report template to create. String. A comma-separated list of SQLWindows variables that contain data to fetch. The data types of these variables must match the data types of the input names in strInputs. String. A comma-separated list of the report's input names. Boolean. If TRUE, SQLWindows generates a quick report and nError is a RPT_Err* value. If FALSE, SQLWindows generates an empty report. Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. If you call SalReportCreate ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportCreate.
strInputs bDefaultReport
nError
bOk is TRUE if the function succeeds and FALSE if it fails. If bOk is FALSE, nError is a RPT_Err* value.
Call SalReportCreate ( 'quick.qrp',':nDiv,:nDept,:nSection, :nEmplNum )
SalReportDlgOptions
Syntax Description bOk = SalReportDlgOptions ( hWndReport, strCaption, strLine1, strLine2, strDocName ) Sets the options for the report printing dialog box. Call this function after creating the report but before printing begins. For example, you can call SalReportDlgOptions while processing the SAM_ReportFetchInit message. hWndReport strCaption Window Handle. The wParam of a SAM_Report* message that contains the window handle. String. The replacement text for the Print dialog box caption text.
Parameters
2-141
Chapter 2
strLine1 strLine2 strDocName Return Value Example
String. The replacement text for the first centered-text field. String. The replacement text for the second centered-text field. String. The name of the document that Print Manager displays when the output is spooled and waiting to print.

Call SalReportDlgOptions ( SalNumberToWindowHandle (wParam ), 'Sales Report', 'This is a long report', 'Hit CANCEL to quit', 'sales.rpt' )
SalReportGetDateTimeVar
Syntax Description Parameters bOk = SalReportGetDateTimeVar ( hWndReport, strVariable, dtValue ) Returns the value of a date/time report variable. hWndReport strVariable dtValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of a date/time report variable. Receive Date/Time. The value of strVariable.
bOk is TRUE if the function is successful, and FALSE otherwise. SalReportGetNumberVar SalReportGetObjectVar SalReportGetStringVar SalReportSetDateTimeVar
Call SalReportGetDateTimeVar ( hWndReport, strVariable, dtGet )
Example
SalReportGetFileInfo
Syntax Description Parameters bOk = SalReportGetFileReport ( strFileName, strFileInfo ) Returns the comment which was embedded in a report template at design time. strFileName strVariable String. The name of a file containing a Report Builder template. Receive String. The string that should hold the comment.
Return Value
bOk is TRUE if the function is successful, and FALSE otherwise.
2-142
SalReportGetNumberVar
Example
Call SalReportGetFileInfo ( mytemplate.cqt, sComment)
SalReportGetNumberVar
Syntax Description Parameters bOk = SalReportGetNumberVar ( hWndReport, strVariable, nValue ) Returns the value of a number report variable. hWndReport strVariable nValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of a number report variable. Receive Number. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetDateTimeVar SalReportGetObjectVar SalReportGetStringVar SalReportSetNumberVar
Call bOk = SalReportGetNumberVar ( hWndToMove, nXOffset, nYOffset )
Example
SalReportGetObjectVar
Syntax Description Parameters bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue ) Returns the value of an object report variable. hWndReport strVariable strValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of an object report variable. Receive String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetStringVar SalReportSetObjectVar
Set bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )
Example
SalReportGetPrinterSettings
2-143
Chapter 2
Syntax
bOk = SalReportGetPrinterSettings( hWndReport, strPrinterName, nOrientation, nPaperType, nWidth, nHeight) Gets the printer settings for a report at runtime. You must wait until processing of message SAM_ReportStart is complete before calling this function. else the settings retrieved may be incorrect. hWndReport : strPrinterName: nOrientation : RPT_Portrait RPT_Landscape Receive number. Paper type. Can be one of the following constants Report window handle. The handle of the report window Receive string. The friendly name of the printer. Receive number. Orientation. Can be one of the following constants
Description
Parameters
nPaperType: nWidth : nHeight : Return Value See Also
RPT_PaperA3 RPT_PaperA4 RPT_PaperA5 RPT_PaperB5 RPT_PaperLegal RPT_PaperLetter RPT_PaperTabloid RPT_PaperCustom Receive number. Paper width in milli-inches. Receive number. Paper height in milli-inches.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportSetPrinterSettings SalReportGetPrinterTray SalReportSetPrinterTray
Example
2-144
SalReportGetPrinterTray
Variables String: String: String: Number: Number: Number: Number:
sPrinterName sFirstPageTray sOtherPagesTray nOrientation nPaperType nPaperWidth nPaperHeight
Message Actions On SAM_ReportStart Call SalReportGetPrinterSettings( SalNumberToWindowHandle(wParam), sPrinterName, nOrientation, nPaperType, nPaperWidth, nPaperHeight )
SalReportGetPrinterTray
Syntax Description Parameters bOk = SalReportGetPrinterTray(hWndReport,nPage,strTrayName) Gets the printer tray that will be used for the a specific page printed for a report at runtime. hWndReport : nPage: Report window handle. The handle of the report window Receive Number. The number of the page, or one of these constants: RPT_PageAll, RPT_PageFirst, RPT_PageLast, RPT_PageOdd, RPT_PageEven. String. Friendly name of the tray where the page is to be printed. The names of printer trays are determined by the Windows Control Panel properties of the printer that is being used. Some printer drivers do not offer tray names.
strTrayName :
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportSetPrinterTray SalReportGetPrinterSettings SalReportSetPrinterSettings
Variables Number: nPage Message Actions On SAM_ReportStart Set nPageNumber = 0 On SAM_ReportNotify If lParam = RPT_StartPagePrint
Example
2-145
Chapter 2
Set nPageNumber = nPageNumber + 1 If nPageNumber = 1 Call SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageFirst,'Lower Paper tray' ) Else Call SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageAll,'Upper Paper tray' )
SalReportGetStringVar
Syntax Description Parameters bOk = SalReportGetStringVar ( hWndReport, strVariable, strValue ) Returns the value of a string report variable. hWndReport strVariable strValue Return Value Window Handle. The handle (or name) of a report window. String. The name of a string report variable. Receive String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. See Also SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetObjectVar SalReportSetStringVar
Example
Call SalReportGetStringVar ( hWndReport, 'strVariable', strGet )
SalReportPrint
Syntax Description hWndRet = SalReportPrint ( hWndFrm, strTemplate, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr ) Prints a report. This function is synchronous and does not return until the report has been formatted and sent to Windows or Windows Print Manager for printing. SalReportPrint creates a minimized Report Builder window. A print status dialog box displays while printing. When this function completes, Report Builder automatically ends.
2-146
SalReportPrint
Note: This function establishes a dialog between Report Builder and the application; the real work of reporting is in processing the SAM_Report* messages which Report Builder sends. SQLWindows sends data from an application to Report Builder when the application returns TRUE in SAM_ReportFetchNext processing. Report Builder continues to send SAM_ReportFetchNext messages until the application returns FALSE. Parameters hWndFrm strTemplate strVariables Window Handle. The handle (or name) of the application window that processes SAM_Report* messages. String. The report template name. String. A comma-separated list of SQLWindows variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs. String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template. nCopies nOptions Number. The number of copies. If you specify a zero or a negative number, SQLWindows prints one copy. Number. You can combine two or more of these constants with the OR (|) operator:
RPT_PrintAll RPT_PrintDraft RPT_PrintNoAbort RPT_PrintNoErrors RPT_PrintNoWarn RPT_PrintRange
strInputs
nFirstPage nLastPage nErr
Number. The first page of the report (if nOptions includes RPT_PrintRange). Number. The last page of the report (if nOptions includes RPT_PrintRange). Receive Number. If this function succeeds, this parameter is zero. If an error occurs, this parameter is one of the RPT_Err* values.
Note: If you call SalReportPrint ten times in a row, you will receive the following error code:
RPT_ErrMaxRps.
2-147
Chapter 2
In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportPrint. Return Value The return value is reserved for future use and can be ignored. To detect if the function succeeded, check nErr which is a RPT_Err* value. If successful, nErr is zero. If you want to interact with the report window, interrogate wParam at SAM_ReportStart and save that into the hWndReport variable. See Also Example SalReportPrintToFile
Call SalReportPrint ( frmMain, strReportFile, strReportBinds, strReportInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr )
SalReportPrintToFile
Syntax Description hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr ) Prints a report to a file in RTF format or in ASCII text format. This function is synchronous and does not return until the output report file is closed. Parameters hWndFrm strTemplate strDestFile strVariables Window Handle. The handle (or name) of the application window that processes the SAM_Report* messages. String. The report template name. String. The destination file name. String. A comma-separated list of SQLWindows variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs. String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template. nCopies nOptions Number. The number of copies. Number. You can combine two or more of these constants with the OR (|) operator: RPT_PrintAll
strInputs
2-148
SalReportReset
RPT_PrintDraft RPT_PrintNoAbort RPT_PrintNoErrors RPT_PrintNoWarn RPT_PrintRange nFirstPage nLastPage bFormat nErr Number. The first page of the report (if nOptions includes RPT_PrintRange). Number. The last page of the report (if nOptions includes RPT_PrintRange). Boolean. Specify TRUE to write the report in RTF format; specify FALSE to write the report in ASCII format. Receive Number. If this function succeeds, this parameter is zero. If an error occurs, this parameter is one of the RPT_Err* values. If you call SalReportPrintToFile ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportPrintToFile. Return Value See Also Example The return value is reserved for future use and can be ignored. To detect if the function succeeded, check nErr which is a RPT_Err* value. If successful, nErr is zero. SalReportPrint
Set hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )
SalReportReset
Syntax Description bOk = SalReportReset ( hWndReport ) Re-populates the report window. This function re-sends the SAM_ReportFetchInit message, and one or more SAM_ReportFetchNext messages to populate the report window with the new data. hWndReport Window Handle. The handle (or name) of the report window.

2-149
Chapter 2
Example
If NOT SalReportReset ( hWndReport ) Call SalMessageBox ( 'Reset Failed', 'SalReportReset', MB_Ok )
SalReportResetPages
Syntax Description bOk = SalReportResetPages ( hWndReport, strBreakGroupName ) Resets the current page number, and total number of pages, when a change in the value of a break group is detected. Calling this function at runtime is equivalent to using the Reset Pages feature in Report Builders Report, Format Report menu item at design time. The break group that you specify must have at least one line that uses the Page Break Before option, else the page numbers will not be set correctly. Call this function during message processing for these messages: SAM_ReportFetchInit, SAM_ReportStart, SAM_ReportFetchNext, and SAM_ReportNotify (except with parameter RPT_StartPagePrint). Parameters hWndReport Window Handle. The handle (or name) of the report window.
strBreakGroupName String. The name of a break group that was previously defined in the Report Builder designer. Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
Call SalReportResetPages ( frmReport, customer )
SalReportSetDateTimeVar
Syntax Description Parameters bOk = SalReportSetDateTimeVar ( hWndReport, strVariable, dtValue ) Sets the value of a date/time report variable. hWndReport strVariable dtValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of the variable whose value you want to set. Date/Time. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar SalReportSetStringVar
If NOT SalReportSetDateTimeVar ( hWndReport,
Example 2-150
SalReportSetNumberVar
'dtVariable', dtGDateTime[1] ) Call SalMessageBox ( 'SetDateTimeError', 'RPT_BeforePageHeader-d', MB_Ok )
SalReportSetNumberVar
Syntax Description Parameters bOk = SalReportSetNumberVar ( hWndReport, strVariable, nValue ) Sets the value of a numeric report variable. hWndReport strVariable nValue Return Value Window Handle. The handle (or name) of a report window. String. The name of the variable whose value you want to set. Number. The value of strVariable.
Related Function SalReportGetNumberVar SalReportSetDateTimeVar SalReportSetObjectVar SalReportSetStringVar Example

Call SalReportSetNumberVar ( hWndReport, 'strUnknown', nVariable )
SalReportSetObjectVar
Syntax Description Parameters bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue ) Sets the value of an object report variable. hWndReport strVariable strValue Return Value See Also Window Handle. The window of the report window handle. String. The name of the variable whose value you want to set. String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetObjectVar SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetStringVar
Set bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue )
Example
2-151
Chapter 2
SalReportSetPrinterSettings
Syntax bOk = SalReportGetPrinterSettings( hWndReport, strPrinterName, nOrientation, nPaperType, nWidth, nHeight) Sets the printer settings for a report at runtime. If needed, this function should be called when processing the actions of SAM_ReportStart. In most cases, passing an invalid value in a parameter causes that parameter to be ignored, and the default printer setting is retained instead. Parameters hWndReport : strPrinterName: Report window handle. The handle of the report window String. Friendly name of the printer. eg: HP LasertJet 5, \\\\machinename\\HP DeskJet 610C (for network printers). Pass STRING_Null or an empty string if you do not want to switch the printer. If you pass an invalid name in this parameter, the function will fail. If you use a network printer name in conjunction with a call to SalReportView, your changes are ignored when the user presses Print from the report viewing window. To ensure that your changes take effect, use a network printer name in conjunction with SalReport Print instead. Number. Orientation. Can be one of the following constants (or use -1 to retain current orientation.)
Description
nOrientation : RPT_Portrait
RPT_Landscape Number. Paper type. Can be one of the following constants (or use -1 to retain current paper type.)
nPaperType: 2-152
RPT_PaperA3 RPT_PaperA4 RPT_PaperA5 RPT_PaperB5 RPT_PaperLegal RPT_PaperLetter
SalReportSetPrinterTray
nWidth :
RPT_PaperTabloid RPT_PaperCustom Number. Paper width in milli-inches. This value is ignored for all paper types except RPT_PaperCustom. Number. Paper height in milli-inches. This value is ignored for all paper types except RPT_PaperCustom.
nHeight : Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetPrinterSettings SalReportGetPrinterTray SalReportSetPrinterTray
Call SalReportSetPrinterSettings( SalNumberToWindowHandle(wParam), HP LaserJet 5, RPT_Portrait, RPT_PaperA4, 0, 0 )
Example
SalReportSetPrinterTray
Syntax Description bOk = SalReportSetPrinterTray(hWndReport,nPage,strTrayName) Sets the printer tray that will be used for the a specific page printed for a report at runtime. If needed, this function should be called when processing the actions of message SAM_ReportNotify when lParam is RPT_StartPagePrint, which signifies that a new page is about to begin. You can also call this function in the SAM_ReportStart message handler, but note that any subsequent call during SAM_ReportNotify will override what was done in SAM_ReportStart. It is your responsibility to keep track of pages printed and call this function as needed. Since it is possible to call SalReportSetTray multiple times, using different parameter values, the potential for conflict exists. For example, if you specify a tray for page 1, and a tray for first page, and a tray for odd-numbered pages, all of these could affect the first page of the report. Which tray will actually be used at runtime? Report Builder evaluates the tray assignments without regard to the order in which they are defined in the report file, or the order in which the SalReportSetTray calls were made. Instead, it compares a given page with the list below (searching from top to bottom). Upon finding the first match, it uses the corresponding tray and ignores any tray associations that may exist farther down in the list. 1. 2. 3. First Last Numeric ( user-supplied number)
2-153
Chapter 2
4. 5. 6.
Odd Even All
Parameters
hWndReport : nPage:
Report window handle. The handle of the report window Number. The number of the page, or one of these constants: RPT_PageAll, RPT_PageFirst, RPT_PageLast, RPT_PageOdd, RPT_PageEven. String. Friendly name of the tray where the next page is to be printed. The names of printer trays are determined by the Windows Control Panel properties of the printer that is being used. Some printer drivers do not offer tray names.
strTrayName :
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetPrinterTray SalReportGetPrinterSettings SalReportSetPrinterSettings
Variables Number: nPage Message Actions On SAM_ReportStart Set nPageNumber = 0 On SAM_ReportNotify If lParam = RPT_StartPagePrint Set nPageNumber = nPageNumber + 1 If nPageNumber = 1 Call SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageFirst,'Lower Paper tray' ) Else Call SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageAll,'Upper Paper tray' )
Example
SalReportSetStringVar
Syntax Description Parameters bOk = SalReportSetStringVar ( hWndReport, strVariable, strValue ) Sets the value of a string report variable. hWndReport Window Handle. The handle (or name) of a report window.
2-154
SalReportTableCreate
strVariable strValue Return Value See Also
String. The name of the variable whose value you want to set. String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetStringVar SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar
Call SalReportSetStringVar ( hWndReport, 'strUnknown', strVariable )
Example
SalReportTableCreate
Syntax Description bOk = SalReportTableCreate ( strReport, hWndTbl, nError ) Creates a report template from the specified table window. The table window column names are the input names to the report and their titles are the column names on the report. For a top-level table window, the report's title is the same as the table window's title; for a child table window, the report does not have a title. strReport hWndTbl nError String. The name of the report. Window Handle. The handle (or name) of a table window. Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. Note: If you call SalReportTableCreate ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportTableCreate. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalReportTablePrint SalReportTableView
Set bOk = SalReportTableCreate ( strReport, hWndTbl, nError )
Parameters
SalReportTablePrint
Syntax hWnd = SalReportTablePrint ( hWndTbl, strReport, nParamArray, nError )
2-155
Chapter 2
Description Parameters
Prints a report created from the specified table window. hWndTbl strReport nParamArray Window Handle. The handle (or name) of a table window. String. The name of the report. Number. An array you create containing information about the print job. The array indexes are: RPT_PrintParamCopies RPT_PrintParamFirstPage RPT_PrintParamLastPage RPT_PrintParamOptions nError Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. If you call SalReportTablePrint ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportTablePrint.
hWnd is the handle of the report window if the function succeeds. SalReportTableCreate SalReportTableView
Set hWndReport = SalReportTablePrint ( hWndTbl, 'test.qrp', nParamArray,nError )
SalReportTableView
Syntax Description Parameters hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError ) Displays, in preview mode, a report created from the specified table window. hWndTbl hWndDisplay Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a report display window. If null, SQLWindows creates a window in which you can preview the report. String. The name of the report.
strReport
2-156
SalReportView
nError
Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* constants. If you call SalReportTableView ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportTableView.
hWnd is the handle of the report window if the function succeeds. SalReportTableCreate SalReportTablePrint
Set hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError )
SalReportView
Syntax Description hWndReport = SalReportView ( hWndFrm, hWndRptTemp, strTemplate, strVariables, strInputs, nFlags ) Displays a report in preview mode. Report processing is asynchronous; SalReportView returns after starting the report process. Note: This function establishes a dialog between Report Builder and the application; the real work of reporting is done in trapping and handling the SAM_Report messages which Report Builder sends. If you are reporting on application variables, an array, or a file, your data is transmitted to the report only if you return TRUE from the SAM_ReportFetchNext message. Report Builder does not receive any data until it issues the SAM_ReportFetchNext message and the SQLWindows application returns TRUE to that message. Report Builder keeps sending SAM_ReportFetchNext messages until SQLWindows returns FALSE. Parameters hWndFrm hWndRptTemp Window Handle. The handle (or name) of the application window that processes SAM_Report* messages. Window Handle. An optional window handle (or name) to a custom report template. If null, Report Builder creates its own window in which it displays the report.
2-157
Chapter 2
strTemplate strVariables
String. The report template name. String. A comma-separated list of SQLWindows variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs. The contents of this string must match the order of the input names declared in the report template.
strInputs
String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template.
nFlags
Receive Number. Before you call this function, you can set this parameter to one of the constants below to turn off the printer icon on the default report view tool bar or turn off the tool bar completely: No print button on the tool bar. No tool bar in the preview window. If an error occurs, this parameter is one of the RPT_Err* constants. If you call SalReportView ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, SQLWindows always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, SQLWindows only displays an error dialog box if you set this parameter to 1 before calling SalReportView.
RPT_NoPrint RPT_NoToolbar
hWndReport is the handle of the report window if the function succeeds. SQLWindows returns the window handle before Report Builder displays the report.
Set hWndReport = SalReportView ( frmMain, hWndNULL, strReportFile, strReportBinds, strReportInputs, nError )
2-158
SalScrollGetPos
SalScrollGetPos
Syntax Description Parameters bOk = SalScrollGetPos ( hWndsb, nPos ) Returns the current scroll bar value. hWndsb nPos Return Value See Also Example Window Handle. The handle (or name) of a vertical or horizontal scroll bar. Receive Number. The scroll bar value.
bOk is TRUE if the function succeeds and FALSE if it fails. SalScrollSetPos

Set bOk = SalScrollGetPos ( hWndsb, nPos )
SalScrollGetRange
Syntax Description Parameters bOk = SalScrollGetRange ( hWndsb, nMin, nMax, nLine, nPage ) Gets a scroll bar's scroll range, line increment, and page increment. hWndsb nMin nMax nLine Window Handle. The handle (or name) of a vertical or horizontal scroll bar. Receive Number. The minimum scroll bar position. Receive Number. The maximum scroll bar position. Receive Number. The line increment. The number of units the scroll bar increments or decrements when the user clicks the scroll bar arrow. Receive Number. The page increment. The number of units the scroll bar increments or decrements when the user clicks either side of the scroll bar's scroll box.
nPage
bOk is TRUE if the function succeeds and FALSE if it fails. SalScrollSetRange

Call SalScrollGetRange ( hWndsbCounter, nMin, nMax, nLine, nPage )
2-159
Chapter 2
SalScrollSetPos
Syntax Description Parameters bOk = SalScrollSetPos ( hWndsb, nPos ) Sets a scroll bar's position. This function is equivalent to using a Set statement to assign a value to the scroll bar. hWndsb nPos Window Handle. The handle (or name) of a vertical or horizontal scroll bar. Number. The scroll bar position. If this value is outside the scroll bar's range, SQLWindows sets the scroll bar position to the scroll range minimum or the scroll range maximum, depending on whether nPos is below or above the range.
bOk is TRUE if the function succeeds and FALSE if it fails. SalScrollGetPos

Call SalScrollSetPos ( hWndsbCounter, 0 )
SalScrollSetRange
Syntax Description bOk = SalScrollSetRange ( hWndsb, nMin, nMax, nLine, nPage ) Sets a scroll bar's range, line increment, and page increment. When the scroll bar is created, SQLWindows assigns it these values:
Minimum scroll position0 Maximum scroll position100 Line Increment1 Page Increment10
If the scroll bar's current position is outside the new range, its position changes to one within the new range. The range of a scroll bar is -32,767 to 32,767. Parameters hWndsb nMin nMax nLine nPage Return Value Window Handle. The handle (or name) of a vertical or horizontal scroll bar. Number. The minimum position of the scroll bar. Number. The maximum position of the scroll bar. Number. The number of units to increment or decrement the scroll bar when the user clicks the scroll bar arrow. Number. The number of units to increment or decrement the scroll bar when the user clicks either side of the scroll box.
2-160
SalSendClassMessage
See Also Example
SalScrollGetRange
Call SalScrollSetRange ( hWndsbCounter, 0, 50, 1, 5 )
SalSendClassMessage
Syntax Description Parameters nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam ) Invokes the message actions implemented or inherited by an object's class when called from either a derived class or from an object that is an instance of a class. nMessage nMywParm nMylParam Return Value See Also Example Number. The message number. Number. The wParam. Number. The lParam.
nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0). SalSendClassMessageNamed
Set nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )
SalSendClassMessageNamed
Syntax Description nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam ) Invokes the message actions implemented or inherited by an object's class when called from either a derived class or from an object that is an instance of a class. Use this function instead of SalSendClassMessage with a class that is the result of multiple inheritance. It lets you specify which base class message action you want to execute. tClassName must be a direct base class of the class from which this call is made. Parameters tClassName nMsg nMywParam nMylParam Return Value Template. The ancestor's class name. Number. The message number. Number. The wParam. Number. The lParam.
nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0).
2-161
Chapter 2
See Also Example
SalSendClassMessage
Set nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam )
SalSendMsg
Syntax Description Parameters nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam ) Sends the specified message to a window. SalSendMsg does not return until the processing for the message is complete. hWnd nMsg nMywParam nMylParam Return Value See Also Window Handle. The window receiving the message. Number. The message number. Number. The wParam. Number. The lParam.
nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0). SalPostMsg SalSendMsgToChildren SalSendValidateMsg
Set nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )
Example
SalSendMsgToChildren
Syntax Description Parameters bSent = SalSendMsgToChildren ( hWnd, nMsg, nMywParam, nMylParam ) Sends a message to all child items of a form window, dialog box, table window, or MDI window. hWnd nMsg nMywParam nMylParam Return Value See Also Window Handle. The handle (or name) of a form window, dialog box, table window, or MDI window. Number. The message number. Number. The wParam for the message. Number. The lParam for the message.
bSent is TRUE if the function succeeds and FALSE if it fails. SalPostMsg SalSendMsg SalSendValidateMsg
2-162
SalSendValidateMsg
Example
Call SalSendMsgToChildren ( hWndForm,CHM_DISABLE, 0, 0 )
SalSendValidateMsg
Syntax Description nStatus = SalSendValidateMsg ( ) Sends a SAM_Validate message to the object with the focus data field, multiline field, or table window column if it was edited and sets the wParam and lParam message variables to zero (0). Call this function to force field validation before processing a menu pick. SQLWindows does not automatically send SAM_Validate message on a menu pick. Parameters Return Value Np parameters. nStatus is returned by the object's message actions for the SAM_Validate message: VALIDATE_Cancel VALIDATE_Ok VALIDATE_OkClearFlag See Also Example SalSendMsg SalSendMsgToChildren
Set nStatus = SalSendValidateMsg ( )
SalSetDefButton
Syntax Description bOk = SalSetDefButton ( hWndButton ) Sets the default push button of a form window or dialog box. When this function returns, the default push button gets the focus only if the focus was on one of the push buttons before you called SalSetDefButton. hWndButton Window Handle. The handle (or name) of the default push button.
bOk is TRUE if the function succeeds and FALSE if hWndButton is not a valid button. SalGetDefButton
Call SalSetDefButton ( frmMain.pb2 )
2-163
Chapter 2
SalSetErrorInfo
Syntax Description bOK = SalSetErrorInfo( nCode, sDesc, sHelpfileName, nHelpContext ) If an error occurs during a method, you can call SalSetErrorInfo to set standard error information. SQLWindows takes the information you supply in this function, fills in a COM EXCEPINFO structure, and passes a pointer to it to the client after the Invoke. An EXCEPINFO structure describes an exception that the server raised. This function does not halt processing. This function should be the last statement that the method executes. nCode
A number identifying the error. This number should be less than 1000 and negative; if this number is zero or positive, SQLWindows converts the value to E_FAIL, the generic error code. The actual error code returned from the Invoke call is DISP_E_EXCEPTION, meaning that the server raised an exception.n.
Parameters
sDesc sHelpfileName nHelpContext Return Value
A textual, human-readable description of the error intended for the end user. The fully qualified drive, path, and file name of a help file with more information about the error. The help context identifier of a topic in the help file. This field is ignored when sHelpfileName is empty.
SalSetFieldEdit
Syntax Description bOk = SalSetFieldEdit ( hWndField, bSet ) Sets or clears the field edit flag for an editable data field, combo box, multiline text field, table window column, or picture. The field edit flag is set whenever the user changes the value of a data field, multiline field, combo box or table window column. For a picture, the field edit flag is set whenever an OLE server application is opened for editing. The field edit flag is unset (set to FALSE) if you make the change with a Set statement or a fetch from a database. Parameters hWndField bSet Window Handle. The handle (or name) of a data field, multiline text field, table window column, or picture. Boolean. TRUE sets the flag; FALSE clears it.
2-164
SalSetFocus
bOk is TRUE if the function succeeds and FALSE if it fails. SalQueryFieldEdit

Call SalSetFieldEdit ( hWndChild, FALSE )
SalSetFocus
Syntax Description hWndFocus = SalSetFocus ( hWndToSet ) Sets the focus to a specified window. Warning: You cannot call SalSetFocus in SAM_KillFocus processing because of a Windows
limitation.
hWndToSet
Window Handle. The handle (or name) of the window to receive the focus.
hWndFocus is the handle of the window that previously had the focus. SalGetFocus
Call SalSetFocus ( hWndSave )
SalSetMaxDataLength
Syntax Description Parameters bOk = SalSetMaxDataLength ( hWndField, nLength ) Sets a limit on the number of characters that a user can enter into a data field, multiline text field, or table window column. hWndField nLength Return Value See Also Example Window Handle. The handle (or name) of a data field, multiline text field, or table window column. Number. The character limit.
bOk is TRUE if the function succeeds and FALSE if it fails. SalGetMaxDataLength
2-165
Chapter 2
Set bOk = SalSetMaxDataLength ( hWndField, nLength )
SalSetProfileString
Syntax Description bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName ) Set the value of an entry in the specified section of an initialization file or registry. All profile information is stored as string, so if you want to store an integer it must be converted to a string first. Then it can be retrieved as an integer using the SalGetProfileInt-Function . strSection strEntry strValue strFileName String. The section heading. String. The entry whose associated value is being set. String. The value of strEntry. String. The name of the initialization file or company name depending on the settings made using the SalUseRegistry function. If you are searching for an INI file and do not specify the full path, SQLWindows searches for the file in the Windows subdirectory.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalGetProfileInt SalGetProfileString SalUseRegistry
Set bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )
Example
SalSetWindowLabelText
Syntax Description bOk = SalSetWindowLabelText ( hWnd, sText ) Sets the background text of a window. To be associated with a specific window, background text must immeditately precede the window in the Outliner. Important: The background text does not require a mnemonic for the function to operate. Parameters hWnd sText Return Value Example 2-166 Window Handle. The handle (or name) of a window. String. The window text.

Set bOk = SalSetWindowLabelText ( hWnd, sText )
SalSetWindowLoc
SalSetWindowLoc
Syntax Description Parameters bOk = SalSetWindowLoc ( hWnd, nX, nY ) Moves a window to a new position (x, y) on the X and Y axes. hWnd nX nY Return Value See Also Example Window Handle. The handle (or name) of the window to move. Number. The position on the X axis (expressed in form units). Number. The position on the Y axis (expressed in form units).
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle. SalGetWindowLoc
Call SalSetWindowLoc ( pbExample, 0, 0 )
SalSetWindowSize
Syntax Description Parameters bOk = SalSetWindowSize ( hWnd, nWidth, nHeight ) Resizes a window. hWnd nWidth nHeight Return Value See Also Example Window Handle. The handle (or name) of the window to resize. Number. The new width of the window (expressed in SQLWindows form units). Number. The new height of the window (expressed in SQLWindows form units).
bOk is TRUE if the window is successfully resized, and FALSE if hWnd is an invalid window handle. SalGetWindowSize
Call SalSetWindowSize ( pbExample, nWidth+1, nHeight+1)
SalSetWindowText
Syntax Description bOk = SalSetWindowText ( hWnd, strTitle ) Sets the text of a window to a specified string. A window's text is the title of a form window, modeless dialog box, table window, radio button, check box, or push button.
2-167
Chapter 2
For a data field or table window column, the text is the object's value in string form, regardless of the object's data type. For a combo box, the text is the contents of the editable data field portion. If the combo box is not editable, SQLWindows tries to set the list selection to the item that matches the specified string. This latter statement is true for list boxes as well. The SalSetWindowText function clears the field edit flag. Parameters hWnd strTitle Return Value See Also Example Window Handle. The handle (or name) of a window. String. The window text.
bOk is TRUE if the function succeeds and FALSE if it fails. SalGetWindowText SalTblSetColumnTitle
Call SalSetWindowText ( hWndForm, 'First National Bank' )
SalShowWindow
Syntax Description Parameters Return Value bOk = SalShowWindow ( hWndToShow ) Makes a window visible. hWndToShoWindow Handle. The handle (or name) of a window to make visible. bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible. SalHideWindow
Call SalShowWindow ( hWndForm )
See Also Example
SalShowWindowAndLabel
Syntax Description bOk = SalShowWindowAndLabel ( hWndToShow ) Makes a window and its associated label visible. A label is the background text that immediately precedes the window in the outline. Parameters Return Value hWndToShow The handle (or name) of a window to make visible.
bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they
2-168
SalStartTrace
are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible. See Also Example SalHideWindowAndLabel SalShowWindow
Set bOk = SalShowWindowAndLabel ( hWndToShow )
SalStartTrace
Syntax Description
bOk = SalStartTrace (nOutputType, strTraceFile, bClearExisting )
Allows tracing to begin. You are responsible for ensuring that existing trace log files do not grow too large.
Parameters
nOutputType
Number. One of the four TRACE_* constants: TRACE_Event outputs information to the Windows event log. (Windows 98 and Windows ME do not have event logging as a built-in operating system feature. In these cases, when TRACE_Event is chosen for nOutputType, the trace information goes to file "TDEvent.log" in the Windows temporary directory.) TRACE_File outputs to the file named in the strTraceFile parameter. TRACE_Output outputs to the SQLWindows output window, which ordinarily displays information such as compile-time errors. This option only works when the SQLWindows application is in debug mode. TRACE_stdout outputs to the standard output device; it is designed to make trace output available to third-party diagnostic applications. String. The name of the file to receive output when nOutputType is TRACE_File. If that output type is chosen but this parameter is left null, a file will be created in the Windows temporary directory. The file name will be the name of the application executable, with a suffix of .LOG. Boolean. Whether existing output should be cleared before new tracing begins..
strTraceFile
bClearExisting Return Value See Also Example
bOk is TRUE if the functions succeeds, and FALSE if it fails. SalTrace SalEndTrace
Call SalStartTrace ( TRACE_Event, '', TRUE )
2-169
Chapter 2
SalStatusGetText
Syntax Description Parameters nLength = SalStatusGetText ( hWnd, strText, nMaxLen ) Gets the text displayed in the status bar of a top-level or MDI window. hWnd strText nMaxLen Return Value See Also Example Window Handle. The handle (or name) of a top-level or MDI window. Receive String. The text displayed in the status bar. Number. The maximum length of the window text.
nLength is the length of strText. nLength is zero (0) if the window has no text. SalStatusSetText SalStatusSetVisible
Set nLength = SalStatusGetText ( hWnd, strText, nMaxLen )
SalStatusSetText
Syntax Description Parameters bOk = SalStatusSetText ( hWnd, strText ) Displays specified text in the status bar of a top-level or MDI window. hWnd strText Return Value See Also Example Window Handle. The handle (or name) of a top-level or MDI window. String. The text to display in the status bar.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStatusGetText SalStatusSetVisible
Set bOk = SalStatusSetText ( hWnd, strText )
2-170
SalStatusSetVisible
SalStatusSetVisible
Syntax Description Parameters bOk = SalStatusSetVisible ( hWnd, bShow ) Shows or hides the status bar on a top-level or MDI window. hWnd Window Handle. The handle (or name) of a top-level or MDI window.
bShoBoolean. If TRUE, the status bar displays; if FALSE, the status bar hides. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalStatusGetText SalStatusSetText
Call SalStatusSetVisible ( hWndForm, TRUE )
SalStrCompress
Syntax Description bOk = SalStrCompress ( strString ) Compresses the specified string. Use this function to compress strings for storage on disk or in the database. Use this function for long strings, or when storing images and so on. Note: when the last character of the string is a null character, you may encounter an error if the compressed string is inserted into a database table, fetched back from that table, and used in SalStrUncompress. This is because some databases will not store the terminating null character. Thus the database string is now shorter by one character, which conflicts with the original string length. To prevent this error, check for the null character and, if present, add code like this line after the call to SalStrCompress:
Call SalStrSetBufferLength( sBuffer, SalStrGetBufferLength( sBuffer ) + 1 )
strString
Receive String. The string to compress.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStrUncompress

Set bOk = SalStrCompress ( strString )
SalStrFirstC
Syntax bOk = SalStrFirstC ( strString, nChar )
2-171
Chapter 2
Description
Extracts the first character of a string and initializes a numeric parameter with its value. If the application has DBCS (double-byte character set) enabled, the number represents the integer value of the 16-bit character. Otherwise, the number represents the ASCII value of the 8-bit character. You must use this function in place of SalStrLop if the input string contains DBCS or 16-bit characters. If the character returned is a 16-bit character, the leading byte of the character is in the high-order byte, and the trailing byte of the character is in the loworder byte. Use SalNumberHigh to get the leading byte and SalNumberLow to get the trailing byte.
Parameters
strString nChar
Receive String. The string whose first character is lopped off. Receive Number. The first character of strString.
bOk is TRUE unless strString is empty or invalid. SalNumberHigh SalNumberLow SalNumberToChar SalStrLop
On SAM_Click Set dfString = 'ABC' Call SalStrFirstC ( dfString, dfNumChar ) ! Now dfString = 'BC' and dfNumChar = 65
Example
SalStrGetBufferLength
Syntax Description nLength = SalStrGetBufferLength ( strString ) Returns the current buffer length of a string. SQLWindows stores string variables in buffers. The length includes the string's null termination character. Parameters Return Value See Also Example strString String. The string whose buffer length you want.
nLength is the length of strString's buffer. SalStrLength SalStrSetBufferLength

Set nBufferLength = SalStrGetBufferLength (strNumbers )
2-172
SalStrIsValidCurrency
SalStrIsValidCurrency
Syntax Description bOk = SalStrIsValidCurrency ( strMoney, nPrecision, nScale ) Verifies that an entire character string represents a valid currency value. SQLWindows validates the string based on the current settings for the keywords sDecimal, sThousands, sCurrency, iNegCurr, and iCurrency in the [INTL] section of WIN.INI. strMoney nPrecision nScale Return Value See Also Example String. A string that contains a currency value. Number. The number of digits to display. Number. The number of digits to the right of the decimal point.
Parameters
bOk is TRUE if strMoney is a valid currency value and FALSE otherwise. SalStrIsValidDateTime SalStrIsValidNumber
Set bOk1 = SalStrIsValidCurrency ( '$120.00' )
SalStrIsValidDateTime
Syntax Description bOk = SalStrIsValidDateTime ( strDateTime ) Verifies that an entire character string represents a valid date/time value. SQLWindows validates the string based on the current settings for the keywords sShortDate, sLongDate, s1159, s2359, and sTime in the [INTL] section of WIN.INI. strDateTime String. A string that contains a date/time value.
bOk is TRUE if strDateTime is a valid date/time value and FALSE otherwise. SalStrIsValidCurrency SalStrIsValidNumber
Set bOk2 = SalStrIsValidDateTime ( '2/2/91' )
SalStrIsValidNumber
Syntax Description bOk = SalStrIsValidNumber ( strNumber ) Verifies that an entire character string represents a valid number value. SQLWindows validates the string based on the current settings for the keywords sDecimal and sThousands in the [INTL] section of WIN.INI. strNumber String. A string that contains a number value.
Parameters
2-173
Chapter 2
bOk is TRUE if strNumber is a valid number value and FALSE otherwise. SalStrIsValidCurrency SalStrIsValidDateTime
Set bOk1 = SalStrIsValidNumber ( '120.00' )
SalStrLeft
Syntax Description Parameters nLength = SalStrLeft ( strSource, nExtract, strTarget ) Returns a substring of a specified length starting at position zero (0), the left-most character in the string. strSource nExtract strTarget String. The string from which to extract characters. Number. The number of characters to extract from strSource. Receive String. The substring.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of the new string. strTarget is the substring. See Also SalStrMid SalStrMidX SalStrRight SalStrLeftX
Set nLength = SalStrLeft ( 'LEFT01234', 4, strTarget )
Examples
SalStrLeftX
Syntax Description Parameters strTarget = SalStrLeftX ( strSource, nExtract) Returns a substring of a specified length starting at position zero (0), the left-most character in the string. strSource nExtract strTarget String. The string from which to extract characters. Number. The number of characters to extract from strSource. Receive String. The substring.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of the new string. strTarget is the substring. 2-174
SalStrLength
See Also
SalStrMid SalStrMidX SalStrRight SalStrLeft

Set strTarget = SalStrLeftX ( 'LEFT01234', 4)
Examples
SalStrLength
Syntax Description nLength = SalStrLength ( strString ) Returns a string's length. Strings are stored internally in SQLWindows with a null termination character. The null terminator is not included in the length. Parameters Return Value See Also Example strString String. The string whose length you want.
nLength is the length of strString. SalStrGetBufferLength

On SAM_Create Set strNumbers = '1234567890' Set nStringLength = SalStrLength ( strNumbers )
SalStrLop
Syntax Description Parameters Return Value See Also Example nCharacter = SalStrLop ( strString ) Returns the ASCII numeric value of the first character of a string in decimal format. This function removes the first character of the string. strString Receive String. The input string without the first character.
nCharacter is the ASCII value of the first character of strString. When strString is null, nCharacter is equal to zero (0). SalNumberToChar SalStrFirstC
On SAM_Create Set strString = 'ABC' Set nCharacter = SalStrLop ( strString )
2-175
Chapter 2
SalStrLower
Syntax nLength = SalStrLower ( strSource, strTarget ) or strTarget = SalStrLowerX ( strSource ) Description Parameters Converts a string to lowercase. strSource strTarget String. The string to convert . Receive String. The lowercase string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the lowercase string. See Also Examples SalStrUpper SalStrUpperX
On SAM_Create Set nLength = SalStrLower ( 'LOWERCASE', strTarget ) or On SAM_Create Set strTarget = SalStrLowerX ( 'LOWERCASE' )
SalStrMid
Syntax nLength = SalStrMid ( strSource, nStartPos, nLength, strTarget ) or strTarget = SalStrMidX ( strSource, nStartPos, nLength ) Description Parameters Returns a substring, starting at a specified position and containing a specified number of characters. strSource nStartPos nLength strTarget String. The source string. Number. The starting position of the substring (zero is the first position) in strSource. Number. The number of characters to put in the substring. Receive String. The substring.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of the substring.
2-176
SalStrMid
strTarget is the substring. See Also SalStrLeft SalStrLeftX SalStrRight

Set nLength = SalStrMid (012ABC345, 3, 3, strTarget) Or Set strTarget = SalStrMidX ( '012ABC345', 3, 3 ) ! strTarget = 'ABC'
Examples
2-177
Chapter 2
SalStrProper
Syntax nLength = SalStrProper ( strSource, strTarget ) or strTarget = SalStrProperX ( strSource ) Description Parameters Converts a string to a proper name. In a proper name, the first letter of each word is uppercase; the remaining letters are lowercase. strSource strTarget String. The string to convert. Receive String. The converted string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the converted string. Examples
Set nLength = SalStrProper ( 'JOHN L. SMITH', strTarget ) or Set strTarget = SalStrProperX ( 'JOHN L. SMITH')
SalStrRepeat and SalStrRepeatX

Syntax nLength = SalStrRepeat ( strSource, nTimes, strTarget ) or strTarget = SalStrRepeatX ( strSource, nTimes ) Description Parameters Concatenates a string with itself a specified number of times. strSource nTimes strTarget String. The source string. Number. The number of times to concatenate strSource with itself. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the new string. Examples
On SAM_Create Set nLength = SalStrRepeat ( 'ABC*', 3, strTarget )
2-178
SalStrReplace and SalStrReplaceX
or On SAM_Create Set strTarget = SalStrRepeatX '( 'ABC*', 3)
SalStrReplace and SalStrReplaceX

Syntax nReturn = SalStrReplace ( strSource, nStartPos, nLength, strReplace, strTarget ) or strTarget = SalStrReplaceX ( strSource, nStartPos, nLength, strReplace ) Description Parameters Replaces characters in one string with characters from another string. strSource nStartPos nLength strReplace strTarget Return Value String. The source string that contains characters to replace. Number. The position in strSource at which to begin replacing characters. Number. The number of characters to replace. String. The replacement string. Receive String. The new string.
nReturn is the length of strTarget. strTarget is the new string.
Examples
Message Actions On SAM_Create Set nReturn = SalStrReplace ('far', 0, 1, 'be', strTarget ) ! strTarget = 'bear' and nReturn = 4 Message Actions On SAM_Create Set strTarget = SalStrReplaceX ('bear', 0, 2, 'f' ) !strTarget = 'far'
SalStrRight and SalStrRightX

Syntax nLength = SalStrRight ( strSource, nLength, strTarget ) or strTarget = SalStrRightX ( strSource, nLength ) Description Returns a string of specified length, starting with the last character in the string.
2-179
Chapter 2
Parameters
strSource nLength strTarget
String. The source string. Number. The number of characters to extract. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the new string. See Also SalStrLeft SalStrLeftX SalStrMid SalStrMidX
On SAM_Create Set nLength = SalStrRight ( '123RIGHT', 5, strTarget ) or On SAM_Create Set StrTarget = SalStrRightX ( '123RIGHT', 5 )
Example
SalStrScan
Syntax Description nOffset = SalStrScan ( strString1, strString2 ) Searches for and returns the offset of a specified substring. If there is more than one instance of the string being searched for, only the offset of the first instance is returned. strString1 strString2 String. The string to search. The first character in the string is at offset zero (0). String. The string to search for. Case is disregarded in the search. You can use pattern matching characters. The percent character (%) matches any set of characters. The underscore character (_) matches any single character. The use of a backslash(\) with SalStrScan differs when searching for a backslash, percent, or underscore character. Its usage also differs depending on whether or not the second parameter is a string literal.
Parameters
2-180
SalStrSetBufferLength
When searching for a backslash and strString2 is a string literal, you need four backslashes: SalStrScan ( 'This is a \\', '\\\\' ) When searching for a percent character or an underscore character and strString2 is a string literal, you need two backslashes: SalStrScan ( 'This is a %', '\\%' ) SalStrScan ( 'This is an _', '\\_' ) Even if strString2 is not a string literal, you need a single backslash to search for a percent character or an underscore. Return Value Example nOffset is a number that indicates the offset (0 origin) of strString2 in strString1. If SQLWindows does not find strString2 in strString1, SalStrScan returns a -1.
Set nOffset = SalStrScan ( '012AbC345', 'ABC' )
SalStrSetBufferLength
Syntax Description bOk = SalStrSetBufferLength ( strString, nLength ) Sets the buffer string length to the parameter value and allocates memory. If strString is expected to contain a string value, rather than binary bytes, be sure to set nLength equal to 1 plus the expected number of characters, to accomodate the null terminator. This is only needed if you want to pass a Receive String to an external function. Note that after calling this function, if you subsequently assign a value to the string using an ordinary operation like Set sExample = some text, the buffer length of the string will change to match the number of characters assigned, plus one for the null terminator. If you then call an external function that was expecting the original buffer length, you risk the chance of memory corruption through writing text beyond the buffer length. If a string already has characters assigned to it before you call SalStrSetBufferLength, and you then call the function using a length that is less than the present buffer length, you will truncate the string and lose the null terminator character. This may cause problems when you pass the string to an external function. Parameters strString nLength Return Value See Also Receive String. The string whose buffer length you want to set. Number. The length of strString.
bOk is TRUE if the function succeeds and FALSE if it fails. SalSetMaxDataLength
2-181
Chapter 2
SalStrGetBufferLength Example
Set bOk = SalStrSetBufferLength( recvString, 10 ) ! 9 chars
SalStrToDate
Syntax Description Parameters Return Value See Also Example dtDateTime = SalStrToDate ( strString ) Converts a string to a date/time value.This function uses the system date format to convert a date string. If you want to be format independent, use SalDateConstruct. strString String. The string to convert.
dtDateTime is the date/time value converted from strString. SalDateToStr

Set dtDateTime = SalStrToDate ( strDateTime )
SalStrTokenize
Syntax Description nNumTokens = SalStrTokenize ( strSource, strStartDel, strEndDel, strTokenArray ) Parses a string into substrings (tokens) based on specified start and end delimiters. SQLWindows uses delimiters to recognize the beginning and end of each substring. SQLWindows interprets the first non-start delimiter character as the beginning of a substring, and skips any start delimiters that precede this character. For example, if '!' is a start delimiter, the strings 'Hello' and '!!!Hello' produce the same token: 'Hello'. If the first non-start delimiter character is an end delimiter character, SQLWindows interprets it as a null substring. This is useful for comma-separated data where ',' is an end delimiter. SQLWindows recognizes that the records 'data1,data2,,data4' and ',data2,data3,data4' have four tokens each, one of which is null. Once SQLWindows finds the beginning of a substring, it interprets all characters that follow as elements of the substring until it finds an end delimiter. For example, if '!' is a start delimiter and '?' is an end delimiter, the string 'abc!def?ghi!' produces the tokens: 'abc!def' and 'ghi!'. Although the exclamation point is a start delimiter, SQLWindows correctly interprets them as elements of the substring. Parameters strSource strStartDel String. The string to parse. String. A string that contains the start delimiter characters. Pass an empty string ('') to specify the lack of a start delimiter. strEndDel String. A string that contains the end delimiter characters. Pass an empty string ('') to specify the lack of an end delimiter. 2-182
SalStrToNumber
strTokenArray Return Value Example
String Array. The handle (or name) of an array of substrings created from strSource.
nNumTokens is the number of substrings created. nNumTokens is zero (0) if no substrings are created, or if an error occurs.
Set dfNumTokens = SalStrTokenize( dfSource1, '', ',', astrToken1 )
SalStrToNumber
Syntax Description Parameters Return Value See Also Example nNumber = SalStrToNumber ( strString ) Converts a string to a number. strString String. The string to convert.
nNumber is the number resulting from the conversion. SalNumberToStr

Set nNumber = SalStrToNumber ( '100.22' )
SalStrTrim
Syntax nNewLength = SalStrTrim ( strSource, strTarget ) or strTarget = SalStrTrimX ( strSource ) Description Parameters Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces. strSource strTarget String. The original string. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nNewLength is the length of strTarget. strTarget is the new string. Example
Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )
SalStrTrimX
Syntax strTarget = SalStrTrimX ( strSource)
2-183
Chapter 2
Description Parameters
Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces. strSource strTarget String. The original string. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nNewLength is the length of strTarget. strTarget is the new string. Example
On SAM_Create Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )
SalStrUncompress
Syntax Description Parameters Return Value See Also Example bOk = SalStrUncompress ( strString ) Decompresses the specified string. Use this function to decompress a string that you compressed with SalStrCompress. strString Receive String. The string to decompress.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStrCompress

Set bOk = SalStrUncompress ( strString )
SalStrUpper
Syntax Description Parameters nLength = SalStrUpper ( strSource, str Target ) Converts a string to uppercase. strSource strTarget String. The string to convert. Receive String. The uppercase string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the uppercase string. See Also Example SalStrLower
Set nLength = SalStrUpper ( 'uppercase', strTarget )
2-184
SalStrUpperX
SalStrUpperX
Syntax Description Parameters strTarget = SalStrUpperX ( strSource ) Converts a string to uppercase. strSource String. The string to convert.
You can specify the same string for both strSource and strTarget. Return Value See Also Example This function returns the uppercase string in strTarget. SalStrLower
On SAM_Create Set strTarget = SalStrUpperX ( 'uppercase' )
SalTBarSetVisible
Syntax Description Parameters bOk = SalTBarSetVisible (hWind, bShw) Shows or hides the tool bar on a top-level or MDI window. hWnd bShow Return Value See Also Example Window Handle. The handle (or name) of a top-level or MDI window. Boolean. If TRUE, displays the tool bar; if FALSE, hides the tool bar.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStatusSetVisible

Set bOk = SalTBarSetVisible (hWind, bShw)
SalTblAnyRows
Syntax Description bAny = SalTblAnyRows ( hWndTbl, nFlagsOn, nFlagsOff ) Determines whether any rows in the specified table window match certain flags. If you set nFlagsOn to zero (0) and nFlagsOff to zero (0), SalTblAnyRows returns TRUE if the table window contains any rows at all, regardless of their flags. Parameters hWndTbl nFlagsOn Window Handle. The handle (or name) of a table window. Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator.
2-185
Chapter 2
nFlagsOff Return Value See Also Example
Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.
bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags and none of the nFlagsOff flags. SalTblFindNextRow SalTblFindPrevRow
Menu Settings Enabled When: SalTblAnyRows ( tblTable, ROW_Selected, 0 )
SalTblClearSelection
Syntax Description Parameters Return Value See Also Example bOk = SalTblClearSelection ( hWndTbl ) Deselects all rows of a table window. hWndTbl Window Handle. The handle (or name) of a table window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblSetRowFlags

Call SalTblClearSelection ( hWndForm )
SalTblColumnAverage
Syntax Description nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff ) Computes the average of all column values or only specified column values in a table window. Use SQLWindows row flag constants to specify the rows to use in the computation. For example, you can choose to average only the values of modified rows. Parameters hWndTbl nColumnID nFlagsOn nFlagsOff Return Value Window Handle. The handle (or name) of a table window. Number. The Column Identifier. Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator. Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator:
nAverage is the average of all column values or only specified column values in a table window. nAverage is equal to zero (0) if an error occurs.
2-186
SalTblColumnAverage
See Also Example
SalTblColumnSum
Set nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )
2-187
Chapter 2
SalTblColumnSum
Syntax Description nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff ) Computes the sum of all column values or only specified column values in a table window. Use SQLWindows row flag constants to specify the rows to use to compute the sum. For example, you can choose to sum only the values of modified rows. Parameters hWndTbl nColumnID nFlagsOn nFlagsOff Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The Column Identifier Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator. Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.
nSum is the sum of all column values or only specified column values in a table window. nSum is equal to zero (0) if an error occurs. SalTblColumnAverage
Set nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )
SalTblCopyRows
Syntax
bOk = SalTblCopyRows ( hWndTbl, nFlagsOn, nFlagsOff ) Copies the contents of the specified table window rows to the Clipboard in text format. In the Clipboard, columns are delimited by TAB characters and rows are delimited by end-of-line characters. Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to copy the entire table. The copy stops, without indicating a failure, after copying 64 Kbytes of text. Each individual column value is limited to 512 bytes of text.
Description
Parameters
hWndTbl nFlagsOn nFlagsOff
Window Handle. The handle (or name) of a table window. Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator. Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.
2-188
SalTblCreateColumn
Return Value
bOk is TRUE if any of the table window's rows are copied to the Clipboard and FALSE if no rows matched the indicated flags, or if none of the matched rows could be copied to the Clipboard. SalTblPasteRows
Call SalTblCopyRows ( tblTable, ROW_Selected, 0 )
See Also Example
SalTblCreateColumn
Syntax Description nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars, strTitle ) Creates a table window column of string data type at runtime. When you return to design mode, SQLWindows destroys the column. If the nColumnPos that you specify points to an existing column then that column, and all the columns to the right of it, are shifted to the right by one to make room for the newly created column. If nColumnPos does not point to an existing column then the newly created column will be placed at the end of the table. Parameters hWndTbl nColumnPos nDispWidth Window Handle. The handle (or name) of a table window. Number. The Column Position. Column positions begin with one, not zero. Number. The display width of the column in inches. If zero, the newly created column is hidden. If negative, the column is displayed partially obscured until it is manually resized by dragging with the mouse. Number. The maximum number of characters that the column can contain. If zero or negative, the number of characters allowed is unlimited. String. The column title.
nMaxChars
strTitle Return Value Example
nColId is the Column Identifier of the new column. nColld is negative one (-1) if an error occurs.
Set nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars, strTitle )
SalTblCreateColumnEx
2-189
Chapter 2
Syntax Description
nColId = SalTblCreateColumnEx ( hWndTbl, nColumnPos, nDispWidth, strTitle, nMaxChars, nDatatype ) Creates a table window column of speicified data type at runtime. When you return to design mode, SQLWindows destroys the column. If the nColumnPos that you specify points to the position of an existing column then that column, and all the columns to the right of it, are shifted to the right by one to make room for the newly created column. If nColumnPos does not point to an existing column then the newly created column will be placed at the end of the table.
Parameters
hWndTbl nColumnPos nDispWidth
Window Handle. The handle (or name) of a table window. Number. The Column Position Number. The display width of the column in inches. If zero, the newly created column is hidden. If negative, the column is displayed partially obscured until it is manually resized by dragging with the mouse. String. The column title. Number. The maximum number of characters that the column can contain. If zero or negative, the number of characters allowed is unlimited. Number. Must be equal to constant DT_String, DT_DateTime, or DT_Number. Any other value will cause the function to fail.
strTitle nMaxChars
nDatatype Return Value Example
nColId is the Column Identifier of the new column. nColld is negative one (-1) if an error occurs.
Set nColId = SalTblCreateColumnEx ( hWndTbl, nColumnPos, nDispWidth, strTitle, nMaxChars, DT_Number )
SalTblDefineCheckBoxColumn
Syntax Description Parameters bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue ) Define a column as a check box. hWnd HWndCol Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column.
2-190
SalTblDefineDropDownListColumn
nFlags
Number. nFlags is a combination of the following flags using the '|' operator: COL_CheckBox_IgnoreCase = 0x0001 String. sCheckedValue is the value that a cell will get when the check box is checked. String. The value when a check box is unchecked.
sCheckedValue sUncheckedValue Return Value Example

Set bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue )
SalTblDefineDropDownListColumn
Syntax Description Parameters bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol, nFlags, nLines ) Define a column as a drop down list. hWnd HWndCol nFlags Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Number. nFlags is a combination of the following flags using the '|' operator: COL_DropDownList_Sorted COL_DropDownList_VScroll COL_DropDownList_Auto COL_DropDownList_Editabel nLines Return Value Example = = = = 0x0001 0x0002 0x0004 0x0008
Number. nLines indicates the maximum number of lines to display in the list.

Set bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol, nFlags, nLines )
SalTblDefinePopupEditColumn
Syntax Description bOk = SalTblDefinePopupEditColumn( hWnd, hWndCol, nFlags, nLines ) Define a column as a popup edit window. nLines indicates the maximum number of lines to display in the control.
2-191
Chapter 2
Parameters
hWnd HWndCol nFlags nLines
Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Number. nFlags is always 0 (zero). Number. nLines indicates the maximum number of lines to display in the list.

Set bOk = SalTblDefinePopupEditColumn ( hWnd, hWndCol, nFlags, nLines )
SalTblDefineRowHeader
Syntax Description bOk = SalTblDefineRowHeader ( hWndTable, strTitle, nWidth, nFlags, hWndCol ) Defines the appearance and behavior of a table window's row header. The row header is a non-editable area on the left edge of a table window that displays information that stays displayed even when a user scrolls horizontally. A typical use of a row header is the display of row numbers. hWndTable strTitle nWidth nFlags Window Handle. The handle (or name) of a table window. String. The title of the row header column. Number. The width of the row header in pixels. Number. The row header attributes. You can combine these flags using the OR (|) operator. Possible values include: TBL_RowHdr_MarkEdits TBL_RowHdr_ShareColor TBL_RowHdr_Sizable TBL_RowHdr_Visible hWndCol Window Handle. The column that the row header mirrors. Whatever displays in hWndCol displays in the row header. If hWndCol equals hWndNULL, the row header is blank.
Parameters

Call SalTblDefineRowHeader ( tbl1, strTitle, nWidth,TBL_RowHdr_Visible | TBL_RowHdr_ShareColor, colRowHeader )
2-192
SalTblDefineSplitWindow
SalTblDefineSplitWindow
Syntax Description bOk = SalTblDefineSplitWindow ( hWndTable, nRowsLowerHalf, bDragAdjust ) Splits a table window horizontally. You can insert rows into the lower half of a split table window. This is convenient when the scroll range is dynamic because you can insert rows without knowing the number of rows in the table window. You can also use the lower half of a split table window to display summary data. Parameters hWndTable nRowsLowerHalf Window Handle. The handle (or name) of a table window to split. Number. The number of rows to make visible in the lower half of the split window. If you specify zero (0), the table window is not split. Boolean. Specify whether (TRUE) or not (FALSE) to let the user drag-adjust the visible rows in both halves of a split window.
bDragAdjust

Set bAnyFlag = SalTblDefineSplitWindow ( hWndTbl, 3, TBL_Split_Adjustable )
SalTblDeleteRow
Syntax Description Parameters bOk = SalTblDeleteRow ( hWndTbl, nRow, nFlag ) Deletes a row from a table window but not from the database. hWndTbl Window Handle. The handle (or name) of a table window.
nRoNumber. The number of the row to delete. nFlag Number. A constant used to coordinate a delete from the table window with a delete from a SQLBase result set. This parameter can be one of these values: TBL_Adjust TBL_NoAdjust Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
Call SalTblDeleteRow ( hWndForm, nCurrentRow, TBL_NoAdjust)
SalTblDeleteSelected
2-193
Chapter 2
Syntax Description
bOk = SalTblDeleteSelected ( hWndTbl, hSql ) Applies a SQL DELETE statement to all table window rows with the ROW_Selected flag set. You must prepare or retrieve the SQL DELETE statement before calling this function. As each row is deleted from the database, SQLWindows deletes it from the table window display. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the deletions are not lost in the case of a rollback.
Parameters
hWndTbl hSql
Window Handle. The handle (or name) of a table window. Sql Handle. The handle of a DELETE statement.
bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid. SalTblDoDeletes SalTblDoInserts SalTblDoUpdates SalTblPopulate
Call SalTblDeleteSelected ( tblExample, hSql )
Example
SalTblDestroyColumns
Syntax Description bOk = SalTblDestroyColumns ( hWndTbl ) Destroys all automatic columns created by SalTblCreateColumn or SalTblPopulate at runtime. This function only works on table windows that contain only automatic columns. Parameters Return Value See Also Example hWndTbl Window Handle. The handle (or name) of a table window.
bOk is TRUE if the function succeeds and FALSE if hWndTbl is invalid or the table window contains non-automatic columns (columns created at design time). SalTblCreateColumn SalTblPopulate
Set bOk = SalTblDestroyColumns ( hWndTbl )
SalTblDoDeletes
Syntax bOk = SalTblDoDeletes ( hWndTbl, hSql, nFlagsOn )
2-194
SalTblDoInserts
Description
Applies a SQL DELETE statement to all table window rows that have nFlagsOn flags set. You must prepare the SQL DELETE statement before calling this function. As each row is deleted from the database, SQLWindows deletes it from the table window display. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the deletions are not lost in the case of a rollback.
Parameters
hWndTbl hSql nFlagsOn
Window Handle. The handle (or name) of a table window. Sql Handle. The handle of a DELETE statement. Number. SQLWindows uses row flags to determine which rows to delete. You can specify either of these flags: ROW_MarkDeleted ROW_Selected
bOk is TRUE if any rows are deleted and FALSE otherwise. bOk is FALSE if hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoInserts SalTblDoUpdates
Call SalTblDoDeletes ( tblExample, hSql, ROW_MarkDeleted )
Example
SalTblDoInserts
Syntax Description bOk = SalTblDoInserts ( hWndTbl, hSql, bClearFlags ) Applies a SQL INSERT statement to all the rows in a table window that have the ROW_New flag set. You must prepare the SQL INSERT statement before calling this function. This function does not perform a COMMIT. You must perform a COMMIT to ensure that insertions are not lost in the case of a rollback. Parameters hWndTbl hSql bClearFlags Window Handle. The handle (or name) of a table window. Sql Handle. The handle of an INSERT statement. Boolean. Whether to reset the ROW_New flag. If TRUE, SQLWindows clears the ROW_New flag of each inserted row; if FALSE, SQLWindows does not clear the ROW_New flag of each inserted row. This is useful for error handling; if an error occurs, you can rollback the transaction and try again.
2-195
Chapter 2
bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoDeletes SalTblDoUpdates SalTblPopulate
Call SalTblDoInserts ( tblExample, hSql, FALSE )
Example
SalTblDoUpdates
Syntax Description bOk = SalTblDoUpdates ( hWndTbl, hSql, bClearFlags ) Applies a SQL UPDATE statement to all table window rows with the ROW_Edited flag set. You must prepare the SQL UPDATE statement before calling this function. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the updates are not lost in the case of a rollback. Parameters hWndTbl hSql bClearFlags Window Handle. The handle (or name) of a table window. Sql Handle. The handle of an UPDATE statement. Boolean. Whether to reset the ROW_Edited flag. If TRUE, SQLWindows clears the ROW_Edited flag of each changed row; if FALSE, SQLWindows does not clear the ROW_Edited flag of each changed row. This is useful for error handling; if an error occurs, you can roll back the transaction and try again. Return Value See Also bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoDeletes SalTblDoInserts SalTblPopulate
Call SalTblDoUpdates ( tblExample, hSql, FALSE )
Example
SalTblFetchRow
Syntax Description nResult = SalTblFetchRow ( hWndTbl, nRow ) Sends a SAM_FetchRow message to a table window if the row you specify is not currently in the table window cache. To process the SAM_FetchRow message, fetch the row from the database or another data source.
2-196
SalTblFindNextRow
The SAM_FetchRow message sets the context row to the row you specify before the table window receives the message. Parameters hWndTbl nRoNumber. Return Value See Also Example Window Handle. The handle (or name) of the table window that owns the row being retrieved. The row number.
nResult is one of these values: TBL_RowDeleted, TBL_RowFetched, TBL_NoMoreRows. SalTblQueryContext SalTblSetContext

Call SalTblFetchRow ( hWndtblTelephone, nMaxRange )
SalTblFindNextRow
Syntax Description bOk = SalTblFindNextRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff ) Scans forward in a table looking for a row whose flags match those specified. The search stops at the first row that has any of the nFlagsOn flags set, and none of the nFlagsOff flags set. Use this function in a loop to find all the table window rows that match specified conditions. You do not need to increment the row number; SQLWindows continues the search starting at the next row. To begin the search at the first row, set nRow to TBL_MinRow. Note: You cannot use TBL_MinRow without first assigning its value to a variable. This is because TBL_MinRow is a SQLWindows constant, and nRow is a receive parameter whose value the function can change. Parameters hWndTbl nRow Window Handle. The handle of the table window to search. Receive Number. The row at which to begin the search; the search starts on nRow + 1. If SQLWindows finds a row, it returns its row number in this parameter. Number. The flags the row should have. Number. The flags the row should not have. Specify zero (0) for no flags. You can specify any of the ROW_* flags for nFlagsOn and nFlagsOff. If you want to specify more than one, combine them using the OR (|) operator.
nFlagsOn nFlagsOff
2-197
Chapter 2
bOk is TRUE if SQLWindows finds a row and FALSE if there are no matches. SalTblFindPrevRow SalTblSetFlagsAnyRows
If SalTblFindNextRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )
SalTblFindPrevRow
Syntax Description bOk = SalTblFindPrevRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff ) Scans backward in a table looking for a row whose flags match those specified. The search stops at the first row that has any of the nFlagsOn flags set, and none of the nFlagsOff flags set. Use this function in a loop to find all the table window rows that match specified conditions. You do not need to decrement the row number; SQLWindows continues the search starting at the next row. To begin the search at the last row, set nRow to TBL_MaxRow. Note: You cannot use TBL_MaxRow without first assigning its value to a variable. This is because TBL_MaxRow is a SQLWindows constant, and nRow is a receive parameter whose value the function can change. Parameters hWndTbl Window Handle. The handle of the table window to search.
nRoReceive Number The row at which to begin the search; the search starts on nRow - 1. If SQLWindows finds a row, it returns its row number in this parameter. nFlagsOn nFlagsOff Number. The flags the row should have. Number. The flags the row should not have. Specify zero (0) for no flags. You can specify any of the ROW_* flags for nFlagsOn and nFlagsOff. If you want to specify more than one, combine them using the OR (|) operator. Return Value See Also Example bOk is TRUE if SQLWindows finds a row and FALSE if there are no matches. SalTblFindNextRow SalTblSetFlagsAnyRows
If SalTblFindPrevRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )
2-198
SalTblGetColumnText
SalTblGetColumnText
Syntax Description Parameters bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText ) Gets data from a column of a table window's context row. hWndTbl nColumnID strText Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The Column Identifier Receive string. The column data.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblSetColumnText

Set bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )
SalTblGetColumnTitle
Syntax Description Parameters nLength = SalTblGetColumnTitle ( hWndCol, strText, nMaxLen ) Gets the title of a table window column. hWndCol strText nMaxLen Return Value See Also Example Window Handle. The handle (or name) of a table window column. Receive String. The title. Number. The maximum length of the title.
nLength is the length of the column title returned in strText. SalTblSetColumnTitle

Call SalTblGetColumnTitle ( colRowHeader, strTitle, 100 )
SalTblGetColumnWindow
Syntax Description Parameters hWndCol = SalTblGetColumnWindow ( hWndTbl, nCol, nFlags ) Gets the handle of a table window column. hWndTbl nCol nFlags Window Handle. The handle (or name) of the table window that contains the column whose window handle you want. Number. A column position or a column identifier. Number. A constant that identifies whether nCol's value is a column identifier or a column position. Specify either:
2-199
Chapter 2
COL_GetID COL_GetPos Return Value Example hWndCol is the handle of a table window column. hWndCol is equal to hWndNULL if SQLWindows cannot find the table window column.
Set hWndCol = SalTblGetColumnWindow ( tbl1, nColID, COL_GetID )
SalTblInsertRow
Syntax Description Parameters nNewRow = SalTblInsertRow ( hWndTbl, nRow ) Inserts a new blank row into a table window. hWndTbl nRowNumber Window Handle. The handle (or name) of a table window. The row number of the new row. If this value is a valid row number within the table window range, then SQLWindows inserts a blank row at that location. If you specify TBL_MaxRow, SQLWindows appends the row to the end of the table window. If the table window is split and you specify TBL_MinSplitRow, SQLWindows appends the row to the top of the lower half of the table window. Return Value Example nNewRow is the number of the new row if the function succeeds. It is equal to TBL_Error if an error occurs.
Set nNewRow = SalTblInsertRow ( hWndTbl, TBL_MinSplitRow )
SalTblKillEdit
Syntax Description Parameters Return Value Example bOk = SalTblKillEdit ( hWndTbl ) Takes a row out of edit mode and selects the row. This causes the row to receive both SAM_Validate and SAM_KillFocus messages. hWndTbl Window Handle. The handle (or name) of the table window that contains the row just inserted or modified.

Set bOk = SalTblKillEdit ( hWndTbl )
2-200
SalTblKillFocus
SalTblKillFocus
Syntax Description bOk = SalTblKillFocus ( hWndTbl ) Turns off the table window's focus frame. This is useful when the user chooses a menu item from a table window menu; in this case, the focus cannot leave the table window. hWndTbl Window Handle. The handle (or name) of a table window.

Call SalTblKillFocus ( hWndForm )
SalTblObjectsFromPoint
Syntax Description bOk = SalTblObjectsFromPoint( hWndTable, nX, nY, nRow, hWndCol, nFlags ) Returns the part of the table window located at a given coordinate. These flags indicate the part where the X coordinate is located: TBL_XOverLockedColumns TBL_XOverLockedColumnsBorder TBL_XOverRowHeader TBL_XOverUnlockedColumns These flags indicate the part where the Y coordinate is located: TBL_YOverColumnHeader TBL_YOverNormalRows TBL_YOverSplitBar TBL_YOverSplitRows hWndTable Window Handle. The handle of the table window. nX, nY Number. Screen pixel coordinates relative to upper left corner of the table window. You get these values from SAM_ContextMenu. Receive Number. If nY is over a row then the row number is returned in nRow; otherwise nRow is TBL_Error. Receive Window Handle. If nX is over a column then its window handle is returned in hWndCol; otherwise hWndCol is hWndNULL. Receive Number. The part of the table. These flags indicate the part where the X coordinate is located.
Parameters
nRow hWndCol
nFlags Return Value

2-201
Chapter 2
No Example See Also SAM_ContextMenu
SalTblPasteRows
Syntax Description bOk = SalTblPasteRows ( hWndTbl ) Pastes the contents of the Clipboard to the specified table window. SQLWindows assumes the Clipboard data is in text format with cells delimited by tab characters and rows delimited by end-of-line characters. SQLWindows inserts the new rows into the table window without overwriting existing rows, and converts the data to the data types of the corresponding table window columns. Parameters Return Value See Also Example hWndTbl Window Handle. The handle (or name) of the table window receiving the data from the Clipboard.
bOk is TRUE if the Clipboard contains text that is successfully inserted into the table window, and FALSE otherwise, and if none of the columns are editable. SalTblCopyRows
Call SalTblPasteRows ( tblPhoneList )
SalTblPopulate
Syntax Description bOk = SalTblPopulate( hWndTbl, hSql, strSelect, nMethod ) Compiles, binds, and executes a SQL SELECT statement, then fetches the rows of the result set and populates a table window with them. SalTblPopulate also manages table window browsing. This function also works with table windows that do not have columns. SQLWindows creates columns at runtime based on the SQL statement's SELECT list, and uses the database column names as table window column titles. If you call SalTblPopulate again during the same runtime session, SQLWindows destroys the automatic table window columns created by the last SELECT statement and creates new columns. SalTblPopulate also works with SELECT statements that do not include INTO clauses. The table window must have the same number of columns as the SQL statement's SELECT list, and their data types must match the data types of the columns in the SELECT list. If you process and Return from the SAM_FetchRow message, SalTblPopulate does not fetch that row into the table window. If you process but do not Return from the SAM_FetchRow message, SalTblPopulate fetches the row into the table window. 2-202
SalTblPopulateFromXML
The SAM_FetchRow message is sent before the row is actually fetched from the result set so in processing this message, you cannot refer to the row being fetched. However, the SAM_FetchRowDone message is sent after the row is fetched, enabling you to refer to the row just fetched. Parameters hWndTbl hSql Window Handle. The handle (or name) of the table window to populate. Sql Handle. The handle of the SELECT statement. Do not use the Sql Handle passed to SalTblPopulate by other functions while the table window is in use. String. The SELECT statement. If the string is null (), SQLWindows uses the previously prepared SELECT statement associated with hSql. This avoids re-preparing the statement each time SalTblPopulate executes. Number. How to populate the table window. Specify one of these values: TBL_FillAll TBL_FillAllBackground TBL_FillNormal Return Value See Also bOk is TRUE if the function succeeds and FALSE if either hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoDeletes SalTblDoInserts SalTblDoUpdates
Call SalTblPopulate ( tblExample, hSql, strSql, TBL_FillAllBackground )
strSelect
nMethod
Example
Syntax Description bOk = SalTblPopulateFromXML (hWndTbl, sFile, sRootNode, bTableNode, bUseSchema) Clears a table window and then fills new rows with data from an XML document. Optionally uses an XML schema to set attributes in the table. After each row of data is populated, this function sends message SAM_XMLRowDone to the table window. New to version 3.1, this function requires that XML documents and schemas conform to Guptas naming conventions and structures. It is not possible to populate a table
2-203
Chapter 2
from just any well-formed generalized XML document and schema. XML documents and schemas generated from the SalTblWriteXMLAndSchema function do conform to the necessary conventions and structures. To learn more about these conventions and structures, use SalTblWriteXMLAndSchema against one of your table windows in a test application, and examine the output files. When bUseSchema is set to TRUE, if the table windows columns were created at design time, the length of each columns value will be the length assigned at design time. If the table window has no design-time columns and they are being automatically created during the call to this function, then the length of each columns value will be the length that is specified in the XML schema. This raises the possibility of data truncation, if the value of an element contains more characters than are specified by the design-time length or the XML schema length. Parameters hWndTbl sFile sRootNode Window Handle. The handle (or name) of the table window to populate. String. The name of the XML document file containing data to be used to populate the table. String. The name of the XML root node of the table, or the name of the XML node pertaining to a table row. See bTableNode. Boolean. If TRUE, it means that the name specified in sRootNode is the actual root node of the table, and this function should use the default name row as the name of the node for each table row. If FALSE, it means that the name in sRootNode is actually the name of a row node, and each node found with that name should be processed as a table window row. Boolean. Indicates whether to retrieve and use an XML schema for determining data types and attributes. If TRUE, the schema is retrieved. If FALSE, data is written into table window cells with the presumption that the table structure is already correct. Currently, bUseSchema cannot be specified TRUE when bTableNode is FALSE.It is possible to call SalTblSetFromXMLSchema against a table window just once, then call this function repeatedly while keeping bUseSchema as FALSE. This technique is somewhat faster than making multiple calls while bUseSchema is TRUE. If bUseSchema is TRUE, the schema file is searched for in the directory that the document is located in, then the current directory, then the Windows TEMP directory. If the schema file is not found, or if
bTableNode
bUseSchema
2-204
SalTblQueryCheckBoxColumn
the schema is invalid, this function tries to do the XML import without the schema.
Return Value
bOk is TRUE if the function succeeds and FALSE if fails. Some failure conditions, such as an invalid file name or invalid root node name, will cause error message dialogs to be displayed.
SalTblQueryCheckBoxColumn
Syntax Description Parameters bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue ) If the column is defined as a check box, this function retrieves information about the check box and returns TRUE. If it is not a check box, this function returns FALSE. hWnd HWndCol nFlags Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Receive Number. nFlags is a combination of the following flags using the '|' operator: COL_CheckBox_IgnoreCase = 0x0001 sCheckedValue sUncheckedValue Return Value Example Receive String. sCheckedValue is the value that a cell will get when the check box is checked. Receive String. The value when a check box is unchecked.

bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue )
SalTblQueryColumnCellType
Syntax Description Parameters bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType ) Indicates whether a column is a checkbox, drop down list, popup edit, or standard column. hWnd hWindCol Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. 2-205
Chapter 2
nType
Receive Number. Receives one of the following values. COL_CellType_Standard COL_CellType_CheckBox COL_CellType_PopupEdit = = = 1 2 3 4
COL_CellType_DropDownList = Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
Set bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType )
SalTblQueryColumnFlags
Syntax Description Parameters bSet = SalTblQueryColumnFlags ( hWndCol, nFlags ) Tests the state of a table window column's flags. hWndCol nFlags Return Value See Also Example Window Handle. The handle (or name) of a table window column. Number. The column flags to test. You can combine COL_* flags using the OR (|) operator.
bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise. SalTblSetColumnFlags
If SalTblQueryColumnFlags ( col1, COL_CenterJustify ) Set rbCenter = TRUE Else Set rbLeft = TRUE
SalTblQueryColumnID
Syntax Description Parameters Return Value Example nColID = SalTblQueryColumnID ( hWndCol ) Gets a table window column's identifier. hWndCol Window Handle. The handle of a table window column.
nColID is the Column Identifier. nColID is -1 if hWndCol is not a valid column.

Set nColID = SalTblQueryColumnID ( hWndCol ) Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )
SalTblQueryColumnPos
Syntax nPos = SalTblQueryColumnPos ( hWndCol )
2-206
SalTblQueryColumnWidth
Description Parameters Return Value See Also Example
Gets a table window column's relative position. hWndCol Window Handle. The handle of a table window column.
nPos is the Column Position. nPos is -1 if hWndCol is not a valid handle for a table window column. SalTblSetColumnPos
Set nPos = SalTblQueryColumnPos ( hWndCol )
SalTblQueryColumnWidth
Syntax Description Parameters bOk = SalTblQueryColumnWidth ( hWndTbl, nFormUnits ) Returns the width (in form units) of a table window column. hWndTbl nInches Return Value See Also Example Window Handle. The handle (or name) of a table window column. Receive Number. The width of the table window column.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblSetColumnWidth

Call SalTblQueryColumnWidth ( colRowHeader, nWidth )
SalTblQueryContext
Syntax Description nContext = SalTblQueryContext ( hWndTbl ) Returns a table window's current context row. Before sending a SAM_FetchRow message, SQLWindows automatically sets the context row so that assignments made while processing the message reference the correct row. Parameters Return Value See Also Example hWndTbl Window Handle. The handle (or name) of a table window.
nContext is the current context row number. SalTblFetchRow SalTblSetContext

Set nContext = SalTblQueryContext ( hWndTbl )
SalTblQueryDropDownListColumn
2-207
Chapter 2
Syntax Description Parameters
bOk = SalTblQueryDropDownListColumn( hWnd, hWndCol, nFlags, nLines ) If the column is defined as a drop down list, this function retrieves information about the list and returns TRUE. If it is not a drop down list, this function returns FALSE. hWnd HWndCol nFlags Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Receive Number. nFlags is a combination of the following flags using the '|' operator: COL_DropDownList_Sorted COL_DropDownList_VScroll COL_DropDownList_Auto COL_DropDownList_Editable nLines = = = = 0x0001 0x0002 0x0004 0x0008
Receive Number. nLines indicates the maximum number of lines to display in the list.

Set bOk = SalTblQueryDropDownListColumn ( hWnd, hWndCol, nFlags, nLines )
SalTblQueryFocus
Syntax Description Parameters bOk = SalTblQueryFocus ( hWndTbl, nRow, hWndCol ) Identifies the cell in a table window with the focus. hWndTbl Window Handle. The handle (or name) of a table window.
nRoReceive Number. The row number of the focus row. hWndCol Return Value See Also Example Receive Window Handle. The handle of the column with the focus.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblSetFocusCell SalTblSetFocusRow
On SAM_Click Call SalTblQueryFocus ( hWndtblTelephone, nRow,hWndColumn )
2-208
SalTblQueryLinesPerRow
SalTblQueryLinesPerRow
Syntax Description Parameters bOk = SalTblQueryLinesPerRow( hWndTbl, nLines ) Retrieves the height of a row in lines. HWndTbl nLines Return Value Example Window Handle. The handle (or name) of a table window. Receive Number. The number of lines.

Set bOk = SalTblQueryLinesPerRow( hWndTbl, nLines )
SalTblQueryLockedColumns
Syntax Description nLockedColumns = SalTblQueryLockedColumns ( hWndTbl ) Retrieves the number of locked table window columns. Locked table window columns do not scroll horizontally; they are fixed to the left side of the table window. All other columns appear to scroll under the locked columns. Parameters Return Value See Also Example hWndTbl Window Handle. The handle (or name) of a table window.
nLockedColumns is the number of locked columns. If there are no locked columns, nLockedColumns is zero (0). SalTblSetLockedColumns
Set nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )
SalTblQueryPopupEditColumn
Syntax Description Parameters bOk = SalTblQueryPopupEditColumn( hWnd, hWndCol, nFlags, Lines ) If the column is defined as a popup edit, this function retrieves information about the popup edit and returns TRUE. If it is not a popup edit, this function returns FALSE. hWnd HWndCol nFlags Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Receive Number. nFlags is a combination of the following flags using the '|' operator: COL_DropDownList_Sorted COL_DropDownList_VScroll = = 0x0001 0x0002 2-209
Chapter 2
COL_DropDownList_Auto COL_DropDownList_Editable nLines Return Value Example
= =
0x0004 0x0008
Receive Number. nLines indicates the maximum number of lines to display in the list.

Set bOk = SalTblQueryPopupEditColumn ( hWnd, hWndCol, nFlags, Lines )
SalTblQueryRowFlags
Syntax Description Parameters bOk = SalTblQueryRowFlags ( hWndTbl, nRow, nFlags ) Queries a row's flags. hWndTbl Window Handle. The handle (or name) of a table window.
nRoNumber. The row number of the row whose flags you want to test. nFlags Return Value See Also Example Number. The row flags to test for. You can combine ROW_* flags using the OR (|) operator.
bOk is TRUE if any of the specified flags are set and FALSE if none of the specified flags are set. SalTblSetFlagsAnyRows SalTblSetRowFlags
On SAM_SetFocus If SalTblQueryRowFlags ( hWndForm, lParam, ROW_New )
SalTblQueryRowHeader
Syntax Description bOk = SalTblQueryRowHeader ( hWndTbl, strTitle, nMaxTitle, nWidth, nFlags, hWndCol ) Gets a table window's row header definition. The row header is a non-editable area on the left edge of a table window that displays information that you do not want to scroll off the screen as the user scrolls horizontally. A typical use is the display of row numbers. hWndTbl strTitle nMaxTitle nWidth 2-210
Parameters
Window Handle. The handle (or name) of a table window. Receive String. The title of the row header. Number. The maximum length of the title. Receive Number. The width of the row header in pixels.
SalTblQueryScroll
nFlags
Receive Number. Row header attributes. Specify one of these: TBL_RowHdr_MarkEdits TBL_RowHdr_ShareColor TBL_RowHdr_Sizable TBL_RowHdr_Visible
hWndCol
Receive Window Handle. The column that the row header mirrors. Whatever displays in hWndCol displays in the row header. If hWndCol is equal to hWndNULL, the row header is blank.

Call SalTblQueryRowHeader ( tbl1, strTitle, 100, nWidth, nFlags, colRowHeader )
SalTblQueryScroll
Syntax Description bOk = SalTblQueryScroll ( hWndTbl, nPosition, nMinRange, nMaxRange ) Returns a table window's current scroll position and range. The scroll position is the row number of the row that is currently at the top of the window. You set the table window range with SalTblSetRange and SQLWindows changes it when you insert or delete rows from the table window. Parameters hWndTbl nPosition nMinRange nMaxRange Return Value Example Window Handle. The handle (or name) of a table window. Receive Number. The scroll position. Receive Number. The minimum table range. Receive Number. The maximum table range.

Call SalTblQueryScroll ( hWndTbl, nPosRow, nMinRow, nMaxRow )
SalTblQuerySplitWindow
Syntax Description Parameters bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax bDragAdjust ) Specifies how a table window is split horizontally. hWndTbl Window Handle. The handle (or name) of a split table window.
2-211
Chapter 2
nRowLowerHalf bDragAdjust
Receive Number. The number of visible rows in the lower half of the split window. If zero (0), the table is not split. Receive Number Boolean. Specify whether (TRUE) or not (FALSE) the user can drag-adjust the visible rows in both halves of a split window.

Set bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax,bDragAdjust )
SalTblQueryTableFlags
Syntax Description Parameters bSet = SalTblQueryTableFlags ( hWndTbl, nFlags ) Tests the state of a table window's flags. hWndTbl nFlags Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The table flags to test. You can combine TBL_* flags using the OR (|) operator.
bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise. SalTblSetTableFlags
If SalTblQueryTableFlags ( tbl1, TBL_Flag_MoveableCols ) Set rbColsMovable = TRUE
SalTblQueryVisibleRange
Syntax Description Parameters bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax ) Returns the current range of visible rows in a table window. hWndTbl nRangeMin nRangeMax Return Value Example Window Handle. The handle (or name) of a table window. Receive Number. The first visible row. Receive Number. The last visible row.

Set bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )
SalTblReset
Syntax 2-212 bOk = SalTblReset ( hWndTbl )
SalTblScroll
Description Parameters Return Value See Also Example
Clears a table window by discarding all rows from the table window cache and setting the table range to 0, -1. hWndTbl Window Handle. The handle (or name) of a table window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblSetRange

If nRowCount > 0 Call SalTblReset ( hWndForm )
SalTblScroll
Syntax Description Parameters bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll ) Scrolls a table window to the specified row and column. hWndTbl nRoWNumber hWndColumn nTBLScroll Window Handle. The handle (or name) of a table window. The number of the row to scroll to. If you specify -1, only the column scrolls into view. Window Handle. The table window column to scroll into view. If you specify hWndNULL, only the row scrolls into view. Number. The position of the scroll row. Specify one of these: TBL_AutoScroll TBL_ScrollBottom TBL_ScrollTop Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if SQLWindows cannot scroll the row. This function fails if either nRow or nTBLScroll are invalid values. SalTblQueryScroll SalTblQueryVisibleRange
Set bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )
SalTblSetCellTextColor
Syntax Description Parameters bOk = SalTblSetCellTextColor ( hWndCol, nColor, bDiscardable ) Changes a table window cell's text color. hWndCol Window Handle. The handle (or name) of a table window column.
2-213
Chapter 2
nColor bDiscardable
Number. The cell text color. Specify one of the predefined windows colors. Boolean. Determines whether SQLWindows discards the cell text color if and when the user re-fetches the row. If TRUE, SQLWindows discards the cell text color when the user re-fetches the row. If FALSE, SQLWindows keeps the cell text color. This requires additional resources to keep the row in memory.

On SAM_FetchRow Call SalTblSetCellTextColor ( Col1, COLOR_Red, TRUE ) Return TBL_RowFetched
2-214
SalTblSetColumnFlags
SalTblSetColumnFlags
Syntax Description Parameters bOk = SalTblSetColumnFlags ( hWndCol, nFlags, bSet ) Sets or clears a table window column's flags. hWndCol nFlags bSet Return Value Window Handle. The handle (or name) of a table window column. Number. The column flags to change. You can combine COL_* flags using the OR (|) operator. Boolean. If TRUE, SQLWindows sets the flags; if FALSE, SQLWindows clears the flags.
bOk is TRUE if the function succeeds and FALSE if it fails. To define a column a column as multiline use the flag: COL_MultilineCell = 0x00800000
See Also Example
SalTblQueryColumnFlags
Call SalTblSetColumnFlags ( col1, COL_CenterJustify, TRUE )
SalTblSetColumnPos
Syntax Description Parameters bOk = SalTblSetColumnPos ( hWndCol, nPos ) Moves a table window column to a new position. hWndCol nPos Window Handle. The handle (or name) of a table window column to move. Number. The new position of the table window column. 1 is the first (left-most) position, 2 is the second position, and so on.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryColumnPos

Call SalTblSetColumnPos ( col3, nPos + 1 )
SalTblSetColumnText
Syntax Description Parameters bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText ) Assigns data to a column of a table window's context row. hWndTbl Window Handle. The handle (or name) of a table window.
2-215
Chapter 2
nColumnID strText Return Value See Also Example
Number. The Column Identifiers String. The data to assign.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblGetColumnText

Set bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )
SalTblSetColumnTitle
Syntax Description Parameters bOk = SalTblSetColumnTitle ( hWndCol, strTitle ) Sets the title of a table window column. hWndCol strTitle Return Value See Also Example Window Handle. The handle (or name) of a table window column. String. The title of the table window column.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblGetColumnTitle

Set bOk = SalTblSetColumnTitle ( hWndCol, strTitle )
SalTblSetColumnWidth
Syntax Description Parameters bOk = SalTblSetColumnWidth ( hWndTbl, nFormUnits ) Sets a table window column's display width. hWndTbl nFormUnits Return Value See Also Example Window Handle. The handle (or name) of a table window column. Number. The table window column's display width in form units.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryColumnWidth

Set nColID = SalTblQueryColumnID ( hWndCol ) Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )
2-216
SalTblSetContext
SalTblSetContext
Syntax Description bOk = SalTblSetContext ( hWndTbl, nRow ) Sets a table window's context row. Setting the context row does not send a SAM_FetchRow message. If the row is not currently in memory, SQLWindows creates a new row in memory and sets its cell values to null. Parameters hWndTbl Window Handle. The handle (or name) of a table window whose context row you want to set.
nRoNumber. The row number of the new context row. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryContext
Set bOk = SalTblSetContext ( hWndTbl, nRow
SalTblSetFlagsAnyRows
Syntax Description Parameters bAny = SalTblSetFlagsAnyRows ( hWndTbl, nFlags, bSet, nFlagsOn, nFlagsOff ) Sets or clears row flags. hWndTbl nFlags bSet nFlagsOn Window Handle. The handle (or name) of a table window whose row flags you want to set or clear. Number. The flags to change. You can combine flag values using the OR (|) operator. Boolean. Whether to set (TRUE) or clear (FALSE) the specified flags. Number. The flags that the rows should have. You can combine flag values using the OR (|) operator. Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to specify all rows. nFlagsOff Number. The flags that the rows should not have. You can combine flag values using the OR (|) operator. Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to specify all rows.
2-217
Chapter 2
bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags and none of the nFlagsOff flags. SalTblFindNextRow SalTblFindPrevRow
Call SalTblSetFlagsAnyRows ( tblExample, ROW_MarkDeleted, TRUE, ROW_Selected, 0 )
SalTblSetFocusCell
Syntax Description bOk = SalTblSetFocusCell ( hWndTbl, nRow, hWndCol, nEditMin, nEditMax ) Sets the focus to the specified table window cell (row and column). SQLWindows puts the table window into edit mode and lets the user select a portion of the data in the cell. hWndTbl nRowNumbe hWndCol nEditMin Window Handle. The handle (or name) of a table window. The row that receives the edit focus. Window Handle. The handle (or name) of the column that receives the edit focus. Number. The position of the left-most character. When used with nEditMax, this parameter lets the user select a portion of the cell text. nEditMin must be less than or equal to nEditMax. To select all the characters in a cell, specify zero (0) for this parameter and -1 for nEditMax. nEditMax Number. The position of the right-most character. When used with nEditMin, this parameter lets the user select a portion of the cell text. nEditMax must be greater than or equal to nEditMin. To select all the characters in a cell, specify -1 for this parameter and zero (0) for nEditMin. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryFocus
Call SalTblSetFocusCell ( hWndForm, lParam, hWndItem, 0, 1 )
Parameters
2-218
SalTblSetFocusRow
SalTblSetFocusRow
Syntax Description Parameters bOk = SalTblSetFocusRow ( hWndTbl, nRow ) Sets a table window's focus frame row. hWndTbl Window Handle. The handle (or name) of a table window.
nRoNumber. The row number of the row to which to apply the focus frame. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryFocus
Set bOk = SalTblSetFocusRow ( hWndTbl, nRow
SalTblSetFromXMLSchema
Syntax Description bOk = SalTblSetFromXMLSchema ( hWndTbl, sSchemaFile, sSchemaName ) For an automatic-column table window, this function resets the columns in the table to comply with the schema. For a static-column table window, this function returns a Boolean value indicating whether the attributes in the schema are a match for the attributes of the table window columns. hWndTbl sSchemaFile sSchemaName Return Value Window Handle. The handle (or name) of the table window to validate. String. The name of the XML schema file containing attributes to be used for validation. String. The name of the schema within the schema file.
Parameters
See Also
SalTblSetLinesPerRow
Syntax Description bOk = SalTblSetLinesPerRow( hWndTbl, nLines ) Sets the height of a row in lines. Multirow lines are useful when a column is defined as multiline. The text in each cell will wrap. To define a column a column as multiline use the function SalTblSetColumnFlags with the flag: COL_MultilineCell = 0x00800000 Parameters HWndTbl Window Handle. The handle (or name) of a table window.
2-219
Chapter 2
nLines Return Value Example
Number. The number of lines.

Set bOk = SalTblSetLinesPerRow( hWndTbl, nLines )
SalTblSetLockedColumns
Syntax Description bOk = SalTblSetLockedColumns ( hWndTbl, nLockedColumns ) Sets the number of locked table window columns. Table window columns that you lock do not scroll horizontally; they are fixed to the left side of the table window. All other columns appear to scroll under the locked columns. This function locks zero (0) or more of the left-most visible columns of a table window. hWndTbl nLockedColumns Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The number of table window columns to lock.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryLockedColumns

Call SalTblSetLockedColumns ( tbl1, 2 )
SalTblSetRange
Syntax Description Parameters bOk = SalTblSetRange ( hWndTbl, nMin, nMax ) Defines the minimum and maximum rows (range) of a table. hWndTbl nMin nMax The handle (or name) of a table window. Number. The lower boundary of the table window. Number. The upper boundary of the table window. Setting nMin and nMax: nMin must be less than or equal to nMax. You can specify an empty table with the range 0, -1. You can specify a dynamic range with the values zero (0), TBL_MaxRow. SQLWindows determines the higher boundary when the application returns TBL_NoMoreRows from a SAM_FetchRow message, or from the return of the SAM_FetchDone message. Return Value bOk is TRUE if the function succeeds and FALSE if it fails.
2-220
SalTblSetRow
See Also Example
SalTblReset
Call SalTblSetRange ( hWndForm, 0, nRowCount - 1 )
SalTblSetRow
Syntax Description Parameters nRowNum = SalTblSetRow ( hWnd, nRowPos ) Sets the focus to the first, last, next, or previous row in a table window. tName nRowPos Window Handle. The handle (or name) of the window whose current focus row you want to change. Number. The position of the focus row. Specify one of these values: TBL_SetFirstRow TBL_SetLastRow TBL_SetNextRow TBL_SetPrevRow Return Value Example nRowNum is the row number of the new focus row.
Set = nRowNum = SalTblSetRow ( hWnd, nRowPos )
SalTblSetRowFlags
Syntax Description Parameters bOk = SalTblSetRowFlags ( hWndTbl, nRow, nFlags, bSet ) Sets or clears a table window row's flags. hWndTbl nRoNumber. nFlags bSet Return Value See Also Example Window Handle. The handle (or name) of a table window. The row number of the row whose flags you want to set or clear. Number. The row flags. You can combine any of the ROW_* flags using the OR (|) operator. Boolean. Whether to set (TRUE) or clear (FALSE) the specified flags.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryRowFlags SalTblSetFlagsAnyRows
Call SalTblSetRowFlags ( hWndTbl, nRow, ROW_Selected, TRUE )
2-221
Chapter 2
SalTblSetTableFlags
Syntax Description Parameters bOk = SalTblSetTableFlags ( hWndTbl, nFlags, bSet ) Sets or clears a table window's flags. hWndTbl nFlags bSet Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The table flags. You can combine any of the TBL_* flags using the OR (|) operator. Boolean. Whether to set (TRUE) or clear (FALSE) the specified flags.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblQueryTableFlags

Call SalTblSetTableFlags ( tbl1, TBL_Flag_MoveableCols, FALSE)
2-222
SalTblSortRows
SalTblSortRows
Syntax Description bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder ) Sorts the rows of a non-discardable table window based on the values in one of the table window's columns. You must create this column at design time; it cannot be an automatic column such as a column created by SalTblPopulate. or SalTblCreateColumn. Important: The table window cache must not be discardable and the setting of maximum
rows in memory must be large enough to hold the rows that you are sorting.
Important: The column used for sorting cannot be datatype Long String. Parameters hWndTbl nColumnID nOrder Window Handle. The handle (or name) of a table window. Number. The Column Identifier of the column by which to sort. Number. The direction of the sort. Specify either: TBL_SortDecreasing TBL_SortIncreasing Return Value Example bRet is TRUE if the function succeeds and FALSE if nColumnID is not a valid identifier.
Set bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )
SalTblWriteXMLandSchema
Syntax Description bOk = SalTblWriteXMLandSchema ( hWndTbl, sPath, bFrontEnd, nWriteTypes ) Writes the contents and properties of a table window to an XML file and/or a schema file. Note that if the table window contains a column with datatype Date/Time, and a cell in that column is empty, then no content will be written for that particular XML document node. Validating XML parsers will flag this situation as an invalid value. The element names used in the XML file are based on the titles of the table window columns. Spaces are replaced with underscore characters. Note that if a table window contains more than one column with the same column title, this function will fail. Parameters hWndTblWindow Handle. The handle (or name) of a table window.
2-223
Chapter 2
sPath
String. The path and name of the output file. Note that the schema file will have the same name, plus the suffix _SCHEMA. Boolean. If TRUE, the schema will be based on the table window properties. If FALSE, the schema will be based on the column information returned by a database cursor (as in a call to SalTblPopulate.) In the latter case, all datatypes will be strings. Number. One of the XML constants, determining whether to write XML, schema, or both.
bFrontEnd
nWriteTypes Return Value Example See Also

SalTblWriteXMLandSchema (tblOrders, c:\\My Documents\ORDERS, TRUE, XML_DocAndSchema)
SalTblWriteXMLandSchemaEx
SalTblWriteXMLandSchemaEx
Syntax Description bOk = SalTblWriteXMLandSchemaEx ( hWndTbl, sPath, bFrontEnd, nWriteTypes, nFlagsOn, nFlagsOff ) Writes the contents and properties of a table window to an XML file and/or a schema file. Only rows that match the selection criteria in nFlagsOn and nFlagsOff will be written. Note that if the table window contains a column with datatype Date/Time, and a cell in that column is empty, then no content will be written for that particular XML document node. Validating XML parsers will flag this situation as an invalid value. The element names used in the XML file are based on the titles of the table window columns. Spaces are replaced with underscore characters. Note that if a table window contains more than one column with the same column title, this function will fail. Parameters hWndTbl sPath Window Handle. The handle (or name) of a table window. String. The path and name of the output file. Note that the schema file will have the same name, plus the suffix _SCHEMA. Boolean. If TRUE, the schema will be based on the table window properties. If FALSE, the schema will be based on the column information returned by a database cursor (as in a call to SalTblPopulate.)
bFrontEnd
2-224
SalTimerKill
nWriteTypes nFlagsOn
Number. One of the XML constants, determining whether to write XML, schema, or both. Number. A combination of one or more of the row flags. Rows must have these flags on in order to be part of the output to XML. Number. A combinaion of one or more of the row flags. Rows must have these flags off in order to be part of the output to XML. Specify 0 to use no flags in this parameter.
nFlagsOff
bOk is TRUE if the function succeeds and FALSE if it fails. In this example, only rows that have been edited, but not marked for deletion, are output to files.
SalTblWriteXMLandSchema (tblOrders, c:\\My Documents\ORDERS, TRUE, XML_DocAndSchema, ROW_Edited, ROW_MarkDeleted)
SalTimerKill
Syntax Description bOk = SalTimerKill ( hWnd, nIDEvent ) Destroys an object's system timer. SQLWindows removes any pending SAM_Timer messages from the message queue of hWnd. Set a system timer with the SalTimerSet function. Parameters hWnd nIDEvent Return Value See Also Example Window Handle. The handle (or name) of an object. Number. The timer ID to kill.
bOk is TRUE if SQLWindows successfully kills the event and FALSE if SQLWindows cannot find the specified timer. SalTimerSet
On SAM_Destroy Call SalTimerKill ( dfClock, 1 )
SalTimerSet
Syntax Description bOk = SalTimerSet ( hWnd, nIDEvent, nElapseMilliSec ) Creates a system timer for a given object. When a timer event occurs, SQLWindows sends SAM_Timer messages to the object in specified intervals.
2-225
Chapter 2
Timers are a limited global resource. Your application must check the value returned by SalTimerSet to verify that the timer was created. Parameters hWnd nIDEvent nElapseMilliSec Return Value See Also Example Window Handle. The handle (or name) of an object associated with a system timer. Number. The timer ID number. Number. The elapsed time between each SAM_Timer message, in milliseconds.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTimerKill

On SAM_Create Set bOk = SalTimerSet ( hWndItem, 1, 1000 )
SalTrace
Syntax Description Parameters bOk = SalTrace ( nSeverity, strTextToWrite ) Writes a string of text to the trace output target that was specified in an earlier call to SalStartTrace. nSeverity Number. One of the following three constants: EVENT_Error, EVENT_Warning, or EVENT_Information. When used with the Windows event log, these numeric values will be integrated into that logs severity system. When output is going to some other target, such as a file, these numeric values are translated into text strings. String. The text of the trace message.
strTextToWrite Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalStartTrace SalEndTrace
Example
bOk = SalTrace (EVENT_Warning, 'User entered a null password')
SalTrackPopupMenu
Syntax Description bOk = SalTrackPopupMenu ( hWndProcMsgs, strMenuName, nFlags, nX, nY ) Creates pop-up menus at runtime.
2-226
SalUpdateWindow
Parameters
hWndProcMsgs
Window Handle. The handle (or name) of the top-level window that processes messages generated by the pop-up menu. String. The name of a pop-up menu accessible to hWndProcMsgs. For example, a menu defined by hWndProcMsgs or its MDI window parent, or a global menu. Number. Specifies how the pop-up menu displays. You can combine flag values using the OR (|) operator. Number. The position of the pop-up menu on the X axis. The value of this parameter is ignored if you set the TPM_CursorX flag in nFlags. Number. The position of the pop-up menu on the Y axis. The value of this parameter is ignored if you set the TPM_CursorY flag in nFlags.
strMenuName
nFlags nX
nY
The nX and nY Parameters together represent a point (the top left, top middle, or top right) of the pop-up menu, depending on the nFlags value. Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
On SAM_Click Call SalTrackPopupMenu ( hWndForm, 'menuEdit', TPM_CursorX | TPM_CursorY | TPM_CenterAlign, 0, 0 )
SalUpdateWindow
Syntax Description bOk = SalUpdateWindow ( hWndUpdate ) Forces SQLWindows to update a window. Painting is a low priority in Microsoft Windows. Windows sends WM_Paint messages to the end of an object's message queue and processes them only after it processes all other messages in the queue. If, during the development phase of your application, you find that painting is being delayed, you can force SQLWindows to update a window. For example, if you call SalListClear to delete all the entries in a list box and follow this call with a loop, SQLWindows delays repainting the list box until it completes processing the loop. To force SQLWindows to repaint the list box before processing the loop, call SalUpdateWindow. Parameters hWndUpdate Window Handle. The handle (or name) of the window to update.
2-227
Chapter 2
bOk is TRUE if the function succeeds and FALSE if hWndUpdate is not a valid window handle. SalInvalidateWindow
Message Actions On SAM_FieldEdit Call SalUpdateWindow ( ml1 )
SalUseEventLog
Syntax Description bOk = SalUseEventLog( bUseEventLog, bContinueProcessing ) This function is used to start redirecting SQLWindows event processing from pop-up message boxes to the Windows event log, or to end such redirection. Some operating systems do not support true Windows event logging. See Event Logging in Chapter 10 of Developing with SQLWindows for more information. When this function is called with bUseEventLog=TRUE, SQLWindows checks for a registry key and creates it if it does not already exist. This key is: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ EventLog\Application\SWMSG41 Note: If the user running the application does not have Administrator privileges, the creation
of the registry key will fail.
Parameters
bUseEventLog
TRUE if event log is to be used, FALSE if pop-up message boxes are to be used.
bContinueProcessing Indicates whether to attempt to automatically resume the application when a recoverable SQL event occurs. Such an event would be one that would contain a Yes or Continue pushbutton if displayed in a pop-up message dialog box. To get this behavior, set this parameter to TRUE. To cause execution to stop for recoverable SQL events, set this parameter to FALSE. If a non-SQL event occurs, execution always stops, regardless of the setting of bContinueProcessing. Return Value Example bOk is TRUE if the function succeeds and FALSE if function fails.
Set bOk = SalUseEventLog( TRUE, TRUE )
SalUseRegistry
Syntax 2-228 bOk = SalUseRegistry( bUseRegistry, sCompanyName )
SalValidateSet
Description
This function is used to re-direct all SalProfile* functions to use the Registry. All values for the SalProfile* functions are saved as strings. The INI file name used as the last parameter of the SalProfile* functions will be used as the application name. The resulting path will be:
\\HKEY_CURRENT_USER\Software\<company name>\<application name>\<section>\<setting>\
Parameters
bUseRegistry sCompanyName
- TRUE if registry is to be used, FALSE if INI files are to be used. - Name of company to be used under the registry.
bOk is TRUE if the function succeeds and FALSE if function fails.

Set bOk = SalUseRegistry( bUseRegistry, sCompanyName )
SalValidateSet
Syntax Description bOk = SalValidateSet ( hWndCC, bValState, lParam ) You call SalValidateSet when the user tries to move the focus to the custom control. In SQLWindows, changes in focus trigger validation. SalValidateSet tells SQLWindows that the focus is changing to a custom control so that SQLWindows can perform validation as needed. Important: You must set the Tab stop item in the Attribute Inspector to Tab or Group so that
the custom control can receive the focus.
Parameters
hWndCC bValState lParam
Handle of the custom control. Validates this custom control when it loses the focus. SQLWindows passes the value you specify in the lParam of SAM_Validate.
Return Value
bOk is TRUE SQLWindows sends SAM_Validate when the custom control loses the focus and FALSE if SQLWindows does not send SAM_Validate when the custom control loses the focus. Specify TRUE in bValState for controls that behave like editable objects. When bValState is TRUE, SQLWindows sends SAM_Validate to the object losing the focus: If validation succeeds, SalValidateSet returns TRUE and SQLWindows moves the focus to the custom control. Later, when the user moves the focus
2-229
Chapter 2
off the custom control, SQLWindows sends it SAM_Validate if its field edit flag is set to TRUE. If validation fails, SalValidateSet returns FALSE and SQLWindows sets the focus to the invalid object.
For an editable custom control, you want SQLWindows to send SAM_Validate if the user changes the value. Call SalSetFieldEdit( hWndItem, TRUE ) when the user changes the value so that SQLWindows sends SAM_Validate if the user tries to change the focus to another object. Example
Call SalValidateSet( hWndItem, TRUE, 0 )
SalWaitCursor
Syntax Description bOk = SalWaitCursor ( bOn ) Displays or removes the hourglass cursor. The hourglass is a visual indicator that the application is busy. You must always call this function twice; once to turn the cursor into an hourglass and again to restore it to its original form. Parameters Return Value Example bOn Boolean. Whether to turn the hourglass on (TRUE) or off (FALSE).

Call SalWaitCursor ( TRUE )
SalWindowClassName
Syntax Description Parameters Return Value Example sClassName = SalWindowClassName( hWnd ) Return the name of a window's class as a string. hWnd Window Handle. The window handle of an instance of a Window Class object.
Returns an empty string if the window is not a class object.

Set sClassName = SalWindowClassName( hWnd )
SalWindowGetDockSetting
Syntax Description bOk = SalWindowGetDockSetting ( hWndDlg, nOrientation ) Gets information about the docking orientations permitted for a top-level window. These orientations are specified at design time, and are not changeable at run time.
2-230
SalWindowGetProperty
Parameters
hWnd nOrientation
Window Handle. The handle (or name) of the top-level window. Receive Number. One or more of the docking orientation flags as described below. If more than one docking orientation is permitted, the values of the permitted flags are combined with the OR operator into a single number. DOCK_Top: the child window may dock to the top edge of its parent window. DOCK_Bottom: the child window may dock to the bottom edge of its parent window. DOCK_Left: the child window may dock to the left edge of its parent window. DOCK_Right: the child window may dock to the right edge of its parent window. DOCK_Any: the child window may dock to any edge of its parent window. DOCK_None: the child window is not permitted to dock to the parent window.
bRet is TRUE if the docking information is found and FALSE if an error occurs. SalDlgGetDockStatus, SalDlgSetDockStatus
Call SalWindowGetDockSetting ( hWndForm, nDock )
SalWindowGetProperty
Syntax Description Parameters bOk = SalWindowGetProperty( hWndQO, strPropName, strPropValue ) Gets the value of a named property for an instance of a QuickObject. The property must have been created at designtime with the QuickObject Editor. hWndQO strPropName strPropValue Return Value Example Window Handle. The window handle of an instance of a QuickObject. String. The name of the property. Receive String. The value of the property.
bOk is TRUE if the function succeeds and FALSE if it fails. This example gets a window name property:
Set bOk = SalWindowGetProperty( hWndItem, 'WindowName', strWindowName )
2-231
Chapter 2
SalWindowHandleToNumber
Syntax Description nWnd = SalWindowHandleToNumber ( hWnd ) Converts a window handle to a number. For example, you can pass a window handle as a SalSendMsg wParam parameter as follows: nWnd = SalWindowHandleToNumber ( hWndParm ) Call SalSendMsg ( hWndDest, nMsg, nWnd, 0 ) Parameters Return Value See Also Example hWnd Window Handle. The handle to convert.
nWnd is the number converted from hWnd. SalNumberToWindowHandle

Set ntblCustomer = SalWindowHandleToNumber ( hWndtblCustomer )
SalWindowIsDerivedFromClass
Syntax Description bOk = SalWindowIsDerivedFromClass( hWnd, ClassName ) Tells you if a window is an instance of the class that you specify or an instance of a class that is derived from the class that you specify. Call this function to determine if you can make a late-bound call to a function defined in the named class using the window handle that you specify. If you make a latebound function call with a handle that is not for a window derived from the named class and the function returns a value, you get an error at runtime and the application ends. Parameters hWnd ClassName Return Value Example Window Handle. The handle (or name) of the window. Symbol. The ClassName parameter is a symbol, not a string. Type the class name without single quotes.
bOk is TRUE if the window is an instance of the named class or an instance of a class that is derived from the named class.
Set bOk = SalWindowIsDerivedFromClass( hWnd, ClassName )
SalWinHelp
Syntax bOk = SalWinHelp( hWnd, strFile, nCommand, nData, strData )
2-232
SalXMLDeserializeUDV
Description
Starts the Windows help system. Use SalWinHelp to start a help system you created with the Microsoft Windows SDK. SQLWindows sends a SAM_Help message to the top-level object when the user presses the F1 key. Process this message by calling SalWinHelp.
Parameters
hWnd strFile nCommand nData
Window Handle. The handle (or name) of the window requesting help. String. The file name of the help system file. Number. The type of help requested; any HELP_* value. Number. Specify zero (0) unless: nCommand is HELP_Context and nData is a context identifier number. nCommand is HELP_SetIndex and nData specifies the current help index. HELP_FINDER uses constant to bring up the help Find Dialog.
strData
String. The context or keyword string of the requested help topic. This parameter is null unless nCommand is equal to HELP_Key.

Call SalWinHelp ( hWndForm, 'CONTROL.HLP', HELP_Index, 0, '')
SalXMLDeserializeUDV
Syntax Description bOk = SalXMLDeserializeUDV ( sUDV, sFilename, sSchema ) Writes data from an XML file into a UDV or array. The XML file should be a good match for the structure of the UDV or array. For example, the datatype of an element in the XML file should be compatible with the datatype of the identically-named instance variable in the UDV, and the attribute class=xxx in the XML file should use a class name matching that of the UDV. The XML file can contain extra information that does not match any instance variables of the UDV; that extra information will be ignored. The easiest way to be sure that the XML file is a good match is to create the XML file originally through a call to SalXMLSerializeUDV. If parameter sUDV does not evaluate at runtime to a UDV or array that is in scope, an error will occur.
2-233
Chapter 2
If an error occurs, this function will return FALSE. You can then call SalXMLGetLastError to get the text of the error. Parameters sUDV sFilename sSchema Return Value See Also Example String. The name of the UDV or array to be overwritten. String. The name of the XML file containing the data. String. Reserved for future use. Any value specified will be ignored.
bOk is TRUE if the function succeeds and FALSE if it fails. SalXMLSerializeUDV

Call SalXMLDeserializeUDV( oMyInvoice, invoice.xml, )
SalXMLGetLastError
Syntax Description bOk = SalXMLGetLastError ( nError, sError) Retrieves the error code and description resulting from the most recent XML operation. The errors that are monitored by this function can occur as a result of a call to SalXMLDeserializeUDV, SalXMLSerializeUDV, or any of the many functions found in optional include library xmllib.apl. Parameters nError sError Receive Number. The internal error code. If the most recent XML operation succeeded, this value will be zero Receuve String. The descriptive text associated with the value of nError. If the most recent XML operation succeeded, this value will be empty.
bOk is TRUE if the function succeeds and FALSE if it fails. SalXMLDeserializeUDV SalXMLSerilaizeUDV
Call SalXMLGetLastError( nReturn, sDescription )
SalXMLSerializeUDV
Syntax Description bOk = SalXMLSerializeUDV ( sUDV, sFilename, nWriteStyle ) Writes data from a UDV or array into an XML data file. If parameter sUDV does not evaluate at runtime to a UDV or array that is in scope, an error will occur. If an error occurs, this function will return FALSE. You can then call SalXMLGetLastError to get the text of the error. 2-234
SalYieldEnable
The name of the root element in the output document becomes the UDV name that was referenced in the first parameter. The class definition of the UDV is included as an attribute (for example, class="myClass"). The names of other elements are equal to the names of the class variables and instance variables in the UDV. Arrays are defined in an element whose name is the same as the name of the array, then a series of elements named "arrayEntry", one for each array element, with attribute "index=0", index="1", etc. Multi-dimensional arrays are not supported, whether as the main target of the function call or as an incuded array inside a UDV. Processing will continue but the array will not be serialized and an error will be produced. The UDV can contain any mixture of primitive datatypes (number, string, date/time) and nested UDVs as instance variables. Class variables are not serialized. All levels of nesting will be represented in the output file. Whether or not a specific variable is included in the XML output is determined at design time, when you edit the UDVs class definition to set property "Serialize" to TRUE or FALSE. In addition, the built-in SAL primitive datatypes are less specialized than those supported by XML. (For example, is a SAL "Number" variable an integer, a float, a decimal, or a double?) For this reason you should specify, at design time, the specific XML datatype to be associated with each primitive variable that will be serialized. The XML datatype and the Serialize property can be set through the Coding Assistant, Active Coding Assistant, or the right-click context menu, when focus is on an instance variable in a class definition. Parameters sUDV sFilename nWriteStyle Return Value See Also Example String. The name of the UDV or array to be written. String. The name of the XML file to contain the data. String. Reserved for future use. Any value specified will be ignored.
bOk is TRUE if the function succeeds and FALSE if it fails. SalXMLDeserializeUDV

Call SalXMLSerializeUDV( oMyInvoice, invoice.xml, )
SalYieldEnable
Syntax Description Parameters Return Value bOk = SalYieldEnable ( bSet ) Enables or disables application yielding. bSet Boolean. If TRUE, enable yielding; if FALSE, disable yielding.
2-235
Chapter 2
See Also
SalYieldQueryState SalYieldStartMessages SalYieldStopMessages

Call SalYieldEnable( FALSE )
Example
SalYieldQueryState
Syntax bEnabled = SalYieldQueryState ( ) Determines whether application yielding is enabled or disabled. Parameters Return Value See Also No parameters. bEnabled is TRUE if yielding is enabled, and FALSE if it is not. SalYieldEnable SalYieldStartMessages SalYieldStopMessages
Set bEnabled = SalYieldQueryState ( )
Example
SalYieldStartMessages
Syntax Description bOk = SalYieldStartMessages ( hWnd ) Enables yielding and the sending of messages to a window. Enable yielding to give the user enough control to stop long operations. For example, if it takes a long time to populate a table window, allow the user access to a Cancel push button to stop the query. Parameters Return Value See Also hWnd Window Handle. The handle (or name) of a window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalYieldEnable SalYieldQueryState SalYieldStopMessages
Call SalYieldStartMessages ( pbCancel )
Example
2-236
SalYieldStopMessages
SalYieldStopMessages
Syntax Description Parameters Return Value See Also bOk = SalYieldStopMessages ( ) Stops yielding and the sending of messages to the window specified in a prior call to SalYieldStartMessages. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalYieldEnable SalYieldQueryState SalYieldStartMessages
Call SalYieldStopMessages ( )
Example
SqlClearImmediate
Syntax Description bOk = SqlClearImmediate ( ) Disconnects the internal Sql Handle from a database. You connect the internal handle to a database by calling SqlImmediate and it remains connected until the application terminates or you explicitly disconnect it with SqlClearImmediate. SqlClearImmediate causes an implicit COMMIT if it is the last cursor you disconnect from the database. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SqlImmediate
Set bOk = SqlClearImmediate ( )
SqlClose
Syntax Description bOk = SqlClose ( hSql ) Invalidates a SQL command and/or frees the cursor name associated with the specified cursor, making it available for re-use. If you create a named cursor by calling SqlOpen and then instead of closing it, call SqlOpen or SqlExecute again, you get an error that the name has already been used. Parameters hSql Sql Handle. A handle that identifies a database connection.
2-237
Chapter 2
bOk is TRUE if the function succeeds and FALSE if it fails. SqlOpen

Set bOk = SqlClose ( hSql )
SqlCloseAllSPResultSets
Syntax Description bOk = SqlCloseAllSPResultSets ( hSql ) This function closes any result sets generated by the execution of a stored procedure. This function is useful when you want to retrieve the return status of the stored procedure without having to go through all the result sets and close them individually. If there was no stored procedure executed on this Sql Handle, this function returns FALSE. If there is no return status associated with the stored procedure executed on this Sql Handle, there is no need to call this function. And, if there is a return status associated with the stored procedure, the value of the SAL variable specified at the time of SqlPrepareSP will be automatically updated with the return status soon after this function returns successfully. Parameters Return Value Example hSql Sql Handle. The sql handle on which the Stored Procedure was prepared.

Message Actions On SAM_Click Call SalDisableWindow (pbFetch) Call SalDisableWindow (pbNextRS) Set bOk = SqlCloseAllSPResultSets( hSql ) If bOk = FALSE Call SalMessageBox ('Close ResultSet failed', 'Error!', MB_Ok) Else Set dfInteger = numReturn Call SalMessageBox ( ' Return value is NOW available !', 'Good job', MB_Ok )
See Also
SqlGetNextSPResultSet SqlPrepareSP
2-238
SqlCommit
SqlCommit
Syntax Description bOk = SqlCommit ( hSql ) Commits all of the SQL transaction's cursors that are connected to the same database. NOTE: To prevent destroying a cursor's result set when a COMMIT is performed, turn on cursor context preservation by calling SqlSetParameter and setting the DBP_PRESERVE parameter to TRUE. Parameters Return Value Example hSql Sql Handle. A handle that identifies a database connection.

Call SqlCommit ( hSql )
SqlCommitSession
Syntax Description bOk = SqlCommitSession ( hSession ) This call commits the current transaction associated with the specified session. The SQL operations currently active on all the statements belonging to this session get committed. Instead of taking a SqlHandle as its input (as done in case of the old SqlCommit function), this function takes the session handle. This function returns TRUE if the transaction was committed successfully. If the call failed, it returns FALSE. Parameters Return Value Example hSession Session Handle. The session handle used to commit the transaction.

Message Actions On SAM_Click ! ! Commit the transaction... Set bOk = SqlCommitSession (hSession) If bOk Call SalMessageBox ( ' Committed!!', 'Good', MB_Ok) Else Call SalMessageBox ( ' Commit failed ', 'Bad', MB_Ok)
See Also
SqlCreateSession SqlCreateStatement SqlFreeSession
2-239
Chapter 2
SqlGetSessionHandle
SqlConnect
Syntax Description bOk = SqlConnect ( hSql ) Connects to a database. The connection will be via OLE DB or via native routers, depending on the presence or absence of a value in system variable SqlUDL. SQLWindows uses the values in the SqlUDL, SqlDatabase, SqlUser, and SqlPassword variables. The default values for these variables are (none), DEMO, SYSADM, and SYSADM. The value of other system variables such as SqlNoRecovery, SqlInMessage, and SqlOutMessage take effect after this function executes. SqlUDL is a system variable that can contain a provider name, a connection string, or the name of a UDL file to use for OLE DB connection information. This variable was introduced in version 3.1. One of its purposes is to ease the migration of existing SQLWindows applications from use of native routers to use of OLE DB. In many cases, existing apps simply need a few lines to set the value of SqlUDL and the rest of the app will run smoothly against OLE DB To accomplish this, function SQLConnect has been altered in SQLWindows version 3.1. SQLConnect now looks first at variable SqlUDL and, if it finds a file name in that variable, reads connection information from that file. If it finds a provider name or connection string in SqlUDL, it uses the provider name. However, variables SqlDatabase, SqlUser and SqlPassword may still affect the connection information. If the database name or user name or password was not specified from the SqlUDL information, SQLConnect will obtain the needed value from those three variables. If the SqlUDL information was complete, but there is also a value in SqlDatabase, SqlUser, or SqlPassword, that value will override whatever had been in the connection information. This function then forms a connection string from that information, then makes an OLE DB connection with that string. Because variable SqlPassword can override any password information that may have been in the connection string, you can keep password information out of the UDL file and supply it programmatically at runtime instead, for greater security. If SqlUDL is null, SqlConnect uses the older (API and routers) method of connecting with the values of SqlDatabase, SqlUser, and SqlPassword.. Parameters Return Value See Also hSql Receive Sql Handle. A handle that identifies a database connection.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlDisconnect
2-240
SqlContextClear
Example
Call SqlConnect ( hSqlPrimary )
SqlContextClear
Deprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup. Syntax Description bOk = SqlContextClear ( hSql ) Clears the context set by SqlContextSet or SqlContextSetToForm. SQLWindows evaluates the bind and into variables associated with the specified Sql Handle in the local context. hSql Sql Handle. A handle that identifies a database connection.
Parameters Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SqlContextSet SqlContextSetToForm SqlImmediateContext
Set bOk = SqlContextClear ( hSql )
Example
SqlContextSet
Deprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup. Syntax Description bOk = SqlContextSet ( hSql ) Sets the context for future processing (for example, calls to SqlPrepare, SqlFetchNext, SqlFetchPrevious, and SqlFetchRow). Sql* functions you call after SqlContextSet behave as if they are in the window identified by hWndForm. Call this function in a class to perform SQL processing for the current window without fully qualifying bind and into variables. This function is also useful for global functions. Important: After you call SqlContextSet, the context for bind variables and into variables is
always hWndForm. If you call a Sql* function in an internal function, window function, or class function after calling SqlContextSet, SQLWindows does not recognize local variables or parameters that you use as bind variables and into variables.
hSql
Sql Handle. A handle that identifies a database connection.
2-241
Chapter 2
See Also
SqlContextClear SqlContextSetToForm SqlImmediateContext

Set bOk = SqlContextSet ( hSql )
Example
SqlContextSetToForm
Deprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup. Syntax Description bOk = SqlContextSetToForm ( hSql, hWndMyForm ) This function is like SqlContextSet, except for an additional parameter. SqlContextSet sets the context of the Sql Handle to the window identified by hWndForm; SqlContextSetToForm sets the context of the Sql Handle to the window you specify in the second parameter. Call this function from a child table window when you want to set the context to the parent form window; in this situation hWndForm refers to the child table window, not to the parent form window. Parameters hSql hWndMyForm See Also SqlContextClear SqlContextSet SqlImmediateContext
Set bOk = SqlContextSetToForm ( hSql, hWndMyForm )
Sql Handle. A handle that identifies a database connection. Window Handle. The handle of the window to which to set the execution context.
Example
SqlCreateSession
Syntax Description bOk = SqlCreateSession ( hSession, strSessionProperties ) This function creates a new session. This function takes as its input argument a string which specifies all the properties for this session. . This call returns a valid session handle if the call was successful. All statements created using a single session belong to the same transaction. Thus, a commit call on a given session handle commits SQL operations on all the statements belonging to that session. Similarly, a rollback on a session rolls back all SQL operations on all statements belonging to that session. Instead of taking a SqlHandle as its input (as compared to the old SqlConnect function ), this function takes the Session Handle.
2-242
SqlCreateSession
When connected to SQLBase, or when using an OLE DB connection, a call to SqlCreateSession will create a new database connection. When connected to other databases, Gupa first checks the combination of database name, user ID, and password. For each new combination, a new database connection is created. However, if the combination has already been used in the application, only a new cursor is created, not a new database connection. About session properties: OLE DB specifications allow a program to set specific session properties at the time of establishing a session. Using SAL, you do not have to make a separate function call to set these prooperties. SQLWindows internally sets all the properties to the values specified in this call. Session Properties also remove any dependency on the configuration (SQL.INI) file; the call to create the session itself provides all the information necessary to identify the OLE DB provider to be targeted for this session. For example, a SQLWindows application wishing to connect to SQLBase using the SQLWindows OLE DB Data Provider specifies, at the minimum, the following session property:
Set strSessionProp = "Provider=SQLBASEOLEDB;"
A more explicit version of the same example might be:

Set strSessionProp = "Provider=SQLBASEOLEDB;Data Source=Island;User IDr=sysadm;Password=sysadm;"
Connection string information may be overridden by system variables

In all cases described above, any missing information in the final connection string is obtained from the system variables SqlDatabase, SqlUser, and SqlPassword. In addition, even if the connection string does contain information about user, password, and database, that information may be overridden. If there are any values in variables SqlDatabase, SqlUser, and SqlPassword, those values will be used in preference to anything that is already present in the connection string, regardless of whether that connection string came from variable SqlUDL, from a UDL file, or from an actual string passed as a parameter to this function.
Parameters
hSession
Session Handle. The session handle created as a result of this call.
strSessionProperties String. The string that specifies the session properties for this session. There are several possible behaviors for this parameter. If it is null, this function looks at system variable SqlUDL to get connection information. SqlUDL may contain the name of a UDL file or the name of an OLE DB provider. If SqlUDL is also null, then this session makes a connection
2-243
Chapter 2
using the SQL API and routers, not OLE DB. If strSessionProperties is not null, it may be a file name ending in .UDL - in this case, the function reads that file to obtain connection information. Otherwise, when strSessionProperties is not null, it is presumed that this parameter is a string that contains connection information. In all the cases above, if the resulting connection string is missing the database name, user ID or password, then values are obtained from SAL global variables SqlDatabase, SqlUser and SqlPassword respectively. Return Value Example bOk is TRUE if a new session was created successfully. If the call failed, it returns FALSE.
If dfSessionProp != '' Set strSessionProp = strSessionProp || dfSessionProp Set SqlDatabase = dfDatasource Set SqlUser = dfUser Set SqlPassword = dfPassword Set bOk = SqlCreateSession (hSession, strSessionProp) If bOk Call SalMessageBox( 'Create session done', 'Good!', MB_Ok ) Call SalEnableWindow( pbFreeSession) Call SalEnableWindow( pbFreeStatement) Call SalEnableWindow( pbCreateStatement) Call SalEnableWindow( pbExecuteSQL) Else Call SalMessageBox( 'Create session failed', 'error!', MB_Ok )
See Also
SqlCommitSession SqlCreateStatement SqlFreeSession SqlGetSessionHandle
SqlCreateStatement
Syntax Description bOk = SqlCreateStatement ( hSession, hSql ) This call creates a new statement belonging to the specified session. The Sql Handle parameter specified here is the same as what the current SqlConnect call returns. There can be any number of statements within a session; there is no limit on this number.
2-244
SqlDirectoryByName
This call returns a statement handle if the call was successful. To free a statement, the existing SqlDisconnect call needs to be used. Parameters hSession hSql Return Value Example Session Handle. The Session handle used to create the statement. Sql Handle The Sql handle used to associate any number of statements to a session.
bOk is TRUE if a statement was created successfully. If the call failed, it returns FALSE.
Pushbutton: pbCreateStatement Message Actions On SAM_Click ! ! Create the statement Set bOk = SqlCreateStatement (hSession, hSql) If bOk Call SalMessageBox( 'Create statement done', 'Good!', MB_Ok ) Else Call SalMessageBox( 'Create statement failed', 'error!', MB_Ok )
See Also
SqlCommitSession SqlCreateSession SqlFreeSession SqlGetSessionHandle
SqlDirectoryByName
Syntax Description Parameters bOk = SqlDirectoryByName ( strServerName, strArrayNames ) Returns the database names on the specified server. strServerName strArrayNames Return Value Example String. The name of a server. String Array. The name of an array of strings containing database names.

On SAM_AppStartup Call SqlDirectoryByName ( 'server1', strDatabaseNames )
SqlDisconnect
Syntax Description bOk = SqlDisconnect ( hSql ) Disconnects from a database.
2-245
Disconnecting the last Sql Handle from a database causes an implicit COMMIT of the database. Disconnect all Sql Handles before the application exits. Parameters Return Value See Also Example hSql Sql Handle. The handle that identifies the database connection to disconnect.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlConnect

On SAM_AppExit Call SqlDisconnect ( hSqlPrimary )
SqlDropStoredCmd
Syntax Description Parameters bOk = SqlDropStoredCmd ( hSql, strName ) Deletes a stored command from a SQLBase database. hSql strName Return Value See Also Example Sql Handle. A handle that identifies a database connection. String. The name of the stored command to delete.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlRetrieve SqlStore
Call SqlDropStoredCmd ( hSqlPrimary, 'PRODUCTS )
SqlError
Syntax Description nError = SqlError ( hSql ) Returns the most recent error code for the specified Sql Handle. SqlError is not useful after a call to SqlImmediate because SqlImmediate does not return a handle that you can use as the parameter for SqlError. Parameters Return Value See Also Example hSql Sql Handle. The handle on which an error occurred.
nError is the error code returned. It is equal to zero (0) if no error occurred. SqlExtractArgs
Set nSqlError = SqlError ( hSqlPrimary )
SqlErrorText
SqlExecute
Syntax Description
bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength ) Gets the error reason or remedy for the specified error code from ERROR.SQL. Call SqlError to get the most recent error code. When your application detects an error condition, you can use the error code returned by SqlError to look up the error reason and remedy with SqlErrorText. When connected to an OLE DB data source, do not use this function; use SqlGetSessionErrorInfo instead.
Parameters
nError nType
Number. A SQLBase error code. Number. Specify one or both (by combining them with the OR (|) operator) of these constants:
Constant Description Retrieve error code reason. Retrieve error message remedy.
SQLERROR_Reason SQLERROR_Remedy
strError nLength nRealLength Return Value See Also
Receive String. The reason or remedy explanation. Number. The maximum length of strError. Receive Number. The actual length of strError.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlError SqlGetErrorText SqlGetErrorTextX
Set bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength )
Example
SqlExecute
Syntax Description bOk = SqlExecute ( hSql ) Executes a SQL statement that was prepared with SqlPrepare or retrieved with SqlRetrieve. SqlExecute does not fetch data. To fetch data, call one of the SqlFetch* functions: SqlFetchNext, SqlFetchPrevious, or SqlFetchRow. Bind variables are sent to the database when you call SqlExecute.
2-247
Chapter 2
You can use SqlExecute just like SqlOpen, but you can never address rows in the result set by a cursor name. That is, you cannot use the 'CURRENT OF <cursor_name>' and 'ADJUSTING <cursor_name>' clauses to UPDATE, DELETE or INSERT result set rows. Parameters Return Value See Also Example hSql Sql Handle. The handle associated with a SQL statement.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlOpen

Call SqlExecute ( hSqlPrimary )
SqlExecutionPlan
Syntax Description bOk = SqlExecutionPlan ( hSql, strString, nLength ) Gets the execution plan for a compiled SQL statement. An execution plan shows the tables, views, indexes, and optimizations for the SQL statement. Tables and views are listed in the order in which they are processed. hSql strString nLength Return Value Example Sql Handle. The handle associated with a compiled SQL statement. String. The execution plan. Also, a Receive parameter. Number. The maximum length of the execution plan. Also, a Receive parameter.
Parameters

Set bOk = SqlExecutionPlan ( hSql, strString, nLength )
SqlExists
Syntax Description bOk = SqlExists ( strSelect, bExists ) Determines whether a row exists. SqlExists uses the values of the SqlDatabase, SqlUser, and SqlPassword variables to connect to a database, and uses an internal Sql Handle to execute the specified query. Parameters strSelect bExists Return Value String. The SELECT statement that establishes the existence of a row. Receive Boolean. TRUE if the row exists and FALSE if it does not.
bOk is TRUE if strSelect is correct and executable and FALSE otherwise.
2-248
SqlExtractArgs
Example
Call SqlExists ( 'SELECT * FROM ' || strTable || 'WHERE ' || strExistsColumn || ' = ' || '\'' || strExistsObject || '\'', bExists )
SqlExtractArgs
Syntax Description bOk = SqlExtractArgs ( wParam, lParam, hSql, nError, nPos ) Extracts information from the SAM_SqlError wParam and lParam arguments. Call this function only while processing a SAM_SqlError message which is sent when an error occurs while executing a SQL function. wParam lParam hSql Number. The value of the wParam argument of the SAM_SqlError message. Number. The value of the lParam argument of the SAM_SqlError message. Receive Sql Handle. The handle of the function that got an error. SQLWindows extracts this value from the wParam argument. Receive Number. The error code. SQLWindows extracts this value from the low-order word of the lParam argument. Receive number. The error position, if relevant to the function call. SQLWindows extracts this value from the high-order word of the lParam argument.
Parameters
nError nPos
bOk is TRUE if the function succeeds and FALSE if it fails. SqlError SqlGetErrorPosition
Call SqlExtractArgs ( wParam, lParam, hSqlError, nSqlError, nErrorPos )
SqlFetchNext
Syntax Description Parameters bOk = SqlFetchNext ( hSql, nInd ) Fetches the next row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen. hSql Sql Handle. The handle of a SELECT statement.
2-249
Chapter 2
nInd Return Value
Receive Number. The fetch return code is one of the FETCH_* values.
bOk is TRUE if another row was fetched and FALSE if no row was fetched. SqlFetchNext does not return FALSE and Fetch indicatior does not show EOF until you attempt to fetch past the last row. SqlFetchPrevious SqlFetchRow
Call SqlFetchNext ( hSqlPrimary, nRetVal )
See Also Example
SqlFetchPrevious
Syntax Description bOk = SqlFetchPrevious ( hSql, nInd ) Fetches the previous row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen. hSql nInd Return Value See Also Sql Handle. The handle of a SELECT statement. Receive Number. The fetch return code is one of the FETCH_* values.
Parameters
bOk is TRUE if there is another row to fetch and FALSE otherwise. SqlFetchNext SqlFetchRow
Example
Call SqlFetchPrevious ( hSqlPrimary, nRetVal)
SqlFetchRow
Syntax Description bOk = SqlFetchRow ( hSql, nRow, nInd ) Fetches a row according to an absolute row position. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen. Note that when connected to an Oracle database, you must first set SqlResultSet to FALSE before calling SqlFetchRow. When connected to SQLBase or any non-Oracle database, you must first set SqlResultSet to TRUE before calling SqlFetchRow. Parameters hSql Sql Handle. The handle of a SELECT statement.
nRoNumber. The row number of the row to fetch.
2-250
SqlFreeSession
nInd Return Value See Also Example
Receive Number. The fetch return code is one of the FETCH_* values.
bOk is TRUE if nRow could be fetched and FALSE otherwise. SqlFetchNext SqlFetchPrevious
Call SqlFetchRow ( hSqlPrimary, lParam, nRetVal )
SqlFreeSession
Syntax Description Parameters Return Value Example bOk = SqlFreeSession ( hSession ) This call frees the session. If there are any open statements belonging to this session, they are closed before the session is freed. hSession Session Handle. The session handle used to commit the transaction.
bOk is TRUE if the specified session was freed successfully. If the call failed, it returns FALSE.
Pushbutton: pbFreeSession Message Actions On SAM_Click If (hSession) Call SqlFreeSession (hSession) Call SalDisableWindow (pbCreateStatement) Call SalDisableWindow (pbFreeStatement) Call SalDisableWindow (pbFreeSession) Call SalDisableWindow (pbExecuteSQL)
See Also
SqlCommitSession SqlCreateSession SqlCreateStatement SqlGetSessionHandle
SqlGetCmdOrRowsetPtr
Syntax Description bOk = SqlGetCmdOrRowsetPtr ( hSql, bCmdOrRowset, numOLEDBPtr ) This function gives the caller either the ICommand or the IRowset interface pointer of the Command or the Rowset OLE DB object. Once you get the interface pointer, you can pass it to an external DLL and use it as needed (for example, to access interfaces/methods that we do not expose in SAL).
2-251
Chapter 2
Parameters
hSql bCmdOrRowset
Sql Handle. The Sql handle associated with the Command or the Rowset object. BOOLEAN. If set to TRUE, this function gives the user the ICommand interface pointer. If set to FALSE, this function gives the user the IRowset interface pointer. Number. This contains the interface pointer as specified if the function was successful. It contains NULL if there is no rowset associated with this Sql handle yet, and if the user asks for the IRowset interface pointer.
numOLEDBPtr

Message Actions On SAM_Click ! ! Get the Rowset object ptr. The code returns the IRowset interface ptr Set bOk = SqlGetCmdOrRowsetPtr( hSql, 0, dfRSPtr ) If bOk Call SalMessageBox ( ' Got the IRowset interface ptr!!', 'Good', MB_Ok) Else Call SalMessageBox ( ' Getting IRowset interface pointer failed ', 'Bad', MB_Ok)
See Also
SqlGetCommandText
Syntax Description bOk = SqlGetCommandText (hSql, sText) This function returns the SQL command last prepared on the specified SQL handle. This function is only supported against OLE DB connections. If the Sql Handle was not created with an OLE DB provider, then, the function returns FALSE. If the call is made before a SQL command was prepared (either by SqlPrepare, SqlPrepareAndExecute or SqlPrepareSP), then the function returns FALSE. Note that the function returns the SQL string even if the prepare failed (due to wrong syntax etc). There is a related function named SqlGetLastStatement. That function doesnt take a Sql Handle as a parameter and returns the last statement that was prepared in the entire application. With OLE DB applications, Gupta does not recommend using that function. 2-252
SqlGetCursor
Parameters
hSql sText
Sql Handle. The Sql handle associated with the desired statement handle. Receive String. The text of the command that was prepared.
Return Value
bOk
Boolean. TRUE for success and FALSE for failure.
SqlGetCursor
Syntax Description nCursorHandle = SqlGetCursor ( hSql ) This function gets the actual cursor handle associated with a SQL handle. The cursor handle returned is useful when calling functions in the SQLBase API. It is equivalent to the second parameter of SQLBase API function sqlcnc. This function is only valid with SQLBase and native routers. Do not use it against an OLE DB connection. Parameters Return Value hSql nCursorHandle Sql Handle. The logical SQL handle for which you seek the statement handle. Number. Use this cursor handle when calling a large number of SQLBase API functions that require such a handle.
Syntax Description bOk = SqlGetDSOrSessionPtr ( hSql, bDSOrSession, numOLEDBPtr ) This function gives the caller the IDBInitialize interface pointer of the Data Source OLE DB object or the IDBCreateSession interface pointer of the Session OLE DB object. Once you get the interface pointer, you can pass it to an external DLL and use it as needed (for example, to access interfaces/methods that we do not expose in SAL). Parameters hSql bDSOrSession Sql Handle. The Sql handle associated with the interface pointer. BOOLEAN. If set to TRUE, this function gives the user the IDBInitialize interface pointer. If set to FALSE, this function gives the user the IDBCreateSession interface pointer. Number. NULL if there is no rowset associated with this Sql Handle yet, and if the user asks for the IDBInitialize interface pointer.
numOLEDBPtr
2-253
Chapter 2

Message Actions On SAM_Click !!Get the DataSource object ptr. The code returns the IDBInitialize interface ptr Set bOk = SqlGetDSOrSessionPtr( hSession, 1, dfDSPtr ) If bOk Call SalMessageBox ('Got the IDBInitialize interface ptr!!','Good', MB_Ok) Else Call SalMessageBox ( 'Getting IDBInitialize interface pointer failed ', 'Bad', MB_Ok)
See Also
SqlGetCmdOrRowsetPtr
SqlGetError
Syntax Description bOk = SqlGetError( hSql, nError, strErrorString ) Turns off backend error mapping and reports real backend errors. If the error number is less than 20,000, the file ERROR.SQL is searched for the error text and that text (if found) is returned; otherwise, the translated error number and database error message from the database server are returned. When connected to an OLE DB data source, do not use this function; use SqlGetSessionErrorInfo instead. Parameters hSql nError strErrorString Return Value Sql Handle. The handle of a SELECT statement. Number. The error number. String. The error text.
bOk is TRUE if the function succeeds and FALSE if it fails. You specify the Sql Handle in hSql and SqlGetError returns the last error number and error text in nError and strErrorString. If the backend is SQLBase, this function does the same thing as calling SqlError and SqlGetErrorText.
Example
Set bOk = SqlGetError( hSql, nError, strErrorString )
SqlGetErrorPosition
Syntax bOk = SqlGetErrorPosition ( hSql, nPos )
2-254
SqlGetErrorText
Description
Returns the offset of the error position within a SQL statement. After a SqlPrepare, the error position points to the place in the SQL statement where SQLWindows detected aSyntax error. The first character position in the SQL statement is zero (0). This function is valid only when used against a SQLBase database connection. When used with any other database router, including OLE DB, the function always returns zero.
Parameters
hSql nPos
Sql Handle. The handle of a SELECT statement. Receive Number. The position in the SQL statement where aSyntax error occurred.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlExtractArgs

Call SqlGetErrorPosition ( hSqlPrimary, nErrorPos )
SqlGetErrorText
Syntax bOk = SqlGetErrorText ( nError, strText ) or strText = SqlGetErrorTextX ( nError ) Description Gets the message text for a SQL error number from ERROR.SQL. When connected to an OLE DB data source, do not use this function; use SqlGetSessionErrorInfo instead. Parameters nError strText Return Value Number. The error number. Receive String. The error text.
bOk is TRUE if the function succeeds and FALSE if it fails. strText is the message text for nError.
See Also Example
SqlErrorText SqlExtractArgs
Call SqlGetErrorText ( nError, strText ) or Set strText = SqlGetErrorTextX ( nError )
2-255
Chapter 2
SqlGetErrorTextX
Syntax Description strText = SqlGetErrorTextX (nError) When the user chooses the Insert menu item, this example compiles a SQL statement for execution. To process any invalid SQL statements and trap the error (bypassing the default error processing), add the When SqlError statement with a FALSE return before the SqlPrepare. When SqlPrepare returns FALSE, call SqlError to get the error number, call SqlGetErrorTextX to get the error description, and call SqlGetErrorPosition to get the character position where theSyntax error was detected.
Set strErrorText = SqlGetErrorTextX ( nSqlError )
Example
SqlGetLastStatement
Syntax Description sSqlStatement = SqlGetLastStatement( ) Returns the last SQL statement passed to a SqlXxxx function for any cursor. The statement returned is the same statement that would be shown in the default SQL Error dialog box. Note: The statement is global for all cursors, therefore, if you get a SQL error after another cursor has had a statement prepared the statement returned may not be the one prepared for the handle. Parameters Return Value Example No parameters. sSqlStatement contains the last SQL statement.
When SqlError Set sStatement = SqlGetLastStatement()
SqlGetModifiedRows
Syntax Description Parameters bOk = SqlGetModifiedRows ( hSql, nCount ) Returns the number of rows affected by the most recent INSERT, UPDATE, or DELETE statement. hSql nCount Return Value Example Sql Handle. The handle of a SQL statement. Receive Number. The number of rows affected.

Set bOk = SqlGetModifiedRows ( hSql, nCount )
2-256
SqlGetNextSPResultSet
SqlGetNextSPResultSet
Syntax Description bOk = SqlGetNextSPResultSet ( hSql, strIntoList, bEndOfRS ) If a stored procedure invoked by calling SqlPrepareSP (and later executed by calling SqlExecute or SalTblPopulate) returns more than one result set, the application should call this function to get the second and subsequent result sets. Separate the variables listed in strIntoList with commas and precede each variable name with a colon. If the stored procedure returns zero rows, the variables in strIntoList keep whatever values they had before the call to this function. If a result set is returned its associated cursor points to just before the first row of the result set. To set the INTO variables in strIntoList to the column values of the first row, call SqlFetchNext. To obtain subsequent rows in the result set, repeatedly call SqlFetchNext. Once all the rows in a given result set have been retrieved, get the next result set (if any) by again calling SqlGetNextSPResultSet. Parameters hSql strIntoList Sql Handle. The sql handle on which the Stored Procedure should be executed. String. String variable that contains the Into variables for any result set generated by the Stored Procedure. If the caller knows that the stored procedure does not generate any result set, this can be set to strNull. If passed, this should be a comma-separated list of variables and precede each variable name with a colon. BOOLEAN. If SqlGetNextSPResultSet is called and there are no more result sets, the function will return FALSE and bEndOfRS is set to TRUE. If there are more result sets, bEndOfRS will be set to FALSE.
bEndOfRS

Message Actions On SAM_Click Set bOk = SqlGetNextSPResultSet( hSql, ' :dfString ', bEORS) If bOk = FALSE Call SalDisableWindow (pbFetch) Call SalMessageBox ('No more result sets', 'EORS', MB_Ok) Else Call SalEnableWindow (pbFetch)
2-257
Chapter 2
See Also
SqlCloseAllSPResultSets SqlPrepareSP
SqlGetParameter
Syntax Description bOk = SqlGetParameter ( hSql, nParameter, nNumber, strString ) Gets the value of a database parameter. This function returns the parameter value in nNumber or strString as appropriate for the data type of the parameter. When using a connection to database servers other than SQLBase you cannot manipulate parameters that are specific to those databases with SqlGetParameter. You must use SqlGetParameterAll instead. Parameters hSql nParameter nNumber Sql Handle. A handle that identifies a database connection. Number. The database parameter. Specify one of the DBP_* constants. Receive number. The value (TRUE or FALSE) of the parameter. If nParameter is DBP_BRAND, nNumber is one of the DBV_BRAND_* values. strString Return Value See Also Receive string. If you specify DBP_VERSION in nParameter, this is the version number.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameterAll SqlSetParameter SqlSetParameterAll
On SAM_AppStartup Call SqlGetParameter ( hSqlPrimary, DBP_LOCKWAITTIMEOUT, nTimeout, strNull )
Example
SqlGetParameterAll
Syntax Description bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber ) Gets the value of a database parameter identified by a SQLP* constant value defined in SQL.H. This function returns the parameter value in nNumber or strString as appropriate for the data type of the parameter.
2-258
SqlGetResultSetCount
Important: A set of the SQLP* constants in SQL.H have the same values as the DBP_*
constants, but the values identify different parameters. Be sure to specify the correct number.
Parameters
hSql nParameter nNumber
Sql Handle. A handle that identifies a database connection. Number. The database parameter. Specify the value of one of the SQLP* constants defined in SQL.H. Receive number. The value of nparameter it it is a number. Receive string. The value of nParameter if it is a string.
bNumber
Boolean. If TRUE, the parameter value is returned in nNumber. If FALSE, the parameter value is returned in strString.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameter SqlSetParameter SqlSetParameterAll
Set bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )
Example
SqlGetResultSetCount
Syntax Description bOk = SqlGetResultSetCount ( hSql, nCount ) Counts the rows in a result set by building the result set. SQLWindows fetches each row that has not already been fetched, returns a count of the rows, and positions the cursor back to its original position. Warning: this can be time-consuming if the result set is large. INSERTs into the result set increase the result set row count, but DELETEs which display as blank rows in result set mode do not decrease the row count. However, the deleted blank rows disappear on the next SELECT. You must be in Result Set mode. You must call SqlExecute before SqlGetResultSetCount. Parameters hSql nCount Return Value Example Sql Handle. A handle associated with a result set. Receive Number. The number of rows in the result set.

Actions
2-259
Chapter 2
Call SqlPrepare ( hSqlPrimary, strSqlTblWindow ) Call SqlExecute ( hSqlPrimary ) Call SqlGetResultSetCount ( hSqlPrimary, nRowCount )
SqlGetRollbackFlag
Syntax Description bOk = SqlGetRollbackFlag ( hSql, bRollbackFlag ) Returns the database rollback flag. Use this function after an error to find out if a transaction rolled back. SQLWindows sets the rollback flag when a system-initiated rollback occurs as the result of a deadlock or system failure. SQLWindows does not set the rollback flag on a user-initiated rollback. This function is valid for conenctions that use native routers, but not for OLE DB connections. Parameters hSql bRollbackFlag Return Value Example Sql Handle. The handle associated with the function call that got an error. Receive Boolean. TRUE if a rollback occurred and FALSE otherwise.

Call SqlGetRollbackFlag ( hSqlError, bRollbackFlag ) If bRollbackFlag ! Execute code to handle rolled back ! transaction
SqlGetSessionErrorInfo
Syntax Description bOk = SqlGetSessionErrorInfo ( hSession, numErrorNumber, strErrorDescription, strSqlState ) This call returns the error information associated with the specified session. Use this function if any of the newly introduced SAL functions which take the Session handle as the input return FALSE. Parameters hSession numErrorNumber strErrorDescription strSqlState Session Handle. The Session handle passed to the SAL call that failed. Number The error number. String. The error description. String. The Sql state.
2-260
SqlGetSessionHandle
Return Value bOk is TRUE if the error information was retrieved successfully. If the call failed, it returns FALSE. Example
Actions Set SessionProperties="Provider=DataDirect.Oracle8OLEDBProvider;" Set bok = SqlCreateSession(strSessionProp,SessionProperties) If bok Call SqlCreateStatement (strSessionProp, hSql) Set bok = SqlPrepareAndExecute (hSql,'drop table test ( col1 int ) ') If bok Call SalMessageBox('Succeeded','Succeeded',MB_Ok) Else Set nError = SqlError( hSql ) Call SqlGetStatementErrorInfo( strSessionProp, nError1, HStr, HStr1 ) Else Call SqlGetSessionErrorInfo( strSessionProp, nError1, HStr, HStr1 )
See Also
SqlGetStatementErrorInfo
SqlGetSessionHandle
Syntax Description bOk = SqlGetSessionHandle ( hSql, hSession ) This call returns the session handle to which the specified statement handle belongs. The SqlHandle must have been created using SqlCreateStatement function and not by calling SqlConnect function. hSql hSession Return Value Example
Message Actions On SAM_Click ! ! Create the statement Set bOk = SqlCreateStatement (hSession, hSql) If bOk Call SalMessageBox( 'Create statement done', 'Good!', MB_Ok ) ! ! Set auto commit ON Set bOk = SqlGetSessionHandle (hSql, hSession) ! !
Parameters
Sql Handle. The Sql handle used to associate any number of statements to a session. Session Handle. The Session handle of the statement.
bOk is TRUE if the function was successful. If the call failed, it returns FALSE.
2-261
Chapter 2
Set bOk = SqlSetSessionParameter (hSession, DBP_AUTOCOMMIT, FALSE, '') If bOk = FALSE Call SalMessageBox( 'set session parameter failed', 'error!', MB_Ok) ! ! Set bOk = SqlSetParameter (hSql, DBP_AUTOCOMMIT, FALSE, '') ! ! Else Call SalMessageBox( 'Create statement failed', 'error!', MB_Ok )
See Also
SqlCommitSession SqlCreateSession SqlCreateStatement SqlFreeSession
SqlGetSessionParameter
Syntax Description bOk = SqlGetSessionParameter ( hSession, numPropertyID, numValue, strValue ) This function gets the value of the specified session property. It takes as input the session handle and the property ID. This function will know the data type of the specified property ID and will accordingly return either the number value or the string value. Parameters hSession numPropertyID numValue strValue Return Value Example Session Handle. The session handle. Number. The number value of the property ID. Number. The number value of the property ID. String. The string value of the property ID.
bOk is TRUE if successful. It will return FALSE if it failed.

Pushbutton: pbGetParam Message Actions On SAM_Click Set bOk = SqlGetSessionParameter( hSession, dfPropID, dfIntValue, dfStrValue) If bOk = FALSE Call SalMessageBox ( 'GetSessionParam failed', 'Error!', MB_Ok) Else Call SalMessageBox ( 'GetSessionParam done', 'Done!', MB_Ok)
See Also
SqlSetSessionParameter
2-262
Syntax Description bOk = SqlGetStatementErrorInfo ( hSql, numErrorNumber, strErrorDescription, strSqlState ) This call returns the error information associated with the specified statement handle (command/cursor). Note that this function will work with Sql Handles created either with SqlCreateStatement or SqlConnect. In the case of Sql Handles created with SqlConnect, the SQLState will be always NULL. Parameters hSql numErrorNumber strErrorDescription strSqlState Return Value Example
Actions Set SessionProperties="Provider=DataDirect.Oracle8OLEDBProvider;" Set bok = SqlCreateSession(strSessionProp,SessionProperties) If bok Call SqlCreateStatement (strSessionProp, hSql) Set bok = SqlPrepareAndExecute (hSql,'drop table test ( col1 int ) ') If bok Call SalMessageBox('Succeeded','Succeeded',MB_Ok) Else Set nError = SqlError( hSql ) Call SqlGetStatementErrorInfo( strSessionProp, nError1, HStr, HStr1 ) Else Call SqlGetSessionErrorInfo( strSessionProp, nError1, HStr, HStr1 )
Sql Handle. The Sql handle passed to the SAL call that failed. Number The error number. String. The error description. String. The Sql state.
bOk is TRUE if the error information was retrieved successfully. If the call failed, it returns FALSE.
See Also
SqlGetSessionErrorInfo
SqlImmediate
Syntax Description bOk = SqlImmediate ( strSqlCommand ) Prepares and executes a SQL statement. SqlImmediate actually performs a SqlConnect, a SqlPrepare, a SqlExecute, and for SELECT statements, a SqlFetchNext. The first time you call SqlImmediate,
2-263
Chapter 2
SQLWindows performs all of these functions. On later calls, SqlConnect is not performed if not needed. Use SqlImmediate with INSERT, UPDATE, DELETE, and other non-query SQL commands. You can use SqlImmediate with a SELECT statement if you expect that the statement only returns one row. SqlImmediate manages SQLWindows' internal handle. It uses the values of the SqlDatabase, SqlUser, and SqlPassword system variables to connect to a database. You cannot use SqlImmediate when you are connected to an OLE DB datasource. Any command that you execute with SqlImmediate, you can also execute with explicit calls to SqlConnect, SqlPrepare, SqlExecute or SqlOpen, and SqlFetchNext, for SELECTs. Parameters strSqlCommand String. The SQL statement to prepare and execute. This statement cannot have more than 128 bind variables and more than 128 INTO variables.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlClearImmediate

Call SqlImmediate ( 'INSERT INTO COMPANY ( COMPANY )' ||'VALUES ( :frmMain dfCompany )' )
SqlImmediateContext
Deprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup. Syntax Description bOk = SqlImmediateContext ( strSqlStatement ) Prepares and executes a SQL statement, and evaluates any bind or into variables in the context of the window identified by hWndForm. Call this function in a class to perform SQL processing for the current window without fully qualifying bind and into variables. This function is also useful for global functions. Important: When you call SqlImmediateContext, the context for bind variables and into
variables is always hWndForm. If you call SqlImmediateContext in an internal function, window function, or class function, SQLWindows does not recognize local variables or parameters that you use as bind variables and into variables.
Parameters
strSqlStatement
String. A SQL statement.
2-264
SqlOpen
bOk is TRUE if the function succeeds and FALSE if it fails. SqlContextClear SqlContextSet SqlContextSetToForm
Set bOk = SqlImmediateContext ( strSqlStatement )
Example
SqlOpen
Syntax Description bOk = SqlOpen ( hSql, strCursorName ) Names a cursor and executes a SQL statement. Use this function to perform INSERTs, UPDATEs, and DELETEs on the current row. Call SqlOpen after SqlPrepare and before any of the SqlFetch* commands. Important: This function will return an error when used against an OLE DB database
connection.
Parameters
hSql strCursorName
Sql Handle. The handle associated with the SqlPrepare. String. A string containing the cursor name. Specify this name in the 'CURRENT OF <cursor_name>' or 'ADJUSTING <cursor_name>' clause of an INSERT, UPDATE, or DELETE statement. The value of this parameter is case insensitive. You can set it to null using the empty string ('').
bOk is TRUE if the function succeeds and FALSE if it fails. SqlClose SqlExecute
Set bOk = SqlOpen ( hSql, strCursorName )
SqlOraPLSQLPrepare
Syntax Description bOk = SqlOraPLSQLPrepare (hSql, strAnonymousPLSQLBlock) This function compiles the anonymous PL/SQL block. This function looks very much like the regular SqlPrepare function. But the underlying code is meant specifically for handling Oracle PL/SQL blocks. hSql SqlHandle. A handle that identifies a database connection.
Parameters
2-265
Chapter 2
strAnonymousPLSQLBlock String. The actual anonymous PL/SQL block that the user wants to prepare. That will also contain the input and output variables. Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
Set strAnonymousPLSQLBlock = ' BEGIN Pkg1.Proc1 ( :nInput1, :sOutput1, :nOutput2 ); Pkg1.Proc2 ( :nOutput2 ); Pkg1.Proc3 ( :sOutput1 ); END; ' bOk = SqlOraPLSQLPrepare ( hSql, strAnonymousPLSQLBlock)
Note: If this call is made to a non-Oracle connection, the function returns FALSE. This call needs a newer version of the Oracle router. If the router being used is not capable of supporting this call, an error "This call needs a newer version of Oracle router." is returned.
2-266
SqlOraPLSQLExecute
SqlOraPLSQLExecute
Syntax Description bOk = SqlOraPLSQLExecute (hSql) This function executes the anonymous PL/SQL block that was prepared using SqlOraPLSQLPrepare. If the execution succeeds, then all output parameters from the PL/SQL block are updated by the time the control returns to the user. hSql Sql Handle. The sql handle associated with the prepared Anonymous PL/SQL block.

Set strCMD = ' BEGIN Pkg1.Proc1 ( :nInput1, :sOutput1); Pkg1.Proc2 ( :sOutput1 ); Pkg2.Proc1 ( :nInput1 ); END; ' Set bOK = SqlOraPLSQLPrepare (hSql, strCMD) Set nInput1 = 100 Set bOk = SqlOraPLSQLExecute ( hSql ) If bOk ! now the output parameter is available Call SalMessageBox ( sOutput1, 'Output parameter from PL/SQL', MB_Ok)
SqlOraPLSQLStringBindType
Syntax Description bOk = SqlOraPLSQLStringBindType (hSql, strBindName, nBindType) This function informs the Oracle router the specific type of the STRING array bind variable that is being used in the prepared anonymous PL/SQL block. By default, any STRING array is bound to Oracle as a VARCHAR type. If the PL/SQL table is of type CHAR, this function needs to be called. If the PL/SQL table is either VARCHAR or STRING, there is no need to call this function. Call this function after doing a SqlOraPLSQLPrepare but before doing the SqlOraPLSQLExecute. Since the binding is done for every execute, you need to call this function every time you execute. hSql strBindName Sql Handle. The sql handle associated with the prepared Anonymous PL/SQL block. String. The name of the bind variable (the input or the output parameter) as specifed in the sql statement passed for the SqlOraPLSQLPrepare command.
Parameters
2-267
Chapter 2
nBindType
Number. The PL/SQL table datatype. Specify 5 if the table is either VARCHAR or STRING. Specify 97 if the PL/SQL table is of type CHAR.

! Data type declarations ! String: strCMD Number: nInput1 String: sOutput1[1:100] Boolean: bOk ! ! Code follows ! Set strCMD = ' ArrayPkg.Proc1 (:nInput1, :sOutput1); ' Set bOk = SqlOraPLSQLPrepare (hSql, strCMD) Set nInput1 = 100 Set bOk = SqlOraPLSQLStringBindType (hSql, 'sOutput1', 97) Set bOk = SqlOraPLSQLExecute (hSql) If bOk ! now the output parameter is available Call SalMessageBox ( sOutput1[1], 'Output parameter #1 from PL/SQL', MB_Ok)
Note: This function needs to be called only for string array parameters. If the PL/SQL block uses only scalars, irrespective of whether is CHAR or VARCHAR or STRING, this function is not needed. If the parameter is an array of type CHAR this function needs to be called. If this is not called and SqlOraPLSQLExecute is called, Oracle server will return errors ORA-6550 and PLS-00418 - "Array bind type must match PL/SQL table row type".
SqlPLSQLCommand
Syntax Description bOk = SqlPLSQLCommand ( hSqlHandle, strCommand ) Use this function to execute PL/SQL stored procedures in SQLWindows. Call it once for each invocation of PL/SQL. The first argument identifies the SQL Handle to the database. The second parameter is a command string used to invoke a PL/SQL stored procedure. Like a stored procedure call, this command string must have a name. You can use PL/SQL IN variables the same way you use any other parameter in SAL function calls. PL/SQL OUT or IN/OUT variables must be valid SAL receive parameters and, like SAL receive parameters, are set when the call returns. 2-268
SqlPLSQLCommand
You can use arrays for IN, OUT, and IN/OUT parameters. IN/OUT parameters can be made to pass data to the PL/SQL stored procedure and to receive data from a PL/SQL stored procedure in the same parameter. Note: The SqlPLSQLCommand supports SQLWindows dynamic arrays as input, output and input/output arguments to Oracle7 PL/SQL stored procedures. Dynamic arrays of type NUMBER, STRING and DATE/TIME are supported. Dynamic Arrays as INPUT arguments Dynamic arrays grow to the size of the largest index value used in an assignment statement using the dynamic array variables. For example: nDynvar[0] = 0 nnDynVar[1]= 1 nDynvar[9] = 9 causes nDynVar to be a dynamic array of 10 elements. When a dynamic array is passed as an INPUT argument to a PL/SQL stored procedure via SqlPLSQLCommand the number of elements created on the front-end are available on the backend. Thus in the backend stored procedure: insert into foo values(nDynVar(9)) will insert the value 9 into the table, while the statement insert into foo values(nDynVar(10)) will cause an error Attempting to fetch beyond end of result set. Uninitialized values Dynamic array values are not initialized on the front-end, but falling within the range of a dynamic array created on the front-end are passed as NULL for datatypes STRING and DATE/TIME and as zero for datatype NUMBER. To pass NUMBER as a NULL, the user must explicitly assign them as NUMBER_Null on the front-end; Dynamic Arrays as OUTPUT arguments The size of output arguments of type dynamic array is determined in the backend stored procedure . For example: sOutVar(1):= abc; sOutVar(10) := def; returns an array of size 10 to the front-end program. Uninitialized values Values for output arguments are not initialized on the backend, but are returned as NULL values.
2-269
Chapter 2
Dynamic Arrays as INPUT/OUTPUT arguments INPUT / OUTPUT dynamic arrays behave as INPUT dynamic arrays on input and as OUTPUT dynamic arrays on OUTPUT. Parameters hSqlHandle strCommand Return Value Example Sql Handle. The connected SQL Handle to an Oracle database. String. Command string used to invoke a PL/SQL procedure.
bOK is TRUE if the function succeeds and FALSE if it fails.

If NOT SqlPLSQLCommand( hSql, 'INVOICES.INSERT_INVOICE (ninv_id, strClient, dt_inv_dt, nitem_No, nQnty, nAmt, nNum)' ) Set nSqlError = SqlError ( hSql! See ORACLE DOCUMENTATION ! for Error Listings
Note: If SqlPLSQLCommand receives an Invalid Object error from ORACLE when executing a stored procedure, this means that a table referenced by the procedure was modified. To fix this problem, you need to force a recompile of that procedure. SqlPlSQLCommand does not automatically do this.
SqlPrepare
Syntax Description bOk = SqlPrepare ( hSql, strSqlStatement ) Compiles a SQL statement for execution. Compiling includes: Checking theSyntax of the SQL statement. Checking the system catalog. Processing a SELECT statement's INTO clause. An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 255 INTO variables per SQL statement. Identifying bind variables in the SQL statement. Bind variables contain input data for the statement. You can specify up to 2558 bind variables per SQL statement.
Follow this function with a SqlOpen, SqlExecute, SalTblDoInserts, SalTblDoUpdates, or SalTblDoDeletes, or fetches. Parameters hSql strSqlStatement Return Value Sql Handle. A handle that identifies a database connection. String. The SQL statement to compile.
2-270
SqlPrepareAndExecute
See Also Example
SqlExecute
Call SqlPrepare ( hSqlPrimary, 'INSERT INTO CUSTOMER ' || ' ( CUSTOMER ) VALUES ' ||'( :frmCustomer.dfCustomer )' )
SqlPrepareAndExecute
Syntax Description bOk = SqlPrepareAndExecute ( hSql, strSqlStatement ) Compiles and executes a SQL statement. Compiling includes: Checking theSyntax of the SQL statement. Checking the system catalog. Processing a SELECT statement's INTO clause. An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 128 INTO variables per SQL statement. Identifying bind variables in the SQL statement. Bind variables contain input data for the statement. You can specify up to 128 bind variables per SQL statement. Sql Handle. A handle that identifies a database connection. String. The SQL statement to compile and execute.
Parameters
hSql strSqlStatement
bOk is TRUE if the function succeeds and FALSE if it fails. SqlExecute SqlPrepare
Set bOk = SqlPrepareAndExecute ( hSql, 'Select name from' || ' employees into :df1' ) If bOk Call SqlFetchNext ( hSql, nInd )
SqlPrepareSP
Syntax Description bOk = SqlPrepareSP (hSql, strStoredProc, strIntoList) This SAL function prepares a stored procedure invokation statement. It handles any input parameters passed to it by the caller. The function also handles output parameters, but the output parameters will not be updated after a successful execution. The values of the SAL variables specified for
2-271
Chapter 2
any output parameter are updated only after any result set generated by the stored procedure has been completely processed. If you are calling a Microsoft SQL Server stored procedure, be sure that front-end result sets have been disabled first. Parameters hSql strStoredProc Sql Handle. The sql handle on which the Stored Procedure should be executed. String. String variable which contains the stored procedure name and any optional input or output parameters. This string can either be in the ODBC calling syntax () or in the native database format. For ODBC syntax with SQL Server procedures that have no input parameters and no output parameters, you must drop the parentheses following the procedure name. A set of empty parentheses will cause a SQL error in this case. For example: {:myReturn = call sql4net61} strIntoList String String variable that contains the Into variables for any result set generated by the Stored Procedure. If the caller knows that the stored procedure does not generate any result set, this can be set to strNull. If passed, this should be a comma-separated list of variables and precede each variable name with a colon.
Return Value
bOk is TRUE if the function succeeds and FALSE if the prepare fails. Once the stored procedure has been prepared, it can be executed either by calling SqlExecute on the same Sql Handle or by calling SalTblPopulate.
Message Actions On SAM_Click ! ! Now time to prepare the statement... Set bOk = SqlPrepareSP (hSql, dfSQL, STRING_Null ) If bOk Set numInput = dfInteger Set bOk = SqlExecute ( hSql ) If bOk = FALSE Call SalMessageBox ( ' Stored Procedure execution failed', 'Bad', MB_Ok) Call SalDisableWindow( pbFetch)
Example
See Also
SqlCloseAllSPResultSets SqlGetNextSPResultSet
SqlRetrieve
2-272
SqlRollbackSession
Syntax Description
bOk = SqlRetrieve ( hSql, strName, strBindList, strIntoList ) Retrieves a SQLBase compiled command. To execute the command, you need only call SqlExecute. You do not need to compile the command with SqlPrepare because the command is compiled when it is stored with SqlStore.
Parameters
hSql strName strBindList
Sql Handle. A handle that identifies a database connection. String. The name of the compiled command. String. A comma-separated list of up to 128 SQLWindows bind variables. This list has the same number of variables as the compiled command. This string can be null. String. A comma-separated list of up to 128 SQLWindows INTO variables. This list has the same (or less) number of INTO variables as named in the SELECT list of the compiled command. This string can be null (''), and should be null if the next command being executed is SalListPopulate.
strIntoList
bOk is TRUE if the function succeeds and FALSE if it fails. SqlDropStoredCmd SqlStore
Call SqlRetrieve ( hSqlPrimary, 'PRODUCTS', ':nPrice', ':strLBItem' )
SqlRollbackSession
Syntax Description bOk = SqlRollbackSession ( hSession ) This call rolls back the current transaction associated with the specified session. The SQL operations currently active on all the statements belonging to this session get rolled back. Parameters Return Value Example
Message Actions On SAM_Click ! ! Rollback
hSession
Session Handle. The session handle used to commit the transaction.
bOk is TRUE if the transaction was rolled back successfully. If the call failed, it returns FALSE.
the transaction...
2-273
Chapter 2
Set bOk = SqlRollbackSession (hSession) If bOk Call SalMessageBox ( ' Rolled back!!', 'Good', MB_Ok) Else Call SalMessageBox ( ' Rollback failed ', 'Bad', MB_Ok)
See Also
SqlCommitSession SqlCreateSession SqlCreateStatement SqlGetSessionHandle
SqlSetInMessage
Syntax Description bOk = SqlSetInMessage ( hSql, nSize ) Sets the size (in bytes) of the input message buffer for the specified Sql Handle. The input message buffer holds input for the application (such as the result of a query). There is one input message buffer per connected Sql Handle on the client computer. The database server (or gateway) maintains one input message buffer that is the size of the largest input message buffer on the client computer. When fetching data, as many rows as possible are compacted into one input message buffer. Each FETCH reads the next row from the input message buffer until they are exhausted. At this point, if you are accessing a SQLBase database, SQLBase transparently fetches the next input buffer of rows depending on the isolation level. A large input message buffer can improve performance because it reduces the number of network messages between the client and server. A large input message buffer can have a negative impact on concurrency, however, because any row currently in the buffer can have a shared lock on it (depending on the isolation level) which prevents other users from changing that row. Parameters hSql nSize Sql Handle. A handle that identifies a database connection. Number. The size (in bytes) of the input message buffer that you want to set. The default is 1 Kbyte and the maximum is 32 Kbtyes.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlSetOutMessage

On SAM_AppStartup Call SqlConnect ( hSqlPrimary ) Call SqlSetInMessage ( hSqlPrimary, 10000 )
2-274
SqlSetIsolationLevel
SqlSetIsolationLevel
Syntax Description bOk = SqlSetIsolationLevel ( hSql, strIsolation ) Sets SQLBase's isolation level for all the application's cursors. Read Repeatability is the default setting for SQLWindows. Changing isolation levels causes an implicit commit of the database. The isolation level you set applies to all the Sql Handles for that user name that the application connects to the database. Parameters hSql strIsolation Sql Handle. A handle that identifies a database connection. String. The isolation level to set. Specify one of these values: CS RL RO RR Return Value Example Cursor Stability Release Locks Read Only Read Repeatability

On SAM_AppStartup Call SqlSetIsolationLevel ( hSqlPrimary, 'RL' )
SqlSetLockTimeout
Syntax Description Parameters bOk = SqlSetLockTimeout ( hSql, nTimeout ) Specifies the maximum time to wait to acquire a lock. After the specified time elapses, a timeout occurs and the transaction rolls back. hSql nTimeout Sql Handle. A handle that identifies a database connection; the cursor on which you want to set a lock timeout value. Number. The timeout period in seconds. Valid values include 1 (wait forever), 0 (never wait), and values up to and including 1800 (30 minutes). The default is 300.

On SAM_AppStartup Call SqlSetLockTimeout ( hSqlPrimary, 10 )
SqlSetLongBindDatatype
Syntax bOk = SqlSetLongBindDatatype( nBindVarNumber, nDatatype )
2-275
Chapter 2
Description
Sets the type of column (text or binary) that a Long String binds to. By default, SQLWindows binds Long Strings to text columns. However, when you write or update a long binary column, call SqlSetLongBindDatatype and set the nDatatype parameter to binary (value = 23). Later you can set the type back to text by calling this function and setting nDatatype to text (value = 22). Value = 24 is for Informix and Ingres specific routers. Call this function before executing the SQL statement (implicitly or explicitly) because SQLWindows compiles bind variables at execute time. Use this function until Gupta Technologies LLC implements a native SAL binary long data type.
Parameters
nBindVarNumber nDatatype
Number. The bind variable to set. The first bind variable in the SQL statement is 1, the second is 2, and so on. Number. The data type: 22 = text 23 = binary 24 = char \ long varchar > 254
bOk is TRUE if this function succeeds and FALSE if it fails.

Call SqlSetLongBindDatatype( 1, DT_Binary )
SqlSetOutMessage
Syntax Description bOk = SqlSetOutMessage ( hSql, nSize ) Sets the size (in bytes) of the output message buffer for a specified Sql Handle. The output message buffer holds output from the application (such as a SQL command to compile or rows of data to insert into a database). There is an output message buffer for each connected Sql Handle on the client computer. At the same time, the database server (or gateway) maintains an output message buffer that is the size of the largest of its clients' output message buffers. A large output message buffer does not necessarily improve performance because the buffer only needs to be large enough to hold the largest SQL command to compile or the largest row of data to insert. (Rows are always sent to the database and inserted individually.) A large output message buffer can allocate space unnecessarily on both the client and the server, and it does not reduce network traffic. Parameters hSql nSize Sql Handle. A handle that identifies a database connection. Number. The size (in bytes) of the output message buffer. The default is 1 Kbyte and the maximum is 32 Kbytes.
2-276
SqlSetParameter
bOk is TRUE if the function succeeds and FALSE if it fails. SqlSetInMessage

On SAM_AppStartup Call SqlConnect ( hSqlPrimary ) Call SqlSetOutMessage ( hSqlPrimary, 1500 )
SqlSetParameter
Syntax Description bOk = SqlSetParameter ( hSql, nParameter, nNumber, strString ) Sets the value of a database parameter. Use the number (nNumber) and string (strString) arguments as appropriate for the data type of the parameter. When using a connection to database servers other than SQLBase you cannot manipulate parameters that are specific to those databases with SqlSetParameter. You must use SqlSetParameterAll instead. Parameters hSql nParameter nNumber Sql Handle. A handle that identifies a database connection. Number. The database parameter to set. Specify one of the DBP_* constants. Number. The value to assign to nParameter. Specify TRUE or FALSE for all but DBP_LOCKWAITTIMEOUT, for which you must specify a value in seconds. String. The value to assign to nParameter.
strString Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameter SqlGetParameterAll SqlSetParameterAll
Call SqlSetParameter ( hSqlPrimary, DBP_PRESERVE, TRUE, strNull )
Example
SqlSetParameterAll
Syntax Description bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber ) Sets the value of a database parameter identified by a SQLP* constant value defined in SQL.H. This function uses the number (nNumber) and string (strString) parameters as appropriate depending on the data type of the value of the parameter. hSql Sql Handle. The handle that identifies a database connection.
Parameters
2-277
Chapter 2
nParameter nNumber strString bNumber Return Value See Also
Number. The database parameter to set. Specify the value of one of the SQLP* constants defined in SQL.H. Number. The value to assign to nParameter if it is a number. String. The value to assign to nParameter if it is a string. If TRUE, the parameter value is in nNumber. If FALSE, the parameter value is in strString.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameter SqlGetParameterAll SqlSetParameter
Set bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )
Example
SqlSetResultSet
Syntax Description bOk = SqlSetResultSet ( hSql, bSet ) Turns result set mode on or off. Result set mode is on by default in SQLWindows. If you are using an OLE DB connection to SQL Server, and you are executing a stored procedure that returns a result set, do not call this function with bSet=TRUE. SQL Server does not support scrollable result sets for stored procedures. Parameters hSql bSet Return Value Example Sql Handle. A handle that identifies a database connection. Boolean. Turns result set mode on (TRUE) or off (FALSE).

Call SqlSetResultSet ( hSqlPrimary, FALSE )
SqlSetSessionParameter
Syntax Description bOk = SqlSetSessionParameter ( hSession, numPropertyID, numValue, strValue ) This function sets the value of the specified session property. It takes as input the session handle and the property ID. This function will know the data type of the specified property ID and will accordingly use either the number value or the string value. Parameters hSession Session Handle. The Session handle.
2-278
SqlStore
numPropertyID numValue strValue Return Value Example
Number. The property ID. Number. The number value of the property ID. String. The string value of the property ID.
bOk is TRUE if successful. It will return FALSE if it failed.
Pushbutton: pbSetParam Message Actions On SAM_Click Set bOk = SqlSetSessionParameter( hSession, dfPropID, dfIntValue, dfStrValue) If bOk = FALSE Call SalMessageBox ( 'SetSessionParam failed', 'Error!', MB_Ok ) Else Call SalMessageBox ( 'SetSessionParam done', 'Done!', MB_Ok )
See Also
SqlGetSessionParameter
SqlStore
Syntax Description bOk = SqlStore ( hSql, strName, strSqlCommand ) Stores and names a SQLBase compiled SQL statement. You do not need to call SqlPrepare before calling SqlStore. SqlStore compiles the SQL statement. You can specify up to 128 bind variables. Use numeric bind variables in the SQL statement, not variable names. For example: "SELECT * FROM PRESIDENT WHERE LASTNAME = :1 AND AGE > :2;". When you retrieve the stored command with SqlRetrieve, you specify the bind variable names in the INTO clause. For example, specify :dfLastName and :dfAge where dfLastName and dfAge are data fields on a form window. Before SQLWindows performs a SQL execute or fetch operation, it compiles the bind and into variables which is looking up the symbols and generating the code that gets the values (for bind variables) or that fetches the values (for an into variable). By default, SQLWindows compiles: Bind variables at execute time Into variables at fetch time
You can change this default behavior by calling SqlVarSetup which saves the current execution context. When you execute or fetch later, SQLWindows uses that execution context to resolve references to bind variables and into variables. This means that you
2-279
Chapter 2
can use bind and into variables in a different context than where you call Sql* functions. You must call SqlPrepare for the Sql Handle before you call SqlVarSetup. Use this function to write: Global functions that store bind and into variables in local variables A hierarchy of classes where a base class can prepare and fetch and a derived class can specify the into variables
This function does not affect the lifetime of the bind and into variables and does not guarantee that the variables will exist when you execute or fetch. You must ensure that the variables are still valid when you use them. Parameters hSql strName strSqlCommand Return Value See Also Example Sql Handle. A handle that identifies a database connection. String. The name of the stored command. String. The SQL statement to compile and store.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlDropStoredCmd SqlRetrieve
Set bOk = SqlStore (hSql, strName, strSqlCommand)
SqlVarSetup
Syntax Description nOk = SqlVarSetup (hSql) Before SQLWindows performs a SQL execute or fetch operation, it compiles the bind and into variables which is looking up the symbols and generating the code that gets the values (for bind variables) or that fetches the values (for an into variable). By default, SQLWindows compiles: Bind variables at execute time Into variables at fetch time
You can change this default behavior by calling SqlVarSetup which saves the current execution context. When you execute or fetch later, SQLWindows uses that execution context to resolve references to bind variables and into variables. This means that you can use bind and into variables in a different context than where you call Sql*functions. You must call SqlPrepare for the Sql Handle before you call SqlVarSetup. The saved context persists until your application complies another SQL statement (such as another call to SqlPrepare.) Thus the saved context can be used to execute a statement multiple times, so long as no other statement is compiled in the interim.
2-280
SqlVarSetup
The context applies to variables of top-level windows. Variables declared in child table windows and variables declared in functions do not work with SqlVarSetup. Use this function to write: Global functions that store bind and into variables in local variables A hierarchy of classes where a base class can prepare and fetch and a derived class can specify the into variables
This function does not effect the lifetime of the bind and into variables and does not guarantee that the variables will exist when you execute or fetch. You must ensure that the variables are still valid when you use them. Parameters Return Value hSql Sql Handle. A handle that identifies a database connection..
2-281
Chapter 2
2-282
Index
A
array functions 1-4
window management 1-38 XML 1-41
B
background text functions 1-19
L
list and combo box functions 1-17
C
color and font functions 1-4 Conventions used in the manual 1-4 data type conversion functions 1-3, 1-4, 1-7 date functions 1-7 debugging functions 1-8 dialog box functions 1-9 drag drop functions 1-11
M
Manipulating background text functions 1-5 Manual description of 1-4 MDI functions 1-19 message functions 1-19 miscellaneous functions 1-20
N
number functions 1-24
E
edit functions 1-12
O
obsolete functions 1-42
F
file management functions 1-13 format and validation functions 1-15 functions array 1-4 data type conversion 1-3, 1-4, 1-7 date 1-7 DDE 1-8 debugging 1-8 dialog box 1-9 drag drop 1-11 edit 1-12 file management 1-13 format and validation 1-15 list and combo box 1-17 manipulating background text 1-5 MDI 1-19 message 1-19 miscellaneous 1-20 number 1-24 OLE DB Consumer 1-26 picture 1-27 prints 1-28 reports 1-29 scroll bar 1-30 SQL 1-30 string conversion 1-33 table window 1-34
P
pause 2-127 picture functions 1-27 print functions 1-28
S
SalAbort 2-2 SalActiveXAutoErrorMode 2-2 SalAppDisable 2-2 SalAppEnable 2-9 SalAppFind 2-10 SalArrayAvg 2-12 SalArrayDimCount 2-12 SalArrayGetLowerBound 2-13 SalArrayGetUpperBound 2-13 SalArrayIsEmpty 2-14 SalArrayMax 2-14 SalArrayMin 2-15 SalArraySetUpperBound 2-15 SalArraySum 2-16 SalBringWindowToTop 2-16 SalCenterWindow 2-17 SalClearField 2-17 SalColorFromRGB 2-17 SalColorGet 2-18 SalColorGetSysColor 2-19 SalColorSet 2-19 SalColorToRGB 2-20
Index-1
Index
SalCompileAndEvaluate 2-21 SalContextCurrent 2-22 SalCreateWindow 2-23 SalCreateWindowExWithParms 2-24 SalCursorClear 2-26 SalCursorSet 2-26 SalCursorSetFile 2-27 SalCursorSetString 2-28 SalDateConstruct 2-28 SalDateCurrent 2-30 SalDateDay 2-30 SalDateHour 2-30 SalDateMinute 2-30 SalDateMonth 2-31 SalDateMonthBegin 2-31 SalDateQuarter 2-32 SalDateQuarterBegin 2-32 SalDateSecond 2-32 SalDateToStr 2-33 SalDateWeekBegin 2-33 SalDateWeekday 2-33 SalDateYear 2-34 SalDDEStopServer 2-34 SalDDEStopSession 2-34 SalDestroyWindow 2-34 SalDisableWindow 2-34 SalDisableWindowAndLabel 2-35 SalDlgChooseColor 2-36 SalDlgChooseFont 2-36 SalDlgGetDockStatus 2-37 SalDlgOpenFile 2-37 SalDlgSaveFile 2-39 SalDlgSetDockStatus 2-40 SalDragDropDisableDrop 2-41 SalDragDropEnableDrop 2-41 SalDragDropGetSource 2-42 SalDragDropGetTarget 2-42 SalDragDropStart 2-43 SalDragDropStop 2-43 SalDrawMenuBar 2-43 SalDropFilesAcceptFiles 2-44 SalDropFilesQueryFiles 2-44 SalDropFilesQueryPoint 2-46 SalEditCanCopyTo 2-46 SalEditCanCut 2-47 SalEditCanPaste 2-47 SalEditCanPasteFrom 2-47 SalEditCanUndo 2-48
SalEditClear 2-48 SalEditCopy 2-48 SalEditCopyString 2-49 SalEditCopyTo 2-49 SalEditCut 2-49 SalEditPaste 2-50 SalEditPasteFrom 2-50 SalEditPasteString 2-51 SalEditUndo 2-51 SalEnableWindow 2-51 SalEnableWindowAndLabel 2-52 SalEndDialog 2-52 SalEndTrace 2-53 SalEventLogSetName 2-53 SalFileClose 2-53 SalFileCopy 2-54 SalFileCreateDirectory 2-55 SalFileGetC 2-55 SalFileGetChar 2-55 SalFileGetCurrentDirectory 2-56 SalFileGetDateTime 2-56 SalFileGetDrive 2-57 SalFileGetStr 2-57 SalFileOpen 2-58 SalFileOpenExt 2-58 SalFilePutC 2-59 SalFilePutChar 2-59 SalFilePutStr 2-60 SalFileRead 2-60 SalFileRemoveDirectory 2-61 SalFileSeek 2-61 SalFileSetCurrentDirectory 2-62 SalFileSetDateTime 2-62 SalFileSetDrive 2-62 SalFileTell 2-63 SalFileWrite 2-63 SalFmtFieldToStr 2-63 SalFmtFormatDateTime 2-64 SalFmtFormatNumber 2-65 SalFmtGetFormat 2-65, 2-66 SalFmtGetInputMask 2-66 SalFmtGetPicture 2-66 SalFmtIsValidField 2-67 SalFmtIsValidInputMask 2-67 SalFmtIsValidPicture 2-68 SalFmtKeepMask 2-69 SalFmtSetFormat 2-70 SalFmtSetInputMask 2-70
Index-2 SQLWindows Function Reference
SalFmtSetPicture 2-71 SalFmtStrToField 2-71 SalFmtUnmaskInput 2-73 SalFmtValidateField 2-73 SalFontGet 2-74 SalFontGetNames 2-74 SalFontGetSizes 2-75 SalFontSet 2-75 SalFormGetParmNum 2-76 SalFormUnitsToPixels 2-76 SalGetDataType 2-77 SalGetDefButton 2-77 SalGetFirstChild 2-78 SalGetFocus 2-78 SalGetItemName 2-78 SalGetMaxDataLength 2-79 SalGetNextChild 2-79 SalGetProfileInt 2-80 SalGetProfileString 2-80 SalGetType 2-81 SalGetVersion 2-82 SalGetWindowLabel 2-83 SalGetWindowLabelText 2-82, 2-84 SalGetWindowLoc 2-82 SalGetWindowSize 2-83 SalGetWindowState 2-83 SalGetWindowText 2-84 SalHideWindow 2-85 SalHideWindowAndLabel 2-86 SalHStringToNumber 2-86 SalInvalidateWindow 2-88 SalIsButtonChecked 2-88 SalIsNull 2-88 SalIsValidDateTime 2-88 SalIsValidDecimal 2-89 SalIsValidInteger 2-90 SalIsValidNumber 2-90 SalIsWindowEnabled 2-91 SalIsWindowVisible 2-91 SalListAdd 2-91 SalListClear 2-92 SalListDelete 2-92 SalListFiles 2-92 SalListGetMultiSelect 2-93 SalListInsert 2-93 SalListPopulate 2-94 SalListQueryCount 2-94 SalListQueryFile 2-95
SalListQueryMultiCount 2-95 SalListQuerySelection 2-95 SalListQueryState 2-96 SalListQueryText 2-96 SalListQueryTextLength 2-97 SalListQueryTextX 2-96, 2-97 SalListRedraw 2-97 SalListSelectString 2-98 SalListSetMultiSelect 2-98 SalListSetSelect 2-99 SalListSetTabs 2-99 SalLoadApp 2-100 SalLoadAppAndProcessMsgs 2-101 SalLoadAppAndWait 2-100 SalMapEnterToTab 2-102 SalMDIArrangeIcons 2-103 SalMDICascade 2-103 SalMDITile 2-103 SalMessageBeep 2-104 SalMessageBox 2-104 SalModalDialog 2-106 SalModalDialogFromStr 2-107 SalMoveWindow 2-107 SalMTSCreateInstance 2-108 SalMTSDisableCommit 2-108 SalMTSEnableCommit 2-109 SalMTSGetObjectContext 2-109 SalMTSInTransaction 2-110 SalMTSIsCallerInRoll 2-109 SalMTSSecurityEnabled 2-110 SalMTSSetAbort 2-111 SalMTSSetComplete 2-111 SalNumberAbs 2-112 SalNumberArcCos 2-112 SalNumberArcSin 2-112 SalNumberArcTan 2-113 SalNumberArcTan2 2-113 SalNumberCos 2-113 SalNumberCosH 2-114 SalNumberExponent 2-114 SalNumberHigh 2-114 SalNumberHypot 2-115 SalNumberLog 2-115 SalNumberLogBase10 2-115 SalNumberLow 2-116 SalNumberMax 2-116 SalNumberMin 2-116 SalNumberMod 2-117
Index-3
Index
SalNumberPi 2-117 SalNumberPower 2-117 SalNumberRandInit 2-118 SalNumberRandom 2-118 SalNumberRound 2-119 SalNumberSin 2-119 SalNumberSinH 2-119 SalNumberSqrt 2-120 SalNumberTan 2-120 SalNumberTanH 2-120 SalNumberToChar 2-121 SalNumberToHString 2-121 SalNumberToStr 2-121 SalNumberToStrX 2-122 SalNumberToWindowHandle 2-122 SalNumberTruncate 2-123 SalObjCreateFromString 2-124 SalObjGetType 2-124 SalObjIsDerived 2-125 SalObjIsNull 2-126 SalObjIsValidClassName 2-126 SalParentWindow 2-127 SalPause 2-127 SalPicClear 2-128, 2-129 SalPicGetDescription 2-128 SalPicGetString 2-130 SalPicSet 2-130 SalPicSetFile 2-131 SalPicSetFit 2-131 SalPicSetString 2-133 SalPixelsToFormUnits 2-134 SalPostMsg 2-135 SalPrtExtractRect 2-135 SalPrtGetDefault 2-136 SalPrtGetParmNum 2-136 SalPrtPrintForm 2-136 SalPrtSetDefault 2-137 SalPrtSetParmDefaults 2-137 SalPrtSetParmNum 2-138 SalPrtSetup 2-138 SalQueryFieldEdit 2-139 SalQuit 2-139 SalReportClose 2-140 SalReportCmd 2-140 SalReportCreate 2-140 SalReportDlgOptions 2-141 SalReportGetDateTimeVar 2-142 SalReportGetFileInfo 2-142
SalReportGetNumberVar 2-143 SalReportGetObjectVar 2-143 SalReportGetPrinterSettings 2-143 SalReportGetPrinterTray 2-145 SalReportGetStringVar 2-146 SalReportPrint 2-146 SalReportPrintToFile 2-148 SalReportReset 2-149 SalReportResetPages 2-150 SalReportSetDateTimeVar 2-150 SalReportSetNumberVar 2-151 SalReportSetObjectVar 2-151 SalReportSetPrinterSettings 2-152 SalReportSetPrinterTray 2-153 SalReportSetStringVar 2-154 SalReportTableCreate 2-155 SalReportTablePrint 2-155 SalReportTableView 2-156 SalReportView 2-157 SalScrollGetPos 2-159 SalScrollGetRange 2-159 SalScrollSetPos 2-160 SalScrollSetRange 2-160 SalSendClassMessage 2-161 SalSendClassMessageNamed 2-161 SalSendMsg 2-162 SalSendMsgToChildren 2-162 SalSendValidateMsg 2-163 SalSetDefButton 2-163 SalSetFieldEdit 2-164 SalSetFocus 2-165 SalSetMaxDataLength 2-165 SalSetProfileString 2-166 SalSetWindowLabelText 2-166 SalSetWindowLoc 2-167 SalSetWindowSize 2-167 SalSetWindowText 2-167 SalShowWindow 2-168 SalShowWindowAndLabel 2-168 SalStartTrace 2-169 SalStatusGetText 2-170 SalStatusSetText 2-170 SalStatusSetVisible 2-171 SalStrCompress 2-171 SalStrFirstC 2-171 SalStrGetBufferLength 2-172 SalStrIsValidCurrency 2-173 SalStrIsValidDateTime 2-173
SalStrIsValidNumber 2-173 SalStrLeft 2-174 SalStrLeftX 2-174 SalStrLength 2-175 SalStrLop 2-175 SalStrLower 2-176 SalStrMid 2-176 SalStrProper 2-178 SalStrRepeat 2-178 SalStrRepeatX 2-178 SalStrReplace 2-179 SalStrReplaceX 2-179 SalStrRight 2-179 SalStrRightX 2-179 SalStrScan 2-180 SalStrSetBufferLength 2-181 SalStrToDate 2-182 SalStrTokenize 2-182 SalStrToNumber 2-183 SalStrTrim 2-183 SalStrTrimX 2-183 SalStrUncompress 2-184 SalStrUpper 2-184 SalStrUpperX 2-185 SalTBarSetVisible 2-185 SalTblAnyRows 2-185 SalTblClearSelection 2-186 SalTblColumnAverage 2-186 SalTblColumnSum 2-188 SalTblCopyRows 2-188 SalTblCreateColumn 2-189 SalTblDefineCheckBoxColumn 2-190 SalTblDefineDropDownListColumn 2-191 SalTblDefinePopupEditColumn 2-191 SalTblDefineRowHeader 2-192 SalTblDefineSplitWindow 2-193 SalTblDeleteRow 2-193 SalTblDeleteSelected 2-193 SalTblDestroyColumns 2-194 SalTblDoDeletes 2-194 SalTblDoInserts 2-195 SalTblDoUpdates 2-196 SalTblFetchRow 2-196 SalTblFindNextRow 2-197 SalTblFindPrevRow 2-198 SalTblGetColumnText 2-199 SalTblGetColumnTitle 2-199 SalTblGetColumnWindow 2-199
SalTblInsertRow 2-200 SalTblKillEdit 2-200 SalTblKillFocus 2-201 SalTblPasteRows 2-202 SalTblPopulate 2-202 SalTblQueryCheckBoxColumn 2-205 SalTblQueryColumnCellType 2-205 SalTblQueryColumnFlags 2-206 SalTblQueryColumnID 2-206 SalTblQueryColumnPos 2-206 SalTblQueryColumnWidth 2-207 SalTblQueryContext 2-207 SalTblQueryDropDownListColumn 2-207 SalTblQueryFocus 2-208 SalTblQueryLinesPerRow 2-209 SalTblQueryLockedColumns 2-209 SalTblQueryPopupEditColumn 2-209 SalTblQueryRowFlags 2-210 SalTblQueryRowHeader 2-210 SalTblQueryScroll 2-211 SalTblQuerySplitWindow 2-211 SalTblQueryTableFlags 2-212 SalTblQueryVisibleRange 2-212 SalTblReset 2-212 SalTblScroll 2-213 SalTblSetCellTextColor 2-213 SalTblSetColumnFlags 2-215 SalTblSetColumnPos 2-215 SalTblSetColumnText 2-215 SalTblSetColumnTitle 2-216 SalTblSetColumnWidth 2-216 SalTblSetContext 2-217 SalTblSetFlagsAnyRows 2-217 SalTblSetFocusCell 2-218 SalTblSetFocusRow 2-219 SalTblSetLinesPerRow 2-219 SalTblSetLockedColumns 2-220 SalTblSetRange 2-220 SalTblSetRow 2-221 SalTblSetRowFlags 2-221 SalTblSetTableFlags 2-222 SalTblSortRows 2-223 SalTimerKill 2-225 SalTimerSet 2-225 SalTrace 2-226 SalTrackPopupMenu 2-226 SalUpdateWindow 2-227 SalUseRegistry 2-228
Index-5
Index
SalValidateSet 2-229 SalWaitCursor 2-230 SalWindowClassName 2-230 SalWindowGetDockSettings 2-230 SalWindowGetProperty 2-231 SalWindowHandleToNumber 2-232 SalWindowIsDerivedFromClass 2-232 SalWinHelp 2-232 SalXMLDeserializeUDV 2-233 SalXMLGetLastError 2-234 SalXMLSerializeUDV 2-234 SalYieldEnable 2-235 SalYieldQueryState 2-236 SalYieldStartMessages 2-236 SalYieldStopMessages 2-237 scroll bar functions 1-30 SQL functions 1-30 SQLBase API 2-253 SqlClearImmediate 2-237 SqlClose 2-237 SqlCloseAllSPResultSets 2-238 SqlCommit 2-239 SqlCommitSession 2-239 SqlConnect 2-240 SqlContextClear 2-241 SqlContextSet 2-241 SqlContextSetToForm 2-242 SqlCreateSession 2-242 SqlCreateStatement 2-244 SqlDirectoryByName 2-245 SqlDisconnect 2-245 SqlDropStoredCmd 2-246 SqlError 2-246 SqlErrorText 2-246 SqlExecute 2-247 SqlExecutionPlan 2-248 SqlExists 2-248 SqlExtractArgs 2-249 SqlFetchNext 2-249 SqlFetchPrevious 2-250 SqlFetchRow 2-250 SqlFreeSession 2-251 SqlGetCmdOrRowsetPtr 2-251 SqlGetCursor 2-253 SqlGetDSOrSessionPtr 2-253 SqlGetError 2-254 SqlGetErrorPosition 2-254 SqlGetErrorText 2-255
SqlGetErrorTextX 2-256 SqlGetLastStatement 2-256 SqlGetModifiedRows 2-256 SqlGetNextSPResultSet 2-257 SqlGetParameter 2-258 SqlGetParameterAll 2-258 SqlGetResultSetCount 2-259 SqlGetRollbackFlag 2-260 SqlGetSessionErrorInfo 2-260 SqlGetSessionHandle 2-261 SqlGetSessionProperty 2-262 SqlGetStatementErrorInfo 2-263 SqlImmediate 2-263 SqlImmediateContext 2-264 SqlOpen 2-265 SqlPLSQLCommand 2-268 SqlPrepare 2-270 SqlPrepareAndExecute 2-271 SqlPrepareSP 2-271 SqlRetrieve 2-272 SqlRollbackSession 2-273 SqlSetInMessage 2-274 SqlSetIsolationLevel 2-275 SqlSetLockTimeout 2-275 SqlSetLongBindDatatype 2-275 SqlSetOutMessage 2-276 SqlSetParameter 2-277 SqlSetParameterAll 2-277 SqlSetResultSet 2-278 SqlSetSessionProperty 2-278 SqlStore 2-279 SQLWindows function categories 1-2 SQLWindows functions 1-1, 2-1 string conversion functions 1-33 system functions obsolete 1-42
T
table window functions 1-34
V
Visual Toolchest 1-2
W
window management functions 1-38

Gupta Sqlwindows Function Reference

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Gupta Sqlwindows Function Reference

Încărcat de

Drepturi de autor:

Formate disponibile

GUPTA SQLWindows Function Reference

SQLWindows/32 Function Reference

SQLWindows/32 Function Reference

What is in this manual

SQLWindows/32 Function Reference

Other helpful resources

Send comments to...

SQLWindows/32 Function Reference

SQLWindows Function Reference

SQLWindows Function Tables

SQLWindows Function Reference

SQLWindows Function Tables

SQLWindows function categories

SQLWindows Function Reference

SQLWindows function categories

ActiveX Client Functions

SalActiveXClose SalActiveXCreate SalActiveXCreateFromData SalActiveXCreateFromFile SalActiveXDelete SalActiveXDoVerb SalActiveXGetActiveObject

SQLWindows Function Reference

SQLWindows Function Tables

Anonymous Block Functions

SQLWindows Function Reference

SQLWindows function categories

Background Text Functions

SalGetWindowLabelText SalHideWindowAndLabel SalSetWindowLabelText SalShowWindowAndLabel

SQLWindows Function Reference

SQLWindows Function Tables

Color and Font Functions

SQLWindows Function Reference

SQLWindows function categories

Data Type Conversion Functions

SQLWindows Function Reference

SQLWindows Function Tables

Function Name SalDateWeekBegin SalDateWeekday SalDateYea SalDateYearBegin

SQLWindows Function Reference

SQLWindows function categories

Dialog Box Functions

DOS Management Functions

VisDosEnumDirInfo VisDosEnumDirs VisDosEnumDrives

SQLWindows Function Reference

SQLWindows Function Tables

Function Name VisDosEnumFiles VisDosEnumNetConnections VisDosEnumPath VisDosEnumsShortDirInfo

SQLWindows Function Reference

SQLWindows function categories

Function Name VisDosMakeAllDir VisDosMakePath VisDosNetConnect VisDosNetDisconnect VisDosSetFlags VisDosSetVolumeLabel VisDosSplitPath

Drag Drop Functions

SalDragDropGetTarget SalDragDropStart SalDragDropStop SalDropFilesAcceptFiles SalDropFilesQueryFiles SalDropFilesQueryPoint

SQLWindows Function Reference

SQLWindows Function Tables

SalEditCanPasteFrom SalEditCanUndo SalEditClear

SalEditCopyString SalEditCopyTo SalEditCut

SQLWindows Function Reference

SQLWindows function categories

Function Name SalEditPasteFrom SalEditPasteString SalEditUndo VisWinClearAllFields

File Management Functions

SQLWindows Function Reference

SQLWindows Function Tables

SQLWindows Function Reference

SQLWindows function categories

Function Name VisFileSetDateTime VisFileTell VisFileWrite VisFileWriteString

Format and Validation Functions

SalFmtFormatDateTime SalFmtFormatNumber SalFmtGetFormat SalFmtGetInputMask SalFmtGetPicture SalFmtIsValidField SalFmtIsValidInputMask SalFmtIsValidPicture SalFmtKeepMask

SQLWindows Function Reference