funcref

GUPTA SQLWindowsFunction Reference20-6202-0003

TrademarksGUPTA, 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.

CopyrightCopyright © 1998 - 2005 by Gupta Technologies LLC. All rights reserved.GUPTA SQLWindows Function Reference20-6202-0003March 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...

SQLWindows/32 Function Reference -3

Preface

AudienceThis manual is an advanced guide for programmers creating complex and sophisticated applications using SQLWindows.

What is in this manualThis manual is included with the Gupta Team Developer documentation set. This manual contains the following chapters:

Chapter 1: SQLWindows Function TablesThis chapter identifies function categories, provides a brief description of each category, and lists the functions in each category.

Chapter 2: SQLWindows FunctionsThis 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 conventionsBefore you start using this manual, it is important to understand the typographical conventions we use in this manual:

Note: We use this Note: convention to call your attention to special information.

Formatting Convention Type of Information

bold type Menu items, push buttons, and field names. Things that you select. Keyboard keys that you press.

italic type 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 fol-lowed by a space and then the name of a directory.

courier type Commands or code you must enter through the keyboard exactly as shown.

-4 SQLWindows/32 Function Reference

Other helpful resourcesGUPTA 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 Technologies’s World Wide Web site contains information about Gupta Technologies LLC’s 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 GUPTA’s 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 DepartmentGupta Technologies LLC975 Island DriveRedwood Shores, CA 94065USA

or send email, with comments or suggestions to:

[email protected]

SQLWindows/32 Function Reference -5

SQLWindows Function Reference

Chapter 1

SQLWindows Function Tables

The chapter contains functions tables that are arranged by type.

SQLWindows Function Reference 1-1

Chapter 1 SQLWindows Function Tables

SQLWindows function categoriesSQLWindows functions are divided into categories. This section identifies and briefly describes each category in addition to listing the functions in each one.

ActiveX client functionsAnonymous block functionsArray functionsColor and font functionsData type conversion functionsDate functionsDebugging functionsDialog box functionsDOS management functionsDrag-drop functionsEdit functionsFile management functionsFormat and validation functionsList and combo box functionsManipulating background text functionsMDI (Multiple Document Interface) functionsMessage functionsMiscellaneous functionsMTS functionsNumber functionsOLE DB Consumer functionsPicture functionsPrint functionsReport functionsScroll bar functionsSQL functionsString conversion functionsTable window functionsWindow management functionsXML 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 SQLWindows Function Reference

SQLWindows function categories

ActiveX Client FunctionsYou can programmatically manipulate an ActiveX container control and its contents at runtime using these functions.

Function Name Description

SalActiveXAutoErrorMode Turn off automatic error handling (on by default) by calling this function and specifying FALSE.

SalActiveXClose Closes an object and ends the connection to the application that provided the object.

SalActiveXCreate Creates an object given its class descriptor (progID).

SalActiveXCreateFromData Recreates an object from binary storage data, in the form of a string.

SalActiveXCreateFromFile Creates an instance of an ActiveX object.

SalActiveXDelete Deletes an instance of an ActiveX object.

SalActiveXDoVerb Opens an object for an operation such as editing.

SalActiveXGetActiveObject Gets an instance of an ActiveX object when the server application is already up and running.

SalActiveXGetData Gets the storage (state and data) associated with the object as a raw blob of bytes.

SalActiveXGetFileName Gets the file name of an ActiveX object that was inserted into a window using the SalActiveXInsertObjectDialog function and the “Create from File” option.

SalActiveXGetObject Gives access to the automation dispatch interface of the object in the specified container.

SalActiveXGetProgID Gets the ProgID of an ActiveX object that was inserted into a window using the SalActiveXInsertObjectDialog function and the “Create from File” option.

SalActiveXInsertObjectDialog Displays the standard Insert Object dialog.

SalActiveXOLEType Returns the status of the object in an ActiveX container control.



Anonymous Block FunctionsThese functions have been introduced to provide support for anonymous PL/SQL blocks without changing the behavior of existing features.

Array FunctionsThese functions manage arrays and compute values.


SqlOraPLSQLPrepare Compiles the anonymous PL/SQL block. Resembles the regular SqlPrepare function, but the underlying code is meant specifically for handling Oracle PL/SQL blocks.

SqlOraPLSQLExecute Executes the anonymous PL/SQL block that was prepared using SqlOraPLSQLPrepare.

SqlOraPLSQLStringBindType Informs the Oracle router the specific type of the STRING array bind variable that is being used in the prepared anonymous PL/SQL block.


SalArrayAvg Gets the average of values in an array of numbers

SalArrayDimCount Gets the number of dimensions in nValue.

SalArrayGetLowerBound Gets the lower bound of an array.

SalArrayGetUpperBound Gets the upper bound of an array.

SalArrayIsEmpty Determines if a dynamic array contains any data.

SalArrayMax Gets the maximum value in an array of numbers.

SalArrayMin Gets the minimum value in an array of numbers.

SalArraySetUpperBound Sets the upper bound of an array.

SalArraySum Computes the sum of an array's elements.

VisArrayAppend Appends one array onto the end of another array.



Background Text FunctionsThese functions manipulate background text.

VisArrayCopy Copies one array into another.

VisArrayDeleteItem Deletes an item from an array.

VisArrayFillDateTime Fills a Date/Time array with a specified date/time value.

VisArrayFillNumber Fills a number array with a specified value.

VisArrayFillString Fills a string array with a specified string.

VisArrayFindDateTime Locates a date/time value within an array.

VisArrayFindNumber Locates a number within an array.

VisArrayFindString Locates a string within an array.

VisArrayInsertItem Inserts an item into an array.

VisArraySort Sorts an array in either ascending or descending order.


SalDisableWindowAndLabel Disables mouse and keyboard input to a window, including disabling background text.

SalGetWindowLabelText Retrieves a window's background text.

SalHideWindowAndLabel Hides a window and its associated label.

SalSetWindowLabelText Sets a window's background text.

SalShowWindowAndLabel Shows a window and its associated label.




Color and Font FunctionsThese functions get and set window colors and fonts, as well as let you compose new colors.


SalColorFromRGB Composes a color from red, green, and blue values.

SalColorGet Gets a window's color.

SalColorGetSys Gets a system color.

SalColorSet Sets a window's color.

SalColorToRGB Decomposes a color into red, green, and blue values.

SalFontGet Gets a window's font name, size, and enhancements.

SalFontGetNames Gets the names of available screen fonts.

SalFontGetSizes Gets the available sizes for a particularfont.

SalFontSet Sets a window's font name, size, and enhancements.

VisFontEnum Gets the font names and types (printer, true type, etc.).

VisFontFree Frees a font loaded into memory with the VisFontLoad function.

VisFontGet Gets specifications of a font.

VisFontLoad Loads a font into memory.

VisTblSetRowColor Sets the text color for an entire row of a table window.

VisMenuInsertFont Inserts a menu item into a menu and displays it in the specified font.

VisMenuSetFont Displays a menu item in the specified font. VisMenuSetFont operates on SQLWindows menus or menus inserted with the Vis Library.



Data Type Conversion FunctionsThese functions manipulate string data by converting to and from other data types.

Date FunctionsThese functions manipulate date/time values.


SalFormUnitsToPixels Computes the number of pixels in the number of SQLWindows form units.

SalGetDataType Returns an object's data type.

SalGetItemName Gets the name of a form window or data field.

SalGetMaxDataLength Gets the maximum length of a data field, multiline field, or table window column.

SalHStringToNumber Converts a string to a number.

SalPixelsToFormUnits Computes the number of SQLWindows form units in the number of pixels.

SalSetMaxDataLength Sets the maximum length of a data field.


SalDateConstruct Constructs a date.

SalDateCurrent Gets the client's current date and time.

SalDateDay Gets the day portion of a date.

SalDateHour Gets the hour portion of a date.

SalDateMinute Gets the minute portion of a date.

SalDateMonth Gets the month portion of a date.

SalDateMonthBegin Gets the date of the first day of a month.

SalDateQuarter Gets the quarter of the year of a date.

SalDateQuarterBegin Gets the date of the first day of the quarter of a given date.

SalDateSecond Gets the seconds portion of the date.

SalDateToStr Converts a date value to a string value.



Debugging FunctionsThese functions help you debug your application.

SalDateWeekBegin Gets the date of the previous Monday.

SalDateWeekday Gets the day of the week as a number.

SalDateYea Gets the year portion of a date.

SalDateYearBegin Gets the date of the first day of the year of a given date.


SalCompileAndEvaluate Evaluates the data type of an expression and returns its value.

SalContextBreak Retrieves the context of the most recently executed Break statement.

SalContextCurrent Retrieves the current execution context.

VisDebugAssert Asserts that a condition is true.

VisDebugBeginTime Begins timing an operation.

VisDebugEndTime Stops recording the time and displays all incremental times and the total time.

VisDebugGetFlags Retrieves the current debug flags.

VisDebugSetFlags Sets debug flags.

VisDebugSetLevel Sets the current debug level.

VisDebugSetTime Records the time since the last VisDebugSetTime or VisDebugBeginTime call.

VisDebugString Writes a string to the debug application window.




Dialog Box FunctionsThese functions provide an interface to Microsoft Windows' standard dialog boxes.

These functions let you create and destroy your own dialog boxes.

DOS Management FunctionsThese functions manage DOS features.


SalDlgChooseColor Displays the Color dialog box.

SalDlgChooseFont Displays the Font dialog box.

SalDlgOpenFile Displays the Open File dialog box.

SalDlgSaveFile Displays the Save File dialog box.


SalEndDialog Destroys a modal dialog box.

SalModalDialog Creates a modal dialog box.

SalModalDialogFromStr Creates a modal dialog box with the specified name.


VisDosBuildFullName Builds a file name with drive and full directory based on the location of a running executable.

VisDosEnumDirInfo Retrieves all subdirectories for a given directory into a SQLWindows array.

VisDosEnumDirs Retrieves all subdirectories within a given directory into a SQLWindows array.

VisDosEnumDrives Retrieves all available drives into a SQLWindows array, including floppy drives, hard disks, CD-ROM, network and RAM drives.

VisDosEnumFileInfo Retrieves all files in a given directory into a SQLWindows array, and returns each file's size, date/time, and attributes.



VisDosEnumFiles Retrieves all file names from a given directory into a SQLWindows array.

VisDosEnumNetConnections Retrieves all current network connections.

VisDosEnumPath Returns each directory in the DOS PATH environment string.

VisDosEnumsShortDirInfo Retrieves all long and short subdirectory names for a given directory into a SQLWindows array.

VisDosEnumsShortDirs Retrieves all long and short subdirectory names for a given directory into a SQLWindows array.

VisDosEnumsShortFileInfo Retrieves all long and short file names for a given directory into a SQLWindows array.

VisDosEnumsShortFiles Retrieves all long and short file names for a given directory into a SQLWindows array.

VisDosExist Tests for existence of a drive, directory, or file.

VisDosGetCurDir Returns the current directory of a specified drive.

VisDosGetDriveSize Returns total space and available space on a drive.

VisDosGetDriveType Gets the type of drive specified.

VisDosGetEnvString Returns an environment string based on a keyword.

VisDosGetFlags Returns the state of DOS flags.

VisDosGetNetName Retrieves the network name for the specified device.

VisDosGetVersion Returns the MS-DOS version number.

VisDosGetVolumeLabel Returns the volume label of a specified drive.

VisDosIsParent Return indicator if directory contains subdirectories.




Drag Drop FunctionsThese 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.

VisDosMakeAllDir Creates all directories along the full path specified.

VisDosMakePath Builds a full path from a drive, directory or file name.

VisDosNetConnect Connects to a network device.

VisDosNetDisconnect Cancels a network connection.

VisDosSetFlags Sets verify, break, or error mode flags.

VisDosSetVolumeLabel Sets the volume label on a disk drive.

VisDosSplitPath Splits a full path specification into drive, directory, and file name.


SalDragDropDisableDrop Disables dropping while in drag mode.

SalDragDropEnableDrop Enables dropping while in drag mode.

SalDragDropGetSource Retrieves the handle of the source window and the location of the mouse when you initiated drag mode.

SalDragDropGetTarget Retrieves the handle of the target window and the location of the mouse.

SalDragDropStart Initiates drag mode.

SalDragDropStop Ends drag mode.

SalDropFilesAcceptFiles Verifies whether a window can accept a file from Windows' File Manager.

SalDropFilesQueryFiles Retrieves the names of the files dropped on a window.

SalDropFilesQueryPoint Finds the location of the mouse in a window at the time that the user dropped files onto the window.




Edit FunctionsMost 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.


SalEditCanCopyTo Returns TRUE if an editable picture has the focus and contains an object.

SalEditCanCut Returns TRUE if the data in a data field, multiline field, table window column, or editable picture is selected.

SalEditCanPaste Returns TRUE if there is data on the Clipboard to paste into the data field, multiline field, table window column, picture with the focus.

SalEditCanPasteFrom Returns TRUE if an editable picture has the focus.

SalEditCanUndo Returns TRUE if there is any editing to undo.

SalEditClear Deletes selected data from the data field, multiline field, table window column, or picture with the focus.

SalEditCopy Copies selected data from a data field, multiline table window column, or picture and puts it on Clipboard.

SalEditCopyString Copies a string to the Clipboard.

SalEditCopyTo Copies an object to a file if the editable picture that contains the object has the focus.

SalEditCut Cuts selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard.

SalEditPaste Pastes data from the Clipboard into the data field, multiline field, table window column, or picture with the focus.



File Management FunctionsThese functions manage file, directory, and drive operations.

SalEditPasteFrom Copies a file into the editable picture with the focus.

SalEditPasteString Pastes the contents of the Clipboard into the specified string.

SalEditUndo Undoes the last edit to a data field, multiline field, table window column, or picture.

VisWinClearAllFields Clears all child fields of a parent window.


SalFileClose Closes a file.

SalFileCopy Copies the contents of one file to another.

SalFileCreateDirectory Creates a directory.

SalFileGetC Gets the next character from an open file that contains non-ASCII (ANSI) or 16-bit characters.

SalFileGetChar Gets the next character from an open file.

SalFileGetCurrentDirectory Gets the path of the current working directory.

SalFileGetDateTime Gets a file's modification date and time.

SalFileGetDrive Gets the letter of the current disk drive.

SalFileGetStr Gets the next line from an open file.

SalFileOpen Opens a file.

SalFileOpenExt Opens or re-opens a file.

SalFilePutC Writes a character to an open file.

SalFilePutChar Writes a character to an open file.

SalFilePutStr Writes a string to an open file.

SalFileRead Reads from an open file.




SalFileRemoveDirectory Deletes a directory.

SalFileSeek Sets the position in an open file.

SalFileSetCurrentDirectory Changes a drive's current working directory.

SalFileSetDateTime Sets a file's modification date and time.

SalFileSetDrive Sets the default disk drive.

SalFileTell Gets the current position in an open file.

SalFileWrite Writes to an open file.

VisFileAppend Appends one or more files to another.

VisFileClose Closes a file opened with the VisFileOpen call.

VisFileCopy Copies one or more files.

VisFileCreateTemp Creates a temporary file.

VisFileDelete Deletes one or more files.

VisFileExpand Copies a source file to a destination file.

VisFileFind Searches for a file in the following locations and returns the full path to the file:

VisFileGetAttribute Gets the attribute bit values for the specified file.

VisFileGetSize Gets the size of the specified file in bytes.

VisFileGetType Gets the file type. A file can be only one type.

VisFileOpen Creates or opens a file. A file must be opened before it can be read or written to.

VisFileRead Reads a block of data from a file.

VisFileReadString Reads a text line from a text file into a string.

VisFileRename Renames one or more files.

VisFileSeek Seeks to a specified offset within a file.

VisFileSetAttribute Sets the attribute bits for one or more files.




Format and Validation FunctionsThese functions format and validate the value of an object.

VisFileSetDateTime Sets the date and time for one or more files.

VisFileTell Returns the current file offset.

VisFileWrite Writes a block of data to a file.

VisFileWriteString Writes a string to a file.


SalFmtFieldToStr Copies the formatted or unformatted contents of a data field or table window column to a string.

SalFmtFormatDateTime Formats a date/time value.

SalFmtFormatNumber Formats a number value.

SalFmtGetFormat Returns the format of a data field or table window column.

SalFmtGetInputMask Gets the input mask of a data field or table window column.

SalFmtGetPicture Returns the picture format of a data field or table window column.

SalFmtIsValidField Validates the contents of a data field or table window column using its profile.

SalFmtIsValidInputMask Validates an input mask.

SalFmtIsValidPicture Validates a number or date/time picture format.

SalFmtKeepMask Sets whether you keep input mask characters when you copy the value in a data field, table window column, or combo box.

SalFmtSetFormat Sets the format of a data field or table window column.

SalFmtSetInputMask Sets the input mask of a data field or table window column.




SalFmtSetPicture Sets the picture format of a data field or table window column at runtime.

SalFmtStrToField Copies a string's formatted or unformatted contents to an object.

SalFmtUnmaskInput Unmasks the input in a masked data field or table window column.

SalFmtValidateField Validates and formats the contents of a data field or table window column.

SalIsNull Verifies whether a data field, multiline field, or table window column is empty.

SalIsValidDateTime Verifies whether a data field, multiline field, or table window column contains a valid date/time value.

SalIsValidDecimal Verifies whether input to a data field, multiline field, or table window column is of a specified precision and scale.

SalIsValidInteger Verifies whether the value of a data field, multiline field, or table window column is a valid integer.

SalIsValidNumber Verifies whether the value of a data field, multiline field, or table window column is a valid number.

SalStrIsValidCurrency Verifies whether the entire string is a valid currency value.

SalStrIsValidDateTime Verifies whether the entire string is a valid date/time value.

SalStrIsValidNumber Verifies whether the entire string is a valid number value.

SalValidateSet Tells SQLWindows that the focus is changing to a custom control so that SQLWindows can perform validation as needed.




List and Combo Box FunctionsThese functions manage list boxes and combo boxes. Since list boxes can be single- or multiple-selection, and sorted or not sorted, you cannot use all the functions for all list boxes.


SalListAdd Adds an entry to a list box or combo box.

SalListClear Clears a list box or combo box.

SalListDelete Deletes an entry from a list box or combo box.

SalListFiles Populates a list box or combo box with a directory listing.

SalListGetMultiSelect Returns the index numbers of selected list box entries.

SalListInsert Inserts an entry into a list box or combo box.

SalListPopulate Populates a list box or combo box with the result set of a query.

SalListQueryCount Returns the number of entries in a list box or combo box.

SalListQueryFile Fetches the selected file name from a list box or combo box.

SalListQueryMultiCount Returns the number of currently selected list box entries.

SalListQuerySelection Returns the index of the currently selected list box or combo box entry.

SalListQueryState Indicates whether the specified list box or combo box entry is selected.

SalListQueryText and SalListQueryTextX Fetches a list box or combo box entry.

SalListQueryTextLength Returns the length of a list box or combo box entry.

SalListRedraw Allows changes in a list box or combo box to be redrawn or prevents changes from being redrawn.

SalListSelectString Finds and selects a particular list box or combo box entry.



SalListSetMultiSelect Selects or deselects the specified list box entry.

SalListSetSelect Selects the specified list box or combo box index entry.

SalListSetTabs Sets tab stops in a list box.

VisListAddValue Adds an item to a sorted list box or combo box and associates the specified value with the item.

VisListArrayPopulate Populates a list box from a string array.

VisListArrayPopulateValue 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

VisListClearSelection Unselects all selected items in a list box or combo box.

VisListDeleteSelected Deletes all selected items from a list box or combo box.

VisListFindString Finds the first string that matches the specified string in a list box or combo box.

VisListFindValue This function will locate a value associated with an item based on an index.

VisListGetDropdownState Determines whether the list box portion of a combo box is visible.

VisListGetFocusIndex 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.

VisListGetVisibleRange Retrieves the indexes of both the first visible item and the last visible item in a list box.

VisListInsertValue Inserts an item into an unsorted list box or combo box and associates the specified value with the item.

VisListIsMultiSelect Tests a list box to determine if multiple selection is enabled.

VisListScroll Scrolls an item into view.




MDI FunctionsThese functions support MDI (multiple document interface) windows.

Message FunctionsUse these functions to post and send messages to objects.

VisListSetDropdownState Shows or hides the list box portion of a combo box.

VisListSetFocusIndex Sets the focus rectangle to the item at the specified index in a multiple-selection list box.

VisListSetScrollWidth Sets the width by which a list box can be scrolled horizontally.


SalMDIArrangeIcons Arranges minimized child window icons in an MDI window.

SalMDICascade Cascades child windows of an MDI window.

SalMDITile Tiles child windows of an MDI window.


SalPostMsg Posts a message to a window.

SalSendClassMessage Invokes the message actions in the closest ancestor class that implements the given message.

SalSendClassMessageNamed 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.

SalSendMsg Sends a message to a window.

SalSendMsgToChildren Sends a message to all children of a form window.

SalSendValidateMsg Sends a SAM_Validate message to the current data field, multiline field, or table window column if it has been edited.




Miscellaneous FunctionsThese functions perform miscellaneous system tasks from within a SQLWindows application.

VisMessageBox Displays a message box with user defined buttons and a user defined icon.

VisMessageFreeButton Frees memory allocated with VisMessageLoadButton.

VisMessageLoadButton Establishes a button to be used in user-defined message boxes.

VisMessageSetBkgdColor Sets the background color for a VisMessageBox dialog box.

VisSendMsgString Sends a message and passes a string in lParam.


SalAbort Halts the execution of current actions.

SalClearField Clears the value from a field.

SalCursorSet Sets a window's cursor.

SalCursorSetFile Sets an application-defined cursor for the specified window.

SalCursorSetString Sets a window's cursor from a string variable.

SalDrawMenuBar Redraws a menu bar.

SalGetProfileInt Retrieves the integer value of an entry in the specified section of an initialization file.

SalGetProfileString Retrieves the string value of an entry in the specified section of an initialization file.

SalGetVersion Returns the SQLWindows version.

SalLoadApp Loads and starts an application.

SalLoadAppAndWait Loads and starts an application, then waits for it to exit before returning control to the original application.




SalLoadAppAndProcessMsgs 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.

SalMapEnterToTab Sets the default action of the Enter key (execute default push button or shift focus to next object).

SalMessageBeep Generates a beep.

SalMessageBox Displays a message box.

SalObjIsNull Checks to see if the variable of a functional, coclass, or interface class is null.

SalPause Pauses execution for the specified number of milliseconds.

SalQuit Exits the SQLWindows application.

SalSetErrorInfo If an error occurs during a method, you can call SalSetErrorInfo to set standard error information.

SalSetProfileString Sets the value of an entry in the specified section of an initialization file.

SalTimerKill Destroys a system timer.

SalTimerSet Creates a system timer.

SalTrackPopupMenu Creates a pop-up menu at runtime.

SalWaitCursor Displays or removes the hourglass cursor.

SalWinHelp Invokes the Windows help system.

SalYieldEnable Enables or disables application yielding.

SalYieldQueryState Determines whether application yielding is enabled or disabled.

SalYieldStartMessages Allows yielding and the sending of messages to a window.

SalYieldStopMessages Stops yielding and the sending of messages to a window.




VisErrorRecovery Displays an error message and allows the user to free resources and retry the operation.

VisGetCopyright Retrieves a copyright string to display in applications that use the Vis Library.

VisGetKeyState Retrieves the state of a specified key.

VisGetSystemMetrics Retrieves widths and heights of various elements displayed by Windows.

VisGetVersion Gets the Vis Library version number.

VisGetWinFlags Retrieves the current Windows system and memory configuration.

VisGetWinVersion Returns the Windows version number.

VisListLoadOutline Loads an outline from a blob (binary large object) in memory.

VisListLoadOutlineFile Loads an outline from a tab indented ASCII file.

VisListSaveOutline Compresses and saves a list box or combo box outline into a blob (binary large object) in memory.

VisMenuGetPopupHandle Retrieves the menu handle of a pop-up menu.

VisMenuGetSystemHandle Retrieves the system menu handle of a window.

VisMenuGetText Retrieves the text of a menu item.

VisMenuInsert Inserts a menu item into a menu.

VisMenuIsChecked Uses the Windows check state to test whether a menu item is checked.

VisMenuIsEnabled Uses the Windows enable state to test whether a menu item is enabled.

VisMenuUncheck Unchecks a menu item.

VisNumberBitClear Clears bit values from a number.

VisNumberBitSet Sets bit values in a number.




MTS FunctionsUse these functions to run COM objects across a network.

VisNumberChoose Evaluates bExpression.

VisStrChoose Evaluates bExpression.

VisStrFind Locates a string within a string table.

VisStrFreeTable Frees all memory associated with a string table.

VisStrLeftTrim Trims leading blanks from a string.

VisStrLoadTable Loads a string table from disk into memory.

VisWaitCursor Turns hourglass cursor on or off.

VisWinClearAllEditFlags Clears the field edit flags for each data field or multi-line text field of a parent window.

VisWinEnumProps Enumerates the property list for a specified window.

VisWinFreeAccelerator Clears an accelerator for a window, along with all memory associated with the accelerator.

VisWinGetFlags Retrieves window flags for a window.

VisWinGetProp Retrieves a value from the property list of a specified window.

VisWinGetStyle Retrieves the Windows style bits for a specified window.

VisWinIsRequiredFieldNull Tests to determine if any required field is null.

VisWinSetMeter Displays a completion meter within a SQLWindows data field.


SalMTSCreateInstance Creates a new component as part of the current transaction or in a new, independent transaction.




Number FunctionsThese functions perform mathematical calculations.

SalMTSDisableCommit Indicates that the object’s transactional updates cannot be committed in their current form (stateful object).

SalMTSEnableCommit Indicates that the object’s work is not necessarily done, but that its transactional updates can be committed in their current form (stateful object).

SalMTSGetObjectContext Gets the explicit object context (IUnknown).

SalMTSIsCallerInRoll Determines if the component’s caller is a member of a specified role.

SalMTSIsInTransaction Determines if the component is in a transaction.

SalMTSIsSecurityEnabled Determines if declarative security is enabled for the component.

SalMTSSetAbort Indicates that the object’s work can never be committed.

SalMTSSetComplete Indicates that the object has successfully completed its work for the transaction.


SalNumberAbs Computes a number's absolute value.

SalNumberArcCos Computes a value's arccosine.

SalNumberArcSin Computes a value's arcsine.

SalNumberArcTan Computes a value's arctangent.

SalNumberArcTan2 Computes the arctangent of two values.

SalNumberCos Computes an angle's cosine.

SalNumberCosH Computes an angle's hyperbolic cosine.




SalNumberExponent Computes a value's exponential function.

SalNumberHigh Returns a number's high-order word value (most significant 16 bits).

SalNumberHypot Computes the length of the hypotenuse of a right triangle.

SalNumberLog Computes a number's natural logarithm.

SalNumberLogBase10 Computes a number's base-10 logarithm.

SalNumberLow Returns a number's low-order word value (least significant 16 bits).

SalNumberMax Returns the greater of two values.

SalNumberMin Returns the lesser of two values.

SalNumberMod Returns a number's modulo.

SalNumberPi Multiplies a number by Pi.

SalNumberPower Computes a number raised to the power of another number.

SalNumberRandInit Sets the starting point for generating a series of pseudorandom numbers.

SalNumberRandom Generates a pseudorandom integer in the range 0 to 32767.

SalNumberRound Returns a rounded number.

SalNumberSin Computes an angle's sine.

SalNumberSinH Computes an angle's hyperbolic sine.

SalNumberSqrt Computes a number's square root.

SalNumberTan Computes an angle's tangent.

SalNumberTanH Computes an angle's hyperbolic tangent.

SalNumberToChar Converts an ASCII numeric value to a character.

SalNumberToHString Converts a number to a string handle.

SalNumberToStr and SalNumberToStrX Convert a number to a string.




See Also: Array Functions

OLE DB Consumer FunctionsUse these functions when you use CTD as a consumer to connect to databases.

SalNumberToWindowHandle Converts a number to a window handle.

SalNumberTruncate Truncates a number.

VisNumberHighByte Converts the specified number to a WORD and returns the high order 8 bits of the WORD.

VisNumberLowByte Converts the specified number to a WORD and returns the low order 8 bits of the WORD.

VisNumberMakeLong Creates a double word value (DWORD) from two word values.


SqlCloseAllSPResultSets Closes any result set generated by the execution of a stored procedure.

SqlCommitSession Commits the current transaction associated with a specified session.

SqlCreateSession Creates a new session.

SqlCreateStatement Creates a new statement belonging to the specified session.

SqlFreeSession Closes a session.

SqlGetCmdOrRowsetPtr Gives the caller either the ICommand or the IRowset interface pointer of the Command or the Rowset OLE DB object.

SqlGetDSOrSessionPtr 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.




Picture FunctionsThese functions manipulate the contents of a picture.

SqlGetNextSPResultSet 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.

SqlGetSessionErrorInfo Returns the error information associated with the specified session.

SqlGetSessionHandle Returns the session handle to which the specified statement handle belongs.

SqlGetSessionProperty Gets the value of the specified session property.

SqlGetStatementErrorInfo Returns the error information associated with the specified statement handle (command/cursor).

SqlPrepareSP Prepares a stored procedure invokation statement.

SqlRollbackSession Rolls back the current transaction associated with the specified session.

SqlSetSessionProperty Sets the value of the specified session property.


SalPicClear Clears the contents of a picture.

SalPicGetDescription Retrieves a description of a picture's contents.

SalPicGetImage Copies the contents of a picture to an image without the SQLWindows image header.

SalPicGetString Copies the contents of a picture to a string.

SalPicSet Inserts a resource into a picture.




Print FunctionsThese functions let you control printing.

SalPicSetFile Sets the contents of a picture from a file.

SalPicSetFit Sets the fit for a picture.

SalPicSetImage Inserts the contents of a picture to an image without the SQLWindows image header.

SalPicSetString Sets the contents of a picture from a string.

VisMenuInsertPicture Inserts a menu item into a menu and displays the specified picture with it.

VisMenuSetPicture Displays a picture in a menu item.

VisPicFree Frees a picture from memory. A picture is either a bitmap or an icon.

VisPicLoad Loads a picture into memory.

VisTblSetRowPicture Sets the picture for a bit flag of a table window.


SalPrtExtractRect Extracts the printing rectangle from the SAM_Print message's lParam argument.

SalPrtGetDefault Gets the default printer.

SalPrtGetParmNum Gets the value of a print parameter.

SalPrtPrintForm Prints a window.

SalPrtSetDefault Sets the default printer.

SalPrtSetParmDefaults Resets print parameters to their defaults.

SalPrtSetParmNum Sets the value of a print parameter.

SalPrtSetup Displays the Printer Setup Dialog Box which lets the user alter the printer setup.




Report FunctionsGUPTA 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.


SalReportClose Closes a Report Builder window.

SalReportCmd Sends a command to a report window.

SalReportCreate Creates a report.

SalReportDlgOptions Sets the options for the report printing dialog box.

SalReportGetDateTimeVar Gets the value of a date/time report variable.

SalReportGetFileInfo Gets a comment which is embedded in a report template.

SalReportGetNumberVar Gets the value of a numeric report variable.

SalReportGetObjectVar Gets the value of an object report variable.

SalReportGetPrinterSettings Gets the characteristics of the currently active printer.

SalReportGetStringVar Gets the value of a string report variable.

SalReportPrint Prints a report.

SalReportPrintToFile Prints a report to a file.

SalReportReset Updates the report preview with new data.

SalReportResetPages Sets current page to 1 and total page to the value specific to a particular break group.

SalReportSetDateTimeVar Sets the value of a date/time report variable.

SalReportSetNumberVar Sets the value of a date/time report variable.

SalReportSetObjectVar Sets the value of an object report variable.

SalReportSetPrinterSettings Sets specific characteristics of the printer

SalReportSetPrinterTray Specifies which printer trays are used for the first page and subsequent pages.

SalReportSetStringVar Sets the value of a string report variable.



Scroll Bar FunctionsThese functions manage horizontal and vertical scroll bars.

SQL FunctionsMost 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.

SalReportTableCreate Creates a report from the specified table window.

SalReportTablePrint Prints a report created from a table window.

SalReportTableView Displays, in preview mode, a report created from a table window.

SalReportView Displays a report in preview mode.


SalScrollGetPos Gets the scroll bar position.

SalScrollGetRange Gets values set by SalScrollSetRange.

SalScrollSetPos Sets the scroll bar position.

SalScrollSetRange Sets the range of a scroll bar.


SqlClearImmediate Disconnects the Sql Handle used by SqlImmediate.

SqlClose Closes a named cursor.

SqlCommit Commits the current SQL transaction.

SqlConnect Connects a Sql Handle to a database.

SqlContextClear Clears the context set by SqlContextSet.

SqlContextSet Sets the context for later compilation and fetching.

SqlContextSetToForm Sets context to form name.




SqlDirectoryByName Gets the names of databases on a given server.

SqlDisconnect Disconnects a Sql Handle from a database.

SqlDropStoredCmd Deletes a stored command.

SqlError Gets the most recent error code for the specified Sql Handle.

SqlErrorText Gets an error code's reason and/or remedy.

SqlExecute Executes a SQL statement.

SqlExecutionPlan Gets the execution plan for a compiled SQL statement.

SqlExists Checks for the existence of a particular row.

SqlExtractArgs Extracts error information.

SqlFetchNext Fetches the next row in a result set.

SqlFetchPrevious Fetches the previous row in a result set.

SqlFetchRow Fetches a specific row from a result set.

SqlGetCursor Returns a cursor handle, which can then be used for calls into the SQLBase API.

SqlGetError Turns off backend error mapping and reports real backend errors.

SqlGetErrorPosition Gets the offset of an error within a SQL statement.

SqlGetErrorText and SqlGetErrorTextX Gets the message text for a SQL error number.

SqlGetModifiedRows Returns the number of rows changed by an INSERT, UPDATE, or DELETE.

SqlGetParameter Returns a database parameter.

SqlGetParameterAll Returns a database parameter.

SqlGetResultSetCount Returns the number of rows in a result set.

SqlGetRollbackFlag Returns the database rollback flag.




SqlImmediate Prepares and executes a SQL statement.

SqlImmediateContext Prepares, executes, and fetches the results of a SQL statement.

SqlOpen Names a cursor and executes a SQL statement.

SqlPLSQLCommand Executes PL/SQL stored procedures in SQLWindows. Call it once for each invocation of PL/SQL.

SqlPrepare Prepares a Sql statement for execution.

SqlPrepareAndExecute Prepares and executes an Sql statement.

SqlRetrieve Retrieves a stored command.

SqlSetInMessage Sets the size of the input message buffer for a specified cursor.

SqlSetIsolationLevel Sets the isolation level.

SqlSetLockTimeout Sets the timeout period on waiting for a lock.

SqlSetLongBindDatatype Sets type of column to bind to.

SqlSetOutMessage Sets the size of the output message buffer for a specified cursor.

SqlSetParameter Sets a database parameter.

SqlSetParameterAll Sets a database parameter.

SqlSetResultSet Turns a result set mode on and off.

SqlStore Compiles and stores a command.

SqlVarSetup 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).




String Conversion FunctionsThese functions manipulate string data by changing the form of a string or looking for substrings.


SalStrCompress Compresses a string.

SalStrFirstC Returns the first character in a string.

SalStrGetBufferLength Returns the length of a string buffer.

SalStrLeft and SalStrLeftX Returns a string of specified length, starting with the first character in the string.

SalStrLength Returns the length of a string.

SalStrLop Returns the ANSI numeric value of the first character of a string.

SalStrLowerand SalStrLowerX Converts a string to lowercase.

SalStrMid and SalStrMidX Returns a substring.

SalStrProper and SalStrProperX Converts a string to a proper name.

SalStrRepeat and SalStrRepeatX Concatenates a string with itself a specified number of times.

SalStrReplace and SalStrReplaceX Replaces characters in one string with characters from another string.

SalStrRight and SalStrRightX Returns a string of specified length, starting with the last or right-most character in the string.

SalStrScan Finds a string within a string.

SalStrSetBufferLength Sets the length of the specified string buffer.

SalStrToDate Converts a string to a date/time value.

SalStrTokenize Parses a string into substrings.

SalStrToNumber Converts a string to a number.

SalStrTrim and SalStrTrimX Removes white space from a string.

SalStrUncompress Decompresses a string.

SalStrUpper and SalStrUpperX Converts a string to uppercase.



Table Window FunctionsThese functions manage table windows.

VisStrExpand Expands a template string by inserting one or more array elements.

VisStrPad Pads a string with trailing blanks and returns the result.

VisStrProper Converts a string to mixed case.

VisStrRightTrim Trims trailing blanks from a string.

VisStrScanReverse Scans a string for a specified sub-string from the last character to the first.

VisStrSubstitute Substitutes all occurrences of one string with another string.

VisStrTrim Trims leading and trailing blanks from a string. It does not adjust embedded brackets.


SalTblAnyRows Determines whether any rows have certain flags set.

SalTblClearSelection Clears the selection of rows in a table window.

SalTblColumnAverage Computes the average of a column's values.

SalTblColumnSum Computes the sum of a column's values.

SalTblCopyRows Copies the contents of specified rows to the Clipboard.

SalTblCreateColumn Creates columns at runtime.

SalTblCreateColumnEx Creates columns at runtime, with user-specified datatype.

SalTblDefineRowHeader Defines the appearance and behavior of a row header.

SalTblDefineSplitWindow Defines how a table window is split horizontally.

SalTblDeleteRow Deletes a row.




SalTblDeleteSelected Applies a DELETE statement to all selected rows.

SalTblDestroyColumns Destroys automatic columns created at runtime.

SalTblDoDeletes Applies a DELETE statement to all rows with certain flags set.

SalTblDoInserts Applies an INSERT statement to all new rows.

SalTblDoUpdates Applies an UPDATE statement to all edited rows.

SalTblFetchRow Sends a SAM_FetchRow message to the table window if the specified row is not in the table window cache.

SalTblFindNextRow Scans forward looking for a row that has certain flags set.

SalTblFindPrevRow Scans backward looking for a row that has certain flags set.

SalTblGetColumnText Returns the value in a specified column of the context row.

SalTblGetColumnTitle Returns a column's title.

SalTblGetColumnWindow Retrieves a column's window handle based on its position in the table window or its column identifier.

SalTblInsertRow Inserts a new row.

SalTblKillEdit Sets the ROW_Edited flag on a new or changed row.

SalTblKillFocus Turns off the focus frame.

SalTblObjectsFromPoint Returns the part of a table window located at a given coordinate.

SalTblPasteRows Pastes the contents of the Clipboard into the specified table window.

SalTblPopulate Populates a table window with a result set.




SalTblPopulateFromXML Clears a table window and then populates it with data from an XML file.

SalTblQueryColumnFlags Tests the state of a column's flags.

SalTblQueryColumnID Gets a column's identifier.

SalTblQueryColumnPos Gets a column's position in the table window.

SalTblQueryColumnWidth Retrieves a column's width.

SalTblQueryContext Gets the current context row.

SalTblQueryFocus Identifies the cell with the focus.

SalTblQueryLockedColumns Returns the number of locked columns.

SalTblQueryRowFlags Queries a row's flags.

SalTblQueryRowHeader Gets the definition of a row header.

SalTblQueryScroll Gets the current scroll position and range.

SalTblQuerySplitWindow Specifies how the table window is split horizontally.

SalTblQueryTableFlags Tests the state of a table window's flags.

SalTblQueryVisibleRange Gets the current visible range.

SalTblReset Clears a table window.

SalTblScroll Scrolls to a specified cell.

SalTblSetCellTextColor Sets a cell's text color.

SalTblSetColumnFlags Sets or clears a column's flags.

SalTblSetColumnPos Moves a column.

SalTblSetColumnText Sets the value of a specified column in the context row.

SalTblSetColumnTitle Sets a column's title.

SalTblSetColumnWidth Sets a column's width.

SalTblSetContext Sets the context row.

SalTblSetFlagsAnyRows Sets or clears row flags.




SalTblSetFocusCell Sets the focus to a specified cell.

SalTblSetFocusRow Sets the focus frame row.

SalTblSetLockedColumns Defines the number of columns to lock.

SalTblSetRange Defines the minimum and maximum rows.

SalTblSetRow Sets focus to a row.

SalTblSetRowFlags Sets or clears row flags.

SalTblSetTableFlags Sets or clears table window flags.

SalTblSortRows Sorts the contents of a table window based on the values in a specified column.

SalTblWriteXMLAndSchema Writes the contents of a table window to an XML file and/or an XML schema file.

SalTblWriteXMLAndSchemaEx Writes the contents of a table window to an XML file and/or an XML schema file. Selects rows with specific flags.

VisTblAllRows Determines whether any rows in the specified table window match certain flags.

VisTblAutoSizeColumn Performs a best fit on the display contents of a specific column.

VisTblClearColumnSelection Clears selection for all columns of a table window.

VisTblFindDateTime Locates a date/time value within a column.

VisTblFindNumber 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.

VisTblFindString Locates a string value within a column.

VisTblGetCell Retrieves the contents of a cell in a table window.

VisTblGetColumnTitle Retrieves the contents of a column heading. The row specified will be set to the context row.




Window Management FunctionsThese functions let you manipulate an application's windows.


SalAppDisable Disables input to open windows.

SalAppEnable Enables input to open windows.

SalAppFind Finds a visible top-level window for the application that you specify and returns its window handle.

SalBringWindowToTop Brings a specified window to the top of all overlapping windows.

SalCenterWindow Centers a window.

SalCreateWindow Creates a window.

SalCreateWindowEx Creates a form window, dialog box, or table window as a child of another form window, dialog box, or toolbar at runtime.

SalDestroyWindow Destroys a window.

SalDisableWindow Disables mouse and keyboard input to a window.

SalDisableWindowAndLabel Disables mouse and keyboard input to a window, including disabling background text.

SalEnableWindow Enables keyboard and mouse input to a window.

SalEnableWindowAndLabel Enables keyboard and mouse input to a window, including enabling background text.

SalFormGetParmNum Gets information about a form window.

SalDlgGetDockStatus Gets information about the current docking orientation of a dialog box.

SalDlgSetDockStatus Sets the docking orientation of a dialog box with its parent window.

SalGetDefButton Gets the handle of the default push button.

SalGetFirstChild Finds the first child of a window.



SalGetFocus Gets the object with the focus.

SalGetNextChild Finds the next child of a window.

SalGetType Returns the type of the specified object.

SalGetWindowLabel Retrieves the window handle of a background text label.

SalGetWindowLabelText Retrieves a window's background text.

SalGetWindowLoc Gets a window's current position on the X and Y axes.

SalGetWindowSize Gets the current window's size.

SalGetWindowState Gets the current state of a window.

SalGetWindowText Retrieves a window's text.

SalHideWindow Hides a window.

SalHideWindowAndLabel Hides a window and its associated label.

SalInvalidateWindow Causes a window to be repainted.

SalIsButtonChecked Determines whether a radio button is set or a check box is checked.

SalIsWindowEnabled Specifies whether a window is enabled for mouse and keyboard input.

SalIsWindowVisible Specifies whether a window is visible.

SalMoveWindow Moves a window a given number of form units on the X and Y axes relative to its current position.

SalParentWindow Returns the window handle of a parent or owner window.

SalQueryFieldEdit Returns the setting of the field edit flag for a data field, multiline field, table window column, or picture.

SalSetDefButton Sets the default push button for a form window or dialog box.




SalSetFieldEdit Sets or clears the field edit flag for a data field, multiline field, table window column, or picture.

SalSetFocus Sets the focus to a window.

SalSetWindowLabelText Sets a window's background text.

SalSetWindowLoc Moves a window to a position on the X and Y axes.

SalSetWindowSize Resizes a window.

SalSetWindowText Sets a window's text.

SalShowWindow Makes a window visible.

SalShowWindowAndLabel Shows a window and its associated label.

SalStatusGetText Gets the text displayed in a top-level window's status bar.

SalStatusSetText Displays specified text in a top-level window's status bar.

SalStatusSetVisible Shows or hides a top-level window's optional status bar.

SalTBarSetVisible Shows or hides a top-level window's tool bar.

SalUpdateWindow Updates the client area of a window.

SalWindowGetDockSettings Gets information about the docking orientations allowed by a top-level window.

SalWindowGetProperty 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.

SalWindowHandleToNumber Converts a window handle to a number.

SalWindowIsDerivedFromClass Converts a window handle to a number.

VisWinEnumProps Enumerates the property list for a specified window.

VisWinGetProp Retrieves a value from the property list of a specified window.




XML FunctionsThese 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...

VisWinIsChild Tests whether a specified window is a child or direct descendant of a parent window.

VisWinIsMaximized Tests whether a specified window is maximized.

VisWinIsMinimized Tests whether a specified window is minimized.

VisWinIsRestored Tests whether a specified window is neither maximized or minimized.

VisWinIsWindow Tests whether a specified window is valid.

VisWinLoadAccelerator Sets an accelerator keystroke for a window.

VisWinMove Moves and resizes a window, based on pixel coordinates.

VisWinRemoveProp Removes a property list entry for a specified window.

VisWinSetFlags Sets flags for a specified window.

VisWinSetProp Adds a new property list entry or changes an existing property list entry for a specified window.

VisWinSetStyle Adds a window style to a window.

VisWinSetTabOrder Changes the tab order of a control.

VisWinShow Sets a window's visibility state.


SalTblPopulateFromXML Loads XML data into a table window.

SalTblWriteXMLAndSchema Writes table window data into an XML data file and/or an XML schema file..



Obsolete FunctionsSalCreateWindowFrmStrSalFmtCopyProfileSalFmtGetParmIntSalFmtGetParmStrSalFmtGetProfileSalFmtSetParmIntSalFmtSetParmStrSalFmtSetProfileSalQueryArrayBoundsSalSetArrayBoundsSalDDEAddAtomSalDDEAllocSalDDEDeleteAtomSalDDEExtractSalDDEExtractCmdSalDDEExtractDataTextSalDDEExtractOptionsSalDDEFindAtomSalDDEFreeSalDDEGetAtomNameSalDDEGetExecuteStringSalDDEPostSalDDERequestSalDDESendSalDDESendAllSalDDESendExecute

SalTblWriteXMLAndSchemaEx Writes table window data into an XML data file and/or an XML schema file..Filters by row flags

SalXMLDeserializeUDV Reads an XML data file and places its contents into a UDV or array.

SalXMLGetLastError Gets the error code and description from the last XML operation performed.

SalXMLSerializeUDV Writes the contents of a UDV or array into an XML data file.


Obsolete Functions

SalDDESendToClientSalDDESetCmdSalDDESetDataTextSalDDESetOptionsSalDDEStartServerSalDDEStartSessionSalDDEStopServerSalDDEStopSession





Chapter 2

SQLWindows Functions

This is an alphabetical list of the GUPTA SQLWindows functions accompanied by detailed information about each function’s purpose, its parameters and return value, and an example.

Function descriptions include:

• Syntax

• Description

• Parameters

• Return value

• See also

• Example


Chapter 2 SQLWindows Functions

SalAbortSyntax bOk = SalAbort ( nExitCode )

Description 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 nExitCode Receive Number. The status of the exit performed by SalAbort. SQLWindows ignores this parameter as input.

Return Value bOk is TRUE if the function succeeds and FALSE if it fails.

See Also SalQuit

Example If NOT SqlConnect ( hSql )

Call SalAbort ( -1 )

SalActiveXAutoErrorModeSyntax bOK = SalActiveXAutoErrorMode( bOn )

Description 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.

Parameters bOn Boolean. Specify FALSE to turn off automatic error handling or specify TRUE to turn on automatic error handling.

Return Value Always returns TRUE.

See Also ActiveX exception handling

Example None

SalActiveXCloseSyntax bOK = SalActiveXClose( hwndCntrCtrl, bSave )

Description 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.


SalActiveXCreate

Parameters hwndCntrCtrl Window Handle. The ActiveX container control.

bSave Boolean. If TRUE, the object's application will do a save before closing the connection.

Return Value bOK is TRUE if the function succeeds and FALSE if it fails.

See Also SalActiveXCreateFromFile

Example ActiveX: ax1

…

Call SalActiveXClose( ax1, FALSE )

SalActiveXCreateSyntax bOK = SalActiveXCreate( hwndCntrCtrl, strBytes )

Description Creates an object given its class descriptor (progID).


strBytes String. The OLE progID of the class (such as Excel.Sheet.8).


See Also SalActiveXCreateFromFile

Example Data Field: df1

ActiveX: ax1

…

Call SalActiveXCreate( ax1, df1 )

SalActiveXCreateFromDataSyntax bOK = SalActiveXCreateFromData( hwndCntrCtrl, strBytes )

Description Creates an object given its class descriptor (progID).


strBytes String. The object's data as a raw blob of bytes.


See Also SalActiveXGetData


String: blob

…



Call SalActiveXCreateFromData( ax1, blob )

SalActiveXCreateFromFileSyntax bOK = SalActiveXCreateFromFile( objObject, strFile )

Description Creates an instance of an ActiveX object.

Parameters objObject Object. A reference to the created object.

strFile String. The file name of a valid doc object (such as c:\docs\mywordfile.doc).


See Also SalActiveXCreate

Example None.

SalActiveXDeleteSyntax bOK = SalActiveXDelete( hwndCntrCtrl)

Description 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.

Parameters hwndCntrCtrl Window Handle. The window handle of the object to delete.


See Also None.


…

Call SalActiveXDelete( ax1 )

SalActiveXDoVerbSyntax bOK = SalActiveXDoVerb( hwndCntrCtrl, nVerb, bSize)

Description 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.

Parameters hwndCntrCtrl Window Handle. The window handle of the object to delete.


SalActiveXGetActiveObject

nVerb Number. A constant that identifies the verb:

Constant Description

salOLEPrimary The default action for the object.

salOLEShow 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.

salOLEOpen 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.

salOLEHide For embedded objects, hides the application that created the object.

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 If TRUE, sizes the object to the size of the site window upon activation.


See Also None.


Data Field: df2

Data Field: df3

…

Call SalActiveXDoVerb( ax1, SalStrToNumber(df2), SalStrToNumber(df3) )

SalActiveXGetActiveObjectSyntax bOK = SalActiveXGetActiveObject( objObject, strClass)



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 Object. The object that was found.

strClass String. The class name of the object to get in appname.objecttype format.

Return Value bOK is TRUE if the function succeeds and FALSE if SQLWindows could not find a valid automation dispatch.

See Also None.

Example None.

SalActiveXGetDataSyntax bOK = SalActiveXGetData( hwndCntrCtrl, strBytes)

Description 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.


strBytes Receive String. The object's data as a raw blob of bytes.


See Also SalActiveXCreateFromData


String: blob

…

Call SalActiveXGetData( ax1, blob )

SalActiveXGetFileNameSyntax bOK = SalActiveXGetFileName ( hwndControl, strFileName )

Description Gets the File Name of the object inserted with the ‘Create From File’ option using SalActiveXInsertObjectDlg.


SalActiveXGetObject

Parameters hwndControl Window Handle. The ActiveX container control.

strFileName Receive String. The object's FileName, if the object was inserted using ‘Create From File’ Option.

Return value bOK is TRUE if the function succeeds and FALSE if it fails.

See Also SalActiveXInsertObjectDlg


String: strFileName

Call SalActiveXInsertObjectDlg ( ax1 )

Call SalActiveXGetFileName( ax1, strFileName )

SalActiveXGetObjectSyntax bOK = SalActiveXGetObject( hwndCntrCtrl, objObject)

Description Gives access to the automation dispatch interface of the object in the specified container.


objObject Object. The object that was retrieved.

Return Value TRUE if a valid automation dispatch interface was found, FALSE otherwise.

See Also None

Example 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)



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)

SalActiveXGetProgIDSyntax bOK = SalActiveXGetProgID( hwndControl, strProgID )

Description Gets the ProgID of the object inserted using SalActiveXInsertObjectDlg.

Parameters hwndControl Window Handle. The ActiveX container control.

strProgID Receive String. The object's ProgID.

Return value bOK is TRUE if the function succeeds and FALSE if it fails.

See Also SalActiveXInsertObjectDlg


String: strProgID

Call SalActiveXInsertObjectDlg ( ax1 )

Call SalActiveXGetData( ax1, strProgID )

SalActiveXInsertObjectDlgSyntax bOK = SalActiveXInsertObjectDialog( hwndCntrCtrl)

Description 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 hwndCntrCtrl Window Handle. The ActiveX container control where the object is created.

Return Value 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).

See Also None



SalActiveXOLEType

…

Call SalActiveXInsertObjectDlg( ax1 )

SalActiveXOLETypeSyntax bOK = SalActiveXOLEType( hwndCntrCtrl)

Description Returns the status of the object in an ActiveX container control.


Return Value Number. The status of the ActiveX container control:


salOLEControl 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 None. The ActiveX container control does not contain an object.

See Also None

SalAppDisableSyntax bOk = SalAppDisable ( )

Description 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.

Parameters No parameters.


See Also SalAppEnable

Example Call SalAppDisable ( )

Call SalLoadAppAndWait ( 'Excel', '' )

Call SalAppEnable ( )

SalAppEnableSyntax bOk = SalAppEnable ( )



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.


Return Value bOk is TRUE if the function succeeds and FALSE if you did not previously call SalAppDisable.

See Also SalAppDisable

Example Call SalAppDisable ( )

Call SalLoadAppAndWait ( 'Excel', '' )

Call SalAppEnable ( )

SalAppFindSyntax hWnd = SalAppFind ( strAppName, bActivate )

Description 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 application’s *.DEF file.

bActivate Boolean. If you set bActivate to TRUE, SalAppFind also activates the application's window.

Return Value hWnd is the handle of the window.

Example On SAM_AppStartup


SalAppFind

If SalAppFind( 'INVOICE', TRUE ) != hWndNULL

Call SalQuit( )



SalArrayAvgSyntax nAvg = SalArrayAvg ( nArrayNum )

Description Returns the average value of all the numbers in an array.

Parameters nArrayNum Numeric Array. The name of an array of numbers.

Return Value nAvg is the average value in an array of numbers.

See Also SalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum

Example On SAM_Create

Set dfAvg = SalArrayAvg( nArrayNum )

SalArrayDimCountSyntax bOk = SalArrayDimCount ( aArray, nDim )

Description Returns the number of dimensions in an array.

Parameters aArray Array. The name of the array to query.

nDim Receive Number. Number of dimensions in the array.


See Also SalArrayAvgSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum


Set bOk = SalArrayDimCount (aArray, nDim)

If nDim = 0

Set bDimTrue = False


SalArrayGetLowerBound

SalArrayGetLowerBoundSyntax bOk = SalArrayGetLowerBound ( aArray, nDim, nBound )

Description Returns the lower bound of an array.


nDim Number. Number of the dimension to query. The first dimension is one, the second is two, and so on.

nBound Receive Number. Lower bound value.


See Also SalArrayAvgSalArrayDimCountSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum

Example On SAM_Click

Set bOk = SalArrayGetLowerBound (aArray, nBound)

SalArrayGetUpperBoundSyntax bOk = SalArrayGetUpperBound ( aArray, nDim, nBound )

Description Returns the upper bound of an array.



nBound Receive Number. Upper bound value.


See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBound



SalArraySum


Set bOk = SalArrayGetUpperBound (aArray, nBound)

SalArrayIsEmptySyntax bData = SalArrayIsEmpty ( aArray )

Description Determines if a dynamic array contains data.


Return Value bData is TRUE if the array contains no data and FALSE if it is has data.

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum


If Not SalArrayIsEmpty (aArray)

Call ...

SalArrayMaxSyntax nMax = SalArrayMax ( nArrayNum )

Description Returns the maximum value in an array of numbers.


Return Value nMax is the maximum value in an array of numbers.

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMinSalArraySetUpperBoundSalArraySum



SalArrayMin

Set dfMax = SalArrayMax( nArrayNum )

SalArrayMinSyntax nMin = SalArrayMin ( nArrayNum )

Description Returns the minimum value in an array of numbers.

nArrayNum Numeric Array. The name of an array of numbers.

Return Value nMin is the minimum value in an array of numbers.

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArraySetUpperBoundSalArraySum


Set dfMin = SalArrayMin( nArrayNum )

SalArraySetUpperBoundSyntax bOk = SalArraySetUpperBound ( aArray, nDim, nBound )

Description 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.



nBound 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.)


See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBound



SalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySum


Call SalArraySetUpperBound (aArray, 1, 5)

SalArraySumSyntax nSum = SalArraySum ( nArrayNum )

Description Returns the sum of the elements in an array of numbers.


Return Value nSum is the sum of the elements in an array of numbers.

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBound


Set dfSum = SalArraySum( nArrayNum )

SalBringWindowToTopSyntax bOk = SalBringWindowToTop ( hWndToExpose )

Description Brings a window to the top of all overlapping windows.

Parameters hWndToExpose Window Handle. The handle (or name) of the window to bring to the top.


See Also SalHideWindowSalShowWindow

Example If ( hWndCustomer )

Call SalBringWindowToTop ( hWndCustomer )


SalCenterWindow

SalCenterWindowSyntax bOk = SalCenterWindow ( hWndCenter )

Description 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.

Parameters hWndCenter Window Handle. The handle (or name) of the window to center.


See Also SalMoveWindow

Example Call SalCenterWindow ( pbExample )

SalClearFieldSyntax bOk = SalClearField ( hWndFldToClear )

Description Clears the value from a data field, multiline field, or table window column.

Parameters hWndFldToClear Window Handle. The handle (or name) of the data field, multiline field, or table window column to clear.


See Also SalIsNull

Example If ( dfAge < 0 )

Call SalClearField ( dfAge )

SalColorFromRGBSyntax nColor = SalColorFromRGB ( nRed, nGreen, nBlue )

Description Composes a color from red, green, and blue values.

Parameters nRed Number. A number from 0 to 255.

nGreen Number. A number from 0 to 255.

nBlue Number. A number from 0 to 255.

Return Value nColor is the color created.

See Also SalColorGetSalColorGetSysColorSalColorSetSalColorToRGB



Example Set nRed = 128

Set nGreen = 128

Set nBlue = 128

Set nColor = SalColorFromRGB ( nRed, nGreen, nBlue )

If NOT SalColorSet ( hWndItem, COLOR_IndexWindow, nColor )

...

SalColorGetSyntax nColor = SalColorGet ( hWndColored, nColorIndex )

Description Gets a window's color.

Parameters hWndColored Window Handle. The handle (or name) of the window whose color you want.

nColorIndex 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 SalColorFromRGBSalColorGetSysColorSalColorSetSalColorToRGB

Example Set nColor = SalColorGet ( hWndItem, COLOR_IndexWindow )

If nColor = COLOR_Default

Call SalColorSet ( hWndItem, COLOR_IndexWindow,

COLOR_Magenta )


SalColorGetSysColor

SalColorGetSysColorSyntax nColor = SalColorGetSysColor ( nColorIndex )

Description Gets a system color.

Parameters nColorIndex Number. The color of a part of the window, represented by one of these constants:

COLOR_SysWindow

COLOR_SysWindowFrame

COLOR_SysWindowText

Return Value 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).

See Also SalColorFromRGBSalColorGetSalColorSetSalColorToRGB

Example Set nSysColorBckgrnd = SalColorGetSysColor ( COLOR_SysWindow )

SalColorSetSyntax bOk = SalColorSet ( hWndToSet, nColorIndex, nColor )

Description Sets a window's color.

Parameters hWndToSet Window Handle. The handle (or name) of the window whose color you want to set.

nColorIndex 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.


See Also SalColorFromRGBSalColorGet



SalColorGetSysColorSalColorToRGB

Example Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Red )

SalColorToRGBSyntax bOk = SalColorToRGB ( nColor, nRed, nGreen, nBlue )

Description Decomposes a color into red, green, and blue values.

Parameters nColor Number. A user-defined value or any of the predefined window colors (excluding COLOR_Default, COLOR_None, and the three COLOR_Sys* constants).

nRed Receive number. A number from 0 to 255 that represents the red value.

nGreen Receive number. A number from 0 to 255 that represents the green value.

nBlue Receive number. A number from 0 to 255 that represents the blue value.


See Also SalColorFromRGBSalColorGetSalColorGetSysColorSalColorSet

Example If NOT SalColorToRGB ( nColor, nRed, nGreen, nBlue )

... Error ...

SalComCleanupModeSyntax void SalComCleanupMode ( bLateCleanup )

Description Determines when unused COM+ thread resources are cleaned up.

Parameters 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.


SalCompileAndEvaluate

Example Call SalComCleanupMode ( TRUE )

SalCompileAndEvaluateSyntax nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos, nReturn,

strReturn, dtReturn, hWndReturn, bInhibitErrors, strContext )

Description 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.

Parameters strExpression String. The expression to evaluate.

nError Receive Number. The error number, if one is returned.

nErrorPos Receive Number. The position in strExpression at which an error, if any, occurred.

nReturn Receive Number. This parameter is set if strExpression evaluates to a number.

strReturn Receive String. This parameter is set if strExpression evaluates to a string.

dtReturn Receive Date/Time. This parameter is set if strExpression evaluates to a date/time value.

hWndReturn Receive Window Handle. This parameter is set if strExpression evaluates to a handle.

bInhibitErrors 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.

strContext String. The handle to an execution context, returned by either SalContextBreak or SalContextCurrent.

Return Value nType is equal to one of the following values if the function succeeds:

EVAL_DateEVAL_HandleEVAL_IfEVAL_NumberEVAL_SetEVAL_StringEVAL_Template



See Also SalContextBreak SalContextCurrent

Example Set nType = SalCompileAndEvaluate ( strExpression, nError,

nErrorPos,nReturn, strReturn, dtReturn, hWndReturn,

FALSE, strContext )

If nType = EVAL_Number

Call SalNumberToStr ( nReturn, 0, strString )...

SalContextBreakSyntax strContext = SalContextBreak ( )

Description Retrieves the context of the most recently executed Break statement. Use this function with SalCompileAndEvaluate.


Return Value strContext serves as the last parameter of the SalCompileAndEvaluate function.

See Also SalCompileAndEvaluateSalContextCurrent

Example Set strContext = SalContextBreak ( )

SalContextCurrentSyntax strContext = SalContextCurrent ( )

Description Retrieves the current execution context. Use this function with SalCompileAndEvaluate.


Return Value strContext serves as the last parameter of the SalCompileAndEvaluate function.

See Also SalCompileAndEvaluateSalContextBreak

Example Set strContext = SalContextCurrent ( )

SalContextMenuSetPopupSyntax bOk = ( hWnd, strMenuName, nFlags)

Description Defines a named popup menu that displays automatically when a window receives SAM_ContextMenu.


SalCreateWindow

For some windows, this function also affects how the window processes a right mouse button click:

List box Right click selects the line under the cursor. If the line is already selected, there is no effect.

Combo box For a combo box where the list is always displayed, the behavior is the same as for a list box.

Table window Right click selects the row under the cursor. If the row is already selected there is no effect.

Parameters hWnd Window Handle. The handle of the lowest level window that processes messages that the popup menu sends.

strMenuName String. A named menu defined in one of the Named Menus section in hWnd, hWnd's MDI window parent, or Global Declarations.

nFlags 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.

Return Value bOk is TRUE if this function succeeds and FALSE otherwise.

Example No example.

See Also SAM_ContextMenu

SalCreateWindowSyntax hWndCreated = SalCreateWindow ( tWndToCreate, hWndOwner, Parm1,

Parm2, ... )

Description 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.



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.

Parm1 Any SQLWindows data type. The (optional) first of a variable number of window parameters.

Parm2 Any SQLWindows data type. The (optional) second of a variable number of window parameters.

Return Value hWndCreated is the handle of the new window.

See Also SalModalDialogSalDestroyWindow


If NOT SalCreateWindow (frmCustomer, hWndNULL)

...Error...

SalCreateWindowExSyntax hWndCreated = SalCreateWindowEx( tWndToCreate,

hWndOwner, nLeft, nTop, nWidth, nHeight, nFlags ... )

Description Creates a form, dialog box or table window as a child of another form or dialog box at runtime.



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 )


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.

nLeft, nTop Position of the window in form units.

nWidth, nHeight Size of the window in form units.

nFlags 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.

CREATE_Border When used with CREATE_AsChild, the window will have a border.

CREATE_Hidden The window will be created but not shown.





Return Value hWndCreated is the handle of the new window.

See Also SalModalDialogSalCreateWindowSalDestroyWindow


If NOT SalCreateWindowEx (frmCustomer, hWndNULL, nLeft, nTop, nWidth, nHeight)

...Error...

SalCursorClearSyntax bOk = SalCursorClear ( hWnd, nType )

Description Clears a window's cursor.

Parameters hWnd Window Handle. The handle (or name) of a window.

nType Number. The cursor type. Specify one of these constants:

CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorSetSalCursorSetFileSalCursorSetString


Call SalCursorClear (frmMain, Cursor_Windows)

SalCursorSetSyntax bOk = SalCursorSet ( hWnd, tResource, nType )

Description Sets a window's cursor.


tResource Template. An icon resource from the Resources section of the outline. Specify one of these system-supplied cursors:

CURSOR_Arrow


SalCursorSetFile

CURSOR_Cross

CURSOR_IBeam

CURSOR_Icon

CURSOR_Size

CURSOR_SizeNESW

CURSOR_SizeNS

CURSOR_SizeNWSE

CURSOR_SizeWE

CURSOR_UpArrow

CURSOR_Wait


CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorClearSalCursorSetFileSalCursorSetString


Call SalCursorSet (frmMain, Cursor_Arrow, Cursor_Window)

SalCursorSetFileSyntax bOk = SalCursorSetFile ( hWnd, sFile, nType )

Description Sets an application-defined cursor for the specified window. Use this function to set the cursor from an image stored in a file.


sFile String. The name of a cursor or an icon file.


CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorClear



SalCursorSetSalCursorSetString


Call SalCursorSetFile (frmMain, “file1.cne”, Cursor_Window)

SalCursorSetStringSyntax bOk = SalCursorSetString ( hWnd, sBuffer, nType )

Description Sets a window's cursor from a string variable.


sBuffer String. The image of a cursor or an icon file.


CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorClearSalCursorSetSalCursorSetFile


Call SalCursorSetString (frmMain, strCurBuf, Cursor_Window)

SalDateConstructSyntax dtDate = SalDateConstruct ( nYear, nMonth, nDay, nHour, nMinute, nSecond )

Description 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 Number. A number with a 4-digit year value greater than zero.

nMonth Number. A number with a 2-digit month value between 01 and 12 inclusive.


SalDateConstruct

nDay Number. A number with a 2-digit day value between 01 and 31 inclusive.

nHour Number. A number with a 2-digit hour value between 0 and 23 inclusive.

nMinute Number. A number with a 2-digit minute value between 01 and 59 inclusive.

nSecond Number. A number with a 2-digit second value between 01 and 59 inclusive.

Return Value dtDate is the newly constructed date/time value.


Set dtDeb = SalDateConstruct (1996, 1, 1, 10, 30, 1)



SalDateCurrentSyntax dtNow = SalDateCurrent ( )

Description 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.


Return Value dtNow is the PC's current date/time.


Set dfCurrent = SalDateCurrent ( )

SalDateDaySyntax nDay = SalDateDay ( dtDateTime )

Description Returns the day portion (1 to 31) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter.

Parameters dtDateTime Date/Time. A date/time value.

Return Value nDay is a number between 1 and 31.

See Also SalDateMonth

SalDateYear

Example Set nDay = SalDateDay ( dtDateTime )

SalDateHourSyntax nHour = SalDateHour ( dtDateTime )

Description Returns the hour portion (0 to 23) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter.


Return Value nHour is a number between 0 and 23.

See Also SalDateMinute

SalDateSecond

Example Set nHour= SalDateHour ( dtDateTime )

SalDateMinute


SalDateMonth

Syntax nMinute = SalDateMinute ( dtDateTime )

Description Returns the minute portion (0 to 59) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter.


Return Value nMinute is a number between 0 and 59.

See Also SalDateHour

SalDateSecond

Example Set nMinute = SalDateMinute ( dtDateTime )

SalDateMonthSyntax nMonth = SalDateMonth ( dtDateTime )

Description Returns the month portion (1 to 12) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter.


Return Value nMonth is a number between 1 and 12.

Related Functions

SalDateDaySalDateYear

Example Set nMonth = SalDateMonth ( dtDateTime )

SalDateMonthBeginSyntax dtMonthBegin = SalDateMonthBegin ( dtDateTime )

Description 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.


Return Value dtMonthBegin is the date of the first day of the month of dtDateTime.

See Also SalDateQuarterBeginSalDateWeekBegin

Example Set dtMonthBegin = SalDateMonthBegin ( SalDateCurrent ( ) )



SalDateQuarterSyntax nQuarter = SalDateQuarter ( dtDateTime )

Description 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.


Return Value nQuarter is a number between 1 and 4.

Example Select Case ( SalDateQuarter ( dtDate ) )

Case 1

Set strQuarter = 'First Quarter'

Break

...

SalDateQuarterBeginSyntax dtQuarterBegin = SalDateQuarterBegin ( dtDateTime )

Description 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.


Return Value dtQuarterBegin is the first day of the quarter of dtDateTime.

See Also SalDateMonthBeginSalDateWeekBeginSalDateYearBegin

Example Set dtQuarterBegin = SalDateQuarterBegin

( SalDateCurrent ( ) )

SalDateSecondSyntax nSeconds = SalDateSecond ( dtDateTime )

Description Returns the seconds portion (0 to 59) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter.


Return Value nSeconds is a number between 0 and 59.

See Also SalDateHourSalDateMinute


SalDateToStr

Example Set nSeconds = SalDateSecond ( dtDateTime )

SalDateToStrSyntax nLength = SalDateToStr ( dtDateTime, strDate )

Description Converts a date/time value to a string value or returns -1 if you specify DATETIME_Null as a parameter.

Parameters dtDateTime Date/Time. The date/time value to convert.

strDate Receive string. The resulting string value.

Return Value nLength is the length of strDate.

See Also SalFmtFormatDateTimeSalStrToDate

Example Call SalDateToStr ( dtDateTime, strDateTime )

! strDateTime = YYYY-MM-DD-HH.MM.SS.TTTTTT

SalDateWeekBeginSyntax dtWeekBegin = SalDateWeekBegin ( dtDateTime )

Description 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.


Return Value dtWeekBegin is the date of the previous Monday, or today's date if it is Monday.

See Also SalDateMonthBeginSalDateQuarterBeginSalDateYearBegin

Example Set dtWeekBegin = SalDateWeekBegin ( SalDateCurrent ( ) )

SalDateWeekdaySyntax nWeekday = SalDateWeekday ( dtDateTime )

Description 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.


Return Value



nWeekday is a number between 0 and 6.

Example Select Case ( SalDateWeekday ( dtDate ) )

Case 0

Set strWeekday = 'Saturday'

Break

SalDateYearSyntax nYear = SalDateYear ( dtDateTime )

Description Returns the year portion of a date or returns -1 if you specify DATETIME_Null as a parameter.


Return Value nYear is the year portion of a date.

See Also SalDateDaySalDateMonth

Example Set nYear = SalDateYear ( dtDateTime )

SalDestroyWindowSyntax bOk = SalDestroyWindow ( hWndDestroy )

Description 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.

Parameters hWndDestroy Window Handle. The handle (or name) of the window to destroy.


See Also SalCreateWindowSalEndDialog


Call SalDestroyWindow ( hWndForm )

SalDisableWindowSyntax bOk = SalDisableWindow ( hWndDisable )

Description Disables keyboard and mouse input to a window.


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 hWndDisable Window Handle. The handle (or name) of the window to disable.


See Also SalDisableWindowAndLabelSalEnableWindowSalIsWindowEnabled


Call SalDisableWindow ( pbUpdate )

SalDisableWindowAndLabelSyntax bOk = SalDisableWindowAndLabel ( hWndDisable )

Description 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 hWndDisable Window Handle. The handle (or name) of the window to disable.


See Also SalDisableWindow

SalEnableWindowAndLabel

SalIsWindowEnabled

SalGetWindowLabelText

SalHideWindowAndLabel

SalSetWindowLabelText

SalShowWindowAndLabel

Example Call SalDisableWindow ( dfName )



SalDlgChooseColorSyntax bRet = SalDlgChooseColor ( hWndOwner, nColor )

Description 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 Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner.

nColor Receive Number. The RGB value of the color the user selects.

Return Value bRet is TRUE if the user selects a color and FALSE if the user clicks the Cancel push button.

See Also SalDlgChooseFont


Call SalDlgChooseColor ( frmMain, nColor )

SalDlgChooseFontSyntax bRet = SalDlgChooseFont ( hWndOwner, strFontName, nSize, nEnhancements,

nColor )

Description 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.


strFontName Receive String. The name of the font the user selects.

nSize Receive Number. The size of the font the user selects.

nEnhancements Receive Number. The font enhancements (italic, bold, and so on), if any, that the user selects.

nColor 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.


SalDlgGetDockStatus

See Also SalDlgChooseColor

Example Call SalDlgChooseFont ( frmMain, strFontName,

nSize, nEnhancements )

SalDlgGetDockStatusSyntax bOk = SalDlgGetDockStatus ( hWndDlg, nOrientation )

Description Returns information about the current docking orientation of a dialog box.

Parameters hWndDlg Window Handle. The handle (or name) of the dialog box.

nOrientation 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 bRet is TRUE if the dialog box is found and FALSE if an error occurs.

See Also SalDlgSetDockStatus, SalWindowGetDockSettings

Example Call SalDlgGetDockStatus ( dlgPrompt, nDock )

SalDlgOpenFileSyntax bRet = SalDlgOpenFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex,

strFile, strPath )

Description Displays a Windows dialog box where the user can select a file to open.


strDlgTitle String. The title of the Open file dialog box.

strFilters 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 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.

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 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.

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.

Return Value bRet is TRUE if the user specifies a file name and FALSE if the user clicks the Cancel push button.

See Also SalDlgSaveFile

Example Message Actions

On SAM_Create



SalDlgSaveFile






strFilters, 6, nIndex, strFile, strPath)

Call SalDlgOpenFile ( frmMain, 'Open File', strFilters, 6, nIndex, strFile, strPath)

SalDlgSaveFileSyntax bRet = SalDlgSaveFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex,

strFile, strPath )

Description 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.


strDlgTitle String. The title of the Save file dialog box.

strFilters 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:







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.



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.


On SAM_Create







On SAM_Click

Call SalDlgSaveFile ( frmMain, 'Save File',

strFilters, 6,nIndex, strFile, strPath )

SalDlgSetDockStatusSyntax bOk = SalDlgSetDockStatus ( hWndDlg, nOrientation )

Description 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”


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 Window Handle. The handle (or name) of the dialog box.

nOrientation 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 bRet is TRUE if the docking operation is successful and FALSE if an error occurs.

See Also SalDlgGetDockStatus, SalWindowGetDockSettings

Example Call SalDlgSetDockStatus ( dlgPrompt, DOCK_Top )

SalDragDropDisableDropSyntax bOk = SalDragDropDisableDrop ( )

Disables dropping while in drag mode.



See Also SalDragDropEnableDrop


Call SalDragDropDisableDrop ()

SalDragDropEnableDrop



Syntax bOk = SalDragDropEnableDrop ( )

Description Enables dropping while in drag mode.



See Also SalDragDropDisableDrop


Call SalDragDropEnableDrop ()

SalDragDropGetSourceSyntax bOk = SalDragDropGetSource ( hWndSource, nX, nY )

Description Retrieves the handle of the source window and the location of the mouse in that window when you initiated drag mode.

Parameters hWndSource Receive Window Handle. The handle of the source window.

These window types can be source windows:

Combo box Multiline field

Data field Picture

List box Table window

nX Receive Number. The position of the mouse on the X axis.

nY Receive Number. The position of the mouse on the Y axis.


See Also SalDragDropGetTarget


Call SalDragDropGetSource (hWndSource,nX, nY)

SalDragDropGetTargetSyntax bOk = SalDragDropGetTarget ( hWndTarget, nX, nY )

Description Retrieves the handle of the target window and the location of the mouse in that window.

Parameters hWndTarget Receive Window Handle. The handle of the target window.


SalDragDropStart

Any SQLWindows window type can be a target window, however windows without actions (such as frames) do not receive SAM_Drag* messages.

nX Receive Number. The position of the mouse on the X axis.

nY Receive Number. The position of the mouse on the Y axis.


See Also SalDragDropGetSource


Call SalDragDropGetTarget (hWndRecv,nX, nY)

SalDragDropStartSyntax bOk = SalDragDropStart ( hWndSource )

Description Initiates drag mode. You must have one of the mouse buttons (left, middle, right) depressed.

Parameters hWndSource Window Handle. The handle (or name) of a window.


See Also SalDragDropStop


Call SalDragDropStart (frmMain)

SalDragDropStopSyntax bOk = SalDragDropStop ( )

Description Ends drag mode.

Parameters No parameter.


See Also SalDragDropStart

Example Set bOk = SalDragDropStop ( )

SalDrawMenuBarSyntax bOk = SalDrawMenuBar ( hWndForm )



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 hWndForm Window Handle. The handle (or name) of the form window or top-level table window whose menu bar you want to redraw.



Call SalDrawMenuBar ( frmMain)

SalDropFilesAcceptFilesSyntax bOk = SalDropFilesAcceptFiles ( hWnd, bAccept )

Description Indicates whether a window can accept a file from Windows' File Manager.


bAccept 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.


See Also SalDropFilesQueryFilesSalDropFilesQueryPoint

Example Set bAccept = SalDropFilesAcceptFiles ( hWnd, TRUR )

SalDropFilesQueryFilesSyntax nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )

Description 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.

Parameters hWndSource Window Handle. The handle (or name) of the window on which the files were dropped.

sArrayFiles Receive String Array. The names of the dropped files.


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.

See Also SalDropFilesAcceptFilesSalDropFilesQueryPoint


Set nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )



SalDropFilesQueryPointSyntax bOk = SalDropFilesQueryPoint ( hWnd, nX, nY )

Description 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.

Parameters hWnd Window Handle. The handle (or name) of the window on which files were dropped.

nX Receive Number. The location of the mouse on the X axis.

nY Receive Number. The location of the mouse on the Y axis.


See Also SalDropFilesAcceptFilesSalDropFilesQueryFiles


Call SalDropFilesQueryPoint ( hWnd, nX, nY )

SalEditCanCopyToSyntax bOk = SalEditCanCopyTo ( )

Description 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.


Return Value 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.

See Also SalEditCopyTo

Example Menu

Popup Menu: &Edit

Menu Item: &Copy To

...

Menu Settings

Enabled when: SalEditCanCopyTo ( )


SalEditCanCut

SalEditCanCutSyntax bOk = SalEditCanCut ( )

Description 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.


Return Value bOk is TRUE if data is selected and FALSE otherwise.

See Also SalEditCut

Example Menu Settings

Enabled when: SalEditCanCut ( )

...

SalEditCanPasteSyntax bOk = SalEditCanPaste ( )

Description 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 ValuebOk is TRUE if there is data on the Clipboard to be pasted and FALSE otherwise.

See Also SalEditPaste


Enabled when: SalEditCanPaste ( )

SalEditCanPasteFromSyntax bOk = SalEditCanPasteFrom ( )

Description 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.


Return ValuebOk is TRUE if an editable picture has the focus and FALSE otherwise.

See Also SalEditPasteFrom




Enabled when: SalEditCanPasteFrom ( )

SalEditCanUndoSyntax bOk = SalEditCanUndo ( )

Description 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 bOk is TRUE if there is any editing to undo and FALSE otherwise.

See Also SalEditUndo


Enabled when: SalEditCanUndo ( )

...

SalEditClearSyntax bOk = SalEditClear ( )

Description 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.





SalEditCopySyntax bOk = SalEditCopy ( )

Description Copies selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard.






SalEditCopyString

...

Menu Actions

Call SalEditCopy ( )

SalEditCopyStringSyntax bOk = SalEditCopyString ( strString )

Description Copies a string to the Clipboard as text.

Parameters strString String. The string to copy to the Clipboard.


See Also SalEditPasteString

Example Menu Actions

Call SalEditCopyString ( mlNotes )

SalEditCopyToSyntax bOk = SalEditCopyTo ( )

Description 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.



See Also SalEditCanCopyToSalEditPasteFrom


Call SalEditCopyTo ( )

SalEditCutSyntax bOk = SalEditCut ( )

Description Cuts selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard.





See Also SalEditCanCut



SalEditPasteSyntax bOk = SalEditPaste ( )

Description Pastes data from the Clipboard into the data field, multiline field, table window column, or picture with the focus.



See Also SalEditCanPaste


Call SalEditPaste ( )

SalEditPasteFromSyntax bOk = SalEditPasteFrom ( )

Description 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 File Extension Description

BMP . Device-Independent Bitmap

DIB .dib Device-Independent Bitmap

GIF .gif Graphics Interchange Format

ICON .ico Icon File

PCX .pcx Paintbrush

TIFF .tif Tag Image File Format

JPEG *.jpg JPEG format

WMF .wmf Windows MetaFile


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.



See Also SalEditCanPasteFrom


Call SalEditPasteFrom ( )

SalEditPasteStringSyntax bOk = SalEditPasteString ( strString )

Description Pastes the contents of the Clipboard into the specified string in text format.

Parameters strString Receive String. The string into which the contents of the Clipboard are pasted.


See Also SalEditCopyString

Example Call SalEditPasteString ( strOldClipboard )

SalEditUndoSyntax bOk = SalEditUndo ( )

Description 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.



See Also SalEditCanUndo


Enabled when: SalEditCanUndo ( )

SalEnableWindowSyntax bOk = SalEnableWindow ( hWndEnable )



Description Enables keyboard and mouse input to a window.

Parameters hWndEnable Window Handle. The handle (or name) of the window to enable.


See Also SalDisableWindowSalEnableWindowAndLabelSalIsWindowEnabled

Example Call SalEnableWindow ( frmCustomer )

SalEnableWindowAndLabelSyntax bOk = SalEnableWindowAndLabel ( hWndEnable )

Description 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 hWndEnable Window Handle. The handle (or name) of the window to enable.


See Also SalDisableWindowAndLabelSalEnableWindowWindowEnabled


Call SalEnableWindowAndLabel ( dfName )

SalEndDialogSyntax bOk = SalEndDialog ( hWndModal, nReturn )

Description Destroys a modal dialog box and returns control to the caller of SalModalDialog.

Parameters hWndModal Window Handle. The handle (or name) of the modal dialog box to destroy.

nReturn Number. The Return Value from the SalModalDialog function.


See Also SalModalDialog



SalEndTrace

Call SalEndDialog ( hWndForm, 0 )

SalEndTraceSyntax SalEndTrace ( )

Description Ends all tracing. Any calls to SalTrace() made after this function is called will be ignored.

Parameters none

Return Value none.

See Also SalStartTrace

SalTrace

Example No example

SalEventLogSetNameSyntax bOk = SalEventLogSetName ( strName )

Description 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 strName String. The name to use as the source in the event log.

Return Value bOk is TRUE if the function succeeds and FALSE if it fails


SalTrace

Example No example

SalFileClose



Syntax bOk = SalFileClose ( hFile )

Description Closes a file.

Parameters hFile Receive file handle. The handle of the file to close. When the function returns, the value of this parameter becomes null.


See Also SalFileOpen

Example If NOT SalFilePutStr ( hFile, sLine )

Call SalFileClose ( hFile )

Call SalMessageBeep ( 0 )

SalFileCopySyntax nStatus = SalFileCopy ( strSourcePath, strDestPath, bOverWrite )

Description Copies the contents of one file (source) to another file (destination).

Parameters strSourcePath String. The full path name of the source file.

strDestPath String. The full path name of the destination file.

bOverWrite 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_CopyDestFILE_CopyExistFILE_CopyOKFILE_CopyReadFILE_CopySrcFILE_CopyWrite


Set bLogFileSaved = SalFileCopy ( 'C:\\DB\\APP.LOG', ('C:\\DB\\APP.OLD', TRUE )


SalFileCreateDirectory

SalFileCreateDirectorySyntax bOk = SalFileCreateDirectory ( strDir )

Description Creates a directory.

Parameters strDir String. The full path name of the new directory.

Return Value 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.

See Also SalFileRemoveDirectory

Example Set DirCreated = SalFileCreateDirectory('C:\\NOTES\\REL2' )

SalFileGetCSyntax bOk = SalFileGetC ( hFile, nChar )

Description 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 File Handle. The handle of the open file.

nChar Receive Number. The next character in hFile.

Return Value 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.

See Also SalFilePutC


Call SalFileOpen ( hFile, 'C:\\DB\\APP.LOG',

OF_Read | OF_Binary )

SalFileGetCharSyntax nChar = SalFileGetChar ( hFile )

Description Returns the next character in an open file.


Return Value nChar is a number that represents an ANSI character. At the end of the file, SalFileGetChar returns a -1.



See Also SalFilePutChar

Example If SalFileOpen ( fhDestFile, strDestFile, OF_Create

| OF_ReadWrite )

Loop

Set nChar = SalFileGetChar ( fhSrcFile )

...

SalFileGetCurrentDirectorySyntax bOk = SalFileGetCurrentDirectory ( strPath )

Description Gets the full path name of the current working directory.

Parameters strPath Receive String. The full path name, including the drive letter, of the current working directory.


See Also SalFileSetCurrentDirectory


If NOT SalFileGetCurrentDirectory (strCurrentDir)

Call SalMessageBox ( 'Couldn't get current

directory', 'Error', 0 )

SalFileGetDateTimeSyntax bOk = SalFileGetDateTime ( strFilename, dtDateTime )

Description Gets the modification date and time of the specified file.

Parameters strFilename String. The name of the file whose modification date you want.

dtDateTime Receive Date/Time. The modification date and time of strFilename.


See Also SalFileSetDateTime

Example Set bOk = SalFileGetDateTime ( 'WIN.INI', gdFileDate )


SalFileGetDrive

SalFileGetDriveSyntax strDriveLetter = SalFileGetDrive ( )

Description Gets the letter of the default (current) disk drive.

No Parameters

Return Value 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(:).

See Also SalFileSetDrive


If SalFileGetDrive ( ) = 'A'

Set blsDriveA = TRUE

Else

Set blsDriveA = FALSE

SalFileGetStrSyntax bOk = SalFileGetStr ( hFile, strBuffer, nBufferSize )

Description Returns the next line from an open file. SQLWindows strips off the trailing carriage return/line feed of the returned string.


strBuffer Receive String. The returned string.

nBufferSize Number. The maximum number of bytes to read.

Return Value bOk is TRUE if the file is successfully read and FALSE otherwise. FALSE is also returned on end of file.

See Also SalFilePutStr

Example If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE )

Call SalFilePutStr ( fhDestFile, strText )

Else

Break



SalFileOpenSyntax bOk = SalFileOpen ( hFile, strFileName, nStyle )

Description Opens, re-opens, creates, or deletes a file.

Parameters hFile Receive File Handle. The handle of the open file.

strFileName String. The name of the file to open, create, delete, or test.

nStyle 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.


See Also SalFileClose

SalListFiles

SalFileOpenExt

Example Call SalFileOpen ( fhSrcFile, strSrcFile, OF_Read )

SalFileOpenExtSyntax bOk = SalFileOpenExt ( hFile, strFileName, nStyle, strReopen)

Description Opens or re-opens a file. Long filenames up to 260 characters is supported.

Parameters hFile Receive File Handle. The handle of the opened or re-opened file.

strFileName String. The name of the file to open, create, delete, or test.

nStyle 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.

strReopen Receive String. Information used to re-open the file.


See Also SalFileOpenF


If SalFileOpenExt ( hFile, 'C:\\AUTOEXEC.BAT', OF_Read,

strReopen )


SalFilePutC

SalFilePutCSyntax bOk = SalFilePutC ( hFile, nChar )

Description 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.


nChar Number. The non-ASCII or 16-bit numeric value of the character to write to hFile.

Return Value bOk is TRUE if the function succeeds and FALSE if it is unable to write to hFile.

See Also SalFileGetC

Example Loop

Call SalFilePutC ( hFile, nNull )

If nCount = 5

Break

Set nCount = nCount + 1

SalFilePutCharSyntax bOk = SalFilePutChar ( hFile, nChar )

Description Writes a character to an open file.


nChar Number. The ANSI numeric value of the character to write to hFile.


See Also SalFileGetChar

Example Call SalFileSeek (fhInFile, nFilePos, FILE,_SeekBegin)

Call SalFilePutChar ( hFile, nChar )



SalFilePutStrSyntax bOk = SalFilePutStr ( hFile, strString )

Description Writes a string to an open file. SQLWindows appends a carriage return/line feed character to the string.


strString String. The string to write.


See Also SalFileGetStr

Example 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 )

SalFileReadSyntax nResult = SalFileRead ( hFile, strBuffer, nBufferLength )

Description Reads a buffer of characters from an open file to a string .


strBuffer Receive String. The string to which the data is read.

nBufferLength Number. The number of bytes to read.

Return Value nResult is the number of bytes read. On end of file, SalFileRead returns a byte count less than the requested amount.

See Also SalFileWrite

Example Call SalFileSeek ( fhInFile, nFilePos, FILE_SeekBegin )

Loop

Set nCharsRead = SalFileRead ( fhInFile, strBuffer,

nRecSize )


SalFileRemoveDirectory

SalFileRemoveDirectorySyntax bOk = SalFileRemoveDirectory ( strDir )

Description Deletes a directory.

Parameters strDir String. The full path name of the directory to delete.

Return Value bOk is TRUE if the function succeeds and FALSE if it fails. SalFileRemoveDirectory also returns FALSE if strDir contains files or other directories.

See Also SalFileCreateDirectory


Set bNotesOldDeleted = SalFileRemoveDirectory (strDir)

SalFileSeekSyntax bOk = SalFileSeek ( hFile, nBytes, nPosition )

Description Positions the file pointer in an open file. The next file operation (such as a read or write) takes place at this new location.

Parameters hFile File Handle. The handle of an open file.

nBytes Number. The specific position of the file pointer; the number of bytes from nPosition where the next file operation will take place.

nPosition Number. The general position of the file pointer; one of the following values:

FILE_SeekBegin

FILE_SeekCurrent

FILE_SeekEnd


See Also SalFileTell

Example Call SalFileSeek ( fhInFile, 0, FILE_SeekBegin )



SalFileSetCurrentDirectorySyntax bOk = SalFileSetCurrentDirectory ( strPath )

Description 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.

Parameters strPath String. The path name of the new current working directory.


See Also SalFileGetCurrentDirectorySalFileSetDrive


Set DirOk = SalFileSetCurrentDirectory ('C:\\NOTES\\REL2' )

SalFileSetDateTimeSyntax bOk = SalFileSetDateTime ( strFilename, dtDateTime )

Description Sets the modification date and time of the specified file.

Parameters strFilename String. The name of the file whose modification date you want to set.

dtDateTime Date/Time. The modification date and time.


See Also SalFileGetDateTime


Set bOk = SalFileSetDateTime ('SQL.INI', SalDateCurrent ( ))

SalFileSetDriveSyntax bOk = SalFileSetDrive ( strDriveLetter )

Description Sets the current disk drive to the specified drive letter.

Parameters 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.


See Also SalFileGetDrive


SalFileTell

SalFileSetCurrentDirectory


Set bDriveIsC = SalFileSetDrive ( 'c' )

SalFileTellSyntax nPos = SalFileTell ( hFile )

Description Returns the current position in an open file.


Return Value nPos is the current position in hFile. If an error occurs, nPos is equal to -1.

See Also SalFileSeek

Example Set nRecPos = SalFileTell ( fhInFile)

SalFileWriteSyntax nResult = SalFileWrite ( hFile, strBuffer, nBufferLength )

Description Writes a string to an open file.


strBuffer String. The string to write to hFile.

nBufferLength Number. The number of bytes to write.

Return Value nResult is the number of bytes written.

See Also SalFileRead

Example Call SalFileWrite ( fhInFile, strCharBuf, 1 )

SalFmtFieldToStrSyntax bOk = SalFmtFieldToStr ( hWndField, strValue, bFormat )

Description 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.

Parameters 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.



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.

bFormat 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.


See Also SalFmtStrToField

Example On SAM_FieldEdit

Call SalFmtFieldToStr ( dfDateTime,dfDateString, TRUE )

SalFmtFormatDateTime Syntax strDateTime = SalFmtFormatDateTime ( dtDateTime, strPicture )

Description 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 Date/Time. The date/time value to format.

strPicture String. The date/time picture format.

Return Value strDateTime is the formatted date/time string.

See Also SalFmtFormatNumber SalFmtIsValidPicture

Example Set dtDateTime = 1992-02-14-00.00.00

Set strFormatted = SalFmtFormatDateTime ( dtDateTime,

strPicture )


SalFmtFormatNumber

SalFmtFormatNumber Syntax strNumber = SalFmtFormatNumber ( nNumber, strPicture )

Description 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.

Parameters nNumber Number. The number value to format.

strPicture String. The number picture format.

Return Value strNumber is a formatted number string.

See Also SalFmtFormatDateTime

SalFmtIsValidPicture

Example Set strNumber = SalFmtFormatNumber ( nNumber, strPicture )

SalFmtGetFormatSyntax nFormat = SalFmtGetFormat ( hWndField )

Description 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 date’s separator character and a subparameter that specifies the month/day/year sequence.

Parameters hWndField Window Handle. The handle (or name) of the data field or table window column to format.

Return Value 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_DateFMT_Format_DateTimeFMT_Format_PictureFMT_Format_TimeFMT_Format_Unformatted

Number fields can be formatted as:

FMT_Format_Format_CurrencyFMT_Format_Decimal



FMT_Format_PercentageFMT_Format_PictureFMT_Format_Unformatted

String fields can be formatted as:

FMT_Format_InvisibleFMT_Format_LowercaseFMT_Format_UppercaseFMT_Format_Unformatted

See Also SalFmtSetFormat


Enabled when:

Checked when: SalFmtGetFormat ( dfDateTime ) =

FMT_Format_Unformatted

SalFmtGetInputMask Syntax bOk = SalFmtGetInputMask ( hWnd, strMask )

Description 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 Window Handle. The handle (or name) of a combo box, data field, or table window column.

strMask Receive String. The input mask retrieved.

Return Value 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.

See Also SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask SalFmtUnmaskInput


Set bOk = SalFmtGetInputMask ( df1, df2 )

SalFmtGetPicture Syntax bOk = SalFmtGetPicture ( hWndField, strPicture )

Description Gets the picture format of a data field or table window column.


SalFmtIsValidField

Parameters hWndField Window Handle. The handle (or name) of the data field or table window column whose picture format you want.

strPicture Receive String. The picture format.

Return Value bOk is TRUE if the function succeeds, and FALSE if the data field or table window column is not picture-formatted.

See Also SalFmtSetPicture

Example Set bOk = SalFmtGetPicture ( hWndField, strPicture )

SalFmtIsValidField Syntax bValid = SalFmtIsValidField ( hWndField )

Description 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.

Parameters hWndField Window Handle. The handle (or name) of the data field or table window column whose contents you want to validate.

Return Value bValid is TRUE if the field's contents are valid and FALSE if the field's contents are invalid.

Example On SAM_Validate

If SalFmtIsValidField ( dfDateTime )

Call SalFmtValidateField ( dfDateTime,

FMT_Validate_None )

SalFmtIsValidInputMask Syntax bOk = SalFmtIsValidInputMask ( strMask )

Description Validates the input mask of a data field or table window column.


Parameters strMask String. An input mask.

Return Value bOk is TRUE if strMask is a valid input mask and FALSE if it is not valid.

See Also SalFmtGetInputMask SalFmtSetInputMask



SalFmtKeepMask SalFmtUnmaskInput


If SalFmtIsValidInputMask ( df1 )

Set df2 = 'Is Valid'

Else

Set df2 = 'Is Not Valid'

SalFmtIsValidPicture Syntax bOk = SalFmtIsValidPicture ( strPicture, nType )

Description Validates a number or date/time picture format.

These are examples of date/time picture formats:

These are examples of number picture formats:

Parameters strPicture String. The picture string.

Date/Time Picture Displayed Value

d MMMM, yyyy 9 January, 1989

dddd, MMMM d, yyyy Friday, February 7, 1989

M/d/yy 3/18/89

dd-MM-yyyy 18-03-1989

d "of " MMMM, yyyy 9 of January, 1989

M/d/yy-hh.mm.ss AMPM 2/3/91-12.23.15 AM

Number Picture Displayed Value

0.00% 7.00%

0.00e+00 3.65e+03

0.00e-00 3.65e03

$#,##0;($#,##0) $1,350

$#,##0;($#,##0) ($1,350)

0.00 95.00


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

Return Value bOk is TRUE if the picture format is valid and FALSE otherwise.

See Also SalFmtGetPicture

SalFmtSetPicture

Example Set strPicture = 'M/d/yy'

Set bValid = SalFmtIsValidPicture ( strPicture,

FMT_Pic_DateTime )

SalFmtKeepMask Syntax bRet = SalFmtKeepMask ( bKeep )

Description 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.


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 bRet is the value you specified in bKeep.

See Also SalFmtGetInputMask SalFmtIsValidInputMask



SalFmtSetInputMask SalFmtUnmaskInput

Example Set bRet = SalFmtKeepMask ( bKeep )

SalFmtSetFormatSyntax bOk = SalFmtSetFormat ( hWndField, nFormat )

Description 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 Window Handle. The handle (or name) of the data field or table window column whose format you want to set.

nFormat Number. The format for hWndField.

Return Value 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.

See Also SalFmtGetFormat

Example Set bOk = SalFmtSetFormat ( hWndField, nFormat )

SalFmtSetInputMask Syntax bOk = SalFmtSetInputMask ( hWnd, strMask )

Description Sets the input mask of a data field or table window column.



strMask String. The string that holds the input mask. If strMask is an empty string (''), SQLWindows sets hWnd to be unformatted.


See Also SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtUnmaskInput


SalFmtSetPicture

Example Set bOk = SalFmtSetInputMask ( hWnd, strMask )

SalFmtSetPicture Syntax bOk = SalFmtSetPicture ( hWndField, strPicture )

Description Sets the picture format of a data field or table window cell.

Parameters 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.

strPicture String. The picture format.

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 SalFmtGetPicture

Example Set bOk = SalFmtSetPicture ( hWndField, strPicture )

SalFmtStrToField Syntax bOk = SalFmtStrToField ( hWndField, strValue, bFormat )

Description Copies a string to a data field or table window column. After copying the string to the field, SQLWindows formats the string.

Parameters hWndField Window Handle. The handle (or name) of the data field or table window column to which the string is assigned.

strValue String. The string to copy.

bFormat Boolean. Specify whether (TRUE) or not (FALSE) the string value has the same format as the field.

Return Value 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.

See Also SalFmtFieldToStr


On SAM_FieldEdit



Call SalFmtStrToField ( dfDateTime, dfDateString,TRUE )


SalFmtUnmaskInput

SalFmtUnmaskInput Syntax bOk = SalFmtUnmaskInput ( hWnd, strInput )

Description 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.



strInput Receive String. The unmasked contents of hWnd.

Return Value 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.

See Also SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask

Example Set bOk = SalFmtUnmaskInput ( hWnd, strInput )

SalFmtValidateField Syntax bOk = SalFmtValidateField ( hWndField, nValidate )

Description 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 Window Handle. The handle (or name) of the data field or table window column to validate and format.

nValidate Number. A constant value that indicates what SQLWindows does if a format error occurs and the function returns FALSE:

Return Value 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.

Example If SalFmtIsValidField ( dfDateTime )



Call SalFmtValidateField ( dfDateTime,FMT_Validate_None )

Return VALIDATE_Ok

SalFontGetSyntax bOk = SalFontGet ( hWndFont, strName, nSize, nEnhancement )

Description Gets a window's font name, size, and enhancements.

Parameters hWndFont Window Handle. The handle (or name) of the window whose font information you want.

strName Receive String. The name of the font.

nSize Receive Number. The size of the font.

nEnhancment Receive Number. The font enhancements. To combine two or more of the FONT_Enh* constants, use the OR (|) operator.


See Also SalFontGetNamesSalFontGetSizesSalFontSet

Example If NOT SalFontGet ( hWndField, strFont, nSize, nEnhancement )

... Error ...

SalFontGetNamesSyntax nNames = SalFontGetNames ( nGet, strArrayFontNames )

Description Gets the names of the screen or printer fonts.

Parameters nGet Number. A constant that specifies whether to get the screen or printer fonts:

strArrayFontNames Receive String Array. The name of an array of strings that contains the font names returned.

Return Value nNames is the number of font names returned.

See Also SalFontGetSalFontGetSizesSalFontSet

Example Set nTotal = SalFontGetNames ( FONT_GetScreen, sFontNames )


SalFontGetSizes

SalFontGetSizesSyntax nSizes = SalFontGetSizes ( nGet, strFontName, nArrayFontSizes )

Description Gets the sizes of a screen or printer font.

Parameters nGet Number. Specify whether to get the sizes of a printer or screen font:

strFontName String. The name of the font.

nArrayFontSizes Receive Numeric Array. The name of an array of numbers that contains the font sizes (in points) returned.

Return Value nSizes is the number of font sizes returned.

See Also SalFontGetSalFontGetNamesSalFontSet

Example Set nTotal = SalFontGetSizes ( FONT_GetScreen, sFont, nSizes )

SalFontSetSyntax bOk = SalFontSet ( hWnd, strName, nSize, nEnhancement )

Description Sets a window's font, font size, and font enhancements.

Parameters hWnd Window Handle. The handle (or name) of the window whose font attributes you want to set.

strName String. The name of the font.

nSize Number. The size of the font (in points).

nEnhancment Number. The font enhancements. To specify two or more of the FONT_Enh* constants, combine them using the OR (|) operator.


See Also SalFontGetSalFontGetNamesSalFontGetSizes

Example Set bOk = SalFontSet ( hWnd, strName, nSize, nEnhancement )



SalFormGetParmNumSyntax bOk = SalFormGetParmNum ( hWndForm, nParm, nValue )

Description Returns the value of one of three form window parameters: height, width, or number of pages.

Parameters hWndForm Window Handle. The handle (or name) of the form window whose parameter value you want.

nParm Number. Specify form height, form width, or number of pages to return in nValue:

nValue Receive Number. The value of the form parameter requested.



Call SalFormGetParmNum ( frmMain, FORM_nFormPages,

dfPages )

SalFormUnitsToPixelsSyntax nNumPixels = SalFormUnitsToPixels ( hWnd, nFormUnits, bVertical )

Description 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.


nFormUnits Number. The number of form units.

bVertical 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.

Return Value nNumPixels is the number of pixels returned if the function succeeds. nNumPixels is zero (0) if hWnd is invalid.

See Also SalPixelsToFormUnits

Example Set nPixels = SalFormUnitsToPixels ( pbExample, nWidth, FALSE )


SalGetDataType

SalGetDataTypeSyntax nDataType = SalGetDataType ( hWnd )

Description 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 hWnd Window Handle. The handle (or name) of a data field or table window column.

Return Value 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).

See Also SalGetType

Example Set nType = SalGetType ( hWndChild )

If nType = TYPE_DataField

Set nDataType = SalGetDataType ( hWndChild )

SalGetDefButtonSyntax hWndDef = SalGetDefButton ( hWndParent )

Description 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.

Parameters hWndParent Window Handle. The handle (or name) of the form window or dialog box.

Return Value 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.

See Also SalSetDefButton


Set hWndDef = SalGetDefButton ( frmMain )

Call SalSetDefButton ( frmMain.pb2 )

Set hWndDef = SalGetDefButton ( frmMain )



SalGetFirstChildSyntax hWndChild = SalGetFirstChild ( hWndParent, nTypeMask )

Description 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.

Parameters hWndParent Window Handle. The handle (or name) of a form window, dialog box, or table window whose first child handle you want.

nTypeMask 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 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.

See Also SalGetNextChildSalGetType

Example Set hWndChild = SalGetFirstChild ( hWndCurrentFW, nTypeMask )

SalGetFocusSyntax hWndFocus = SalGetFocus ( )

Description Returns the handle of the window with the focus.


Return Value hWndFocus identifies the window that can currently receive input from the keyboard.

See Also SalSetFocus

Example Set hWndSave = SalGetFocus ( )

SalGetItemNameSyntax bOk = SalGetItemName ( hWnd, strText )

Description Gets the name of an object. Use SalGetItemName to qualify variables in SQL statements.

Parameters hWnd Window Handle. The handle of an object.

strText Receive String. The name of the object.


SalGetMaxDataLength


Example Call SalGetItemName ( hWndCurrent, strItemName )

Return strItemName

SalGetMaxDataLengthSyntax nDataLength = SalGetMaxDataLength ( hWndObject )

Description 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.

Parameters hWndObject Window Handle. The handle of a data field, multiline text field, or table window column.

Return Value 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’.

See Also SalSetMaxDataLength

Example Set nDataLen = SalGetMaxDataLength ( hWnddfCurrent )

SalGetNextChildSyntax hWndNextChild = SalGetNextChild ( hWndChild, nTypeMask )

Description 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 Window Handle. The handle (or name) of a child window. You can specify the return value of SalGetFirstChild.

nTypeMask 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.

See Also SalGetFirstChild



SalGetType

Example Set hWndChild = SalGetNextChild ( hWndChild, nTypeMask )

SalGetProfileInt Syntax nValue = SalGetProfileInt ( strSection, strEntry, nDefault, strFileName )

Description Retrieves the integer value of an entry in the specified section of an initialization file or registry.

Parameters strSection String. The section heading.

strEntry String. The entry whose associated value is being retrieved.

nDefault Number. Specify the default value (0 to 32,767) to return if the function cannot find the entry.

strFileName 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.

See Also SalGetProfileStringSalSetProfileStringSalUseRegistry

Example Set nValue = SalGetProfileInt ( strSection, strEntry, nDefault, strFileName )

SalGetProfileStringSyntax nBytes = SalGetProfileString ( strSection, strEntry, strDefault, strValue,

strFileName )

Description Retrieves the string value of an entry in the specified section of an initialization file or registry.


strEntry String. The entry whose associated value is being retrieved.

strDefault String. Specify the default value to return if the function cannot find the entry.


SalGetType

strValue Receive String. The value of strEntry. Maximum 1024 bytes.


Note: Specify the strFileName parameter as a NULL string when a company name is not necessary.

Return Value nBytes is the number of bytes copied to strValue, not including the terminating null character.

See Also SalGetProfileIntSalSetProfileStringSalUseRegistry

Example Set nBytes = SalGetProfileString ( strSection, strEntry,strDefault, strValue, strFileName )

SalGetTypeSyntax nType = SalGetType ( hWnd )

Description 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.

Parameters hWnd Window Handle. The handle of an object.

Return Value nType is a number that indicates the object's type. The value returned is one of a predetermined set of constants.

See Also SalGetFirstChildSalGetNextChild

Example Set nType = SalGetType ( hWndChild )

If nType = TYPE_DataField

Set nDataType = SalGetDataType ( hWndChild )



If nDataType = nHideDataType

Call SalHideWindow ( hWndChild )

SalGetVersionSyntax nType = SalGetVersion ( )

Description Returns the SQLWindows version. For example, SalGetVersion returns 300 for SQLWindows v3.0.0.


Return Value nType is a number that indicates the SQLWindows version number.


On SAM_Create

Set df1 = SalGetVersion ( )

SalGetWindowLabelTextSyntax nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )

Description Retrieves the background text of a window.

Important: The background text does not require a mnemonic for the functions listed above to operate.


strText Receive String. The window text.

nMaxLen Number. The maximum length of the window text.

Return Value nLength is a number that indicates the length of strText. nLength is zero (0) if the window has no text.

Example Set nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )

SalGetWindowLocSyntax bOk = SalGetWindowLoc ( hWnd, nX, nY )

Description Returns a window's current position on the X and Y axes.


nX Receive Number. The position of the window on the X axis, specified in SQLWindows form units.


SalGetWindowSize

nY Receive Number. The position of the window on the Y axis, specified in SQLWindows form units.


See Also SalSetWindowLoc

Example Call SalSetWindowLoc ( pbExample, 0, 0 )

Call SalGetWindowLoc ( pbExample, nX, nY )

SalGetWindowSizeSyntax bOk = SalGetWindowSize ( hWnd, nWidth, nHeight )

Description Returns a window's size.


nWidth Receive Number. The width of the window, specified in SQLWindows form units.

nHeight Receive Number. The height of the window, specified in SQLWindows form units.


See Also SalSetWindowSize

Example Call SalGetWindowSize ( pbExample, nWidth, nHeight )

Call SalSetWindowSize ( pbExample, nWidth+1, nHeight+1 )

SalGetWindowStateSyntax nState = SalGetWindowState ( hWnd )

Description Returns a window's current state.

Parameters hWnd Window Handle. The handle (or name) of a window. This function fails if you specify a window name that has not been created.

Return Value nState is a constant that indicates a window's current state. It is equal to one of a predefined set of values.


If SalGetWindowState ( fwDataWindow ) != Window_Normal

SalGetWindowLabel



Syntax hWndLabel = SalGetWindowText ( hWnd )

Description Retrieves the window handle of another window’s 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.


Return Value hWndLabel contains the window handle of the label if the function succeeds. If the function fails, it contains hWndNULL.

See Also SalGetWindowLabelTextSalTblGetColumnTitle

Example hWndLabel = SalGetWindowLabel ( dfUser )

SalGetWindowLabelText ( hWnd, sText, nMaxLength )Syntax nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )

Description 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.


No Example

SalGetWindowText Syntax nLength = SalGetWindowText ( hWnd, strText, nMaxLen )

Description 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.


SalHideWindow

Note: Use SalTblGetColumnTitle to get the title of a table window column.


strText Receive String. The window text.



See Also SalSetWindowTextSalTblGetColumnTitle

Example Call SalGetWindowText ( hWndForm, strfrmTitle, 50 )

SalHideWindowSyntax bOk = SalHideWindow ( hWndToHide )

Description Hides a window.

This function does not destroy the window; it only makes the window invisible.

Parameters hWndToHide Window Handle. The handle (or name) of a window to hide.


See Also SalBringWindowToTopSalShowWindow

Example Call SalHideWindow ( hWndChild )



SalHideWindowAndLabelSyntax bOk = SalHideWindowAndLabel ( hWndToHide )

Description Hides a window and its associated label.


This function does not destroy the window; it only makes the window invisible.

Parameters hWndToHide Window Handle. The handle (or name) of a window to hide.

Return Value 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.

See Also SalBringWindowToTopSalHideWindowSalShowWindowAndLabel

Example Set bOk = SalHideWindowAndLabel ( hWndToHide )

SalHStringToNumberSyntax nHString = SalHStringToNumber ( strString )

Description Converts a string handle to a number so you can pass it as a message parameter.

Parameters strString String. The string whose handle you want to change to a number.

Return Value nHString is a number that represents the converted string handle.

See Also SalNumberToHString

Example Set nHString = SalHStringToNumber ( strString )

SalIdleKickSyntax bOk = SalIdleKick( )

Description 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.


SalIdleRegisterWindow

Parameters None

ReturnValue bOk is TRUE if this function succeeds and FALSE otherwise.

See Also SalIdleRegisterWindow

SalIdleUnregisterWindow

SalIdleRegisterWindowSyntax bOk = SalIdleRegisterWindow( hWnd, iMsg, wParam, lParam )

Description 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.

Parameters hWnd Window Handle. The handle of the window to which to send the message.

iMsg Number. Message to send to the window. Usually this is a SAM_User message.

wParam Number. Standard message parameter that you can set.

lParam Number. Standard message parameter that you can set.


No Example

See Also SalIdleKick

SalIdleUnregisterWindow

SalIdleUnRegisterWindowSyntax bOk = SalIdleUnRegisterWindow( hWnd, )

Description Tells SQLWindows to stop sending idle messages to a window for which you have previously called SalIdleRegisterWindow.

Parameters hWnd Window Handle. The handle of the window on which you called SalIdleRegisterWindow.


No Example

See Also SalIdleKick

SalIdleRegisterWindow



SalInvalidateWindow Syntax bOk = SalInvalidateWindow ( hWndToPaint )

Description Causes a window to be repainted.

Parameters hWndToPaint Window Handle. The handle (or name) of a window to repaint.


See Also SalUpdateWindow

Example Set bOk = SalInvalidateWindow ( hWndToPaint )

SalIsButtonCheckedSyntax bIsSet = SalIsButtonChecked ( hWnd )

Description Determines whether a radio button is set or a check box is checked.

Parameters hWnd Window Handle. The handle (or name) of a radio button or check box.

Return Value bIsSet is TRUE if hWnd is set or checked and FALSE otherwise.

Example Set bIsSet = SalIsButtonChecked ( hWnd )

SalIsNullSyntax bNull = SalIsNull ( hWndIsNull )

Description Verifies whether a data field, multiline text field, or table window column is null or empty.

Parameters hWndIsNull Window Handle. The handle (or name) of a data field, multiline text field, or table window column.

Return Value bNull is TRUE if hWndIsNull is null or empty, and FALSE otherwise.

See Also SalClearField


If SalIsNull ( dfDateTime )

Call SalMessageBox ( 'You must enter a value',

'Validate Error', MB_Ok )

Return VALIDATE_Cancel

SalIsValidDateTime


SalIsValidDecimal

Syntax bOk = SalIsValidDateTime ( hWndField )

Description 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.

Parameters hWndField Window Handle. The handle (or name) of a data field, multiline text field, or table window column.

Return Value bOk is TRUE if hWndField contains a valid date/time value and FALSE otherwise.


If NOT SalIsValidDateTime ( dfDateTime )

SalIsValidDecimalSyntax bOk = SalIsValidDecimal ( hWndField, nPrecision, nScale )

Description 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.


nPrecision Number. The number of digits to display.

nScale Number. The number of digits to the right of the decimal point.

Return Value 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.

See Also SalIsValidIntegerSalIsValidNumber


If NOT SalIsValidDecimal ( dfDecimal, 5, 2 )

Call SalMessageBox ( 'Invalid decimal value', 'Validate



SalIsValidIntegerSyntax bOk = SalIsValidInteger ( hWndField )

Description 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.


Return Value 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.

See Also SalIsValidDecimalSalIsValidNumber


If NOT SalIsValidInteger ( dfInteger)

Call SalMessageBox ( 'Invalid integer value', 'Validate

Error', MB_Ok )

Return VALIDATE_Cancel

SalIsValidNumberSyntax bOk = SalIsValidNumber ( hWndField )

Description 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.


Return Value bOk is TRUE if hWndField contains a valid SQLBase number and FALSE otherwise.

See Also SalIsValidDecimalSalIsValidInteger


! Examples of valid numbers: 100, 100.123, -100

If NOT SalIsValidNumber ( dfNumber)

Call SalMessageBox ( 'Invalid number value', 'Validate Error', MB_Ok )


SalIsWindowEnabled

SalIsWindowEnabledSyntax bEnabled = SalIsWindowEnabled ( hWndEnabled )

Description Determines whether a window is enabled for mouse and keyboard input.

Parameters hWndEnabled Window Handle. The handle (or name) of a window.

Return Value bOk is TRUE if hWndEnabled is enabled and FALSE if hWndEnabled is not enabled or is not a valid handle.

See Also SalDisableWindowSalEnableWindow

Example If SalIsWindowEnabled ( pbUpdate )

Call SalDisableWindow ( pbUpdate )

SalIsWindowVisibleSyntax bOk = SalIsWindowVisible ( hWndVisible )

Description Determines whether a window is currently visible.

Parameters hWndVisible Window Handle. The handle (or name) of a window. Create a window first before using a window template as a parameter.

Return Value bOk is TRUE if the window is visible and FALSE otherwise.

See Also SalHideWindowSalShowWindow

Example Set bOk = SalIsWindowVisible ( hWndVisible )

SalListAdd Syntax nIndex = SalListAdd ( hWndList, strName )

Description 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 Window Handle. The handle (or name) of a list box or combo box.

strName String. The string to add.



Return Value 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.

See Also SalListInsertSalListPopulate

Example Call SalListAdd ( hWndlbCurrent, strLBItem )

SalListClearSyntax bOk = SalListClear ( hWndList )

Description Deletes all entries from a list box or combo box.



Example Call SalListClear ( lbProducts )

SalListDeleteSyntax nRemaining = SalListDelete ( hWndList, nIndex )

Description Deletes a list box or combo box entry.


nIndex Number. The index of the entry to delete.

Return Value 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.

Example Set nCount = SalListDelete ( hWndlbCurrent, nLBIdx )

SalListFilesSyntax bOk = SalListFiles ( hWndList, hWndPath, strPathName, nFlags )

Description 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.


hWndPath Window Handle. The handle (or name) of the data field that displays the current directory and drive of the files listed in hWndList.


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.

nFlags Number. The type of file access. You can combine FA_* constants with the OR (|) operator to create this value.


See Also SalFileOpen

Example Call SalListFiles ( hWndLB, hWndLoadPath, strLoadPath,nFileAttrib )

SalListGetMultiSelectSyntax bOk = SalListGetMultiSelect ( hWndList, nSelectedArray )

Description 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 Window Handle. The handle (or name) of a list box.

nSelectedArray Receive Numeric Array. The name of an array of index numbers of selected list box entries.

Return Value bOk is TRUE if the function succeeds and FALSE if hWndList or nSelectedArray are not valid, or if no list box entries are selected.

Example Call SalListGetMultiSelect ( lbExample, nSelectedArray )

SalListInsertSyntax nIndex = SalListInsert ( hWndList, nIndex, strAdd )

Description Inserts an entry into a list box or combo box at a specified position.


nIndex 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.

strAdd String. The string to insert.

Return Value 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.



See Also SalListAdd

Example Call SalListInsert ( hWndLB, -1, strInsertStr )

SalListPopulateSyntax bOk = SalListPopulate ( hWndList, hSql, strSelect )

Description 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 Window Handle. The handle (or name) of the list box or combo box to populate.

hSql Sql Handle. The handle of a SELECT statement.

strSelect 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 bOk is TRUE if the function succeeds and FALSE if any of the parameters are invalid or if strSelect contains INTO variables.

See Also SalListAddSalListInsert


Call SalListPopulate ( lbExample, hSql, 'select

name, trainer, room ' || 'from guest_roster' )

SalListQueryCountSyntax nEntries = SalListQueryCount ( hWndList )

Description Returns the number of list box or combo box entries.



SalListQueryFile

Return Value nEntries is the number of entries in hWndList. SalListQueryCount returns LB_Er if an error occurs.

Example If NOT SalListQueryCount ( hWndlbCurrent )

Return FALSE

SalListQueryFileSyntax bDirectory = SalListQueryFile ( hWndList, strFileName )

Description Fetches the selected directory or file name from a list box or combo box.


strFileName Receive String. The directory or file name being fetched.

Return Value bDirectory is TRUE if strFileName is the name of a directory and FALSE if it is the name of a file.

Example Call SalListQueryFile ( hWndLB, strFileName )

SalListQueryMultiCountSyntax nSelected = SalListQueryMultiCount ( hWndList )

Description 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 hWndList Window Handle. The handle (or name) of a multiple-selection list box.

Return Value 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.

Example Set nSelected = SalListQueryMultiCount ( lbExample )

SalListQuerySelectionSyntax nIndex = SalListQuerySelection ( hWndList )

Description Returns the index of the selected entry in a combo box or single-selection list box.




Note: For an example of getting a list of selected entries in a multiple-selection list box, see SalListQueryState.

Parameters hWndList Window Handle. The handle (or name) of a combo box or single-selection list box.

Return Value 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.

See Also SalListGetMultiSelectSalListQueryState

Example Set nLBIdx = SalListQuerySelection (hWndlbCurrent )

SalListQueryStateSyntax bSelected = SalListQueryState ( hWndList, nIndex )

Description Determines whether the specified list box or combo box entry is selected.


nIndex Number. The index of the list box or combo box entry.

Return Value bSelected is TRUE if the nIndex entry is selected and FALSE if the entry is not selected or an error occurs.

Example 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 Fetches a list box or combo box entry.




SalListQueryTextLength

Return Value strText is the fetched list box or combo box entry.

Example Set strRecv = SalListQueryTextx ( hWnddbCurrent, nLBIdx )

SalListQueryTextLengthSyntax nLength = SalListQueryTextLength ( hWndList, nIndex )

Description Returns the length of a list box or combo box entry.



Return Value nLength is the length of the string. SalListQueryTextLength returns LB_Err if an error occurs.

Example Set nLBItemLen = SalListQueryTextLength (hWndlbCurrent, nLBIdx)

SalListQueryTextXSyntax strText = SalListQueryTextX ( hWndList, nIndex )

Description Fetches a list box or combo box entry.



strText Receive String. The string to which the entry is fetched.

Return Value 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 )

SalListRedrawSyntax bOk = SalListRedraw ( hWndList, bRedraw )

Description 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 .




bRedraBoolean. If TRUE, SQLWindows redraws the list box or combo box contents; if FALSE, SQLWindows does not.

Return Value bOk is TRUE if the function succeeds and FALSE otherwise, such as when hWndList is not a valid handle.


Call SalListRedraw ( lbList, FALSE )

SalListSelectStringSyntax nIndex = SalListSelectString ( hWndList, nIndexStart, strText )

Description 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.


nIndexStart Number. The index at which to start the search. The search begins at row nIndexStart + 1.

strText String. The string to search for.

Return Value 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.

Example Set nIdx = SalListSelectString ( hWndLB, 0, strFindStr )

If nIdx = LB_Err

Call SalListInsert ( hWndLB, -1, strInsertStr )

Else

Call SalListInsert ( hWndLB, nIdx + 1, strInsertStr )

SalListSetMultiSelectSyntax bOk = SalListSetMultiSelect ( hWndList, nIndex, bSelect )

Description Selects or deselects a combo box or multiple-selection list box entry.


SalListSetSelect


Parameters hWndList Window Handle. The handle (or name) of a combo box or multiple-selection list box.

nIndex 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.

bSelect Boolean. Specify whether to select (TRUE) or deselect (FALSE) the nIndex entry.


Example Call SalListSetMultiSelect ( lbExample, 5, TRUE )

SalListSetSelectSyntax bOk = SalListSetSelect ( hWndList, nIndex )

Description Selects or deselects a combo box or single-selection list box entry.



nIndex Number. The index of the entry to select. If you specify -1, SQLWindows deselects the entry.

Return Value bOk is TRUE if the function succeeds and FALSE if it fails. bOk is equal to LB_Err if an error occurs.

Example Call SalListSetSelect ( hWndLB, 0 )

SalListSetTabsSyntax bOk = SalListSetTabs ( hWndList, nArrayTabStops )

Description 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.

Parameters hWndList Window Handle. The handle (or name) of a list box.

nArrayTabStops Numeric Array. The name of an array of numbers that represent tabs. Specify tabs in inches.





Set nTabStops[0] = 2

Set nTabStops[1] = 3

Call SalListSetTabs ( hWndItem, nTabStops )

Call SalListAdd ( hWndItem, 'aaa'||TAB||'aaaa'||TAB||'aaaaa' )

SalLoadAppSyntax bOk = SalLoadApp ( strAppName, strParameters )

Description Starts an application.

Parameters strAppName String. The name of the application to start.

strParameters String. Optional command line arguments.

See the SAL chapter of Developing with SQLWindows for information about command line arguments.

Return Value bOk is TRUE if the function succeeds and FALSE if SQLWindows cannot find the application or cannot start it.

See Also SalLoadAppAndProcessMsgsSalLoadAppAndWait


Call SalLoadApp ( 'DBWINDOW.EXE','' )

SalLoadAppAndWaitSyntax bOk = SalLoadAppAndWait ( strAppName, nMode, nRet )

Description Starts an application, then waits for it to exit before returning control to the original application.

Parameters 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_MaximizedWindow_MinimizedWindow_Normal


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++.


See Also SalLoadAppSalLoadAppAndProcessMsgs


Call SalLoadAppAndWait (‘DBWindow.EXE’, WINDOW_Normal, nRecstatus)

SalLoadAppAndProcessMsgsSyntax bOk = SalLoadAppAndProcessMsgs ( strAppName, nMode, nRet )

Description 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.

Parameters 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_MaximizedWindow_MinimizedWindow_NormalWindow_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++.


See Also SalLoadAppSalLoadAppAndWait

Example None

SalMapEnterToTabSyntax bOk = SalMapEnterToTab ( bState )

Description 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.

Parameters 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 bOk is TRUE if the function succeeds and FALSE if you do not specify a Boolean value.

Example Set bOk = SalMapEnterToTab ( bState )


SalMDIArrangeIcons

SalMDIArrangeIcons Syntax bOk = SalMDIArrangeIcons ( hWndMDI )

Description Arranges minimized child window icons in an MDI window.

Parameters hWndMDI Window Handle. The handle of an MDI window.


See Also SalMDICascadeSalMDITile


Call SalMDIArrangeIcons ( hWndMDI )

SalMDICascadeSyntax bOk = SalMDICascade ( hWndMDI )

Description Cascades all non-iconized child windows of an MDI window.



See Also SalMDIArrangeIconsSalMDITile


Call SalMDICascade ( hWndMDI )

SalMDITileSyntax bOk = SalMDITile ( hWndMDI, bPosition )

Description Tiles all non-iconized child windows of an MDI window. Windows that are not sizable will not be tiled.


bPosition Boolean. How to tile the child windows. If TRUE, tile the windows vertically; if FALSE, tile the windows horizontally.


See Also SalMDIArrangeIconsSalMDICascade




Call SalMDITile ( hWndMDI, FALSE )

SalMessageBeepSyntax bOk = SalMessageBeep ( nAlertLevel )

Description 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.

Parameters nAlertLevel Number. The alert level:

0xFFFFFFFF (-1)Standard beep using the computer speaker.

MB_IconAsterisk

MB_IconExclamation

MB_IconStop

MB_IconQuestion

MB_Ok


See Also SalMessageBox

Example Call SalMessageBeep ( -1 )

SalMessageBoxSyntax nResult = SalMessageBox ( strText, strTitle, nFlags )

Description 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 String. The message text. You can enter multiple lines of text by pressing CTRL-ENTER to start a new line.

strTitle String. The message box title.

nFlags 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.


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 nResult is the value of the push button the user clicks.

See Also SalMessageBeep

Example Set nResult = SalMessageBox ( strText, strTitle, nFlags )



SalModalDialog Syntax nReturn = SalModalDialog ( tDlgBoxToCreate, hWndOwner, Parm1, Parm2, ...)

Description Creates a modal dialog box.


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.


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 Window Handle. The handle (or name) of the owner window. Use hWndNULL for a dialog box that does not have an owner.



Return Value nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created.

See Also SalEndDialogSalModalDialogFromStr

Example Call SalModalDialog ( dlgAboutBox, hWndForm )


SalModalDialogFromStr

SalModalDialogFromStrSyntax nReturn = SalModalDialogFromStr ( strName, hWndOwner, Parm1, Parm2, ... )

Description 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 String. The name of the modal dialog box to create.

hWndOwner Window Handle. The handle (or name) of the owner window. Use hWndNULL for dialog boxes that do not have owners.

Parm1 Any SQLWindows data type. The (optional) first of a variable number of window parameters. The window parameters must be defined in the dialog.

Parm2 Any SQLWindows data type. The (optional) second of a variable number of window parameters. The window parameters must be defined in the dialog.

Return Value nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created.

See Also SalModalDialog

Example Set nReturn = SalModalDialogFromStr ( tDlgBoxToCreate,hWndOwner )

SalMoveWindowSyntax bOk = SalMoveWindow ( hWndToMove, nXOffset, nYOffset )

Description Moves a window a given number of form units on the X and Y axes relative to its current position.

Parameters hWndToMove Window Handle. The handle (or name) of the window to move.

nXOffset Number. The number of form units to move the window on the X axis.

nYOffset Number. The number of form units to move the window on the Y axis.

Return Value bOk is TRUE if the function succeeds, and FALSE if hWndToMove is invalid.

See Also SalCenterWindow



Example Call SalMoveWindow ( pbExample, 1,1 )

SalMTSCreateInstanceSyntax bOk = SalMTSCreateInstance( oObj )

Description Creates a new component. Depending on the Transaction settings this component will continue the current transaction, will start a new transaction, or will under non-transactional state.

For non-MTS components the SalMTSCreateInstance() will work as Create().

Parameters oObj Object/Interface. The requested interface/object to be instantiated.

Return Value Returns TRUE if the object gets successfully instantiated, otherwise returns FALSE.

Example Variable:Stocks: objStocksAccounts: objAccountsBoolean: bRet

Actions:Call SalMTSCreateInstance(objStocks)Call objStocks.Buy(UserID, sTicker, nShares)// changes Transactions

tableCall 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()

SalMTSDisableCommitSyntax bOk = SalMTSDisableCommit( )

Description 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 None.

Return Value Returns TRUE if successful, returns FALSE if it fails.

Example Set bRet = SalMTSDisableCommit()


SalMTSEnableCommit

SalMTSEnableCommitSyntax bOk = SalMTSEnableCommit( )

Description Indicates that the object’s 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 None.


Example Set bRet = SalMTSEnableCommit()

SalMTSGetObjectContextSyntax bOk = SalMTSGetObjectContext(Ctx )

Description Gets the explicit object context Ctx.

For non-MTS components the SalMTSGetObjectContext() will fail (returns FALSE).

Parameters Ctx Receive Number. The current object context.


Example Number: nCtxBoolean: bRet

Set bRet = SalMTSGetObjectContext(nCtx)If bRetCall ExtFunc(nCtx, ...)

SalMTSIsCallerInRoleSyntax bOk = SalMTSIsCallerInRole( strRole, bFound )

Description This function checks if the current caller is listed in the role strRole.

Parameters strRole ) String. The name of the role.

bFound Receive Boolean. TRUE if the component's caller is a member of the specified role.

Return Value 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.



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 doesn’t exist or the call failed', MB_Ok)

SalMTSInTransactionSyntax bOk = SalMTSIsInTransaction( bIsInTransaction )

Description This method checks if the component is executing in the transaction context.

For non-MTS components the SalMTSIsInTransaction() will fail (returns FALSE).

Parameters bIsInTransaction Receive Boolean. TRUE if the component is executing in the transaction context.

Return Value Returns TRUE if the component is in a transaction; returns FALSE otherwise.

Example Boolean: bIsInTransaction

Call SalMTSIsInTransaction(bIsInTransaction)

If (bIsInTransaction)

Call SalMTSSetComplete()

Else

Call SqlCommit()

SalMTSSecurityEnabledSyntax bOk = SalMTSIsSecurityEnabled( bIsSecurityEnabled )

Description 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).


SalMTSSetAbort

Parameters bIsSecurityEnabled Receive Boolean. TRUE if the security is enabled.

Return Value Returns TRUE if declarative security is enabled for the component; returns FALSE otherwise.

Example Boolean: bIsSecurityEnalbed

Boolean: bRet

Set bRet = SalMTSIsSecurityEnabled(bIsSecurityEnabled)

SalMTSSetAbortSyntax bOk = SalMTSSetAbort( )

Description Indicates that the object’s 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 None.


Example Set bRet = SqlExecute(hSql)

If Not bRet

Call SalMTSSetAbort()

Else

Call SamMTSSetComplete()

SalMTSSetCompleteSyntax bOk = SalMTSSetComplete( )

Description 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 None.


Example Set bRet = SqlExecute(hSql)

If Not bRet

Call SalMTSSetAbort()



Else

Call SamMTSSetComplete()

SalNumberAbsSyntax nNum = SalNumberAbs ( nValue )

Description Computes a number's absolute value.

Parameters nValue Number. The number whose absolute value you want.

Return Value nNum is the absolute value of nValue.


Set nNum1 = SalNumberAbs ( -12 )

SalNumberArcCosSyntax nArcCos = SalNumberArcCos ( nValue )

Description Computes the arccosine of a value in the range 0 to 1. The value's domain is -1 to 1.

Parameters nValue Number. The number whose arccosine you want.

Return Value nArcCos is the arccosine of nValue. It is NUMBER_Null if nValue is less than -1 or greater than 1.


Set nNum1 = SalNumberArcCos ( 1 )

SalNumberArcSinSyntax nArcSin = SalNumberArcSin ( nValue )

Description Computes a value's arcsine. The value's domain is -1 to 1.

Parameters nValue Number. The number whose arcsine you want.

Return Value nArcSin is the arcsine of nValue. nArcSin is NUMBER_Null if nValue is less than -1 or greater than 1.


Set nNum1 = SalNumberArcSin ( 1 )


SalNumberArcTan

SalNumberArcTanSyntax nArcTan = SalNumberArcTan ( nValue )

Description Computes a value's arctangent.

Parameters nValue Number. The number whose arctangent you want.

Return Value nArcTan is the arctangent of nValue. nArcTan is in the range -1 to 1.

See Also SalNumberArcTan2

Example On SAM_ClickSet nNum1 = SalNumberArcTan ( 1 )

SalNumberArcTan2Syntax nArcTan2 = SalNumberArcTan2 ( nValueY, nValueX )

Description Computes the arctangent of two values. This function uses the signs of both parameters to determine the quadrant of the return value.

Parameters nValueY Number. One of two values whose arctangent you want.

nValueX Number. The other of two values whose arctangent you want.

Return Value nArcTan2 is the arctangent of nValueY and nValueX. nArcTan2 is in the range -1/2 to 1/2.

See Also SalNumberArcTan

Example On SAM_ClickSet nNum1 = SalNumberArcTan2 ( 1, 0 )

SalNumberCosSyntax nCos = SalNumberCos ( nAngle )

Description Computes an angle's cosine. You must specify the angle in terms of radians.

Parameters nAngle Number. The value of the angle whose cosine you want.

Return Value 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).

See Also SalNumberCosH




Set nNum1 = SalNumberCos ( 0 )

SalNumberCosHSyntax nCosH = SalNumberCosH ( nAngle )

Description Computes an angle's hyperbolic cosine. You must specify the angle in terms of radians.

Parameters nAngle Number. The value of the angle whose hyperbolic cosine you want.

Return Value nCosH is the hyperbolic cosine of nAngle. If the return value is too large, nCosH equals zero (0).

See Also SalNumberCos

Example On SAM_ClickSet nNum1 = SalNumberCosH ( 0 )

SalNumberExponentSyntax nNumExp = SalNumberExponent ( nValue )

Description Computes a value's exponential function.

Parameters nValue Number. The value whose exponential function you want.

Return Value nNumExp is the result of 'e' to the power of nValue. When there is an underflow or overflow, nNumExp is equal to NUMBER_Null.

Example On SAM_ClickSet nNumExp = SalNumberExponent ( 2.302585093 )

SalNumberHighSyntax nHi = SalNumberHigh ( nValue )

Description Returns a number's high-order word value (most significant 16 bits).

Parameters nValue Number. The number whose high-order word value you want. SQLWindows treats nValue as an unsigned 32-bit number.

Return Value nHi is the high-order word value of nValue.

See Also SalNumberLow

VisNumberMakeLong (in Visual Toolchest section of online help)


SalNumberHypot

Example On SAM_ClickSet nHi = SalNumberHigh ( 0xffffaaaa )

SalNumberHypotSyntax nHypotenuse = SalNumberHypot ( nX, nY )

Description Computes the length of the hypotenuse of a right triangle, given the lengths of the other two sides.

Parameters nX Number. The length of one side of a right triangle.

nY Number. The length of another side of a right triangle.

Return Value 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).

Example On SAM_ClickSet nHypotenuse = SalNumberHypot ( 3, 4 )

SalNumberLogSyntax nLog = SalNumberLog ( nValue )

Description Computes a number's natural logarithm.

Parameters nValue Number. The number whose natural logarithm you want.

Return Value nLog is the natural logarithm of nValue. If nValue is negative or 0, nLog is equal to NUMBER_Null.

See Also SalNumberLogBase10

Example On SAM_ClickSet nLog = SalNumberLog ( 1000 )

SalNumberLogBase10Syntax nLogBase10 = SalNumberLogBase10 ( nValue )

Description Computes a number's base -10 logarithm.

Parameters nValue Number. The number whose base -10 logarithm you want.

Return Value nLogBase10 is the base-10 logarithm of nValue. If nValue is negative or 0, nLogBase10 is equal to NUMBER_Null.

See Also SalNumberLog



Example On SAM_ClickSet nLogBase10 = SalNumberLogBase10 ( 1000 )

SalNumberLowSyntax nLo = SalNumberLow ( nValue )

Description Returns a number's low-order word value (least significant 16 bits).

Parameters nValue Number. The number whose low-order word value you want. SQLWindows treats nValue as an unsigned 32-bit number.

Return Value nLo is the low-order word value of nValue.

See Also SalNumberHigh

VisNumberMakeLong (in Visual Toolchest section of online help)

Example On SAM_ClickSet nLo = SalNumberLow ( 0xffffaaaa )

SalNumberMaxSyntax nNumMax = SalNumberMax ( nVal1, nVal2 )

Description Returns the greater of two values.

Parameters nVal1 Number. The first of two values.

nVal2 Number. The second of two values.

Return Value nNumMax is the greater of nVal1 and nVal2.

See Also SalNumberMin

Example On SAM_ClickSet nNumMax = SalNumberMax ( 1765.2, -2 )

SalNumberMinSyntax nNumMin = SalNumberMin ( nVal1, nVal2 )

Description Returns the lesser of two values.

Parameters nVal1 Number. The first value.

nVal2 Number. The second value.

Return Value nNumMin is the lesser of nVal1 and nVal2.


SalNumberMod

See Also SalNumberMax

Example On SAM_ClickSet nNumMin = SalNumberMin ( 1765.2, -2 )

SalNumberModSyntax nModulo = SalNumberMod ( nNumber, nNumberMod )

Description Returns a number's modulo. This function divides nNumber by nNumberMod and returns the remainder.

ParameternNumber Number. The number to divide.

nNumberMod Number. The number by which to divide nNumber.

Return Value nModulo is the remainder of nNumber divided by nNumberMod.

Example On SAM_ClickSet nNumber = SalNumberMod ( 5, 2 )

SalNumberPiSyntax nNumPi = SalNumberPi ( nValue )

Description Multiples a number by Pi. Pi is equal to 3.1415926535979323.

Parameters nValue Number. The number to multiply by Pi.

Return Value nNumPi is nValue multiplied by Pi.

Example On SAM_ClickSet nNumPi = SalNumberSin ( SalNumberPi ( 1 ) /2 )

SalNumberPowerSyntax nNumPower = SalNumberPower ( nX, nY )

Description 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.

Parameters nX Number. The number to raise to the power of nY.

nY Number. The exponent.

Return Value nNumPower is equal to nX raised to the nYth power, with the following conditions:



1. If nX is not 0 and nY is 0, nNumPower is equal to 1.

2. If nX is 0 and nY is negative, nNumPower is equal to zero (0).

3. 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.

4. In instances where an overflow or an underflow occurs, nNumPower is equal to zero (0).

Example On SAM_ClickSet nNumPow = SalNumberPower ( 2, 3 )

SalNumberRandInitSyntax bOk = SalNumberRandInit ( nSeed )

Description 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 nSeed Number. The starting point. A whole number in the range of 0 to 32767.


See Also SalNumberRandom

Example On SAM_ClickCall SalNumberRandInit ( 12 )

SalNumberRandomSyntax nRandomNum = SalNumberRandom ( )

Description Generates a pseudo-random number. The numbers generated by this function are integers (whole numbers) in the range 0 to 32767 (0 to 0x7FFF).


Return Value nRandomNum is a pseudo-random number.

See Also SalNumberRandInit


SalNumberRound

Example On SAM_ClickCall SalNumberRandInit ( 12 )Set nRandNum = SalNumberRandom ( )

SalNumberRoundSyntax nResult = SalNumberRound ( nNumber )

Description 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 nNumber Number. The number to round.

Return Value nResult is nNumber after rounding.

Example On SAM_ClickSet nNumber = SalNumberRound ( 124.5 )

SalNumberSinSyntax nSin = SalNumberSin ( nAngle )

Description Computes an angle's sine. You must specify the angle in terms of radians.

Parameters nAngle Number. The value of the angle whose sine you want.

Return Value 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).

See Also SalNumberSinH

Example On SAM_ClickSet nNum = SalNumberSin ( SalNumberPi ( 1 ) /2 )

SalNumberSinHSyntax nSinH = SalNumberSinH ( nAngle )

Description Computes an angle's hyperbolic sine. You must specify the angle in terms of radians.

Parameters nAngle Number. The value of the angle whose hyperbolic sine you want.



Return Value nSinH is the hyperbolic sine of nAngle. If the angle is too large, nSinH is equal to zero (0).

See Also SalNumberSin

Example On SAM_ClickSet nNum = SalNumberSinH ( 0 )

SalNumberSqrtSyntax nSqrt = SalNumberSqrt ( nValue )

Description Computes a number's square root.

Parameters nValue Number. The number whose square root you want.

Return Value 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).

Example On SAM_ClickSet nSqrt = SalNumberSqrt ( 36 )

SalNumberTanSyntax nTan = SalNumberTan ( nAngle )

Description Computes an angle's tangent. You must specify the angle in terms of radians.

Parameters nAngle Number. The value of the angle whose tangent you want.

Return Value 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).

See Also SalNumberTanH

Example On SAM_ClickSet nNum = SalNumberTan ( SalNumberPi ( 1 ) / 4 ) )

SalNumberTanHSyntax nTanH = SalNumberTanH ( nAngle )

Description Computes an angle's hyperbolic tangent. You must specify the angle in terms of radians.

Parameters nAngle Number. The value of the angle whose hyperbolic tangent you want.


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).

See Also SalNumberTan

Example On SAM_ClickSet nNum = SalNumberTanH ( 0 )

SalNumberToCharSyntax strChar = SalNumberToChar ( nNumber )

Description Converts a decimal value to an ASCII character.

Parameters nNumber Number. The number to convert.

Return Value strChar is the character converted from nNumber.

See Also SalStrFirstC

Example On SAM_ClickSet df2 = SalNumberToChar ( df1 )

SalNumberToHStringSyntax strString = SalNumberToHString ( nHString )

Description Converts a number to a string handle.

Parameters nHString Number. The numeric value of the string handle to convert.

Return Value strString is a string handle that represents the number converted.

See Also SalHStringToNumber

Example On SAM_ClickSet strString = SalNumberToHString ( lParam )

Set nBuffLen = SalStrGetBufferLength (strString)

SalNumberToStrSyntax nLength = SalNumberToStr ( nNumber, nDecimalPlaces, strString )

Description Converts a number to a string.


nDecimalPlaces Number. The number of decimal places you want in strString.



strString Receive String. The string converted from nNumber.

Return Value nLength is the length of strString, including the decimal point.

strString is the string converted from nNumber.

See Also SalNumberToStrXSalStrToNumber

Example On SAM_ClickSet nLength = SalNumberToStr ( 124.5, 1, strString )

SalNumberToStrXSyntax strString = SalNumberToStrX ( nNumber, nDecimalPlaces)

Description Converts a number to a string.


nDecimalPlaces Number. The number of decimal places you want in strString.

strString Receive String. The string converted from nNumber.

Return Value nLength is the length of strString, including the decimal point.

strString is the string converted from nNumber.

See Also SalNumberToStrSalStrToNumber

Example On SAM_ClickSet df2 = SalNumberToStrX ( df1, 2 )

SalNumberToWindowHandleSyntax hWnd = SalNumberToWindowHandle ( nWnd )

Description Converts a number to a window handle.

Parameters nWnd Number. The number to convert.

Return Value hWnd is the window handle converted from nWnd.

See Also SalWindowHandleToNumber

Example 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


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 ActionsOn SAM_CreateSet hWndtblCustomer = hWndForm! Populate Table Window

On SAM_DoubleClickSet hWndfrmCustomer = SalCreateWindow (frmCustomer, hWndNULL )! Convert the hWndtblCustomer window handle to a numberSet ntblCustomer = SalWindowHandleToNumber (hWndtblCustomer )

! Send the PASS_HWND message to the form window ! with lParam set to ntblCustomerCall SalSendMsg ( hWndfrmCustomer, PASS_HWND, 0, ntblCustomer )! Hide the table windowCall SalHideWindow ( hWndForm )

On SHOW_WNDCall SalShowWindow ( hWndForm )

Form Window: frmCustomer...Message ActionsOn PASS_HWND! Convert lParam back into the window handle hWndtblCustomerSet hWndtblCustomer = SalNumberToWindowHandle (lParam )Set strCustomer = tblCustomer.colCustomer...

On SAM_Destroy! Make table window visible againCall SalSendMsg ( hWndtblCustomer, SHOW_WND, 0, 0 )

SalNumberTruncateSyntax nResult = SalNumberTruncate ( nNumber, nPrecision, nScale )

Description Truncates a number.

Parameters nNumber Number. The number to truncate, starting with the leftmost.

nPrecision Number. The number of digits to display, starting with the leftmost.

nScale 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.



Return Value nResult is the result of truncating nNumber.

Example On SAM_ClickSet nNum = SalNumberTruncate( 10.0625, 4, 4 )! nNum is .0625

SalObjCreateFromStringSyntax RefObject = SalObjCreateFromString( StrClassName )

Description Creates an object of a user-defined class. The class name will be determined by the value of StrClassName.

Parameters: StrClassName String. The name of the user-defined class.

Return Value Reference. Reference to the object created if the function succeeds, OBJ_Null if the function fails.

Example Class Definitions Internal FunctionsFunction: GetAnimalObjDescription: Returns: CAnimalParameters:Static VariablesLocal VariablesActions Return SalObjCreateFromString( “CAnimal” )

See Also SalObjIsDerived()SalObjGetType()SalObjIsNull()SalObjIsValidClassName()

SalObjGetTypeSyntax StrClassName = SalObjGetType( RefObject )

Description 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.

Parameters RefObject Reference. Reference to the object whose class name is to be determined.

Return Value String. Class name of the object referred to by RefObject if successful, STRING_Null if unsuccessful.


SalObjIsDerived

Example Call SalMessageBox( "Class type of RefAnimal is: " || SalObjGetType( RefAnimal ), "", MB_Ok )

See Also SalObjCreateFromString()SalObjIsDerived()SalObjIsNull()SalObjIsValidClassName()

SalObjIsDerivedSyntax bDerived = SalObjIsDerived( RefObject, StrClassName )

Description 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.

Parameters RefObject Reference. Reference to the object in question.

StrClassName String. The name of the class to use for the match.

Return Value 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.

ExampleFunctional Class: CAnimalDerived From:

Functional Class: CDogDerived From: CAnimal

Local Variable:CAnimal: RefAnimalCDog: Ref Dog

On Sam_AppStartupIf ( 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 SalObjCreateFromStringSalObjGetTypeSalObjIsNullSalObjIsValidClassName



SalObjIsNullSyntax bOK = SalObjIsNull( varClassInst )

Description This function checks to see if the variable of a functional, coclass, or interface class is null.

Parameters varClassInst A variable of a functional, coclass, or interface class.

Return Value Returns TRUE if the parameter is a null reference, and FALSE if it is not.

Example Functional Class: CAnimalLocal 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 SalObjCreateFromStringSalObjGetTypeSalObjIsDerivedSalObjIsValidClassName

SalObjIsValidClassNameSyntax bValidClassName = SalObjIsValidClassName( StrClassName )

Determine whether StrClassName holds a valid user-defined class name.

Parameters StrClassName String. Name of the class to check.

Return Value TRUE if StrClassName holds a valid user-defined class name, FALSE otherwise.

Example Functional Class: CAnimalDerived From:

Functional Class: CDogDerived From: CAnimal

Local Variable:CAnimal: RefAnimal


SalParentWindow

On Sam_AppStartup:

If ( SalObjIsValidClassName( "CDog" ) ANDSalObjIsDerived( RefAnimal, "CDog" )

Set RefAnimal = SalObjCreateFromString( "CDog" )

See Also SalObjCreateFromStringSalObjGetTypeSalObjIsDerivedSalObjIsNull

SalParentWindowSyntax hWndParent = SalParentWindow ( hWnd )

Description Returns the handle of an object’s parent window. The following table shows the SalParentWindow behavior with tool bars and MDI windows:

Parameters hWnd Window Handle. The handle (or name) of the object whose parent window handle you want.

Return Value 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.

Example Set hWndParent = SalParentWindow ( hWnd )

SalPauseSyntax bOk = SalPause ( nMilliseconds )

Where called Parameter Return

Tool bar child in a top-level object.

hWndItem Handle of the top-level object that contains it (hWndForm).

Tool bar child in an MDI window.

hWndItem Handle of the MDI window that contains it (hWndMDI).

Child table window in a tool bar.

hWndForm Handle of the top-level object that contains it (hWndForm is the handle of the table window).

Top-level object in an MDI window.

hWndForm Handle of hte MDI window that contains it (hWndMDI).



Description 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.

Parameters nMilliseconds Number. The length of the pause, in milliseconds

Return Value bOk is TRUE if the function succeeds and FALSE if if fails.

Example Call SalPause (500)

SalPicClearSyntax bOk = SalPicClear ( hWndToClear )

Description Deletes the contents of a picture.

Parameters hWndToClear Window Handle. The handle (or name) of a picture.

Return Value bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid picture.

See Also SalPicSetSalPicSetFileSalPicSetFitSalPicSetString

Example Call SalPicClear ( hWndPicture )

SalPicGetDescriptionSyntax nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )

Description Retrieves a description of a picture's contents. An example of a description is "Microsoft Draw".

Parameters hWndPict Window Handle. The handle (or name) of a picture.

strDesc Receive String. A description of the contents of hWndPict.

For a graphic image, SalPicGetDescription returns one of the following values:

Value Image Type

Gupta:BMP Device-Independent Bitmap

Gupta:GIF Graphics Interchange Format

Gupta:ICO Icon File

Gupta:PCX Paintbrush


SalPicGetImage

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 ObjectPaintbrush Picture ObjectSound Object

nMaxLength Number. The maximum length of the text to retrieve.

Return Value nLength is the length (in bytes) of strDesc.

See Also SalPicGetSting

Example Set nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )

SalPicGetImageSyntax bOk = SalPicGetImage ( hWndPict, strImageBytes, nType )

Description 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.

Parameters hWndPict Window handle. The handle (or name) of a picture.

strImageBytes Receive String. The contents of hWndPict.

nType 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

Gupta:TIFF Tag Image File Format

Gupta:WMF Windows MetaFile



PIC_ImageTypeNuVEQ

PIC_ImapeTypeOBJECT

Return Value nLength is the length (in bytes) of strPict. If the format is not available, nLength is zero.

See Also SalPicClearSalPicGetDescriptionSalPicSetSalPicSetFileSalPicSetFitSalPicSetHandleSalPicSetImageSalPicSetString

Example None

SalPicGetStringSyntax nLength = SalPicGetString ( hWndPict, nFormat, strPict )

Description Copies the contents of a picture to a string.


nFormat Number. The format of the picture contents:

PIC_FormatBitmap

PIC_FormatIcon

PIC_FormatObject

strPict Receive String. The contents of hWndPict.

Return Value nLength is the length (in bytes) of strPict. If the format is not available, nLength is equal to zero (0).

See Also SalPicGetDescription

Example Set nLength = SalPicGetString ( hWndPict, nFormat, strPict )

SalPicSetSyntax bOk = SalPicSet ( hWndPic, tResource, nFormat )

Description Inserts a resource into a picture.

Parameters hWndPic Window Handle. The handle (or name) of a picture.


SalPicSetFile

tResource Template. An icon or bitmap in the Resources section of the outline.

nFormat Number. The resource type. If you specify zero, SQLWindows determines the resource type. Otherwise, specify one of these values:

PIC_FormatBitmap

PIC_FormatIcon


See Also SalPicClearSalPicSetFileSalPicSetFitSalPicSetString

Example Set bOk = SalPicSet ( hWndPic, tResource, nFormat )

SalPicSetFileSyntax bOk = SalPicSetFile ( hWndPict, strFileName )

Description Inserts a file's contents into a picture.


strFileName 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.


See Also SalPicClearSalPicSetSalPicSetFitSalPicSetString

Example Set bOk = SalPicSetFile ( hWndPict, strFileName )

SalPicSetFitSyntax bOk = SalPicSetFit ( hWndPict, nFit, nScaleWidth, nScaleHeight )

Description Sets the fit for a picture.




nFit Number. The type of fit:

PIC_FitBestFit

PIC_FitScale

PIC_FitSizeToFit

nScaleWidth Number. The width scaling percentage if nFit is PIC_FitScale.

nScaleHeight Number. The height scaling percentage if nFit is PIC_FitScale.


See Also SalPicClearSalPicSetSalPicSetFileSalPicSetString

Example Call SalPicSetFit ( hWndItem, PIC_FitBestFit, 0, 0 )

SalPicSetHandleSyntax bOk = SalPicSetHandle ( hWnd, nType, nHandle)

Description 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.

Parameters hWnd Window handle. The handle (or name) of the picture window.

nType Number. Set this to PIC_FormatIcon if nHandle is an HICON or to PIC_FormatBitmapif nHandle is an HBITMAP.

nHandle Number. An HBITMAP or HICON.


Example Set bOk = SalPicSetHandle (hWnd, nType, nHandle)

See Also SalPicClear

SalPicGetDescription

SalPicGetString

SalPicSet

SalPicSetFile

SalPicSetFit

SalPicSetString


SalPicSetImage

SalPicSetImageSyntax bOk = SalPicSetImage ( hWndPict, strImageBytes, nType )

Description Inserts the contents of a string to a picture object without the SQLWindows image header.


strImageBytes Receive String. The contents of hWndPict.

nType 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


See Also SalPicClearSalPicGetDescriptionSalPicGetImageSalPicSetSalPicSetFileSalPicSetFitSalPicSetHandleSalPicSetString

Example None

SalPicSetStringSyntax bOk = SalPicSetString ( hWnd, nFormat, strPicture )

Description Inserts the contents of a string into a picture.

Parameters hWnd Window Handle. The handle (or name) of a picture.



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.


See Also SalPicClearSalPicSetSalPicSetFileSalPicSetFit

Example Call SalPicSetString ( hWndPicture, PIC_FormatBitmap, strPicture )

SalPixelsToFormUnitsSyntax nFormUnits = SalPixelsToFormUnits ( hWnd, nNumPixels, bVertical )

Description 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.

Parameters hWnd Window Handle. The handle (or name) of a window whose form units you want to compute.

nNumPixels Number. The number of pixels.

bVertical 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.

Return Value nFormUnits is the number of form units returned if the function call is successful. nFormUnits is equal to zero (0) if hWnd is invalid.

See Also SalFormUnitsToPixels

Example Set nFormUnits = SalPixelsToFormUnits ( pbExample, nPixels, FALSE )


SalPostMsg

SalPostMsgSyntax bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )

Description Posts the specified message to a window by adding nMsg to hWndReceiver's message queue.

Parameters hWndReceiver Window Handle. The handle (or name) of the window receiving the message.

nMsg Number. The message number.

nMywParam Number. The wParam for the message.

nMylParam Number. The lParam for the message.


See Also SalSendMsgSalSendMsgToChildren

Example Set bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )

SalPrtExtractRectSyntax bOk = SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom )

Description Extracts the currently printing rectangle from the SAM_Print message's lParam parameter.

Parameters nMylParam Number. The SAM_Print message's lParam parameter.

nLeft Receive Number. The position on the X axis of the rectangle's left side.

nTop Receive Number. The position on the Y axis of the top of the rectangle.

nRight Receive Number. The position on the X axis of the rectangle's right side.

nBottom Receive Number. The position on the Y axis of the bottom of the rectangle.


Example On SAM_PrintCall SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight,

nBottom )



SalPrtGetDefaultSyntax bOk = SalPrtGetDefault ( strDevice, strDriver, strPort )

Description Returns the default device (printer), the default driver, and the default port.

Parameters strDevice Receive String. The default device.

strDriver Receive String. The default driver.

strPort Receive String. The default port.

Return Value bOk is TRUE if the function call is successful in getting the default values, and FALSE otherwise.

See Also SalPrtSetDefaultSalPrtSetup

Example Message ActionsCall SalPrtGetDefault ( strDevice, strDriver, strPort )

SalPrtGetParmNumSyntax bOk = SalPrtGetParmNum ( nParm, nValue )

Description 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.

Parameters nParm Number. The print parameter whose value you want; one of the PRT_* constants.

nValue Receive Number. The print parameter's value. For boolean parameters, nValue is TRUE or FALSE.


See Also SalPrtSetParmNum

Example On SAM_CreateCall SalPrtGetParmNum ( PRT_nDraftMode, nPrtValue)If nPrtValue

Set rbDraftMode = TRUEElse

Set rbProofMode = TRUE

SalPrtPrintFormSyntax bOk = SalPrtPrintForm ( hWndForm )


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.

Parameters hWndForm Window Handle. The handle (or name) of the window to print.


Example Call SalPrtPrintForm ( hWndForm )

SalPrtSetDefaultSyntax bOk = SalPrtSetDefault ( strDevice, strDriver, strPort )

Description Sets the default device (printer), driver, and port.

Parameters strDevice String. The default device.

strDriver String. The default driver.

strPort String. The default port.


See Also SalPrtGetDefaultSalPrtSetup

Example Set strDevice = 'PostScript Printer'Set strDriver = 'PSCRIPT'Set strPort = 'LPT2'Call SalPrtSetDefault ( strDevice, strDriver, strPort )

SalPrtSetParmDefaultsSyntax bOk = SalPrtSetParmDefaults ( )

Description 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



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



Example On SAM_ClickCall SalPrtSetParmDefaults ( )

SalPrtSetParmNumSyntax bOk = SalPrtSetParmNum ( nParm, nValue )

Description 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.

Parameters nParm Number. A constant that represents the parameter to set; one of the PRT_* constants.

nValue Number. The parameter value.


See Also SalPrtGetParmNum

Example If rbDraftModeCall SalPrtSetParmNum ( PRT_nDraftMode,

TRUE)

SalPrtSetupSyntax bOk = SalPrtSetup ( strDevice, strDriver, strPort, bActiveOnly )

Description 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.

Parameters strDevice Receive String. The device (printer).


SalQueryFieldEdit

strDriver Receive String. The driver.

strPort Receive String. The port.

bActiveOnly Boolean. Whether to display active and/or inactive printers: if TRUE, all printers display and if FALSE, only active printers display.


Example Message ActionsCall SalPrtSetup ( strDevice, strDriver, strPort, TRUE)

SalQueryFieldEditSyntax bSet = SalQueryFieldEdit ( hWndField )

Description 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 hWndField Window Handle. The handle (or name) of a data field, multiline field, combo box table window column, or picture.

Return Value bSet is TRUE if hWndField's field edit flag is set and FALSE otherwise.

See Also SalSendValidateMsgSalSetFieldEdit

Example If SalQueryFieldEdit ( SalGetFocus () )If SalSendValidateMsg ( ) = VALIDATE_Ok

! Process Save.

SalQuitSyntax bOk = SalQuit ( )

Description Exits an application.

If you are in user mode, SQLWindows returns you to design mode. If the application running from SQLRUN.EXE, it exits.





See Also SalAbort

Example On SAM_ClickCall SalQuit ( )

SalReportCloseSyntax bOk = SalReportClose ( hWndReport )

Description Closes a report window. Call this function when you want to close a report preview window.

Parameters hWndReport Window Handle. The handle (or name) of a report window.

Return Value bOk is TRUE if the function succeeds and FALSE if hWndReport is invalid.

Example If not SalReportClose ( hWndReport )Call SalMessageBox ( 'Close Failed', 'SalReportClose',

MB_Ok )

SalReportCmdSyntax bOk = SalReportCmd ( hWndReport, nCommand )

Description 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 Window Handle. The window handle (or name) of a report window.

nCommand Number. The command to send to the report. Possible values include any of the RPT_Cmd* commands.


Example Set bOk = SalReportCmd ( hWndReport, nCommand )

SalReportCreate


SalReportDlgOptions

Syntax bOk = SalReportCreate ( strTemplate, strVariables, strInputs, bDefaultReport, nError )

Description Creates a report template.

Parameters strTemplate String. The name of the report template to create.

strVariables 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.

strInputs String. A comma-separated list of the report's input names.

bDefaultReport Boolean. If TRUE, SQLWindows generates a quick report and nError is a RPT_Err* value. If FALSE, SQLWindows generates an empty report.

nError 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.

Return Value bOk is TRUE if the function succeeds and FALSE if it fails. If bOk is FALSE, nError is a RPT_Err* value.

Example Call SalReportCreate ( 'quick.qrp',':nDiv,:nDept,:nSection, :nEmplNum )

SalReportDlgOptionsSyntax bOk = SalReportDlgOptions ( hWndReport, strCaption, strLine1, strLine2,

strDocName )

Description 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.

Parameters hWndReport Window Handle. The wParam of a SAM_Report* message that contains the window handle.

strCaption String. The replacement text for the Print dialog box caption text.



strLine1 String. The replacement text for the first centered-text field.

strLine2 String. The replacement text for the second centered-text field.

strDocName String. The name of the document that Print Manager displays when the output is spooled and waiting to print.


Example Call SalReportDlgOptions ( SalNumberToWindowHandle (wParam ), 'Sales Report', 'This is a long report', 'Hit CANCEL to quit', 'sales.rpt' )

SalReportGetDateTimeVarSyntax bOk = SalReportGetDateTimeVar ( hWndReport, strVariable, dtValue )

Description Returns the value of a date/time report variable.


strVariable String. The name of a date/time report variable.

dtValue Receive Date/Time. The value of strVariable.

Return Value bOk is TRUE if the function is successful, and FALSE otherwise.

See Also SalReportGetNumberVarSalReportGetObjectVarSalReportGetStringVarSalReportSetDateTimeVar

Example Call SalReportGetDateTimeVar ( hWndReport, strVariable, dtGet )

SalReportGetFileInfoSyntax bOk = SalReportGetFileReport ( strFileName, strFileInfo )

Description Returns the comment which was embedded in a report template at design time.

Parameters strFileName String. The name of a file containing a Report Builder template.

strVariable Receive String. The string that should hold the comment.

Return Value bOk is TRUE if the function is successful, and FALSE otherwise.


SalReportGetNumberVar

Example Call SalReportGetFileInfo ( ‘mytemplate.cqt’, sComment)

SalReportGetNumberVarSyntax bOk = SalReportGetNumberVar ( hWndReport, strVariable, nValue )

Description Returns the value of a number report variable.


strVariable String. The name of a number report variable.

nValue Receive Number. The value of strVariable.


See Also SalReportGetDateTimeVarSalReportGetObjectVarSalReportGetStringVarSalReportSetNumberVar

Example Call bOk = SalReportGetNumberVar ( hWndToMove, nXOffset, nYOffset )

SalReportGetObjectVarSyntax bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )

Description Returns the value of an object report variable.


strVariable String. The name of an object report variable.

strValue Receive String. The value of strVariable.


See Also SalReportGetDateTimeVarSalReportGetNumberVarSalReportGetStringVarSalReportSetObjectVar

Example Set bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )

SalReportGetPrinterSettings



Syntax bOk = SalReportGetPrinterSettings(hWndReport,strPrinterName,nOrientation,nPaperType,nWidth,nHeight)

Description 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.

Parameters hWndReport : Report window handle. The handle of the report window

strPrinterName: Receive string. The friendly name of the printer.

nOrientation : Receive number. Orientation. Can be one of the following constants

• RPT_Portrait

• RPT_Landscape

nPaperType: Receive number. Paper type. Can be one of the following constants

• RPT_PaperA3

• RPT_PaperA4

• RPT_PaperA5

• RPT_PaperB5

• RPT_PaperLegal

• RPT_PaperLetter

• RPT_PaperTabloid

• RPT_PaperCustom

nWidth : Receive number. Paper width in milli-inches.

nHeight : Receive number. Paper height in milli-inches.


See Also SalReportSetPrinterSettingsSalReportGetPrinterTraySalReportSetPrinterTray

Example


SalReportGetPrinterTray

VariablesString: sPrinterNameString: sFirstPageTrayString: sOtherPagesTrayNumber: nOrientationNumber: nPaperTypeNumber: nPaperWidthNumber: nPaperHeight

Message ActionsOn SAM_ReportStart

Call SalReportGetPrinterSettings( SalNumberToWindowHandle(wParam), sPrinterName, nOrientation, nPaperType, nPaperWidth, nPaperHeight )

SalReportGetPrinterTraySyntax bOk = SalReportGetPrinterTray(hWndReport,nPage,strTrayName)

Description Gets the printer tray that will be used for the a specific page printed for a report at runtime.


nPage: Receive Number. The number of the page, or one of these constants: RPT_PageAll, RPT_PageFirst, RPT_PageLast, RPT_PageOdd, RPT_PageEven.

strTrayName : 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.


See Also SalReportSetPrinterTraySalReportGetPrinterSettingsSalReportSetPrinterSettings

Example VariablesNumber: nPage

Message ActionsOn SAM_ReportStartSet nPageNumber = 0

On SAM_ReportNotifyIf lParam = RPT_StartPagePrint



Set nPageNumber = nPageNumber + 1If nPageNumber = 1

Call SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageFirst,'Lower Paper tray' )

ElseCall SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageAll,'Upper Paper tray' )

SalReportGetStringVarSyntax bOk = SalReportGetStringVar ( hWndReport, strVariable, strValue )

Description Returns the value of a string report variable.


strVariable String. The name of a string report variable.

strValue Receive String. The value of strVariable.


See AlsoSalReportGetDateTimeVarSalReportGetNumberVarSalReportGetObjectVarSalReportSetStringVar

Example Call SalReportGetStringVar ( hWndReport, 'strVariable', strGet )

SalReportPrintSyntax hWndRet = SalReportPrint ( hWndFrm, strTemplate, strVariables, strInputs,

nCopies, nOptions, nFirstPage, nLastPage, nErr )

Description 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.


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 Window Handle. The handle (or name) of the application window that processes SAM_Report* messages.

strTemplate String. The report template name.

strVariables 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 are case-sensitive and must match the case of the input names declared in the report template.

nCopies Number. The number of copies. If you specify a zero or a negative number, SQLWindows prints one copy.

nOptions 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

nFirstPage Number. The first page of the report (if nOptions includes RPT_PrintRange).

nLastPage Number. The last page of the report (if nOptions includes RPT_PrintRange).

nErr 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.



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 SalReportPrintToFile

Example Call SalReportPrint ( frmMain, strReportFile, strReportBinds, strReportInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr )

SalReportPrintToFileSyntax hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile,

strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )

Description 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 Window Handle. The handle (or name) of the application window that processes the SAM_Report* messages.


strDestFile String. The destination file name.




nCopies Number. The number of copies.

nOptions Number. You can combine two or more of these constants with the OR (|) operator:

RPT_PrintAll


SalReportReset

RPT_PrintDraft

RPT_PrintNoAbort

RPT_PrintNoErrors

RPT_PrintNoWarn

RPT_PrintRange

nFirstPage Number. The first page of the report (if nOptions includes RPT_PrintRange).

nLastPage Number. The last page of the report (if nOptions includes RPT_PrintRange).

bFormat Boolean. Specify TRUE to write the report in RTF format; specify FALSE to write the report in ASCII format.

nErr 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 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.

See Also SalReportPrint

Example Set hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )

SalReportResetSyntax bOk = SalReportReset ( hWndReport )

Description 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.

Parameters hWndReport Window Handle. The handle (or name) of the report window.




Example If NOT SalReportReset ( hWndReport )Call SalMessageBox ( 'Reset Failed', 'SalReportReset',

MB_Ok )

SalReportResetPagesSyntax bOk = SalReportResetPages ( hWndReport, strBreakGroupName )

Description 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 Builder’s 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.


Example Call SalReportResetPages ( frmReport, ‘customer’ )

SalReportSetDateTimeVarSyntax bOk = SalReportSetDateTimeVar ( hWndReport, strVariable, dtValue )

Description Sets the value of a date/time report variable.


strVariable String. The name of the variable whose value you want to set.

dtValue Date/Time. The value of strVariable.


See Also SalReportGetDateTimeVarSalReportSetNumberVarSalReportSetObjectVarSalReportSetStringVar

Example If NOT SalReportSetDateTimeVar ( hWndReport,


SalReportSetNumberVar

'dtVariable', dtGDateTime[1] )Call SalMessageBox ( 'SetDateTimeError',

'RPT_BeforePageHeader-d', MB_Ok )

SalReportSetNumberVarSyntax bOk = SalReportSetNumberVar ( hWndReport, strVariable, nValue )

Description Sets the value of a numeric report variable.



nValue Number. The value of strVariable.


Related Function

SalReportGetNumberVarSalReportSetDateTimeVarSalReportSetObjectVarSalReportSetStringVar

Example Call SalReportSetNumberVar ( hWndReport, 'strUnknown', nVariable )

SalReportSetObjectVarSyntax bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue )

Description Sets the value of an object report variable.

Parameters hWndReport Window Handle. The window of the report window handle.


strValue String. The value of strVariable.


See Also SalReportGetObjectVarSalReportSetDateTimeVarSalReportSetNumberVarSalReportSetStringVar

Example Set bOk = SalReportSetObjectVar ( hWndReport, strVariable,strValue )



SalReportSetPrinterSettingsSyntax bOk = SalReportGetPrinterSettings(

hWndReport,strPrinterName,nOrientation,nPaperType,nWidth,nHeight)

Description 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.


strPrinterName: 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.

nOrientation : Number. Orientation. Can be one of the following constants (or use -1 to retain current orientation.)

• RPT_Portrait

• RPT_Landscape

nPaperType: Number. Paper type. Can be one of the following constants (or use -1 to retain current paper type.)

• RPT_PaperA3

• RPT_PaperA4

• RPT_PaperA5

• RPT_PaperB5

• RPT_PaperLegal

• RPT_PaperLetter


SalReportSetPrinterTray

• RPT_PaperTabloid

• RPT_PaperCustom

nWidth : Number. Paper width in milli-inches. This value is ignored for all paper types except RPT_PaperCustom.

nHeight : Number. Paper height in milli-inches. This value is ignored for all paper types except RPT_PaperCustom.


See Also SalReportGetPrinterSettingsSalReportGetPrinterTraySalReportSetPrinterTray

Example Call SalReportSetPrinterSettings( SalNumberToWindowHandle(wParam), “HP LaserJet 5”, RPT_Portrait, RPT_PaperA4, 0, 0 )

SalReportSetPrinterTraySyntax bOk = SalReportSetPrinterTray(hWndReport,nPage,strTrayName)

Description 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. First

2. Last

3. Numeric ( user-supplied number)



4. Odd

5. Even

6. All


nPage: Number. The number of the page, or one of these constants: RPT_PageAll, RPT_PageFirst, RPT_PageLast, RPT_PageOdd, RPT_PageEven.

strTrayName : 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.


See Also SalReportGetPrinterTraySalReportGetPrinterSettingsSalReportSetPrinterSettings

Example VariablesNumber: nPage

Message ActionsOn SAM_ReportStartSet nPageNumber = 0

On SAM_ReportNotifyIf lParam = RPT_StartPagePrintSet nPageNumber = nPageNumber + 1

If nPageNumber = 1Call SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageFirst,'Lower Paper tray' )

ElseCall SalReportSetPrinterTray( SalNumberToWindowHandle(wParam), RPT_PageAll,'Upper Paper tray' )

SalReportSetStringVarSyntax bOk = SalReportSetStringVar ( hWndReport, strVariable, strValue )

Description Sets the value of a string report variable.



SalReportTableCreate


strValue String. The value of strVariable.


See Also SalReportGetStringVarSalReportSetDateTimeVarSalReportSetNumberVarSalReportSetObjectVar

Example Call SalReportSetStringVar ( hWndReport, 'strUnknown', strVariable )

SalReportTableCreateSyntax bOk = SalReportTableCreate ( strReport, hWndTbl, nError )

Description 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.

Parameters strReport String. The name of the report.

hWndTbl Window Handle. The handle (or name) of a table window.


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.


See Also SalReportTablePrintSalReportTableView

Example Set bOk = SalReportTableCreate ( strReport, hWndTbl, nError )

SalReportTablePrintSyntax hWnd = SalReportTablePrint ( hWndTbl, strReport, nParamArray, nError )



Description Prints a report created from the specified table window.

Parameters hWndTbl Window Handle. The handle (or name) of a table window.

strReport String. The name of the report.

nParamArray Number. An array you create containing information about the print job. The array indexes are:

RPT_PrintParamCopies

RPT_PrintParamFirstPage

RPT_PrintParamLastPage

RPT_PrintParamOptions


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.

Return Value hWnd is the handle of the report window if the function succeeds.

See Also SalReportTableCreateSalReportTableView

Example Set hWndReport = SalReportTablePrint ( hWndTbl, 'test.qrp', nParamArray,nError )

SalReportTableViewSyntax hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError )

Description Displays, in preview mode, a report created from the specified table window.


hWndDisplay Window Handle. The handle (or name) of a report display window. If null, SQLWindows creates a window in which you can preview the report.

strReport String. The name of the report.


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.

Return Value hWnd is the handle of the report window if the function succeeds.

See Also SalReportTableCreateSalReportTablePrint

Example Set hWnd = SalReportTableView ( hWndTbl, hWndDisplay,strReport, nError )

SalReportViewSyntax hWndReport = SalReportView ( hWndFrm, hWndRptTemp, strTemplate,

strVariables, strInputs, nFlags )

Description 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 Window Handle. The handle (or name) of the application window that processes SAM_Report* messages.

hWndRptTemp 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.





The contents of this string must match the order 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:

RPT_NoPrint No print button on the tool bar.

RPT_NoToolbar 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.

Return Value hWndReport is the handle of the report window if the function succeeds. SQLWindows returns the window handle before Report Builder displays the report.

Example Set hWndReport = SalReportView ( frmMain, hWndNULL, strReportFile, strReportBinds, strReportInputs, nError )


SalScrollGetPos

SalScrollGetPosSyntax bOk = SalScrollGetPos ( hWndsb, nPos )

Description Returns the current scroll bar value.

Parameters hWndsb Window Handle. The handle (or name) of a vertical or horizontal scroll bar.

nPos Receive Number. The scroll bar value.


See Also SalScrollSetPos

Example Set bOk = SalScrollGetPos ( hWndsb, nPos )

SalScrollGetRangeSyntax bOk = SalScrollGetRange ( hWndsb, nMin, nMax, nLine, nPage )

Description Gets a scroll bar's scroll range, line increment, and page increment.


nMin Receive Number. The minimum scroll bar position.

nMax Receive Number. The maximum scroll bar position.

nLine Receive Number. The line increment. The number of units the scroll bar increments or decrements when the user clicks the scroll bar arrow.

nPage 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.


See Also SalScrollSetRange

Example Call SalScrollGetRange ( hWndsbCounter, nMin, nMax, nLine, nPage )



SalScrollSetPosSyntax bOk = SalScrollSetPos ( hWndsb, nPos )

Description Sets a scroll bar's position. This function is equivalent to using a Set statement to assign a value to the scroll bar.


nPos 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.


See Also SalScrollGetPos

Example Call SalScrollSetPos ( hWndsbCounter, 0 )

SalScrollSetRangeSyntax bOk = SalScrollSetRange ( hWndsb, nMin, nMax, nLine, nPage )

Description Sets a scroll bar's range, line increment, and page increment.

When the scroll bar is created, SQLWindows assigns it these values:

Minimum scroll position0Maximum scroll position100Line Increment1Page Increment10If 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.


nMin Number. The minimum position of the scroll bar.

nMax Number. The maximum position of the scroll bar.

nLine Number. The number of units to increment or decrement the scroll bar when the user clicks the scroll bar arrow.

nPage Number. The number of units to increment or decrement the scroll bar when the user clicks either side of the scroll box.



SalSendClassMessage

See Also SalScrollGetRange

Example Call SalScrollSetRange ( hWndsbCounter, 0, 50, 1, 5 )

SalSendClassMessageSyntax nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )

Description 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.

Parameters nMessage Number. The message number.

nMywParm Number. The wParam.

nMylParam Number. The lParam.

Return Value nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0).

See Also SalSendClassMessageNamed

Example Set nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )

SalSendClassMessageNamedSyntax nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam,

nMylParam )

Description 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 Template. The ancestor's class name.


nMywParam Number. The wParam.





See Also SalSendClassMessage

Example Set nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam )

SalSendMsgSyntax nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )

Description Sends the specified message to a window. SalSendMsg does not return until the processing for the message is complete.

Parameters hWnd Window Handle. The window receiving the message.


nMywParam Number. The wParam.



See Also SalPostMsgSalSendMsgToChildrenSalSendValidateMsg

Example Set nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )

SalSendMsgToChildrenSyntax bSent = SalSendMsgToChildren ( hWnd, nMsg, nMywParam, nMylParam )

Description Sends a message to all child items of a form window, dialog box, table window, or MDI window.

Parameters hWnd Window Handle. The handle (or name) of a form window, dialog box, table window, or MDI window.


nMywParam Number. The wParam for the message.

nMylParam Number. The lParam for the message.

Return Value bSent is TRUE if the function succeeds and FALSE if it fails.

See Also SalPostMsgSalSendMsgSalSendValidateMsg


SalSendValidateMsg

Example Call SalSendMsgToChildren ( hWndForm,CHM_DISABLE, 0, 0 )

SalSendValidateMsgSyntax nStatus = SalSendValidateMsg ( )

Description 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 Np parameters.

Return Value nStatus is returned by the object's message actions for the SAM_Validate message:

VALIDATE_CancelVALIDATE_OkVALIDATE_OkClearFlag

See Also SalSendMsgSalSendMsgToChildren

Example Set nStatus = SalSendValidateMsg ( )

SalSetDefButtonSyntax bOk = SalSetDefButton ( hWndButton )

Description 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.

Parameters hWndButton Window Handle. The handle (or name) of the default push button.

Return Value bOk is TRUE if the function succeeds and FALSE if hWndButton is not a valid button.

See Also SalGetDefButton

Example Call SalSetDefButton ( frmMain.pb2 )



SalSetErrorInfoSyntax bOK = SalSetErrorInfo( nCode, sDesc, sHelpfileName, nHelpContext )

Description 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.

Parameters 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.

sDesc A textual, human-readable description of the error intended for the end user.

sHelpfileName The fully qualified drive, path, and file name of a help file with more information about the error.

nHelpContext The help context identifier of a topic in the help file. This field is ignored when sHelpfileName is empty.


SalSetFieldEditSyntax bOk = SalSetFieldEdit ( hWndField, bSet )

Description 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 Window Handle. The handle (or name) of a data field, multiline text field, table window column, or picture.

bSet Boolean. TRUE sets the flag; FALSE clears it.


SalSetFocus


See Also SalQueryFieldEdit

Example Call SalSetFieldEdit ( hWndChild, FALSE )

SalSetFocusSyntax hWndFocus = SalSetFocus ( hWndToSet )

Description Sets the focus to a specified window.

Warning: You cannot call SalSetFocus in SAM_KillFocus processing because of a Windows limitation.

Parameters hWndToSet Window Handle. The handle (or name) of the window to receive the focus.

Return Value hWndFocus is the handle of the window that previously had the focus.

See Also SalGetFocus

Example Call SalSetFocus ( hWndSave )

SalSetMaxDataLengthSyntax bOk = SalSetMaxDataLength ( hWndField, nLength )

Description Sets a limit on the number of characters that a user can enter into a data field, multiline text field, or table window column.


nLength Number. The character limit.


See Also SalGetMaxDataLength

Example



Set bOk = SalSetMaxDataLength ( hWndField, nLength )

SalSetProfileStringSyntax bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )

Description 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 .


strEntry String. The entry whose associated value is being set.

strValue String. The value of strEntry.



See Also SalGetProfileIntSalGetProfileStringSalUseRegistry

Example Set bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )

SalSetWindowLabelTextSyntax bOk = SalSetWindowLabelText ( hWnd, sText )

Description 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.


sText String. The window text.


Example Set bOk = SalSetWindowLabelText ( hWnd, sText )


SalSetWindowLoc

SalSetWindowLocSyntax bOk = SalSetWindowLoc ( hWnd, nX, nY )

Description Moves a window to a new position (x, y) on the X and Y axes.

Parameters hWnd Window Handle. The handle (or name) of the window to move.

nX Number. The position on the X axis (expressed in form units).

nY Number. The position on the Y axis (expressed in form units).

Return Value bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle.

See Also SalGetWindowLoc

Example Call SalSetWindowLoc ( pbExample, 0, 0 )

SalSetWindowSizeSyntax bOk = SalSetWindowSize ( hWnd, nWidth, nHeight )

Description Resizes a window.

Parameters hWnd Window Handle. The handle (or name) of the window to resize.

nWidth Number. The new width of the window (expressed in SQLWindows form units).

nHeight Number. The new height of the window (expressed in SQLWindows form units).

Return Value bOk is TRUE if the window is successfully resized, and FALSE if hWnd is an invalid window handle.

See Also SalGetWindowSize

Example Call SalSetWindowSize ( pbExample, nWidth+1, nHeight+1)

SalSetWindowTextSyntax bOk = SalSetWindowText ( hWnd, strTitle )

Description 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.



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.


strTitle String. The window text.


See Also SalGetWindowTextSalTblSetColumnTitle

Example Call SalSetWindowText ( hWndForm, 'First National Bank' )

SalShowWindowSyntax bOk = SalShowWindow ( hWndToShow )

Description Makes a window visible.

Parameters hWndToShoWindow Handle. The handle (or name) of a window to make visible.

Return Value 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.

See Also SalHideWindow

Example Call SalShowWindow ( hWndForm )

SalShowWindowAndLabelSyntax bOk = SalShowWindowAndLabel ( hWndToShow )

Description Makes a window and its associated label visible.


Parameters hWndToShow The handle (or name) of a window to make visible.

Return Value 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


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 SalHideWindowAndLabelSalShowWindow

Example Set bOk = SalShowWindowAndLabel ( hWndToShow )

SalStartTraceSyntax bOk = SalStartTrace (nOutputType, strTraceFile, bClearExisting )

Description 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.

strTraceFile 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.

bClearExisting Boolean. Whether existing output should be cleared before new tracing begins..

Return Value bOk is TRUE if the functions succeeds, and FALSE if it fails.

See Also SalTraceSalEndTrace

Example Call SalStartTrace ( TRACE_Event, '', TRUE )



SalStatusGetTextSyntax nLength = SalStatusGetText ( hWnd, strText, nMaxLen )

Description Gets the text displayed in the status bar of a top-level or MDI window.

Parameters hWnd Window Handle. The handle (or name) of a top-level or MDI window.

strText Receive String. The text displayed in the status bar.


Return Value nLength is the length of strText. nLength is zero (0) if the window has no text.

See Also SalStatusSetTextSalStatusSetVisible

Example Set nLength = SalStatusGetText ( hWnd, strText, nMaxLen )

SalStatusSetTextSyntax bOk = SalStatusSetText ( hWnd, strText )

Description Displays specified text in the status bar of a top-level or MDI window.


strText String. The text to display in the status bar.


See Also SalStatusGetTextSalStatusSetVisible

Example Set bOk = SalStatusSetText ( hWnd, strText )


SalStatusSetVisible

SalStatusSetVisibleSyntax bOk = SalStatusSetVisible ( hWnd, bShow )

Description Shows or hides the status bar on a top-level or MDI window.


bShoBoolean. If TRUE, the status bar displays; if FALSE, the status bar hides.


See Also SalStatusGetTextSalStatusSetText

Example Call SalStatusSetVisible ( hWndForm, TRUE )

SalStrCompressSyntax bOk = SalStrCompress ( strString )

Description 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 )

Parameters strString Receive String. The string to compress.


See Also SalStrUncompress

Example Set bOk = SalStrCompress ( strString )

SalStrFirstCSyntax bOk = SalStrFirstC ( strString, nChar )



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 low-order byte.

Use SalNumberHigh to get the leading byte and SalNumberLow to get the trailing byte.

Parameters strString Receive String. The string whose first character is lopped off.

nChar Receive Number. The first character of strString.

Return Value bOk is TRUE unless strString is empty or invalid.

See Also SalNumberHighSalNumberLowSalNumberToCharSalStrLop

Example On SAM_ClickSet dfString = 'ABC'Call SalStrFirstC ( dfString, dfNumChar )! Now dfString = 'BC' and dfNumChar = 65

SalStrGetBufferLengthSyntax nLength = SalStrGetBufferLength ( strString )

Description Returns the current buffer length of a string.

SQLWindows stores string variables in buffers. The length includes the string's null termination character.

Parameters strString String. The string whose buffer length you want.

Return Value nLength is the length of strString's buffer.

See Also SalStrLengthSalStrSetBufferLength

Example Set nBufferLength = SalStrGetBufferLength (strNumbers )


SalStrIsValidCurrency

SalStrIsValidCurrencySyntax bOk = SalStrIsValidCurrency ( strMoney, nPrecision, nScale )

Description 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.

Parameters strMoney String. A string that contains a currency value.

nPrecision Number. The number of digits to display.

nScale Number. The number of digits to the right of the decimal point.

Return Value bOk is TRUE if strMoney is a valid currency value and FALSE otherwise.

See Also SalStrIsValidDateTimeSalStrIsValidNumber

Example Set bOk1 = SalStrIsValidCurrency ( '$120.00' )

SalStrIsValidDateTimeSyntax bOk = SalStrIsValidDateTime ( strDateTime )

Description 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.

Parameters strDateTime String. A string that contains a date/time value.

Return Value bOk is TRUE if strDateTime is a valid date/time value and FALSE otherwise.

See Also SalStrIsValidCurrencySalStrIsValidNumber

Example Set bOk2 = SalStrIsValidDateTime ( '2/2/91' )

SalStrIsValidNumberSyntax bOk = SalStrIsValidNumber ( strNumber )

Description 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.

Parameters strNumber String. A string that contains a number value.



Return Value bOk is TRUE if strNumber is a valid number value and FALSE otherwise.

See Also SalStrIsValidCurrencySalStrIsValidDateTime

Example Set bOk1 = SalStrIsValidNumber ( '120.00' )

SalStrLeftSyntax nLength = SalStrLeft ( strSource, nExtract, strTarget )

Description Returns a substring of a specified length starting at position zero (0), the left-most character in the string.

Parameters strSource String. The string from which to extract characters.

nExtract Number. The number of characters to extract from strSource.

strTarget 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 SalStrMidSalStrMidXSalStrRightSalStrLeftX

Examples Set nLength = SalStrLeft ( 'LEFT01234', 4, strTarget )

SalStrLeftXSyntax strTarget = SalStrLeftX ( strSource, nExtract)

Description Returns a substring of a specified length starting at position zero (0), the left-most character in the string.

Parameters strSource String. The string from which to extract characters.

nExtract Number. The number of characters to extract from strSource.



Return Value nLength is the length of the new string.



SalStrLength

See Also SalStrMidSalStrMidXSalStrRightSalStrLeft

Examples Set strTarget = SalStrLeftX ( 'LEFT01234', 4)

SalStrLengthSyntax nLength = SalStrLength ( strString )

Description 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 strString String. The string whose length you want.

Return Value nLength is the length of strString.

See Also SalStrGetBufferLength

Example On SAM_CreateSet strNumbers = '1234567890'Set nStringLength = SalStrLength ( strNumbers )

SalStrLopSyntax nCharacter = SalStrLop ( strString )

Description Returns the ASCII numeric value of the first character of a string in decimal format. This function removes the first character of the string.

Parameters strString Receive String. The input string without the first character.

Return Value nCharacter is the ASCII value of the first character of strString. When strString is null, nCharacter is equal to zero (0).

See Also SalNumberToCharSalStrFirstC

Example On SAM_CreateSet strString = 'ABC'Set nCharacter = SalStrLop ( strString )



SalStrLowerSyntax nLength = SalStrLower ( strSource, strTarget )

or

strTarget = SalStrLowerX ( strSource )

Description Converts a string to lowercase.

Parameters strSource String. The string to convert .

strTarget Receive String. The lowercase string.


Return Value nLength is the length of strTarget.

strTarget is the lowercase string.

See Also SalStrUpperSalStrUpperX

Examples On SAM_CreateSet nLength = SalStrLower ( 'LOWERCASE', strTarget )

orOn SAM_Create

Set strTarget = SalStrLowerX ( 'LOWERCASE' )

SalStrMidSyntax nLength = SalStrMid ( strSource, nStartPos, nLength, strTarget )

or

strTarget = SalStrMidX ( strSource, nStartPos, nLength )

Description Returns a substring, starting at a specified position and containing a specified number of characters.

Parameters strSource String. The source string.

nStartPos Number. The starting position of the substring (zero is the first position) in strSource.

nLength Number. The number of characters to put in the substring.



Return Value nLength is the length of the substring.


SalStrMid


See Also SalStrLeftSalStrLeftXSalStrRight

Examples Set nLength = SalStrMid (‘012ABC345’, 3, 3, strTarget)OrSet strTarget = SalStrMidX ( '012ABC345', 3, 3 )! strTarget = 'ABC'



SalStrProperSyntax nLength = SalStrProper ( strSource, strTarget )

or

strTarget = SalStrProperX ( strSource )

Description Converts a string to a proper name. In a proper name, the first letter of each word is uppercase; the remaining letters are lowercase.

Parameters strSource String. The string to convert.

strTarget Receive String. The converted string.



strTarget is the converted string.

Examples Set nLength = SalStrProper ( 'JOHN L. SMITH', strTarget )

orSet strTarget = SalStrProperX ( 'JOHN L. SMITH')

SalStrRepeat and SalStrRepeatXSyntax nLength = SalStrRepeat ( strSource, nTimes, strTarget )

or

strTarget = SalStrRepeatX ( strSource, nTimes )

Description Concatenates a string with itself a specified number of times.


nTimes Number. The number of times to concatenate strSource with itself.

strTarget Receive String. The new string.



strTarget is the new string.

Examples On SAM_CreateSet nLength = SalStrRepeat ( 'ABC*', 3, strTarget )


SalStrReplace and SalStrReplaceX

or

On SAM_CreateSet strTarget = SalStrRepeatX '( 'ABC*', 3)

SalStrReplace and SalStrReplaceX Syntax nReturn = SalStrReplace ( strSource, nStartPos, nLength, strReplace, strTarget )

or

strTarget = SalStrReplaceX ( strSource, nStartPos, nLength, strReplace )

Description Replaces characters in one string with characters from another string.

Parameters strSource String. The source string that contains characters to replace.

nStartPos Number. The position in strSource at which to begin replacing characters.

nLength Number. The number of characters to replace.

strReplace String. The replacement string.


Return Value nReturn is the length of strTarget.


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 SalStrRightXSyntax 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.




nLength Number. The number of characters to extract.





See Also SalStrLeftSalStrLeftXSalStrMidSalStrMidX

Example On SAM_CreateSet nLength = SalStrRight ( '123RIGHT', 5, strTarget )

or

On SAM_CreateSet StrTarget = SalStrRightX ( '123RIGHT', 5 )

SalStrScanSyntax nOffset = SalStrScan ( strString1, strString2 )

Description 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.

Parameters strString1 String. The string to search. The first character in the string is at offset zero (0).

strString2 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.


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 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.

Example Set nOffset = SalStrScan ( '012AbC345', 'ABC' )

SalStrSetBufferLengthSyntax bOk = SalStrSetBufferLength ( strString, nLength )

Description 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 Receive String. The string whose buffer length you want to set.

nLength Number. The length of strString.


See Also SalSetMaxDataLength



SalStrGetBufferLength

Example Set bOk = SalStrSetBufferLength( recvString, 10 ) ! 9 chars

SalStrToDateSyntax dtDateTime = SalStrToDate ( strString )

Description 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.

Parameters strString String. The string to convert.

Return Value dtDateTime is the date/time value converted from strString.

See Also SalDateToStr

Example Set dtDateTime = SalStrToDate ( strDateTime )

SalStrTokenizeSyntax nNumTokens = SalStrTokenize ( strSource, strStartDel, strEndDel, strTokenArray )

Description 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 String. The string to parse.

strStartDel 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.


SalStrToNumber

strTokenArray String Array. The handle (or name) of an array of substrings created from strSource.

Return Value nNumTokens is the number of substrings created. nNumTokens is zero (0) if no substrings are created, or if an error occurs.

Example Set dfNumTokens = SalStrTokenize( dfSource1, '', ',', astrToken1 )

SalStrToNumberSyntax nNumber = SalStrToNumber ( strString )

Description Converts a string to a number.

Parameters strString String. The string to convert.

Return Value nNumber is the number resulting from the conversion.

See Also SalNumberToStr

Example Set nNumber = SalStrToNumber ( '100.22' )

SalStrTrimSyntax nNewLength = SalStrTrim ( strSource, strTarget )

or

strTarget = SalStrTrimX ( strSource )

Description Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces.

Parameters strSource String. The original string.



Return Value nNewLength is the length of strTarget.


Example Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )

SalStrTrimXSyntax strTarget = SalStrTrimX ( strSource)



Description Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces.

Parameters strSource String. The original string.



Return Value nNewLength is the length of strTarget.


Example On SAM_CreateSet nLength = SalStrTrim ( ' 1 2 3 ', strTarget )

SalStrUncompressSyntax bOk = SalStrUncompress ( strString )

Description Decompresses the specified string. Use this function to decompress a string that you compressed with SalStrCompress.

Parameters strString Receive String. The string to decompress.


See Also SalStrCompress

Example Set bOk = SalStrUncompress ( strString )

SalStrUpperSyntax nLength = SalStrUpper ( strSource, str Target )

Description Converts a string to uppercase.


strTarget Receive String. The uppercase string.



strTarget is the uppercase string.

See Also SalStrLower

Example Set nLength = SalStrUpper ( 'uppercase', strTarget )


SalStrUpperX

SalStrUpperXSyntax strTarget = SalStrUpperX ( strSource )

Description Converts a string to uppercase.



Return Value This function returns the uppercase string in strTarget.

See Also SalStrLower

Example On SAM_CreateSet strTarget = SalStrUpperX ( 'uppercase' )

SalTBarSetVisibleSyntax bOk = SalTBarSetVisible (hWind, bShw)

Description Shows or hides the tool bar on a top-level or MDI window.


bShow Boolean. If TRUE, displays the tool bar; if FALSE, hides the tool bar.


See Also SalStatusSetVisible

Example Set bOk = SalTBarSetVisible (hWind, bShw)

SalTblAnyRowsSyntax bAny = SalTblAnyRows ( hWndTbl, nFlagsOn, nFlagsOff )

Description 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.


nFlagsOn Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator.



nFlagsOff Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.

Return Value bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags and none of the nFlagsOff flags.

See Also SalTblFindNextRowSalTblFindPrevRow

Example Menu SettingsEnabled When: SalTblAnyRows ( tblTable, ROW_Selected, 0 )

SalTblClearSelectionSyntax bOk = SalTblClearSelection ( hWndTbl )

Description Deselects all rows of a table window.



See Also SalTblSetRowFlags

Example Call SalTblClearSelection ( hWndForm )

SalTblColumnAverageSyntax nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

Description 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.


nColumnID Number. The Column Identifier.


nFlagsOff Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator:

Return Value 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.


SalTblColumnAverage

See Also SalTblColumnSum

Example Set nAverage = SalTblColumnAverage ( hWndTbl, nColumnID,nFlagsOn, nFlagsOff )



SalTblColumnSumSyntax nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

Description 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.


nColumnID Number. The Column Identifier



Return Value 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.

See Also SalTblColumnAverage

Example Set nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn,nFlagsOff )

SalTblCopyRowsSyntax bOk = SalTblCopyRows ( hWndTbl, nFlagsOn, nFlagsOff )

Description 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.





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.

See Also SalTblPasteRows

Example Call SalTblCopyRows ( tblTable, ROW_Selected, 0 )

SalTblCreateColumnSyntax nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars,

strTitle )

Description 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.


nColumnPos Number. The Column Position. Column positions begin with one, not zero.

nDispWidth 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.

nMaxChars Number. The maximum number of characters that the column can contain. If zero or negative, the number of characters allowed is unlimited.

strTitle String. The column title.

Return Value nColId is the Column Identifier of the new column. nColld is negative one (-1) if an error occurs.

Example Set nColId = SalTblCreateColumn ( hWndTbl, nColumnPos,nDispWidth, nMaxChars, strTitle )

SalTblCreateColumnEx



Syntax nColId = SalTblCreateColumnEx ( hWndTbl, nColumnPos, nDispWidth, strTitle, nMaxChars, nDatatype )

Description 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.


nColumnPos Number. The Column Position

nDispWidth 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.

strTitle String. The column title.

nMaxChars Number. The maximum number of characters that the column can contain. If zero or negative, the number of characters allowed is unlimited.

nDatatype Number. Must be equal to constant DT_String, DT_DateTime, or DT_Number. Any other value will cause the function to fail.

Return Value nColId is the Column Identifier of the new column. nColld is negative one (-1) if an error occurs.

Example Set nColId = SalTblCreateColumnEx ( hWndTbl, nColumnPos,nDispWidth, strTitle, nMaxChars, DT_Number )

SalTblDefineCheckBoxColumnSyntax bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue,

sUncheckedValue )

Description Define a column as a check box.

Parameters hWnd Window Handle. The handle (or name) of a table window.

HWndCol Window Handle. The handle (or name) of a table window column.


SalTblDefineDropDownListColumn

nFlags Number. nFlags is a combination of the following flags using the '|' operator:

COL_CheckBox_IgnoreCase = 0x0001

sCheckedValue String. sCheckedValue is the value that a cell will get when the check box is checked.

sUncheckedValue String. The value when a check box is unchecked.


Example Set bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags,sCheckedValue, sUncheckedValue )

SalTblDefineDropDownListColumnSyntax bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol, nFlags, nLines )

Description Define a column as a drop down list.



nFlags Number. nFlags is a combination of the following flags using the '|' operator:

COL_DropDownList_Sorted = 0x0001

COL_DropDownList_VScroll = 0x0002

COL_DropDownList_Auto = 0x0004

COL_DropDownList_Editabel = 0x0008

nLines Number. nLines indicates the maximum number of lines to display in the list.


Example Set bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol,nFlags, nLines )

SalTblDefinePopupEditColumnSyntax bOk = SalTblDefinePopupEditColumn( hWnd, hWndCol, nFlags, nLines )

Description Define a column as a popup edit window. nLines indicates the maximum number of lines to display in the control.





nFlags Number. nFlags is always 0 (zero).

nLines Number. nLines indicates the maximum number of lines to display in the list.


Example Set bOk = SalTblDefinePopupEditColumn ( hWnd, hWndCol, nFlags,nLines )

SalTblDefineRowHeaderSyntax bOk = SalTblDefineRowHeader ( hWndTable, strTitle, nWidth, nFlags, hWndCol )

Description 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.

Parameters hWndTable Window Handle. The handle (or name) of a table window.

strTitle String. The title of the row header column.

nWidth Number. The width of the row header in pixels.

nFlags 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.


Example Call SalTblDefineRowHeader ( tbl1, strTitle, nWidth,TBL_RowHdr_Visible | TBL_RowHdr_ShareColor,colRowHeader )


SalTblDefineSplitWindow

SalTblDefineSplitWindowSyntax bOk = SalTblDefineSplitWindow ( hWndTable, nRowsLowerHalf, bDragAdjust )

Description 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 Window Handle. The handle (or name) of a table window to split.

nRowsLowerHalf 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.

bDragAdjust Boolean. Specify whether (TRUE) or not (FALSE) to let the user drag-adjust the visible rows in both halves of a split window.


Example Set bAnyFlag = SalTblDefineSplitWindow ( hWndTbl, 3,TBL_Split_Adjustable )

SalTblDeleteRowSyntax bOk = SalTblDeleteRow ( hWndTbl, nRow, nFlag )

Description Deletes a row from a table window but not from the database.


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


Example Call SalTblDeleteRow ( hWndForm, nCurrentRow, TBL_NoAdjust)

SalTblDeleteSelected



Syntax bOk = SalTblDeleteSelected ( hWndTbl, hSql )

Description 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.


hSql Sql Handle. The handle of a DELETE statement.

Return Value bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid.

See Also SalTblDoDeletesSalTblDoInsertsSalTblDoUpdatesSalTblPopulate

Example Call SalTblDeleteSelected ( tblExample, hSql )

SalTblDestroyColumnsSyntax bOk = SalTblDestroyColumns ( hWndTbl )

Description Destroys all automatic columns created by SalTblCreateColumn or SalTblPopulate at runtime.

This function only works on table windows that contain only automatic columns.


Return Value 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).

See Also SalTblCreateColumnSalTblPopulate

Example Set bOk = SalTblDestroyColumns ( hWndTbl )

SalTblDoDeletesSyntax bOk = SalTblDoDeletes ( hWndTbl, hSql, nFlagsOn )


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.


hSql Sql Handle. The handle of a DELETE statement.

nFlagsOn Number. SQLWindows uses row flags to determine which rows to delete. You can specify either of these flags:

ROW_MarkDeleted

ROW_Selected

Return Value bOk is TRUE if any rows are deleted and FALSE otherwise. bOk is FALSE if hWndTbl or hSql is invalid.

See Also SalTblDeleteSelectedSalTblDoInsertsSalTblDoUpdates

Example Call SalTblDoDeletes ( tblExample, hSql, ROW_MarkDeleted )

SalTblDoInsertsSyntax bOk = SalTblDoInserts ( hWndTbl, hSql, bClearFlags )

Description 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.


hSql Sql Handle. The handle of an INSERT statement.

bClearFlags 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.




See Also SalTblDeleteSelectedSalTblDoDeletesSalTblDoUpdatesSalTblPopulate

Example Call SalTblDoInserts ( tblExample, hSql, FALSE )

SalTblDoUpdatesSyntax bOk = SalTblDoUpdates ( hWndTbl, hSql, bClearFlags )

Description 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.


hSql Sql Handle. The handle of an UPDATE statement.

bClearFlags 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.


See Also SalTblDeleteSelectedSalTblDoDeletesSalTblDoInsertsSalTblPopulate

Example Call SalTblDoUpdates ( tblExample, hSql, FALSE )

SalTblFetchRowSyntax nResult = SalTblFetchRow ( hWndTbl, nRow )

Description 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.


SalTblFindNextRow

The SAM_FetchRow message sets the context row to the row you specify before the table window receives the message.

Parameters hWndTbl Window Handle. The handle (or name) of the table window that owns the row being retrieved.

nRoNumber. The row number.

Return Value nResult is one of these values: TBL_RowDeleted, TBL_RowFetched, TBL_NoMoreRows.

See Also SalTblQueryContextSalTblSetContext

Example Call SalTblFetchRow ( hWndtblTelephone, nMaxRange )

SalTblFindNextRowSyntax bOk = SalTblFindNextRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff )

Description 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 Window Handle. The handle of the table window to search.

nRow 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.

nFlagsOn Number. The flags the row should have.

nFlagsOff 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 bOk is TRUE if SQLWindows finds a row and FALSE if there are no matches.

See Also SalTblFindPrevRowSalTblSetFlagsAnyRows

Example If SalTblFindNextRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )

SalTblFindPrevRowSyntax bOk = SalTblFindPrevRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff )

Description 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 Number. The flags the row should have.

nFlagsOff 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 bOk is TRUE if SQLWindows finds a row and FALSE if there are no matches.

See Also SalTblFindNextRowSalTblSetFlagsAnyRows

Example If SalTblFindPrevRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )


SalTblGetColumnText

SalTblGetColumnTextSyntax bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )

Description Gets data from a column of a table window's context row.


nColumnID Number. The Column Identifier

strText Receive string. The column data.


See Also SalTblSetColumnText

Example Set bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )

SalTblGetColumnTitleSyntax nLength = SalTblGetColumnTitle ( hWndCol, strText, nMaxLen )

Description Gets the title of a table window column.

Parameters hWndCol Window Handle. The handle (or name) of a table window column.

strText Receive String. The title.

nMaxLen Number. The maximum length of the title.

Return Value nLength is the length of the column title returned in strText.

See Also SalTblSetColumnTitle

Example Call SalTblGetColumnTitle ( colRowHeader, strTitle, 100 )

SalTblGetColumnWindowSyntax hWndCol = SalTblGetColumnWindow ( hWndTbl, nCol, nFlags )

Description Gets the handle of a table window column.

Parameters hWndTbl Window Handle. The handle (or name) of the table window that contains the column whose window handle you want.

nCol Number. A column position or a column identifier.

nFlags Number. A constant that identifies whether nCol's value is a column identifier or a column position. Specify either:



COL_GetID

COL_GetPos

Return Value hWndCol is the handle of a table window column. hWndCol is equal to hWndNULL if SQLWindows cannot find the table window column.

Example Set hWndCol = SalTblGetColumnWindow ( tbl1, nColID,COL_GetID )

SalTblInsertRowSyntax nNewRow = SalTblInsertRow ( hWndTbl, nRow )

Description Inserts a new blank row into a table window.


nRowNumber 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 nNewRow is the number of the new row if the function succeeds. It is equal to TBL_Error if an error occurs.

Example Set nNewRow = SalTblInsertRow ( hWndTbl,TBL_MinSplitRow )

SalTblKillEditSyntax bOk = SalTblKillEdit ( hWndTbl )

Description Takes a row out of edit mode and selects the row. This causes the row to receive both SAM_Validate and SAM_KillFocus messages.

Parameters hWndTbl Window Handle. The handle (or name) of the table window that contains the row just inserted or modified.


Example Set bOk = SalTblKillEdit ( hWndTbl )


SalTblKillFocus

SalTblKillFocusSyntax bOk = SalTblKillFocus ( hWndTbl )

Description 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.



Example Call SalTblKillFocus ( hWndForm )

SalTblObjectsFromPointSyntax bOk = SalTblObjectsFromPoint( hWndTable, nX, nY, nRow, hWndCol, nFlags )

Description Returns the part of the table window located at a given coordinate.

These flags indicate the part where the X coordinate is located:

TBL_XOverLockedColumnsTBL_XOverLockedColumnsBorderTBL_XOverRowHeaderTBL_XOverUnlockedColumnsThese flags indicate the part where the Y coordinate is located:

TBL_YOverColumnHeaderTBL_YOverNormalRowsTBL_YOverSplitBarTBL_YOverSplitRows

Parameters 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.

nRow Receive Number. If nY is over a row then the row number is returned in nRow; otherwise nRow is TBL_Error.

hWndCol Receive Window Handle. If nX is over a column then its window handle is returned in hWndCol; otherwise hWndCol is hWndNULL.

nFlags Receive Number. The part of the table. These flags indicate the part where the X coordinate is located.




No Example

See Also SAM_ContextMenu

SalTblPasteRowsSyntax bOk = SalTblPasteRows ( hWndTbl )

Description 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 hWndTbl Window Handle. The handle (or name) of the table window receiving the data from the Clipboard.

Return Value 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.

See Also SalTblCopyRows

Example Call SalTblPasteRows ( tblPhoneList )

SalTblPopulateSyntax bOk = SalTblPopulate( hWndTbl, hSql, strSelect, nMethod )

Description 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.


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 Window Handle. The handle (or name) of the table window to populate.

hSql 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.

strSelect 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.

nMethod Number. How to populate the table window. Specify one of these values:

TBL_FillAll

TBL_FillAllBackground

TBL_FillNormal

Return Value bOk is TRUE if the function succeeds and FALSE if either hWndTbl or hSql is invalid.

See Also SalTblDeleteSelectedSalTblDoDeletesSalTblDoInsertsSalTblDoUpdates

Example Call SalTblPopulate ( tblExample, hSql, strSql, TBL_FillAllBackground )

SalTblPopulateFromXMLSyntax bOk = SalTblPopulateFromXML (hWndTbl, sFile, sRootNode, bTableNode,

bUseSchema)

Description 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 Gupta’s naming conventions and structures. It is not possible to populate a table



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 window’s columns were created at design time, the length of each column’s 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 column’s 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 Window Handle. The handle (or name) of the table window to populate.

sFile String. The name of the XML document file containing data to be used to populate the table.

sRootNode 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.

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.

bUseSchema 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


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.

SalTblQueryCheckBoxColumnSyntax bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue,

sUncheckedValue )

Description 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.



nFlags Receive Number. nFlags is a combination of the following flags using the '|' operator:

COL_CheckBox_IgnoreCase = 0x0001

sCheckedValue Receive String. sCheckedValue is the value that a cell will get when the check box is checked.

sUncheckedValue Receive String. The value when a check box is unchecked.


Example bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags,sCheckedValue, sUncheckedValue )

SalTblQueryColumnCellTypeSyntax bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType )

Description Indicates whether a column is a checkbox, drop down list, popup edit, or standard column.


hWindCol Window Handle. The handle (or name) of a table window column.



nType Receive Number. Receives one of the following values.

COL_CellType_Standard = 1

COL_CellType_CheckBox = 2

COL_CellType_DropDownList = 3

COL_CellType_PopupEdit = 4


Example Set bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType )

SalTblQueryColumnFlagsSyntax bSet = SalTblQueryColumnFlags ( hWndCol, nFlags )

Description Tests the state of a table window column's flags.


nFlags Number. The column flags to test. You can combine COL_* flags using the OR (|) operator.

Return Value bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise.

See Also SalTblSetColumnFlags

Example If SalTblQueryColumnFlags ( col1, COL_CenterJustify )Set rbCenter = TRUE

ElseSet rbLeft = TRUE

SalTblQueryColumnIDSyntax nColID = SalTblQueryColumnID ( hWndCol )

Description Gets a table window column's identifier.

Parameters hWndCol Window Handle. The handle of a table window column.

Return Value nColID is the Column Identifier. nColID is -1 if hWndCol is not a valid column.

Example Set nColID = SalTblQueryColumnID ( hWndCol )Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )

SalTblQueryColumnPosSyntax nPos = SalTblQueryColumnPos ( hWndCol )


SalTblQueryColumnWidth

Description Gets a table window column's relative position.

Parameters hWndCol Window Handle. The handle of a table window column.

Return Value nPos is the Column Position. nPos is -1 if hWndCol is not a valid handle for a table window column.

See Also SalTblSetColumnPos

Example Set nPos = SalTblQueryColumnPos ( hWndCol )

SalTblQueryColumnWidthSyntax bOk = SalTblQueryColumnWidth ( hWndTbl, nFormUnits )

Description Returns the width (in form units) of a table window column.

Parameters hWndTbl Window Handle. The handle (or name) of a table window column.

nInches Receive Number. The width of the table window column.


See Also SalTblSetColumnWidth

Example Call SalTblQueryColumnWidth ( colRowHeader, nWidth )

SalTblQueryContextSyntax nContext = SalTblQueryContext ( hWndTbl )

Description 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.


Return Value nContext is the current context row number.

See Also SalTblFetchRowSalTblSetContext

Example Set nContext = SalTblQueryContext ( hWndTbl )

SalTblQueryDropDownListColumn



Syntax bOk = SalTblQueryDropDownListColumn( hWnd, hWndCol, nFlags, nLines )

Description 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.







COL_DropDownList_Editable = 0x0008

nLines Receive Number. nLines indicates the maximum number of lines to display in the list.


Example Set bOk = SalTblQueryDropDownListColumn ( hWnd, hWndCol,nFlags, nLines )

SalTblQueryFocusSyntax bOk = SalTblQueryFocus ( hWndTbl, nRow, hWndCol )

Description Identifies the cell in a table window with the focus.


nRoReceive Number. The row number of the focus row.

hWndCol Receive Window Handle. The handle of the column with the focus.


See Also SalTblSetFocusCellSalTblSetFocusRow

Example On SAM_ClickCall SalTblQueryFocus ( hWndtblTelephone,

nRow,hWndColumn )


SalTblQueryLinesPerRow

SalTblQueryLinesPerRowSyntax bOk = SalTblQueryLinesPerRow( hWndTbl, nLines )

Description Retrieves the height of a row in lines.

Parameters HWndTbl Window Handle. The handle (or name) of a table window.

nLines Receive Number. The number of lines.


Example Set bOk = SalTblQueryLinesPerRow( hWndTbl, nLines )

SalTblQueryLockedColumnsSyntax nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )

Description 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.


Return Value nLockedColumns is the number of locked columns. If there are no locked columns, nLockedColumns is zero (0).

See Also SalTblSetLockedColumns

Example Set nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )

SalTblQueryPopupEditColumnSyntax bOk = SalTblQueryPopupEditColumn( hWnd, hWndCol, nFlags, Lines )

Description 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.









COL_DropDownList_Editable = 0x0008

nLines Receive Number. nLines indicates the maximum number of lines to display in the list.


Example Set bOk = SalTblQueryPopupEditColumn ( hWnd, hWndCol, nFlags, Lines )

SalTblQueryRowFlagsSyntax bOk = SalTblQueryRowFlags ( hWndTbl, nRow, nFlags )

Description Queries a row's flags.


nRoNumber. The row number of the row whose flags you want to test.

nFlags Number. The row flags to test for. You can combine ROW_* flags using the OR (|) operator.

Return Value bOk is TRUE if any of the specified flags are set and FALSE if none of the specified flags are set.

See Also SalTblSetFlagsAnyRowsSalTblSetRowFlags

Example On SAM_SetFocusIf SalTblQueryRowFlags ( hWndForm, lParam, ROW_New )

SalTblQueryRowHeaderSyntax bOk = SalTblQueryRowHeader ( hWndTbl, strTitle, nMaxTitle, nWidth,

nFlags, hWndCol )

Description 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.


strTitle Receive String. The title of the row header.

nMaxTitle Number. The maximum length of the title.

nWidth 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.


Example Call SalTblQueryRowHeader ( tbl1, strTitle, 100, nWidth, nFlags, colRowHeader )

SalTblQueryScrollSyntax bOk = SalTblQueryScroll ( hWndTbl, nPosition, nMinRange, nMaxRange )

Description 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.


nPosition Receive Number. The scroll position.

nMinRange Receive Number. The minimum table range.

nMaxRange Receive Number. The maximum table range.


Example Call SalTblQueryScroll ( hWndTbl, nPosRow, nMinRow, nMaxRow )

SalTblQuerySplitWindowSyntax bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax

bDragAdjust )

Description Specifies how a table window is split horizontally.

Parameters hWndTbl Window Handle. The handle (or name) of a split table window.



nRowLowerHalf Receive Number. The number of visible rows in the lower half of the split window. If zero (0), the table is not split.

bDragAdjust Receive Number Boolean. Specify whether (TRUE) or not (FALSE) the user can drag-adjust the visible rows in both halves of a split window.


Example Set bOk = SalTblQuerySplitWindow ( hWndTbl,nRowsLowerHalf,Syntax,bDragAdjust )

SalTblQueryTableFlagsSyntax bSet = SalTblQueryTableFlags ( hWndTbl, nFlags )

Description Tests the state of a table window's flags.


nFlags Number. The table flags to test. You can combine TBL_* flags using the OR (|) operator.

Return Value bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise.

See Also SalTblSetTableFlags

Example If SalTblQueryTableFlags ( tbl1, TBL_Flag_MoveableCols )Set rbColsMovable = TRUE

SalTblQueryVisibleRangeSyntax bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )

Description Returns the current range of visible rows in a table window.


nRangeMin Receive Number. The first visible row.

nRangeMax Receive Number. The last visible row.


Example Set bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )

SalTblResetSyntax bOk = SalTblReset ( hWndTbl )


SalTblScroll

Description Clears a table window by discarding all rows from the table window cache and setting the table range to 0, -1.



See Also SalTblSetRange

Example If nRowCount > 0Call SalTblReset ( hWndForm )

SalTblScrollSyntax bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )

Description Scrolls a table window to the specified row and column.


nRoWNumber The number of the row to scroll to. If you specify -1, only the column scrolls into view.

hWndColumn Window Handle. The table window column to scroll into view. If you specify hWndNULL, only the row scrolls into view.

nTBLScroll Number. The position of the scroll row. Specify one of these:

TBL_AutoScroll

TBL_ScrollBottom

TBL_ScrollTop

Return Value 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.

See Also SalTblQueryScrollSalTblQueryVisibleRange

Example Set bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )

SalTblSetCellTextColorSyntax bOk = SalTblSetCellTextColor ( hWndCol, nColor, bDiscardable )

Description Changes a table window cell's text color.




nColor Number. The cell text color. Specify one of the predefined windows colors.

bDiscardable 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.


Example On SAM_FetchRowCall SalTblSetCellTextColor ( Col1, COLOR_Red, TRUE )Return TBL_RowFetched


SalTblSetColumnFlags

SalTblSetColumnFlagsSyntax bOk = SalTblSetColumnFlags ( hWndCol, nFlags, bSet )

Description Sets or clears a table window column's flags.


nFlags Number. The column flags to change. You can combine COL_* flags using the OR (|) operator.

bSet Boolean. If TRUE, SQLWindows sets the flags; if FALSE, SQLWindows clears the flags.

Return Value 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 SalTblQueryColumnFlags

Example Call SalTblSetColumnFlags ( col1, COL_CenterJustify, TRUE )

SalTblSetColumnPosSyntax bOk = SalTblSetColumnPos ( hWndCol, nPos )

Description Moves a table window column to a new position.

Parameters hWndCol Window Handle. The handle (or name) of a table window column to move.

nPos Number. The new position of the table window column. 1 is the first (left-most) position, 2 is the second position, and so on.


See Also SalTblQueryColumnPos

Example Call SalTblSetColumnPos ( col3, nPos + 1 )

SalTblSetColumnTextSyntax bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )

Description Assigns data to a column of a table window's context row.




nColumnID Number. The Column Identifiers

strText String. The data to assign.


See Also SalTblGetColumnText

Example Set bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )

SalTblSetColumnTitleSyntax bOk = SalTblSetColumnTitle ( hWndCol, strTitle )

Description Sets the title of a table window column.


strTitle String. The title of the table window column.


See Also SalTblGetColumnTitle

Example Set bOk = SalTblSetColumnTitle ( hWndCol, strTitle )

SalTblSetColumnWidthSyntax bOk = SalTblSetColumnWidth ( hWndTbl, nFormUnits )

Description Sets a table window column's display width.

Parameters hWndTbl Window Handle. The handle (or name) of a table window column.

nFormUnits Number. The table window column's display width in form units.


See Also SalTblQueryColumnWidth

Example Set nColID = SalTblQueryColumnID ( hWndCol )Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )


SalTblSetContext

SalTblSetContextSyntax bOk = SalTblSetContext ( hWndTbl, nRow )

Description 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.


See Also SalTblQueryContext

Example Set bOk = SalTblSetContext ( hWndTbl, nRow

SalTblSetFlagsAnyRowsSyntax bAny = SalTblSetFlagsAnyRows ( hWndTbl, nFlags, bSet,

nFlagsOn, nFlagsOff )

Description Sets or clears row flags.

Parameters hWndTbl Window Handle. The handle (or name) of a table window whose row flags you want to set or clear.

nFlags Number. The flags to change. You can combine flag values using the OR (|) operator.

bSet Boolean. Whether to set (TRUE) or clear (FALSE) the specified flags.

nFlagsOn 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.



Return Value bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags and none of the nFlagsOff flags.

See Also SalTblFindNextRowSalTblFindPrevRow

Example Call SalTblSetFlagsAnyRows ( tblExample, ROW_MarkDeleted, TRUE, ROW_Selected, 0 )

SalTblSetFocusCellSyntax bOk = SalTblSetFocusCell ( hWndTbl, nRow, hWndCol, nEditMin, nEditMax )

Description 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.


nRowNumbe The row that receives the edit focus.

hWndCol Window Handle. The handle (or name) of the column that receives the edit focus.

nEditMin 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.


See Also SalTblQueryFocus

Example Call SalTblSetFocusCell ( hWndForm, lParam,hWndItem, 0, 1 )


SalTblSetFocusRow

SalTblSetFocusRowSyntax bOk = SalTblSetFocusRow ( hWndTbl, nRow )

Description Sets a table window's focus frame row.


nRoNumber. The row number of the row to which to apply the focus frame.


See Also SalTblQueryFocus

Example Set bOk = SalTblSetFocusRow ( hWndTbl, nRow

SalTblSetFromXMLSchemaSyntax bOk = SalTblSetFromXMLSchema ( hWndTbl, sSchemaFile, sSchemaName )

Description 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.

Parameters hWndTbl Window Handle. The handle (or name) of the table window to validate.

sSchemaFile String. The name of the XML schema file containing attributes to be used for validation.

sSchemaName String. The name of the schema within the schema file.


See Also SalTblPopulateFromXML

SalTblSetLinesPerRowSyntax bOk = SalTblSetLinesPerRow( hWndTbl, nLines )

Description 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.



nLines Number. The number of lines.


Example Set bOk = SalTblSetLinesPerRow( hWndTbl, nLines )

SalTblSetLockedColumnsSyntax bOk = SalTblSetLockedColumns ( hWndTbl, nLockedColumns )

Description 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.


nLockedColumns Number. The number of table window columns to lock.


See Also SalTblQueryLockedColumns

Example Call SalTblSetLockedColumns ( tbl1, 2 )

SalTblSetRangeSyntax bOk = SalTblSetRange ( hWndTbl, nMin, nMax )

Description Defines the minimum and maximum rows (range) of a table.

Parameters hWndTbl The handle (or name) of a table window.

nMin Number. The lower boundary of the table window.

nMax 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.



SalTblSetRow

See Also SalTblReset

Example Call SalTblSetRange ( hWndForm, 0, nRowCount - 1 )

SalTblSetRowSyntax nRowNum = SalTblSetRow ( hWnd, nRowPos )

Description Sets the focus to the first, last, next, or previous row in a table window.

Parameters tName Window Handle. The handle (or name) of the window whose current focus row you want to change.

nRowPos Number. The position of the focus row. Specify one of these values:

TBL_SetFirstRow

TBL_SetLastRow

TBL_SetNextRow

TBL_SetPrevRow

Return Value nRowNum is the row number of the new focus row.

Example Set = nRowNum = SalTblSetRow ( hWnd, nRowPos )

SalTblSetRowFlagsSyntax bOk = SalTblSetRowFlags ( hWndTbl, nRow, nFlags, bSet )

Description Sets or clears a table window row's flags.


nRoNumber. The row number of the row whose flags you want to set or clear.

nFlags Number. The row flags. You can combine any of the ROW_* flags using the OR (|) operator.



See Also SalTblQueryRowFlagsSalTblSetFlagsAnyRows

Example Call SalTblSetRowFlags ( hWndTbl, nRow, ROW_Selected, TRUE )



SalTblSetTableFlagsSyntax bOk = SalTblSetTableFlags ( hWndTbl, nFlags, bSet )

Description Sets or clears a table window's flags.


nFlags Number. The table flags. You can combine any of the TBL_* flags using the OR (|) operator.



See Also SalTblQueryTableFlags

Example Call SalTblSetTableFlags ( tbl1, TBL_Flag_MoveableCols, FALSE)


SalTblSortRows

SalTblSortRowsSyntax bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )

Description 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.


nColumnID Number. The Column Identifier of the column by which to sort.

nOrder Number. The direction of the sort. Specify either:

TBL_SortDecreasing

TBL_SortIncreasing

Return Value bRet is TRUE if the function succeeds and FALSE if nColumnID is not a valid identifier.

Example Set bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )

SalTblWriteXMLandSchemaSyntax bOk = SalTblWriteXMLandSchema ( hWndTbl, sPath, bFrontEnd, nWriteTypes )

Description 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.



sPath String. The path and name of the output file. Note that the schema file will have the same name, plus the suffix _SCHEMA.

bFrontEnd 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.

nWriteTypes Number. One of the XML constants, determining whether to write XML, schema, or both.


Example SalTblWriteXMLandSchema (tblOrders, “c:\\My Documents\ORDERS”, TRUE, XML_DocAndSchema)

See Also SalTblWriteXMLandSchemaEx

SalTblWriteXMLandSchemaExSyntax bOk = SalTblWriteXMLandSchemaEx ( hWndTbl, sPath, bFrontEnd,

nWriteTypes, nFlagsOn, nFlagsOff )

Description 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.


sPath String. The path and name of the output file. Note that the schema file will have the same name, plus the suffix _SCHEMA.

bFrontEnd 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.)


SalTimerKill

nWriteTypes Number. One of the XML constants, determining whether to write XML, schema, or both.

nFlagsOn 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.

nFlagsOff 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.


Example 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)

SalTimerKillSyntax bOk = SalTimerKill ( hWnd, nIDEvent )

Description 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 Window Handle. The handle (or name) of an object.

nIDEvent Number. The timer ID to kill.

Return Value bOk is TRUE if SQLWindows successfully kills the event and FALSE if SQLWindows cannot find the specified timer.

See Also SalTimerSet

Example On SAM_DestroyCall SalTimerKill ( dfClock, 1 )

SalTimerSetSyntax bOk = SalTimerSet ( hWnd, nIDEvent, nElapseMilliSec )

Description Creates a system timer for a given object. When a timer event occurs, SQLWindows sends SAM_Timer messages to the object in specified intervals.



Timers are a limited global resource. Your application must check the value returned by SalTimerSet to verify that the timer was created.

Parameters hWnd Window Handle. The handle (or name) of an object associated with a system timer.

nIDEvent Number. The timer ID number.

nElapseMilliSec Number. The elapsed time between each SAM_Timer message, in milliseconds.


See Also SalTimerKill

Example On SAM_CreateSet bOk = SalTimerSet ( hWndItem, 1, 1000 )

SalTraceSyntax bOk = SalTrace ( nSeverity, strTextToWrite )

Description Writes a string of text to the trace output target that was specified in an earlier call to SalStartTrace.

Parameters 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 log’s severity system. When output is going to some other target, such as a file, these numeric values are translated into text strings.

strTextToWrite String. The text of the trace message.



SalEndTrace

Example bOk = SalTrace (EVENT_Warning, 'User entered a null password')

SalTrackPopupMenuSyntax bOk = SalTrackPopupMenu ( hWndProcMsgs, strMenuName, nFlags, nX, nY )

Description Creates pop-up menus at runtime.


SalUpdateWindow

Parameters hWndProcMsgs Window Handle. The handle (or name) of the top-level window that processes messages generated by the pop-up menu.

strMenuName 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.

nFlags Number. Specifies how the pop-up menu displays. You can combine flag values using the OR (|) operator.

nX 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.

nY 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.

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.


Example On SAM_ClickCall SalTrackPopupMenu ( hWndForm, 'menuEdit', TPM_CursorX | TPM_CursorY | TPM_CenterAlign, 0, 0 )

SalUpdateWindowSyntax bOk = SalUpdateWindow ( hWndUpdate )

Description 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.



Return Value bOk is TRUE if the function succeeds and FALSE if hWndUpdate is not a valid window handle.

See Also SalInvalidateWindow

Example Message ActionsOn SAM_FieldEdit

Call SalUpdateWindow ( ml1 )

SalUseEventLogSyntax bOk = SalUseEventLog( bUseEventLog, bContinueProcessing )

Description 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 bOk is TRUE if the function succeeds and FALSE if function fails.

Example Set bOk = SalUseEventLog( TRUE, TRUE )

SalUseRegistrySyntax 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 - TRUE if registry is to be used, FALSE if INI files are to be used.

sCompanyName - Name of company to be used under the registry.

Return Value bOk is TRUE if the function succeeds and FALSE if function fails.

Example Set bOk = SalUseRegistry( bUseRegistry, sCompanyName )

SalValidateSetSyntax bOk = SalValidateSet ( hWndCC, bValState, lParam )

Description 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 Handle of the custom control.

bValState Validates this custom control when it loses the focus.

lParam 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



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 )

SalWaitCursorSyntax bOk = SalWaitCursor ( bOn )

Description 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 bOn Boolean. Whether to turn the hourglass on (TRUE) or off (FALSE).


Example Call SalWaitCursor ( TRUE )

SalWindowClassNameSyntax sClassName = SalWindowClassName( hWnd )

Description Return the name of a window's class as a string.

Parameters hWnd Window Handle. The window handle of an instance of a Window Class object.

Return Value Returns an empty string if the window is not a class object.

Example Set sClassName = SalWindowClassName( hWnd )

SalWindowGetDockSettingSyntax bOk = SalWindowGetDockSetting ( hWndDlg, nOrientation )

Description 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.


SalWindowGetProperty

Parameters hWnd Window Handle. The handle (or name) of the top-level window.

nOrientation 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.

Return Value bRet is TRUE if the docking information is found and FALSE if an error occurs.

See Also SalDlgGetDockStatus, SalDlgSetDockStatus

Example Call SalWindowGetDockSetting ( hWndForm, nDock )

SalWindowGetPropertySyntax bOk = SalWindowGetProperty( hWndQO, strPropName, strPropValue )

Description 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.

Parameters hWndQO Window Handle. The window handle of an instance of a QuickObject.

strPropName String. The name of the property.

strPropValue Receive String. The value of the property.


Example This example gets a window name property:

Set bOk = SalWindowGetProperty( hWndItem, 'WindowName',strWindowName )



SalWindowHandleToNumberSyntax nWnd = SalWindowHandleToNumber ( hWnd )

Description 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 hWnd Window Handle. The handle to convert.

Return Value nWnd is the number converted from hWnd.

See Also SalNumberToWindowHandle

Example Set ntblCustomer = SalWindowHandleToNumber( hWndtblCustomer )

SalWindowIsDerivedFromClassSyntax bOk = SalWindowIsDerivedFromClass( hWnd, ClassName )

Description 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 late-bound 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 Window Handle. The handle (or name) of the window.

ClassName Symbol. The ClassName parameter is a symbol, not a string. Type the class name without single quotes.

Return Value 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.

Example Set bOk = SalWindowIsDerivedFromClass( hWnd, ClassName )

SalWinHelpSyntax bOk = SalWinHelp( hWnd, strFile, nCommand, nData,

strData )


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 Window Handle. The handle (or name) of the window requesting help.

strFile String. The file name of the help system file.

nCommand Number. The type of help requested; any HELP_* value.

nData 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.


Example Call SalWinHelp ( hWndForm, 'CONTROL.HLP', HELP_Index, 0, '')

SalXMLDeserializeUDVSyntax bOk = SalXMLDeserializeUDV ( sUDV, sFilename, sSchema )

Description 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.



If an error occurs, this function will return FALSE. You can then call SalXMLGetLastError to get the text of the error.

Parameters sUDV String. The name of the UDV or array to be overwritten.

sFilename String. The name of the XML file containing the data.

sSchema String. Reserved for future use. Any value specified will be ignored.


See Also SalXMLSerializeUDVExample Call SalXMLDeserializeUDV( ‘oMyInvoice’, ‘invoice.xml’, ‘’ )

SalXMLGetLastErrorSyntax bOk = SalXMLGetLastError ( nError, sError)

Description 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 Receive Number. The internal error code. If the most recent XML operation succeeded, this value will be zero

sError Receuve String. The descriptive text associated with the value of nError. If the most recent XML operation succeeded, this value will be empty.


See Also SalXMLDeserializeUDVSalXMLSerilaizeUDV

Example Call SalXMLGetLastError( nReturn, sDescription )

SalXMLSerializeUDVSyntax bOk = SalXMLSerializeUDV ( sUDV, sFilename, nWriteStyle )

Description 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.


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 UDV’s 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 String. The name of the UDV or array to be written.

sFilename String. The name of the XML file to contain the data.

nWriteStyle String. Reserved for future use. Any value specified will be ignored.


See Also SalXMLDeserializeUDVExample Call SalXMLSerializeUDV( ‘oMyInvoice’, ‘invoice.xml’, ‘’ )

SalYieldEnableSyntax bOk = SalYieldEnable ( bSet )

Description Enables or disables application yielding.

Parameters bSet Boolean. If TRUE, enable yielding; if FALSE, disable yielding.




See Also SalYieldQueryStateSalYieldStartMessagesSalYieldStopMessages

Example Call SalYieldEnable( FALSE )

SalYieldQueryStateSyntax bEnabled = SalYieldQueryState ( )

Determines whether application yielding is enabled or disabled.


Return Value bEnabled is TRUE if yielding is enabled, and FALSE if it is not.

See Also SalYieldEnableSalYieldStartMessagesSalYieldStopMessages

Example Set bEnabled = SalYieldQueryState ( )

SalYieldStartMessagesSyntax bOk = SalYieldStartMessages ( hWnd )

Description 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.



See Also SalYieldEnableSalYieldQueryStateSalYieldStopMessages

Example Call SalYieldStartMessages ( pbCancel )


SalYieldStopMessages

SalYieldStopMessagesSyntax bOk = SalYieldStopMessages ( )

Description Stops yielding and the sending of messages to the window specified in a prior call to SalYieldStartMessages.



See Also SalYieldEnableSalYieldQueryStateSalYieldStartMessages

Example Call SalYieldStopMessages ( )

SqlClearImmediateSyntax bOk = SqlClearImmediate ( )

Description 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.



See Also SqlImmediate

Example Set bOk = SqlClearImmediate ( )

SqlCloseSyntax bOk = SqlClose ( hSql )

Description 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.




See Also SqlOpen

Example Set bOk = SqlClose ( hSql )

SqlCloseAllSPResultSetsSyntax bOk = SqlCloseAllSPResultSets ( hSql )

Description 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 hSql Sql Handle. The sql handle on which the Stored Procedure was prepared.



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 SqlGetNextSPResultSetSqlPrepareSP


SqlCommit

SqlCommitSyntax bOk = SqlCommit ( hSql )

Description 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.



Example Call SqlCommit ( hSql )

SqlCommitSessionSyntax bOk = SqlCommitSession ( hSession )

Description 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 hSession Session Handle. The session handle used to commit the transaction.



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 SqlCreateSessionSqlCreateStatementSqlFreeSession



SqlGetSessionHandle

SqlConnectSyntax bOk = SqlConnect ( hSql )

Description 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 hSql Receive Sql Handle. A handle that identifies a database connection.


See Also SqlDisconnect


SqlContextClear

Example Call SqlConnect ( hSqlPrimary )

SqlContextClearDeprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup.

Syntax bOk = SqlContextClear ( hSql )

Description 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.



See Also SqlContextSetSqlContextSetToFormSqlImmediateContext

Example Set bOk = SqlContextClear ( hSql )

SqlContextSetDeprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup.

Syntax bOk = SqlContextSet ( hSql )

Description 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.





See Also SqlContextClearSqlContextSetToFormSqlImmediateContext

Example Set bOk = SqlContextSet ( hSql )

SqlContextSetToFormDeprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup.

Syntax bOk = SqlContextSetToForm ( hSql, hWndMyForm )

Description 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.


hWndMyForm Window Handle. The handle of the window to which to set the execution context.

See Also SqlContextClearSqlContextSetSqlImmediateContext

Example Set bOk = SqlContextSetToForm ( hSql, hWndMyForm )

SqlCreateSessionSyntax bOk = SqlCreateSession ( hSession, strSessionProperties )

Description 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.


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



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 bOk is TRUE if a new session was created successfully. If the call failed, it returns FALSE.

Example 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 SqlCommitSessionSqlCreateStatementSqlFreeSessionSqlGetSessionHandle

SqlCreateStatementSyntax bOk = SqlCreateStatement ( hSession, hSql )

Description 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.


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 Session Handle. The Session handle used to create the statement.

hSql Sql Handle The Sql handle used to associate any number of statements to a session.

Return Value bOk is TRUE if a statement was created successfully. If the call failed, it returns FALSE.

Example 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 SqlCommitSessionSqlCreateSessionSqlFreeSessionSqlGetSessionHandle

SqlDirectoryByNameSyntax bOk = SqlDirectoryByName ( strServerName, strArrayNames )

Description Returns the database names on the specified server.

Parameters strServerName String. The name of a server.

strArrayNames String Array. The name of an array of strings containing database names.


Example On SAM_AppStartupCall SqlDirectoryByName ( 'server1', strDatabaseNames )

SqlDisconnectSyntax bOk = SqlDisconnect ( hSql )

Description Disconnects from a database.


Disconnecting the last Sql Handle from a database causes an implicit COMMIT of the database. Disconnect all Sql Handles before the application exits.

Parameters hSql Sql Handle. The handle that identifies the database connection to disconnect.


See Also SqlConnect

Example On SAM_AppExitCall SqlDisconnect ( hSqlPrimary )

SqlDropStoredCmdSyntax bOk = SqlDropStoredCmd ( hSql, strName )

Description Deletes a stored command from a SQLBase database.


strName String. The name of the stored command to delete.


See Also SqlRetrieveSqlStore

Example Call SqlDropStoredCmd ( hSqlPrimary, 'PRODUCTS )

SqlErrorSyntax nError = SqlError ( hSql )

Description 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 hSql Sql Handle. The handle on which an error occurred.

Return Value nError is the error code returned. It is equal to zero (0) if no error occurred.

See Also SqlExtractArgs

Example Set nSqlError = SqlError ( hSqlPrimary )

SqlErrorText

SqlExecute

Syntax bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength )

Description 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 Number. A SQLBase error code.

nType Number. Specify one or both (by combining them with the OR (|) operator) of these constants:

strError Receive String. The reason or remedy explanation.

nLength Number. The maximum length of strError.

nRealLength Receive Number. The actual length of strError.


See Also SqlErrorSqlGetErrorTextSqlGetErrorTextX

Example Set bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength )

SqlExecuteSyntax bOk = SqlExecute ( hSql )

Description 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.


SQLERROR_Reason Retrieve error code reason.

SQLERROR_Remedy Retrieve error message remedy.



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 hSql Sql Handle. The handle associated with a SQL statement.


See Also SqlOpen

Example Call SqlExecute ( hSqlPrimary )

SqlExecutionPlanSyntax bOk = SqlExecutionPlan ( hSql, strString, nLength )

Description 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.

Parameters hSql Sql Handle. The handle associated with a compiled SQL statement.

strString String. The execution plan. Also, a Receive parameter.

nLength Number. The maximum length of the execution plan. Also, a Receive parameter.


Example Set bOk = SqlExecutionPlan ( hSql, strString, nLength )

SqlExistsSyntax bOk = SqlExists ( strSelect, bExists )

Description 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 String. The SELECT statement that establishes the existence of a row.

bExists Receive Boolean. TRUE if the row exists and FALSE if it does not.

Return Value bOk is TRUE if strSelect is correct and executable and FALSE otherwise.


SqlExtractArgs

Example Call SqlExists ( 'SELECT * FROM ' || strTable || 'WHERE ' || strExistsColumn || ' = ' || '\'' || strExistsObject || '\'', bExists )

SqlExtractArgsSyntax bOk = SqlExtractArgs ( wParam, lParam, hSql, nError,

nPos )

Description 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.

Parameters wParam Number. The value of the wParam argument of the SAM_SqlError message.

lParam Number. The value of the lParam argument of the SAM_SqlError message.

hSql Receive Sql Handle. The handle of the function that got an error. SQLWindows extracts this value from the wParam argument.

nError Receive Number. The error code. SQLWindows extracts this value from the low-order word of the lParam argument.

nPos Receive number. The error position, if relevant to the function call. SQLWindows extracts this value from the high-order word of the lParam argument.


See Also SqlErrorSqlGetErrorPosition

Example Call SqlExtractArgs ( wParam, lParam, hSqlError, nSqlError, nErrorPos )

SqlFetchNextSyntax bOk = SqlFetchNext ( hSql, nInd )

Description 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.

Parameters hSql Sql Handle. The handle of a SELECT statement.



nInd Receive Number. The fetch return code is one of the FETCH_* values.

Return Value 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.

See Also SqlFetchPreviousSqlFetchRow

Example Call SqlFetchNext ( hSqlPrimary, nRetVal )

SqlFetchPreviousSyntax bOk = SqlFetchPrevious ( hSql, nInd )

Description 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.



Return Value bOk is TRUE if there is another row to fetch and FALSE otherwise.

See Also SqlFetchNext

SqlFetchRow

Example Call SqlFetchPrevious ( hSqlPrimary, nRetVal)

SqlFetchRowSyntax bOk = SqlFetchRow ( hSql, nRow, nInd )

Description 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.


nRoNumber. The row number of the row to fetch.


SqlFreeSession


Return Value bOk is TRUE if nRow could be fetched and FALSE otherwise.

See Also SqlFetchNextSqlFetchPrevious

Example Call SqlFetchRow ( hSqlPrimary, lParam, nRetVal )

SqlFreeSessionSyntax bOk = SqlFreeSession ( hSession )

Description This call frees the session. If there are any open statements belonging to this session, they are closed before the session is freed.


Return Value bOk is TRUE if the specified session was freed successfully. If the call failed, it returns FALSE.

Example 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 SqlCommitSessionSqlCreateSessionSqlCreateStatementSqlGetSessionHandle

SqlGetCmdOrRowsetPtrSyntax bOk = SqlGetCmdOrRowsetPtr ( hSql, bCmdOrRowset, numOLEDBPtr )

Description 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).



Parameters hSql Sql Handle. The Sql handle associated with the Command or the Rowset object.

bCmdOrRowset 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.

numOLEDBPtr 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.


Example 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 SqlGetDSOrSessionPtr

SqlGetCommandTextSyntax bOk = SqlGetCommandText (hSql, sText)

Description 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 doesn’t 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.


SqlGetCursor

Parameters hSql Sql Handle. The Sql handle associated with the desired statement handle.

sText Receive String. The text of the command that was prepared.

Return Value bOk Boolean. TRUE for success and FALSE for failure.

SqlGetCursorSyntax nCursorHandle = SqlGetCursor ( hSql )

Description 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 hSql Sql Handle. The logical SQL handle for which you seek the statement handle.

Return Value nCursorHandle Number. Use this cursor handle when calling a large number of SQLBase API functions that require such a handle.

SqlGetDSOrSessionPtrSyntax bOk = SqlGetDSOrSessionPtr ( hSql, bDSOrSession, numOLEDBPtr )

Description 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 Sql Handle. The Sql handle associated with the interface pointer.

bDSOrSession 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.

numOLEDBPtr Number. NULL if there is no rowset associated with this Sql Handle yet, and if the user asks for the IDBInitialize interface pointer.




Example 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

SqlGetErrorSyntax bOk = SqlGetError( hSql, nError, strErrorString )

Description 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.



nError Number. The error number.

strErrorString String. The error text.


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 )

SqlGetErrorPositionSyntax bOk = SqlGetErrorPosition ( hSql, nPos )


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.


nPos Receive Number. The position in the SQL statement where aSyntax error occurred.


See Also SqlExtractArgs

Example Call SqlGetErrorPosition ( hSqlPrimary, nErrorPos )

SqlGetErrorTextSyntax bOk = SqlGetErrorText ( nError, strText )

or

strText = SqlGetErrorTextX ( nError )

Description Gets the message text for a SQL error number from ERROR.SQL.


Parameters nError Number. The error number.

strText Receive String. The error text.


strText is the message text for nError.

See Also SqlErrorTextSqlExtractArgs

Example Call SqlGetErrorText ( nError, strText )

or

Set strText = SqlGetErrorTextX ( nError )



SqlGetErrorTextXSyntax strText = SqlGetErrorTextX (nError)Description 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.

Example Set strErrorText = SqlGetErrorTextX ( nSqlError )

SqlGetLastStatementSyntax sSqlStatement = SqlGetLastStatement( )

Description 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.


Return Value sSqlStatement contains the last SQL statement.

Example When SqlErrorSet sStatement = SqlGetLastStatement()

SqlGetModifiedRowsSyntax bOk = SqlGetModifiedRows ( hSql, nCount )

Description Returns the number of rows affected by the most recent INSERT, UPDATE, or DELETE statement.

Parameters hSql Sql Handle. The handle of a SQL statement.

nCount Receive Number. The number of rows affected.


Example Set bOk = SqlGetModifiedRows ( hSql, nCount )


SqlGetNextSPResultSet

SqlGetNextSPResultSetSyntax bOk = SqlGetNextSPResultSet ( hSql, strIntoList, bEndOfRS )

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.

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 Sql Handle. The sql handle on which the Stored Procedure should be executed.

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.

bEndOfRS 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.


Example 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)



See Also SqlCloseAllSPResultSetsSqlPrepareSP

SqlGetParameterSyntax bOk = SqlGetParameter ( hSql, nParameter, nNumber, strString )

Description 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.


nParameter Number. The database parameter. Specify one of the DBP_* constants.

nNumber Receive number. The value (TRUE or FALSE) of the parameter.

If nParameter is DBP_BRAND, nNumber is one of the DBV_BRAND_* values.

strString Receive string. If you specify DBP_VERSION in nParameter, this is the version number.


See Also SqlGetParameterAllSqlSetParameterSqlSetParameterAll

Example On SAM_AppStartupCall SqlGetParameter ( hSqlPrimary, DBP_LOCKWAITTIMEOUT,

nTimeout, strNull )

SqlGetParameterAllSyntax bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

Description 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.


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.


nParameter Number. The database parameter. Specify the value of one of the SQLP* constants defined in SQL.H.

nNumber 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.


See Also SqlGetParameterSqlSetParameterSqlSetParameterAll

Example Set bOk = SqlGetParameterAll ( hSql, nParameter, nNumber,strString, bNumber )

SqlGetResultSetCountSyntax bOk = SqlGetResultSetCount ( hSql, nCount )

Description 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 Sql Handle. A handle associated with a result set.

nCount Receive Number. The number of rows in the result set.


Example Actions



Call SqlPrepare ( hSqlPrimary, strSqlTblWindow )Call SqlExecute ( hSqlPrimary )Call SqlGetResultSetCount ( hSqlPrimary, nRowCount )

SqlGetRollbackFlagSyntax bOk = SqlGetRollbackFlag ( hSql, bRollbackFlag )

Description 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 Sql Handle. The handle associated with the function call that got an error.

bRollbackFlag Receive Boolean. TRUE if a rollback occurred and FALSE otherwise.


Example Call SqlGetRollbackFlag ( hSqlError, bRollbackFlag )If bRollbackFlag

! Execute code to handle rolled back ! transaction

SqlGetSessionErrorInfoSyntax bOk = SqlGetSessionErrorInfo ( hSession, numErrorNumber, strErrorDescription,

strSqlState )

Description 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 Session Handle. The Session handle passed to the SAL call that failed.

numErrorNumber Number The error number.

strErrorDescription String. The error description.

strSqlState String. The Sql state.


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

SqlGetSessionHandleSyntax bOk = SqlGetSessionHandle ( hSql, hSession )

Description 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.

Parameters hSql Sql Handle. The Sql handle used to associate any number of statements to a session.

hSession Session Handle. The Session handle of the statement.

Return Value bOk is TRUE if the function was successful. If the call failed, it returns FALSE.

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) ! !



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 SqlCommitSessionSqlCreateSessionSqlCreateStatementSqlFreeSession

SqlGetSessionParameterSyntax bOk = SqlGetSessionParameter ( hSession, numPropertyID, numValue, strValue )

Description 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 Session Handle. The session handle.

numPropertyID Number. The number value of the property ID.

numValue Number. The number value of the property ID.

strValue String. The string value of the property ID.

Return Value bOk is TRUE if successful. It will return FALSE if it failed.

Example 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


SqlGetStatementErrorInfo

SqlGetStatementErrorInfoSyntax bOk = SqlGetStatementErrorInfo ( hSql, numErrorNumber, strErrorDescription,

strSqlState )

Description 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 Sql Handle. The Sql handle passed to the SAL call that failed.

numErrorNumber Number The error number.

strErrorDescription String. The error description.

strSqlState String. The Sql state.

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 SqlGetSessionErrorInfo

SqlImmediateSyntax bOk = SqlImmediate ( strSqlCommand )

Description 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,



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.


See Also SqlClearImmediate

Example Call SqlImmediate ( 'INSERT INTO COMPANY ( COMPANY )' ||'VALUES( :frmMain dfCompany )' )

SqlImmediateContextDeprecated. This function has been deprecated and should no longer be used. Instead use SqlVarSetup.

Syntax bOk = SqlImmediateContext ( strSqlStatement )

Description 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.


SqlOpen


See Also SqlContextClearSqlContextSetSqlContextSetToForm

Example Set bOk = SqlImmediateContext ( strSqlStatement )

SqlOpenSyntax bOk = SqlOpen ( hSql, strCursorName )

Description 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 Sql Handle. The handle associated with the SqlPrepare.

strCursorName 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 ('').


See Also SqlCloseSqlExecute

Example Set bOk = SqlOpen ( hSql, strCursorName )

SqlOraPLSQLPrepareSyntax bOk = SqlOraPLSQLPrepare (hSql, strAnonymousPLSQLBlock)

Description 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.

Parameters hSql SqlHandle. A handle that identifies a database connection.



strAnonymousPLSQLBlock String. The actual anonymous PL/SQL block that the user wants to prepare. That will also contain the input and output variables.


Example Set strAnonymousPLSQLBlock = ' BEGINPkg1.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.


SqlOraPLSQLExecute

SqlOraPLSQLExecuteSyntax bOk = SqlOraPLSQLExecute (hSql)

Description 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.

Parameters hSql Sql Handle. The sql handle associated with the prepared Anonymous PL/SQL block.


Example Set strCMD = ' BEGINPkg1.Proc1 ( :nInput1, :sOutput1);Pkg1.Proc2 ( :sOutput1 );Pkg2.Proc1 ( :nInput1 );END; '

Set bOK = SqlOraPLSQLPrepare (hSql, strCMD)Set nInput1 = 100Set bOk = SqlOraPLSQLExecute ( hSql )If bOk! now the output parameter is availableCall SalMessageBox ( sOutput1, 'Output parameter from PL/SQL', MB_Ok)

SqlOraPLSQLStringBindTypeSyntax bOk = SqlOraPLSQLStringBindType (hSql, strBindName, nBindType)

Description 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.

Parameters hSql Sql Handle. The sql handle associated with the prepared Anonymous PL/SQL block.

strBindName String. The name of the bind variable (the input or the output parameter) as specifed in the sql statement passed for the SqlOraPLSQLPrepare command.



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.


Example ! Data type declarations!String: strCMDNumber: nInput1String: sOutput1[1:100]Boolean: bOk!! Code follows!Set strCMD = ' ArrayPkg.Proc1 (:nInput1, :sOutput1); 'Set bOk = SqlOraPLSQLPrepare (hSql, strCMD)Set nInput1 = 100Set 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".

SqlPLSQLCommandSyntax bOk = SqlPLSQLCommand ( hSqlHandle, strCommand )

Description 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.


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] = 0nnDynVar[1]= 1nDynvar[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.



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 Sql Handle. The connected SQL Handle to an Oracle database.

strCommand String. Command string used to invoke a PL/SQL procedure.


Example 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.

SqlPrepareSyntax bOk = SqlPrepare ( hSql, strSqlStatement )

Description 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.


strSqlStatement String. The SQL statement to compile.



SqlPrepareAndExecute

See Also SqlExecute

Example Call SqlPrepare ( hSqlPrimary, 'INSERT INTO CUSTOMER ' || ' ( CUSTOMER ) VALUES ' ||'(

:frmCustomer.dfCustomer )' )

SqlPrepareAndExecuteSyntax bOk = SqlPrepareAndExecute ( hSql, strSqlStatement )

Description 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.


strSqlStatement String. The SQL statement to compile and execute.


See Also SqlExecuteSqlPrepare

Example Set bOk = SqlPrepareAndExecute ( hSql, 'Select name from' || ' employees into :df1' )

If bOkCall SqlFetchNext ( hSql, nInd )

SqlPrepareSPSyntax bOk = SqlPrepareSP (hSql, strStoredProc, strIntoList)

Description 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



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 Sql Handle. The sql handle on which the Stored Procedure should be executed.

strStoredProc 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.


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)

See Also SqlCloseAllSPResultSetsSqlGetNextSPResultSet

SqlRetrieve


SqlRollbackSession

Syntax bOk = SqlRetrieve ( hSql, strName, strBindList, strIntoList )

Description 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.


strName String. The name of the compiled command.

strBindList 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.

strIntoList 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.


See Also SqlDropStoredCmdSqlStore

Example Call SqlRetrieve ( hSqlPrimary, 'PRODUCTS', ':nPrice', ':strLBItem' )

SqlRollbackSessionSyntax bOk = SqlRollbackSession ( hSession )

Description 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.


Return Value bOk is TRUE if the transaction was rolled back successfully. If the call failed, it returns FALSE.


On SAM_Click ! ! Rollback the transaction...



Set bOk = SqlRollbackSession (hSession) If bOk Call SalMessageBox ( ' Rolled back!!', 'Good', MB_Ok) Else Call SalMessageBox ( ' Rollback failed ', 'Bad', MB_Ok)

See Also SqlCommitSessionSqlCreateSessionSqlCreateStatementSqlGetSessionHandle

SqlSetInMessageSyntax bOk = SqlSetInMessage ( hSql, nSize )

Description 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.


nSize 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.


See Also SqlSetOutMessage

Example On SAM_AppStartupCall SqlConnect ( hSqlPrimary )Call SqlSetInMessage ( hSqlPrimary, 10000 )


SqlSetIsolationLevel

SqlSetIsolationLevelSyntax bOk = SqlSetIsolationLevel ( hSql, strIsolation )

Description 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.


strIsolation String. The isolation level to set. Specify one of these values:

CS Cursor Stability

RL Release Locks

RO Read Only

RR Read Repeatability


Example On SAM_AppStartupCall SqlSetIsolationLevel ( hSqlPrimary, 'RL' )

SqlSetLockTimeoutSyntax bOk = SqlSetLockTimeout ( hSql, nTimeout )

Description Specifies the maximum time to wait to acquire a lock. After the specified time elapses, a timeout occurs and the transaction rolls back.

Parameters hSql Sql Handle. A handle that identifies a database connection; the cursor on which you want to set a lock timeout value.

nTimeout 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.


Example On SAM_AppStartupCall SqlSetLockTimeout ( hSqlPrimary, 10 )

SqlSetLongBindDatatypeSyntax bOk = SqlSetLongBindDatatype( nBindVarNumber, nDatatype )



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 Number. The bind variable to set. The first bind variable in the SQL statement is 1, the second is 2, and so on.

nDatatype Number. The data type:

22 = text

23 = binary

24 = char \ long varchar > 254

Return Value bOk is TRUE if this function succeeds and FALSE if it fails.

Example Call SqlSetLongBindDatatype( 1, DT_Binary )

SqlSetOutMessageSyntax bOk = SqlSetOutMessage ( hSql, nSize )

Description 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.


nSize Number. The size (in bytes) of the output message buffer. The default is 1 Kbyte and the maximum is 32 Kbytes.


SqlSetParameter


See Also SqlSetInMessage

Example On SAM_AppStartupCall SqlConnect ( hSqlPrimary )Call SqlSetOutMessage ( hSqlPrimary, 1500 )

SqlSetParameterSyntax bOk = SqlSetParameter ( hSql, nParameter, nNumber, strString )

Description 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.


nParameter Number. The database parameter to set. Specify one of the DBP_* constants.

nNumber 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.

strString String. The value to assign to nParameter.


See Also SqlGetParameterSqlGetParameterAllSqlSetParameterAll

Example Call SqlSetParameter ( hSqlPrimary, DBP_PRESERVE, TRUE, strNull )

SqlSetParameterAllSyntax bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

Description 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.

Parameters hSql Sql Handle. The handle that identifies a database connection.



nParameter Number. The database parameter to set. Specify the value of one of the SQLP* constants defined in SQL.H.

nNumber Number. The value to assign to nParameter if it is a number.

strString String. The value to assign to nParameter if it is a string.

bNumber If TRUE, the parameter value is in nNumber. If FALSE, the parameter value is in strString.


See Also SqlGetParameterSqlGetParameterAllSqlSetParameter

Example Set bOk = SqlSetParameterAll ( hSql, nParameter, nNumber,strString, bNumber )

SqlSetResultSetSyntax bOk = SqlSetResultSet ( hSql, bSet )

Description 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.


bSet Boolean. Turns result set mode on (TRUE) or off (FALSE).


Example Call SqlSetResultSet ( hSqlPrimary, FALSE )

SqlSetSessionParameterSyntax bOk = SqlSetSessionParameter ( hSession, numPropertyID, numValue, strValue )

Description 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.


SqlStore

numPropertyID Number. The property ID.

numValue Number. The number value of the property ID.

strValue String. The string value of the property ID.

Return Value bOk is TRUE if successful. It will return FALSE if it failed.

ExamplePushbutton: 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

SqlStoreSyntax bOk = SqlStore ( hSql, strName, strSqlCommand )

Description 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



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.


strName String. The name of the stored command.

strSqlCommand String. The SQL statement to compile and store.


See Also SqlDropStoredCmdSqlRetrieve

Example Set bOk = SqlStore (hSql, strName, strSqlCommand)

SqlVarSetupSyntax nOk = SqlVarSetup (hSql)

Description 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.


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 hSql Sql Handle. A handle that identifies a database connection..






Index
Aarray functions 1-4
Bbackground text functions 1-19

Ccolor and font functions 1-4Conventions used in the manual 1-4

Ddata type conversion functions 1-3, 1-4, 1-7date functions 1-7debugging functions 1-8dialog box functions 1-9drag drop functions 1-11

Eedit functions 1-12

Ffile management functions 1-13format and validation functions 1-15functions

array 1-4data type conversion 1-3, 1-4, 1-7date 1-7DDE 1-8debugging 1-8dialog box 1-9drag drop 1-11edit 1-12file management 1-13format and validation 1-15list and combo box 1-17manipulating background text 1-5MDI 1-19message 1-19miscellaneous 1-20number 1-24OLE DB Consumer 1-26picture 1-27prints 1-28reports 1-29scroll bar 1-30SQL 1-30string conversion 1-33table window 1-34

window management 1-38XML 1-41

Llist and combo box functions 1-17

MManipulating background text functions 1-5Manual

description of 1-4MDI functions 1-19message functions 1-19miscellaneous functions 1-20

Nnumber functions 1-24

Oobsolete functions 1-42

Ppause 2-127picture functions 1-27print functions 1-28

SSalAbort 2-2SalActiveXAutoErrorMode 2-2SalAppDisable 2-2SalAppEnable 2-9SalAppFind 2-10SalArrayAvg 2-12SalArrayDimCount 2-12SalArrayGetLowerBound 2-13SalArrayGetUpperBound 2-13SalArrayIsEmpty 2-14SalArrayMax 2-14SalArrayMin 2-15SalArraySetUpperBound 2-15SalArraySum 2-16SalBringWindowToTop 2-16SalCenterWindow 2-17SalClearField 2-17SalColorFromRGB 2-17SalColorGet 2-18SalColorGetSysColor 2-19SalColorSet 2-19SalColorToRGB 2-20

SQLWindows Function Reference Index-1

Index

SalCompileAndEvaluate 2-21SalContextCurrent 2-22SalCreateWindow 2-23SalCreateWindowExWithParms 2-24SalCursorClear 2-26SalCursorSet 2-26SalCursorSetFile 2-27SalCursorSetString 2-28SalDateConstruct 2-28SalDateCurrent 2-30SalDateDay 2-30SalDateHour 2-30SalDateMinute 2-30SalDateMonth 2-31SalDateMonthBegin 2-31SalDateQuarter 2-32SalDateQuarterBegin 2-32SalDateSecond 2-32SalDateToStr 2-33SalDateWeekBegin 2-33SalDateWeekday 2-33SalDateYear 2-34SalDDEStopServer 2-34SalDDEStopSession 2-34SalDestroyWindow 2-34SalDisableWindow 2-34SalDisableWindowAndLabel 2-35SalDlgChooseColor 2-36SalDlgChooseFont 2-36SalDlgGetDockStatus 2-37SalDlgOpenFile 2-37SalDlgSaveFile 2-39SalDlgSetDockStatus 2-40SalDragDropDisableDrop 2-41SalDragDropEnableDrop 2-41SalDragDropGetSource 2-42SalDragDropGetTarget 2-42SalDragDropStart 2-43SalDragDropStop 2-43SalDrawMenuBar 2-43SalDropFilesAcceptFiles 2-44SalDropFilesQueryFiles 2-44SalDropFilesQueryPoint 2-46SalEditCanCopyTo 2-46SalEditCanCut 2-47SalEditCanPaste 2-47SalEditCanPasteFrom 2-47SalEditCanUndo 2-48

SalEditClear 2-48SalEditCopy 2-48SalEditCopyString 2-49SalEditCopyTo 2-49SalEditCut 2-49SalEditPaste 2-50SalEditPasteFrom 2-50SalEditPasteString 2-51SalEditUndo 2-51SalEnableWindow 2-51SalEnableWindowAndLabel 2-52SalEndDialog 2-52SalEndTrace 2-53SalEventLogSetName 2-53SalFileClose 2-53SalFileCopy 2-54SalFileCreateDirectory 2-55SalFileGetC 2-55SalFileGetChar 2-55SalFileGetCurrentDirectory 2-56SalFileGetDateTime 2-56SalFileGetDrive 2-57SalFileGetStr 2-57SalFileOpen 2-58SalFileOpenExt 2-58SalFilePutC 2-59SalFilePutChar 2-59SalFilePutStr 2-60SalFileRead 2-60SalFileRemoveDirectory 2-61SalFileSeek 2-61SalFileSetCurrentDirectory 2-62SalFileSetDateTime 2-62SalFileSetDrive 2-62SalFileTell 2-63SalFileWrite 2-63SalFmtFieldToStr 2-63SalFmtFormatDateTime 2-64SalFmtFormatNumber 2-65SalFmtGetFormat 2-65, 2-66SalFmtGetInputMask 2-66SalFmtGetPicture 2-66SalFmtIsValidField 2-67SalFmtIsValidInputMask 2-67SalFmtIsValidPicture 2-68SalFmtKeepMask 2-69SalFmtSetFormat 2-70SalFmtSetInputMask 2-70

Index-2 SQLWindows Function Reference

SalFmtSetPicture 2-71SalFmtStrToField 2-71SalFmtUnmaskInput 2-73SalFmtValidateField 2-73SalFontGet 2-74SalFontGetNames 2-74SalFontGetSizes 2-75SalFontSet 2-75SalFormGetParmNum 2-76SalFormUnitsToPixels 2-76SalGetDataType 2-77SalGetDefButton 2-77SalGetFirstChild 2-78SalGetFocus 2-78SalGetItemName 2-78SalGetMaxDataLength 2-79SalGetNextChild 2-79SalGetProfileInt 2-80SalGetProfileString 2-80SalGetType 2-81SalGetVersion 2-82SalGetWindowLabel 2-83SalGetWindowLabelText 2-82, 2-84SalGetWindowLoc 2-82SalGetWindowSize 2-83SalGetWindowState 2-83SalGetWindowText 2-84SalHideWindow 2-85SalHideWindowAndLabel 2-86SalHStringToNumber 2-86SalInvalidateWindow 2-88SalIsButtonChecked 2-88SalIsNull 2-88SalIsValidDateTime 2-88SalIsValidDecimal 2-89SalIsValidInteger 2-90SalIsValidNumber 2-90SalIsWindowEnabled 2-91SalIsWindowVisible 2-91SalListAdd 2-91SalListClear 2-92SalListDelete 2-92SalListFiles 2-92SalListGetMultiSelect 2-93SalListInsert 2-93SalListPopulate 2-94SalListQueryCount 2-94SalListQueryFile 2-95

SalListQueryMultiCount 2-95SalListQuerySelection 2-95SalListQueryState 2-96SalListQueryText 2-96SalListQueryTextLength 2-97SalListQueryTextX 2-96, 2-97SalListRedraw 2-97SalListSelectString 2-98SalListSetMultiSelect 2-98SalListSetSelect 2-99SalListSetTabs 2-99SalLoadApp 2-100SalLoadAppAndProcessMsgs 2-101SalLoadAppAndWait 2-100SalMapEnterToTab 2-102SalMDIArrangeIcons 2-103SalMDICascade 2-103SalMDITile 2-103SalMessageBeep 2-104SalMessageBox 2-104SalModalDialog 2-106SalModalDialogFromStr 2-107SalMoveWindow 2-107SalMTSCreateInstance 2-108SalMTSDisableCommit 2-108SalMTSEnableCommit 2-109SalMTSGetObjectContext 2-109SalMTSInTransaction 2-110SalMTSIsCallerInRoll 2-109SalMTSSecurityEnabled 2-110SalMTSSetAbort 2-111SalMTSSetComplete 2-111SalNumberAbs 2-112SalNumberArcCos 2-112SalNumberArcSin 2-112SalNumberArcTan 2-113SalNumberArcTan2 2-113SalNumberCos 2-113SalNumberCosH 2-114SalNumberExponent 2-114SalNumberHigh 2-114SalNumberHypot 2-115SalNumberLog 2-115SalNumberLogBase10 2-115SalNumberLow 2-116SalNumberMax 2-116SalNumberMin 2-116SalNumberMod 2-117


Index

SalNumberPi 2-117SalNumberPower 2-117SalNumberRandInit 2-118SalNumberRandom 2-118SalNumberRound 2-119SalNumberSin 2-119SalNumberSinH 2-119SalNumberSqrt 2-120SalNumberTan 2-120SalNumberTanH 2-120SalNumberToChar 2-121SalNumberToHString 2-121SalNumberToStr 2-121SalNumberToStrX 2-122SalNumberToWindowHandle 2-122SalNumberTruncate 2-123SalObjCreateFromString 2-124SalObjGetType 2-124SalObjIsDerived 2-125SalObjIsNull 2-126SalObjIsValidClassName 2-126SalParentWindow 2-127SalPause 2-127SalPicClear 2-128, 2-129SalPicGetDescription 2-128SalPicGetString 2-130SalPicSet 2-130SalPicSetFile 2-131SalPicSetFit 2-131SalPicSetString 2-133SalPixelsToFormUnits 2-134SalPostMsg 2-135SalPrtExtractRect 2-135SalPrtGetDefault 2-136SalPrtGetParmNum 2-136SalPrtPrintForm 2-136SalPrtSetDefault 2-137SalPrtSetParmDefaults 2-137SalPrtSetParmNum 2-138SalPrtSetup 2-138SalQueryFieldEdit 2-139SalQuit 2-139SalReportClose 2-140SalReportCmd 2-140SalReportCreate 2-140SalReportDlgOptions 2-141SalReportGetDateTimeVar 2-142SalReportGetFileInfo 2-142

SalReportGetNumberVar 2-143SalReportGetObjectVar 2-143SalReportGetPrinterSettings 2-143SalReportGetPrinterTray 2-145SalReportGetStringVar 2-146SalReportPrint 2-146SalReportPrintToFile 2-148SalReportReset 2-149SalReportResetPages 2-150SalReportSetDateTimeVar 2-150SalReportSetNumberVar 2-151SalReportSetObjectVar 2-151SalReportSetPrinterSettings 2-152SalReportSetPrinterTray 2-153SalReportSetStringVar 2-154SalReportTableCreate 2-155SalReportTablePrint 2-155SalReportTableView 2-156SalReportView 2-157SalScrollGetPos 2-159SalScrollGetRange 2-159SalScrollSetPos 2-160SalScrollSetRange 2-160SalSendClassMessage 2-161SalSendClassMessageNamed 2-161SalSendMsg 2-162SalSendMsgToChildren 2-162SalSendValidateMsg 2-163SalSetDefButton 2-163SalSetFieldEdit 2-164SalSetFocus 2-165SalSetMaxDataLength 2-165SalSetProfileString 2-166SalSetWindowLabelText 2-166SalSetWindowLoc 2-167SalSetWindowSize 2-167SalSetWindowText 2-167SalShowWindow 2-168SalShowWindowAndLabel 2-168SalStartTrace 2-169SalStatusGetText 2-170SalStatusSetText 2-170SalStatusSetVisible 2-171SalStrCompress 2-171SalStrFirstC 2-171SalStrGetBufferLength 2-172SalStrIsValidCurrency 2-173SalStrIsValidDateTime 2-173


SalStrIsValidNumber 2-173SalStrLeft 2-174SalStrLeftX 2-174SalStrLength 2-175SalStrLop 2-175SalStrLower 2-176SalStrMid 2-176SalStrProper 2-178SalStrRepeat 2-178SalStrRepeatX 2-178SalStrReplace 2-179SalStrReplaceX 2-179SalStrRight 2-179SalStrRightX 2-179SalStrScan 2-180SalStrSetBufferLength 2-181SalStrToDate 2-182SalStrTokenize 2-182SalStrToNumber 2-183SalStrTrim 2-183SalStrTrimX 2-183SalStrUncompress 2-184SalStrUpper 2-184SalStrUpperX 2-185SalTBarSetVisible 2-185SalTblAnyRows 2-185SalTblClearSelection 2-186SalTblColumnAverage 2-186SalTblColumnSum 2-188SalTblCopyRows 2-188SalTblCreateColumn 2-189SalTblDefineCheckBoxColumn 2-190SalTblDefineDropDownListColumn 2-191SalTblDefinePopupEditColumn 2-191SalTblDefineRowHeader 2-192SalTblDefineSplitWindow 2-193SalTblDeleteRow 2-193SalTblDeleteSelected 2-193SalTblDestroyColumns 2-194SalTblDoDeletes 2-194SalTblDoInserts 2-195SalTblDoUpdates 2-196SalTblFetchRow 2-196SalTblFindNextRow 2-197SalTblFindPrevRow 2-198SalTblGetColumnText 2-199SalTblGetColumnTitle 2-199SalTblGetColumnWindow 2-199

SalTblInsertRow 2-200SalTblKillEdit 2-200SalTblKillFocus 2-201SalTblPasteRows 2-202SalTblPopulate 2-202SalTblQueryCheckBoxColumn 2-205SalTblQueryColumnCellType 2-205SalTblQueryColumnFlags 2-206SalTblQueryColumnID 2-206SalTblQueryColumnPos 2-206SalTblQueryColumnWidth 2-207SalTblQueryContext 2-207SalTblQueryDropDownListColumn 2-207SalTblQueryFocus 2-208SalTblQueryLinesPerRow 2-209SalTblQueryLockedColumns 2-209SalTblQueryPopupEditColumn 2-209SalTblQueryRowFlags 2-210SalTblQueryRowHeader 2-210SalTblQueryScroll 2-211SalTblQuerySplitWindow 2-211SalTblQueryTableFlags 2-212SalTblQueryVisibleRange 2-212SalTblReset 2-212SalTblScroll 2-213SalTblSetCellTextColor 2-213SalTblSetColumnFlags 2-215SalTblSetColumnPos 2-215SalTblSetColumnText 2-215SalTblSetColumnTitle 2-216SalTblSetColumnWidth 2-216SalTblSetContext 2-217SalTblSetFlagsAnyRows 2-217SalTblSetFocusCell 2-218SalTblSetFocusRow 2-219SalTblSetLinesPerRow 2-219SalTblSetLockedColumns 2-220SalTblSetRange 2-220SalTblSetRow 2-221SalTblSetRowFlags 2-221SalTblSetTableFlags 2-222SalTblSortRows 2-223SalTimerKill 2-225SalTimerSet 2-225SalTrace 2-226SalTrackPopupMenu 2-226SalUpdateWindow 2-227SalUseRegistry 2-228


Index

SalValidateSet 2-229SalWaitCursor 2-230SalWindowClassName 2-230SalWindowGetDockSettings 2-230SalWindowGetProperty 2-231SalWindowHandleToNumber 2-232SalWindowIsDerivedFromClass 2-232SalWinHelp 2-232SalXMLDeserializeUDV 2-233SalXMLGetLastError 2-234SalXMLSerializeUDV 2-234SalYieldEnable 2-235SalYieldQueryState 2-236SalYieldStartMessages 2-236SalYieldStopMessages 2-237scroll bar functions 1-30SQL functions 1-30SQLBase API 2-253SqlClearImmediate 2-237SqlClose 2-237SqlCloseAllSPResultSets 2-238SqlCommit 2-239SqlCommitSession 2-239SqlConnect 2-240SqlContextClear 2-241SqlContextSet 2-241SqlContextSetToForm 2-242SqlCreateSession 2-242SqlCreateStatement 2-244SqlDirectoryByName 2-245SqlDisconnect 2-245SqlDropStoredCmd 2-246SqlError 2-246SqlErrorText 2-246SqlExecute 2-247SqlExecutionPlan 2-248SqlExists 2-248SqlExtractArgs 2-249SqlFetchNext 2-249SqlFetchPrevious 2-250SqlFetchRow 2-250SqlFreeSession 2-251SqlGetCmdOrRowsetPtr 2-251SqlGetCursor 2-253SqlGetDSOrSessionPtr 2-253SqlGetError 2-254SqlGetErrorPosition 2-254SqlGetErrorText 2-255

SqlGetErrorTextX 2-256SqlGetLastStatement 2-256SqlGetModifiedRows 2-256SqlGetNextSPResultSet 2-257SqlGetParameter 2-258SqlGetParameterAll 2-258SqlGetResultSetCount 2-259SqlGetRollbackFlag 2-260SqlGetSessionErrorInfo 2-260SqlGetSessionHandle 2-261SqlGetSessionProperty 2-262SqlGetStatementErrorInfo 2-263SqlImmediate 2-263SqlImmediateContext 2-264SqlOpen 2-265SqlPLSQLCommand 2-268SqlPrepare 2-270SqlPrepareAndExecute 2-271SqlPrepareSP 2-271SqlRetrieve 2-272SqlRollbackSession 2-273SqlSetInMessage 2-274SqlSetIsolationLevel 2-275SqlSetLockTimeout 2-275SqlSetLongBindDatatype 2-275SqlSetOutMessage 2-276SqlSetParameter 2-277SqlSetParameterAll 2-277SqlSetResultSet 2-278SqlSetSessionProperty 2-278SqlStore 2-279SQLWindows function categories 1-2SQLWindows functions 1-1, 2-1string conversion functions 1-33system functions

obsolete 1-42

Ttable window functions 1-34

VVisual Toolchest 1-2

Wwindow management functions 1-38
