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

Centura Builder Function Reference

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


v

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

x


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

Type of Information

bold type

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

italic type

Names of books and publications. Placeholders for items you must supply, such as file names. For example, when the manual says to type cd directory name you type the letters cd followed by a space and then the name of a directory.

courier type ❑

Commands or code you must enter through the keyboard exactly as shown. 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 Corporation’s 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 Centura’s 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 Corporation’s World Wide Web site contains a wealth of information about Centura Software Corporation’s partners, products, and users. The URL address is http://www.centurasoft.com. Windows User’s 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 [email protected]

Centura Builder Function Referencexxvii


Chapter 1

Centura Builder Function Tables The chapter contains functions tables that are arranged by type.


1-1

Chapter

1

Centura Builder Function Tables

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

1


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

1


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

1


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

1


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

1


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

1


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

1


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

Description

SalArrayAvg

Gets the average of values in an array of numbers

SalArrayDimCount

Gets the number of dimensions in nValue.

SalArrayGetLowerBound

Gets the lower bound of an array.

SalArrayGetUpperBound

Gets the upper bound of an array.


1-17

Chapter

1


Function Name

Description

SalArrayIsEmpty

Determines if a dynamic array contains any data.

SalArrayMax

Gets the maximum value in an array of numbers.

SalArrayMin

Gets the minimum value in an array of numbers.

SalArraySetUpperBound

Sets the upper bound of an array.

SalArraySum

Computes the sum of an array's elements.

VisArrayAppend

Appends one array onto the end of another array.

VisArrayCopy

Copies one array into another.

VisArrayDeleteItem

Deletes an item from an array.

VisArrayFillDateTime

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

VisArrayFillNumber

Fills a number array with a specified value.

VisArrayFillString

Fills a string array with a specified string.

VisArrayFindDateTime

Locates a date/time value within an array.

VisArrayFindNumber

Locates a number within an array.

VisArrayFindString

Locates a string within an array.

VisArrayInsertItem

Inserts an item into an array.

VisArraySort

Sorts an array in either ascending or descending order.

Color and Font Functions These functions get and set window colors and fonts, as well as let you compose new colors. Function Name

1-18

Description

SalColorFromRGB

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

SalColorGet

Gets a window's color.



Function Name

Description

SalColorGetSys

Gets a system color.

SalColorSet

Sets a window's color.

SalColorToRGB

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

SalFontGet

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

SalFontGetNames

Gets the names of available screen fonts.

SalFontGetSizes

Gets the available sizes for a particularfont.

SalFontSet

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

VisFontEnum

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

VisFontFree

Frees a font loaded into memory with the VisFontLoad function.

VisFontGet

Gets specifications of a font.

VisFontLoad

Loads a font into memory.

VisTblSetRowColor

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

VisMenuInsertFont

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

VisMenuSetFont

Displays a menu item in the specified font. VisMenuSetFont operates on 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

Description

SalFormUnitsToPixels

Computes the number of pixels in the number of Centura form units.

SalGetDataType

Returns an object's data type.


1-19

Chapter

1


Function Name

Description

SalGetItemName

Gets the name of a form window or data field.

SalGetMaxDataLength

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

SalHStringToNumber

Converts a string to a number.

SalPixelsToFormUnits

Computes the number of Centura form units in the number of pixels.

SalSetMaxDataLength

Sets the maximum length of a data field.

Date Functions These functions manipulate date/time values. Function Name

1-20

Description

SalDateConstruct

Constructs a date.

SalDateCurrent

Gets the client's current date and time.

SalDateDay

Gets the day portion of a date.

SalDateHour

Gets the hour portion of a date.

SalDateMinute

Gets the minute portion of a date.

SalDateMonth

Gets the month portion of a date.

SalDateMonthBegin

Gets the date of the first day of a month.

SalDateQuarter

Gets the quarter of the year of a date.

SalDateQuarterBegin

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

SalDateSecond

Gets the seconds portion of the date.

SalDateToStr

Converts a date value to a string value.

SalDateWeekBegin

Gets the date of the previous Monday.

SalDateWeekday

Gets the day of the week as a number.

SalDateYea

Gets the year portion of a date.

SalDateYearBegin

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



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

Description

SalDDEAddAtom

Adds a string to the atom table.

SalDDEAlloc

Allocates a memory handle.

SalDDEDeleteAtom

Deletes an atom.

SalDDEExtract

Extracts DDE information from the wParam and lParam parameters of a DDE message.

SalDDEExtractCmd

Extracts the command string in a WM_DDE_Execute message.

SalDDEExtractDataText

Extracts data in a WM_DDE_Date or WM_DDE_Poke message.

SalDDEExtractOptions

Extracts options in a WM_DDE_Advise message.

SalDDEFindAtom

Finds the atom associated with a string.

SalDDEFree

Frees a memory handle.

SalDDEGetAtomName

Returns the string associated with an atom number.

SalDDEGetExecuteString

Returns the command string sent by a client.

SalDDEPost

Sends a DDE message.

SalDDERequest

Asks a server to send specified data.

SalDDESend

Sends a WM_DDE_Ack message in response to a WM_DDE_Initiate message.

SalDDESendAll

Broadcasts a WM_DDE_Initiate message.

SalDDESendExecute

Sends a WM_DDE_EXECUTE command to the specified server.

SalDDESendToClient

Sends data to a client.

SalDDESetCmd

Sets the command string in a WM_DDE_Execute message.


1-21

Chapter

1


Function Name

Description

SalDDESetDataText

Sets the data in a WM_DDE_Data or WM_DDE_Poke message.

SalDDESetOptions

Sets the options in a WM_DDE_Advise message.

SalDDEStartServer

Signals clients that the server is able to accept client connections and participate in a conversation.

SalDDEStartSession

Starts a hot link conversation between a client and a server.

SalDDEStopServer

Signals clients that the server wants to end DDE server operations.

SalDDEStopSession

Ends a hot link conversation between a client and a server.

Debugging Functions These functions help you debug your application. Function Name

1-22

Description

SalCompileAndEvaluate

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

SalContextBreak

Retrieves the context of the most recently executed Break statement.

SalContextCurrent

Retrieves the current execution context.

VisDebugAssert

Asserts that a condition is true.

VisDebugBeginTime

Begins timing an operation.

VisDebugEndTime

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

VisDebugGetFlags

Retrieves the current debug flags.

VisDebugSetFlags

Sets debug flags.

VisDebugSetLevel

Sets the current debug level.

VisDebugSetTime

Records the time since the last VisDebugSetTime or VisDebugBeginTime call.



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

Description

SalDlgChooseColor

Displays the Color dialog box.

SalDlgChooseFont

Displays the Font dialog box.

SalDlgOpenFile

Displays the Open File dialog box.

SalDlgSaveFile

Displays the Save File dialog box.

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

Description

SalEndDialog

Destroys a modal dialog box.

SalModalDialog

Creates a modal dialog box.

SalModalDialogFromStr

Creates a modal dialog box with the specified name.

DOS Management Functions These functions manage DOS features. Function Name

Description

VisDosBuildFullName

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

VisDosEnumDirInfo

Retrieves all subdirectories for a given directory into a Centura array.

VisDosEnumDirs

Retrieves all subdirectories within a given directory into a Centura array.

VisDosEnumDrives

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


1-23

Chapter

1


Function Name

1-24

Description

VisDosEnumFileInfo

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

VisDosEnumFiles

Retrieves all file names from a given directory into a Centura array.

VisDosEnumNetConnections

Retrieves all current network connections.

VisDosEnumPath

Returns each directory in the DOS PATH environment string.

VisDosEnumsShortDirInfo

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

VisDosEnumsShortDirs


VisDosEnumsShortFileInfo

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

VisDosEnumsShortFiles


VisDosExist

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

VisDosGetCurDir

Returns the current directory of a specified drive.

VisDosGetDriveSize

Returns total space and available space on a drive.

VisDosGetDriveType

Gets the type of drive specified.

VisDosGetEnvString

Returns an environment string based on a keyword.

VisDosGetFlags

Returns the state of DOS flags.

VisDosGetNetName

Retrieves the network name for the specified device.

VisDosGetVersion

Returns the MS-DOS version number.

VisDosGetVolumeLabel

Returns the volume label of a specified drive.



Function Name

Description

VisDosIsParent

Return indicator if directory contains subdirectories.

VisDosMakeAllDir

Creates all directories along the full path specified.

VisDosMakePath

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

VisDosNetConnect

Connects to a network device.

VisDosNetDisconnect

Cancels a network connection.

VisDosSetFlags

Sets verify, break, or error mode flags.

VisDosSetVolumeLabel

Sets the volume label on a disk drive.

VisDosSplitPath

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

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

Description

SalDragDropDisableDrop

Disables dropping while in drag mode.

SalDragDropEnableDrop

Enables dropping while in drag mode.

SalDragDropGetSource

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

SalDragDropGetTarget

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

SalDragDropStart

Initiates drag mode.

SalDragDropStop

Ends drag mode.

SalDropFilesAcceptFiles

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

SalDropFilesQueryFiles

Retrieves the names of the files dropped on a window.


1-25

Chapter

1


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

1-26

Description

SalEditCanCopyTo

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

SalEditCanCut

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

SalEditCanPaste

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

SalEditCanPasteFrom

Returns TRUE if an editable picture has the focus.

SalEditCanUndo

Returns TRUE if there is any editing to undo.

SalEditClear

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

SalEditCopy

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

SalEditCopyString

Copies a string to the Clipboard.

SalEditCopyTo

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



Function Name

Description

SalEditCut

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

SalEditPaste

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

SalEditPasteFrom

Copies a file into the editable picture with the focus.

SalEditPasteString

Pastes the contents of the Clipboard into the specified string.

SalEditUndo

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

VisWinClearAllFields

Clears all child fields of a parent window.

File Management Functions These functions manage file, directory, and drive operations. Function Name

Description

SalFileClose

Closes a file.

SalFileCopy

Copies the contents of one file to another.

SalFileCreateDirectory

Creates a directory.

SalFileGetC

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

SalFileGetChar

Gets the next character from an open file.

SalFileGetCurrentDirectory

Gets the path of the current working directory.

SalFileGetDateTime

Gets a file's modification date and time.

SalFileGetDrive

Gets the letter of the current disk drive.

SalFileGetStr

Gets the next line from an open file.

SalFileOpen

Opens a file.

SalFileOpenExt

Opens or re-opens a file.


1-27

Chapter

1


Function Name

1-28

Description

SalFilePutC

Writes a character to an open file.

SalFilePutChar


SalFilePutStr

Writes a string to an open file.

SalFileRead

Reads from an open file.

SalFileRemoveDirectory

Deletes a directory.

SalFileSeek

Sets the position in an open file.

SalFileSetCurrentDirectory

Changes a drive's current working directory.

SalFileSetDateTime

Sets a file's modification date and time.

SalFileSetDrive

Sets the default disk drive.

SalFileTell

Gets the current position in an open file.

SalFileWrite

Writes to an open file.

VisFileAppend

Appends one or more files to another.

VisFileClose

Closes a file opened with the VisFileOpen call.

VisFileCopy

Copies one or more files.

VisFileCreateTemp

Creates a temporary file.

VisFileDelete

Deletes one or more files.

VisFileExpand

Copies a source file to a destination file.

VisFileFind

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

VisFileGetAttribute

Gets the attribute bit values for the specified file.

VisFileGetSize

Gets the size of the specified file in bytes.

VisFileGetType

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

VisFileOpen

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

VisFileRead

Reads a block of data from a file.



Function Name

Description

VisFileReadString

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

VisFileRename

Renames one or more files.

VisFileSeek

Seeks to a specified offset within a file.

VisFileSetAttribute

Sets the attribute bits for one or more files.

VisFileSetDateTime

Sets the date and time for one or more files.

VisFileTell

Returns the current file offset.

VisFileWrite

Writes a block of data to a file.

VisFileWriteString

Writes a string to a file.

Format and Validation Functions These functions format and validate the value of an object. Function Name

Description

SalFmtFieldToStr

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

SalFmtFormatDateTime

Formats a date/time value.

SalFmtFormatNumber

Formats a number value.

SalFmtGetFormat

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

SalFmtGetInputMask

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

SalFmtGetPicture

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

SalFmtIsValidField

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

SalFmtIsValidInputMask

Validates an input mask.

SalFmtIsValidPicture

Validates a number or date/time picture format.

SalFmtKeepMask

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


1-29

Chapter

1


Function Name

1-30

Description

SalFmtSetFormat

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

SalFmtSetInputMask

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

SalFmtSetPicture

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

SalFmtStrToField

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

SalFmtUnmaskInput

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

SalFmtValidateField

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

SalIsNull

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

SalIsValidDateTime

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

SalIsValidDecimal

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

SalIsValidInteger

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

SalIsValidNumber

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

SalStrIsValidCurrency

Verifies whether the entire string is a valid currency value.

SalStrIsValidDateTime

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

SalStrIsValidNumber

Verifies whether the entire string is a valid number value.

SalValidateSet

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



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

Description

SalListAdd

Adds an entry to a list box or combo box.

SalListClear

Clears a list box or combo box.

SalListDelete

Deletes an entry from a list box or combo box.

SalListFiles

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

SalListGetMultiSelect

Returns the index numbers of selected list box entries.

SalListInsert

Inserts an entry into a list box or combo box.

SalListPopulate

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

SalListQueryCount

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

SalListQueryFile

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

SalListQueryMultiCount

Returns the number of currently selected list box entries.

SalListQuerySelection

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

SalListQueryState

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

SalListQueryText and SalListQueryTextX

Fetches a list box or combo box entry.

SalListQueryTextLength

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

SalListRedraw

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

SalListSelectString

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


1-31

Chapter

1


Function Name

1-32

Description

SalListSetMultiSelect

Selects or deselects the specified list box entry.

SalListSetSelect

Selects the specified list box or combo box index entry.

SalListSetTabs

Sets tab stops in a list box.

VisListAddValue

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

VisListArrayPopulate

Populates a list box from a string array.

VisListArrayPopulateValue

Populates a list box from a string array and an array of values. Each item in the string is inserted as an item in the list box. The number of

VisListClearSelection

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

VisListDeleteSelected

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

VisListFindString

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

VisListFindValue

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

VisListGetDropdownState

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

VisListGetFocusIndex

Gets the index of the item which has the focus rectangle or the last item to receive the focus frame in a multiple-selection list box.

VisListGetVisibleRange

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

VisListInsertValue

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

VisListIsMultiSelect

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

VisListScroll

Scrolls an item into view.



Function Name

Description

VisListSetDropdownState

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

VisListSetFocusIndex

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

VisListSetScrollWidth

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

Manipulating Background Text Functions These functions manipulate the background text. Function Name

Description

SalAppDisable

Disables input to open windows.

SalAppEnable

Enables input to open windows.

SalAppFind

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

SalBringWindowToTop

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

SalCenterWindow

Centers a window.

SalCreateWindow

Creates a window.

SalDestroyWindow

Destroys a window.

SalDisableWindow

Disables mouse and keyboard input to a window.

SalDisableWindowAndLabel

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

SalEnableWindow

Enables keyboard and mouse input to a window.

SalEnableWindowAndLabel

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

SalFormGetParmNum

Gets information about a form window.

SalGetDefButton

Gets the handle of the default push button.


1-33

Chapter

1


Function Name

1-34

Description

SalGetFirstChild

Finds the first child of a window.

SalGetFocus

Gets the object with the focus.

SalGetNextChild

Finds the next child of a window.

SalGetType

Returns the type of the specified object.

SalGetWindowLabelText

Retrieves a window's background text.

SalGetWindowLoc

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

SalGetWindowSize

Gets the current window's size.

SalGetWindowState

Gets the current state of a window.

SalGetWindowText

Retrieves a window's text.

SalHideWindow

Hides a window.

SalHideWindowAndLabel

Hides a window and its associated label.

SalInvalidateWindow

Causes a window to be repainted.

SalIsButtonChecked

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

SalIsWindowEnabled

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

SalIsWindowVisible

Specifies whether a window is visible.

SalMoveWindow

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

SalParentWindow

Returns the window handle of a parent or owner window.

SalQueryFieldEdit

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

SalSetDefButton

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

SalSetFieldEdit

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



Function Name

Description

SalSetFocus

Sets the focus to a window.

SalSetWindowLabelText

Sets a window's background text.

SalSetWindowLoc

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

SalSetWindowSize

Resizes a window.

SalSetWindowText

Sets a window's text.

SalShowWindow

Makes a window visible.

SalShowWindowAndLabel


SalStatusGetText

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

SalStatusSetText

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

SalStatusSetVisible

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

SalTBarSetVisible

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

SalUpdateWindow

Updates the client area of a window.

SalWindowGetProperty

Gets the value of a named property for an instance of a QuickObject. The property must have been created at designtime with the QuickObject Editor.

SalWindowHandleToNumber

Converts a window handle to a number.

SalWindowIsDerivedFromClass


VisMenuSetText

Changes the text of a menu item.

VisWinGetText

Obtains the text of a window.

These functions manipulate the background text label of a child window: •


•


•


Two other functions you can use with background text are explained below. nLength = SalGetWindowLabelText( hWnd, sText, nMaxLength)


1-35

Chapter

1


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

Description

SalMDIArrangeIcons

Arranges minimized child window icons in an MDI window.

SalMDICascade

Cascades child windows of an MDI window.

SalMDITile

Tiles child windows of an MDI window.

Message Functions Use these functions to post and send messages to objects. Function Name

1-36

Description

SalPostMsg

Posts a message to a window.

SalSendClassMessage

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

SalSendClassMessageNamed

Invokes the message actions in the closest ancestor class that implements the given message. Use with a class that is the result of multiple inheritance.

SendMsg

Sends a message to a window.

SalSendMsgToChildren

Sends a message to all children of a form window.

SalSendValidateMsg

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



Function Name

Description

VisMessageBox

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

VisMessageFreeButton

Frees memory allocated with VisMessageLoadButton.

VisMessageLoadButton

Establishes a button to be used in userdefined message boxes.

VisMessageSetBkgdColor

Sets the background color for a VisMessageBox dialog box.

VisSendMsgString

Sends a message and passes a string in lParam.

Miscellaneous Functions These functions perform miscellaneous system tasks from within a Centura application. Function Name

Description

SalAbort

Halts the execution of current actions.

SalClearField

Clears the value from a field.

SalCursorSet

Sets a window's cursor.

SalCursorSetFile

Sets an application-defined cursor for the specified window.

SalCursorSetString

Sets a window's cursor from a string variable.

SalDrawMenuBar

Redraws a menu bar.

SalGetProfileInt

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

SalGetProfileString

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

SalGetVersion

Returns the Centura version.

SalLoadApp

Loads and starts an application.

SalLoadAppAndWait

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


1-37

Chapter

1


Function Name

1-38

Description

SalMapEnterToTab

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

SalMessageBeep

Generates a beep.

SalMessageBox

Displays a message box.

SalQuit

Exits the Centura application.

SalSetProfileString

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

SalTimerKill

Destroys a system timer.

SalTimerSet

Creates a system timer.

SalTrackPopupMenu

Creates a pop-up menu at runtime.

SalWaitCursor

Displays or removes the hourglass cursor.

SalWinHelp

Invokes the Windows help system.

SalYieldEnable

Enables or disables application yielding.

SalYieldQueryState

Determines whether application yielding is enabled or disabled.

SalYieldStartMessages

Allows yielding and the sending of messages to a window.

SalYieldStopMessages

Stops yielding and the sending of messages to a window.

VisErrorRecovery

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

VisGetCopyright

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

VisGetKeyState

Retrieves the state of a specified key.

VisGetSystemMetrics

Retrieves widths and heights of various elements displayed by Windows.

VisGetVersion

Gets the Vis Library version number.

VisGetWinFlags

Retrieves the current Windows system and memory configuration.



Function Name

Description

VisGetWinVersion

Returns the Windows version number.

VisListLoadOutline

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

VisListLoadOutlineFile

Loads an outline from a tab indented ASCII file.

VisListSaveOutline

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

VisMenuGetPopupHandle

Retrieves the menu handle of a pop-up menu.

VisMenuGetSystemHandle

Retrieves the system menu handle of a window.

VisMenuGetText

Retrieves the text of a menu item.

VisMenuInsert

Inserts a menu item into a menu.

VisMenuIsChecked

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

VisMenuIsEnabled

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

VisMenuUncheck

Unchecks a menu item.

VisNumberBitClear

Clears bit values from a number.

VisNumberBitSet

Sets bit values in a number.

VisNumberChoose

Evaluates bExpression.

VisStrChoose

Evaluates bExpression.

VisStrFind

Locates a string within a string table.

VisStrFreeTable

Frees all memory associated with a string table.

VisStrLeftTrim

Trims leading blanks from a string.

VisStrLoadTable

Loads a string table from disk into memory.

VisWaitCursor

Turns hourglass cursor on or off.


1-39

Chapter

1


Function Name

Description

VisWinClearAllEditFlags

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

VisWinEnumProps

Enumerates the property list for a specified window.

VisWinFreeAccelerator

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

VisWinGetFlags

Retrieves window flags for a window.

VisWinGetProp

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

VisWinGetStyle

Retrieves the Windows style bits for a specified window.

VisWinIsRequiredFieldNull

Tests to determine if any required field is null.

VisWinSetMeter

Displays a completion meter within a Centura data field.

Number Functions These functions perform mathematical calculations. Function Name

1-40

Description

SalNumberAbs

Computes a number's absolute value.

SalNumberArcCos

Computes a value's arccosine.

SalNumberArcSin

Computes a value's arcsine.

SalNumberArcTan

Computes a value's arctangent.

SalNumberArcTan2

Computes the arctangent of two values.

SalNumberCos

Computes an angle's cosine.

SalNumberCosH

Computes an angle's hyperbolic cosine.

SalNumberExponent

Computes a value's exponential function.

SalNumberHigh

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



Function Name

Description

SalNumberHypot

Computes the length of the hypotenuse of a right triangle.

SalNumberLog

Computes a number's natural logarithm.

SalNumberLogBase10

Computes a number's base-10 logarithm.

SalNumberLow

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

SalNumberMax

Returns the greater of two values.

SalNumberMin

Returns the lesser of two values.

SalNumberMod

Returns a number's modulo.

SalNumberPi

Multiplies a number by Pi.

SalNumberPower

Computes a number raised to the power of another number.

SalNumberRandInit

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

SalNumberRandom

Generates a pseudorandom integer in the range 0 to 32767.

SalNumberRound

Returns a rounded number.

SalNumberSin

Computes an angle's sine.

SalNumberSinH

Computes an angle's hyperbolic sine.

SalNumberSqrt

Computes a number's square root.

SalNumberTan

Computes an angle's tangent.

SalNumberTanH

Computes an angle's hyperbolic tangent.

SalNumberToChar

Converts an ASCII numeric value to a character.

SalNumberToHString

Converts a number to a string handle.

SalNumberToStr and SalNumberToStrX

Convert a number to a string.

SalNumberToWindowHandle

Converts a number to a window handle.

SalNumberTruncate

Truncates a number.


1-41

Chapter

1


Function Name

Description

VisNumberHighByte

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

VisNumberLowByte

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

VisNumberMakeLong

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

See Also: Array Functions

Picture Functions These functions manipulate the contents of a picture. Function Name

1-42

Description

SalPicClear

Clears the contents of a picture.

SalPicGetDescription

Retrieves a description of a picture's contents.

SalPicGetString

Copies the contents of a picture to a string.

SalPicSet

Inserts a resource into a picture.

SalPicSetFile

Sets the contents of a picture from a file.

SalPicSetFit

Sets the fit for a picture.

SalPicSetString

Sets the contents of a picture from a string.

VisMenuInsertPicture

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

VisMenuSetPicture

Displays a picture in a menu item.

VisPicFree

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

VisPicLoad

Loads a picture into memory.

VisTblSetRowPicture

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



Print Functions These functions let you control printing. Function Name

Description

SalPrtExtractRect

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

SalPrtGetDefault

Gets the default printer.

SalPrtGetParmNum

Gets the value of a print parameter.

SalPrtPrintForm

Prints a window.

SalPrtSetDefault

Sets the default printer.

SalPrtSetParmDefaults

Resets print parameters to their defaults.

SalPrtSetParmNum

Sets the value of a print parameter.

SalPrtSetup

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

Report 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

Description

SalReportClose

Closes a ReportWindows window.

SalReportCmd

Sends a command to a report window.

SalReportCreate

Creates a report.

SalReportDlgOptions

Sets the options for the report printing dialog box.

SalReportGetDateTimeVar

Gets the value of a date/time report variable.

SalReportGetNumberVar

Gets the value of a numeric report variable.

SalReportGetObjectVar

Gets the value of an object report variable.

SalReportGetStringVar

Gets the value of a string report variable.

SalReportPrint

Prints a report.

SalReportPrintToFile

Prints a report to a file.


1-43

Chapter

1


Function Name

Description

SalReportReset

Updates the report preview with new data.

SalReportSetDateTimeVar

Sets the value of a date/time report variable.

SalReportSetNumberVar


SalReportSetObjectVar

Sets the value of an object report variable.

SalReportSetStringVar

Sets the value of a string report variable.

SalReportTableCreate

Creates a report from the specified table window.

SalReportTablePrint

Prints a report created from a table window.

SalReportTableView

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

SalReportView

Displays a report in preview mode.

Scroll Bar Functions These functions manage horizontal and vertical scroll bars. Function Name

Description

SalScrollGetPos

Gets the scroll bar position.

SalScrollGetRange

Gets values set by SalScrollSetRange.

SalScrollSetPos

Sets the scroll bar position.

SalScrollSetRange

Sets the range of a scroll bar.

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

1-44

Description

SqlClearImmediate

Disconnects the Sql Handle used by SqlImmediate.

SqlClose

Closes a named cursor.

SqlCommit

Commits the current SQL transaction.



Function Name

Description

SqlConnect

Connects a Sql Handle to a database.

SqlContextClear

Clears the context set by SqlContextSet.

SqlContextSet

Sets the context for later compilation and fetching.

SqlContextSetToForm

Sets context to form name.

SqlDirectoryByName

Gets the names of databases on a given server.

SqlDisconnect

Disconnects a Sql Handle from a database.

SqlDropStoredCmd

Deletes a stored command.

SqlError

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

SqlErrorText

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

SqlExecute

Executes a SQL statement.

SqlExecutionPlan

Gets the execution plan for a compiled SQL statement.

SqlExists

Checks for the existence of a particular row.

SqlExtractArgs

Extracts error information.

SqlFetchNext

Fetches the next row in a result set.

SqlFetchPrevious

Fetches the previous row in a result set.

SqlFetchRow

Fetches a specific row from a result set.

SqlGetError

Turns off backend error mapping and reports real backend errors.

SqlGetErrorPosition

Gets the offset of an error within a SQL statement.

SqlGetErrorText and SqlGetErrorTextX

Gets the message text for a SQL error number.

SqlGetModifiedRows

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

SqlGetParameter

Returns a database parameter.


1-45

Chapter

1


Function Name

1-46

Description

SqlGetParameterAll

Returns a database parameter.

SqlGetResultSetCount

Returns the number of rows in a result set.

SqlGetRollbackFlag

Returns the database rollback flag.

SqlImmediate

Prepares and executes a SQL statement.

SqlImmediateContext

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

SqlOpen

Names a cursor and executes a SQL statement.

SqlPLSQLCommand

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

SqlPrepare

Prepares a Sql statement for execution.

SqlPrepareAndExecute

Prepares and executes an Sql statement.

SqlRetrieve

Retrieves a stored command.

SqlSetInMessage

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

SqlSetIsolationLevel

Sets the isolation level.

SqlSetLockTimeout

Sets the timeout period on waiting for a lock.

SqlSetLongBindDatatype

Sets type of column to bind to.

SqlSetOutMessage

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

SqlSetParameter

Sets a database parameter.

SqlSetParameterAll

Sets a database parameter.

SqlSetResultSet

Turns a result set mode on and off.

SqlStore

Compiles and stores a command.

SqlVarSetup

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



String Conversion Functions These functions manipulate string data by changing the form of a string or looking for substrings. Function Name

Description

SalStrCompress

Compresses a string.

SalStrFirstC

Returns the first character in a string.

SalStrGetBufferLength

Returns the length of a string buffer.

SalStrLeft and SalStrLeftX

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

SalStrLength

Returns the length of a string.

SalStrLop

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

SalStrLowerand SalStrLowerX

Converts a string to lowercase.

SalStrMid and SalStrMidX

Returns a substring.

SalStrProper and SalStrProperX

Converts a string to a proper name.

SalStrRepeat and SalStrRepeatX

Concatenates a string with itself a specified number of times.

SalStrReplace and SalStrReplaceX

Replaces characters in one string with characters from another string.

SalStrRight and SalStrRightX

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

SalStrScan

Finds a string within a string.

SalStrSetBufferLength

Sets the length of the specified string buffer.

SalStrToDate

Converts a string to a date/time value.

SalStrTokenize

Parses a string into substrings.

SalStrToNumber


SalStrTrim and SalStrTrimX

Removes white space from a string.

SalStrUncompress

Decompresses a string.

SalStrUpper and SalStrUpperX

Converts a string to uppercase.


1-47

Chapter

1


Function Name

Description

VisStrExpand

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

VisStrPad

Pads a string with trailing blanks and returns the result.

VisStrProper

Converts a string to mixed case.

VisStrRightTrim

Trims trailing blanks from a string.

VisStrScanReverse

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

VisStrSubstitute

Substitutes all occurrences of one string with another string.

VisStrTrim

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

Table Window Functions These functions manage table windows. Function Name

1-48

Description

SalTblAnyRows

Determines whether any rows have certain flags set.

SalTblClearSelection

Clears the selection of rows in a table window.

SalTblColumnAverage

Computes the average of a column's values.

SalTblColumnSum

Computes the sum of a column's values.

SalTblCopyRows

Copies the contents of specified rows to the Clipboard.

SalTblCreateColumn

Creates columns at runtime.

SalTblDefineRowHeader

Defines the appearance and behavior of a row header.

SalTblDefineSplitWindow

Defines how a table window is split horizontally.

SalTblDeleteRow

Deletes a row.

SalTblDeleteSelected

Applies a DELETE statement to all selected rows.



Function Name

Description

SalTblDestroyColumns

Destroys automatic columns created at runtime.

SalTblDoDeletes

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

SalTblDoInserts

Applies an INSERT statement to all new rows.

SalTblDoUpdates

Applies an UPDATE statement to all edited rows.

SalTblFetchRow

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

SalTblFindNextRow

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

SalTblFindPrevRow

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

SalTblGetColumnText

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

SalTblGetColumnTitle

Returns a column's title.

SalTblGetColumnWindow

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

SalTblInsertRow

Inserts a new row.

SalTblKillEdit

Sets the ROW_Edited flag on a new or changed row.

SalTblKillFocus

Turns off the focus frame.

SalTblPasteRows

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

SalTblPopulate

Populates a table window with a result set.

SalTblQueryColumnFlags

Tests the state of a column's flags.

SalTblQueryColumnID

Gets a column's identifier.

SalTblQueryColumnPos

Gets a column's position in the table window.

SalTblQueryColumnWidth

Retrieves a column's width.


1-49

Chapter

1


Function Name

1-50

Description

SalTblQueryContext

Gets the current context row.

SalTblQueryFocus

Identifies the cell with the focus.

SalTblQueryLockedColumns

Returns the number of locked columns.

SalTblQueryRowFlags

Queries a row's flags.

SalTblQueryRowHeader

Gets the definition of a row header.

SalTblQueryScroll

Gets the current scroll position and range.

SalTblQuerySplitWindow

Specifies how the table window is split horizontally.

SalTblQueryTableFlags

Tests the state of a table window's flags.

SalTblQueryVisibleRange

Gets the current visible range.

SalTblReset

Clears a table window.

SalTblScroll

Scrolls to a specified cell.

SalTblSetCellTextColor

Sets a cell's text color.

SalTblSetColumnFlags

Sets or clears a column's flags.

SalTblSetColumnPos

Moves a column.

SalTblSetColumnText

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

SalTblSetColumnTitle

Sets a column's title.

SalTblSetColumnWidth

Sets a column's width.

SalTblSetContext

Sets the context row.

SalTblSetFlagsAnyRows

Sets or clears row flags.

SalTblSetFocusCell

Sets the focus to a specified cell.

SalTblSetFocusRow

Sets the focus frame row.

SalTblSetLockedColumns

Defines the number of columns to lock.

SalTblSetRange

Defines the minimum and maximum rows.

SalTblSetRow

Sets focus to a row.

SalTblSetRowFlags




Function Name

Description

SalTblSetTableFlags

Sets or clears table window flags.

SalTblSortRows

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

VisTblAllRows

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

VisTblAutoSizeColumn

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

VisTblClearColumnSelection

Clears selection for all columns of a table window.

VisTblFindDateTime

Locates a date/time value within a column.

VisTblFindNumber

Locates a number value within a column.

VisTblFindString

Locates a string value within a column.

VisTblGetCell

Retrieves the contents of a cell in a table window.

VisTblGetColumnTitle

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

Window Management Functions These functions let you manipulate an application's windows. Function Name

Description

SalAppDisable

Disables input to open windows.

SalAppEnable

Enables input to open windows.

SalAppFind

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

SalBringWindowToTop

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

SalCenterWindow

Centers a window.


1-51

Chapter

1


Function Name

1-52

Description

SalCreateWindow

Creates a window.

SalDestroyWindow

Destroys a window.

SalDisableWindow

Disables mouse and keyboard input to a window.


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

SalEnableWindow



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

SalFormGetParmNum

Gets information about a form window.

SalGetDefButton

Gets the handle of the default push button.

SalGetFirstChild

Finds the first child of a window.

SalGetFocus

Gets the object with the focus.

SalGetNextChild

Finds the next child of a window.

SalGetType

Returns the type of the specified object.

SalGetWindowLabelText

Retrieves a window's background text.

SalGetWindowLoc

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

SalGetWindowSize

Gets the current window's size.

SalGetWindowState

Gets the current state of a window.

SalGetWindowText

Retrieves a window's text.

SalHideWindow

Hides a window.



SalInvalidateWindow


SalIsButtonChecked


SalIsWindowEnabled

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



Function Name

Description

SalIsWindowVisible

Specifies whether a window is visible.

SalMoveWindow


SalParentWindow

Returns the window handle of a parent or owner window.

SalQueryFieldEdit

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

SalSetDefButton

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

SalSetFieldEdit

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

SalSetFocus

Sets the focus to a window.

SalSetWindowLabelText

Sets a window's background text.

SalSetWindowLoc

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

SalSetWindowSize

Resizes a window.

SalSetWindowText

Sets a window's text.

SalShowWindow




SalStatusGetText

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

SalStatusSetText

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

SalStatusSetVisible

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

SalTBarSetVisible

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

SalUpdateWindow

Updates the client area of a window.


1-53

Chapter

1


Function Name

1-54

Description

SalWindowGetProperty




SalWindowIsDerivedFromClass


VisWinEnumProps

Enumerates the property list for a specified window.

VisWinGetProp

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

VisWinIsChild

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

VisWinIsMaximized

Tests whether a specified window is maximized.

VisWinIsMinimized

Tests whether a specified window is minimized.

VisWinIsRestored

Tests whether a specified window is neither maximized or minimized.

VisWinIsWindow

Tests whether a specified window is valid.

VisWinLoadAccelerator

Sets an accelerator keystroke for a window.

VisWinMove

Moves and resizes a window, based on pixel coordinates.

VisWinRemoveProp

Removes a property list entry for a specified window.

VisWinSetFlags

Sets flags for a specified window.

VisWinSetProp

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

VisWinSetStyle

Adds a window style to a window.

VisWinSetTabOrder

Changes the tab order of a control.

VisWinShow

Sets a window's visibility state.



Chapter 2

Centura Builder Functions This 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. Function descriptions include: •

Syntax

•

Description

•

Parameters

•

Return value

•

See Also

•

Example


2-1

Chapter

2

Centura Builder Functions

SalAbort Syntax

bOk = SalAbort ( nExitCode )

Description

Halts processing of the current menu action, message action, or application action. Use SalAbort when you want to terminate the current calling sequence without returning a status. For example, if your application is several layers into internal function calls and an error occurs, SalAbort terminates the current calling sequence of functions and leaves the application in the state it was prior to the first function call of that sequence.

Parameters

nExitCode

Return Value

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

See Also

SalQuit

Example

If NOT SqlConnect ( hSql )

Receive Number. The status of the exit performed by SalAbort. Centura ignores this parameter as input.

Call SalAbort ( -1 )

SalAppDisable Syntax

bOk = SalAppDisable ( )

Description

Disables input to all open applications. Use SalAppDisable and SalAppEnable when there are multiple applications running simultaneously and you want to control which application receives user input.

Parameters

No parameters.

Return Value


See Also

SalAppEnable

Example

Call SalAppDisable ( ) Call SalLoadAppAndWait ( 'Excel', '' ) Call SalAppEnable ( )

2-2


SalAppEnable Syntax

bOk = SalAppEnable ( )

Description

Enables input to all open applications that were disabled by SalAppDisable. Use SalAppDisable and SalAppEnable when there are multiple applications running simultaneously and you want to control which application receives user input.

Parameters

No parameters.

Return Value

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

See Also

SalAppDisable

Example

Call SalAppDisable ( ) Call SalLoadAppAndWait ( 'Excel', '' ) Call SalAppEnable ( )

SalAppFind Syntax

hWnd = SalAppFind ( strAppName, bActivate )

Description

Finds a visible top-level window for the application that you specify and returns its window handle. SalAppFind first looks for running instances of 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 application’s *.DEF file.

bActivate

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

2-3

Chapter

2


Return Value

hWnd is the handle of the window.

Example

On SAM_AppStartup If SalAppFind( 'INVOICE', TRUE ) != hWndNULL Call SalQuit( )

SalArrayAvg Syntax

nAvg = SalArrayAvg ( nArrayNum )

Description

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

Parameters

nArrayNum

Return Value

nAvg is the average value in an array of numbers.

See Also

SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum

Example

On SAM_Create

Numeric Array. The name of an array of numbers.

Set dfAvg = SalArrayAvg( nArrayNum )

SalArrayDimCount Syntax

bOk = SalArrayDimCount ( aArray, nDim )

Description

Returns the number of dimensions in an array.

Parameters

aArray

Array. The name of the array to query.

nDim

Receive Number. Number of dimensions in the array.

Return Value


See Also

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

bOk = SalArrayGetLowerBound ( aArray, nDim, nBound )

Description

Returns the lower bound of an array.

Parameters

aArray


nDim

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

nBound

Receive Number. Lower bound value.

Return Value


See Also

SalArrayAvg SalArrayDimCount SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum

Example

On SAM_Click Set bOk = SalArrayGetLowerBound (aArray, nBound)

SalArrayGetUpperBound Syntax

bOk = SalArrayGetUpperBound ( aArray, nDim, nBound )

Description

Returns the upper bound of an array.

Parameters

aArray


nDim


nBound

Receive Number. Upper bound value.

Return Value



2-5

Chapter

2


See Also

SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum

Example

On SAM_Click Set bOk = SalArrayGetUpperBound (aArray, nBound)

SalArrayIsEmpty Syntax

bData = SalArrayIsEmpty ( aArray )

Description

Determines if a dynamic array contains data.

Parameters

aArray

Return Value

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

See Also

SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayMax SalArrayMin SalArraySetUpperBound SalArraySum

Example

On SAM_Click


If Not SalArrayIsEmpty (aArray) Call ...

2-6


SalArrayMax Syntax

nMax = SalArrayMax ( nArrayNum )

Description

Returns the maximum value in an array of numbers.

Parameters

nArrayNum

Return Value

nMax is the maximum value in an array of numbers.

See Also

SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMin SalArraySetUpperBound SalArraySum

Example

On SAM_Create


Set dfMax = SalArrayMax( nArrayNum )

SalArrayMin Syntax

nMin = SalArrayMin ( nArrayNum )

Description

Returns the minimum value in an array of numbers. nArrayNum


Return Value

nMin is the minimum value in an array of numbers.

See Also

SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArraySetUpperBound SalArraySum

Example

On SAM_Create Set dfMin = SalArrayMin( nArrayNum )


2-7

Chapter

2


SalArraySetUpperBound Syntax

bOk = SalArraySetUpperBound ( aArray, nDim, nBound )

Description

Sets the upper bound of an array. When you call this function for a dimension other than the first, 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

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

SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySum

Example

On SAM_Click Call SalArraySetUpperBound (aArray, 1, 5)

SalArraySum Syntax

nSum = SalArraySum ( nArrayNum )

Description

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

Parameters

nArrayNum

Return Value

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

See Also

SalArrayAvg SalArrayDimCount SalArrayGetLowerBound SalArrayGetUpperBound

2-8



SalArrayIsEmpty SalArrayMax SalArrayMin SalArraySetUpperBound Example

On SAM_Create Set dfSum = SalArraySum( nArrayNum )

SalBringWindowToTop Syntax

bOk = SalBringWindowToTop ( hWndToExpose )

Description

Brings a window to the top of all overlapping windows.

Parameters

hWndToExpose

Return Value


See Also

SalHideWindow SalShowWindow

Example

If ( hWndCustomer )

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

Call SalBringWindowToTop ( hWndCustomer )

SalCenterWindow Syntax

bOk = SalCenterWindow ( hWndCenter )

Description

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.

Parameters

hWndCenter

Return Value


See Also

SalMoveWindow

Example

Call SalCenterWindow ( pbExample )

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


2-9

Chapter

2


SalClearField Syntax

bOk = SalClearField ( hWndFldToClear )

Description

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

Parameters

hWndFldToClear

Return Value


See Also

SalIsNull

Example

If ( dfAge < 0 )

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

Call SalClearField ( dfAge )

SalColorFromRGB Syntax

nColor = SalColorFromRGB ( nRed, nGreen, nBlue )

Description

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

Parameters

nRed

Number. A number from 0 to 255.

nGreen


nBlue


Return Value

nColor is the color created.

See Also

SalColorGet SalColorGetSysColor SalColorSet SalColorToRGB

Example

Set nRed = 128 Set nGreen = 128 Set nBlue = 128 Set nColor = SalColorFromRGB ( nRed, nGreen, nBlue ) If NOT SalColorSet ( hWndItem, COLOR_IndexWindow, nColor ) ...

2-10


SalColorGet Syntax

nColor = SalColorGet ( hWndColored, nColorIndex )

Description

Gets a window's color.

Parameters

hWndColored

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

nColorIndex

Number. The color of a part of the window, represented by one of these constants: COLOR_IndexCellText COLOR_IndexTransparent COLOR_IndexWindow COLOR_IndexWindowText

Return Value

nColor is the color returned. It can be user-defined or one of the predefined window colors (excluding COLOR_Default and the three COLOR_Sys* constants). If you specify COLOR_IndexTransparent in the second parameter and the transparent color is not set, SalColorGet returns COLOR_None.

See Also

Example

SalColorFromRGB SalColorGetSysColor SalColorSet SalColorToRGB Set nColor = SalColorGet ( hWndItem, COLOR_IndexWindow ) If nColor = COLOR_Default Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Magenta )

SalColorGetSysColor Syntax

nColor = SalColorGetSysColor ( nColorIndex )

Description

Gets a system color.

Parameters

nColorIndex

Number. The color of a part of the window, represented by one of these constants: COLOR_SysWindow COLOR_SysWindowFrame COLOR_SysWindowText


2-11

Chapter

2


Return Value

nColor is the color returned. It can be one of the predefined windows colors (excluding COLOR_Default, COLOR_None, and the three COLOR_Sys* constants).

See Also

SalColorFromRGB SalColorGet SalColorSet SalColorToRGB

Example

Set nSysColorBckgrnd = SalColorGetSysColor ( COLOR_SysWindow )

SalColorSet Syntax

bOk = SalColorSet ( hWndToSet, nColorIndex, nColor )

Description

Sets a window's color.

Parameters

hWndToSet

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

nColorIndex

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

nColor

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.

Return Value


See Also

SalColorFromRGB SalColorGet SalColorGetSysColor SalColorToRGB

Example

Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Red )

2-12


SalColorToRGB Syntax

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

Description

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

Parameters

nColor

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

nRed

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

nGreen

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

nBlue

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

Return Value


See Also

SalColorFromRGB SalColorGet SalColorGetSysColor SalColorSet

Example

If NOT SalColorToRGB ( nColor, nRed, nGreen, nBlue ) ... Error ...

SalCompileAndEvaluate Syntax

nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos, nReturn, strReturn, dtReturn, hWndReturn, bInhibitErrors, strContext )

Description

Evaluates an expression and returns the expression's value in the receive parameter appropriate to its data type. SalCompileAndEvaluate lets you access the value of a variable whose name you do not specify until runtime.

Parameters

strExpression

String. The expression to evaluate.

nError

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

nErrorPos

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

nReturn

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

strReturn

Receive String. This parameter is set if strExpression evaluates to a string. Centura Builder Function Reference

2-13

Chapter

2

Return Value


dtReturn

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

hWndReturn

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

bInhibitErrors

Boolean. If TRUE, 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.

strContext

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

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

SalContextBreak SalContextCurrent

Example

Set nType = SalCompileAndEvaluate ( strExpression, nError, nErrorPos,nReturn, strReturn, dtReturn, hWndReturn, FALSE, strContext ) If nType = EVAL_Number Call SalNumberToStr ( nReturn, 0, strString ) ...

SalContextBreak Syntax

strContext = SalContextBreak ( )

Description

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

Parameters

No parameters.

Return Value

strContext serves as the last parameter of the SalCompileAndEvaluate function.

See Also

SalCompileAndEvaluate SalContextCurrent

2-14


Example

Set strContext = SalContextBreak ( )

SalContextCurrent Syntax

strContext = SalContextCurrent ( )

Description

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

Parameters

No parameters.

Return Value

strContext serves as the last parameter of the SalCompileAndEvaluate function.

See Also

SalCompileAndEvaluate SalContextBreak

Example

Set strContext = SalContextCurrent ( )

SalCreateWindow Syntax

hWndCreated = SalCreateWindow ( tWndToCreate, hWndOwner, Parm1, Parm2, ... )

Description

Creates modeless dialog boxes, MDI windows, form windows, and top-level table windows at runtime. This function accepts a string or a template as the first parameter. When you pass a string, you cannot also pass window parameters. If you specify an owner (hWndOwner), the new window always displays on top of its owner, closes when its owner closes, and hides when its owner is minimized. SalCreateWindow can pass data to and from the window being created by accepting a variable number of parameters. The data types of these parameters must match the parameter data types of the window being created. You define parameters for the window in the Window Parameters section of the application outline. For example, this code passes the variable, nGlobal and the data field, df1 to the form window, frmMain. Before SAM_Create is sent to frmMain, its first window parameter is initialized with the value of nGlobal and its second window parameter is initialized with the value of df1. Call SalCreateWindow ( frmMain, hWndNULL, nGlobal, df1 )

You can use window parameters to return information from the window being created by using a receive type. However, you can initialize receive window parameters only with variables. This means that you cannot pass a data field or any other window object to a window parameter that was defined as a receive type. Parameters

tWndToCreate

Template or String. The name of the window to create. Centura Builder Function Reference

2-15

Chapter

2


Note: If you specify a string value, you cannot pass window parameter arguments (Parm1, Parm2, ...). hWndOwner

Window Handle. The handle (or name) of the owner window. Specify hWndNULL if there is no owner window. Note that if you create a toplevel form inside of a MDI window, then that MDI window will always be the owner of this form.

Parm1

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

Parm2

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

Return Value

hWndCreated is the handle of the new window.

See Also

SalModalDialog SalDestroyWindow

Example

On SAM_Click If NOT SalCreateWindow (frmCustomer, hWndNULL) ...Error...

SalCreateWindowExWithParms Syntax

hWndCreated = SalCreateWindowExWithParms( tWndToCreate, hWndOwner, nLeft, nTop, nWidth, nHeight, nFlags ... )

Description

Creates a form, dialog box or table window as a child of another form or dialog box at runtime. 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.

nLeft, nTop

Position of the window in form units.

nWidth, nHeight

Size of the window in form units.

nFlags

The following can be combined with the ‘|’ operator: CREATE_AsChild

Parm1 Parm2

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.

Return Value

hWndCreated is the handle of the new window.

See Also

SalModalDialog SalDestroyWindow

Example

On SAM_Click If NOT SalCreateWindowExWithParms (frmCustomer, hWndNULL, nLeft, nTop, nWidth, nHeight) ...Error...


2-17

Chapter

2


SalCursorClear Syntax

bOk = SalCursorClear ( hWnd, nType )

Description

Clears a window's cursor.

Parameters

hWnd

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

nType

Number. The cursor type. Specify one of these constants: CURSOR_DisableDrop CURSOR_DragDrop CURSOR_Window

Return Value


See Also

SalCursorSet SalCursorSetFile SalCursorSetString

Example

On SAM_Click Call SalCursorClear (frmMain, Cursor_Windows)

SalCursorSet Syntax

bOk = SalCursorSet ( hWnd, tResource, nType )

Description

Sets a window's cursor.

Parameters

hWnd


tResource

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


Return Value


See Also

SalCursorClear SalCursorSetFile SalCursorSetString

Example

On SAM_Click Call SalCursorSet (frmMain, Cursor_Arrow, Cursor_Window)

SalCursorSetFile Syntax

bOk = SalCursorSetFile ( hWnd, sFile, nType )

Description

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

Parameters

hWnd


sFile

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

nType


Return Value


See Also

SalCursorClear SalCursorSet SalCursorSetString

Example

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

SalCursorSetString Syntax

bOk = SalCursorSetString ( hWnd, sBuffer, nType )

Description

Sets a window's cursor from a string variable.

Parameters

hWnd



2-19

Chapter

2


sBuffer

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

nType


Return Value


See Also

SalCursorClear SalCursorSet SalCursorSetFile

Example

On SAM_Click Call SalCursorSetString (frmMain, strCurBuf, Cursor_Window)

SalDateConstruct Syntax

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

Description

Returns the date/time constructed from the parameters nYear, nMonth, nDay, nHour, nMinute, and nSecond. If you specify invalid parameter values, an unexpected date construction can result. Note: If any of the parameter values has less than the specified number of digits, SalDateConstruct pads the resulting value with leading zeroes (0). For example, if nYear is 92, dtDate begins with 0092.

Parameters

Return Value

2-20

nYear

Number. A number with a 4-digit year value.

nMonth

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

nDay

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

nHour

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

nMinute

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

nSecond

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

dtDate is the newly constructed date/time value.


Example

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

SalDateCurrent Syntax

dtNow = SalDateCurrent ( )

Description

Returns the PC's current date/time. To get the database server's system date/ time, use a database system keyword (SYSDATE, SYSTIME, or SYSDATETIME ) in a SQL SELECT statement.

Parameters

No parameters.

Return Value

dtNow is the PC's current date/time.

Example

On SAM_Create Set dfCurrent = SalDateCurrent ( )

SalDateDay Syntax

nDay = SalDateDay ( dtDateTime )

Description

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

Parameters

dtDateTime

Return Value

nDay is a number between 1 and 31.

See Also

SalDateMonth

Date/Time. A date/time value.

SalDateYear Example

Set nDay = SalDateDay ( dtDateTime )

SalDateHour Syntax

nHour = SalDateHour ( dtDateTime )

Description

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

Parameters

dtDateTime

Return Value

nHour is a number between 0 and 23.

See Also

SalDateMinute


SalDateSecond


2-21

Chapter

2

Example


Set nHour= SalDateHour ( dtDateTime )

SalDateMinute Syntax

nMinute = SalDateMinute ( dtDateTime )

Description

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

Parameters

dtDateTime

Return Value

nMinute is a number between 0 and 59.

See Also

SalDateHour


SalDateSecond Example

Set nMinute = SalDateMinute ( dtDateTime )

SalDateMonth Syntax

nMonth = SalDateMonth ( dtDateTime )

Description

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

Parameters

dtDateTime

Return Value

nMonth is a number between 1 and 12.


Related Functions SalDateDay SalDateYear Example

Set nMonth = SalDateMonth ( dtDateTime )

SalDateMonthBegin Syntax

dtMonthBegin = SalDateMonthBegin ( dtDateTime )

Description

Returns the date of the first day of the month or it returns DATETIME_Null if the value you specify is null. For example, if dtDateTime is December 25, 1992, SalDateMonthBegin returns December 1, 1992.

Parameters

dtDateTime

Return Value

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

See Also

SalDateQuarterBegin

2-22



SalDateWeekBegin Example

Set dtMonthBegin = SalDateMonthBegin ( SalDateCurrent ( ) )

SalDateQuarter Syntax

nQuarter = SalDateQuarter ( dtDateTime )

Description

Returns the quarter of the year (1 to 4) of a date/time value or returns -1 if you specify DATETIME_Null as a parameter.

Parameters

dtDateTime

Return Value

nQuarter is a number between 1 and 4.

Example

Select Case ( SalDateQuarter ( dtDate ) )


Case 1 Set strQuarter = 'First Quarter' Break ...

SalDateQuarterBegin Syntax

dtQuarterBegin = SalDateQuarterBegin ( dtDateTime )

Description

Returns the date of the first day of the quarter of a date/time value or it returns DATETIME_Null if the value you specify is null.

Parameters

dtDateTime

Return Value

dtQuarterBegin is the first day of the quarter of dtDateTime.

See Also

SalDateMonthBegin SalDateWeekBegin SalDateYearBegin

Example

Set dtQuarterBegin = SalDateQuarterBegin


( SalDateCurrent ( )

SalDateSecond Syntax

nSeconds = SalDateSecond ( dtDateTime )

Description

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

Parameters

dtDateTime



2-23

Chapter

2


Return Value

nSeconds is a number between 0 and 59.

See Also

SalDateHour SalDateMinute

Example

Set nSeconds = SalDateSecond ( dtDateTime )

SalDateToStr Syntax

nLength = SalDateToStr ( dtDateTime, strDate )

Description

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

Parameters

dtDateTime

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

strDate

Receive string. The resulting string value.

Return Value

nLength is the length of strDate.

See Also

SalFmtFormatDateTime SalStrToDate

Example

Call SalDateToStr ( dtDateTime, strDateTime ) ! strDateTime = YYYY-MM-DD-HH.MM.SS.TTTTTT

SalDateWeekBegin Syntax

dtWeekBegin = SalDateWeekBegin ( dtDateTime )

Description

Returns the date of the previous Monday or the current day if it is a Monday or it returns DATETIME_Null if the value you specify is null.

Parameters

dtDateTime

Return Value

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

See Also

SalDateMonthBegin SalDateQuarterBegin SalDateYearBegin

Example

Set dtWeekBegin = SalDateWeekBegin ( SalDateCurrent ( ) )

2-24



SalDateWeekday Syntax

nWeekday = SalDateWeekday ( dtDateTime )

Description

Returns the day of the week as a number between 0 and 6 or returns -1 if you specify DATETIME_Null as a parameter. 0 represents Saturday, 1 represents Sunday, and so on.

Parameters

dtDateTime


Return Value nWeekday is a number between 0 and 6. Example

Select Case ( SalDateWeekday ( dtDate ) ) Case 0 Set strWeekday = 'Saturday' Break

SalDateYear Syntax

nYear = SalDateYear ( dtDateTime )

Description

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

Parameters

dtDateTime

Return Value

nYear is the year portion of a date.

See Also

SalDateDay SalDateMonth

Example

Set nYear = SalDateYear ( dtDateTime )


SalDateYearBegin Syntax

dtYearBegin = SalDateYearBegin ( dtDateTime )

Description

Returns the date of the first day of the year or it returns DATETIME_Null if the value you specify is null.

Parameters

dtDateTime

Return Value

dtYearBegin is the date of the first day of the year.

See Also

SalDateMonthBegin SalDateQuarterBegin SalDateWeekBegin



2-25

Chapter

2

Example


Set dtYearBegin = SalDateYearBegin ( SalDateCurrent ( ) )

SalDDEAddAtom Syntax

nNewAtom = SalDDEAddAtom ( strStringToAdd )

Description

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

strStringToAdd

Return Value

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

See Also

SalDDEDeleteAtom SalDDEFindAtom SalDDEGetAtomName

Example

Set nOptions = SalDDEAlloc ( )

String. The string (255 characters or less) to add to the global atom table.

Call SalDDESetOptions ( nOptions, 0, CF_Text ) Set nItem = SalDDEAddAtom ( strItem ) Call SalDDEPost( hWndServer, WM_DDE_Advise, hWndForm, nOptions, nItem )

SalDDEAlloc Syntax

nMemory = SalDDEAlloc ( )

Description

Allocates a memory handle 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.

Parameters

No paameters.

Return Value

nMemory is a global memory handle. If the function fails, nMemory is zero (0).

See Also

SalDDEFree

Example

Set nOptions = SalDDEAlloc ( )

2-26


SalDDEDeleteAtom Syntax

nAtomCount = SalDDEDeleteAtom ( nAtomToDelete )

Description

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

nAtomToDelete

Return Value

If the function succeeds, nAtomCount is zero (0). If the function fails, nAtomCount is equal to nAtomToDelete.

See Also

SalDDEAddAtom

Example

Call SalDDEDeleteAtom ( nReceivedItem )

Number. The atom to delete.

SalDDEExtract Syntax

bOk = SalDDEExtract ( nwParam, nlParam, hWndSender, nLowlParam, nHighlParam )

Description

Extracts the sender's window handle and the data in the lParam parameter upon receipt of a Windows DDE message.

Parameters

nwParam

Number. The word parameter of the DDE message.

nlParam

Number. The long parameter of the DDE message.

hWndSender

Receive Window Handle. The sender's window handle.

nLowlParam

Receive Number. The low-order word of lParam.

nHighlParam

Receive Number. The high-order word of lParam.

Return Value

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

Example

Call SalDDEExtract (wParam, lParam, hWndServer, nData,nReceivedItem)

SalDDEExtractCmd Syntax

bOk = SalDDEExtractCmd ( nCommand, strCommand, nCommandSize )

Description

Extracts the command string referenced by the high-order word of the lParam of a WM_DDE_Execute message.

Parameters

nCommand

Number. The memory handle for the command string.


2-27

Chapter

2


strCommand

Receive String. The command string.

nCommandSize

Number. The maximum size of the command string.

Return Value


See Also

SalDDESetCmd

Example

If SalDDEExtractCmd ( nCommand, strCommand, nCommandSize ) Set fldData = strCommand

SalDDEExtractDataText Syntax

bOk = SalDDEExtractDataText ( nData, nStatus, strData, nDataSize )

Description

Extracts the data referenced by the low-order word of the lParam in a WM_DDE_Data or WM_DDE_Poke message.

Parameters

nData

Number. The handle of the memory object that contains the data and other information.

nStatus

Receive Number. The status word. See the DDE chapter in the Centura Developer’s Reference for more about the DDE_* status bits.

strData

Receive string. The data.

nDataSize

Number. The size of the data buffer.

Return Value


See Also

SalDDESetDataText

Example

Call SalDDEExtractDataText ( nData, nStatus, strDDEData, DDE_Data )

SalDDEExtractOptions Syntax

bOk = SalDDEExtractOptions ( nOptions, nFlags, nFormat )

Description

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 Developer’s Reference.

Parameters

2-28

nwParam

Number. The word parameter of the DDE message.

nlParam

Number. The long parameter of the DDE message.

hWndSender

Receive WIndow handle. The sender's window handle.


nLowParam

Receive Number. The low-order word of lParam.

nHighParam

Receive Number. The high-order .word of lParam.

Return Value

None.

Example

If NOT SalDDEExtractOptions ( nOptions, nFlags, nFormat) Call SalMessageBox ( 'Cannot extract option?', 'DDE Server', MB_Ok )

SalDDEFindAtom Syntax

nAtom = SalDDEFindAtom ( strTopicString )

Description

Searches the global atom table and returns the atom associated with the given string.

Parameters

strTopicString

Return Value

nAtom is the global atom associated with strTopicString. nAtom is zero (0) if Centura does not find the string in the atom table.

See Also

SalDDEGetAtomName

Example

If nApplication = 0

String. The string to search for.

Set nApplication = SalDDEAddAtom ( DDEServer_Application) Call SalMessageBox ( 'Add Application atom', 'DDE', MB_Ok)

SalDDEFree Syntax

nHandle = SalDDEFree ( nMemory )

Description

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

nMemory

Return Value

nHandle is zero (0) if the function succeeds, and is equal to the value of nMemory if the function fails.

See Also

SalDDEAlloc

Number. The memory handle to free.


2-29

Chapter

2

Example


Call SalDDEDeleteAtom ( nReceivedItem ) If nStatus & DDE_fRelease Call SalDDEFree ( nData )

SalDDEGetAtomName Syntax

nAtomSize = SalDDEGetAtomName ( nAtom, strAtomName, nStringLength )

Description

Returns the string associated with an atom.

Parameters

nAtom

Number. The atom number.

strAtomName

Receive string. The string associated with nAtom.

nStringLength

Number. Specify the maximum length of strAtomName.

Return Value

nAtomSize is the length of the returned string if the function succeeds and zero (0) if there is no such atom.

See Also

SalDDEAddAtom SalDDEDeleteAtom SalDDEFindAtom

Example

Set nAtomSize = SalDDEGetAtomName ( nAtom, strAtomName, nStringLength )

SalDDEGetExecuteString Syntax

strCommand = SalDDEGetExecuteString ( nMsglParam )

Description

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.

Parameters

nMsglParam

Return Value

strCommand is the command string sent by a client application to the server.

Example

Set strCommand = SalDDEGetExecuteString ( nMsglParam )

Number. The lParam of the SAM_DDE_ClientExecute message that contains the command string.

SalDDEPost Syntax

nReturn = SalDDEPost ( hWndReceiver, nMessage, hWndSender, nLowlParam, nHighlParam )

Description

Posts all WM_DDE_* messages except: •

2-30

WM_DDE_Initiate


•

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

Window Handle. The receiver's window handle.

nMessage

Number. The message number.

hWndSender

Window Handle. The sender's window handle.

nLowlParam

Number. The low-order word of the lParam parameter sent with the message.

nHighlParam

Number. The high-order word of the lParam parameter sent with the message.

Return Value

nReturn is a non-zero value if the function succeeds and zero (0) otherwise.

See Also

SalDDESend SalDDESendAll

Example

Call SalDDEPost ( hWndServer, WM_DDE_Execute,hWndForm, 0, nCommand)

SalDDERequest Syntax

bOk = SalDDERequest ( hWndClient, strService, strServerTopic, strServerItem, nTimeout, strData )

Description

A client application calls this function to ask a server to send data.

Parameters

hWndClient

Window Handle. The client's window handle associated with the DDE service, topic, and item.

strService

String. The DDE service name.

strServerTopic

String. The DDE topic name.

strServerItem

String. The DDE item name.

nTimeout

Number. The timeout value in milliseconds.

strData

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

2

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

nReturn = SalDDESend ( hWndReceiver, nMessage, hWndSender, nLowlParam, nHighlParam )

Description

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.

Parameters

hWndReceiver

Window Handle. The receiver's window handle.

nMessage


hWndSender


nLowlParam


nHighlParam


Return Value

nReturn is the value returned from the receiver of the message.

See Also

SalDDEPost SalDDESendAll

Example

Call SalDDESend ( hWndClient, WM_DDE_Ack, hWndForm, nApplication, nTopic )

SalDDESendAll Syntax

nReturn = SalDDESendAll ( nMessage, hWndSender, nLowlParam, nHighlParam )

Description

Broadcasts a WM_DDE_Initiate message and does not return until all receivers have processed the message.

Parameters

nMessage


hWndSender


nLowlParam


2-32


nHighlParam


Return Value

nReturn is a non-zero value if the function succeeds, and zero (0) otherwise.

See Also

SalDDEPostSalDDESend

Example

Call SalDDESendAll ( WM_DDE_Initiate, hWndForm, nApplication, nTopic )

SalDDESendExecute Syntax

bOk = SalDDESendExecute ( hWndClient, strService, strServerTopic, strServerItem, nTimeout, strCommand )

Description

A client calls this function to send a WM_DDE_Execute command to a server.

Parameters

hWndClient

Window Handle. The client's window handle associated with the DDE service, topic, and item.

strService

String. The DDE service.

strServerTopic


strServerItem


nTimeout


strCommand

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 Developer’s Reference.

Return Value


Example

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

2


SalDDESendToClient Syntax

bOk = SalDDESendToClient ( hWndServer, strData, nClientID, nTimeout )

Description

A server application calls this function to send data to clients. Use SalDDESendToClient with both hot and cold link conversations.

Parameters

hWndServer

Window Handle. The server's window handle associated with the DDE service, topic, and item.

strData

String. The data to send to clients.

nClientID

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

If NOT SalDDESendToClient ( frmMain, dfServerData, 0, 100 ) Call SalWaitCursor ( FALSE )

SalDDESetCmd Syntax

bOk = SalDDESetCmd ( nHighlParam, strCommand )

Description

Assigns a command string to the data referenced by the high-order word of the lParam in a WM_DDE_Execute message.

Parameters

nHighlParam

Number. The handle to the command block that contains the command string.

strCommand

String. The command to execute.

Return Value


See Also

SalDDEExtractCmd

Example

Call SalDDESetCmd ( nCommand, strCommand ) Call SalDDEPost ( hWndServer, WM_DDE_Execute, hWndForm, 0, nCommand )

2-34


SalDDESetDataText Syntax

bOk = SalDDESetDataText ( nData, nStatus, strData )

Description

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.

Parameters

nData

Number. The handle to the memory object that contains the data and other information.

nStatus

Number. The status word. See the DDE chapter in the Centura Developer’s Reference for more about the DDE_* status bits.

strData

String. The value to assign.

Return Value


See Also

SalDDEExtractDataText

Example

Call SalDDESetDataText ( nData, nDDEFlags, strData ) Call SalDDEPost ( hWndServer, WM_DDE_Poke, hWndForm, nData, nItem )

SalDDESetOptions Syntax

bOk = SalDDESetOptions ( nOptions, nFlags, nFormat )

Description

Assigns a value to the data referenced by the low-order word of the lParam in a WM_DDE_Advise message.

Parameters

nOptions

Number. The handle to the memory object that specifies how the data is to be sent.

nFlags

Number. The status word. See the DDE chapter in the Centura Developer’s Reference for more about the DDE_* status bits.

nFormat

Number. The CF_* data format.

Return Value


Example

Call SalDDESetOptions ( nOptions, 0, CF_Text ) Set nItem = SalDDEAddAtom ( strItem ) Call SalDDEPost ( hWndServer, WM_DDE_Advise, hWndForm, nOptions, nItem )


2-35

Chapter

2


SalDDEStartServer Syntax

bOk = SalDDEStartServer ( hWndServer, strService, strServerTopic, strServerItem )

Description

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.

Parameters

hWndServer

Window Handle. The server's window handle associated with the DDE application, topic, and item.

strService


strServerTopic


strServerItem


Return Value


Example

If NOT SalDDEStartServer ( frmMain, dfServerApplication, dfServerTopic, dfServer Item) Call SalWaitCursor ( FALSE )

SalDDEStartSession Syntax

bOk = SalDDEStartSession ( hWndDest, strService, strServerTopic, strServerItem, nTimeout )

Description

A client calls this function to start a hot link conversation with a server application.

Parameters

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.

Return Value

2-36

strService


strServerTopic


strServerItem


nTimeout




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

bOk = SalDDEStopServer ( hWndServer )

Description

A server calls this function to end DDE server operations. The server must call SalDDEStopServer for each successful SalDDEStartServer.

Parameters

hWndServer

Return Value


Example

If NOT SalDDEStopServer ( frmMain )

Window Handle. The server's window handle associated with the DDE service, topic, and item.

Call SalWaitCursor ( FALSE )

SalDDEStopSession Syntax

bOk = SalDDEStopSession ( hWndDest )

Description

A client calls this function to end a hot link conversation with a server application. The client must call SalDDEStopSession for each successful SalDDEStartSession.

Parameters

hWndDest

Return Value


Example

If NOT SalDDEStopSession ( mlString1 )

Window Handle. The handle (or name) of the object in the client application associated with the DDE service, topic, and item.

Call SalWaitCursor ( FALSE )

SalDestroyWindow Syntax

bOk = SalDestroyWindow ( hWndDestroy )

Description

Destroys a form window, a top-level table window, or a modeless dialog box created with SalCreateWindow. In the case of a form window or top-level table window, you can have automatically created it at runtime.

Parameters

hWndDestroy

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


2-37

Chapter

2


Return Value


See Also

SalCreateWindow SalEndDialog

Example

On SAM_Click Call SalDestroyWindow ( hWndForm )

SalDisableWindow Syntax

bOk = SalDisableWindow ( hWndDisable )

Description

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

hWndDisable

Return Value


See Also

SalDisableWindowAndLabel SalEnableWindow SalIsWindowEnabled

Example

On SAM_Create

Window Handle. The handle (or name) of the window to disable.

Call SalDisableWindow ( pbUpdate )

SalDisableWindowAndLabel Syntax

bOk = SalDisableWindowAndLabel ( hWndDisable )

Description

Disables keyboard and mouse input to a window and grays out its associated label. A label is the background text that immediately precedes the window in the outline. The bacground text must have a mneumonic. If the window contains text (for example, a push button), the text is grayed. If the window is a data field, it cannot receive the focus.

Parameters

hWndDisable

Return Value


See Also

SalDisableWindow

Window Handle. The handle (or name) of the window to disable.


2-38


SalIsWindowEnabled SalGetWindowLabelText SalHideWindowAndLabel SalSetWindowLabelText SalShowWindowAndLabel Example

Call SalDisableWindow ( dfName )

SalDlgChooseColor Syntax

bRet = SalDlgChooseColor ( hWndOwner, nColor )

Description

Displays the Windows Color dialog box where the user can either select an existing color or create a new one. See the Control Panel chapter in the Microsoft Windows' User's Guide for a detailed description of the Color dialog box.

Parameters

hWndOwner

Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner.

nColor

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

Return Value

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

See Also

SalDlgChooseFont

Example

On SAM_Click Call SalDlgChooseColor ( frmMain, nColor )

SalDlgChooseFont Syntax

bRet = SalDlgChooseFont ( hWndOwner, strFontName, nSize, nEnhancements, nColor )

Description

Displays the Windows Font dialog box where the user can choose a font as well as its size, style, enhancements, display color, and so on. See the Control Panel chapter in the Microsoft Windows' User's Guide for a detailed description of the Font dialog box.

Parameters

hWndOwner


strFontName

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


2-39

Chapter

2


nSize

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

nEnhancements

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

nColor

Receive Number. Specify the initial text color. When SalDlgChooseFont returns, nColor is the text color that the user selects.

Return Value

bRet is TRUE if the user chooses a font and FALSE if the user clicks the Cancel push button.

See Also

SalDlgChooseColor

Example

Call SalDlgChooseFont ( frmMain, strFontName, nSize, nEnhancements )

SalDlgOpenFile Syntax

bRet = SalDlgOpenFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex, strFile, strPath )

Description

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

Parameters

hWndOwner


strDlgTitle

String. The title of the Open file dialog box.

strFilters

String. An array of file filters and their descriptions. Each filter must have a description that precedes the filter in the array. For example, to enable users to open files with only specific extensions, populate the strFilters array with filters such as: Set strFilters[0] = 'Executable Files' Set strFilters[1] = '*.exe' Set strFilters[2] = 'Dynamic Link Libraries' Set strFilters[3] = '*.dll' Set strFilters[4] = 'Initialization Files' Set strFilters[5] = '*.ini'

nFilters

Number. The number of elements in strFilters. The above array of six elements contains three filters. Specify 6 to display all three filters. You can limit the number of filters displayed. For example, to display only the first two filters (*.exe and *.dll), specify 4.

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.

strFile

Receive String. The file name the user chooses. To initialize the combo box in which the file names display, assign a file name to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, Centura ignores your attempt to set the default display value.

strPath

Receive String. The full path name of the file the user chooses. To initialize the combo box in which the paths display, assign a path to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, Centura ignores your attempt to set the default display value.

Return Value

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

See Also

SalDlgSaveFile

Example

Message Actions On SAM_Create 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

2


SalDlgSaveFile Syntax

bRet = SalDlgSaveFile ( hWndOwner, strDlgTitle, strFilters, nFilters, nIndex, strFile, strPath )

Description

Displays a Windows dialog box where the user can save a file. If you do not specify a file extension, Centura saves the file with the extension displayed by the Save File as Type combo box.

Parameters

hWndOwner


strDlgTitle

String. The title of the Save file dialog box.

strFilters

String. An array of file filters and their descriptions. Each filter must have a description that precedes the filter in the array. For example, to enable users to save files with only specific extensions, populate the strFilters array with filters such as: 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

2-42


Receive String. The file name the user chooses.

To initialize the combo box in which the file names display, assign a file name to a variable prior to calling SalDlgSaveFile. In the subsequent SalDlgSaveFile call, specify the variable for this parameter. If the variable's value is incorrect or invalid, 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

No parameters.

Return Value


See Also

SalDragDropEnableDrop

Example

On SAM_Click Call SalDragDropDisableDrop ()


2-43

Chapter

2


SalDragDropEnableDrop Syntax

bOk = SalDragDropEnableDrop ( )

Description

Enables dropping while in drag mode.

Parameters

No parameters.

Return Value


See Also

SalDragDropDisableDrop

Example

On SAM_Click Call SalDragDropEnableDrop ()

SalDragDropGetSource Syntax

bOk = SalDragDropGetSource ( hWndSource, nX, nY )

Description

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

Parameters

hWndSource

Receive Window Handle. The handle of the source window. These window types can be source windows:

nX

Combo box Multiline field Data field Picture List box Table window Receive Number. The position of the mouse on the X axis.

nY

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

Return Value


See Also

SalDragDropGetTarget

Example

On SAM_Click Call SalDragDropGetSource (hWndSource,nX, nY)

2-44


SalDragDropGetTarget Syntax

bOk = SalDragDropGetTarget ( hWndTarget, nX, nY )

Description

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

Parameters

hWndTarget

Receive Window Handle. The handle of the target window. Any Centura window type can be a target window, however windows without actions (such as frames) do not receive SAM_Drag* messages.

nX

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

nY

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

Return Value


See Also

SalDragDropGetSource

Example

On SAM_Click Call SalDragDropGetTarget (hWndRecv,nX, nY)

SalDragDropStart Syntax

bOk = SalDragDropStart ( hWndSource )

Description

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

Parameters

hWndSource

Return Value


See Also

SalDragDropStop

Example

On SAM_Click


Call SalDragDropStart (frmMain)

SalDragDropStop Syntax

bOk = SalDragDropStop ( )

Description

Ends drag mode.

Parameters

No parameter.

Return Value



2-45

Chapter

2


See Also

SalDragDropStart

Example

Set bOk = SalDragDropStop ( )

SalDrawMenuBar Syntax

bOk = SalDrawMenuBar ( hWndForm )

Description

Redraws the menu bar for a given form window or top-level table window. Call this function to cause top-level menu items to be enabled or disabled. For a top-level menu item or pop-up menu, an Enabled when variable is only evaluated when you call SalDrawMenuBar or when the menu bar is redrawn for other reasons.

Parameters

hWndForm

Return Value


Example

On SAM_Click

Window Handle. The handle (or name) of the form window or top-level table window whose menu bar you want to redraw.

Call SalDrawMenuBar ( frmMain)

SalDropFilesAcceptFiles Syntax

bOk = SalDropFilesAcceptFiles ( hWnd, bAccept )

Description

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

Parameters

hWnd


bAccept

Boolean. Specify whether hWnd can accept a file from Windows' File Manager. The default for editable pictures is TRUE; the default for all other window types is FALSE.

Return Value


See Also

SalDropFilesQueryFiles SalDropFilesQueryPoint

Example

Set bAccept = SalDropFilesAcceptFiles ( hWnd, TRUR )

2-46


SalDropFilesQueryFiles Syntax

nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )

Description

Retrieves the names of the files dropped on a window. Receipt of the SAM_DropFilesmsg_SAM_DropFiles message indicates that the user dropped files onto the window.

Parameters

hWndSource

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

sArrayFiles

Receive String Array. The names of the dropped files.

Return Value

nFiles is the number of dropped files if the function succeeds and zero (0) if the function fails. SalDropFilesQueryFiles fails unless it is called as the result of receiving the SAM_DropFiles message.

See Also

SalDropFilesAcceptFiles SalDropFilesQueryPoint

Example

On SAM_Click Set nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )


2-47

Chapter

2


SalDropFilesQueryPoint Syntax

bOk = SalDropFilesQueryPoint ( hWnd, nX, nY )

Description

Finds the location of the mouse in a window at the time that the user dropped files onto the window. Receipt of the SAM_DropFiles message indicates that the user dropped files onto the window.

Parameters

hWnd

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

nX

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

nY

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

Return Value


See Also

SalDropFilesAcceptFiles SalDropFilesQueryFiles

Example

On SAM_Click Call SalDropFilesQueryPoint ( hWnd, nX, nY )

SalEditCanCopyTo Syntax

bOk = SalEditCanCopyTo ( )

Description

This function returns TRUE if an editable picture has the focus and contains an object that can be copied to a file. You can use this function in the Enabled When section for a Copy To menu item.

Parameters

No parameters.

Return Value

bOk is TRUE if an editable picture has the focus and contains an object, and FALSE otherwise. bOk is TRUE even when the picture's contents are not the result of a Paste From operation.

See Also

SalEditCopyTo

Example

Menu Popup Menu: &Edit Menu Item: &Copy To ... Menu Settings Enabled when: SalEditCanCopyTo ( )

2-48


SalEditCanCut Syntax

bOk = SalEditCanCut ( )

Description

This function returns TRUE if the data in a data field, multiline field, table window column, or editable picture is selected. You can use this function in the Enabled When section for a Cut menu item.

Parameters

No parameters.

Return Value

bOk is TRUE if data is selected and FALSE otherwise.

See Also

SalEditCut

Example

Menu Settings Enabled when: SalEditCanCut ( ) ...

SalEditCanPaste Syntax

bOk = SalEditCanPaste ( )

Description

This function returns TRUE if there is data on the Clipboard that can be pasted into the editable picture with the focus. You can use this function in the Enabled When section for a Paste menu item.

No Parameters Return Value bOk is TRUE if there is data on the Clipboard to be pasted and FALSE otherwise. See Also

SalEditPaste

Example

Menu Settings Enabled when: SalEditCanPaste ( )

SalEditCanPasteFrom Syntax

bOk = SalEditCanPasteFrom ( )

Description

This function returns TRUE if an editable picture has the focus. You can use this function in the Enabled When section for a Paste From menu item.

Parameters

No parameters.

Return Value bOk is TRUE if an editable picture has the focus and FALSE otherwise. See Also

SalEditPasteFrom Centura Builder Function Reference

2-49

Chapter

2

Example


Menu Settings Enabled when: SalEditCanPasteFrom ( )

SalEditCanUndo Syntax

bOk = SalEditCanUndo ( )

Description

This function returns TRUE if there is any editing of a data field, multiline field, table window column, or picture that can be undone. You can use this function in the Enabled When section for an Undo menu item.

No Parameters Return Value

bOk is TRUE if there is any editing to undo and FALSE otherwise.

See Also

SalEditUndo

Example

Menu Settings Enabled when: SalEditCanUndo ( ) ...

SalEditClear Syntax

bOk = SalEditClear ( )

Description

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.

Parameters

No parameters.

Return Value


Example

Menu Settings Enabled when: SalEditCanCut ( )

SalEditCopy Syntax

bOk = SalEditCopy ( )

Description

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

Parameters

No parameters.

Return Value


2-50


Example

Menu Settings Enabled when: SalEditCanCut ( ) ... Menu Actions Call SalEditCopy ( )

SalEditCopyString Syntax

bOk = SalEditCopyString ( strString )

Description

Copies a string to the Clipboard as text.

Parameters

strString

Return Value


See Also

SalEditPasteString

Example

Menu Actions

String. The string to copy to the Clipboard.

Call SalEditCopyString ( mlNotes )

SalEditCopyTo Syntax

bOk = SalEditCopyTo ( )

Description

Copies an object to a file from an editable picture. The picture must have the focus. This function only works when the picture's contents are the result of a Paste From operation.

Parameters

No parameters.

Return Value


See Also

SalEditCanCopyTo SalEditPasteFrom

Example

Menu Actions Call SalEditCopyTo ( )

SalEditCut Syntax

bOk = SalEditCut ( )

Description

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

Parameters

No parameters.


2-51

Chapter

2


Return Value


See Also

SalEditCanCut

Example

Menu Settings Enabled when: SalEditCanCut ( )

SalEditPaste Syntax

bOk = SalEditPaste ( )

Description

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

Parameters

No parameters.

Return Value


See Also

SalEditCanPaste

Example

Menu Actions Call SalEditPaste ( )

SalEditPasteFrom Syntax

bOk = SalEditPasteFrom ( )

Description

Copies a file to the editable picture with the focus. This function displays the Paste From dialog box where the user can select a file to paste into the picture. The user can retrieve these file types: Type

2-52

File Extension

Description

BMP

.

Device-Independent Bitmap

DIB

.dib


GIF

.gif

Graphics Interchange Format

ICON

.ico

Icon File

PCX

.pcx

Paintbrush

TIFF

.tif

Tag Image File Format

JPEG

*.jpg

JPEG format


WMF

.wmf

Windows MetaFile

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

No parameters.

Return Value


See Also

SalEditCanPasteFrom

Example

Menu Actions Call SalEditPasteFrom ( )

SalEditPasteString Syntax

bOk = SalEditPasteString ( strString )

Description

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

Parameters

strString

Return Value


See Also

SalEditCopyString

Example

Call SalEditPasteString ( strOldClipboard )

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

SalEditUndo Syntax

bOk = SalEditUndo ( )

Description

Undoes the last edit to a data field, multiline field, table window column, or picture. Editing that you can undo includes inserting text, cutting text, clearing text, and pasting text.

Parameters

No parameters.

Return Value


See Also

SalEditCanUndo

Example

Menu Settings Enabled when: SalEditCanUndo ( )


2-53

Chapter

2


SalEnableWindow Syntax

bOk = SalEnableWindow ( hWndEnable )

Description


Parameters

hWndEnable

Return Value


See Also

SalDisableWindow SalEnableWindowAndLabel SalIsWindowEnabled

Example

Call SalEnableWindow ( frmCustomer )

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

SalEnableWindowAndLabel Syntax

bOk = SalEnableWindowAndLabel ( hWndEnable )

Description

Enables keyboard and mouse input to a window and enables its associated label as well. A label is the background text that immediately precedes the window in the outline.

Parameters

hWndEnable

Return Value


See Also

SalDisableWindowAndLabel SalEnableWindow WindowEnabled

Example

On SAM_Click

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

Call SalEnableWindowAndLabel ( dfName )

SalEndDialog Syntax

bOk = SalEndDialog ( hWndModal, nReturn )

Description

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

Parameters

hWndModal

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

nReturn

Number. The Return Value from the SalModalDialog function.

Return Value 2-54



See Also

SalModalDialog

Example

On SAM_Click Call SalEndDialog ( hWndForm, 0 )

SalFileClose Syntax

bOk = SalFileClose ( hFile )

Description

Closes a file.

Parameters

hFile

Return Value


See Also

SalFileOpen

Example

If NOT SalFilePutStr ( hFile, sLine )

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

Call SalFileClose ( hFile ) Call SalMessageBeep ( 0 )

SalFileCopy Syntax

nStatus = SalFileCopy ( strSourcePath, strDestPath, bOverWrite )

Description

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

Parameters

strSourcePath

String. The full path name of the source file.

strDestPath

String. The full path name of the destination file.

bOverWrite

Boolean. Specifies whether (TRUE) or not (FALSE) to overwrite the destination file. If the destination file already exists and bOverWrite is FALSE, then SalFileCopy fails, and returns FILE_CopyExist. If the destination file already exists and bOverWrite is TRUE, then SalFileCopy succeeds and the destination file is overwritten.

Return Value

nStatus is equal to one of the following values: FILE_CopyDest FILE_CopyExist FILE_CopyOK FILE_CopyRead FILE_CopySrc FILE_CopyWrite


2-55

Chapter

2

Example


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

SalFileCreateDirectory Syntax

bOk = SalFileCreateDirectory ( strDir )

Description

Creates a directory.

Parameters

strDir

Return Value

bOk is TRUE if the function succeeds and FALSE if a directory or file with the specified name already exists, or if the specified path to the directory cannot be found.

See Also

SalFileRemoveDirectory

Example

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

String. The full path name of the new directory.

SalFileGetC Syntax

bOk = SalFileGetC ( hFile, nChar )

Description

Returns the next character in an open file. You must use this function in place of the SalFileGetChar function if the file contains non-ASCII (ANSI) or 16-bit characters. If the character returned is a 16-bit character, the lead byte of the character is in the high-order byte, and the trail byte is in the low-order byte. To get the lead byte, use SalNumberHighand to get the trail byte, use SalNumberLow.

Parameters

hFile

File Handle. The handle of the open file.

nChar

Receive Number. The next character in hFile.

Return Value

bOk is TRUE if the function succeeds and FALSE if the function is unable to read the next character from the file, or if an invalid file handle is passed in hFile.

See Also

SalFilePutC

Example

On SAM_AppStartup Call SalFileOpen ( hFile, 'C:\\DB\\APP.LOG', OF_Read | OF_Binary )

2-56


SalFileGetChar Syntax

nChar = SalFileGetChar ( hFile )

Description

Returns the next character in an open file.

Parameters

hFile

Return Value

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

See Also

SalFilePutChar

Example

If SalFileOpen ( fhDestFile, strDestFile, OF_Create


| OF_ReadWrite ) Loop Set nChar = SalFileGetChar ( fhSrcFile ) ...

SalFileGetCurrentDirectory Syntax

bOk = SalFileGetCurrentDirectory ( strPath )

Description

Gets the full path name of the current working directory.

Parameters

strPath

Return Value


See Also

SalFileSetCurrentDirectory

Example

On SAM_AppStartup

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

If NOT SalFileGetCurrentDirectory

(strCurrentDir)

Call SalMessageBox ( 'Couldn't get current directory', 'Error', 0

SalFileGetDateTime Syntax

bOk = SalFileGetDateTime ( strFilename, dtDateTime )

Description

Gets the modification date and time of the specified file.

Parameters

strFilename

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

dtDateTime

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


2-57

Chapter

2


Return Value


See Also

SalFileSetDateTime

Example

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

SalFileGetDrive Syntax

strDriveLetter = SalFileGetDrive ( )

Description

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

No Parameters Return Value

strDriveLetter is a string identifying the current disk drive. The first character is a letter between ‘A’ and ‘Z’, and the second character is a colon(:).

See Also

SalFileSetDrive

Example

On SAM_AppStartup If SalFileGetDrive ( ) = 'A' Set blsDriveA = TRUE Else Set blsDriveA = FALSE

SalFileGetStr Syntax

bOk = SalFileGetStr ( hFile, strBuffer, nBufferSize )

Description

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

Parameters

hFile


strBuffer

Receive String. The returned string.

nBufferSize

Number. The maximum number of bytes to read.

Return Value

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

See Also

SalFilePutStr

Example

If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE ) Call SalFilePutStr ( fhDestFile, strText ) Else Break

2-58


SalFileOpen Syntax

bOk = SalFileOpen ( hFile, strFileName, nStyle )

Description

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

Parameters

hFile

Receive File Handle. The handle of the open file.

strFileName

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

nStyle

Number. A constant that specifies the style in which to open the file. nStyle can be one or more styles combined using the bitwise OR (|) operator.

Return Value


See Also

SalFileClose SalListFiles SalFileOpenExt

Example

Call SalFileOpen ( fhSrcFile, strSrcFile, OF_Read )

SalFileOpenExt Syntax

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

Description

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

Parameters

hFile

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

strFileName

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

nStyle

Number. A constant that specifies the style in which to open the file. nStyle can be one or more styles combined using the OR (|) operator.

strReopen

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

Return Value


See Also

SalFileOpenF

Example

On SAM_Create If SalFileOpenExt ( hFile, 'C:\\AUTOEXEC.BAT', OF_Read, strReopen )


2-59

Chapter

2


SalFilePutC Syntax

bOk = SalFilePutC ( hFile, nChar )

Description

Writes a character to an open file. Use this function instead of SalFilePutChar if the character is a non-ASCII (ANSI) or 16-bit character.

Parameters

hFile


nChar

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

Return Value

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

See Also

SalFileGetC

Example

Loop Call SalFilePutC ( hFile, nNull ) If nCount = 5 Break Set nCount = nCount + 1

SalFilePutChar Syntax

bOk = SalFilePutChar ( hFile, nChar )

Description


Parameters

hFile


nChar

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

Return Value


See Also

SalFileGetChar

Example

Call SalFileSeek (fhInFile, nFilePos, FILE,_SeekBegin) Call SalFilePutChar ( hFile, nChar )

2-60


SalFilePutStr Syntax

bOk = SalFilePutStr ( hFile, strString )

Description

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

Parameters

hFile


strString

String. The string to write.

Return Value


See Also

SalFileGetStr

Example

Loop ! Read each line from the source file and write it to the destination file If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE ) Call SalFilePutStr ( fhDestFile, strText )

SalFileRead Syntax

nResult = SalFileRead ( hFile, strBuffer, nBufferLength )

Description

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

Parameters

hFile


strBuffer

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

nBufferLength

Number. The number of bytes to read.

Return Value

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

See Also

SalFileWrite

Example

Call SalFileSeek ( fhInFile, nFilePos, FILE_SeekBegin ) Loop Set nCharsRead = SalFileRead ( fhInFile, strBuffer, nRecSize )


2-61

Chapter

2


SalFileRemoveDirectory Syntax

bOk = SalFileRemoveDirectory ( strDir )

Description

Deletes a directory.

Parameters

strDir

Return Value

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

See Also

SalFileCreateDirectory

Example

On SAM_AppStartup

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

Set bNotesOldDeleted = SalFileRemoveDirectory (strDir)

SalFileSeek Syntax

bOk = SalFileSeek ( hFile, nBytes, nPosition )

Description

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

Parameters

hFile

File Handle. The handle of an open file.

nBytes

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

nPosition

Number. The general position of the file pointer; one of the following values: FILE_SeekBegin FILE_SeekCurrent FILE_SeekEnd

Return Value


See Also

SalFileTell

Example

Call SalFileSeek ( fhInFile, 0, FILE_SeekBegin )

2-62


SalFileSetCurrentDirectory Syntax

bOk = SalFileSetCurrentDirectory ( strPath )

Description

Changes the current working directory. If the specified path does not contain a drive letter, the default drive's current directory is changed. Otherwise, the specified drive's current directory is changed without making that drive current.

Parameters

strPath

Return Value


See Also

SalFileGetCurrentDirectory SalFileSetDrive

Example

On SAM_AppStartup

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

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

SalFileSetDateTime Syntax

bOk = SalFileSetDateTime ( strFilename, dtDateTime )

Description

Sets the modification date and time of the specified file.

Parameters

strFilename

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

dtDateTime

Date/Time. The modification date and time.

Return Value


See Also

SalFileGetDateTime

Example

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

SalFileSetDrive Syntax

bOk = SalFileSetDrive ( strDriveLetter )

Description

Sets the current disk drive to the specified drive letter.

Parameters

strDriveLetter

Return Value


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.


2-63

Chapter

2


See Also

SalFileGetDrive SalFileSetCurrentDirectory

Example

On SAM_AppStartup Set bDriveIsC = SalFileSetDrive ( 'c' )

SalFileTell Syntax

nPos = SalFileTell ( hFile )

Description

Returns the current position in an open file.

Parameters

hFile

Return Value

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

See Also

SalFileSeek

Example

Set nRecPos = SalFileTell ( fhInFile)


SalFileWrite Syntax

nResult = SalFileWrite ( hFile, strBuffer, nBufferLength )

Description

Writes a string to an open file.

Parameters

hFile


strBuffer

String. The string to write to hFile.

nBufferLength

Number. The number of bytes to write.

Return Value

nResult is the number of bytes written.

See Also

SalFileRead

Example

Call SalFileWrite ( fhInFile, strCharBuf, 1 )

SalFmtFieldToStr Syntax

bOk = SalFmtFieldToStr ( hWndField, strValue, bFormat )

Description

Copies the contents of a data field or table window column to a string. This function also lets you copy the format of the data.

Parameters

hWndField

2-64


Window handle. The handle (or name) of the data field or table window column whose value (and optionally, whose format) you want to copy.

strValue

Receive String. The string to which to copy the data field's value. If bFormat is TRUE, the string must be long enough to hold the formatting characters.

bFormat

Boolean. Specifies whether you want to keep the field's format. If TRUE, CENTURA copies the formatted field contents to the string; if FALSE, Centura copies the unformatted field contents to the string.

Return Value


See Also

SalFmtStrToField

Example

On SAM_FieldEdit Call SalFmtFieldToStr ( dfDateTime, dfDateString, TRUE )

SalFmtFormatDateTime Syntax

strDateTime = SalFmtFormatDateTime ( dtDateTime, strPicture )

Description

Formats a date/time value using a given date/time picture format. If you do not specify a picture format or the one you specify is invalid, Centura uses the default settings in the [INTL] section and the user-defined [GTITOOLS] section of WIN.INI for formatting.

Parameters

dtDateTime

Date/Time. The date/time value to format.

strPicture

String. The date/time picture format.

Return Value

strDateTime is the formatted date/time string.

See Also

SalFmtFormatNumber SalFmtIsValidPicture

Example

Set dtDateTime = 1992-02-14-00.00.00 Set strFormatted = SalFmtFormatDateTime ( dtDateTime, strPicture )


2-65

Chapter

2


SalFmtFormatNumber Syntax

strNumber = SalFmtFormatNumber ( nNumber, strPicture )

Description

Formats a number value using a number picture format. If you do not specify a picture format or the one you specify is invalid, Centura uses the default settings in the [INTL] section and the user-defined [GTITOOLS] section of WIN.INI for formatting.

Parameters

nNumber

Number. The number value to format.

strPicture

String. The number picture format.

Return Value

strNumber is a formatted number string.

See Also

SalFmtFormatDateTime SalFmtIsValidPicture

Example

Set strNumber = SalFmtFormatNumber ( nNumber, strPicture )

SalFmtGetFormat Syntax

nFormat = SalFmtGetFormat ( hWndField )

Description

Returns the current format of a data field or table window column. Note: Some of the Parameters have subparameters. For example, the date format has both a subparameter that specifies a date’s separator character and a subparameter that specifies the month/day/year sequence.

Parameters

hWndField

Return Value

nFormat is a number that indicates the format of the field. The return value is one of the following constants.

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

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

SalFmtSetFormat

Example

Menu Settings Enabled when: Checked when: SalFmtGetFormat ( dfDateTime ) = FMT_Format_Unformatted

SalFmtGetInputMask Syntax

bOk = SalFmtGetInputMask ( hWnd, strMask )

Description

Gets the input mask of a data field or table window column. See the Formatting and Validating chapter in the Centura Technical Reference for more about input masks.

Parameters

hWnd

Window Handle. The handle (or name) of a combo box, data field, or table window column.

strMask

Receive String. The input mask retrieved.

Return Value

bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle or the object does not have an input mask.

See Also

SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask SalFmtUnmaskInput

Example

On SAM_Click Set bOk = SalFmtGetInputMask ( df1, df2 )


2-67

Chapter

2


SalFmtGetPicture Syntax

bOk = SalFmtGetPicture ( hWndField, strPicture )

Description Parameters

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

Receive String. The picture format.

Return Value

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

See Also

SalFmtSetPicture

Example

Set bOk = SalFmtGetPicture ( hWndField, strPicture )

SalFmtIsValidField Syntax

bValid = SalFmtIsValidField ( hWndField )

Description

Validates the contents of a data field or table window column using the current profile. 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

hWndField

Return Value

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

Example

On SAM_Validate

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

If SalFmtIsValidField ( dfDateTime ) Call SalFmtValidateField ( dfDateTime, FMT_Validate_None )

2-68



SalFmtIsValidInputMask Syntax

bOk = SalFmtIsValidInputMask ( strMask )

Description

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

strMask

Return Value

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

See Also

SalFmtGetInputMask SalFmtSetInputMask SalFmtKeepMask SalFmtUnmaskInput

Example

On SAM_Click

String. An input mask.

If SalFmtIsValidInputMask ( df1 ) Set df2 = 'Is Valid' Else Set df2 = 'Is Not Valid'

SalFmtIsValidPicture Syntax

bOk = SalFmtIsValidPicture ( strPicture, nType )

Description

Validates a number or date/time picture format. These are examples of date/time picture formats: Date/Time Picture

Displayed Value

d MMMM, yyyy

9 January, 1989

dddd, MMMM d, yyyy

Friday, February 7, 1989

M/d/yy

3/18/89

dd-MM-yyyy

18-03-1989

d "of " MMMM, yyyy

9 of January, 1989

M/d/yy-hh.mm.ss AMPM

2/3/91-12.23.15 AM


2-69

Chapter

2

These are examples of number picture formats: Number Picture

Parameters

Displayed Value

7.00%

0.00e+00

3.65e+03

0.00e-00

3.65e03

$#,##0;($#,##0)

$1,350

$#,##0;($#,##0)

($1,350)

0.00

95.00

strPicture

String. The picture string.

nType

Number. Specify whether the format is for a number or date/ time value with one of these constants: FMT_Pic_DateTime FMT_Pic_Number

Return Value

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

See Also

SalFmtGetPicture SalFmtSetPicture

Example

Set strPicture = 'M/d/yy' Set bValid = SalFmtIsValidPicture ( strPicture, FMT_Pic_DateTime )

SalFmtKeepMask Syntax

bRet = SalFmtKeepMask ( bKeep )

Description

By default, 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

bRet is the value you specified in bKeep.

See Also

SalFmtGetInputMask SalFmtIsValidInputMask SalFmtSetInputMask SalFmtUnmaskInput

Example

Set bRet = SalFmtKeepMask ( bKeep )

SalFmtSetFormat Syntax

bOk = SalFmtSetFormat ( hWndField, nFormat )

Description

Sets a data field's or table window column's format. A field's country profile determines a format's characteristics. If the field uses the default format, the profile in WIN.INI determines a format's characteristics. A field's format must agree with the field's data type, so for example, number fields can only be formatted as decimal, percentage, or currency values.

Parameters

hWndField

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

nFormat

Number. The format for hWndField.

Return Value

bOk is TRUE if the function succeeds and FALSE if the format cannot be set such as when the format is not appropriate for the specified field.

See Also

SalFmtGetFormat

Example

Set bOk = SalFmtSetFormat ( hWndField, nFormat )


2-71

Chapter

2

SalFmtSetInputMask Syntax

bOk = SalFmtSetInputMask ( hWnd, strMask )

Description

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

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

Return Value


See Also

SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtUnmaskInput

Example

Set bOk = SalFmtSetInputMask ( hWnd, strMask )

SalFmtSetPicture Syntax

bOk = SalFmtSetPicture ( hWndField, strPicture )

Description

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

Parameters

hWndField

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

strPicture

String. The picture format.

Return Value

bOk is TRUE if the function succeeds and FALSE if it fails. bOk is FALSE if any of the following are true: •

The window handle is not valid.

•

The field/column is not of date/time or number data type.

•

The picture format is not valid.

See Also

SalFmtGetPicture

Example

Set bOk = SalFmtSetPicture ( hWndField, strPicture )

2-72


SalFmtStrToField Syntax

bOk = SalFmtStrToField ( hWndField, strValue, bFormat )

Description

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

Parameters

hWndField

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

strValue

String. The string to copy.

bFormat

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

Return Value

bOk is TRUE if the string's value has the same format as the data field or table window column. bOk is FALSE if the string's value is unformatted.

See Also

SalFmtFieldToStr

Example

Message Actions On SAM_FieldEdit Call SalFmtStrToField ( dfDateTime, dfDateString, TRUE )

SalFmtUnmaskInput Syntax

bOk = SalFmtUnmaskInput ( hWnd, strInput )

Description

Unmasks the contents of a data field or table window column and puts the result in a string. Unmasking involves taking control characters out of a string, but does not include converting characters from lowercase to uppercase and vice versa. See the Formatting and Validating chapter in the Centura Technical Reference for more about input masks.

Parameters

hWnd


strInput

Receive String. The unmasked contents of hWnd.

Return Value

bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle or the object does not have an input mask.

See Also

SalFmtGetInputMask SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask


2-73

Chapter

2

Example

Set bOk = SalFmtUnmaskInput ( hWnd, strInput )

SalFmtValidateField Syntax

bOk = SalFmtValidateField ( hWndField, nValidate )

Description

Validates and formats a data field's or table window column's contents. 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

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

nValidate

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

Return Value

bOk is TRUE if the function succeeds and FALSE otherwise, such as when the input is invalid. If bOk is FALSE, Centura optionally displays an error dialog box.

Example

If SalFmtIsValidField ( dfDateTime ) Call SalFmtValidateField ( dfDateTime, FMT_Validate_None ) Return VALIDATE_Ok

SalFontGet Syntax

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

Description

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

Parameters

hWndFont

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

strName

Receive String. The name of the font.

nSize

Receive Number. The size of the font.

nEnhancment

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

Return Value


See Also

SalFontGetNames SalFontGetSizes SalFontSet

2-74


Example

If NOT SalFontGet ( hWndField, strFont, nSize, nEnhancement ) ... Error ...

SalFontGetNames Syntax

nNames = SalFontGetNames ( nGet, strArrayFontNames )

Description

Gets the names of the screen or printer fonts.

Parameters

nGet

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

strArrayFontNames

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

Return Value

nNames is the number of font names returned.

See Also

SalFontGet SalFontGetSizes SalFontSet

Example

Set nTotal = SalFontGetNames ( FONT_GetScreen, sFontNames )

SalFontGetSizes Syntax

nSizes = SalFontGetSizes ( nGet, strFontName, nArrayFontSizes )

Description

Gets the sizes of a screen or printer font.

Parameters

nGet

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

strFontName

String. The name of the font.

nArrayFontSizes

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

Return Value

nSizes is the number of font sizes returned.

See Also

SalFontGet SalFontGetNames SalFontSet

Example

Set nTotal = SalFontGetSizes ( FONT_GetScreen, sFont, nSizes )


2-75

Chapter

2

SalFontSet Syntax

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

Description

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

Parameters

hWnd

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

strName

String. The name of the font.

nSize

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

nEnhancment

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

Return Value


See Also

SalFontGet SalFontGetNames SalFontGetSizes

Example

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

SalFormGetParmNum Syntax

bOk = SalFormGetParmNum ( hWndForm, nParm, nValue )

Description

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

Parameters

hWndForm

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

nParm

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

nValue

Receive Number. The value of the form parameter requested.

Return Value


Example

On SAM_Create Call SalFormGetParmNum ( frmMain, FORM_nFormPages, dfPages )

2-76


SalFormUnitsToPixels Syntax

nNumPixels = SalFormUnitsToPixels ( hWnd, nFormUnits, bVertical )

Description

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.

Parameters

hWnd


nFormUnits

Number. The number of form units.

bVertical

Boolean. If the form units are on the X axis, set this parameter to FALSE. If the form units are on the Y axis, set this parameter to TRUE.

Return Value

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

See Also

SalPixelsToFormUnits

Example

Set nPixels = SalFormUnitsToPixels ( pbExample, nWidth, FALSE )

SalGetDataType Syntax

nDataType = SalGetDataType ( hWnd )

Description

Returns a data field's or table window column's data type. Use this function with internal functions that handle data fields and table window columns generically. Such internal functions pass only a window handle; the internal function does not know the data type of the associated window.

Parameters

hWnd

Return Value

nDataType is a number that indicates the data field's or table window column's data type. Its value is one of a predetermined set of constants (excluding DT_Boolean).

See Also

SalGetType

Example

Set nType = SalGetType ( hWndChild )

Window Handle. The handle (or name) of a data field or table window column.

If nType = TYPE_DataField Set nDataType = SalGetDataType ( hWndChild )


2-77

Chapter

2

SalGetDefButton Syntax

hWndDef = SalGetDefButton ( hWndParent )

Description

Returns the handle of the default push button on a form window or dialog box. The default push button is the one that has the focus by default.

Parameters

hWndParent

Return Value

hWndDef is the handle of the default push button. It equals if hWndParent is not the handle of a valid form window or dialog box, or if the window associated with hWndParent does not have a default push button.

See Also

SalSetDefButton

Example

Menu Actions

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

Set hWndDef = SalGetDefButton ( frmMain ) Call SalSetDefButton ( frmMain.pb2 ) Set hWndDef = SalGetDefButton ( frmMain )

SalGetFirstChild Syntax

hWndChild = SalGetFirstChild ( hWndParent, nTypeMask )

Description

Returns the handle of the first child window of the specified type. This function can be used to get MDI child windows.

Parameters

hWndParent

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

nTypeMask

Number. One or more window types combined (using the OR (|) operator) to create a mask of child window types. Centura only examines those child windows whose type AND'd with nTypeMask yields a non-zero value.

Return Value

hWndChild is the handle of the first child window of the specified type. hWndChild equals hWndNULL if there is no child window or if hWndParent is invalid.

See Also

SalGetNextChild SalGetType

Example

Set hWndChild = SalGetFirstChild ( hWndCurrentFW, nTypeMask )

2-78


SalGetFocus Syntax

hWndFocus = SalGetFocus ( )

Description

Returns the handle of the window with the focus.

Parameters

No parameters.

Return Value

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

See Also

SalSetFocus

Example

Set hWndSave = SalGetFocus ( )

SalGetItemName Syntax

bOk = SalGetItemName ( hWnd, strText )

Description

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

Parameters

hWnd

Window Handle. The handle of an object.

strText

Receive String. The name of the object.

Return Value


Example

Call SalGetItemName ( hWndCurrent, strItemName ) Return strItemName

SalGetMaxDataLength Syntax

nDataLength = SalGetMaxDataLength ( hWndObject )

Description

Returns the maximum length of a data field, multiline text field, or table window column. Use this function before assigning a value to any of these objects to ensure that the value fits.

Parameters

hWndObject

Return Value

nDataLength is a number that specifies the maximum length of hWndObject. A length of DW_Default (-1) indicates that the object was declared with a length of ‘Default’.

See Also

SalSetMaxDataLength

Example

Set nDataLen = SalGetMaxDataLength ( hWnddfCurrent )

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


2-79

Chapter

2

SalGetNextChild Syntax

hWndNextChild = SalGetNextChild ( hWndChild, nTypeMask )

Description

Returns the handle of the next child window that matches a specified type. Use this function after calling SalGetFirstChild to get the other child window siblings. If you want this function to work for background text, lines, and frames, set the system variable bStaticsAsWindows to TRUE. This is a global system variable, so the setting persists until you change it.

Parameters

hWndChild

Window Handle. The handle (or name) of a child window. You can specify the return value of SalGetFirstChild.

nTypeMask

Number. One or more window types combined (using the OR (|) operator) to create a mask of child window types. 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.

See Also

SalGetFirstChild SalGetType

Example

Set hWndChild = SalGetNextChild ( hWndChild, nTypeMask )

SalGetProfileInt Syntax

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

Description

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

Parameters

strSection

String. The section heading.

strEntry

String. The entry whose associated value is being retrieved.

nDefault

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

strFileName

String. The name of the initialization file or company name depending on the settings made using the SalUseRegistry function. If you are searching for an INI file and do not specify the full path, 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.

See Also

SalGetProfileString SalSetProfileString SalUseRegistry

Example

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

SalGetProfileString Syntax

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

Description

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

Parameters

strSection


strEntry

String. The entry whose associated value is being retrieved.

strDefault

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

strValue

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

strFileName


Return Value

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

See Also

SalGetProfileInt SalSetProfileString SalUseRegistry

Example

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


2-81

Chapter

2

SalGetType Syntax

nType = SalGetType ( hWnd )

Description

Returns an object's type. Use SalGetType with internal functions that process objects generically. Such internal functions pass only a window handle; the internal function does not know the type of the associated object.

Parameters

hWnd

Return Value

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

See Also

SalGetFirstChild SalGetNextChild

Example

Set nType = SalGetType ( hWndChild )

Window Handle. The handle of an object.

If nType = TYPE_DataField Set nDataType = SalGetDataType ( hWndChild ) If nDataType = nHideDataType Call SalHideWindow ( hWndChild )

SalGetVersion Syntax

nType = SalGetVersion ( )

Description

Returns the Centura version. For example, SalGetVersion returns 400 for Centura v4.0.0.

Parameters

No parameters.

Return Value

nType is a number that indicates the Centura version number.

Example

Message Actions On SAM_Create Set df1 = SalGetVersion ( )

2-82


SalGetWindowLabelText Syntax

nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )

Description

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

Parameters

hWnd


strText

Receive String. The window text.

nMaxLen

Number. The maximum length of the window text.

Return Value

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

Example

Set nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )

SalGetWindowLoc Syntax

bOk = SalGetWindowLoc ( hWnd, nX, nY )

Description

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

Parameters

hWnd


nX

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

nY

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

Return Value


See Also

SalSetWindowLoc

Example

Call SalSetWindowLoc ( pbExample, 0, 0 ) Call SalGetWindowLoc ( pbExample, nX, nY )


2-83

Chapter

2

SalGetWindowSize Syntax

bOk = SalGetWindowSize ( hWnd, nWidth, nHeight )

Description

Returns a window's size.

Parameters

hWnd


nWidth

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

nHeight

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

Return Value


See Also

SalSetWindowSize

Example

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

SalGetWindowState Syntax

nState = SalGetWindowState ( hWnd )

Description

Returns a window's current state.

Parameters

hWnd

Return Value

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

Example

On SAM_Click

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

If SalGetWindowState ( fwDataWindow ) != Window_Normal

SalGetWindowText Syntax

nLength = SalGetWindowText ( hWnd, strText, nMaxLen )

Description

Retrieves the text of a window. Window text is the title of a form window, dialog box, table window, radio button, check box, background text, or push button. For a data field, multiline text field, or table window column, window text is the field value in string form, regardless of the object's data type.

2-84


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

hWnd


strText

Receive String. The window text.

nMaxLen


Return Value

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

See Also

SalSetWindowText SalTblGetColumnTitle

Example

Call SalGetWindowText ( hWndForm, strfrmTitle, 50 )

SalHideWindow Syntax

bOk = SalHideWindow ( hWndToHide )

Description

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

Parameters

hWndToHide

Return Value


See Also

SalBringWindowToTop SalShowWindow

Example

Call SalHideWindow ( hWndChild )

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

SalHideWindowAndLabel Syntax

bOk = SalHideWindowAndLabel ( hWndToHide )

Description

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

hWndToHide

Return Value

bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible.

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


2-85

Chapter

2

See Also

SalBringWindowToTop SalHideWindow SalShowWindowAndLabel

Example

Set bOk = SalHideWindowAndLabel ( hWndToHide )

SalHStringToNumber Syntax

nHString = SalHStringToNumber ( strString )

Description

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.

Parameters

strString

Return Value

nHString is a number that represents the converted string handle.

See Also

SalNumberToHString

Example

Set nHString = SalHStringToNumber ( strString )

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

SalInvalidateWindow Syntax

bOk = SalInvalidateWindow ( hWndToPaint )

Description


Parameters

hWndToPaint

Return Value


See Also

SalUpdateWindow

Example

Set bOk = SalInvalidateWindow ( hWndToPaint )

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

SalIsButtonChecked Syntax

bIsSet = SalIsButtonChecked ( hWnd )

Description


Parameters

hWnd

Return Value

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

2-86


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

Example

Set bIsSet = SalIsButtonChecked ( hWnd )

SalIsNull Syntax

bNull = SalIsNull ( hWndIsNull )

Description

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

Parameters

hWndIsNull

Return Value

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

See Also

SalClearField

Example

On SAM_Validate

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

If SalIsNull ( dfDateTime ) Call SalMessageBox ( 'You must enter a value', 'Validate Error', MB_Ok ) Return VALIDATE_Cancel

SalIsValidDateTime Syntax

bOk = SalIsValidDateTime ( hWndField )

Description

Verifies whether a data field, multiline text field, or table window column contains a valid date/time value. For multiline text fields, the date/time value must be the only item in the field.

Parameters

hWndField

Return Value

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

Example

On SAM_Validate


If NOT SalIsValidDateTime ( dfDateTime )

SalIsValidDecimal Syntax

bOk = SalIsValidDecimal ( hWndField, nPrecision, nScale )

Description

Verifies whether a data field, multiline text field, or table window column contains a valid decimal value. For multiline text fields, the decimal value must be the only item in the field.


2-87

Chapter

2

Parameters

hWndField


nPrecision

Number. The number of digits to display.

nScale

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

Return Value

bOk is TRUE if hWndField contains a number of the specified precision and scale, and FALSE if hWndField's value does not match the parameter specifications.

See Also

SalIsValidInteger SalIsValidNumber

Example

On SAM_Validate If NOT SalIsValidDecimal ( dfDecimal, 5, 2 ) Call SalMessageBox ( 'Invalid decimal value', 'Validate

SalIsValidInteger Syntax

bOk = SalIsValidInteger ( hWndField )

Description

Verifies whether a data field, multiline text field, or table window column contains a valid integer value. For multiline text fields, the integer value must be the only item in the field.

Parameters

hWndField

Return Value

bOk is TRUE if hWndField contains a valid integer value and FALSE if the number is a fraction, decimal, or any other invalid integer value.

See Also

SalIsValidDecimal SalIsValidNumber

Example

On SAM_Validate


If NOT SalIsValidInteger ( dfInteger) Call SalMessageBox ( 'Invalid integer value', 'Validate Error', MB_Ok ) Return VALIDATE_Cancel

2-88


SalIsValidNumber Syntax

bOk = SalIsValidNumber ( hWndField )

Description

Verifies whether a data field, multiline text field, or table window column contains a valid numeric value. Valid numbers are integers or floating point numbers, negative and positive. For multiline text fields, the numeric value must be the only item in the field.

Parameters

hWndField

Return Value

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

See Also

SalIsValidDecimal SalIsValidInteger

Example

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

bEnabled = SalIsWindowEnabled ( hWndEnabled )

Description

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

Parameters

hWndEnabled

Return Value

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

See Also

SalDisableWindow SalEnableWindow

Example

If SalIsWindowEnabled ( pbUpdate )


Call SalDisableWindow ( pbUpdate )

SalIsWindowVisible Syntax

bOk = SalIsWindowVisible ( hWndVisible )

Description

Determines whether a window is currently visible.

Parameters

hWndVisible

Window Handle. The handle (or name) of a window. Create a window first before using a window template as a parameter. Centura Builder Function Reference

2-89

Chapter

2

Return Value

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

See Also

SalHideWindow SalShowWindow

Example

Set bOk = SalIsWindowVisible ( hWndVisible )

SalListAdd Syntax

nIndex = SalListAdd ( hWndList, strName )

Description

Adds a string to a list box or combo box. If the list box is sorted (the default), 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

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

strName

String. The string to add.

Return Value

nIndex is the index of the new list box entry. SalListAdd returns LB_Err on an error and LB_ErrSpace if there is insufficient memory to store the new string.

See Also

SalListInsert SalListPopulate

Example

Call SalListAdd ( hWndlbCurrent, strLBItem )

SalListClear Syntax

bOk = SalListClear ( hWndList )

Description

Deletes all entries from a list box or combo box.

Parameters

hWndList

Return Value


Example

Call SalListClear ( lbProducts )

2-90



SalListDelete Syntax

nRemaining = SalListDelete ( hWndList, nIndex )

Description

Deletes a list box or combo box entry.

Parameters

hWndList


nIndex

Number. The index of the entry to delete.

Return Value

nRemaining is the number of rows remaining in the list box or combo box if the function succeeds. SalListDelete returns LB_Err if an error occurs.

Example

Set nCount = SalListDelete ( hWndlbCurrent, nLBIdx )

SalListFiles Syntax

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

Description

Populates a list box or combo box with a directory of files. You can create the same kinds of dialog boxes as those displayed by items of the Windows File menu.

Parameters

hWndList


hWndPath

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

strPathName

Receive String. The path name of the directory whose files are listed. You must specify a field name or variable; you cannot specify a string constant as a receive parameter.

nFlags

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

Return Value


See Also

SalFileOpen

Example

Call SalListFiles ( hWndLB, hWndLoadPath, strLoadPath, nFileAttrib )


2-91

Chapter

2

SalListGetMultiSelect Syntax

bOk = SalListGetMultiSelect ( hWndList, nSelectedArray )

Description

Returns an array of index numbers of selected list box entries. Use the SalListQueryMultiCount function to return the number of selected list box entries.

Parameters

hWndList

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

nSelectedArray

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

Return Value

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

Example

Call SalListGetMultiSelect ( lbExample, nSelectedArray )

SalListInsert Syntax

nIndex = SalListInsert ( hWndList, nIndex, strAdd )

Description

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

Parameters

hWndList


nIndex

Number. The position at which to insert the row. A value of -1 adds the entry to the end of the list box or combo box.

strAdd

String. The string to insert.

Return Value

nIndex is the index of the new entry. SalListInsert returns LB_Err on an error and LB_ErrSpace if there is insufficient memory to store the new string.

See Also

SalListAdd

Example

Call SalListInsert ( hWndLB, -1, strInsertStr )

SalListPopulate Syntax

bOk = SalListPopulate ( hWndList, hSql, strSelect )

Description

Populates a list box or combo box with a result set. SalListPopulate overrides any settings made with SalListSetTabs. If the SELECT statement returns data from multiple columns, each column's data displayed in a list box is separated by tabs. However, due to a Microsoft Windows limitation, each column's data displayed in a combo box is separated by a single '|'

2-92


character. There is no space between one column's data, the separator character, and another column's data. Parameters

hWndList

Window Handle. The handle (or name) of the list box or combo box to populate.

hSql

Sql Handle. The handle of a SELECT statement.

strSelect

String. The SELECT statement. The SELECT statement can contain bind variables, but it cannot contain INTO variables. If strSelect is null (''), Centura uses the previously prepared SELECT statement associated with hSql. This avoids repreparing each time SalListPopulate executes.

Return Value

bOk is TRUE if the function succeeds and FALSE if any of the parameters are invalid or if strSelect contains INTO variables.

See Also

SalListAdd SalListInsert

Example

On SAM_Click Call SalListPopulate ( lbExample, hSql, 'select name, trainer, room ' || 'from guest_roster' )

SalListQueryCount Syntax

nEntries = SalListQueryCount ( hWndList )

Description

Returns the number of list box or combo box entries.

Parameters

hWndList

Return Value

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

Example

If NOT SalListQueryCount ( hWndlbCurrent )


Return FALSE


2-93

Chapter

2

SalListQueryFile Syntax

bDirectory = SalListQueryFile ( hWndList, strFileName )

Description

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

Parameters

hWndList


strFileName

Receive String. The directory or file name being fetched.

Return Value

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

Example

Call SalListQueryFile ( hWndLB, strFileName )

SalListQueryMultiCount Syntax

nSelected = SalListQueryMultiCount ( hWndList )

Description

Returns the number of selected entries in a multiple-selection list box. Specify single- or multiple-selection in the list box's customizer.

Parameters

hWndList

Return Value

nSelected is the number of selected entries in hWndList if the function succeeds. nSelected equals LB_Err if hWndList is a single-selection list box or is not a valid handle.

Example

Set nSelected = SalListQueryMultiCount ( lbExample )

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

SalListQuerySelection Syntax

nIndex = SalListQuerySelection ( hWndList )

Description

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

2-94

hWndList


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

Return Value

nIndex is the index of the selected entry if the function succeeds. SalListQuerySelection returns LB_Err if no entry is selected or if the list box is a multiple-selection box.

See Also

SalListGetMultiSelect SalListQueryState

Example

Set nLBIdx = SalListQuerySelection (hWndlbCurrent )

SalListQueryState Syntax

bSelected = SalListQueryState ( hWndList, nIndex )

Description

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

Parameters

hWndList


nIndex

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

Return Value

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

Example

If SalListQueryState ( hWndlbCurrent, nLBIdx ) Set nCount = SalListDelete (hWndlbCurrent, nLBIdx) Else Set nLBIdx = nLBIdx + 1

SalListQueryText or SalListQueryTextX Syntax

nLength = SalListQueryText ( hWndList, nIndex, strText ) or strText = SalListQueryTextX ( hWndList, nIndex )

Description


Parameters

hWndList


nIndex


Return Value

strText is the fetched list box or combo box entry.

Example

Set strRecv = SalListQueryTextx ( hWnddbCurrent, nLBIdx )


2-95

Chapter

2

SalListQueryTextLength Syntax

nLength = SalListQueryTextLength ( hWndList, nIndex )

Description

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

Parameters

hWndList


nIndex


Return Value

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

Example

Set nLBItemLen = SalListQueryTextLength (hWndlbCurrent, nLBIdx)

SalListQueryTextX Syntax

strText = SalListQueryTextX ( hWndList, nIndex )

Description


Parameters

hWndList


nIndex


strText

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

Return Value

nLength is the length of strText. SalListQueryText returns LB_Err if nIndex is invalid. strText is the fetched list box or combo box entry.

Example

Set strText = SalListQueryTextX ( hwndLst, 2 )

SalListRedraw Syntax

bOk = SalListRedraw ( hWndList, bRedraw )

Description

Redraws entries in a list box or combo box, or prevents them from being redrawn. For example, use SalListRedraw when populating a list box or combo box to prevent the contents from being redrawn after adding each entry. When 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


Return Value

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

Example

On SAM_Click Call SalListRedraw ( lbList, FALSE )

SalListSelectString Syntax

nIndex = SalListSelectString ( hWndList, nIndexStart, strText )

Description

Finds and selects a combo box or single-selection list box entry. Specify single-selection in the list box's 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

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

strText

String. The string to search for.

Return Value

nIndex is the index of the selected string. SalListSelectString returns LB_Err if an error occurs or if hWndList is a multiple-selection list box.

Example

Set nIdx = SalListSelectString ( hWndLB, 0, strFindStr ) If nIdx = LB_Err Call SalListInsert ( hWndLB, -1, strInsertStr ) Else Call SalListInsert ( hWndLB, nIdx + 1, strInsertStr )

SalListSetMultiSelect Syntax

bOk = SalListSetMultiSelect ( hWndList, nIndex, bSelect )

Description

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

2

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.

bSelect

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

Return Value


Example

Call SalListSetMultiSelect ( lbExample, 5, TRUE )

SalListSetSelect Syntax

bOk = SalListSetSelect ( hWndList, nIndex )

Description

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

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

Return Value

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

Example

Call SalListSetSelect ( hWndLB, 0 )

SalListSetTabs Syntax

bOk = SalListSetTabs ( hWndList, nArrayTabStops )

Description

Sets tabs in a list box. List boxes use tabs to align columns of data. You need to set tabs when you are using a proportional font. SalListPopulate overrides any settings made with SalListSetTabs.

Parameters

hWndList

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

nArrayTabStops

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

Return Value


Example

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

bOk = SalLoadApp ( strAppName, strParameters )

Description

Starts an application.

Parameters

strAppName

String. The name of the application to start.

strParameters

String. Optional command line arguments.

See the SAL (Centura Application Language) chapter of the Centura Developer's Reference for detailed information about command line arguments. Return Value

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

See Also

SalLoadAppAndWait

Example

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

SalLoadAppAndWait Syntax

bOk = SalLoadAppAndWait ( strAppName, nMode, nRet )

Description

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

Parameters

strAppName

String. The name of the application to start, separated from command line arguments with a space. See the SAL chapter in the Centura Developer’s 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

2

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

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

Return Value

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

See Also

SalLoadApp

Example

On SAM_AppStartup Call SalLoadAppAndWait (‘DBWindow.EXE’, WINDOW_NORMAL, NRECUSTATUS)

2-100 Centura Builder Function Reference

SalMapEnterToTab Syntax

bOk = SalMapEnterToTab ( bState )

Description

This function changes the behavior of the Enter key from executing the default button on a window to moving the focus to the next field. This function takes one parameter (TRUE or FALSE) to enable or disable this action.

Parameters

bState

Boolean. If TRUE, the Enter key shifts the focus to the next editable object. If FALSE (default), the Enter key executes the default push button on the form window or dialog box.

Return Value

bOk is TRUE if the function succeeds and FALSE if you do not specify a Boolean value.

Example

Set bOk = SalMapEnterToTab ( bState )

SalMDIArrangeIcons Syntax

bOk = SalMDIArrangeIcons ( hWndMDI )

Description

Arranges minimized child window icons in an MDI window.

Parameters

hWndMDI

Return Value


See Also

SalMDICascade SalMDITile

Example

Menu Actions

Window Handle. The handle of an MDI window.

Call SalMDIArrangeIcons ( hWndMDI )

SalMDICascade Syntax

bOk = SalMDICascade ( hWndMDI )

Description

Cascades all non-iconized child windows of an MDI window.

Parameters

hWndMDI

Return Value


See Also

SalMDIArrangeIcons SalMDITile



2-101

Chapter

2

Example

Menu Actions Call SalMDICascade ( hWndMDI )

SalMDITile Syntax

bOk = SalMDITile ( hWndMDI, bPosition )

Description

Tiles all non-iconized child windows of an MDI window. Windows that are not sizable will not be tiled.

Parameters

hWndMDI


bPosition

Boolean. How to tile the child windows. If TRUE, tile the windows vertically; if FALSE, tile the windows horizontally.

Return Value


See Also

SalMDIArrangeIcons SalMDICascade

Example

Menu Actions Call SalMDITile ( hWndMDI, FALSE )

SalMessageBeep Syntax

bOk = SalMessageBeep ( nAlertLevel )

Description

Plays a waveform sound that corresponds to a given system alert level defined in the [sounds] section of WIN.INI. A user can set the sound for each alert level with the sounds application in the Control Panel.

Parameters

nAlertLevel

Number. The alert level: 0xFFFFFFFF (-1)Standard beep using the computer speaker. MB_IconAsterisk MB_IconExclamation MB_IconStop MB_IconQuestion MB_Ok

Return Value


See Also

SalMessageBox

Example

Call SalMessageBeep ( -1 )


SalMessageBox Syntax

nResult = SalMessageBox ( strText, strTitle, nFlags )

Description

Displays a message box and returns a number that indicates the user's response. You can customize the message box push buttons and icons. The active parent window, whose value is hWndForm, creates the message box.

Parameters

strText

String. The message text. You can enter multiple lines of text by pressing CTRL-ENTER to start a new line.

strTitle

String. The message box title.

nFlags

Number. The message box style. Create a style by combining style option constants using the OR (|) operator. You can combine at most one constant from each component. 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

2

MB_DefButton2 MB_DefButton3 MB_NoFocus System Style Constants MB_ApplModal (default) MB_SystemModal Return Value

nResult is the value of the push button the user clicks.

See Also

SalMessageBeep

Example

Set nResult = SalMessageBox ( strText, strTitle, nFlags )


SalModalDialog Syntax

nReturn = SalModalDialog ( tDlgBoxToCreate, hWndOwner, Parm1, Parm2, ...)

Description

Creates a modal dialog box. 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

Window Handle. The handle (or name) of the owner window. Use hWndNULL for a dialog box that does not have an owner.

Parm1


Parm2


Return Value

nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created.

See Also

SalEndDialog SalModalDialogFromStr

Example

Call SalModalDialog ( dlgAboutBox, hWndForm )


2-105

Chapter

2

SalModalDialogFromStr Syntax

nReturn = SalModalDialogFromStr ( tDlgBoxToCreate, hWndOwner, Parm1, Parm2, ... )

Description

Creates a modal dialog box. This function is useful with internal functions that expect to receive a dialog box name in a string parameter. A modal dialog box disables its owner window. A system modal dialog box disables the entire Windows system. SalEndDialog destroys a modal dialog box and enables all windows that were disabled.

Parameters

strName

String. The name of the modal dialog box to create.

hWndOwner

Window Handle. The handle (or name) of the owner window. Use hWndNUL for dialog boxes that do not have owners.

Parm1


Parm2


Return Value

nReturn is the value specified in the second parameter of SalEndDialog (hWndOwner). nReturn is equal to -1 if the dialog box is not created.

See Also

SalModalDialog

Example

Set nReturn = SalModalDialogFromStr ( tDlgBoxToCreate, hWndOwner )

SalMoveWindow Syntax

bOk = SalMoveWindow ( hWndToMove, nXOffset, nYOffset )

Description


Parameters

hWndToMove

Window Handle. The handle (or name) of the window to move.

nXOffset

Number. The number of form units to move the window on the X axis.

nYOffset

Number. The number of form units to move the window on the Y axis.

Return Value

bOk is TRUE if the function succeeds, and FALSE if hWndToMove is invalid.

See Also

SalCenterWindow

Example

Call SalMoveWindow ( pbExample, 1,1 )



SalNumberAbs Syntax

nNum = SalNumberAbs ( nValue )

Description

Computes a number's absolute value.

Parameters

nValue

Return Value

nNum is the absolute value of nValue.

Example

On SAM_Click

Number. The number whose absolute value you want.

Set nNum1 = SalNumberAbs ( -12 )

SalNumberArcCos Syntax

nArcCos = SalNumberArcCos ( nValue )

Description

Computes the arccosine of a value in the range 0 to 1. The value's domain is -1 to 1.

Parameters

nValue

Return Value

nArcCos is the arccosine of nValue. It is zero (0) if nValue is less than -1 or greater than 1.

Example

On SAM_Click

Number. The number whose arccosine you want.

Set nNum1 = SalNumberArcCos ( 1 )

SalNumberArcSin Syntax

nArcSin = SalNumberArcSin ( nValue )

Description

Computes a value's arcsine. The value's domain is -1 to 1.

Parameters

nValue

Return Value

nArcSin is the arcsine of nValue. nArcSin is zero (0) if nValue is less than -1 or greater than 1.

Example

On SAM_Click

Number. The number whose arcsine you want.

Set nNum1 = SalNumberArcSin ( 1 )


2-107

Chapter

2

SalNumberArcTan Syntax

nArcTan = SalNumberArcTan ( nValue )

Description

Computes a value's arctangent.

Parameters

nValue

Return Value

nArcTan is the arctangent of nValue. nArcTan is in the range -1 to 1.

See Also

SalNumberArcTan2

Example

On SAM_Click

Number. The number whose arctangent you want.

Set nNum1 = SalNumberArcTan ( 1 )

SalNumberArcTan2 Syntax

nArcTan2 = SalNumberArcTan2 ( nValueY, nValueX )

Description

Computes the arctangent of two values. This function uses the signs of both parameters to determine the quadrant of the return value.

Parameters

nValueY

Number. One of two values whose arctangent you want.

nValueX

Number. The other of two values whose arctangent you want.

Return Value

nArcTan2 is the arctangent of nValueY and nValueX. nArcTan2 is in the range -1/2 to 1/2.

See Also

SalNumberArcTan

Example

On SAM_Click Set nNum1 = SalNumberArcTan2 ( 1, 0 )

SalNumberCos Syntax

nCos = SalNumberCos ( nAngle )

Description

Computes an angle's cosine. You must specify the angle in terms of radians.

Parameters

nAngle

Return Value

nCos is the cosine of nAngle. If the angle is large, nCos can reflect a partial loss of significance. If the angle is so large that significance is totally lost, SalNumberCos returns zero (0).

See Also

SalNumberCosH

Example

On SAM_Click

Number. The value of the angle whose cosine you want.

Set nNum1 = SalNumberCos ( 0 )


SalNumberCosH Syntax

nCosH = SalNumberCosH ( nAngle )

Description

Computes an angle's hyperbolic cosine. You must specify the angle in terms of radians.

Parameters

nAngle

Return Value

nCosH is the hyperbolic cosine of nAngle. If the return value is too large, nCosH equals zero (0).

See Also

SalNumberCos

Example

On SAM_Click

Number. The value of the angle whose hyperbolic cosine you want.

Set nNum1 = SalNumberCosH ( 0 )

SalNumberExponent Syntax

nNumExp = SalNumberExponent ( nValue )

Description

Computes a value's exponential function.

Parameters

nValue

Return Value

nNumExp is the result of 'e' to the power of nValue. When there is an underflow or overflow, nNumExp is equal to zero (0).

Example

On SAM_Click

Number. The value whose exponential function you want.

Set nNumExp = SalNumberExponent ( 2.302585093 )

SalNumberHigh Syntax

nHi = SalNumberHigh ( nValue )

Description

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

Parameters

nValue

Return Value

nHi is the high-order word value of nValue.

See Also

SalNumberLow

Example

On SAM_Click

Number. The number whose high-order word value you want. Centura treats nValue as an unsigned 32-bit number.

Set nHi = SalNumberHigh ( 0xffffaaaa )


2-109

Chapter

2

SalNumberHypot Syntax

nHypotenuse = SalNumberHypot ( nX, nY )

Description

Computes the length of the hypotenuse of a right triangle, given the lengths of the other two sides.

Parameters

nX

Number. The length of one side of a right triangle.

nY

Number. The length of another side of a right triangle.

Return Value

nHypotenuse is the length of the hypotenuse of a right triangle. If the computation of the hypotenuse results in an overflow, nHypotenuse is equal to zero (0).

Example

On SAM_Click Set nHypotenuse = SalNumberHypot ( 3, 4 )

SalNumberLog Syntax

nLog = SalNumberLog ( nValue )

Description

Computes a number's natural logarithm.

Parameters

nValue

Return Value

nLog is the natural logarithm of nValue. If nValue is negative or 0, nLog is equal to zero (0).

See Also

SalNumberLogBase10

Example

On SAM_Click

Number. The number whose natural logarithm you want.

Set nLog = SalNumberLog ( 1000 )

SalNumberLogBase10 Syntax

nLogBase10 = SalNumberLogBase10 ( nValue )

Description

Computes a number's base -10 logarithm.

Parameters

nValue

Return Value

nLogBase10 is the base-10 logarithm of nValue. If nValue is negative or 0, nLogBase10 is equal to zero (0).

See Also

SalNumberLog

Example

On SAM_Click

Number. The number whose base -10 logarithm you want.

Set nLogBase10 = SalNumberLogBase10 ( 1000 )


SalNumberLow Syntax

nLo = SalNumberLow ( nValue )

Description

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

Parameters

nValue

Return Value

nLo is the low-order word value of nValue.

See Also

SalNumberHigh

Example

On SAM_Click

Number. The number whose low-order word value you want. Centura treats nValue as an unsigned 32-bit number.

Set nLo = SalNumberLow ( 0xffffaaaa )

SalNumberMax Syntax

nNumMax = SalNumberMax ( nVal1, nVal2 )

Description

Returns the greater of two values.

Parameters

nVal1

Number. The first of two values.

nVal2

Number. The second of two values.

Return Value

nNumMax is the greater of nVal1 and nVal2.

See Also

SalNumberMin

Example

On SAM_Click Set nNumMax = SalNumberMax ( 1765.2, -2 )

SalNumberMin Syntax

nNumMin = SalNumberMin ( nVal1, nVal2 )

Description

Returns the lesser of two values.

Parameters

nVal1

Number. The first value.

nVal2

Number. The second value.

Return Value

nNumMin is the lesser of nVal1 and nVal2.

See Also

SalNumberMax

Example

On SAM_Click Set nNumMin = SalNumberMin ( 1765.2, -2 )


2-111

Chapter

2

SalNumberMod Syntax

nModulo = SalNumberMod ( nNumber, nNumberMod )

Description

Returns a number's modulo. This function divides nNumber by nNumberMod and returns the remainder.

Parameter nNumber

Number. The number to divide.

nNumberMod

Number. The number by which to divide nNumber.

Return Value

nModulo is the remainder of nNumber divided by nNumberMod.

Example

On SAM_Click Set nNumber = SalNumberMod ( 5, 2 )

SalNumberPi Syntax

nNumPi = SalNumberPi ( nValue )

Description

Multiples a number by Pi. Pi is equal to 3.1415926535979323.

Parameters

nValue

Return Value

nNumPi is nValue multiplied by Pi.

Example

On SAM_Click

Number. The number to multiply by Pi.

Set nNumPi = SalNumberSin ( SalNumberPi ( 1 ) /2 )

SalNumberPower Syntax

nNumPower = SalNumberPower ( nX, nY )

Description

Computes nX raised to the power of nY. This function does not recognize integral, floating-point values greater than 2 to the 64th power, such as 1.0E100.

Parameters

nX

Number. The number to raise to the power of nY.

nY

Number. The exponent.

Return Value

nNumPower is equal to nX raised to the nYth power, with the following conditions: 1.

If nX is not 0 and nY is 0, nNumPower is equal to 1.

2.

If nX is 0 and nY is negative, nNumPower is equal to zero (0).

3.

If both nX and nY are zero (0), or if nX is negative and nY is not a whole number, nNumPower is equal to zero (0), meaning that an error occurred.


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

bOk = SalNumberRandInit ( nSeed )

Description

Sets the starting point for generating a series of pseudo-random numbers using SalNumberRandom. Use SalNumberRandInit when you want to generate the same set of pseudo-random numbers over and over again, for example, when doing reproducible experiments. Call SalNumberRandInit followed by numerous calls to SalNumberRandom. To repeat the random number series, call SalNumberRandInit again, specify the same seed value, and follow with numerous calls to SalNumberRandom.

Parameters

nSeed

Return Value


See Also

SalNumberRandom

Example

On SAM_Click

Number. The starting point. A whole number in the range of 0 to 32767.

Call SalNumberRandInit ( 12 )

SalNumberRandom Syntax

nRandomNum = SalNumberRandom ( )

Description

Generates a pseudo-random number. The numbers generated by this function are integers (whole numbers) in the range 0 to 32767 (0 to 0x7FFF).

Parameters

No parameters.

Return Value

nRandomNum is a pseudo-random number.

See Also

SalNumberRandInit

Example

On SAM_Click Call SalNumberRandInit ( 12 ) Set nRandNum = SalNumberRandom ( )


2-113

Chapter

2

SalNumberRound Syntax

nResult = SalNumberRound ( nNumber )

Description

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

nNumber

Return Value

nResult is nNumber after rounding.

Example

On SAM_Click

Number. The number to round.

Set nNumber = SalNumberRound ( 124.5 )

SalNumberSin Syntax

nSin = SalNumberSin ( nAngle )

Description

Computes an angle's sine. You must specify the angle in terms of radians.

Parameters

nAngle

Return Value

nSin is the sine of nAngle. If the angle is large, nSin can reflect a partial loss of significance. If the angle is so large that significance is totally lost, nSin is equal to zero (0).

See Also

SalNumberSinH

Example

On SAM_Click

Number. The value of the angle whose sine you want.

Set nNum = SalNumberSin ( SalNumberPi ( 1 ) /2 )

SalNumberSinH Syntax

nSinH = SalNumberSinH ( nAngle )

Description

Computes an angle's hyperbolic sine. You must specify the angle in terms of radians.

Parameters

nAngle

Return Value

nSinH is the hyperbolic sine of nAngle. If the angle is too large, nSinH is equal to zero (0).

See Also

SalNumberSin

Example

On SAM_Click


Number. The value of the angle whose hyperbolic sine you want.

Set nNum = SalNumberSinH ( 0 )

SalNumberSqrt Syntax

nSqrt = SalNumberSqrt ( nValue )

Description

Computes a number's square root.

Parameters

nValue

Return Value

nSqrt is the square root of nValue. If nValue is negative, it is out of the domain of valid values and nSqrt is equal to zero (0).

Example

On SAM_Click

Number. The number whose square root you want.

Set nSqrt = SalNumberSqrt ( 36 )

SalNumberTan Syntax

nTan = SalNumberTan ( nAngle )

Description

Computes an angle's tangent. You must specify the angle in terms of radians.

Parameters

nAngle

Return Value

nTan is the tangent of nAngle. If the angle is large, nTan can reflect a partial loss of significance. If the angle is so large that significance is totally lost, nTan is equal to zero (0).

See Also

SalNumberTanH

Example

On SAM_Click

Number. The value of the angle whose tangent you want.

Set nNum = SalNumberTan ( SalNumberPi ( 1 ) / 4 ) )

SalNumberTanH Syntax

nTanH = SalNumberTanH ( nAngle )

Description

Computes an angle's hyperbolic tangent. You must specify the angle in terms of radians.

Parameters

nAngle

Return Value

nTanH is the hyperbolic tangent of nAngle. If the angle is large, nTanH can reflect a partial loss of significance. If the angle is so large that significance is totally lost, nTanH is equal to zero (0).

See Also

SalNumberTan

Number. The value of the angle whose hyperbolic tangent you want.


2-115

Chapter

2

Example

On SAM_Click Set nNum = SalNumberTanH ( 0 )

SalNumberToChar Syntax

strChar = SalNumberToChar ( nNumber )

Description

Converts a decimal value to an ASCII character.

Parameters

nNumber

Return Value

strChar is the character converted from nNumber.

See Also

SalStrFirstC

Example

On SAM_Click

Number. The number to convert.

Set df2 = SalNumberToChar ( df1 )

SalNumberToHString Syntax

strString = SalNumberToHString ( nHString )

Description

Converts a number to a string handle.

Parameters

nHString

Return Value

strString is a string handle that represents the number converted.

See Also

SalHStringToNumber

Example

On SAM_Click

Number. The numeric value of the string handle to convert.

Set strString = SalNumberToHString ( lParam ) Set nBuffLen = SalStrGetBufferLength (strString)

SalNumberToStr Syntax

nLength = SalNumberToStr ( nNumber, nDecimalPlaces, strString )

Description

Converts a number to a string.

Parameters

nNumber


nDecimalPlaces

Number. The number of decimal places you want in strString.

strString

Receive String. The string converted from nNumber.

Return Value

nLength is the length of strString, including the decimal point. strString is the string converted from nNumber.


See Also

SalNumberToStrX SalStrToNumber

Example

On SAM_Click Set nLength = SalNumberToStr ( 124.5, 1, strString )

SalNumberToStrX Syntax

strString = SalNumberToStrX ( nNumber, nDecimalPlaces)

Description

Converts a number to a string.

Parameters

nNumber


nDecimalPlaces

Number. The number of decimal places you want in strString.

strString

Receive String. The string converted from nNumber.

Return Value

nLength is the length of strString, including the decimal point. strString is the string converted from nNumber.

See Also

SalNumberToStr SalStrToNumber

Example

On SAM_Click Set df2 = SalNumberToStrX ( df1, 2 )

SalNumberToWindowHandle Syntax

hWnd = SalNumberToWindowHandle ( nWnd )

Description

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 )

Parameters

nWnd

Return Value

hWnd is the window handle converted from nWnd.

See Also


Example

Set hWndtblCustomer = SalNumberToWindowHandle (lParam )



2-117

Chapter

2

SalNumberTruncate Syntax

nResult = SalNumberTruncate ( nNumber, nPrecision, nScale )

Description

Truncates a number.

Parameters

nNumber

Number. The number to truncate, starting with the leftmost.

nPrecision

Number. The number of digits to display, starting with the leftmost.

nScale

Number. The number of digits to the right of the decimal point. The nPrecision parameter must be large enough to hold the number of digits that you specify in this parameter.

Return Value

nResult is the result of truncating nNumber.

Example

On SAM_Click Set nNum = SalNumberTruncate( 10.0625, 4, 4 )

SalParentWindow Syntax

hWndParent = SalParentWindow ( hWnd )

Description

Returns the handle of an object’s parent window. The following table shows the SalParentWindow behavior with tool bars and MDI windows: Where called

Parameter

Return

Tool bar child in a top-level object.

hWndItem

Handle of the top-level object that contains it (hWndForm).

Tool bar child in an MDI window.

hWndItem

Handle of the MDI window that contains it (hWndMDI).

Child table window in a tool bar.

hWndForm

Handle of the top-level object that contains it (hWndForm is the handle of the table window).

Top-level object in an MDI window.

hWndForm

Handle of hte MDI window that contains it (hWndMDI).

Parameters

hWnd

Return Value

hWndParent is the parent window handle of hWnd. If hWnd is a top-level window, hWndParent is the window handle of the owner window, as passed to SalCreateWindow, otherwise hWndParent is equal to hWndNull.


Window Handle. The handle (or name) of the object whose parent window handle you want.

Example

Set hWndParent = SalParentWindow ( hWnd )

SalPicClear Syntax

bOk = SalPicClear ( hWndToClear )

Description

Deletes the contents of a picture.

Parameters

hWndToClear

Return Value

bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid picture.

See Also

SalPicSet SalPicSetFile SalPicSetFit SalPicSetString

Example

Call SalPicClear ( hWndPicture )

Window Handle. The handle (or name) of a picture.

SalPicGetDescription Syntax

nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )

Description

Retrieves a description of a picture's contents. An example of a description is "Microsoft Draw".

Parameters

hWndPict


strDesc

Receive String. A description of the contents of hWndPict. For a graphic image, SalPicGetDescription returns one of the following values: Value

Image Type

Gupta:BMP


Gupta:GIF

Graphics Interchange Format

Gupta:ICO

Icon File

Gupta:PCX

Paintbrush

Gupta:TIFF

Tag Image File Format

Gupta:WMF

Windows MetaFile

For a file, SalPicGetDescription returns 'Gupta:DOSFILE'.


2-119

Chapter

2

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:

nMaxLength

Package Object Paintbrush Picture Object Sound Object Number. The maximum length of the text to retrieve.

Return Value

nLength is the length (in bytes) of strDesc.

See Also

SalPicGetSting

Example

Set nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )

SalPicGetString Syntax

nLength = SalPicGetString ( hWndPict, nFormat, strPict )

Description

Copies the contents of a picture to a string.

Parameters

hWndPict

Window handle. The handle (or name) of a picture.

nFormat

Number. The format of the picture contents: PIC_FormatBitmap PIC_FormatIcon PIC_FormatObject

strPict

Receive String. The contents of hWndPict.

Return Value

nLength is the length (in bytes) of strPict. If the format is not available, nLength is equal to zero (0).

See Also

SalPicGetDescription

Example

Set nLength = SalPicGetString ( hWndPict, nFormat, strPict )

SalPicSet Syntax

bOk = SalPicSet ( hWndPic, tResource, nFormat )

Description

Inserts a resource into a picture.

Parameters

hWndPic


tResource

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

Return Value


See Also

SalPicClear SalPicSetFile SalPicSetFit SalPicSetString

Example

Set bOk = SalPicSet ( hWndPic, tResource, nFormat )

SalPicSetFile Syntax

bOk = SalPicSetFile ( hWndPict, strFileName )

Description

Inserts a file's contents into a picture.

Parameters

hWndPict


strFileName

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

SalPicClear SalPicSet SalPicSetFit SalPicSetString

Example

Set bOk = SalPicSetFile ( hWndPict, strFileName )

SalPicSetFit Syntax

bOk = SalPicSetFit ( hWndPict, nFit, nScaleWidth, nScaleHeight )

Description

Sets the fit for a picture.

Parameters

hWndPict



2-121

Chapter

2

nFit

Number. The type of fit:

nScaleWidth

PIC_FitBestFit PIC_FitScale PIC_FitSizeToFit Number. The width scaling percentage if nFit is PIC_FitScale.

nScaleHeight

Number. The height scaling percentage if nFit is PIC_FitScale.

Return Value


See Also

SalPicClear SalPicSet SalPicSetFile SalPicSetString

Example

Call SalPicSetFit ( hWndItem, PIC_FitBestFit, 0, 0 )

SalPicSetString Syntax

bOk = SalPicSetString ( hWnd, nFormat, strPicture )

Description

Inserts the contents of a string into a picture.

Parameters

hWnd


nFormat

Number. The format of the picture contents:

strPicture

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

SalPicClear SalPicSet SalPicSetFile SalPicSetFit

Example

Call SalPicSetString ( hWndPicture, PIC_FormatBitmap, strPicture )


SalPixelsToFormUnits Syntax

nFormUnits = SalPixelsToFormUnits ( hWnd, nNumPixels, bVertical )

Description

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.

Parameters

hWnd

Window Handle. The handle (or name) of a window whose form units you want to compute.

nNumPixels

Number. The number of pixels.

bVertical

Boolean. If the pixels are on the X axis, set this parameter to FALSE. If the pixels are on the Y axis, set this parameter to TRUE.

Return Value

nFormUnits is the number of form units returned if the function call is successful. nFormUnits is equal to zero (0) if hWnd is invalid.

See Also

SalFormUnitsToPixels

Example

Set nFormUnits = SalPixelsToFormUnits ( pbExample, nPixels, FALSE )

SalPostMsg Syntax

bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )

Description

Posts the specified message to a window by adding nMsg to hWndReceiver's message queue.

Parameters

hWndReceiver

Window Handle. The handle (or name) of the window receiving the message.

nMsg


nMywParam

Number. The wParam for the message.

nMylParam

Number. The lParam for the message.

Return Value


See Also

SalSendMsg SalSendMsgToChildren

Example

Set bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )


2-123

Chapter

2

SalPrtExtractRect Syntax

bOk = SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom )

Description

Extracts the currently printing rectangle from the SAM_Print message's lParam parameter.

Parameters

nMylParam

Number. The SAM_Print message's lParam parameter.

nLeft

Receive Number. The position on the X axis of the rectangle's left side.

nTop

Receive Number. The position on the Y axis of the top of the rectangle.

nRight

Receive Number. The position on the X axis of the rectangle's right side.

nBottom

Receive Number. The position on the Y axis of the bottom of the rectangle.

Return Value


Example

On SAM_Print Call SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom )

SalPrtGetDefault Syntax

bOk = SalPrtGetDefault ( strDevice, strDriver, strPort )

Description

Returns the default device (printer), the default driver, and the default port.

Parameters

strDevice

Receive String. The default device.

strDriver

Receive String. The default driver.

strPort

Receive String. The default port.

Return Value

bOk is TRUE if the function call is successful in getting the default values, and FALSE otherwise.

See Also

SalPrtSetDefault SalPrtSetup

Example

Message Actions Call SalPrtGetDefault ( strDevice, strDriver, strPort )


SalPrtGetParmNum Syntax

bOk = SalPrtGetParmNum ( nParm, nValue )

Description

Gets the value of a print parameter. The print parameters are a set of global variables which are initialized to default values and can be set using SalPrtSetParmNum, retrieved using SalPrtGetParmNum or reinitialized using SalPrtSetParmDefaults.

Parameters

nParm

Number. The print parameter whose value you want; one of the PRT_* constants.

nValue

Receive Number. The print parameter's value. For boolean parameters, nValue is TRUE or FALSE.

Return Value


See Also

SalPrtSetParmNum

Example

On SAM_Create Call SalPrtGetParmNum ( PRT_nDraftMode, nPrtValue) If nPrtValue Set rbDraftMode = TRUE Else Set rbProofMode = TRUE

SalPrtPrintForm Syntax

bOk = SalPrtPrintForm ( hWndForm )

Description

Prints a form window, table window, or dialog box, including its contents and row header flags. If a form window or dialog box contains a child table window, list box or combo box, only the rows on screen print. Lines, frames, and pictures print as well. 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

hWndForm

Return Value


Example

Call SalPrtPrintForm ( hWndForm )

Window Handle. The handle (or name) of the window to print.


2-125

Chapter

2

SalPrtSetDefault Syntax

bOk = SalPrtSetDefault ( strDevice, strDriver, strPort )

Description

Sets the default device (printer), driver, and port.

Parameters

strDevice

String. The default device.

strDriver

String. The default driver.

strPort

String. The default port.

Return Value


See Also

SalPrtGetDefault SalPrtSetup

Example

Set strDevice = 'PostScript Printer' Set strDriver = 'PSCRIPT' Set strPort = 'LPT2' Call SalPrtSetDefault ( strDevice, strDriver, strPort )

SalPrtSetParmDefaults Syntax

bOk = SalPrtSetParmDefaults ( )

Description

Resets print parameters back to their default values. The print parameters are a set of global variables which are initialized to default values and can be set using SalPrtSetParmNum, retrieved using SalPrtGetParmNum or reinitialized using SalPrtSetParmDefaults. Number of copies: 1 Print in draft mode: FALSE Print all pages: TRUE Print from page: 1 Print to page: 1 Left margin: 0 Top margin: 0 Draw a rectangle around the printed form: FALSE

Parameters

No parameters.

Return Value



Example

On SAM_Click Call SalPrtSetParmDefaults ( )

SalPrtSetParmNum Syntax

bOk = SalPrtSetParmNum ( nParm, nValue )

Description

Sets the value of a print parameter. The print parameters are a set of global variables which are initialized to default values and can be set using SalPrtSetParmNum, retrieved using SalPrtGetParmNum or reinitialized using SalPrtSetParmDefaults.

Parameters

nParm

Number. A constant that represents the parameter to set; one of the PRT_* constants.

nValue

Number. The parameter value.

Return Value


See Also

SalPrtGetParmNum

Example

If rbDraftMode Call SalPrtSetParmNum ( PRT_nDraftMode, TRUE)

SalPrtSetup Syntax

bOk = SalPrtSetup ( strDevice, strDriver, strPort, bActiveOnly )

Description

Displays the Printer Setup dialog box that lets the user alter the printer setup. Initially, the current default printer is displayed and the user may change the printer. SalPrtSetup returns the user's selections in the Receive Strings.

Parameters

strDevice

Receive String. The device (printer).

strDriver

Receive String. The driver.

strPort

Receive String. The port.

bActiveOnly

Boolean. Whether to display active and/or inactive printers: if TRUE, all printers display and if FALSE, only active printers display.

Return Value


Example

Message Actions Call SalPrtSetup ( strDevice, strDriver, strPort, TRUE)


2-127

Chapter

2

SalQueryFieldEdit Syntax

bSet = SalQueryFieldEdit ( hWndField )

Description

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

hWndField

Return Value

bSet is TRUE if hWndField's field edit flag is set and FALSE otherwise.

See Also

SalSendValidateMsg SalSetFieldEdit

Example

If SalQueryFieldEdit ( SalGetFocus () )

Window Handle. The handle (or name) of a data field, multiline field, combo box table window column, or picture.

If SalSendValidateMsg ( ) = VALIDATE_Ok ! Process Save.

SalQuit Syntax

bOk = SalQuit ( )

Description

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

No parameters.

Return Value


See Also

SalAbort

Example

On SAM_Click Call SalQuit ( )


SalReportClose Syntax

bOk = SalReportClose ( hWndReport )

Description

Closes a report window. Call this function when you want to close a report preview window.

Parameters

hWndReport

Return Value

bOk is TRUE if the function succeeds and FALSE if hWndReport is invalid.

Example

If not SalReportClose ( hWndReport )

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

Call SalMessageBox ( 'Close Failed', 'SalReportClose', MB_Ok )

SalReportCmd Syntax

bOk = SalReportCmd ( hWndReport, nCommand )

Description

Sends a command to an open report window. Use SalReportCmd to control a window that displays a report. When you call SalReportView, its second parameter contains the handle of the window in which the report displays. The application creates that window. Use SalReportCmd to send commands that control the window to 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

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

nCommand

Number. The command to send to the report. Possible values include any of the RPT_Cmd* commands.

Return Value


Example

Set bOk = SalReportCmd ( hWndReport, nCommand )

SalReportCreate Syntax

bOk = SalReportCreate ( strTemplate, strVariables, strInputs, bDefaultReport, nError )

Description

Creates a report template.

Parameters

strTemplate

String. The name of the report template to create.


2-129

Chapter

2

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.

strInputs

String. A comma-separated list of the report's input names.

bDefaultReport

Boolean. If TRUE, Centura generates a quick report and nError is a RPT_Err* value. If FALSE, Centura generates an empty report.

nError

Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* values. If you call SalReportCreate ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, 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.

Return Value

bOk is TRUE if the function succeeds and FALSE if it fails. If bOk is FALSE, nError is a RPT_Err* value.

Example

Call SalReportCreate ( 'quick.qrp',':nDiv,:nDept,:nSection, :nEmplNum )

SalReportDlgOptions Syntax

bOk = SalReportDlgOptions ( hWndReport, strCaption, strLine1, strLine2, strDocName )

Description

Sets the options for the report printing dialog box. Call this function after creating the report but before printing begins. For example, you can call SalReportDlgOptions while processing the SAM_ReportFetchInit message.

Parameters

hWndReport

Window Handle. The wParam of a SAM_Report* message that contains the window handle.

strCaption

String. The replacement text for the Print dialog box caption text.

strLine1

String. The replacement text for the first centered-text field.

strLine2

String. The replacement text for the second centered-text field.

strDocName

String. The name of the document that Print Manager displays when the output is spooled and waiting to print.

Return Value



Example

Call SalReportDlgOptions ( SalNumberToWindowHandle (wParam ), 'Sales Report', 'This is a long report', 'Hit CANCEL to quit', 'sales.rpt' )

SalReportGetDateTimeVar Syntax

bOk = SalReportGetDateTimeVar ( hWndReport, strVariable, dtValue )

Description

Returns the value of a date/time report variable.

Parameters

hWndReport


strVariable

String. The name of a date/time report variable.

dtValue

Receive Date/Time. The value of strVariable.

Return Value

bOk is TRUE if the function is successful, and FALSE otherwise.

See Also

SalReportGetNumberVar SalReportGetObjectVar SalReportGetStringVar SalReportSetDateTimeVar

Example

Call SalReportGetDateTimeVar ( hWndReport, strVariable, dtGet )

SalReportGetNumberVar Syntax

bOk = SalReportGetNumberVar ( hWndReport, strVariable, nValue )

Description

Returns the value of a number report variable.

Parameters

hWndReport


strVariable

String. The name of a number report variable.

nValue

Receive Number. The value of strVariable.

Return Value


See Also

SalReportGetDateTimeVar SalReportGetObjectVar SalReportGetStringVar SalReportSetNumberVar

Example

Call bOk = SalReportGetNumberVar ( hWndToMove, nXOffset, nYOffset )


2-131

Chapter

2

SalReportGetObjectVar Syntax

bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )

Description

Returns the value of an object report variable.

Parameters

hWndReport


strVariable

String. The name of an object report variable.

strValue

Receive String. The value of strVariable.

Return Value


See Also

SalReportGetDateTimeVar SalReportGetNumberVar SalReportGetStringVar SalReportSetObjectVar

Example

Set bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )

SalReportGetStringVar Syntax

bOk = SalReportGetStringVar ( hWndReport, strVariable, strValue )

Description

Returns the value of a string report variable.

Parameters

hWndReport


strVariable

String. The name of a string report variable.

strValue

Receive String. The value of strVariable.

Return Value

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

hWndRet = SalReportPrint ( hWndFrm, strTemplate, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr )

Description

Prints a report. This function is synchronous and does not return until the report has been formatted and sent to Windows or Windows Print Manager for printing. SalReportPrint creates a minimized 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

Window Handle. The handle (or name) of the application window that processes SAM_Report* messages.

strTemplate

String. The report template name.

strVariables

String. A comma-separated list of Centura variables from which to fetch data. The data types of these variables must match the data types of the input names in strInputs.

strInputs

String. A comma-separated list of the report's input names. The contents of this string are case-sensitive and must match the case of the input names declared in the report template.

nCopies

Number. The number of copies. If you specify a zero or a negative number, Centura prints one copy.

nOptions

Number. You can combine two or more of these constants with the OR (|) operator: RPT_PrintAll RPT_PrintDraft RPT_PrintNoAbort RPT_PrintNoErrors RPT_PrintNoWarn RPT_PrintRange


2-133

Chapter

2

nFirstPage

Number. The first page of the report (if nOptions includes RPT_PrintRange).

nLastPage

Number. The last page of the report (if nOptions includes RPT_PrintRange).

nErr

Receive Number. If this function succeeds, this parameter is zero. If an error occurs, this parameter is one of the RPT_Err* values.

Note: If you call SalReportPrint ten times in a row, you will receive the following error code: RPT_ErrMaxRps.

In run mode at designtime, 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

SalReportPrintToFile

Example

Call SalReportPrint ( frmMain, strReportFile, strReportBinds, strReportInputs, nCopies, nOptions, nFirstPage, nLastPage, nErr )

SalReportPrintToFile Syntax

hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )

Description

Prints a report to a file in RTF format or in ASCII text format. This function is synchronous and does not return until the output report file is closed.

Parameters

hWndFrm

Window Handle. The handle (or name) of the application window that processes the SAM_Report* messages.

strTemplate


strDestFile

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.

strInputs


nCopies

Number. The number of copies.

nOptions

Number. You can combine two or more of these constants with the OR (|) operator:

nFirstPage

RPT_PrintAll RPT_PrintDraft RPT_PrintNoAbort RPT_PrintNoErrors RPT_PrintNoWarn RPT_PrintRange Number. The first page of the report (if nOptions includes RPT_PrintRange).

nLastPage

Number. The last page of the report (if nOptions includes RPT_PrintRange).

bFormat

Boolean. Specify TRUE to write the report in RTF format; specify FALSE to write the report in ASCII format.

nErr

Receive Number. If this function succeeds, this parameter is zero. If an error occurs, this parameter is one of the RPT_Err* values. If you call SalReportPrintToFile ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, 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.

Return Value

The return value is reserved for future use and can be ignored. To detect if the function succeeded, check nErr which is a RPT_Err* value. If successful, nErr is zero.

See Also

SalReportPrint


2-135

Chapter

2

Example

Set hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )

SalReportReset Syntax

bOk = SalReportReset ( hWndReport )

Description

Re-populates the report window. This function re-sends the SAM_ReportFetchInit message, and one or more SAM_ReportFetchNext messages to populate the report window with the new data.

Parameters

hWndReport

Return Value


Example

If NOT SalReportReset ( hWndReport )

Window Handle. The handle (or name) of the report window.

Call SalMessageBox ( 'Reset Failed', 'SalReportReset', MB_Ok )

SalReportSetDateTimeVar Syntax

bOk = SalReportSetDateTimeVar ( hWndReport, strVariable, dtValue )

Description


Parameters

hWndReport


strVariable

String. The name of the variable whose value you want to set.

dtValue

Date/Time. The value of strVariable.

Return Value


See Also

SalReportGetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar SalReportSetStringVar

Example

If NOT SalReportSetDateTimeVar ( hWndReport, 'dtVariable', dtGDateTime[1] ) Call SalMessageBox ( 'SetDateTimeError', 'RPT_BeforePageHeader-d', MB_Ok )


SalReportSetNumberVar Syntax

bOk = SalReportSetNumberVar ( hWndReport, strVariable, nValue )

Description

Sets the value of a numeric report variable.

Parameters

hWndReport


strVariable


nValue

Number. The value of strVariable.

Return Value


Related Function SalReportGetNumberVar SalReportSetDateTimeVar SalReportSetObjectVar SalReportSetStringVar Example

Call SalReportSetNumberVar ( hWndReport, 'strUnknown', nVariable )

SalReportSetObjectVar Syntax

bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue )

Description

Sets the value of an object report variable.

Parameters

hWndReport

Window Handle. The window of the report window handle.

strVariable


strValue

String. The value of strVariable.

Return Value


See Also

SalReportGetObjectVar SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetStringVar

Example

Set bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue )


2-137

Chapter

2

SalReportSetStringVar Syntax

bOk = SalReportSetStringVar ( hWndReport, strVariable, strValue )

Description

Sets the value of a string report variable.

Parameters

hWndReport


strVariable


strValue

String. The value of strVariable.

Return Value


See Also

SalReportGetStringVar SalReportSetDateTimeVar SalReportSetNumberVar SalReportSetObjectVar

Example

Call SalReportSetStringVar ( hWndReport, 'strUnknown', strVariable )

SalReportTableCreate Syntax

bOk = SalReportTableCreate ( strReport, hWndTbl, nError )

Description

Creates a report template from the specified table window. The table window column names are the input names to the report and their titles are the column names on the report. For a top-level table window, the report's title is the same as the table window's title; for a child table window, the report does not have a title.

Parameters

strReport

String. The name of the report.

hWndTbl

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

nError

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



See Also

SalReportTablePrint SalReportTableView

Example

Set bOk = SalReportTableCreate ( strReport, hWndTbl, nError )

SalReportTablePrint Syntax

hWnd = SalReportTablePrint ( hWndTbl, strReport, nParamArray, nError )

Description

Prints a report created from the specified table window.

Parameters

hWndTbl


strReport


nParamArray

Number. An array you create containing information about the print job. The array indexes are:

nError

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

hWnd is the handle of the report window if the function succeeds.

See Also

SalReportTableCreate SalReportTableView

Example

Set hWndReport = SalReportTablePrint ( hWndTbl, 'test.qrp', nParamArray,nError )


2-139

Chapter

2

SalReportTableView Syntax

hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError )

Description

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

Parameters

hWndTbl


hWndDisplay

Window Handle. The handle (or name) of a report display window. If null, Centura creates a window in which you can preview the report.

strReport


nError

Receive Number. If an error occurs, this parameter is equal to one of the RPT_Err* constants. If you call SalReportTableView ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, 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

hWnd is the handle of the report window if the function succeeds.

See Also

SalReportTableCreate SalReportTablePrint

Example

Set hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError )

SalReportView Syntax

hWndReport = SalReportView ( hWndFrm, hWndRptTemp, strTemplate, strVariables, strInputs, nFlags )

Description

Displays a report in preview mode. Report processing is asynchronous; SalReportView returns after starting the report process. Note: This function establishes a dialog between 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


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

Window Handle. The handle (or name) of the application window that processes SAM_Report* messages.

hWndRptTemp

Window Handle. An optional window handle (or name) to a custom report template. If null, ReportWindows creates its own window in which it displays the report.

strTemplate


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. The contents of this string must match the order of the input names declared in the report template.

strInputs


nFlags

Receive Number. Before you call this function, you can set this parameter to one of the constants below to turn off the printer icon on the default report view tool bar or turn off the tool bar completely:

RPT_NoPrint

No print button on the tool bar.

RPT_NoToolBar

No tool bar in the preview window. If an error occurs, this parameter is one of the RPT_Err* constants. If you call SalReportView ten times in a row, you will receive the following error code: RPT_ErrMaxRps. In run mode at designtime, 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.


2-141

Chapter

2

Example

Set hWndReport = SalReportView ( frmMain, hWndNULL, strReportFile, strReportBinds, strReportInputs, nError )

SalScrollGetPos Syntax

bOk = SalScrollGetPos ( hWndsb, nPos )

Description

Returns the current scroll bar value.

Parameters

hWndsb

Window Handle. The handle (or name) of a vertical or horizontal scroll bar.

nPos

Receive Number. The scroll bar value.

Return Value


See Also

SalScrollSetPos

Example

Set

bOk = SalScrollGetPos ( hWndsb, nPos )

SalScrollGetRange Syntax

bOk = SalScrollGetRange ( hWndsb, nMin, nMax, nLine, nPage )

Description

Gets a scroll bar's scroll range, line increment, and page increment.

Parameters

hWndsb


nMin

Receive Number. The minimum scroll bar position.

nMax

Receive Number. The maximum scroll bar position.

nLine

Receive Number. The line increment. The number of units the scroll bar increments or decrements when the user clicks the scroll bar arrow.

nPage

Receive Number. The page increment. The number of units the scroll bar increments or decrements when the user clicks either side of the scroll bar's scroll box.

Return Value


See Also

SalScrollSetRange

Example

Call SalScrollGetRange ( hWndsbCounter, nMin, nMax, nLine, nPage )


SalScrollSetPos Syntax

bOk = SalScrollSetPos ( hWndsb, nPos )

Description

Sets a scroll bar's position. This function is equivalent to using a Set statement to assign a value to the scroll bar.

Parameters

hWndsb


nPos

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.

Return Value


See Also

SalScrollGetPos

Example

Call SalScrollSetPos ( hWndsbCounter, 0 )

SalScrollSetRange Syntax

bOk = SalScrollSetRange ( hWndsb, nMin, nMax, nLine, nPage )

Description

Sets a scroll bar's range, line increment, and page increment. When the scroll bar is created, 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

Number. The minimum position of the scroll bar.

nMax

Number. The maximum position of the scroll bar.

nLine

Number. The number of units to increment or decrement the scroll bar when the user clicks the scroll bar arrow.

nPage

Number. The number of units to increment or decrement the scroll bar when the user clicks either side of the scroll box.


2-143

Chapter

2

Return Value


See Also

SalScrollGetRange

Example

Call SalScrollSetRange ( hWndsbCounter, 0, 50, 1, 5 )

SalSendClassMessage Syntax

nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )

Description

Invokes the message actions implemented or inherited by an object's class when called from either a derived class or from an object that is an instance of a class.

Parameters

nMessage


nMywParm

Number. The wParam.

nMylParam

Number. The lParam.

Return Value

nMsgReturn is the message return value. If the message has no return, nMsgReturn is zero (0).

See Also

SalSendClassMessageNamed

Example

Set nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )

SalSendClassMessageNamed Syntax

nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam )

Description

Invokes the message actions implemented or inherited by an object's class when called from either a derived class or from an object that is an instance of a class. Use this function instead of SalSendClassMessage with a class that is the result of multiple inheritance. It lets you specify which base class message action you want to execute. tClassName must be a direct base class of the class from which this call is made.

Parameters

Return Value

tClassName

Template. The ancestor's class name.

nMsg


nMywParam

Number. The wParam.

nMylParam

Number. The lParam.



See Also

SalSendClassMessage

Example

Set nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam )

SalSendMsg Syntax

nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )

Description

Sends the specified message to a window. SalSendMsg does not return until the processing for the message is complete.

Parameters

hWnd

Window Handle. The window receiving the message.

nMsg


nMywParam

Number. The wParam.

nMylParam

Number. The lParam.

Return Value


See Also

SalPostMsg SalSendMsgToChildren SalSendValidateMsg

Example

Set nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )

SalSendMsgToChildren Syntax

bSent = SalSendMsgToChildren ( hWnd, nMsg, nMywParam, nMylParam )

Description

Sends a message to all child items of a form window, dialog box, table window, or MDI window.

Parameters

hWnd

Window Handle. The handle (or name) of a form window, dialog box, table window, or MDI window.

nMsg


nMywParam

Number. The wParam for the message.

nMylParam

Number. The lParam for the message.

Return Value

bSent is TRUE if the function succeeds and FALSE if it fails.

See Also

SalPostMsg SalSendMsg SalSendValidateMsg


2-145

Chapter

2

Example

Call SalSendMsgToChildren ( hWndForm,CHM_DISABLE, 0, 0 )

SalSendValidateMsg Syntax

nStatus = SalSendValidateMsg ( )

Description

Sends a SAM_Validate message to the object with the focus data field, multiline field, or table window column if it was edited and sets the wParam and lParam message variables to zero (0). Call this function to force field validation before processing a menu pick. Centura does not automatically send SAM_Validate message on a menu pick.

Parameters

Np parameters.

Return Value

nStatus is returned by the object's message actions for the SAM_Validate message: VALIDATE_Cancel VALIDATE_Ok VALIDATE_OkClearFlag

See Also

SalSendMsg SalSendMsgToChildren

Example

Set nStatus = SalSendValidateMsg ( )

SalSetDefButton Syntax

bOk = SalSetDefButton ( hWndButton )

Description

Sets the default push button of a form window or dialog box. When this function returns, the default push button gets the focus only if the focus was on one of the push buttons before you called SalSetDefButton.

Parameters

hWndButton

Return Value

bOk is TRUE if the function succeeds and FALSE if hWndButton is not a valid button.

See Also

SalGetDefButton

Example

Call SalSetDefButton ( frmMain.pb2 )


Window Handle. The handle (or name) of the default push button.

SalSetFieldEdit Syntax

bOk = SalSetFieldEdit ( hWndField, bSet )

Description

Sets or clears the field edit flag for an editable data field, combo box, multiline text field, table window column, or picture. The Field Edit Flag is set whenever the user changes the value of a data field, multiline field, combo box or table window column. For a picture, the field edit flag is set whenever an OLE server application is opened for editing. The field edit flag is not set if you make the change with a Set statement or a fetch from a database.

Parameters

hWndField

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

bSet

Boolean. TRUE sets the flag; FALSE clears it.

Return Value


See Also

SalQueryFieldEdit

Example

Call SalSetFieldEdit ( hWndChild, FALSE )

SalSetFocus Syntax

hWndFocus = SalSetFocus ( hWndToSet )

Description

Sets the focus to a specified window. Warning: You cannot call SalSetFocus in SAM_KillFocus processing because of a Windows limitation.

Parameters

hWndToSet

Return Value

hWndFocus is the handle of the window that previously had the focus.

See Also

SalGetFocus

Example

Call SalSetFocus ( hWndSave )

Window Handle. The handle (or name) of the window to receive the focus.


2-147

Chapter

2

SalSetMaxDataLength Syntax

bOk = SalSetMaxDataLength ( hWndField, nLength )

Description

Sets a limit on the number of characters that a user can enter into a data field, multiline text field, or table window column.

Parameters

hWndField


nLength

Number. The character limit.

Return Value


See Also

SalGetMaxDataLength

Example

Set bOk = SalSetMaxDataLength ( hWndField, nLength )

SalSetProfileString Syntax

bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )

Description

Set the value of an entry in the specified section of an initialization file or registry. All profile information is stored as string, so if you want to store an integer it must be converted to a string first. Then it can be retrieved as an integer using the SalGetProfileInt-Function .

Parameters

strSection


strEntry

String. The entry whose associated value is being set.

strValue

String. The value of strEntry.

strFileName


Return Value


See Also

SalGetProfileInt SalGetProfileString SalUseRegistry

Example

Set bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )


SalSetWindowLabelText Syntax

bOk = SalSetWindowLabelText ( hWnd, sText )

Description

Sets the background text of a window. To be associated with a specific window, background text must immeditately precede the window in the Outliner. Important: The background text does not require a mnemonic for the function to operate.

Parameters

hWnd


sText

String. The window text.

Return Value


Example

Set bOk = SalSetWindowLabelText ( hWnd, sText )

SalSetWindowLoc Syntax

bOk = SalSetWindowLoc ( hWnd, nX, nY )

Description

Moves a window to a new position (x, y) on the X and Y axes.

Parameters

hWnd

Window Handle. The handle (or name) of the window to move.

nX

Number. The position on the X axis (expressed in form units).

nY

Number. The position on the Y axis (expressed in form units).

Return Value

bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle.

See Also

SalGetWindowLoc

Example

Call SalSetWindowLoc ( pbExample, 0, 0 )

SalSetWindowSize Syntax

bOk = SalSetWindowSize ( hWnd, nWidth, nHeight )

Description

Resizes a window.

Parameters

hWnd

Window Handle. The handle (or name) of the window to resize.

nWidth

Number. The new width of the window (expressed in form units).


2-149

Chapter

2

nHeight

Number. The new height of the window (expressed in form units).

Return Value

bOk is TRUE if the window is successfully resized, and FALSE if hWnd is an invalid window handle.

See Also

SalGetWindowSize

Example

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

SalSetWindowText Syntax

bOk = SalSetWindowText ( hWnd, strTitle )

Description

Sets the text of a window to a specified string. A window's text is the title of a form window, modeless dialog box, table window, radio button, check box, or push button. For a data field or table window column, the text is the object's value in string form, regardless of the object's data type. For a combo box, the text is the contents of the editable data field portion. If the combo box is not editable, 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

String. The window text.

Return Value


See Also

SalGetWindowText SalTblSetColumnTitle

Example

Call SalSetWindowText ( hWndForm, 'First National Bank' )

SalShowWindow Syntax

bOk = SalShowWindow ( hWndToShow )

Description


Parameters

hWndToShoWindow Handle. The handle (or name) of a window to make visible.

Return Value

bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they


are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible. See Also

SalHideWindow

Example

Call SalShowWindow ( hWndForm )

SalShowWindowAndLabel Syntax

bOk = SalShowWindowAndLabel ( hWndToShow )

Description

Makes a window and its associated label visible. A label is the background text that immediately precedes the window in the outline.

Parameters

hWndToShow

Return Value

bOk is TRUE if the previous state of the window was visible and FALSE if it was hidden. Use this information to hide many windows without first checking that they are visible. When you restore them to their original state at a later point in time, the return lets you make visible only those windows that were previously visible.

See Also

SalHideWindowAndLabel SalShowWindow

Example

Set bOk = SalShowWindowAndLabel ( hWndToShow )

The handle (or name) of a window to make visible.

SalStatusGetText Syntax

nLength = SalStatusGetText ( hWnd, strText, nMaxLen )

Description

Gets the text displayed in the status bar of a top-level or MDI window.

Parameters

hWnd

Window Handle. The handle (or name) of a top-level or MDI window.

strText

Receive String. The text displayed in the status bar.

nMaxLen


Return Value

nLength is the length of strText. nLength is zero (0) if the window has no text.

See Also

SalStatusSetText SalStatusSetVisible

Example

Set nLength = SalStatusGetText ( hWnd, strText, nMaxLen )


2-151

Chapter

2

SalStatusSetText Syntax

bOk = SalStatusSetText ( hWnd, strText )

Description

Displays specified text in the status bar of a top-level or MDI window.

Parameters

hWnd


strText

String. The text to display in the status bar.

Return Value


See Also

SalStatusGetText SalStatusSetVisible

Example

Set bOk = SalStatusSetText ( hWnd, strText )

SalStatusSetVisible Syntax

bOk = SalStatusSetVisible ( hWnd, bShow )

Description

Shows or hides the status bar on a top-level or MDI window.

Parameters

hWnd


bShoBoolean. If TRUE, the status bar displays; if FALSE, the status bar hides. Return Value


See Also

SalStatusGetText SalStatusSetText

Example

Call SalStatusSetVisible ( hWndForm, TRUE )

SalStrCompress Syntax

bOk = SalStrCompress ( strString )

Description

Compresses the specified string. Use this function to compress strings for storage on disk or in the database. Use this function for long strings, or when storing images and so on.

Parameters

strString

Return Value


See Also

SalStrUncompress

Example

Set bOk = SalStrCompress ( strString )


Receive String. The string to compress.

SalStrFirstC Syntax

bOk = SalStrFirstC ( strString, nChar )

Description

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

Receive String. The string whose first character is lopped off.

nChar

Receive Number. The first character of strString.

Return Value

bOk is TRUE unless strString is empty or invalid.

See Also

SalNumberHigh SalNumberLow SalNumberToChar SalStrLop

Example

On SAM_Click Set dfString = 'ABC' Call SalStrFirstC ( dfString, dfNumChar ) ! Now dfString = 'BC' and dfNumChar = 65

SalStrGetBufferLength Syntax

nLength = SalStrGetBufferLength ( strString )

Description

Returns the current buffer length of a string. Centura stores string variables in buffers. The length includes the string's null termination character.

Parameters

strString

Return Value

nLength is the length of strString's buffer.

See Also

SalStrLength SalStrSetBufferLength

Example

Set nBufferLength = SalStrGetBufferLength (strNumbers )

String. The string whose buffer length you want.


2-153

Chapter

2

SalStrIsValidCurrency Syntax

bOk = SalStrIsValidCurrency ( strMoney, nPrecision, nScale )

Description

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.

Parameters

strMoney

String. A string that contains a currency value.

nPrecision

Number. The number of digits to display.

nScale

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

Return Value

bOk is TRUE if strMoney is a valid currency value and FALSE otherwise.

See Also

SalStrIsValidDateTime SalStrIsValidNumber

Example

Set bOk1 = SalStrIsValidCurrency ( '$120.00' )

SalStrIsValidDateTime Syntax

bOk = SalStrIsValidDateTime ( strDateTime )

Description

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.

Parameters

strDateTime

Return Value

bOk is TRUE if strDateTime is a valid date/time value and FALSE otherwise.

See Also

SalStrIsValidCurrency SalStrIsValidNumber

Example

Set bOk2 = SalStrIsValidDateTime ( '2/2/91' )


String. A string that contains a date/time value.

SalStrIsValidNumber Syntax

bOk = SalStrIsValidNumber ( strNumber )

Description

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.

Parameters

strNumber

Return Value

bOk is TRUE if strNumber is a valid number value and FALSE otherwise.

See Also

SalStrIsValidCurrency SalStrIsValidDateTime

Example

Set bOk1 = SalStrIsValidNumber ( '120.00' )

String. A string that contains a number value.

SalStrLeft Syntax

nLength = SalStrLeft ( strSource, nExtract, strTarget )

Description

Returns a substring of a specified length starting at position zero (0), the left-most character in the string.

Parameters

strSource

String. The string from which to extract characters.

nExtract

Number. The number of characters to extract from strSource.

strTarget

Receive String. The substring.

You can specify the same string for both strSource and strTarget. Return Value

nLength is the length of the new string. strTarget is the substring.

See Also

SalStrMid SalStrMidX SalStrRight SalStrLeftX

Examples

Set nLength = SalStrLeft ( 'LEFT01234', 4, strTarget )


2-155

Chapter

2

SalStrLeftX Syntax

strTarget = SalStrLeftX ( strSource, nExtract)

Description

Returns a substring of a specified length starting at position zero (0), the left-most character in the string.

Parameters

strSource

String. The string from which to extract characters.

nExtract

Number. The number of characters to extract from strSource.

strTarget



nLength is the length of the new string. strTarget is the substring.

See Also

SalStrMid SalStrMidX SalStrRight SalStrLeft

Examples

Set strTarget = SalStrLeftX ( 'LEFT01234', 4)

SalStrLength Syntax

nLength = SalStrLength ( strString )

Description

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

strString

Return Value

nLength is the length of strString.

See Also

SalStrGetBufferLength

Example

On SAM_Create

String. The string whose length you want.

Set strNumbers = '1234567890' Set nStringLength = SalStrLength ( strNumbers )


SalStrLop Syntax

nCharacter = SalStrLop ( strString )

Description

Returns the ASCII numeric value of the first character of a string in decimal format. This function removes the first character of the string.

Parameters

strString

Return Value

nCharacter is the ASCII value of the first character of strString. When strString is null, nCharacter is equal to zero (0).

See Also

SalNumberToChar SalStrFirstC

Example

On SAM_Create

Receive String. The input string without the first character.

Set strString = 'ABC' Set nCharacter = SalStrLop ( strString )

SalStrLower Syntax

nLength = SalStrLower ( strSource, strTarget ) or strTarget = SalStrLowerX ( strSource )

Description

Converts a string to lowercase.

Parameters

strSource

String. The string to convert .

strTarget

Receive String. The lowercase string.


nLength is the length of strTarget. strTarget is the lowercase string.

See Also

SalStrUpper SalStrUpperX

Examples

On SAM_Create Set nLength = SalStrLower ( 'LOWERCASE', strTarget ) or On SAM_Create Set strTarget = SalStrLowerX ( 'LOWERCASE' )


2-157

Chapter

2

SalStrMid Syntax

nLength = SalStrMid ( strSource, nStartPos, nLength, strTarget ) or strTarget = SalStrMidX ( strSource, nStartPos, nLength )

Description

Returns a substring, starting at a specified position and containing a specified number of characters.

Parameters

strSource

String. The source string.

nStartPos

Number. The starting position of the substring (zero is the first position) in strSource.

nLength

Number. The number of characters to put in the substring.

strTarget



nLength is the length of the substring. strTarget is the substring.

See Also

SalStrLeft SalStrLeftX SalStrRight

Examples

Set nLength = SalStrMid (‘012ABC345’, 3, 3, strTarget) Or Set strTarget = SalStrMidX ( '012ABC345', 3, 3 ) ! strTarget = 'ABC'

SalStrProper Syntax

nLength = SalStrProper ( strSource, strTarget ) or strTarget = SalStrProperX ( strSource )

Description

Converts a string to a proper name. In a proper name, the first letter of each word is uppercase; the remaining letters are lowercase.

Parameters

strSource

String. The string to convert.

strTarget

Receive String. The converted string.

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

Concatenates a string with itself a specified number of times.

Parameters

strSource


nTimes

Number. The number of times to concatenate strSource with itself.

strTarget

Receive String. The new string.


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

2

Parameters

Return Value

strSource

String. The source string that contains characters to replace.

nStartPos

Number. The position in strSource at which to begin replacing characters.

nLength

Number. The number of characters to replace. If zero (0), strReplace starts at nStartPos.

strReplace

String. The replacement string.

strTarget


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

Returns a string of specified length, starting with the last character in the string.

Parameters

strSource


nLength

Number. The number of characters to extract.

strTarget



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

nOffset = SalStrScan ( strString1, strString2 )

Description

Searches for and returns the offset of a specified substring. If there is more than one instance of the string being searched for, only the offset of the first instance is returned.

Parameters

strString1

String. The string to search. The first character in the string is at offset zero (0).

strString2

String. The string to search for. Case is disregarded in the search. You can use pattern matching characters. The percent character (%) matches any set of characters. The underscore character (_) matches any single character. The use of a backslash(\) with SalStrScan differs when searching for a backslash, percent, or underscore character. Its usage also differs depending on whether or not the second parameter is a string literal. 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.


2-161

Chapter

2

Return Value

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.

Example

Set nOffset = SalStrScan ( '012AbC345', 'ABC' )

SalStrSetBufferLength Syntax

bOk = SalStrSetBufferLength ( strString, nLength )

Description

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.

Parameters

strString

Receive String. The string whose buffer length you want to set.

nLength

Number. The length of strString.

Return Value


See Also

SalSetMaxDataLength SalStrGetBufferLength

Example

Set bOk = SalStrSetBufferLength( recvString, 10 ) ! 11 chars

SalStrToDate Syntax

dtDateTime = SalStrToDate ( strString )

Description

Converts a string to a date/time value.This function uses the system date format to convert a date string. If you want to be format independent, use SalDateConstruct.

Parameters

strString

Return Value

dtDateTime is the date/time value converted from strString.

See Also

SalDateToStr

Example

Set dtDateTime = SalStrToDate ( strDateTime )



SalStrTokenize Syntax

nNumTokens = SalStrTokenize ( strSource, strStartDel, strEndDel, strTokenArray )

Description

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

String. The string to parse.

strStartDel

String. A string that contains the start delimiter characters. Pass an empty string ('') to specify the lack of a start delimiter.

strEndDel

String. A string that contains the end delimiter characters. Pass an empty string ('') to specify the lack of an end delimiter.

strTokenArray

String Array. The handle (or name) of an array of substrings created from strSource.

Return Value

nNumTokens is the number of substrings created. nNumTokens is zero (0) if no substrings are created, or if an error occurs.

Example

Set dfNumTokens = SalStrTokenize( dfSource1, '', ',', astrToken1 )

SalStrToNumber Syntax

nNumber = SalStrToNumber ( strString )

Description


Parameters

strString

Return Value

nNumber is the number resulting from the conversion.



2-163

Chapter

2

See Also

SalNumberToStr

Example

Set nNumber = SalStrToNumber ( '100.22' )

SalStrTrim Syntax

nNewLength = SalStrTrim ( strSource, strTarget ) or strTarget = SalStrTrimX ( strSource )

Description

Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces.

Parameters

strSource

String. The original string.

strTarget



nNewLength is the length of strTarget. strTarget is the new string.

Example

Set nLength = SalStrTrim ( ' 1 2

3 ', strTarget )

SalStrTrimX Syntax

strTarget = SalStrTrimX ( strSource)

Description

Strips leading and trailing blanks and compresses multiple spaces and tabs within a string to single spaces.

Parameters

strSource

String. The original string.

strTarget



nNewLength is the length of strTarget. strTarget is the new string.

Example

On SAM_Create Set nLength = SalStrTrim ( ' 1 2


3 ', strTarget )

SalStrUncompress Syntax

bOk = SalStrUncompress ( strString )

Description

Decompresses the specified string. Use this function to decompress a string that you compressed with SalStrCompress.

Parameters

strString

Return Value


See Also

SalStrCompress

Example

Set bOk = SalStrUncompress ( strString )

Receive String. The string to decompress.

SalStrUpper Syntax

nLength = SalStrUpper ( strSource, str Target )

Description


Parameters

strSource


strTarget

Receive String. The uppercase string.


nLength is the length of strTarget. strTarget is the uppercase string.

See Also

SalStrLower

Example

Set nLength = SalStrUpper ( 'uppercase', strTarget )

SalStrUpperX Syntax

strTarget = SalStrUpperX ( strSource )

Description


Parameters

strSource



This function returns the uppercase string in strTarget.

See Also

SalStrLower

Example

On SAM_Create Set strTarget = SalStrUpperX ( 'uppercase' )


2-165

Chapter

2

SalTBarSetVisible Syntax

bOk = SalTBarSetVisible (hWind, bShw)

Description

Shows or hides the tool bar on a top-level or MDI window.

Parameters

hWnd


bShow

Boolean. If TRUE, displays the tool bar; if FALSE, hides the tool bar.

Return Value


See Also

SalStatusSetVisible

Example

Set bOk = SalTBarSetVisible (hWind, bShw)

SalTblAnyRows Syntax

bAny = SalTblAnyRows ( hWndTbl, nFlagsOn, nFlagsOff )

Description

Determines whether any rows in the specified table window match certain flags. If you set nFlagsOn to zero (0) and nFlagsOff to zero (0), SalTblAnyRows returns TRUE if the table window contains any rows at all, regardless of their flags.

Parameters

hWndTbl


nFlagsOn

Number. The flags that the row should have. You can combine ROW_* flags using the OR (|) operator.

nFlagsOff

Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator.

Return Value

bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags and none of the nFlagsOff flags.

See Also

SalTblFindNextRow SalTblFindPrevRow

Example

Menu Settings Enabled When: SalTblAnyRows ( tblTable, ROW_Selected, 0 )


SalTblClearSelection Syntax

bOk = SalTblClearSelection ( hWndTbl )

Description

Deselects all rows of a table window.

Parameters

hWndTbl

Return Value


See Also

SalTblSetRowFlags

Example

Call SalTblClearSelection ( hWndForm )


SalTblColumnAverage Syntax

nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

Description

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

Number. The Column Identifier.

nFlagsOn


nFlagsOff

Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator:

Return Value

nAverage is the average of all column values or only specified column values in a table window. nAverage is equal to zero (0) if an error occurs.

See Also

SalTblColumnSum

Example

Set nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

SalTblColumnSum Syntax

nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

Description

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. Centura Builder Function Reference

2-167

Chapter

2

Parameters

hWndTbl


nColumnID

Number. The Column Identifier

nFlagsOn


nFlagsOff


Return Value

nSum is the sum of all column values or only specified column values in a table window. nSum is equal to zero (0) if an error occurs.

See Also

SalTblColumnAverage

Example

Set nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

SalTblCopyRows Syntax

bOk = SalTblCopyRows ( hWndTbl, nFlagsOn, nFlagsOff )

Description

Copies the contents of the specified table window rows to the Clipboard in text format. In the Clipboard, columns are delimited by TAB characters and rows are delimited by end-of-line characters. Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to copy the entire table. The copy stops, without indicating a failure, after copying 64 Kbytes of text.

Parameters

hWndTbl


nFlagsOn


nFlagsOff


Return Value

bOk is TRUE if any of the table window's rows are copied to the Clipboard and FALSE if no rows matched the indicated flags, or if none of the matched rows could be copied to the Clipboard.

See Also

SalTblPasteRows

Example

Call SalTblCopyRows ( tblTable, ROW_Selected, 0 )



SalTblCreateColumn Syntax

nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars, strTitle )

Description

Creates a table window column of string data type at runtime. When you return to design mode, Centura destroys the column.

Parameters

hWndTbl


nColumnPos

Number. The Column Position

nDispWidth

Number. The display width of the column in inches.

nMaxChars

Number. The maximum number of characters that the column can contain.

strTitle

String. The column title.

Return Value

nColId is the Column Identifier of the new column. nColld is zero (0) if an error occurs.

Example

Set nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars, strTitle )

SalTblDefineCheckBoxColumn Syntax

bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue )

Description

Define a column as a check box.

Parameters

hWnd


HWndCol

Window Handle. The handle (or name) of a table window column.

nFlags

Number. nFlags is a combination of the following flags using the '|' operator:

sCheckedValue

COL_CheckBox_IgnoreCase = 0x0001 String. sCheckedValue is the value that a cell will get when the check box is checked.

sUncheckedValue

String. The value when a check box is unchecked.

Return Value


Example

Set bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue )


2-169

Chapter

2

SalTblDefineDropDownListColumn Syntax

bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol, nFlags, nLines )

Description

Define a column as a drop down list.

Parameters

hWnd


HWndCol


nFlags

Number. nFlags is a combination of the following flags using the '|' operator:

nLines

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.

Return Value


Example

Set bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol, nFlags, nLines )

SalTblDefinePopupEditColumn Syntax

bOk = SalTblDefinePopupEditColumn( hWnd, hWndCol, nFlags, nLines )

Description

Define a column as a popup edit window. nLines indicates the maximum number of lines to display in the control.

Parameters

hWnd


HWndCol


nFlags

Number. nFlags is always 0 (zero).

nLines

Number. nLines indicates the maximum number of lines to display in the list.

Return Value


Example

Set bOk = SalTblDefinePopupEditColumn ( hWnd, hWndCol, nFlags, nLines )


SalTblDefineRowHeader Syntax

bOk = SalTblDefineRowHeader ( hWndTable, strTitle, nWidth, nFlags, hWndCol )

Description

Defines the appearance and behavior of a table window's row header. The row header is a non-editable area on the left edge of a table window that displays information that stays displayed even when a user scrolls horizontally. A typical use of a row header is the display of row numbers.

Parameters

hWndTable


strTitle

String. The title of the row header column.

nWidth

Number. The width of the row header in pixels.

nFlags

Number. The row header attributes. You can combine these flags using the OR (|) operator. Possible values include: TBL_RowHdr_MarkEdits TBL_RowHdr_ShareColor TBL_RowHdr_Sizable TBL_RowHdr_Visible

hWndCol

Window Handle. The column that the row header mirrors. Whatever displays in hWndCol displays in the row header. If hWndCol equals hWndNULL, the row header is blank.

Return Value


Example

Call SalTblDefineRowHeader ( tbl1, strTitle, nWidth,TBL_RowHdr_Visible | TBL_RowHdr_ShareColor, colRowHeader )

SalTblDefineSplitWindow Syntax

bOk = SalTblDefineSplitWindow ( hWndTable, nRowsLowerHalf, bDragAdjust )

Description

Splits a table window horizontally. You can insert rows into the lower half of a split table window. This is convenient when the scroll range is dynamic because you can insert rows without knowing the number of rows in the table window. You can also use the lower half of a split table window to display summary data.

Parameters

hWndTable

Window Handle. The handle (or name) of a table window to split.


2-171

Chapter

2

nRowsLowerHalf

Number. The number of rows to make visible in the lower half of the split window. If you specify zero (0), the table window is not split.

bDragAdjust

Boolean. Specify whether (TRUE) or not (FALSE) to let the user drag-adjust the visible rows in both halves of a split window.

Return Value


Example

Set bAnyFlag = SalTblDefineSplitWindow ( hWndTbl, 3, TBL_Split_Adjustable )

SalTblDeleteRow Syntax

bOk = SalTblDeleteRow ( hWndTbl, nRow, nFlag )

Description

Deletes a row from a table window but not from the database.

Parameters

hWndTbl


nRoNumber. The number of the row to delete. nFlag

Number. A constant used to coordinate a delete from the table window with a delete from a SQLBase result set. This parameter can be one of these values: TBL_Adjust TBL_NoAdjust

Return Value


Example

Call SalTblDeleteRow ( hWndForm, nCurrentRow, TBL_NoAdjust)

SalTblDeleteSelected Syntax

bOk = SalTblDeleteSelected ( hWndTbl, hSql )

Description

Applies a SQL DELETE statement to all table window rows with the ROW_Selected flag set. You must prepare or retrieve the SQL DELETE statement before calling this function. As each row is deleted from the database, 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

Sql Handle. The handle of a DELETE statement.


Return Value

bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid.

See Also

SalTblDoDeletes SalTblDoInserts SalTblDoUpdates SalTblPopulate

Example

Call SalTblDeleteSelected ( tblExample, hSql )

SalTblDestroyColumns Syntax

bOk = SalTblDestroyColumns ( hWndTbl )

Description

Destroys all automatic columns created by SalTblCreateColumn or SalTblPopulate at runtime. This function only works on table windows that contain only automatic columns.

Parameters

hWndTbl

Return Value

bOk is TRUE if the function succeeds and FALSE if hWndTbl is invalid or the table window contains non-automatic columns (columns created at design time).

See Also

SalTblCreateColumn SalTblPopulate

Example

Set bOk = SalTblDestroyColumns ( hWndTbl )


SalTblDoDeletes Syntax

bOk = SalTblDoDeletes ( hWndTbl, hSql, nFlagsOn )

Description

Applies a SQL DELETE statement to all table window rows that have nFlagsOn flags set. You must prepare the SQL DELETE statement before calling this function. As each row is deleted from the database, 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

Sql Handle. The handle of a DELETE statement.

nFlagsOn

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

2

Return Value

bOk is TRUE if any rows are deleted and FALSE otherwise. bOk is FALSE if hWndTbl or hSql is invalid.

See Also

SalTblDeleteSelected SalTblDoInserts SalTblDoUpdates

Example

Call SalTblDoDeletes ( tblExample, hSql, ROW_MarkDeleted )

SalTblDoInserts Syntax

bOk = SalTblDoInserts ( hWndTbl, hSql, bClearFlags )

Description

Applies a SQL INSERT statement to all the rows in a table window that have the ROW_New flag set. You must prepare the SQL INSERT statement before calling this function. This function does not perform a COMMIT. You must perform a COMMIT to ensure that insertions are not lost in the case of a rollback.

Parameters

hWndTbl


hSql

Sql Handle. The handle of an INSERT statement.

bClearFlags

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

SalTblDeleteSelected SalTblDoDeletes SalTblDoUpdates SalTblPopulate

Example

Call SalTblDoInserts ( tblExample, hSql, FALSE )


SalTblDoUpdates Syntax

bOk = SalTblDoUpdates ( hWndTbl, hSql, bClearFlags )

Description

Applies a SQL UPDATE statement to all table window rows with the ROW_Edited flag set. You must prepare the SQL UPDATE statement before calling this function. This function does not perform a COMMIT. You must perform a COMMIT to ensure that the updates are not lost in the case of a rollback.

Parameters

hWndTbl


hSql

Sql Handle. The handle of an UPDATE statement.

bClearFlags

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

SalTblDeleteSelected SalTblDoDeletes SalTblDoInserts SalTblPopulate

Example

Call SalTblDoUpdates ( tblExample, hSql, FALSE )

SalTblFetchRow Syntax

nResult = SalTblFetchRow ( hWndTbl, nRow )

Description

Sends a SAM_FetchRow message to a table window if the row you specify is not currently in the table window cache. To process the SAM_FetchRow message, fetch the row from the database or another data source. The SAM_FetchRow message sets the context row to the row you specify before the table window receives the message.

Parameters

Return Value

hWndTbl

Window Handle. The handle (or name) of the table window that owns the row being retrieved.

nRoNumber.

The row number.

nResult is one of these values: TBL_RowDeleted, TBL_RowFetched, TBL_NoMoreRows.


2-175

Chapter

2

See Also

SalTblQueryContext SalTblSetContext

Example

Call SalTblFetchRow ( hWndtblTelephone, nMaxRange )

SalTblFindNextRow Syntax

bOk = SalTblFindNextRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff )

Description

Scans forward in a table looking for a row whose flags match those specified. The search stops at the first row that has any of the nFlagsOn flags set, and none of the nFlagsOff flags set. Use this function in a loop to find all the table window rows that match specified conditions. You do not need to increment the row number; 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

Window Handle. The handle of the table window to search.

nRow

Receive Number. The row at which to begin the search; the search starts on nRow + 1. If Centura finds a row, it returns its row number in this parameter.

nFlagsOn

Number. The flags the row should have.

nFlagsOff

Number. The flags the row should not have. Specify zero (0) for no flags. You can specify any of the ROW_* flags for nFlagsOn and nFlagsOff. If you want to specify more than one, combine them using the OR (|) operator.

Return Value

bOk is TRUE if Centura finds a row and FALSE if there are no matches.

See Also

SalTblFindPrevRow SalTblSetFlagsAnyRows


Example

If SalTblFindNextRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )

SalTblFindPrevRow Syntax

bOk = SalTblFindPrevRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff )

Description

Scans backward in a table looking for a row whose flags match those specified. The search stops at the first row that has any of the nFlagsOn flags set, and none of the nFlagsOff flags set. Use this function in a loop to find all the table window rows that match specified conditions. You do not need to decrement the row number; 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

Number. The flags the row should have.

nFlagsOff

Number. The flags the row should not have. Specify zero (0) for no flags. You can specify any of the ROW_* flags for nFlagsOn and nFlagsOff. If you want to specify more than one, combine them using the OR (|) operator.

Return Value

bOk is TRUE if Centura finds a row and FALSE if there are no matches.

See Also

SalTblFindNextRow SalTblSetFlagsAnyRows

Example

If SalTblFindPrevRow ( hWndForm, nCurrentRow, ROW_Selected, 0 )


2-177

Chapter

2

SalTblGetColumnText Syntax

bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )

Description

Gets data from a column of a table window's context row.

Parameters

hWndTbl


nColumnID

Number. The Column Identifier

strText

Receive string. The column data.

Return Value


See Also

SalTblSetColumnText

Example

Set bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )

SalTblGetColumnTitle Syntax

nLength = SalTblGetColumnTitle ( hWndCol, strText, nMaxLen )

Description

Gets the title of a table window column.

Parameters

hWndCol


strText

Receive String. The title.

nMaxLen

Number. The maximum length of the title.

Return Value

nLength is the length of the column title returned in strText.

See Also

SalTblSetColumnTitle

Example

Call SalTblGetColumnTitle ( colRowHeader, strTitle, 100 )

SalTblGetColumnWindow Syntax

hWndCol = SalTblGetColumnWindow ( hWndTbl, nCol, nFlags )

Description

Gets the handle of a table window column.

Parameters

hWndTbl

Window Handle. The handle (or name) of the table window that contains the column whose window handle you want.

nCol

Number. A column position or a column identifier.

nFlags

Number. A constant that identifies whether nCol's value is a column identifier or a column position. Specify either: COL_GetID


COL_GetPos

Return Value

hWndCol is the handle of a table window column. hWndCol is equal to hWndNULL if Centura cannot find the table window column.

Example

Set hWndCol = SalTblGetColumnWindow ( tbl1, nColID, COL_GetID )

SalTblInsertRow Syntax

nNewRow = SalTblInsertRow ( hWndTbl, nRow )

Description

Inserts a new blank row into a table window.

Parameters

hWndTbl


nRowNumber

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

nNewRow is the number of the new row if the function succeeds. It is equal to TBL_Error if an error occurs.

Example

Set nNewRow = SalTblInsertRow ( hWndTbl, TBL_MinSplitRow )

SalTblKillEdit Syntax

bOk = SalTblKillEdit ( hWndTbl )

Description

Takes a row out of edit mode and selects the row. This causes the row to receive both SAM_Validate and SAM_KillFocus messages.

Parameters

hWndTbl

Return Value


Example

Set bOk = SalTblKillEdit ( hWndTbl )

Window Handle. The handle (or name) of the table window that contains the row just inserted or modified.


2-179

Chapter

2

SalTblKillFocus Syntax

bOk = SalTblKillFocus ( hWndTbl )

Description

Turns off the table window's focus frame. This is useful when the user chooses a menu item from a table window menu; in this case, the focus cannot leave the table window.

Parameters

hWndTbl

Return Value


Example

Call SalTblKillFocus ( hWndForm )


SalTblPasteRows Syntax

bOk = SalTblPasteRows ( hWndTbl )

Description

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

hWndTbl

Return Value

bOk is TRUE if the Clipboard contains text that is successfully inserted into the table window, and FALSE otherwise, and if none of the columns are editable.

See Also

SalTblCopyRows

Example

Call SalTblPasteRows ( tblPhoneList )

Window Handle. The handle (or name) of the table window receiving the data from the Clipboard.

SalTblPopulate Syntax

bOk = SalTblPopulate( hWndTbl, hSql, strSelect, nMethod )

Description

Compiles, binds, and executes a SQL SELECT statement, then fetches the rows of the result set and populates a table window with them. SalTblPopulate also manages table window browsing. This function also works with table windows that do not have columns. 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

Window Handle. The handle (or name) of the table window to populate.

hSql

Sql Handle. The handle of the SELECT statement. Do not use the Sql Handle passed to SalTblPopulate by other functions while the table window is in use.

strSelect

String. The SELECT statement. If the string is null (“), Centura uses the previously prepared SELECT statement associated with hSql. This avoids re-preparing the statement each time SalTblPopulate executes.

nMethod

Number. How to populate the table window. Specify one of these values: TBL_FillAll TBL_FillAllBackground TBL_FillNormal

Return Value

bOk is TRUE if the function succeeds and FALSE if either hWndTbl or hSql is invalid.

See Also

SalTblDeleteSelected SalTblDoDeletes SalTblDoInserts SalTblDoUpdates

Example

Call SalTblPopulate ( tblExample, hSql, strSql, TBL_FillAllBackground )


2-181

Chapter

2

SalTblQueryCheckBoxColumn Syntax

bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue )

Description

If the column is defined as a check box, this function retrieves information about the check box and returns TRUE. If it is not a check box, this function returns FALSE.

Parameters

hWnd


HWndCol


nFlags

Receive Number. nFlags is a combination of the following flags using the '|' operator:

sCheckedValue

COL_CheckBox_IgnoreCase = 0x0001 Receive String. sCheckedValue is the value that a cell will get when the check box is checked.

sUncheckedValue

Receive String. The value when a check box is unchecked.

Return Value


Example

bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue, sUncheckedValue )

SalTblQueryColumnCellType Syntax

bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType )

Description

Indicates whether a column is a checkbox, drop down list, popup edit, or standard column.

Parameters

hWnd


hWindCol


nType

Receive Number. Receives one of the following values. COL_CellType_Standard=1 COL_CellType_CheckBox=2 COL_CellType_DropDownList=3 COL_CellType_PopupEdit=4

Return Value


Example

Set bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType )


SalTblQueryColumnFlags Syntax

bSet = SalTblQueryColumnFlags ( hWndCol, nFlags )

Description

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

Parameters

hWndCol


nFlags

Number. The column flags to test. You can combine COL_* flags using the OR (|) operator.

Return Value

bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise.

See Also

SalTblSetColumnFlags

Example

If SalTblQueryColumnFlags ( col1, COL_CenterJustify ) Set rbCenter = TRUE Else Set rbLeft = TRUE

SalTblQueryColumnID Syntax

nColID = SalTblQueryColumnID ( hWndCol )

Description

Gets a table window column's identifier.

Parameters

hWndCol

Return Value

nColID is the Column Identifier. nColID is -1 if hWndCol is not a valid column.

Example

Set nColID = SalTblQueryColumnID ( hWndCol )

Window Handle. The handle of a table window column.

Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )

SalTblQueryColumnPos Syntax

nPos = SalTblQueryColumnPos ( hWndCol )

Description

Gets a table window column's relative position.

Parameters

hWndCol

Return Value

nPos is the Column Position. nPos is -1 if hWndCol is not a valid handle for a table window column.

See Also

SalTblSetColumnPos

Example

Set nPos = SalTblQueryColumnPos ( hWndCol )

Window Handle. The handle of a table window column.


2-183

Chapter

2

SalTblQueryColumnWidth Syntax

bOk = SalTblQueryColumnWidth ( hWndTbl, nFormUnits )

Description

Returns the width (in form units) of a table window column.

Parameters

hWndTbl


nInches

Receive Number. The width of the table window column.

Return Value


See Also

SalTblSetColumnWidth

Example

Call SalTblQueryColumnWidth ( colRowHeader, nWidth )

SalTblQueryContext Syntax

nContext = SalTblQueryContext ( hWndTbl )

Description

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

hWndTbl

Return Value

nContext is the current context row number.

See Also

SalTblFetchRow SalTblSetContext

Example

Set nContext = SalTblQueryContext ( hWndTbl )


SalTblQueryDropDownListColumn Syntax

bOk = SalTblQueryDropDownListColumn( hWnd, hWndCol, nFlags, nLines )

Description

If the column is defined as a drop down list, this function retrieves information about the list and returns TRUE. If it is not a drop down list, this function returns FALSE.

Parameters

hWnd


HWndCol



nFlags

nLines

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.

Return Value


Example

Set bOk = SalTblQueryDropDownListColumn ( hWnd, hWndCol, nFlags, nLines )

SalTblQueryFocus Syntax

bOk = SalTblQueryFocus ( hWndTbl, nRow, hWndCol )

Description

Identifies the cell in a table window with the focus.

Parameters

hWndTbl


nRoReceive Number. The row number of the focus row. hWndCol

Receive Window Handle. The handle of the column with the focus.

Return Value


See Also

SalTblSetFocusCell SalTblSetFocusRow

Example

On SAM_Click Call SalTblQueryFocus ( hWndtblTelephone, nRow,hWndColumn )

SalTblQueryLinesPerRow Syntax

bOk = SalTblQueryLinesPerRow( hWndTbl, nLines )

Description

Retrieves the height of a row in lines.

Parameters

HWndTbl


nLines

Receive Number. The number of lines.

Return Value



2-185

Chapter

2

Example

Set bOk = SalTblQueryLinesPerRow( hWndTbl, nLines )

SalTblQueryLockedColumns Syntax

nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )

Description

Retrieves the number of locked table window columns. Locked table window columns do not scroll horizontally; they are fixed to the left side of the table window. All other columns appear to scroll under the locked columns.

Parameters

hWndTbl

Return Value

nLockedColumns is the number of locked columns. If there are no locked columns, nLockedColumns is zero (0).

See Also

SalTblSetLockedColumns

Example

Set nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )


SalTblQueryPopupEditColumn Syntax

bOk = SalTblQueryPopupEditColumn( hWnd, hWndCol, nFlags, Lines )

Description

If the column is defined as a popup edit, this function retrieves information about the popup edit and returns TRUE. If it is not a popup edit, this function returns FALSE.

Parameters

hWnd


HWndCol


nFlags

Receive Number. nFlags is a combination of the following flags using the '|' operator:

nLines

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.

Return Value


Example

Set bOk = SalTblQueryPopupEditColumn ( hWnd, hWndCol, nFlags, Lines )


SalTblQueryRowFlags Syntax

bOk = SalTblQueryRowFlags ( hWndTbl, nRow, nFlags )

Description

Queries a row's flags.

Parameters

hWndTbl


nRoNumber. The row number of the row whose flags you want to test. nFlags

Number. The row flags to test for. You can combine ROW_* flags using the OR (|) operator.

Return Value

bOk is TRUE if any of the specified flags are set and FALSE if none of the specified flags are set.

See Also

SalTblSetFlagsAnyRows SalTblSetRowFlags

Example

On SAM_SetFocus If SalTblQueryRowFlags ( hWndForm, lParam, ROW_New )

SalTblQueryRowHeader Syntax

bOk = SalTblQueryRowHeader ( hWndTbl, strTitle, nMaxTitle, nWidth, nFlags, hWndCol )

Description

Gets a table window's row header definition. The row header is a non-editable area on the left edge of a table window that displays information that you do not want to scroll off the screen as the user scrolls horizontally. A typical use is the display of row numbers.

Parameters

hWndTbl


strTitle

Receive String. The title of the row header.

nMaxTitle

Number. The maximum length of the title.

nWidth

Receive Number. The width of the row header in pixels.

nFlags

Receive Number. Row header attributes. Specify one of these: TBL_RowHdr_MarkEdits TBL_RowHdr_ShareColor TBL_RowHdr_Sizable TBL_RowHdr_Visible


2-187

Chapter

2

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.

Return Value


Example

Call SalTblQueryRowHeader ( tbl1, strTitle, 100, nWidth, nFlags, colRowHeader )

SalTblQueryScroll Syntax

bOk = SalTblQueryScroll ( hWndTbl, nPosition, nMinRange, nMaxRange )

Description

Returns a table window's current scroll position and range. The scroll position is the row number of the row that is currently at the top of the window. You set the table window range with SalTblSetRange and Centura changes it when you insert or delete rows from the table window.

Parameters

hWndTbl


nPosition

Receive Number. The scroll position.

nMinRange

Receive Number. The minimum table range.

nMaxRange

Receive Number. The maximum table range.

Return Value


Example

Call SalTblQueryScroll ( hWndTbl, nPosRow, nMinRow, nMaxRow )

SalTblQuerySplitWindow Syntax

bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax bDragAdjust )

Description

Specifies how a table window is split horizontally.

Parameters

hWndTbl

Window Handle. The handle (or name) of a split table window.

nRowLowerHalf

Receive Number. The number of visible rows in the lower half of the split window. If zero (0), the table is not split.

bDragAdjust

Receive Number Boolean. Specify whether (TRUE) or not (FALSE) the user can drag-adjust the visible rows in both halves of a split window.

Return Value



Example

Set bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax,bDragAdjust )

SalTblQueryTableFlags Syntax

bSet = SalTblQueryTableFlags ( hWndTbl, nFlags )

Description

Tests the state of a table window's flags.

Parameters

hWndTbl


nFlags

Number. The table flags to test. You can combine TBL_* flags using the OR (|) operator.

Return Value

bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwise.

See Also

SalTblSetTableFlags

Example

If SalTblQueryTableFlags ( tbl1, TBL_Flag_MoveableCols ) Set rbColsMovable = TRUE

SalTblQueryVisibleRange Syntax

bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )

Description

Returns the current range of visible rows in a table window.

Parameters

hWndTbl


nRangeMin

Receive Number. The first visible row.

nRangeMax

Receive Number. The last visible row.

Return Value


Example

Set bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )

SalTblReset Syntax

bOk = SalTblReset ( hWndTbl )

Description

Clears a table window by discarding all rows from the table window cache and setting the table range to 0, -1.

Parameters

hWndTbl

Return Value


See Also

SalTblSetRange



2-189

Chapter

2

Example

If nRowCount > 0 Call SalTblReset ( hWndForm )

SalTblScroll Syntax

bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )

Description

Scrolls a table window to the specified row and column.

Parameters

hWndTbl


nRoWNumber

The number of the row to scroll to. If you specify -1, only the column scrolls into view.

hWndColumn

Window Handle. The table window column to scroll into view. If you specify hWndNULL, only the row scrolls into view.

nTBLScroll

Number. The position of the scroll row. Specify one of these: TBL_AutoScroll TBL_ScrollBottom TBL_ScrollTop

Return Value

bOk is TRUE if the function succeeds and FALSE if Centura cannot scroll the row. This function fails if either nRow or nTBLScroll are invalid values.

See Also

SalTblQueryScroll SalTblQueryVisibleRange

Example

Set bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )

SalTblSetCellTextColor Syntax

bOk = SalTblSetCellTextColor ( hWndCol, nColor, bDiscardable )

Description

Changes a table window cell's text color.

Parameters

hWndCol


nColor

Number. The cell text color. Specify one of the predefined windows colors.

bDiscardable

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.


Return Value


Example

On SAM_FetchRow Call SalTblSetCellTextColor ( Col1, COLOR_Red, TRUE ) Return TBL_RowFetched

SalTblSetColumnFlags Syntax

bOk = SalTblSetColumnFlags ( hWndCol, nFlags, bSet )

Description

Sets or clears a table window column's flags.

Parameters

hWndCol


nFlags

Number. The column flags to change. You can combine COL_* flags using the OR (|) operator.

bSet

Boolean. If TRUE, Centura sets the flags; if FALSE, Centura clears the flags.

Return Value

bOk is TRUE if the function succeeds and FALSE if it fails. To define a column a column as multiline use the flag: COL_MultilineCell = 0x00800000

See Also

SalTblQueryColumnFlags

Example

Call SalTblSetColumnFlags ( col1, COL_CenterJustify, TRUE )

SalTblSetColumnPos Syntax

bOk = SalTblSetColumnPos ( hWndCol, nPos )

Description

Moves a table window column to a new position.

Parameters

hWndCol

Window Handle. The handle (or name) of a table window column to move.

nPos

Number. The new position of the table window column. 1 is the first (left-most) position, 2 is the second position, and so on.

Return Value


See Also

SalTblQueryColumnPos

Example

Call SalTblSetColumnPos ( col3, nPos + 1 )


2-191

Chapter

2

SalTblSetColumnText Syntax

bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )

Description

Assigns data to a column of a table window's context row.

Parameters

hWndTbl


nColumnID

Number. The Column Identifiers

strText

String. The data to assign.

Return Value


See Also

SalTblGetColumnText

Example

Set bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )

SalTblSetColumnTitle Syntax

bOk = SalTblSetColumnTitle ( hWndCol, strTitle )

Description

Sets the title of a table window column.

Parameters

hWndCol


strTitle

String. The title of the table window column.

Return Value


See Also

SalTblGetColumnTitle

Example

Set bOk = SalTblSetColumnTitle ( hWndCol, strTitle )

SalTblSetColumnWidth Syntax

bOk = SalTblSetColumnWidth ( hWndTbl, nFormUnits )

Description

Sets a table window column's display width.

Parameters

hWndTbl


nFormUnits

Number. The table window column's display width in form units.

Return Value


See Also

SalTblQueryColumnWidth


Example

Set nColID = SalTblQueryColumnID ( hWndCol ) Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )

SalTblSetContext Syntax

bOk = SalTblSetContext ( hWndTbl, nRow )

Description

Sets a table window's context row. Setting the context row does not send a SAM_FetchRow message. If the row is not currently in memory, 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

SalTblQueryContext

Example

Set bOk = SalTblSetContext ( hWndTbl, nRow

SalTblSetFlagsAnyRows Syntax

bAny = SalTblSetFlagsAnyRows ( hWndTbl, nFlags, bSet, nFlagsOn, nFlagsOff )

Description


Parameters

hWndTbl

Window Handle. The handle (or name) of a table window whose row flags you want to set or clear.

nFlags

Number. The flags to change. You can combine flag values using the OR (|) operator.

bSet

Boolean. Whether to set (TRUE) or clear (FALSE) the specified flags.

nFlagsOn

Number. The flags that the rows should have. You can combine flag values using the OR (|) operator. Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to specify all rows.

nFlagsOff

Number. The flags that the rows should not have. You can combine flag values using the OR (|) operator.


2-193

Chapter

2

Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to specify all rows. Return Value

bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags and none of the nFlagsOff flags.

See Also

SalTblFindNextRow SalTblFindPrevRow

Example

Call SalTblSetFlagsAnyRows ( tblExample, ROW_MarkDeleted, TRUE, ROW_Selected, 0 )

SalTblSetFocusCell Syntax

bOk = SalTblSetFocusCell ( hWndTbl, nRow, hWndCol, nEditMin, nEditMax )

Description

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.

Parameters

hWndTbl


nRowNumbe

The row that receives the edit focus.

hWndCol

Window Handle. The handle (or name) of the column that receives the edit focus.

nEditMin

Number. The position of the left-most character. When used with nEditMax, this parameter lets the user select a portion of the cell text. nEditMin must be less than or equal to nEditMax. To select all the characters in a cell, specify zero (0) for this parameter and -1 for nEditMax.

nEditMax

Number. The position of the right-most character. When used with nEditMin, this parameter lets the user select a portion of the cell text. nEditMax must be greater than or equal to nEditMin. To select all the characters in a cell, specify -1 for this parameter and zero (0) for nEditMin.

Return Value


See Also

SalTblQueryFocus

Example

Call SalTblSetFocusCell ( hWndForm, lParam, hWndItem, 0, 1 )


SalTblSetFocusRow Syntax

bOk = SalTblSetFocusRow ( hWndTbl, nRow )

Description

Sets a table window's focus frame row.

Parameters

hWndTbl


nRoNumber. The row number of the row to which to apply the focus frame. Return Value


See Also

SalTblQueryFocus

Example

Set bOk = SalTblSetFocusRow ( hWndTbl, nRow

SalTblSetLinesPerRow Syntax

bOk = SalTblSetLinesPerRow( hWndTbl, nLines )

Description

Sets the height of a row in lines. Multirow lines are useful when a column is defined as multiline. The text in each cell will wrap. To define a column a column as multiline use the function SalTblSetColumnFlags with the flag: COL_MultilineCell = 0x00800000

Parameters

HWndTbl


nLines

Number. The number of lines.

Return Value


Example

Set bOk = SalTblSetLinesPerRow( hWndTbl, nLines )

SalTblSetLockedColumns Syntax

bOk = SalTblSetLockedColumns ( hWndTbl, nLockedColumns )

Description

Sets the number of locked table window columns. Table window columns that you lock do not scroll horizontally; they are fixed to the left side of the table window. All other columns appear to scroll under the locked columns. This function locks zero (0) or more of the left-most visible columns of a table window.

Parameters

hWndTbl


nLockedColumns

Number. The number of table window columns to lock.

Return Value


See Also

SalTblQueryLockedColumns


2-195

Chapter

2

Example

Call SalTblSetLockedColumns ( tbl1, 2 )

SalTblSetRange Syntax

bOk = SalTblSetRange ( hWndTbl, nMin, nMax )

Description

Defines the minimum and maximum rows (range) of a table.

Parameters

hWndTbl

The handle (or name) of a table window.

nMin

Number. The lower boundary of the table window.

nMax

Number. The upper boundary of the table window. Setting nMin and nMax: nMin must be less than or equal to nMax. You can specify an empty table with the range 0, -1. You can specify a dynamic range with the values zero (0), TBL_MaxRow. 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

SalTblReset

Example

Call SalTblSetRange ( hWndForm, 0, nRowCount - 1 )

SalTblSetRow Syntax

nRowNum = SalTblSetRow ( hWnd, nRowPos )

Description

Sets the focus to the first, last, next, or previous row in a table window.

Parameters

tName

Window Handle. The handle (or name) of the window whose current focus row you want to change.

nRowPos

Number. The position of the focus row. Specify one of these values: TBL_SetFirstRow TBL_SetLastRow TBL_SetNextRow TBL_SetPrevRow

Return Value

nRowNum is the row number of the new focus row.


Example

Set = nRowNum = SalTblSetRow ( hWnd, nRowPos )

SalTblSetRowFlags Syntax

bOk = SalTblSetRowFlags ( hWndTbl, nRow, nFlags, bSet )

Description

Sets or clears a table window row's flags.

Parameters

hWndTbl


nRoNumber.

The row number of the row whose flags you want to set or clear.

nFlags

Number. The row flags. You can combine any of the ROW_* flags using the OR (|) operator.

bSet


Return Value


See Also

SalTblQueryRowFlags SalTblSetFlagsAnyRows

Example

Call SalTblSetRowFlags ( hWndTbl, nRow, ROW_Selected, TRUE )

SalTblSetTableFlags Syntax

bOk = SalTblSetTableFlags ( hWndTbl, nFlags, bSet )

Description

Sets or clears a table window's flags.

Parameters

hWndTbl


nFlags

Number. The table flags. You can combine any of the TBL_* flags using the OR (|) operator.

bSet


Return Value


See Also

SalTblQueryTableFlags

Example

Call SalTblSetTableFlags ( tbl1, TBL_Flag_MoveableCols, FALSE)


2-197

Chapter

2

SalTblSortRows Syntax

bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )

Description

Sorts the rows of a non-discardable table window based on the values in one of the table window's columns. You must create this column at design time; it cannot be an automatic column such as a column created by SalTblPopulate. or SalTblCreateColumn. Important: The table window cache must not be discardable and the setting of maximum rows in memory must be large enough to hold the rows that you are sorting.

Parameters

hWndTbl


nColumnID

Number. The Column Identifier of the column by which to sort.

nOrder

Number. The direction of the sort. Specify either: TBL_SortDecreasing TBL_SortIncreasing

Return Value

bRet is TRUE if the function succeeds and FALSE if nColumnID is not a valid identifier.

Example

Set bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )

SalTimerKill Syntax

bOk = SalTimerKill ( hWnd, nIDEvent )

Description

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

Window Handle. The handle (or name) of an object.

nIDEvent

Number. The timer ID to kill.

Return Value

bOk is TRUE if Centura successfully kills the event and FALSE if Centura cannot find the specified timer.

See Also

SalTimerSet

Example

On SAM_Destroy Call SalTimerKill ( dfClock, 1 )


SalTimerSet Syntax

bOk = SalTimerSet ( hWnd, nIDEvent, nElapseMilliSec )

Description

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

Window Handle. The handle (or name) of an object associated with a system timer.

nIDEvent

Number. The timer ID number.

nElapseMilliSec

Number. The elapsed time between each SAM_Timer message. The maximum value is 65535 (approximately 65 seconds). If you set this parameter to a higher value, it wraps.

Return Value


See Also

SalTimerKill

Example

On SAM_Create Set bOk = SalTimerSet ( hWndItem, 1, 1000 )

SalTrackPopupMenu Syntax

bOk = SalTrackPopupMenu ( hWndProcMsgs, strMenuName, nFlags, nX, nY )

Description

Creates pop-up menus at runtime.

Parameters

hWndProcMsgs

Window Handle. The handle (or name) of the top-level window that processes messages generated by the pop-up menu.

strMenuName

String. The name of a pop-up menu accessible to hWndProcMsgs. For example, a menu defined by hWndProcMsgs or its MDI window parent, or a global menu.

nFlags

Number. Specifies how the pop-up menu displays. You can combine flag values using the OR (|) operator.

nX

Number. The position of the pop-up menu on the X axis. The value of this parameter is ignored if you set the TPM_CursorX flag in nFlags.


2-199

Chapter

2

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

On SAM_Click Call SalTrackPopupMenu ( hWndForm, 'menuEdit', TPM_CursorX | TPM_CursorY | TPM_CenterAlign, 0, 0 )

SalUpdateWindow Syntax

bOk = SalUpdateWindow ( hWndUpdate )

Description

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

hWndUpdate

Return Value

bOk is TRUE if the function succeeds and FALSE if hWndUpdate is not a valid window handle.

See Also

SalInvalidateWindow

Example

Message Actions

Window Handle. The handle (or name) of the window to update.

On SAM_FieldEdit Call SalUpdateWindow ( ml1 )


SalUseRegistry Syntax

bOk = SalUseRegistry( bUseRegistry, sCompanyName )

Description

This function is used to re-direct all SalProfile* functions to use the Registry. All values for the SalProfile* functions are saved as strings. The INI file name used as the last parameter of the SalProfile* functions will be used as the application name. The resulting path will be: \\HKEY_CURRENT_USER\Software\\\
\\

Parameters

bUseRegistry

- TRUE if registry is to be used, FALSE if INI files are to be used.

sCompanyName

- Name of company to be used under the registry.

Return Value

bOk is TRUE if the function succeeds and FALSE if function fails.

Example

Set bOk = SalUseRegistry( bUseRegistry, sCompanyName )

SalValidateSet Syntax

bOk = SalValidateSet ( hWndCC, bValState, lParam )

Description

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

Return Value

hWndCC

Handle of the custom control.

bValState

Validates this custom control when it loses the focus.

lParam

Centura passes the value you specify in the lParam of SAM_Validate.

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

2

•

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

bOk = SalWaitCursor ( bOn )

Description

Displays or removes the hourglass cursor. The hourglass is a visual indicator that the application is busy. You must always call this function twice; once to turn the cursor into an hourglass and again to restore it to its original form.

Parameters

bOn

Return Value


Example

Call SalWaitCursor ( TRUE )

Boolean. Whether to turn the hourglass on (TRUE) or off (FALSE).

SalWindowClassName Syntax

sClassName = SalWindowClassName( hWnd )

Description

Return the name of a window's class as a string.

Parameters

hWnd

Return Value

Returns an empty string if the window is not a class object.

Example

Set sClassName = SalWindowClassName( hWnd )


Window Handle. The window handle of an instance of a Window Class object.

SalWindowGetProperty Syntax

bOk = SalWindowGetProperty( hWndQO, strPropName, strPropValue )

Description


Parameters

hWndQO

Window Handle. The window handle of an instance of a QuickObject.

strPropName

String. The name of the property.

strPropValue

Receive String. The value of the property.

Return Value


Example

This example gets a window name property: Set bOk = SalWindowGetProperty( hWndItem, 'WindowName', strWindowName )

SalWindowHandleToNumber Syntax

nWnd = SalWindowHandleToNumber ( hWnd )

Description

Converts a window handle to a number. For example, you can pass a window handle as a SalSendMsg wParam parameter as follows: nWnd = SalWindowHandleToNumber ( hWndParm ) Call SalSendMsg ( hWndDest, nMsg, nWnd, 0 )

Parameters

hWnd

Return Value

nWnd is the number converted from hWnd.

See Also

SalNumberToWindowHandle

Example

Set ntblCustomer = SalWindowHandleToNumber ( hWndtblCustomer )

Window Handle. The handle to convert.

SalWindowIsDerivedFromClass Syntax

bOk = SalWindowIsDerivedFromClass( hWnd, ClassName )

Description

Tells you if a window is an instance of the class that you specify or an instance of a class that is derived from the class that you specify.


2-203

Chapter

2

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

Window Handle. The handle (or name) of the window.

ClassName

Symbol. The ClassName parameter is a symbol, not a string. Type the class name without single quotes.

Return Value

bOk is TRUE if the window is an instance of the named class or an instance of a class that is derived from the named class.

Example

Set bOk = SalWindowIsDerivedFromClass( hWnd, ClassName )

SalWinHelp Syntax

bOk = SalWinHelp( hWnd, strFile, nCommand, nData, strData )

Description

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

Window Handle. The handle (or name) of the window requesting help.

strFile

String. The file name of the help system file.

nCommand

Number. The type of help requested; any HELP_* value.

nData

Number. Specify zero (0) unless:

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.

Return Value


Example

Call SalWinHelp ( hWndForm, 'CONTROL.HLP', HELP_Index, 0, '')


SalYieldEnable Syntax

bOk = SalYieldEnable ( bSet )

Description

Enables or disables application yielding.

Parameters

bSet

Return Value


See Also

SalYieldQueryState SalYieldStartMessages SalYieldStopMessages

Example

Call SalYieldEnable( FALSE )

Boolean. If TRUE, enable yielding; if FALSE, disable yielding.

SalYieldQueryState Syntax

bEnabled = SalYieldQueryState ( ) Determines whether application yielding is enabled or disabled.

Parameters

No parameters.

Return Value

bEnabled is TRUE if yielding is enabled, and FALSE if it is not.

See Also

SalYieldEnable SalYieldStartMessages SalYieldStopMessages

Example

Set bEnabled = SalYieldQueryState ( )

SalYieldStartMessages Syntax

bOk = SalYieldStartMessages ( hWnd )

Description

Enables yielding and the sending of messages to a window. Enable yielding to give the user enough control to stop long operations. For example, if it takes a long time to populate a table window, allow the user access to a Cancel push button to stop the query.

Parameters

hWnd

Return Value


See Also

SalYieldEnable SalYieldQueryState SalYieldStopMessages



2-205

Chapter

2

Example

Call SalYieldStartMessages ( pbCancel )

SalYieldStopMessages Syntax

bOk = SalYieldStopMessages ( )

Description

Stops yielding and the sending of messages to the window specified in a prior call to SalYieldStartMessages.

Parameters

No parameters.

Return Value


See Also

SalYieldEnable SalYieldQueryState SalYieldStartMessages

Example

Call SalYieldStopMessages ( )

SqlClearImmediate Syntax

bOk = SqlClearImmediate ( )

Description

Disconnects the internal Sql Handle from a database. You connect the internal handle to a database by calling SqlImmediate and it remains connected until the application terminates or you explicitly disconnect it with SqlClearImmediate. SqlClearImmediate causes an implicit COMMIT if it is the last cursor you disconnect from the database.

Parameters

No parameters.

Return Value


See Also

SqlImmediate

Example

Set bOk = SqlClearImmediate ( )

SqlClose Syntax

bOk = SqlClose ( hSql )

Description

Invalidates a SQL command and/or frees the cursor name associated with the specified cursor, making it available for re-use. If you create a named cursor by calling SqlOpen and then instead of closing it, call SqlOpen or SqlExecute again, you get an error that the name has already been used.


Parameters

hSql

Return Value


See Also

SqlOpen

Example

Set bOk = SqlClose ( hSql )

Sql Handle. A handle that identifies a database connection.

SqlCommit Syntax

bOk = SqlCommit ( hSql )

Description

Commits all of the SQL transaction's cursors that are connected to the same database. NOTE: To prevent destroying a cursor's result set when a COMMIT is performed, turn on cursor context preservation by calling SqlSetParameter and setting the DBP_PRESERVE parameter to TRUE.

Parameters

hSql

Return Value


Example

Call SqlCommit ( hSql )


SqlConnect Syntax

bOk = SqlConnect ( hSql )

Description

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

hSql

Return Value


See Also

SqlDisconnect

Example

Call SqlConnect ( hSqlPrimary )

Receive Sql Handle. A handle that identifies a database connection.


2-207

Chapter

2

SqlContextClear Syntax

bOk = SqlContextClear ( hSql )

Description

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

hSql

Return Value


See Also

SqlContextSet SqlContextSetTo Form

Example

Set bOk = SqlContextClear ( hSql )


SqlContextSet Syntax

bOk = SqlContextSet ( hSql )

Description

Sets the context for future processing (for example, calls to SqlPrepare, SqlFetchNext, SqlFetchPrevious, and SqlFetchRow). Sql* functions you call after SqlContextSet behave as if they are in the window identified by hWndForm. Call this function in a class to perform SQL processing for the current window without fully qualifying bind and INTO variables. This function is also useful for global functions. Important: After you call SqlContextSet, the context for bind variables and INTO variables is always hWndForm. If you call a Sql* function in an internal function, window function, or class function after calling SqlContextSet, 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

hSql

Return Value


See Also

SqlContextClear SqlContextSetTo Form

Example

Set bOk = SqlContextSet ( hSql )



SqlContextSetToForm Syntax

bOk = SqlContextSetToForm ( hSql, hWndMyForm)

Description

This function is like SqlContextSet, except for an additional parameter: SqlContextSet sets the context of the Sql Handle to the window identified by hWndForm; SqlContextSetToForm sets the context of the Sql Handle to the window you specify in the second parameter. Call this function from a child table window when you want to set the context to the parent form window; in this situation hWndForm refers to the child table window, not to the parent form window. For new applications, call SqlVarSetup instead of this function.

See Also

SqlContextClear SqlContextSet

Example

Set bOk = SqlContextSetToForm ( hSql, hWndMyForm)

SqlDirectoryByName Syntax

bOk = SqlDirectoryByName ( strServerName, strArrayNames )

Description

Returns the database names on the specified server.

Parameters

strServerName

String. The name of a server.

strArrayNames

String Array. The name of an array of strings containing database names.

Return Value


Example

On SAM_AppStartup Call SqlDirectoryByName ( 'server1', strDatabaseNames )

SqlDisconnect Syntax

bOk = SqlDisconnect ( hSql )

Description

Disconnects from a database. Disconnecting the last Sql Handle from a database causes an implicit COMMIT of the database. Disconnect all Sql Handles before the application exits.

Parameters

hSql

Sql Handle. The handle that identifies the database connection to disconnect.


2-209

Chapter

2

Return Value


See Also

SqlConnect

Example

On SAM_AppExit Call SqlDisconnect ( hSqlPrimary )

SqlDropStoredCmd Syntax

bOk = SqlDropStoredCmd ( hSql, strName )

Description

Deletes a stored command from a SQLBase database.

Parameters

hSql


strName

String. The name of the stored command to delete.

Return Value


See Also

SqlRetrieve SqlStore

Example

Call SqlDropStoredCmd ( hSqlPrimary, 'PRODUCTS )

SqlError Syntax

nError = SqlError ( hSql )

Description

Returns the most recent error code for the specified Sql Handle. SqlError is not useful after a call to SqlImmediate because SqlImmediate does not return a handle that you can use as the parameter for SqlError.

Parameters

hSql

Return Value

nError is the error code returned. It is equal to zero (0) if no error occurred.

See Also

SqlExtractArgs

Example

Set nSqlError = SqlError ( hSqlPrimary )

Sql Handle. The handle on which an error occurred.

SqlErrorText Syntax

bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength )

Description

Gets the error reason or remedy for the specified error code from ERROR.SQL. Call SqlError to get the most recent error code. When your application detects an error condition, you can use the error code returned by SqlError to look up the error reason and remedy with SqlErrorText.


Parameters

nError

Number. A SQLBase error code.

nType

Number. Specify one or both (by combining them with the OR (|) operator) of these constants: Constant

Description

SQLERROR_Reason

Retrieve error code reason.

SQLERROR_Remedy

Retrieve error message remedy.

strError

Receive String. The reason or remedy explanation.

nLength

Number. The maximum length of strError.

nRealLength

Receive Number. The actual length of strError.

Return Value


See Also

SqlError SqlGetErrorText SqlGetErrorTextX

Example

Set bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength )

SqlExecute Syntax

bOk = SqlExecute ( hSql )

Description

Executes a SQL statement that was prepared with SqlPrepare or retrieved with SqlRetrieve. SqlExecute does not fetch data. To fetch data, call one of the SqlFetch* functions: SqlFetchNext, SqlFetchPrevious, or SqlFetchRow. Bind variables are sent to the database when you call SqlExecute. 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 ' and 'ADJUSTING ' clauses to UPDATE, DELETE or INSERT result set rows.

Parameters

hSql

Return Value


See Also

SqlOpen

Example

Call SqlExecute ( hSqlPrimary )

Sql Handle. The handle associated with a SQL statement.


2-211

Chapter

2

SqlExecutionPlan Syntax

bOk = SqlExecutionPlan ( hSql, strString, nLength )

Description

Gets the execution plan for a compiled SQL statement. An execution plan shows the tables, views, indexes, and optimizations for the SQL statement. Tables and views are listed in the order in which they are processed.

Parameters

hSql

Sql Handle. The handle associated with a compiled SQL statement.

strString

String. The execution plan.

nLength

Number. The maximum length of the execution plan.

Return Value


Example

Set bOk = SqlExecutionPlan ( hSql, strString, nLength )

SqlExists Syntax

bOk = SqlExists ( strSelect, bExists )

Description

Determines whether a row exists. SqlExists uses the values of the SqlDatabase, SqlUser, and SqlPassword variables to connect to a database, and uses an internal Sql Handle to execute the specified query.

Parameters

strSelect

String. The SELECT statement that establishes the existence of a row.

bExists

Receive Boolean. TRUE if the row exists and FALSE if it does not.

Return Value

bOk is TRUE if strSelect is correct and executable and FALSE otherwise.

Example

Call SqlExists ( 'SELECT * FROM ' || strTable || 'WHERE ' || strExistsColumn || ' = ' || '\'' || strExistsObject || '\'', bExists )

SqlExtractArgs Syntax

bOk = SqlExtractArgs ( wParam, lParam, hSql, nError, nPos )

Description

Extracts information from the SAM_SqlError wParam and lParam arguments. Call this function only while processing a SAM_SqlError message which is sent when an error occurs while executing a SQL function.


Parameters

wParam

Number. The value of the wParam argument of the SAM_SqlError message.

lParam

Number. The value of the lParam argument of the SAM_SqlError message.

hSql

Receive Sql Handle. The handle of the function that got an error. Centura extracts this value from the wParam argument.

nError

Receive Number. The error code. Centura extracts this value from the low-order word of the lParam argument.

nPos

Receive number. The error position, if relevant to the function call. Centura extracts this value from the high-order word of the lParam argument.

Return Value


See Also

SqlError SqlGetErrorPosition

Example

Call SqlExtractArgs ( wParam, lParam, hSqlError, nSqlError, nErrorPos )

SqlFetchNext Syntax

bOk = SqlFetchNext ( hSql, nInd )

Description

Fetches the next row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen.

Parameters

hSql


nInd

Receive Number. The fetch return code is one of the FETCH_* values.

Return Value

bOk is TRUE if another row was fetched and FALSE if no row was fetched. SqlFetchNext does not return FALSE and Fetch indicatior does not show EOF until you attempt to fetch past the last row.

See Also

SqlFetchPrevious SqlFetchRow

Example

Call SqlFetchNext ( hSqlPrimary, nRetVal )


2-213

Chapter

2

SqlFetchPrevious Syntax

bOk = SqlFetchPrevious ( hSql, nInd )

Description

Fetches the previous row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen.

Parameters

hSql


nInd


Return Value

bOk is TRUE if there is another row to fetch and FALSE otherwise.

See Also

SqlFetchNext SqlFetchRow

Example

Call SqlFetchPrevious ( hSqlPrimary, nRetVal)

SqlFetchRow Syntax

bOk = SqlFetchRow ( hSql, nRow, nInd )

Description

Fetches a row according to an absolute row position. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen.

Parameters

hSql


nRoNumber. The row number of the row to fetch. nInd


Return Value

bOk is TRUE if nRow could be fetched and FALSE otherwise.

See Also

SqlFetchNext SqlFetchPrevious

Example

Call SqlFetchRow ( hSqlPrimary, lParam, nRetVal )

SqlGetError Syntax

bOk = SqlGetError( hSql, nError, strErrorString )

Description

Turns off backend error mapping and reports real backend errors.


Parameters

Return Value

hSql


nError

Number. The error number.

strErrorString

String. The error text.

bOk is TRUE if the function succeeds and FALSE if it fails. You specify the Sql Handle in hSql and SqlGetError returns the last error number and error text in nError and strErrorString. If the backend is SQLBase, this function does the same thing as calling SqlError and SqlGetErrorText.

Example

Set bOk = SqlGetError( hSql, nError, strErrorString )

SqlGetErrorPosition Syntax

bOk = SqlGetErrorPosition ( hSql, nPos )

Description

Returns the offset of the error position within a SQL statement. After a SqlPrepare, the error position points to the place in the SQL statement where Centura detected aSyntax error. The first character position in the SQL statement is zero (0).

Parameters

hSql


nPos

Receive Number. The position in the SQL statement where aSyntax error occurred.

Return Value


See Also

SqlExtractArgs

Example

Call SqlGetErrorPosition ( hSqlPrimary, nErrorPos )

SqlGetErrorText Syntax

bOk = SqlGetErrorText ( nError, strText ) or strText = SqlGetErrorTextX ( nError )

Description

Gets the message text for a SQL error number from ERROR.SQL.

Parameters

nError

Number. The error number.

strText

Receive String. The error text.

Return Value

bOk is TRUE if the function succeeds and FALSE if it fails. strText is the message text for nError. Centura Builder Function Reference

2-215

Chapter

2

See Also

SqlErrorText SqlExtractArgs

Example

Call SqlGetErrorText ( nError, strText ) or Set strText = SqlGetErrorTextX ( nError )

SqlGetErrorTextX Syntax

strText = SqlGetErrorTextX (nError)

Description

When the user chooses the Insert menu item, this example compiles a SQL statement for execution. To process any invalid SQL statements and trap the error (bypassing the default error processing), add the “When SqlError” statement with a FALSE return before the SqlPrepare. When SqlPrepare returns FALSE, call SqlError to get the error number, call SqlGetErrorTextX to get the error description, and call SqlGetErrorPosition to get the character position where theSyntax error was detected.

Example

Set strErrorText = SqlGetErrorTextX ( nSqlError )

SqlGetLastStatement Syntax

sSqlStatement = SqlGetLastStatement( )

Description

Returns the last SQL statement passed to a SqlXxxx function for any cursor. The statement returned is the same statement that would be shown in the default SQL Error dialog box. Note: The statement is global for all cursors, therefore, if you get a SQL error after another cursor has had a statement prepared the statement returned may not be the one prepared for the handle.

Parameters

No parameters.

Return Value

sSqlStatement contains the last SQL statement.

Example

When SqlError Set sStatement = SqlGetLastStatement()


SqlGetModifiedRows Syntax

bOk = SqlGetModifiedRows ( hSql, nCount )

Description

Returns the number of rows affected by the most recent INSERT, UPDATE, or DELETE statement.

Parameters

hSql

Sql Handle. The handle of a SQL statement.

nCount

Receive Number. The number of rows affected.

Return Value


Example

Set bOk = SqlGetModifiedRows ( hSql, nCount )

SqlGetParameter Syntax

bOk = SqlGetParameter ( hSql, nParameter, nNumber, strString )

Description

Gets the value of a database parameter. This function returns the parameter value in nNumber or strString as appropriate for the data type of the parameter.

Parameters

hSql


nParameter

Number. The database parameter. Specify one of the DBP_* constants.

nNumber

Receive number. The value (TRUE or FALSE) of the parameter. If nParameter is DBP_BRAND, nNumber is one of the DBV_BRAND_* values.

strString

Receive string. If you specify DBP_VERSION in nParameter, this is the version number.

Return Value


See Also

SqlGetParameterAll SqlSetParameter SqlSetParameterAll

Example

On SAM_AppStartup Call SqlGetParameter ( hSqlPrimary, DBP_LOCKWAITTIMEOUT, nTimeout, strNull )


2-217

Chapter

2

SqlGetParameterAll Syntax

bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

Description

Gets the value of a database parameter identified by a SQLP* constant value defined in SQL.H. This function returns the parameter value in nNumber or strString as appropriate for the data type of the parameter. 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

Number. The database parameter. Specify the value of one of the SQLP* constants defined in SQL.H.

nNumber

Receive number. The value of nparameter it it is a number. Receive string. The value of nParameter if it is a string.

bNumber

Boolean. If TRUE, the parameter value is returned in nNumber. If FALSE, the parameter value is returned in strString.

Return Value


See Also

SqlGetParameter SqlSetParameter SqlSetParameterAll

Example

Set bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

SqlGetResultSetCount Syntax

bOk = SqlGetResultSetCount ( hSql, nCount )

Description

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.


You must call SqlExecute before SqlGetResultSetCount. Parameters

hSql

Sql Handle. A handle associated with a result set.

nCount

Receive Number. The number of rows in the result set.

Return Value


Example

Actions Call SqlPrepare ( hSqlPrimary, strSqlTblWindow ) Call SqlExecute ( hSqlPrimary ) Call SqlGetResultSetCount ( hSqlPrimary, nRowCount )

SqlGetRollbackFlag Syntax

bOk = SqlGetRollbackFlag ( hSql, bRollbackFlag )

Description

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

Sql Handle. The handle associated with the function call that got an error.

bRollbackFlag

Receive Boolean. TRUE if a rollback occurred and FALSE otherwise.

Return Value


Example

Call SqlGetRollbackFlag ( hSqlError, bRollbackFlag ) If bRollbackFlag ! Execute code to handle rolled back ! transaction

SqlImmediate Syntax

bOk = SqlImmediate ( strSqlCommand )

Description

Prepares and executes a SQL statement. SqlImmediate actually performs a SqlConnect, a SqlPrepare, a SqlExecute, and for SELECT statements, a SqlFetchNext. The first time you call SqlImmediate, Centura performs all of these functions. On later calls, SqlConnect is not performed if not needed.


2-219

Chapter

2

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

Return Value


See Also

SqlClearImmediate

Example

Call SqlImmediate ( 'INSERT INTO COMPANY ( COMPANY )' ||'VALUES ( :frmMain dfCompany )' )

String. The SQL statement to prepare and execute. This statement cannot have more than 128 bind variables and more than 128 INTO variables.

SqlImmediateContext Syntax

bOk = SqlImmediateContext ( strSqlStatement )

Description

Prepares and executes a SQL statement, and evaluates any bind or INTO variables in the context of the window identified by hWndForm. Call this function in a class to perform SQL processing for the current window without fully qualifying bind and INTO variables. This function is also useful for global functions. Important: When you call SqlImmediateContext, the context for bind variables and INTO variables is always hWndForm. If you call SqlImmediateContext in an internal function, window function, or class function, Centura does not recognize local variables or parameters that you use as bind variables and INTO variables.

Parameters

strSqlStatement

Return Value


See Also

SqlContextClear SqlContextSet

Example

Set bOk = SqlImmediateContext ( strSqlStatement )


String. A SQL statement.

SqlOpen Syntax

bOk = SqlOpen ( hSql, strCursorName )

Description

Names a cursor and executes a SQL statement. Use this function to perform INSERTs, UPDATEs, and DELETEs on the current row. Call SqlOpen after SqlPrepare and before any of the SqlFetch* commands.

Parameters

hSql

Sql Handle. The handle associated with the SqlPrepare.

strCursorName

String. A string containing the cursor name. Specify this name in the 'CURRENT OF ' or 'ADJUSTING ' 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

SqlClose SqlExecute

Example

Set bOk = SqlOpen ( hSql, strCursorName )

SqlPLSQLCommand Syntax

bOk = SqlPLSQLCommand ( hSqlHandle, strCommand )

Description

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

2

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

Sql Handle. The connected SQL Handle to an Oracle database.

strCommand

String. Command string used to invoke a PL/SQL procedure.

Return Value

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

Example

If NOT SqlPLSQLCommand( hSql, 'INVOICES.INSERT_INVOICE (ninv_id, strClient, dt_inv_dt, nitem_No, nQnty, nAmt, nNum)' ) Set nSqlError = SqlError ( hSql! See ORACLE DOCUMENTATION ! for Error Listings

Note: If SqlPLSQLCommand receives an ‘Invalid Object’ error from ORACLE when executing a stored procedure, this means that a table referenced by the procedure was modified. To fix this problem, you need to force a recompile of that procedure. SqlPlSQLCommand does not automatically do this.

SqlPrepare Syntax

bOk = SqlPrepare ( hSql, strSqlStatement )

Description

Compiles a SQL statement for execution. Compiling includes: •

Checking theSyntax of the SQL statement.

•

Checking the system catalog.

•

Processing a SELECT statement's INTO clause. An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 255 INTO variables per SQL statement.

•

Identifying bind variables in the SQL statement. Bind variables contain input data for the statement. You can specify up to 2558 bind variables per SQL statement.

Follow this function with a SqlOpen, SqlExecute, SalTblDoInserts, SalTblDoUpdates, or SalTblDoDeletes, or fetches. Parameters

Return Value

hSql


strSqlStatement

String. The SQL statement to compile.



2-223

Chapter

2

See Also

SqlExecute

Example

Call SqlPrepare ( hSqlPrimary, 'INSERT INTO CUSTOMER ' || ' ( CUSTOMER ) VALUES ' ||'( :frmCustomer.dfCustomer )' )

SqlPrepareAndExecute Syntax

bOk = SqlPrepareAndExecute ( hSql, strSqlStatement )

Description

Compiles and executes a SQL statement. Compiling includes: •

Checking theSyntax of the SQL statement.

•

Checking the system catalog.

•

Processing a SELECT statement's INTO clause. An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 128 INTO variables per SQL statement.

•

Parameters

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.

hSql


strSqlStatement

String. The SQL statement to compile and execute.

Return Value


See Also

SqlExecute SqlPrepare

Example

Set bOk = SqlPrepareAndExecute ( hSql, 'Select name from' || ' employees into :df1' ) If bOk Call SqlFetchNext ( hSql, nInd )


SqlRetrieve Syntax

bOk = SqlRetrieve ( hSql, strName, strBindList, strIntoList )

Description

Retrieves a SQLBase compiled command. To execute the command, you need only call SqlExecute. You do not need to compile the command with SqlPrepare because the command is compiled when it is stored with SqlStore.

Parameters

hSql


strName

String. The name of the compiled command.

strBindList

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.

strIntoList

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.

Return Value


See Also

SqlDropStoredCmd SqlStore

Example

Call SqlRetrieve ( hSqlPrimary, 'PRODUCTS', ':nPrice', ':strLBItem' )

SqlSetInMessage Syntax

bOk = SqlSetInMessage ( hSql, nSize )

Description

Sets the size (in bytes) of the input message buffer for the specified Sql Handle. The input message buffer holds input for the application (such as the result of a query). There is one input message buffer per connected Sql Handle on the client computer. The database server (or gateway) maintains one input message buffer that is the size of the largest input message buffer on the client computer. When fetching data, as many rows as possible are compacted into one input message buffer. Each FETCH reads the next row from the input message buffer until they are exhausted. At this point, if you are accessing a SQLBase database, SQLBase transparently fetches the next input buffer of rows depending on the isolation level.


2-225

Chapter

2

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

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.

Return Value


See Also

SqlSetOutMessage

Example

On SAM_AppStartup Call SqlConnect ( hSqlPrimary ) Call SqlSetInMessage ( hSqlPrimary, 10000 )

SqlSetIsolationLevel Syntax

bOk = SqlSetIsolationLevel ( hSql, strIsolation )

Description

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

String. The isolation level to set. Specify one of these values: CS RL RO RR

Cursor Stability Release Locks Read Only Read Repeatability

Return Value


Example

On SAM_AppStartup Call SqlSetIsolationLevel ( hSqlPrimary, 'RL' )



SqlSetLockTimeout Syntax

bOk = SqlSetLockTimeout ( hSql, nTimeout )

Description

Specifies the maximum time to wait to acquire a lock. After the specified time elapses, a timeout occurs and the transaction rolls back.

Parameters

hSql

Sql Handle. A handle that identifies a database connection; the cursor on which you want to set a lock timeout value.

nTimeout

Number. The timeout period in seconds. Valid values include 1 (wait forever), 0 (never wait), and values up to and including 1800 (30 minutes). The default is 300.

Return Value


Example

On SAM_AppStartup Call SqlSetLockTimeout ( hSqlPrimary, 10 )

SqlSetLongBindDatatype Syntax

bOk = SqlSetLongBindDatatype( nBindVarNumber, nDatatype )

Description

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

Number. The bind variable to set. The first bind variable in the SQL statement is 1, the second is 2, and so on.

nDatatype

Number. The data type: 22 = text 23 = binary 24 = char \ long varchar > 254

Return Value

bOk is TRUE if this function succeeds and FALSE if it fails.

Example

Call SqlSetLongBindDatatype( 1, DT_Binary )


2-227

Chapter

2

SqlSetOutMessage Syntax

bOk = SqlSetOutMessage ( hSql, nSize )

Description

Sets the size (in bytes) of the output message buffer for a specified Sql Handle. The output message buffer holds output from the application (such as a SQL command to compile or rows of data to insert into a database). There is an output message buffer for each connected Sql Handle on the client computer. At the same time, the database server (or gateway) maintains an output message buffer that is the size of the largest of its clients' output message buffers. A large output message buffer does not necessarily improve performance because the buffer only needs to be large enough to hold the largest SQL command to compile or the largest row of data to insert. (Rows are always sent to the database and inserted individually.) A large output message buffer can allocate space unnecessarily on both the client and the server, and it does not reduce network traffic.

Parameters

hSql


nSize

Number. The size (in bytes) of the output message buffer. The default is 1 Kbyte and the maximum is 32 Kbytes.

Return Value


See Also

SqlSetInMessage

Example

On SAM_AppStartup Call SqlConnect ( hSqlPrimary ) Call SqlSetOutMessage ( hSqlPrimary, 1500 )

SqlSetParameter Syntax

bOk = SqlSetParameter ( hSql, nParameter, nNumber, strString )

Description

Sets the value of a database parameter. Use the number (nNumber) and string (strString) arguments as appropriate for the data type of the parameter.

Parameters

hSql


nParameter

Number. The database parameter to set. Specify one of the DBP_* constants.

nNumber

Number. The value of nParameter. Specify TRUE or FALSE for all but DBP_LOCKWAITTIMEOUT, for which you must specify a value in seconds.

strString

String. The value of nParameter.


Return Value


See Also

SqlGetParameter SqlGetParameterAll SqlSetParameterAll

Example

Call SqlSetParameter ( hSqlPrimary, DBP_PRESERVE, TRUE, strNull )

SqlSetParameterAll Syntax

bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

Description

Sets the value of a database parameter identified by a SQLP* constant value defined in SQL.H. This function uses the number (nNumber) and string (strString) parameters as appropriate depending on the data type of the value of the parameter.

Parameters

hSql

Sql Handle. The handle that identifies a database connection.

nParameter

Number. The database parameter to set. Specify the value of one of the SQLP* constants defined in SQL.H.

nNumber

Number. The value of nParameter if it is a number.

strString

String. The value of nParameter if it is a string.

bNumber

If TRUE, the parameter value is in nNumber. If FALSE, the parameter value is in strString.

Return Value


See Also

SqlGetParameter SqlGetParameterAll SqlSetParameter

Example

Set bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

SqlSetResultSet Syntax

bOk = SqlSetResultSet ( hSql, bSet )

Description

Turns result set mode on or off. Result set mode is on by default in Centura.

Parameters

Return Value

hSql


bSet

Boolean. Turns result set mode on (TRUE) or off (FALSE).

bOk is TRUE if the function succeeds and FALSE if it fails. Centura Builder Function Reference

2-229

Chapter

2

Example

Call SqlSetResultSet ( hSqlPrimary, FALSE )

SqlStore Syntax

bOk = SqlStore ( hSql, strName, strSqlCommand )

Description

Stores and names a SQLBase compiled SQL statement. You do not need to call SqlPrepare before calling SqlStore. SqlStore compiles the SQL statement. You can specify up to 128 bind variables. Use numeric bind variables in the SQL statement, not variable names. For example: "SELECT * FROM PRESIDENT WHERE LASTNAME = :1 AND AGE > :2;". When you retrieve the stored command with SqlRetrieve, you specify the bind variable names in the INTO clause. For example, specify ‘:dfLastName’ and ‘:dfAge’ where dfLastName and dfAge are data fields on a form window. Before 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

Return Value

hSql


strName

String. The name of the stored command.

strSqlCommand

String. The SQL statement to compile and store.



See Also

SqlDropStoredCmd SqlRetrieve

Example

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

Description

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.

Parameters

hArySource

Source array to append onto the end of the target.

hAryTarget

Target array, source array will be appended onto this array.

nDataType

Data type of both arrays. Options are: DT_Boolean DT_DateTime DT_Number DT_String DT_Handle

Return

Number: The number of total items in the target array after the append operation, if successful, or negative if an error occurs.

Example

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'


2-231

Chapter

2

VisArrayCopy Syntax

nNumItems = VisArrayCopy (hArySource, hAryTarget, nDataType) Number | String | Date/Time: hArySource[*] Number | String | Date/Time: hAryTarget[*] Number: nDataType

Description

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.

Parameters

hArySource

Source array to copy into the target.

hAryTarget

Target array, source array will be copied into this array, replacing its current contents.

nDataType

Data type of both arrays. Options are: DT_Boolean DT_DateTime DT_Number DT_String DT_Handle

Return

Number: The number of items in the target array, if successful, or negative if an error occurs.

Example

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'


VisArrayDeleteItem Syntax

nNumItems = VisArrayDeleteItem (hAry, nIndex, nDataType) Number | String | Date/Time: hAry[*] Number: nIndex Number: nDataType

Description

Deletes an item from an array. All subsequent items will be moved up in the array. The array cannot be a multi-dimensional array.

Parameters

hAry

Array to delete item from.

nIndex

Index of item to delete.

nDataType

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 deletion, if successful, or negative if an error occurs.

Example

Variables String: sString[*] ... Actions Call VisArrayDeleteItem (sString, 3, DT_String)

VisArrayFillDateTime Syntax

bOk = VisArrayFillDateTime (dtDateTimes, dtValue, nCount) Date/Time: dtDateTimes[*] Date/Time: dtValue Number: nCount

Description

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.

Parameters

dtDateTimes

Date/Time array to fill.

dtValue

Value to fill in each element of array.

nCount

Number of items to fill.

Return

Boolean: TRUE if successful, or FALSE if an error occurs.


2-233

Chapter

2

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

Description

Fills a number array with a specified value. This function is useful for initializing an array. The array cannot be a multi-dimensional array.

Parameters

nNumbers

Number array to fill.

nValue

Value to fill in each element of array.

nCount


Return


Example

Variables Number: nSample[*] ... Actions Call VisArrayFillNumber (nSample, NUMBER_Null, 5)

VisArrayFillString Syntax

bOk = VisArrayFillString (sStrings, sValue, nCount) String: sStrings[*] String: sValue Number: nCount

Description

Fills a string array with a specified string. This function is useful for initializing an array. The array cannot be a multi-dimensional array.

Parameters

sStrings

String array to fill.

sValue

String value to fill in each element of array.

nCount


Return



Related Functions Example

Variables String: sSample[*] ... Actions Call VisArrayFillString (sSample, '', 5)

VisArrayFindDateTime Syntax

nIndex = VisArrayFindDateTime (dtDateTimes, dtSearchFor) Date/Time: dtDateTimes[*] Date/Time: dtSearchFor

Description

Locates a date/time value within an array. The array cannot be a multi-dimensional array.

Parameters

dtDateTimes

Date/Time array to search.

dtSearchFor

Date/Time value to search for.

Return

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

Description

Locates a number within an array. The array cannot be a multi-dimensional array.

Parameters

nNumbers

Number array to search.


2-235

Chapter

2

nSearchFor Return

Number to search for.

Number: The index of the item found, if successful, or negative if not found. 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

Description

Locates a string within an array. The entire specified string is compared to each array item. The array cannot be a multi-dimensional array.

Parameters

sStrings

String array to search.

sSearchFor

String to search for.

Return

Number: The index of the item found, if successful, or negative if not found.

Example

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

Description

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.

Parameters

hAry

Array to insert item into.

nIndex

Index number where item should be inserted.

nDataType

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.

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

Description

Sorts an array in either ascending or descending order. The array cannot be a multidimensional array.

Parameters

hAry

Array to sort. Centura Builder Function Reference

2-237

Chapter

2

nSortOrder

Flag indicating sort order.

nDataType

SORT_Ascending SORT_Descending Indicates the data type for the array.

Return

Number: The number of items in the array, if successful, or negative if an error occurs.

Example

Variables String: sDirs[*] ... Actions Call VisArraySort (sDirs, SORT_Ascending, DT_String)

VisDebugAssert Syntax

bOk = VisDebugAssert (bExpression, sDebugString) Boolean: bExpression String: sDebugString

Description

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.

Parameters

bExpression

Condition to be tested. The condition may be a constant, expression, or variable.

sDebugString

Debug message to display if condition is FALSE. The Centura name of the current window will be prepended to sDebugString before displaying.

Return

Boolean: Always returns TRUE.

Example

Variables Window Handle: hWnd ... Actions Set hWnd = SalCreateWindow (dbTest, dbParent) Call VisDebugAssert (hWnd, 'dbTest not created')


VisDebugBeginTime Syntax

bOk = VisDebugBeginTime ()

Description

Begins timing an operation. VisDebugBeginTime must be called before VisDebugSetTime or VisDebugEndTime.

Parameters

No parameters.

Return


Related Functions VisDebugEndTime, VisDebugSetTime Example

Actions Call VisDebugBeginTime () Call SqlPrepare (hSql, 'Select...') Call VisDebugSetTime ('SqlPrepare') Call SqlExecute (hSql) Call VisDebugSetTime ('SqlExecute')

VisDebugEndTime Syntax

bOk = VisDebugEndTime (sContext, nDebugLevel) String: sContext Number: nDebugLevel

Description

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.

Parameters

sContext

Context string describing the total time.

nDebugLevel

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.

Return


Related Functions VisDebugBeginTime, VisDebugSetTime Example

Actions Call VisDebugBeginTime () Call SqlPrepare (hSql, 'Select...')


2-239

Chapter

2

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

nDebugFlags = VisDebugGetFlags ()

Description

Retrieves the current debug flags.

Parameters

No parameters.

Return

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

bOk = VisDebugSetFlags (nDebugFlags, bMode) Number: nDebugFlags Boolean: bMode

Description

Sets debug flags.

Parameters

nDebugFlags

Bit flags to set or clear. May be any of the following: DBF_IncrementalTime


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

bOk = VisDebugSetLevel (nDebugLevel) Number: nDebugLevel

Description

Sets the current debug level. The debug level allows selective debug messages to be displayed.

Parameters

nDebugLevel

Return


Example

Actions

Current debug level. Debug messages must be equal or greater than the current debug level to be displayed.

Call VisDebugSetLevel (0)

VisDebugSetTime Syntax

bOk = VisDebugSetTime (sContext) String: sContext

Description

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.

Parameters

sContext

Return


Context string describing the time interval.

Related Functions VisDebugBeginTime, VisDebugEndTime Example

Set bOk = VisDebugSetTime (sContext)


2-241

Chapter

2

VisDebugString Syntax

bOk = VisDebugString (sDebugString, nDebugLevel) String: sDebugString Number: nDebugLevel

Description

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.

Parameters

sString

String to write to debugging terminal.

nDebugLevel

Debug level. Specify zero to always display the message. Typically, the higher the debug level, the greater the number of debug messages displayed.

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

Description

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.

Parameters

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.

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

String: A string containing the full file name (drive, path, and file name), or a null string if an error occurs.

Example

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[*]

Description

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.

Parameters

sDirSpec

Directory to search, must include wildcard characters.

sDirs

Array to contain the subdirectories.

dtDateTimes

Array to contain the date/time each subdirectory was created.

nAttributes

Array to contain the attributes of each subdirectory.

Returns

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

2

Set nCount = VisDosEnumDirInfo ('c:\\windows\\*.*', sDirs, dtDateTimes, nAttributes If nCount >0

VisDosEnumDirs Syntax

nNumDirs = VisDosEnumDirs (sDirSpec, sDirs) String: sDirSpec Receive String: sDirs[*]

Description

Retrieves all subdirectories within a given directory into a Centura array.

Parameters

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.

sDirs

Array to contain the subdirectories. Note that only directory names are returned, no leading or trailing backslashes.

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

nNumDrives = VisDosEnumDrives (sDrives) Receive String: sDrives[*]

Description

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

sDrives

Return

Number: The number of available drives returned in the specified array.

Array to contain the available drive letters (A:-Z:). The colon is always included.

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[*]

Description

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.

Parameters

sDirSpec

Directory to search, must include wildcard characters.

nAttribute

Attribute bits to match. See the table below for a list of attributes.

sFiles

Array to contain the file names.

nSizes

Array to contain the size of each file.

dtDateTimes

Array to contain the date/time each file was created.

nAttributes

Array to contain the attributes of each file. May be one or more of the following values: FA_Standard


2-245

Chapter

2

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[*]

Description

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.

Parameters

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.

nAttributes

Attributes bits to match. This parameter may be one or more of the following values: FA_Standard FA_ReadOnly FA_Hidden


FA_System FA_Archive Array to contain the file names. Note that only file names are returned, no drive or paths.

sFiles Return

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[*]

Description

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.

Parameters

sDevices

Array to contain the connected devices (A:-Z:, LPT1:-LPT3:).

sNetNames

Array to contain the network names.

Return

Number: The number of devices connected, or negative if an error occurs.

Related Functions VisDosNetConnect, VisDosNetDisconnect


2-247

Chapter

2

Example

Variables Number: nCount String: sDevices[*] String: sNetPaths[*] ... Actions Set nCount = VisDosEnumNetConnections (sDevices, sNetNames) If nCount > 0 Call VisListArrayPopulate (lbDevices, sDevice)

VisDosEnumPath Syntax

nNumPaths = VisDosEnumPath (sDirs) Receive String: sDirs[*]

Description

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

sDirs

Return

Number: The number of valid directories found.

Array to contain the PATH directories.

Related Functions VisDosEnumFiles Example

Variables String: sDirs[*] ... Actions Set nCount = VisDosEnumPath (sDirs) If nCount > 0 Call VisListArrayPopulate (lbPath, sDirs)


VisDosEnumsShortDirInfo Syntax

nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames, arrDateTime, arrAttribs )

Description

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.

Parameters

sDirName

Parent Directory to retrieve subdirectory information from. Must include wildcard characters.

arrLongDirNames

Handle to array of long name subdirectories

arrShortDirNames

Handle to array of short name directories

arrDateTime

Handle to array of Date/Times when each subdirectory was created.

arrAttribs

Handle to array of attributes for each subdirectory.

Return

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

nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames )

Description


Parameters

sDirName

Parent Directory to retrieve subdirectory information from. Must include wildcard characters.

arrLongDirNames

Handle to array of long name subdirectories

arrShortDirNames

Handle to array of short name directories

Return

Returns the number of subdirectories in the arrays or negative if an error occured.


2-249

Chapter

2

Related Functions VisDosEnumsShortDirInfo VisDosEnumsShortFileInfo VisDosEnumsShortFiles VisDosIsParent Example

Set nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames )

VisDosEnumsShortFileInfo Syntax

nSubFileNum = VisDosEnumsShortFileInfo (sDirName, nAttribBits, arrLongFileNames, arrShortFileNames, arrSizes, arrDateTime, arrAttribs )

Description

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.

Parameters

sDirName

Directory to retrieve file information from. Must include wildcard characters.

nAttribBits

Attribute bits to match.

arrLongFileNames

Handle to array of long file names

arrShortFileNames

Handle to array of short file names

arrSizes

Handle to array of file sizes.

arrDateTime

Handle to array of Date/Times for each file.

arrAttribs

Handle to array of attributes for each file.

Return

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

nSubFileNum = VisDosEnumsShortFiles (sDirName, nAttribBits, arrLongFileNames, arrShortFileNames )

Description


Parameters

sDirName

Directory to retrieve file information from. Must include wildcard characters.

nAttribBits

Attribute bits to match.

arrLongFileNames

Handle to array of long file names

arrShortFileNames

Handle to array of short file names

Return

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

bOk = VisDosExist (sFileSpec) String: sFileSpec

Description

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.

Parameters

sFileSpec

Return

Boolean: TRUE if sFileSpec exists and FALSE if it does not.

Example

If VisDosExist ... If VisDosExist ... If VisDosExist ... If VisDosExist ... If VisDosExist

Drive, directory, or file to test. It may contain a drive letter, directory, file name, full path or wildcard characters (? and *).

('c:') ('c:\\dos') ('c:\\dos\\') ('c:\\dos\\command.com') ('c:\\dos\\*.exe')


2-251

Chapter

2

VisDosGetCurDir Syntax

sDir = VisDosGetCurDir (sDrive)String: sDrive

Description

Returns the current directory of a specified drive.

Parameters

sDrive

Return

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.

Example

Variables

Drive letter (A:-Z:) to retrieve the current directory for.

String: sCurDir ... Actions Set sCurDir = VisDosGetCurDir (VisDosGetCurDrive()) If VisDosEnumFiles (sCurDir || '*.*',FA_Standard, sFiles) VisListArrayPopulate (lbFiles, sFiles)

VisDosGetDriveSize Syntax

nErrCode = VisDosGetDriveSize (sDrive, nTotalSpace, nFreeSpace) String: sDrive Receive Number: nTotalSpace Receive Number: nFreeSpace

Description

Returns total space and available space on a drive.

Parameters

sDrive

Drive letter to retrieve space information for, may include both a drive letter and colon.

nTotalSpace

Total space on specified drive.

nFreeSpace

Total available space on specified drive.

Return

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

nTypeFlags = VisDosGetDriveType (sDrive) String: sDrive

Description

Gets the type of drive specified.

Parameters

sDrive

Drive letter to retrieve space information for, may include both a drive letter and colon.

Return

Number

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

2

VisDosGetEnvString Syntax

sEnvString = VisDosGetEnvString (sKeyName) String: sKeyName

Description

Returns an environment string based on a keyword. The keyword is the text before the = sign in the environment. For example, PATH = C:\DOS.

Parameters

sKeyName

Return

String: The environment variable contents. If the keyword cannot be found, a null string is returned.

Example

Variables


String: sTempDir ... Actions Set sTempDir = VisDosGetEnvString ('TEMP')

VisDosGetFlags Syntax

nFlags = VisDosGetFlags ()

Description

Returns the state of DOS flags.

Parameters

No parameters.

Return

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

sNetName = VisDosGetNetName (sDevice) String: sDevice

Description

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.

Parameters

sDevice

Return

String: The network name, if successful, or a null string if an error occurs.

Pointer to device name (A:-Z:, LPT1:-LPT3:).

Related Functions VisDosEnumNetConnections, VisDosNetConnect, VisDosNetDisconnect Example

Variables String: sNetName ... Actions Set sNetName = VisDosGetNetName ('f:')

VisDosGetVersion Syntax

nVersionNum = VisDosGetVersion ()

Description

Returns the MS-DOS version number.

Parameters

None.

Return

Number: Both the major and minor (3.31) DOS version number.

Example

Variables Number: nVersion ... Actions Set nVersion = VisDosGetVersion ()


2-255

Chapter

2

VisDosGetVolumeLabel Syntax

sLabel = VisDosGetVolumeLabel (sDrive) String: sDrive

Description

Returns the volume label of a specified drive.

Parameters

sDrive

Return

String: The volume label of the specified drive, or negative if an error occurs.

Drive to retrieve volume label for.

Related Functions VisDosSetVolumeLabel Example

Variables String: sLabel ... Actions Set sLabel = VisDosGetVolumeLabel ('c:')

VisDosIsParent Syntax

bOk = VisDosIsParent (sDirSpec) String: sDirSpec

Description

Return indicator if directory contains subdirectories.

Parameters

sDirSpec

Return

Boolean. TRUE if directory contains subdirectories, FALSE if not.

Directory to test.

Related Functions VisDosEnumsShortDirInfo VisDosEnumsShortDirs VisDosEnumsShortFileInfo VisDosEnumsShortFiles Example

Set bOk = VisDosIsParent (sDirSpec)


VisDosMakeAllDir Syntax

nErrCode = VisDosMakeAllDir (sDir) String: sDir

Description

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.

Parameters

sDir

Returns


Example

Actions

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.

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

Description

Builds a full path from a drive, directory or file name. No existence check is performed on the result string.

Parameters

sDrive

Drive letter.

sDir

Directory.

sBase

Base portion of file name (8 characters before period).

sEx

tFile extension (must include period).

Return

String: The path after concatenating the drive, directory, and file name.

Related Functions VisDosSplitPath Example

Actions Set sFullName = VisDosMakePath ('c:', '\\dos\\', 'command', '.com') Centura Builder Function Reference

2-257

Chapter

2

VisDosNetConnect Syntax

nErrCode = VisDosNetConnect (sDevice, sNetName, sPassword) String: sDevice String: sNetName String: sPassword

Description

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.

Parameters

sDevice

Device name (A:-Z:, LPT1:-LPT3:).

sNetName

Network device (\\server\directory).

sPassword

Password to network device (optional).

Return


Related Functions VisDosEnumNetConnections, VisDosNetDisconnect Example

Actions If VisDosNetConnect ('f:','\\\\server\\data', 'cubswin') != VTERR_Ok

VisDosNetDisconnect Syntax

nErrCode = VisDosNetDisconnect (sDevice, bForce) String: sDevice Boolean: bForce

Description

Cancels a network connection.

Parameters

sDevice

Device name (A:-Z:, LPT1:-LPT3:).

bForce

TRUE to force open files and print jobs to be closed.

Return


Related Functions VisDosNetConnect Example

Actions Call VisDosNetDisconnect ('f:', TRUE)


VisDosSetFlags Syntax

nErrCode = VisDosSetFlags (nFlags, bState) Number: nFlags Boolean: bState

Description

Sets verify, break, or error mode flags.

Parameters

nFlags

Bits indicating flags to set. May be any combination of the following values. To combine bit values, use the bitwise OR (|) operator.

bState

TRUE to turn the flag on, FALSE to turn the flag off.

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

Description

Sets the volume label on a disk drive.

Parameters

sDrive

Drive to set volume label for.

sLabel

Volume label to set. Limited to 11 characters

Return


Related Functions VisDosGetVolumeLabel Example

If VisDosSetVolumeLabel ('c:', 'my_disk') != VTERR_Ok


2-259

Chapter

2

VisDosSplitPath Syntax

Void VisDosSplitPath (sFileSpec, sDrive, sDir, sBase, sExt) String: sFileSpec Receive String: sDrive Receive String: sDir Receive String: sBase Receive String: sExt

Description

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.

Parameters

sFileSpec

Full path specification to split.

sDrive

Drive letter including colon.

sDir

Directory always contains a leading and a trailing backslash (\DOS\).

sBase

Base portion of file name (8 characters before period).

sExt

File extension (always includes period).

Return

No return value

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

nErrCode = VisErrorRecovery (sCaption) String: sCaption

Description

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.

Parameters

sCaption

Return

Number: An action code depending on whether the user choose Retry or Abort pushbuttons:

Example

Caption of error recovery dialog.

If VisErrorRecovery ('Error') = ACTION_Abort Call SalQuit()

VisFileAppend Syntax

nErrCode = VisFileAppend (sSourceFile, sTargetFile) String: sSourceFile String: sTargetFile

Description

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.

Parameters

sSourceFile

Source file specification to append.

sTargetFile

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.

Return

Number: The number of files appended, or negative if an error occurs.

Related Functions VisFileCopy, VisFileRename Example

Actions If VisFileAppend ('*.txt', 'all.txt') <0 Call SalMessageBox ('Error Occurred', 'Error', MB_Ok)


2-261

Chapter

2

VisFileClose Syntax

nErrCode = VisFileClose (hFile) File Handle: hFile

Description

Closes a file opened with the VisFileOpen call. Cannot be used with a file handle returned from SalFileOpen.

Parameters

hFile

Return


Handle to file returned from VisFileOpen.

Related Functions VisFileOpen Example

Set nErrCode = VisFileClose (hFile)

VisFileCopy Syntax

nErrCode = VisFileCopy (sSourceFile, sTargetFile) String: sSourceFile String: sTargetFile

Description

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.

Parameters

sSourceFile

Source file to copy. File name specified may be in long format or in DOS 8.3 format.

sTargetFile

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.

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

sTempFileName = VisFileCreateTemp (sPrefix) String: sPrefix

Description

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.

Parameters

sPrefix

Return

String: A string containing drive, directory, and file name of the temporary file.

Example

Set sFileName = VisFileCreateTemp ('Vis')

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.

Set hFile = VisFileOpen (sFileName, OF_Write)

VisFileDelete Syntax

nErrCode = VisFileDelete (sFileSpec) String: sFileSpec

Description

Deletes one or more files.

Parameters

sFileSpec

Return

Number: The number of files deleted, or negative if an error occurs.

Example

Call VisFileDelete ('c:\\windows\\temp\\*.*')

Directory and file specification to delete, may include wildcard characters. File name specified may be in long format or in DOS 8.3 format.

VisFileExpand Syntax

nErrCode = VisFileExpand (sSourceFile, sTargetFile) String: sSourceFile String: sTargetFile

Description

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.

Parameters

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. Centura Builder Function Reference

2-263

Chapter

2

sTargetFile

Return

Target file specification. May also include wildcard characters. File name specified may be in long format or in DOS 8.3 format.

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

sFullName = VisFileFind (sFileName) String: sFileName

Description

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

Current directory

2.

Windows directory and Windows system directory

3.

Directory containing executable file for the current task

4.

Directories listed in the PATH environment variable You can also specify . or .. to search the parent or root directory of the current subdirectory.

Parameters

sFileName

Return

String: The full path if the file name is found. A null string is returned if the file cannot be found.

Example

Set sFileName = VisFileFind ('win.com')

File name to search for. Cannot contain wildcard characters. File name specified may be in long format or in DOS 8.3 format.

VisFileGetAttribute Syntax

nAttribute = VisFileGetAttribute(sFileName) String: sFileName

Description

Gets the attribute bit values for the specified file.

Parameters

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

nFileSize = VisFileGetSize (sFileName) String: sFileName

Description

Gets the size of the specified file in bytes.

Parameters

sFileName

Return

Number: The file size, or negative if an error occurs.

File name to get size of. File name specified may be in long format or in DOS 8.3 format.

Related Functions VisFileGetAttribute Example

Set nFileSize = VisFileGetSize ('c:\\autoexec.bat')

VisFileGetType Syntax

nFileType = VisFileGetType (sFileName) String: sFileName

Description

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

Parameters

sFileName

Return

Number: The file type, or negative if an error occurs. File types are mutually exclusive and valid values are:

File name to obtain type of. File name specified may be in long format or in DOS 8.3 format.

Related Functions VisFileGetAttribute, VisFileGetSize Example

Set nType = VisFileGetType ('c:\\winword\\letter.doc') If nType = FILETYPE_Document ...


2-265

Chapter

2

VisFileOpen Syntax

nErrCode = VisFileOpen (hFile, sFileName, nFlags) Receive File Handle: hFile String: sFileName Number: nFlags

Description

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

Parameters

hFile

Handle of the open file.

sFileName

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

nFlags

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



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

Description

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.

Parameters

hFile


sBuffer

String to contain the data read.

nSize

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.

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

2

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

Description

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.

Parameters

hFile


sLine

Text line read from the file. Pre-allocation of the sLine with SalStrSetBufferLength is not necessary.

Return


Related Functions VisFileOpen, VisFileRead, VisFileWrite, VisFileWriteString Example

Set nErrCode = VisFileReadString (hFile, sLine)

VisFileRename Syntax

nErrCode = VisFileRename (sOldFileSpec, sNewFileSpec) String: sOldFileSpec String: sNewFileSpec

Description

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.

Parameters

sOldFileSpec

Source file specification to rename. File name specified may be in long format or in DOS 8.3 format.

sNewFileSpec

Target file specification. File name specified may be in long format or in DOS 8.3 format.

Return

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

Description

Seeks to a specified offset within a file.

Parameters

hFile


nOffset

Specifies the number of bytes the offset is to be moved from the origin.

nOrigin

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

Description

Sets the attribute bits for one or more files.


2-269

Chapter

2

Parameters

Return

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.

nAttribute

Attribute bits to set or clear:

bState

FA_Standard FA_ReadOnly FA_Hidden FA_System FA_Archive TRUE to set attributes, FALSE to clear.

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

Description

Sets the date and time for one or more files.

Parameters

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.

dtDateTime

Date and time to set for all files specified.

Return

Number: The number of files effected, or negative if an error occurs.

Example

Set dtDateTime = SalDateCurrent() Set nNumFiles = VisFileSetDateTime ('c:\\myapp\\*.exe', dtDateTime)


VisFileTell Syntax

nOffset = VisFileTell (hFile) File Handle: hFile

Description

Returns the current file offset.

Parameters

hFile

Return

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

Description

Writes a block of data to a file.The maximum number of characters you can write is 65,535.

Parameters

hFile


sBuffer

String containing data to write.

nSize

Number of bytes to write. Must be less than or equal to size of sBuffer.

Return

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

2

VisFileWriteString Syntax

nErrCode = VisFileWriteString (hFile, sLine) File Handle: hFile String: sLine

Description

Writes a string to a file. CR/LF characters are added to the end of the string before it's written to the file.

Parameters

hFile

Handle to file context structure returned from VisFileOpen.

sLine

String to write to the file.

Return


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[*]

Description

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

Parameters

sGetFlag

sFontNames nFontTypes

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.


Related Functions VisFontGet Example

Set nNumFonts = VisFontEnum (FONT_GetScreen, sFontNames, nFontTypes) Set nIndex = 0 While nIndex < nNumfonts If nFontTypes(nIndex) & FONTTYPE_TrueType

VisFontFree Syntax

bOk = VisFontFree (hFont) String: hFont

Description

Frees a font loaded into memory with the VisFontLoad function.

Parameters

hFont

Return


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

Description

Gets specifications of a font.

Parameters

hFont

Font to get specifications for.

sFaceName

String to contain the font name (Arial, Times New Roman, etc.)

nPointSize

Point size of font.

nFontEnhancement

Bit flags containing font enhancements. To combine bit values, use the bitwise OR (|) operator. FONT_EnhNormal FONT_EnhItalic


2-273

Chapter

2

FONT_EnhUnderline FONT_EnhBold FONT_EnhStrikeout Return


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

Description

Loads a font into memory.

Parameters

sFontName

Font name (Arial, Times New Roman, etc.).

nFontSize

Point size of font.

nFontEnhancement

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

sCopyrightMsg = VisGetCopyright ()

Description

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

Parameters

No parameters.

Return

String: The copyright string for the Vis Library.

Related Functions VisGetVersion Example

On SAM_Create Set dfCopyright = VisGetCopyright()

VisGetKeyState Syntax

nState = VisGetKeyState (nVirtualKey) Number: nVirtualKey

Description

Retrieves the state of a specified key. The state specifies whether the key is up, down, or toggled.

Parameters

nVirtualKey

Return

Number: The bit values indicating the state of the key specified. To test a bit value, use the bitwise AND (&) operator.

Example

On SAM_Click

Virtual key code to retrieve the state. See the Appendix for a complete list of virtual key codes.

Set nState = VisGetKeyState (VK_Control) If nState & KS_Down ...

VisGetSystemMetrics Syntax

nValue = VisGetSystemMetrics(nIndex) Number: nIndex

Description

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.

Parameters

nIndex

Specifies the system measurement to retrieve:


2-275

Chapter

2

Return

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.

Example

Actions Set nScreenWidth = VisGetSystemMetrics (SM_XScreen)

VisGetVersion Syntax

sVisVersion = VisGetVersion ()

Description

Gets the Vis Library version number.

Parameters

No parameters.

Return

String: The version number of the Vis Library.

Example

Actions Set dfVersion = 'Version ' || VisGetVersion()

VisGetWinFlags Syntax

nFlags = VisGetWinFlags ()

Description

Retrieves the current Windows system and memory configuration.

Parameters

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

nWinVersion = VisGetWinVersion ()

Description

Returns the Windows version number.

Parameters

No parameters.

Return

NumberThe major and minor (3.10) Windows version number.

Example

Actions Set nWinVersion = VisGetWinVersion ()

VisListAddValue Syntax

nIndex = VisListAddValue (hWndList, sText, nValue) Window Handle: hWndList String: sText Number: nValue

Description

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.

Parameters

hWndList

Window handle of list box or combo box to add item to.

sText

Text of item to add.

nValue

Value to associate with the added item. May be a positive or negative integer value. Centura Builder Function Reference

2-277

Chapter

2

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[*]

Description

Populates a list box from a string array. Each item in the string is inserted as an item in the list box.

Parameters

hWndList

Window handle of list box or combo box to populate.

sText

String array to populate the list box with.

Return

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[*]

Description

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.

Parameters

hWndList

Window handle of list box or combo box to populate.

sText

String array to populate the list box with.

nValues

Number array of values to associate with each item.


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

bOk = VisListClearSelection (hWndList) Window Handle: hWndList

Description

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.

Parameters

hWndList

Returns


Handle to list box or combo box to clear selection from.

Related Functions VisListDeleteSelected Example

Actions Call VisListClearSelection (hWndItem)

VisListDeleteSelected Syntax

nNumDeleted = VisListDeleteSelected (hWndList) Window Handle: hWndList

Description

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.

Parameters

hWndList

Return

Number: nNumDeleted is the number of items deleted, or negative if an error occurs.

Window handle of list box or combo box to delete selected items.


2-279

Chapter

2

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

Description

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.

Parameters

hWndList

Window handle of list box or combo box.

nStartIndex

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.

sText

String to search for. The search is not case-sensitive.

Return

Number: The index of the string if it is found, or negative if an error occurs.

Example

Actions Set nIndex = VisListFindString (lbSample, 0, 'Red')

VisListFindValue Syntax

nIndex = VisListFindValue (hWndList, nStartIndex, nValue) Window Handle: hWndList Number: nStartIndex Number:nValue

Description

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

Parameters

hWndList

Window handle to search.

nStartIndex

The index to begin searching; specify -1 to search from the top of the list. Searching begins at nStartIndex +1.


nValue

Value to search for.

Return

Number: The index containing the value specified, or LB_Err if the value cannot be found.

Example

Actions Set nIndex = SalListQuerySelection (hWndItem) If nIndex != LB_Err Set nIndexFound = VisListFindValue (lbNames, nIndex, 100)

VisListGetDropdownState Syntax

bState = VisListGetDropdownState (hWndList) Window Handle: hWndList,

Description

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

Parameters

hWndList

Return

Boolean: TRUE if visible, FALSE if not visible

Example

Actions

Window handle of combo box.

If VisListGetDropdownState (hWndItem) ...

VisListGetFocusIndex Syntax

nIndex = VisListGetFocusIndex (hWndList) Window Handle: hWndList

Description

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.

Parameters

hWndList

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

2

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

Description

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.

Parameters

hWndList

Window handle of list box.

nTop

Top visible index of list box

nBottom

Bottom visible index of list box

Return

Number: The number of visible items, or negative if an error occurs or if hWndList is a combo box.

Example

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

Description

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.

Parameters

hWndList

Window handle of list box or combo box to insert item into.

nIndex

Position to insert item in list box (-1 to insert at the bottom).


Return

sText

Text of item to insert.

nValue

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

bOk = VisListIsMultiSelect (hWndList) Window Handle: hWndList

Description

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

Parameters

hWndList

Returns

Boolean: TRUE if multi selection is enabled for the list box, FALSE if not.

Example

Actions

List box to test.

If VisListIsMultiSelect (hWndList) ...

VisListLoadOutline Syntax

nErrCode = VisListLoadOutline (hWndList, sOutlineBlob) Window Handle: hWndList String: sOutlineBlob

Description

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.

Parameters

hWndList


sOutlineBlob

String containing outline to load.

Return



2-283

Chapter

2

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

Description

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.

Parameters

hWndList


sOutlineFileName

File name of the outline to load.

hPicParentNormal

Picture to use when parent item is not selected. Call VisPicLoad to create a picture handle.

hPicParentSelect

Picture to use when parent item is selected. hPicParentNormal and hPicParentSelect may be the same.

hPicChildNormal

Picture to use when lowest level child item is not selected. Call VisPicLoad to create a picture handle.

hPicChildSelect

Picture to use when lowest level child item is selected. hPicChildNormal and hPicChildSelect may be the same.

Return


Example

Set nErrCode = VisListLoadOutlineFile (hWndList, sOutlineFileName, hPicParentNormal, hPicParentSelect, hPicChildNormal, hPicChildSelect)


VisListSaveOutline Syntax

nErrCode = VisListSaveOutline (hWndList, sOutlineBlob) Window Handle: hWndList String: sOutlineBlob

Description

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.

Parameters

hWndList


sOutlineBlob

String to contain the ouline.

Return


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

Description

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.

Parameters

hWndList

Window handle of list box to scroll.

nIndex

Index of item to scroll.

Return

Number: Negative if an error occurs.

Example

Actions Call VisListScroll (hWndItem, 0)


2-285

Chapter

2

VisListSetDropdownState Syntax

bOk = VisListSetDropDownState (hWndList, bState) Window Handle: hWndList Boolean: bState

Description

Shows or hides the list box portion of a combo box. This function does not operated on list boxes.

Parameters

hWndList

Window handle of combo box.

bState

TRUE to show, FALSE to hide.

Return


Related Functions VisListGetDropDownState Example

Actions Call VisListSetDropDownState (hWndItem, TRUE)

VisListSetFocusIndex Syntax

nErrCode = VisListSetFocusIndex (hWndList, nIndex) Window Handle: hWndList Number: nIndex

Description

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.

Parameters

hWndList

Window handle of list box.

nIndex

Index of the item to receive the focus rectangle.

Return

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

Description

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.

Parameters

hWndList

Window handle of list box to set the scroll width.

nIndex

Item to base the scroll width on. If -1 all items are searched for the largest text length.

Return

Number: Zero if successful, or negative if an error occurs.

Example

Actions Call VisListSetScrollWidth (lbText, -1)

VisMenuGetPopupHandle Syntax

hMenu = VisMenuGetPopupHandle (hMenu, nPos) Number: hMenu Number: nPos

Description

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.

Parameters

hMenu

Handle of menu whose pop-up menu handle is to be retrieved.

nPos

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

2

Example

Set hMenu = VisMenuGetHandle (hUnd) If hMenu Set hSubMenu = VisMenuGetPopupHandle (hMenu, 2)

VisMenuGetSystemHandle Syntax

hMenu = VisMenuGetSystemHandle (hWnd) Window Handle: hWnd

Description

Retrieves the system menu handle of a window. The system menu is located in the upper left corner of a window.

Parameters

hWnd

Return

Number: The system menu handle of window specified, or NULL if the window has no menu.

Window handle to retrieve 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

Description

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.

Parameters

hWnd

Handle to window containing menu.

hMenu

Handle of menu containing item to retrieve.

nPos

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

Description

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.

Parameters

hWnd

Handle to window containing the menu. This window will be notified with a VTM_MenuSelect message when the menu item is selected.

hMenu

Handle of menu to insert item into.

nPos

Zero-based position within the menu of the item. Menu positions include separators. Specify -1 to insert at the end of the menu.

sMenuText

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.

nFlags

Menu flags. To combine bit values, use the bitwise OR (|) operator.


2-289

Chapter

2

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

Description

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.

Parameters

hWnd


hMenu


nPos


hFont

Handle to font to use for menu item display. Call VisFontLoad to create a font handle.

sMenuText

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


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

Description

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.

Parameters

hWnd


hMenu


nPos


hPicNormal

Handle of picture to display in menu item when item is not selected. Call VisPicLoad to create a picture handle. Centura Builder Function Reference

2-291

Chapter

2

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


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

Description

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.

Parameters

hMenu

Menu handle of menu to test. This may be a pop-up or system menu. It cannot be a top-level menu.

nPos


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

Description

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.

Parameters

hMenu

Menu handle of menu to test.

nPos


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

2

VisMenuSetFont Syntax

bOk = VisMenuSetFont (hWnd, hMenu, nPos, hFont sMenuText) Number: hWnd Number: hMenu Number: nPos Number: hFont String: sMenuText

Description

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

Parameters

hWnd


hMenu

Handle to menu containing item to display picture with.

nPos


hFont

Handle to font to use for menu item display. Call VisFontLoad to create a font handle.

sMenuText

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.

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

Description

Displays a picture in a menu item. VisMenuSetPicture operates on Centura menus or menus inserted with the Vis Library.

Parameters

hWnd


hMenu

Handle to menu containing item to display picture with.

nPos


hPicNormal

Handle of picture to display in menu item when item is not selected. Call VisPicLoad to create a picture handle.

hPicSelect

Handle of picture to display in menu item when item is selected. hPicNormal and hPicSelect may be the same.

sMenuText

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.

Returns


Related Functions VisMenuSetFont, VisMenuSetText


2-295

Chapter

2

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

Description

Changes the text of a menu item. VisMenuSetText operates on Centura menus or menus inserted with the Vis Library.

Parameters

hWnd


hMenu

Handle of menu that contains the menu item to reset text for.

nPos


sText

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.

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

Description

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.

Parameters

hMenu

Handle of menu containing item to uncheck.

nPos


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

Description

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

Parameters

sMsgText

Text to be displayed in message box.

sCaption

Caption of message box window.

hPicIcon

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: Centura Builder Function Reference

2-297

Chapter

2

hBtnHandles

nNumButtons Returns

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.

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

bOk = VisMessageFreeButton (hBtn) Number: hBtn

Description

Frees memory allocated with VisMessageLoadButton.

Parameters

hBtn

Returns


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

Description

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

Parameters

sLabel

Text label for button.

nReturn

Return value if button is clicked in the message box. This value is returned from VisMessageBox.

Returns

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

bOk = VisMessageSetBkgdColor (nColor) Number: nColor

Description

Sets the background color for a VisMessageBox dialog box. All subsequent calls to VisMessageBox will display a dialog with the color indicated.

Parameters

nColor

Returns


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

Description

Clears bit values from a number.


2-299

Chapter

2

Parameters

Return

nValue

Number value to clear bits from. The function replaces this number with the result.

nBitMask

Bit mask identifying the bits to clear.

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

Description

Sets bit values in a number.

Parameters

nValue

Number value to set bits for. The function replaces this number with the result.

nBitMask

Bit mask identifying the bits to set.

Return

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

Description

Evaluates bExpression. If expression is TRUE, it returns nTrueNumber, else it returns nFalseNumber. The expression may be a constant, expression or variable.

Parameters

bExpression

Expression to test

nTrueNumber

Number returned if expression TRUE.

nFalseNumber

Number returned if expression FALSE.

Returns

Number: nTrueNumber or nFalseNumber depending on how the expression evaluates.

Related Functions VisStrChoose Example

Actions Set nError = VisNumberChoose (nWnd = hWndNULL, TRUE, FALSE)

VisNumberHighByte Syntax

nNumber = VisNumberHighByte(nNumber) Number: nNumber

Description

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

Parameters

nNumber

Return

Number: The high order 8 bits.

Number to convert and obtain high 8 bits for.

Related Functions VisNumberLowByte Example

Actions Set nValue = 0xC8D4 Set nHiByte = VisNumberHighByte (nValue) !nHiByte = OxC8.


2-301

Chapter

2

VisNumberLowByte Syntax

nNumber = VisNumberLowByte(nNumber) Number: nNumber

Description

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

Parameters

nNumber

Return

Number: The low order 8 bits.

Number to convert and obtain low 8 bits for.

Related Functions VisNumberHighByte Example

Actions Set nValue = 0xC8D4 Set nLowByte = VisNumberLowByte (nValue) !nLowByte = OxD4.

VisNumberMakeLong Syntax

nLong = VisNumberMakeLong(nLow, nHigh) Number: nLow Number: nHigh

Description

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

Parameters

nLow

Low order 16 bits.

nHigh

High order 16 bits.

Return

Number: The combined value.

Example

Actions Set nLow = 0x0101 Set nHigh = 0xABCD Set nLong = VisNumberMakeLong (nLow, nHigh) ! nLong = 0xaABCD0101

VisPicFree Syntax

nErrCode = VisPicFree (hPic) Number: hPic

Description

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


Parameters

hPic

Return

Number: Zero if successful, or non-zero if an error occurs.

Handle of picture to free.

Related Functions VisPicLoad Example

Set nErrCode = VisPicFree (hPic)

VisPicLoad Syntax

hPic = VisPicLoad (nFormatFlags, sString1, sString2) Number: nFormatFlags String: sString1 String: sString2

Description

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.

Parameters

nFormatFlags

sString1

sString2 Return

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.

Number: The handle of the specified picture if successful, or NULL if an error occurs.

Related Functions VisPicFree


2-303

Chapter

2

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

Description

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

Parameters

hWnd

Handle of window to send message to.

nMessage

Message number.

wParam

WORD parameter

sString

String to pass in lParam.

Returns

Number: Return value from message.

Example

Call VisSendMsgString (hWndItem, LB_FINDSTRING, 0, sSearchFor)


VisStrChoose Syntax

sString = VisStrChoose (bExpression, sTrueString, sFalseString) Boolean: bExpression String: sTrueString String: sFalseString

Description

Evaluates bExpression. If expression is TRUE, it returns sTrueString, else it returns sFalseString

Parameters

bExpression

Expression to test

sTrueString

String returned if expression TRUE.

sFalseString

String returned if expression FALSE.

Returns

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[*]

Description

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.


2-305

Chapter

2

Parameters

Return

sTemplate

Template to expand.

hAry

Array to expand into template. hAry may be a number array or a string array.

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

Description

Locates a string within a string table. The string table must be loaded into memory using VisStrLoadTable.

Parameters

hStrTable

Handle to string table to load string from.

sIdentifier

Identifier used to located the string within the string table. Identifiers are enclosed within braces {} in the string table.

Returns

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

bOk = VisStrFreeTable (hStrTable) Number: hStrTable

Description

Frees all memory associated with a string table.

Parameters

hStrTable

Returns


Handle to string table to free from memory.

Related Functions VisStrFind, VisStrLoadTable Example

Set bOk = VisStrFreeTable (hStrTable)

VisStrLeftTrim Syntax

sString = VisStrLeftTrim (sSource) String: sSource

Description

Trims leading blanks from a string.

Parameters

sSource

Return

String: The trimmed string.

Source string.

Related Functions VisStrRightTrim, VisStrTrim Example

Set sTarget = VisStrLeftTrim (' ABC ') ! sTarget = 'ABC '

VisStrLoadTable Syntax

hStrTable = VisStrLoadTable (sFileName) String: sFileName

Description

Loads a string table from disk into memory. The maximum size of a string table is 65,533 bytes.

Parameters

sFileName

Returns

String: The handle of the string table if successful, or negative if an error occurs.

File name of string table to load. If no path is specified, the current drive/directory is searched.


2-307

Chapter

2

Related Functions VisStrFind, VisStrFreeTable Example

Set hStrTable = VisStrLoadTable (sFileName)

VisStrPad Syntax

sString = VisStrPad (sSource, nSize) String: sSource Number: nSize

Description

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.

Parameters

sSource

String to pad to the specified size.

nSize

Size of the string to return.

Return

String: The padded string. The return string is always the size specified.

Related Functions VisStrTrim Example

Set sTarget = VisStrPad ('ABC', 10)

VisStrProper Syntax

sString = VisStrProper (sSource) String: sSource

Description

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.

Parameters

sSource

Return

String: The converted string.

Example

Set sTarget = VisStrProper ('M.L. SMITH')


Source string.

VisStrRightTrim Syntax

sString = VisStrRightTrim (sSource) String: sSource

Description

Trims trailing blanks from a string.

Parameters

sSource

Return


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

Description

Scans a string for a specified sub-string from the last character to the first. Case is ignored when performing the search.

Parameters

sSource

Source string to search.

nPos

Position to begin the search, -1 to begin searching from the last character.

sSearchFor


Return

Number: The position of search string, -1 if string not found.

Example

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

2

Description

Substitutes all occurrences of one string with another string.

Parameters

sSource

Source string.

sSearch


sReplace

Replacement string.

Return

String: The modified string.

Example

Set sTarget = VisStrSubstitute ('12ABC34ABC', 'ABC', '*' ! sTarget = '12*34*'

VisStrTrim Syntax

sString = VisStrTrim (sSource) String: sSource

Description

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

Parameters

sSource

Return


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

Description

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

Parameters

hWndTable

Table window handle.

nFlagsOn

Bit flags to test, all bits must exist in the row flag for a valid match.

nFlagsOff

Bit flags that the row cannot have. The row cannot have any of the flags specified.


ROW_Edited ROW_Hidden ROW_HideMarks ROW_MarkDeleted ROW_New ROW_Selected Returns


Example

If VisTblAllRows (twTable, ROW_New | ROW_Selected, 0)

VisTblAutoSizeColumn Syntax

bOk = VisTblAutoSizeColumn (hWndTable, hWndColumn) Handle: hWndTable Handle: hWndColumn

Description

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.

Parameters

hWndTable


hWndColumn

Column window handle to auto size. Specify hWndNULL to size all columns.

Returns


Example

Call VisTblAutoSizeColumn (twTable, colPrice)

VisTblClearColumnSelection Syntax

bOk = VisTblClearColumnSelection (hWndTable) Handle: hWndTable

Description

Clears selection for all columns of a table window.

Parameters

hWndTable

Returns


Example

Call VisTblClearColumnSelection (hWndForm)



2-311

Chapter

2

VisTblFindDateTime Syntax

nRow = VisTblFindDateTime (hWndTable, nStartRow, hWndColumn, dtDateTime) Handle: hWndTable Number: nStartRow Number: hWndColumn Date/Time: dtDateTime

Description

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.

Parameters

hWndTable


nStartRow

Row number to start the search at.

hWndColumn

Handle of column to search or hWndNULL to search all date/ time columns.

dtDateTime

Date/time to search for.

Returns

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

Description

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.

Parameters

hWndTable


nStartRow


hWndColumn

Handle of column to search or hWndNULL to search all number columns.

nNumber

Number to search for.


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

Description

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

Returns

hWndTable


nStartRow


hWndColumn

Handle of column to search or hWndNULL to search all string columns.

sString


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

2

VisTblGetCell Syntax

sText = VisTblGetCell (hWndTable, nRow, hWndColumn) Number: nRow Handle: hWndColumn

Description

Retrieves the contents of a cell in a table window. The row specified will be set to the context row.

Parameters

hWndtable


nRow

Row number to obtain data from.

hWndColumn

Column window handle to retrieve text.

Returns

String: The cell text, or null string if error occurs.

Related Functions VisTblGetColumnTitle Example

Set sText = VisTblGetCell (10, colName)

VisTblGetColumnTitle Syntax

sTitle = VisTblGetColumnTitle (hWndColumn) Handle: hWndColumn

Description

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

Parameters

hWndTable


hWndColumn

Column window handle to retrieve column heading for.

Returns

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

Description

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

Parameters

hWndTable


nRow

Row number to set the text color for.

nColor

Color to set for all columns of the row specified.

Returns


Related Functions VisTblSetRowPicture, VisTblGetColumnTitle Example

Call VisTblSetRowColor (twOrders, 10, COLOR_Red)

VisTblSetRowPicture Syntax

bOk = VisTblSetRowPicture (hWndTable, nRowFlag, hPic) Handle: hWndTable Number: nRowFlag Number: hPic

Description

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.

Parameters

hWndTable


nRowFlag

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 Centura Builder Function Reference

2-315

Chapter

2

hPic

Returns

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.


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

bOk = VisWaitCursor (nFlags) Number: nFlags

Description

Turns hourglass cursor on or off. Differs from SalWaitCursor in the following ways:

Parameters

1.

Disables the current application when the hourglass is turned on and enables the application when the hourglass is turned off.

2.

Shows hourglass cursor if no mouse is present (shown in miiddle of screen).

3.

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.

nFlags

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

Boolean: No return value.

Example

Call VisWaitCursor (WAIT_TempOff) Call SalMessageBox ('Error Occurred', 'Error', MB_OK) Call VisWaitCursor (WAIT_TempOn)


VisWinClearAllEditFlags Syntax

nNumCleared = VisWinClearAllEditFlags (hWnd{Parent) Window Handle: hWndParent

Description

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.

Parameters

hWndParent

Return

Number: The number of fields cleared, or negative if an error occurs.

Window handle of parent window to clear all edit flags of.

Related Functions VisWinClearAllFields Example

Message Actions On SAM_Create Call VisWinSetFlags (hWndItem, SWF_NoClearEditFlag) Actions Call VisWinClearAllEditFlags (hWndForm)

VisWinClearAllFields Syntax

nNumCleared = VisWinClearAllFields (hWndParent) Window Handle: hWndParent

Description

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.

Parameters

hWndParent

Return

Number: The number of fields cleared, or negative if an error occurs.

Window handle of parent window to clear all child fields of.

Related Functions VisWinClearAllEditFlags


2-317

Chapter

2

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[*]

Description

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.

Parameters

hWnd

Window handle of window to get the property list of.

sPropStrings

Array to contain all the property list strings.

sValues

Array to contain the property values.

Return

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

bOk = VisWinFreeAccelerator (hAcc) Handle: hAcc

Description

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

Parameters

hAcc


Handle to accelerator.

Returns


Related Functions VisWinGetProp Example

Set bOk = VisWinFreeAccelerator (hAcc)

VisWinGetFlags Syntax

nWinFlags = VisWinGetFlags (hWnd) Handle: hWnd

Description

Retrieves window flags for a window.

Parameters

hWndWindow handle to retrieve flags for.

Returns

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

Description

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.

Parameters

hWndDialog

Window handle of dialog box containing window handles to search for.


2-319

Chapter

2

sContext

Context string to uniquely identify the window.

nWindowType

Centura type: TYPE_BkgdText TYPE_GroupBox

Return

Window Handle: The window handle if successful, or NULL if window not found.

Example

Actions Set hWnd = VisWinGetHandle (hWndForm, 'Sample:', TYPE_BkgdText)

VisWinGetProp Syntax

nValue = VisWinGetProp (hWnd, sPropString) Window Handle: hWnd String: sPropString

Description

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.

Parameters

hWnd

Window handle of window to get the property list for.

sPropString

Context string used to identify the property list.

Return

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

nStyle = VisWinGetStyle (hWnd) Window Handle: hWnd

Description

Retrieves the Windows style bits for a specified window. These style bits are documented in the Windows SDK documentation.

Parameters

hWnd

Return

Number: The style bits of the window specified, or -1 if window is invalid.


Window handle of window to retrieve style bits of.

Related Functions VisWinSetStyle Example

Variables Number: nStyle ... Actions Set nStyle = VisWinGetStyle (hWndForm)

VisWinGetText Syntax

sString = VisWinGetText (hWnd) Window Handle: hWnd

Description

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.

Parameters

hWnd

Returns

String: The window text, if successful, or null string if error occurs.

Example

Radio Button: rbSample

Window to obtain text for.

Title: Option: ... Actions Set sText = VisWinGetText (rbSample) ! sText = 'Option:'

VisWinIsChild Syntax

bOk = VisWinIsChild (hWndParent, hWndChild) Window Handle: hWndParent Window Handle: hWndChild

Description

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

Parameters

hWndParent

Window handle of parent window.

hWndChild

Window handle of child window to test for.

Return

Boolean: TRUE if child is a descendant, FALSE if not a descendant.


2-321

Chapter

2

Related Functions VisWinIsWindow Example

Actions If VisWinIsChild (hWndForm, pbOk) ...

VisWinIsMaximized Syntax

bOk = VisWinIsMaximized (hWnd) Window Handle: hWnd

Description

Tests whether a specified window is maximized.

Parameters

hWnd

Return

Boolean: TRUE if window maximized, FALSE if not maximized.

Window handle of window to test.

Related Functions VisWinIsMinimized, VisWinIsRestored Example

Actions If VisWinIsMaximized (hWndForm)

VisWinIsMinimized Syntax

bOk = VisWinIsMinimized (hWnd) Window Handle: hWnd

Description

Tests whether a specified window is minimized.

Parameters

hWnd

Return

Boolean: TRUE if window minimized, FALSE if not minimized


Related Functions VisWinIsMaximized, VisWinIsRestored Example

Actions If VisWinIsMinimized (hWndForm)


VisWinIsRequiredFieldNull Syntax

hWnd = VisWinIsRequiredFieldNull (hWndParent) Handle: hWndParent

Description

Tests to determine if any required field is null.

Parameters

hWndParent

Returns

Window Handle: Handle of first required field that contains no value, or null if all required fields are non-null.

Example

Dialog Box: dbTest

Handle of parent window to test. If any child window is required and contains a null value, VisWinIsRequiredFieldNull returns TRUE.

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

bOk = VisWinIsRestored (hWnd) Window Handle: hWnd

Description

Tests whether a specified window is neither maximized or minimized.

Parameters

hWnd

Return

Boolean: TRUE if window restored, FALSE if not maximized or minimized



2-323

Related Functions VisWinIsMaximized, VisWinIsMinimized Example

Actions If VisWinIsRestored (hWndForm)

VisWinIsWindow Syntax

bOk = VisWinIsWindow (hWnd) Window Handle: hWnd

Description

Tests whether a specified window is valid.

Parameters

hWnd

Return

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

Description

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.

Parameters

hWndNotify

Window to notify when the accelerator is pressed.

nMsg

Message to send to the window specified when the accelerator is pressed.

nKeyDownState

Flag indicating the keys held down in combination with the virtual key. Options are: KDS_None KDS_Shift

nVirtualKey nValue

Returns

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.

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

Description

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.

Parameters

hWnd

Handle of window to move.


2-325

Chapter

2

nLeft

Identifies the new position of the left side of the window.

nTop

Identifies the new position of the top of the window.

nWidth

Identifies the new width of the window.

nHeight

Identifies the new height of the window.

Returns


Example

Actions Call VisWinMove (hWnd, 10, 25, 425, 200)

VisWinRemoveProp Syntax

bOk = VisWinRemoveProp (hWnd, sPropString) Window Handle: hWnd String: sPropString

Description

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.

Parameters

hWnd

Window handle of window to remove the property list from.

sPropString

Context string used to identify the property list.

Return

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

Description

Sets flags for a specified window.

Parameters

hWnd

Window handle to set flags for.

nWinFlags

Window flags to set. Options are: WF_Required WF_NoClear


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

Description

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.

Parameters

hWnd

Window handle of a data field to display the completion meter in. This must be the window handle of a data field.

nPercent

Percentage complete to display within meter (0-100).

Return

Number: Zero if successful, or negative if an error occurs.

Example

Actions Call VisWinSetMeter (dbMeter, 0)

VisWinSetProp Syntax

bOk = VisWinSetProp (hWnd, sPropString, nValue) Window Handle: hWnd String: sPropString Number: nValue

Description

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.


2-327

Chapter

2

Parameters

Return

hWnd

Window handle of window to set the property list for.

sPropString

Context string used to identify the property.

nValue

Value stored with the property (application specific).

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

Description

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.

Parameters

hWnd

Window handle of window to change style of.

nStyle

Style bits to set or clear. The style bits are documented in the Windows SDK documentation.

bState

TRUE to turn the style bits on or FALSE to turn style bits off.

Return

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

Description

Changes the tab order of a control. If hWndInsertAfter is NULL, the window is removed from the tab order.

Parameters

hWnd

Window handle of window to set tab order.

hWndInsertAfter

Window handle of window to be inserted after this window.

Return


Example

Actions Call VisWinSetTabOrder (hWndItem, NULL)

VisWinShow Syntax

bOk = VisWinShow (hWnd, nShowFlag) Window Handle: hWnd Number: nShowFlag

Description

Sets a window's visibility state.

Parameters

hWnd

Window handle of window to show.

nShowFlag

Specifies how the window is to be shown: SHOW_Hidden SHOW_Minimized SHOW_Maximized SHOW_Normal

Return

Boolean: TRUE if window previously was visible, FALSE if previously hidden.

Example

Actions Call VisWinShow (hWndForm, SHOW_Maximized)


2-329


Index 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

A array functions 1-17

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

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

E edit functions 1-26

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

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

N number functions 1-40

P picture functions 1-42 print functions 1-43

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

Index-2

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


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

Index-4

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

Index-6

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


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

Recommend Documents