Centura Builder - Function Reference

Centura Builder Function Reference
20-6202-0000
Trademarks
Centura, Centura Builder, Centura Ranger, Centura Team Developer, the Centura logo, Gupta, the Gupta logo, Gupta Powered, the Gupta Powered logo, Fast Facts, Quest, QuickObjects, SQL/API, SQLBase, SQLBase Ranger, SQLConsole, SQLGateway, SQLHost, SQLNetwork, SQLRouter, SQLTalk, and Team Object Manager are trademarks of Gupta Corporation and may be registered in the United States of America and/or other countries. SQLWindows is a registered trademark and TeamWindows, ReportWindows and EditWindows are trademarks exclusively used and licensed by Centura Software Corporation. Microsoft, Win 32, Windows, Windows NT and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States of America and/or other countries. SApplication Builder is a trademark of Rosbach Consulting Team. Java is a trademark of Sun Microsystems Inc. All other product or service names mentioned herein are trademarks or registered trademarks of their respective owners.
Copyright
Copyright 1996 by Centura Software Corporation. All rights reserved. Centura Buildern Function Reference 20-6202-0000 February 1996
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv 1 Centura Builder Function Tables . . . . . . 1-1

Centura Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Obsolete Centura Functions . . . . . . . . . . . . . . . 1-16 Centura Function Categories . . . . . . . . . . . . . . . . . . 1-17 Array Functions. . . . . . . . . . . . . . . . . . . . . . . . . . 1-17 Color and Font Functions . . . . . . . . . . . . . . . . . . 1-18 Data Type Conversion Functions . . . . . . . . . . . . 1-19 Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20 DDE Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21 Debugging Functions . . . . . . . . . . . . . . . . . . . . . 1-22 Dialog Box Functions . . . . . . . . . . . . . . . . . . . . . 1-23 DOS Management Functions . . . . . . . . . . . . . . . 1-23 Drag Drop Functions. . . . . . . . . . . . . . . . . . . . . . 1-25 Edit Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26 File Management Functions . . . . . . . . . . . . . . . . 1-27 Format and Validation Functions . . . . . . . . . . . . 1-29 List and Combo Box Functions. . . . . . . . . . . . . . 1-31 Manipulating Background Text Functions. . . . . . 1-33 MDI Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36 Message Functions. . . . . . . . . . . . . . . . . . . . . . . 1-36 Miscellaneous Functions . . . . . . . . . . . . . . . . . . 1-37 Number Functions . . . . . . . . . . . . . . . . . . . . . . . 1-40 Picture Functions . . . . . . . . . . . . . . . . . . . . . . . . 1-42 Print Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-43 Report Functions . . . . . . . . . . . . . . . . . . . . . . . . 1-43 Scroll Bar Functions . . . . . . . . . . . . . . . . . . . . . . 1-44 SQL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-44 String Conversion Functions. . . . . . . . . . . . . . . . 1-47
iii
Contents Table Window Functions . . . . . . . . . . . . . . . . . . 1-48 Window Management Functions . . . . . . . . . . . . 1-51
2 Centura Builder Functions . . . . . . . . . . . . . 2-1

SalAbort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 SalAppDisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 SalAppEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 SalAppFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 SalArrayAvg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 SalArrayDimCount . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 SalArrayGetLowerBound . . . . . . . . . . . . . . . . . . . . . . 2-5 SalArrayGetUpperBound . . . . . . . . . . . . . . . . . . . . . . 2-5 SalArrayIsEmpty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 SalArrayMax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 SalArrayMin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 SalArraySetUpperBound. . . . . . . . . . . . . . . . . . . . . . . 2-8 SalArraySum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 SalBringWindowToTop . . . . . . . . . . . . . . . . . . . . . . . . 2-9 SalCenterWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 SalClearField. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 SalColorFromRGB . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 SalColorGet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 SalColorGetSysColor . . . . . . . . . . . . . . . . . . . . . . . . 2-11 SalColorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 SalColorToRGB . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 SalCompileAndEvaluate . . . . . . . . . . . . . . . . . . . . . 2-13 SalContextBreak . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 SalContextCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 SalCreateWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 SalCreateWindowExWithParms . . . . . . . . . . . . . . . . 2-16 SalCursorClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 SalCursorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 SalCursorSetFile . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
iv
SalCursorSetString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19 SalDateConstruct . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20 SalDateCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21 SalDateDay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21 SalDateHour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21 SalDateMinute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22 SalDateMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22 SalDateMonthBegin . . . . . . . . . . . . . . . . . . . . . . . . . 2-22 SalDateQuarter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 SalDateQuarterBegin . . . . . . . . . . . . . . . . . . . . . . . . 2-23 SalDateSecond . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 SalDateToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24 SalDateWeekBegin . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24 SalDateWeekday . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 SalDateYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 SalDateYearBegin . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 SalDDEAddAtom . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26 SalDDEAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26 SalDDEDeleteAtom . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 SalDDEExtract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 SalDDEExtractCmd . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 SalDDEExtractDataText . . . . . . . . . . . . . . . . . . . . . . 2-28 SalDDEExtractOptions . . . . . . . . . . . . . . . . . . . . . . . 2-28 SalDDEFindAtom . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29 SalDDEFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29 SalDDEGetAtomName . . . . . . . . . . . . . . . . . . . . . . . 2-30 SalDDEGetExecuteString . . . . . . . . . . . . . . . . . . . . 2-30 SalDDEPost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30 SalDDERequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31 SalDDESend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32 SalDDESendAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32 SalDDESendExecute . . . . . . . . . . . . . . . . . . . . . . . . 2-33
Contents SalDDESendToClient . . . . . . . . . . . . . . . . . . . . . . . . 2-34 SalDDESetCmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34 SalDDESetDataText . . . . . . . . . . . . . . . . . . . . . . . . 2-35 SalDDESetOptions . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35 SalDDEStartServer . . . . . . . . . . . . . . . . . . . . . . . . . 2-36 SalDDEStartSession . . . . . . . . . . . . . . . . . . . . . . . . 2-36 SalDDEStopServer . . . . . . . . . . . . . . . . . . . . . . . . . 2-37 SalDDEStopSession . . . . . . . . . . . . . . . . . . . . . . . . 2-37 SalDestroyWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37 SalDisableWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38 SalDisableWindowAndLabel . . . . . . . . . . . . . . . . . . 2-38 SalDlgChooseColor . . . . . . . . . . . . . . . . . . . . . . . . . 2-39 SalDlgChooseFont . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39 SalDlgOpenFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40 SalDlgSaveFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42 SalDragDropDisableDrop . . . . . . . . . . . . . . . . . . . . . 2-43 SalDragDropEnableDrop . . . . . . . . . . . . . . . . . . . . . 2-44 SalDragDropGetSource . . . . . . . . . . . . . . . . . . . . . . 2-44 SalDragDropGetTarget . . . . . . . . . . . . . . . . . . . . . . 2-45 SalDragDropStart . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45 SalDragDropStop . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45 SalDrawMenuBar . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46 SalDropFilesAcceptFiles . . . . . . . . . . . . . . . . . . . . . 2-46 SalDropFilesQueryFiles . . . . . . . . . . . . . . . . . . . . . . 2-47 SalDropFilesQueryPoint . . . . . . . . . . . . . . . . . . . . . . 2-48 SalEditCanCopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48 SalEditCanCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49 SalEditCanPaste . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49 SalEditCanPasteFrom. . . . . . . . . . . . . . . . . . . . . . . . 2-49 SalEditCanUndo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50 SalEditClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50 SalEditCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
vi
SalEditCopyString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51 SalEditCopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51 SalEditCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51 SalEditPaste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52 SalEditPasteFrom . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52 SalEditPasteString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53 SalEditUndo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53 SalEnableWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54 SalEnableWindowAndLabel . . . . . . . . . . . . . . . . . . . 2-54 SalEndDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54 SalFileClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-55 SalFileCopy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-55 SalFileCreateDirectory . . . . . . . . . . . . . . . . . . . . . . . 2-56 SalFileGetC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56 SalFileGetChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-57 SalFileGetCurrentDirectory . . . . . . . . . . . . . . . . . . . 2-57 SalFileGetDateTime . . . . . . . . . . . . . . . . . . . . . . . . . 2-57 SalFileGetDrive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58 SalFileGetStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58 SalFileOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-59 SalFileOpenExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-59 SalFilePutC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-60 SalFilePutChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-60 SalFilePutStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61 SalFileRead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61 SalFileRemoveDirectory . . . . . . . . . . . . . . . . . . . . . 2-62 SalFileSeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62 SalFileSetCurrentDirectory . . . . . . . . . . . . . . . . . . . . 2-63 SalFileSetDateTime . . . . . . . . . . . . . . . . . . . . . . . . . 2-63 SalFileSetDrive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63 SalFileTell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64 SalFileWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64
vii
Contents SalFmtFieldToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64 SalFmtFormatDateTime . . . . . . . . . . . . . . . . . . . . . . 2-65 SalFmtFormatNumber . . . . . . . . . . . . . . . . . . . . . . . 2-66 SalFmtGetFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-66 SalFmtGetInputMask . . . . . . . . . . . . . . . . . . . . . . . . 2-67 SalFmtGetPicture . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-68 SalFmtIsValidField . . . . . . . . . . . . . . . . . . . . . . . . . . 2-68 SalFmtIsValidInputMask . . . . . . . . . . . . . . . . . . . . . . 2-69 SalFmtIsValidPicture . . . . . . . . . . . . . . . . . . . . . . . . 2-69 SalFmtKeepMask . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-70 SalFmtSetFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-71 SalFmtSetInputMask. . . . . . . . . . . . . . . . . . . . . . . . . 2-72 SalFmtSetPicture . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72 SalFmtStrToField . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-73 SalFmtUnmaskInput . . . . . . . . . . . . . . . . . . . . . . . . . 2-73 SalFmtValidateField . . . . . . . . . . . . . . . . . . . . . . . . . 2-74 SalFontGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-74 SalFontGetNames. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-75 SalFontGetSizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-75 SalFontSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-76 SalFormGetParmNum . . . . . . . . . . . . . . . . . . . . . . . 2-76 SalFormUnitsToPixels. . . . . . . . . . . . . . . . . . . . . . . . 2-77 SalGetDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-77 SalGetDefButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-78 SalGetFirstChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-78 SalGetFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-79 SalGetItemName . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-79 SalGetMaxDataLength . . . . . . . . . . . . . . . . . . . . . . . 2-79 SalGetNextChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-80 SalGetProfileInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-80 SalGetProfileString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-81 SalGetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82
viii
SalGetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82 SalGetWindowLabelText . . . . . . . . . . . . . . . . . . . . . 2-83 SalGetWindowLoc . . . . . . . . . . . . . . . . . . . . . . . . . . 2-83 SalGetWindowSize . . . . . . . . . . . . . . . . . . . . . . . . . 2-84 SalGetWindowState . . . . . . . . . . . . . . . . . . . . . . . . . 2-84 SalGetWindowText . . . . . . . . . . . . . . . . . . . . . . . . . 2-84 SalHideWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-85 SalHideWindowAndLabel . . . . . . . . . . . . . . . . . . . . . 2-85 SalHStringToNumber . . . . . . . . . . . . . . . . . . . . . . . . 2-86 SalInvalidateWindow . . . . . . . . . . . . . . . . . . . . . . . . 2-86 SalIsButtonChecked . . . . . . . . . . . . . . . . . . . . . . . . . 2-86 SalIsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87 SalIsValidDateTime . . . . . . . . . . . . . . . . . . . . . . . . . 2-87 SalIsValidDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87 SalIsValidInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-88 SalIsValidNumber . . . . . . . . . . . . . . . . . . . . . . . . . . 2-89 SalIsWindowEnabled . . . . . . . . . . . . . . . . . . . . . . . . 2-89 SalIsWindowVisible . . . . . . . . . . . . . . . . . . . . . . . . . 2-89 SalListAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-90 SalListClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-90 SalListDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91 SalListFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91 SalListGetMultiSelect . . . . . . . . . . . . . . . . . . . . . . . . 2-92 SalListInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92 SalListPopulate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92 SalListQueryCount . . . . . . . . . . . . . . . . . . . . . . . . . . 2-93 SalListQueryFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-94 SalListQueryMultiCount . . . . . . . . . . . . . . . . . . . . . . 2-94 SalListQuerySelection. . . . . . . . . . . . . . . . . . . . . . . . 2-94 SalListQueryState . . . . . . . . . . . . . . . . . . . . . . . . . . 2-95 SalListQueryText or SalListQueryTextX . . . . . . . . . 2-95 SalListQueryTextLength . . . . . . . . . . . . . . . . . . . . . . 2-96
ix
Contents SalListQueryTextX . . . . . . . . . . . . . . . . . . . . . . . . . . 2-96 SalListRedraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-96 SalListSelectString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-97 SalListSetMultiSelect . . . . . . . . . . . . . . . . . . . . . . . . 2-97 SalListSetSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-98 SalListSetTabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-98 SalLoadApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-99 SalLoadAppAndWait . . . . . . . . . . . . . . . . . . . . . . . . 2-99 SalMapEnterToTab . . . . . . . . . . . . . . . . . . . . . . . . 2-101 SalMDIArrangeIcons . . . . . . . . . . . . . . . . . . . . . . . 2-101 SalMDICascade . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-101 SalMDITile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102 SalMessageBeep . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102 SalMessageBox . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-103 SalModalDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-105 SalModalDialogFromStr . . . . . . . . . . . . . . . . . . . . . 2-106 SalMoveWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-106 SalNumberAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-107 SalNumberArcCos . . . . . . . . . . . . . . . . . . . . . . . . . 2-107 SalNumberArcSin . . . . . . . . . . . . . . . . . . . . . . . . . . 2-107 SalNumberArcTan. . . . . . . . . . . . . . . . . . . . . . . . . . 2-108 SalNumberArcTan2 . . . . . . . . . . . . . . . . . . . . . . . . 2-108 SalNumberCos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-108 SalNumberCosH . . . . . . . . . . . . . . . . . . . . . . . . . . 2-109 SalNumberExponent . . . . . . . . . . . . . . . . . . . . . . . 2-109 SalNumberHigh . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-109 SalNumberHypot . . . . . . . . . . . . . . . . . . . . . . . . . . 2-110 SalNumberLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-110 SalNumberLogBase10 . . . . . . . . . . . . . . . . . . . . . . 2-110 SalNumberLow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-111 SalNumberMax . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-111 SalNumberMin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-111
SalNumberMod . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-112 SalNumberPi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-112 SalNumberPower . . . . . . . . . . . . . . . . . . . . . . . . . . 2-112 SalNumberRandInit . . . . . . . . . . . . . . . . . . . . . . . . 2-113 SalNumberRandom. . . . . . . . . . . . . . . . . . . . . . . . . 2-113 SalNumberRound . . . . . . . . . . . . . . . . . . . . . . . . . . 2-114 SalNumberSin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-114 SalNumberSinH . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-114 SalNumberSqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-115 SalNumberTan . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-115 SalNumberTanH . . . . . . . . . . . . . . . . . . . . . . . . . . 2-115 SalNumberToChar . . . . . . . . . . . . . . . . . . . . . . . . . 2-116 SalNumberToHString . . . . . . . . . . . . . . . . . . . . . . . 2-116 SalNumberToStr . . . . . . . . . . . . . . . . . . . . . . . . . . 2-116 SalNumberToStrX . . . . . . . . . . . . . . . . . . . . . . . . . 2-117 SalNumberToWindowHandle . . . . . . . . . . . . . . . . . 2-117 SalNumberTruncate . . . . . . . . . . . . . . . . . . . . . . . . 2-118 SalParentWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-118 SalPicClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-119 SalPicGetDescription . . . . . . . . . . . . . . . . . . . . . . . 2-119 SalPicGetString. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-120 SalPicSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-120 SalPicSetFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-121 SalPicSetFit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-121 SalPicSetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-122 SalPixelsToFormUnits. . . . . . . . . . . . . . . . . . . . . . . 2-123 SalPostMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-123 SalPrtExtractRect . . . . . . . . . . . . . . . . . . . . . . . . . . 2-124 SalPrtGetDefault . . . . . . . . . . . . . . . . . . . . . . . . . . 2-124 SalPrtGetParmNum . . . . . . . . . . . . . . . . . . . . . . . . 2-125 SalPrtPrintForm. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-125 SalPrtSetDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-126
xi
SalPrtSetParmDefaults . . . . . . . . . . . . . . . . . . . . . 2-126 SalPrtSetParmNum . . . . . . . . . . . . . . . . . . . . . . . . . 2-127 SalPrtSetup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-127 SalQueryFieldEdit . . . . . . . . . . . . . . . . . . . . . . . . . 2-128 SalQuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-128 SalReportClose . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-129 SalReportCmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-129 SalReportCreate . . . . . . . . . . . . . . . . . . . . . . . . . . 2-129 SalReportDlgOptions . . . . . . . . . . . . . . . . . . . . . . . 2-130 SalReportGetDateTimeVar . . . . . . . . . . . . . . . . . . 2-131 SalReportGetNumberVar . . . . . . . . . . . . . . . . . . . . 2-131 SalReportGetObjectVar . . . . . . . . . . . . . . . . . . . . . 2-132 SalReportGetStringVar . . . . . . . . . . . . . . . . . . . . . 2-132 SalReportPrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-133 SalReportPrintToFile . . . . . . . . . . . . . . . . . . . . . . . 2-134 SalReportReset . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-136 SalReportSetDateTimeVar . . . . . . . . . . . . . . . . . . . 2-136 SalReportSetNumberVar . . . . . . . . . . . . . . . . . . . . 2-137 SalReportSetObjectVar . . . . . . . . . . . . . . . . . . . . . 2-137 SalReportSetStringVar . . . . . . . . . . . . . . . . . . . . . . 2-138 SalReportTableCreate . . . . . . . . . . . . . . . . . . . . . . 2-138 SalReportTablePrint . . . . . . . . . . . . . . . . . . . . . . . . 2-139 SalReportTableView . . . . . . . . . . . . . . . . . . . . . . . . 2-140 SalReportView . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-140 SalScrollGetPos . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-142 SalScrollGetRange . . . . . . . . . . . . . . . . . . . . . . . . . 2-142 SalScrollSetPos . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-143 SalScrollSetRange . . . . . . . . . . . . . . . . . . . . . . . . . 2-143 SalSendClassMessage . . . . . . . . . . . . . . . . . . . . . 2-144 SalSendClassMessageNamed . . . . . . . . . . . . . . . . 2-144 SalSendMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-145 SalSendMsgToChildren . . . . . . . . . . . . . . . . . . . . . 2-145
SalSendValidateMsg. . . . . . . . . . . . . . . . . . . . . . . . 2-146 SalSetDefButton . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-146 SalSetFieldEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-147 SalSetFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-147 SalSetMaxDataLength . . . . . . . . . . . . . . . . . . . . . . 2-148 SalSetProfileString . . . . . . . . . . . . . . . . . . . . . . . . . 2-148 SalSetWindowLabelText . . . . . . . . . . . . . . . . . . . . 2-149 SalSetWindowLoc . . . . . . . . . . . . . . . . . . . . . . . . . 2-149 SalSetWindowSize . . . . . . . . . . . . . . . . . . . . . . . . . 2-149 SalSetWindowText . . . . . . . . . . . . . . . . . . . . . . . . . 2-150 SalShowWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-150 SalShowWindowAndLabel . . . . . . . . . . . . . . . . . . . 2-151 SalStatusGetText . . . . . . . . . . . . . . . . . . . . . . . . . . 2-151 SalStatusSetText . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152 SalStatusSetVisible . . . . . . . . . . . . . . . . . . . . . . . . 2-152 SalStrCompress . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152 SalStrFirstC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-153 SalStrGetBufferLength . . . . . . . . . . . . . . . . . . . . . . 2-153 SalStrIsValidCurrency . . . . . . . . . . . . . . . . . . . . . . . 2-154 SalStrIsValidDateTime . . . . . . . . . . . . . . . . . . . . . . 2-154 SalStrIsValidNumber . . . . . . . . . . . . . . . . . . . . . . . 2-155 SalStrLeft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-155 SalStrLeftX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-156 SalStrLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-156 SalStrLop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-157 SalStrLower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-157 SalStrMid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-158 SalStrProper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-158 SalStrRepeat and SalStrRepeatX . . . . . . . . . . . . . 2-159 SalStrReplace and SalStrReplaceX . . . . . . . . . . . . 2-159 SalStrRight and SalStrRightX . . . . . . . . . . . . . . . . 2-160 SalStrScan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-161
xiii
Contents SalStrSetBufferLength . . . . . . . . . . . . . . . . . . . . . . 2-162 SalStrToDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-162 SalStrTokenize . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-163 SalStrToNumber . . . . . . . . . . . . . . . . . . . . . . . . . . 2-163 SalStrTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-164 SalStrTrimX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-164 SalStrUncompress . . . . . . . . . . . . . . . . . . . . . . . . . 2-165 SalStrUpper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-165 SalStrUpperX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-165 SalTBarSetVisible . . . . . . . . . . . . . . . . . . . . . . . . . 2-166 SalTblAnyRows . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-166 SalTblClearSelection . . . . . . . . . . . . . . . . . . . . . . . 2-167 SalTblColumnAverage . . . . . . . . . . . . . . . . . . . . . . 2-167 SalTblColumnSum . . . . . . . . . . . . . . . . . . . . . . . . . 2-167 SalTblCopyRows . . . . . . . . . . . . . . . . . . . . . . . . . . 2-168 SalTblCreateColumn . . . . . . . . . . . . . . . . . . . . . . . 2-169 SalTblDefineCheckBoxColumn . . . . . . . . . . . . . . . 2-169 SalTblDefineDropDownListColumn . . . . . . . . . . . . 2-170 SalTblDefinePopupEditColumn. . . . . . . . . . . . . . . . 2-170 SalTblDefineRowHeader . . . . . . . . . . . . . . . . . . . . 2-171 SalTblDefineSplitWindow . . . . . . . . . . . . . . . . . . . . 2-171 SalTblDeleteRow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-172 SalTblDeleteSelected . . . . . . . . . . . . . . . . . . . . . . . 2-172 SalTblDestroyColumns . . . . . . . . . . . . . . . . . . . . . 2-173 SalTblDoDeletes . . . . . . . . . . . . . . . . . . . . . . . . . . 2-173 SalTblDoInserts. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-174 SalTblDoUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . 2-175 SalTblFetchRow . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-175 SalTblFindNextRow . . . . . . . . . . . . . . . . . . . . . . . . 2-176 SalTblFindPrevRow . . . . . . . . . . . . . . . . . . . . . . . . 2-177 SalTblGetColumnText . . . . . . . . . . . . . . . . . . . . . . 2-178 SalTblGetColumnTitle . . . . . . . . . . . . . . . . . . . . . . 2-178
xiv
SalTblGetColumnWindow . . . . . . . . . . . . . . . . . . . 2-178 SalTblInsertRow . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-179 SalTblKillEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-179 SalTblKillFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-180 SalTblPasteRows . . . . . . . . . . . . . . . . . . . . . . . . . . 2-180 SalTblPopulate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-180 SalTblQueryCheckBoxColumn . . . . . . . . . . . . . . . 2-182 SalTblQueryColumnCellType . . . . . . . . . . . . . . . . . 2-182 SalTblQueryColumnFlags. . . . . . . . . . . . . . . . . . . . 2-183 SalTblQueryColumnID . . . . . . . . . . . . . . . . . . . . . . 2-183 SalTblQueryColumnPos . . . . . . . . . . . . . . . . . . . . . 2-183 SalTblQueryColumnWidth . . . . . . . . . . . . . . . . . . . 2-184 SalTblQueryContext . . . . . . . . . . . . . . . . . . . . . . . . 2-184 SalTblQueryDropDownListColumn . . . . . . . . . . . . 2-184 SalTblQueryFocus . . . . . . . . . . . . . . . . . . . . . . . . . 2-185 SalTblQueryLinesPerRow. . . . . . . . . . . . . . . . . . . . 2-185 SalTblQueryLockedColumns . . . . . . . . . . . . . . . . . 2-186 SalTblQueryPopupEditColumn . . . . . . . . . . . . . . . . 2-186 SalTblQueryRowFlags . . . . . . . . . . . . . . . . . . . . . . 2-187 SalTblQueryRowHeader . . . . . . . . . . . . . . . . . . . . 2-187 SalTblQueryScroll . . . . . . . . . . . . . . . . . . . . . . . . . 2-188 SalTblQuerySplitWindow . . . . . . . . . . . . . . . . . . . . 2-188 SalTblQueryTableFlags . . . . . . . . . . . . . . . . . . . . . 2-189 SalTblQueryVisibleRange . . . . . . . . . . . . . . . . . . . 2-189 SalTblReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-189 SalTblScroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-190 SalTblSetCellTextColor . . . . . . . . . . . . . . . . . . . . . 2-190 SalTblSetColumnFlags . . . . . . . . . . . . . . . . . . . . . 2-191 SalTblSetColumnPos . . . . . . . . . . . . . . . . . . . . . . . 2-191 SalTblSetColumnText . . . . . . . . . . . . . . . . . . . . . . 2-192 SalTblSetColumnTitle . . . . . . . . . . . . . . . . . . . . . . 2-192 SalTblSetColumnWidth . . . . . . . . . . . . . . . . . . . . . 2-192
xv
Contents SalTblSetContext . . . . . . . . . . . . . . . . . . . . . . . . . . 2-193 SalTblSetFlagsAnyRows . . . . . . . . . . . . . . . . . . . . 2-193 SalTblSetFocusCell . . . . . . . . . . . . . . . . . . . . . . . . 2-194 SalTblSetFocusRow . . . . . . . . . . . . . . . . . . . . . . . . 2-195 SalTblSetLinesPerRow . . . . . . . . . . . . . . . . . . . . . 2-195 SalTblSetLockedColumns . . . . . . . . . . . . . . . . . . . 2-195 SalTblSetRange . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-196 SalTblSetRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-196 SalTblSetRowFlags . . . . . . . . . . . . . . . . . . . . . . . . 2-197 SalTblSetTableFlags . . . . . . . . . . . . . . . . . . . . . . . 2-197 SalTblSortRows . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-198 SalTimerKill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-198 SalTimerSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-199 SalTrackPopupMenu. . . . . . . . . . . . . . . . . . . . . . . . 2-199 SalUpdateWindow. . . . . . . . . . . . . . . . . . . . . . . . . . 2-200 SalUseRegistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-201 SalValidateSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-201 SalWaitCursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202 SalWindowClassName . . . . . . . . . . . . . . . . . . . . . . 2-202 SalWindowGetProperty. . . . . . . . . . . . . . . . . . . . . . 2-203 SalWindowHandleToNumber . . . . . . . . . . . . . . . . . 2-203 SalWindowIsDerivedFromClass . . . . . . . . . . . . . . . 2-203 SalWinHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-204 SalYieldEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-205 SalYieldQueryState . . . . . . . . . . . . . . . . . . . . . . . . 2-205 SalYieldStartMessages . . . . . . . . . . . . . . . . . . . . . 2-205 SalYieldStopMessages . . . . . . . . . . . . . . . . . . . . . . 2-206 SqlClearImmediate . . . . . . . . . . . . . . . . . . . . . . . . . 2-206 SqlClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-206 SqlCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-207 SqlConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-207 SqlContextClear . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-208
xvi
SqlContextSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-208 SqlContextSetToForm . . . . . . . . . . . . . . . . . . . . . . 2-209 SqlDirectoryByName . . . . . . . . . . . . . . . . . . . . . . . 2-209 SqlDisconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-209 SqlDropStoredCmd . . . . . . . . . . . . . . . . . . . . . . . . . 2-210 SqlError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-210 SqlErrorText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-210 SqlExecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-211 SqlExecutionPlan . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212 SqlExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212 SqlExtractArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212 SqlFetchNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-213 SqlFetchPrevious . . . . . . . . . . . . . . . . . . . . . . . . . . 2-214 SqlFetchRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-214 SqlGetError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-214 SqlGetErrorPosition . . . . . . . . . . . . . . . . . . . . . . . . 2-215 SqlGetErrorText . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-215 SqlGetErrorTextX . . . . . . . . . . . . . . . . . . . . . . . . . . 2-216 SqlGetLastStatement . . . . . . . . . . . . . . . . . . . . . . . 2-216 SqlGetModifiedRows . . . . . . . . . . . . . . . . . . . . . . . 2-217 SqlGetParameter . . . . . . . . . . . . . . . . . . . . . . . . . . 2-217 SqlGetParameterAll . . . . . . . . . . . . . . . . . . . . . . . . 2-218 SqlGetResultSetCount . . . . . . . . . . . . . . . . . . . . . . 2-218 SqlGetRollbackFlag . . . . . . . . . . . . . . . . . . . . . . . . 2-219 SqlImmediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-219 SqlImmediateContext . . . . . . . . . . . . . . . . . . . . . . . 2-220 SqlOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-221 SqlPLSQLCommand. . . . . . . . . . . . . . . . . . . . . . . . 2-221 SqlPrepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-223 SqlPrepareAndExecute . . . . . . . . . . . . . . . . . . . . . 2-224 SqlRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-225 SqlSetInMessage . . . . . . . . . . . . . . . . . . . . . . . . . . 2-225
xvii
Contents SqlSetIsolationLevel . . . . . . . . . . . . . . . . . . . . . . . . 2-226 SqlSetLockTimeout . . . . . . . . . . . . . . . . . . . . . . . . 2-227 SqlSetLongBindDatatype . . . . . . . . . . . . . . . . . . . . 2-227 SqlSetOutMessage . . . . . . . . . . . . . . . . . . . . . . . . 2-228 SqlSetParameter . . . . . . . . . . . . . . . . . . . . . . . . . . 2-228 SqlSetParameterAll . . . . . . . . . . . . . . . . . . . . . . . . 2-229 SqlSetResultSet . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-229 SqlStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-230 VisArrayAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-231 VisArrayCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-232 VisArrayDeleteItem . . . . . . . . . . . . . . . . . . . . . . . . . 2-233 VisArrayFillDateTime . . . . . . . . . . . . . . . . . . . . . . . 2-233 VisArrayFillNumber . . . . . . . . . . . . . . . . . . . . . . . . 2-234 VisArrayFillString. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-234 VisArrayFindDateTime . . . . . . . . . . . . . . . . . . . . . . 2-235 VisArrayFindNumber . . . . . . . . . . . . . . . . . . . . . . . 2-235 VisArrayFindString . . . . . . . . . . . . . . . . . . . . . . . . . 2-236 VisArrayInsertItem . . . . . . . . . . . . . . . . . . . . . . . . . 2-237 VisArraySort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-237 VisDebugAssert . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-238 VisDebugBeginTime . . . . . . . . . . . . . . . . . . . . . . . 2-239 VisDebugEndTime . . . . . . . . . . . . . . . . . . . . . . . . . 2-239 VisDebugGetFlags . . . . . . . . . . . . . . . . . . . . . . . . . 2-240 VisDebugSetFlags . . . . . . . . . . . . . . . . . . . . . . . . . 2-240 VisDebugSetLevel . . . . . . . . . . . . . . . . . . . . . . . . . 2-241 VisDebugSetTime . . . . . . . . . . . . . . . . . . . . . . . . . 2-241 VisDebugString . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-242 VisDosBuildFullName . . . . . . . . . . . . . . . . . . . . . . 2-242 VisDosEnumDirInfo . . . . . . . . . . . . . . . . . . . . . . . . 2-243 VisDosEnumDirs . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-244 VisDosEnumDrives . . . . . . . . . . . . . . . . . . . . . . . . 2-244 VisDosEnumFileInfo . . . . . . . . . . . . . . . . . . . . . . . . 2-245
xviii
VisDosEnumFiles . . . . . . . . . . . . . . . . . . . . . . . . . . 2-246 VisDosEnumNetConnections . . . . . . . . . . . . . . . . . 2-247 VisDosEnumPath . . . . . . . . . . . . . . . . . . . . . . . . . . 2-248 VisDosEnumsShortDirInfo . . . . . . . . . . . . . . . . . . . 2-249 VisDosEnumsShortDirs . . . . . . . . . . . . . . . . . . . . . 2-249 VisDosEnumsShortFileInfo . . . . . . . . . . . . . . . . . . 2-250 VisDosEnumsShortFiles . . . . . . . . . . . . . . . . . . . . . 2-251 VisDosExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-251 VisDosGetCurDir . . . . . . . . . . . . . . . . . . . . . . . . . . 2-252 VisDosGetDriveSize . . . . . . . . . . . . . . . . . . . . . . . . 2-252 VisDosGetDriveType . . . . . . . . . . . . . . . . . . . . . . . 2-253 VisDosGetEnvString . . . . . . . . . . . . . . . . . . . . . . . 2-254 VisDosGetFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-254 VisDosGetNetName . . . . . . . . . . . . . . . . . . . . . . . . 2-255 VisDosGetVersion. . . . . . . . . . . . . . . . . . . . . . . . . . 2-255 VisDosGetVolumeLabel . . . . . . . . . . . . . . . . . . . . . 2-256 VisDosIsParent . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-256 VisDosMakeAllDir . . . . . . . . . . . . . . . . . . . . . . . . . 2-257 VisDosMakePath. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-257 VisDosNetConnect . . . . . . . . . . . . . . . . . . . . . . . . . 2-258 VisDosNetDisconnect . . . . . . . . . . . . . . . . . . . . . . 2-258 VisDosSetFlags. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-259 VisDosSetVolumeLabel . . . . . . . . . . . . . . . . . . . . . 2-259 VisDosSplitPath . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-260 VisErrorRecovery . . . . . . . . . . . . . . . . . . . . . . . . . . 2-261 VisFileAppend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-261 VisFileClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262 VisFileCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262 VisFileCreateTemp . . . . . . . . . . . . . . . . . . . . . . . . 2-263 VisFileDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-263 VisFileExpand . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-263 VisFileFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-264
xix
Contents VisFileGetAttribute . . . . . . . . . . . . . . . . . . . . . . . . . 2-264 VisFileGetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-265 VisFileGetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-265 VisFileOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-266 VisFileRead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-267 VisFileReadString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-268 VisFileRename . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-268 VisFileSeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-269 VisFileSetAttribute . . . . . . . . . . . . . . . . . . . . . . . . . 2-269 VisFileSetDateTime . . . . . . . . . . . . . . . . . . . . . . . . 2-270 VisFileTell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-271 VisFileWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-271 VisFileWriteString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272 VisFontEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272 VisFontFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-273 VisFontGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-273 VisFontLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-274 VisGetCopyright . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-275 VisGetKeyState . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-275 VisGetSystemMetrics . . . . . . . . . . . . . . . . . . . . . . . 2-275 VisGetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-276 VisGetWinFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-276 VisGetWinVersion . . . . . . . . . . . . . . . . . . . . . . . . . 2-277 VisListAddValue . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-277 VisListArrayPopulate . . . . . . . . . . . . . . . . . . . . . . . 2-278 VisListArrayPopulateValue . . . . . . . . . . . . . . . . . . . 2-278 VisListClearSelection . . . . . . . . . . . . . . . . . . . . . . . 2-279 VisListDeleteSelected . . . . . . . . . . . . . . . . . . . . . . . 2-279 VisListFindString . . . . . . . . . . . . . . . . . . . . . . . . . . 2-280 VisListFindValue . . . . . . . . . . . . . . . . . . . . . . . . . . 2-280 VisListGetDropdownState . . . . . . . . . . . . . . . . . . . 2-281 VisListGetFocusIndex . . . . . . . . . . . . . . . . . . . . . . 2-281
xx
VisListGetVisibleRange . . . . . . . . . . . . . . . . . . . . . 2-282 VisListInsertValue . . . . . . . . . . . . . . . . . . . . . . . . . 2-282 VisListIsMultiSelect . . . . . . . . . . . . . . . . . . . . . . . . 2-283 VisListLoadOutline . . . . . . . . . . . . . . . . . . . . . . . . . 2-283 VisListLoadOutlineFile . . . . . . . . . . . . . . . . . . . . . . 2-284 VisListSaveOutline . . . . . . . . . . . . . . . . . . . . . . . . . 2-285 VisListScroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-285 VisListSetDropdownState . . . . . . . . . . . . . . . . . . . 2-286 VisListSetFocusIndex . . . . . . . . . . . . . . . . . . . . . . . 2-286 VisListSetScrollWidth . . . . . . . . . . . . . . . . . . . . . . . 2-287 VisMenuGetPopupHandle . . . . . . . . . . . . . . . . . . . 2-287 VisMenuGetSystemHandle . . . . . . . . . . . . . . . . . . 2-288 VisMenuGetText . . . . . . . . . . . . . . . . . . . . . . . . . . 2-288 VisMenuInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-289 VisMenuInsertFont . . . . . . . . . . . . . . . . . . . . . . . . . 2-290 VisMenuInsertPicture . . . . . . . . . . . . . . . . . . . . . . . 2-291 VisMenuIsChecked . . . . . . . . . . . . . . . . . . . . . . . . 2-292 VisMenuIsEnabled . . . . . . . . . . . . . . . . . . . . . . . . . 2-293 VisMenuSetFont . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-294 VisMenuSetPicture . . . . . . . . . . . . . . . . . . . . . . . . . 2-295 VisMenuSetText . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-296 VisMenuUncheck . . . . . . . . . . . . . . . . . . . . . . . . . . 2-297 VisMessageBox . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-297 VisMessageFreeButton . . . . . . . . . . . . . . . . . . . . . 2-298 VisMessageLoadButton . . . . . . . . . . . . . . . . . . . . . 2-299 VisMessageSetBkgdColor . . . . . . . . . . . . . . . . . . . 2-299 VisNumberBitClear . . . . . . . . . . . . . . . . . . . . . . . . . 2-299 VisNumberBitSet . . . . . . . . . . . . . . . . . . . . . . . . . . 2-300 VisNumberChoose . . . . . . . . . . . . . . . . . . . . . . . . . 2-301 VisNumberHighByte . . . . . . . . . . . . . . . . . . . . . . . . 2-301 VisNumberLowByte . . . . . . . . . . . . . . . . . . . . . . . . 2-302 VisNumberMakeLong . . . . . . . . . . . . . . . . . . . . . . . 2-302
xxi
Contents VisPicFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-302 VisPicLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-303 VisSendMsgString . . . . . . . . . . . . . . . . . . . . . . . . . 2-304 VisStrChoose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-305 VisStrExpand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-305 VisStrFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-306 VisStrFreeTable . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-307 VisStrLeftTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-307 VisStrLoadTable . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-307 VisStrPad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-308 VisStrProper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-308 VisStrRightTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-309 VisStrScanReverse . . . . . . . . . . . . . . . . . . . . . . . . 2-309 VisStrSubstitute . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-309 VisStrTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-310 VisTblAllRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-310 VisTblAutoSizeColumn . . . . . . . . . . . . . . . . . . . . . 2-311 VisTblClearColumnSelection . . . . . . . . . . . . . . . . . 2-311 VisTblFindDateTime . . . . . . . . . . . . . . . . . . . . . . . . 2-312 VisTblFindNumber . . . . . . . . . . . . . . . . . . . . . . . . . 2-312 VisTblFindString . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-313 VisTblGetCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-314 VisTblGetColumnTitle . . . . . . . . . . . . . . . . . . . . . . 2-314 VisTblSetRowColor . . . . . . . . . . . . . . . . . . . . . . . . 2-315 VisTblSetRowPicture . . . . . . . . . . . . . . . . . . . . . . . 2-315 VisWaitCursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-316 VisWinClearAllEditFlags . . . . . . . . . . . . . . . . . . . . 2-317 VisWinClearAllFields . . . . . . . . . . . . . . . . . . . . . . . 2-317 VisWinEnumProps . . . . . . . . . . . . . . . . . . . . . . . . . 2-318 VisWinFreeAccelerator . . . . . . . . . . . . . . . . . . . . . 2-318 VisWinGetFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-319 VisWinGetHandle . . . . . . . . . . . . . . . . . . . . . . . . . . 2-319
xxii
VisWinGetProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-320 VisWinGetStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-320 VisWinGetText . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-321 VisWinIsChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-321 VisWinIsMaximized . . . . . . . . . . . . . . . . . . . . . . . . 2-322 VisWinIsMinimized . . . . . . . . . . . . . . . . . . . . . . . . . 2-322 VisWinIsRequiredFieldNull . . . . . . . . . . . . . . . . . . . 2-323 VisWinIsRestored . . . . . . . . . . . . . . . . . . . . . . . . . . 2-323 VisWinIsWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 2-324 VisWinLoadAccelerator . . . . . . . . . . . . . . . . . . . . . 2-324 VisWinMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-325 VisWinRemoveProp . . . . . . . . . . . . . . . . . . . . . . . . 2-326 VisWinSetFlags. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-326 VisWinSetMeter . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-327 VisWinSetProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-327 VisWinSetStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-328 VisWinSetTabOrder . . . . . . . . . . . . . . . . . . . . . . . . 2-329 VisWinShow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-329
xxiii
Preface
This Preface contains the following sections: Audience What is in this manual Typographical conventions Other helpful resources Send comments to...
xxv
Preface
Audience
This manual is an advanced guide for programmers creating complex and sophisticated applications using the Centura Builder.
What is in this manual

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

Centura Books Online. The Centura 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 Centura Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group. Centura Software Corporations Fast Facts. Centura Corporation maintains some of the latest information on topics such as, programming examples, and commonly occurring problems on Fast Facts. Call (415) 617-4600 to access a catalog of the documents available. You can request any document on the catalog to be faxed to you. CompuServe. If you are a CompuServe subscriber, you can join Centuras forum to learn about Centura products and communicate with other Centura users. The name of the forum is Centura. Centura 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. Centura Software Corporations World Wide Web site contains a wealth of information about Centura Software Corporations partners, products, and users. The URL address is http://www.centurasoft.com. Windows Users Guide. Refer to this manual for more information on the Microsoft Windows operating system.
Send comments to...

Everyone who reads the Guide can contribute to it. If you have any comments or suggestions, please send them to: Technical Publications Department Centura Corporation 1060 Marsh Rd. Menlo Park, CA 94025 techpubs@centurasoft.com
Centura Builder Function Referencexxvii
Chapter 1
Centura Builder Function Tables

The chapter contains functions tables that are arranged by type.
1-1
Chapter
Centura Functions
SalAbort SalAppDisable SalAppEnable SalAppFind SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum SalBringWindowToTop SalCenterWindow SalClearField SalColorFromRGB SalColorGet SalColorGetSysColor SalColorSet SalColorToRGB SalCompileAndEvaluate SalContextBreak SalContextCurrent SalCreateWindow SalCursorClear SalCursorSet SalCursorSetFile SalCursorSetString SalDateConstruct SalDateCurrent SalDateDay SalDateHour SalDateMinute SalDateMonth SalDateMonthBegin SalDateQuarter SalDateQuarterBegin SalDateSecond SalDateToStr SalDateWeekBegin 1-2
Centura Functions
SalDateWeekday SalDateYear SalDateYearBegin SalDDEAddAtom SalDDEAlloc SalDDEDeleteAtom SalDDEExtract SalDDEExtractCmd SalDDEExtractDataText SalDDEExtractOptions SalDDEFindAtom SalDDEFree SalDDEGetAtomName SalDDEGetExecuteString SalDDEPost SalDDERequest SalDDESend SalDDESendAll SalDDESendExecute SalDDESendToClient SalDDESetCmd SalDDESetDataText SalDDESetOptions SalDDEStartServer SalDDEStartSession SalDDEStopServer SalDDEStopSession SalDestroyWindow SalDisableWindow SalDisableWindowAndLabel SalDlgChooseColor SalDlgChooseFont SalDlgOpenFile SalDlgSaveFile SalDragDropDisableDrop SalDragDropEnableDrop SalDragDropGetSource SalDragDropGetTarget SalDragDropStart SalDragDropStop SalDrawMenuBar SalDropFilesAcceptFiles SalDropFilesQueryFiles 1-3
Chapter
SalDropFilesQueryPoint SalEditCanCopyTo SalEditCanCut SalEditCanPaste SalEditCanPasteFrom SalEditCanUndo SalEditClear SalEditCopy SalEditCopyString SalEditCopyTo SalEditCut SalEditPaste SalEditPasteFrom SalEditPasteString SalEditUndo SalEnableWindow SalEnableWindowAndLabel SalEndDialog SalFileClose SalFileCopy SalFileCreateDirectory SalFileGetC SalFileGetChar SalFileGetCurrentDirectory SalFileGetDateTime SalFileGetDrive SalFileGetStr SalFileOpen SalFileOpenExt SalFilePutC SalFilePutChar SalFilePutStr SalFileRead SalFileRemoveDirectory SalFileSeek SalFileSetCurrentDirectory SalFileSetDateTime SalFileSetDrive SalFileTell SalFileWrite SalFmtFieldToStr SalFmtFormatDateTime SalFmtFormatNumber 1-4
Centura Functions
SalFmtGetFormat SalFmtGetInputMask SalFmtGetPicture SalFmtIsValidField SalFmtIsValidInputMask SalFmtIsValidPicture SalFmtKeepMask SalFmtSetFormat SalFmtSetInputMask SalFmtSetPicture SalFmtStrToField SalFmtUnmaskInput SalFmtValidateField SalFontGet SalFontGetNames SalFontGetSizes SalFontSet SalFormGetParmNum SalFormUnitsToPixels SalGetDataType SalGetDefButton SalGetFirstChild SalGetFocus SalGetItemName SalGetMaxDataLength SalGetNextChild SalGetProfileInt SalGetProfileString SalGetType SalGetVersion SalGetWindowLabelText SalGetWindowLoc SalGetWindowSize SalGetWindowState SalGetWindowText SalHideWindow SalHideWindowAndLabel SalHStringToNumber SalInvalidateWindow SalIsButtonChecked SalIsNull SalIsValidDateTime SalIsValidDecimal 1-5
Chapter
SalIsValidInteger SalIsValidNumber SalIsWindowEnabled SalIsWindowVisible SalListAdd SalListClear SalListDelete SalListFiles SalListGetMultiSelect SalListInsert SalListPopulate SalListQueryCount SalListQueryFile SalListQueryMultiCount SalListQuerySelection SalListQueryState SalListQueryText SalListQueryTextLength SalListQueryTextX SalListRedraw SalListSelectString SalListSetMultiSelect SalListSetSelect SalListSetTabs SalLoadApp SalLoadAppAndWait SalMapEnterToTab SalMDIArrangeIcons SalMDICascade SalMDITile SalMessageBeep SalMessageBox SalModalDialog SalModalDialogFromStr SalMoveWindow SalNumberAbs SalNumberArcCos SalNumberArcSin SalNumberArcTan SalNumberArcTan2 SalNumberCos SalNumberCosH SalNumberExponent 1-6
Centura Functions
SalNumberHigh SalNumberHypot SalNumberLog SalNumberLogBase10 SalNumberLow SalNumberMax SalNumberMin SalNumberMod SalNumberPi SalNumberPower SalNumberRandInit SalNumberRandom SalNumberRound SalNumberSin SalNumberSinH SalNumberSqrt SalNumberTan SalNumberTanH SalNumberToChar SalNumberToHString SalNumberToStr SalNumberToStrX SalNumberToWindowHandle SalNumberTruncate SalParentWindow SalPicClear SalPicGetDescription SalPicGetString SalPicSet SalPicSetFile SalPicSetFit SalPicSetString SalPixelsToFormUnits SalPostMsg SalPrtExtractRect SalPrtGetDefault SalPrtGetParmNum SalPrtPrintForm SalPrtSetDefault SalPrtSetParmDefaults SalPrtSetParmNum SalPrtSetup SalQueryFieldEdit 1-7
Chapter
SalQuit SalReportClose SalReportCmd SalReportCreate SalReportDlgOptions SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetObjectVar SalReportGetStringVar SalReportPrint SalReportPrintToFile SalReportReset SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar SalReportSetStringVar SalReportTableCreate SalReportTablePrint SalReportTableView SalReportView SalScrollGetPos SalScrollGetRange SalScrollSetPos SalScrollSetRange SalSendClassMessage SalSendClassMessageNamed SalSendMsg SalSendMsgToChildren SalSendValidateMsg SalSetDefButton SalSetFieldEdit SalSetFocus SalSetMaxDataLength SalSetProfileString SalSetWindowLabelText SalSetWindowLoc SalSetWindowSize SalSetWindowText SalShowWindow SalShowWindowAndLabel SalStatusGetText SalStatusSetText SalStatusSetVisible 1-8
Centura Functions
SalStrCompress SalStrFirstC SalStrGetBufferLength SalStrIsValidCurrency SalStrIsValidDateTime SalStrIsValidNumber SalStrLeft SalStrLeftX SalStrLength SalStrLop SalStrLower SalStrLowerX SalStrMid SalStrMidX SalStrProper SalStrProperX SalStrRepeat SalStrRepeatX SalStrReplace SalStrReplaceX SalStrRight SalStrRightX SalStrScan SalStrSetBufferLength SalStrToDate SalStrTokenize SalStrToNumber SalStrTrim SalStrTrimX SalStrUncompress SalStrUpper SalStrUpperX SalTBarSetVisible SalTblAnyRows SalTblClearSelection SalTblColumnAverage SalTblColumnSum SalTblCopyRows SalTblCreateColumn SalTblDefineRowHeader SalTblDefineSplitWindow SalTblDeleteRow SalTblDeleteSelected 1-9
Chapter
SalTblDestroyColumns SalTblDoDeletes SalTblDoInserts SalTblDoUpdates SalTblFetchRow SalTblFindNextRow SalTblFindPrevRow SalTblGetColumnText SalTblGetColumnTitle SalTblGetColumnWindow SalTblInsertRow SalTblKillEdit SalTblKillFocus SalTblPasteRows SalTblPopulate SalTblQueryColumnFlags SalTblQueryColumnID SalTblQueryColumnPos SalTblQueryColumnWidth SalTblQueryContext SalTblQueryFocus SalTblQueryLockedColumns SalTblQueryRowFlags SalTblQueryRowHeader SalTblQueryScroll SalTblQuerySplitWindow SalTblQueryTableFlags SalTblQueryVisibleRange SalTblReset SalTblScroll SalTblSetCellTextColor SalTblSetColumnFlags SalTblSetColumnPos SalTblSetColumnText SalTblSetColumnTitle SalTblSetColumnWidth SalTblSetContext SalTblSetFlagsAnyRows SalTblSetFocusCell SalTblSetFocusRow SalTblSetLockedColumns SalTblSetRange SalTblSetRow 1-10
Centura Functions
SalTblSetRowFlags SalTblSetTableFlags SalTblSortRows SalTimerKill SalTimerSet SalTrackPopupMenu SalUpdateWindow SalValidateSet SalWaitCursor SalWindowGetProperty SalWindowHandleToNumber SalWindowIsDerivedFromClass SalWinHelp SalYieldEnable SalYieldQueryState SalYieldStartMessages SalYieldStopMessages SqlClearImmediate SqlClose SqlCommit SqlConnect SqlContextClear SqlContextSet SqlContextSetToForm SqlDirectoryByName SqlDisconnect SqlDropStoredCmd SqlError SqlErrorText SqlExecute SqlExecutionPlan SqlExists SqlExtractArgs SqlFetchNext SqlFetchPrevious SqlFetchRow SqlGetError SqlGetErrorPosition SqlGetErrorText SqlGetErrorTextX SqlGetModifiedRows SqlGetParameter SqlGetParameterAll 1-11
Chapter
SqlGetResultSetCount SqlGetRollbackFlag SqlImmediate SqlImmediateContext SqlOpen SqlPLSQLCommand SqlPrepare SqlPrepareAndExecute SqlRetrieve SqlSetInMessage SqlSetIsolationLevel SqlSetLockTimeout SqlSetLongBindDatatype SqlSetOutMessage SqlSetParameter SqlSetParameterAll SqlSetResultSet SqlStore SqlVarSetup VisArrayAppend VisArrayCopy VisArrayDeleteItem VisArrayFillDateTime VisArrayFillNumber VisArrayFillString VisArrayFindDateTime VisArrayFindNumber VisArrayFindString VisArrayInsertItem VisArraySort VisDebugAssert VisDebugBeginTime VisDebugEndTime VisDebugGetFlags VisDebugSetFlags VisDebugSetLevel VisDebugSetTime VisDebugString VisDosBuildFullName VisDosEnumDirInfo VisDosEnumDirs VisDosEnumDrives VisDosEnumFileInfo 1-12
Centura Functions
VisDosEnumFiles VisDosEnumNetConnections VisDosEnumPath VisDosEnumsShortDirInfo VisDosEnumsShortDirs VisDosEnumsShortFileInfo VisDosEnumsShortFiles VisDosExist VisDosGetCurDir VisDosGetDriveSize VisDosGetDriveType VisDosGetEnvString VisDosGetFlags VisDosGetNetName VisDosGetVersion VisDosGetVolumeLabel VisDosIsParent VisDosMakeAllDir VisDosMakePath VisDosNetConnect VisDosNetDisconnect VisDosSetFlags VisDosSetVolumeLabel VisDosSplitPath VisErrorRecovery VisFileAppend VisFileClose VisFileCopy VisFileCreateTemp VisFileDelete VisFileExpand VisFileFind VisFileGetAttribute VisFileGetSize VisFileGetType VisFileOpen VisFileRead VisFileReadString VisFileRename VisFileSeek VisFileSetAttribute VisFileSetDateTime VisFileTell 1-13
Chapter
VisFileWrite VisFileWriteString VisFontEnum VisFontFree VisFontGet VisFontLoad VisGetCopyright VisGetKeyState VisGetSystemMetrics VisGetVersion VisGetWinFlags VisGetWinVersion VisListAddValue VisListArrayPopulate VisListArrayPopulateValue VisListClearSelection VisListDeleteSelected VisListFindString VisListFindValue VisListGetDropdownState VisListGetFocusIndex VisListGetVisibleRange VisListInsertValue VisListIsMultiSelect VisListLoadOutline VisListLoadOutlineFile VisListSaveOutline VisListScroll VisListSetDropdownState VisListSetFocusIndex VisListSetScrollWidth VisMenuGetPopupHandle VisMenuGetSystemHandle VisMenuGetText VisMenuInsert VisMenuInsertFont VisMenuInsertPicture VisMenuIsChecked VisMenuIsEnabled VisMenuSetFont VisMenuSetPicture VisMenuSetText VisMenuUncheck 1-14
Centura Functions
VisMessageBox VisMessageFreeButton VisMessageLoadButton VisMessageSetBkgdColor VisNumberBitClear VisNumberBitSet VisNumberChoose VisNumberHighByte VisNumberLowByte VisNumberMakeLong VisPicFree VisPicLoad VisProfileDelete VisProfileEnumStrings VisSendMsgString VisStrChoose VisStrExpand VisStrFind VisStrFreeTable VisStrLeftTrim VisStrLoadTable VisStrPad VisStrProper VisStrRightTrim VisStrScanReverse VisStrSubstitute VisStrTrim VisTblAllRows VisTblAutoSizeColumn VisTblClearColumnSelection VisTblFindDateTime VisTblFindNumber VisTblFindString VisTblGetCell VisTblGetColumnTitle VisTblSetRowColor VisTblSetRowPicture VisWaitCursor VisWinClearAllEditFlags VisWinClearAllFields VisWinEnumProps VisWinFreeAccelerator VisWinGetFlags 1-15
Chapter
VisWinGetHandle VisWinGetProp VisWinGetStyle VisWinGetText VisWinIsChild VisWinIsMaximized VisWinIsMinimized VisWinIsRequiredFieldNull VisWinIsRestored VisWinIsWindow VisWinLoadAccelerator VisWinMove VisWinRemoveProp VisWinSetFlags VisWinSetMeter VisWinSetProp VisWinSetStyle VisWinSetTabOrder VisWinShow
Obsolete Centura Functions

SalCreateWindowFrmStr SalFmtCopyProfile SalFmtGetParmInt SalFmtGetParmStr SalFmtGetProfile SalFmtSetParmInt SalFmtSetParmStr SalFmtSetProfile SalQueryArrayBounds SalSetArrayBounds
1-16
Centura Function Categories

Centura functions are divided into categories. This section identifies and briefly describes each category in addition to listing the functions in each one. Array functions Color and font functions Data type conversion functions Date functions DDE functions Debugging functions Dialog box functions DOS management functions Drag Drop functions Edit functions File management functions Format and validation functions List and combo box functions Manipulating background text functions MDI (Multiple Document Interface) functions Message functions Miscellaneous functions Number functions Picture functions Print functions Report functions Scroll bar functions SQL functions String conversion functions Table window functions Window management functions
Array Functions
These functions manage arrays and compute values.
Function Name SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound Description Gets the average of values in an array of numbers Gets the number of dimensions in nValue. Gets the lower bound of an array. Gets the upper bound of an array.
1-17
Chapter
Function Name SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum VisArrayAppend VisArrayCopy VisArrayDeleteItem VisArrayFillDateTime VisArrayFillNumber VisArrayFillString VisArrayFindDateTime VisArrayFindNumber VisArrayFindString VisArrayInsertItem VisArraySort
Description Determines if a dynamic array contains any data. Gets the maximum value in an array of numbers. Gets the minimum value in an array of numbers. Sets the upper bound of an array. Computes the sum of an array's elements. Appends one array onto the end of another array. Copies one array into another. Deletes an item from an array. Fills a Date/Time array with a specified date/ time value. Fills a number array with a specified value. Fills a string array with a specified string. Locates a date/time value within an array. Locates a number within an array. Locates a string within an array. Inserts an item into an array. Sorts an array in either ascending or descending order.
Color and Font Functions

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

These functions manipulate string data by converting to and from other data types.
Function Name SalFormUnitsToPixels SalGetDataType Description Computes the number of pixels in the number of Centura form units. Returns an object's data type.
1-19
Chapter
Function Name SalGetItemName SalGetMaxDataLength SalHStringToNumber SalPixelsToFormUnits SalSetMaxDataLength
Description Gets the name of a form window or data field. Gets the maximum length of a data field, multiline field, or table window column. Converts a string to a number. Computes the number of Centura form units in the number of pixels. Sets the maximum length of a data field.
Date Functions
These functions manipulate date/time values.
Function Name SalDateConstruct SalDateCurrent SalDateDay SalDateHour SalDateMinute SalDateMonth SalDateMonthBegin SalDateQuarter SalDateQuarterBegin SalDateSecond SalDateToStr SalDateWeekBegin SalDateWeekday SalDateYea SalDateYearBegin Description Constructs a date. Gets the client's current date and time. Gets the day portion of a date. Gets the hour portion of a date. Gets the minute portion of a date. Gets the month portion of a date. Gets the date of the first day of a month. Gets the quarter of the year of a date. Gets the date of the first day of the quarter of a given date. Gets the seconds portion of the date. Converts a date value to a string value. Gets the date of the previous Monday. Gets the day of the week as a number. Gets the year portion of a date. Gets the date of the first day of the year of a given date.
1-20
DDE Functions
These functions support the Microsoft protocols for Dynamic Data Exchange (DDE). DDE lets you exchange data with other Windows applications that also support the Microsoft protocols.
Function Name SalDDEAddAtom SalDDEAlloc SalDDEDeleteAtom SalDDEExtract SalDDEExtractCmd SalDDEExtractDataText SalDDEExtractOptions SalDDEFindAtom SalDDEFree SalDDEGetAtomName SalDDEGetExecuteString SalDDEPost SalDDERequest SalDDESend SalDDESendAll SalDDESendExecute SalDDESendToClient SalDDESetCmd Description Adds a string to the atom table. Allocates a memory handle. Deletes an atom. Extracts DDE information from the wParam and lParam parameters of a DDE message. Extracts the command string in a WM_DDE_Execute message. Extracts data in a WM_DDE_Date or WM_DDE_Poke message. Extracts options in a WM_DDE_Advise message. Finds the atom associated with a string. Frees a memory handle. Returns the string associated with an atom number. Returns the command string sent by a client. Sends a DDE message. Asks a server to send specified data. Sends a WM_DDE_Ack message in response to a WM_DDE_Initiate message. Broadcasts a WM_DDE_Initiate message. Sends a WM_DDE_EXECUTE command to the specified server. Sends data to a client. Sets the command string in a WM_DDE_Execute message.
1-21
Chapter
Function Name SalDDESetDataText SalDDESetOptions SalDDEStartServer
Description Sets the data in a WM_DDE_Data or WM_DDE_Poke message. Sets the options in a WM_DDE_Advise message. Signals clients that the server is able to accept client connections and participate in a conversation. Starts a hot link conversation between a client and a server. Signals clients that the server wants to end DDE server operations. Ends a hot link conversation between a client and a server.
SalDDEStartSession SalDDEStopServer SalDDEStopSession
Debugging Functions
These functions help you debug your application.
Function Name SalCompileAndEvaluate SalContextBreak SalContextCurrent VisDebugAssert VisDebugBeginTime VisDebugEndTime VisDebugGetFlags VisDebugSetFlags VisDebugSetLevel VisDebugSetTime Description Evaluates the data type of an expression and returns its value. Retrieves the context of the most recently executed Break statement. Retrieves the current execution context. Asserts that a condition is true. Begins timing an operation. Stops recording the time and displays all incremental times and the total time. Retrieves the current debug flags. Sets debug flags. Sets the current debug level. Records the time since the last VisDebugSetTime or VisDebugBeginTime call.
1-22
Function Name VisDebugString
Description Writes a string to the debug application window.
Dialog Box Functions

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

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

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

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

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

These functions manage list boxes and combo boxes. Since list boxes can be singleor multiple-selection, and sorted or not sorted, you cannot use all the functions for all list boxes.
Function Name SalListAdd SalListClear SalListDelete SalListFiles SalListGetMultiSelect SalListInsert SalListPopulate SalListQueryCount SalListQueryFile SalListQueryMultiCount SalListQuerySelection SalListQueryState SalListQueryText and SalListQueryTextX SalListQueryTextLength SalListRedraw Description Adds an entry to a list box or combo box. Clears a list box or combo box. Deletes an entry from a list box or combo box. Populates a list box or combo box with a directory listing. Returns the index numbers of selected list box entries. Inserts an entry into a list box or combo box. Populates a list box or combo box with the result set of a query. Returns the number of entries in a list box or combo box. Fetches the selected file name from a list box or combo box. Returns the number of currently selected list box entries. Returns the index of the currently selected list box or combo box entry. Indicates whether the specified list box or combo box entry is selected. Fetches a list box or combo box entry. Returns the length of a list box or combo box entry. Allows changes in a list box or combo box to be redrawn or prevents changes from being redrawn. Finds and selects a particular list box or combo box entry.
SalListSelectString
1-31
Chapter
Function Name SalListSetMultiSelect SalListSetSelect SalListSetTabs VisListAddValue
Description Selects or deselects the specified list box entry. Selects the specified list box or combo box index entry. Sets tab stops in a list box. Adds an item to a sorted list box or combo box and associates the specified value with the item. Populates a list box from a string array. Populates a list box from a string array and an array of values. Each item in the string is inserted as an item in the list box. The number of Unselects all selected items in a list box or combo box. Deletes all selected items from a list box or combo box. Finds the first string that matches the specified string in a list box or combo box. This function will locate a value associated with an item based on an index. Determines whether the list box portion of a combo box is visible. Gets the index of the item which has the focus rectangle or the last item to receive the focus frame in a multiple-selection list box. Retrieves the indexes of both the first visible item and the last visible item in a list box. Inserts an item into an unsorted list box or combo box and associates the specified value with the item. Tests a list box to determine if multiple selection is enabled. Scrolls an item into view.
VisListArrayPopulate VisListArrayPopulateValue
VisListClearSelection VisListDeleteSelected VisListFindString VisListFindValue VisListGetDropdownState VisListGetFocusIndex
VisListGetVisibleRange VisListInsertValue
VisListIsMultiSelect VisListScroll
1-32
Function Name VisListSetDropdownState VisListSetFocusIndex
Description Shows or hides the list box portion of a combo box. Sets the focus rectangle to the item at the specified index in a multiple-selection list box. Sets the width by which a list box can be scrolled horizontally.
VisListSetScrollWidth
Manipulating Background Text Functions

These functions manipulate the background text.
Function Name SalAppDisable SalAppEnable SalAppFind Description Disables input to open windows. Enables input to open windows. Finds a visible top-level window for the application that you specify and returns its window handle. Brings a specified window to the top of all overlapping windows. Centers a window. Creates a window. Destroys a window. Disables mouse and keyboard input to a window. Disables mouse and keyboard input to a window, including disabling background text. Enables keyboard and mouse input to a window. Enables keyboard and mouse input to a window, including enabling background text. Gets information about a form window. Gets the handle of the default push button.
SalBringWindowToTop SalCenterWindow SalCreateWindow SalDestroyWindow SalDisableWindow SalDisableWindowAndLabel
SalEnableWindow SalEnableWindowAndLabel SalFormGetParmNum SalGetDefButton
1-33
Chapter
Function Name SalGetFirstChild SalGetFocus SalGetNextChild SalGetType SalGetWindowLabelText SalGetWindowLoc SalGetWindowSize SalGetWindowState SalGetWindowText SalHideWindow SalHideWindowAndLabel SalInvalidateWindow SalIsButtonChecked SalIsWindowEnabled SalIsWindowVisible SalMoveWindow
Description Finds the first child of a window. Gets the object with the focus. Finds the next child of a window. Returns the type of the specified object. Retrieves a window's background text. Gets a window's current position on the X and Y axes. Gets the current window's size. Gets the current state of a window. Retrieves a window's text. Hides a window. Hides a window and its associated label. Causes a window to be repainted. Determines whether a radio button is set or a check box is checked. Specifies whether a window is enabled for mouse and keyboard input. Specifies whether a window is visible. Moves a window a given number of form units on the X and Y axes relative to its current position. Returns the window handle of a parent or owner window. Returns the setting of the field edit flag for a data field, multiline field, table window column, or picture. Sets the default push button for a form window or dialog box. Sets or clears the field edit flag for a data field, multiline field, table window column, or picture.
SalParentWindow SalQueryFieldEdit
SalSetDefButton SalSetFieldEdit
1-34
Function Name SalSetFocus SalSetWindowLabelText SalSetWindowLoc SalSetWindowSize SalSetWindowText SalShowWindow SalShowWindowAndLabel SalStatusGetText SalStatusSetText SalStatusSetVisible SalTBarSetVisible SalUpdateWindow SalWindowGetProperty
Description Sets the focus to a window. Sets a window's background text. Moves a window to a position on the X and Y axes. Resizes a window. Sets a window's text. Makes a window visible. Hides a window and its associated label. Gets the text displayed in a top-level window's status bar. Displays specified text in a top-level window's status bar. Shows or hides a top-level window's optional status bar. Shows or hides a top-level window's tool bar. Updates the client area of a window. Gets the value of a named property for an instance of a QuickObject. The property must have been created at designtime with the QuickObject Editor. Converts a window handle to a number. Converts a window handle to a number. Changes the text of a menu item. Obtains the text of a window.
SalWindowHandleToNumber SalWindowIsDerivedFromClass VisMenuSetText VisWinGetText
These functions manipulate the background text label of a child window: SalDisableWindowAndLabel SalHideWindowAndLabel SalShowWindowAndLabel
Two other functions you can use with background text are explained below.
nLength = SalGetWindowLabelText( hWnd, sText, nMaxLength)
1-35
Chapter
Retrieves the background text of a window:
hWnd identifies the window that has a label to return it in the receive string sText. If this function fails, 0 is returned. The parameters are similar to SalGetWindowText.
bOk = SalSetWindowLabelText (hWnd, Stext)
Sets the background text of a window:
hWnd identifies the window that has a label. If this function fails, FALSE is returned. The parameters are the same as SalSetWindow Text.
MDI Functions
These functions support MDI (multiple document interface) windows.
Function Name SalMDIArrangeIcons SalMDICascade SalMDITile Description Arranges minimized child window icons in an MDI window. Cascades child windows of an MDI window. Tiles child windows of an MDI window.
Message Functions
Use these functions to post and send messages to objects.
Function Name SalPostMsg SalSendClassMessage Description Posts a message to a window. Invokes the message actions in the closest ancestor class that implements the given message. Invokes the message actions in the closest ancestor class that implements the given message. Use with a class that is the result of multiple inheritance. Sends a message to a window. Sends a message to all children of a form window. Sends a SAM_Validate message to the current data field, multiline field, or table window column if it has been edited.
SalSendClassMessageNamed
SendMsg SalSendMsgToChildren SalSendValidateMsg
1-36
Function Name VisMessageBox VisMessageFreeButton VisMessageLoadButton VisMessageSetBkgdColor VisSendMsgString
Description Displays a message box with user defined buttons and a user defined icon. Frees memory allocated with VisMessageLoadButton. Establishes a button to be used in userdefined message boxes. Sets the background color for a VisMessageBox dialog box. Sends a message and passes a string in lParam.
Miscellaneous Functions
These functions perform miscellaneous system tasks from within a Centura application.
Function Name SalAbort SalClearField SalCursorSet SalCursorSetFile SalCursorSetString SalDrawMenuBar SalGetProfileInt SalGetProfileString SalGetVersion SalLoadApp SalLoadAppAndWait Description Halts the execution of current actions. Clears the value from a field. Sets a window's cursor. Sets an application-defined cursor for the specified window. Sets a window's cursor from a string variable. Redraws a menu bar. Retrieves the integer value of an entry in the specified section of an initialization file. Retrieves the string value of an entry in the specified section of an initialization file. Returns the Centura version. Loads and starts an application. Loads and starts an application, then waits for it to exit before returning control to the original application.
1-37
Chapter
Function Name SalMapEnterToTab
Description Sets the default action of the Enter key (execute default push button or shift focus to next object). Generates a beep. Displays a message box. Exits the Centura application. Sets the value of an entry in the specified section of an initialization file. Destroys a system timer. Creates a system timer. Creates a pop-up menu at runtime. Displays or removes the hourglass cursor. Invokes the Windows help system. Enables or disables application yielding. Determines whether application yielding is enabled or disabled. Allows yielding and the sending of messages to a window. Stops yielding and the sending of messages to a window. Displays an error message and allows the user to free resources and retry the operation. Retrieves a copyright string to display in applications that use the Vis Library. Retrieves the state of a specified key. Retrieves widths and heights of various elements displayed by Windows. Gets the Vis Library version number. Retrieves the current Windows system and memory configuration.
SalMessageBeep SalMessageBox SalQuit SalSetProfileString SalTimerKill SalTimerSet SalTrackPopupMenu SalWaitCursor SalWinHelp SalYieldEnable SalYieldQueryState SalYieldStartMessages SalYieldStopMessages VisErrorRecovery VisGetCopyright VisGetKeyState VisGetSystemMetrics VisGetVersion VisGetWinFlags
1-38
Function Name VisGetWinVersion VisListLoadOutline VisListLoadOutlineFile VisListSaveOutline
Description Returns the Windows version number. Loads an outline from a blob (binary large object) in memory. Loads an outline from a tab indented ASCII file. Compresses and saves a list box or combo box outline into a blob (binary large object) in memory. Retrieves the menu handle of a pop-up menu. Retrieves the system menu handle of a window. Retrieves the text of a menu item. Inserts a menu item into a menu. Uses the Windows check state to test whether a menu item is checked. Uses the Windows enable state to test whether a menu item is enabled. Unchecks a menu item. Clears bit values from a number. Sets bit values in a number. Evaluates bExpression. Evaluates bExpression. Locates a string within a string table. Frees all memory associated with a string table. Trims leading blanks from a string. Loads a string table from disk into memory. Turns hourglass cursor on or off.
VisMenuGetPopupHandle VisMenuGetSystemHandle VisMenuGetText VisMenuInsert VisMenuIsChecked VisMenuIsEnabled VisMenuUncheck VisNumberBitClear VisNumberBitSet VisNumberChoose VisStrChoose VisStrFind VisStrFreeTable VisStrLeftTrim VisStrLoadTable VisWaitCursor
1-39
Chapter
Function Name VisWinClearAllEditFlags VisWinEnumProps VisWinFreeAccelerator
Description Clears the field edit flags for each data field or multi-line text field of a parent window. Enumerates the property list for a specified window. Clears an accelerator for a window, along with all memory associated with the accelerator. Retrieves window flags for a window. Retrieves a value from the property list of a specified window. Retrieves the Windows style bits for a specified window. Tests to determine if any required field is null. Displays a completion meter within a Centura data field.
VisWinGetFlags VisWinGetProp VisWinGetStyle VisWinIsRequiredFieldNull VisWinSetMeter
Number Functions
These functions perform mathematical calculations.
Function Name SalNumberAbs SalNumberArcCos SalNumberArcSin SalNumberArcTan SalNumberArcTan2 SalNumberCos SalNumberCosH SalNumberExponent SalNumberHigh Description Computes a number's absolute value. Computes a value's arccosine. Computes a value's arcsine. Computes a value's arctangent. Computes the arctangent of two values. Computes an angle's cosine. Computes an angle's hyperbolic cosine. Computes a value's exponential function. Returns a number's high-order word value (most significant 16 bits).
1-40
Function Name SalNumberHypot SalNumberLog SalNumberLogBase10 SalNumberLow SalNumberMax SalNumberMin SalNumberMod SalNumberPi SalNumberPower SalNumberRandInit SalNumberRandom SalNumberRound SalNumberSin SalNumberSinH SalNumberSqrt SalNumberTan SalNumberTanH SalNumberToChar SalNumberToHString SalNumberToStr and SalNumberToStrX SalNumberToWindowHandle SalNumberTruncate
Description Computes the length of the hypotenuse of a right triangle. Computes a number's natural logarithm. Computes a number's base-10 logarithm. Returns a number's low-order word value (least significant 16 bits). Returns the greater of two values. Returns the lesser of two values. Returns a number's modulo. Multiplies a number by Pi. Computes a number raised to the power of another number. Sets the starting point for generating a series of pseudorandom numbers. Generates a pseudorandom integer in the range 0 to 32767. Returns a rounded number. Computes an angle's sine. Computes an angle's hyperbolic sine. Computes a number's square root. Computes an angle's tangent. Computes an angle's hyperbolic tangent. Converts an ASCII numeric value to a character. Converts a number to a string handle. Convert a number to a string. Converts a number to a window handle. Truncates a number.
1-41
Chapter
Function Name VisNumberHighByte
Description Converts the specified number to a WORD and returns the high order 8 bits of the WORD. Converts the specified number to a WORD and returns the low order 8 bits of the WORD. Creates a double word value (DWORD) from two word values.
VisNumberLowByte
VisNumberMakeLong
See Also: Array Functions
Picture Functions
These functions manipulate the contents of a picture.
Function Name SalPicClear SalPicGetDescription SalPicGetString SalPicSet SalPicSetFile SalPicSetFit SalPicSetString VisMenuInsertPicture VisMenuSetPicture VisPicFree VisPicLoad VisTblSetRowPicture Description Clears the contents of a picture. Retrieves a description of a picture's contents. Copies the contents of a picture to a string. Inserts a resource into a picture. Sets the contents of a picture from a file. Sets the fit for a picture. Sets the contents of a picture from a string. Inserts a menu item into a menu and displays the specified picture with it. Displays a picture in a menu item. Frees a picture from memory. A picture is either a bitmap or an icon. Loads a picture into memory. Sets the picture for a bit flag of a table window.
1-42
Print Functions
These functions let you control printing.
Function Name SalPrtExtractRect SalPrtGetDefault SalPrtGetParmNum SalPrtPrintForm SalPrtSetDefault SalPrtSetParmDefaults SalPrtSetParmNum SalPrtSetup Description Extracts the printing rectangle from the SAM_Print message's lParam argument. Gets the default printer. Gets the value of a print parameter. Prints a window. Sets the default printer. Resets print parameters to their defaults. Sets the value of a print parameter. Displays the Printer Setup Dialog Box which lets the user alter the printer setup.
Report Functions
Centura lets you generate reports previously designed with ReportWindows. By using the ReportWindows functions listed in the following section, you can create, display, format, and print a report as well as get and set report variables.
Function Name SalReportClose SalReportCmd SalReportCreate SalReportDlgOptions SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetObjectVar SalReportGetStringVar SalReportPrint SalReportPrintToFile Description Closes a ReportWindows window. Sends a command to a report window. Creates a report. Sets the options for the report printing dialog box. Gets the value of a date/time report variable. Gets the value of a numeric report variable. Gets the value of an object report variable. Gets the value of a string report variable. Prints a report. Prints a report to a file.
1-43
Chapter
Function Name SalReportReset SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar SalReportSetStringVar SalReportTableCreate SalReportTablePrint SalReportTableView SalReportView
Description Updates the report preview with new data. Sets the value of a date/time report variable. Sets the value of a date/time report variable. Sets the value of an object report variable. Sets the value of a string report variable. Creates a report from the specified table window. Prints a report created from a table window. Displays, in preview mode, a report created from a table window. Displays a report in preview mode.
Scroll Bar Functions

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

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

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

These functions let you manipulate an application's windows.
Function Name SalAppDisable SalAppEnable SalAppFind Description Disables input to open windows. Enables input to open windows. Finds a visible top-level window for the application that you specify and returns its window handle. Brings a specified window to the top of all overlapping windows. Centers a window.
SalBringWindowToTop SalCenterWindow
1-51
Chapter
Function Name SalCreateWindow SalDestroyWindow SalDisableWindow SalDisableWindowAndLabel
Description Creates a window. Destroys a window. Disables mouse and keyboard input to a window. Disables mouse and keyboard input to a window, including disabling background text. Enables keyboard and mouse input to a window. Enables keyboard and mouse input to a window, including enabling background text. Gets information about a form window. Gets the handle of the default push button. Finds the first child of a window. Gets the object with the focus. Finds the next child of a window. Returns the type of the specified object. Retrieves a window's background text. Gets a window's current position on the X and Y axes. Gets the current window's size. Gets the current state of a window. Retrieves a window's text. Hides a window. Hides a window and its associated label. Causes a window to be repainted. Determines whether a radio button is set or a check box is checked. Specifies whether a window is enabled for mouse and keyboard input.
SalEnableWindow SalEnableWindowAndLabel SalFormGetParmNum SalGetDefButton SalGetFirstChild SalGetFocus SalGetNextChild SalGetType SalGetWindowLabelText SalGetWindowLoc SalGetWindowSize SalGetWindowState SalGetWindowText SalHideWindow SalHideWindowAndLabel SalInvalidateWindow SalIsButtonChecked SalIsWindowEnabled
1-52
Function Name SalIsWindowVisible SalMoveWindow
Description Specifies whether a window is visible. Moves a window a given number of form units on the X and Y axes relative to its current position. Returns the window handle of a parent or owner window. Returns the setting of the field edit flag for a data field, multiline field, table window column, or picture. Sets the default push button for a form window or dialog box. Sets or clears the field edit flag for a data field, multiline field, table window column, or picture. Sets the focus to a window. Sets a window's background text. Moves a window to a position on the X and Y axes. Resizes a window. Sets a window's text. Makes a window visible. Hides a window and its associated label. Gets the text displayed in a top-level window's status bar. Displays specified text in a top-level window's status bar. Shows or hides a top-level window's optional status bar. Shows or hides a top-level window's tool bar. Updates the client area of a window.
SalParentWindow SalQueryFieldEdit
SalSetDefButton SalSetFieldEdit
SalSetFocus SalSetWindowLabelText SalSetWindowLoc SalSetWindowSize SalSetWindowText SalShowWindow SalShowWindowAndLabel SalStatusGetText SalStatusSetText SalStatusSetVisible SalTBarSetVisible SalUpdateWindow
1-53
Chapter
Function Name SalWindowGetProperty
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. Converts a window handle to a number. Converts a window handle to a number. Enumerates the property list for a specified window. Retrieves a value from the property list of a specified window. Tests whether a specified window is a child or direct descendant of a parent window. Tests whether a specified window is maximized. Tests whether a specified window is minimized. Tests whether a specified window is neither maximized or minimized. Tests whether a specified window is valid. Sets an accelerator keystroke for a window. Moves and resizes a window, based on pixel coordinates. Removes a property list entry for a specified window. Sets flags for a specified window. Adds a new property list entry or changes an existing property list entry for a specified window. Adds a window style to a window. Changes the tab order of a control. Sets a window's visibility state.
SalWindowHandleToNumber SalWindowIsDerivedFromClass VisWinEnumProps VisWinGetProp VisWinIsChild VisWinIsMaximized VisWinIsMinimized VisWinIsRestored VisWinIsWindow VisWinLoadAccelerator VisWinMove VisWinRemoveProp VisWinSetFlags VisWinSetProp
VisWinSetStyle VisWinSetTabOrder VisWinShow
1-54
Chapter 2
Centura Builder Functions

This is an alphabetical list of the Centura Builder functions accompanied by detailed information about each functions purpose, its parameters and return value, and an example. Function descriptions include: Syntax Description Parameters Return value See Also Example
2-1
Chapter
SalAbort
Syntax Description bOk = SalAbort ( nExitCode ) Halts processing of the current menu action, message action, or application action. Use SalAbort when you want to terminate the current calling sequence without returning a status. For example, if your application is several layers into internal function calls and an error occurs, SalAbort terminates the current calling sequence of functions and leaves the application in the state it was prior to the first function call of that sequence. Parameters Return Value See Also Example nExitCode Receive Number. The status of the exit performed by SalAbort. Centura ignores this parameter as input.
bOk is TRUE if the function succeeds and FALSE if it fails. SalQuit

If NOT SqlConnect ( hSql ) Call SalAbort ( -1 )
SalAppDisable
Syntax Description bOk = SalAppDisable ( ) Disables input to all open applications. Use SalAppDisable and SalAppEnable when there are multiple applications running simultaneously and you want to control which application receives user input. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalAppEnable
Call SalAppDisable ( ) Call SalLoadAppAndWait ( 'Excel', '' ) Call SalAppEnable ( )
Parameters Return Value See Also Example
2-2
SalAppEnable
Syntax Description bOk = SalAppEnable ( ) Enables input to all open applications that were disabled by SalAppDisable. Use SalAppDisable and SalAppEnable when there are multiple applications running simultaneously and you want to control which application receives user input. No parameters. bOk is TRUE if the function succeeds and FALSE if you did not previously call SalAppDisable. SalAppDisable
Call SalAppDisable ( ) Call SalLoadAppAndWait ( 'Excel', '' ) Call SalAppEnable ( )
SalAppFind
Syntax Description hWnd = SalAppFind ( strAppName, bActivate ) Finds a visible top-level window for the application that you specify and returns its window handle. SalAppFind first looks for running instances of Centura applications and then for running instances of other Windows applications. If you specify the calling application's name in SalAppFind, Centura 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 Centura applications, specify the *.EXE name. For other Windows applications, specify the value given in the NAME statement in the applications *.DEF file. Boolean. If you set bActivate to TRUE, SalAppFind also activates the application's window.
bActivate
2-3
Chapter
Return Value Example
hWnd is the handle of the window.

On SAM_AppStartup If SalAppFind( 'INVOICE', TRUE ) != hWndNULL Call SalQuit( )
SalArrayAvg
Syntax Description Parameters Return Value See Also nAvg = SalArrayAvg ( nArrayNum ) Returns the average value of all the numbers in an array. nArrayNum Numeric Array. The name of an array of numbers.
nAvg is the average value in an array of numbers. SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Create Set dfAvg = SalArrayAvg( nArrayNum )
Example
SalArrayDimCount
Syntax Description Parameters bOk = SalArrayDimCount ( aArray, nDim ) Returns the number of dimensions in an array. aArray nDim Return Value See Also Array. The name of the array to query. Receive Number. Number of dimensions in the array.
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound
2-4
SalArraySum Example
On SAM_Create Set bOk = SalArrayDimCount (aArray, nDim) If nDim = 0 Set bDimTrue = False
SalArrayGetLowerBound
Syntax Description Parameters bOk = SalArrayGetLowerBound ( aArray, nDim, nBound ) Returns the lower bound of an array. aArray nDim nBound Return Value See Also Array. The name of the array to query. Number. Number of the dimension to query. The first dimension is one, the second is two, and so on. Receive Number. Lower bound value.
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayDimCount SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Click Set bOk = SalArrayGetLowerBound (aArray, nBound)
Example
SalArrayGetUpperBound
Syntax Description Parameters bOk = SalArrayGetUpperBound ( aArray, nDim, nBound ) Returns the upper bound of an array. aArray nDim nBound Return Value Array. The name of the array to query. Number. Number of the dimension to query. The first dimension is one, the second is two, and so on. Receive Number. Upper bound value.
bOk is TRUE if the function succeeds and FALSE if it fails.
2-5
Chapter
See Also
SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum

On SAM_Click Set bOk = SalArrayGetUpperBound (aArray, nBound)
Example
SalArrayIsEmpty
Syntax Description Parameters Return Value See Also bData = SalArrayIsEmpty ( aArray ) Determines if a dynamic array contains data. aArray Array. The name of the array to query.
bData is TRUE if the array contains no data and FALSE if it is has data. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Click If Not SalArrayIsEmpty (aArray) Call ...
Example
2-6
SalArrayMax
Syntax Description Parameters Return Value See Also nMax = SalArrayMax ( nArrayNum ) Returns the maximum value in an array of numbers. nArrayNum Numeric Array. The name of an array of numbers.
nMax is the maximum value in an array of numbers. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMin SalArraySetUpperBound SalArraySum
On SAM_Create Set dfMax = SalArrayMax( nArrayNum )
Example
SalArrayMin
Syntax Description nMin = SalArrayMin ( nArrayNum ) Returns the minimum value in an array of numbers. nArrayNum Return Value See Also Numeric Array. The name of an array of numbers.
nMin is the minimum value in an array of numbers. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArraySetUpperBound SalArraySum
On SAM_Create Set dfMin = SalArrayMin( nArrayNum )
Example
2-7
Chapter
SalArraySetUpperBound
Syntax Description bOk = SalArraySetUpperBound ( aArray, nDim, nBound ) Sets the upper bound of an array. When you call this function for a dimension other than the first, Centura must copy most of the array's data. There can be a performance cost when you call this function for any dimension but the first one. Parameters aArray nDim nBound Array. The name of the array to query. Number. Number of the dimension to query. The first dimension is one, the second is two, and so on. Number. Upper bound value. Specify -1 to reset a dynamic array to zero elements. Specify AC_Dynamic to change a static array to a dynamic array. (You can make only the first dimension of an array dynamic.)
Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySum
On SAM_Click Call SalArraySetUpperBound (aArray, 1, 5)
Example
SalArraySum
Syntax Description Parameters Return Value See Also nSum = SalArraySum ( nArrayNum ) Returns the sum of the elements in an array of numbers. nArrayNum Numeric Array. The name of an array of numbers.
nSum is the sum of the elements in an array of numbers. SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound
2-8
SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound Example

On SAM_Create Set dfSum = SalArraySum( nArrayNum )
SalBringWindowToTop
Syntax Description Parameters Return Value See Also Example bOk = SalBringWindowToTop ( hWndToExpose ) Brings a window to the top of all overlapping windows. hWndToExpose Window Handle. The handle (or name) of the window to bring to the top.
bOk is TRUE if the function succeeds and FALSE if it fails. SalHideWindow SalShowWindow
If ( hWndCustomer ) Call SalBringWindowToTop ( hWndCustomer )
SalCenterWindow
Syntax Description Parameters Return Value See Also Example bOk = SalCenterWindow ( hWndCenter ) Centers a window. If the window is a top-level window, Centura centers it on the desktop. If the window is a child window, Centura centers it on top of its parent. hWndCenter Window Handle. The handle (or name) of the window to center.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMoveWindow

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

If ( dfAge < 0 ) Call SalClearField ( dfAge )
SalColorFromRGB
Syntax Description Parameters nColor = SalColorFromRGB ( nRed, nGreen, nBlue ) Composes a color from red, green, and blue values. nRed nGreen nBlue Return Value See Also Number. A number from 0 to 255. Number. A number from 0 to 255. Number. A number from 0 to 255.
nColor is the color created. SalColorGet SalColorGetSysColor SalColorSet SalColorToRGB

Set nRed = 128 Set nGreen = 128 Set nBlue = 128 Set nColor = SalColorFromRGB ( nRed, nGreen, nBlue ) If NOT SalColorSet ( hWndItem, COLOR_IndexWindow, nColor ) ...
Example
2-10
SalColorGet
Syntax Description Parameters nColor = SalColorGet ( hWndColored, nColorIndex ) Gets a window's color. hWndColored nColorIndex Window Handle. The handle (or name) of the window whose color you want. Number. The color of a part of the window, represented by one of these constants: COLOR_IndexCellText COLOR_IndexTransparent COLOR_IndexWindow COLOR_IndexWindowText Return Value nColor is the color returned. It can be user-defined or one of the predefined window colors (excluding COLOR_Default and the three COLOR_Sys* constants). If you specify COLOR_IndexTransparent in the second parameter and the transparent color is not set, SalColorGet returns COLOR_None. See Also SalColorFromRGB SalColorGetSysColor SalColorSet SalColorToRGB
Set nColor = SalColorGet ( hWndItem, COLOR_IndexWindow ) If nColor = COLOR_Default Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Magenta )
Example
SalColorGetSysColor
Syntax Description Parameters nColor = SalColorGetSysColor ( nColorIndex ) Gets a system color. nColorIndex Number. The color of a part of the window, represented by one of these constants: COLOR_SysWindow COLOR_SysWindowFrame COLOR_SysWindowText
2-11
Chapter
nColor is the color returned. It can be one of the predefined windows colors (excluding COLOR_Default, COLOR_None, and the three COLOR_Sys* constants). SalColorFromRGB SalColorGet SalColorSet
SalColorToRGB Set nSysColorBckgrnd = SalColorGetSysColor ( COLOR_SysWindow )
Example
SalColorSet
Syntax Description Parameters bOk = SalColorSet ( hWndToSet, nColorIndex, nColor ) Sets a window's color. hWndToSet nColorIndex Window Handle. The handle (or name) of the window whose color you want to set. Number. The color of a part of the window, represented by one of these constants: COLOR_IndexCellText COLOR_IndexTransparent COLOR_IndexWindow COLOR_IndexWindowText 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.
nColor
bOk is TRUE if the function succeeds and FALSE if it fails. SalColorFromRGB SalColorGet SalColorGetSysColor SalColorToRGB
Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Red )
Example
2-12
SalColorToRGB
Syntax Description Parameters bOk = SalColorToRGB ( nColor, nRed, nGreen, nBlue ) Decomposes a color into red, green, and blue values. nColor Number. A user-defined value or any of the predefined window colors (excluding COLOR_Default, COLOR_None, and the three COLOR_Sys* constants). Receive number. A number from 0 to 255 that represents the red value. Receive number. A number from 0 to 255 that represents the green value. Receive number. A number from 0 to 255 that represents the blue value.
nRed nGreen nBlue Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalColorFromRGB SalColorGet SalColorGetSysColor SalColorSet
If NOT SalColorToRGB ( nColor, nRed, nGreen, nBlue ) ... Error ...
Example
SalCompileAndEvaluate
Syntax Description nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos, nReturn, strReturn, dtReturn, hWndReturn, bInhibitErrors, strContext ) Evaluates an expression and returns the expression's value in the receive parameter appropriate to its data type. SalCompileAndEvaluate lets you access the value of a variable whose name you do not specify until runtime. strExpression nError nErrorPos nReturn strReturn String. The expression to evaluate. Receive Number. The error number, if one is returned. Receive Number. The position in strExpression at which an error, if any, occurred. Receive Number. This parameter is set if strExpression evaluates to a number. Receive String. This parameter is set if strExpression evaluates to a string.
Parameters
2-13
Chapter
dtReturn hWndReturn bInhibitErrors
Receive Date/Time. This parameter is set if strExpression evaluates to a date/time value. Receive Window Handle. This parameter is set if strExpression evaluates to a handle. Boolean. If TRUE, Centura does not report compilation or evaluation errors to the user. Specify TRUE if the application processes its own errors. If FALSE, Centura reports compilation and evaluation errors to the user in a dialog box. String. The handle to an execution context, returned by either SalContextBreak or SalContextCurrent.
strContext Return Value
nType is equal to one of the following values if the function succeeds: EVAL_Date EVAL_Handle EVAL_If EVAL_Number EVAL_Set EVAL_String EVAL_Template
See Also Example
SalContextBreak SalContextCurrent
Set nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos,nReturn, strReturn, dtReturn, hWndReturn, FALSE, strContext ) If nType = EVAL_Number Call SalNumberToStr ( nReturn, 0, strString ) ...
SalContextBreak
Syntax Description Parameters Return Value See Also strContext = SalContextBreak ( ) Retrieves the context of the most recently executed Break statement. Use this function with SalCompileAndEvaluate. No parameters. strContext serves as the last parameter of the SalCompileAndEvaluate function. SalCompileAndEvaluate SalContextCurrent
2-14
Example
Set strContext = SalContextBreak ( )
SalContextCurrent
Syntax Description Parameters Return Value See Also Example strContext = SalContextCurrent ( ) Retrieves the current execution context. Use this function with SalCompileAndEvaluate. No parameters. strContext serves as the last parameter of the SalCompileAndEvaluate function. SalCompileAndEvaluate SalContextBreak
Set strContext = SalContextCurrent ( )
SalCreateWindow
Syntax Description hWndCreated = SalCreateWindow ( tWndToCreate, hWndOwner, Parm1, Parm2, ... ) Creates modeless dialog boxes, MDI windows, form windows, and top-level table windows at runtime. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters. If you specify an owner (hWndOwner), the new window always displays on top of its owner, closes when its owner closes, and hides when its owner is minimized. SalCreateWindow can pass data to and from the window being created by accepting a variable number of parameters. The data types of these parameters must match the parameter data types of the window being created. You define parameters for the window in the Window Parameters section of the application outline. 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. Parameters tWndToCreate Template or String. The name of the window to create.
2-15
Chapter
Note: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner Window Handle. The handle (or name) of the owner window. Specify hWndNULL if there is no owner window. Note that if you create a toplevel form inside of a MDI window, then that MDI window will always be the owner of this form. Any Centura data type. The (optional) first of a variable number of window parameters. Any Centura data type. The (optional) second of a variable number of window parameters.
Parm1 Parm2 Return Value See Also Example
hWndCreated is the handle of the new window. SalModalDialog SalDestroyWindow

On SAM_Click If NOT SalCreateWindow (frmCustomer, hWndNULL) ...Error...
SalCreateWindowExWithParms
Syntax Description hWndCreated = SalCreateWindowExWithParms( tWndToCreate, hWndOwner, nLeft, nTop, nWidth, nHeight, nFlags ... ) Creates a form, dialog box or table window as a child of another form or dialog box at runtime. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters. 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. SalCreateWindowExWithParms 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.
2-16
Call SalCreateWindowExWithParms ( frmMain, hWndNULL, nLeft, nTop,nWidth, nHeight, nGlobal, df1 )
You can use window parameters to return information from the window being created by using a receive type. However, you can initialize receive window parameters only with variables. This means that you cannot pass a data field or any other window object to a window parameter that was defined as a receive type. Parameters tWndToCreate Template or String. The name of the window to create. Note: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner Window Handle. The handle (or name) of the owner window. Specify hWndNULL if there is no owner window. Note that if you create a toplevel form inside of a MDI window, then that MDI window will always be the owner of this form. Position of the window in form units. Size of the window in form units. The following can be combined with the | operator: CREATE_AsChild Create the windows as a child hWndParent. HWndParent must be a form, dialog box or tool bar. CREATE_Border When used with CREATE_AsChild, the window will have a border. CREATE_Hidden The window will be created but not shown. Any Centura data type. The (optional) first of a variable number of window parameters. Any Centura data type. The (optional) second of a variable number of window parameters.
nLeft, nTop nWidth, nHeight nFlags
Parm1 Parm2 Return Value See Also Example
hWndCreated is the handle of the new window. SalModalDialog SalDestroyWindow

On SAM_Click If NOT SalCreateWindowExWithParms (frmCustomer, hWndNULL, nLeft, nTop, nWidth, nHeight) ...Error...
2-17
Chapter
SalCursorClear
Syntax Description Parameters bOk = SalCursorClear ( hWnd, nType ) Clears a window's cursor. hWnd nType Window Handle. The handle (or name) of a window. Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorSet SalCursorSetFile SalCursorSetString
On SAM_Click Call SalCursorClear (frmMain, Cursor_Windows)
Example
SalCursorSet
Syntax Description Parameters bOk = SalCursorSet ( hWnd, tResource, nType ) Sets a window's cursor. hWnd tResource Window Handle. The handle (or name) of a window. Template. An icon resource from the Resources section of the outline. Specify one of these system-supplied cursors: CURSOR_Arrow CURSOR_Cross CURSOR_IBeam CURSOR_Icon CURSOR_Size CURSOR_SizeNESW CURSOR_SizeNS CURSOR_SizeNWSE CURSOR_SizeWE CURSOR_UpArrow CURSOR_Wait
2-18
nType
Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window
bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorClear SalCursorSetFile SalCursorSetString
On SAM_Click Call SalCursorSet (frmMain, Cursor_Arrow, Cursor_Window)
Example
SalCursorSetFile
Syntax Description Parameters bOk = SalCursorSetFile ( hWnd, sFile, nType ) Sets an application-defined cursor for the specified window. Use this function to set the cursor from an image stored in a file. hWnd sFile nType Window Handle. The handle (or name) of a window. String. The name of a cursor or an icon file. Number. The cursor type. Specify one of these constants:
CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window
bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorClear SalCursorSet SalCursorSetString
On SAM_Click Call SalCursorSetFile (frmMain, file1.cne, Cursor_Window)
Example
SalCursorSetString
Syntax Description Parameters bOk = SalCursorSetString ( hWnd, sBuffer, nType ) Sets a window's cursor from a string variable. hWnd Window Handle. The handle (or name) of a window.
2-19
Chapter
sBuffer nType
String. The image of a cursor or an icon file. Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window
bOk is TRUE if the function succeeds and FALSE if it fails. SalCursorClear SalCursorSet SalCursorSetFile
On SAM_Click Call SalCursorSetString (frmMain, strCurBuf, Cursor_Window)
Example
SalDateConstruct
Syntax Description dtDate = SalDateConstruct ( nYear, nMonth, nDay, nHour, nMinute, nSecond ) Returns the date/time constructed from the parameters nYear, nMonth, nDay, nHour, nMinute, and nSecond. If you specify invalid parameter values, an unexpected date construction can result. Note: If any of the parameter values has less than the specified number of digits,
SalDateConstruct pads the resulting value with leading zeroes (0). For example, if nYear is 92, dtDate begins with 0092.
Parameters
nYear nMonth nDay nHour nMinute nSecond
Number. A number with a 4-digit year value. Number. A number with a 2-digit month value between 01 and 12 inclusive. Number. A number with a 2-digit day value between 01 and 31 inclusive. Number. A number with a 2-digit hour value between 0 and 23 inclusive. Number. A number with a 2-digit minute value between 01 and 59 inclusive. Number. A number with a 2-digit second value between 01 and 59 inclusive.
Return Value
dtDate is the newly constructed date/time value.
2-20
Example
On SAM_Create Set dtDeb = SalDateConstruct (1996, 1, 1, 10, 30, 1)
SalDateCurrent
Syntax Description dtNow = SalDateCurrent ( ) Returns the PC's current date/time. To get the database server's system date/ time, use a database system keyword (SYSDATE, SYSTIME, or SYSDATETIME ) in a SQL SELECT statement. Parameters Return Value Example No parameters. dtNow is the PC's current date/time.
On SAM_Create Set dfCurrent = SalDateCurrent ( )
SalDateDay
Syntax Description Parameters Return Value See Also nDay = SalDateDay ( dtDateTime ) Returns the day portion (1 to 31) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nDay is a number between 1 and 31. SalDateMonth SalDateYear
Example
Set nDay = SalDateDay ( dtDateTime )
SalDateHour
Syntax Description Parameters Return Value See Also nHour = SalDateHour ( dtDateTime ) Returns the hour portion (0 to 23) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nHour is a number between 0 and 23. SalDateMinute SalDateSecond
2-21
Chapter
Example
Set nHour= SalDateHour ( dtDateTime )
SalDateMinute
Syntax Description Parameters Return Value See Also nMinute = SalDateMinute ( dtDateTime ) Returns the minute portion (0 to 59) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nMinute is a number between 0 and 59. SalDateHour SalDateSecond
Example
Set nMinute = SalDateMinute ( dtDateTime )
SalDateMonth
Syntax Description Parameters Return Value nMonth = SalDateMonth ( dtDateTime ) Returns the month portion (1 to 12) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime Date/Time. A date/time value.
nMonth is a number between 1 and 12.
Related Functions SalDateDay SalDateYear Example

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

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

Set nSeconds = SalDateSecond ( dtDateTime )
SalDateToStr
Syntax Description Parameters nLength = SalDateToStr ( dtDateTime, strDate ) Converts a date/time value to a string value or returns -1 if you specify DATETIME_Null as a parameter. dtDateTime strDate Return Value See Also Example Date/Time. The date/time value to convert. Receive string. The resulting string value.
nLength is the length of strDate. SalFmtFormatDateTime SalStrToDate

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

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

Set nYear = SalDateYear ( dtDateTime )
SalDateYearBegin
Syntax Description Parameters Return Value See Also dtYearBegin = SalDateYearBegin ( dtDateTime ) Returns the date of the first day of the year or it returns DATETIME_Null if the value you specify is null. dtDateTime Date/Time. A date/time value.
dtYearBegin is the date of the first day of the year. SalDateMonthBegin SalDateQuarterBegin SalDateWeekBegin
2-25
Chapter
Example
Set dtYearBegin = SalDateYearBegin ( SalDateCurrent ( ) )
SalDDEAddAtom
Syntax Description nNewAtom = SalDDEAddAtom ( strStringToAdd ) Adds a string to the global atom table and creates a new atom to identify the string. If the string to add is already in the atom table, the atom reference count for that string increases by one. Call SalDDEGetAtomName to retrieve the string from the atom table. Parameters Return Value strStringToAdd String. The string (255 characters or less) to add to the global atom table.
If the function succeeds, nNewAtom is the value of the new global atom. If the string already exists, nNewAtom is the value of the existing atom. Otherwise, nNewAtom is zero (0). SalDDEDeleteAtom SalDDEFindAtom SalDDEGetAtomName
Set nOptions = SalDDEAlloc ( ) Call SalDDESetOptions ( nOptions, 0, CF_Text ) Set nItem = SalDDEAddAtom ( strItem ) Call SalDDEPost( hWndServer, WM_DDE_Advise, hWndForm, nOptions, nItem )
See Also
Example
SalDDEAlloc
Syntax Description nMemory = SalDDEAlloc ( ) Allocates a memory handle for: Parameters Return Value See Also Example Data in a WM_DDE_Data or WM_DDE_Poke message. Options in a WM_DDE_Advise message. Command string of a WM_DDE_Execute message.
No paameters. nMemory is a global memory handle. If the function fails, nMemory is zero (0). SalDDEFree
Set nOptions = SalDDEAlloc ( )
2-26
SalDDEDeleteAtom
Syntax Description nAtomCount = SalDDEDeleteAtom ( nAtomToDelete ) Decrements an atom's reference count. If the reference count reaches zero (0), Centura deletes both the atom and its associated string from the global atom table. When the application terminates, call this function for each successful SalDDEAddAtom call you made. Parameters Return Value See Also Example nAtomToDelete Number. The atom to delete.
If the function succeeds, nAtomCount is zero (0). If the function fails, nAtomCount is equal to nAtomToDelete. SalDDEAddAtom
Call SalDDEDeleteAtom ( nReceivedItem )
SalDDEExtract
Syntax Description Parameters bOk = SalDDEExtract ( nwParam, nlParam, hWndSender, nLowlParam, nHighlParam ) Extracts the sender's window handle and the data in the lParam parameter upon receipt of a Windows DDE message. nwParam nlParam hWndSender nLowlParam nHighlParam Return Value Example Number. The word parameter of the DDE message. Number. The long parameter of the DDE message. Receive Window Handle. The sender's window handle. Receive Number. The low-order word of lParam. Receive Number. The high-order word of lParam.
bOk is TRUE if the function succeeds and FALSE if it fails..

Call SalDDEExtract (wParam, lParam, hWndServer, nData,nReceivedItem)
SalDDEExtractCmd
Syntax Description Parameters bOk = SalDDEExtractCmd ( nCommand, strCommand, nCommandSize ) Extracts the command string referenced by the high-order word of the lParam of a WM_DDE_Execute message. nCommand Number. The memory handle for the command string.
2-27
Chapter
strCommand nCommandSize Return Value See Also Example
Receive String. The command string. Number. The maximum size of the command string.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDDESetCmd

If SalDDEExtractCmd ( nCommand, strCommand, nCommandSize ) Set fldData = strCommand
SalDDEExtractDataText
Syntax Description Parameters bOk = SalDDEExtractDataText ( nData, nStatus, strData, nDataSize ) Extracts the data referenced by the low-order word of the lParam in a WM_DDE_Data or WM_DDE_Poke message. nData nStatus Number. The handle of the memory object that contains the data and other information. Receive Number. The status word. See the DDE chapter in the Centura Developers Reference for more about the DDE_* status bits. Receive string. The data. Number. The size of the data buffer.
strData nDataSize Return Value See Also Example
bOk is TRUE if the function succeeds and FALSE if it fails. SalDDESetDataText

Call SalDDEExtractDataText ( nData, nStatus, strDDEData, DDE_Data )
SalDDEExtractOptions
Syntax Description bOk = SalDDEExtractOptions ( nOptions, nFlags, nFormat ) Extracts the sender's window handle and the data in the lParm parameter from a Windows DDE message. For more about DDE, see the DDE chapter in the Centura Developers Reference. Parameters nwParam nlParam hWndSender Number. The word parameter of the DDE message. Number. The long parameter of the DDE message. Receive WIndow handle. The sender's window handle.
2-28
nLowParam nHighParam Return Value Example None.
Receive Number. The low-order word of lParam. Receive Number. The high-order .word of lParam.
If NOT SalDDEExtractOptions ( nOptions, nFlags, nFormat) Call SalMessageBox ( 'Cannot extract option?', 'DDE Server', MB_Ok )
SalDDEFindAtom
Syntax Description Parameters Return Value See Also Example nAtom = SalDDEFindAtom ( strTopicString ) Searches the global atom table and returns the atom associated with the given string. strTopicString String. The string to search for.
nAtom is the global atom associated with strTopicString. nAtom is zero (0) if Centura does not find the string in the atom table. SalDDEGetAtomName
If nApplication = 0 Set nApplication = SalDDEAddAtom ( DDEServer_Application) Call SalMessageBox ( 'Add Application atom', 'DDE', MB_Ok)
SalDDEFree
Syntax Description nHandle = SalDDEFree ( nMemory ) Frees a memory handle allocated by SalDDEAlloc for: Data in a WM_DDE_Data or WM_DDE_Poke message. Options in a WM_DDE_Advise message. Command string of a WM_DDE_Execute message.
When the application terminates, call this function for each successful SalDDEAlloc call you made. Parameters Return Value See Also nMemory Number. The memory handle to free.
nHandle is zero (0) if the function succeeds, and is equal to the value of nMemory if the function fails. SalDDEAlloc
2-29
Chapter
Example
Call SalDDEDeleteAtom ( nReceivedItem ) If nStatus & DDE_fRelease Call SalDDEFree ( nData )
SalDDEGetAtomName
Syntax Description Parameters nAtomSize = SalDDEGetAtomName ( nAtom, strAtomName, nStringLength ) Returns the string associated with an atom. nAtom strAtomName nStringLength Return Value See Also Number. The atom number. Receive string. The string associated with nAtom. Number. Specify the maximum length of strAtomName.
nAtomSize is the length of the returned string if the function succeeds and zero (0) if there is no such atom. SalDDEAddAtom SalDDEDeleteAtom SalDDEFindAtom
Set nAtomSize = SalDDEGetAtomName ( nAtom, strAtomName, nStringLength )
Example
SalDDEGetExecuteString
Syntax Description strCommand = SalDDEGetExecuteString ( nMsglParam ) A server application calls this function to get the command string sent by a client. This function converts the lParam of the SAM_DDE_ClientExecute message from a numeric value to a string value and returns that string value in strCommand. nMsglParam Number. The lParam of the SAM_DDE_ClientExecute message that contains the command string.
Parameters Return Value Example
strCommand is the command string sent by a client application to the server.

Set strCommand = SalDDEGetExecuteString ( nMsglParam )
SalDDEPost
Syntax Description nReturn = SalDDEPost ( hWndReceiver, nMessage, hWndSender, nLowlParam, nHighlParam ) Posts all WM_DDE_* messages except: WM_DDE_Initiate
2-30
WM_DDE_Ack in response to a WM_DDE_Initiate
SalDDEPost places a message in the receiver's message queue, letting the receiver process messages already in its message queue first. SalDDEPost returns without waiting for the receiver to process the message. Parameters hWndReceiver nMessage hWndSender nLowlParam nHighlParam Return Value See Also Example Window Handle. The receiver's window handle. Number. The message number. Window Handle. The sender's window handle. Number. The low-order word of the lParam parameter sent with the message. Number. The high-order word of the lParam parameter sent with the message.
nReturn is a non-zero value if the function succeeds and zero (0) otherwise. SalDDESend SalDDESendAll
Call SalDDEPost ( hWndServer, WM_DDE_Execute,hWndForm, 0, nCommand)
SalDDERequest
Syntax Description Parameters bOk = SalDDERequest ( hWndClient, strService, strServerTopic, strServerItem, nTimeout, strData ) A client application calls this function to ask a server to send data. hWndClient strService strServerTopic strServerItem nTimeout strData Window Handle. The client's window handle associated with the DDE service, topic, and item. String. The DDE service name. String. The DDE topic name. String. The DDE item name. Number. The timeout value in milliseconds. Receive String. A string variable or a window in the client application that can receive data. The window must be able to hold a value (for example, a data field, table window column, multiline field, or combo box) and it must be defined with a data type of string.
Return Value
2-31
Chapter
Example
If NOT SalDDERequest ( frmMain, dfApplication2, dfTopic2, dfItem2, 10000, dfRequestData2 ) Call SalWaitCursor ( FALSE ) Call SalMessageBox ( 'SalDDERequest to Excel server failed', 'DDE Error', MB_Ok | MB_IconHand )
SalDDESend
Syntax Description nReturn = SalDDESend ( hWndReceiver, nMessage, hWndSender, nLowlParam, nHighlParam ) Sends a WM_DDE_Ack message in response to a WM_DDE_Initiate message. Unlike SalDDEPost, SalDDESend does not place the message in the receiver's message queue; instead, it does an immediate send of the message. SalDDESend does not return until the receiver has processed the message. hWndReceiver nMessage hWndSender nLowlParam nHighlParam Return Value See Also Example Window Handle. The receiver's window handle. Number. The message number. Window Handle. The sender's window handle. Number. The low-order word of the lParam parameter sent with the message. Number. The high-order word of the lParam parameter sent with the message.
Parameters
nReturn is the value returned from the receiver of the message. SalDDEPost SalDDESendAll
Call SalDDESend ( hWndClient, WM_DDE_Ack, hWndForm, nApplication, nTopic )
SalDDESendAll
Syntax Description Parameters nReturn = SalDDESendAll ( nMessage, hWndSender, nLowlParam, nHighlParam ) Broadcasts a WM_DDE_Initiate message and does not return until all receivers have processed the message. nMessage hWndSender nLowlParam Number. The message number. Window Handle. The sender's window handle. Number. The low-order word of the lParam parameter sent with the message.
2-32
nHighlParam Return Value See Also Example
Number. The high-order word of the lParam parameter sent with the message.
nReturn is a non-zero value if the function succeeds, and zero (0) otherwise. SalDDEPostSalDDESend
Call SalDDESendAll ( WM_DDE_Initiate, hWndForm, nApplication, nTopic )
SalDDESendExecute
Syntax Description Parameters bOk = SalDDESendExecute ( hWndClient, strService, strServerTopic, strServerItem, nTimeout, strCommand ) A client calls this function to send a WM_DDE_Execute command to a server. hWndClient strService strServerTopic strServerItem nTimeout strCommand Window Handle. The client's window handle associated with the DDE service, topic, and item. String. The DDE service. String. The DDE topic name. String. The DDE item name. Number. The timeout value in milliseconds. String. The command string to send to strService. For compatibility with other DDE applications, follow the syntax rules for command strings. For information about the syntax rules, see the section about the WM_DDE_Execute message at the end of the DDE chapter in the Centura Developers Reference. Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
If NOT SalDDESendExecute ( frmMain, dfApplication2, dfTopic2, dfItem2, 10000, strSend ) Call SalWaitCursor ( FALSE ) Call Sal Message Box ( 'SalDDESendExecute ' || 'to Excel server failed', 'DDE Error',
2-33
Chapter
SalDDESendToClient
Syntax Description Parameters bOk = SalDDESendToClient ( hWndServer, strData, nClientID, nTimeout ) A server application calls this function to send data to clients. Use SalDDESendToClient with both hot and cold link conversations. hWndServer strData nClientID Window Handle. The server's window handle associated with the DDE service, topic, and item. String. The data to send to clients. Number. The client's window handle converted to a number. For a hot link conversation, specify zero (0). Centura updates all hot-linked clients with the data in strData. For a cold link conversation, the server receives SAM_DDE_ClientRequest (in response to a client's SalDDERequest call). The SAM_DDE_ClientRequest wParam identifies the client to receive the data in strData. nTimeout Return Value Example Number. The timeout value in milliseconds.

If NOT SalDDESendToClient ( frmMain, dfServerData, 0, 100 ) Call SalWaitCursor ( FALSE )
SalDDESetCmd
Syntax Description Parameters bOk = SalDDESetCmd ( nHighlParam, strCommand ) Assigns a command string to the data referenced by the high-order word of the lParam in a WM_DDE_Execute message. nHighlParam strCommand Return Value See Also Example Number. The handle to the command block that contains the command string. String. The command to execute.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDDEExtractCmd

Call SalDDESetCmd ( nCommand, strCommand ) Call SalDDEPost ( hWndServer, WM_DDE_Execute, hWndForm, 0, nCommand )
2-34
SalDDESetDataText
Syntax Description Parameters bOk = SalDDESetDataText ( nData, nStatus, strData ) Assigns a value to the data referenced by the low-order word of the lParam in a WM_DDE_Data or WM_DDE_Poke message. nData nStatus strData Return Value See Also Example Number. The handle to the memory object that contains the data and other information. Number. The status word. See the DDE chapter in the Centura Developers Reference for more about the DDE_* status bits. String. The value to assign.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDDEExtractDataText

Call SalDDESetDataText ( nData, nDDEFlags, strData ) Call SalDDEPost ( hWndServer, WM_DDE_Poke, hWndForm, nData, nItem )
SalDDESetOptions
Syntax Description Parameters bOk = SalDDESetOptions ( nOptions, nFlags, nFormat ) Assigns a value to the data referenced by the low-order word of the lParam in a WM_DDE_Advise message. nOptions nFlags nFormat Return Value Example Number. The handle to the memory object that specifies how the data is to be sent. Number. The status word. See the DDE chapter in the Centura Developers Reference for more about the DDE_* status bits. Number. The CF_* data format.

Call SalDDESetOptions ( nOptions, 0, CF_Text ) Set nItem = SalDDEAddAtom ( strItem ) Call SalDDEPost ( hWndServer, WM_DDE_Advise, hWndForm, nOptions, nItem )
2-35
Chapter
SalDDEStartServer
Syntax Description bOk = SalDDEStartServer ( hWndServer, strService, strServerTopic, strServerItem ) A server application calls this function to signal clients that it is ready to accept connections from them. A server application must call this function before clients can connect to it. hWndServer strService strServerTopic strServerItem Return Value Example Window Handle. The server's window handle associated with the DDE application, topic, and item. String. The DDE service. String. The DDE topic name. String. The DDE item name.
Parameters

If NOT SalDDEStartServer ( frmMain, dfServerApplication, dfServerTopic, dfServer Item) Call SalWaitCursor ( FALSE )
SalDDEStartSession
Syntax Description Parameters bOk = SalDDEStartSession ( hWndDest, strService, strServerTopic, strServerItem, nTimeout ) A client calls this function to start a hot link conversation with a server application. hWndDest Window Handle. The handle (or name) of an object that can hold a value (such as a data field, table window column, multiline field, or combo box). If SalDDEStartSession succeeds, the server application updates the object associated with hWndDest with the value of strServerItem. A SAM_DDE_DataChange message is sent to hWndDest after the value of the object changes. strService strServerTopic strServerItem nTimeout Return Value String. The DDE service. String. The DDE topic name. String. The DDE item name. Number. The timeout value in milliseconds.
2-36
Example
If NOT SalDDEStartSession ( mlString1, dfApplication1, dfTopic1, dfItem1, 1000) Call SalWaitCursor ( FALSE ) Call SalMessageBox ( 'SalDDEStartSession with SW server failed','DDE Error', MB_Ok | MB_IconHand )
SalDDEStopServer
Syntax Description Parameters Return Value Example bOk = SalDDEStopServer ( hWndServer ) A server calls this function to end DDE server operations. The server must call SalDDEStopServer for each successful SalDDEStartServer. hWndServer Window Handle. The server's window handle associated with the DDE service, topic, and item.

If NOT SalDDEStopServer ( frmMain ) Call SalWaitCursor ( FALSE )
SalDDEStopSession
Syntax Description Parameters bOk = SalDDEStopSession ( hWndDest ) A client calls this function to end a hot link conversation with a server application. The client must call SalDDEStopSession for each successful SalDDEStartSession. hWndDest Window Handle. The handle (or name) of the object in the client application associated with the DDE service, topic, and item.

If NOT SalDDEStopSession ( mlString1 ) Call SalWaitCursor ( FALSE )
SalDestroyWindow
Syntax Description bOk = SalDestroyWindow ( hWndDestroy ) Destroys a form window, a top-level table window, or a modeless dialog box created with SalCreateWindow. In the case of a form window or top-level table window, you can have automatically created it at runtime. hWndDestroy Window Handle. The handle (or name) of the window to destroy.
Parameters
2-37
Chapter
bOk is TRUE if the function succeeds and FALSE if it fails. SalCreateWindow SalEndDialog
On SAM_Click Call SalDestroyWindow ( hWndForm )
SalDisableWindow
Syntax Description bOk = SalDisableWindow ( hWndDisable ) Disables keyboard and mouse input to a window. If the window contains text (for example, a push button), the text is grayed. If the window is a data field, it cannot receive the focus. Parameters Return Value See Also hWndDisable Window Handle. The handle (or name) of the window to disable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDisableWindowAndLabel SalEnableWindow SalIsWindowEnabled
On SAM_Create Call SalDisableWindow ( pbUpdate )
Example
SalDisableWindowAndLabel
Syntax Description bOk = SalDisableWindowAndLabel ( hWndDisable ) Disables keyboard and mouse input to a window and grays out its associated label. A label is the background text that immediately precedes the window in the outline. The bacground text must have a mneumonic. If the window contains text (for example, a push button), the text is grayed. If the window is a data field, it cannot receive the focus. Parameters Return Value See Also hWndDisable Window Handle. The handle (or name) of the window to disable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalDisableWindow SalEnableWindowAndLabel
2-38
SalIsWindowEnabled SalGetWindowLabelText SalHideWindowAndLabel SalSetWindowLabelText SalShowWindowAndLabel Example

Call SalDisableWindow ( dfName )
SalDlgChooseColor
Syntax Description bRet = SalDlgChooseColor ( hWndOwner, nColor ) Displays the Windows Color dialog box where the user can either select an existing color or create a new one. See the Control Panel chapter in the Microsoft Windows' User's Guide for a detailed description of the Color dialog box. Parameters hWndOwner nColor Return Value See Also Example Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. Receive Number. The RGB value of the color the user selects.
bRet is TRUE if the user selects a color and FALSE if the user clicks the Cancel push button. SalDlgChooseFont
On SAM_Click Call SalDlgChooseColor ( frmMain, nColor )
SalDlgChooseFont
Syntax Description bRet = SalDlgChooseFont ( hWndOwner, strFontName, nSize, nEnhancements, nColor ) Displays the Windows Font dialog box where the user can choose a font as well as its size, style, enhancements, display color, and so on. See the Control Panel chapter in the Microsoft Windows' User's Guide for a detailed description of the Font dialog box. Parameters hWndOwner strFontName Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. Receive String. The name of the font the user selects.
2-39
Chapter
nSize nEnhancements nColor
Receive Number. The size of the font the user selects. Receive Number. The font enhancements (italic, bold, and so on), if any, that the user selects. Receive Number. Specify the initial text color. When SalDlgChooseFont returns, nColor is the text color that the user selects.
bRet is TRUE if the user chooses a font and FALSE if the user clicks the Cancel push button. SalDlgChooseColor
Call SalDlgChooseFont ( frmMain, strFontName, nSize, nEnhancements )
SalDlgOpenFile
Syntax Description Parameters bRet = SalDlgOpenFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex, strFile, strPath ) Displays a Windows dialog box where the user can select a file to open. hWndOwner strDlgTitle strFilters Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. String. The title of the Open file dialog box. String. An array of file filters and their descriptions. Each filter must have a description that precedes the filter in the array. 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.
2-40
nIndex
Receive Number. The filter that the user chooses. For example, if the user chooses Initialization Files, nIndex is 3. The default filter is always the first filter in strFilters. Receive String. The file name the user chooses. To initialize the combo box in which the file names display, assign a file name to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, Centura ignores your attempt to set the default display value.
strFile
strPath
Receive String. The full path name of the file the user chooses. To initialize the combo box in which the paths display, assign a path to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, Centura ignores your attempt to set the default display value.
bRet is TRUE if the user specifies a file name and FALSE if the user clicks the Cancel push button. SalDlgSaveFile
Message Actions On SAM_Create Set strFilters[0] = 'Dynamic Link Libraries' Set strFilters[1] = '*.dll' Set strFilters[2] = 'Executable Files' Set strFilters[3] = '*.exe' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini' strFilters, 6, nIndex, strFile, strPath) Call SalDlgOpenFile ( frmMain, 'Open File', strFilters, 6, nIndex, strFile, strPath)
2-41
Chapter
SalDlgSaveFile
Syntax Description bRet = SalDlgSaveFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex, strFile, strPath ) Displays a Windows dialog box where the user can save a file. If you do not specify a file extension, Centura saves the file with the extension displayed by the Save File as Type combo box. Parameters hWndOwner strDlgTitle strFilters Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner. String. The title of the Save file dialog box. String. An array of file filters and their descriptions. Each filter must have a description that precedes the filter in the array. For example, to enable users to save files with only specific extensions, populate the strFilters array with filters such as:
Set strFilters[0] = 'Executable Files' Set strFilters[1] = '*.exe' Set strFilters[2] = 'Dynamic Link Libraries' Set strFilters[3] = '*.dll' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini'
nFilters
Number. The number of elements in strFilters. The above array of six elements contains three filters. Specify 6 to display all three filters. You can limit the number of filters that display. For example, to see only the first two filters (*.exe and *.dll), specify 4.
nIndex
Receive Number. The filter that the user chooses. This reflects the format in which Centura saves the file. A file's extension does not imply format. By default, if the user does not specify a file extension, Centura 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.
2-42
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, Centura 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, Centura ignores your attempt to set the default display value. Example
Message Actions On SAM_Create Set strFilters[0] = 'Dynamic Link Libraries' Set strFilters[1] = '*.dll' Set strFilters[2] = 'Executable Files' Set strFilters[3] = '*.exe' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini' On SAM_Click Call SalDlgSaveFile ( frmMain, 'Save File', strFilters, 6,nIndex, strFile, strPath )
SalDragDropDisableDrop
Syntax bOk = SalDragDropDisableDrop ( ) Disables dropping while in drag mode. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropEnableDrop
On SAM_Click Call SalDragDropDisableDrop ()
2-43
Chapter
SalDragDropEnableDrop
Syntax Description Parameters Return Value See Also Example bOk = SalDragDropEnableDrop ( ) Enables dropping while in drag mode. No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropDisableDrop
On SAM_Click Call SalDragDropEnableDrop ()
SalDragDropGetSource
Syntax Description Parameters bOk = SalDragDropGetSource ( hWndSource, nX, nY ) Retrieves the handle of the source window and the location of the mouse in that window when you initiated drag mode. hWndSource Receive Window Handle. The handle of the source window. These window types can be source windows: Combo box Multiline field Data field Picture List box Table window Receive Number. The position of the mouse on the X axis. Receive Number. The position of the mouse on the Y axis.
nX nY Return Value See Also Example
bOk is TRUE if the function succeeds and FALSE if it fails. SalDragDropGetTarget

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

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

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

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

Menu Actions Call SalEditCopyString ( mlNotes )
SalEditCopyTo
Syntax Description bOk = SalEditCopyTo ( ) Copies an object to a file from an editable picture. The picture must have the focus. This function only works when the picture's contents are the result of a Paste From operation. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCanCopyTo SalEditPasteFrom
Menu Actions Call SalEditCopyTo ( )
SalEditCut
Syntax Description Parameters bOk = SalEditCut ( ) Cuts selected data from a data field, multiline field, table window column, or picture and puts it on the Clipboard. No parameters.
2-51
Chapter
bOk is TRUE if the function succeeds and FALSE if it fails. SalEditCanCut

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

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

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

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

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

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

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

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

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

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

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

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

On SAM_FieldEdit Call SalFmtFieldToStr ( dfDateTime, dfDateString, TRUE )
SalFmtFormatDateTime
Syntax Description strDateTime = SalFmtFormatDateTime ( dtDateTime, strPicture ) Formats a date/time value using a given date/time picture format. If you do not specify a picture format or the one you specify is invalid, Centura uses the default settings in the [INTL] section and the user-defined [GTITOOLS] section of WIN.INI for formatting. dtDateTime strPicture Return Value See Also Example Date/Time. The date/time value to format. String. The date/time picture format.
Parameters
strDateTime is the formatted date/time string. SalFmtFormatNumber SalFmtIsValidPicture

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

Number Picture Displayed Value 7.00% 3.65e+03 3.65e03 $1,350 ($1,350) 95.00

0.00e+00 0.00e-00 $#,##0;($#,##0) $#,##0;($#,##0) 0.00
Parameters
strPicture nType
String. The picture string. Number. Specify whether the format is for a number or date/ time value with one of these constants: FMT_Pic_DateTime FMT_Pic_Number
bOk is TRUE if the picture format is valid and FALSE otherwise. SalFmtGetPicture SalFmtSetPicture
Example
Set strPicture = 'M/d/yy' Set bValid = SalFmtIsValidPicture ( strPicture, FMT_Pic_DateTime )
SalFmtKeepMask
Syntax Description bRet = SalFmtKeepMask ( bKeep ) By default, Centura 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, Centura does not copy the hyphen. You can call SalFmtKeepMask to change the default behavior so that Centura 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, Centura copies the hyphen.
2-70
The "^" character in an input mask overrides a setting that you make with this function. See the Formatting and Validating chapter in the Centura NTURA Technical Reference for more about input masks. Parameters bKeep Boolean. If FALSE (default), Centura removes input mask characters when you copy a value. If TRUE, Centura keeps the input mask characters when you copy a value. Return Value See Also bRet is the value you specified in bKeep. SalFmtGetInputMask SalFmtIsValidInputMask SalFmtSetInputMask SalFmtUnmaskInput
Set bRet = SalFmtKeepMask ( bKeep )
Example
SalFmtSetFormat
Syntax Description bOk = SalFmtSetFormat ( hWndField, nFormat ) Sets a data field's or table window column's format. A field's country profile determines a format's characteristics. If the field uses the default format, the profile in WIN.INI determines a format's characteristics. A field's format must agree with the field's data type, so for example, number fields can only be formatted as decimal, percentage, or currency values. Parameters hWndField nFormat Return Value See Also Example Window Handle. The handle (or name) of the data field or table window column whose format you want to set. Number. The format for hWndField.
bOk is TRUE if the function succeeds and FALSE if the format cannot be set such as when the format is not appropriate for the specified field. SalFmtGetFormat
Set bOk = SalFmtSetFormat ( hWndField, nFormat )
2-71
Chapter
SalFmtSetInputMask
Syntax Description bOk = SalFmtSetInputMask ( hWnd, strMask ) Sets the input mask of a data field or table window column. See the Formatting and Validating chapter in the Centura Technical Reference for more about input masks. Parameters hWnd strMask Return Value See Also Window Handle. The handle (or name) of a combo box, data field, or table window column. String. The string that holds the input mask. If strMask is an empty string (''), Centura sets hWnd to be unformatted.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtUnmaskInput
Set bOk = SalFmtSetInputMask ( hWnd, strMask )
Example
SalFmtSetPicture
Syntax Description Parameters bOk = SalFmtSetPicture ( hWndField, strPicture ) Sets the picture format of a data field or table window column. hWndField strPicture Return Value Window Handle. The handle (or name) of the data field or table window column whose picture format you want to set. String. The picture format.
bOk is TRUE if the function succeeds and FALSE if it fails. bOk is FALSE if any of the following are true: The window handle is not valid. The field/column is not of date/time or number data type. The picture format is not valid.
See Also Example
SalFmtGetPicture
Set bOk = SalFmtSetPicture ( hWndField, strPicture )
2-72
SalFmtStrToField
Syntax Description Parameters bOk = SalFmtStrToField ( hWndField, strValue, bFormat ) Copies a string to a data field or table window column. After copying the string to the field, Centura formats the string. hWndField strValue bFormat Return Value See Also Example Window Handle. The handle (or name) of the data field or table window column to which the string is assigned. String. The string to copy. Boolean. Specify whether (TRUE) or not (FALSE) the string value has the same format as the field.
bOk is TRUE if the string's value has the same format as the data field or table window column. bOk is FALSE if the string's value is unformatted. SalFmtFieldToStr
Message Actions On SAM_FieldEdit Call SalFmtStrToField ( dfDateTime, dfDateString, TRUE )
SalFmtUnmaskInput
Syntax Description bOk = SalFmtUnmaskInput ( hWnd, strInput ) Unmasks the contents of a data field or table window column and puts the result in a string. Unmasking involves taking control characters out of a string, but does not include converting characters from lowercase to uppercase and vice versa. See the Formatting and Validating chapter in the Centura Technical Reference for more about input masks. Parameters hWnd strInput Return Value See Also Window Handle. The handle (or name) of a combo box, data field, or table window column. Receive String. The unmasked contents of hWnd.
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle or the object does not have an input mask. SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask
2-73
Chapter
Example
Set bOk = SalFmtUnmaskInput ( hWnd, strInput )
SalFmtValidateField
Syntax Description bOk = SalFmtValidateField ( hWndField, nValidate ) Validates and formats a data field's or table window column's contents. Centura strips off formatting characters and validates a field's contents according to type. After that, Centura 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 Centura to validate the field successfully. Parameters hWndField nValidate Return Value Example Window Handle. The handle (or name) of the data field or table window column to validate and format. Number. A constant value that indicates what Centura does if a format error occurs and the function returns FALSE:
bOk is TRUE if the function succeeds and FALSE otherwise, such as when the input is invalid. If bOk is FALSE, Centura optionally displays an error dialog box.
If SalFmtIsValidField ( dfDateTime ) Call SalFmtValidateField ( dfDateTime, FMT_Validate_None ) Return VALIDATE_Ok
SalFontGet
Syntax Description Parameters bOk = SalFontGet ( hWndFont, strName, nSize, nEnhancement ) Gets a window's font name, size, and enhancements. hWndFont strName nSize nEnhancment Return Value See Also Window Handle. The handle (or name) of the window whose font information you want. Receive String. The name of the font. Receive Number. The size of the font. Receive Number. The font enhancements. To combine two or more of the FONT_Enh* constants, use the OR (|) operator.
bOk is TRUE if the function succeeds and FALSE if it fails. SalFontGetNames SalFontGetSizes SalFontSet
2-74
Example
If NOT SalFontGet ( hWndField, strFont, nSize, nEnhancement ) ... Error ...
SalFontGetNames
Syntax Description Parameters nNames = SalFontGetNames ( nGet, strArrayFontNames ) Gets the names of the screen or printer fonts. nGet strArrayFontNames Return Value See Also Number. A constant that specifies whether to get the screen or printer fonts: Receive String Array. The name of an array of strings that contains the font names returned.
nNames is the number of font names returned. SalFontGet SalFontGetSizes SalFontSet

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

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

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

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

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

Call SalGetWindowSize ( pbExample, nWidth, nHeight ) Call SalSetWindowSize ( pbExample, nWidth+1, nHeight+1 )
SalGetWindowState
Syntax Description Parameters nState = SalGetWindowState ( hWnd ) Returns a window's current state. hWnd Window Handle. The handle (or name) of a window. This function fails if you specify a window name that has not been created.
nState is a constant that indicates a window's current state. It is equal to one of a predefined set of values.
On SAM_Click If SalGetWindowState ( fwDataWindow ) != Window_Normal
SalGetWindowText
Syntax Description nLength = SalGetWindowText ( hWnd, strText, nMaxLen ) Retrieves the text of a window. Window text is the title of a form window, dialog box, table window, radio button, check box, background text, or push button. For a data field, multiline text field, or table window column, window text is the field value in string form, regardless of the object's data type.
2-84
Note: Use SalTblGetColumnTitle to get the title of a table window column. Parameters hWnd strText nMaxLen Return Value See Also Example Window Handle. The handle (or name) of a window. Receive String. The window text. Number. The maximum length of the window text.
nLength is a number that indicates the length of strText. nLength is zero (0) if the window has no text. SalSetWindowText SalTblGetColumnTitle
Call SalGetWindowText ( hWndForm, strfrmTitle, 50 )
SalHideWindow
Syntax Description bOk = SalHideWindow ( hWndToHide ) Hides a window. This function does not destroy the window; it only makes the window invisible. Parameters Return Value See Also Example hWndToHide Window Handle. The handle (or name) of a window to hide.
bOk is TRUE if the function succeeds and FALSE if it fails. SalBringWindowToTop SalShowWindow
Call SalHideWindow ( hWndChild )
SalHideWindowAndLabel
Syntax Description bOk = SalHideWindowAndLabel ( hWndToHide ) Hides a window and its associated label. A label is the background text that immediately precedes the window in the outline. This function does not destroy the window; it only makes the window invisible. Parameters Return Value hWndToHide Window Handle. The handle (or name) of a window to hide.
bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible.
2-85
Chapter
See Also
SalBringWindowToTop SalHideWindow SalShowWindowAndLabel

Set bOk = SalHideWindowAndLabel ( hWndToHide )
Example
SalHStringToNumber
Syntax Description nHString = SalHStringToNumber ( strString ) Converts a string handle to a number so you can pass it as a message parameter. Note: You must pass a string handle as the lParam parameter because the value is too large to
fit in the wParam.
strString
String. The string whose handle you want to change to a number.
nHString is a number that represents the converted string handle. SalNumberToHString

Set nHString = SalHStringToNumber ( strString )
SalInvalidateWindow
Syntax Description Parameters Return Value See Also Example bOk = SalInvalidateWindow ( hWndToPaint ) Causes a window to be repainted. hWndToPaint Window Handle. The handle (or name) of a window to repaint.
bOk is TRUE if the function succeeds and FALSE if it fails. SalUpdateWindow

Set bOk = SalInvalidateWindow ( hWndToPaint )
SalIsButtonChecked
Syntax Description Parameters Return Value bIsSet = SalIsButtonChecked ( hWnd ) Determines whether a radio button is set or a check box is checked. hWnd Window Handle. The handle (or name) of a radio button or check box.
bIsSet is TRUE if hWnd is set or checked and FALSE otherwise.
2-86
Example
Set bIsSet = SalIsButtonChecked ( hWnd )
SalIsNull
Syntax Description Parameters Return Value See Also Example bNull = SalIsNull ( hWndIsNull ) Verifies whether a data field, multiline text field, or table window column is null or empty. hWndIsNull Window Handle. The handle (or name) of a data field, multiline text field, or table window column.
bNull is TRUE if hWndIsNull is null or empty, and FALSE otherwise. SalClearField

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

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

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

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

Call SalListSetMultiSelect ( lbExample, 5, TRUE )
SalListSetSelect
Syntax Description bOk = SalListSetSelect ( hWndList, nIndex ) Selects or deselects a combo box or single-selection list box entry. Specify single- or multiple-selection in the list box's customizer. Parameters hWndList nIndex Return Value Example Window Handle. The handle (or name) of a combo box or single-selection list box. Number. The index of the entry to select. If you specify -1, Centura deselects the entry.
bOk is TRUE if the function succeeds and FALSE if it fails. bOk is equal to LB_Err if an error occurs.
Call SalListSetSelect ( hWndLB, 0 )
SalListSetTabs
Syntax Description bOk = SalListSetTabs ( hWndList, nArrayTabStops ) Sets tabs in a list box. List boxes use tabs to align columns of data. You need to set tabs when you are using a proportional font. SalListPopulate overrides any settings made with SalListSetTabs. hWndList nArrayTabStops Return Value Example Window Handle. The handle (or name) of a list box. Numeric Array. The name of an array of numbers that represent tabs. Specify tabs in inches.
Parameters

On SAM_Create Set nTabStops[0] = 2 Set nTabStops[1] = 3 Call SalListSetTabs ( hWndItem, nTabStops )
2-98
Call SalListAdd ( hWndItem, 'aaa'||TAB||'aaaa'||TAB||'aaaaa' )
SalLoadApp
Syntax Description Parameters bOk = SalLoadApp ( strAppName, strParameters ) Starts an application. strAppName strParameters String. The name of the application to start. String. Optional command line arguments.
See the SAL (Centura Application Language) chapter of the Centura Developer's Reference for detailed information about command line arguments. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if Centura cannot find the application or cannot start it. SalLoadAppAndWait
On SAM_AppStartup Call SalLoadApp ( 'DBWINDOW.EXE','' )
SalLoadAppAndWait
Syntax Description Parameters bOk = SalLoadAppAndWait ( strAppName, nMode, nRet ) Starts an application, then waits for it to exit before returning control to the original application. strAppName String. The name of the application to start, separated from command line arguments with a space. See the SAL chapter in the Centura Developers Reference for information about command line arguments. nMode Number. The show mode. Specify any of these Window_* constants:
Window_Maximized Window_Minimized Window_Normal 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
2-99
Chapter
execution. If bOk is TRUE, but the invoked application exits before entering a message loop, its exit status is not available to Centura. 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. In Windows 3.1, this value is less than 32: 0 2 3 5 6 8 10 11 12 13 14 15 16 19 20 21 Return Value See Also Example Out of memory, executable file was corrupt, or invalid relocations File not found Path not found Attempt to dynamically link to a task, or there was a sharing or network protection violation Library requires separate data segments for each task Insufficient memory to start application Incorrect Windows version Invalid .EXE file (non-Windows .EXE or error in .EXE image) Application designed for different operating system DOS 4.0 application Unknown .EXE type Attempt to load real-mode application developed for an earlier version of Windows Attempt to load a second instance of an .EXE containing multiple, writeable data segments Attempt to load a compressed executable file. The file must be decompressed before it can be loaded. A DLL required to run this application was corrupt. Application requires Microsoft Windows 32-bit extensions
bOk is TRUE if the function succeeds and FALSE if Centura cannot find the application or cannot start it. SalLoadApp
On SAM_AppStartup Call SalLoadAppAndWait (DBWindow.EXE, WINDOW_NORMAL, NRECUSTATUS)
2-100 Centura Builder Function Reference
SalMapEnterToTab
Syntax Description bOk = SalMapEnterToTab ( bState ) This function changes the behavior of the Enter key from executing the default button on a window to moving the focus to the next field. This function takes one parameter (TRUE or FALSE) to enable or disable this action. bState Boolean. If TRUE, the Enter key shifts the focus to the next editable object. If FALSE (default), the Enter key executes the default push button on the form window or dialog box. Return Value Example bOk is TRUE if the function succeeds and FALSE if you do not specify a Boolean value.
Set bOk = SalMapEnterToTab ( bState )
Parameters
SalMDIArrangeIcons
Syntax Description Parameters Return Value See Also Example bOk = SalMDIArrangeIcons ( hWndMDI ) Arranges minimized child window icons in an MDI window. hWndMDI Window Handle. The handle of an MDI window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMDICascade SalMDITile
Menu Actions Call SalMDIArrangeIcons ( hWndMDI )
SalMDICascade
Syntax Description Parameters Return Value See Also bOk = SalMDICascade ( hWndMDI ) Cascades all non-iconized child windows of an MDI window. hWndMDI Window Handle. The handle of an MDI window.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMDIArrangeIcons SalMDITile
2-101
Chapter
Example
Menu Actions Call SalMDICascade ( hWndMDI )
SalMDITile
Syntax Description Parameters bOk = SalMDITile ( hWndMDI, bPosition ) Tiles all non-iconized child windows of an MDI window. Windows that are not sizable will not be tiled. hWndMDI bPosition Return Value See Also Example Window Handle. The handle of an MDI window. Boolean. How to tile the child windows. If TRUE, tile the windows vertically; if FALSE, tile the windows horizontally.
bOk is TRUE if the function succeeds and FALSE if it fails. SalMDIArrangeIcons SalMDICascade
Menu Actions Call SalMDITile ( hWndMDI, FALSE )
SalMessageBeep
Syntax Description bOk = SalMessageBeep ( nAlertLevel ) Plays a waveform sound that corresponds to a given system alert level defined in the [sounds] section of WIN.INI. A user can set the sound for each alert level with the sounds application in the Control Panel. nAlertLevel Number. The alert level: 0xFFFFFFFF (-1)Standard beep using the computer speaker. MB_IconAsterisk MB_IconExclamation MB_IconStop MB_IconQuestion MB_Ok Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalMessageBox
Call SalMessageBeep ( -1 )
Parameters
SalMessageBox
Syntax Description nResult = SalMessageBox ( strText, strTitle, nFlags ) Displays a message box and returns a number that indicates the user's response. You can customize the message box push buttons and icons. The active parent window, whose value is hWndForm, creates the message box. Parameters strText strTitle nFlags String. The message text. You can enter multiple lines of text by pressing CTRL-ENTER to start a new line. String. The message box title. Number. The message box style. Create a style by combining style option constants using the OR (|) operator. You can combine at most one constant from each component. 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 2-103
Chapter
MB_DefButton2 MB_DefButton3 MB_NoFocus System Style Constants MB_ApplModal (default) MB_SystemModal Return Value See Also Example nResult is the value of the push button the user clicks. SalMessageBeep
Set nResult = SalMessageBox ( strText, strTitle, nFlags )
SalModalDialog
Syntax Description nReturn = SalModalDialog ( tDlgBoxToCreate, hWndOwner, Parm1, Parm2, ...) Creates a modal dialog box. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters. You cannot use receive window parameters as receive function arguments. You can use a temporary variable as the function argument and then assign the temporary variable to the receive function parameter. A modal dialog box disables its owner window. A system modal dialog box disables the entire Windows system. SalEndDialog destroys the modal dialog box and enables all windows that were disabled. SalModalDialog can pass information to the dialog box by accepting a variable number of parameters. The data types of these parameters must match the parameter data types of the dialog box being created. You define parameters for the dialog box in the Window Parameters section of the application outline. You can use window parameters to return information from the window being created by using a receive type. However, you can initialize receive window parameters only with variables. This means that you cannot pass a data field or any other window object to a window parameter that was defined as a receive type. Parameters tDlgBoxToCreate Template or String. The name of the modal dialog box to create. NOTE: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner Parm1 Parm2 Return Value See Also Example Window Handle. The handle (or name) of the owner window. Use hWndNULL for a dialog box that does not have an owner. Any Centura data type. The (optional) first of a variable number of window parameters. Any Centura data type. The (optional) second of a variable number of window parameters.
nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created. SalEndDialog SalModalDialogFromStr
Call SalModalDialog ( dlgAboutBox, hWndForm )
2-105
Chapter
SalModalDialogFromStr
Syntax Description nReturn = SalModalDialogFromStr ( tDlgBoxToCreate, hWndOwner, Parm1, Parm2, ... ) Creates a modal dialog box. This function is useful with internal functions that expect to receive a dialog box name in a string parameter. A modal dialog box disables its owner window. A system modal dialog box disables the entire Windows system. SalEndDialog destroys a modal dialog box and enables all windows that were disabled. Parameters strName hWndOwner Parm1 Parm2 Return Value See Also Example String. The name of the modal dialog box to create. Window Handle. The handle (or name) of the owner window. Use hWndNUL for dialog boxes that do not have owners. Any Centura data type. The (optional) first of a variable number of window parameters. Any Centura data type. The (optional) second of a variable number of window parameters.
nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created. SalModalDialog
Set nReturn = SalModalDialogFromStr ( tDlgBoxToCreate, hWndOwner )
SalMoveWindow
Syntax Description Parameters bOk = SalMoveWindow ( hWndToMove, nXOffset, nYOffset ) Moves a window a given number of form units on the X and Y axes relative to its current position. hWndToMove nXOffset nYOffset Return Value See Also Example Window Handle. The handle (or name) of the window to move. Number. The number of form units to move the window on the X axis. Number. The number of form units to move the window on the Y axis.
bOk is TRUE if the function succeeds, and FALSE if hWndToMove is invalid. SalCenterWindow
Call SalMoveWindow ( pbExample, 1,1 )
SalNumberAbs
Syntax Description Parameters Return Value Example nNum = SalNumberAbs ( nValue ) Computes a number's absolute value. nValue Number. The number whose absolute value you want.
nNum is the absolute value of nValue.

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

On SAM_Click Set nNum1 = SalNumberArcTan ( 1 )
SalNumberArcTan2
Syntax Description Parameters nArcTan2 = SalNumberArcTan2 ( nValueY, nValueX ) Computes the arctangent of two values. This function uses the signs of both parameters to determine the quadrant of the return value. nValueY nValueX Return Value See Also Example Number. One of two values whose arctangent you want. Number. The other of two values whose arctangent you want.
nArcTan2 is the arctangent of nValueY and nValueX. nArcTan2 is in the range -1/2 to 1/2. SalNumberArcTan
On SAM_Click Set nNum1 = SalNumberArcTan2 ( 1, 0 )
SalNumberCos
Syntax Description Parameters Return Value nCos = SalNumberCos ( nAngle ) Computes an angle's cosine. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose cosine you want.
nCos is the cosine of nAngle. If the angle is large, nCos can reflect a partial loss of significance. If the angle is so large that significance is totally lost, SalNumberCos returns zero (0). SalNumberCosH
On SAM_Click Set nNum1 = SalNumberCos ( 0 )
See Also Example
SalNumberCosH
Syntax Description Parameters Return Value See Also Example nCosH = SalNumberCosH ( nAngle ) Computes an angle's hyperbolic cosine. You must specify the angle in terms of radians. nAngle Number. The value of the angle whose hyperbolic cosine you want.
nCosH is the hyperbolic cosine of nAngle. If the return value is too large, nCosH equals zero (0). SalNumberCos
On SAM_Click Set nNum1 = SalNumberCosH ( 0 )
SalNumberExponent
Syntax Description Parameters Return Value Example nNumExp = SalNumberExponent ( nValue ) Computes a value's exponential function. nValue Number. The value whose exponential function you want.
nNumExp is the result of 'e' to the power of nValue. When there is an underflow or overflow, nNumExp is equal to zero (0).
On SAM_Click Set nNumExp = SalNumberExponent ( 2.302585093 )
SalNumberHigh
Syntax Description Parameters Return Value See Also Example nHi = SalNumberHigh ( nValue ) Returns a number's high-order word value (most significant 16 bits). nValue Number. The number whose high-order word value you want. Centura treats nValue as an unsigned 32-bit number.
nHi is the high-order word value of nValue. SalNumberLow

On SAM_Click Set nHi = SalNumberHigh ( 0xffffaaaa )
2-109
Chapter
SalNumberHypot
Syntax Description Parameters nHypotenuse = SalNumberHypot ( nX, nY ) Computes the length of the hypotenuse of a right triangle, given the lengths of the other two sides. nX nY Return Value Example Number. The length of one side of a right triangle. Number. The length of another side of a right triangle.
nHypotenuse is the length of the hypotenuse of a right triangle. If the computation of the hypotenuse results in an overflow, nHypotenuse is equal to zero (0).
On SAM_Click Set nHypotenuse = SalNumberHypot ( 3, 4 )
SalNumberLog
Syntax Description Parameters Return Value See Also Example nLog = SalNumberLog ( nValue ) Computes a number's natural logarithm. nValue Number. The number whose natural logarithm you want.
nLog is the natural logarithm of nValue. If nValue is negative or 0, nLog is equal to zero (0). SalNumberLogBase10
On SAM_Click Set nLog = SalNumberLog ( 1000 )
SalNumberLogBase10
Syntax Description Parameters Return Value See Also Example nLogBase10 = SalNumberLogBase10 ( nValue ) Computes a number's base -10 logarithm. nValue Number. The number whose base -10 logarithm you want.
nLogBase10 is the base-10 logarithm of nValue. If nValue is negative or 0, nLogBase10 is equal to zero (0). SalNumberLog
On SAM_Click Set nLogBase10 = SalNumberLogBase10 ( 1000 )
SalNumberLow
Syntax Description Parameters Return Value See Also Example nLo = SalNumberLow ( nValue ) Returns a number's low-order word value (least significant 16 bits). nValue Number. The number whose low-order word value you want. Centura treats nValue as an unsigned 32-bit number.
nLo is the low-order word value of nValue. SalNumberHigh

On SAM_Click Set nLo = SalNumberLow ( 0xffffaaaa )
SalNumberMax
Syntax Description Parameters nNumMax = SalNumberMax ( nVal1, nVal2 ) Returns the greater of two values. nVal1 nVal2 Return Value See Also Example Number. The first of two values. Number. The second of two values.
nNumMax is the greater of nVal1 and nVal2. SalNumberMin

On SAM_Click Set nNumMax = SalNumberMax ( 1765.2, -2 )
SalNumberMin
Syntax Description Parameters nNumMin = SalNumberMin ( nVal1, nVal2 ) Returns the lesser of two values. nVal1 nVal2 Return Value See Also Example Number. The first value. Number. The second value.
nNumMin is the lesser of nVal1 and nVal2. SalNumberMax

On SAM_Click Set nNumMin = SalNumberMin ( 1765.2, -2 )
2-111
Chapter
SalNumberMod
Syntax Description Parameter nNumber nNumberMod Return Value Example Number. The number to divide. Number. The number by which to divide nNumber. nModulo = SalNumberMod ( nNumber, nNumberMod ) Returns a number's modulo. This function divides nNumber by nNumberMod and returns the remainder.
nModulo is the remainder of nNumber divided by nNumberMod.

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

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

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

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

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

On SAM_Click Set strString = SalNumberToHString ( lParam ) Set nBuffLen = SalStrGetBufferLength (strString)
SalNumberToStr
Syntax Description Parameters nLength = SalNumberToStr ( nNumber, nDecimalPlaces, strString ) Converts a number to a string. nNumber nDecimalPlaces strString Return Value Number. The number to convert. Number. The number of decimal places you want in strString. Receive String. The string converted from nNumber.
nLength is the length of strString, including the decimal point. strString is the string converted from nNumber.
See Also Example
SalNumberToStrX SalStrToNumber
On SAM_Click Set nLength = SalNumberToStr ( 124.5, 1, strString )
SalNumberToStrX
Syntax Description Parameters strString = SalNumberToStrX ( nNumber, nDecimalPlaces) Converts a number to a string. nNumber nDecimalPlaces strString Return Value Number. The number to convert. Number. The number of decimal places you want in strString. Receive String. The string converted from nNumber.
nLength is the length of strString, including the decimal point. strString is the string converted from nNumber.
See Also Example
SalNumberToStr SalStrToNumber
On SAM_Click Set df2 = SalNumberToStrX ( df1, 2 )
SalNumberToWindowHandle
Syntax Description hWnd = SalNumberToWindowHandle ( nWnd ) Converts a number to a window handle. For example, you can broadcast a message by passing -1 to SalSendMsg as follows:
Set hWndAll = SalNumberToWindowHandle ( -1 ) Call SalSendMsg ( hWndAll, nMsg, 0, 0 )
nWnd
Number. The number to convert.
hWnd is the window handle converted from nWnd. SalWindowHandleToNumber

Set hWndtblCustomer = SalNumberToWindowHandle (lParam )
2-117
Chapter
SalNumberTruncate
Syntax Description Parameters nResult = SalNumberTruncate ( nNumber, nPrecision, nScale ) Truncates a number. nNumber nPrecision nScale Number. The number to truncate, starting with the leftmost. Number. The number of digits to display, starting with the leftmost. Number. The number of digits to the right of the decimal point. The nPrecision parameter must be large enough to hold the number of digits that you specify in this parameter.
nResult is the result of truncating nNumber.

On SAM_Click Set nNum = SalNumberTruncate( 10.0625, 4, 4 )
SalParentWindow
Syntax Description hWndParent = SalParentWindow ( hWnd ) Returns the handle of an objects parent window. The following table shows the SalParentWindow behavior with tool bars and MDI windows:
Where called Tool bar child in a top-level object. Tool bar child in an MDI window. Child table window in a tool bar. Parameter hWndItem hWndItem hWndForm Return Handle of the top-level object that contains it (hWndForm). Handle of the MDI window that contains it (hWndMDI). Handle of the top-level object that contains it (hWndForm is the handle of the table window). Handle of hte MDI window that contains it (hWndMDI).
Top-level object in an MDI window.
hWndForm
hWnd
Window Handle. The handle (or name) of the object whose parent window handle you want.
hWndParent is the parent window handle of hWnd. If hWnd is a top-level window, hWndParent is the window handle of the owner window, as passed to SalCreateWindow, otherwise hWndParent is equal to hWndNull.
Example
Set hWndParent = SalParentWindow ( hWnd )
SalPicClear
Syntax Description Parameters Return Value See Also bOk = SalPicClear ( hWndToClear ) Deletes the contents of a picture. hWndToClear Window Handle. The handle (or name) of a picture.
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid picture. SalPicSet SalPicSetFile SalPicSetFit SalPicSetString
Call SalPicClear ( hWndPicture )
Example
SalPicGetDescription
Syntax Description Parameters nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen ) Retrieves a description of a picture's contents. An example of a description is "Microsoft Draw". hWndPict strDesc Window Handle. The handle (or name) of a picture. Receive String. A description of the contents of hWndPict. For a graphic image, SalPicGetDescription returns one of the following values:
Value Gupta:BMP Gupta:GIF Gupta:ICO Gupta:PCX Gupta:TIFF Gupta:WMF Image Type Device-Independent Bitmap Graphics Interchange Format Icon File Paintbrush Tag Image File Format Windows MetaFile
For a file, SalPicGetDescription returns 'Gupta:DOSFILE'.
2-119
Chapter
For an OLE object, SalPicGetDescription returns the description of the object class that the server application recorded in the Windows registration database, followed by the word "Object". For example: Package Object Paintbrush Picture Object Sound Object Number. The maximum length of the text to retrieve.
nMaxLength Return Value See Also Example
nLength is the length (in bytes) of strDesc. SalPicGetSting

Set nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )
SalPicGetString
Syntax Description Parameters nLength = SalPicGetString ( hWndPict, nFormat, strPict ) Copies the contents of a picture to a string. hWndPict nFormat Window handle. The handle (or name) of a picture. Number. The format of the picture contents:
PIC_FormatBitmap PIC_FormatIcon PIC_FormatObject
strPict Return Value See Also Example
Receive String. The contents of hWndPict.
nLength is the length (in bytes) of strPict. If the format is not available, nLength is equal to zero (0). SalPicGetDescription
Set nLength = SalPicGetString ( hWndPict, nFormat, strPict )
SalPicSet
Syntax Description Parameters bOk = SalPicSet ( hWndPic, tResource, nFormat ) Inserts a resource into a picture. hWndPic tResource Window Handle. The handle (or name) of a picture. Template. An icon or bitmap in the Resources section of the outline.
nFormat
Number. The resource type. If you specify zero, Centura determines the resource type. Otherwise, specify one of these values: PIC_FormatBitmap PIC_FormatIcon
bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSetFile SalPicSetFit SalPicSetString
Set bOk = SalPicSet ( hWndPic, tResource, nFormat )
Example
SalPicSetFile
Syntax Description Parameters bOk = SalPicSetFile ( hWndPict, strFileName ) Inserts a file's contents into a picture. hWndPict strFileName Window Handle. The handle (or name) of a picture. String. The name of the file whose contents are to be inserted into hWndPict. Centura derives a picture's file type from the file extension. The file extension of a bitmap must be .BMP; the file extension of an icon must be .ICO. Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSet SalPicSetFit SalPicSetString
Set bOk = SalPicSetFile ( hWndPict, strFileName )
Example
SalPicSetFit
Syntax Description Parameters bOk = SalPicSetFit ( hWndPict, nFit, nScaleWidth, nScaleHeight ) Sets the fit for a picture. hWndPict Window Handle. The handle (or name) of a picture.
2-121
Chapter
nFit
Number. The type of fit: PIC_FitBestFit PIC_FitScale PIC_FitSizeToFit Number. The width scaling percentage if nFit is PIC_FitScale. Number. The height scaling percentage if nFit is PIC_FitScale.
nScaleWidth nScaleHeight Return Value See Also
bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSet SalPicSetFile SalPicSetString
Call SalPicSetFit ( hWndItem, PIC_FitBestFit, 0, 0 )
Example
SalPicSetString
Syntax Description Parameters bOk = SalPicSetString ( hWnd, nFormat, strPicture ) Inserts the contents of a string into a picture. hWnd nFormat Window Handle. The handle (or name) of a picture. Number. The format of the picture contents: PIC_FormatBitmap PIC_FormatIcon PIC_FormatObject 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. Return Value See Also bOk is TRUE if the function succeeds and FALSE if it fails. SalPicClear SalPicSet SalPicSetFile SalPicSetFit
Call SalPicSetString ( hWndPicture, PIC_FormatBitmap, strPicture )
strPicture
Example
SalPixelsToFormUnits
Syntax Description nFormUnits = SalPixelsToFormUnits ( hWnd, nNumPixels, bVertical ) Computes the number of Centura form units based on the number of pixels. Centura form units is a unit of measurement used by functions that move and position objects. Form units are computed by Centura using physical units (pixels) in conjunction with a window's font sizes. hWnd nNumPixels bVertical Window Handle. The handle (or name) of a window whose form units you want to compute. Number. The number of pixels. Boolean. If the pixels are on the X axis, set this parameter to FALSE. If the pixels are on the Y axis, set this parameter to TRUE.
Parameters
nFormUnits is the number of form units returned if the function call is successful. nFormUnits is equal to zero (0) if hWnd is invalid. SalFormUnitsToPixels
Set nFormUnits = SalPixelsToFormUnits ( pbExample, nPixels, FALSE )
SalPostMsg
Syntax Description Parameters bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam ) Posts the specified message to a window by adding nMsg to hWndReceiver's message queue. hWndReceiver nMsg nMywParam nMylParam Return Value See Also Example Window Handle. The handle (or name) of the window receiving the message. Number. The message number. Number. The wParam for the message. Number. The lParam for the message.
bOk is TRUE if the function succeeds and FALSE if it fails. SalSendMsg SalSendMsgToChildren
Set bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )
2-123
Chapter
SalPrtExtractRect
Syntax Description Parameters bOk = SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom ) Extracts the currently printing rectangle from the SAM_Print message's lParam parameter. nMylParam nLeft nTop nRight nBottom Return Value Example Number. The SAM_Print message's lParam parameter. Receive Number. The position on the X axis of the rectangle's left side. Receive Number. The position on the Y axis of the top of the rectangle. Receive Number. The position on the X axis of the rectangle's right side. Receive Number. The position on the Y axis of the bottom of the rectangle.

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

On SAM_Create Call SalPrtGetParmNum ( PRT_nDraftMode, nPrtValue) If nPrtValue Set rbDraftMode = TRUE Else Set rbProofMode = TRUE
SalPrtPrintForm
Syntax Description bOk = SalPrtPrintForm ( hWndForm ) 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. Centura 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 Return Value Example hWndForm Window Handle. The handle (or name) of the window to print.

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

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

Message Actions Call SalPrtSetup ( strDevice, strDriver, strPort, TRUE)
2-127
Chapter
SalQueryFieldEdit
Syntax Description bSet = SalQueryFieldEdit ( hWndField ) Returns the setting of the Field Edit Flag for a 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 not set if you make the change with a Set statement or a fetch from the database. This function does not clear the field edit flag of hWndField. Parameters Return Value See Also Example hWndField Window Handle. The handle (or name) of a data field, multiline field, combo box table window column, or picture.
bSet is TRUE if hWndField's field edit flag is set and FALSE otherwise. SalSendValidateMsg SalSetFieldEdit
If SalQueryFieldEdit ( SalGetFocus () ) If SalSendValidateMsg ( ) = VALIDATE_Ok ! Process Save.
SalQuit
Syntax Description bOk = SalQuit ( ) Exits an application. If you are in user mode, Centura returns you to design mode. If the application running from SQLRUN.EXE, it exits. Parameters Return Value See Also Example No parameters. bOk is TRUE if the function succeeds and FALSE if it fails. SalAbort
On SAM_Click Call SalQuit ( )
SalReportClose
Syntax Description Parameters Return Value Example bOk = SalReportClose ( hWndReport ) Closes a report window. Call this function when you want to close a report preview window. hWndReport Window Handle. The handle (or name) of a report window.
bOk is TRUE if the function succeeds and FALSE if hWndReport is invalid.

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

Set bOk = SalReportCmd ( hWndReport, nCommand )
SalReportCreate
Syntax Description Parameters bOk = SalReportCreate ( strTemplate, strVariables, strInputs, bDefaultReport, nError ) Creates a report template. strTemplate String. The name of the report template to create.
2-129
Chapter
strVariables
String. A comma-separated list of Centura variables that contain data to fetch. The data types of these variables must match the data types of the input names in strInputs. String. A comma-separated list of the report's input names. Boolean. If TRUE, Centura generates a quick report and nError is a RPT_Err* value. If FALSE, Centura generates an empty report. Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. If you call SalReportCreate ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura only displays an error dialog box if you set this parameter to 1 before calling SalReportCreate.
strInputs bDefaultReport
nError
bOk is TRUE if the function succeeds and FALSE if it fails. If bOk is FALSE, nError is a RPT_Err* value.
Call SalReportCreate ( 'quick.qrp',':nDiv,:nDept,:nSection, :nEmplNum )
SalReportDlgOptions
Syntax Description bOk = SalReportDlgOptions ( hWndReport, strCaption, strLine1, strLine2, strDocName ) Sets the options for the report printing dialog box. Call this function after creating the report but before printing begins. For example, you can call SalReportDlgOptions while processing the SAM_ReportFetchInit message. hWndReport strCaption strLine1 strLine2 strDocName Return Value Window Handle. The wParam of a SAM_Report* message that contains the window handle. String. The replacement text for the Print dialog box caption text. String. The replacement text for the first centered-text field. String. The replacement text for the second centered-text field. String. The name of the document that Print Manager displays when the output is spooled and waiting to print.
Parameters
Example
Call SalReportDlgOptions ( SalNumberToWindowHandle (wParam ), 'Sales Report', 'This is a long report', 'Hit CANCEL to quit', 'sales.rpt' )
SalReportGetDateTimeVar
Syntax Description Parameters bOk = SalReportGetDateTimeVar ( hWndReport, strVariable, dtValue ) Returns the value of a date/time report variable. hWndReport strVariable dtValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of a date/time report variable. Receive Date/Time. The value of strVariable.
bOk is TRUE if the function is successful, and FALSE otherwise. SalReportGetNumberVar SalReportGetObjectVar SalReportGetStringVar SalReportSetDateTimeVar
Call SalReportGetDateTimeVar ( hWndReport, strVariable, dtGet )
Example
SalReportGetNumberVar
Syntax Description Parameters bOk = SalReportGetNumberVar ( hWndReport, strVariable, nValue ) Returns the value of a number report variable. hWndReport strVariable nValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of a number report variable. Receive Number. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetDateTimeVar SalReportGetObjectVar SalReportGetStringVar SalReportSetNumberVar
Call bOk = SalReportGetNumberVar ( hWndToMove, nXOffset, nYOffset )
Example
2-131
Chapter
SalReportGetObjectVar
Syntax Description Parameters bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue ) Returns the value of an object report variable. hWndReport strVariable strValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of an object report variable. Receive String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetStringVar SalReportSetObjectVar
Set bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )
Example
SalReportGetStringVar
Syntax Description Parameters bOk = SalReportGetStringVar ( hWndReport, strVariable, strValue ) Returns the value of a string report variable. hWndReport strVariable strValue Return Value Window Handle. The handle (or name) of a report window. String. The name of a string report variable. Receive String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. See Also SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetObjectVar SalReportSetStringVar
Example
Call SalReportGetStringVar ( hWndReport, 'strVariable', strGet )
SalReportPrint
Syntax Description hWndRet = SalReportPrint ( hWndFrm, strTemplate, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr ) Prints a report. This function is synchronous and does not return until the report has been formatted and sent to Windows or Windows Print Manager for printing. SalReportPrint creates a minimized ReportWindows window. A print status dialog box displays while printing. When this function completes, ReportWindows automatically ends. Note: This function establishes a dialog between ReportWindows and the application; the real
work of reporting is in processing the SAM_Report* messages which ReportWindows sends.
Centura sends data from an application to ReportWindows when the application returns TRUE in SAM_ReportFetchNext processing. ReportWindows continues to send SAM_ReportFetchNext messages until the application returns FALSE. Parameters hWndFrm strTemplate strVariables Window Handle. The handle (or name) of the application window that processes SAM_Report* messages. String. The report template name. String. A comma-separated list of Centura variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs. String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template. nCopies nOptions Number. The number of copies. If you specify a zero or a negative number, Centura prints one copy. Number. You can combine two or more of these constants with the OR (|) operator:
RPT_PrintAll RPT_PrintDraft RPT_PrintNoAbort RPT_PrintNoErrors RPT_PrintNoWarn RPT_PrintRange
strInputs
2-133
Chapter
nFirstPage nLastPage nErr
Number. The first page of the report (if nOptions includes RPT_PrintRange). Number. The last page of the report (if nOptions includes RPT_PrintRange). Receive Number. If this function succeeds, this parameter is zero. If an error occurs, this parameter is one of the RPT_Err* values.
Note: If you call SalReportPrint ten times in a row, you will receive the following error code:
RPT_ErrMaxRps.
In run mode at designtime, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura only displays an error dialog box if you set this parameter to 1 before calling SalReportPrint. Return Value The return value is reserved for future use and can be ignored. To detect if the function succeeded, check nErr which is a RPT_Err* value. If successful, nErr is zero. If you want to interact with the report window, interrogate wParam at SAM_ReportStart and save that into the hWndReport variable. See Also Example SalReportPrintToFile
Call SalReportPrint ( frmMain, strReportFile, strReportBinds, strReportInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr )
SalReportPrintToFile
Syntax Description hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr ) Prints a report to a file in RTF format or in ASCII text format. This function is synchronous and does not return until the output report file is closed. Parameters hWndFrm strTemplate strDestFile Window Handle. The handle (or name) of the application window that processes the SAM_Report* messages. String. The report template name. String. The destination file name.
strVariables
String. A comma-separated list of Centura variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs. String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template.
strInputs
nCopies nOptions
Number. The number of copies. 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 Number. The first page of the report (if nOptions includes RPT_PrintRange). Number. The last page of the report (if nOptions includes RPT_PrintRange). Boolean. Specify TRUE to write the report in RTF format; specify FALSE to write the report in ASCII format. Receive Number. If this function succeeds, this parameter is zero. If an error occurs, this parameter is one of the RPT_Err* values. If you call SalReportPrintToFile ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura only displays an error dialog box if you set this parameter to 1 before calling SalReportPrintToFile.
nFirstPage nLastPage bFormat nErr
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. SalReportPrint
See Also
2-135
Chapter
Example
Set hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )
SalReportReset
Syntax Description bOk = SalReportReset ( hWndReport ) Re-populates the report window. This function re-sends the SAM_ReportFetchInit message, and one or more SAM_ReportFetchNext messages to populate the report window with the new data. hWndReport Window Handle. The handle (or name) of the report window.

If NOT SalReportReset ( hWndReport ) Call SalMessageBox ( 'Reset Failed', 'SalReportReset', MB_Ok )
SalReportSetDateTimeVar
Syntax Description Parameters bOk = SalReportSetDateTimeVar ( hWndReport, strVariable, dtValue ) Sets the value of a date/time report variable. hWndReport strVariable dtValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of the variable whose value you want to set. Date/Time. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar SalReportSetStringVar
If NOT SalReportSetDateTimeVar ( hWndReport, 'dtVariable', dtGDateTime[1] ) Call SalMessageBox ( 'SetDateTimeError', 'RPT_BeforePageHeader-d', MB_Ok )
Example
SalReportSetNumberVar
Syntax Description Parameters bOk = SalReportSetNumberVar ( hWndReport, strVariable, nValue ) Sets the value of a numeric report variable. hWndReport strVariable nValue Return Value Window Handle. The handle (or name) of a report window. String. The name of the variable whose value you want to set. Number. The value of strVariable.
Related Function SalReportGetNumberVar SalReportSetDateTimeVar SalReportSetObjectVar SalReportSetStringVar Example

Call SalReportSetNumberVar ( hWndReport, 'strUnknown', nVariable )
SalReportSetObjectVar
Syntax Description Parameters bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue ) Sets the value of an object report variable. hWndReport strVariable strValue Return Value See Also Window Handle. The window of the report window handle. String. The name of the variable whose value you want to set. String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetObjectVar SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetStringVar
Set bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue )
Example
2-137
Chapter
SalReportSetStringVar
Syntax Description Parameters bOk = SalReportSetStringVar ( hWndReport, strVariable, strValue ) Sets the value of a string report variable. hWndReport strVariable strValue Return Value See Also Window Handle. The handle (or name) of a report window. String. The name of the variable whose value you want to set. String. The value of strVariable.
bOk is TRUE if the function succeeds and FALSE if it fails. SalReportGetStringVar SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar
Call SalReportSetStringVar ( hWndReport, 'strUnknown', strVariable )
Example
SalReportTableCreate
Syntax Description bOk = SalReportTableCreate ( strReport, hWndTbl, nError ) Creates a report template from the specified table window. The table window column names are the input names to the report and their titles are the column names on the report. For a top-level table window, the report's title is the same as the table window's title; for a child table window, the report does not have a title. strReport hWndTbl nError String. The name of the report. Window Handle. The handle (or name) of a table window. Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. Note: If you call SalReportTableCreate ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura only displays an error dialog box if you set this parameter to 1 before calling SalReportTableCreate. Return Value bOk is TRUE if the function succeeds and FALSE if it fails.
Parameters
See Also Example
SalReportTablePrint SalReportTableView
Set bOk = SalReportTableCreate ( strReport, hWndTbl, nError )
SalReportTablePrint
Syntax Description Parameters hWnd = SalReportTablePrint ( hWndTbl, strReport, nParamArray, nError ) Prints a report created from the specified table window. hWndTbl strReport nParamArray Window Handle. The handle (or name) of a table window. String. The name of the report. Number. An array you create containing information about the print job. The array indexes are: RPT_PrintParamCopies RPT_PrintParamFirstPage RPT_PrintParamLastPage RPT_PrintParamOptions Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. If you call SalReportTablePrint ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura only displays an error dialog box if you set this parameter to 1 before calling SalReportTablePrint. Return Value See Also Example hWnd is the handle of the report window if the function succeeds. SalReportTableCreate SalReportTableView
Set hWndReport = SalReportTablePrint ( hWndTbl, 'test.qrp', nParamArray,nError )
nError
2-139
Chapter
SalReportTableView
Syntax Description Parameters hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError ) Displays, in preview mode, a report created from the specified table window. hWndTbl hWndDisplay Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a report display window. If null, Centura creates a window in which you can preview the report. String. The name of the report. 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, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura only displays an error dialog box if you set this parameter to 1 before calling SalReportTableView. Return Value See Also Example hWnd is the handle of the report window if the function succeeds. SalReportTableCreate SalReportTablePrint
Set hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError )
strReport nError
SalReportView
Syntax Description hWndReport = SalReportView ( hWndFrm, hWndRptTemp, strTemplate, strVariables, strInputs, nFlags ) Displays a report in preview mode. Report processing is asynchronous; SalReportView returns after starting the report process. Note: This function establishes a dialog between ReportWindows and the application; the real work of reporting is done in trapping and handling the SAM_Report messages which ReportWindows 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 2-140 Centura Builder Function Reference
message. ReportWindows does not receive any data until it issues the SAM_ReportFetchNext message and the Centura application returns TRUE to that message. ReportWindows keeps sending SAM_ReportFetchNext messages until Centura returns FALSE. Parameters hWndFrm hWndRptTemp Window Handle. The handle (or name) of the application window that processes SAM_Report* messages. Window Handle. An optional window handle (or name) to a custom report template. If null, ReportWindows creates its own window in which it displays the report. String. The report template name. String. A comma-separated list of Centura variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs. The contents of this string must match the order of the input names declared in the report template. strInputs String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template. nFlags Receive Number. Before you call this function, you can set this parameter to one of the constants below to turn off the printer icon on the default report view tool bar or turn off the tool bar completely: No print button on the tool bar. No tool bar in the preview window. If an error occurs, this parameter is one of the RPT_Err* constants. If you call SalReportView ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, Centura always displays a dialog box with an explanation if an error happens. For *.RUN and *.EXE applications, Centura 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. Centura returns the window handle before ReportWindows displays the report.
strTemplate strVariables
RPT_NoPrint RPT_NoToolBar
2-141
Chapter
Example
Set hWndReport = SalReportView ( frmMain, hWndNULL, strReportFile, strReportBinds, strReportInputs, nError )
SalScrollGetPos
Syntax Description Parameters bOk = SalScrollGetPos ( hWndsb, nPos ) Returns the current scroll bar value. hWndsb nPos Return Value See Also Example Window Handle. The handle (or name) of a vertical or horizontal scroll bar. Receive Number. The scroll bar value.
bOk is TRUE if the function succeeds and FALSE if it fails. SalScrollSetPos

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

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

Call SalScrollSetPos ( hWndsbCounter, 0 )
SalScrollSetRange
Syntax Description bOk = SalScrollSetRange ( hWndsb, nMin, nMax, nLine, nPage ) Sets a scroll bar's range, line increment, and page increment. When the scroll bar is created, Centura assigns it these values:
Minimum scroll position0 Maximum scroll position100 Line Increment1 Page Increment10
If the scroll bar's current position is outside the new range, its position changes to one within the new range. The range of a scroll bar is -32,767 to 32,767. Parameters hWndsb nMin nMax nLine nPage Window Handle. The handle (or name) of a vertical or horizontal scroll bar. Number. The minimum position of the scroll bar. Number. The maximum position of the scroll bar. Number. The number of units to increment or decrement the scroll bar when the user clicks the scroll bar arrow. Number. The number of units to increment or decrement the scroll bar when the user clicks either side of the scroll box.
2-143
Chapter
bOk is TRUE if the function succeeds and FALSE if it fails. SalScrollGetRange

Call SalScrollSetRange ( hWndsbCounter, 0, 50, 1, 5 )
SalSendClassMessage
Syntax Description Parameters nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam ) Invokes the message actions implemented or inherited by an object's class when called from either a derived class or from an object that is an instance of a class. nMessage nMywParm nMylParam Return Value See Also Example Number. The message number. Number. The wParam. Number. The lParam.
nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0). SalSendClassMessageNamed
Set nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )
SalSendClassMessageNamed
Syntax Description nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam ) Invokes the message actions implemented or inherited by an object's class when called from either a derived class or from an object that is an instance of a class. Use this function instead of SalSendClassMessage with a class that is the result of multiple inheritance. It lets you specify which base class message action you want to execute. tClassName must be a direct base class of the class from which this call is made. Parameters tClassName nMsg nMywParam nMylParam Return Value Template. The ancestor's class name. Number. The message number. Number. The wParam. Number. The lParam.
nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0).
See Also Example
SalSendClassMessage
Set nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam )
SalSendMsg
Syntax Description Parameters nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam ) Sends the specified message to a window. SalSendMsg does not return until the processing for the message is complete. hWnd nMsg nMywParam nMylParam Return Value See Also Window Handle. The window receiving the message. Number. The message number. Number. The wParam. Number. The lParam.
nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0). SalPostMsg SalSendMsgToChildren SalSendValidateMsg
Set nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )
Example
SalSendMsgToChildren
Syntax Description Parameters bSent = SalSendMsgToChildren ( hWnd, nMsg, nMywParam, nMylParam ) Sends a message to all child items of a form window, dialog box, table window, or MDI window. hWnd nMsg nMywParam nMylParam Return Value See Also Window Handle. The handle (or name) of a form window, dialog box, table window, or MDI window. Number. The message number. Number. The wParam for the message. Number. The lParam for the message.
bSent is TRUE if the function succeeds and FALSE if it fails. SalPostMsg SalSendMsg SalSendValidateMsg
2-145
Chapter
Example
Call SalSendMsgToChildren ( hWndForm,CHM_DISABLE, 0, 0 )
SalSendValidateMsg
Syntax Description nStatus = SalSendValidateMsg ( ) Sends a SAM_Validate message to the object with the focus data field, multiline field, or table window column if it was edited and sets the wParam and lParam message variables to zero (0). Call this function to force field validation before processing a menu pick. Centura does not automatically send SAM_Validate message on a menu pick. Parameters Return Value Np parameters. nStatus is returned by the object's message actions for the SAM_Validate message: VALIDATE_Cancel VALIDATE_Ok VALIDATE_OkClearFlag See Also Example SalSendMsg SalSendMsgToChildren
Set nStatus = SalSendValidateMsg ( )
SalSetDefButton
Syntax Description bOk = SalSetDefButton ( hWndButton ) Sets the default push button of a form window or dialog box. When this function returns, the default push button gets the focus only if the focus was on one of the push buttons before you called SalSetDefButton. hWndButton Window Handle. The handle (or name) of the default push button.
bOk is TRUE if the function succeeds and FALSE if hWndButton is not a valid button. SalGetDefButton
Call SalSetDefButton ( frmMain.pb2 )
SalSetFieldEdit
Syntax Description bOk = SalSetFieldEdit ( hWndField, bSet ) Sets or clears the field edit flag for an editable data field, combo box, multiline text field, table window column, or picture. The Field Edit Flag is set whenever the user changes the value of a data field, multiline field, combo box or table window column. For a picture, the field edit flag is set whenever an OLE server application is opened for editing. The field edit flag is not set if you make the change with a Set statement or a fetch from a database. Parameters hWndField bSet Return Value See Also Example Window Handle. The handle (or name) of a data field, multiline text field, table window column, or picture. Boolean. TRUE sets the flag; FALSE clears it.
bOk is TRUE if the function succeeds and FALSE if it fails. SalQueryFieldEdit

Call SalSetFieldEdit ( hWndChild, FALSE )
SalSetFocus
Syntax Description hWndFocus = SalSetFocus ( hWndToSet ) Sets the focus to a specified window. Warning: You cannot call SalSetFocus in SAM_KillFocus processing because of a
Windows limitation.
hWndToSet
Window Handle. The handle (or name) of the window to receive the focus.
hWndFocus is the handle of the window that previously had the focus. SalGetFocus
Call SalSetFocus ( hWndSave )
2-147
Chapter
SalSetMaxDataLength
Syntax Description Parameters bOk = SalSetMaxDataLength ( hWndField, nLength ) Sets a limit on the number of characters that a user can enter into a data field, multiline text field, or table window column. hWndField nLength Return Value See Also Example Window Handle. The handle (or name) of a data field, multiline text field, or table window column. Number. The character limit.
bOk is TRUE if the function succeeds and FALSE if it fails. SalGetMaxDataLength

Set bOk = SalSetMaxDataLength ( hWndField, nLength )
SalSetProfileString
Syntax Description bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName ) Set the value of an entry in the specified section of an initialization file or registry. All profile information is stored as string, so if you want to store an integer it must be converted to a string first. Then it can be retrieved as an integer using the SalGetProfileInt-Function . strSection strEntry strValue strFileName String. The section heading. String. The entry whose associated value is being set. String. The value of strEntry. String. The name of the initialization file or company name depending on the settings made using the SalUseRegistry function. If you are searching for an INI file and do not specify the full path, Centura searches for the file in the Windows subdirectory.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalGetProfileInt SalGetProfileString SalUseRegistry
Set bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )
Example
SalSetWindowLabelText
Syntax Description bOk = SalSetWindowLabelText ( hWnd, sText ) Sets the background text of a window. To be associated with a specific window, background text must immeditately precede the window in the Outliner. Important: The background text does not require a mnemonic for the function to
operate.
Parameters
hWnd sText
Window Handle. The handle (or name) of a window. String. The window text.

Set bOk = SalSetWindowLabelText ( hWnd, sText )
SalSetWindowLoc
Syntax Description Parameters bOk = SalSetWindowLoc ( hWnd, nX, nY ) Moves a window to a new position (x, y) on the X and Y axes. hWnd nX nY Return Value See Also Example Window Handle. The handle (or name) of the window to move. Number. The position on the X axis (expressed in form units). Number. The position on the Y axis (expressed in form units).
bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle. SalGetWindowLoc
Call SalSetWindowLoc ( pbExample, 0, 0 )
SalSetWindowSize
Syntax Description Parameters bOk = SalSetWindowSize ( hWnd, nWidth, nHeight ) Resizes a window. hWnd nWidth Window Handle. The handle (or name) of the window to resize. Number. The new width of the window (expressed in form units).
2-149
Chapter
nHeight Return Value See Also Example
Number. The new height of the window (expressed in form units).
bOk is TRUE if the window is successfully resized, and FALSE if hWnd is an invalid window handle. SalGetWindowSize
Call SalSetWindowSize ( pbExample, nWidth+1, nHeight+1)
SalSetWindowText
Syntax Description bOk = SalSetWindowText ( hWnd, strTitle ) Sets the text of a window to a specified string. A window's text is the title of a form window, modeless dialog box, table window, radio button, check box, or push button. 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, Centura tries to set the list selection to the item that matches the specified string. This latter statement is true for list boxes as well. The SalSetWindowText function clears the field edit flag. Parameters hWnd strTitle Return Value See Also Example Window Handle. The handle (or name) of a window. String. The window text.
bOk is TRUE if the function succeeds and FALSE if it fails. SalGetWindowText SalTblSetColumnTitle
Call SalSetWindowText ( hWndForm, 'First National Bank' )
SalShowWindow
Syntax Description Parameters Return Value bOk = SalShowWindow ( hWndToShow ) Makes a window visible. hWndToShoWindow Handle. The handle (or name) of a window to make visible. bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they
are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible. See Also Example SalHideWindow
Call SalShowWindow ( hWndForm )
SalShowWindowAndLabel
Syntax Description bOk = SalShowWindowAndLabel ( hWndToShow ) Makes a window and its associated label visible. A label is the background text that immediately precedes the window in the outline. Parameters Return Value hWndToShow The handle (or name) of a window to make visible.
bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they 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. SalHideWindowAndLabel SalShowWindow
Set bOk = SalShowWindowAndLabel ( hWndToShow )
See Also Example
SalStatusGetText
Syntax Description Parameters nLength = SalStatusGetText ( hWnd, strText, nMaxLen ) Gets the text displayed in the status bar of a top-level or MDI window. hWnd strText nMaxLen Return Value See Also Example Window Handle. The handle (or name) of a top-level or MDI window. Receive String. The text displayed in the status bar. Number. The maximum length of the window text.
nLength is the length of strText. nLength is zero (0) if the window has no text. SalStatusSetText SalStatusSetVisible
Set nLength = SalStatusGetText ( hWnd, strText, nMaxLen )
2-151
Chapter
SalStatusSetText
Syntax Description Parameters bOk = SalStatusSetText ( hWnd, strText ) Displays specified text in the status bar of a top-level or MDI window. hWnd strText Return Value See Also Example Window Handle. The handle (or name) of a top-level or MDI window. String. The text to display in the status bar.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStatusGetText SalStatusSetVisible
Set bOk = SalStatusSetText ( hWnd, strText )
SalStatusSetVisible
Syntax Description Parameters bOk = SalStatusSetVisible ( hWnd, bShow ) Shows or hides the status bar on a top-level or MDI window. hWnd Window Handle. The handle (or name) of a top-level or MDI window.
bShoBoolean. If TRUE, the status bar displays; if FALSE, the status bar hides. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalStatusGetText SalStatusSetText
Call SalStatusSetVisible ( hWndForm, TRUE )
SalStrCompress
Syntax Description bOk = SalStrCompress ( strString ) Compresses the specified string. Use this function to compress strings for storage on disk or in the database. Use this function for long strings, or when storing images and so on. strString Receive String. The string to compress.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStrUncompress

Set bOk = SalStrCompress ( strString )
SalStrFirstC
Syntax Description bOk = SalStrFirstC ( strString, nChar ) Extracts the first character of a string and returns its decimal value. You must use this function in place of SalStrLop if the input string contains nonASCII (ANSI) 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 nChar Return Value See Also Receive String. The string whose first character is lopped off. Receive Number. The first character of strString.
bOk is TRUE unless strString is empty or invalid. SalNumberHigh SalNumberLow SalNumberToChar SalStrLop
On SAM_Click Set dfString = 'ABC' Call SalStrFirstC ( dfString, dfNumChar ) ! Now dfString = 'BC' and dfNumChar = 65
Example
SalStrGetBufferLength
Syntax Description nLength = SalStrGetBufferLength ( strString ) Returns the current buffer length of a string. Centura stores string variables in buffers. The length includes the string's null termination character. Parameters Return Value See Also Example strString String. The string whose buffer length you want.
nLength is the length of strString's buffer. SalStrLength SalStrSetBufferLength

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

On SAM_Create Set strNumbers = '1234567890' Set nStringLength = SalStrLength ( strNumbers )
SalStrLop
Syntax Description Parameters Return Value See Also Example nCharacter = SalStrLop ( strString ) Returns the ASCII numeric value of the first character of a string in decimal format. This function removes the first character of the string. strString Receive String. The input string without the first character.
nCharacter is the ASCII value of the first character of strString. When strString is null, nCharacter is equal to zero (0). SalNumberToChar SalStrFirstC
On SAM_Create Set strString = 'ABC' Set nCharacter = SalStrLop ( strString )
SalStrLower
Syntax nLength = SalStrLower ( strSource, strTarget ) or strTarget = SalStrLowerX ( strSource ) Description Parameters Converts a string to lowercase. strSource strTarget String. The string to convert . Receive String. The lowercase string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the lowercase string. See Also Examples SalStrUpper SalStrUpperX
On SAM_Create Set nLength = SalStrLower ( 'LOWERCASE', strTarget ) or On SAM_Create Set strTarget = SalStrLowerX ( 'LOWERCASE' )
2-157
Chapter
SalStrMid
Syntax nLength = SalStrMid ( strSource, nStartPos, nLength, strTarget ) or strTarget = SalStrMidX ( strSource, nStartPos, nLength ) Description Parameters Returns a substring, starting at a specified position and containing a specified number of characters. strSource nStartPos nLength strTarget String. The source string. Number. The starting position of the substring (zero is the first position) in strSource. Number. The number of characters to put in the substring. Receive String. The substring.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of the substring. strTarget is the substring. See Also SalStrLeft SalStrLeftX SalStrRight
Set nLength = SalStrMid (012ABC345, 3, 3, strTarget) Or Set strTarget = SalStrMidX ( '012ABC345', 3, 3 ) ! strTarget = 'ABC'
Examples
SalStrProper
Syntax nLength = SalStrProper ( strSource, strTarget ) or strTarget = SalStrProperX ( strSource ) Description Parameters Converts a string to a proper name. In a proper name, the first letter of each word is uppercase; the remaining letters are lowercase. strSource strTarget String. The string to convert. Receive String. The converted string.
You can specify the same string for both strSource and strTarget.
Return Value
nLength is the length of strTarget. strTarget is the converted string.
Examples
Set nLength = SalStrProper ( 'JOHN L. SMITH', strTarget ) or Set strTarget = SalStrProperX ( 'JOHN L. SMITH')
SalStrRepeat and SalStrRepeatX

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

Syntax nReturn = SalStrReplace ( strSource, nStartPos, nLength, strReplace, strTarget ) or strTarget = SalStrReplaceX ( strSource, nStartPos, nLength, strReplace ) Description Replaces characters in one string with characters from another string.
2-159
Chapter
Parameters
strSource nStartPos nLength strReplace strTarget
String. The source string that contains characters to replace. Number. The position in strSource at which to begin replacing characters. Number. The number of characters to replace. If zero (0), strReplace starts at nStartPos. String. The replacement string. Receive String. The new string.
Return Value
nReturn is the length of strTarget. strTarget is the new string.
Examples
Set nReturn = SalStrReplace ( 'ABC1234', 3, 4, 'DEFG', strTarget ) or Set StrTarget = SalStrReplaceX ( 'ABC1234', 3, 4)
SalStrRight and SalStrRightX

Syntax nLength = SalStrRight ( strSource, nLength, strTarget ) or strTarget = SalStrRightX ( strSource, nLength ) Description Parameters Returns a string of specified length, starting with the last character in the string. strSource nLength strTarget String. The source string. Number. The number of characters to extract. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nLength is the length of strTarget. strTarget is the new string. See Also SalStrLeft SalStrLeftX SalStrMid SalStrMidX
Example
On SAM_Create Set nLength = SalStrRight ( '123RIGHT', 5, strTarget ) or On SAM_Create Set StrTarget = SalStrRightX ( '123RIGHT', 5 )
SalStrScan
Syntax Description nOffset = SalStrScan ( strString1, strString2 ) Searches for and returns the offset of a specified substring. If there is more than one instance of the string being searched for, only the offset of the first instance is returned. strString1 strString2 String. The string to search. The first character in the string is at offset zero (0). String. The string to search for. Case is disregarded in the search. You can use pattern matching characters. The percent character (%) matches any set of characters. The underscore character (_) matches any single character. The use of a backslash(\) with SalStrScan differs when searching for a backslash, percent, or underscore character. Its usage also differs depending on whether or not the second parameter is a string literal. 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.
Parameters
2-161
Chapter
nOffset is a number that indicates the offset (0 origin) of strString2 in strString1. If Centura does not find strString2 in strString1, SalStrScan returns a -1.
Set nOffset = SalStrScan ( '012AbC345', 'ABC' )
SalStrSetBufferLength
Syntax Description bOk = SalStrSetBufferLength ( strString, nLength ) Sets the buffer string length to the length plus 1 for the terminator and allocates memory. This is only needed if you want to pass a Receive String to an external function. strString nLength Return Value See Also Receive String. The string whose buffer length you want to set. Number. The length of strString.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SalSetMaxDataLength SalStrGetBufferLength
Example
Set bOk = SalStrSetBufferLength( recvString, 10 ) ! 11 chars
SalStrToDate
Syntax Description Parameters Return Value See Also Example dtDateTime = SalStrToDate ( strString ) Converts a string to a date/time value.This function uses the system date format to convert a date string. If you want to be format independent, use SalDateConstruct. strString String. The string to convert.
dtDateTime is the date/time value converted from strString. SalDateToStr

Set dtDateTime = SalStrToDate ( strDateTime )
SalStrTokenize
Syntax Description nNumTokens = SalStrTokenize ( strSource, strStartDel, strEndDel, strTokenArray ) Parses a string into substrings (tokens) based on specified start and end delimiters. Centura uses delimiters to recognize the beginning and end of each substring. Centura 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, Centura interprets it as a null substring. This is useful for comma-separated data where ',' is an end delimiter. Centura recognizes that the records 'data1,data2,,data4' and ',data2,data3,data4' have four tokens each, one of which is null. Once Centura 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, Centura correctly interprets them as elements of the substring. Parameters strSource strStartDel String. The string to parse. String. A string that contains the start delimiter characters. Pass an empty string ('') to specify the lack of a start delimiter. strEndDel String. A string that contains the end delimiter characters. Pass an empty string ('') to specify the lack of an end delimiter. strTokenArray Return Value Example String Array. The handle (or name) of an array of substrings created from strSource.
nNumTokens is the number of substrings created. nNumTokens is zero (0) if no substrings are created, or if an error occurs.
Set dfNumTokens = SalStrTokenize( dfSource1, '', ',', astrToken1 )
SalStrToNumber
Syntax Description Parameters Return Value nNumber = SalStrToNumber ( strString ) Converts a string to a number. strString String. The string to convert.
nNumber is the number resulting from the conversion.
2-163
Chapter
See Also Example
SalNumberToStr
Set nNumber = SalStrToNumber ( '100.22' )
SalStrTrim
Syntax nNewLength = SalStrTrim ( strSource, strTarget ) or strTarget = SalStrTrimX ( strSource ) Description Parameters Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces. strSource strTarget String. The original string. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nNewLength is the length of strTarget. strTarget is the new string. Example
Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )
SalStrTrimX
Syntax Description Parameters strTarget = SalStrTrimX ( strSource) Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces. strSource strTarget String. The original string. Receive String. The new string.
You can specify the same string for both strSource and strTarget. Return Value nNewLength is the length of strTarget. strTarget is the new string. Example
On SAM_Create Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )
SalStrUncompress
Syntax Description Parameters Return Value See Also Example bOk = SalStrUncompress ( strString ) Decompresses the specified string. Use this function to decompress a string that you compressed with SalStrCompress. strString Receive String. The string to decompress.
bOk is TRUE if the function succeeds and FALSE if it fails. SalStrCompress

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

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

Call SalTblClearSelection ( hWndForm )
SalTblColumnAverage
Syntax Description nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff ) Computes the average of all column values or only specified column values in a table window. Use Centura row flag constants to specify the rows to use in the computation. For example, you can choose to average only the values of modified rows. Parameters hWndTbl nColumnID nFlagsOn nFlagsOff Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The Column Identifier. Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator. Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator:
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. SalTblColumnSum
Set nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )
SalTblColumnSum
Syntax Description nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff ) Computes the sum of all column values or only specified column values in a table window. Use Centura 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.
2-167
Chapter
Parameters
hWndTbl nColumnID nFlagsOn nFlagsOff
Window Handle. The handle (or name) of a table window. Number. The Column Identifier Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator. Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.
nSum is the sum of all column values or only specified column values in a table window. nSum is equal to zero (0) if an error occurs. SalTblColumnAverage
Set nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )
SalTblCopyRows
Syntax
bOk = SalTblCopyRows ( hWndTbl, nFlagsOn, nFlagsOff ) Copies the contents of the specified table window rows to the Clipboard in text format. In the Clipboard, columns are delimited by TAB characters and rows are delimited by end-of-line characters. Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to copy the entire table. The copy stops, without indicating a failure, after copying 64 Kbytes of text.
Description
Parameters
hWndTbl nFlagsOn nFlagsOff
Window Handle. The handle (or name) of a table window. Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator. Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.
Return Value
bOk is TRUE if any of the table window's rows are copied to the Clipboard and FALSE if no rows matched the indicated flags, or if none of the matched rows could be copied to the Clipboard. SalTblPasteRows
Call SalTblCopyRows ( tblTable, ROW_Selected, 0 )
See Also Example
SalTblCreateColumn
Syntax Description nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars, strTitle ) Creates a table window column of string data type at runtime. When you return to design mode, Centura destroys the column. Parameters hWndTbl nColumnPos nDispWidth nMaxChars strTitle Return Value Example Window Handle. The handle (or name) of a table window. Number. The Column Position Number. The display width of the column in inches. Number. The maximum number of characters that the column can contain. String. The column title.
nColId is the Column Identifier of the new column. nColld is zero (0) if an error occurs.
Set nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars, strTitle )
SalTblDefineCheckBoxColumn
Syntax Description Parameters bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue ) Define a column as a check box. hWnd HWndCol nFlags Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Number. nFlags is a combination of the following flags using the '|' operator: COL_CheckBox_IgnoreCase = 0x0001 String. sCheckedValue is the value that a cell will get when the check box is checked. String. The value when a check box is unchecked.
sCheckedValue sUncheckedValue Return Value Example

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

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

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

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

Set bAnyFlag = SalTblDefineSplitWindow ( hWndTbl, 3, TBL_Split_Adjustable )
SalTblDeleteRow
Syntax Description Parameters bOk = SalTblDeleteRow ( hWndTbl, nRow, nFlag ) Deletes a row from a table window but not from the database. hWndTbl Window Handle. The handle (or name) of a table window.
nRoNumber. The number of the row to delete. nFlag Number. A constant used to coordinate a delete from the table window with a delete from a SQLBase result set. This parameter can be one of these values:
TBL_Adjust TBL_NoAdjust

Call SalTblDeleteRow ( hWndForm, nCurrentRow, TBL_NoAdjust)
SalTblDeleteSelected
Syntax Description bOk = SalTblDeleteSelected ( hWndTbl, hSql ) Applies a SQL DELETE statement to all table window rows with the ROW_Selected flag set. You must prepare or retrieve the SQL DELETE statement before calling this function. As each row is deleted from the database, Centura deletes it from the table window display. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the deletions are not lost in the case of a rollback. Parameters hWndTbl hSql 2-172 Centura Builder Function Reference Window Handle. The handle (or name) of a table window. Sql Handle. The handle of a DELETE statement.
bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid. SalTblDoDeletes SalTblDoInserts SalTblDoUpdates SalTblPopulate
Call SalTblDeleteSelected ( tblExample, hSql )
Example
SalTblDestroyColumns
Syntax Description bOk = SalTblDestroyColumns ( hWndTbl ) Destroys all automatic columns created by SalTblCreateColumn or SalTblPopulate at runtime. This function only works on table windows that contain only automatic columns. Parameters Return Value See Also Example hWndTbl Window Handle. The handle (or name) of a table window.
bOk is TRUE if the function succeeds and FALSE if hWndTbl is invalid or the table window contains non-automatic columns (columns created at design time). SalTblCreateColumn SalTblPopulate
Set bOk = SalTblDestroyColumns ( hWndTbl )
SalTblDoDeletes
Syntax Description bOk = SalTblDoDeletes ( hWndTbl, hSql, nFlagsOn ) 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, Centura deletes it from the table window display. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the deletions are not lost in the case of a rollback. Parameters hWndTbl hSql nFlagsOn Window Handle. The handle (or name) of a table window. Sql Handle. The handle of a DELETE statement. Number. Centura uses row flags to determine which rows to delete. You can specify either of these flags:
ROW_MarkDeleted ROW_Selected
2-173
Chapter
bOk is TRUE if any rows are deleted and FALSE otherwise. bOk is FALSE if hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoInserts SalTblDoUpdates
Call SalTblDoDeletes ( tblExample, hSql, ROW_MarkDeleted )
Example
SalTblDoInserts
Syntax Description bOk = SalTblDoInserts ( hWndTbl, hSql, bClearFlags ) Applies a SQL INSERT statement to all the rows in a table window that have the ROW_New flag set. You must prepare the SQL INSERT statement before calling this function. This function does not perform a COMMIT. You must perform a COMMIT to ensure that insertions are not lost in the case of a rollback. Parameters hWndTbl hSql bClearFlags Window Handle. The handle (or name) of a table window. Sql Handle. The handle of an INSERT statement. Boolean. Whether to reset the ROW_New flag. If TRUE, Centura clears the ROW_New flag of each inserted row; if FALSE, Centura 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. Return Value See Also bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoDeletes SalTblDoUpdates SalTblPopulate
Call SalTblDoInserts ( tblExample, hSql, FALSE )
Example
SalTblDoUpdates
Syntax Description bOk = SalTblDoUpdates ( hWndTbl, hSql, bClearFlags ) Applies a SQL UPDATE statement to all table window rows with the ROW_Edited flag set. You must prepare the SQL UPDATE statement before calling this function. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the updates are not lost in the case of a rollback. Parameters hWndTbl hSql bClearFlags Window Handle. The handle (or name) of a table window. Sql Handle. The handle of an UPDATE statement. Boolean. Whether to reset the ROW_Edited flag. If TRUE, Centura clears the ROW_Edited flag of each changed row; if FALSE, Centura does not clear the ROW_Edited flag of each changed row. This is useful for error handling; if an error occurs, you can roll back the transaction and try again. Return Value See Also bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoDeletes SalTblDoInserts SalTblPopulate
Call SalTblDoUpdates ( tblExample, hSql, FALSE )
Example
SalTblFetchRow
Syntax Description nResult = SalTblFetchRow ( hWndTbl, nRow ) Sends a SAM_FetchRow message to a table window if the row you specify is not currently in the table window cache. To process the SAM_FetchRow message, fetch the row from the database or another data source. The SAM_FetchRow message sets the context row to the row you specify before the table window receives the message. Parameters hWndTbl nRoNumber. Return Value Window Handle. The handle (or name) of the table window that owns the row being retrieved. The row number.
nResult is one of these values: TBL_RowDeleted, TBL_RowFetched, TBL_NoMoreRows.
2-175
Chapter
See Also Example
SalTblQueryContext SalTblSetContext
Call SalTblFetchRow ( hWndtblTelephone, nMaxRange )
SalTblFindNextRow
Syntax Description bOk = SalTblFindNextRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff ) Scans forward in a table looking for a row whose flags match those specified. The search stops at the first row that has any of the nFlagsOn flags set, and none of the nFlagsOff flags set. Use this function in a loop to find all the table window rows that match specified conditions. You do not need to increment the row number; Centura 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 Centura constant, and nRow is a receive parameter whose value the function can change.
Parameters
hWndTbl nRow
Window Handle. The handle of the table window to search. Receive Number. The row at which to begin the search; the search starts on nRow + 1. If Centura finds a row, it returns its row number in this parameter. Number. The flags the row should have. Number. The flags the row should not have. Specify zero (0) for no flags. You can specify any of the ROW_* flags for nFlagsOn and nFlagsOff. If you want to specify more than one, combine them using the OR (|) operator.
nFlagsOn nFlagsOff
bOk is TRUE if Centura finds a row and FALSE if there are no matches. SalTblFindPrevRow SalTblSetFlagsAnyRows
Example
If SalTblFindNextRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )
SalTblFindPrevRow
Syntax Description bOk = SalTblFindPrevRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff ) Scans backward in a table looking for a row whose flags match those specified. The search stops at the first row that has any of the nFlagsOn flags set, and none of the nFlagsOff flags set. Use this function in a loop to find all the table window rows that match specified conditions. You do not need to decrement the row number; Centura 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 Centura 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 Centura finds a row, it returns its row number in this parameter. nFlagsOn nFlagsOff Number. The flags the row should have. Number. The flags the row should not have. Specify zero (0) for no flags. You can specify any of the ROW_* flags for nFlagsOn and nFlagsOff. If you want to specify more than one, combine them using the OR (|) operator. Return Value See Also Example bOk is TRUE if Centura finds a row and FALSE if there are no matches. SalTblFindNextRow SalTblSetFlagsAnyRows
If SalTblFindPrevRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )
2-177
Chapter
SalTblGetColumnText
Syntax Description Parameters bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText ) Gets data from a column of a table window's context row. hWndTbl nColumnID strText Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The Column Identifier Receive string. The column data.
bOk is TRUE if the function succeeds and FALSE if it fails. SalTblSetColumnText

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

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

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

Call SalTblKillFocus ( hWndForm )
SalTblPasteRows
Syntax Description bOk = SalTblPasteRows ( hWndTbl ) Pastes the contents of the Clipboard to the specified table window. Centura assumes the Clipboard data is in text format with cells delimited by tab characters and rows delimited by end-of-line characters. Centura inserts the new rows into the table window without overwriting existing rows, and converts the data to the data types of the corresponding table window columns. Parameters Return Value See Also Example hWndTbl Window Handle. The handle (or name) of the table window receiving the data from the Clipboard.
bOk is TRUE if the Clipboard contains text that is successfully inserted into the table window, and FALSE otherwise, and if none of the columns are editable. SalTblCopyRows
Call SalTblPasteRows ( tblPhoneList )
SalTblPopulate
Syntax Description bOk = SalTblPopulate( hWndTbl, hSql, strSelect, nMethod ) Compiles, binds, and executes a SQL SELECT statement, then fetches the rows of the result set and populates a table window with them. SalTblPopulate also manages table window browsing. This function also works with table windows that do not have columns. Centura 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, Centura 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. The SAM_FetchRow message is sent before the row is actually fetched from the result set so in processing this message, you cannot refer to the row being fetched. However, the SAM_FetchRowDone message is sent after the row is fetched, enabling you to refer to the row just fetched. Parameters hWndTbl hSql Window Handle. The handle (or name) of the table window to populate. Sql Handle. The handle of the SELECT statement. Do not use the Sql Handle passed to SalTblPopulate by other functions while the table window is in use. String. The SELECT statement. If the string is null (), Centura uses the previously prepared SELECT statement associated with hSql. This avoids re-preparing the statement each time SalTblPopulate executes. Number. How to populate the table window. Specify one of these values: TBL_FillAll TBL_FillAllBackground TBL_FillNormal Return Value See Also bOk is TRUE if the function succeeds and FALSE if either hWndTbl or hSql is invalid. SalTblDeleteSelected SalTblDoDeletes SalTblDoInserts SalTblDoUpdates
Call SalTblPopulate ( tblExample, hSql, strSql, TBL_FillAllBackground )
strSelect
nMethod
Example
2-181
Chapter
SalTblQueryCheckBoxColumn
Syntax Description Parameters bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue ) If the column is defined as a check box, this function retrieves information about the check box and returns TRUE. If it is not a check box, this function returns FALSE. hWnd HWndCol nFlags Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column. Receive Number. nFlags is a combination of the following flags using the '|' operator: COL_CheckBox_IgnoreCase = 0x0001 Receive String. sCheckedValue is the value that a cell will get when the check box is checked. Receive String. The value when a check box is unchecked.
sCheckedValue sUncheckedValue Return Value Example

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

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

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

Set nContext = SalTblQueryContext ( hWndTbl )
SalTblQueryDropDownListColumn
Syntax Description Parameters bOk = SalTblQueryDropDownListColumn( hWnd, hWndCol, nFlags, nLines ) If the column is defined as a drop down list, this function retrieves information about the list and returns TRUE. If it is not a drop down list, this function returns FALSE. hWnd HWndCol Window Handle. The handle (or name) of a table window. Window Handle. The handle (or name) of a table window column.
nFlags
Receive 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_Editable=0x0008 Receive Number. nLines indicates the maximum number of lines to display in the list.

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

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

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

Call SalTblQueryScroll ( hWndTbl, nPosRow, nMinRow, nMaxRow )
SalTblQuerySplitWindow
Syntax Description Parameters bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax bDragAdjust ) Specifies how a table window is split horizontally. hWndTbl nRowLowerHalf bDragAdjust Window Handle. The handle (or name) of a split table window. Receive Number. The number of visible rows in the lower half of the split window. If zero (0), the table is not split. Receive Number Boolean. Specify whether (TRUE) or not (FALSE) the user can drag-adjust the visible rows in both halves of a split window.
Return Value
Example
Set bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax,bDragAdjust )
SalTblQueryTableFlags
Syntax Description Parameters bSet = SalTblQueryTableFlags ( hWndTbl, nFlags ) Tests the state of a table window's flags. hWndTbl nFlags Return Value See Also Example Window Handle. The handle (or name) of a table window. Number. The table flags to test. You can combine TBL_* flags using the OR (|) operator.
bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise. SalTblSetTableFlags
If SalTblQueryTableFlags ( tbl1, TBL_Flag_MoveableCols ) Set rbColsMovable = TRUE
SalTblQueryVisibleRange
Syntax Description Parameters bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax ) Returns the current range of visible rows in a table window. hWndTbl nRangeMin nRangeMax Return Value Example Window Handle. The handle (or name) of a table window. Receive Number. The first visible row. Receive Number. The last visible row.

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

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

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

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

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

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

Call SalTblSetTableFlags ( tbl1, TBL_Flag_MoveableCols, FALSE)
2-197
Chapter
SalTblSortRows
Syntax Description bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder ) Sorts the rows of a non-discardable table window based on the values in one of the table window's columns. You must create this column at design time; it cannot be an automatic column such as a column created by SalTblPopulate. or SalTblCreateColumn. Important: The table window cache must not be discardable and the setting of
maximum rows in memory must be large enough to hold the rows that you are sorting.
Parameters
hWndTbl nColumnID nOrder
Window Handle. The handle (or name) of a table window. Number. The Column Identifier of the column by which to sort. Number. The direction of the sort. Specify either:
TBL_SortDecreasing TBL_SortIncreasing
bRet is TRUE if the function succeeds and FALSE if nColumnID is not a valid identifier.
Set bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )
SalTimerKill
Syntax Description bOk = SalTimerKill ( hWnd, nIDEvent ) Destroys an object's system timer. Centura removes any pending SAM_Timer messages from the message queue of hWnd. Set a system timer with the SalTimerSet function. Parameters hWnd nIDEvent Return Value See Also Example Window Handle. The handle (or name) of an object. Number. The timer ID to kill.
bOk is TRUE if Centura successfully kills the event and FALSE if Centura cannot find the specified timer. SalTimerSet
On SAM_Destroy Call SalTimerKill ( dfClock, 1 )
SalTimerSet
Syntax Description bOk = SalTimerSet ( hWnd, nIDEvent, nElapseMilliSec ) Creates a system timer for a given object. When a timer event occurs, Centura 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 nIDEvent nElapseMilliSec Window Handle. The handle (or name) of an object associated with a system timer. Number. The timer ID number. Number. The elapsed time between each SAM_Timer message. The maximum value is 65535 (approximately 65 seconds). If you set this parameter to a higher value, it wraps. Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SalTimerKill
On SAM_Create Set bOk = SalTimerSet ( hWndItem, 1, 1000 )
SalTrackPopupMenu
Syntax Description Parameters bOk = SalTrackPopupMenu ( hWndProcMsgs, strMenuName, nFlags, nX, nY ) Creates pop-up menus at runtime. hWndProcMsgs strMenuName Window Handle. The handle (or name) of the top-level window that processes messages generated by the pop-up menu. String. The name of a pop-up menu accessible to hWndProcMsgs. For example, a menu defined by hWndProcMsgs or its MDI window parent, or a global menu. Number. Specifies how the pop-up menu displays. You can combine flag values using the OR (|) operator. Number. The position of the pop-up menu on the X axis. The value of this parameter is ignored if you set the TPM_CursorX flag in nFlags.
nFlags nX
2-199
Chapter
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. Return Value Example bOk is TRUE if the function succeeds and FALSE if it fails.
On SAM_Click Call SalTrackPopupMenu ( hWndForm, 'menuEdit', TPM_CursorX | TPM_CursorY | TPM_CenterAlign, 0, 0 )
SalUpdateWindow
Syntax Description bOk = SalUpdateWindow ( hWndUpdate ) Forces Centura 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 Centura 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, Centura delays repainting the list box until it completes processing the loop. To force Centura to repaint the list box before processing the loop, call SalUpdateWindow. Parameters Return Value See Also Example hWndUpdate Window Handle. The handle (or name) of the window to update.
bOk is TRUE if the function succeeds and FALSE if hWndUpdate is not a valid window handle. SalInvalidateWindow
Message Actions On SAM_FieldEdit Call SalUpdateWindow ( ml1 )
SalUseRegistry
Syntax Description bOk = SalUseRegistry( bUseRegistry, sCompanyName ) This function is used to re-direct all SalProfile* functions to use the Registry. All values for the SalProfile* functions are saved as strings. The INI file name used as the last parameter of the SalProfile* functions will be used as the application name. The resulting path will be:
\\HKEY_CURRENT_USER\Software\<company name>\<application name>\<section>\<setting>\
Parameters
bUseRegistry sCompanyName
- TRUE if registry is to be used, FALSE if INI files are to be used. - Name of company to be used under the registry.
bOk is TRUE if the function succeeds and FALSE if function fails.

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

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

Set sClassName = SalWindowClassName( hWnd )
SalWindowGetProperty
Syntax Description Parameters bOk = SalWindowGetProperty( hWndQO, strPropName, strPropValue ) Gets the value of a named property for an instance of a QuickObject. The property must have been created at designtime with the QuickObject Editor. hWndQO strPropName strPropValue Return Value Example Window Handle. The window handle of an instance of a QuickObject. String. The name of the property. Receive String. The value of the property.
bOk is TRUE if the function succeeds and FALSE if it fails. This example gets a window name property:
Set bOk = SalWindowGetProperty( hWndItem, 'WindowName', strWindowName )
SalWindowHandleToNumber
Syntax Description nWnd = SalWindowHandleToNumber ( hWnd ) Converts a window handle to a number. For example, you can pass a window handle as a SalSendMsg wParam parameter as follows: nWnd = SalWindowHandleToNumber ( hWndParm ) Call SalSendMsg ( hWndDest, nMsg, nWnd, 0 ) Parameters Return Value See Also Example hWnd Window Handle. The handle to convert.
nWnd is the number converted from hWnd. SalNumberToWindowHandle

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

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

Set bOk = SqlClose ( hSql )
SqlCommit
Syntax Description bOk = SqlCommit ( hSql ) Commits all of the SQL transaction's cursors that are connected to the same database. NOTE: To prevent destroying a cursor's result set when a COMMIT is performed, turn on cursor context preservation by calling SqlSetParameter and setting the DBP_PRESERVE parameter to TRUE. Parameters Return Value Example hSql Sql Handle. A handle that identifies a database connection.

Call SqlCommit ( hSql )
SqlConnect
Syntax Description bOk = SqlConnect ( hSql ) Connects to a database. Centura uses the values in the SqlDatabase, SqlUser, and SqlPassword variables. The default values for these variables are DEMO, SYSADM, and SYSADM. The value of other system variables such as SqlNoRecovery, SqlInMessage, and SqlOutMessage take effect after this function executes. Parameters Return Value See Also Example hSql Receive Sql Handle. A handle that identifies a database connection.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlDisconnect

Call SqlConnect ( hSqlPrimary )
2-207
Chapter
SqlContextClear
Syntax Description bOk = SqlContextClear ( hSql ) Clears the context set by SqlContextSet. Centura evaluates the bind and INTO variables associated with the specified Sql Handle in the local context. For new applications, call SqlVarSetup instead of this function. Parameters Return Value See Also Example hSql Sql Handle. A handle that identifies a database connection.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlContextSet SqlContextSetTo Form
Set bOk = SqlContextClear ( hSql )
SqlContextSet
Syntax Description bOk = SqlContextSet ( hSql ) Sets the context for future processing (for example, calls to SqlPrepare, SqlFetchNext, SqlFetchPrevious, and SqlFetchRow). Sql* functions you call after SqlContextSet behave as if they are in the window identified by hWndForm. Call this function in a class to perform SQL processing for the current window without fully qualifying bind and INTO variables. This function is also useful for global functions. Important: After you call SqlContextSet, the context for bind variables and INTO variables is always hWndForm. If you call a Sql* function in an internal function, window function, or class function after calling SqlContextSet, Centura does not recognize local variables or Parameters that you use as bind variables and INTO variables. For new applications, call SqlVarSetup instead of this function. Parameters Return Value See Also Example hSql Sql Handle. A handle that identifies a database connection.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlContextClear SqlContextSetTo Form
Set bOk = SqlContextSet ( hSql )
SqlContextSetToForm
Syntax Description bOk = SqlContextSetToForm ( hSql, hWndMyForm) This function is like SqlContextSet, except for an additional parameter: SqlContextSet sets the context of the Sql Handle to the window identified by hWndForm; SqlContextSetToForm sets the context of the Sql Handle to the window you specify in the second parameter. Call this function from a child table window when you want to set the context to the parent form window; in this situation hWndForm refers to the child table window, not to the parent form window. For new applications, call SqlVarSetup instead of this function. See Also Example SqlContextClear SqlContextSet
Set bOk = SqlContextSetToForm ( hSql, hWndMyForm)
SqlDirectoryByName
Syntax Description Parameters bOk = SqlDirectoryByName ( strServerName, strArrayNames ) Returns the database names on the specified server. strServerName strArrayNames Return Value Example String. The name of a server. String Array. The name of an array of strings containing database names.

On SAM_AppStartup Call SqlDirectoryByName ( 'server1', strDatabaseNames )
SqlDisconnect
Syntax Description bOk = SqlDisconnect ( hSql ) Disconnects from a database. 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.
2-209
Chapter
bOk is TRUE if the function succeeds and FALSE if it fails. SqlConnect

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

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

Set bOk = SqlExecutionPlan ( hSql, strString, nLength )
SqlExists
Syntax Description bOk = SqlExists ( strSelect, bExists ) Determines whether a row exists. SqlExists uses the values of the SqlDatabase, SqlUser, and SqlPassword variables to connect to a database, and uses an internal Sql Handle to execute the specified query. Parameters strSelect bExists Return Value Example String. The SELECT statement that establishes the existence of a row. Receive Boolean. TRUE if the row exists and FALSE if it does not.
bOk is TRUE if strSelect is correct and executable and FALSE otherwise.

Call SqlExists ( 'SELECT * FROM ' || strTable || 'WHERE ' || strExistsColumn || ' = ' || '\'' || strExistsObject || '\'', bExists )
SqlExtractArgs
Syntax Description bOk = SqlExtractArgs ( wParam, lParam, hSql, nError, nPos ) Extracts information from the SAM_SqlError wParam and lParam arguments. Call this function only while processing a SAM_SqlError message which is sent when an error occurs while executing a SQL function.
Parameters
wParam lParam hSql nError nPos
Number. The value of the wParam argument of the SAM_SqlError message. Number. The value of the lParam argument of the SAM_SqlError message. Receive Sql Handle. The handle of the function that got an error. Centura extracts this value from the wParam argument. Receive Number. The error code. Centura extracts this value from the low-order word of the lParam argument. Receive number. The error position, if relevant to the function call. Centura extracts this value from the high-order word of the lParam argument.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlError SqlGetErrorPosition
Call SqlExtractArgs ( wParam, lParam, hSqlError, nSqlError, nErrorPos )
SqlFetchNext
Syntax Description Parameters bOk = SqlFetchNext ( hSql, nInd ) Fetches the next row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen. hSql nInd Return Value Sql Handle. The handle of a SELECT statement. Receive Number. The fetch return code is one of the FETCH_* values.
bOk is TRUE if another row was fetched and FALSE if no row was fetched. SqlFetchNext does not return FALSE and Fetch indicatior does not show EOF until you attempt to fetch past the last row. SqlFetchPrevious SqlFetchRow
Call SqlFetchNext ( hSqlPrimary, nRetVal )
See Also Example
2-213
Chapter
SqlFetchPrevious
Syntax Description bOk = SqlFetchPrevious ( hSql, nInd ) Fetches the previous row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen. hSql nInd Return Value See Also Sql Handle. The handle of a SELECT statement. Receive Number. The fetch return code is one of the FETCH_* values.
Parameters
bOk is TRUE if there is another row to fetch and FALSE otherwise. SqlFetchNext SqlFetchRow
Example
Call SqlFetchPrevious ( hSqlPrimary, nRetVal)
SqlFetchRow
Syntax Description bOk = SqlFetchRow ( hSql, nRow, nInd ) Fetches a row according to an absolute row position. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen. hSql Sql Handle. The handle of a SELECT statement.
Parameters
nRoNumber. The row number of the row to fetch. nInd Return Value See Also Example Receive Number. The fetch return code is one of the FETCH_* values.
bOk is TRUE if nRow could be fetched and FALSE otherwise. SqlFetchNext SqlFetchPrevious
Call SqlFetchRow ( hSqlPrimary, lParam, nRetVal )
SqlGetError
Syntax Description bOk = SqlGetError( hSql, nError, strErrorString ) Turns off backend error mapping and reports real backend errors.
Parameters
hSql nError strErrorString
Sql Handle. The handle of a SELECT statement. Number. The error number. String. The error text.
Return Value
bOk is TRUE if the function succeeds and FALSE if it fails. You specify the Sql Handle in hSql and SqlGetError returns the last error number and error text in nError and strErrorString. If the backend is SQLBase, this function does the same thing as calling SqlError and SqlGetErrorText.
Example
Set bOk = SqlGetError( hSql, nError, strErrorString )
SqlGetErrorPosition
Syntax Description bOk = SqlGetErrorPosition ( hSql, nPos ) 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 Centura detected aSyntax error. The first character position in the SQL statement is zero (0). hSql nPos Return Value See Also Example Sql Handle. The handle of a SELECT statement. Receive Number. The position in the SQL statement where aSyntax error occurred.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SqlExtractArgs

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

When SqlError Set sStatement = SqlGetLastStatement()
SqlGetModifiedRows
Syntax Description Parameters bOk = SqlGetModifiedRows ( hSql, nCount ) Returns the number of rows affected by the most recent INSERT, UPDATE, or DELETE statement. hSql nCount Return Value Example Sql Handle. The handle of a SQL statement. Receive Number. The number of rows affected.

Set bOk = SqlGetModifiedRows ( hSql, nCount )
SqlGetParameter
Syntax Description Parameters bOk = SqlGetParameter ( hSql, nParameter, nNumber, strString ) Gets the value of a database parameter. This function returns the parameter value in nNumber or strString as appropriate for the data type of the parameter. hSql nParameter nNumber Sql Handle. A handle that identifies a database connection. Number. The database parameter. Specify one of the DBP_* constants. Receive number. The value (TRUE or FALSE) of the parameter. If nParameter is DBP_BRAND, nNumber is one of the DBV_BRAND_* values. strString Return Value See Also Receive string. If you specify DBP_VERSION in nParameter, this is the version number.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameterAll SqlSetParameter SqlSetParameterAll
On SAM_AppStartup Call SqlGetParameter ( hSqlPrimary, DBP_LOCKWAITTIMEOUT, nTimeout, strNull )
Example
2-217
Chapter
SqlGetParameterAll
Syntax Description bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber ) Gets the value of a database parameter identified by a SQLP* constant value defined in SQL.H. This function returns the parameter value in nNumber or strString as appropriate for the data type of the parameter. Important: A set of the SQLP* constants in SQL.H have the same values as the
DBP_* constants, but the values identify different parameters. Be sure to specify the correct number.
Parameters
hSql nParameter nNumber
Sql Handle. A handle that identifies a database connection. Number. The database parameter. Specify the value of one of the SQLP* constants defined in SQL.H. Receive number. The value of nparameter it it is a number. Receive string. The value of nParameter if it is a string.
bNumber
Boolean. If TRUE, the parameter value is returned in nNumber. If FALSE, the parameter value is returned in strString.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameter SqlSetParameter SqlSetParameterAll
Set bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )
Example
SqlGetResultSetCount
Syntax Description bOk = SqlGetResultSetCount ( hSql, nCount ) Counts the rows in a result set by building the result set. Centura 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. 2-218 Centura Builder Function Reference
You must call SqlExecute before SqlGetResultSetCount. Parameters hSql nCount Return Value Example Sql Handle. A handle associated with a result set. Receive Number. The number of rows in the result set.

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

Call SqlGetRollbackFlag ( hSqlError, bRollbackFlag ) If bRollbackFlag ! Execute code to handle rolled back ! transaction
SqlImmediate
Syntax Description bOk = SqlImmediate ( strSqlCommand ) Prepares and executes a SQL statement. SqlImmediate actually performs a SqlConnect, a SqlPrepare, a SqlExecute, and for SELECT statements, a SqlFetchNext. The first time you call SqlImmediate, Centura performs all of these functions. On later calls, SqlConnect is not performed if not needed.
2-219
Chapter
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 Centura' internal handle. It uses the values of the SqlDatabase, SqlUser, and SqlPassword system variables to connect to a database. Any command that you execute with SqlImmediate, you can also execute with explicit calls to SqlConnect, SqlPrepare, SqlExecute or SqlOpen, and SqlFetchNext, for SELECTs. Parameters strSqlCommand String. The SQL statement to prepare and execute. This statement cannot have more than 128 bind variables and more than 128 INTO variables.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlClearImmediate

Call SqlImmediate ( 'INSERT INTO COMPANY ( COMPANY )' ||'VALUES ( :frmMain dfCompany )' )
SqlImmediateContext
Syntax Description bOk = SqlImmediateContext ( strSqlStatement ) Prepares and executes a SQL statement, and evaluates any bind or INTO variables in the context of the window identified by hWndForm. Call this function in a class to perform SQL processing for the current window without fully qualifying bind and INTO variables. This function is also useful for global functions. Important: When you call SqlImmediateContext, the context for bind variables and INTO variables is always hWndForm. If you call SqlImmediateContext in an internal function, window function, or class function, Centura does not recognize local variables or parameters that you use as bind variables and INTO variables. Parameters Return Value See Also Example strSqlStatement String. A SQL statement.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlContextClear SqlContextSet
Set bOk = SqlImmediateContext ( strSqlStatement )
SqlOpen
Syntax Description bOk = SqlOpen ( hSql, strCursorName ) Names a cursor and executes a SQL statement. Use this function to perform INSERTs, UPDATEs, and DELETEs on the current row. Call SqlOpen after SqlPrepare and before any of the SqlFetch* commands. Parameters hSql strCursorName Sql Handle. The handle associated with the SqlPrepare. String. A string containing the cursor name. Specify this name in the 'CURRENT OF <cursor_name>' or 'ADJUSTING <cursor_name>' clause of an INSERT, UPDATE, or DELETE statement. The value of this parameter is case insensitive. You can set it to null using the empty string (''). Return Value See Also Example bOk is TRUE if the function succeeds and FALSE if it fails. SqlClose SqlExecute
Set bOk = SqlOpen ( hSql, strCursorName )
SqlPLSQLCommand
Syntax Description bOk = SqlPLSQLCommand ( hSqlHandle, strCommand ) Use this function to execute PL/SQL stored procedures in Centura. 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. 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.
2-221
Chapter
Note: The SqlPLSQLCommand supports Centura dynamic arrays as input, output and input/
output arguments to Oracle7 PL/SQL stored procedures. Dynamic arrays of type NUMBER, STRING and DATE/TIME are supported.
Dynamic Arrays as INPUT arguments Dynamic arrays grow to the size of the largest index value used in an assignment statement using the dynamic array variables. For example: nDynvar[0] = 0 nnDynVar[1]= 1 nDynvar[9] = 9 causes nDynVar to be a dynamic array of 10 elements. When a dynamic array is passed as an INPUT argument to a PL/SQL stored procedure via SqlPLSQLCommand the number of elements created on the front-end are available on the backend. Thus in the backend stored procedure: insert into foo values(nDynVar(9)) will insert the value 9 into the table, while the statement insert into foo values(nDynVar(10)) will cause an error Attempting to fetch beyond end of result set. Uninitialized values Dynamic array values are not initialized on the front-end, but falling within the range of a dynamic array created on the front-end are passed as NULL for datatypes STRING and DATE/TIME and as zero for datatype NUMBER. To pass NUMBER as a NULL, the user must explicitly assign them as NUMBER_Null on the front-end; Dynamic Arrays as OUTPUT arguments The size of output arguments of type dynamic array is determined in the backend stored procedure . For example: sOutVar(1):= abc; sOutVar(10) := def; returns an array of size 10 to the front-end program. Uninitialized values Values for output arguments are not initialized on the backend, but are returned as NULL values.
Dynamic Arrays as INPUT/OUTPUT arguments INPUT / OUTPUT dynamic arrays behave as INPUT dynamic arrays on input and as OUTPUT dynamic arrays on OUTPUT. Parameters hSqlHandle strCommand Return Value Example Sql Handle. The connected SQL Handle to an Oracle database. String. Command string used to invoke a PL/SQL procedure.
bOK is TRUE if the function succeeds and FALSE if it fails.

If NOT SqlPLSQLCommand( hSql, 'INVOICES.INSERT_INVOICE (ninv_id, strClient, dt_inv_dt, nitem_No, nQnty, nAmt, nNum)' ) Set nSqlError = SqlError ( hSql! See ORACLE DOCUMENTATION ! for Error Listings
Note: If SqlPLSQLCommand receives an Invalid Object error from ORACLE when

executing a stored procedure, this means that a table referenced by the procedure was modified. To fix this problem, you need to force a recompile of that procedure. SqlPlSQLCommand does not automatically do this.
SqlPrepare
Syntax Description bOk = SqlPrepare ( hSql, strSqlStatement ) Compiles a SQL statement for execution. Compiling includes: Checking theSyntax of the SQL statement. Checking the system catalog. Processing a SELECT statement's INTO clause. An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 255 INTO variables per SQL statement. Identifying bind variables in the SQL statement. Bind variables contain input data for the statement. You can specify up to 2558 bind variables per SQL statement.
Follow this function with a SqlOpen, SqlExecute, SalTblDoInserts, SalTblDoUpdates, or SalTblDoDeletes, or fetches. Parameters hSql strSqlStatement Return Value Sql Handle. A handle that identifies a database connection. String. The SQL statement to compile.
2-223
Chapter
See Also Example
SqlExecute
Call SqlPrepare ( hSqlPrimary, 'INSERT INTO CUSTOMER ' || ' ( CUSTOMER ) VALUES ' ||'( :frmCustomer.dfCustomer )' )
SqlPrepareAndExecute
Syntax Description bOk = SqlPrepareAndExecute ( hSql, strSqlStatement ) Compiles and executes a SQL statement. Compiling includes: Checking theSyntax of the SQL statement. Checking the system catalog. Processing a SELECT statement's INTO clause. An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 128 INTO variables per SQL statement. Identifying bind variables in the SQL statement. Bind variables contain input data for the statement. You can specify up to 128 bind variables per SQL statement. Sql Handle. A handle that identifies a database connection. String. The SQL statement to compile and execute.
Parameters
hSql strSqlStatement
bOk is TRUE if the function succeeds and FALSE if it fails. SqlExecute SqlPrepare
Set bOk = SqlPrepareAndExecute ( hSql, 'Select name from' || ' employees into :df1' ) If bOk Call SqlFetchNext ( hSql, nInd )
SqlRetrieve
Syntax Description bOk = SqlRetrieve ( hSql, strName, strBindList, strIntoList ) Retrieves a SQLBase compiled command. To execute the command, you need only call SqlExecute. You do not need to compile the command with SqlPrepare because the command is compiled when it is stored with SqlStore. Parameters hSql strName strBindList Sql Handle. A handle that identifies a database connection. String. The name of the compiled command. String. A comma-separated list of up to 128 Centura bind variables. This list has the same number of variables as the compiled command. This string can be null. String. A comma-separated list of up to 128 Centura INTO variables. This list has the same (or less) number of INTO variables as named in the SELECT list of the compiled command. This string can be null (''), and should be null if the next command being executed is SalListPopulate.
strIntoList
bOk is TRUE if the function succeeds and FALSE if it fails. SqlDropStoredCmd SqlStore
Call SqlRetrieve ( hSqlPrimary, 'PRODUCTS', ':nPrice', ':strLBItem' )
SqlSetInMessage
Syntax Description bOk = SqlSetInMessage ( hSql, nSize ) Sets the size (in bytes) of the input message buffer for the specified Sql Handle. The input message buffer holds input for the application (such as the result of a query). There is one input message buffer per connected Sql Handle on the client computer. The database server (or gateway) maintains one input message buffer that is the size of the largest input message buffer on the client computer. When fetching data, as many rows as possible are compacted into one input message buffer. Each FETCH reads the next row from the input message buffer until they are exhausted. At this point, if you are accessing a SQLBase database, SQLBase transparently fetches the next input buffer of rows depending on the isolation level.
2-225
Chapter
A large input message buffer can improve performance because it reduces the number of network messages between the client and server. A large input message buffer can have a negative impact on concurrency, however, because any row currently in the buffer can have a shared lock on it (depending on the isolation level) which prevents other users from changing that row. Parameters hSql nSize Sql Handle. A handle that identifies a database connection. Number. The size (in bytes) of the input message buffer that you want to set. The default is 1 Kbyte and the maximum is 32 Kbtyes.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlSetOutMessage

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

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

On SAM_AppStartup Call SqlSetLockTimeout ( hSqlPrimary, 10 )
SqlSetLongBindDatatype
Syntax Description bOk = SqlSetLongBindDatatype( nBindVarNumber, nDatatype ) Sets the type of column (text or binary) that a Long String binds to. By default, Centura 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 Centura compiles bind variables at execute time. Use this function until Centura Software Corporation implements a native SAL binary long data type. Parameters nBindVarNumber nDatatype Number. The bind variable to set. The first bind variable in the SQL statement is 1, the second is 2, and so on. Number. The data type: 22 = text 23 = binary 24 = char \ long varchar > 254 Return Value Example bOk is TRUE if this function succeeds and FALSE if it fails.
Call SqlSetLongBindDatatype( 1, DT_Binary )
2-227
Chapter
SqlSetOutMessage
Syntax Description bOk = SqlSetOutMessage ( hSql, nSize ) Sets the size (in bytes) of the output message buffer for a specified Sql Handle. The output message buffer holds output from the application (such as a SQL command to compile or rows of data to insert into a database). There is an output message buffer for each connected Sql Handle on the client computer. At the same time, the database server (or gateway) maintains an output message buffer that is the size of the largest of its clients' output message buffers. A large output message buffer does not necessarily improve performance because the buffer only needs to be large enough to hold the largest SQL command to compile or the largest row of data to insert. (Rows are always sent to the database and inserted individually.) A large output message buffer can allocate space unnecessarily on both the client and the server, and it does not reduce network traffic. Parameters hSql nSize Return Value See Also Example Sql Handle. A handle that identifies a database connection. Number. The size (in bytes) of the output message buffer. The default is 1 Kbyte and the maximum is 32 Kbytes.
bOk is TRUE if the function succeeds and FALSE if it fails. SqlSetInMessage

On SAM_AppStartup Call SqlConnect ( hSqlPrimary ) Call SqlSetOutMessage ( hSqlPrimary, 1500 )
SqlSetParameter
Syntax Description Parameters bOk = SqlSetParameter ( hSql, nParameter, nNumber, strString ) Sets the value of a database parameter. Use the number (nNumber) and string (strString) arguments as appropriate for the data type of the parameter. hSql nParameter nNumber Sql Handle. A handle that identifies a database connection. Number. The database parameter to set. Specify one of the DBP_* constants. Number. The value of nParameter. Specify TRUE or FALSE for all but DBP_LOCKWAITTIMEOUT, for which you must specify a value in seconds. String. The value of nParameter.
strString
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameter SqlGetParameterAll SqlSetParameterAll
Call SqlSetParameter ( hSqlPrimary, DBP_PRESERVE, TRUE, strNull )
Example
SqlSetParameterAll
Syntax Description bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber ) Sets the value of a database parameter identified by a SQLP* constant value defined in SQL.H. This function uses the number (nNumber) and string (strString) parameters as appropriate depending on the data type of the value of the parameter. hSql nParameter nNumber strString bNumber Return Value See Also Sql Handle. The handle that identifies a database connection. Number. The database parameter to set. Specify the value of one of the SQLP* constants defined in SQL.H. Number. The value of nParameter if it is a number. String. The value of nParameter if it is a string. If TRUE, the parameter value is in nNumber. If FALSE, the parameter value is in strString.
Parameters
bOk is TRUE if the function succeeds and FALSE if it fails. SqlGetParameter SqlGetParameterAll SqlSetParameter
Set bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )
Example
SqlSetResultSet
Syntax Description bOk = SqlSetResultSet ( hSql, bSet ) Turns result set mode on or off. Result set mode is on by default in Centura. Parameters hSql bSet Return Value Sql Handle. A handle that identifies a database connection. Boolean. Turns result set mode on (TRUE) or off (FALSE).

2-229
Chapter
Example
Call SqlSetResultSet ( hSqlPrimary, FALSE )
SqlStore
Syntax Description bOk = SqlStore ( hSql, strName, strSqlCommand ) Stores and names a SQLBase compiled SQL statement. You do not need to call SqlPrepare before calling SqlStore. SqlStore compiles the SQL statement. You can specify up to 128 bind variables. Use numeric bind variables in the SQL statement, not variable names. For example: "SELECT * FROM PRESIDENT WHERE LASTNAME = :1 AND AGE > :2;". When you retrieve the stored command with SqlRetrieve, you specify the bind variable names in the INTO clause. For example, specify :dfLastName and :dfAge where dfLastName and dfAge are data fields on a form window. Before Centura 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, Centura 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, Centura 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. Parameters hSql strName strSqlCommand Return Value Sql Handle. A handle that identifies a database connection. String. The name of the stored command. String. The SQL statement to compile and store.
See Also Example
SqlDropStoredCmd SqlRetrieve
Set bOk = SqlStore ( hSql, strName, strSqlCommand )
VisArrayAppend
Syntax nNumItems = VisArrayAppend (hArySource, hAryTarget, nDataType) Number | String | Date/Time: hArySource[*] Number | String | Date/Time: hAryTarget[*] Number: nDataType Appends one array onto the end of another array. The source and target arrays must be defined as dynamic arrays, must be the same data type, and cannot be multidimensional arrays. hArySource hAryTarget nDataType Source array to append onto the end of the target. Target array, source array will be appended onto this array. Data type of both arrays. Options are: DT_Boolean DT_DateTime DT_Number DT_String DT_Handle Return Example Number: The number of total items in the target array after the append operation, if successful, or negative if an error occurs.
Variables: String: sSource[*] String: sTarget[*] ... Actions Set sSource[0] = "Source #1" Set sSource[1] = "Source #2" Set sTarget[0] = "Target #1" Call VisArrayAppend (sSource, sTarget, DT_String) ! sTarget contains 'Target #1' ! 'Source #1' ! 'Source #2'
Description
Parameters
2-231
Chapter
VisArrayCopy
Syntax nNumItems = VisArrayCopy (hArySource, hAryTarget, nDataType) Number | String | Date/Time: hArySource[*] Number | String | Date/Time: hAryTarget[*] Number: nDataType Copies one array into another. After this call the two arrays will be identical. The source and target arrays must be defined as dynamic arrays, must be the same data type, and cannot be multi-dimensional arrays. hArySource hAryTarget nDataType Source array to copy into the target. Target array, source array will be copied into this array, replacing its current contents. Data type of both arrays. Options are: DT_Boolean DT_DateTime DT_Number DT_String DT_Handle Return Example Number: The number of items in the target array, if successful, or negative if an error occurs.
Variables: String: sSource[*] String: sTarget[*] ... Actions Set sSource[0] = "Source #1" Set sSource[1] = "Source #2" Set sTarget[0] = "Target #1" Call VisArrayCopy (sSource, sTarget, DT_String) ! sTarget contains 'Source #1' ! 'Source #2'
Description
Parameters
VisArrayDeleteItem
Syntax nNumItems = VisArrayDeleteItem (hAry, nIndex, nDataType) Number | String | Date/Time: hAry[*] Number: nIndex Number: nDataType Deletes an item from an array. All subsequent items will be moved up in the array. The array cannot be a multi-dimensional array. hAry nIndex nDataType Array to delete item from. Index of item to delete. Data type of the array. Options are: DT_Boolean DT_DateTime DT_Number DT_String DT_Handle Return Example Number: The number of items in the array after the deletion, if successful, or negative if an error occurs.
Variables String: sString[*] ... Actions Call VisArrayDeleteItem (sString, 3, DT_String)
Description Parameters
VisArrayFillDateTime
Syntax bOk = VisArrayFillDateTime (dtDateTimes, dtValue, nCount) Date/Time: dtDateTimes[*] Date/Time: dtValue Number: nCount Fills a Date/Time array with a specified date/time value. This function is useful for initializing an array. The array cannot be a multi-dimensional array. dtDateTimes dtValue nCount Return Date/Time array to fill. Value to fill in each element of array. Number of items to fill.
Boolean: TRUE if successful, or FALSE if an error occurs.
2-233
Chapter
Example
Variables Date/Time: dtSample[*] ... Actions Call VisArrayFillDateTime (dtSample, DATETIME_Null, 5)
VisArrayFillNumber
Syntax bOk = VisArrayFillNumber (nNumbers, nValue, nCount) Number: nNumbers[*] Number: nValue Number: nCount Fills a number array with a specified value. This function is useful for initializing an array. The array cannot be a multi-dimensional array. nNumbers nValue nCount Return Example Number array to fill. Value to fill in each element of array. Number of items to fill.

Variables Number: nSample[*] ... Actions Call VisArrayFillNumber (nSample, NUMBER_Null, 5)
VisArrayFillString
Syntax bOk = VisArrayFillString (sStrings, sValue, nCount) String: sStrings[*] String: sValue Number: nCount Fills a string array with a specified string. This function is useful for initializing an array. The array cannot be a multi-dimensional array. sStrings sValue nCount Return String array to fill. String value to fill in each element of array. Number of items to fill.
Related Functions Example

Variables String: sSample[*] ... Actions Call VisArrayFillString (sSample, '', 5)
VisArrayFindDateTime
Syntax nIndex = VisArrayFindDateTime (dtDateTimes, dtSearchFor) Date/Time: dtDateTimes[*] Date/Time: dtSearchFor Locates a date/time value within an array. The array cannot be a multi-dimensional array. dtDateTimes dtSearchFor Return Date/Time array to search. Date/Time value to search for.
Number: The index of the item found, if successful, or negative if not found.
Variables Date/Time: dtMyDates[*] Number: nIndex ... Actions ! Populate Array Set nIndex = VisArrayFindDateTime (dtMyDates, 10/10/88) If nIndex >= 0 ! Item found Else ! Item not found
VisArrayFindNumber
Syntax nIndex = VisArrayFindNumber (nNumbers, nSearchFor) Number: nNumbers[*] Number: nSearchFor Locates a number within an array. The array cannot be a multi-dimensional array. nNumbers Number array to search.
2-235
Chapter
nSearchFor Return
Number to search for.
Variables Number: nMyNumbers[*] Number: nIndex ... Actions ! Populate Array Set nIndex = VisArrayFindNumber (nMyNumbers, 76) If nIndex >= 0 ! Item found Else ! Item not found
VisArrayFindString
Syntax nIndex = VisArrayFindString (sStrings, sSearchFor) String: sStrings[*] String: sSearchFor Locates a string within an array. The entire specified string is compared to each array item. The array cannot be a multi-dimensional array. sStrings sSearchFor Return Example String array to search. String to search for.
Variables Number: nMyString[*] Number: nIndex ... Actions ! Populate Array Set nIndex = VisArrayFindString (nMyNumbers, 'Marc') If nIndex >= 0 ! Item found Else ! Item not found
VisArrayInsertItem
Syntax nNumItems = VisArrayInsertItem (hAry, nIndex, nDataType) Number | String | Date/Time: hAry[*] Number: nIndex Number: nDataType Inserts an item into an array. All subsequent items will be moved down in the array. The inserted item is initialized to a null value. The array cannot be a multidimensional array. hAry nIndex nDataType Array to insert item into. Index number where item should be inserted. Data type of the array. Options are: DT_Boolean DT_DateTime DT_Number DT_String DT_Handle Return Number: The number of items in the array after the insertion, if successful, or negative if an error occurs.
Description
Parameters
Related Functions VisArrayDeleteItem Example

Variables String: sString[*] ... Actions ! Populate Array Call VisArrayInsertItem (sString, 3, DT_String)
VisArraySort
Syntax nNumItems = VisArraySort (hAry, nSortOrder, nDataType) Number | String | Date/Time: hAry[*] Number: nSortOrder Number: nDataType Sorts an array in either ascending or descending order. The array cannot be a multidimensional array. hAry Array to sort.
2-237
Chapter
nSortOrder
Flag indicating sort order. SORT_Ascending SORT_Descending Indicates the data type for the array.
nDataType Return Example
Number: The number of items in the array, if successful, or negative if an error occurs.
Variables String: sDirs[*] ... Actions Call VisArraySort (sDirs, SORT_Ascending, DT_String)
VisDebugAssert
Syntax bOk = VisDebugAssert (bExpression, sDebugString) Boolean: bExpression String: sDebugString Asserts that a condition is true. If expression is FALSE, the debug message specified will be displayed in a message box. This function is typically used in a development environment to provide an indication that an internal, potentially fatal, error occurred. bExpression sDebugString Condition to be tested. The condition may be a constant, expression, or variable. Debug message to display if condition is FALSE. The Centura name of the current window will be prepended to sDebugString before displaying.
Description
Parameters
Return Example
Boolean: Always returns TRUE.

Variables Window Handle: hWnd ... Actions Set hWnd = SalCreateWindow (dbTest, dbParent) Call VisDebugAssert (hWnd, 'dbTest not created')
VisDebugBeginTime
Syntax Description Parameters Return bOk = VisDebugBeginTime () Begins timing an operation. VisDebugBeginTime must be called before VisDebugSetTime or VisDebugEndTime. No parameters. Boolean: Always returns TRUE.
Related Functions VisDebugEndTime, VisDebugSetTime Example

Actions Call VisDebugBeginTime () Call SqlPrepare (hSql, 'Select...') Call VisDebugSetTime ('SqlPrepare') Call SqlExecute (hSql) Call VisDebugSetTime ('SqlExecute')
VisDebugEndTime
Syntax Description bOk = VisDebugEndTime (sContext, nDebugLevel) String: sContext Number: nDebugLevel Stops recording the time and displays all incremental times and the total time. All times are displayed in the debug application window (DBWIN.EXE) or in a message box depending on the current debug flags. sContext nDebugLevel Context string describing the total time. Minimum debug level before performance time will be displayed. Specify zero to always display the message. Typically, the higher the debug level, the greater the number of debug messages displayed.
Parameters
Return
Related Functions VisDebugBeginTime, VisDebugSetTime Example

Actions Call VisDebugBeginTime () Call SqlPrepare (hSql, 'Select...')
2-239
Chapter
Call VisDebugSetTime ('SqlPrepare') Call SqlExecute (hSql) Call VisDebugSetTime ('SqlExecute') Set nRow = 0 While SqlFetchRow (hSql, nRow) ... Call VisDebugSetTime ('SqlFetchRow') Call VisDebugEndTime ('Query #1', 0)
VisDebugGetFlags
Syntax Description Parameters Return nDebugFlags = VisDebugGetFlags () Retrieves the current debug flags. No parameters. Number: The current debug bit flags. To test a bit flag, use the bitwise AND (&) operator. DBF_IncrementalTime DBF_RealTime DBF_MessageBox Related Functions VisDebugSetFlags Example
Variables Number: nDebugFlags ... Actions Set nDebugFlags = VisDebugGetFlags () If nDebugFlags & DBF_MessageBox ...
VisDebugSetFlags
Syntax Description Parameters bOk = VisDebugSetFlags (nDebugFlags, bMode) Number: nDebugFlags Boolean: bMode Sets debug flags. nDebugFlags Bit flags to set or clear. May be any of the following: DBF_IncrementalTime 2-240 Centura Builder Function Reference
bMode Return
DBF_RealTime DBF_MessageBox TRUE to set the flags, FALSE to clear the flags.
Related Functions VisDebugGetFlags Example

Actions Call VisDebugSetFlags (DBF_MessageBox, TRUE)
VisDebugSetLevel
Syntax Description Parameters Return Example bOk = VisDebugSetLevel (nDebugLevel) Number: nDebugLevel Sets the current debug level. The debug level allows selective debug messages to be displayed. nDebugLevel Current debug level. Debug messages must be equal or greater than the current debug level to be displayed.

Actions Call VisDebugSetLevel (0)
VisDebugSetTime
Syntax Description bOk = VisDebugSetTime (sContext) String: sContext Records the time since the last VisDebugSetTime or VisDebugBeginTime call. This function records an incremental time. The time will not be displayed in the debug application until a VisDebugEndTime call is made. The context string will be displayed to the left of the time. sContext Context string describing the time interval.
Parameters Return
Related Functions VisDebugBeginTime, VisDebugEndTime Example

Set bOk = VisDebugSetTime (sContext)
2-241
Chapter
VisDebugString
Syntax bOk = VisDebugString (sDebugString, nDebugLevel) String: sDebugString Number: nDebugLevel Writes a string to the debug application window. If the debug application is not running, this function performs no action. If the DBF_MessageBox flag is set, a message box will be displayed. sString nDebugLevel String to write to debugging terminal. Debug level. Specify zero to always display the message. Typically, the higher the debug level, the greater the number of debug messages displayed.
Description
Parameters
Return
Related Functions VisDebugSetLevel Example

Pushbutton: pbOk ... Message Actions On SAM_Click Call VisDebugString ('SAM_Click in pbOk', 0)
VisDosBuildFullName
Syntax sFullName = VisDosBuildFullName (sModuleName, sFileName) String: sModuleName String: sFileName Builds a file name with drive and full directory based on the location of a running executable. The path of the result file is the location of the executable when Windows loaded it into memory. The directory structure on disk is not used in any way to build the path. This function may be used to locate supplemental files (i.e. INI files, etc.) without a DOS PATH established to the application. This function does not check for the existence of the full file name returned. sModuleName Module name to use for building the full file name. Specify just the base name, no drive, path, or extension. This name must be the base name of a loaded EXE or DLL file.
Description
Parameters
sFileName
File name to concatenate with path of module name. Specify just the base name and extension, no drive or directory. Any drive or directory specified is ignored.
Return Example
String: A string containing the full file name (drive, path, and file name), or a null string if an error occurs.
Variables String: sFileName ... Actions Set sFileName = VisDosBuildFullName ('swinapp', 'options.ini') Call VisFileOpen (sFileName, OF_Read)
VisDosEnumDirInfo
Syntax nNumDirs = VisDosEnumDirInfo (sDirSpec, sDirs, dtDateTimes, nAttributes) String: sDirSpec Receive String: sDirs[*] Receive Date/Time: dtDateTimes[*] Receive Number: nAttributes[*] Retrieves all subdirectories for a given directory into a Centura array, also returns the date/time the directory was created and the attributes of the directory. sDirSpec sDirs dtDateTimes nAttributes Returns Directory to search, must include wildcard characters. Array to contain the subdirectories. Array to contain the date/time each subdirectory was created. Array to contain the attributes of each subdirectory.
Number: The number of items returned in sDirs, dtDateTimes and nAttributes, or negative if an error occurs.
Related Functions VisDosEnumFileInfo Example

Variables String: sDirs[*] Date/Time: dtDateTimes[*] Number: nAttributes[*] ... Actions
2-243
Chapter
Set nCount = VisDosEnumDirInfo ('c:\\windows\\*.*', sDirs, dtDateTimes, nAttributes If nCount >0
VisDosEnumDirs
Syntax nNumDirs = VisDosEnumDirs (sDirSpec, sDirs) String: sDirSpec Receive String: sDirs[*] Retrieves all subdirectories within a given directory into a Centura array. sDirSpec Directory to search, may include wildcard characters (? and *). It must be a valid DOS path. If no drive or directory is specified, the current drive and/or directory is used. Use a double backslash (\\) to represent a single backslash. Array to contain the subdirectories. Note that only directory names are returned, no leading or trailing backslashes.
sDirs Return
Number: The number of subdirectories returned into the specified array, or negative if an error occurs.
Related Functions VisDosEnumDrives, VisDosEnumFiles Example

Variables Number: nCount String: sDirs[*] ... Actions Set nCount = VisDosEnumDirs ('c:\\windows\\*.*', sDirs) If nCount > 0 Call VisListArrayPopulate (lbDirs, sDirs)
VisDosEnumDrives
Syntax Description nNumDrives = VisDosEnumDrives (sDrives) Receive String: sDrives[*] Retrieves all available drives into a Centura array, including floppy drives, hard disks, CD-ROM, network and RAM drives. To determine the type of each drive, call VisDosGetDriveType.
Parameters Return
sDrives
Array to contain the available drive letters (A:-Z:). The colon is always included.
Number: The number of available drives returned in the specified array.
Related Functions VisDosEnumDirs, VisDosEnumFiles Example

Variables Number: nCount String: sDrives[*] ... Actions Set nCount = VisDosEnumDrives (sDrives) If nCount > 0 Call VisListArrayPopulate (lbDrives)
VisDosEnumFileInfo
Syntax nNumFiles = VisDosEnumFileInfo (sDirSpec, nAttribute, sFiles, nSizes, dtDateTimes, nAttributes) String: sDirSpec Number: nAttribute Receive String: sFiles[*] Receive Number: nSizes[*] Receive Date/Time: dtDateTimes[*] Receive Number: nAttributes[*] Retrieves all files in a given directory into a Centura array, and returns each file's size, date/time, and attributes. If the source drive supports long file names, then the long name will be returned. sDirSpec nAttribute sFiles nSizes dtDateTimes nAttributes Directory to search, must include wildcard characters. Attribute bits to match. See the table below for a list of attributes. Array to contain the file names. Array to contain the size of each file. Array to contain the date/time each file was created. Array to contain the attributes of each file. May be one or more of the following values: FA_Standard
Description
Parameters
2-245
Chapter
FA_ReadOnly FA_Hidden FA_System FA_Archive Returns Number: The number of subdirectories returned in the specified array, or negative if an error occurs.
Related Functions VisDosEnumDirInfo Example

Variables String: sFiles[*] Number: Sizes[*] Date/Time: dtDateTimes[*] umber: nAttributes[*] ... Actions Set nCount = VisDosEnumFileInfo ('c:\\windows\\*.*', FA_Standard, sFiles, nSizes, dtDateTimes, nAttributes) If nCount >0 ...
VisDosEnumFiles
Syntax nNumFiles = VisDosEnumFiles (sFileSpec, nAttributes, sFiles) String: sFileSpec Number: nAttributes Receive String: sFiles[*] Retrieves all file names from a given directory into a Centura array. If the drive supports long file names, then the long name will be returned. sFileSpec Directory to search, may include wildcard characters (? and *). It must be a valid DOS path. If no drive or directory is specified, the current drive and/or directory is used. Use a double backslash (\\) to represent a single backslash. Attributes bits to match. This parameter may be one or more of the following values: FA_Standard FA_ReadOnly FA_Hidden
nAttributes
sFiles Return
FA_System FA_Archive Array to contain the file names. Note that only file names are returned, no drive or paths.
Number: The number of files returned in the specified array, or negative if an error occurs.
Related Functions VisDosEnumDirs, VisDosEnumFiles Example

Variables Number: nCount String: sFiles[*] ... Actions Set nCount = VisDosEnumFiles ('c:\\windows\\*.*', FA_ReadOnly | FA_Archive, sFiles) If nCount > 0 Call VisListArrayPopulate (lbFiles, sFiles)
VisDosEnumNetConnections
Syntax nNumLinks = VisDosEnumNetConnections (sDevices, sNetNames) Receive String: sDevices[*] Receive String: sNetNames[*] Retrieves all current network connections. Both sDevices and sNetNames will contain the same number of elements. The network name consists of a computer name and a share name, and may also include a path. The computer name uniquely identifies the network server, while the share name identifies the resource. If a path is given, it uniquely identifies a directory or file. For example, \\server\data\path, \\servers\laser. This follows the standard DOS naming convention for network devices. sDevices sNetNames Return Array to contain the connected devices (A:-Z:, LPT1:-LPT3:). Array to contain the network names.
Description
Parameters
Number: The number of devices connected, or negative if an error occurs.
Related Functions VisDosNetConnect, VisDosNetDisconnect
2-247
Chapter
Example
Variables Number: nCount String: sDevices[*] String: sNetPaths[*] ... Actions Set nCount = VisDosEnumNetConnections (sDevices, sNetNames) If nCount > 0 Call VisListArrayPopulate (lbDevices, sDevice)
VisDosEnumPath
Syntax Description nNumPaths = VisDosEnumPath (sDirs) Receive String: sDirs[*] Returns each directory in the DOS PATH environment string. Any nonexistent directories on the path are not returned. DOS does not support directories on the path with trailing backslashes. If a path directory contains a trailing backslash, it is not returned. A trailing backslash is added to each directory returned. This trailing backslash is helpful for scanning all path directories for a particular file. To scan, simply concatenate *.* onto the end of each directory returned and call VisDosEnumFiles. Parameters Return sDirs Array to contain the PATH directories.
Number: The number of valid directories found.
Related Functions VisDosEnumFiles Example

Variables String: sDirs[*] ... Actions Set nCount = VisDosEnumPath (sDirs) If nCount > 0 Call VisListArrayPopulate (lbPath, sDirs)
VisDosEnumsShortDirInfo
Syntax Description nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames, arrDateTime, arrAttribs ) Retrieves all long and short subdirectory names for a given directory into a Centura array, also returns the date/time the directory was created and the attributes for that directory. sDirName arrLongDirNames arrShortDirNames arrDateTime arrAttribs Return Parent Directory to retrieve subdirectory information from. Must include wildcard characters. Handle to array of long name subdirectories Handle to array of short name directories Handle to array of Date/Times when each subdirectory was created. Handle to array of attributes for each subdirectory.
Parameters
Returns the number of subdirectories in the arrays or negative if an error occured.
Related Functions VisDosEnumsShortDirs VisDosEnumsShortFileInfo VisDosEnumsShortFiles VisDosIsParent Example

Set nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames, arrDateTime, arrAttribs )
VisDosEnumsShortDirs
Syntax Description Parameters nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames ) Retrieves all long and short subdirectory names for a given directory into a Centura array. sDirName arrLongDirNames arrShortDirNames Return Parent Directory to retrieve subdirectory information from. Must include wildcard characters. Handle to array of long name subdirectories Handle to array of short name directories
Returns the number of subdirectories in the arrays or negative if an error occured.
2-249
Chapter
Related Functions VisDosEnumsShortDirInfo VisDosEnumsShortFileInfo VisDosEnumsShortFiles VisDosIsParent Example

Set nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames )
VisDosEnumsShortFileInfo
Syntax Description Parameters nSubFileNum = VisDosEnumsShortFileInfo (sDirName, nAttribBits, arrLongFileNames, arrShortFileNames, arrSizes, arrDateTime, arrAttribs ) Retrieves all long and short file names for a given directory into a Centura array, also returns each of the files sizes, date/time and attributes. sDirName nAttribBits arrLongFileNames arrShortFileNames arrSizes arrDateTime arrAttribs Return Directory to retrieve file information from. Must include wildcard characters. Attribute bits to match. Handle to array of long file names Handle to array of short file names Handle to array of file sizes. Handle to array of Date/Times for each file. Handle to array of attributes for each file.
Returns the number of files in the arrays or negative if an error occured.
Related Functions VisDosEnumsShortDirInfo VisDosEnumsShortDirs VisDosEnumsShortFiles VisDosIsParent Example

Set nSubFileNum = VisDosEnumsShortFileInfo (sDirName, nAttribBits, arrLongFileNames, arrShortFileNames, arrSizes, arrDateTime, arrAttribs)
VisDosEnumsShortFiles
Syntax Description Parameters nSubFileNum = VisDosEnumsShortFiles (sDirName, nAttribBits, arrLongFileNames, arrShortFileNames ) Retrieves all long and short file names for a given directory into a Centura array. sDirName nAttribBits arrLongFileNames arrShortFileNames Return Directory to retrieve file information from. Must include wildcard characters. Attribute bits to match. Handle to array of long file names Handle to array of short file names
Returns the number of files in the arrays or negative if an error occured.
Related Functions VisDosEnumsShortDirInfo VisDosEnumsShortDirs VisDosEnumsShortFileInfo VisDosIsParent Example

Set nSubFileNum = VisDosEnumsShortFiles (sDirName, nAttribBits, arrLongFileNames, arrShortFileNames )
VisDosExist
Syntax Description Parameters Return Example bOk = VisDosExist (sFileSpec) String: sFileSpec Tests for existence of a drive, directory, or file. If a directory is tested, any trailing backslash is ignored. If wildcards are used, files and directories are searched. sFileSpec Drive, directory, or file to test. It may contain a drive letter, directory, file name, full path or wildcard characters (? and *).
Boolean: TRUE if sFileSpec exists and FALSE if it does not.

If VisDosExist ... If VisDosExist ... If VisDosExist ... If VisDosExist ... If VisDosExist ('c:') ('c:\\dos') ('c:\\dos\\') ('c:\\dos\\command.com') ('c:\\dos\\*.exe')
2-251
Chapter
VisDosGetCurDir
Syntax Description Parameters Return sDir = VisDosGetCurDir (sDrive)String: sDrive Returns the current directory of a specified drive. sDrive Drive letter (A:-Z:) to retrieve the current directory for.
String: The current directory of the drive specified. If the drive is invalid, a null string is returned. The returned directory always contains the drive letter, path and a trailing backslash.
Variables String: sCurDir ... Actions Set sCurDir = VisDosGetCurDir (VisDosGetCurDrive()) If VisDosEnumFiles (sCurDir || '*.*',FA_Standard, sFiles) VisListArrayPopulate (lbFiles, sFiles)
Example
VisDosGetDriveSize
Syntax nErrCode = VisDosGetDriveSize (sDrive, nTotalSpace, nFreeSpace) String: sDrive Receive Number: nTotalSpace Receive Number: nFreeSpace Returns total space and available space on a drive. sDrive nTotalSpace nFreeSpace Return Drive letter to retrieve space information for, may include both a drive letter and colon. Total space on specified drive. Total available space on specified drive.
Number: VTERR_Ok if successful, or negative if an error occurs.
Related Functions VisDosEnumDrives, , VisDosGetDriveType Example

Variables Number: nTotalSpace Number: nAvailableSpace ... Actions
Call VisDosGetDriveSize ('c:', nTotalSpace, nAvailableSpace)
VisDosGetDriveType
Syntax Description Parameters Return nTypeFlags = VisDosGetDriveType (sDrive) String: sDrive Gets the type of drive specified. sDrive Number Drive letter to retrieve space information for, may include both a drive letter and colon. A flag indicating the drive type, or negative if an error occurs. DRIVE_Floppy DRIVE_Fixed DRIVE_Network DRIVE_CDROM DRIVE_RAM Related Functions VisDosEnumDrives, VisDosGetDriveSize Example
Variables Number: nType ... Actions Set nType = VisDosGetDriveType ('c:') Select Case nType Case DRIVE_Floppy ... Break Case DRIVE_Fixed ... Break
2-253
Chapter
VisDosGetEnvString
Syntax Description Parameters Return Example sEnvString = VisDosGetEnvString (sKeyName) String: sKeyName Returns an environment string based on a keyword. The keyword is the text before the = sign in the environment. For example, PATH = C:\DOS. sKeyName String to search for.
String: The environment variable contents. If the keyword cannot be found, a null string is returned.
Variables String: sTempDir ... Actions Set sTempDir = VisDosGetEnvString ('TEMP')
VisDosGetFlags
Syntax Description Parameters Return nFlags = VisDosGetFlags () Returns the state of DOS flags. No parameters. Number Any of the following bit flags. To test a bit value, use the bitwise AND (&) operator.
Related Functions VisDosSetFlags Example

Variables Number: nFlags ... Actions Set nFlags = VisDosGetFlags() If nFlags & DOS_VerifyFlag ... If nFlags & DOS_BreakFlag
VisDosGetNetName
Syntax Description sNetName = VisDosGetNetName (sDevice) String: sDevice Retrieves the network name for the specified device. The network name consists of a computer name and a share name, and may also include a path. The computer name uniquely identifies the network server, while the share name identifies the resource. If a path is given, it uniquely identifies a directory or file. For example, \\server\data\path, \\servers\laser. This follows the standard DOS naming convention for network devices. sDevice Pointer to device name (A:-Z:, LPT1:-LPT3:).
Parameters Return
String: The network name, if successful, or a null string if an error occurs.
Related Functions VisDosEnumNetConnections, VisDosNetConnect, VisDosNetDisconnect Example

Variables String: sNetName ... Actions Set sNetName = VisDosGetNetName ('f:')
VisDosGetVersion
Syntax Description Parameters Return nVersionNum = VisDosGetVersion () Returns the MS-DOS version number. None. Number: Both the major and minor (3.31) DOS version number.
Example
Variables Number: nVersion ... Actions Set nVersion = VisDosGetVersion ()
2-255
Chapter
VisDosGetVolumeLabel
Syntax Description Parameters Return sLabel = VisDosGetVolumeLabel (sDrive) String: sDrive Returns the volume label of a specified drive. sDrive Drive to retrieve volume label for.
String: The volume label of the specified drive, or negative if an error occurs.
Related Functions VisDosSetVolumeLabel Example

Variables String: sLabel ... Actions Set sLabel = VisDosGetVolumeLabel ('c:')
VisDosIsParent
Syntax Description Parameters Return bOk = VisDosIsParent (sDirSpec) String: sDirSpec Return indicator if directory contains subdirectories. sDirSpec Directory to test.
Boolean. TRUE if directory contains subdirectories, FALSE if not.
Related Functions VisDosEnumsShortDirInfo VisDosEnumsShortDirs VisDosEnumsShortFileInfo VisDosEnumsShortFiles Example

Set bOk = VisDosIsParent (sDirSpec)
VisDosMakeAllDir
Syntax Description nErrCode = VisDosMakeAllDir (sDir) String: sDir Creates all directories along the full path specified. For example, if c:\stuff\junk\newone is specified, the stuff, junk and newone directories are all created, if necessary. sDir Directory name to create, may contain a drive letter and/or full path. If path not specified, directory will be created on the current drive under the current directory. If sDir contains a trailing backslash, it is ignored.
Parameters
Returns Example

Actions If VisDosMakeAllDir ('c:\\stuff\\junk\\newone') != VTERR_Ok Call SalMessageBox ('Cannot create directory', 'Error', MB_Ok)
VisDosMakePath
Syntax sFileSpec = VisDosMakePath (sDrive, sDir, sBase, sExt) String: sDrive String: sDir String: sBase String: sExt Builds a full path from a drive, directory or file name. No existence check is performed on the result string. sDrive sDir sBase sEx Return Drive letter. Directory. Base portion of file name (8 characters before period). tFile extension (must include period).
String: The path after concatenating the drive, directory, and file name.
Related Functions VisDosSplitPath Example

Actions Set sFullName = VisDosMakePath ('c:', '\\dos\\', 'command', '.com')
2-257
Chapter
VisDosNetConnect
Syntax nErrCode = VisDosNetConnect (sDevice, sNetName, sPassword) String: sDevice String: sNetName String: sPassword Connects to a network device. The network name consists of a computer name and a share name, and may also include a path. The computer name uniquely identifies the network server, while the share name identifies the resource. If a path is given, it uniquely identifies a directory or file. For example, \\server\data\path, \\servers\laser. This follows the standard DOS naming convention for network devices. sDevice sNetName sPassword Return Device name (A:-Z:, LPT1:-LPT3:). Network device (\\server\directory). Password to network device (optional).
Description
Parameters
Related Functions VisDosEnumNetConnections, VisDosNetDisconnect Example

Actions If VisDosNetConnect ('f:','\\\\server\\data', 'cubswin') != VTERR_Ok
VisDosNetDisconnect
Syntax nErrCode = VisDosNetDisconnect (sDevice, bForce) String: sDevice Boolean: bForce Cancels a network connection. sDevice bForce Return Device name (A:-Z:, LPT1:-LPT3:). TRUE to force open files and print jobs to be closed.
Related Functions VisDosNetConnect Example

Actions Call VisDosNetDisconnect ('f:', TRUE)
VisDosSetFlags
Syntax nErrCode = VisDosSetFlags (nFlags, bState) Number: nFlags Boolean: bState Sets verify, break, or error mode flags. nFlags Bits indicating flags to set. May be any combination of the following values. To combine bit values, use the bitwise OR (|) operator. TRUE to turn the flag on, FALSE to turn the flag off.
bState Return
Number: Always returns zero.
Related Functions VisDosGetFlags Example

Actions Call VisDosSetFlags (DOS_VerifyFlag, TRUE)
VisDosSetVolumeLabel
Syntax nErrCode = VisDosSetVolumeLabel (sDrive, sLabel) String: sDrive String: sLabel Sets the volume label on a disk drive. sDrive sLabel Return Drive to set volume label for. Volume label to set. Limited to 11 characters
Related Functions VisDosGetVolumeLabel Example

If VisDosSetVolumeLabel ('c:', 'my_disk') != VTERR_Ok
2-259
Chapter
VisDosSplitPath
Syntax Void VisDosSplitPath (sFileSpec, sDrive, sDir, sBase, sExt) String: sFileSpec Receive String: sDrive Receive String: sDir Receive String: sBase Receive String: sExt Splits a full path specification into drive, directory, and file name. The end of the directory is located by searching backward for the last backslash. For example, c:\dos will be split into c:, \, and dos. sFileSpec sDrive sDir sBase sExt Return No return value Full path specification to split. Drive letter including colon. Directory always contains a leading and a trailing backslash (\DOS\). Base portion of file name (8 characters before period). File extension (always includes period).
Description
Parameters
Related Functions VisDosMakePath Example

Variables String: sDrive String: sDir String: sFile ... Actions Call VisDosSplitPath ('c:\\windows\\user.exe', sDrive, sDir, sFile, sExt) ! sDrive = 'c:' ! sDir = '\windows\' ! sFile = 'user' ! sExt = '.exe'
VisErrorRecovery
Syntax Description nErrCode = VisErrorRecovery (sCaption) String: sCaption Displays an error message and allows the user to free resources and retry the operation. This function should be called when a recoverable error has occurred. A recoverable error is caused by a temporary lack of resources, such as memory or disk space. sCaption Caption of error recovery dialog.
Parameters Return Example
Number: An action code depending on whether the user choose Retry or Abort pushbuttons:
If VisErrorRecovery ('Error') = ACTION_Abort Call SalQuit()
VisFileAppend
Syntax nErrCode = VisFileAppend (sSourceFile, sTargetFile) String: sSourceFile String: sTargetFile Appends one or more files to another. Wildcard characters are supported in the source file name. If wildcard character(s) are used, all matching files will be appended onto the target file. sSourceFile sTargetFile Source file specification to append. Target file name. If this file does not exist, an error is returned. File name specified may be in long format or in DOS 8.3 format.
Description
Parameters
Return
Number: The number of files appended, or negative if an error occurs.
Related Function s VisFileCopy, VisFileRename Example

Actions If VisFileAppend ('*.txt', 'all.txt') <0 Call SalMessageBox ('Error Occurred', 'Error', MB_Ok)
2-261
Chapter
VisFileClose
Syntax Description Parameters Return nErrCode = VisFileClose (hFile) File Handle: hFile Closes a file opened with the VisFileOpen call. Cannot be used with a file handle returned from SalFileOpen. hFile Handle to file returned from VisFileOpen.
Related Functions VisFileOpen Example

Set nErrCode = VisFileClose (hFile)
VisFileCopy
Syntax nErrCode = VisFileCopy (sSourceFile, sTargetFile) String: sSourceFile String: sTargetFile Copies one or more files. Wildcard characters are supported in both the source and target file names. If wildcards are used in the target, they must also be used in the same manner in the source. All attributes and date/times are preserved from the source to the target. This function operates up to 7 times faster than SalFileCopy. sSourceFile sTargetFile Source file to copy. File name specified may be in long format or in DOS 8.3 format. Target file to copy to or directory to copy into. Trailing backslashes are ignored. If a file is specified for copy, the source file is renamed. If wildcards are used, the source names are used to fill in the target names.
Description
Parameters
Return
Number: The number of files copied, or negative if an error occurs.
Related Functions VisFileAppend, VisFileRename Example

Call VisFileCopy ('oldfile.txt', 'newfile.txt')
VisFileCreateTemp
Syntax Description sTempFileName = VisFileCreateTemp (sPrefix) String: sPrefix Creates a temporary file. If successful, this function creates the file name returned. Temporary files are created in the directory pointed to by the TEMP environment variable. If no TEMP environment variable is set, the file is created in the root directory of the current drive. sPrefix The prefix is used to build the file name. A temporary file name contains a tilde character (~), the prefix, a random number and the extension TMP. Only the first 3 characters of the prefix are used, the rest are ignored.
Parameters
Return Example
String: A string containing drive, directory, and file name of the temporary file.
Set sFileName = VisFileCreateTemp ('Vis') Set hFile = VisFileOpen (sFileName, OF_Write)
VisFileDelete
Syntax Description Parameters nErrCode = VisFileDelete (sFileSpec) String: sFileSpec Deletes one or more files. sFileSpec Directory and file specification to delete, may include wildcard characters. File name specified may be in long format or in DOS 8.3 format.
Return Example
Number: The number of files deleted, or negative if an error occurs.

Call VisFileDelete ('c:\\windows\\temp\\*.*')
VisFileExpand
Syntax nErrCode = VisFileExpand (sSourceFile, sTargetFile) String: sSourceFile String: sTargetFile Copies a source file to a destination file. If the source file was compressed by COMPRESS.EXE (Microsoft SDK), this function creates a decompressed destination file. If the source was not compressed, this function duplicates the source file. sSourceFile Source file specification to expand. May include wildcard characters (? and *). File name specified may be in long format or in DOS 8.3 format.
Description
Parameters
2-263
Chapter
sTargetFile
Target file specification. May also include wildcard characters. File name specified may be in long format or in DOS 8.3 format.
Return
Number: The number of files expanded, or negative if an error occurs.
Related Functions VisFileAppend, VisFileCopy, VisFileRename Example

Call VisFileExpand ('oldfile.tx_', 'newfile.txt')
VisFileFind
Syntax Description sFullName = VisFileFind (sFileName) String: sFileName Searches for a file in the following locations and returns the full path to the file: 1. 2. 3. 4. Current directory Windows directory and Windows system directory Directory containing executable file for the current task Directories listed in the PATH environment variable You can also specify . or .. to search the parent or root directory of the current subdirectory. File name to search for. Cannot contain wildcard characters. File name specified may be in long format or in DOS 8.3 format.
Parameters
sFileName
Return Example
String: The full path if the file name is found. A null string is returned if the file cannot be found.
Set sFileName = VisFileFind ('win.com')
VisFileGetAttribute
Syntax Description Parameters nAttribute = VisFileGetAttribute(sFileName) String: sFileName Gets the attribute bit values for the specified file. sFileName File name to obtain attribute bits for. Cannot include wildcards. File name specified may be in long format or in DOS 8.3 format.
Return
Number: The attribute bits of the file specified, or negative if an error occurs. To test a bit value, use the bitwise AND (&) operator.
Related Functions VisFileGetSize, VisFileSetAttribute Example

Set nAttribute = VisFileGetAttribute ('c:\\autoexec.bat') If nAttribute & FA_ReadOnly ...
VisFileGetSize
Syntax Description Parameters Return nFileSize = VisFileGetSize (sFileName) String: sFileName Gets the size of the specified file in bytes. sFileName File name to get size of. File name specified may be in long format or in DOS 8.3 format.
Number: The file size, or negative if an error occurs.
Related Functions VisFileGetAttribute Example

Set nFileSize = VisFileGetSize ('c:\\autoexec.bat')
VisFileGetType
Syntax Description Parameters Return nFileType = VisFileGetType (sFileName) String: sFileName Gets the file type. A file can be only one type. sFileName File name to obtain type of. File name specified may be in long format or in DOS 8.3 format.
Number: The file type, or negative if an error occurs. File types are mutually exclusive and valid values are:
Related Functions VisFileGetAttribute, VisFileGetSize Example

Set nType = VisFileGetType ('c:\\winword\\letter.doc') If nType = FILETYPE_Document ...
2-265
Chapter
VisFileOpen
Syntax nErrCode = VisFileOpen (hFile, sFileName, nFlags) Receive File Handle: hFile String: sFileName Number: nFlags Creates or opens a file. A file must be opened before it can be read or written to. hFile sFileName Handle of the open file. File name to open. File name specified may be in long format or in DOS 8.3 format. If only a file name is given, this function searches the following directories: 1) Current directory 2) Windows or Windows System directories 3) Directory containing currently running executable 4) Directories in PATH environment variable Specifies the style in which the file is to be opened. To combine bit values, use the bitwise OR (|) operator. Options include: OF_Append OF_Binary OF_Cancel OF_Create OF_Delete OF_Exist OF_Parse OF_Prompt OF_Read OF_ReadWrite OF_Share_Deny_Compat OF_Share_Deny_Exlcusive OF_Share_Deny_None OF_Share_Deny_Read OF_Share_Deny_Write OF_Text OF_Verify OF_Write Return Number: VTERR_Ok if successful, or negative if an error occurs.
nFlags
Related Functions VisFileClose Example

Variables File Handle: hFile String: sLine ... Actions If VisFileOpen (hFile, 'c:\\autoexec.bat', OF_Read) = VTERR_Ok While VisFileReadString (hFile, sLine) = VTERR_Ok ... VisFileClose (hFile)
VisFileRead
Syntax nBytesRead = VisFileRead (hFile, sBuffer, nSize) File Handle: hFile Receive String: sBuffer Number: nSize Reads a block of data from a file. See Chapter 2, Programming Techniques, of your documentation for an explanation of the difference between VisFileRead and SalFileRead. hFile sBuffer nSize Handle to file returned from VisFileOpen. String to contain the data read. Number of bytes to read. Use SalStrSetBufferLength to initialize sBuffer to the size needed. sBuffer must be at least the size of nSize. The maximum size that may be read is 65,534 bytes.
Description
Parameters
Return
Number: The number of bytes actually read. If return is less than nSize, the end of file was reached. Negative if an error occurs.
Related Functions VisFileOpen, VisFileWrite Example

If VisFileOpen (hFile, 'mydata.dat', OF_Read | OF_Binary) = VTERR_Ok Call SalStrSetBufferLength (sData, 512) Loop
2-267
Chapter
Set nNumRead = VisFileRead (hFile, sData, 512) ... If nNumRead < 512 Break Call VisFileClose (hFile)
VisFileReadString
Syntax nErrCode = VisFileReadString (hFile, sLine) File Handle: hFile Receive String: sLine Reads a text line from a text file into a string. The text file must indicate the end of each line by carriage return/line feed characters. The CR/LF characters are removed from the string. hFile sLine Return Handle to file returned from VisFileOpen. Text line read from the file. Pre-allocation of the sLine with SalStrSetBufferLength is not necessary.
Description
Parameters
Related Functions VisFileOpen, VisFileRead, VisFileWrite, VisFileWriteString Example

Set nErrCode = VisFileReadString (hFile, sLine)
VisFileRename
Syntax nErrCode = VisFileRename (sOldFileSpec, sNewFileSpec) String: sOldFileSpec String: sNewFileSpec Renames one or more files. Wildcard characters are supported in both the source and target file names. If the source and target directories are different but the file names are the same, the files are moved to the target directory specified. sOldFileSpec sNewFileSpec Return Source file specification to rename. File name specified may be in long format or in DOS 8.3 format. Target file specification. File name specified may be in long format or in DOS 8.3 format.
Description
Parameters
Number: The number of files renamed, or negative if an error occurs.
Related Functions VisFileAppend, VisFileCopy, VisFileExpand Example

Call VisFileRename ('myfile.txt', 'yourfile.txt')
VisFileSeek
Syntax nErrCode = VisFileSeek (hFile, nOffset, nOrigin) File Handle: hFile Number: nOffset Number: nOrigin Seeks to a specified offset within a file. hFile nOffset nOrigin Handle to file returned from VisFileOpen. Specifies the number of bytes the offset is to be moved from the origin. Specifies the direction of the offset. May be any of the following values: SEEK_Begin SEEK_Current SEEK_End Return Number: The current offset in file if successful, or negative if an error occurs.
Related Functions VisFileOpen, VisFileTell Example

If VisFileOpen (hFile, 'c:\\autoexec.bat', OF_Write) = VTERR_Ok Call VisFileSeek (hFile, 0, SEEK_End) ... Call VisFileClose (hFile)
VisFileSetAttribute
Syntax nErrCode = VisFileSetAttribute (sFileName, nAttribute, bState) String: sFileName Number: nAttribute Boolean: bState Sets the attribute bits for one or more files.
Description
2-269
Chapter
Parameters
sFileName
Directory and file specification to set, may include wildcard characters. If wildcard characters are used, the attributes are set for each matching file. File name specified may be in long format or in DOS 8.3 format. Attribute bits to set or clear: FA_Standard FA_ReadOnly FA_Hidden FA_System FA_Archive TRUE to set attributes, FALSE to clear.
nAttribute
bState Return
Number: The number of files effected, or negative if an error occurs.
Related Functions VisFileGetAttribute, VisFileSetDateTime Example

Call VisFileSetAttribute ('c:\\myapp\\*.exe', FA_ReadOnly, TRUE)
VisFileSetDateTime
Syntax nErrCode = VisFileSetDateTime (sFileName, dtDateTime) String: sFileName Date/Time: dtDateTime Sets the date and time for one or more files. sFileSpec Directory and file specification to set, may include wildcard characters. If wildcard characters are used, the date and time are set for each matching file. File name specified may be in long format or in DOS 8.3 format. Date and time to set for all files specified.
dtDateTime Return Example
Number: The number of files effected, or negative if an error occurs.

Set dtDateTime = SalDateCurrent() Set nNumFiles = VisFileSetDateTime ('c:\\myapp\\*.exe', dtDateTime)
VisFileTell
Syntax Description Parameters Return nOffset = VisFileTell (hFile) File Handle: hFile Returns the current file offset. hFile Handle to file returned from VisFileOpen.
Number: The current offset in file if successful, or negative if an error occurs.
Related Functions VisFileOpen, VisFileSeek Example

Actions Set nFilePos = VisFileTell (hFile)
VisFileWrite
Syntax nErrCode = VisFileWrite (hFile, sBuffer, nSize) File Handle: hFile String: sBuffer Number: nSize Writes a block of data to a file.The maximum number of characters you can write is 65,535. hFile sBuffer nSize Return Handle to file returned from VisFileOpen. String containing data to write. Number of bytes to write. Must be less than or equal to size of sBuffer.
Number: The number of bytes written to the file. If the return value is less than nSize, the drive is out of space. Negative if an error occurs.
Related Functions VisFileOpen, VisFileWriteString Example

If VisFileOpen (hFile, 'mydata.dat', OF_Write) = VTERR_Ok Call VisFileWrite (hFile, sData, SalStrLength (sData)) Call VisFileClose (hFile)
2-271
Chapter
VisFileWriteString
Syntax nErrCode = VisFileWriteString (hFile, sLine) File Handle: hFile String: sLine Writes a string to a file. CR/LF characters are added to the end of the string before it's written to the file. hFile sLine Return Handle to file context structure returned from VisFileOpen. String to write to the file.
Related Functions VisFileOpen, VisFileWrite Example

While nIndex <= nMax Call VisFileWriteString (hFile, sLines[nIndex]) Set nIndex = nIndex + 1 Call VisFileClose (hFile)
VisFontEnum
Syntax nNumFonts = VisFontEnum (sGetFlag, sFontNames, nFontTypes) String: sGetFlag Receive String: sFontNames[*] Receive Number: nFontTypes[*] Gets the font names and types (printer, true type, etc.). sGetFlag One or more flags indicating type of fonts to retrieve. To combine bit values, use the bitwise OR (|) operator. FONT_GetScreen FONT_GetPrinter Names of each available font (Arial, Times New Roman, etc.) Bit flags indicating types of each available font. To combine bit values, use the bitwise OR (|) operator. FONTTYPE_Device FONTTYPE_Raster FONTTYPE_TrueType Return Number: The total number of fonts if successful, or negative if an error occurs.
sFontNames nFontTypes
Related Functions VisFontGet Example

Set nNumFonts = VisFontEnum (FONT_GetScreen, sFontNames, nFontTypes) Set nIndex = 0 While nIndex < nNumfonts If nFontTypes(nIndex) & FONTTYPE_TrueType
VisFontFree
Syntax Description Parameters Return bOk = VisFontFree (hFont) String: hFont Frees a font loaded into memory with the VisFontLoad function. hFont Handle of font to free.
Related Functions VisFontEnum, VisFontLoad Example

Set bOk = VisFontFree (hFont)
VisFontGet
Syntax bOk = VisFontGet (hFont, sFaceName, nPointSize, nFontEnhancement) Number: hFont Receive String: sFaceName Receive Number: nPointSize Receive Number: nFontEnhancement Gets specifications of a font. hFont sFaceName nPointSize nFontEnhancement Font to get specifications for. String to contain the font name (Arial, Times New Roman, etc.) Point size of font. Bit flags containing font enhancements. To combine bit values, use the bitwise OR (|) operator. FONT_EnhNormal FONT_EnhItalic
2-273
Chapter
FONT_EnhUnderline FONT_EnhBold FONT_EnhStrikeout Return Boolean: TRUE if successful, or FALSE if an error occurs.
Related Functions VisFontEnum, VisFontLoad Example

On SAM_Click Set nIndex = SalListQuerySelection (hWndItem) If nIndex != LB_Err Call VisFontGet (hFont, sFontName, nPointSize, nFontFlags) If nFontFlags & FONT_EnhBold ...
VisFontLoad
Syntax hFont = VisFontLoad (sFontName, nFontSize, nFontEnhancement) String: sFontName Number: nFontSize Number: nFontEnhancement Loads a font into memory. sFontName nFontSize nFontEnhancement Font name (Arial, Times New Roman, etc.). Point size of font. Bit flags containing font enhancements. To combine bit values, use the bitwise OR (|) operator. FONT_EnhNormal FONT_EnhItalic FONT_EnhUnderline FONT_EnhBold FONT_EnhStrikeout Return Number: The handle of the font if successful, NULL if an error occurs.
Related Functions VisFontEnum, VisFontFree Example

On SAM_Create Set hFont = VisFontLoad ('Arial', 10, FONT_EnhBold)
VisGetCopyright
Syntax Description Parameters Return sCopyrightMsg = VisGetCopyright () Retrieves a copyright string to display in applications that use the Vis Library. No parameters. String: The copyright string for the Vis Library.
Related Functions VisGetVersion Example

On SAM_Create Set dfCopyright = VisGetCopyright()
VisGetKeyState
Syntax Description Parameters Return Example nState = VisGetKeyState (nVirtualKey) Number: nVirtualKey Retrieves the state of a specified key. The state specifies whether the key is up, down, or toggled. nVirtualKey Virtual key code to retrieve the state. See the Appendix for a complete list of virtual key codes.
Number: The bit values indicating the state of the key specified. To test a bit value, use the bitwise AND (&) operator.
On SAM_Click Set nState = VisGetKeyState (VK_Control) If nState & KS_Down ...
VisGetSystemMetrics
Syntax Description nValue = VisGetSystemMetrics(nIndex) Number: nIndex Retrieves widths and heights of various elements displayed by Windows. VisGetSystemMetrics can also return flags indicating whether the current version of Windows is a debugging version, whether a mouse is present, or whether the meanings of the left and right mouse buttons have been exchanged. nIndex Specifies the system measurement to retrieve:
Parameters
2-275
Chapter
Return Example
SM_XBorderSM_YMin SM_YBorderSM_XMinTrack SM_YCaptionSM_YMinTrack SM_XCursorSM_XScreen SM_YCursorSM_YScreen SM_XDoubleClickSM_XHScroll SM_YDoubleClickSM_YHScroll SM_XDlgFrameSM_XVScroll SM_YDlgFrameSM_YVScroll SM_XFrameSM_XSize SM_YFrameSM_YSize SM_XFullScreenSM_XHThumb SM_YFullScreenSM_YVThumb SM_XIconSM_DBCSEnabled SM_YIconSM_Debug SM_XIconSpacingSM_MenuDropAlignment SM_YIconSpacingSM_MousePresent SM_KanjiWindowSM_PenWindows SM_MenuSM_SwapButton SM_XMin Number: The specified system metric.
Actions Set nScreenWidth = VisGetSystemMetrics (SM_XScreen)
VisGetVersion
Syntax Description Parameters Return Example sVisVersion = VisGetVersion () Gets the Vis Library version number. No parameters. String: The version number of the Vis Library.
Actions Set dfVersion = 'Version ' || VisGetVersion()
VisGetWinFlags
Syntax Description Parameters nFlags = VisGetWinFlags () Retrieves the current Windows system and memory configuration. None.
Return
Number: A series of bits indicating the current system configuration. To test a bit value, use the bitwise AND (&) operator. WF_80x87 WF_CPU286 WF_CPU386 WF_CPU486 WF_Enhanced WF_Paging WF_PMode WF_Standard WF_WLO
Example
Actions Set nWinFlags = VisGetWinFlags() If nWinFlags & WF_CPU486
VisGetWinVersion
Syntax Description Parameters Return Example nWinVersion = VisGetWinVersion () Returns the Windows version number. No parameters. NumberThe major and minor (3.10) Windows version number.
Actions Set nWinVersion = VisGetWinVersion ()
VisListAddValue
Syntax nIndex = VisListAddValue (hWndList, sText, nValue) Window Handle: hWndList String: sText Number: nValue Adds an item to a sorted list box or combo box and associates the specified value with the item. The value can be a record identifier for a database, a file offset, or any other integer value that the application can use to uniquely identify the item. Use VisListInsertValue for unsorted list boxes or combo boxes. hWndList sText nValue Window handle of list box or combo box to add item to. Text of item to add. Value to associate with the added item. May be a positive or negative integer value.
Description
Parameters
2-277
Chapter
Return
Number: The index to the item added, or LB_Err if an error occurs.
Related Functions VisListInsertValue Example

Call VisListAddValue (hWndItem, sText[nIndex], nKeys[nIndex]) Set nIndex = nIndex +1
VisListArrayPopulate
Syntax nNumItems = VisListArrayPopulate (hWndList, sText) Window Handle: hWndList String: sText[*] Populates a list box from a string array. Each item in the string is inserted as an item in the list box. hWndList sText Return Window handle of list box or combo box to populate. String array to populate the list box with.
Number: The number of items added to the list box or combo box, or LB_Err if an error occurs.
Related Functions VisListArrayPopulateValue Example

Set nCount = VisDosEnumDirs ('c:\\windows\\*.*', sDirs) If nCount > 0 Call VisListArrayPopulate (lbDirs, sDirs)
VisListArrayPopulateValue
Syntax nNumItems = VisListArrayPopulateValue (hWndList, sText, nValues) Window Handle: hWndList String: sText[*] Number: nValues[*] 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 items in the string array and the number of items in the value array must be the same. hWndList sText nValues 2-278 Centura Builder Function Reference Window handle of list box or combo box to populate. String array to populate the list box with. Number array of values to associate with each item.
Description
Parameters
Return
Number: The number of items added to the list box or combo box, or LB_Err if an error occurs.
Related Functions VisListArrayPopulate Example

Set nCount = VisDosEnumFileInfo ('c:\\windows\\*.*', 0, sFiles, nSizes, dtDateTimes, nAttributes) If nCount , 0 Call VisListArrayPopulateValue (lbFiles, sFiles, nAttributes)
VisListClearSelection
Syntax Description bOk = VisListClearSelection (hWndList) Window Handle: hWndList Unselects all selected items in a list box or combo box. If the window handle is a multiple selection list box, all selected items are unselected. If the window handle is a single selection list box or a combo box, the currently selected item is unselected. Combo boxes do not allow multiple selections. hWndList Handle to list box or combo box to clear selection from.
Parameters Returns
Related Functions VisListDeleteSelected Example

Actions Call VisListClearSelection (hWndItem)
VisListDeleteSelected
Syntax Description nNumDeleted = VisListDeleteSelected (hWndList) Window Handle: hWndList Deletes all selected items from a list box or combo box. If the window handle is a multiple selection list box, all selected items are deleted. If the window handle is a single selection list box or a combo box, the currently selected item is deleted. Combo boxes do not allow multiple selections. hWndList Window handle of list box or combo box to delete selected items.
Parameters Return
Number: nNumDeleted is the number of items deleted, or negative if an error occurs. 2-279
Chapter
Related Functions VisListClearSelection Example

Pushbutton: pbDelete ... Message Actions On SAM_Click Call VisListDeleteSelected (lbSample)
VisListFindString
Syntax nIndex = VisListFindString (hWndList, nStartIndex, sText) Window Handle: hWndList, Number: nStartIndex String:sText Finds the first string that matches the specified string in a list box or combo box. The search requires an exact match of all characters, but it is not case sensitive. hWndList nStartIndex Window handle of list box or combo box. Specifies the index of the item before the first item to be searched. Searching begins at nStartIndex +1. If the search reaches the bottom of the list, it continues at the top and back to the item specified. To search from the beginning, specify -1. String to search for. The search is not case-sensitive.
sText Return Example
Number: The index of the string if it is found, or negative if an error occurs.

Actions Set nIndex = VisListFindString (lbSample, 0, 'Red')
VisListFindValue
Syntax nIndex = VisListFindValue (hWndList, nStartIndex, nValue) Window Handle: hWndList Number: nStartIndex Number:nValue Description Parameters This function will locate a value associated with an item based on an index. hWndList nStartIndex Window handle to search. The index to begin searching; specify -1 to search from the top of the list. Searching begins at nStartIndex +1.
nValue Return Example
Value to search for.
Number: The index containing the value specified, or LB_Err if the value cannot be found.
Actions Set nIndex = SalListQuerySelection (hWndItem) If nIndex != LB_Err Set nIndexFound = VisListFindValue (lbNames, nIndex, 100)
VisListGetDropdownState
Syntax Description Parameters Return Example bState = VisListGetDropdownState (hWndList) Window Handle: hWndList, Determines whether the list box portion of a combo box is visible. hWndList Window handle of combo box.
Boolean: TRUE if visible, FALSE if not visible

Actions If VisListGetDropdownState (hWndItem) ...
VisListGetFocusIndex
Syntax Description nIndex = VisListGetFocusIndex (hWndList) Window Handle: hWndList 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. This function will retrieve the selected item on a combo box. hWndList Window handle of list box or combo box.
Parameters Return
Number: The index of the item that has the focus rectangle, if a multiple selection list box. If the function is operating on a single-selection list box or combo box, the return value is the index of the item that is selected, if any.
Related Functions VisListSetFocusIndex
2-281
Chapter
Example
Actions Set nIndex = VisListGetFocusIndex (hWndItem) If nIndex != LB_Err
VisListGetVisibleRange
Syntax nNumVisible = VisListGetVisibleRange (hWndList, nTop, nBottom) Window Handle: hWndList Receive Number: nTop Receive Number: nBottom Retrieves the indexes of both the first visible item and the last visible item in a list box. This function will not operate on a combo box. hWndList nTop nBottom Return Example Window handle of list box. Top visible index of list box Bottom visible index of list box
Number: The number of visible items, or negative if an error occurs or if hWndList is a combo box.
Call VisListGetVisibleRange (hWndItem, nTop, nBottom) Set nIndex = nTop While nTop <= nBottom Set sText = VisListGetText (hWndItem, nIndex) ... Set nIndex = nIndex + 1
VisListInsertValue
Syntax nIndex = VisListInsertValue (hWndList, nIndex, sText, nValue) Window Handle: hWndList Number: nIndex String: sText Number: nValue Inserts an item into an unsorted list box or combo box and associates the specified value with the item. The value can be a record identifier for a database, a file offset, or any other integer value that the application can use to uniquely identify the item. Use VisListAddValue for sorted list boxes or combo boxes. hWndList nIndex Window handle of list box or combo box to insert item into. Position to insert item in list box (-1 to insert at the bottom).
Description
Parameters
sText nValue Return
Text of item to insert. Value to associate with the inserted item. May be a positive or negative integer value.
Number: The index to the item inserted, or LB_Err if an error occurs.
Related Functions VisListAddValue Example

While SqlFetchRow (hSql, nIndex) Call VisListInsertValue (hWndItem, -1, sText[nIndex], nKeys[nIndex]) Set nIndex = nIndex +1
VisListIsMultiSelect
Syntax Description Parameters Returns Example bOk = VisListIsMultiSelect (hWndList) Window Handle: hWndList Tests a list box to determine if multiple selection is enabled. hWndList List box to test.
Boolean: TRUE if multi selection is enabled for the list box, FALSE if not.
Actions If VisListIsMultiSelect (hWndList) ...
VisListLoadOutline
Syntax nErrCode = VisListLoadOutline (hWndList, sOutlineBlob) Window Handle: hWndList String: sOutlineBlob Loads an outline from a blob (binary large object) in memory. The blob must be created from a call to VisListSaveOutline. The outline will be restored exactly as it was when the outline was saved, including selected items and outline position in the list box or combo box. hWndList sOutlineBlob Return Window handle of list box or combo box. String containing outline to load.
Description
Parameters
2-283
Chapter
Related Functions VisListSaveOutline Example

On Sam_Click Call VisListLoadOutline (twOutline, sOutline)
VisListLoadOutlineFile
Syntax nErrCode = VisListLoadOutlineFile (hWndList, sOutlineFileName, hPicParentNormal, hPicParentSelect, hPicChildNormal, hPicChildSelect) Window Handle: hWndList String: sOutlineFileName Number: hPicParentNormal Number: hPicParentSelect Number: hPicChildNormal Number: hPicChildSelect Loads an outline from a tab indented ASCII file. The parent/child relationships are derived from the order of the text lines and the indentation of the text in the file. Since the file contains no picture information, handles to the pictures to use for the parent and lowest level children must be passed in. hWndList sOutlineFileName hPicParentNormal hPicParentSelect hPicChildNormal hPicChildSelect Return Example Window handle of list box or combo box. File name of the outline to load. Picture to use when parent item is not selected. Call VisPicLoad to create a picture handle. Picture to use when parent item is selected. hPicParentNormal and hPicParentSelect may be the same. Picture to use when lowest level child item is not selected. Call VisPicLoad to create a picture handle. Picture to use when lowest level child item is selected. hPicChildNormal and hPicChildSelect may be the same.
Description
Parameters

Set nErrCode = VisListLoadOutlineFile (hWndList, sOutlineFileName, hPicParentNormal, hPicParentSelect, hPicChildNormal, hPicChildSelect)
VisListSaveOutline
Syntax nErrCode = VisListSaveOutline (hWndList, sOutlineBlob) Window Handle: hWndList String: sOutlineBlob Compresses and saves a list box or combo box outline into a blob (binary large object) in memory. The blob data may then be inserted into a LONG VARCHAR column of a database. hWndList sOutlineBlob Return Window handle of list box or combo box. String to contain the ouline.
Description
Parameters
Related Functions VisListLoadOutline Example

On SAM_Destroy If VisListSaveOutline (twOutline, sOutline) Call SqlPrepare (hSql, 'INSERT INTO TABLE (out_id, outline)values (:nOutID, :sOutline')
VisListScroll
Syntax nErrCode = VisListScroll (hWndList, nIndex) Window Handle: hWndList Number: nIndex Scrolls an item into view. This function does not force the item to the top of a list box. The item may be scrolled anywhere in the visible range. This function does not operate on combo boxes. hWndList nIndex Return Example Window handle of list box to scroll. Index of item to scroll.
Description
Parameters
Number: Negative if an error occurs.

Actions Call VisListScroll (hWndItem, 0)
2-285
Chapter
VisListSetDropdownState
Syntax bOk = VisListSetDropDownState (hWndList, bState) Window Handle: hWndList Boolean: bState Shows or hides the list box portion of a combo box. This function does not operated on list boxes. hWndList bState Return Window handle of combo box. TRUE to show, FALSE to hide.
Related Functions VisListGetDropDownState Example

Actions Call VisListSetDropDownState (hWndItem, TRUE)
VisListSetFocusIndex
Syntax nErrCode = VisListSetFocusIndex (hWndList, nIndex) Window Handle: hWndList Number: nIndex Sets the focus rectangle to the item at the specified index in a multiple-selection list box. If the item is not visible, it is scrolled into view. If hWndList is a single select list box, no action is performed. hWndList nIndex Return Window handle of list box. Index of the item to receive the focus rectangle.
Description
Parameters
Number: Negative if an error occurs.
Related Functions VisListGetFocusIndex Example

Actions Call VisListSetFocusIndex (hWndItem, 5)
VisListSetScrollWidth
Syntax nErrCode = VisListSetScrollWidth (hWndList, nIndex) Window Handle: hWndList Number: nIndex Sets the width by which a list box can be scrolled horizontally. The horizontal width is determined by the string length of the longest item. If the width of the item specified is not longer that the current width, the current width is not adjusted. The first call to VisListSetScrollWidth displays a horizontal scroll bar in the list box. This function does not work on combo boxes. hWndList nIndex Return Example Window handle of list box to set the scroll width. Item to base the scroll width on. If -1 all items are searched for the largest text length.
Description
Parameters
Number: Zero if successful, or negative if an error occurs.

Actions Call VisListSetScrollWidth (lbText, -1)
VisMenuGetPopupHandle
Syntax hMenu = VisMenuGetPopupHandle (hMenu, nPos) Number: hMenu Number: nPos Retrieves the menu handle of a pop-up menu. A pop-up menu appears below a top level menu option, or to the side of another pop-up menu. hMenu nPos Handle of menu whose pop-up menu handle is to be retrieved. Zero-based position in the specified menu of the pop-up menu. Menu separators are included in the position count. It cannot be a negative value indicating a menu ID added using VisMenuInsert, which always returns a negative menu ID value.
Return
Number: The menu handle of the menu specified, or NULL if the window has no menu.
Related Functions VisMenuGetSystemHandle
2-287
Chapter
Example
Set hMenu = VisMenuGetHandle (hUnd) If hMenu Set hSubMenu = VisMenuGetPopupHandle (hMenu, 2)
VisMenuGetSystemHandle
Syntax Description Parameters Return hMenu = VisMenuGetSystemHandle (hWnd) Window Handle: hWnd Retrieves the system menu handle of a window. The system menu is located in the upper left corner of a window. hWnd Window handle to retrieve menu.
Number: The system menu handle of window specified, or NULL if the window has no menu.
Related Functions VisMenuGetPopupHandle Example

Variables Number: hMenu ... Actions Set hMenu = VisMenuGetSystemHandle (hWnd)
VisMenuGetText
Syntax sMenuText = VisMenuGetText (hWnd, hMenu, nPos) Window Handle: hWnd Number: hMenu Number: nPos Retrieves the text of a menu item. The text of any menu item, whether defined in Centura or inserted via the Vis Library, may be returned. hWnd hMenu nPos Handle to window containing menu. Handle of menu containing item to retrieve. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value.
Returns
String: The text of the specified menu item. The text will contain a tab character between the text and the accelerator indicator.
Related Functions VisMenuSetText Example

Variables Number: hMenu ... Actions Set hMenu = VisMenuGetHandle (hWnd) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Set sText = VisMenuGetText (hWndForm, hMenu, 5)
VisMenuInsert
Syntax nMenuID = VisMenuInsert (hWnd, hMenu, nPos, sMenuText, nFlags) Number: hWnd Number: hMenu Number: nPos String: sMenuText Number: nFlags Inserts a menu item into a menu. Menu items can be inserted into system, top-level or pop-up menus. Prior to Centura 4.1, items could not be inserted into the middle of a Centura menu. They could only be inserted at the end of a Centura menu or in the middle of items previously inserted with a VisMenuInsert call. hWnd Handle to window containing the menu. This window will be notified with a VTM_MenuSelect message when the menu item is selected. Handle of menu to insert item into. Zero-based position within the menu of the item. Menu positions include separators. Specify -1 to insert at the end of the menu. Text of item to insert. Specify \t to insert a tab in the text. A tab will separate the menu text from the accelerator indicator. All text after the tab will be shown along the right edge of the menu. Menu flags. To combine bit values, use the bitwise OR (|) operator.
Description
Parameters
hMenu nPos
sMenuText
nFlags
2-289
Chapter
MF_Checked MF_Disabled MF_Separator Returns Number: The ID value of the menu item inserted, or NULL if an error occurs. Menu IDs are always negative. Each inserted item is assigned a unique ID.
Related Functions VisMenuInsertFont, VisMenuInsertPicture Example

On SAM_Create Set hMenu = VisMenuGetHandle (hWndForm) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Call VisMenuInsert (hWndForm, hMenu, -1, '', MF_Separator) Set nMenuID = VisMenuInsert (hWndForm, hMenu, -1, 'Sample\tAlt-S', 0)
VisMenuInsertFont
Syntax nMenuID = VisMenuInsertFont (hWnd, hMenu, nPos, hFont sMenuText) Number: hWnd Number: hMenu Number: nPos Number: hFont String: sMenuText Inserts a menu item into a menu and displays it in the specified font. Prior to Centura 4.1, items could not be inserted into the middle of a Centura menu. They could only be inserted at the end of a Centura menu or in the middle of items previously inserted with a VisMenuInsert call. hWnd Handle to window containing the menu. This window will be notified with a VTM_MenuSelect message when the menu item is selected. Handle of menu to insert item into. Zero-based position within the menu of the item. Menu positions include separators. Specify -1 to insert at the end of the menu. Handle to font to use for menu item display. Call VisFontLoad to create a font handle. Text of item to insert. Specify \t to insert a tab in the text. A tab will separate the menu text from the accelerator indicator. All
Description
Parameters
hMenu nPos
hFont sMenuText
text after the tab will be shown along the right edge of the menu. Returns Number: The ID value of the menu item inserted, or NULL if an error occurs. Menu IDs are always negative. Each inserted item is assigned a unique ID.
Related Functions VisMenuInsert, VisMenuInsertPicture Example

On SAM_Create Set hFont = VisFontLoad ('Arial', 12, FONT_EnhBold) Set hMenu = VisMenuGetHandle (hWndForm) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Call VisMenuInsert (hWndForm, hMenu, -1, '', MF_Separator) Set nMenuID = VisMenuInsertFont (hWndForm, hMenu, -1, hFont, 'Sample\tAlt-S')
VisMenuInsertPicture
Syntax nMenuID = VisMenuInsertPicture (hWnd, hMenu, nPos, hPicNormal, hPicSelect, sMenuText) Number: hWnd Number: hMenu Number: nPos Number: hPicNormal Number: hPicSelect String: sMenuText Inserts a menu item into a menu and displays the specified picture with it. Prior to Centura 4.1, items could not be inserted into the middle of a Centura menu. They could only be inserted at the end of a Centura menu or in the middle of items previously inserted with a VisMenuInsert call. hWnd Handle to window containing the menu. This window will be notified with a VTM_MenuSelect message when the menu item is selected. Handle of menu to insert item into. Zero-based position within the menu of the item. Menu positions include separators. Specify -1 to insert at the end of the menu. Handle of picture to display in menu item when item is not selected. Call VisPicLoad to create a picture handle.
Description
Parameters
hMenu nPos
hPicNormal
2-291
Chapter
hPicSelect
Handle of picture to display in menu item when item is selected. hPicNormal and hPicSelect may be the same.
sMenuTextText of item to insert. Specify \t to insert a tab in the text. A tab will separate the menu text from the accelerator indicator. All text after the tab will be shown along the right edge of the menu. Returns Number: The ID value of the menu item inserted, or NULL if an error occurs. Menu IDs are always negative. Each inserted item is assigned a unique ID.
Related Functions VisMenuInsert, VisMenuInsertFont Example

Call VisMenuInsert (hWndForm, hMenu, -1, '', MF_Separator) Set nMenuID = VisMenuInsertPicture (hWndForm, hMenu, -1, hPic, 'Sample\tAlt-S')
VisMenuIsChecked
Syntax bOk = VisMenuIsChecked (hMenu, nPos) Number: hMenu Number: nPos Uses the Windows check state to test whether a menu item is checked. VisMenuIsChecked works with either menu items inserted using the Vis Library or Centura menu items. It must be called in the Checked When section of the Centura outline in order to properly display the check status of a Centura menu item. hMenu nPos Menu handle of menu to test. This may be a pop-up or system menu. It cannot be a top-level menu. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value.
Description
Parameters
Return
Boolean: TRUE if successful, FALSE if unsuccessful.
Related Functions VisMenuIsEnabled, VisMenuUncheck
Example
Menu Item: Sample Menu ... Menu Settings Enabled when: Checked when: VisMenuIsChecked (VisMenuGetPopupHandle (VisMenuGetHandle(hWndForm), 3), 4) Menu Actions
VisMenuIsEnabled
Syntax bOk = VisMenuIsEnabled (hMenu, nPos) Number: hMenu Number: nPos Uses the Windows enable state to test whether a menu item is enabled. VisMenuIsEnabled works with either menu items inserted using the Vis Library or Centura menu items. It must be called in the Enabled When section of the Centura outline in order to properly display the enable status of a Centura menu item. hMenu nPos Menu handle of menu to test. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value.
Description
Parameters
Return
Boolean: TRUE if successful, FALSE if unsuccessful.
Related Functions VisMenuIsChecked Example

Menu Item: Sample Menu Menu Settings Enabled when: VisMenuIsEnabled (VisMenuGetPopupHandle (VisMenuGetHandle(hWndForm), 3), 0) Checked when: Menu Actions
2-293
Chapter
VisMenuSetFont
Syntax bOk = VisMenuSetFont (hWnd, hMenu, nPos, hFont sMenuText) Number: hWnd Number: hMenu Number: nPos Number: hFont String: sMenuText Displays a menu item in the specified font. VisMenuSetFont operates on Centura menus or menus inserted with the Vis Library. hWnd hMenu nPos Handle to window containing menu. Handle to menu containing item to display picture with. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value. Handle to font to use for menu item display. Call VisFontLoad to create a font handle. Text of item to insert. Specify \t to insert a tab in the text. A tab will separate the menu text from the accelerator indicator. All text after the tab will be shown along the right edge of the menu. If the menu text is a null string, the text is unchanged.
hFont sMenuText
Returns
Boolean: TRUE if successful, FALSE if an error occurs.
Related Functions VisMenuSetPicture, VisMenuSetText Example

On SAM_Create Set hFont = VisFontLoad ('Arial', 12, FONT_EnhBold) Set hMenu = VisMenuGetHandle (hWndForm) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Set nMenuID = VisMenuSetFont (hWndForm, hMenu, -1, hFont, 'Sample\tAlt-S')
VisMenuSetPicture
Syntax bOk = VisMenuSetPicture (hWnd, hMenu, nPos, hPicNormal, hPicSelect, sMenuText) Number: hWnd Number: hMenu Number: nPos Number: hPicNormal Number: hPicSelect String: sMenuText Displays a picture in a menu item. VisMenuSetPicture operates on Centura menus or menus inserted with the Vis Library. hWnd hMenu nPos Handle to window containing menu. Handle to menu containing item to display picture with. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value. Handle of picture to display in menu item when item is not selected. Call VisPicLoad to create a picture handle. Handle of picture to display in menu item when item is selected. hPicNormal and hPicSelect may be the same. Text of item to insert. Specify \t to insert a tab in the text. A tab will separate the menu text from the accelerator indicator. All text after the tab will be shown along the right edge of the menu. If the menu text is a null string, only the picture will be shown. If a picture and text are specified, the text is always shown to the right of the picture.
hPicNormal hPicSelect sMenuText
Returns
Related Functions VisMenuSetFont, VisMenuSetText
2-295
Chapter
Example
On SAM_Create Set hPic = VisPicLoad (PIC_LoadResource | PIC_FormatBitmap, 'Vis.dll', 'bkopen') Set hMenu = VisMenuGetHandle (hWndForm) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Set nMenuID = VisMenuSetPicture (hWndForm, hMenu, -1, hPic, 'Sample\tAlt-S')
VisMenuSetText
Syntax bOk = VisMenuSetText (hWnd, hMenu, nPos, sText) Window Handle: hWnd Number: hMenu Number: nPos String: sText Changes the text of a menu item. VisMenuSetText operates on Centura menus or menus inserted with the Vis Library. hWnd hMenu nPos Handle to window containing menu. Handle of menu that contains the menu item to reset text for. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value. New text to use for the specified menu item. Specify \t to insert a tab in the text. A tab will separate the menu text from the accelerator indicator. All text after the tab will be shown along the right edge of the menu.
sText
Returns
Related Functions VisMenuSetFont, VisMenuSetPicture Example

Set hMenu = VisMenuGetHandle (hWnd) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Call VisMenuSetText (hWndForm, hMenu, 5, 'New Item')
VisMenuUncheck
Syntax bOk = VisMenuUncheck (hMenu, nPos) Number: hMenu Number: nPos Unchecks a menu item. VisMenuUncheck is intended for menu items that have been inserted using the Vis Library. It also works for Centura menu items but will remove the check mark only if VisMenuIsChecked is called in the When Checked section of the Centura outline. This is because VisMenuIsChecked returns the Windows state of the menu item and VisMenuUncheck will set the Windows state. hMenu nPos Handle of menu containing item to uncheck. Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu item added using VisMenuInsert, which always returns a negative menu ID value.
Description
Parameters
Returns
Boolean: TRUE if successful, or FALSE if unsuccessful.
Related Functions VisMenuIsChecked Example

Set hMenu = VisMenuGetHandle (hWnd) Set hMenu = VisMenuGetPopupHandle (hMenu, 2) Call VisMenuUncheck (hWnd, hMenu, 5)
VisMessageBox
Syntax nReturn = VisMessageBox (sMsgText, sCaption, hPicIcon, hBtnHandles, nNumButtons) String: sText String: sCaption Number: hPicIcon Number: hBtnHandles[*] Number: nNumButtons Displays a message box with user defined buttons and a user defined icon. sMsgText sCaption hPicIcon Text to be displayed in message box. Caption of message box window. Icon to display in message box. This must be an icon; it cannot be a bitmap. Call VisPicLoad to create a picture handle. May be one of the following constants:
2-297
Chapter
hBtnHandles
MBF_IconAsterisk MBF_IconHand MBF_IconQuestion MBF_IconExclamation Array of button handles to display. These handles are obtained from a call to VisMessageLoadButton. The button handle may be OR'ed with MBF_DefButton to set the default focus button. Number of buttons contained in hBtnHandles array.
nNumButtons Returns
Number: The return value indicating which button is selected. The return value is assigned using VisMessageLoadButton.
Related Functions VisMessageFreeButton, VisMessageLoadButton, VisMessageSetBkgdColor Example

Set nReturn = VisMessageBox ('Cannot insert.', 'Error', MBF_IconHand, hBtns, 3) If nReturn = ID_Abort Call SalQuit () Else If nReturn = ID_Help Call SalWinHelp (...)
VisMessageFreeButton
Syntax Description Parameters Returns bOk = VisMessageFreeButton (hBtn) Number: hBtn Frees memory allocated with VisMessageLoadButton. hBtn Handle of button handle to free memory for.
Related Functions VisMessageLoadButton Example

Set bOk = VisMessageFreeButton (hBtn)
VisMessageLoadButton
Syntax hBtn = VisMessageLoadButton (sLabel, nReturn) String: sLabel Number: nReturn Establishes a button to be used in user-defined message boxes. sLabel nReturn Returns Text label for button. Return value if button is clicked in the message box. This value is returned from VisMessageBox.
Number: The button handle if successful, or NULL if an error occurs.
Related Functions VisMessageFreeButton Example

On SAM_AppStartup Set hBtnOk = VisMessageLoadButton ('Ok', ID_OK) Set hBtnHelp = VisMessageLoadButton ('&Help', ID_Help)
VisMessageSetBkgdColor
Syntax Description Parameters Returns bOk = VisMessageSetBkgdColor (nColor) Number: nColor Sets the background color for a VisMessageBox dialog box. All subsequent calls to VisMessageBox will display a dialog with the color indicated. nColor Color to paint the background of the VisMessageBox.
Related Functions VisMessageBox Example

Call VisMessageSetBkgdColor (COLOR_Gray)
VisNumberBitClear
Syntax nResult = VisNumberBitClear (nValue, nBitMask) Receive Number: nValue Number: nBitMask Clears bit values from a number.
Description
2-299
Chapter
Parameters
nValue nBitMask
Number value to clear bits from. The function replaces this number with the result. Bit mask identifying the bits to clear.
Return
Number: The resulting value after mask bits are cleared. This value is also placed in nValue.
Related Functions VisNumberBitSet Example

Constants Number: BIT_Flag1 = 0x0001 Number: BIT_Flag2 = 0x0004 ... Actions Call VisNumberBitClear (nValue, BIT_Flag2)
VisNumberBitSet
Syntax nResult = VisNumberBitSet (nValue, nBitMask) Receive Number: nValue Number: nBitMask Sets bit values in a number. nValue nBitMask Return Number value to set bits for. The function replaces this number with the result. Bit mask identifying the bits to set.
Number: The resulting value after mask bits are set. This value is also placed in nValue.
Related Functions VisNumberBitClear Example

Constants Number: BIT_Flag1 = 0x0001 Number: BIT_Flag2 = 0x0004 ... Actions Call VisNumberBitSet (nValue, BIT_Flag2)
VisNumberChoose
Syntax nNumber = VisNumberChoose (bExpression, nTrueNumber, nFalseNumber) Boolean: bExpression Number: nTrueNumber Number: nFalseNumber Evaluates bExpression. If expression is TRUE, it returns nTrueNumber, else it returns nFalseNumber. The expression may be a constant, expression or variable. bExpression nTrueNumber nFalseNumber Returns Expression to test Number returned if expression TRUE. Number returned if expression FALSE.
Number: nTrueNumber or nFalseNumber depending on how the expression evaluates.
Related Functions VisStrChoose Example

Actions Set nError = VisNumberChoose (nWnd = hWndNULL, TRUE, FALSE)
VisNumberHighByte
Syntax Description Parameters Return nNumber = VisNumberHighByte(nNumber) Number: nNumber Converts the specified number to a WORD and returns the high order 8 bits of the WORD. nNumber Number to convert and obtain high 8 bits for.
Number: The high order 8 bits.
Related Functions VisNumberLowByte Example

Actions Set nValue = 0xC8D4 Set nHiByte = VisNumberHighByte (nValue) !nHiByte = OxC8.
2-301
Chapter
VisNumberLowByte
Syntax Description Parameters Return nNumber = VisNumberLowByte(nNumber) Number: nNumber Converts the specified number to a WORD and returns the low order 8 bits of the WORD. nNumber Number to convert and obtain low 8 bits for.
Number: The low order 8 bits.
Related Functions VisNumberHighByte Example

Actions Set nValue = 0xC8D4 Set nLowByte = VisNumberLowByte (nValue) !nLowByte = OxD4.
VisNumberMakeLong
Syntax nLong = VisNumberMakeLong(nLow, nHigh) Number: nLow Number: nHigh Creates a double word value (DWORD) from two word values. nLow nHigh Return Example Low order 16 bits. High order 16 bits.
Number: The combined value.

Actions Set nLow = 0x0101 Set nHigh = 0xABCD Set nLong = VisNumberMakeLong (nLow, nHigh) ! nLong = 0xaABCD0101
VisPicFree
Syntax Description nErrCode = VisPicFree (hPic) Number: hPic Frees a picture from memory. A picture is either a bitmap or an icon.
Parameters Return
hPic
Handle of picture to free.
Number: Zero if successful, or non-zero if an error occurs.
Related Functions VisPicLoad Example

Set nErrCode = VisPicFree (hPic)
VisPicLoad
Syntax hPic = VisPicLoad (nFormatFlags, sString1, sString2) Number: nFormatFlags String: sString1 String: sString2 Loads a picture into memory. A picture is either a bitmap or an icon and may be obtained from a file, a resource-only DLL, a Centura string, or a Centura resource. The maximum size of a picture is 65,633 bytes. nFormatFlags Flags indicating the type and format of the picture. One format flag and one load flag must be OR'ed together. PIC_FormatBitmap PIC_FormatIcon PIC_LoadFile PIC_LoadResource PIC_SWinRes PIC_SWinStr Meaning is determined by the nFormatFlags argument: PIC_LoadFile PIC_LoadResource PIC_SwinRes PIC_SwinStra If PIC_LoadResource is specified, contains the name of the picture resource to load. Not used for any other load flags.
Description
Parameters
sString1
sString2 Return
Number: The handle of the specified picture if successful, or NULL if an error occurs.
Related Functions VisPicFree
2-303
Chapter
Example
Resources Bitmap: BookOpen File Name: c:\mydir\bkopen.bmp ... Variables Number: hPicIcon Number: hPicBmp Number: hPicRes ... Message Actions On SAM_Create Set hPicIcon = VisPicLoad (PIC_LoadFile | PIC_FormatIcon, 'c:\\icons\\Vis.ico','')
VisSendMsgString
Syntax nResult = VisSendMsgString (hWnd, nMessage, wParam, sString) Number: hWnd Number nMessage Number: wParam String: sString Sends a message and passes a string in lParam. VisSendMsgString should be used to send Windows SDK messages to a window where a string must be passed. The string is passed as a pointer (LPSTR). hWnd nMessage wParam sString Returns Example Handle of window to send message to. Message number. WORD parameter String to pass in lParam.
Description
Parameters
Number: Return value from message.

Call VisSendMsgString (hWndItem, LB_FINDSTRING, 0, sSearchFor)
VisStrChoose
Syntax sString = VisStrChoose (bExpression, sTrueString, sFalseString) Boolean: bExpression String: sTrueString String: sFalseString Evaluates bExpression. If expression is TRUE, it returns sTrueString, else it returns sFalseString bExpression sTrueString sFalseString Returns Expression to test String returned if expression TRUE. String returned if expression FALSE.
String: sTrueString or sFalseString depending on how the expression evaluates.
Related Functions VisNumberChoose Example

Call SalMessageBox (VisStrChoose (hWnd = hWndNull, 'Window not created', 'Window created'), "Debug", MB_OK).
VisStrExpand
Syntax sString = VisStrExpand (sTemplate, hAry) String: sTemplate Number | String: hAry[*] Expands a template string by inserting one or more array elements. A template string consists of ordinary characters, and one or more expand specifications. An expand specification has the following format: %[ , ]type Expand specifications always begin with a percent sign and are read from left to right. When the first expand specification is encountered, the value of the first array element is converted and inserted into the return string. The second expand specification causes the second element to be inserted, and so on. If there are more array elements than expand specifications, the extra elements are ignored. Valid types are s, n, and u. If braces {} are specified in the template, the text between the braces is repeated. If a comma is specified between the percent sign and the type character, each repeat string is comma delimited before the repeat string, except the first element.
Description
2-305
Chapter
Parameters
sTemplate hAry
Template to expand. Array to expand into template. hAry may be a number array or a string array.
Return
String: The expanded string.
Related Functions VisStrSubstitute Example

Variables String: sReplaceAry[*] Actions Set sReplaceAry[1] = 'myfile' Call SalMessageBox (VisStrExpand ('Error:%s File:%s', sReplaceAry), 'Title', MB_Ok)
VisStrFind
Syntax sString = VisStrFind (hStrTable, sIdentifier) Number: hStrTable String: sIdentifier Locates a string within a string table. The string table must be loaded into memory using VisStrLoadTable. hStrTable sIdentifier Returns Handle to string table to load string from. Identifier used to located the string within the string table. Identifiers are enclosed within braces {} in the string table.
String: The located string, or null string if not found. The entire string after the trailing brace of the identifier is returned.
Related Functions VisStrFreeTable, VisStrLoadTable Example

On SAM_AppStartup Set hStrTable = VisStrLoadTable ('MyStrings.txt') Set sString = VisStrFind (hStrTable, 'dbError.MyString')
VisStrFreeTable
Syntax Description Parameters Returns bOk = VisStrFreeTable (hStrTable) Number: hStrTable Frees all memory associated with a string table. hStrTable Handle to string table to free from memory.
Related Functions VisStrFind, VisStrLoadTable Example

Set bOk = VisStrFreeTable (hStrTable)
VisStrLeftTrim
Syntax Description Parameters Return sString = VisStrLeftTrim (sSource) String: sSource Trims leading blanks from a string. sSource Source string.
String: The trimmed string.
Related Functions VisStrRightTrim, VisStrTrim Example

Set sTarget = VisStrLeftTrim (' ABC ') ! sTarget = 'ABC '
VisStrLoadTable
Syntax Description Parameters Returns hStrTable = VisStrLoadTable (sFileName) String: sFileName Loads a string table from disk into memory. The maximum size of a string table is 65,533 bytes. sFileName File name of string table to load. If no path is specified, the current drive/directory is searched.
String: The handle of the string table if successful, or negative if an error occurs.
2-307
Chapter
Related Functions VisStrFind, VisStrFreeTable Example Set hStrTable = VisStrLoadTable (sFileName)
VisStrPad
Syntax sString = VisStrPad (sSource, nSize) String: sSource Number: nSize Pads a string with trailing blanks and returns the result. If the length of the source string is greater than the size, the source string is truncated. sSource nSize Return String to pad to the specified size. Size of the string to return.
String: The padded string. The return string is always the size specified.
Related Functions VisStrTrim Example

Set sTarget = VisStrPad ('ABC', 10)
VisStrProper
Syntax Description sString = VisStrProper (sSource) String: sSource Converts a string to mixed case. If the string is all lowercase, the first letter of each word is capitalized. If the string is all uppercase, the first letter of each word is left capitalized while the remaining letters are made lowercase. Before the source string is converted, the following delimiters are removed: ~!@#$%^&*()_+-=|\[]{}:";'?,./. After the conversion, the delimiters are reinserted. The first letter following Mc, Mac, or O' are also capitalized. sSource Source string.
Parameters Return Example
String: The converted string.

Set sTarget = VisStrProper ('M.L. SMITH')
VisStrRightTrim
Syntax Description Parameters Return sString = VisStrRightTrim (sSource) String: sSource Trims trailing blanks from a string. sSource Source string.
Related Functi ons VisStrLeftTrim, VisStrTrim Example

Set sTarget = VisStrRightTrim (' ABC ')
VisStrScanReverse
Syntax nOffset = VisStrScanReverse (sSource, nPos, sSearchFor) String: sSource Number: nPos String: sSearchFor Scans a string for a specified sub-string from the last character to the first. Case is ignored when performing the search. sSource nPos sSearchFor Return Example Source string to search. Position to begin the search, -1 to begin searching from the last character. String to search for.
Number: The position of search string, -1 if string not found.

Set nOffset = VisStrScanReverse ('c:\\path\\file', -1, '\\') If nOffset = 0 ...
VisStrSubstitute
Syntax sString = VisStrSubstitute (sSource, sSearch, sReplace) String: sSource String: sSearch String: sReplace
2-309
Chapter
Substitutes all occurrences of one string with another string. sSource sSearch sReplace Source string. String to search for. Replacement string.
Return Example
String: The modified string.

Set sTarget = VisStrSubstitute ('12ABC34ABC', 'ABC', '*' ! sTarget = '12*34*'
VisStrTrim
Syntax Description Parameters Return sString = VisStrTrim (sSource) String: sSource Trims leading and trailing blanks from a string. It does not adjust embedded brackets. sSource Source string
Related Functions VisStrLeftTrim, VisStrRightTrim Example

Set sTarget = VisStrTrim (' ABC ') ! sTarget = 'ABC'
VisTblAllRows
Syntax bOk = VisTblAllRows (hWndTable, nFlagsOn, nFlagsOff) Handle: hWndTable Number: nFlagsOn Number: nFlagsOff Determines whether any rows in the specified table window match certain flags. If multiple flags are specified in the nFlagsOn parameter, all specified flags must match the row flags (an AND operation is used to test the flags). hWndTable nFlagsOn nFlagsOff Table window handle. Bit flags to test, all bits must exist in the row flag for a valid match. Bit flags that the row cannot have. The row cannot have any of the flags specified.
Description
Parameters
ROW_Edited ROW_Hidden ROW_HideMarks ROW_MarkDeleted ROW_New ROW_Selected Returns Example Boolean: TRUE if successful, or FALSE if an error occurs.
If VisTblAllRows (twTable, ROW_New | ROW_Selected, 0)
VisTblAutoSizeColumn
Syntax bOk = VisTblAutoSizeColumn (hWndTable, hWndColumn) Handle: hWndTable Handle: hWndColumn Performs a best fit on the display contents of a specific column. A best fit will resize a column based on the current contents of the displayed columns. The column heading and split window contents are included in calculating the width. hWndTable hWndColumn Returns Example Table window handle. Column window handle to auto size. Specify hWndNULL to size all columns.
Description
Parameters

Call VisTblAutoSizeColumn (twTable, colPrice)
VisTblClearColumnSelection
Syntax Description Parameters Returns Example bOk = VisTblClearColumnSelection (hWndTable) Handle: hWndTable Clears selection for all columns of a table window. hWndTable Table window handle.

Call VisTblClearColumnSelection (hWndForm)
2-311
Chapter
VisTblFindDateTime
Syntax nRow = VisTblFindDateTime (hWndTable, nStartRow, hWndColumn, dtDateTime) Handle: hWndTable Number: nStartRow Number: hWndColumn Date/Time: dtDateTime Locates a date/time value within a column. Searching ends when the last row in the table is checked. A SAM_FetchRow message is sent for all rows that have not yet been fetched into the cache. hWndTable nStartRow hWndColumn dtDateTime Returns Table window handle. Row number to start the search at. Handle of column to search or hWndNULL to search all date/ time columns. Date/time to search for.
Description
Parameters
Number: The row number if date/time is found, -1 if not found.
Related Functions VisTblFindNumber, VisTblFindString Example

Set nRow = VisTblFindDateTime (twOrders, 0, colOrderDate, '10-10-88')
VisTblFindNumber
Syntax nRow = VisTblFindNumber (hWndTable, nStartRow, hWndColumn, nNumber) Handle: hWndTable Number: nStartRow Number: hWndColumn Number: nNumber Locates a number value within a column. Searching ends when the last row in the table is checked. A SAM_FetchRow message is sent for all rows that have not yet been fetched into the cache. hWndTable nStartRow hWndColumn nNumber 2-312 Centura Builder Function Reference Table window handle. Row number to start the search at. Handle of column to search or hWndNULL to search all number columns. Number to search for.
Description
Parameters
Returns
Number: The row number if number is found, -1 if not found.
Related Functions VisTblFindDateTime, VisTblFindString Example

Set nRow = VisTblFindNumber (twOrders, 0, colPrice, 100)
VisTblFindString
Syntax nRow = VisTblFindString (hWndTable, nStartRow, hWndColumn, sString) Handle: hWndTable Number: nStartRow Number: hWndColumn String: sString Locates a string value within a column. The string must match exactly and case is ignored. Searching ends when the last row in the table is checked. A SAM_FetchRow message is sent for all rows that have not yet been fetched into the cache. 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. Parameters hWndTable nStartRow hWndColumn sString Returns Table window handle. Row number to start the search at. Handle of column to search or hWndNULL to search all string columns. String to search for.
Description
Number: The row number if string is found, -1 if not found.
Related Functions VisTblFindDateTime, VisTblFindNumber Example

Set nRow = VisTblFindString (twOrders, 0, colDesc, 'Widget')
2-313
Chapter
VisTblGetCell
Syntax sText = VisTblGetCell (hWndTable, nRow, hWndColumn) Number: nRow Handle: hWndColumn Retrieves the contents of a cell in a table window. The row specified will be set to the context row. hWndtable nRow hWndColumn Returns Table window handle. Row number to obtain data from. Column window handle to retrieve text.
String: The cell text, or null string if error occurs.
Related Functions VisTblGetColumnTitle Example

Set sText = VisTblGetCell (10, colName)
VisTblGetColumnTitle
Syntax Description Parameters sTitle = VisTblGetColumnTitle (hWndColumn) Handle: hWndColumn Retrieves the contents of a column heading. The row specified will be set to the context row. hWndTable hWndColumn Returns Table window handle. Column window handle to retrieve column heading for.
String: The column heading, or null string if error occurs.
Related Functions VisTblGetCell Example

Set sTitle = VisTblGetColumnTitle (colName)
VisTblSetRowColor
Syntax bOk = VisTblSetRowColor (hWndTable, nRow, nColor) Handle: hWndTable Number: nRow Number: nColor Sets the text color for an entire row of a table window. hWndTable nRow nColor Returns Table window handle. Row number to set the text color for. Color to set for all columns of the row specified.
Related Functions VisTblSetRowPicture, VisTblGetColumnTitle Example

Call VisTblSetRowColor (twOrders, 10, COLOR_Red)
VisTblSetRowPicture
Syntax bOk = VisTblSetRowPicture (hWndTable, nRowFlag, hPic) Handle: hWndTable Number: nRowFlag Number: hPic Sets the picture for a bit flag of a table window. When any row contains the bit flag specified, the picture will be drawn in the row header portion of the table window. Centura normally displays pictures for the ROW_New, ROW_Edited, and ROW_MarkDeletedFlags. The Centura pictures will no longer be displayed after the first call to VisTblSetRowPicture. The picture will simply be inverted when the row is selected. A second picture cannot be displayed when the row is selected. hWndTable nRowFlag Table window handle. Row flag to trigger the display of the picture specified. Pictures may be set for any of the following row flags: ROW_New ROW_Edited ROW_Markdeleted ROW_UserFlag1 ROW_UserFlag2 ROW_UserFlag3 ROW_UserFlag4
Description
Parameters
2-315
Chapter
hPic
ROW_UserFlag5 Picture to display in the row header when the row contains the specified row flag. This must be a bitmap; it cannot be an icon. Call VisPicLoad to create a picture handle.
Returns
Related Functions VisTblSetRowColor Example

On SAM_Create Set hPic = VisPicLoad (PIC_Load Resource | PIC_FormatBitmap, 'Vis.dll', VISPIC_CheckBlack) Call VisTblSetRowPicture (twOrders, ROW_New, hPic)
VisWaitCursor
Syntax Description bOk = VisWaitCursor (nFlags) Number: nFlags Turns hourglass cursor on or off. Differs from SalWaitCursor in the following ways: 1. 2. 3. Disables the current application when the hourglass is turned on and enables the application when the hourglass is turned off. Shows hourglass cursor if no mouse is present (shown in miiddle of screen). Keeps a reference count each time the hourglass is turned on. Turns the hourglass off only when the reference count is equal to zero. This allows VisWaitCursor to be embedded in low-level functions. TRUE to display the cursor as an hourglass and FALSE to display as an arrow. TRUE FALSE WAIT_SysModalOn WAIT_SysModalOff WAIT_TempOn WAIT_TempOff Return Example Boolean: No return value.
Call VisWaitCursor (WAIT_TempOff) Call SalMessageBox ('Error Occurred', 'Error', MB_OK) Call VisWaitCursor (WAIT_TempOn)
Parameters
nFlags
VisWinClearAllEditFlags
Syntax Description nNumCleared = VisWinClearAllEditFlags (hWnd{Parent) Window Handle: hWndParent Clears the field edit flags for each data field or multi-line text field of a parent window. To prevent clearing an edit flag for an individual window, set the WF_NoClearEditFlag flag with a call to VisWinSetFlags. hWndParent Window handle of parent window to clear all edit flags of.
Parameters Return
Number: The number of fields cleared, or negative if an error occurs.
Related Functions VisWinClearAllFields Example

Message Actions On SAM_Create Call VisWinSetFlags (hWndItem, SWF_NoClearEditFlag) Actions Call VisWinClearAllEditFlags (hWndForm)
VisWinClearAllFields
Syntax Description nNumCleared = VisWinClearAllFields (hWndParent) Window Handle: hWndParent Clears all child fields of a parent window. Data fields, multi-line text, list boxes, combo boxes, check boxes, radio buttons, and child table windows are cleared. To prevent clearing a window, set the WF_NoClear flag with a call to VisWinSetFlags. hWndParent Window handle of parent window to clear all child fields of.
Parameters Return
Number: The number of fields cleared, or negative if an error occurs.
Related Functions VisWinClearAllEditFlags
2-317
Chapter
Example
Message Actions On SAM_Create Call VisWinSetFlags (hWndItem, SWF_NoClear) Actions Call VisWinClearAllFields (hWndForm)
VisWinEnumProps
Syntax nNumItems = VisWinEnumProps (hWnd, sPropStrings, sValues) Window Handle: hWnd String: sPropStrings[*] String: sValues[*] Enumerates the property list for a specified window. A property list can be used to define application-specific attributes for a window. Use property lists sparingly as each string takes up system resource space. hWnd sPropStrings sValues Return Window handle of window to get the property list of. Array to contain all the property list strings. Array to contain the property values.
Description
Parameters
Number: The number of property list entries returned, or -1 if window handle is invalid.
Related Functions VisWinGetProp, VisWinRemoveProp, VisWinSetProp Example

Variables String: sPropStrings[*] Number: nPropValues[*] ... Actions Set dfReturn = VisWinEnumProps (hWndForm, sPropStrings, nPropValues)
VisWinFreeAccelerator
Syntax Description Parameters bOk = VisWinFreeAccelerator (hAcc) Handle: hAcc Clears an accelerator for a window, along with all memory associated with the accelerator. hAcc Handle to accelerator.
Returns
Related Functions VisWinGetProp Example Set bOk = VisWinFreeAccelerator (hAcc)
VisWinGetFlags
Syntax Description Parameters Returns nWinFlags = VisWinGetFlags (hWnd) Handle: hWnd Retrieves window flags for a window. hWndWindow handle to retrieve flags for. Number: The window flags of window specified. To test a bit flag, use the bitwise AND (&) operator. Options are: WF_Required WF_NoClear WF_NoClearEditFlag WF_EnableWhenNotNull WF_FitPath WF_DisplayOnly Related Functions VisWinSetFlags Example
Actions Set nFlags = VisWinGetFlags (hWndForm)
VisWinGetHandle
Syntax hWnd = VisWinGetHandle (hWndDialog, sContext, nWindowType) Window Handle: hWndDialog String: sContext Number: nWindowType Obtains a window handle based on the window type and a context string. Under Centura, the bStaticsAsWindows variable must be set to TRUE in order for Centura to create actual windows. Otherwise, Centura paints the background text and the window handle does not exist. hWndDialog Window handle of dialog box containing window handles to search for.
Description
Parameters
2-319
Chapter
sContext nWindowType
Context string to uniquely identify the window. Centura type: TYPE_BkgdText TYPE_GroupBox
Return Example
Window Handle: The window handle if successful, or NULL if window not found.
Actions Set hWnd = VisWinGetHandle (hWndForm, 'Sample:', TYPE_BkgdText)
VisWinGetProp
Syntax nValue = VisWinGetProp (hWnd, sPropString) Window Handle: hWnd String: sPropString Retrieves a value from the property list of a specified window. A property list can be used to define application-specific attributes for a window. Use property lists sparingly as each string takes up system resource space. hWnd sPropString Return Window handle of window to get the property list for. Context string used to identify the property list.
Description
Parameters
Number: The property value of the window. Zero may indicate no property exists, or the window has a property with the value of zero.
Related Functions VisWinRemoveProp, VisWinSetProp Example

Set nValue = VisWinGetProp (hWnd, sPropString)
VisWinGetStyle
Syntax Description Parameters Return nStyle = VisWinGetStyle (hWnd) Window Handle: hWnd Retrieves the Windows style bits for a specified window. These style bits are documented in the Windows SDK documentation. hWnd Window handle of window to retrieve style bits of.
Number: The style bits of the window specified, or -1 if window is invalid.
Related Functions VisWinSetStyle Example

Variables Number: nStyle ... Actions Set nStyle = VisWinGetStyle (hWndForm)
VisWinGetText
Syntax Description sString = VisWinGetText (hWnd) Window Handle: hWnd Obtains 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, multi-line text field or table window column, window text is the current contents. Note: Use VisTblGetColumnTitle to get the title of a table window column. hWnd Window to obtain text for.
Parameters Returns Example
String: The window text, if successful, or null string if error occurs.

Radio Button: rbSample Title: Option: ... Actions Set sText = VisWinGetText (rbSample) ! sText = 'Option:'
VisWinIsChild
Syntax bOk = VisWinIsChild (hWndParent, hWndChild) Window Handle: hWndParent Window Handle: hWndChild Tests whether a specified window is a child or direct descendant of a parent window. hWndParent hWndChild Return Window handle of parent window. Window handle of child window to test for.
Boolean: TRUE if child is a descendant, FALSE if not a descendant.
2-321
Chapter
Related Functions VisWinIsWindow Example

Actions If VisWinIsChild (hWndForm, pbOk) ...
VisWinIsMaximized
Syntax Description Parameters Return bOk = VisWinIsMaximized (hWnd) Window Handle: hWnd Tests whether a specified window is maximized. hWnd Window handle of window to test.
Boolean: TRUE if window maximized, FALSE if not maximized.
Related Functions VisWinIsMinimized, VisWinIsRestored Example

Actions If VisWinIsMaximized (hWndForm)
VisWinIsMinimized
Syntax Description Parameters Return bOk = VisWinIsMinimized (hWnd) Window Handle: hWnd Tests whether a specified window is minimized. hWnd Window handle of window to test.
Boolean: TRUE if window minimized, FALSE if not minimized
Related Functions VisWinIsMaximized, VisWinIsRestored Example

Actions If VisWinIsMinimized (hWndForm)
VisWinIsRequiredFieldNull
Syntax Description Parameters hWnd = VisWinIsRequiredFieldNull (hWndParent) Handle: hWndParent Tests to determine if any required field is null. hWndParent Handle of parent window to test. If any child window is required and contains a null value, VisWinIsRequiredFieldNull returns TRUE.
Returns Example
Window Handle: Handle of first required field that contains no value, or null if all required fields are non-null.
Dialog Box: dbTest Contents Data Field: dfPrice ... Message Actions On SAM_Create Call VisWinSetFlags (hWndItem, SWF_Required) ... Pushbutton: pbOk ... Message Actions On SAM_Click Set hWnd = VisWinIsRequiredFieldNull (dbTest) If hWnd Call SalMessageBox ('Required field contains no value', 'Error', MB_OK) Call SalSetFocus (hWnd) Return FALSE
VisWinIsRestored
Syntax Description Parameters Return bOk = VisWinIsRestored (hWnd) Window Handle: hWnd Tests whether a specified window is neither maximized or minimized. hWnd Window handle of window to test.
Boolean: TRUE if window restored, FALSE if not maximized or minimized
2-323
Related Functions VisWinIsMaximized, VisWinIsMinimized Example

Actions If VisWinIsRestored (hWndForm)
VisWinIsWindow
Syntax Description Parameters Return bOk = VisWinIsWindow (hWnd) Window Handle: hWnd Tests whether a specified window is valid. hWnd Window handle of window to test.
Boolean: TRUE if window valid, FALSE if invalid
Related Functions VisWinIsChild Example

Actions If VisWinIsWindow (hWndForm)
VisWinLoadAccelerator
Syntax hAcc = VisWinLoadAccelerator (hWndNotify, nMsg, nKeyDownState, nVirtualKey, nValue) Handle: hWndNotify Number: nMsg Number: nKeyDownState Number: nVirtualKey Number: nValue Sets an accelerator keystroke for a window. If the accelerator is pressed, the specified window is notified with the specified message. The lParam of the message sent will contain the accelerator handle. hWndNotify nMsg nKeyDownState Window to notify when the accelerator is pressed. Message to send to the window specified when the accelerator is pressed. Flag indicating the keys held down in combination with the virtual key. Options are: KDS_None KDS_Shift
Description
Parameters
nVirtualKey nValue
KDS_Ctrl KDS_ShiftCtrl KDS_Alt KDS_AltCtrl KDS_AltShift KDS_ShiftAltCtrl Virtual key to act as accelerator. See the Appendix for a complete listing of virtual key codes. Any application defined value that will be passed in lParam of the message sent when the accelerator is pressed. This can be used to pass menu ID values when menu accelerators are used.
Returns
Handle: Handle to accelerator if successful, NULL if an error occurs.
Related Functions VisWinFreeAccelerator Example

Pushbutton: pbExpand Variables Number: hAcc ... Message Actions On SAM_Create Set hAcc = VisWinLoadAccelerator (pbExpand, SAM_Click, KDS_Alt, VK_Plus, 0) On SAM_Destroy Call VisWinFreeAccelerator (hAcc)
VisWinMove
Syntax bOk = VisWinMove (hWnd, nLeft, nTop, nWidth, nHeight) Handle: hWnd Number: nLeft Number: nTop Number: nWidth Number: nHeight Moves and resizes a window, based on pixel coordinates. If the window is a form window or table window, the coordinates are relative to the screen. If the window is a child window, the coordinates are relative to the parent window's client area. hWnd Handle of window to move.
Description
Parameters
2-325
Chapter
nLeft nTop nWidth nHeight Returns Example
Identifies the new position of the left side of the window. Identifies the new position of the top of the window. Identifies the new width of the window. Identifies the new height of the window.

Actions Call VisWinMove (hWnd, 10, 25, 425, 200)
VisWinRemoveProp
Syntax bOk = VisWinRemoveProp (hWnd, sPropString) Window Handle: hWnd String: sPropString Removes a property list entry for a specified window. A property list can be used to define application-specific attributes for a window. Use property lists sparingly as each string takes up system resource space. hWnd sPropString Return Window handle of window to remove the property list from. Context string used to identify the property list.
Description
Parameters
Boolean: TRUE is entry was removed, FALSE if window handle invalid or property does not exist.
Related Functions VisWinGetProp, VisWinSetProp Example Set bOk = VisWinRemoveProp (hWnd, sPropString)
VisWinSetFlags
Syntax bOk = VisWinSetFlags (hWnd, nWinFlags, bState) Handle: hWnd Number: nWinFlags Boolean: bState Sets flags for a specified window. hWnd nWinFlags Window handle to set flags for. Window flags to set. Options are: WF_Required WF_NoClear 2-326 Centura Builder Function Reference
bState Returns
WF_NoClearEditFlag WF_EnableWhenNotNull WF_FitPath WF_DisplayOnly TRUE to set the flags, FALSE to remove the flags.
Related Functions VisWinGetFlags Example

On SAM_Create Call VisWinSetFlags (hWndItem, SWF_DisplayOnly, TRUE)
VisWinSetMeter
Syntax nErrCode = VisWinSetMeter (hWnd, nPercent) Window Handle: hWnd Number: nPercent Displays a completion meter within a Centura data field. The complete portion is displayed in the current text color and the incomplete portion is displayed in the current background color. hWnd nPercent Return Example Window handle of a data field to display the completion meter in. This must be the window handle of a data field. Percentage complete to display within meter (0-100).
Description
Parameters
Number: Zero if successful, or negative if an error occurs.

Actions Call VisWinSetMeter (dbMeter, 0)
VisWinSetProp
Syntax bOk = VisWinSetProp (hWnd, sPropString, nValue) Window Handle: hWnd String: sPropString Number: nValue Adds a new property list entry or changes an existing property list entry for a specified window. A property list can be used to define application-specific attributes for a window. Use property lists sparingly as each string takes up system resource space.
Description
2-327
Chapter
Parameters
hWnd sPropString nValue
Window handle of window to set the property list for. Context string used to identify the property. Value stored with the property (application specific).
Return
Boolean: TRUE if entry was added or changed, FALSE if window handle invalid.
Related Functions VisWinGetProp, VisWinRemoveProp Example Set bOk = VisWinSetProp (hWnd, sPropString, nValue)
VisWinSetStyle
Syntax bOk = VisWinSetStyle (hWnd, nStyle, bState) Window Handle: hWnd Number: nStyle Boolean: bState Adds a window style to a window. It does not set the style to the style bits passed in, rather it adds or removes the style bits to the current style of the window. hWnd nStyle bState Return Window handle of window to change style of. Style bits to set or clear. The style bits are documented in the Windows SDK documentation. TRUE to turn the style bits on or FALSE to turn style bits off.
Boolean: TRUE if the function succeeded, FALSE if the function failed.
Related Functions VisWinGetStyle Example

Actions Call VisWinSetStyle (hWndItem, ES_AUTOHSCROLL)
VisWinSetTabOrder
Syntax bOk = VisWinSetTabOrder (hWnd, hWndInsertAfter) Window Handle: hWnd Window Handle: hWndInsertAfter Changes the tab order of a control. If hWndInsertAfter is NULL, the window is removed from the tab order. hWnd hWndInsertAfter Return Example Window handle of window to set tab order. Window handle of window to be inserted after this window.

Actions Call VisWinSetTabOrder (hWndItem, NULL)
VisWinShow
Syntax bOk = VisWinShow (hWnd, nShowFlag) Window Handle: hWnd Number: nShowFlag Sets a window's visibility state. hWnd nShowFlag Window handle of window to show. Specifies how the window is to be shown: SHOW_Hidden SHOW_Minimized SHOW_Maximized SHOW_Normal Return Example Boolean: TRUE if window previously was visible, FALSE if previously hidden.
Actions Call VisWinShow (hWndForm, SHOW_Maximized)
2-329
Index
A
array functions 1-17 prints 1-43 reports 1-43 scroll bar 1-44 SQL 1-44 string conversion 1-47 table window 1-48 window management 1-51
C
Centura function categories 1-17 Centura functions 1-1, 2-1 types system 1-2 Centura system functions 1-2 obsolete 1-16 color and font functions 1-17 Compuserve xxvii Conventions used in the manual xxvi
L
list and combo box functions 1-31
M
Manipulating Background Text functions 1-33 Manipulating background text functions 1-33 Manual description of xxvi MDI functions 1-36 message functions 1-36 miscellaneous functions 1-37
D
data type conversion functions 1-19 date functions 1-20 DDE functions 1-21 debugging functions 1-22 dialog box functions 1-23 drag drop functions 1-25
N
number functions 1-40
E
edit functions 1-26
P
picture functions 1-42 print functions 1-43
F
file management functions 1-27 format and validation functions 1-29 functions array 1-17 data type conversion 1-19 date 1-20 DDE 1-21 debugging 1-22 dialog box 1-23 drag drop 1-25 edit 1-26 file management 1-27 format and validation 1-29 list and combo box 1-31 manipulating background text 1-33 MDI 1-36 message 1-36 miscellaneous 1-37 number 1-40 picture 1-42
S
SalAbort 2-2 SalAppDisable 2-2 SalAppEnable 2-3 SalAppFind 2-3 SalArrayAvg 2-4 SalArrayDimCount 2-4 SalArrayGetLowerBound 2-5 SalArrayGetUpperBound 2-5 SalArrayIsEmpty 2-6 SalArrayMax 2-7 SalArrayMin 2-7 SalArraySetUpperBound 2-8 SalArraySum 2-8 SalBringWindowToTop 2-9 SalCenterWindow 2-9 SalClearField 2-10 SalColorFromRGB 2-10 SalColorGet 2-11 SalColorGetSysColor 2-11
Index-1

SalColorSet 2-12 SalColorToRGB 2-13 SalCompileAndEvaluate 2-13 SalContextCurrent 2-15 SalCreateWindow 2-15 SalCreateWindowExWithParms 2-16 SalCursorClear 2-18 SalCursorSet 2-18 SalCursorSetFile 2-19 SalCursorSetString 2-19 SalDateConstruct 2-20 SalDateCurrent 2-21 SalDateDay 2-21 SalDateHour 2-21 SalDateMinute 2-22 SalDateMonth 2-22 SalDateMonthBegin 2-22 SalDateQuarter 2-23 SalDateQuarterBegin 2-23 SalDateSecond 2-23 SalDateToStr 2-24 SalDateWeekBegin 2-24 SalDateWeekday 2-25 SalDateYear 2-25 SalDateYearBegin 2-25 SalDDEAddAtom 2-26 SalDDEAlloc 2-26 SalDDEDeleteAtom 2-27 SalDDEExtract 2-27 SalDDEExtractCmd 2-27 SalDDEExtractDataText 2-28 SalDDEExtractOptions 2-28 SalDDEFindAtom 2-29 SalDDEFree 2-29 SalDDEGetAtomName 2-30 SalDDEGetExecuteString 2-30 SalDDEPost 2-30 SalDDERequest 2-31 SalDDESend 2-32 SalDDESendAll 2-32 SalDDESendExecute 2-33 SalDDESendToClient 2-34 SalDDESetCmd 2-34 SalDDESetDataText 2-35 SalDDESetOptions 2-35 SalDDEStartServer 2-36 SalDDEStartSession 2-36 SalDDEStopServer 2-37
SalDDEStopSession 2-37 SalDestroyWindow 2-37 SalDisableWindow 2-38 SalDisableWindowAndLabel 2-38 SalDlgChooseColor 2-39 SalDlgChooseFont 2-39 SalDlgOpenFile 2-40 SalDlgSaveFile 2-42 SalDragDropDisableDrop 2-43 SalDragDropEnableDrop 2-44 SalDragDropGetSource 2-44 SalDragDropGetTarget 2-45 SalDragDropStart 2-45 SalDragDropStop 2-45 SalDrawMenuBar 2-46 SalDropFilesAcceptFiles 2-46 SalDropFilesQueryFiles 2-47 SalDropFilesQueryPoint 2-48 SalEditCanCopyTo 2-48 SalEditCanCut 2-49 SalEditCanPaste 2-49 SalEditCanPasteFrom 2-49 SalEditCanUndo 2-50 SalEditClear 2-50 SalEditCopy 2-50 SalEditCopyString 2-51 SalEditCopyTo 2-51 SalEditCut 2-51 SalEditPaste 2-52 SalEditPasteFrom 2-52 SalEditPasteString 2-53 SalEditUndo 2-53 SalEnableWindow 2-54 SalEnableWindowAndLabel 2-54 SalEndDialog 2-54 SalFileClose 2-55 SalFileCopy 2-55 SalFileCreateDirectory 2-56 SalFileGetC 2-56 SalFileGetChar 2-57 SalFileGetCurrentDirectory 2-57 SalFileGetDateTime 2-57 SalFileGetDrive 2-58 SalFileGetStr 2-58 SalFileOpen 2-59 SalFileOpenExt 2-59 SalFilePutC 2-60 SalFilePutChar 2-60
Index-2
SalFilePutStr 2-61 SalFileRead 2-61 SalFileRemoveDirectory 2-62 SalFileSeek 2-62 SalFileSetCurrentDirectory 2-63 SalFileSetDateTime 2-63 SalFileSetDrive 2-63 SalFileTell 2-64 SalFileWrite 2-64 SalFmtFieldToStr 2-64 SalFmtFormatDateTime 2-65 SalFmtFormatNumber 2-66 SalFmtGetFormat 2-66, 2-67 SalFmtGetInputMask 2-67 SalFmtIsValidField 2-68 SalFmtIsValidInputMask 2-69 SalFmtIsValidPicture 2-69 SalFmtKeepMask 2-70 SalFmtSetFormat 2-71 SalFmtSetInputMask 2-72 SalFmtSetPicture 2-72 SalFmtStrToField 2-73 SalFmtUnmaskInput 2-73 SalFmtValidateField 2-74 SalFontGet 2-74 SalFontGetNames 2-75 SalFontGetSizes 2-75 SalFontSet 2-76 SalFormGetParmNum 2-76 SalFormUnitsToPixels 2-77 SalGetDataType 2-77 SalGetDefButton 2-78 SalGetFirstChild 2-78 SalGetFocus 2-79 SalGetItemName 2-79 SalGetMaxDataLength 2-79 SalGetNextChild 2-80 SalGetProfileInt 2-80 SalGetProfileString 2-81 SalGetType 2-82 SalGetVersion 2-82 SalGetWindowLabelText 2-83 SalGetWindowLoc 2-83 SalGetWindowSize 2-84 SalGetWindowState 2-84 SalGetWindowText 2-84 SalHideWindow 2-85 SalHideWindowAndLabel 2-85
SalHStringToNumber 2-86 SalInvalidateWindow 2-86 SalIsButtonChecked 2-86 SalIsNull 2-87 SalIsValidDateTime 2-87 SalIsValidDecimal 2-87 SalIsValidInteger 2-88 SalIsValidNumber 2-89 SalIsWindowEnabled 2-89 SalIsWindowVisible 2-89 SalListAdd 2-90 SalListClear 2-90 SalListDelete 2-91 SalListFiles 2-91 SalListGetMultiSelect 2-92 SalListInsert 2-92 SalListPopulate 2-92 SalListQueryCount 2-93 SalListQueryFile 2-94 SalListQueryMultiCount 2-94 SalListQuerySelection 2-94 SalListQueryState 2-95 SalListQueryText 2-95 SalListQueryTextLength 2-96 SalListQueryTextX 2-95, 2-96 SalListRedraw 2-96 SalListSelectString 2-97 SalListSetMultiSelect 2-97 SalListSetSelect 2-98 SalListSetTabs 2-98 SalLoadApp 2-99 SalLoadAppAndWait 2-99 SalMapEnterToTab 2-101 SalMDIArrangeIcons 2-101 SalMDICascade 2-101 SalMDITile 2-102 SalMessageBeep 2-102 SalMessageBox 2-103 SalModalDialog 2-104 SalModalDialogFromStr 2-106 SalMoveWindow 2-106 SalNumberAbs 2-107 SalNumberArcCos 2-107 SalNumberArcSin 2-107 SalNumberArcTan 2-108 SalNumberArcTan2 2-108 SalNumberCos 2-108 SalNumberCosH 2-109
Index-3

SalNumberExponent 2-109 SalNumberHigh 2-109 SalNumberHypot 2-110 SalNumberLog 2-110 SalNumberLogBase10 2-110 SalNumberLow 2-111 SalNumberMax 2-111 SalNumberMin 2-111 SalNumberMod 2-112 SalNumberPi 2-112 SalNumberPower 2-112 SalNumberRandInit 2-113 SalNumberRandom 2-113 SalNumberRound 2-114 SalNumberSin 2-114 SalNumberSinH 2-114 SalNumberSqrt 2-115 SalNumberTan 2-115 SalNumberTanH 2-115 SalNumberToChar 2-116 SalNumberToHString 2-116 SalNumberToStr 2-116 SalNumberToStrX 2-117 SalNumberToWindowHandle 2-117 SalNumberTruncate 2-118 SalParentWindow 2-118 SalPicClear 2-119 SalPicGetDescription 2-119 SalPicGetString 2-120 SalPicSet 2-120 SalPicSetFile 2-121 SalPicSetFit 2-121 SalPicSetString 2-122 SalPixelsToFormUnits 2-123 SalPostMsg 2-123 SalPrtExtractRect 2-124 SalPrtGetDefault 2-124 SalPrtGetParmNum 2-125 SalPrtPrintForm 2-125 SalPrtSetDefault 2-126 SalPrtSetParmDefaults 2-126 SalPrtSetParmNum 2-127 SalPrtSetup 2-127 SalQueryFieldEdit 2-128 SalQuit 2-128 SalReportClose 2-129 SalReportCmd 2-129 SalReportCreate 2-129
SalReportDlgOptions 2-130 SalReportGetDateTimeVar 2-131 SalReportGetNumberVar 2-131 SalReportGetObjectVar 2-132 SalReportGetStringVar 2-132 SalReportPrint 2-133 SalReportPrintToFile 2-134 SalReportReset 2-136 SalReportSetDateTimeVar 2-136 SalReportSetNumberVar 2-137 SalReportSetObjectVar 2-137 SalReportSetStringVar 2-138 SalReportTableCreate 2-138 SalReportTablePrint 2-139 SalReportTableView 2-140 SalReportView 2-140 SalScrollGetPos 2-142 SalScrollGetRange 2-142 SalScrollSetPos 2-143 SalScrollSetRange 2-143 SalSendClassMessage 2-144 SalSendClassMessageNamed 2-144 SalSendMsg 2-145 SalSendMsgToChildren 2-145 SalSendValidateMsg 2-146 SalSetDefButton 2-146 SalSetFieldEdit 2-147 SalSetFocus 2-147 SalSetMaxDataLength 2-148 SalSetProfileString 2-148 SalSetWindowLabelText 2-149 SalSetWindowLoc 2-149 SalSetWindowSize 2-149 SalSetWindowText 2-150 SalShowWindow 2-150 SalShowWindowAndLabel 2-151 SalStatusGetText 2-151 SalStatusSetText 2-152 SalStatusSetVisible 2-152 SalStrCompress 2-152 SalStrFirstC 2-153 SalStrGetBufferLength 2-153 SalStrIsValidCurrency 2-154 SalStrIsValidDateTime 2-154 SalStrIsValidNumber 2-155 SalStrLeft 2-155 SalStrLeftX 2-156 SalStrLength 2-156
Index-4
SalStrLop 2-157 SalStrLower 2-157 SalStrMid 2-158 SalStrProper 2-158 SalStrRepeat 2-159 SalStrRepeatX 2-159 SalStrReplace 2-159 SalStrReplaceX 2-159 SalStrRight 2-160 SalStrRightX 2-160 SalStrScan 2-161 SalStrSetBufferLength 2-162 SalStrToDate 2-162 SalStrTokenize 2-163 SalStrToNumber 2-163 SalStrTrim 2-164 SalStrTrimX 2-164 SalStrUncompress 2-165 SalStrUpper 2-165 SalStrUpperX 2-165 SalTBarSetVisible 2-166 SalTblAnyRows 2-166 SalTblClearSelection 2-167 SalTblColumnAverage 2-167 SalTblColumnSum 2-167 SalTblCopyRows 2-168 SalTblCreateColumn 2-168 SalTblDefineCheckBoxColumn 2-169 SalTblDefineDropDownListColumn 2-170 SalTblDefinePopupEditColumn 2-170 SalTblDefineRowHeader 2-171 SalTblDefineSplitWindow 2-171 SalTblDeleteRow 2-172 SalTblDeleteSelected 2-172 SalTblDestroyColumns 2-173 SalTblDoDeletes 2-173 SalTblDoInserts 2-174 SalTblDoUpdates 2-175 SalTblFetchRow 2-175 SalTblFindNextRow 2-176 SalTblFindPrevRow 2-177 SalTblGetColumnText 2-178 SalTblGetColumnTitle 2-178 SalTblGetColumnWindow 2-178 SalTblInsertRow 2-179 SalTblKillEdit 2-179 SalTblKillFocus 2-180 SalTblPasteRows 2-180
SalTblPopulate 2-180 SalTblQueryCheckBoxColumn 2-182 SalTblQueryColumnCellType 2-182 SalTblQueryColumnFlags 2-183 SalTblQueryColumnID 2-183 SalTblQueryColumnPos 2-183 SalTblQueryColumnWidth 2-184 SalTblQueryContext 2-184 SalTblQueryDropDownListColumn 2-184 SalTblQueryFocus 2-185 SalTblQueryLinesPerRow 2-185 SalTblQueryLockedColumns 2-186 SalTblQueryPopupEditColumn 2-186 SalTblQueryRowFlags 2-187 SalTblQueryRowHeader 2-187 SalTblQueryScroll 2-188 SalTblQuerySplitWindow 2-188 SalTblQueryTableFlags 2-189 SalTblQueryVisibleRange 2-189 SalTblReset 2-189 SalTblScroll 2-190 SalTblSetCellTextColor 2-190 SalTblSetColumnFlags 2-191 SalTblSetColumnPos 2-191 SalTblSetColumnText 2-192 SalTblSetColumnTitle 2-192 SalTblSetColumnWidth 2-192 SalTblSetContext 2-193 SalTblSetFlagsAnyRows 2-193 SalTblSetFocusCell 2-194 SalTblSetFocusRow 2-195 SalTblSetLinesPerRow 2-195 SalTblSetLockedColumns 2-195 SalTblSetRange 2-196 SalTblSetRow 2-196 SalTblSetRowFlags 2-197 SalTblSetTableFlags 2-197 SalTblSortRows 2-198 SalTimerKill 2-198 SalTimerSet 2-199 SalTrackPopupMenu 2-199 SalUpdateWindow 2-200 SalUseRegistry 2-201 SalValidateSet 2-201 SalWaitCursor 2-202 SalWindowClassName 2-202 SalWindowGetProperty 2-203 SalWindowHandleToNumber 2-203
Index-5

SalWindowIsDerivedFromClass 2-203 SalWinHelp 2-204 SalYieldEnable 2-205 SalYieldQueryState 2-205 SalYieldStartMessages 2-205 SalYieldStopMessages 2-206 scroll bar functions 1-44 SQL functions 1-44 SqlClearImmediate 2-206 SqlClose 2-206 SqlCommit 2-207 SqlConnect 2-207 SqlContextClear 2-208 SqlContextSet 2-208 SqlContextSetToForm 2-209 SqlDirectoryByName 2-209 SqlDisconnect 2-209 SqlDropStoredCmd 2-210 SqlError 2-210 SqlErrorText 2-210 SqlExecute 2-211 SqlExecutionPlan 2-212 SqlExists 2-212 SqlExtractArgs 2-212 SqlFetchNext 2-213 SqlFetchPrevious 2-214 SqlFetchRow 2-214 SqlGetError 2-214 SqlGetErrorPosition 2-215 SqlGetErrorText 2-215 SqlGetErrorTextX 2-216 SqlGetLastStatement 2-216 SqlGetModifiedRows 2-217 SqlGetParameter 2-217 SqlGetParameterAll 2-218 SqlGetResultSetCount 2-218 SqlGetRollbackFlag 2-219 SqlImmediate 2-219 SqlImmediateContext 2-220 SqlOpen 2-221 SqlPLSQLCommand 2-221 SqlPrepare 2-223 SqlPrepareAndExecute 2-224 SqlRetrieve 2-225 SqlSetInMessage 2-225 SqlSetIsolationLevel 2-226 SqlSetLockTimeout 2-226 SqlSetLongBindDatatype 2-227
SqlSetOutMessage 2-228 SqlSetParameter 2-228 SqlSetParameterAll 2-229 SqlSetResultSet 2-229 SqlStore 2-230 string conversion functions 1-47
T
table window functions 1-48
V
VisArrayAppend 2-231 VisArrayCopy 2-227 VisArrayDeleteItem 2-233 VisArrayFillDateTime 2-233 VisArrayFillNumber 2-234 VisArrayFillString 2-234 VisArrayFindDateTime 2-235 VisArrayFindNumber 2-235 VisArrayFindString 2-236 VisArrayInsertItem 2-237 VisArraySort 2-237 VisDebugAssert 2-238 VisDebugBeginTime 2-239 VisDebugEndTime 2-239 VisDebugGetFlags 2-240 VisDebugSetFlags 2-240 VisDebugSetLevel 2-241 VisDebugSetTime 2-241 VisDebugString 2-242 VisDosBuildFullName 2-242 VisDosEnumDirInfo 2-243 VisDosEnumDirs 2-244 VisDosEnumDrives 2-244 VisDosEnumFileInfo 2-245 VisDosEnumFiles 2-246 VisDosEnumNetConnections 2-247 VisDosEnumPath 2-248 VisDosEnumsShortDirInfo 2-249 VisDosEnumsShortDirs 2-249 VisDosEnumsShortFileInfo 2-250 VisDosEnumsShortFiles 2-251 VisDosExist 2-251 VisDosGetCurDir 2-252 VisDosGetDriveSize 2-252 VisDosGetDriveType 2-253 VisDosGetEnvString 2-254 VisDosGetFlags 2-254
Index-6
VisDosGetNetName 2-255 VisDosGetVersion 2-255 VisDosGetVolumeLabel 2-256 VisDosIsParent 2-256 VisDosMakeAllDir 2-257 VisDosMakePath 2-257 VisDosNetConnect 2-258 VisDosNetDisconnect 2-258 VisDosSetFlags 2-259 VisDosSetVolumeLabel 2-259 VisDosSplitPath 2-260 VisErrorRecovery 2-261 VisFileAppend 2-261 VisFileClose 2-262 VisFileCopy 2-262 VisFileCreateTemp 2-263 VisFileDelete 2-263 VisFileExpand 2-263 VisFileFind 2-264 VisFileGetAttribute 2-264 VisFileGetSize 2-265 VisFileGetType 2-265 VisFileOpen 2-266 VisFileRead 2-267 VisFileReadString 2-268 VisFileRename 2-268 VisFileSeek 2-269 VisFileSetAttribute 2-269 VisFileSetDateTime 2-270 VisFileTell 2-271 VisFileWrite 2-271 VisFileWriteString 2-272 VisFontEnum 2-272 VisFontFree 2-273 VisFontGet 2-273 VisFontLoad 2-274 VisGetCopyright 2-275 VisGetKeyState 2-275 VisGetSystemMetrics 2-275 VisGetVersion 2-276 VisGetWinFlags 2-276 VisGetWinVersion 2-277 VisListAddValue 2-277 VisListArrayPopulate 2-278 VisListArrayPopulateValue 2-278 VisListClearSelection 2-279 VisListDeleteSelected 2-279 VisListFindString 2-280
VisListFindValue 2-280 VisListGetDropdownState 2-281 VisListGetFocusIndex 2-281 VisListGetVisibleRange 2-282 VisListInsertValue 2-282 VisListIsMultiSelect 2-283 VisListLoadOutline 2-283 VisListLoadOutlineFile 2-284 VisListSaveOutline 2-285 VisListScroll 2-285 VisListSetDropdownState 2-286 VisListSetFocusIndex 2-286 VisListSetScrollWidth 2-287 VisMenuGetPopupHandle 2-287 VisMenuGetSystemHandle 2-288 VisMenuGetText 2-288 VisMenuInsert 2-289 VisMenuInsertFont 2-290 VisMenuInsertPicture 2-291 VisMenuIsChecked 2-292 VisMenuIsEnabled 2-293 VisMenuSetFont 2-294 VisMenuSetPicture 2-295 VisMenuSetText 2-296 VisMenuUncheck 2-297 VisMessageBox 2-297 VisMessageFreeButton 2-298 VisMessageLoadButton 2-299 VisMessageSetBkgdColor 2-299 VisNumberBitClear 2-299 VisNumberBitSet 2-300 VisNumberChoose 2-301 VisNumberHighByte 2-301 VisNumberLowByte 2-302 VisNumberMakeLong 2-302 VisPicFree 2-302 VisPicLoad 2-303 VisSendMsgString 2-304 VisStrChoose 2-305 VisStrExpand 2-305 VisStrFind 2-306 VisStrFreeTable 2-307 VisStrLeftTrim 2-307 VisStrLoadTable 2-307 VisStrPad 2-308 VisStrProper 2-308 VisStrRightTrim 2-309 VisStrScanReverse 2-309
Index-7

VisStrSubstitute 2-309 VisStrTrim 2-310 VisTblAllRows 2-310 VisTblAutoSizeColumn 2-311 VisTblClearColumnSelection 2-311 VisTblFindDateTime 2-312 VisTblFindNumber 2-312 VisTblFindString 2-313 VisTblGetCell 2-314 VisTblGetColumnTitle 2-314 VisTblSetRowColor 2-315 VisTblSetRowPicture 2-315 VisWaitCursor 2-316 VisWinClearAllEditFlags 2-317 VisWinClearAllFields 2-317 VisWinEnumProps 2-318 VisWinFreeAccelerator 2-318 VisWinGetFlags 2-319 VisWinGetHandle 2-319 VisWinGetProp 2-320 VisWinGetStyle 2-320 VisWinGetText 2-321 VisWinIsChild 2-321 VisWinIsMaximized 2-322 VisWinIsMinimized 2-322 VisWinIsRequiredFieldNull 2-323 VisWinIsRestored 2-323 VisWinIsWindow 2-324 VisWinLoadAccelerator 2-324 VisWinMove 2-325 VisWinRemoveProp 2-326 VisWinSetFlags 2-326 VisWinSetMeter 2-327 VisWinSetProp 2-327 VisWinSetStyle 2-328 VisWinSetTabOrder 2-329 VisWinShow 2-329
W
window management functions 1-51
Index-8
Index-9

Centura Builder - Function Reference

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Centura Builder - Function Reference

Transféré par

Droits d'auteur :

Formats disponibles

Centura Builder Function Reference