Centura Builder - Function Reference

Centura BuilderFunction Reference20-6202-0000

ra ts,

ted and ed

ca

d

TrademarksCentura, Centura Builder, Centura Ranger, Centura Team Developer, the Centulogo, Gupta, the Gupta logo, Gupta Powered, the Gupta Powered logo, Fast FacQuest, 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 UniStates of America and/or other countries. SQLWindows is a registered trademarkTeamWindows, ReportWindows and EditWindows are trademarks exclusively usand licensed by Centura Software Corporation.

Microsoft, Win 32, Windows, Windows NT and Visual Basic are either registeredtrademarks or trademarks of Microsoft Corporation in the United States of Ameriand/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 registeretrademarks of their respective owners.

CopyrightCopyright 1996 by Centura Software Corporation. All rights reserved.Centura Buildern Function Reference20-6202-0000February 1996

Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv

1 Centura Builder Function Tables . . . . . . 1-1

Centura Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Obsolete Centura Functions . . . . . . . . . . . . . . . 1-16

Centura Function Categories . . . . . . . . . . . . . . . . . . 1-17

Array Functions. . . . . . . . . . . . . . . . . . . . . . . . . . 1-17

Color and Font Functions . . . . . . . . . . . . . . . . . . 1-18

Data Type Conversion Functions . . . . . . . . . . . . 1-19

Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20

DDE Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21

Debugging Functions . . . . . . . . . . . . . . . . . . . . . 1-22

Dialog Box Functions . . . . . . . . . . . . . . . . . . . . . 1-23

DOS Management Functions . . . . . . . . . . . . . . . 1-23

Drag Drop Functions. . . . . . . . . . . . . . . . . . . . . . 1-25

Edit Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26

File Management Functions . . . . . . . . . . . . . . . . 1-27

Format and Validation Functions . . . . . . . . . . . . 1-29

List and Combo Box Functions. . . . . . . . . . . . . . 1-31

Manipulating Background Text Functions. . . . . . 1-33

MDI Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36

Message Functions. . . . . . . . . . . . . . . . . . . . . . . 1-36

Miscellaneous Functions . . . . . . . . . . . . . . . . . . 1-37

Number Functions . . . . . . . . . . . . . . . . . . . . . . . 1-40

Picture Functions . . . . . . . . . . . . . . . . . . . . . . . . 1-42

Print Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-43

Report Functions . . . . . . . . . . . . . . . . . . . . . . . . 1-43

Scroll Bar Functions . . . . . . . . . . . . . . . . . . . . . . 1-44

SQL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-44

String Conversion Functions. . . . . . . . . . . . . . . . 1-47

Centura Builder Function Reference

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference 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 Centura Builder Function Reference

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

Centura Builder Function Reference xxiii


Preface

This Preface contains the following sections:

• Audience

• What is in this manual

• Typographical conventions

• Other helpful resources

• Send comments to...

Centura Builder Function Reference xxv

Preface

al

by lue,

al

s

.

AudienceThis manual is an advanced guide for programmers creating complex and sophisticated applications using the Centura Builder.

What is in this manualThis manual is included with the Centura Builder documentation set. This manucontains the following chapters:

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

Chapter 2: Centura Builder FunctionsThis chapter is an alphabetical list of the Centura Builder functions accompanieddetailed information about each function's purpose, its parameters and return vaand an example.

Typographical conventionsBefore you start using this manual, it is important to understand the typographicconventions we use in this manual:

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

Formatting Convention Type of Information

bold type Menu items, push buttons, and field names. Thingthat 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 totype cd directory name you type the letters cd fol-lowed by a space and then the name of a directory

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

❑ This symbol alerts you that a procedure is about tobegin.

xxvi Centura Builder Function Reference

s

f e to you.

to ame

he ,

nd

r

Other helpful resourcesCentura Books Online. The Centura document suite is available online. This document collection lets you perform full-text indexed searches across the entiredocument suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the Centura BookOnline 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 othe latest information on topics such as, programming examples, and commonlyoccurring problems on Fast Facts. Call (415) 617-4600 to access a catalog of thdocuments available. You can request any document on the catalog to be faxed

CompuServe. If you are a CompuServe subscriber, you can join Centura’s forum learn about Centura products and communicate with other Centura users. The nof the forum is Centura.

Centura Online Help. This is an extensive context-sensitive online help system. Tonline help offers a quick way to find information on topics including menu itemsfunctions, messages, and objects.

World Wide Web. Centura Software Corporation’s World Wide Web site contains awealth of information about Centura Software Corporation’s partners, products, ausers. The URL address is http://www.centurasoft.com.

Windows User’s Guide. Refer to this manual for more information on the MicrosoftWindows operating system.

Send comments to...Everyone who reads the Guide can contribute to it. If you have any comments osuggestions, please send them to:

Technical Publications DepartmentCentura Corporation1060 Marsh Rd.Menlo Park, CA [email protected]

Centura Builder Function Referencexxvii


Chapter 1

Centura Builder Function Tables

The chapter contains functions tables that are arranged by type.

Centura Builder Function Reference 1-1

Chapter 1 Centura Builder Function Tables

Centura FunctionsSalAbortSalAppDisableSalAppEnableSalAppFindSalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySumSalBringWindowToTopSalCenterWindowSalClearFieldSalColorFromRGBSalColorGetSalColorGetSysColorSalColorSetSalColorToRGBSalCompileAndEvaluateSalContextBreakSalContextCurrentSalCreateWindowSalCursorClearSalCursorSetSalCursorSetFileSalCursorSetStringSalDateConstructSalDateCurrentSalDateDaySalDateHourSalDateMinuteSalDateMonthSalDateMonthBeginSalDateQuarterSalDateQuarterBeginSalDateSecondSalDateToStrSalDateWeekBegin

1-2 Centura Builder Function Reference

Centura Functions

SalDateWeekdaySalDateYearSalDateYearBeginSalDDEAddAtomSalDDEAllocSalDDEDeleteAtomSalDDEExtractSalDDEExtractCmdSalDDEExtractDataTextSalDDEExtractOptionsSalDDEFindAtomSalDDEFreeSalDDEGetAtomNameSalDDEGetExecuteStringSalDDEPostSalDDERequestSalDDESendSalDDESendAllSalDDESendExecuteSalDDESendToClientSalDDESetCmdSalDDESetDataTextSalDDESetOptionsSalDDEStartServerSalDDEStartSessionSalDDEStopServerSalDDEStopSessionSalDestroyWindowSalDisableWindowSalDisableWindowAndLabelSalDlgChooseColorSalDlgChooseFontSalDlgOpenFileSalDlgSaveFileSalDragDropDisableDropSalDragDropEnableDropSalDragDropGetSourceSalDragDropGetTargetSalDragDropStartSalDragDropStopSalDrawMenuBarSalDropFilesAcceptFilesSalDropFilesQueryFiles



SalDropFilesQueryPointSalEditCanCopyToSalEditCanCutSalEditCanPasteSalEditCanPasteFromSalEditCanUndoSalEditClearSalEditCopySalEditCopyStringSalEditCopyToSalEditCutSalEditPasteSalEditPasteFromSalEditPasteStringSalEditUndoSalEnableWindowSalEnableWindowAndLabelSalEndDialogSalFileCloseSalFileCopySalFileCreateDirectorySalFileGetCSalFileGetCharSalFileGetCurrentDirectorySalFileGetDateTimeSalFileGetDriveSalFileGetStrSalFileOpenSalFileOpenExtSalFilePutCSalFilePutCharSalFilePutStrSalFileReadSalFileRemoveDirectorySalFileSeekSalFileSetCurrentDirectorySalFileSetDateTimeSalFileSetDriveSalFileTellSalFileWriteSalFmtFieldToStrSalFmtFormatDateTimeSalFmtFormatNumber


Centura Functions

SalFmtGetFormatSalFmtGetInputMaskSalFmtGetPictureSalFmtIsValidFieldSalFmtIsValidInputMaskSalFmtIsValidPictureSalFmtKeepMaskSalFmtSetFormatSalFmtSetInputMaskSalFmtSetPictureSalFmtStrToFieldSalFmtUnmaskInputSalFmtValidateFieldSalFontGetSalFontGetNamesSalFontGetSizesSalFontSetSalFormGetParmNumSalFormUnitsToPixelsSalGetDataTypeSalGetDefButtonSalGetFirstChildSalGetFocusSalGetItemNameSalGetMaxDataLengthSalGetNextChildSalGetProfileIntSalGetProfileStringSalGetTypeSalGetVersionSalGetWindowLabelTextSalGetWindowLocSalGetWindowSizeSalGetWindowStateSalGetWindowTextSalHideWindowSalHideWindowAndLabelSalHStringToNumberSalInvalidateWindowSalIsButtonCheckedSalIsNullSalIsValidDateTimeSalIsValidDecimal



SalIsValidIntegerSalIsValidNumberSalIsWindowEnabledSalIsWindowVisibleSalListAddSalListClearSalListDeleteSalListFilesSalListGetMultiSelectSalListInsertSalListPopulateSalListQueryCountSalListQueryFileSalListQueryMultiCountSalListQuerySelectionSalListQueryStateSalListQueryTextSalListQueryTextLengthSalListQueryTextXSalListRedrawSalListSelectStringSalListSetMultiSelectSalListSetSelectSalListSetTabsSalLoadAppSalLoadAppAndWaitSalMapEnterToTabSalMDIArrangeIconsSalMDICascadeSalMDITileSalMessageBeepSalMessageBoxSalModalDialogSalModalDialogFromStrSalMoveWindowSalNumberAbsSalNumberArcCosSalNumberArcSinSalNumberArcTanSalNumberArcTan2SalNumberCosSalNumberCosHSalNumberExponent


Centura Functions

SalNumberHighSalNumberHypotSalNumberLogSalNumberLogBase10SalNumberLowSalNumberMaxSalNumberMinSalNumberModSalNumberPiSalNumberPowerSalNumberRandInitSalNumberRandomSalNumberRoundSalNumberSinSalNumberSinHSalNumberSqrtSalNumberTanSalNumberTanHSalNumberToCharSalNumberToHStringSalNumberToStrSalNumberToStrXSalNumberToWindowHandleSalNumberTruncateSalParentWindowSalPicClearSalPicGetDescriptionSalPicGetStringSalPicSetSalPicSetFileSalPicSetFitSalPicSetStringSalPixelsToFormUnitsSalPostMsgSalPrtExtractRectSalPrtGetDefaultSalPrtGetParmNumSalPrtPrintFormSalPrtSetDefaultSalPrtSetParmDefaultsSalPrtSetParmNumSalPrtSetupSalQueryFieldEdit



SalQuitSalReportCloseSalReportCmdSalReportCreateSalReportDlgOptionsSalReportGetDateTimeVarSalReportGetNumberVarSalReportGetObjectVarSalReportGetStringVarSalReportPrintSalReportPrintToFileSalReportResetSalReportSetDateTimeVarSalReportSetNumberVarSalReportSetObjectVarSalReportSetStringVarSalReportTableCreateSalReportTablePrintSalReportTableViewSalReportViewSalScrollGetPosSalScrollGetRangeSalScrollSetPosSalScrollSetRangeSalSendClassMessageSalSendClassMessageNamedSalSendMsgSalSendMsgToChildrenSalSendValidateMsgSalSetDefButtonSalSetFieldEditSalSetFocusSalSetMaxDataLengthSalSetProfileStringSalSetWindowLabelTextSalSetWindowLocSalSetWindowSizeSalSetWindowTextSalShowWindowSalShowWindowAndLabelSalStatusGetTextSalStatusSetTextSalStatusSetVisible


Centura Functions

SalStrCompressSalStrFirstCSalStrGetBufferLengthSalStrIsValidCurrencySalStrIsValidDateTimeSalStrIsValidNumberSalStrLeftSalStrLeftXSalStrLengthSalStrLopSalStrLowerSalStrLowerXSalStrMidSalStrMidXSalStrProperSalStrProperXSalStrRepeatSalStrRepeatXSalStrReplaceSalStrReplaceXSalStrRightSalStrRightXSalStrScanSalStrSetBufferLengthSalStrToDateSalStrTokenizeSalStrToNumberSalStrTrimSalStrTrimXSalStrUncompressSalStrUpperSalStrUpperXSalTBarSetVisibleSalTblAnyRowsSalTblClearSelectionSalTblColumnAverageSalTblColumnSumSalTblCopyRowsSalTblCreateColumnSalTblDefineRowHeaderSalTblDefineSplitWindowSalTblDeleteRowSalTblDeleteSelected



SalTblDestroyColumnsSalTblDoDeletesSalTblDoInsertsSalTblDoUpdatesSalTblFetchRowSalTblFindNextRowSalTblFindPrevRowSalTblGetColumnTextSalTblGetColumnTitleSalTblGetColumnWindowSalTblInsertRowSalTblKillEditSalTblKillFocusSalTblPasteRowsSalTblPopulateSalTblQueryColumnFlagsSalTblQueryColumnIDSalTblQueryColumnPosSalTblQueryColumnWidthSalTblQueryContextSalTblQueryFocusSalTblQueryLockedColumnsSalTblQueryRowFlagsSalTblQueryRowHeaderSalTblQueryScrollSalTblQuerySplitWindowSalTblQueryTableFlagsSalTblQueryVisibleRangeSalTblResetSalTblScrollSalTblSetCellTextColorSalTblSetColumnFlagsSalTblSetColumnPosSalTblSetColumnTextSalTblSetColumnTitleSalTblSetColumnWidthSalTblSetContextSalTblSetFlagsAnyRowsSalTblSetFocusCellSalTblSetFocusRowSalTblSetLockedColumnsSalTblSetRangeSalTblSetRow


Centura Functions

SalTblSetRowFlagsSalTblSetTableFlagsSalTblSortRowsSalTimerKillSalTimerSetSalTrackPopupMenuSalUpdateWindowSalValidateSetSalWaitCursorSalWindowGetPropertySalWindowHandleToNumberSalWindowIsDerivedFromClassSalWinHelpSalYieldEnableSalYieldQueryStateSalYieldStartMessagesSalYieldStopMessagesSqlClearImmediateSqlCloseSqlCommitSqlConnectSqlContextClearSqlContextSetSqlContextSetToFormSqlDirectoryByNameSqlDisconnectSqlDropStoredCmdSqlErrorSqlErrorTextSqlExecuteSqlExecutionPlanSqlExistsSqlExtractArgsSqlFetchNextSqlFetchPreviousSqlFetchRowSqlGetErrorSqlGetErrorPositionSqlGetErrorTextSqlGetErrorTextXSqlGetModifiedRowsSqlGetParameterSqlGetParameterAll



SqlGetResultSetCountSqlGetRollbackFlagSqlImmediateSqlImmediateContextSqlOpenSqlPLSQLCommandSqlPrepareSqlPrepareAndExecuteSqlRetrieveSqlSetInMessageSqlSetIsolationLevelSqlSetLockTimeoutSqlSetLongBindDatatypeSqlSetOutMessageSqlSetParameterSqlSetParameterAllSqlSetResultSetSqlStoreSqlVarSetupVisArrayAppendVisArrayCopyVisArrayDeleteItemVisArrayFillDateTimeVisArrayFillNumberVisArrayFillStringVisArrayFindDateTimeVisArrayFindNumberVisArrayFindStringVisArrayInsertItem VisArraySort VisDebugAssertVisDebugBeginTimeVisDebugEndTime VisDebugGetFlags VisDebugSetFlags VisDebugSetLevel VisDebugSetTime VisDebugString VisDosBuildFullName VisDosEnumDirInfo VisDosEnumDirs VisDosEnumDrives VisDosEnumFileInfo


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



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


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



VisWinGetHandle VisWinGetProp VisWinGetStyle VisWinGetText VisWinIsChild VisWinIsMaximized VisWinIsMinimized VisWinIsRequiredFieldNull VisWinIsRestored VisWinIsWindow VisWinLoadAccelerator VisWinMove VisWinRemoveProp VisWinSetFlags VisWinSetMeter VisWinSetProp VisWinSetStyle VisWinSetTabOrder VisWinShow

Obsolete Centura FunctionsSalCreateWindowFrmStrSalFmtCopyProfileSalFmtGetParmIntSalFmtGetParmStrSalFmtGetProfileSalFmtSetParmIntSalFmtSetParmStrSalFmtSetProfileSalQueryArrayBoundsSalSetArrayBounds


Centura Function Categories

Centura Function CategoriesCentura functions are divided into categories. This section identifies and briefly describes each category in addition to listing the functions in each one.

Array functionsColor and font functionsData type conversion functionsDate functionsDDE functionsDebugging functionsDialog box functionsDOS management functionsDrag Drop functionsEdit functionsFile management functionsFormat and validation functionsList and combo box functionsManipulating background text functionsMDI (Multiple Document Interface) functionsMessage functionsMiscellaneous functionsNumber functionsPicture functionsPrint functionsReport functionsScroll bar functionsSQL functionsString conversion functionsTable window functionsWindow management functions

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



new

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

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.


SalColorFromRGB Composes a color from red, green, and bluevalues.

SalColorGet Gets a window's color.




s.

e

.

s

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

SalColorGetSys Gets a system color.

SalColorSet Sets a window's color.

SalColorToRGB Decomposes a color into red, green, and bluvalues.

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, truetype, 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 tablewindow.

VisMenuInsertFont Inserts a menu item into a menu and displayit 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.


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

SalGetDataType Returns an object's data type.




s

f

Date FunctionsThese functions manipulate date/time values.

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 unitin the number of pixels.

SalSetMaxDataLength Sets the maximum length of a data field.


SalDateConstruct Constructs a date.

SalDateCurrent Gets the client's current date and time.

SalDateDay Gets the day portion of a date.

SalDateHour Gets the hour portion of a date.

SalDateMinute Gets the minute portion of a date.

SalDateMonth Gets the month portion of a date.

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

SalDateQuarter Gets the quarter of the year of a date.

SalDateQuarterBegin Gets the date of the first day of the quarter oa 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 agiven date.




E). he

t.

DDE FunctionsThese functions support the Microsoft protocols for Dynamic Data Exchange (DDDDE lets you exchange data with other Windows applications that also support tMicrosoft protocols.


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 clien

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 tothe specified server.

SalDDESendToClient Sends data to a client.

SalDDESetCmd Sets the command string in a WM_DDE_Execute message.



nt

d

Debugging FunctionsThese functions help you debug your application.

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

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

SalDDEStopServer Signals clients that the server wants to endDDE server operations.

SalDDEStopSession Ends a hot link conversation between a clieand a server.


SalCompileAndEvaluate Evaluates the data type of an expression anreturns 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.




s.

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

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

DOS Management FunctionsThese functions manage DOS features.

VisDebugString Writes a string to the debug application window.


SalDlgChooseColor Displays the Color dialog box.

SalDlgChooseFont Displays the Font dialog box.

SalDlgOpenFile Displays the Open File dialog box.

SalDlgSaveFile Displays the Save File dialog box.


SalEndDialog Destroys a modal dialog box.

SalModalDialog Creates a modal dialog box.

SalModalDialogFromStr Creates a modal dialog box with the specified name.


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

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

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

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




a

d

.

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 Retrieves all long and short subdirectory names for a given directory into a Centura array.

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

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

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

VisDosGetCurDir Returns the current directory of a specified drive.

VisDosGetDriveSize Returns total space and available space ondrive.

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

VisDosGetVersion Returns the MS-DOS version number.

VisDosGetVolumeLabel Returns the volume label of a specified drive




ects.

a

Drag Drop FunctionsThese functions enable users to drop files from the File Manager onto a Centuraapplication window at runtime, as well as drag and drop between application obj

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.


SalDragDropDisableDrop Disables dropping while in drag mode.

SalDragDropEnableDrop Enables dropping while in drag mode.

SalDragDropGetSource Retrieves the handle of the source windowand 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 filefrom Windows' File Manager.

SalDropFilesQueryFiles Retrieves the names of the files dropped onwindow.




a

a

ns

e

.

Edit FunctionsMost of these functions provide text editing capabilities. Use them for fields that user edits.

Microsoft Windows maintains both an undo buffer that stores previous edits andpaste buffer that it uses for cutting and pasting between text fields.

Other functions identify whether a user has selected data and if so, these functioenable Edit menu items.

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


SalEditCanCopyTo Returns TRUE if an editable picture has thefocus 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 thfocus.

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




e

t

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

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 datafield, 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 thspecified string.

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

VisWinClearAllFields Clears all child fields of a parent window.


SalFileClose Closes a file.

SalFileCopy Copies the contents of one file to another.

SalFileCreateDirectory Creates a directory.

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

SalFileGetChar Gets the next character from an open file.

SalFileGetCurrentDirectory Gets the path of the current working directory.

SalFileGetDateTime Gets a file's modification date and time.

SalFileGetDrive Gets the letter of the current disk drive.

SalFileGetStr Gets the next line from an open file.

SalFileOpen Opens a file.

SalFileOpenExt Opens or re-opens a file.




.

SalFilePutC Writes a character to an open file.

SalFilePutChar Writes a character to an open file.

SalFilePutStr Writes a string to an open file.

SalFileRead Reads from an open file.

SalFileRemoveDirectory Deletes a directory.

SalFileSeek Sets the position in an open file.

SalFileSetCurrentDirectory Changes a drive's current working directory

SalFileSetDateTime Sets a file's modification date and time.

SalFileSetDrive Sets the default disk drive.

SalFileTell Gets the current position in an open file.

SalFileWrite Writes to an open file.

VisFileAppend Appends one or more files to another.

VisFileClose Closes a file opened with the VisFileOpen call.

VisFileCopy Copies one or more files.

VisFileCreateTemp Creates a temporary file.

VisFileDelete Deletes one or more files.

VisFileExpand Copies a source file to a destination file.

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

VisFileGetAttribute Gets the attribute bit values for the specifiedfile.

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.




.

.

rs

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

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.


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 ortable window column.

SalFmtIsValidField Validates the contents of a data field or tablewindow 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 charactewhen you copy the value in a data field, table window column, or combo box.




e

r

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 tablwindow column at runtime.

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

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

SalFmtValidateField Validates and formats the contents of a datafield 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 acustom control so that Centura can perform validation as needed.




ngle- r all

.

r

x

t

x

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


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

SalListClear Clears a list box or combo box.

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

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

SalListGetMultiSelect Returns the index numbers of selected list box entries.

SalListInsert Inserts an entry into a list box or combo box

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

SalListQueryCount Returns the number of entries in a list box ocombo box.

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

SalListQueryMultiCount Returns the number of currently selected lisbox 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 boentry.

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

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



SalListSetMultiSelect Selects or deselects the specified list box entry.

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

SalListSetTabs Sets tab stops in a list box.

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

VisListArrayPopulate Populates a list box from a string array.

VisListArrayPopulateValue Populates a list box from a string array andan 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 orcombo 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 acombo box is visible.

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

VisListGetVisibleRange Retrieves the indexes of both the first visibleitem 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 valuewith the item.

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

VisListScroll Scrolls an item into view.




Manipulating Background Text FunctionsThese functions manipulate the background text.

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.


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.




a

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




l

.

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

• SalDisableWindowAndLabel

• SalHideWindowAndLabel

• SalShowWindowAndLabel

Two other functions you can use with background text are explained below.

nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength)

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 Hides a window and its associated label.

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

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

SalStatusSetVisible Shows or hides a top-level window's optionastatus 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 Converts a window handle to a number.

VisMenuSetText Changes the text of a menu item.

VisWinGetText Obtains the text of a window.




t. If t.

ed.

.

t

st

f

Retrieves the background text of a window:

hWnd identifies the window that has a label to return it in the receive string sTexthis function fails, 0 is returned. The parameters are similar to SalGetWindowTex

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 return

The parameters are the same as SalSetWindow Text.

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

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


SalMDIArrangeIcons Arranges minimized child window icons in an MDI window.

SalMDICascade Cascades child windows of an MDI window

SalMDITile Tiles child windows of an MDI window.


SalPostMsg Posts a message to a window.

SalSendClassMessage Invokes the message actions in the closesancestor class that implements the given message.

SalSendClassMessageNamed Invokes the message actions in the closeancestor class that implements the given message. Use with a class that is the result omultiple 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.



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

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

VisMessageFreeButton Frees memory allocated with VisMessageLoadButton.

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

VisMessageSetBkgdColor Sets the background color for a VisMessageBox dialog box.

VisSendMsgString Sends a message and passes a string in lParam.


SalAbort Halts the execution of current actions.

SalClearField Clears the value from a field.

SalCursorSet Sets a window's cursor.

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

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

SalDrawMenuBar Redraws a menu bar.

SalGetProfileInt Retrieves the integer value of an entry in thespecified 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.




s

s

.

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 messageto a window.

SalYieldStopMessages Stops yielding and the sending of messageto a window.

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

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

VisGetKeyState Retrieves the state of a specified key.

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

VisGetVersion Gets the Vis Library version number.

VisGetWinFlags Retrieves the current Windows system and memory configuration.




VisGetWinVersion Returns the Windows version number.

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

VisListLoadOutlineFile Loads an outline from a tab indented ASCII file.

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

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

VisMenuGetSystemHandle Retrieves the system menu handle of a window.

VisMenuGetText Retrieves the text of a menu item.

VisMenuInsert Inserts a menu item into a menu.

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

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

VisMenuUncheck Unchecks a menu item.

VisNumberBitClear Clears bit values from a number.

VisNumberBitSet Sets bit values in a number.

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.




Number FunctionsThese functions perform mathematical calculations.

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.


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




s

SalNumberHypot Computes the length of the hypotenuse of aright 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 serieof 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.




s

See Also: Array Functions

Picture FunctionsThese functions manipulate the contents of a picture.

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.


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




sing lay,

le.

.

Print FunctionsThese functions let you control printing.

Report FunctionsCentura lets you generate reports previously designed with ReportWindows. By uthe ReportWindows functions listed in the following section, you can create, dispformat, and print a report as well as get and set report variables.


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 whichlets the user alter the printer setup.


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

SalReportGetDateTimeVar Gets the value of a date/time report variab

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.



n se

le.

le.

.

Scroll Bar FunctionsThese functions manage horizontal and vertical scroll bars.

SQL FunctionsMost SQL functions are database-independent. As Centura Software Corporatiocontinues to provide connectivity to an ever-increasing number of databases, thefunctions provide a consistent interface.

SalReportReset Updates the report preview with new data.

SalReportSetDateTimeVar Sets the value of a date/time report variab

SalReportSetNumberVar Sets the value of a date/time report variab

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 createdfrom a table window.

SalReportView Displays a report in preview mode.


SalScrollGetPos Gets the scroll bar position.

SalScrollGetRange Gets values set by SalScrollSetRange.

SalScrollSetPos Sets the scroll bar position.

SalScrollSetRange Sets the range of a scroll bar.


SqlClearImmediate Disconnects the Sql Handle used by SqlImmediate.

SqlClose Closes a named cursor.

SqlCommit Commits the current SQL transaction.




SqlConnect Connects a Sql Handle to a database.

SqlContextClear Clears the context set by SqlContextSet.

SqlContextSet Sets the context for later compilation and fetching.

SqlContextSetToForm Sets context to form name.

SqlDirectoryByName Gets the names of databases on a given server.

SqlDisconnect Disconnects a Sql Handle from a database.

SqlDropStoredCmd Deletes a stored command.

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

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

SqlExecute Executes a SQL statement.

SqlExecutionPlan Gets the execution plan for a compiled SQLstatement.

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 reportsreal 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 anINSERT, UPDATE, or DELETE.

SqlGetParameter Returns a database parameter.




of

r a

.

for

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




for

ed

r.

String Conversion FunctionsThese functions manipulate string data by changing the form of a string or lookingsubstrings.


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, startingwith 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 specifinumber of times.

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

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

SalStrScan Finds a string within a string.

SalStrSetBufferLength Sets the length of the specified string buffe

SalStrToDate Converts a string to a date/time value.

SalStrTokenize Parses a string into substrings.

SalStrToNumber Converts a string to a number.

SalStrTrim and SalStrTrimX Removes white space from a string.

SalStrUncompress Decompresses a string.

SalStrUpper and SalStrUpperX Converts a string to uppercase.



r

.

d

Table Window FunctionsThese functions manage table windows.

VisStrExpand Expands a template string by inserting one omore array elements.

VisStrPad Pads a string with trailing blanks and returnsthe result.

VisStrProper Converts a string to mixed case.

VisStrRightTrim Trims trailing blanks from a string.

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

VisStrSubstitute Substitutes all occurrences of one string withanother string.

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


SalTblAnyRows Determines whether any rows have certain flags set.

SalTblClearSelection Clears the selection of rows in a table window.

SalTblColumnAverage Computes the average of a column's values

SalTblColumnSum Computes the sum of a column's values.

SalTblCopyRows Copies the contents of specified rows to theClipboard.

SalTblCreateColumn Creates columns at runtime.

SalTblDefineRowHeader Defines the appearance and behavior of arow header.

SalTblDefineSplitWindow Defines how a table window is split horizontally.

SalTblDeleteRow Deletes a row.

SalTblDeleteSelected Applies a DELETE statement to all selecterows.




e

.

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




SalTblQueryContext Gets the current context row.

SalTblQueryFocus Identifies the cell with the focus.

SalTblQueryLockedColumns Returns the number of locked columns.

SalTblQueryRowFlags Queries a row's flags.

SalTblQueryRowHeader Gets the definition of a row header.

SalTblQueryScroll Gets the current scroll position and range.

SalTblQuerySplitWindow Specifies how the table window is split horizontally.

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

SalTblQueryVisibleRange Gets the current visible range.

SalTblReset Clears a table window.

SalTblScroll Scrolls to a specified cell.

SalTblSetCellTextColor Sets a cell's text color.

SalTblSetColumnFlags Sets or clears a column's flags.

SalTblSetColumnPos Moves a column.

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

SalTblSetColumnTitle Sets a column's title.

SalTblSetColumnWidth Sets a column's width.

SalTblSetContext Sets the context row.

SalTblSetFlagsAnyRows Sets or clears row flags.

SalTblSetFocusCell Sets the focus to a specified cell.

SalTblSetFocusRow Sets the focus frame row.

SalTblSetLockedColumns Defines the number of columns to lock.

SalTblSetRange Defines the minimum and maximum rows.

SalTblSetRow Sets focus to a row.

SalTblSetRowFlags Sets or clears row flags.




f

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

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


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.




a

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.

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 orcheck box is checked.

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




l

.

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 adata field, multiline field, table window column, or picture.

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

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

SalSetFocus Sets the focus to a window.

SalSetWindowLabelText Sets a window's background text.

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

SalSetWindowSize Resizes a window.

SalSetWindowText Sets a window's text.

SalShowWindow Makes a window visible.

SalShowWindowAndLabel Hides a window and its associated label.

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

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

SalStatusSetVisible Shows or hides a top-level window's optionastatus 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 Converts a window handle to a number.

VisWinEnumProps Enumerates the property list for a specified window.

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

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

VisWinRemoveProp Removes a property list entry for a specifiedwindow.

VisWinSetFlags Sets flags for a specified window.

VisWinSetProp Adds a new property list entry or changes anexisting 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.



iled an


Chapter 2

Centura Builder Functions

This is an alphabetical list of the Centura Builder functions accompanied by detainformation about each function’s purpose, its parameters and return value, and example.

Function descriptions include:

• Syntax

• Description

• Parameters

• Return value

• See Also

• Example


Chapter 2 Centura Builder Functions

on.

n aves

ort.

hen ich

SalAbortSyntax bOk = SalAbort ( nExitCode )

Description Halts processing of the current menu action, message action, or application actiUse 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 aerror occurs, SalAbort terminates the current calling sequence of functions and lethe application in the state it was prior to the first function call of that sequence.

Parameters nExitCode Receive Number. The status of the exit performed by SalAbCentura ignores this parameter as input.

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

See Also SalQuit

Example If NOT SqlConnect ( hSql )

Call SalAbort ( -1 )

SalAppDisableSyntax bOk = SalAppDisable ( )

Description Disables input to all open applications. Use SalAppDisable and SalAppEnable wthere are multiple applications running simultaneously and you want to control whapplication receives user input.

Parameters No parameters.


See Also SalAppEnable

Example Call SalAppDisable ( )

Call SalLoadAppAndWait ( 'Excel', '' )

Call SalAppEnable ( )


ts

ns

f ys

For

SalAppEnableSyntax bOk = SalAppEnable ( )

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


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

See Also SalAppDisable

Example Call SalAppDisable ( )

Call SalLoadAppAndWait ( 'Excel', '' )

Call SalAppEnable ( )

SalAppFindSyntax hWnd = SalAppFind ( strAppName, bActivate )

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

SalAppFind first looks for running instances of Centura applications and then forrunning instances of other Windows applications.

If you specify the calling application's name in SalAppFind, Centura can only findanother running instance of it. You can use this feature to prevent more than oneinstance of an application running.

If there are multiple instances of a single application, SalAppFind finds and returthe window handle of the first instance it finds.

If an application has multiple top-level windows, SalAppFind returns the handle othe first top-level window it finds. Calling SalAppFind multiple times does not alwareturn 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. 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.



Return Value hWnd is the handle of the window.

Example On SAM_AppStartup

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

Call SalQuit( )

SalArrayAvgSyntax nAvg = SalArrayAvg ( nArrayNum )

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

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

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

See Also SalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum

Example On SAM_Create

Set dfAvg = SalArrayAvg ( nArrayNum )

SalArrayDimCountSyntax bOk = SalArrayDimCount ( aArray, nDim )

Description Returns the number of dimensions in an array.

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

nDim Receive Number. Number of dimensions in the array.


See Also SalArrayAvgSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBound


SalArraySum


Set bOk = SalArrayDimCount (aArray, nDim)

If nDim = 0

Set bDimTrue = False

SalArrayGetLowerBoundSyntax bOk = SalArrayGetLowerBound ( aArray, nDim, nBound )

Description Returns the lower bound of an array.


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

nBound Receive Number. Lower bound value.


See Also SalArrayAvgSalArrayDimCountSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum

Example On SAM_Click

Set bOk = SalArrayGetLowerBound (aArray, nBound)

SalArrayGetUpperBoundSyntax bOk = SalArrayGetUpperBound ( aArray, nDim, nBound )

Description Returns the upper bound of an array.



nBound Receive Number. Upper bound value.




See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum


Set bOk = SalArrayGetUpperBound (aArray, nBound)

SalArrayIsEmptySyntax bData = SalArrayIsEmpty ( aArray )

Description Determines if a dynamic array contains data.


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

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayMaxSalArrayMinSalArraySetUpperBoundSalArraySum


If Not SalArrayIsEmpty (aArray)

Call ...


SalArrayMaxSyntax nMax = SalArrayMax ( nArrayNum )

Description Returns the maximum value in an array of numbers.


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

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMinSalArraySetUpperBoundSalArraySum


Set dfMax = SalArrayMax ( nArrayNum )

SalArrayMinSyntax nMin = SalArrayMin ( nArrayNum )

Description Returns the minimum value in an array of numbers.

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

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

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArraySetUpperBoundSalArraySum


Set dfMin = SalArrayMin ( nArrayNum )



py ction

SalArraySetUpperBoundSyntax bOk = SalArraySetUpperBound ( aArray, nDim, nBound )

Description Sets the upper bound of an array.

When you call this function for a dimension other than the first, Centura must comost of the array's data. There can be a performance cost when you call this funfor any dimension but the first one.



nBound Number. Upper bound value. Specify -1 to reset a dynamicarray to zero elements. Specify AC_Dynamic to change a static array to a dynamic array. (You can make only the firstdimension of an array dynamic.)


See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBoundSalArrayIsEmptySalArrayMaxSalArrayMinSalArraySum


Call SalArraySetUpperBound (aArray, 1, 5)

SalArraySumSyntax nSum = SalArraySum ( nArrayNum )

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


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

See Also SalArrayAvgSalArrayDimCountSalArrayGetLowerBoundSalArrayGetUpperBound


ing

SalArrayIsEmptySalArrayMaxSalArrayMinSalArraySetUpperBound


Set dfSum = SalArraySum ( nArrayNum )

SalBringWindowToTopSyntax bOk = SalBringWindowToTop ( hWndToExpose )

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

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


See Also SalHideWindowSalShowWindow

Example If ( hWndCustomer )

Call SalBringWindowToTop ( hWndCustomer )

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


See Also SalMoveWindow

Example Call SalCenterWindow ( pbExample )



SalClearFieldSyntax bOk = SalClearField ( hWndFldToClear )

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

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


See Also SalIsNull

Example If ( dfAge < 0 )

Call SalClearField ( dfAge )

SalColorFromRGBSyntax nColor = SalColorFromRGB ( nRed, nGreen, nBlue )

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

Parameters nRed Number. A number from 0 to 255.

nGreen Number. A number from 0 to 255.

nBlue Number. A number from 0 to 255.

Return Value nColor is the color created.

See Also SalColorGetSalColorGetSysColorSalColorSetSalColorToRGB

Example Set nRed = 128

Set nGreen = 128

Set nBlue = 128

Set nColor = SalColorFromRGB ( nRed, nGreen, nBlue )

If NOT SalColorSet ( hWndItem, COLOR_IndexWindow, nColor )

...


e

one

ow

arent

one

SalColorGetSyntax nColor = SalColorGet ( hWndColored, nColorIndex )

Description Gets a window's color.

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

nColorIndex Number. The color of a part of the window, represented by 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 windcolors (excluding COLOR_Default and the three COLOR_Sys* constants).

If you specify COLOR_IndexTransparent in the second parameter and the transpcolor is not set, SalColorGet returns COLOR_None.

See Also SalColorFromRGBSalColorGetSysColorSalColorSetSalColorToRGB

Example Set nColor = SalColorGet ( hWndItem, COLOR_IndexWindow )

If nColor = COLOR_Default

Call SalColorSet ( hWndItem, COLOR_IndexWindow,

COLOR_Magenta )

SalColorGetSysColorSyntax nColor = SalColorGetSysColor ( nColorIndex )

Description Gets a system color.

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

COLOR_SysWindow

COLOR_SysWindowFrame

COLOR_SysWindowText



nts).

se

one

.

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

See Also SalColorFromRGBSalColorGetSalColorSetSalColorToRGB

Example Set nSysColorBckgrnd = SalColorGetSysColor ( COLOR_SysWindow )

SalColorSetSyntax bOk = SalColorSet ( hWndToSet, nColorIndex, nColor )

Description Sets a window's color.

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

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

COLOR_IndexCellText

COLOR_IndexTransparent

COLOR_IndexWindow

COLOR_IndexWindowText

nColor Number. A user-defined value, a value formulated using SalColorFromRGB, or any of the predefined windows colorsTo turn off the transparent color, specify COLOR_None.


See Also SalColorFromRGBSalColorGetSalColorGetSysColorSalColorToRGB

Example Call SalColorSet ( hWndItem, COLOR_IndexWindow, COLOR_Red )


ow

e

he

e

eter f a

ates

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

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

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

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

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

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


See Also SalColorFromRGBSalColorGetSalColorGetSysColorSalColorSet

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

... Error ...

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

strReturn, dtReturn, hWndReturn, bInhibitErrors, strContext )

Description Evaluates an expression and returns the expression's value in the receive paramappropriate to its data type. SalCompileAndEvaluate lets you access the value ovariable 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 anerror, 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 evaluto a string.



n

.

er

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 applicatioprocesses 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 eithSalContextBreak or SalContextCurrent.

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

EVAL_DateEVAL_HandleEVAL_IfEVAL_NumberEVAL_SetEVAL_StringEVAL_Template

See Also SalContextBreak SalContextCurrent

Example Set nType = SalCompileAndEvaluate ( strExpression, nError,

nErrorPos,nReturn, strReturn, dtReturn, hWndReturn,

FALSE, strContext )

If nType = EVAL_Number

Call SalNumberToStr ( nReturn, 0, strString )

...

SalContextBreakSyntax strContext = SalContextBreak ( )

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


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

See Also SalCompileAndEvaluateSalContextCurrent


e

ss a

f its

ting a the e

form

er is

ated nly

Example Set strContext = SalContextBreak ( )

SalContextCurrentSyntax strContext = SalContextCurrent ( )

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


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

See Also SalCompileAndEvaluateSalContextBreak

Example Set strContext = SalContextCurrent ( )

SalCreateWindowSyntax hWndCreated = SalCreateWindow ( tWndToCreate, hWndOwner, Parm1,

Parm2, ... )

Description Creates modeless dialog boxes, MDI windows, form windows, and top-level tablwindows at runtime.

This function accepts a string or a template as the first parameter. When you pastring, you cannot also pass window parameters.

If you specify an owner (hWndOwner), the new window always displays on top oowner, closes when its owner closes, and hides when its owner is minimized.

SalCreateWindow can pass data to and from the window being created by accepvariable number of parameters. The data types of these parameters must matchparameter data types of the window being created. You define parameters for thwindow in the Window Parameters section of the application outline.

For example, this code passes the variable, nGlobal and the data field, df1 to thewindow, frmMain. Before SAM_Create is sent to frmMain, its first window parameter is initialized with the value of nGlobal and its second window parametinitialized with the value of df1.

Call SalCreateWindow ( frmMain, hWndNULL, nGlobal, df1 )

You can use window parameters to return information from the window being creby using a receive type. However, you can initialize receive window parameters owith variables. This means that you cannot pass a data field or any other windowobject to a window parameter that was defined as a receive type.

Parameters tWndToCreate Template or String. The name of the window to create.



w. f t

x at

ss a

f its

ated ers

form

er is

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

hWndOwner Window Handle. The handle (or name) of the owner windoSpecify hWndNULL if there is no owner window. Note that iyou create a toplevel form inside of a MDI window, then thaMDI 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 variablenumber of window parameters.

Return Value hWndCreated is the handle of the new window.

See Also SalModalDialogSalDestroyWindow


If NOT SalCreateWindow (frmCustomer, hWndNULL)

...Error...

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


If you specify an owner (hWndOwner), the new window always displays on top oowner, closes when its owner closes, and hides when its owner is minimized.

SalCreateWindowExWithParms can pass data to and from the window being creby accepting a variable number of parameters. The data types of these parametmust 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 thewindow, frmMain. Before SAM_Create is sent to frmMain, its first window parameter is initialized with the value of nGlobal and its second window parametinitialized with the value of df1.


ated nly

w.

Call SalCreateWindowExWithParms ( frmMain, hWndNULL, nLeft, nTop,nWidth, nHeight, nGlobal, df1 )


Parameters tWndToCreate Template or String. The name of the window to create.

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

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

nLeft, nTop Position of the window in form units.

nWidth, nHeight Size of the window in form units.

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

CREATE_AsChild Create the windows as a child hWndParent. HWndParent must be a form, dialog box or tool bar.

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

CREATE_Hidden The window will be created but not shown.



Return Value hWndCreated is the handle of the new window.

See Also SalModalDialogSalDestroyWindow


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

...Error...



the

SalCursorClearSyntax bOk = SalCursorClear ( hWnd, nType )

Description Clears a window's cursor.

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

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

CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorSetSalCursorSetFileSalCursorSetString


Call SalCursorClear (frmMain, Cursor_Windows)

SalCursorSetSyntax bOk = SalCursorSet ( hWnd, tResource, nType )

Description Sets a window's cursor.


tResource Template. An icon resource from the Resources section ofoutline. 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


set


CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorClearSalCursorSetFileSalCursorSetString


Call SalCursorSet (frmMain, Cursor_Arrow, Cursor_Window)

SalCursorSetFileSyntax bOk = SalCursorSetFile ( hWnd, sFile, nType )

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


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


CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorClearSalCursorSetSalCursorSetString


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

SalCursorSetStringSyntax bOk = SalCursorSetString ( hWnd, sBuffer, nType )

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




our,

ult.

is 92,

nd

31

23

nd

and

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


CURSOR_DisableDrop

CURSOR_DragDrop

CURSOR_Window


See Also SalCursorClearSalCursorSetSalCursorSetFile


Call SalCursorSetString (frmMain, strCurBuf, Cursor_Window)

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

Description Returns the date/time constructed from the parameters nYear, nMonth, nDay, nHnMinute, and nSecond.

If you specify invalid parameter values, an unexpected date construction can res

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 dtDate begins with 0092.

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

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

nDay Number. A number with a 2-digit day value between 01 andinclusive.

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

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

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

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



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

SalDateCurrentSyntax dtNow = SalDateCurrent ( )

Description Returns the PC's current date/time.

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


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


Set dfCurrent = SalDateCurrent ( )

SalDateDaySyntax nDay = SalDateDay ( dtDateTime )

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

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

Return Value nDay is a number between 1 and 31.

See Also SalDateMonth

SalDateYear

Example Set nDay = SalDateDay ( dtDateTime )

SalDateHourSyntax nHour = SalDateHour ( dtDateTime )

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


Return Value nHour is a number between 0 and 23.

See Also SalDateMinute

SalDateSecond



cify

ify

Example Set nHour= SalDateHour ( dtDateTime )

SalDateMinuteSyntax nMinute = SalDateMinute ( dtDateTime )

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


Return Value nMinute is a number between 0 and 59.

See Also SalDateHour

SalDateSecond

Example Set nMinute = SalDateMinute ( dtDateTime )

SalDateMonthSyntax nMonth = SalDateMonth ( dtDateTime )

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


Return Value nMonth is a number between 1 and 12.

Related Functions

SalDateDaySalDateYear

Example Set nMonth = SalDateMonth ( dtDateTime )

SalDateMonthBeginSyntax dtMonthBegin = SalDateMonthBegin ( dtDateTime )

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


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

See Also SalDateQuarterBegin


ecify

ecify

SalDateWeekBegin

Example Set dtMonthBegin = SalDateMonthBegin ( SalDateCurrent ( ) )

SalDateQuarterSyntax nQuarter = SalDateQuarter ( dtDateTime )

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


Return Value nQuarter is a number between 1 and 4.

Example Select Case ( SalDateQuarter ( dtDate ) )

Case 1

Set strQuarter = 'First Quarter'

Break

...

SalDateQuarterBeginSyntax dtQuarterBegin = SalDateQuarterBegin ( dtDateTime )

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


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

See Also SalDateMonthBeginSalDateWeekBeginSalDateYearBegin

Example Set dtQuarterBegin = SalDateQuarterBegin

( SalDateCurrent ( ) �

SalDateSecondSyntax nSeconds = SalDateSecond ( dtDateTime )

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




t

Return Value nSeconds is a number between 0 and 59.

See Also SalDateHourSalDateMinute

Example Set nSeconds = SalDateSecond ( dtDateTime )

SalDateToStrSyntax nLength = SalDateToStr ( dtDateTime, strDate )

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

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

strDate Receive string. The resulting string value.

Return Value nLength is the length of strDate.

See Also SalFmtFormatDateTimeSalStrToDate

Example Call SalDateToStr ( dtDateTime, strDateTime )

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

SalDateWeekBeginSyntax dtWeekBegin = SalDateWeekBegin ( dtDateTime )

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


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

See Also SalDateMonthBeginSalDateQuarterBeginSalDateYearBegin

Example Set dtWeekBegin = SalDateWeekBegin ( SalDateCurrent ( ) )


ecify

a

lue

SalDateWeekdaySyntax nWeekday = SalDateWeekday ( dtDateTime )

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


Return ValuenWeekday is a number between 0 and 6.

Example Select Case ( SalDateWeekday ( dtDate ) )

Case 0

Set strWeekday = 'Saturday'

Break

SalDateYearSyntax nYear = SalDateYear ( dtDateTime )

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


Return Value nYear is the year portion of a date.

See Also SalDateDaySalDateMonth

Example Set nYear = SalDateYear ( dtDateTime )

SalDateYearBeginSyntax dtYearBegin = SalDateYearBegin ( dtDateTime )

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


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

See Also SalDateMonthBeginSalDateQuarterBeginSalDateWeekBegin



ng. If tring

bal

ring m is

Example Set dtYearBegin = SalDateYearBegin ( SalDateCurrent ( ) )

SalDDEAddAtomSyntax nNewAtom = SalDDEAddAtom ( strStringToAdd )

Description Adds a string to the global atom table and creates a new atom to identify the strithe string to add is already in the atom table, the atom reference count for that sincreases by one.

Call SalDDEGetAtomName to retrieve the string from the atom table.

Parameters strStringToAdd String. The string (255 characters or less) to add to the gloatom table.

Return Value If the function succeeds, nNewAtom is the value of the new global atom. If the stalready exists, nNewAtom is the value of the existing atom. Otherwise, nNewAtozero (0).

See Also SalDDEDeleteAtomSalDDEFindAtomSalDDEGetAtomName

Example Set nOptions = SalDDEAlloc ( )

Call SalDDESetOptions ( nOptions, 0, CF_Text )

Set nItem = SalDDEAddAtom ( strItem )

Call SalDDEPost( hWndServer, WM_DDE_Advise, hWndForm,

nOptions, nItem )

SalDDEAllocSyntax 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 ( )


le.

t is

a

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

When the application terminates, call this function for each successful SalDDEAddAtom call you made.

Parameters nAtomToDelete Number. The atom to delete.

Return Value If the function succeeds, nAtomCount is zero (0). If the function fails, nAtomCounequal to nAtomToDelete.

See Also SalDDEAddAtom

Example Call SalDDEDeleteAtom ( nReceivedItem )

SalDDEExtractSyntax bOk = SalDDEExtract ( nwParam, nlParam, hWndSender, nLowlParam,

nHighlParam )

Description Extracts the sender's window handle and the data in the lParam parameter uponreceipt 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)

SalDDEExtractCmdSyntax bOk = SalDDEExtractCmd ( nCommand, strCommand, nCommandSize )

Description Extracts the command string referenced by the high-order word of the lParam ofWM_DDE_Execute message.

Parameters nCommand Number. The memory handle for the command string.



the

strCommand Receive String. The command string.

nCommandSize Number. The maximum size of the command string.


See Also SalDDESetCmd

Example If SalDDEExtractCmd ( nCommand, strCommand, nCommandSize )

Set fldData = strCommand

SalDDEExtractDataTextSyntax 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 thedata and other information.

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

strData Receive string. The data.

nDataSize Number. The size of the data buffer.


See Also SalDDESetDataText

Example Call SalDDEExtractDataText ( nData, nStatus, strDDEData,

DDE_Data )

SalDDEExtractOptionsSyntax bOk = SalDDEExtractOptions ( nOptions, nFlags, nFormat )

Description Extracts the sender's window handle and the data in the lParm parameter from aWindows DDE message.

For more about DDE, see the DDE chapter in the Centura Developer’s Reference.

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.


tring.

tura

lloc

ry if

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 )

SalDDEFindAtomSyntax nAtom = SalDDEFindAtom ( strTopicString )

Description Searches the global atom table and returns the atom associated with the given s

Parameters strTopicString String. The string to search for.

Return Value nAtom is the global atom associated with strTopicString. nAtom is zero (0) if Cendoes not find the string in the atom table.

See Also SalDDEGetAtomName

Example If nApplication = 0

Set nApplication = SalDDEAddAtom ( DDEServer_Application)

Call SalMessageBox ( 'Add Application atom', 'DDE', MB_Ok)

SalDDEFreeSyntax 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 SalDDEAcall you made.

Parameters nMemory Number. The memory handle to free.

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

See Also SalDDEAlloc



(0) if

t. m a

Example Call SalDDEDeleteAtom ( nReceivedItem )

If nStatus & DDE_fRelease

Call SalDDEFree ( nData )

SalDDEGetAtomNameSyntax 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 there is no such atom.

See Also SalDDEAddAtomSalDDEDeleteAtomSalDDEFindAtom

Example Set nAtomSize = SalDDEGetAtomName ( nAtom, strAtomName, nStringLength )

SalDDEGetExecuteStringSyntax strCommand = SalDDEGetExecuteString ( nMsglParam )

Description A server application calls this function to get the command string sent by a clienThis function converts the lParam of the SAM_DDE_ClientExecute message fronumeric value to a string value and returns that string value in strCommand.

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

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

Example Set strCommand = SalDDEGetExecuteString ( nMsglParam )

SalDDEPostSyntax nReturn = SalDDEPost ( hWndReceiver, nMessage, hWndSender, nLowlParam,

nHighlParam )

Description Posts all WM_DDE_* messages except:

• WM_DDE_Initiate


iver ut

t

h

to ,

• WM_DDE_Ack in response to a WM_DDE_Initiate

SalDDEPost places a message in the receiver's message queue, letting the receprocess messages already in its message queue first. SalDDEPost returns withowaiting 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 sentwith the message.

nHighlParam Number. The high-order word of the lParam parameter senwith the message.

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

See Also SalDDESendSalDDESendAll

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

SalDDERequestSyntax 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 witthe 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 ablehold a value (for example, a data field, table window columnmultiline field, or combo box) and it must be defined with a data type of string.




,

nd does

t

)

have

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 )

SalDDESendSyntax 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'smessage queue; instead, it does an immediate send of the message. SalDDESenot return until the receiver has processed the message.

Parameters hWndReceiver Window Handle. The receiver's window handle.

nMessage Number. The message number.




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

See Also SalDDEPostSalDDESendAll

Example Call SalDDESend ( hWndClient, WM_DDE_Ack, hWndForm,

nApplication, nTopic )

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

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

Parameters nMessage Number. The message number.




t

h


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 )

SalDDESendExecuteSyntax 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 witthe DDE service, topic, and item.

strService String. The DDE service.




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 thesyntax rules, see the section about the WM_DDE_Execute message at the end of the DDE chapter in the Centura Developer’s Reference.


Example If NOT SalDDESendExecute ( frmMain, dfApplication2,

dfTopic2, dfItem2, 10000, strSend )


Call Sal Message Box ( 'SalDDESendExecute ' ||

'to Excel server failed', 'DDE Error',



ith

.

s

he

SalDDESendToClientSyntax 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 wthe 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 updateall 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.



Example If NOT SalDDESendToClient ( frmMain, dfServerData, 0, 100 )


SalDDESetCmdSyntax 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 tcommand string.

strCommand String. The command to execute.


See Also SalDDEExtractCmd

Example Call SalDDESetCmd ( nCommand, strCommand )

Call SalDDEPost ( hWndServer, WM_DDE_Execute, hWndForm, 0,

nCommand )


w

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


See Also SalDDEExtractDataText

Example Call SalDDESetDataText ( nData, nDDEFlags, strData )

Call SalDDEPost ( hWndServer, WM_DDE_Poke, hWndForm, nData,

nItem )

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


Example Call SalDDESetOptions ( nOptions, 0, CF_Text )

Set nItem = SalDDEAddAtom ( strItem )

Call SalDDEPost ( hWndServer, WM_DDE_Advise, hWndForm,

nOptions, nItem )



m

can

ith

,

n.

n

of to

SalDDEStartServerSyntax bOk = SalDDEStartServer ( hWndServer, strService, strServerTopic, strServerIte

)

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 clientsconnect to it.

Parameters hWndServer Window Handle. The server's window handle associated wthe DDE application, topic, and item.





Example If NOT SalDDEStartServer ( frmMain, dfServerApplication, dfServerTopic, dfServer Item)


SalDDEStartSessionSyntax bOk = SalDDEStartSession ( hWndDest, strService, strServerTopic, strServerItem

nTimeout )

Description A client calls this function to start a hot link conversation with a server applicatio

Parameters hWndDest Window Handle. The handle (or name) of an object that cahold 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 valuestrServerItem. A SAM_DDE_DataChange message is sent hWndDest after the value of the object changes.







ith

. on.

d

ted ou

Example If NOT SalDDEStartSession ( mlString1, dfApplication1, dfTopic1, dfItem1, 1000)


Call SalMessageBox ( 'SalDDEStartSession with SW server failed','DDE Error', MB_Ok | MB_IconHand )

SalDDEStopServerSyntax 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 Window Handle. The server's window handle associated wthe DDE service, topic, and item.


Example If NOT SalDDEStopServer ( frmMain )


SalDDEStopSessionSyntax bOk = SalDDEStopSession ( hWndDest )

Description A client calls this function to end a hot link conversation with a server applicationThe client must call SalDDEStopSession for each successful SalDDEStartSessi

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


Example If NOT SalDDEStopSession ( mlString1 )


SalDestroyWindowSyntax bOk = SalDestroyWindow ( hWndDestroy )

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

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



bel.

ne.


See Also SalCreateWindowSalEndDialog


Call SalDestroyWindow ( hWndForm )

SalDisableWindowSyntax 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 thewindow is a data field, it cannot receive the focus.

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


See Also SalDisableWindowAndLabelSalEnableWindowSalIsWindowEnabled


Call SalDisableWindow ( pbUpdate )

SalDisableWindowAndLabelSyntax bOk = SalDisableWindowAndLabel ( hWndDisable )

Description Disables keyboard and mouse input to a window and grays out its associated la

A label is the background text that immediately precedes the window in the outliThe bacground text must have a mneumonic.

If the window contains text (for example, a push button), the text is grayed. If thewindow is a data field, it cannot receive the focus.

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


See Also SalDisableWindow

SalEnableWindowAndLabel


ing

cts.

push

as its

SalIsWindowEnabled

SalGetWindowLabelText

SalHideWindowAndLabel

SalSetWindowLabelText

SalShowWindowAndLabel

Example Call SalDisableWindow ( dfName )

SalDlgChooseColorSyntax bRet = SalDlgChooseColor ( hWndOwner, nColor )

Description Displays the Windows Color dialog box where the user can either select an existcolor 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 sele

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

See Also SalDlgChooseFont


Call SalDlgChooseColor ( frmMain, nColor )

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

nColor )

Description Displays the Windows Font dialog box where the user can choose a font as well 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 Window Handle. The handle (or name) of the owner of the dialog box. Specify hWndNULL if it has no owner.

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



so

push

er

ify

o

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

nEnhancements Receive Number. The font enhancements (italic, bold, andon), 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 button.

See Also SalDlgChooseColor

Example Call SalDlgChooseFont ( frmMain, strFontName,

nSize, nEnhancements )

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

strFile, strPath )

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

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

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

strFilters String. An array of file filters and their descriptions. Each filtmust have a description that precedes the filter in the array.

For example, to enable users to open files with only specificextensions, 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. Spec6 to display all three filters.

You can limit the number of filters displayed. For example, tdisplay only the first two filters (*.exe and *.dll), specify 4.


ple, ult

is

ses.

a

ra

ncel

nIndex Receive Number. The filter that the user chooses. For examif the user chooses Initialization Files, nIndex is 3. The defafilter 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 valueincorrect or invalid, Centura ignores your attempt to set the default display value.

strPath Receive String. The full path name of the file the user choo

To initialize the combo box in which the paths display, assignpath to a variable prior to calling SalDlgOpenFile. In the subsequent SalDlgOpenFile call, specify the variable for thisparameter. If the variable's value is incorrect or invalid, Centuignores 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 Capush button.

See Also SalDlgSaveFile

Example Message Actions

On SAM_Create







strFilters, 6, nIndex, strFile, strPath)

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



er

ify

,

cts

r

t

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

strFile, strPath )

Description Displays a Windows dialog box where the user can save a file.

If you do not specify a file extension, Centura saves the file with the extension displayed by the Save File as Type combo box.

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

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

strFilters String. An array of file filters and their descriptions. Each filtmust have a description that precedes the filter in the array.

For example, to enable users to save files with only specificextensions, populate the strFilters array with filters such as:







nFilters Number. The number of elements in strFilters.

The above array of six elements contains three filters. Spec6 to display all three filters.

You can limit the number of filters that display. For exampleto see only the first two filters (*.exe and *.dll), specify 4.

nIndex Receive Number. The filter that the user chooses. This reflethe format in which Centura saves the file.

A file's extension does not imply format. By default, if the usedoes not specify a file extension, Centura saves the file withthe first extension in strFilters. In this case, the default file extension is .EXE.

For example, if the user chooses Dynamic Link Libraries, budoes not specify a file extension, the file is saved in DLL format but with an .EXE extension.

strFile Receive String. The file name the user chooses.


le. for

.

a e ra

To initialize the combo box in which the file names display, assign a file name to a variable prior to calling SalDlgSaveFiIn the subsequent SalDlgSaveFile call, specify the variable 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, assignpath name to a variable prior to calling SalDlgSaveFile. In thsubsequent SalDlgSaveFile call, specify the variable for thisparameter. If the variable's value is incorrect or invalid, Centuignores your attempt to set the default display value.


On SAM_Create







On SAM_Click

Call SalDlgSaveFile ( frmMain, 'Save File',

strFilters, 6,nIndex, strFile, strPath )

SalDragDropDisableDropSyntax bOk = SalDragDropDisableDrop ( )

Disables dropping while in drag mode.



See Also SalDragDropEnableDrop


Call SalDragDropDisableDrop ()



.

SalDragDropEnableDropSyntax bOk = SalDragDropEnableDrop ( )

Description Enables dropping while in drag mode.



See Also SalDragDropDisableDrop


Call SalDragDropEnableDrop ()

SalDragDropGetSourceSyntax bOk = SalDragDropGetSource ( hWndSource, nX, nY )

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

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

These window types can be source windows:

Combo box Multiline field

Data field Picture

List box Table window

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

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


See Also SalDragDropGetTarget


Call SalDragDropGetSource (hWndSource,nX, nY)


SalDragDropGetTargetSyntax bOk = SalDragDropGetTarget ( hWndTarget, nX, nY )

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

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

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.


See Also SalDragDropGetSource


Call SalDragDropGetTarget (hWndRecv,nX, nY)

SalDragDropStartSyntax bOk = SalDragDropStart ( hWndSource )

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

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


See Also SalDragDropStop


Call SalDragDropStart (frmMain)

SalDragDropStopSyntax bOk = SalDragDropStop ( )

Description Ends drag mode.

Parameters No parameter.




is

ther

or .

See Also SalDragDropStart

Example Set bOk = SalDragDropStop ( )

SalDrawMenuBarSyntax bOk = SalDrawMenuBar ( hWndForm )

Description Redraws the menu bar for a given form window or top-level table window. Call thfunction 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 oreasons.

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



Call SalDrawMenuBar ( frmMain)

SalDropFilesAcceptFilesSyntax bOk = SalDropFilesAcceptFiles ( hWnd, bAccept )

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


bAccept Boolean. Specify whether hWnd can accept a file from Windows' File Manager.

The default for editable pictures is TRUE; the default for all other window types is FALSE.


See Also SalDropFilesQueryFilesSalDropFilesQueryPoint

Example Set bAccept = SalDropFilesAcceptFiles ( hWnd, TRUR )


iles

SalDropFilesQueryFilesSyntax nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )

Description Retrieves the names of the files dropped on a window. Receipt of the SAM_DropFilesmsg_SAM_DropFiles message indicates that the user dropped fonto 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 SalDropFilesAcceptFilesSalDropFilesQueryPoint


Set nFiles = SalDropFilesQueryFiles ( hWndSource, sArrayFiles )



es r

bject n for

LSE Paste

SalDropFilesQueryPointSyntax bOk = SalDropFilesQueryPoint ( hWnd, nX, nY )

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

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

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

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


See Also SalDropFilesAcceptFilesSalDropFilesQueryFiles


Call SalDropFilesQueryPoint ( hWnd, nX, nY )

SalEditCanCopyToSyntax bOk = SalEditCanCopyTo ( )

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


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

See Also SalEditCopyTo

Example Menu

Popup Menu: &Edit

Menu Item: &Copy To

...

Menu Settings

Enabled when: SalEditCanCopyTo ( )


hen

nto n

.

SalEditCanCutSyntax bOk = SalEditCanCut ( )

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


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

See Also SalEditCut

Example Menu Settings

Enabled when: SalEditCanCut ( )

...

SalEditCanPasteSyntax bOk = SalEditCanPaste ( )

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

No Parameters

Return ValuebOk is TRUE if there is data on the Clipboard to be pasted and FALSE otherwise

See Also SalEditPaste


Enabled when: SalEditCanPaste ( )

SalEditCanPasteFromSyntax bOk = SalEditCanPasteFrom ( )

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


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

See Also SalEditPasteFrom



le

r


Enabled when: SalEditCanPasteFrom ( )

SalEditCanUndoSyntax bOk = SalEditCanUndo ( )

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

No Parameters

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

See Also SalEditUndo


Enabled when: SalEditCanUndo ( )

...

SalEditClearSyntax bOk = SalEditClear ( )

Description Deletes selected data from the data field, multiline field, table window column, opicture with the focus. Centura places deleted data in Windows' undo buffer.





SalEditCopySyntax bOk = SalEditCopy ( )

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




us.

om

re



...

Menu Actions

Call SalEditCopy ( )

SalEditCopyStringSyntax bOk = SalEditCopyString ( strString )

Description Copies a string to the Clipboard as text.

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


See Also SalEditPasteString

Example Menu Actions

Call SalEditCopyString ( mlNotes )

SalEditCopyToSyntax bOk = SalEditCopyTo ( )

Description Copies an object to a file from an editable picture. The picture must have the foc

This function only works when the picture's contents are the result of a Paste Froperation.



See Also SalEditCanCopyToSalEditPasteFrom


Call SalEditCopyTo ( )

SalEditCutSyntax bOk = SalEditCut ( )

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




to


See Also SalEditCanCut



SalEditPasteSyntax bOk = SalEditPaste ( )

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



See Also SalEditCanPaste


Call SalEditPaste ( )

SalEditPasteFromSyntax bOk = SalEditPasteFrom ( )

Description Copies a file to the editable picture with the focus.

This function displays the Paste From dialog box where the user can select a filepaste into the picture.

The user can retrieve these file types:

Type File Extension Description

BMP . Device-Independent Bitmap

DIB .dib Device-Independent Bitmap

GIF .gif Graphics Interchange Format

ICON .ico Icon File

PCX .pcx Paintbrush

TIFF .tif Tag Image File Format

JPEG *.jpg JPEG format


ntura

e.

The user can select a file of any type, even if the file type is not listed above. Cestill pastes it into the picture using a generic document icon for its image. The filecontents are available to the application through the SalPicGetString function.



See Also SalEditCanPasteFrom


Call SalEditPasteFrom ( )

SalEditPasteStringSyntax bOk = SalEditPasteString ( strString )

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

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


See Also SalEditCopyString

Example Call SalEditPasteString ( strOldClipboard )

SalEditUndoSyntax bOk = SalEditUndo ( )

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



See Also SalEditCanUndo


Enabled when: SalEditCanUndo ( )

WMF .wmf Windows MetaFile



l as

ne.

.

n.

SalEnableWindowSyntax bOk = SalEnableWindow ( hWndEnable )

Description Enables keyboard and mouse input to a window.

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


See Also SalDisableWindowSalEnableWindowAndLabelSalIsWindowEnabled

Example Call SalEnableWindow ( frmCustomer )

SalEnableWindowAndLabelSyntax bOk = SalEnableWindowAndLabel ( hWndEnable )

Description Enables keyboard and mouse input to a window and enables its associated labewell.

A label is the background text that immediately precedes the window in the outli

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


See Also SalDisableWindowAndLabelSalEnableWindowWindowEnabled


Call SalEnableWindowAndLabel ( dfName )

SalEndDialogSyntax bOk = SalEndDialog ( hWndModal, nReturn )

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

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

nReturn Number. The Return Value from the SalModalDialog functio



e

,

.

See Also SalModalDialog


Call SalEndDialog ( hWndForm, 0 )

SalFileCloseSyntax bOk = SalFileClose ( hFile )

Description Closes a file.

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


See Also SalFileOpen

Example If NOT SalFilePutStr ( hFile, sLine )

Call SalFileClose ( hFile )

Call SalMessageBeep ( 0 )

SalFileCopySyntax nStatus = SalFileCopy ( strSourcePath, strDestPath, bOverWrite )

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

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

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

bOverWrite Boolean. Specifies whether (TRUE) or not (FALSE) to overwrite the destination file.

If the destination file already exists and bOverWrite is FALSEthen SalFileCopy fails, and returns FILE_CopyExist. If the destination file already exists and bOverWrite is TRUE, thenSalFileCopy succeeds and the destination file is overwritten

Return Value nStatus is equal to one of the following values:

FILE_CopyDestFILE_CopyExistFILE_CopyOKFILE_CopyReadFILE_CopySrcFILE_CopyWrite



the s.

the se

the


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

SalFileCreateDirectorySyntax bOk = SalFileCreateDirectory ( strDir )

Description Creates a directory.

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

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

See Also SalFileRemoveDirectory

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

SalFileGetCSyntax bOk = SalFileGetC ( hFile, nChar )

Description Returns the next character in an open file. You must use this function in place ofSalFileGetChar function if the file contains non-ASCII (ANSI) or 16-bit character

If the character returned is a 16-bit character, the lead byte of the character is inhigh-order byte, and the trail byte is in the low-order byte. To get the lead byte, uSalNumberHighand 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 readnext character from the file, or if an invalid file handle is passed in hFile.

See Also SalFilePutC


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

OF_Read | OF_Binary )


r,

ant.

SalFileGetCharSyntax nChar = SalFileGetChar ( hFile )

Description Returns the next character in an open file.


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

See Also SalFilePutChar

Example If SalFileOpen ( fhDestFile, strDestFile, OF_Create

| OF_ReadWrite )

Loop

Set nChar = SalFileGetChar ( fhSrcFile )

...

SalFileGetCurrentDirectorySyntax bOk = SalFileGetCurrentDirectory ( strPath )

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

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


See Also SalFileSetCurrentDirectory


If NOT SalFileGetCurrentDirectory (strCurrentDir)

Call SalMessageBox ( 'Couldn't get current

directory', 'Error', 0 ��

SalFileGetDateTimeSyntax bOk = SalFileGetDateTime ( strFilename, dtDateTime )

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

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

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



urn/


See Also SalFileSetDateTime

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

SalFileGetDriveSyntax strDriveLetter = SalFileGetDrive ( )

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

No Parameters

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

See Also SalFileSetDrive


If SalFileGetDrive ( ) = 'A'

Set blsDriveA = TRUE

Else

Set blsDriveA = FALSE

SalFileGetStrSyntax bOk = SalFileGetStr ( hFile, strBuffer, nBufferSize )

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


strBuffer Receive String. The returned string.

nBufferSize Number. The maximum number of bytes to read.

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

See Also SalFilePutStr

Example If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE )

Call SalFilePutStr ( fhDestFile, strText )

Else

Break


e

d

SalFileOpenSyntax bOk = SalFileOpen ( hFile, strFileName, nStyle )

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

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

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

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


See Also SalFileClose

SalListFiles

SalFileOpenExt

Example Call SalFileOpen ( fhSrcFile, strSrcFile, OF_Read )

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

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

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

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

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

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


See Also SalFileOpenF


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

strReopen )



the

to

SalFilePutCSyntax bOk = SalFilePutC ( hFile, nChar )

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


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

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

See Also SalFileGetC

Example Loop

Call SalFilePutC ( hFile, nNull )

If nCount = 5

Break

Set nCount = nCount + 1

SalFilePutCharSyntax bOk = SalFilePutChar ( hFile, nChar )

Description Writes a character to an open file.


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


See Also SalFileGetChar

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

Call SalFilePutChar ( hFile, nChar )


ter to

ount

SalFilePutStrSyntax bOk = SalFilePutStr ( hFile, strString )

Description Writes a string to an open file. Centura appends a carriage return/line feed characthe string.


strString String. The string to write.


See Also SalFileGetStr

Example Loop

! Read each line from the source file and write it to

the destination file

If SalFileGetStr ( fhSrcFile, strText, LINE_SIZE )

Call SalFilePutStr ( fhDestFile, strText )

SalFileReadSyntax nResult = SalFileRead ( hFile, strBuffer, nBufferLength )

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


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

nBufferLength Number. The number of bytes to read.

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

See Also SalFileWrite

Example Call SalFileSeek ( fhInFile, nFilePos, FILE_SeekBegin )

Loop

Set nCharsRead = SalFileRead ( fhInFile, strBuffer,

nRecSize )



ry

r

r e

SalFileRemoveDirectorySyntax bOk = SalFileRemoveDirectory ( strDir )

Description Deletes a directory.

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

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

See Also SalFileCreateDirectory


Set bNotesOldDeleted = SalFileRemoveDirectory (strDir)

SalFileSeekSyntax bOk = SalFileSeek ( hFile, nBytes, nPosition )

Description Positions the file pointer in an open file. The next file operation (such as a read owrite) 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 numbeof bytes from nPosition where the next file operation will takplace.

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

FILE_SeekBegin

FILE_SeekCurrent

FILE_SeekEnd


See Also SalFileTell

Example Call SalFileSeek ( fhInFile, 0, FILE_SeekBegin )


rive ive's

.

ant

ger

SalFileSetCurrentDirectorySyntax bOk = SalFileSetCurrentDirectory ( strPath )

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

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


See Also SalFileGetCurrentDirectorySalFileSetDrive


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

SalFileSetDateTimeSyntax bOk = SalFileSetDateTime ( strFilename, dtDateTime )

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

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

dtDateTime Date/Time. The modification date and time.


See Also SalFileGetDateTime


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

SalFileSetDriveSyntax bOk = SalFileSetDrive ( strDriveLetter )

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

Parameters strDriveLetter String.0 The new disk drive letter. The length of this parameter's value is one character. If you specify a value larthan this, Centura reads only the first character.




tion

ble

See Also SalFileGetDriveSalFileSetCurrentDirectory


Set bDriveIsC = SalFileSetDrive ( 'c' )

SalFileTellSyntax nPos = SalFileTell ( hFile )

Description Returns the current position in an open file.


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

See Also SalFileSeek

Example Set nRecPos = SalFileTell ( fhInFile)

SalFileWriteSyntax nResult = SalFileWrite ( hFile, strBuffer, nBufferLength )

Description Writes a string to an open file.


strBuffer String. The string to write to hFile.

nBufferLength Number. The number of bytes to write.

Return Value nResult is the number of bytes written.

See Also SalFileRead

Example Call SalFileWrite ( fhInFile, strCharBuf, 1 )

SalFmtFieldToStrSyntax bOk = SalFmtFieldToStr ( hWndField, strValue, bFormat )

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

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


o

at. e ts

lt NI

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

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


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 defausettings in the [INTL] section and the user-defined [GTITOOLS] section of WIN.Ifor 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 )



in

oth a ies the

e of

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 settingsthe [INTL] section and the user-defined [GTITOOLS] section of WIN.INI for formatting.

Parameters nNumber Number. The number value to format.

strPicture String. The number picture format.

Return Value strNumber is a formatted number string.

See Also SalFmtFormatDateTime

SalFmtIsValidPicture

Example Set strNumber = SalFmtFormatNumber ( nNumber, strPicture )

SalFmtGetFormatSyntax nFormat = SalFmtGetFormat ( hWndField )

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

Note: Some of the Parameters have subparameters. For example, the date format has bsubparameter that specifies a date’s separator character and a subparameter that specifmonth/day/year sequence.

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

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

Date fields can be formatted as:FMT_Format_DateFMT_Format_DateTimeFMT_Format_PictureFMT_Format_TimeFMT_Format_Unformatted

Number fields can be formatted as:FMT_Format_Format_CurrencyFMT_Format_DecimalFMT_Format_Percentage


r

a

FMT_Format_PictureFMT_Format_Unformatted

String fields can be formatted as:FMT_Format_InvisibleFMT_Format_LowercaseFMT_Format_UppercaseFMT_Format_Unformatted

See Also SalFmtSetFormat


Enabled when:

Checked when: SalFmtGetFormat ( dfDateTime ) =

FMT_Format_Unformatted

SalFmtGetInputMask Syntax bOk = SalFmtGetInputMask ( hWnd, strMask )

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

See the Formatting and Validating chapter in the Centura Technical Reference fomore about input masks.

Parameters hWnd Window Handle. The handle (or name) of a combo box, datfield, or table window column.

strMask Receive String. The input mask retrieved.

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

See Also SalFmtIsValidInputMask SalFmtKeepMask SalFmtSetInputMask SalFmtUnmaskInput


Set bOk = SalFmtGetInputMask ( df1, df2 )



w

g to ter to

re

SalFmtGetPicture Syntax bOk = SalFmtGetPicture ( hWndField, strPicture )

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

strPicture Receive String. The picture format.

Return Value bOk is TRUE if the function succeeds, and FALSE if the data field or table windocolumn 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 accordintype. After that, Centura validates extra picture formatting characters that you enensure that they conform to the profile requirements.

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

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

Example On SAM_Validate

If SalFmtIsValidField ( dfDateTime )

Call SalFmtValidateField ( dfDateTime,

FMT_Validate_None )


r


SalFmtIsValidInputMask Syntax bOk = SalFmtIsValidInputMask ( strMask )

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


Parameters strMask String. An input mask.

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

See Also SalFmtGetInputMask SalFmtSetInputMaskSalFmtKeepMask SalFmtUnmaskInput


If SalFmtIsValidInputMask ( df1 )

Set df2 = 'Is Valid'

Else

Set df2 = 'Is Not Valid'

SalFmtIsValidPicture Syntax bOk = SalFmtIsValidPicture ( strPicture, nType )

Description Validates a number or date/time picture format.

These are examples of date/time picture formats:

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


Chapter 2

/

data not

eeps k

These are examples of number picture formats:

Parameters strPicture String. The picture string.

nType Number. Specify whether the format is for a number or datetime 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 afield, table window column, or combo box. For example, if you create a data fieldwith the input mask AA-AA and copy its value to another data field, Centura doescopy the hyphen.

You can call SalFmtKeepMask to change the default behavior so that Centura kthe input mask characters when you copy the value in a data field, table windowcolumn, or combo box. For example, if you create a data field with the input masAA-AA and copy its value to another data field, Centura copies the hyphen.

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


u

ds

ble

h as

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 yocopy a value.

Return Value bRet is the value you specified in bKeep.

See Also SalFmtGetInputMask SalFmtIsValidInputMask SalFmtSetInputMask SalFmtUnmaskInput

Example Set bRet = SalFmtKeepMask ( bKeep )

SalFmtSetFormatSyntax bOk = SalFmtSetFormat ( hWndField, nFormat )

Description Sets a data field's or table window column's format.

A field's country profile determines a format's characteristics. If the field uses thedefault 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 fielcan only be formatted as decimal, percentage, or currency values.

Parameters hWndField Window Handle. The handle (or name) of the data field or tawindow 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 sucwhen the format is not appropriate for the specified field.

See Also SalFmtGetFormat

Example Set bOk = SalFmtSetFormat ( hWndField, nFormat )


Chapter 2

or

ta

of

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 fmore about input masks.

Parameters hWnd Window Handle. The handle (or name) of a combo box, dafield, or table window column.

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


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


the

ble

in a

r

a

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

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

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

strValue String. The string to copy.

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

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

See Also SalFmtFieldToStr


On SAM_FieldEdit

Call SalFmtStrToField ( dfDateTime, dfDateString,TRUE )

SalFmtUnmaskInput Syntax bOk = SalFmtUnmaskInput ( hWnd, strInput )

Description Unmasks the contents of a data field or table window column and puts the resultstring. Unmasking involves taking control characters out of a string, but does notinclude converting characters from lowercase to uppercase and vice versa.


Parameters hWnd Window Handle. The handle (or name) of a combo box, datfield, or table window column.

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


Chapter 2

g to

o

if a

nput

e

o or .

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 accordintype. After that, Centura validates picture formatting characters that you enter toensure that they conform to the profile requirements.

For dates, you must enter the proper separator characters in order for Centura tvalidate 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 doesformat error occurs and the function returns FALSE:

Return Value bOk is TRUE if the function succeeds and FALSE otherwise, such as when the iis 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

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

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

Parameters hWndFont Window Handle. The handle (or name) of the window whosfont 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 twmore of the FONT_Enh* constants, use the OR (|) operator


See Also SalFontGetNamesSalFontGetSizesSalFontSet


n or

een

that

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

... Error ...

SalFontGetNamesSyntax nNames = SalFontGetNames ( nGet, strArrayFontNames )

Description Gets the names of the screen or printer fonts.

Parameters nGet Number. A constant that specifies whether to get the screeprinter fonts:

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

Return Value nNames is the number of font names returned.

See Also SalFontGetSalFontGetSizesSalFontSet

Example Set nTotal = SalFontGetNames ( FONT_GetScreen, sFontNames )

SalFontGetSizesSyntax nSizes = SalFontGetSizes ( nGet, strFontName, nArrayFontSizes )

Description Gets the sizes of a screen or printer font.

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

strFontName String. The name of the font.

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

Return Value nSizes is the number of font sizes returned.

See Also SalFontGetSalFontGetNamesSalFontSet

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


Chapter 2

e

of

ber

es

d.

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

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

Parameters hWnd Window Handle. The handle (or name) of the window whosfont 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 the FONT_Enh* constants, combine them using the OR (|) operator.


See Also SalFontGetSalFontGetNamesSalFontGetSizes

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

SalFormGetParmNumSyntax bOk = SalFormGetParmNum ( hWndForm, nParm, nValue )

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

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

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

nValue Receive Number. The value of the form parameter requeste



Call SalFormGetParmNum ( frmMain, FORM_nFormPages,

dfPages )


m tura with

ter

ls is

rnal

le

ata n).

SalFormUnitsToPixelsSyntax nNumPixels = SalFormUnitsToPixels ( hWnd, nFormUnits, bVertical )

Description Computes the number of pixels in the number of Centura form units. Centura forunits are a unit of measurement used by functions which move and position Cenobjects. Centura computes form units using physical units (pixels) in conjunction the window's font size.


nFormUnits Number. The number of form units.

bVertical Boolean. If the form units are on the X axis, set this parameto 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. nNumPixezero (0) if hWnd is invalid.

See Also SalPixelsToFormUnits

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

SalGetDataTypeSyntax nDataType = SalGetDataType ( hWnd )

Description Returns a data field's or table window column's data type.

Use this function with internal functions that handle data fields and table windowcolumns generically. Such internal functions pass only a window handle; the intefunction does not know the data type of the associated window.

Parameters hWnd Window Handle. The handle (or name) of a data field or tabwindow column.

Return Value nDataType is a number that indicates the data field's or table window column's dtype. Its value is one of a predetermined set of constants (excluding DT_Boolea

See Also SalGetType

Example Set nType = SalGetType ( hWndChild )

If nType = TYPE_DataField

Set nDataType = SalGetDataType ( hWndChild )


Chapter 2

he

or

the

an

t.

R

ld

SalGetDefButtonSyntax hWndDef = SalGetDefButton ( hWndParent )

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

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

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

See Also SalSetDefButton


Set hWndDef = SalGetDefButton ( frmMain )

Call SalSetDefButton ( frmMain.pb2 )

Set hWndDef = SalGetDefButton ( frmMain )

SalGetFirstChildSyntax hWndChild = SalGetFirstChild ( hWndParent, nTypeMask )

Description Returns the handle of the first child window of the specified type. This function cbe 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 wan

nTypeMask Number. One or more window types combined (using the O(|) 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. hWndChiequals hWndNULL if there is no child window or if hWndParent is invalid.

See Also SalGetNextChildSalGetType

Example Set hWndChild = SalGetFirstChild ( hWndCurrentFW, nTypeMask )


ard.

ure

ld,

SalGetFocusSyntax hWndFocus = SalGetFocus ( )

Description Returns the handle of the window with the focus.


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

See Also SalSetFocus

Example Set hWndSave = SalGetFocus ( )

SalGetItemNameSyntax bOk = SalGetItemName ( hWnd, strText )

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

Parameters hWnd Window Handle. The handle of an object.

strText Receive String. The name of the object.


Example Call SalGetItemName ( hWndCurrent, strItemName )

Return strItemName

SalGetMaxDataLengthSyntax nDataLength = SalGetMaxDataLength ( hWndObject )

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

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

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

See Also SalSetMaxDataLength

Example Set nDataLen = SalGetMaxDataLength ( hWnddfCurrent )


Chapter 2

this

the

u

R

file

.

he

y

SalGetNextChildSyntax hWndNextChild = SalGetNextChild ( hWndChild, nTypeMask )

Description Returns the handle of the next child window that matches a specified type. Use 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, sosetting persists until you change it.

Parameters hWndChild Window Handle. The handle (or name) of a child window. Yocan specify the return value of SalGetFirstChild.

nTypeMask Number. One or more window types combined (using the O(|) 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 isinvalid.

See Also SalGetFirstChildSalGetType

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 initializationor 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 tfunction cannot find the entry.

strFileName String. The name of the initialization file or company namedepending on the settings made using the SalUseRegistry function. If you are searching for an INI file and do not specifthe full path, Centura searches for the file in the Windows subdirectory.


, if If

e or

.

ot

.

y

ull

Return Value nValue is the integer value of an entry in the specified section of a file or registrythe function is successful. If the value found is not an integer, nValue is zero (0).SalGetProfileInt cannot find the specified entry, nValue is the default value of theentry.

See Also SalGetProfileStringSalSetProfileStringSalUseRegistry

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

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

strFileName )

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


strEntry String. The entry whose associated value is being retrieved

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

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


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

See Also SalGetProfileIntSalSetProfileStringSalUseRegistry

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


Chapter 2

ernal e of

a

ra

SalGetTypeSyntax nType = SalGetType ( hWnd )

Description Returns an object's type.

Use SalGetType with internal functions that process objects generically. Such intfunctions pass only a window handle; the internal function does not know the typthe associated object.

Parameters hWnd Window Handle. The handle of an object.

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

See Also SalGetFirstChildSalGetNextChild

Example Set nType = SalGetType ( hWndChild )

If nType = TYPE_DataField

Set nDataType = SalGetDataType ( hWndChild )

If nDataType = nHideDataType

Call SalHideWindow ( hWndChild )

SalGetVersionSyntax nType = SalGetVersion ( )

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


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


On SAM_Create

Set df1 = SalGetVersion ( )


SalGetWindowLabelTextSyntax nLength = SalGetWindowLabelText ( hWnd, sText, nMaxLength )

Description Retrieves the background text of a window.

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


strText Receive String. The window text.

nMaxLen Number. The maximum length of the window text.

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

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

SalGetWindowLocSyntax bOk = SalGetWindowLoc ( hWnd, nX, nY )

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


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

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


See Also SalSetWindowLoc

Example Call SalSetWindowLoc ( pbExample, 0, 0 )

Call SalGetWindowLoc ( pbExample, nX, nY )


Chapter 2

n

a

r

the

SalGetWindowSizeSyntax bOk = SalGetWindowSize ( hWnd, nWidth, nHeight )

Description Returns a window's size.


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.


See Also SalSetWindowSize

Example Call SalGetWindowSize ( pbExample, nWidth, nHeight )

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

SalGetWindowStateSyntax nState = SalGetWindowState ( hWnd )

Description Returns a window's current state.

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

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


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, otable window column, window text is the field value in string form, regardless of object's data type.


.

ne.

.

y the

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


strText Receive String. The window text.


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

See Also SalSetWindowTextSalTblGetColumnTitle

Example Call SalGetWindowText ( hWndForm, strfrmTitle, 50 )

SalHideWindowSyntax bOk = SalHideWindow ( hWndToHide )

Description Hides a window.

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

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


See Also SalBringWindowToTopSalShowWindow

Example Call SalHideWindow ( hWndChild )

SalHideWindowAndLabelSyntax bOk = SalHideWindowAndLabel ( hWndToHide )

Description Hides a window and its associated label.


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

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

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


Chapter 2

er.

arge to

int.

See Also SalBringWindowToTopSalHideWindowSalShowWindowAndLabel

Example Set bOk = SalHideWindowAndLabel ( hWndToHide )

SalHStringToNumberSyntax nHString = SalHStringToNumber ( strString )

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

Note: You must pass a string handle as the lParam parameter because the value is too lfit in the wParam.

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

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

See Also SalNumberToHString

Example Set nHString = SalHStringToNumber ( strString )

SalInvalidateWindow Syntax bOk = SalInvalidateWindow ( hWndToPaint )

Description Causes a window to be repainted.

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


See Also SalUpdateWindow

Example Set bOk = SalInvalidateWindow ( hWndToPaint )

SalIsButtonCheckedSyntax bIsSet = SalIsButtonChecked ( hWnd )

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

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

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


a ly

e.

a em

Example Set bIsSet = SalIsButtonChecked ( hWnd )

SalIsNullSyntax bNull = SalIsNull ( hWndIsNull )

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

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

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

See Also SalClearField


If SalIsNull ( dfDateTime )

Call SalMessageBox ( 'You must enter a value',

'Validate Error', MB_Ok )

Return VALIDATE_Cancel

SalIsValidDateTimeSyntax bOk = SalIsValidDateTime ( hWndField )

Description Verifies whether a data field, multiline text field, or table window column containsvalid date/time value. For multiline text fields, the date/time value must be the onitem in the field.

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

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


If NOT SalIsValidDateTime ( dfDateTime )

SalIsValidDecimalSyntax bOk = SalIsValidDecimal ( hWndField, nPrecision, nScale )

Description Verifies whether a data field, multiline text field, or table window column containsvalid decimal value. For multiline text fields, the decimal value must be the only itin the field.


Chapter 2

int.

le,

a in

r is


nPrecision Number. The number of digits to display.

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

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

See Also SalIsValidIntegerSalIsValidNumber


If NOT SalIsValidDecimal ( dfDecimal, 5, 2 )

Call SalMessageBox ( 'Invalid decimal value', 'Validate

SalIsValidIntegerSyntax bOk = SalIsValidInteger ( hWndField )

Description Verifies whether a data field, multiline text field, or table window column containsvalid integer value. For multiline text fields, the integer value must be the only itemthe field.


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

See Also SalIsValidDecimalSalIsValidNumber


If NOT SalIsValidInteger ( dfInteger)

Call SalMessageBox ( 'Invalid integer value', 'Validate

Error', MB_Ok )

Return VALIDATE_Cancel


a ive the

ise.

led

a r.

SalIsValidNumberSyntax bOk = SalIsValidNumber ( hWndField )

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


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

See Also SalIsValidDecimalSalIsValidInteger


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

If NOT SalIsValidNumber ( dfNumber)

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

SalIsWindowEnabledSyntax bEnabled = SalIsWindowEnabled ( hWndEnabled )

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

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

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

See Also SalDisableWindowSalEnableWindow

Example If SalIsWindowEnabled ( pbUpdate )

Call SalDisableWindow ( pbUpdate )

SalIsWindowVisibleSyntax bOk = SalIsWindowVisible ( hWndVisible )

Description Determines whether a window is currently visible.

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


Chapter 2

of the

o

ror

o

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

See Also SalHideWindowSalShowWindow

Example Set bOk = SalIsWindowVisible ( hWndVisible )

SalListAdd Syntax nIndex = SalListAdd ( hWndList, strName )

Description Adds a string to a list box or combo box.

If the list box is sorted (the default), 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 list box. Centura uses ANSI ascending order in the sort.

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

strName String. The string to add.

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

See Also SalListInsertSalListPopulate

Example Call SalListAdd ( hWndlbCurrent, strLBItem )

SalListClearSyntax bOk = SalListClear ( hWndList )

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



Example Call SalListClear ( lbProducts )


o

me

o

t

are t

SalListDeleteSyntax nRemaining = SalListDelete ( hWndList, nIndex )

Description Deletes a list box or combo box entry.


nIndex Number. The index of the entry to delete.

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

Example Set nCount = SalListDelete ( hWndlbCurrent, nLBIdx )

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

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


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

strPathName Receive String. The path name of the directory whose fileslisted. You must specify a field name or variable; you cannospecify a string constant as a receive parameter.

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


See Also SalFileOpen

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


Chapter 2

x

are

o

-1

y

s '|'

SalListGetMultiSelectSyntax bOk = SalListGetMultiSelect ( hWndList, nSelectedArray )

Description Returns an array of index numbers of selected list box entries.

Use the SalListQueryMultiCount function to return the number of selected list boentries.

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 not valid, or if no list box entries are selected.

Example Call SalListGetMultiSelect ( lbExample, nSelectedArray )

SalListInsertSyntax nIndex = SalListInsert ( hWndList, nIndex, strAdd )

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


nIndex Number. The position at which to insert the row. A value of 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 andLB_ErrSpace if there is insufficient memory to store the new string.

See Also SalListAdd

Example Call SalListInsert ( hWndLB, -1, strInsertStr )

SalListPopulateSyntax bOk = SalListPopulate ( hWndList, hSql, strSelect )

Description Populates a list box or combo box with a result set. SalListPopulate overrides ansettings 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 Windowlimitation, each column's data displayed in a combo box is separated by a single


r, and

bo

alid

o

if

character. There is no space between one column's data, the separator characteanother column's data.

Parameters hWndList Window Handle. The handle (or name) of the list box or combox 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 re-preparing each time SalListPopulate executes.

Return Value bOk is TRUE if the function succeeds and FALSE if any of the parameters are invor if strSelect contains INTO variables.

See Also SalListAddSalListInsert


Call SalListPopulate ( lbExample, hSql, 'select

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

SalListQueryCountSyntax nEntries = SalListQueryCount ( hWndList )

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


Return Value nEntries is the number of entries in hWndList. SalListQueryCount returns LB_Eran error occurs.

Example If NOT SalListQueryCount ( hWndlbCurrent )

Return FALSE


Chapter 2

o

e

on

. d

x.

see

SalListQueryFileSyntax bDirectory = SalListQueryFile ( hWndList, strFileName )

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


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

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

Example Call SalListQueryFile ( hWndLB, strFileName )

SalListQueryMultiCountSyntax nSelected = SalListQueryMultiCount ( hWndList )

Description Returns the number of selected entries in a multiple-selection list box.

Specify single- or multiple-selection in the list box's customizer.

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

Return Value nSelected is the number of selected entries in hWndList if the function succeedsnSelected equals LB_Err if hWndList is a single-selection list box or is not a valihandle.

Example Set nSelected = SalListQueryMultiCount ( lbExample )

SalListQuerySelectionSyntax nIndex = SalListQuerySelection ( hWndList )

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


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

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


o

o

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

See Also SalListGetMultiSelectSalListQueryState

Example Set nLBIdx = SalListQuerySelection (hWndlbCurrent )

SalListQueryStateSyntax bSelected = SalListQueryState ( hWndList, nIndex )

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


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

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

Example If SalListQueryState ( hWndlbCurrent, nLBIdx )

Set nCount = SalListDelete (hWndlbCurrent, nLBIdx)

Else

Set nLBIdx = nLBIdx + 1

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

or

strText = SalListQueryTextX ( hWndList, nIndex )

Description Fetches a list box or combo box entry.



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

Example Set strRecv = SalListQueryTextx ( hWnddbCurrent, nLBIdx )


Chapter 2

o

o

n.

vent

o

SalListQueryTextLengthSyntax nLength = SalListQueryTextLength ( hWndList, nIndex )

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



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

Example Set nLBItemLen = SalListQueryTextLength (hWndlbCurrent, nLBIdx)

SalListQueryTextXSyntax strText = SalListQueryTextX ( hWndList, nIndex )

Description Fetches a list box or combo box entry.



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

Return Value nLength is the length of strText. SalListQueryText returns LB_Err if nIndex is invalid.

strText is the fetched list box or combo box entry.

Example Set strText = SalListQueryTextX ( hwndLst, 2 )

SalListRedrawSyntax bOk = SalListRedraw ( hWndList, bRedraw )

Description Redraws entries in a list box or combo box, or prevents them from being redraw

For example, use SalListRedraw when populating a list box or combo box to prethe contents from being redrawn after adding each entry. When Centura finishespopulating it, use this function to redraw the list box or combo box .


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


List

for a the

n

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


Call SalListRedraw ( lbList, FALSE )

SalListSelectStringSyntax nIndex = SalListSelectString ( hWndList, nIndexStart, strText )

Description Finds and selects a combo box or single-selection list box entry.

Specify single-selection in the list box's customizer.

SalListSelectString uses search wraps. For example, if Centura starts searchingstring in the middle of a list box and reaches the end of the list box without findingstring, Centura wraps the search to the beginning of the list box. It continues thesearch until it reaches the middle of the list box where it started the search.


nIndexStart Number. The index at which to start the search. The searchbegins 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 aerror occurs or if hWndList is a multiple-selection list box.

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

If nIdx = LB_Err

Call SalListInsert ( hWndLB, -1, strInsertStr )

Else

Call SalListInsert ( hWndLB, nIdx + 1, strInsertStr )

SalListSetMultiSelectSyntax bOk = SalListSetMultiSelect ( hWndList, nIndex, bSelect )

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


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


Chapter 2

r if

set gs

nIndex Number. The index of the entry to select or deselect. If youspecify -1, Centura selects or deselects all list box or combobox entries.

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


Example Call SalListSetMultiSelect ( lbExample, 5, TRUE )

SalListSetSelectSyntax bOk = SalListSetSelect ( hWndList, nIndex )

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



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

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

Example Call SalListSetSelect ( hWndLB, 0 )

SalListSetTabsSyntax bOk = SalListSetTabs ( hWndList, nArrayTabStops )

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

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

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



Set nTabStops[0] = 2

Set nTabStops[1] = 3

Call SalListSetTabs ( hWndItem, nTabStops )


al

s

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

SalLoadAppSyntax bOk = SalLoadApp ( strAppName, strParameters )

Description Starts an application.

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

strParameters String. Optional command line arguments.

See the SAL (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


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

SalLoadAppAndWaitSyntax bOk = SalLoadAppAndWait ( strAppName, nMode, nRet )

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

Parameters strAppName String. The name of the application to start, separated fromcommand 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 succeed(bOk is TRUE), nRet is the exit status of the invoked application. A zero exit status usually means successful


Chapter 2

le

k

n

execution. If bOk is TRUE, but the invoked application exitsbefore entering a message loop, its exit status is not availabto Centura. In this case, nRet is zero as though the programexited 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 Out of memory, executable file was corrupt, or invalidrelocations

2 File not found

3 Path not found

5 Attempt to dynamically link to a task, or there was a sharing or network protection violation

6 Library requires separate data segments for each tas

8 Insufficient memory to start application

10 Incorrect Windows version

11 Invalid .EXE file (non-Windows .EXE or error in .EXEimage)

12 Application designed for different operating system

13 DOS 4.0 application

14 Unknown .EXE type

15 Attempt to load real-mode application developed for aearlier version of Windows

16 Attempt to load a second instance of an .EXE containing multiple, writeable data segments

19 Attempt to load a compressed executable file. The filemust be decompressed before it can be loaded.

20 A DLL required to run this application was corrupt.

21 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


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


tton eter

n

SalMapEnterToTabSyntax bOk = SalMapEnterToTab ( bState )

Description This function changes the behavior of the Enter key from executing the default buon a window to moving the focus to the next field. This function takes one param(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 Booleavalue.

Example Set bOk = SalMapEnterToTab ( bState )

SalMDIArrangeIcons Syntax bOk = SalMDIArrangeIcons ( hWndMDI )

Description Arranges minimized child window icons in an MDI window.

Parameters hWndMDI Window Handle. The handle of an MDI window.


See Also SalMDICascadeSalMDITile


Call SalMDIArrangeIcons ( hWndMDI )

SalMDICascadeSyntax bOk = SalMDICascade ( hWndMDI )

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



See Also SalMDIArrangeIconsSalMDITile


Chapter 2

n the e

er.


Call SalMDICascade ( hWndMDI )

SalMDITileSyntax bOk = SalMDITile ( hWndMDI, bPosition )

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


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


See Also SalMDIArrangeIconsSalMDICascade


Call SalMDITile ( hWndMDI, FALSE )

SalMessageBeepSyntax bOk = SalMessageBeep ( nAlertLevel )

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

Parameters nAlertLevel Number. The alert level:

0xFFFFFFFF (-1)Standard beep using the computer speak

MB_IconAsterisk

MB_IconExclamation

MB_IconStop

MB_IconQuestion

MB_Ok


See Also SalMessageBox

Example Call SalMessageBeep ( -1 )


e.

.

xt

SalMessageBoxSyntax nResult = SalMessageBox ( strText, strTitle, nFlags )

Description Displays a message box and returns a number that indicates the user's respons

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 teby 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 theOR (|) operator. You can combine at most one constant fromeach 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


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 )


ss a

can ry

les ables

meter ox in

ated nly

w. er.

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

Description Creates a modal dialog box.


You cannot use receive window parameters as receive function arguments. You use a temporary variable as the function argument and then assign the temporavariable to the receive function parameter.

A modal dialog box disables its owner window. A system modal dialog box disabthe entire Windows system. SalEndDialog destroys the modal dialog box and enall 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 paradata types of the dialog box being created. You define parameters for the dialog bthe Window Parameters section of the application outline.


Parameters tDlgBoxToCreate Template or String. The name of the modal dialog box to create.

NOTE: If you specify a string value, you cannot pass windowparameter arguments (Parm1, Parm2, ...).

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



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

See Also SalEndDialogSalModalDialogFromStr

Example Call SalModalDialog ( dlgAboutBox, hWndForm )


Chapter 2

pect

les bles

w.

he

he

SalModalDialogFromStrSyntax nReturn = SalModalDialogFromStr ( tDlgBoxToCreate, hWndOwner, Parm1,

Parm2, ... )

Description Creates a modal dialog box. This function is useful with internal functions that exto receive a dialog box name in a string parameter.

A modal dialog box disables its owner window. A system modal dialog box disabthe entire Windows system. SalEndDialog destroys a modal dialog box and enaall 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 windoUse hWndNUL for dialog boxes that do not have owners.



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

See Also SalModalDialog

Example Set nReturn = SalModalDialogFromStr ( tDlgBoxToCreate,hWndOwner )

SalMoveWindowSyntax bOk = SalMoveWindow ( hWndToMove, nXOffset, nYOffset )

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

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

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

nYOffset Number. The number of form units to move the window on tY 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 )


to 1.

ter


SalNumberAbsSyntax nNum = SalNumberAbs ( nValue )

Description Computes a number's absolute value.

Parameters nValue Number. The number whose absolute value you want.

Return Value nNum is the absolute value of nValue.


Set nNum1 = SalNumberAbs ( -12 )

SalNumberArcCosSyntax nArcCos = SalNumberArcCos ( nValue )

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

Parameters nValue Number. The number whose arccosine you want.

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


Set nNum1 = SalNumberArcCos ( 1 )

SalNumberArcSinSyntax nArcSin = SalNumberArcSin ( nValue )

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

Parameters nValue Number. The number whose arcsine you want.

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


Set nNum1 = SalNumberArcSin ( 1 )


Chapter 2

nt.

2 to

of s

SalNumberArcTanSyntax nArcTan = SalNumberArcTan ( nValue )

Description Computes a value's arctangent.

Parameters nValue Number. The number whose arctangent you want.

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

See Also SalNumberArcTan2


Set nNum1 = SalNumberArcTan ( 1 )

SalNumberArcTan2Syntax nArcTan2 = SalNumberArcTan2 ( nValueY, nValueX )

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

Parameters nValueY Number. One of two values whose arctangent you want.

nValueX Number. The other of two values whose arctangent you wa

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

See Also SalNumberArcTan


Set nNum1 = SalNumberArcTan2 ( 1, 0 )

SalNumberCosSyntax nCos = SalNumberCos ( nAngle )

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

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

Return Value nCos is the cosine of nAngle. If the angle is large, nCos can reflect a partial losssignificance. If the angle is so large that significance is totally lost, SalNumberCoreturns zero (0).

See Also SalNumberCosH


Set nNum1 = SalNumberCos ( 0 )


u

or

nt.

SalNumberCosHSyntax nCosH = SalNumberCosH ( nAngle )

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

Parameters nAngle Number. The value of the angle whose hyperbolic cosine yowant.

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

See Also SalNumberCos


Set nNum1 = SalNumberCosH ( 0 )

SalNumberExponentSyntax nNumExp = SalNumberExponent ( nValue )

Description Computes a value's exponential function.

Parameters nValue Number. The value whose exponential function you want.

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


Set nNumExp = SalNumberExponent ( 2.302585093 )

SalNumberHighSyntax nHi = SalNumberHigh ( nValue )

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

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

Return Value nHi is the high-order word value of nValue.

See Also SalNumberLow


Set nHi = SalNumberHigh ( 0xffffaaaa )


Chapter 2

e

n of

to

SalNumberHypotSyntax nHypotenuse = SalNumberHypot ( nX, nY )

Description Computes the length of the hypotenuse of a right triangle, given the lengths of thother 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 computatiothe hypotenuse results in an overflow, nHypotenuse is equal to zero (0).


Set nHypotenuse = SalNumberHypot ( 3, 4 )

SalNumberLogSyntax nLog = SalNumberLog ( nValue )

Description Computes a number's natural logarithm.

Parameters nValue Number. The number whose natural logarithm you want.

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

See Also SalNumberLogBase10


Set nLog = SalNumberLog ( 1000 )

SalNumberLogBase10Syntax nLogBase10 = SalNumberLogBase10 ( nValue )

Description Computes a number's base -10 logarithm.

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

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

See Also SalNumberLog


Set nLogBase10 = SalNumberLogBase10 ( 1000 )


t.

SalNumberLowSyntax nLo = SalNumberLow ( nValue )

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

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

Return Value nLo is the low-order word value of nValue.

See Also SalNumberHigh


Set nLo = SalNumberLow ( 0xffffaaaa )

SalNumberMaxSyntax nNumMax = SalNumberMax ( nVal1, nVal2 )

Description Returns the greater of two values.

Parameters nVal1 Number. The first of two values.

nVal2 Number. The second of two values.

Return Value nNumMax is the greater of nVal1 and nVal2.

See Also SalNumberMin


Set nNumMax = SalNumberMax ( 1765.2, -2 )

SalNumberMinSyntax nNumMin = SalNumberMin ( nVal1, nVal2 )

Description Returns the lesser of two values.

Parameters nVal1 Number. The first value.

nVal2 Number. The second value.

Return Value nNumMin is the lesser of nVal1 and nVal2.

See Also SalNumberMax


Set nNumMin = SalNumberMin ( 1765.2, -2 )


Chapter 2

d

l,

s:

ber,

SalNumberModSyntax nModulo = SalNumberMod ( nNumber, nNumberMod )

Description Returns a number's modulo. This function divides nNumber by nNumberMod anreturns the remainder.

ParameternNumber Number. The number to divide.

nNumberMod Number. The number by which to divide nNumber.

Return Value nModulo is the remainder of nNumber divided by nNumberMod.


Set nNumber = SalNumberMod ( 5, 2 )

SalNumberPiSyntax nNumPi = SalNumberPi ( nValue )

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

Parameters nValue Number. The number to multiply by Pi.

Return Value nNumPi is nValue multiplied by Pi.


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

SalNumberPowerSyntax nNumPower = SalNumberPower ( nX, nY )

Description Computes nX raised to the power of nY. This function does not recognize integrafloating-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 condition

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 numnNumPower is equal to zero (0), meaning that an error occurred.


l to

dom s.

me

f 0

re

4. In instances where an overflow or an underflow occurs, nNumPower is equazero (0).


Set nNumPow = SalNumberPower ( 2, 3 )

SalNumberRandInitSyntax bOk = SalNumberRandInit ( nSeed )

Description Sets the starting point for generating a series of pseudo-random numbers usingSalNumberRandom.

Use SalNumberRandInit when you want to generate the same set of pseudo-rannumbers over and over again, for example, when doing reproducible experimentCall SalNumberRandInit followed by numerous calls to SalNumberRandom. To repeat the random number series, call SalNumberRandInit again, specify the saseed value, and follow with numerous calls to SalNumberRandom.

Parameters nSeed Number. The starting point. A whole number in the range oto 32767.


See Also SalNumberRandom


Call SalNumberRandInit ( 12 )

SalNumberRandomSyntax nRandomNum = SalNumberRandom ( )

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


Return Value nRandomNum is a pseudo-random number.

See Also SalNumberRandInit


Call SalNumberRandInit ( 12 )

Set nRandNum = SalNumberRandom ( )


Chapter 2

e turns

to

ians.

o

SalNumberRoundSyntax nResult = SalNumberRound ( nNumber )

Description Returns a rounded number.

If the fractional part of a number is greater than or equal to .5, Centura rounds thnumber up. For example, the number 124.33 returns 124; the number 124.56 re125.

Parameters nNumber Number. The number to round.

Return Value nResult is nNumber after rounding.


Set nNumber = SalNumberRound ( 124.5 )

SalNumberSinSyntax nSin = SalNumberSin ( nAngle )

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

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

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

See Also SalNumberSinH


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

SalNumberSinHSyntax nSinH = SalNumberSinH ( nAngle )

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

Parameters nAngle Number. The value of the angle whose hyperbolic sine youwant.

Return Value nSinH is the hyperbolic sine of nAngle. If the angle is too large, nSinH is equal tzero (0).

See Also SalNumberSin



of to

ou

t a

Set nNum = SalNumberSinH ( 0 )

SalNumberSqrtSyntax nSqrt = SalNumberSqrt ( nValue )

Description Computes a number's square root.

Parameters nValue Number. The number whose square root you want.

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


Set nSqrt = SalNumberSqrt ( 36 )

SalNumberTanSyntax nTan = SalNumberTan ( nAngle )

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

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

Return Value nTan is the tangent of nAngle. If the angle is large, nTan can reflect a partial losssignificance. If the angle is so large that significance is totally lost, nTan is equalzero (0).

See Also SalNumberTanH


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

SalNumberTanHSyntax nTanH = SalNumberTanH ( nAngle )

Description Computes an angle's hyperbolic tangent. You must specify the angle in terms ofradians.

Parameters nAngle Number. The value of the angle whose hyperbolic tangent ywant.

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

See Also SalNumberTan


Chapter 2

ing.


Set nNum = SalNumberTanH ( 0 )

SalNumberToCharSyntax strChar = SalNumberToChar ( nNumber )

Description Converts a decimal value to an ASCII character.

Parameters nNumber Number. The number to convert.

Return Value strChar is the character converted from nNumber.

See Also SalStrFirstC


Set df2 = SalNumberToChar ( df1 )

SalNumberToHStringSyntax strString = SalNumberToHString ( nHString )

Description Converts a number to a string handle.

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

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

See Also SalHStringToNumber


Set strString = SalNumberToHString ( lParam )

Set nBuffLen = SalStrGetBufferLength (strString)

SalNumberToStrSyntax nLength = SalNumberToStr ( nNumber, nDecimalPlaces, strString )

Description Converts a number to a string.


nDecimalPlaces Number. The number of decimal places you want in strStr

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.


ing.

llows:

See Also SalNumberToStrXSalStrToNumber


Set nLength = SalNumberToStr ( 124.5, 1, strString )

SalNumberToStrXSyntax strString = SalNumberToStrX ( nNumber, nDecimalPlaces)

Description Converts a number to a string.


nDecimalPlaces Number. The number of decimal places you want in strStr

strString Receive String. The string converted from nNumber.

Return Value nLength is the length of strString, including the decimal point.

strString is the string converted from nNumber.

See Also SalNumberToStrSalStrToNumber


Set df2 = SalNumberToStrX ( df1, 2 )

SalNumberToWindowHandleSyntax hWnd = SalNumberToWindowHandle ( nWnd )

Description Converts a number to a window handle.

For example, you can broadcast a message by passing -1 to SalSendMsg as fo

Set hWndAll = SalNumberToWindowHandle ( -1 )

Call SalSendMsg ( hWndAll, nMsg, 0, 0 )

Parameters nWnd Number. The number to convert.

Return Value hWnd is the window handle converted from nWnd.

See Also SalWindowHandleToNumber

Example Set hWndtblCustomer = SalNumberToWindowHandle (lParam )


Chapter 2

.

int.

,

SalNumberTruncateSyntax nResult = SalNumberTruncate ( nNumber, nPrecision, nScale )

Description Truncates a number.

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

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

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

Return Value nResult is the result of truncating nNumber.


Set nNum = SalNumberTruncate ( 10.0625, 4, 4 )

SalParentWindowSyntax hWndParent = SalParentWindow ( hWnd )

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

Parameters hWnd Window Handle. The handle (or name) of the object whoseparent window handle you want.

Return Value hWndParent is the parent window handle of hWnd. If hWnd is a top-level windowhWndParent is the window handle of the owner window, as passed to SalCreateWindow, otherwise hWndParent is equal to hWndNull.

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


e

Example Set hWndParent = SalParentWindow ( hWnd )

SalPicClearSyntax bOk = SalPicClear ( hWndToClear )

Description Deletes the contents of a picture.

Parameters hWndToClear Window Handle. The handle (or name) of a picture.

Return Value bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid picture.

See Also SalPicSetSalPicSetFileSalPicSetFitSalPicSetString

Example Call SalPicClear ( hWndPicture )

SalPicGetDescriptionSyntax nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )

Description Retrieves a description of a picture's contents. An example of a description is "Microsoft Draw".

Parameters hWndPict Window Handle. The handle (or name) of a picture.

strDesc Receive String. A description of the contents of hWndPict.

For a graphic image, SalPicGetDescription returns one of thfollowing values:

For a file, SalPicGetDescription returns 'Gupta:DOSFILE'.

Value Image Type

Gupta:BMP Device-Independent Bitmap

Gupta:GIF Graphics Interchange Format

Gupta:ICO Icon File

Gupta:PCX Paintbrush

Gupta:TIFF Tag Image File Format

Gupta:WMF Windows MetaFile


Chapter 2

he

s

e

For an OLE object, SalPicGetDescription returns the description of the object class that the server application recorded in the Windows registration database, followed by tword "Object". For example:

Package ObjectPaintbrush Picture ObjectSound Object

nMaxLength Number. The maximum length of the text to retrieve.

Return Value nLength is the length (in bytes) of strDesc.

See Also SalPicGetSting

Example Set nLength = SalPicGetDescription ( hWndPict, strDesc, nMaxLen )

SalPicGetStringSyntax 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 iequal to zero (0).

See Also SalPicGetDescription

Example Set nLength = SalPicGetString ( hWndPict, nFormat, strPict )

SalPicSetSyntax bOk = SalPicSet ( hWndPic, tResource, nFormat )

Description Inserts a resource into a picture.

Parameters hWndPic Window Handle. The handle (or name) of a picture.

tResource Template. An icon or bitmap in the Resources section of thoutline.


se

ted

he f

nFormat Number. The resource type. If you specify zero, Centura determines the resource type. Otherwise, specify one of thevalues:

PIC_FormatBitmap

PIC_FormatIcon


See Also SalPicClearSalPicSetFileSalPicSetFitSalPicSetString

Example Set bOk = SalPicSet ( hWndPic, tResource, nFormat )

SalPicSetFileSyntax bOk = SalPicSetFile ( hWndPict, strFileName )

Description Inserts a file's contents into a picture.


strFileName String. The name of the file whose contents are to be inserinto hWndPict.

Centura derives a picture's file type from the file extension. Tfile extension of a bitmap must be .BMP; the file extension oan icon must be .ICO.


See Also SalPicClearSalPicSetSalPicSetFitSalPicSetString

Example Set bOk = SalPicSetFile ( hWndPict, strFileName )

SalPicSetFitSyntax bOk = SalPicSetFit ( hWndPict, nFit, nScaleWidth, nScaleHeight )

Description Sets the fit for a picture.



Chapter 2

le.

ale.

nFit Number. The type of fit:

PIC_FitBestFit

PIC_FitScale

PIC_FitSizeToFit

nScaleWidth Number. The width scaling percentage if nFit is PIC_FitSca

nScaleHeight Number. The height scaling percentage if nFit is PIC_FitSc


See Also SalPicClearSalPicSetSalPicSetFileSalPicSetString

Example Call SalPicSetFit ( hWndItem, PIC_FitBestFit, 0, 0 )

SalPicSetStringSyntax bOk = SalPicSetString ( hWnd, nFormat, strPicture )

Description Inserts the contents of a string into a picture.

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

nFormat Number. The format of the picture contents:

PIC_FormatBitmap

PIC_FormatIcon

PIC_FormatObject

strPicture String. A memory image of a picture file.

You can use SalFileRead to read a bitmap file into a string. You can also SELECT a long varchar database column thatcontains a bitmap or icon file into a string.


See Also SalPicClearSalPicSetSalPicSetFileSalPicSetFit

Example Call SalPicSetString ( hWndPicture, PIC_FormatBitmap, strPicture )


tura ects. with

o

.

ssage

SalPixelsToFormUnitsSyntax nFormUnits = SalPixelsToFormUnits ( hWnd, nNumPixels, bVertical )

Description Computes the number of Centura form units based on the number of pixels. Cenform units is a unit of measurement used by functions that move and position objForm units are computed by Centura using physical units (pixels) in conjunction 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 tFALSE. If the pixels are on the Y axis, set this parameter toTRUE.

Return Value nFormUnits is the number of form units returned if the function call is successfulnFormUnits is equal to zero (0) if hWnd is invalid.

See Also SalFormUnitsToPixels

Example Set nFormUnits = SalPixelsToFormUnits ( pbExample,

nPixels, FALSE )

SalPostMsgSyntax bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )

Description Posts the specified message to a window by adding nMsg to hWndReceiver's mequeue.

Parameters hWndReceiver Window Handle. The handle (or name) of the window receiving the message.

nMsg Number. The message number.

nMywParam Number. The wParam for the message.

nMylParam Number. The lParam for the message.


See Also SalSendMsgSalSendMsgToChildren

Example Set bOk = SalPostMsg ( hWndReceiver, nMsg, nMywParam, nMylParam )


Chapter 2

e's

e

e's

of

SalPrtExtractRectSyntax bOk = SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight, nBottom )

Description Extracts the currently printing rectangle from the SAM_Print message's lParam parameter.

Parameters nMylParam Number. The SAM_Print message's lParam parameter.

nLeft Receive Number. The position on the X axis of the rectanglleft side.

nTop Receive Number. The position on the Y axis of the top of threctangle.

nRight Receive Number. The position on the X axis of the rectanglright side.

nBottom Receive Number. The position on the Y axis of the bottom the rectangle.


Example On SAM_Print

Call SalPrtExtractRect ( nMylParam, nLeft, nTop, nRight,

nBottom )

SalPrtGetDefaultSyntax bOk = SalPrtGetDefault ( strDevice, strDriver, strPort )

Description Returns the default device (printer), the default driver, and the default port.

Parameters strDevice Receive String. The default device.

strDriver Receive String. The default driver.

strPort Receive String. The default port.

Return Value bOk is TRUE if the function call is successful in getting the default values, and FALSE otherwise.

See Also SalPrtSetDefaultSalPrtSetup


Call SalPrtGetDefault ( strDevice, strDriver, strPort )


ables

.

the

or ell.

use

y

nt.

SalPrtGetParmNumSyntax bOk = SalPrtGetParmNum ( nParm, nValue )

Description Gets the value of a print parameter. The print parameters are a set of global variwhich 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 ofPRT_* constants.

nValue Receive Number. The print parameter's value. For boolean parameters, nValue is TRUE or FALSE.


See Also SalPrtSetParmNum


Call SalPrtGetParmNum ( PRT_nDraftMode, nPrtValue)

If nPrtValue

Set rbDraftMode = TRUE

Else

Set rbProofMode = TRUE

SalPrtPrintFormSyntax bOk = SalPrtPrintForm ( hWndForm )

Description Prints a form window, table window, or dialog box, including its contents and rowheader flags. If a form window or dialog box contains a child table window, list boxcombo box, only the rows on screen print. Lines, frames, and pictures print as w

Centura tries to print a window in the font displayed on screen. For best results, only those fonts supported by your printer.

If the window is wider or higher than the paper size, the window prints on as manpages as needed.

Parameters hWndForm Window Handle. The handle (or name) of the window to pri


Example Call SalPrtPrintForm ( hWndForm )


Chapter 2

set of

SalPrtSetDefaultSyntax bOk = SalPrtSetDefault ( strDevice, strDriver, strPort )

Description Sets the default device (printer), driver, and port.

Parameters strDevice String. The default device.

strDriver String. The default driver.

strPort String. The default port.


See Also SalPrtGetDefaultSalPrtSetup

Example Set strDevice = 'PostScript Printer'

Set strDriver = 'PSCRIPT'

Set strPort = 'LPT2'

Call SalPrtSetDefault ( strDevice, strDriver, strPort )

SalPrtSetParmDefaultsSyntax bOk = SalPrtSetParmDefaults ( )

Description Resets print parameters back to their default values. The print parameters are aglobal 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




ables

.

ne of

ially,

if


Call SalPrtSetParmDefaults ( )

SalPrtSetParmNumSyntax bOk = SalPrtSetParmNum ( nParm, nValue )

Description Sets the value of a print parameter. The print parameters are a set of global variwhich 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; othe PRT_* constants.

nValue Number. The parameter value.


See Also SalPrtGetParmNum

Example If rbDraftMode

Call SalPrtSetParmNum ( PRT_nDraftMode, TRUE)

SalPrtSetupSyntax bOk = SalPrtSetup ( strDevice, strDriver, strPort, bActiveOnly )

Description Displays the Printer Setup dialog box that lets the user alter the printer setup. Initthe 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:TRUE, all printers display and if FALSE, only active printersdisplay.



Call SalPrtSetup ( strDevice, strDriver, strPort, TRUE)


Chapter 2

ox,

tiline r an ake

SalQueryFieldEditSyntax bSet = SalQueryFieldEdit ( hWndField )

Description Returns the setting of the Field Edit Flag for a data field, multiline field, combo btable window's context row cell, or picture.

The field edit flag is set whenever the user changes the value of a data field, multext field, or table window column. For a picture, the field edit flag is set wheneveOLE server application is opened for editing. The field edit flag is not set if you mthe change with a Set statement or a fetch from the database.

This function does not clear the field edit flag of hWndField.

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

Return Value bSet is TRUE if hWndField's field edit flag is set and FALSE otherwise.

See Also SalSendValidateMsgSalSetFieldEdit

Example If SalQueryFieldEdit ( SalGetFocus () )

If SalSendValidateMsg ( ) = VALIDATE_Ok

! Process Save.

SalQuitSyntax bOk = SalQuit ( )

Description Exits an application.

If you are in user mode, Centura returns you to design mode. If the application running from SQLRUN.EXE, it exits.



See Also SalAbort


Call SalQuit ( )


w

ndow

dow

es

SalReportCloseSyntax bOk = SalReportClose ( hWndReport )

Description Closes a report window. Call this function when you want to close a report previewindow.

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

Return Value bOk is TRUE if the function succeeds and FALSE if hWndReport is invalid.

Example If not SalReportClose ( hWndReport )

Call SalMessageBox ( 'Close Failed', 'SalReportClose', MB_Ok )

SalReportCmdSyntax bOk = SalReportCmd ( hWndReport, nCommand )

Description Sends a command to an open report window. Use SalReportCmd to control a withat 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 winin 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 valuinclude any of the RPT_Cmd* commands.


Example Set bOk = SalReportCmd ( hWndReport, nCommand )

SalReportCreateSyntax bOk = SalReportCreate ( strTemplate, strVariables, strInputs, bDefaultReport,

nError )

Description Creates a report template.

Parameters strTemplate String. The name of the report template to create.


Chapter 2

t

.

l to

e

g x .

or

the s

n

ield.

lays

strVariables String. A comma-separated list of Centura variables that contain data to fetch. The data types of these variables musmatch 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 anempty report.

nError Receive Number. If an error occurs, this parameter is equaone of the RPT_Err* values.

If you call SalReportCreate ten times in a row, you will receivthe following error code: RPT_ErrMaxRps.

In run mode at designtime, Centura always displays a dialobox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif 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, nErris a RPT_Err* value.

Example Call SalReportCreate ( 'quick.qrp',':nDiv,:nDept,:nSection, :nEmplNum )

SalReportDlgOptionsSyntax bOk = SalReportDlgOptions ( hWndReport, strCaption, strLine1, strLine2,

strDocName )

Description Sets the options for the report printing dialog box. Call this function after creatingreport but before printing begins. For example, you can call SalReportDlgOptionwhile processing the SAM_ReportFetchInit message.

Parameters hWndReport Window Handle. The wParam of a SAM_Report* messagethat contains the window handle.

strCaption String. The replacement text for the Print dialog box captiotext.

strLine1 String. The replacement text for the first centered-text field.

strLine2 String. The replacement text for the second centered-text f

strDocName String. The name of the document that Print Manager dispwhen the output is spooled and waiting to print.



Example Call SalReportDlgOptions ( SalNumberToWindowHandle

(wParam ), 'Sales Report', 'This is a long report',

'Hit CANCEL to quit', 'sales.rpt' )

SalReportGetDateTimeVarSyntax bOk = SalReportGetDateTimeVar ( hWndReport, strVariable, dtValue )

Description Returns the value of a date/time report variable.


strVariable String. The name of a date/time report variable.

dtValue Receive Date/Time. The value of strVariable.

Return Value bOk is TRUE if the function is successful, and FALSE otherwise.

See Also SalReportGetNumberVarSalReportGetObjectVarSalReportGetStringVarSalReportSetDateTimeVar

Example Call SalReportGetDateTimeVar ( hWndReport,

strVariable, dtGet )

SalReportGetNumberVarSyntax bOk = SalReportGetNumberVar ( hWndReport, strVariable, nValue )

Description Returns the value of a number report variable.


strVariable String. The name of a number report variable.

nValue Receive Number. The value of strVariable.


See Also SalReportGetDateTimeVarSalReportGetObjectVarSalReportGetStringVarSalReportSetNumberVar

Example Call bOk = SalReportGetNumberVar ( hWndToMove, nXOffset, nYOffset )


Chapter 2

SalReportGetObjectVarSyntax bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )

Description Returns the value of an object report variable.


strVariable String. The name of an object report variable.

strValue Receive String. The value of strVariable.


See Also SalReportGetDateTimeVarSalReportGetNumberVarSalReportGetStringVarSalReportSetObjectVar

Example Set bOk = SalReportGetObjectVar ( hWndReport, strVariable, strValue )

SalReportGetStringVarSyntax bOk = SalReportGetStringVar ( hWndReport, strVariable, strValue )

Description Returns the value of a string report variable.


strVariable String. The name of a string report variable.

strValue Receive String. The value of strVariable.


See AlsoSalReportGetDateTimeVarSalReportGetNumberVarSalReportGetObjectVarSalReportSetStringVar

Example Call SalReportGetStringVar ( hWndReport, 'strVariable', strGet )


has

g

real ds.

to

h

ith

SalReportPrintSyntax hWndRet = SalReportPrint ( hWndFrm, strTemplate, strVariables, strInputs,

nCopies, nOptions, nFirstPage, nLastPage, nErr )

Description Prints a report. This function is synchronous and does not return until the report been formatted and sent to Windows or Windows Print Manager for printing.

SalReportPrint creates a minimized ReportWindows window. A print status dialobox displays while printing. When this function completes, ReportWindows automatically ends.

Note: This function establishes a dialog between ReportWindows and the application; thework of reporting is in processing the SAM_Report* messages which ReportWindows sen

Centura sends data from an application to ReportWindows when the applicationreturns TRUE in SAM_ReportFetchNext processing. ReportWindows continues 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 matcthe 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 wthe OR (|) operator:

RPT_PrintAll

RPT_PrintDraft

RPT_PrintNoAbort

RPT_PrintNoErrors

RPT_PrintNoWarn

RPT_PrintRange


Chapter 2

s rr*

e:

g x

r )

sed.

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 izero. If an error occurs, this parameter is one of the RPT_Evalues.

Note: If you call SalReportPrint ten times in a row, you will receive the following error codRPT_ErrMaxRps.

In run mode at designtime, Centura always displays a dialobox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif 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 iszero.

If you want to interact with the report window, interrogate wParam at SAM_ReportStart and save that into the hWndReport variable.

See Also SalReportPrintToFile

Example Call SalReportPrint ( frmMain, strReportFile,

strReportBinds, strReportInputs, nCopies, nOptions,

nFirstPage, nLastPage, nErr )

SalReportPrintToFileSyntax hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile,

strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nEr

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 clo

Parameters hWndFrm Window Handle. The handle (or name) of the application window that processes the SAM_Report* messages.


strDestFile String. The destination file name.


h

ith

s rr*

x




nCopies Number. The number of copies.

nOptions Number. You can combine two or more of these constants wthe OR (|) operator:

RPT_PrintAll

RPT_PrintDraft

RPT_PrintNoAbort

RPT_PrintNoErrors

RPT_PrintNoWarn

RPT_PrintRange

nFirstPage Number. The first page of the report (if nOptions includes RPT_PrintRange).

nLastPage Number. The last page of the report (if nOptions includes RPT_PrintRange).

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 izero. If an error occurs, this parameter is one of the RPT_Evalues.

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 dialogbox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif 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 iszero.

See Also SalReportPrint


Chapter 2

it port

w.

et.

Example Set hWndRet = SalReportPrintToFile ( hWndFrm, strTemplate, strDestFile, strVariables, strInputs, nCopies, nOptions, nFirstPage, nLastPage, bFormat, nErr )

SalReportResetSyntax bOk = SalReportReset ( hWndReport )

Description Re-populates the report window. This function re-sends the SAM_ReportFetchInmessage, and one or more SAM_ReportFetchNext messages to populate the rewindow with the new data.

Parameters hWndReport Window Handle. The handle (or name) of the report windo


Example If NOT SalReportReset ( hWndReport )

Call SalMessageBox ( 'Reset Failed', 'SalReportReset',

MB_Ok )

SalReportSetDateTimeVarSyntax bOk = SalReportSetDateTimeVar ( hWndReport, strVariable, dtValue )

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


strVariable String. The name of the variable whose value you want to s

dtValue Date/Time. The value of strVariable.


See Also SalReportGetDateTimeVarSalReportSetNumberVarSalReportSetObjectVarSalReportSetStringVar

Example If NOT SalReportSetDateTimeVar ( hWndReport,

'dtVariable', dtGDateTime[1] )

Call SalMessageBox ( 'SetDateTimeError',

'RPT_BeforePageHeader-d', MB_Ok )


et.

et.

SalReportSetNumberVarSyntax bOk = SalReportSetNumberVar ( hWndReport, strVariable, nValue )

Description Sets the value of a numeric report variable.



nValue Number. The value of strVariable.


Related Function

SalReportGetNumberVarSalReportSetDateTimeVarSalReportSetObjectVarSalReportSetStringVar

Example Call SalReportSetNumberVar ( hWndReport, 'strUnknown', nVariable )

SalReportSetObjectVarSyntax bOk = SalReportSetObjectVar ( hWndReport, strVariable, strValue )

Description Sets the value of an object report variable.

Parameters hWndReport Window Handle. The window of the report window handle.


strValue String. The value of strVariable.


See Also SalReportGetObjectVarSalReportSetDateTimeVarSalReportSetNumberVarSalReportSetStringVar

Example Set bOk = SalReportSetObjectVar ( hWndReport, strVariable,strValue )


Chapter 2

et.

umn n the

l to

u

g x

SalReportSetStringVarSyntax bOk = SalReportSetStringVar ( hWndReport, strVariable, strValue )

Description Sets the value of a string report variable.



strValue String. The value of strVariable.


See Also SalReportGetStringVarSalReportSetDateTimeVarSalReportSetNumberVarSalReportSetObjectVar

Example Call SalReportSetStringVar ( hWndReport, 'strUnknown',

strVariable )

SalReportTableCreateSyntax bOk = SalReportTableCreate ( strReport, hWndTbl, nError )

Description Creates a report template from the specified table window. The table window colnames are the input names to the report and their titles are the column names oreport. 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 equaone of the RPT_Err* values.

Note: If you call SalReportTableCreate ten times in a row, yowill receive the following error code: RPT_ErrMaxRps.

In run mode at designtime, Centura always displays a dialobox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif you set this parameter to 1 before calling SalReportTableCreate.



the

to

x

See Also SalReportTablePrintSalReportTableView

Example Set bOk = SalReportTableCreate ( strReport, hWndTbl, nError )

SalReportTablePrintSyntax hWnd = SalReportTablePrint ( hWndTbl, strReport, nParamArray, nError )

Description Prints a report created from the specified table window.

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

strReport String. The name of the report.

nParamArray Number. An array you create containing information about print job. The array indexes are:

RPT_PrintParamCopies

RPT_PrintParamFirstPage

RPT_PrintParamLastPage

RPT_PrintParamOptions

nError Receive Number. If an error occurs, this parameter is equalone 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 dialogbox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif you set this parameter to 1 before calling SalReportTablePrint.

Return Value hWnd is the handle of the report window if the function succeeds.

See Also SalReportTableCreateSalReportTableView

Example Set hWndReport = SalReportTablePrint ( hWndTbl, 'test.qrp', nParamArray,nError )


Chapter 2

l to

g x

real

t

SalReportTableViewSyntax hWnd = SalReportTableView ( hWndTbl, hWndDisplay, strReport, nError )

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


hWndDisplay Window Handle. The handle (or name) of a report display window. If null, Centura creates a window in which you can preview the report.

strReport String. The name of the report.

nError Receive Number. If an error occurs, this parameter is equaone 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 dialobox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif you set this parameter to 1 before calling SalReportTableView.

Return Value hWnd is the handle of the report window if the function succeeds.

See Also SalReportTableCreateSalReportTablePrint

Example Set hWnd = SalReportTableView ( hWndTbl, hWndDisplay,strReport, nError )

SalReportViewSyntax hWndReport = SalReportView ( hWndFrm, hWndRptTemp, strTemplate,

strVariables, strInputs, nFlags )

Description Displays a report in preview mode. Report processing is asynchronous; SalReportView returns after starting the report process.

Note: This function establishes a dialog between ReportWindows and the application; thework 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_ReportFetchNex


hat il

n

h

his er r

x

message. ReportWindows does not receive any data until it issues the SAM_ReportFetchNext message and the Centura application returns TRUE to tmessage. ReportWindows keeps sending SAM_ReportFetchNext messages untCentura 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 acustom report template. If null, ReportWindows creates its owwindow in which it displays the report.



The contents of this string must match the order of the inputnames declared in the report template.



nFlags Receive Number. Before you call this function, you can set tparameter to one of the constants below to turn off the printicon on the default report view tool bar or turn off the tool bacompletely:

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 receivethe following error code: RPT_ErrMaxRps.

In run mode at designtime, Centura always displays a dialogbox with an explanation if an error happens. For *.RUN and*.EXE applications, Centura only displays an error dialog boif you set this parameter to 1 before calling SalReportView.

Return Value hWndReport is the handle of the report window if the function succeeds. Centurareturns the window handle before ReportWindows displays the report.


Chapter 2

he e

the her

Example Set hWndReport = SalReportView ( frmMain, hWndNULL, strReportFile, strReportBinds, strReportInputs, nError )

SalScrollGetPosSyntax bOk = SalScrollGetPos ( hWndsb, nPos )

Description Returns the current scroll bar value.

Parameters hWndsb Window Handle. The handle (or name) of a vertical or horizontal scroll bar.

nPos Receive Number. The scroll bar value.


See Also SalScrollSetPos

Example Set bOk = SalScrollGetPos ( hWndsb, nPos )

SalScrollGetRangeSyntax bOk = SalScrollGetRange ( hWndsb, nMin, nMax, nLine, nPage )

Description Gets a scroll bar's scroll range, line increment, and page increment.


nMin Receive Number. The minimum scroll bar position.

nMax Receive Number. The maximum scroll bar position.

nLine Receive Number. The line increment. The number of units tscroll bar increments or decrements when the user clicks thscroll bar arrow.

nPage Receive Number. The page increment. The number of unitsscroll bar increments or decrements when the user clicks eitside of the scroll bar's scroll box.


See Also SalScrollSetRange

Example Call SalScrollGetRange ( hWndsbCounter, nMin, nMax, nLine, nPage )


o

ng

one

e

e

SalScrollSetPosSyntax bOk = SalScrollSetPos ( hWndsb, nPos )

Description Sets a scroll bar's position. This function is equivalent to using a Set statement tassign a value to the scroll bar.


nPos Number. The scroll bar position. If this value is outside the scroll bar's range, Centura sets the scroll bar position to thescroll range minimum or the scroll range maximum, dependion whether nPos is below or above the range.


See Also SalScrollGetPos

Example Call SalScrollSetPos ( hWndsbCounter, 0 )

SalScrollSetRangeSyntax bOk = SalScrollSetRange ( hWndsb, nMin, nMax, nLine, nPage )

Description Sets a scroll bar's range, line increment, and page increment.

When the scroll bar is created, 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 towithin the new range. The range of a scroll bar is -32,767 to 32,767.


nMin Number. The minimum position of the scroll bar.

nMax Number. The maximum position of the scroll bar.

nLine Number. The number of units to increment or decrement thscroll bar when the user clicks the scroll bar arrow.

nPage Number. The number of units to increment or decrement thscroll bar when the user clicks either side of the scroll box.


Chapter 2

n .

turn is

n .

t of nt to

e.

turn is


See Also SalScrollGetRange

Example Call SalScrollSetRange ( hWndsbCounter, 0, 50, 1, 5 )

SalSendClassMessageSyntax nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )

Description Invokes the message actions implemented or inherited by an object's class whecalled from either a derived class or from an object that is an instance of a class

Parameters nMessage Number. The message number.

nMywParm Number. The wParam.

nMylParam Number. The lParam.

Return Value nMsgReturn is the message return value. If the message has no return, nMsgRezero (0).

See Also SalSendClassMessageNamed

Example Set nMsgReturn = SalSendClassMessage ( nMessage, nMywParam, nMylParam )

SalSendClassMessageNamedSyntax nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam,

nMylParam )

Description Invokes the message actions implemented or inherited by an object's class whecalled 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 resulmultiple inheritance. It lets you specify which base class message action you waexecute.

tClassName must be a direct base class of the class from which this call is mad

Parameters tClassName Template. The ancestor's class name.


nMywParam Number. The wParam.




turn is

r

See Also SalSendClassMessage

Example Set nMsgReturn = SalSendClassMessageNamed ( tClassName, nMsg, nMywParam, nMylParam )

SalSendMsgSyntax nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )

Description Sends the specified message to a window. SalSendMsg does not return until theprocessing for the message is complete.

Parameters hWnd Window Handle. The window receiving the message.


nMywParam Number. The wParam.



See Also SalPostMsgSalSendMsgToChildrenSalSendValidateMsg

Example Set nMsgReturn = SalSendMsg ( hWnd, nMsg, nMywParam, nMylParam )

SalSendMsgToChildrenSyntax bSent = SalSendMsgToChildren ( hWnd, nMsg, nMywParam, nMylParam )

Description Sends a message to all child items of a form window, dialog box, table window, oMDI window.

Parameters hWnd Window Handle. The handle (or name) of a form window, dialog box, table window, or MDI window.


nMywParam Number. The wParam for the message.

nMylParam Number. The lParam for the message.

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

See Also SalPostMsgSalSendMsgSalSendValidateMsg


Chapter 2

age:

push

Example Call SalSendMsgToChildren ( hWndForm,CHM_DISABLE, 0, 0 )

SalSendValidateMsgSyntax nStatus = SalSendValidateMsg ( )

Description Sends a SAM_Validate message to the object with the focus data field, multilinefield, 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. Centuradoes 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 mess

VALIDATE_CancelVALIDATE_OkVALIDATE_OkClearFlag

See Also SalSendMsgSalSendMsgToChildren

Example Set nStatus = SalSendValidateMsg ( )

SalSetDefButtonSyntax bOk = SalSetDefButton ( hWndButton )

Description Sets the default push button of a form window or dialog box. When this function returns, the default push button gets the focus only if the focus was on one of thebuttons before you called SalSetDefButton.

Parameters hWndButton Window Handle. The handle (or name) of the default push button.

Return Value bOk is TRUE if the function succeeds and FALSE if hWndButton is not a valid button.

See Also SalGetDefButton

Example Call SalSetDefButton ( frmMain.pb2 )


xt

is not

SalSetFieldEditSyntax bOk = SalSetFieldEdit ( hWndField, bSet )

Description Sets or clears the field edit flag for an editable data field, combo box, multiline tefield, 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 flagset whenever an OLE server application is opened for editing. The field edit flag isset 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.


See Also SalQueryFieldEdit

Example Call SalSetFieldEdit ( hWndChild, FALSE )

SalSetFocusSyntax hWndFocus = SalSetFocus ( hWndToSet )

Description Sets the focus to a specified window.

Warning: You cannot call SalSetFocus in SAM_KillFocus processing because of a Windows limitation.

Parameters hWndToSet Window Handle. The handle (or name) of the window to receive the focus.

Return Value hWndFocus is the handle of the window that previously had the focus.

See Also SalGetFocus

Example Call SalSetFocus ( hWndSave )


Chapter 2

All e

y

SalSetMaxDataLengthSyntax bOk = SalSetMaxDataLength ( hWndField, nLength )

Description Sets a limit on the number of characters that a user can enter into a data field, multiline text field, or table window column.


nLength Number. The character limit.


See Also SalGetMaxDataLength

Example Set bOk = SalSetMaxDataLength ( hWndField, nLength )

SalSetProfileStringSyntax bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )

Description Set the value of an entry in the specified section of an initialization file or registry.profile information is stored as string, so if you want to store an integer it must bconverted to a string first. Then it can be retrieved as an integer using the SalGetProfileInt-Function .


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

strValue String. The value of strEntry.



See Also SalGetProfileIntSalGetProfileStringSalUseRegistry

Example Set bOk = SalSetProfileString ( strSection, strEntry, strValue, strFileName )


ve.

).

).

SalSetWindowLabelTextSyntax bOk = SalSetWindowLabelText ( hWnd, sText )

Description Sets the background text of a window. To be associated with a specific window, background text must immeditately precede the window in the Outliner.

Important: The background text does not require a mnemonic for the function to operate.


sText String. The window text.


Example Set bOk = SalSetWindowLabelText ( hWnd, sText )

SalSetWindowLocSyntax bOk = SalSetWindowLoc ( hWnd, nX, nY )

Description Moves a window to a new position (x, y) on the X and Y axes.

Parameters hWnd Window Handle. The handle (or name) of the window to mo

nX Number. The position on the X axis (expressed in form units

nY Number. The position on the Y axis (expressed in form units

Return Value bOk is TRUE if the function succeeds and FALSE if hWnd is not a valid window handle.

See Also SalGetWindowLoc

Example Call SalSetWindowLoc ( pbExample, 0, 0 )

SalSetWindowSizeSyntax bOk = SalSetWindowSize ( hWnd, nWidth, nHeight )

Description Resizes a window.

Parameters hWnd Window Handle. The handle (or name) of the window to resize.

nWidth Number. The new width of the window (expressed in form units).


Chapter 2

lid

m,

ey

nHeight Number. The new height of the window (expressed in formunits).

Return Value bOk is TRUE if the window is successfully resized, and FALSE if hWnd is an invawindow handle.

See Also SalGetWindowSize

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

SalSetWindowTextSyntax bOk = SalSetWindowText ( hWnd, strTitle )

Description Sets the text of a window to a specified string.

A window's text is the title of a form window, modeless dialog box, table window,radio button, check box, or push button.

For a data field or table window column, the text is the object's value in string forregardless 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.


strTitle String. The window text.


See Also SalGetWindowTextSalTblSetColumnTitle

Example Call SalSetWindowText ( hWndForm, 'First National Bank' )

SalShowWindowSyntax bOk = SalShowWindow ( hWndToShow )

Description Makes a window visible.

Parameters hWndToShoWindow Handle. The handle (or name) of a window to make visible.

Return Value bOk is TRUE if the previous state of the window was visible and FALSE if it washidden. Use this information to hide many windows without first checking that th


the

ne.

y the

I

are visible. When you restore them to their original state at a later point in time, return lets you make visible only those windows that were previously visible.

See Also SalHideWindow

Example Call SalShowWindow ( hWndForm )

SalShowWindowAndLabelSyntax bOk = SalShowWindowAndLabel ( hWndToShow )

Description Makes a window and its associated label visible.


Parameters hWndToShow The handle (or name) of a window to make visible.

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

See Also SalHideWindowAndLabelSalShowWindow

Example Set bOk = SalShowWindowAndLabel ( hWndToShow )

SalStatusGetTextSyntax nLength = SalStatusGetText ( hWnd, strText, nMaxLen )

Description Gets the text displayed in the status bar of a top-level or MDI window.

Parameters hWnd Window Handle. The handle (or name) of a top-level or MDwindow.

strText Receive String. The text displayed in the status bar.


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

See Also SalStatusSetTextSalStatusSetVisible

Example Set nLength = SalStatusGetText ( hWnd, strText, nMaxLen )


Chapter 2

I

I

ge on and

SalStatusSetTextSyntax bOk = SalStatusSetText ( hWnd, strText )

Description Displays specified text in the status bar of a top-level or MDI window.


strText String. The text to display in the status bar.


See Also SalStatusGetTextSalStatusSetVisible

Example Set bOk = SalStatusSetText ( hWnd, strText )

SalStatusSetVisibleSyntax bOk = SalStatusSetVisible ( hWnd, bShow )

Description Shows or hides the status bar on a top-level or MDI window.


bShoBoolean. If TRUE, the status bar displays; if FALSE, the status bar hides.


See Also SalStatusGetTextSalStatusSetText

Example Call SalStatusSetVisible ( hWndForm, TRUE )

SalStrCompressSyntax bOk = SalStrCompress ( strString )

Description Compresses the specified string. Use this function to compress strings for storadisk or in the database. Use this function for long strings, or when storing imagesso on.

Parameters strString Receive String. The string to compress.


See Also SalStrUncompress

Example Set bOk = SalStrCompress ( strString )


the

g

ff.

SalStrFirstCSyntax 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 non-ASCII (ANSI) or 16-bit characters. If the character returned is a 16-bit character,leading byte of the character is in the high-order byte, and the trailing byte of thecharacter is in the low-order byte.

Use SalNumberHigh to get the leading byte and SalNumberLow to get the trailinbyte.

Parameters strString Receive String. The string whose first character is lopped o

nChar Receive Number. The first character of strString.

Return Value bOk is TRUE unless strString is empty or invalid.

See Also SalNumberHighSalNumberLowSalNumberToCharSalStrLop


Set dfString = 'ABC'

Call SalStrFirstC ( dfString, dfNumChar )

! Now dfString = 'BC' and dfNumChar = 65

SalStrGetBufferLengthSyntax nLength = SalStrGetBufferLength ( strString )

Description Returns the current buffer length of a string.

Centura stores string variables in buffers. The length includes the string's null termination character.

Parameters strString String. The string whose buffer length you want.

Return Value nLength is the length of strString's buffer.

See Also SalStrLengthSalStrSetBufferLength

Example Set nBufferLength = SalStrGetBufferLength (strNumbers )


Chapter 2

int.

a

SalStrIsValidCurrencySyntax bOk = SalStrIsValidCurrency ( strMoney, nPrecision, nScale )

Description Verifies that an entire character string represents a valid currency value. Centuravalidates 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 po

Return Value bOk is TRUE if strMoney is a valid currency value and FALSE otherwise.

See Also SalStrIsValidDateTimeSalStrIsValidNumber

Example Set bOk1 = SalStrIsValidCurrency ( '$120.00' )

SalStrIsValidDateTimeSyntax bOk = SalStrIsValidDateTime ( strDateTime )

Description Verifies that an entire character string represents a valid date/time value. Centurvalidates the string based on the current settings for the keywords sShortDate, sLongDate, s1159, s2359, and sTime in the [INTL] section of WIN.INI.

Parameters strDateTime String. A string that contains a date/time value.

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

See Also SalStrIsValidCurrencySalStrIsValidNumber

Example Set bOk2 = SalStrIsValidDateTime ( '2/2/91' )


st

e.

SalStrIsValidNumberSyntax 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 andsThousands in the [INTL] section of WIN.INI.

Parameters strNumber String. A string that contains a number value.

Return Value bOk is TRUE if strNumber is a valid number value and FALSE otherwise.

See Also SalStrIsValidCurrencySalStrIsValidDateTime

Example Set bOk1 = SalStrIsValidNumber ( '120.00' )

SalStrLeftSyntax nLength = SalStrLeft ( strSource, nExtract, strTarget )

Description Returns a substring of a specified length starting at position zero (0), the left-mocharacter in the string.

Parameters strSource String. The string from which to extract characters.

nExtract Number. The number of characters to extract from strSourc

strTarget Receive String. The substring.

You can specify the same string for both strSource and strTarget.

Return Value nLength is the length of the new string.

strTarget is the substring.

See Also SalStrMidSalStrMidXSalStrRightSalStrLeftX

Examples Set nLength = SalStrLeft ( 'LEFT01234', 4, strTarget )


Chapter 2

st

e.

ll

SalStrLeftXSyntax strTarget = SalStrLeftX ( strSource, nExtract)

Description Returns a substring of a specified length starting at position zero (0), the left-mocharacter in the string.

Parameters strSource String. The string from which to extract characters.

nExtract Number. The number of characters to extract from strSourc



Return Value nLength is the length of the new string.


See Also SalStrMidSalStrMidXSalStrRightSalStrLeft

Examples Set strTarget = SalStrLeftX ( 'LEFT01234', 4)

SalStrLengthSyntax nLength = SalStrLength ( strString )

Description Returns a string's length.

Strings are stored internally in Centura with a null termination character. The nuterminator is not included in the length.

Parameters strString String. The string whose length you want.

Return Value nLength is the length of strString.

See Also SalStrGetBufferLength


Set strNumbers = '1234567890'

Set nStringLength = SalStrLength ( strNumbers )


at.

SalStrLopSyntax nCharacter = SalStrLop ( strString )

Description Returns the ASCII numeric value of the first character of a string in decimal formThis function removes the first character of the string.

Parameters strString Receive String. The input string without the first character.

Return Value nCharacter is the ASCII value of the first character of strString. When strString isnull, nCharacter is equal to zero (0).

See Also SalNumberToCharSalStrFirstC


Set strString = 'ABC'

Set nCharacter = SalStrLop ( strString )

SalStrLowerSyntax nLength = SalStrLower ( strSource, strTarget )

or

strTarget = SalStrLowerX ( strSource )

Description Converts a string to lowercase.

Parameters strSource String. The string to convert .

strTarget Receive String. The lowercase string.


Return Value nLength is the length of strTarget.

strTarget is the lowercase string.

See Also SalStrUpperSalStrUpperX

Examples On SAM_Create

Set nLength = SalStrLower ( 'LOWERCASE', strTarget )

or

On SAM_Create

Set strTarget = SalStrLowerX ( 'LOWERCASE' )


Chapter 2

mber

first

d is

SalStrMidSyntax nLength = SalStrMid ( strSource, nStartPos, nLength, strTarget )

or

strTarget = SalStrMidX ( strSource, nStartPos, nLength )

Description Returns a substring, starting at a specified position and containing a specified nuof characters.

Parameters strSource String. The source string.

nStartPos Number. The starting position of the substring (zero is the position) in strSource.

nLength Number. The number of characters to put in the substring.



Return Value nLength is the length of the substring.


See Also SalStrLeftSalStrLeftXSalStrRight

Examples Set nLength = SalStrMid (‘012ABC345’, 3, 3, strTarget)

Or

Set strTarget = SalStrMidX ( '012ABC345', 3, 3 )

! strTarget = 'ABC'

SalStrProperSyntax nLength = SalStrProper ( strSource, strTarget )

or

strTarget = SalStrProperX ( strSource )

Description Converts a string to a proper name. In a proper name, the first letter of each woruppercase; the remaining letters are lowercase.

Parameters strSource String. The string to convert.

strTarget Receive String. The converted string.



th


strTarget is the converted string.

Examples Set nLength = SalStrProper ( 'JOHN L. SMITH', strTarget )

or

Set strTarget = SalStrProperX ( 'JOHN L. SMITH')

SalStrRepeat and SalStrRepeatXSyntax nLength = SalStrRepeat ( strSource, nTimes, strTarget )

or

strTarget = SalStrRepeatX ( strSource, nTimes )

Description Concatenates a string with itself a specified number of times.


nTimes Number. The number of times to concatenate strSource wiitself.

strTarget Receive String. The new string.



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.


Chapter 2

e.

ing

Parameters strSource String. The source string that contains characters to replac

nStartPos Number. The position in strSource at which to begin replaccharacters.

nLength Number. The number of characters to replace. If zero (0), strReplace starts at nStartPos.

strReplace String. The replacement string.


Return Value nReturn is the length of strTarget.


Examples Set nReturn = SalStrReplace ( 'ABC1234', 3, 4, 'DEFG', strTarget )

or

Set StrTarget = SalStrReplaceX ( 'ABC1234', 3, 4)

SalStrRight and SalStrRightXSyntax nLength = SalStrRight ( strSource, nLength, strTarget )

or

strTarget = SalStrRightX ( strSource, nLength )

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


nLength Number. The number of characters to extract.





See Also SalStrLeftSalStrLeftXSalStrMidSalStrMidX


one

is

cter er

. Its

re.


Set nLength = SalStrRight ( '123RIGHT', 5, strTarget )

or

On SAM_Create

Set StrTarget = SalStrRightX ( '123RIGHT', 5 )

SalStrScanSyntax nOffset = SalStrScan ( strString1, strString2 )

Description Searches for and returns the offset of a specified substring. If there is more thaninstance 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 stringat offset zero (0).

strString2 String. The string to search for.

Case is disregarded in the search.

You can use pattern matching characters. The percent chara(%) matches any set of characters. The underscore charact(_) matches any single character.

The use of a backslash(\) with SalStrScan differs when searching for a backslash, percent, or underscore characterusage 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 undersco


Chapter 2

If

set.

to ct.

Return Value nOffset is a number that indicates the offset (0 origin) of strString2 in strString1. Centura does not find strString2 in strString1, SalStrScan returns a -1.

Example Set nOffset = SalStrScan ( '012AbC345', 'ABC' )

SalStrSetBufferLengthSyntax bOk = SalStrSetBufferLength ( strString, nLength )

Description Sets the buffer string length to the length plus 1 for the terminator and allocates memory. This is only needed if you want to pass a Receive String to an externalfunction.

Parameters strString Receive String. The string whose buffer length you want to

nLength Number. The length of strString.


See Also SalSetMaxDataLength

SalStrGetBufferLength

Example Set bOk = SalStrSetBufferLength ( recvString, 10 ) ! 11 chars

SalStrToDateSyntax dtDateTime = SalStrToDate ( strString )

Description Converts a string to a date/time value.This function uses the system date formatconvert a date string. If you want to be format independent, use SalDateConstru

Parameters strString String. The string to convert.

Return Value dtDateTime is the date/time value converted from strString.

See Also SalDateToStr

Example Set dtDateTime = SalStrToDate ( strDateTime )


)

rs.

, if '!' '.

' is an

llow start :

er.

ter.

s

SalStrTokenizeSyntax nNumTokens = SalStrTokenize ( strSource, strStartDel, strEndDel, strTokenArray

Description Parses a string into substrings (tokens) based on specified start and end delimiteCentura 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 exampleis 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 ',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 foas elements of the substring until it finds an end delimiter. For example, if '!' is a 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 delimit

strEndDel String. A string that contains the end delimiter characters.

Pass an empty string ('') to specify the lack of an end delimi

strTokenArray String Array. The handle (or name) of an array of substringcreated from strSource.

Return Value nNumTokens is the number of substrings created. nNumTokens is zero (0) if no substrings are created, or if an error occurs.

Example Set dfNumTokens = SalStrTokenize ( dfSource1, '', ',', astrToken1 )

SalStrToNumberSyntax nNumber = SalStrToNumber ( strString )

Description Converts a string to a number.

Parameters strString String. The string to convert.

Return Value nNumber is the number resulting from the conversion.


Chapter 2

in a

in a

See Also SalNumberToStr

Example Set nNumber = SalStrToNumber ( '100.22' )

SalStrTrimSyntax nNewLength = SalStrTrim ( strSource, strTarget )

or

strTarget = SalStrTrimX ( strSource )

Description Strips leading and trailing blanks and compresses multiple spaces and tabs withstring to single spaces.

Parameters strSource String. The original string.



Return Value nNewLength is the length of strTarget.


Example Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )

SalStrTrimXSyntax strTarget = SalStrTrimX ( strSource)

Description Strips leading and trailing blanks and compresses multiple spaces and tabs withstring to single spaces.

Parameters strSource String. The original string.



Return Value nNewLength is the length of strTarget.



Set nLength = SalStrTrim ( ' 1 2 3 ', strTarget )


t you

SalStrUncompressSyntax bOk = SalStrUncompress ( strString )

Description Decompresses the specified string. Use this function to decompress a string thacompressed with SalStrCompress.

Parameters strString Receive String. The string to decompress.


See Also SalStrCompress

Example Set bOk = SalStrUncompress ( strString )

SalStrUpperSyntax nLength = SalStrUpper ( strSource, str Target )

Description Converts a string to uppercase.


strTarget Receive String. The uppercase string.



strTarget is the uppercase string.

See Also SalStrLower

Example Set nLength = SalStrUpper ( 'uppercase', strTarget )

SalStrUpperXSyntax strTarget = SalStrUpperX ( strSource )

Description Converts a string to uppercase.



Return Value This function returns the uppercase string in strTarget.

See Also SalStrLower


Set strTarget = SalStrUpperX ( 'uppercase' )


Chapter 2

I

s

ine

and

SalTBarSetVisibleSyntax bOk = SalTBarSetVisible (hWind, bShw)

Description Shows or hides the tool bar on a top-level or MDI window.


bShow Boolean. If TRUE, displays the tool bar; if FALSE, hides thetool bar.


See Also SalStatusSetVisible

Example Set bOk = SalTBarSetVisible (hWind, bShw)

SalTblAnyRowsSyntax bAny = SalTblAnyRows ( hWndTbl, nFlagsOn, nFlagsOff )

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

If you set nFlagsOn to zero (0) and nFlagsOff to zero (0), SalTblAnyRows returnTRUE if the table window contains any rows at all, regardless of their flags.


nFlagsOn Number. The flags that the row should have. You can combROW_* 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 none of the nFlagsOff flags.

See Also SalTblFindNextRowSalTblFindPrevRow


Enabled When: SalTblAnyRows ( tblTable, ROW_Selected, 0 )


)

table

r

ine

a

e

or

SalTblClearSelectionSyntax bOk = SalTblClearSelection ( hWndTbl )

Description Deselects all rows of a table window.



See Also SalTblSetRowFlags

Example Call SalTblClearSelection ( hWndForm )

SalTblColumnAverageSyntax nAverage = SalTblColumnAverage ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff

Description Computes the average of all column values or only specified column values in a window.

Use Centura row flag constants to specify the rows to use in the computation. Foexample, you can choose to average only the values of modified rows.


nColumnID Number. The Column Identifier.


nFlagsOff Number. The flags that the row should not have. You can combine ROW_* flags using the OR (|) operator:

Return Value nAverage is the average of all column values or only specified column values in table window. nAverage is equal to zero (0) if an error occurs.

See Also SalTblColumnSum

Example Set nAverage = SalTblColumnAverage ( hWndTbl, nColumnID,nFlagsOn, nFlagsOff )

SalTblColumnSumSyntax nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn, nFlagsOff )

Description Computes the sum of all column values or only specified column values in a tablwindow.

Use Centura row flag constants to specify the rows to use to compute the sum. Fexample, you can choose to sum only the values of modified rows.


Chapter 2

ine

copy

ine

uld


nColumnID Number. The Column Identifier



Return Value nSum is the sum of all column values or only specified column values in a table window. nSum is equal to zero (0) if an error occurs.

See Also SalTblColumnAverage

Example Set nSum = SalTblColumnSum ( hWndTbl, nColumnID, nFlagsOn,nFlagsOff )

SalTblCopyRowsSyntax bOk = SalTblCopyRows ( hWndTbl, nFlagsOn, nFlagsOff )

Description Copies the contents of the specified table window rows to the Clipboard in text format. In the Clipboard, columns are delimited by TAB characters and rows aredelimited by end-of-line characters.

Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to copy the entire table. The stops, without indicating a failure, after copying 64 Kbytes of text.




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 cobe copied to the Clipboard.

See Also SalTblPasteRows

Example Call SalTblCopyRows ( tblTable, ROW_Selected, 0 )


,

mn

g

the


SalTblCreateColumnSyntax nColId = SalTblCreateColumn ( hWndTbl, nColumnPos, nDispWidth, nMaxChars

strTitle )

Description Creates a table window column of string data type at runtime.

When you return to design mode, Centura destroys the column.


nColumnPos Number. The Column Position

nDispWidth Number. The display width of the column in inches.

nMaxChars Number. The maximum number of characters that the colucan 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 )

SalTblDefineCheckBoxColumnSyntax bOk = SalTblDefineCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue,

sUncheckedValue )

Description Define a column as a check box.

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

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

nFlags Number. nFlags is a combination of the following flags usinthe '|' operator:

COL_CheckBox_IgnoreCase = 0x0001

sCheckedValue String. sCheckedValue is the value that a cell will get whencheck box is checked.

sUncheckedValue String. The value when a check box is unchecked.


Example Set bOk = SalTblDefineCheckBoxColumn ( hWnd, hWndCol, nFlags,sCheckedValue, sUncheckedValue )


Chapter 2

g

r of

SalTblDefineDropDownListColumnSyntax bOk = SalTblDefineDropDownListColumn( hWnd, hWndCol, nFlags, nLines )

Description Define a column as a drop down list.



nFlags Number. nFlags is a combination of the following flags usinthe '|' operator:

COL_DropDownList_Sorted=0x0001

COL_DropDownList_VScroll=0x0002

COL_DropDownList_Auto=0x0004

COL_DropDownList_Editabel=0x0008

nLines Number. nLines indicates the maximum number of lines to display in the list.


Example Set bOk = SalTblDefineDropDownListColumn ( hWnd, hWndCol,nFlags, nLines )

SalTblDefinePopupEditColumnSyntax bOk = SalTblDefinePopupEditColumn( hWnd, hWndCol, nFlags, nLines )

Description Define a column as a popup edit window. nLines indicates the maximum numbelines to display in the control.



nFlags Number. nFlags is always 0 (zero).

nLines Number. nLines indicates the maximum number of lines to display in the list.


Example Set bOk = SalTblDefinePopupEditColumn ( hWnd, hWndCol, nFlags,nLines )


eader that er is

f

he le

SalTblDefineRowHeaderSyntax bOk = SalTblDefineRowHeader ( hWndTable, strTitle, nWidth, nFlags, hWndCol )

Description Defines the appearance and behavior of a table window's row header. The row his a non-editable area on the left edge of a table window that displays informationstays displayed even when a user scrolls horizontally. A typical use of a row headthe display of row numbers.

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

strTitle String. The title of the row header column.

nWidth Number. The width of the row header in pixels.

nFlags Number. The row header attributes. You can combine theseflags 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. IhWndCol equals hWndNULL, the row header is blank.


Example Call SalTblDefineRowHeader ( tbl1, strTitle, nWidth,TBL_RowHdr_Visible | TBL_RowHdr_ShareColor,colRowHeader )

SalTblDefineSplitWindowSyntax bOk = SalTblDefineSplitWindow ( hWndTable, nRowsLowerHalf, bDragAdjust )

Description Splits a table window horizontally.

You can insert rows into the lower half of a split table window. This is convenientwhen the scroll range is dynamic because you can insert rows without knowing tnumber of rows in the table window. You can also use the lower half of a split tabwindow to display summary data.

Parameters hWndTable Window Handle. The handle (or name) of a table window tosplit.


Chapter 2

alf s

ble

ted this

ow

re

nRowsLowerHalf Number. The number of rows to make visible in the lower hof the split window. If you specify zero (0), the table window inot split.

bDragAdjust Boolean. Specify whether (TRUE) or not (FALSE) to let theuser drag-adjust the visible rows in both halves of a split window.


Example Set bAnyFlag = SalTblDefineSplitWindow ( hWndTbl, 3,TBL_Split_Adjustable )

SalTblDeleteRowSyntax bOk = SalTblDeleteRow ( hWndTbl, nRow, nFlag )

Description Deletes a row from a table window but not from the database.


nRoNumber. The number of the row to delete.

nFlag Number. A constant used to coordinate a delete from the tawindow with a delete from a SQLBase result set. This parameter can be one of these values:

TBL_Adjust

TBL_NoAdjust


Example Call SalTblDeleteRow ( hWndForm, nCurrentRow, TBL_NoAdjust)

SalTblDeleteSelectedSyntax bOk = SalTblDeleteSelected ( hWndTbl, hSql )

Description Applies a SQL DELETE statement to all table window rows with the ROW_Selecflag set. You must prepare or retrieve the SQL DELETE statement before callingfunction.

As each row is deleted from the database, Centura deletes it from the table winddisplay.

This function does not perform a COMMIT. You must perform a COMMIT to ensuthat the deletions are not lost in the case of a rollback.


hSql Sql Handle. The handle of a DELETE statement.


te at

le

lags

ow

re

o

Return Value bOk is TRUE if the function succeeds and FALSE if hWndTbl or hSql is invalid.

See Also SalTblDoDeletesSalTblDoInsertsSalTblDoUpdatesSalTblPopulate

Example Call SalTblDeleteSelected ( tblExample, hSql )

SalTblDestroyColumnsSyntax bOk = SalTblDestroyColumns ( hWndTbl )

Description Destroys all automatic columns created by SalTblCreateColumn or SalTblPopularuntime.

This function only works on table windows that contain only automatic columns.


Return Value bOk is TRUE if the function succeeds and FALSE if hWndTbl is invalid or the tabwindow contains non-automatic columns (columns created at design time).

See Also SalTblCreateColumnSalTblPopulate

Example Set bOk = SalTblDestroyColumns ( hWndTbl )

SalTblDoDeletesSyntax bOk = SalTblDoDeletes ( hWndTbl, hSql, nFlagsOn )

Description Applies a SQL DELETE statement to all table window rows that have nFlagsOn fset. 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 winddisplay.

This function does not perform a COMMIT. You must perform a COMMIT to ensuthat the deletions are not lost in the case of a rollback.


hSql Sql Handle. The handle of a DELETE statement.

nFlagsOn Number. Centura uses row flags to determine which rows tdelete. You can specify either of these flags:

ROW_MarkDeleted

ROW_Selected


Chapter 2

this

re

d f or

Return Value bOk is TRUE if any rows are deleted and FALSE otherwise. bOk is FALSE if hWndTbl or hSql is invalid.

See Also SalTblDeleteSelectedSalTblDoInsertsSalTblDoUpdates

Example Call SalTblDoDeletes ( tblExample, hSql, ROW_MarkDeleted )

SalTblDoInsertsSyntax bOk = SalTblDoInserts ( hWndTbl, hSql, bClearFlags )

Description Applies a SQL INSERT statement to all the rows in a table window that have theROW_New flag set. You must prepare the SQL INSERT statement before callingfunction.

This function does not perform a COMMIT. You must perform a COMMIT to ensuthat insertions are not lost in the case of a rollback.


hSql Sql Handle. The handle of an INSERT statement.

bClearFlags Boolean. Whether to reset the ROW_New flag.

If TRUE, Centura clears the ROW_New flag of each inserterow; if FALSE, Centura does not clear the ROW_New flag oeach inserted row. This is useful for error handling; if an erroccurs, you can rollback the transaction and try again.


See Also SalTblDeleteSelectedSalTblDoDeletesSalTblDoUpdatesSalTblPopulate

Example Call SalTblDoInserts ( tblExample, hSql, FALSE )


d on.

re

ed of or

t etch

the

SalTblDoUpdatesSyntax bOk = SalTblDoUpdates ( hWndTbl, hSql, bClearFlags )

Description Applies a SQL UPDATE statement to all table window rows with the ROW_Editeflag set. You must prepare the SQL UPDATE statement before calling this functi

This function does not perform a COMMIT. You must perform a COMMIT to ensuthat the updates are not lost in the case of a rollback.


hSql Sql Handle. The handle of an UPDATE statement.

bClearFlags Boolean. Whether to reset the ROW_Edited flag.

If TRUE, Centura clears the ROW_Edited flag of each changrow; if FALSE, Centura does not clear the ROW_Edited flag each changed row. This is useful for error handling; if an erroccurs, you can roll back the transaction and try again.


See Also SalTblDeleteSelectedSalTblDoDeletesSalTblDoInsertsSalTblPopulate

Example Call SalTblDoUpdates ( tblExample, hSql, FALSE )

SalTblFetchRowSyntax nResult = SalTblFetchRow ( hWndTbl, nRow )

Description Sends a SAM_FetchRow message to a table window if the row you specify is nocurrently in the table window cache. To process the SAM_FetchRow message, fthe row from the database or another data source.

The SAM_FetchRow message sets the context row to the row you specify beforetable window receives the message.

Parameters hWndTbl Window Handle. The handle (or name) of the table window that owns the row being retrieved.

nRoNumber. The row number.

Return Value nResult is one of these values: TBL_RowDeleted, TBL_RowFetched, TBL_NoMoreRows.


Chapter 2

e the

e

lue the

its

See Also SalTblQueryContextSalTblSetContext

Example Call SalTblFetchRow ( hWndtblTelephone, nMaxRange )

SalTblFindNextRowSyntax bOk = SalTblFindNextRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff )

Description Scans forward in a table looking for a row whose flags match those specified. Thsearch stops at the first row that has any of the nFlagsOn flags set, and none ofnFlagsOff 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 thsearch 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 isbecause TBL_MinRow is a Centura constant, and nRow is a receive parameter whose vafunction 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; thesearch starts on nRow + 1. If Centura finds a row, it returns 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 SalTblFindPrevRowSalTblSetFlagsAnyRows


The the

e

s lue the

m

Example If SalTblFindNextRow ( hWndForm, nCurrentRow,

ROW_Selected, 0 )

SalTblFindPrevRowSyntax bOk = SalTblFindPrevRow ( hWndTbl, nRow, nFlagsOn, nFlagsOff )

Description Scans backward in a table looking for a row whose flags match those specified. search stops at the first row that has any of the nFlagsOn flags set, and none ofnFlagsOff 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 thsearch 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 ibecause TBL_MaxRow is a Centura constant, and nRow is a receive parameter whose vafunction 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 onnRow - 1. If Centura finds a row, it returns its row number inthis 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 theusing the OR (|) operator.

Return Value bOk is TRUE if Centura finds a row and FALSE if there are no matches.

See Also SalTblFindNextRowSalTblSetFlagsAnyRows

Example If SalTblFindPrevRow ( hWndForm, nCurrentRow,

ROW_Selected, 0 )


Chapter 2

a

SalTblGetColumnTextSyntax bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )

Description Gets data from a column of a table window's context row.


nColumnID Number. The Column Identifier

strText Receive string. The column data.


See Also SalTblSetColumnText

Example Set bOk = SalTblGetColumnText ( hWndTbl, nColumnID, strText )

SalTblGetColumnTitleSyntax nLength = SalTblGetColumnTitle ( hWndCol, strText, nMaxLen )

Description Gets the title of a table window column.

Parameters hWndCol Window Handle. The handle (or name) of a table window column.

strText Receive String. The title.

nMaxLen Number. The maximum length of the title.

Return Value nLength is the length of the column title returned in strText.

See Also SalTblSetColumnTitle

Example Call SalTblGetColumnTitle ( colRowHeader, strTitle, 100 )

SalTblGetColumnWindowSyntax hWndCol = SalTblGetColumnWindow ( hWndTbl, nCol, nFlags )

Description Gets the handle of a table window column.

Parameters hWndTbl Window Handle. The handle (or name) of the table windowthat 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 column identifier or a column position. Specify either:

COL_GetID


LL

e

e

both

COL_GetPos

Return Value hWndCol is the handle of a table window column. hWndCol is equal to hWndNUif Centura cannot find the table window column.

Example Set hWndCol = SalTblGetColumnWindow ( tbl1, nColID,COL_GetID )

SalTblInsertRowSyntax nNewRow = SalTblInsertRow ( hWndTbl, nRow )

Description Inserts a new blank row into a table window.


nRowNumber The row number of the new row.

If this value is a valid row number within the table window range, then Centura inserts a blank row at that location.

If you specify TBL_MaxRow, Centura appends the row to thend of the table window.

If the table window is split and you specify TBL_MinSplitRow, Centura appends the row to the top of thlower half of the table window.

Return Value nNewRow is the number of the new row if the function succeeds. It is equal to TBL_Error if an error occurs.

Example Set nNewRow = SalTblInsertRow ( hWndTbl,TBL_MinSplitRow )

SalTblKillEditSyntax bOk = SalTblKillEdit ( hWndTbl )

Description Takes a row out of edit mode and selects the row. This causes the row to receiveSAM_Validate and SAM_KillFocus messages.

Parameters hWndTbl Window Handle. The handle (or name) of the table window that contains the row just inserted or modified.


Example Set bOk = SalTblKillEdit ( hWndTbl )


Chapter 2

ble

rows the

ble

s of ages

s the te indow

SalTblKillFocusSyntax bOk = SalTblKillFocus ( hWndTbl )

Description Turns off the table window's focus frame. This is useful when the user chooses amenu item from a table window menu; in this case, the focus cannot leave the tawindow.



Example Call SalTblKillFocus ( hWndForm )

SalTblPasteRowsSyntax 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 newinto the table window without overwriting existing rows, and converts the data todata types of the corresponding table window columns.

Parameters hWndTbl Window Handle. The handle (or name) of the table windowreceiving the data from the Clipboard.

Return Value bOk is TRUE if the Clipboard contains text that is successfully inserted into the tawindow, and FALSE otherwise, and if none of the columns are editable.

See Also SalTblCopyRows

Example Call SalTblPasteRows ( tblPhoneList )

SalTblPopulateSyntax bOk = SalTblPopulate( hWndTbl, hSql, strSelect, nMethod )

Description Compiles, binds, and executes a SQL SELECT statement, then fetches the rowthe result set and populates a table window with them. SalTblPopulate also mantable 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 usedatabase column names as table window column titles. If you call SalTblPopulaagain during the same runtime session, Centura destroys the automatic table wcolumns created by the last SELECT statement and creates new columns.


oes

.

ed. bling

to

se

ra d

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 dnot 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 theresult set so in processing this message, you cannot refer to the row being fetchHowever, the SAM_FetchRowDone message is sent after the row is fetched, enayou to refer to the row just fetched.

Parameters hWndTbl Window Handle. The handle (or name) of the table window populate.

hSql Sql Handle. The handle of the SELECT statement. Do not uthe Sql Handle passed to SalTblPopulate by other functionswhile the table window is in use.

strSelect String. The SELECT statement. If the string is null (“), Centuuses the previously prepared SELECT statement associatewith hSql. This avoids re-preparing the statement each timeSalTblPopulate executes.

nMethod Number. How to populate the table window. Specify one of these values:

TBL_FillAll

TBL_FillAllBackground

TBL_FillNormal

Return Value bOk is TRUE if the function succeeds and FALSE if either hWndTbl or hSql is invalid.

See Also SalTblDeleteSelectedSalTblDoDeletesSalTblDoInsertsSalTblDoUpdates

Example Call SalTblPopulate ( tblExample, hSql, strSql, TBL_FillAllBackground )


Chapter 2

,

the .

get

.

rd

SalTblQueryCheckBoxColumnSyntax bOk = SalTblQueryCheckBoxColumn( hWnd, hWndCol, nFlags, sCheckedValue

sUncheckedValue )

Description If the column is defined as a check box, this function retrieves information aboutcheck box and returns TRUE. If it is not a check box, this function returns FALSE



nFlags Receive Number. nFlags is a combination of the following flags using the '|' operator:

COL_CheckBox_IgnoreCase = 0x0001

sCheckedValue Receive String. sCheckedValue is the value that a cell willwhen the check box is checked.

sUncheckedValue Receive String. The value when a check box is unchecked


Example bOk = SalTblQueryCheckBoxColumn ( hWnd, hWndCol, nFlags,sCheckedValue, sUncheckedValue )

SalTblQueryColumnCellTypeSyntax bOk = SalTblQueryColumnCellType( hWnd, hWndCol, nType )

Description Indicates whether a column is a checkbox, drop down list, popup edit, or standacolumn.


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

nType Receive Number. Receives one of the following values.

COL_CellType_Standard=1

COL_CellType_CheckBox=2

COL_CellType_DropDownList=3

COL_CellType_PopupEdit=4


Example Set bOk = SalTblQueryColumnCellType ( hWnd, hWndCol, nType )


e.

ble

SalTblQueryColumnFlagsSyntax bSet = SalTblQueryColumnFlags ( hWndCol, nFlags )

Description Tests the state of a table window column's flags.


nFlags Number. The column flags to test. You can combine COL_*flags using the OR (|) operator.

Return Value bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwis

See Also SalTblSetColumnFlags

Example If SalTblQueryColumnFlags ( col1, COL_CenterJustify )

Set rbCenter = TRUE

Else

Set rbLeft = TRUE

SalTblQueryColumnIDSyntax nColID = SalTblQueryColumnID ( hWndCol )

Description Gets a table window column's identifier.

Parameters hWndCol Window Handle. The handle of a table window column.

Return Value nColID is the Column Identifier. nColID is -1 if hWndCol is not a valid column.

Example Set nColID = SalTblQueryColumnID ( hWndCol )

Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )

SalTblQueryColumnPosSyntax nPos = SalTblQueryColumnPos ( hWndCol )

Description Gets a table window column's relative position.

Parameters hWndCol Window Handle. The handle of a table window column.

Return Value nPos is the Column Position. nPos is -1 if hWndCol is not a valid handle for a tawindow column.

See Also SalTblSetColumnPos

Example Set nPos = SalTblQueryColumnPos ( hWndCol )


Chapter 2

text rect

out .

SalTblQueryColumnWidthSyntax bOk = SalTblQueryColumnWidth ( hWndTbl, nFormUnits )

Description Returns the width (in form units) of a table window column.

Parameters hWndTbl Window Handle. The handle (or name) of a table window column.

nInches Receive Number. The width of the table window column.


See Also SalTblSetColumnWidth

Example Call SalTblQueryColumnWidth ( colRowHeader, nWidth )

SalTblQueryContextSyntax nContext = SalTblQueryContext ( hWndTbl )

Description Returns a table window's current context row.

Before sending a SAM_FetchRow message, Centura automatically sets the conrow so that assignments made while processing the message reference the corrow.


Return Value nContext is the current context row number.

See Also SalTblFetchRowSalTblSetContext

Example Set nContext = SalTblQueryContext ( hWndTbl )

SalTblQueryDropDownListColumnSyntax bOk = SalTblQueryDropDownListColumn ( hWnd, hWndCol, nFlags, nLines )

Description If the column is defined as a drop down list, this function retrieves information abthe list and returns TRUE. If it is not a drop down list, this function returns FALSE





COL_DropDownList_Sorted=0x0001

COL_DropDownList_VScroll=0x0002


COL_DropDownList_Editable=0x0008

nLines Receive Number. nLines indicates the maximum number oflines to display in the list.


Example Set bOk = SalTblQueryDropDownListColumn ( hWnd, hWndCol,nFlags, nLines )

SalTblQueryFocusSyntax bOk = SalTblQueryFocus ( hWndTbl, nRow, hWndCol )

Description Identifies the cell in a table window with the focus.


nRoReceive Number. The row number of the focus row.

hWndCol Receive Window Handle. The handle of the column with thefocus.


See Also SalTblSetFocusCellSalTblSetFocusRow


Call SalTblQueryFocus ( hWndtblTelephone, nRow,hWndColumn )

SalTblQueryLinesPerRowSyntax bOk = SalTblQueryLinesPerRow( hWndTbl, nLines )

Description Retrieves the height of a row in lines.

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

nLines Receive Number. The number of lines.



Chapter 2

ns,

the E.

f

Example Set bOk = SalTblQueryLinesPerRow ( hWndTbl, nLines )

SalTblQueryLockedColumnsSyntax nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )

Description Retrieves the number of locked table window columns.

Locked table window columns do not scroll horizontally; they are fixed to the leftside of the table window. All other columns appear to scroll under the locked columns.


Return Value nLockedColumns is the number of locked columns. If there are no locked columnLockedColumns is zero (0).

See Also SalTblSetLockedColumns

Example Set nLockedColumns = SalTblQueryLockedColumns ( hWndTbl )

SalTblQueryPopupEditColumnSyntax bOk = SalTblQueryPopupEditColumn( hWnd, hWndCol, nFlags, Lines )

Description If the column is defined as a popup edit, this function retrieves information aboutpopup edit and returns TRUE. If it is not a popup edit, this function returns FALS




COL_DropDownList_Sorted =0x0001

COL_DropDownList_VScroll =0x0002


COL_DropDownList_Editable=0x0008

nLines Receive Number. nLines indicates the maximum number olines to display in the list.


Example Set bOk = SalTblQueryPopupEditColumn ( hWnd, hWndCol, nFlags, Lines )


*

fied

ea on croll

se:

SalTblQueryRowFlagsSyntax bOk = SalTblQueryRowFlags ( hWndTbl, nRow, nFlags )

Description Queries a row's flags.


nRoNumber. The row number of the row whose flags you want to test.

nFlags Number. The row flags to test for. You can combine ROW_flags using the OR (|) operator.

Return Value bOk is TRUE if any of the specified flags are set and FALSE if none of the speciflags are set.

See Also SalTblSetFlagsAnyRowsSalTblSetRowFlags

Example On SAM_SetFocus

If SalTblQueryRowFlags ( hWndForm, lParam, ROW_New )

SalTblQueryRowHeaderSyntax bOk = SalTblQueryRowHeader ( hWndTbl, strTitle, nMaxTitle, nWidth,

nFlags, hWndCol )

Description Gets a table window's row header definition. The row header is a non-editable arthe left edge of a table window that displays information that you do not want to soff the screen as the user scrolls horizontally. A typical use is the display of row numbers.


strTitle Receive String. The title of the row header.

nMaxTitle Number. The maximum length of the title.

nWidth Receive Number. The width of the row header in pixels.

nFlags Receive Number. Row header attributes. Specify one of the

TBL_RowHdr_MarkEdits

TBL_RowHdr_ShareColor

TBL_RowHdr_Sizable

TBL_RowHdr_Visible


Chapter 2

is

es it

w.

alf

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


Example Call SalTblQueryRowHeader ( tbl1, strTitle, 100, nWidth,

nFlags, colRowHeader )

SalTblQueryScrollSyntax bOk = SalTblQueryScroll ( hWndTbl, nPosition, nMinRange, nMaxRange )

Description Returns a table window's current scroll position and range.

The scroll position is the row number of the row that is currently at the top of thewindow. You set the table window range with SalTblSetRange and Centura changwhen you insert or delete rows from the table window.


nPosition Receive Number. The scroll position.

nMinRange Receive Number. The minimum table range.

nMaxRange Receive Number. The maximum table range.


Example Call SalTblQueryScroll ( hWndTbl, nPosRow, nMinRow, nMaxRow )

SalTblQuerySplitWindowSyntax bOk = SalTblQuerySplitWindow ( hWndTbl, nRowsLowerHalf,Syntax

bDragAdjust )

Description Specifies how a table window is split horizontally.

Parameters hWndTbl Window Handle. The handle (or name) of a split table windo

nRowLowerHalf Receive Number. The number of visible rows in the lower hof 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.



e.

tting

Example Set bOk = SalTblQuerySplitWindow ( hWndTbl,nRowsLowerHalf,Syntax,bDragAdjust )

SalTblQueryTableFlagsSyntax bSet = SalTblQueryTableFlags ( hWndTbl, nFlags )

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


nFlags Number. The table flags to test. You can combine TBL_* flags using the OR (|) operator.

Return Value bSet is TRUE if any of the flags indicated by nFlags are set and FALSE otherwis

See Also SalTblSetTableFlags

Example If SalTblQueryTableFlags ( tbl1, TBL_Flag_MoveableCols )

Set rbColsMovable = TRUE

SalTblQueryVisibleRangeSyntax bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )

Description Returns the current range of visible rows in a table window.


nRangeMin Receive Number. The first visible row.

nRangeMax Receive Number. The last visible row.


Example Set bOk = SalTblQueryVisibleRange ( hWndTbl, nRangeMin, nRangeMax )

SalTblResetSyntax bOk = SalTblReset ( hWndTbl )

Description Clears a table window by discarding all rows from the table window cache and sethe table range to 0, -1.



See Also SalTblSetRange


Chapter 2

e

w.

:

w.

xt

re- ry.

Example If nRowCount > 0

Call SalTblReset ( hWndForm )

SalTblScrollSyntax bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )

Description Scrolls a table window to the specified row and column.


nRoWNumber The number of the row to scroll to. If you specify -1, only thcolumn scrolls into view.

hWndColumn Window Handle. The table window column to scroll into vieIf 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 roThis function fails if either nRow or nTBLScroll are invalid values.

See Also SalTblQueryScrollSalTblQueryVisibleRange

Example Set bOk = SalTblScroll ( hWndTbl, nRow, hWndColumn, nTBLScroll )

SalTblSetCellTextColorSyntax bOk = SalTblSetCellTextColor ( hWndCol, nColor, bDiscardable )

Description Changes a table window cell's text color.


nColor Number. The cell text color. Specify one of the predefined windows colors.

bDiscardable Boolean. Determines whether Centura discards the cell tecolor if and when the user re-fetches the row.

If TRUE, Centura discards the cell text color when the user fetches the row. If FALSE, Centura keeps the cell text color.This requires additional resources to keep the row in memo


a

the


Example On SAM_FetchRow

Call SalTblSetCellTextColor ( Col1, COLOR_Red, TRUE )

Return TBL_RowFetched

SalTblSetColumnFlagsSyntax bOk = SalTblSetColumnFlags ( hWndCol, nFlags, bSet )

Description Sets or clears a table window column's flags.


nFlags Number. The column flags to change. You can combine COL_* flags using the OR (|) operator.

bSet Boolean. If TRUE, Centura sets the flags; if FALSE, Centurclears the flags.

Return Value bOk is TRUE if the function succeeds and FALSE if it fails. To define a column acolumn as multiline use the flag:

COL_MultilineCell = 0x00800000

See Also SalTblQueryColumnFlags

Example Call SalTblSetColumnFlags ( col1, COL_CenterJustify, TRUE )

SalTblSetColumnPosSyntax bOk = SalTblSetColumnPos ( hWndCol, nPos )

Description Moves a table window column to a new position.

Parameters hWndCol Window Handle. The handle (or name) of a table window column to move.

nPos Number. The new position of the table window column. 1 is first (left-most) position, 2 is the second position, and so on.


See Also SalTblQueryColumnPos

Example Call SalTblSetColumnPos ( col3, nPos + 1 )


Chapter 2

SalTblSetColumnTextSyntax bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )

Description Assigns data to a column of a table window's context row.


nColumnID Number. The Column Identifiers

strText String. The data to assign.


See Also SalTblGetColumnText

Example Set bOk = SalTblSetColumnText ( hWndTbl, nColumnID, strText )

SalTblSetColumnTitleSyntax bOk = SalTblSetColumnTitle ( hWndCol, strTitle )

Description Sets the title of a table window column.


strTitle String. The title of the table window column.


See Also SalTblGetColumnTitle

Example Set bOk = SalTblSetColumnTitle ( hWndCol, strTitle )

SalTblSetColumnWidthSyntax bOk = SalTblSetColumnWidth ( hWndTbl, nFormUnits )

Description Sets a table window column's display width.

Parameters hWndTbl Window Handle. The handle (or name) of a table window column.

nFormUnits Number. The table window column's display width in form units.


See Also SalTblQueryColumnWidth


not es to

bine

y

Example Set nColID = SalTblQueryColumnID ( hWndCol )

Call SalTblSetColumnWidth ( hWndCol, nWidths[ nColID ] )

SalTblSetContextSyntax bOk = SalTblSetContext ( hWndTbl, nRow )

Description Sets a table window's context row.

Setting the context row does not send a SAM_FetchRow message. If the row is currently in memory, Centura creates a new row in memory and sets its cell valunull.

Parameters hWndTbl Window Handle. The handle (or name) of a table window whose context row you want to set.

nRoNumber. The row number of the new context row.


See Also SalTblQueryContext

Example Set bOk = SalTblSetContext ( hWndTbl, nRow

SalTblSetFlagsAnyRowsSyntax bAny = SalTblSetFlagsAnyRows ( hWndTbl, nFlags, bSet,

nFlagsOn, nFlagsOff )

Description Sets or clears row flags.

Parameters hWndTbl Window Handle. The handle (or name) of a table window whose row flags you want to set or clear.

nFlags Number. The flags to change. You can combine flag valuesusing 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 comflag values using the OR (|) operator.

Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to specifall rows.

nFlagsOff Number. The flags that the rows should not have. You can combine flag values using the OR (|) operator.


Chapter 2

fy

and

the cell.

of

ed f

Set nFlagsOn to zero (0) and nFlagsOff to zero (0) to speciall rows.

Return Value bAny is TRUE if any of the table window's rows have any of the nFlagsOn flags none of the nFlagsOff flags.

See Also SalTblFindNextRowSalTblFindPrevRow

Example Call SalTblSetFlagsAnyRows ( tblExample, ROW_MarkDeleted, TRUE, ROW_Selected, 0 )

SalTblSetFocusCellSyntax bOk = SalTblSetFocusCell ( hWndTbl, nRow, hWndCol, nEditMin, nEditMax )

Description Sets the focus to the specified table window cell (row and column). Centura putstable window into edit mode and lets the user select a portion of the data in the


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 usedwith nEditMax, this parameter lets the user select a portion the cell text.

nEditMin must be less than or equal to nEditMax.

To select all the characters in a cell, specify zero (0) for thisparameter and -1 for nEditMax.

nEditMax Number. The position of the right-most character. When uswith nEditMin, this parameter lets the user select a portion othe cell text.

nEditMax must be greater than or equal to nEditMin.

To select all the characters in a cell, specify -1 for this parameter and zero (0) for nEditMin.


See Also SalTblQueryFocus

Example Call SalTblSetFocusCell ( hWndForm, lParam,hWndItem, 0, 1 )


ed ine

u ll

o (0)

SalTblSetFocusRowSyntax bOk = SalTblSetFocusRow ( hWndTbl, nRow )

Description Sets a table window's focus frame row.


nRoNumber. The row number of the row to which to apply the focus frame.


See Also SalTblQueryFocus

Example Set bOk = SalTblSetFocusRow ( hWndTbl, nRow

SalTblSetLinesPerRowSyntax bOk = SalTblSetLinesPerRow( hWndTbl, nLines )

Description Sets the height of a row in lines. Multirow lines are useful when a column is definas multiline. The text in each cell will wrap. To define a column a column as multiluse the function SalTblSetColumnFlags with the flag:

COL_MultilineCell = 0x00800000

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

nLines Number. The number of lines.


Example Set bOk = SalTblSetLinesPerRow ( hWndTbl, nLines )

SalTblSetLockedColumnsSyntax bOk = SalTblSetLockedColumns ( hWndTbl, nLockedColumns )

Description Sets the number of locked table window columns. Table window columns that yolock do not scroll horizontally; they are fixed to the left side of the table window. Aother columns appear to scroll under the locked columns. This function locks zeror more of the left-most visible columns of a table window.


nLockedColumns Number. The number of table window columns to lock.


See Also SalTblQueryLockedColumns


Chapter 2

en

e

e

Example Call SalTblSetLockedColumns ( tbl1, 2 )

SalTblSetRangeSyntax bOk = SalTblSetRange ( hWndTbl, nMin, nMax )

Description Defines the minimum and maximum rows (range) of a table.

Parameters hWndTbl The handle (or name) of a table window.

nMin Number. The lower boundary of the table window.

nMax Number. The upper boundary of the table window.

Setting nMin and nMax:

nMin must be less than or equal to nMax.

You can specify an empty table with the range 0, -1.

You can specify a dynamic range with the values zero (0), TBL_MaxRow. Centura determines the higher boundary whthe application returns TBL_NoMoreRows from a SAM_FetchRow message, or from the return of the SAM_FetchDone message.


See Also SalTblReset

Example Call SalTblSetRange ( hWndForm, 0, nRowCount - 1 )

SalTblSetRowSyntax nRowNum = SalTblSetRow ( hWnd, nRowPos )

Description Sets the focus to the first, last, next, or previous row in a table window.

Parameters tName Window Handle. The handle (or name) of the window whoscurrent focus row you want to change.

nRowPos Number. The position of the focus row. Specify one of thesvalues:

TBL_SetFirstRow

TBL_SetLastRow

TBL_SetNextRow

TBL_SetPrevRow

Return Value nRowNum is the row number of the new focus row.


*

*

Example Set = nRowNum = SalTblSetRow ( hWnd, nRowPos )

SalTblSetRowFlagsSyntax bOk = SalTblSetRowFlags ( hWndTbl, nRow, nFlags, bSet )

Description Sets or clears a table window row's flags.


nRoNumber. The row number of the row whose flags you want to set or clear.

nFlags Number. The row flags. You can combine any of the ROW_flags using the OR (|) operator.



See Also SalTblQueryRowFlagsSalTblSetFlagsAnyRows

Example Call SalTblSetRowFlags ( hWndTbl, nRow, ROW_Selected, TRUE )

SalTblSetTableFlagsSyntax bOk = SalTblSetTableFlags ( hWndTbl, nFlags, bSet )

Description Sets or clears a table window's flags.


nFlags Number. The table flags. You can combine any of the TBL_flags using the OR (|) operator.



See Also SalTblQueryTableFlags

Example Call SalTblSetTableFlags ( tbl1, TBL_Flag_MoveableCols, FALSE)


Chapter 2

the e an

t

SalTblSortRowsSyntax bRet = SalTblSortRows ( hWndTbl, nColumnID, nOrder )

Description Sorts the rows of a non-discardable table window based on the values in one oftable window's columns. You must create this column at design time; it cannot bautomatic 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.


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 )

SalTimerKillSyntax 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 cannofind the specified timer.

See Also SalTimerSet

Example On SAM_Destroy

Call SalTimerKill ( dfClock, 1 )


ends

rned

ted

If

ow

.

e rX

SalTimerSetSyntax bOk = SalTimerSet ( hWnd, nIDEvent, nElapseMilliSec )

Description Creates a system timer for a given object. When a timer event occurs, Centura sSAM_Timer messages to the object in specified intervals.

Timers are a limited global resource. Your application must check the value retuby SalTimerSet to verify that the timer was created.

Parameters hWnd Window Handle. The handle (or name) of an object associawith 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). you set this parameter to a higher value, it wraps.


See Also SalTimerKill


Set bOk = SalTimerSet ( hWndItem, 1, 1000 )

SalTrackPopupMenuSyntax 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 windthat 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 cancombine flag values using the OR (|) operator.

nX Number. The position of the pop-up menu on the X axis. Thvalue of this parameter is ignored if you set the TPM_Cursoflag in nFlags.


Chapter 2

e rY

r top

fter it your ate a

ow

nY Number. The position of the pop-up menu on the Y axis. Thvalue of this parameter is ignored if you set the TPM_Cursoflag in nFlags.

The nX and nY Parameters together represent a point (the top left, top middle, oright) of the pop-up menu, depending on the nFlags value.



Call SalTrackPopupMenu ( hWndForm, 'menuEdit',

TPM_CursorX | TPM_CursorY | TPM_CenterAlign, 0, 0 )

SalUpdateWindowSyntax 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 aprocesses all other messages in the queue. If, during the development phase ofapplication, you find that painting is being delayed, you can force Centura to updwindow.

For example, if you call SalListClear to delete all the entries in a list box and follthis 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 Window Handle. The handle (or name) of the window to update.

Return Value bOk is TRUE if the function succeeds and FALSE if hWndUpdate is not a valid window handle.

See Also SalInvalidateWindow


On SAM_FieldEdit

Call SalUpdateWindow ( ml1 )


s the The

trol.

the

cus es

SalUseRegistrySyntax 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 alast parameter of the SalProfile* functions will be used as the application name. resulting path will be:

\\HKEY_CURRENT_USER\Software\<company name>\<application name>\<section>\<setting>\

Parameters bUseRegistry - TRUE if registry is to be used, FALSE if INI files are to beused.

sCompanyName - Name of company to be used under the registry.

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

Example Set bOk = SalUseRegistry ( bUseRegistry, sCompanyName )

SalValidateSetSyntax bOk = SalValidateSet ( hWndCC, bValState, lParam )

Description You call SalValidateSet when the user tries to move the focus to the custom con

In Centura, changes in focus trigger validation. SalValidateSet tells Centura thatfocus is changing to a custom control so that Centura can perform validation as needed.

Important: You must set the Tab stop item in the Customizer to Tab or Group so that the custom control can receive the focus.

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

Return Value bOk is TRUE Centura sends SAM_Validate when the custom control loses the foand FALSE if Centura does not send SAM_Validate when the custom control losthe 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:


Chapter 2

the e to

cus

ser ges us to

t the

s

• If validation succeeds, SalValidateSet returns TRUE and Centura movesfocus to the custom control. Later, when the user moves the focus off thcustom control, Centura sends it SAM_Validate if its field edit flag is setTRUE.

• If validation fails, SalValidateSet returns FALSE and Centura sets the foto the invalid object.

For an editable custom control, you want Centura to send SAM_Validate if the uchanges the value. Call SalSetFieldEdit( hWndItem, TRUE ) when the user chanthe value so that Centura sends SAM_Validate if the user tries to change the focanother object.

Example Call SalValidateSet ( hWndItem, TRUE, 0 )

SalWaitCursorSyntax bOk = SalWaitCursor ( bOn )

Description Displays or removes the hourglass cursor. The hourglass is a visual indicator thaapplication is busy.

You must always call this function twice; once to turn the cursor into an hourglasand again to restore it to its original form.

Parameters bOn Boolean. Whether to turn the hourglass on (TRUE) or off (FALSE).


Example Call SalWaitCursor ( TRUE )

SalWindowClassNameSyntax sClassName = SalWindowClassName( hWnd )

Description Return the name of a window's class as a string.

Parameters hWnd Window Handle. The window handle of an instance of a Window Class object.

Return Value Returns an empty string if the window is not a class object.

Example Set sClassName = SalWindowClassName ( hWnd )


rty

ter as

f a

SalWindowGetPropertySyntax bOk = SalWindowGetProperty( hWndQO, strPropName, strPropValue )

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

Parameters hWndQO Window Handle. The window handle of an instance of a QuickObject.

strPropName String. The name of the property.

strPropValue Receive String. The value of the property.


Example This example gets a window name property:

Set bOk = SalWindowGetProperty ( hWndItem, 'WindowName',strWindowName )

SalWindowHandleToNumberSyntax nWnd = SalWindowHandleToNumber ( hWnd )

Description Converts a window handle to a number.

For example, you can pass a window handle as a SalSendMsg wParam paramefollows:

nWnd = SalWindowHandleToNumber ( hWndParm )

Call SalSendMsg ( hWndDest, nMsg, nWnd, 0 )

Parameters hWnd Window Handle. The handle to convert.

Return Value nWnd is the number converted from hWnd.

See Also SalNumberToWindowHandle

Example Set ntblCustomer = SalWindowHandleToNumber( hWndtblCustomer )

SalWindowIsDerivedFromClassSyntax bOk = SalWindowIsDerivedFromClass( hWnd, ClassName )

Description Tells you if a window is an instance of the class that you specify or an instance oclass that is derived from the class that you specify.


Chapter 2

ned -d ation

ng.

class

r

Call this function to determine if you can make a late-bound call to a function defiin 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 nameclass and the function returns a value, you get an error at runtime and the applicends.

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

ClassName Symbol. The ClassName parameter is a symbol, not a striType 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 that is derived from the named class.

Example Set bOk = SalWindowIsDerivedFromClass ( hWnd, ClassName )

SalWinHelpSyntax 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 usepresses the F1 key. Process this message by calling SalWinHelp.

Parameters hWnd Window Handle. The handle (or name) of the window requesting help.

strFile String. The file name of the help system file.

nCommand Number. The type of help requested; any HELP_* value.

nData Number. Specify zero (0) unless:

• nCommand is HELP_Context and nData is a context identifier number.

• nCommand is HELP_SetIndex and nData specifies thecurrent help index.

strData String. The context or keyword string of the requested helptopic. This parameter is null unless nCommand is equal to HELP_Key.


Example Call SalWinHelp ( hWndForm, 'CONTROL.HLP', HELP_Index, 0, '')


ple, cel

SalYieldEnableSyntax bOk = SalYieldEnable ( bSet )

Description Enables or disables application yielding.

Parameters bSet Boolean. If TRUE, enable yielding; if FALSE, disable yielding.


See Also SalYieldQueryStateSalYieldStartMessagesSalYieldStopMessages

Example Call SalYieldEnable ( FALSE )

SalYieldQueryStateSyntax bEnabled = SalYieldQueryState ( )

Determines whether application yielding is enabled or disabled.


Return Value bEnabled is TRUE if yielding is enabled, and FALSE if it is not.

See Also SalYieldEnableSalYieldStartMessagesSalYieldStopMessages

Example Set bEnabled = SalYieldQueryState ( )

SalYieldStartMessagesSyntax bOk = SalYieldStartMessages ( hWnd )

Description Enables yielding and the sending of messages to a window.

Enable yielding to give the user enough control to stop long operations. For examif it takes a long time to populate a table window, allow the user access to a Canpush button to stop the query.



See Also SalYieldEnableSalYieldQueryStateSalYieldStopMessages


Chapter 2

all to

ains

ect

all used.

Example Call SalYieldStartMessages ( pbCancel )

SalYieldStopMessagesSyntax bOk = SalYieldStopMessages ( )

Description Stops yielding and the sending of messages to the window specified in a prior cSalYieldStartMessages.



See Also SalYieldEnableSalYieldQueryStateSalYieldStartMessages

Example Call SalYieldStopMessages ( )

SqlClearImmediateSyntax bOk = SqlClearImmediate ( )

Description Disconnects the internal Sql Handle from a database.

You connect the internal handle to a database by calling SqlImmediate and it remconnected until the application terminates or you explicitly disconnect it with SqlClearImmediate.

SqlClearImmediate causes an implicit COMMIT if it is the last cursor you disconnfrom the database.



See Also SqlImmediate

Example Set bOk = SqlClearImmediate ( )

SqlCloseSyntax bOk = SqlClose ( hSql )

Description Invalidates a SQL command and/or frees the cursor name associated with the specified cursor, making it available for re-use.

If you create a named cursor by calling SqlOpen and then instead of closing it, cSqlOpen or SqlExecute again, you get an error that the name has already been


tabase.

,

s. The of

sage

Parameters hSql Sql Handle. A handle that identifies a database connection.


See Also SqlOpen

Example Set bOk = SqlClose ( hSql )

SqlCommitSyntax bOk = SqlCommit ( hSql )

Description Commits all of the SQL transaction's cursors that are connected to the same da

NOTE: To prevent destroying a cursor's result set when a COMMIT is performedturn on cursor context preservation by calling SqlSetParameter and setting the DBP_PRESERVE parameter to TRUE.



Example Call SqlCommit ( hSql )

SqlConnectSyntax bOk = SqlConnect ( hSql )

Description Connects to a database.

Centura uses the values in the SqlDatabase, SqlUser, and SqlPassword variabledefault values for these variables are DEMO, SYSADM, and SYSADM. The valueother system variables such as SqlNoRecovery, SqlInMessage, and SqlOutMestake effect after this function executes.

Parameters hSql Receive Sql Handle. A handle that identifies a database connection.


See Also SqlDisconnect

Example Call SqlConnect ( hSqlPrimary )


Chapter 2

.

r

.

SqlContextClearSyntax 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 Sql Handle. A handle that identifies a database connection


See Also SqlContextSetSqlContextSetTo Form

Example Set bOk = SqlContextClear ( hSql )

SqlContextSetSyntax bOk = SqlContextSet ( hSql )

Description Sets the context for future processing (for example, calls to SqlPrepare, SqlFetchNext, SqlFetchPrevious, and SqlFetchRow). Sql* functions you call afteSqlContextSet 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 INTOvariables is always hWndForm. If you call a Sql* function in an internal function, window function, or class function after calling SqlContextSet, Centura does notrecognize local variables or Parameters that you use as bind variables and INTO variables.




See Also SqlContextClearSqlContextSetTo Form

Example Set bOk = SqlContextSet ( hSql )


ow

he not

f the

tion

SqlContextSetToFormSyntax 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 windyou specify in the second parameter.

Call this function from a child table window when you want to set the context to tparent form window; in this situation hWndForm refers to the child table window, to the parent form window.


See Also SqlContextClearSqlContextSet

Example Set bOk = SqlContextSetToForm ( hSql, hWndMyForm)

SqlDirectoryByNameSyntax bOk = SqlDirectoryByName ( strServerName,

strArrayNames )

Description Returns the database names on the specified server.

Parameters strServerName String. The name of a server.

strArrayNames String Array. The name of an array of strings containing database names.



Call SqlDirectoryByName ( 'server1', strDatabaseNames )

SqlDisconnectSyntax bOk = SqlDisconnect ( hSql )

Description Disconnects from a database.

Disconnecting the last Sql Handle from a database causes an implicit COMMIT odatabase. Disconnect all Sql Handles before the application exits.

Parameters hSql Sql Handle. The handle that identifies the database connecto disconnect.


Chapter 2

.

ot

n rror


See Also SqlConnect

Example On SAM_AppExit

Call SqlDisconnect ( hSqlPrimary )

SqlDropStoredCmdSyntax bOk = SqlDropStoredCmd ( hSql, strName )

Description Deletes a stored command from a SQLBase database.


strName String. The name of the stored command to delete.


See Also SqlRetrieveSqlStore

Example Call SqlDropStoredCmd ( hSqlPrimary, 'PRODUCTS )

SqlErrorSyntax nError = SqlError ( hSql )

Description Returns the most recent error code for the specified Sql Handle.

SqlError is not useful after a call to SqlImmediate because SqlImmediate does nreturn a handle that you can use as the parameter for SqlError.

Parameters hSql Sql Handle. The handle on which an error occurred.

Return Value nError is the error code returned. It is equal to zero (0) if no error occurred.

See Also SqlExtractArgs

Example Set nSqlError = SqlError ( hSqlPrimary )

SqlErrorTextSyntax 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 aerror condition, you can use the error code returned by SqlError to look up the ereason and remedy with SqlErrorText.


R

s:

e

E or

Parameters nError Number. A SQLBase error code.

nType Number. Specify one or both (by combining them with the O(|) operator) of these constants:

strError Receive String. The reason or remedy explanation.

nLength Number. The maximum length of strError.

nRealLength Receive Number. The actual length of strError.


See Also SqlErrorSqlGetErrorTextSqlGetErrorTextX

Example Set bOk = SqlErrorText ( nError, nType, strError, nLength, nRealLength )

SqlExecuteSyntax bOk = SqlExecute ( hSql )

Description Executes a SQL statement that was prepared with SqlPrepare or retrieved with SqlRetrieve.

SqlExecute does not fetch data. To fetch data, call one of the SqlFetch* functionSqlFetchNext, 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 thresult set by a cursor name. That is, you cannot use the 'CURRENT OF <cursor_name>' and 'ADJUSTING <cursor_name>' clauses to UPDATE, DELETINSERT result set rows.

Parameters hSql Sql Handle. The handle associated with a SQL statement.


See Also SqlOpen

Example Call SqlExecute ( hSqlPrimary )

Constant Description

SQLERROR_Reason Retrieve error code reason.

SQLERROR_Remedy Retrieve error message remedy.


Chapter 2

s the s are

les to query.

e

es

all n an

SqlExecutionPlanSyntax bOk = SqlExecutionPlan ( hSql, strString, nLength )

Description Gets the execution plan for a compiled SQL statement. An execution plan showtables, views, indexes, and optimizations for the SQL statement. Tables and viewlisted 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.


Example Set bOk = SqlExecutionPlan ( hSql, strString, nLength )

SqlExistsSyntax bOk = SqlExists ( strSelect, bExists )

Description Determines whether a row exists.

SqlExists uses the values of the SqlDatabase, SqlUser, and SqlPassword variabconnect to a database, and uses an internal Sql Handle to execute the specified

Parameters strSelect String. The SELECT statement that establishes the existencof a row.

bExists Receive Boolean. TRUE if the row exists and FALSE if it donot.

Return Value bOk is TRUE if strSelect is correct and executable and FALSE otherwise.

Example Call SqlExists ( 'SELECT * FROM ' || strTable || 'WHERE ' || strExistsColumn || ' = ' || '\'' || strExistsObject || '\'', bExists )

SqlExtractArgsSyntax bOk = SqlExtractArgs ( wParam, lParam, hSql, nError,

nPos )

Description Extracts information from the SAM_SqlError wParam and lParam arguments. Cthis function only while processing a SAM_SqlError message which is sent wheerror occurs while executing a SQL function.


t.

e

on

ent

_*

ntil

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 argumen

nError Receive Number. The error code. Centura extracts this valufrom the low-order word of the lParam argument.

nPos Receive number. The error position, if relevant to the functicall. Centura extracts this value from the high-order word ofthe lParam argument.


See Also SqlErrorSqlGetErrorPosition

Example Call SqlExtractArgs ( wParam, lParam, hSqlError, nSqlError, nErrorPos )

SqlFetchNextSyntax bOk = SqlFetchNext ( hSql, nInd )

Description Fetches the next row in a result set. You must have prepared the SELECT statemwith SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen.

Parameters hSql Sql Handle. The handle of a SELECT statement.

nInd Receive Number. The fetch return code is one of the FETCHvalues.

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 uyou attempt to fetch past the last row.

See Also SqlFetchPreviousSqlFetchRow

Example Call SqlFetchNext ( hSqlPrimary, nRetVal )


Chapter 2

_*

e it

_*

SqlFetchPreviousSyntax bOk = SqlFetchPrevious ( hSql, nInd )

Description Fetches the previous row in a result set. You must have prepared the SELECT statement with SqlPrepare and executed it with SqlExecute, or opened it with SqlOpen.


nInd Receive Number. The fetch return code is one of the FETCHvalues.

Return Value bOk is TRUE if there is another row to fetch and FALSE otherwise.

See Also SqlFetchNext

SqlFetchRow

Example Call SqlFetchPrevious ( hSqlPrimary, nRetVal)

SqlFetchRowSyntax bOk = SqlFetchRow ( hSql, nRow, nInd )

Description Fetches a row according to an absolute row position. You must have prepared thSELECT statement with SqlPrepare and executed it with SqlExecute, or openedwith SqlOpen.


nRoNumber. The row number of the row to fetch.

nInd Receive Number. The fetch return code is one of the FETCH values.

Return Value bOk is TRUE if nRow could be fetched and FALSE otherwise.

See Also SqlFetchNextSqlFetchPrevious

Example Call SqlFetchRow ( hSqlPrimary, lParam, nRetVal )

SqlGetErrorSyntax bOk = SqlGetError ( hSql, nError, strErrorString )

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


r and

and

re, ed


nError Number. The error number.

strErrorString String. The error text.


You specify the Sql Handle in hSql and SqlGetError returns the last error numbeerror text in nError and strErrorString.

If the backend is SQLBase, this function does the same thing as calling SqlErrorSqlGetErrorText.

Example Set bOk = SqlGetError ( hSql, nError, strErrorString )

SqlGetErrorPositionSyntax bOk = SqlGetErrorPosition ( hSql, nPos )

Description Returns the offset of the error position within a SQL statement. After a SqlPrepathe error position points to the place in the SQL statement where Centura detectaSyntax error. The first character position in the SQL statement is zero (0).


nPos Receive Number. The position in the SQL statement whereaSyntax error occurred.


See Also SqlExtractArgs

Example Call SqlGetErrorPosition ( hSqlPrimary, nErrorPos )

SqlGetErrorTextSyntax bOk = SqlGetErrorText ( nError, strText )

or

strText = SqlGetErrorTextX ( nError )

Description Gets the message text for a SQL error number from ERROR.SQL.

Parameters nError Number. The error number.

strText Receive String. The error text.


strText is the message text for nError.


Chapter 2

ement ing

get

ected.

e L

er d for the

See Also SqlErrorTextSqlExtractArgs

Example Call SqlGetErrorText ( nError, strText )

or

Set strText = SqlGetErrorTextX ( nError )

SqlGetErrorTextXSyntax strText = SqlGetErrorTextX ( nError )

Description When the user chooses the Insert menu item, this example compiles a SQL statfor execution. To process any invalid SQL statements and trap the error (bypassthe default error processing), add the “When SqlError” statement with a FALSE return before the SqlPrepare. When SqlPrepare returns FALSE, call SqlError to the error number, call SqlGetErrorTextX to get the error description, and call SqlGetErrorPosition to get the character position where theSyntax error was det

Example Set strErrorText = SqlGetErrorTextX ( nSqlError )

SqlGetLastStatementSyntax sSqlStatement = SqlGetLastStatement( )

Description Returns the last SQL statement passed to a SqlXxxx function for any cursor. Thstatement returned is the same statement that would be shown in the default SQError dialog box.

Note: The statement is global for all cursors, therefore, if you get a SQL error after anothcursor has had a statement prepared the statement returned may not be the one preparehandle.


Return Value sSqlStatement contains the last SQL statement.

Example When SqlError

Set sStatement = SqlGetLastStatement ()


ue in

_*

r,

SqlGetModifiedRowsSyntax bOk = SqlGetModifiedRows ( hSql, nCount )

Description Returns the number of rows affected by the most recent INSERT, UPDATE, or DELETE statement.

Parameters hSql Sql Handle. The handle of a SQL statement.

nCount Receive Number. The number of rows affected.


Example Set bOk = SqlGetModifiedRows ( hSql, nCount )

SqlGetParameterSyntax bOk = SqlGetParameter ( hSql, nParameter, nNumber,

strString )

Description Gets the value of a database parameter. This function returns the parameter valnNumber or strString as appropriate for the data type of the parameter.


nParameter Number. The database parameter. Specify one of the DBPconstants.

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 nParametethis is the version number.


See Also SqlGetParameterAllSqlSetParameterSqlSetParameterAll


Call SqlGetParameter ( hSqlPrimary, DBP_LOCKWAITTIMEOUT, nTimeout, strNull )


Chapter 2

fined

.

e of

ow cursor t is

ever,

SqlGetParameterAllSyntax bOk = SqlGetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

Description Gets the value of a database parameter identified by a SQLP* constant value dein 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.


nParameter Number. The database parameter. Specify the value of onthe SQLP* constants defined in SQL.H.

nNumber Receive number. The value of nparameter it it is a number.

Receive string. The value of nParameter if it is a string.

bNumber Boolean. If TRUE, the parameter value is returned in nNumber. If FALSE, the parameter value is returned in strString.


See Also SqlGetParameterSqlSetParameterSqlSetParameterAll

Example Set bOk = SqlGetParameterAll ( hSql, nParameter, nNumber,strString, bNumber )

SqlGetResultSetCountSyntax bOk = SqlGetResultSetCount ( hSql, nCount )

Description Counts the rows in a result set by building the result set. Centura fetches each rthat has not already been fetched, returns a count of the rows, and positions the back to its original position. Warning: this can be time-consuming if the result selarge.

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. Howthe deleted blank rows disappear on the next SELECT.

You must be in Result Set mode.


ult of tiated

t

for tura

You must call SqlExecute before SqlGetResultSetCount.

Parameters hSql Sql Handle. A handle associated with a result set.

nCount Receive Number. The number of rows in the result set.


Example Actions

Call SqlPrepare ( hSqlPrimary, strSqlTblWindow )

Call SqlExecute ( hSqlPrimary )

Call SqlGetResultSetCount ( hSqlPrimary, nRowCount )

SqlGetRollbackFlagSyntax bOk = SqlGetRollbackFlag ( hSql, bRollbackFlag )

Description Returns the database rollback flag. Use this function after an error to find out if atransaction rolled back.

Centura sets the rollback flag when a system-initiated rollback occurs as the resa deadlock or system failure. Centura does not set the rollback flag on a user-inirollback.

Parameters hSql Sql Handle. The handle associated with the function call thagot an error.

bRollbackFlag Receive Boolean. TRUE if a rollback occurred and FALSE otherwise.


Example Call SqlGetRollbackFlag ( hSqlError, bRollbackFlag )

If bRollbackFlag

! Execute code to handle rolled back

! transaction

SqlImmediateSyntax bOk = SqlImmediate ( strSqlCommand )

Description Prepares and executes a SQL statement.

SqlImmediate actually performs a SqlConnect, a SqlPrepare, a SqlExecute, andSELECT statements, a SqlFetchNext. The first time you call SqlImmediate, Cenperforms all of these functions. On later calls, SqlConnect is not performed if notneeded.


Chapter 2

ase.

ext,

ore

bles in

d nal

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 datab

Any command that you execute with SqlImmediate, you can also execute with explicit calls to SqlConnect, SqlPrepare, SqlExecute or SqlOpen, and SqlFetchNfor SELECTs.

Parameters strSqlCommand String. The SQL statement to prepare and execute. This statement cannot have more than 128 bind variables and mthan 128 INTO variables.


See Also SqlClearImmediate

Example Call SqlImmediate ( 'INSERT INTO COMPANY ( COMPANY )' ||'VALUES( :frmMain dfCompany )' )

SqlImmediateContextSyntax bOk = SqlImmediateContext ( strSqlStatement )

Description Prepares and executes a SQL statement, and evaluates any bind or INTO variathe 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 anINTO variables is always hWndForm. If you call SqlImmediateContext in an interfunction, window function, or class function, Centura does not recognize local variables or parameters that you use as bind variables and INTO variables.

Parameters strSqlStatement String. A SQL statement.


See Also SqlContextClearSqlContextSet

Example Set bOk = SqlImmediateContext ( strSqlStatement )


it to

or

eter

SAL

e

and to

SqlOpenSyntax bOk = SqlOpen ( hSql, strCursorName )

Description Names a cursor and executes a SQL statement. Use this function to perform INSERTs, UPDATEs, and DELETEs on the current row.

Call SqlOpen after SqlPrepare and before any of the SqlFetch* commands.

Parameters hSql Sql Handle. The handle associated with the SqlPrepare.

strCursorName String. A string containing the cursor name.

Specify this name in the 'CURRENT OF <cursor_name>' or'ADJUSTING <cursor_name>' clause of an INSERT, UPDATE, or DELETE statement.

The value of this parameter is case insensitive. You can set null using the empty string ('').


See Also SqlCloseSqlExecute

Example Set bOk = SqlOpen ( hSql, strCursorName )

SqlPLSQLCommandSyntax bOk = SqlPLSQLCommand ( hSqlHandle, strCommand )

Description Use this function to execute PL/SQL stored procedures in Centura. Call it once feach invocation of PL/SQL.

The first argument identifies the SQL Handle to the database. The second paramis 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 infunction calls.

PL/SQL OUT or IN/OUT variables must be valid SAL receive parameters and, likSAL 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 receive data from a PL/SQL stored procedure in the same parameter.


Chapter 2

nput/R,

t

t-end

ge

as ;

d

as

Note: The SqlPLSQLCommand supports Centura dynamic arrays as input, output and ioutput arguments to Oracle7 PL/SQL stored procedures. Dynamic arrays of type NUMBESTRING and DATE/TIME are supported.

Dynamic Arrays as INPUT arguments

Dynamic arrays grow to the size of the largest index value used in an assignmenstatement using the dynamic array variables. For example:

nDynvar[0] = 0nnDynVar[1]= 1nDynvar[9] = 9

causes nDynVar to be a dynamic array of 10 elements.

When a dynamic array is passed as an INPUT argument to a PL/SQL stored procedure via SqlPLSQLCommand the number of elements created on the fronare 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 ranof 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 NUMBERa 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 backenstored 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 NULL values.


d as

base.

re.

odified. does

55

put L

Dynamic Arrays as INPUT/OUTPUT arguments

INPUT / OUTPUT dynamic arrays behave as INPUT dynamic arrays on input anOUTPUT dynamic arrays on OUTPUT.

Parameters hSqlHandle Sql Handle. The connected SQL Handle to an Oracle data

strCommand String. Command string used to invoke a PL/SQL procedu

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 mTo fix this problem, you need to force a recompile of that procedure. SqlPlSQLCommand not automatically do this.

SqlPrepareSyntax bOk = SqlPrepare ( hSql, strSqlStatement )

Description Compiles a SQL statement for execution. Compiling includes:

• Checking theSyntax of the SQL statement.

• Checking the system catalog.

• Processing a SELECT statement's INTO clause.

An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 2INTO variables per SQL statement.

• Identifying bind variables in the SQL statement. Bind variables contain indata for the statement. You can specify up to 2558 bind variables per SQstatement.

Follow this function with a SqlOpen, SqlExecute, SalTblDoInserts, SalTblDoUpdates, or SalTblDoDeletes, or fetches.


strSqlStatement String. The SQL statement to compile.



Chapter 2

28

put L

.

See Also SqlExecute

Example Call SqlPrepare ( hSqlPrimary, 'INSERT INTO CUSTOMER '

|| ' ( CUSTOMER ) VALUES ' ||'( :frmCustomer.dfCustomer )' )

SqlPrepareAndExecuteSyntax bOk = SqlPrepareAndExecute ( hSql, strSqlStatement )

Description Compiles and executes a SQL statement. Compiling includes:

• Checking theSyntax of the SQL statement.

• Checking the system catalog.

• Processing a SELECT statement's INTO clause.

An INTO clause names where data is placed when it is fetched. These variables are sometimes called INTO variables. You can specify up to 1INTO variables per SQL statement.

• Identifying bind variables in the SQL statement. Bind variables contain indata for the statement. You can specify up to 128 bind variables per SQstatement.


strSqlStatement String. The SQL statement to compile and execute.


See Also SqlExecuteSqlPrepare

Example Set bOk = SqlPrepareAndExecute ( hSql, 'Select name from' || ' employees into :df1' )

If bOk

Call SqlFetchNext ( hSql, nInd )


pile red

e

The y).

uter. size

ssage are

el.

SqlRetrieveSyntax 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 comthe command with SqlPrepare because the command is compiled when it is stowith SqlStore.


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 thecompiled 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 thnext command being executed is SalListPopulate.


See Also SqlDropStoredCmdSqlStore

Example Call SqlRetrieve ( hSqlPrimary, 'PRODUCTS', ':nPrice', ':strLBItem' )

SqlSetInMessageSyntax bOk = SqlSetInMessage ( hSql, nSize )

Description Sets the size (in bytes) of the input message buffer for the specified Sql Handle.input message buffer holds input for the application (such as the result of a quer

There is one input message buffer per connected Sql Handle on the client compThe database server (or gateway) maintains one input message buffer that is theof the largest input message buffer on the client computer.

When fetching data, as many rows as possible are compacted into one input mebuffer. Each FETCH reads the next row from the input message buffer until theyexhausted. At this point, if you are accessing a SQLBase database, SQLBase transparently fetches the next input buffer of rows depending on the isolation lev


Chapter 2

umber er can he ents

.

t 32

n n

.

s:

A large input message buffer can improve performance because it reduces the nof network messages between the client and server. A large input message buffhave a negative impact on concurrency, however, because any row currently in tbuffer can have a shared lock on it (depending on the isolation level) which prevother users from changing that row.


nSize Number. The size (in bytes) of the input message buffer thayou want to set. The default is 1 Kbyte and the maximum is Kbtyes.


See Also SqlSetOutMessage


Call SqlConnect ( hSqlPrimary )

Call SqlSetInMessage ( hSqlPrimary, 10000 )

SqlSetIsolationLevelSyntax 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 isolatiolevel you set applies to all the Sql Handles for that user name that the applicatioconnects to the database.


strIsolation String. The isolation level to set. Specify one of these value

CS Cursor Stability

RL Release Locks

RO Read Only

RR Read Repeatability



Call SqlSetIsolationLevel ( hSqlPrimary, 'RL' )


the

e -g

a ter

tion

ary

the


SqlSetLockTimeoutSyntax bOk = SqlSetLockTimeout ( hSql, nTimeout )

Description Specifies the maximum time to wait to acquire a lock. After the specified time elapses, a timeout occurs and the transaction rolls back.

Parameters hSql Sql Handle. A handle that identifies a database connection;cursor on which you want to set a lock timeout value.

nTimeout Number. The timeout period in seconds. Valid values includ1 (wait forever), 0 (never wait), and values up to and includin1800 (30 minutes). The default is 300.



Call SqlSetLockTimeout ( hSqlPrimary, 10 )

SqlSetLongBindDatatypeSyntax bOk = SqlSetLongBindDatatype( nBindVarNumber, nDatatype )

Description Sets the type of column (text or binary) that a Long String binds to. By default, Centura binds Long Strings to text columns. However, when you write or updatelong binary column, call SqlSetLongBindDatatype and set the nDatatype parameto binary (value = 23). Later you can set the type back to text by calling this funcand 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 binlong data type.

Parameters nBindVarNumber Number. The bind variable to set. The first bind variable in 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 )


Chapter 2

The nd to

ut rs.

se the ile or rted

both

.

he

.

e

SqlSetOutMessageSyntax bOk = SqlSetOutMessage ( hSql, nSize )

Description Sets the size (in bytes) of the output message buffer for a specified Sql Handle. output message buffer holds output from the application (such as a SQL commacompile 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 outpmessage buffer that is the size of the largest of its clients' output message buffe

A large output message buffer does not necessarily improve performance becaubuffer only needs to be large enough to hold the largest SQL command to compthe largest row of data to insert. (Rows are always sent to the database and inseindividually.) A large output message buffer can allocate space unnecessarily onthe client and the server, and it does not reduce network traffic.


nSize Number. The size (in bytes) of the output message buffer. Tdefault is 1 Kbyte and the maximum is 32 Kbytes.


See Also SqlSetInMessage


Call SqlConnect ( hSqlPrimary )

Call SqlSetOutMessage ( hSqlPrimary, 1500 )

SqlSetParameterSyntax bOk = SqlSetParameter ( hSql, nParameter, nNumber, strString )

Description Sets the value of a database parameter. Use the number (nNumber) and string (strString) arguments as appropriate for the data type of the parameter.


nParameter Number. The database parameter to set. Specify one of thDBP_* constants.

nNumber Number. The value of nParameter. Specify TRUE or FALSEfor all but DBP_LOCKWAITTIMEOUT, for which you must specify a value in seconds.

strString String. The value of nParameter.


fined ters

n.

of


See Also SqlGetParameterSqlGetParameterAllSqlSetParameterAll

Example Call SqlSetParameter ( hSqlPrimary, DBP_PRESERVE, TRUE, strNull )

SqlSetParameterAllSyntax bOk = SqlSetParameterAll ( hSql, nParameter, nNumber, strString, bNumber )

Description Sets the value of a database parameter identified by a SQLP* constant value dein SQL.H. This function uses the number (nNumber) and string (strString) parameas appropriate depending on the data type of the value of the parameter.

Parameters hSql Sql Handle. The handle that identifies a database connectio

nParameter Number. The database parameter to set. Specify the valueone 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.


See Also SqlGetParameterSqlGetParameterAllSqlSetParameter

Example Set bOk = SqlSetParameterAll ( hSql, nParameter, nNumber,strString, bNumber )

SqlSetResultSetSyntax bOk = SqlSetResultSet ( hSql, bSet )

Description Turns result set mode on or off.

Result set mode is on by default in Centura.


bSet Boolean. Turns result set mode on (TRUE) or off (FALSE).



Chapter 2

e

ge’

and the ault,

rrent t you

tup.

erived

not re

.

Example Call SqlSetResultSet ( hSqlPrimary, FALSE )

SqlStoreSyntax bOk = SqlStore ( hSql, strName, strSqlCommand )

Description Stores and names a SQLBase compiled SQL statement.

You do not need to call SqlPrepare before calling SqlStore. SqlStore compiles thSQL statement.

You can specify up to 128 bind variables. Use numeric bind variables in the SQLstatement, 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 ‘:dfAwhere dfLastName and dfAge are data fields on a form window.

Before Centura performs a SQL execute or fetch operation, it compiles the bindinto variables which is looking up the symbols and generating the code that getsvalues (for bind variables) or that fetches the values (for an into variable). By defCentura compiles:

• Bind variables at execute time

• Into variables at fetch time

You can change this default behavior by calling SqlVarSetup which saves the cuexecution context. When you execute or fetch later, Centura uses that executioncontext to resolve references to bind variables and into variables. This means thacan 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 SqlVarSe

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 dclass can specify the into variables

This function does not affect the lifetime of the bind and into variables and does guarantee that the variables will exist when you execute or fetch. You must ensuthat the variables are still valid when you use them.


strName String. The name of the stored command.

strSqlCommand String. The SQL statement to compile and store.



ust be

, if

See Also SqlDropStoredCmdSqlRetrieve

Example Set bOk = SqlStore ( hSql, strName, strSqlCommand )

VisArrayAppendSyntax 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 mdefined as dynamic arrays, must be the same data type, and cannot be multi-dimensional 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_BooleanDT_DateTimeDT_NumberDT_StringDT_Handle

Return Number: The number of total items in the target array after the append operationsuccessful, or negative if an error occurs.

Example Variables:

String: sSource[*]

String: sTarget[*]

...

Actions

Set sSource[0] = "Source #1"


Set sTarget[0] = "Target #1"

Call VisArrayAppend (sSource, sTarget, DT_String)

! sTarget contains 'Target #1'

! 'Source #1'

! 'Source #2'


Chapter 2

data

error

VisArrayCopySyntax 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. Thesource and target arrays must be defined as dynamic arrays, must be the sametype, 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:


Return Number: The number of items in the target array, if successful, or negative if an occurs.

Example Variables:

String: sSource[*]

String: sTarget[*]

...

Actions



Set sTarget[0] = "Target #1"

Call VisArrayCopy (sSource, sTarget, DT_String)

! sTarget contains 'Source #1'

! 'Source #2'


y.

ative

r

VisArrayDeleteItemSyntax nNumItems = VisArrayDeleteItem (hAry, nIndex, nDataType)

Number | String | Date/Time: hAry[*] Number: nIndexNumber: nDataType

Description Deletes an item from an array. All subsequent items will be moved up in the arraThe 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:


Return Number: The number of items in the array after the deletion, if successful, or negif an error occurs.

Example Variables

String: sString[*]

...

Actions

Call VisArrayDeleteItem (sString, 3, DT_String)

VisArrayFillDateTimeSyntax bOk = VisArrayFillDateTime (dtDateTimes, dtValue, nCount)

Date/Time: dtDateTimes[*] Date/Time: dtValueNumber: nCount

Description Fills a Date/Time array with a specified date/time value. This function is useful foinitializing 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.


Chapter 2

an

Example Variables

Date/Time: dtSample[*]

...

Actions

Call VisArrayFillDateTime (dtSample, DATETIME_Null, 5)

VisArrayFillNumberSyntax 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 array. The array cannot be a multi-dimensional array.

Parameters nNumbers Number array to fill.

nValue Value to fill in each element of array.



Example Variables

Number: nSample[*]

...

Actions

Call VisArrayFillNumber (nSample, NUMBER_Null, 5)

VisArrayFillStringSyntax 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 anarray. The array cannot be a multi-dimensional array.

Parameters sStrings String array to fill.

sValue String value to fill in each element of array.




nal

y.

Related Functions

Example Variables

String: sSample[*]

...

Actions

Call VisArrayFillString (sSample, '', 5)

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

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

VisArrayFindNumberSyntax nIndex = VisArrayFindNumber (nNumbers, nSearchFor)

Number: nNumbers[*]Number: nSearchFor

Description Locates a number within an array. The array cannot be a multi-dimensional arra

Parameters nNumbers Number array to search.


Chapter 2

array

nSearchFor Number to search for.


Variables

Number: nMyNumbers[*]

Number: nIndex

...

Actions

! Populate Array

Set nIndex = VisArrayFindNumber (nMyNumbers, 76)

If nIndex >= 0

! Item found

Else

! Item not found

VisArrayFindStringSyntax nIndex = VisArrayFindString (sStrings, sSearchFor)

String: sStrings[*]String: sSearchFor

Description Locates a string within an array. The entire specified string is compared to each item. The array cannot be a multi-dimensional array.

Parameters sStrings String array to search.

sSearchFor String to search for.


Example Variables

Number: nMyString[*]

Number: nIndex

...

Actions

! Populate Array

Set nIndex = VisArrayFindString (nMyNumbers, 'Marc')

If nIndex >= 0

! Item found

Else

! Item not found


ay.

ulti-

VisArrayInsertItemSyntax 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 arrThe inserted item is initialized to a null value. The array cannot be a multi-dimensional array.

Parameters hAry Array to insert item into.

nIndex Index number where item should be inserted.

nDataType Data type of the array. Options are:


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)

VisArraySortSyntax 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 mdimensional array.

Parameters hAry Array to sort.


Chapter 2

cified ent red.

ra

nSortOrder Flag indicating sort order.

SORT_Ascending

SORT_Descending

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

VisDebugAssertSyntax bOk = VisDebugAssert (bExpression, sDebugString)

Boolean: bExpressionString: sDebugString

Description Asserts that a condition is true. If expression is FALSE, the debug message spewill be displayed in a message box. This function is typically used in a developmenvironment to provide an indication that an internal, potentially fatal, error occur

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 Centuname 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')


ll age

of

VisDebugBeginTimeSyntax bOk = VisDebugBeginTime ()

Description Begins timing an operation. VisDebugBeginTime must be called before VisDebugSetTime or VisDebugEndTime.



Related Functions

VisDebugEndTime, VisDebugSetTime

Example Actions

Call VisDebugBeginTime ()

Call SqlPrepare (hSql, 'Select...')

Call VisDebugSetTime ('SqlPrepare')

Call SqlExecute (hSql)

Call VisDebugSetTime ('SqlExecute')

VisDebugEndTimeSyntax bOk = VisDebugEndTime (sContext, nDebugLevel) String: sContext

Number: nDebugLevel

Description Stops recording the time and displays all incremental times and the total time. Atimes are displayed in the debug application window (DBWIN.EXE) or in a messbox 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 numberdebug messages displayed.


Related Functions

VisDebugBeginTime, VisDebugSetTime

Example Actions

Call VisDebugBeginTime ()

Call SqlPrepare (hSql, 'Select...')


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)

VisDebugGetFlagsSyntax nDebugFlags = VisDebugGetFlags ()

Description Retrieves the current debug flags.


Return Number: The current debug bit flags. To test a bit flag, use the bitwise AND (&) operator.

DBF_IncrementalTimeDBF_RealTimeDBF_MessageBox

Related Functions

VisDebugSetFlags

Example Variables

Number: nDebugFlags

...

Actions

Set nDebugFlags = VisDebugGetFlags ()

If nDebugFlags & DBF_MessageBox

...

VisDebugSetFlagsSyntax 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


to be

ater

DBF_RealTimeDBF_MessageBox

bMode TRUE to set the flags, FALSE to clear the flags.


Related Functions

VisDebugGetFlags

Example Actions

Call VisDebugSetFlags (DBF_MessageBox, TRUE)

VisDebugSetLevelSyntax bOk = VisDebugSetLevel (nDebugLevel) Number: nDebugLevel

Description Sets the current debug level. The debug level allows selective debug messages displayed.

Parameters nDebugLevel Current debug level. Debug messages must be equal or grethan the current debug level to be displayed.


Example Actions

Call VisDebugSetLevel (0)

VisDebugSetTimeSyntax 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 debugapplication until a VisDebugEndTime call is made. The context string will be displayed to the left of the time.

Parameters sContext Context string describing the time interval.


Related Functions

VisDebugBeginTime, VisDebugEndTime

Example Set bOk = VisDebugSetTime (sContext)


Chapter 2

of

ows uild c.) for

VisDebugStringSyntax bOk = VisDebugString (sDebugString, nDebugLevel)

String: sDebugStringNumber: 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 numberdebug messages displayed.


Related Functions

VisDebugSetLevel

Example Pushbutton: pbOk

...

Message Actions

On SAM_Click

Call VisDebugString ('SAM_Click in pbOk', 0)

VisDosBuildFullNameSyntax sFullName = VisDosBuildFullName (sModuleName, sFileName)

String: sModuleName String: sFileName

Description Builds a file name with drive and full directory based on the location of a runningexecutable. The path of the result file is the location of the executable when Windloaded it into memory. The directory structure on disk is not used in any way to bthe path. This function may be used to locate supplemental files (i.e. INI files, etwithout a DOS PATH established to the application. This function does not checkthe 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 namemust be the base name of a loaded EXE or DLL file.


y

s the

d.

sFileName File name to concatenate with path of module name. Specifjust the base name and extension, no drive or directory. Anydrive or directory specified is ignored.

Return String: A string containing the full file name (drive, path, and file name), or a nullstring if an error occurs.

Example Variables

String: sFileName

...

Actions

Set sFileName = VisDosBuildFullName ('swinapp', 'options.ini')

Call VisFileOpen (sFileName, OF_Read)

VisDosEnumDirInfoSyntax 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 returndate/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 create

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


Chapter 2

*).

ive if

sks,

Set nCount = VisDosEnumDirInfo ('c:\\windows\\*.*', sDirs, dtDateTimes, nAttributes

If nCount >0

VisDosEnumDirsSyntax nNumDirs = VisDosEnumDirs (sDirSpec, sDirs)

String: sDirSpecReceive 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 negatan 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)

VisDosEnumDrivesSyntax nNumDrives = VisDosEnumDrives (sDrives)

Receive String: sDrives[*]

Description Retrieves all available drives into a Centura array, including floppy drives, hard diCD-ROM, network and RAM drives. To determine the type of each drive, call VisDosGetDriveType.


is

size, ng

re

Parameters sDrives Array to contain the available drive letters (A:-Z:). The colon always included.

Return Number: The number of available drives returned in the specified array.

Related Functions

VisDosEnumDirs, VisDosEnumFiles

Example Variables

Number: nCount

String: sDrives[*]

...

Actions

Set nCount = VisDosEnumDrives (sDrives)

If nCount > 0

Call VisListArrayPopulate (lbDrives)

VisDosEnumFileInfoSyntax 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'sdate/time, and attributes. If the source drive supports long file names, then the loname 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 moof the following values:

FA_Standard


Chapter 2

e if

y

of

FA_ReadOnlyFA_HiddenFA_SystemFA_Archive

Returns Number: The number of subdirectories returned in the specified array, or negativan 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

...

VisDosEnumFilesSyntax nNumFiles = VisDosEnumFiles (sFileSpec, nAttributes, sFiles)

String: sFileSpecNumber: nAttributesReceive 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 directoris specified, the current drive and/or directory is used. Use adouble backslash (\\) to represent a single backslash.

nAttributes Attributes bits to match. This parameter may be one or morethe following values:

FA_Standard

FA_ReadOnly

FA_Hidden


e

or

and a s the

t ser.

).

FA_System

FA_Archive

sFiles Array to contain the file names. Note that only file names arreturned, no drive or paths.

Return Number: The number of files returned in the specified array, or negative if an erroccurs.

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)

VisDosEnumNetConnectionsSyntax 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 share name, and may also include a path. The computer name uniquely identifienetwork server, while the share name identifies the resource. If a path is given, iuniquely identifies a directory or file. For example, \\server\data\path, \\servers\laThis 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


Chapter 2

path t

s

Example Variables

Number: nCount

String: sDevices[*]

String: sNetPaths[*]

...

Actions

Set nCount = VisDosEnumNetConnections (sDevices, sNetNames)

If nCount > 0

Call VisListArrayPopulate (lbDevices, sDevice)

VisDosEnumPathSyntax 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 thewith trailing backslashes. If a path directory contains a trailing backslash, it is noreturned.

A trailing backslash is added to each directory returned. This trailing backslash ihelpful 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 Array to contain the PATH directories.

Return Number: The number of valid directories found.

Related Functions

VisDosEnumFiles

Example Variables

String: sDirs[*]

...

Actions

Set nCount = VisDosEnumPath (sDirs)

If nCount > 0

Call VisListArrayPopulate (lbPath, sDirs)


ura that

s

d.

ura

d.

VisDosEnumsShortDirInfoSyntax nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames,

arrShortDirNames, arrDateTime, arrAttribs )

Description Retrieves all long and short subdirectory names for a given directory into a Centarray, also returns the date/time the directory was created and the attributes for 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 wacreated.

arrAttribs Handle to array of attributes for each subdirectory.

Return Returns the number of subdirectories in the arrays or negative if an error occure

Related Functions

VisDosEnumsShortDirsVisDosEnumsShortFileInfo VisDosEnumsShortFiles VisDosIsParent

Example Set nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames, arrDateTime, arrAttribs )

VisDosEnumsShortDirsSyntax nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames,

arrShortDirNames )

Description Retrieves all long and short subdirectory names for a given directory into a Centarray.

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 occure


Chapter 2

also

Related Functions

VisDosEnumsShortDirInfo VisDosEnumsShortFileInfo VisDosEnumsShortFiles VisDosIsParent

Example Set nSubDirNum = VisDosEnumsShortDirInfo (sDirName, arrLongDirNames, arrShortDirNames )

VisDosEnumsShortFileInfoSyntax 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,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)


).

VisDosEnumsShortFilesSyntax nSubFileNum = VisDosEnumsShortFiles (sDirName, nAttribBits,

arrLongFileNames, arrShortFileNames )

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

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 )

VisDosExistSyntax bOk = VisDosExist (sFileSpec) String: sFileSpec

Description Tests for existence of a drive, directory, or file. If a directory is tested, any trailingbackslash is ignored. If wildcards are used, files and directories are searched.

Parameters sFileSpec Drive, directory, or file to test. It may contain a drive letter, directory, file name, full path or wildcard characters (? and *

Return Boolean: TRUE if sFileSpec exists and FALSE if it does not.

Example If VisDosExist ('c:')

...

If VisDosExist ('c:\\dos')

...

If VisDosExist ('c:\\dos\\')

...

If VisDosExist ('c:\\dos\\command.com')

...

If VisDosExist ('c:\\dos\\*.exe')


Chapter 2

ng iling

th

VisDosGetCurDirSyntax sDir = VisDosGetCurDir (sDrive)String: sDrive

Description Returns the current directory of a specified drive.

Parameters sDrive Drive letter (A:-Z:) to retrieve the current directory for.

Return String: The current directory of the drive specified. If the drive is invalid, a null striis returned. The returned directory always contains the drive letter, path and a trabackslash.

Example Variables

String: sCurDir

...

Actions

Set sCurDir = VisDosGetCurDir (VisDosGetCurDrive())

If VisDosEnumFiles (sCurDir || '*.*',FA_Standard, sFiles)

VisListArrayPopulate (lbFiles, sFiles)

VisDosGetDriveSizeSyntax nErrCode = VisDosGetDriveSize (sDrive, nTotalSpace, nFreeSpace)

String: sDriveReceive Number: nTotalSpaceReceive Number: nFreeSpace

Description Returns total space and available space on a drive.

Parameters sDrive Drive letter to retrieve space information for, may include boa 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


th

s.

Call VisDosGetDriveSize ('c:', nTotalSpace, nAvailableSpace)

VisDosGetDriveTypeSyntax nTypeFlags = VisDosGetDriveType (sDrive)

String: sDrive

Description Gets the type of drive specified.

Parameters sDrive Drive letter to retrieve space information for, may include boa drive letter and colon.

Return Number A flag indicating the drive type, or negative if an error occur

DRIVE_FloppyDRIVE_FixedDRIVE_NetworkDRIVE_CDROMDRIVE_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


Chapter 2

re

ll

VisDosGetEnvStringSyntax sEnvString = VisDosGetEnvString (sKeyName)

String: sKeyName

Description Returns an environment string based on a keyword. The keyword is the text befothe = sign in the environment. For example, PATH = C:\DOS.

Parameters sKeyName String to search for.

Return String: The environment variable contents. If the keyword cannot be found, a nustring is returned.

Example Variables

String: sTempDir

...

Actions

Set sTempDir = VisDosGetEnvString ('TEMP')

VisDosGetFlagsSyntax nFlags = VisDosGetFlags ()

Description Returns the state of DOS flags.


Return Number Any of the following bit flags. To test a bit value, use the bitwise AND (&) operator.

Related FunctionsVisDosSetFlags

Example Variables

Number: nFlags

...

Actions

Set nFlags = VisDosGetFlags ()

If nFlags & DOS_VerifyFlag

...

If nFlags & DOS_BreakFlag


of a name ce. If

tion

VisDosGetNetNameSyntax sNetName = VisDosGetNetName (sDevice)

String: sDevice

Description Retrieves the network name for the specified device. The network name consistscomputer name and a share name, and may also include a path. The computer uniquely identifies the network server, while the share name identifies the resoura path is given, it uniquely identifies a directory or file. For example, \\server\data\path, \\servers\laser. This follows the standard DOS naming convenfor network devices.

Parameters sDevice Pointer to device name (A:-Z:, LPT1:-LPT3:).

Return String: The network name, if successful, or a null string if an error occurs.

Related FunctionsVisDosEnumNetConnections, VisDosNetConnect, VisDosNetDisconnect

Example Variables

String: sNetName

...

Actions

Set sNetName = VisDosGetNetName ('f:')

VisDosGetVersionSyntax 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 ()


Chapter 2

VisDosGetVolumeLabelSyntax sLabel = VisDosGetVolumeLabel (sDrive)

String: sDrive

Description Returns the volume label of a specified drive.

Parameters sDrive Drive to retrieve volume label for.

Return String: The volume label of the specified drive, or negative if an error occurs.

Related Functions

VisDosSetVolumeLabel

Example Variables

String: sLabel

...

Actions

Set sLabel = VisDosGetVolumeLabel ('c:')

VisDosIsParentSyntax bOk = VisDosIsParent (sDirSpec)

String: sDirSpec

Description Return indicator if directory contains subdirectories.

Parameters sDirSpec Directory to test.

Return Boolean. TRUE if directory contains subdirectories, FALSE if not.

Related Functions

VisDosEnumsShortDirInfo VisDosEnumsShortDirs VisDosEnumsShortFileInfo VisDosEnumsShortFiles

Example Set bOk = VisDosIsParent (sDirSpec)


ull

VisDosMakeAllDirSyntax 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 Directory name to create, may contain a drive letter and/or fpath. 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.

Returns Number: VTERR_Ok if successful, or negative if an error occurs.

Example Actions

If VisDosMakeAllDir ('c:\\stuff\\junk\\newone') != VTERR_Ok

Call SalMessageBox ('Cannot create directory', 'Error', MB_Ok)

VisDosMakePathSyntax sFileSpec = VisDosMakePath (sDrive, sDir, sBase, sExt)

String: sDriveString: sDirString: sBaseString: 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')


Chapter 2

and a s the

t ser.

VisDosNetConnectSyntax nErrCode = VisDosNetConnect (sDevice, sNetName, sPassword)

String: sDeviceString: sNetNameString: sPassword

Description Connects to a network device. The network name consists of a computer name share name, and may also include a path. The computer name uniquely identifienetwork server, while the share name identifies the resource. If a path is given, iuniquely identifies a directory or file. For example, \\server\data\path, \\servers\laThis 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).


Related Functions

VisDosEnumNetConnections, VisDosNetDisconnect

Example Actions

If VisDosNetConnect ('f:','\\\\server\\data', 'cubswin') != VTERR_Ok

VisDosNetDisconnectSyntax nErrCode = VisDosNetDisconnect (sDevice, bForce)

String: sDeviceBoolean: 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.


Related Functions

VisDosNetConnect

Example Actions

Call VisDosNetDisconnect ('f:', TRUE)


(|)

VisDosSetFlagsSyntax nErrCode = VisDosSetFlags (nFlags, bState)

Number: nFlagsBoolean: 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)

VisDosSetVolumeLabelSyntax nErrCode = VisDosSetVolumeLabel (sDrive, sLabel)

String: sDriveString: 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


Related Functions

VisDosGetVolumeLabel

Example If VisDosSetVolumeLabel ('c:', 'my_disk') != VTERR_Ok


Chapter 2

:\dos

VisDosSplitPathSyntax Void VisDosSplitPath (sFileSpec, sDrive, sDir, sBase, sExt)

String: sFileSpecReceive String: sDriveReceive String: sDirReceive String: sBaseReceive 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, cwill 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'


. A r disk

ource nto

d.

VisErrorRecoverySyntax 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 occurredrecoverable error is caused by a temporary lack of resources, such as memory ospace.

Parameters sCaption Caption of error recovery dialog.

Return Number: An action code depending on whether the user choose Retry or Abort pushbuttons:

Example If VisErrorRecovery ('Error') = ACTION_Abort

Call SalQuit()

VisFileAppendSyntax nErrCode = VisFileAppend (sSourceFile, sTargetFile)

String: sSourceFileString: sTargetFile

Description Appends one or more files to another. Wildcard characters are supported in the sfile name. If wildcard character(s) are used, all matching files will be appended othe target file.

Parameters sSourceFile Source file specification to append.

sTargetFile Target file name. If this file does not exist, an error is returneFile 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)


Chapter 2

and he

at

es

VisFileCloseSyntax 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 Handle to file returned from VisFileOpen.


Related Functions

VisFileOpen

Example Set nErrCode = VisFileClose (hFile)

VisFileCopySyntax nErrCode = VisFileCopy (sSourceFile, sTargetFile)


Description Copies one or more files. Wildcard characters are supported in both the source target file names. If wildcards are used in the target, they must also be used in tsame manner in the source. All attributes and date/times are preserved from thesource 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 formor 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 namare 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')


d. t

e nd re

d

tion

at

VisFileCreateTempSyntax sTempFileName = VisFileCreateTemp (sPrefix)

String: sPrefix

Description Creates a temporary file. If successful, this function creates the file name returneTemporary files are created in the directory pointed to by the TEMP environmenvariable. If no TEMP environment variable is set, the file is created in the root directory of the current drive.

Parameters sPrefix The prefix is used to build the file name. A temporary file namcontains a tilde character (~), the prefix, a random number athe extension TMP. Only the first 3 characters of the prefix aused, the rest are ignored.

Return String: A string containing drive, directory, and file name of the temporary file.

Example Set sFileName = VisFileCreateTemp ('Vis')

Set hFile = VisFileOpen (sFileName, OF_Write)

VisFileDeleteSyntax nErrCode = VisFileDelete (sFileSpec)

String: sFileSpec

Description Deletes one or more files.

Parameters sFileSpec Directory and file specification to delete, may include wildcarcharacters. File name specified may be in long format or in DOS 8.3 format.

Return Number: The number of files deleted, or negative if an error occurs.

Example Call VisFileDelete ('c:\\windows\\temp\\*.*')

VisFileExpandSyntax nErrCode = VisFileExpand (sSourceFile, 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 destinafile. 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 formor in DOS 8.3 format.


Chapter 2

s.

nt

.

sTargetFile Target file specification. May also include wildcard characterFile name specified may be in long format or in DOS 8.3 format.

Return Number: The number of files expanded, or negative if an error occurs.

Related Functions

VisFileAppend, VisFileCopy, VisFileRename

Example Call VisFileExpand ('oldfile.tx_', 'newfile.txt')

VisFileFindSyntax 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 variableYou can also specify . or .. to search the parent or root directory of the curresubdirectory.

Parameters sFileName File name to search for. Cannot contain wildcard charactersFile name specified may be in long format or in DOS 8.3 format.

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

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


st a

ng

Return Number: The attribute bits of the file specified, or negative if an error occurs. To tebit value, use the bitwise AND (&) operator.

Related Functions

VisFileGetSize, VisFileSetAttribute

Example Set nAttribute = VisFileGetAttribute ('c:\\autoexec.bat')

If nAttribute & FA_ReadOnly

...

VisFileGetSizeSyntax nFileSize = VisFileGetSize (sFileName)

String: sFileName

Description Gets the size of the specified file in bytes.

Parameters sFileName File name to get size of. File name specified may be in longformat or in DOS 8.3 format.

Return Number: The file size, or negative if an error occurs.

Related Functions

VisFileGetAttribute

Example Set nFileSize = VisFileGetSize ('c:\\autoexec.bat')

VisFileGetTypeSyntax nFileType = VisFileGetType (sFileName)

String: sFileName

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

Parameters sFileName File name to obtain type of. File name specified may be in loformat or in DOS 8.3 format.

Return Number: The file type, or negative if an error occurs. File types are mutually exclusive and valid values are:

Related Functions

VisFileGetAttribute, VisFileGetSize

Example Set nType = VisFileGetType ('c:\\winword\\letter.doc')

If nType = FILETYPE_Document

...


Chapter 2

.

at n

VisFileOpenSyntax nErrCode = VisFileOpen (hFile, sFileName, nFlags)

Receive File Handle: hFileString: sFileNameNumber: 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 formor in DOS 8.3 format. If only a file name is given, this functiosearches the following directories:1) Current directory2) Windows or Windows System directories3) Directory containing currently running executable4) 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. Optionsinclude:

OF_AppendOF_BinaryOF_CancelOF_CreateOF_DeleteOF_ExistOF_ParseOF_PromptOF_ReadOF_ReadWriteOF_Share_Deny_CompatOF_Share_Deny_ExlcusiveOF_Share_Deny_NoneOF_Share_Deny_ReadOF_Share_Deny_WriteOF_TextOF_VerifyOF_Write



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)

VisFileReadSyntax nBytesRead = VisFileRead (hFile, sBuffer, nSize)

File Handle: hFileReceive String: sBufferNumber: 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.


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


Chapter 2

of oved

e and es

y

Set nNumRead = VisFileRead (hFile, sData, 512)

...

If nNumRead < 512

Break

Call VisFileClose (hFile)

VisFileReadStringSyntax nErrCode = VisFileReadString (hFile, sLine)

File Handle: hFileReceive String: sLine

Description Reads a text line from a text file into a string. The text file must indicate the end each line by carriage return/line feed characters. The CR/LF characters are remfrom the string.


sLine Text line read from the file. Pre-allocation of the sLine with SalStrSetBufferLength is not necessary.


Related Functions

VisFileOpen, VisFileRead, VisFileWrite, VisFileWriteString

Example Set nErrCode = VisFileReadString (hFile, sLine)

VisFileRenameSyntax nErrCode = VisFileRename (sOldFileSpec, sNewFileSpec)

String: sOldFileSpecString: sNewFileSpec

Description Renames one or more files. Wildcard characters are supported in both the sourctarget file names. If the source and target directories are different but the file namare the same, the files are moved to the target directory specified.

Parameters sOldFileSpec Source file specification to rename. File name specified mabe 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')

VisFileSeekSyntax nErrCode = VisFileSeek (hFile, nOffset, nOrigin)

File Handle: hFileNumber: nOffsetNumber: nOrigin

Description Seeks to a specified offset within a file.


nOffset Specifies the number of bytes the offset is to be moved fromthe 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)

...


VisFileSetAttributeSyntax nErrCode = VisFileSetAttribute (sFileName, nAttribute, bState)

String: sFileNameNumber: nAttributeBoolean: bState

Description Sets the attribute bits for one or more files.


Chapter 2

e g

e n

Parameters sFileName Directory and file specification to set, may include wildcard characters. If wildcard characters are used, the attributes arset for each matching file. File name specified may be in lonformat or in DOS 8.3 format.

nAttribute Attribute bits to set or clear:

FA_StandardFA_ReadOnlyFA_HiddenFA_SystemFA_Archive

bState TRUE to set attributes, FALSE to clear.

Return Number: The number of files effected, or negative if an error occurs.

Related Functions

VisFileGetAttribute, VisFileSetDateTime

Example Call VisFileSetAttribute ('c:\\myapp\\*.exe', FA_ReadOnly, TRUE)

VisFileSetDateTimeSyntax nErrCode = VisFileSetDateTime (sFileName, dtDateTime)

String: sFileNameDate/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 timare set for each matching file. File name specified may be ilong 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)


is

of

VisFileTellSyntax nOffset = VisFileTell (hFile)

File Handle: hFile

Description Returns the current file offset.


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)

VisFileWriteSyntax nErrCode = VisFileWrite (hFile, sBuffer, nSize)

File Handle: hFileString: sBufferNumber: nSize

Description Writes a block of data to a file.The maximum number of characters you can write65,535.


sBuffer String containing data to write.

nSize Number of bytes to write. Must be less than or equal to sizesBuffer.

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



Chapter 2

re it's

.)

VisFileWriteStringSyntax nErrCode = VisFileWriteString (hFile, sLine)

File Handle: hFileString: sLine

Description Writes a string to a file. CR/LF characters are added to the end of the string befowritten to the file.

Parameters hFile Handle to file context structure returned from VisFileOpen.

sLine String to write to the file.


Related Functions

VisFileOpen, VisFileWrite

Example While nIndex <= nMax

Call VisFileWriteString (hFile, sLines[nIndex])

Set nIndex = nIndex + 1


VisFontEnumSyntax nNumFonts = VisFontEnum (sGetFlag, sFontNames, nFontTypes)

String: sGetFlagReceive String: sFontNames[*]Receive Number: nFontTypes[*]

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

Parameters sGetFlag One or more flags indicating type of fonts to retrieve. To combine bit values, use the bitwise OR (|) operator.

FONT_GetScreenFONT_GetPrinter

sFontNames Names of each available font (Arial, Times New Roman, etc

nFontTypes Bit flags indicating types of each available font. To combinebit 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.


s,

Related Functions

VisFontGet

Example Set nNumFonts = VisFontEnum (FONT_GetScreen, sFontNames, nFontTypes)

Set nIndex = 0

While nIndex < nNumfonts

If nFontTypes(nIndex) & FONTTYPE_TrueType

VisFontFreeSyntax bOk = VisFontFree (hFont)

String: hFont

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

Parameters hFont Handle of font to free.


Related Functions

VisFontEnum, VisFontLoad

Example Set bOk = VisFontFree (hFont)

VisFontGetSyntax bOk = VisFontGet (hFont, sFaceName, nPointSize, nFontEnhancement)

Number: hFontReceive String: sFaceNameReceive Number: nPointSizeReceive 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 valueuse the bitwise OR (|) operator.

FONT_EnhNormalFONT_EnhItalic


Chapter 2

s,

FONT_EnhUnderlineFONT_EnhBoldFONT_EnhStrikeout


Related Functions

VisFontEnum, VisFontLoad


Set nIndex = SalListQuerySelection (hWndItem)

If nIndex != LB_Err

Call VisFontGet (hFont, sFontName, nPointSize, nFontFlags)

If nFontFlags & FONT_EnhBold

...

VisFontLoadSyntax hFont = VisFontLoad (sFontName, nFontSize, nFontEnhancement)

String: sFontNameNumber: nFontSizeNumber: 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 valueuse the bitwise OR (|) operator.

FONT_EnhNormalFONT_EnhItalicFONT_EnhUnderlineFONT_EnhBoldFONT_EnhStrikeout

Return Number: The handle of the font if successful, NULL if an error occurs.

Related Functions

VisFontEnum, VisFontFree


Set hFont = VisFontLoad ('Arial', 10, FONT_EnhBold)


down,

e,

of

VisGetCopyrightSyntax sCopyrightMsg = VisGetCopyright ()

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


Return String: The copyright string for the Vis Library.

Related Functions

VisGetVersion


Set dfCopyright = VisGetCopyright ()

VisGetKeyStateSyntax nState = VisGetKeyState (nVirtualKey)

Number: nVirtualKey

Description Retrieves the state of a specified key. The state specifies whether the key is up, or toggled.

Parameters nVirtualKey Virtual key code to retrieve the state. See the Appendix for acomplete list of virtual key codes.

Return Number: The bit values indicating the state of the key specified. To test a bit valuuse the bitwise AND (&) operator.


Set nState = VisGetKeyState (VK_Control)

If nState & KS_Down

...

VisGetSystemMetricsSyntax 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 versionWindows 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:


Chapter 2

SM_XBorderSM_YMinSM_YBorderSM_XMinTrackSM_YCaptionSM_YMinTrackSM_XCursorSM_XScreenSM_YCursorSM_YScreenSM_XDoubleClickSM_XHScrollSM_YDoubleClickSM_YHScrollSM_XDlgFrameSM_XVScrollSM_YDlgFrameSM_YVScrollSM_XFrameSM_XSizeSM_YFrameSM_YSizeSM_XFullScreenSM_XHThumbSM_YFullScreenSM_YVThumbSM_XIconSM_DBCSEnabledSM_YIconSM_DebugSM_XIconSpacingSM_MenuDropAlignmentSM_YIconSpacingSM_MousePresentSM_KanjiWindowSM_PenWindowsSM_MenuSM_SwapButtonSM_XMin

Return Number: The specified system metric.

Example Actions

Set nScreenWidth = VisGetSystemMetrics (SM_XScreen)

VisGetVersionSyntax sVisVersion = VisGetVersion ()

Description Gets the Vis Library version number.


Return String: The version number of the Vis Library.

Example Actions

Set dfVersion = 'Version ' || VisGetVersion ()

VisGetWinFlagsSyntax nFlags = VisGetWinFlags ()

Description Retrieves the current Windows system and memory configuration.

Parameters None.


with other

r

Return Number: A series of bits indicating the current system configuration. To test a bitvalue, use the bitwise AND (&) operator.

WF_80x87WF_CPU286WF_CPU386WF_CPU486WF_EnhancedWF_PagingWF_PModeWF_StandardWF_WLO

Example Actions

Set nWinFlags = VisGetWinFlags ()

If nWinFlags & WF_CPU486

VisGetWinVersionSyntax nWinVersion = VisGetWinVersion ()

Description Returns the Windows version number.


Return NumberThe major and minor (3.10) Windows version number.

Example Actions

Set nWinVersion = VisGetWinVersion ()

VisListAddValueSyntax nIndex = VisListAddValue (hWndList, sText, nValue)

Window Handle: hWndListString: sTextNumber: nValue

Description Adds an item to a sorted list box or combo box and associates the specified valuethe item. The value can be a record identifier for a database, a file offset, or any 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 onegative integer value.


Chapter 2

item

n

tring the

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

VisListArrayPopulateSyntax nNumItems = VisListArrayPopulate (hWndList, sText)

Window Handle: hWndListString: sText[*]

Description Populates a list box from a string array. Each item in the string is inserted as an 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 aerror occurs.

Related Functions

VisListArrayPopulateValue

Example Set nCount = VisDosEnumDirs ('c:\\windows\\*.*', sDirs)

If nCount > 0

Call VisListArrayPopulate (lbDirs, sDirs)

VisListArrayPopulateValueSyntax nNumItems = VisListArrayPopulateValue (hWndList, sText, nValues)

Window Handle: hWndListString: sText[*]Number: nValues[*]

Description Populates a list box from a string array and an array of values. Each item in the sis inserted as an item in the list box. The number of items in the string array andnumber 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.


n

is a

d.

a mbo

curs.

Return Number: The number of items added to the list box or combo box, or LB_Err if aerror occurs.

Related Functions

VisListArrayPopulate

Example Set nCount = VisDosEnumFileInfo ('c:\\windows\\*.*', 0, sFiles, nSizes, dtDateTimes, nAttributes)

If nCount , 0

Call VisListArrayPopulateValue (lbFiles, sFiles, nAttributes)

VisListClearSelectionSyntax bOk = VisListClearSelection (hWndList)

Window Handle: hWndList

Description Unselects all selected items in a list box or combo box. If the window handle is amultiple selection list box, all selected items are unselected. If the window handlesingle selection list box or a combo box, the currently selected item is unselecteCombo boxes do not allow multiple selections.

Parameters hWndList Handle to list box or combo box to clear selection from.

Returns Boolean: TRUE if successful, or FALSE if an error occurs.

Related Functions

VisListDeleteSelected

Example Actions

Call VisListClearSelection (hWndItem)

VisListDeleteSelectedSyntax nNumDeleted = VisListDeleteSelected (hWndList)


Description Deletes all selected items from a list box or combo box. If the window handle is amultiple selection list box, all selected items are deleted. If the window handle issingle selection list box or a combo box, the currently selected item is deleted. Coboxes do not allow multiple selections.

Parameters hWndList Window handle of list box or combo box to delete selected items.

Return Number: nNumDeleted is the number of items deleted, or negative if an error oc


Chapter 2

The

ck -1.

op

Related Functions

VisListClearSelection

Example Pushbutton: pbDelete

...

Message Actions

On SAM_Click

Call VisListDeleteSelected (lbSample)

VisListFindStringSyntax nIndex = VisListFindString (hWndList, nStartIndex, sText)

Window Handle: hWndList,Number: nStartIndexString:sText

Description Finds the first string that matches the specified string in a list box or combo box.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 bato the item specified. To search from the beginning, specify

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

VisListFindValueSyntax nIndex = VisListFindValue (hWndList, nStartIndex, nValue)


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 tof the list. Searching begins at nStartIndex +1.


be

e the

list turn

nValue Value to search for.

Return Number: The index containing the value specified, or LB_Err if the value cannot found.

Example Actions

Set nIndex = SalListQuerySelection (hWndItem)

If nIndex != LB_Err

Set nIndexFound = VisListFindValue (lbNames, nIndex, 100)

VisListGetDropdownStateSyntax bState = VisListGetDropdownState (hWndList)

Window Handle: hWndList,

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

Parameters hWndList Window handle of combo box.

Return Boolean: TRUE if visible, FALSE if not visible

Example Actions

If VisListGetDropdownState (hWndItem)

...

VisListGetFocusIndexSyntax nIndex = VisListGetFocusIndex (hWndList)


Description Gets the index of the item which has the focus rectangle or the last item to receivfocus frame in a multiple-selection list box. This function will retrieve the selecteditem on a combo box.


Return Number: The index of the item that has the focus rectangle, if a multiple selectionbox. If the function is operating on a single-selection list box or combo box, the revalue is the index of the item that is selected, if any.

Related Functions

VisListSetFocusIndex


Chapter 2

t

ied et, or Use

Example Actions

Set nIndex = VisListGetFocusIndex (hWndItem)

If nIndex != LB_Err

VisListGetVisibleRangeSyntax nNumVisible = VisListGetVisibleRange (hWndList, nTop, nBottom)

Window Handle: hWndListReceive Number: nTopReceive Number: nBottom

Description Retrieves the indexes of both the first visible item and the last visible item in a lisbox. 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

VisListInsertValueSyntax nIndex = VisListInsertValue (hWndList, nIndex, sText, nValue)

Window Handle: hWndListNumber: nIndexString: sTextNumber: nValue

Description Inserts an item into an unsorted list box or combo box and associates the specifvalue with the item. The value can be a record identifier for a database, a file offsany other integer value that the application can use to uniquely identify the item.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).


or

it the

sText Text of item to insert.

nValue Value to associate with the inserted item. May be a positive negative integer value.

Return 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

VisListIsMultiSelectSyntax bOk = VisListIsMultiSelect (hWndList)


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

Parameters hWndList List box to test.

Returns Boolean: TRUE if multi selection is enabled for the list box, FALSE if not.

Example Actions

If VisListIsMultiSelect (hWndList)

...

VisListLoadOutlineSyntax nErrCode = VisListLoadOutline (hWndList, sOutlineBlob)

Window Handle: hWndListString: 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 was when the outline was saved, including selected items and outline position inlist box or combo box.


sOutlineBlob String containing outline to load.



Chapter 2

re ince ent

all

Related Functions

VisListSaveOutline

Example On Sam_Click

Call VisListLoadOutline (twOutline, sOutline)

VisListLoadOutlineFileSyntax nErrCode = VisListLoadOutlineFile (hWndList, sOutlineFileName,

hPicParentNormal, hPicParentSelect, hPicChildNormal, hPicChildSelect)Window Handle: hWndListString: sOutlineFileNameNumber: hPicParentNormalNumber: hPicParentSelectNumber: hPicChildNormalNumber: hPicChildSelect

Description Loads an outline from a tab indented ASCII file. The parent/child relationships aderived from the order of the text lines and the indentation of the text in the file. Sthe file contains no picture information, handles to the pictures to use for the parand lowest level children must be passed in.


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. CVisPicLoad to create a picture handle.

hPicChildSelect Picture to use when lowest level child item is selected. hPicChildNormal and hPicChildSelect may be the same.


Example Set nErrCode = VisListLoadOutlineFile (hWndList, sOutlineFileName, hPicParentNormal, hPicParentSelect, hPicChildNormal, hPicChildSelect)


bject) of a

ox.

VisListSaveOutlineSyntax nErrCode = VisListSaveOutline (hWndList, sOutlineBlob)

Window Handle: hWndListString: sOutlineBlob

Description Compresses and saves a list box or combo box outline into a blob (binary large oin memory. The blob data may then be inserted into a LONG VARCHAR column database.


sOutlineBlob String to contain the ouline.


Related Functions

VisListLoadOutline

Example On SAM_Destroy

If VisListSaveOutline (twOutline, sOutline)

Call SqlPrepare (hSql, 'INSERT INTO TABLE’(out_id, outline)values (:nOutID, :sOutline')

VisListScrollSyntax nErrCode = VisListScroll (hWndList, nIndex)

Window Handle: hWndListNumber: nIndex

Description Scrolls an item into view. This function does not force the item to the top of a list bThe 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)


Chapter 2

ted

list

VisListSetDropdownStateSyntax bOk = VisListSetDropDownState (hWndList, bState)

Window Handle: hWndListBoolean: bState

Description Shows or hides the list box portion of a combo box. This function does not operaon list boxes.

Parameters hWndList Window handle of combo box.

bState TRUE to show, FALSE to hide.


Related Functions

VisListGetDropDownState

Example Actions

Call VisListSetDropDownState (hWndItem, TRUE)

VisListSetFocusIndexSyntax nErrCode = VisListSetFocusIndex (hWndList, nIndex)


Description Sets the focus rectangle to the item at the specified index in a multiple-selectionbox. 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)


h is fied ll to

for

top

ed.

nu. t

VisListSetScrollWidthSyntax nErrCode = VisListSetScrollWidth (hWndList, nIndex)


Description Sets the width by which a list box can be scrolled horizontally. The horizontal widtdetermined by the string length of the longest item. If the width of the item speciis not longer that the current width, the current width is not adjusted. The first caVisListSetScrollWidth displays a horizontal scroll bar in the list box. This functiondoes 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 the largest text length.

Return Number: Zero if successful, or negative if an error occurs.

Example Actions

Call VisListSetScrollWidth (lbText, -1)

VisMenuGetPopupHandleSyntax hMenu = VisMenuGetPopupHandle (hMenu, nPos)

Number: hMenuNumber: nPos

Description Retrieves the menu handle of a pop-up menu. A pop-up menu appears below a 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 retriev

nPos Zero-based position in the specified menu of the pop-up meMenu separators are included in the position count. It cannobe 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 nomenu.

Related Functions

VisMenuGetSystemHandle


Chapter 2

the

as

em

Example Set hMenu = VisMenuGetHandle (hUnd)

If hMenu

Set hSubMenu = VisMenuGetPopupHandle (hMenu, 2)

VisMenuGetSystemHandleSyntax hMenu = VisMenuGetSystemHandle (hWnd)

Window Handle: hWnd

Description Retrieves the system menu handle of a window. The system menu is located in upper left corner of a window.

Parameters hWnd Window handle to retrieve menu.

Return Number: The system menu handle of window specified, or NULL if the window hno menu.

Related Functions

VisMenuGetPopupHandle

Example Variables

Number: hMenu

...

Actions

Set hMenu = VisMenuGetSystemHandle (hWnd)

VisMenuGetTextSyntax sMenuText = VisMenuGetText (hWnd, hMenu, nPos)

Window Handle: hWndNumber: hMenuNumber: nPos

Description Retrieves the text of a menu item. The text of any menu item, whether defined inCentura 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 itadded using VisMenuInsert, which always returns a negativemenu ID value.


vel or of a he

of

b ll

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)

VisMenuInsertSyntax nMenuID = VisMenuInsert (hWnd, hMenu, nPos, sMenuText, nFlags)

Number: hWndNumber: hMenuNumber: nPosString: sMenuTextNumber: nFlags

Description Inserts a menu item into a menu. Menu items can be inserted into system, top-lepop-up menus. Prior to Centura 4.1, items could not be inserted into the middle Centura menu. They could only be inserted at the end of a Centura menu or in tmiddle of items previously inserted with a VisMenuInsert call.

Parameters hWnd Handle to window containing the menu. This window will benotified 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 the menu.

sMenuText Text of item to insert. Specify \t to insert a tab in the text. A tawill separate the menu text from the accelerator indicator. Atext 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.


Chapter 2

nu

tura nly

erted

of

d

ab ll

MF_Checked

MF_Disabled

MF_Separator

Returns Number: The ID value of the menu item inserted, or NULL if an error occurs. MeIDs are always negative. Each inserted item is assigned a unique ID.

Related Functions

VisMenuInsertFont, VisMenuInsertPicture


Set hMenu = VisMenuGetHandle (hWndForm)


Call VisMenuInsert (hWndForm, hMenu, -1, '', MF_Separator)

Set nMenuID = VisMenuInsert (hWndForm, hMenu, -1, 'Sample\tAlt-S', 0)

VisMenuInsertFontSyntax nMenuID = VisMenuInsertFont (hWnd, hMenu, nPos, hFont sMenuText)

Number: hWndNumber: hMenuNumber: nPosNumber: hFontString: sMenuText

Description Inserts a menu item into a menu and displays it in the specified font. Prior to Cen4.1, items could not be inserted into the middle of a Centura menu. They could obe inserted at the end of a Centura menu or in the middle of items previously inswith a VisMenuInsert call.




hFont Handle to font to use for menu item display. Call VisFontLoato create a font handle.

sMenuText Text of item to insert. Specify \t to insert a tab in the text. A twill separate the menu text from the accelerator indicator. A


nu

,

o y

of

text after the tab will be shown along the right edge of the menu.


Related Functions

VisMenuInsert, VisMenuInsertPicture





Call VisMenuInsert (hWndForm, hMenu, -1, '', MF_Separator)

Set nMenuID = VisMenuInsertFont (hWndForm, hMenu, -1, hFont, 'Sample\tAlt-S')

VisMenuInsertPictureSyntax nMenuID = VisMenuInsertPicture (hWnd, hMenu, nPos, hPicNormal, hPicSelect

sMenuText)Number: hWndNumber: hMenuNumber: nPosNumber: hPicNormalNumber: hPicSelectString: sMenuText

Description Inserts a menu item into a menu and displays the specified picture with it. Prior tCentura 4.1, items could not be inserted into the middle of a Centura menu. Thecould only be inserted at the end of a Centura menu or in the middle of items previously inserted with a VisMenuInsert call.




hPicNormal Handle of picture to display in menu item when item is not selected. Call VisPicLoad to create a picture handle.


Chapter 2

nu

r ura

em

em

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 beshown along the right edge of the menu.


Related Functions

VisMenuInsert, VisMenuInsertFont

Example Call VisMenuInsert (hWndForm, hMenu, -1, '', MF_Separator)

Set nMenuID = VisMenuInsertPicture (hWndForm, hMenu, -1, hPic, 'Sample\tAlt-S')

VisMenuIsCheckedSyntax bOk = VisMenuIsChecked (hMenu, 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 oCentura menu items. It must be called in the Checked When section of the Centoutline 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 systmenu. It cannot be a top-level menu.

nPos Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu itadded using VisMenuInsert, which always returns a negativemenu ID value.

Return Boolean: TRUE if successful, FALSE if unsuccessful.

Related Functions

VisMenuIsEnabled, VisMenuUncheck


r ra

em

Example Menu Item: Sample Menu

...

Menu Settings

Enabled when:

Checked when: VisMenuIsChecked (VisMenuGetPopupHandle (VisMenuGetHandle(hWndForm), 3), 4)

Menu Actions

VisMenuIsEnabledSyntax bOk = VisMenuIsEnabled (hMenu, 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 oCentura menu items. It must be called in the Enabled When section of the Centuoutline in order to properly display the enable status of a Centura menu item.

Parameters hMenu Menu handle of menu to test.

nPos Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu itadded using VisMenuInsert, which always returns a negative menu ID value.

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


Chapter 2

em e

d

ab ll

.

VisMenuSetFontSyntax bOk = VisMenuSetFont (hWnd, hMenu, nPos, hFont sMenuText)

Number: hWndNumber: hMenuNumber: nPosNumber: hFontString: sMenuText

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


hMenu Handle to menu containing item to display picture with.

nPos Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu itadded using VisMenuInsert, which always returns a negativmenu ID value.

hFont Handle to font to use for menu item display. Call VisFontLoato create a font handle.

sMenuText Text of item to insert. Specify \t to insert a tab in the text. A twill separate the menu text from the accelerator indicator. Atext 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





Set nMenuID = VisMenuSetFont (hWndForm, hMenu, -1, hFont, 'Sample\tAlt-S')


r

em

b ll

e

VisMenuSetPictureSyntax bOk = VisMenuSetPicture (hWnd, hMenu, nPos, hPicNormal, hPicSelect,

sMenuText)Number: hWndNumber: hMenuNumber: nPosNumber: hPicNormalNumber: hPicSelectString: sMenuText

Description Displays a picture in a menu item. VisMenuSetPicture operates on Centura menus omenus inserted with the Vis Library.


hMenu Handle to menu containing item to display picture with.


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 tawill separate the menu text from the accelerator indicator. Atext 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 bshown. If a picture and text are specified, the text is always shown to the right of the picture.


Related Functions

VisMenuSetFont, VisMenuSetText


Chapter 2

r.

em e

ert

g


Set hPic = VisPicLoad (PIC_LoadResource | PIC_FormatBitmap, 'Vis.dll', 'bkopen')



Set nMenuID = VisMenuSetPicture (hWndForm, hMenu, -1,hPic, 'Sample\tAlt-S')

VisMenuSetTextSyntax bOk = VisMenuSetText (hWnd, hMenu, nPos, sText)

Window Handle: hWndNumber: hMenuNumber: nPosString: sText

Description Changes the text of a menu item. VisMenuSetText operates on Centura menus or menus inserted with the Vis Library.


hMenu Handle of menu that contains the menu item to reset text fo

nPos Zero-based position within the menu of the item. Menu positions include separators. If negative, identifies a menu itadded using VisMenuInsert, which always returns a negativmenu ID value.

sText New text to use for the specified menu item. Specify \t to insa tab in the text. A tab will separate the menu text from the accelerator indicator. All text after the tab will be shown alonthe right edge of the menu.


Related Functions

VisMenuSetFont, VisMenuSetPicture

Example Set hMenu = VisMenuGetHandle (hWnd)


Call VisMenuSetText (hWndForm, hMenu, 5, 'New Item')


n ve f

em

not

VisMenuUncheckSyntax bOk = VisMenuUncheck (hMenu, nPos)


Description Unchecks a menu item. VisMenuUncheck is intended for menu items that have beeinserted using the Vis Library. It also works for Centura menu items but will remothe check mark only if VisMenuIsChecked is called in the When Checked section othe 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.


Returns Boolean: TRUE if successful, or FALSE if unsuccessful.

Related Functions

VisMenuIsChecked

Example Set hMenu = VisMenuGetHandle (hWnd)


Call VisMenuUncheck (hWnd, hMenu, 5)

VisMessageBoxSyntax nReturn = VisMessageBox (sMsgText, sCaption, hPicIcon, hBtnHandles,

nNumButtons)String: sTextString: sCaptionNumber: hPicIconNumber: 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 canbe a bitmap. Call VisPicLoad to create a picture handle. May be one of the following constants:


Chapter 2

ed

s

MBF_IconAsterisk

MBF_IconHand

MBF_IconQuestion

MBF_IconExclamation

hBtnHandles Array of button handles to display. These handles are obtainfrom a call to VisMessageLoadButton. The button handle may be OR'ed with MBF_DefButton to set the default focusbutton.

nNumButtons Number of buttons contained in hBtnHandles array.

Returns Number: The return value indicating which button is selected. The return value iassigned 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 (...)

VisMessageFreeButtonSyntax bOk = VisMessageFreeButton (hBtn)

Number: hBtn

Description Frees memory allocated with VisMessageLoadButton.

Parameters hBtn Handle of button handle to free memory for.


Related Functions

VisMessageLoadButton

Example Set bOk = VisMessageFreeButton (hBtn)


ue

VisMessageLoadButtonSyntax hBtn = VisMessageLoadButton (sLabel, nReturn)

String: sLabelNumber: 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 valis returned from VisMessageBox.

Returns Number: The button handle if successful, or NULL if an error occurs.

Related Functions

VisMessageFreeButton


Set hBtnOk = VisMessageLoadButton ('Ok', ID_OK)

Set hBtnHelp = VisMessageLoadButton ('&Help', ID_Help)

VisMessageSetBkgdColorSyntax 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 Color to paint the background of the VisMessageBox.


Related Functions

VisMessageBox

Example Call VisMessageSetBkgdColor (COLOR_Gray)

VisNumberBitClearSyntax nResult = VisNumberBitClear (nValue, nBitMask)

Receive Number: nValueNumber: nBitMask

Description Clears bit values from a number.


Chapter 2

d in

er

Parameters nValue Number value to clear bits from. The function replaces this number with the result.

nBitMask Bit mask identifying the bits to clear.

Return Number: The resulting value after mask bits are cleared. This value is also placenValue.

Related Functions

VisNumberBitSet

Example Constants

Number: BIT_Flag1 = 0x0001


...

Actions

Call VisNumberBitClear (nValue, BIT_Flag2)

VisNumberBitSetSyntax nResult = VisNumberBitSet (nValue, nBitMask)

Receive Number: nValueNumber: nBitMask

Description Sets bit values in a number.

Parameters nValue Number value to set bits for. The function replaces this numbwith 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 innValue.

Related Functions

VisNumberBitClear

Example Constants



...

Actions

Call VisNumberBitSet (nValue, BIT_Flag2)


s.

e

VisNumberChooseSyntax nNumber = VisNumberChoose (bExpression, nTrueNumber, nFalseNumber)

Boolean: bExpressionNumber: nTrueNumberNumber: 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 evaluate

Related Functions

VisStrChoose

Example Actions

Set nError = VisNumberChoose (nWnd = hWndNULL, TRUE, FALSE)

VisNumberHighByteSyntax nNumber = VisNumberHighByte(nNumber)

Number: nNumber

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

Parameters nNumber Number to convert and obtain high 8 bits for.

Return Number: The high order 8 bits.

Related Functions

VisNumberLowByte

Example Actions

Set nValue = 0xC8D4

Set nHiByte = VisNumberHighByte (nValue)

!nHiByte = OxC8.


Chapter 2

e

VisNumberLowByteSyntax nNumber = VisNumberLowByte(nNumber)

Number: nNumber

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

Parameters nNumber Number to convert and obtain low 8 bits for.

Return Number: The low order 8 bits.

Related Functions

VisNumberHighByte

Example Actions

Set nValue = 0xC8D4

Set nLowByte = VisNumberLowByte (nValue)

!nLowByte = OxD4.

VisNumberMakeLongSyntax nLong = VisNumberMakeLong(nLow, nHigh)

Number: nLowNumber: 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

VisPicFreeSyntax nErrCode = VisPicFree (hPic)

Number: hPic

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


e.

at

urs.

Parameters hPic Handle of picture to free.

Return Number: Zero if successful, or non-zero if an error occurs.

Related Functions

VisPicLoad

Example Set nErrCode = VisPicFree (hPic)

VisPicLoadSyntax hPic = VisPicLoad (nFormatFlags, sString1, sString2)

Number: nFormatFlagsString: sString1String: sString2

Description Loads a picture into memory. A picture is either a bitmap or an icon and may beobtained from a file, a resource-only DLL, a Centura string, or a Centura resourcThe maximum size of a picture is 65,633 bytes.

Parameters nFormatFlags Flags indicating the type and format of the picture. One formflag and one load flag must be OR'ed together.

PIC_FormatBitmapPIC_FormatIconPIC_LoadFilePIC_LoadResourcePIC_SWinResPIC_SWinStr

sString1 Meaning is determined by the nFormatFlags argument:

PIC_LoadFilePIC_LoadResourcePIC_SwinResPIC_SwinStra

sString2 If PIC_LoadResource is specified, contains the name of thepicture resource to load. Not used for any other load flags.

Return Number: The handle of the specified picture if successful, or NULL if an error occ

Related Functions

VisPicFree


Chapter 2

string

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','')

VisSendMsgStringSyntax nResult = VisSendMsgString (hWnd, nMessage, wParam, sString)

Number: hWndNumber nMessageNumber: wParamString: 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. Theis 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)


tring nd

ight. ment

so on. are

. If a t string

VisStrChooseSyntax sString = VisStrChoose (bExpression, sTrueString, sFalseString)

Boolean: bExpressionString: sTrueStringString: 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).

VisStrExpandSyntax sString = VisStrExpand (sTemplate, hAry)

String: sTemplateNumber | String: hAry[*]

Description Expands a template string by inserting one or more array elements. A template sconsists of ordinary characters, and one or more expand specifications. An expaspecification has the following format:

%[ , ]typeExpand specifications always begin with a percent sign and are read from left to rWhen the first expand specification is encountered, the value of the first array eleis converted and inserted into the return string.

The second expand specification causes the second element to be inserted, andIf there are more array elements than expand specifications, the extra elements ignored. Valid types are s, n, and u.

If braces {} are specified in the template, the text between the braces is repeatedcomma is specified between the percent sign and the type character, each repeais comma delimited before the repeat string, except the first element.


Chapter 2

ry

Parameters sTemplate Template to expand.

hAry Array to expand into template. hAry may be a number array ora string array.

Return String: The expanded string.

Related Functions

VisStrSubstitute

Example Variables

String: sReplaceAry[*]

Actions

Set sReplaceAry[1] = 'myfile'

Call SalMessageBox ( VisStrExpand ('Error:%s File:%s', sReplaceAry), 'Title', MB_Ok)

VisStrFindSyntax sString = VisStrFind (hStrTable, sIdentifier)

Number: hStrTableString: sIdentifier

Description Locates a string within a string table. The string table must be loaded into memousing 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


Set hStrTable = VisStrLoadTable ('MyStrings.txt')

Set sString = VisStrFind (hStrTable, 'dbError.MyString')


is

VisStrFreeTableSyntax bOk = VisStrFreeTable (hStrTable)

Number: hStrTable

Description Frees all memory associated with a string table.

Parameters hStrTable Handle to string table to free from memory.


Related Functions

VisStrFind, VisStrLoadTable

Example Set bOk = VisStrFreeTable (hStrTable)

VisStrLeftTrimSyntax sString = VisStrLeftTrim (sSource)

String: sSource

Description Trims leading blanks from a string.

Parameters sSource Source string.

Return String: The trimmed string.

Related Functions

VisStrRightTrim, VisStrTrim

Example Set sTarget = VisStrLeftTrim (' ABC ')

! sTarget = 'ABC '

VisStrLoadTableSyntax hStrTable = VisStrLoadTable (sFileName)

String: sFileName

Description Loads a string table from disk into memory. The maximum size of a string table 65,533 bytes.

Parameters sFileName File name of string table to load. If no path is specified, the current drive/directory is searched.

Returns String: The handle of the string table if successful, or negative if an error occurs.


Chapter 2

e

ch ft ing is

ac,

Related Functions

VisStrFind, VisStrFreeTable

Example Set hStrTable = VisStrLoadTable (sFileName)

VisStrPadSyntax sString = VisStrPad (sSource, nSize)

String: sSourceNumber: nSize

Description Pads a string with trailing blanks and returns the result. If the length of the sourcstring 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)

VisStrProperSyntax sString = VisStrProper (sSource)

String: sSource

Description Converts a string to mixed case. If the string is all lowercase, the first letter of eaword is capitalized. If the string is all uppercase, the first letter of each word is lecapitalized while the remaining letters are made lowercase. Before the source strconverted, the following delimiters are removed: ~!@#$%^&*()_+-=|\[]{}:";'?,./. After the conversion, the delimiters are reinserted. The first letter following Mc, Mor O' are also capitalized.


Return String: The converted string.

Example Set sTarget = VisStrProper ('M.L. SMITH')


is

last

VisStrRightTrimSyntax sString = VisStrRightTrim (sSource)

String: sSource

Description Trims trailing blanks from a string.



Related Functi ons

VisStrLeftTrim, VisStrTrim

Example Set sTarget = VisStrRightTrim (' ABC ')

VisStrScanReverseSyntax nOffset = VisStrScanReverse (sSource, nPos, sSearchFor)

String: sSourceNumber: nPos String: sSearchFor

Description Scans a string for a specified sub-string from the last character to the first. Caseignored when performing the search.

Parameters sSource Source string to search.

nPos Position to begin the search, -1 to begin searching from the character.

sSearchFor String to search for.

Return Number: The position of search string, -1 if string not found.

Example Set nOffset = VisStrScanReverse ('c:\\path\\file', -1, '\\')

If nOffset = 0

...

VisStrSubstituteSyntax sString = VisStrSubstitute (sSource, sSearch, sReplace)

String: sSourceString: sSearchString: sReplace


Chapter 2

kets.

If atch

of

Description Substitutes all occurrences of one string with another string.


sSearch String to search for.

sReplace Replacement string.

Return String: The modified string.

Example Set sTarget = VisStrSubstitute ('12ABC34ABC', 'ABC', '*'

! sTarget = '12*34*'

VisStrTrimSyntax sString = VisStrTrim (sSource)

String: sSource

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

Parameters sSource Source string


Related Functions

VisStrLeftTrim, VisStrRightTrim

Example Set sTarget = VisStrTrim (' ABC ')

! sTarget = 'ABC'

VisTblAllRowsSyntax bOk = VisTblAllRows (hWndTable, nFlagsOn, nFlagsOff)

Handle: hWndTableNumber: nFlagsOnNumber: nFlagsOff

Description Determines whether any rows in the specified table window match certain flags.multiple flags are specified in the nFlagsOn parameter, all specified flags must mthe 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 anythe flags specified.


ze a ading

ROW_Edited

ROW_Hidden

ROW_HideMarks

ROW_MarkDeleted

ROW_New

ROW_Selected


Example If VisTblAllRows (twTable, ROW_New | ROW_Selected, 0)

VisTblAutoSizeColumnSyntax bOk = VisTblAutoSizeColumn (hWndTable, hWndColumn)

Handle: hWndTableHandle: hWndColumn

Description Performs a best fit on the display contents of a specific column. A best fit will resicolumn based on the current contents of the displayed columns. The column heand split window contents are included in calculating the width.


hWndColumn Column window handle to auto size. Specify hWndNULL to size all columns.


Example Call VisTblAutoSizeColumn (twTable, colPrice)

VisTblClearColumnSelectionSyntax bOk = VisTblClearColumnSelection (hWndTable)

Handle: hWndTable

Description Clears selection for all columns of a table window.



Example Call VisTblClearColumnSelection (hWndForm)


Chapter 2

e)

the et

e/

e et

VisTblFindDateTimeSyntax nRow = VisTblFindDateTime (hWndTable, nStartRow, hWndColumn, dtDateTim

Handle: hWndTableNumber: nStartRowNumber: hWndColumnDate/Time: dtDateTime

Description Locates a date/time value within a column. Searching ends when the last row intable is checked. A SAM_FetchRow message is sent for all rows that have not ybeen fetched into the cache.


nStartRow Row number to start the search at.

hWndColumn Handle of column to search or hWndNULL to search all dattime 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')

VisTblFindNumberSyntax nRow = VisTblFindNumber (hWndTable, nStartRow, hWndColumn, nNumber)

Handle: hWndTableNumber: nStartRowNumber: hWndColumnNumber: nNumber

Description Locates a number value within a column. Searching ends when the last row in thtable is checked. A SAM_FetchRow message is sent for all rows that have not ybeen fetched into the cache.



hWndColumn Handle of column to search or hWndNULL to search all number columns.

nNumber Number to search for.


is Row

e ( _ )

g

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)

VisTblFindStringSyntax nRow = VisTblFindString (hWndTable, nStartRow, hWndColumn, sString)

Handle: hWndTableNumber: nStartRowNumber: hWndColumnString: sString

Description Locates a string value within a column. The string must match exactly and case ignored. Searching ends when the last row in the table is checked. A SAM_Fetchmessage 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. Thpercent character (%) matches any set of characters. The underscore charactermatches any single character.



hWndColumn Handle of column to search or hWndNULL to search all strincolumns.

sString String to search for.

Returns Number: The row number if string is found, -1 if not found.

Related Functions

VisTblFindDateTime, VisTblFindNumber

Example Set nRow = VisTblFindString (twOrders, 0, colDesc, 'Widget')


Chapter 2

the

VisTblGetCellSyntax sText = VisTblGetCell (hWndTable, nRow, hWndColumn)

Number: nRowHandle: hWndColumn

Description Retrieves the contents of a cell in a table window. The row specified will be set tocontext row.

Parameters hWndtable Table window handle.

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)

VisTblGetColumnTitleSyntax sTitle = VisTblGetColumnTitle (hWndColumn)

Handle: hWndColumn

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


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)


g .

the

es

VisTblSetRowColorSyntax bOk = VisTblSetRowColor (hWndTable, nRow, nColor)

Handle: hWndTableNumber: nRowNumber: nColor

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


nRow Row number to set the text color for.

nColor Color to set for all columns of the row specified.


Related Functions

VisTblSetRowPicture, VisTblGetColumnTitle

Example Call VisTblSetRowColor (twOrders, 10, COLOR_Red)

VisTblSetRowPictureSyntax bOk = VisTblSetRowPicture (hWndTable, nRowFlag, hPic)

Handle: hWndTableNumber: nRowFlagNumber: hPic

Description Sets the picture for a bit flag of a table window. When any row contains the bit flaspecified, the picture will be drawn in the row header portion of the table windowCentura normally displays pictures for the ROW_New, ROW_Edited, and ROW_MarkDeletedFlags. The Centura pictures will no longer be displayed afterfirst call to VisTblSetRowPicture. The picture will simply be inverted when the rowis selected. A second picture cannot be displayed when the row is selected.


nRowFlag Row flag to trigger the display of the picture specified. Picturmay be set for any of the following row flags:

ROW_NewROW_EditedROW_Markdeleted ROW_UserFlag1ROW_UserFlag2ROW_UserFlag3ROW_UserFlag4


Chapter 2

he n.

s the

.

rglass r to

ROW_UserFlag5

hPic Picture to display in the row header when the row contains tspecified row flag. This must be a bitmap; it cannot be an icoCall VisPicLoad to create a picture handle.


Related Functions

VisTblSetRowColor


Set hPic = VisPicLoad (PIC_Load Resource | PIC_FormatBitmap, 'Vis.dll', VISPIC_CheckBlack)

Call VisTblSetRowPicture (twOrders, ROW_New, hPic)

VisWaitCursorSyntax bOk = VisWaitCursor (nFlags)

Number: nFlags

Description Turns hourglass cursor on or off. Differs from SalWaitCursor in the following ways:

1. Disables the current application when the hourglass is turned on and enableapplication 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 houoff only when the reference count is equal to zero. This allows VisWaitCursobe embedded in low-level functions.

Parameters nFlags TRUE to display the cursor as an hourglass and FALSE to display as an arrow.

TRUEFALSEWAIT_SysModalOnWAIT_SysModalOffWAIT_TempOnWAIT_TempOff

Return Boolean: No return value.

Example Call VisWaitCursor (WAIT_TempOff)

Call SalMessageBox ('Error Occurred', 'Error', MB_OK)

Call VisWaitCursor (WAIT_TempOn)


To

VisWinClearAllEditFlagsSyntax 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 Window handle of parent window to clear all edit flags of.

Return Number: The number of fields cleared, or negative if an error occurs.

Related Functions

VisWinClearAllFields


On SAM_Create

Call VisWinSetFlags (hWndItem, SWF_NoClearEditFlag)

Actions

Call VisWinClearAllEditFlags (hWndForm)

VisWinClearAllFieldsSyntax 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. prevent clearing a window, set the WF_NoClear flag with a call to VisWinSetFlags.

Parameters hWndParent Window handle of parent window to clear all child fields of.

Return Number: The number of fields cleared, or negative if an error occurs.

Related Functions

VisWinClearAllEditFlags


Chapter 2

to


On SAM_Create

Call VisWinSetFlags (hWndItem, SWF_NoClear)

Actions

Call VisWinClearAllFields (hWndForm)

VisWinEnumPropsSyntax nNumItems = VisWinEnumProps (hWnd, sPropStrings, sValues)

Window Handle: hWndString: sPropStrings[*]String: sValues[*]

Description Enumerates the property list for a specified window. A property list can be used define application-specific attributes for a window. Use property lists sparingly aseach 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)

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


ra to


Related Functions

VisWinGetProp

Example Set bOk = VisWinFreeAccelerator (hAcc)

VisWinGetFlagsSyntax 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 bitwiseAND (&) operator. Options are:

WF_RequiredWF_NoClearWF_NoClearEditFlagWF_EnableWhenNotNullWF_FitPathWF_DisplayOnly

Related Functions

VisWinSetFlags

Example Actions

Set nFlags = VisWinGetFlags (hWndForm)

VisWinGetHandleSyntax hWnd = VisWinGetHandle (hWndDialog, sContext, nWindowType)

Window Handle: hWndDialogString: sContextNumber: nWindowType

Description Obtains a window handle based on the window type and a context string. UnderCentura, the bStaticsAsWindows variable must be set to TRUE in order for Centucreate 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.


Chapter 2

be

, or

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)

VisWinGetPropSyntax nValue = VisWinGetProp (hWnd, sPropString)

Window Handle: hWndString: sPropString

Description Retrieves a value from the property list of a specified window. A property list canused 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 existsthe window has a property with the value of zero.

Related Functions

VisWinRemoveProp, VisWinSetProp

Example Set nValue = VisWinGetProp (hWnd, sPropString)

VisWinGetStyleSyntax 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 Window handle of window to retrieve style bits of.

Return Number: The style bits of the window specified, or -1 if window is invalid.


x, ta

n.

dow.

Related Functions

VisWinSetStyle

Example Variables

Number: nStyle

...

Actions

Set nStyle = VisWinGetStyle (hWndForm)

VisWinGetTextSyntax sString = VisWinGetText (hWnd)

Window Handle: hWnd

Description Obtains the text of a window. Window text is the title of a form window, dialog botable window, radio button, check box, background text or push button. For a dafield, 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 colum

Parameters hWnd Window to obtain text for.

Returns String: The window text, if successful, or null string if error occurs.

Example Radio Button: rbSample

Title: Option:

...

Actions

Set sText = VisWinGetText (rbSample)

! sText = 'Option:'

VisWinIsChildSyntax bOk = VisWinIsChild (hWndParent, hWndChild)

Window Handle: hWndParentWindow Handle: hWndChild

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

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.


Chapter 2

Related Functions

VisWinIsWindow

Example Actions

If VisWinIsChild (hWndForm, pbOk)

...

VisWinIsMaximizedSyntax bOk = VisWinIsMaximized (hWnd)

Window Handle: hWnd

Description Tests whether a specified window is maximized.

Parameters hWnd Window handle of window to test.

Return Boolean: TRUE if window maximized, FALSE if not maximized.

Related Functions

VisWinIsMinimized, VisWinIsRestored

Example Actions

If VisWinIsMaximized (hWndForm)

VisWinIsMinimizedSyntax bOk = VisWinIsMinimized (hWnd)

Window Handle: hWnd

Description Tests whether a specified window is minimized.


Return Boolean: TRUE if window minimized, FALSE if not minimized

Related Functions

VisWinIsMaximized, VisWinIsRestored

Example Actions

If VisWinIsMinimized (hWndForm)


VisWinIsRequiredFieldNullSyntax hWnd = VisWinIsRequiredFieldNull (hWndParent)

Handle: hWndParent

Description Tests to determine if any required field is null.

Parameters hWndParent Handle of parent window to test. If any child window is required and contains a null value, VisWinIsRequiredFieldNull returns TRUE.

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

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

VisWinIsRestoredSyntax bOk = VisWinIsRestored (hWnd)

Window Handle: hWnd

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


Return Boolean: TRUE if window restored, FALSE if not maximized or minimized


,

cified will

tor

Related Functions

VisWinIsMaximized, VisWinIsMinimized

Example Actions

If VisWinIsRestored (hWndForm)

VisWinIsWindowSyntax bOk = VisWinIsWindow (hWnd)

Window Handle: hWnd

Description Tests whether a specified window is valid.


Return Boolean: TRUE if window valid, FALSE if invalid

Related Functions

VisWinIsChild

Example Actions

If VisWinIsWindow (hWndForm)

VisWinLoadAcceleratorSyntax hAcc = VisWinLoadAccelerator (hWndNotify, nMsg, nKeyDownState, nVirtualKey

nValue)Handle: hWndNotifyNumber: nMsgNumber: nKeyDownStateNumber: nVirtualKeyNumber: nValue

Description Sets an accelerator keystroke for a window. If the accelerator is pressed, the spewindow is notified with the specified message. The lParam of the message sentcontain the accelerator handle.

Parameters hWndNotify Window to notify when the accelerator is pressed.

nMsg Message to send to the window specified when the accelerais pressed.

nKeyDownState Flag indicating the keys held down in combination with the virtual key. Options are:

KDS_NoneKDS_Shift

of be sed.

is a

KDS_CtrlKDS_ShiftCtrlKDS_AltKDS_AltCtrlKDS_AltShiftKDS_ShiftAltCtrl

nVirtualKey Virtual key to act as accelerator. See the Appendix for a complete listing of virtual key codes.

nValue Any application defined value that will be passed in lParam the message sent when the accelerator is pressed. This canused to pass menu ID values when menu accelerators are u

Returns Handle: Handle to accelerator if successful, NULL if an error occurs.

Related Functions

VisWinFreeAccelerator

Example Pushbutton: pbExpand

Variables

Number: hAcc

...

Message Actions

On SAM_Create

Set hAcc = VisWinLoadAccelerator (pbExpand, SAM_Click, KDS_Alt, VK_Plus, 0)

On SAM_Destroy

Call VisWinFreeAccelerator (hAcc)

VisWinMoveSyntax bOk = VisWinMove (hWnd, nLeft, nTop, nWidth, nHeight)

Handle: hWndNumber: nLeftNumber: nTopNumber: nWidthNumber: nHeight

Description Moves and resizes a window, based on pixel coordinates. If the window is a formwindow or table window, the coordinates are relative to the screen. If the windowchild window, the coordinates are relative to the parent window's client area.

Parameters hWnd Handle of window to move.


Chapter 2

to

ty

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.


Example Actions

Call VisWinMove (hWnd, 10, 25, 425, 200)

VisWinRemovePropSyntax bOk = VisWinRemoveProp (hWnd, sPropString)

Window Handle: hWndString: sPropString

Description Removes a property list entry for a specified window. A property list can be useddefine application-specific attributes for a window. Use property lists sparingly aseach 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 properdoes not exist.

Related Functions

VisWinGetProp, VisWinSetProp

Example Set bOk = VisWinRemoveProp (hWnd, sPropString)

VisWinSetFlagsSyntax bOk = VisWinSetFlags (hWnd, nWinFlags, bState)

Handle: hWndNumber: nWinFlagsBoolean: bState

Description Sets flags for a specified window.

Parameters hWnd Window handle to set flags for.

nWinFlags Window flags to set. Options are:

WF_RequiredWF_NoClear


er

tes ce

WF_NoClearEditFlagWF_EnableWhenNotNullWF_FitPathWF_DisplayOnly

bState TRUE to set the flags, FALSE to remove the flags.


Related Functions

VisWinGetFlags


Call VisWinSetFlags (hWndItem, SWF_DisplayOnly, TRUE)

VisWinSetMeterSyntax nErrCode = VisWinSetMeter (hWnd, nPercent)

Window Handle: hWndNumber: nPercent

Description Displays a completion meter within a Centura data field. The complete portion isdisplayed 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 metin. 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)

VisWinSetPropSyntax bOk = VisWinSetProp (hWnd, sPropString, nValue)

Window Handle: hWndString: sPropStringNumber: 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 attribufor a window. Use property lists sparingly as each string takes up system resourspace.


Chapter 2

d in,

e

.

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

Return Boolean: TRUE if entry was added or changed, FALSE if window handle invalid.

Related Functions

VisWinGetProp, VisWinRemoveProp

Example’ Set bOk = VisWinSetProp (hWnd, sPropString, nValue)

VisWinSetStyleSyntax bOk = VisWinSetStyle (hWnd, nStyle, bState)

Window Handle: hWndNumber: nStyleBoolean: bState

Description Adds a window style to a window. It does not set the style to the style bits passerather 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 thWindows 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)


VisWinSetTabOrderSyntax bOk = VisWinSetTabOrder (hWnd, hWndInsertAfter)

Window Handle: hWndWindow 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 Boolean: TRUE if successful, FALSE if an error occurs.

Example Actions

Call VisWinSetTabOrder (hWndItem, NULL)

VisWinShowSyntax bOk = VisWinShow (hWnd, nShowFlag)

Window Handle: hWndNumber: 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_HiddenSHOW_MinimizedSHOW_MaximizedSHOW_Normal

Return Boolean: TRUE if window previously was visible, FALSE if previously hidden.

Example Actions

Call VisWinShow (hWndForm, SHOW_Maximized)


IndexCentura Builder Function Reference

Aarray functions 1-17

CCentura function categories 1-17Centura functions 1-1, 2-1

typessystem 1-2

Centura system functions 1-2obsolete 1-16

color and font functions 1-17Compuserve xxviiConventions used in the manual xxvi

Ddata type conversion functions 1-19date functions 1-20DDE functions 1-21debugging functions 1-22dialog box functions 1-23drag drop functions 1-25

Eedit functions 1-26

Ffile management functions 1-27format and validation functions 1-29functions

array 1-17data type conversion 1-19date 1-20DDE 1-21debugging 1-22dialog box 1-23drag drop 1-25edit 1-26file management 1-27format and validation 1-29list and combo box 1-31manipulating background text 1-33MDI 1-36message 1-36miscellaneous 1-37number 1-40picture 1-42

prints 1-43reports 1-43scroll bar 1-44SQL 1-44string conversion 1-47table window 1-48window management 1-51

Llist and combo box functions 1-31

MManipulating Background Text functions 1-33Manipulating background text functions 1-33Manual

description of xxviMDI functions 1-36message functions 1-36miscellaneous functions 1-37

Nnumber functions 1-40

Ppicture functions 1-42print functions 1-43

SSalAbort 2-2SalAppDisable 2-2SalAppEnable 2-3SalAppFind 2-3SalArrayAvg 2-4SalArrayDimCount 2-4SalArrayGetLowerBound 2-5SalArrayGetUpperBound 2-5SalArrayIsEmpty 2-6SalArrayMax 2-7SalArrayMin 2-7SalArraySetUpperBound 2-8SalArraySum 2-8SalBringWindowToTop 2-9SalCenterWindow 2-9SalClearField 2-10SalColorFromRGB 2-10SalColorGet 2-11SalColorGetSysColor 2-11

Centura Builder Function Reference Index-1

��

SalColorSet 2-12SalColorToRGB 2-13SalCompileAndEvaluate 2-13SalContextCurrent 2-15SalCreateWindow 2-15SalCreateWindowExWithParms 2-16SalCursorClear 2-18SalCursorSet 2-18SalCursorSetFile 2-19SalCursorSetString 2-19SalDateConstruct 2-20SalDateCurrent 2-21SalDateDay 2-21SalDateHour 2-21SalDateMinute 2-22SalDateMonth 2-22SalDateMonthBegin 2-22SalDateQuarter 2-23SalDateQuarterBegin 2-23SalDateSecond 2-23SalDateToStr 2-24SalDateWeekBegin 2-24SalDateWeekday 2-25SalDateYear 2-25SalDateYearBegin 2-25SalDDEAddAtom 2-26SalDDEAlloc 2-26SalDDEDeleteAtom 2-27SalDDEExtract 2-27SalDDEExtractCmd 2-27SalDDEExtractDataText 2-28SalDDEExtractOptions 2-28SalDDEFindAtom 2-29SalDDEFree 2-29SalDDEGetAtomName 2-30SalDDEGetExecuteString 2-30SalDDEPost 2-30SalDDERequest 2-31SalDDESend 2-32SalDDESendAll 2-32SalDDESendExecute 2-33SalDDESendToClient 2-34SalDDESetCmd 2-34SalDDESetDataText 2-35SalDDESetOptions 2-35SalDDEStartServer 2-36SalDDEStartSession 2-36SalDDEStopServer 2-37

SalDDEStopSession 2-37SalDestroyWindow 2-37SalDisableWindow 2-38SalDisableWindowAndLabel 2-38SalDlgChooseColor 2-39SalDlgChooseFont 2-39SalDlgOpenFile 2-40SalDlgSaveFile 2-42SalDragDropDisableDrop 2-43SalDragDropEnableDrop 2-44SalDragDropGetSource 2-44SalDragDropGetTarget 2-45SalDragDropStart 2-45SalDragDropStop 2-45SalDrawMenuBar 2-46SalDropFilesAcceptFiles 2-46SalDropFilesQueryFiles 2-47SalDropFilesQueryPoint 2-48SalEditCanCopyTo 2-48SalEditCanCut 2-49SalEditCanPaste 2-49SalEditCanPasteFrom 2-49SalEditCanUndo 2-50SalEditClear 2-50SalEditCopy 2-50SalEditCopyString 2-51SalEditCopyTo 2-51SalEditCut 2-51SalEditPaste 2-52SalEditPasteFrom 2-52SalEditPasteString 2-53SalEditUndo 2-53SalEnableWindow 2-54SalEnableWindowAndLabel 2-54SalEndDialog 2-54SalFileClose 2-55SalFileCopy 2-55SalFileCreateDirectory 2-56SalFileGetC 2-56SalFileGetChar 2-57SalFileGetCurrentDirectory 2-57SalFileGetDateTime 2-57SalFileGetDrive 2-58SalFileGetStr 2-58SalFileOpen 2-59SalFileOpenExt 2-59SalFilePutC 2-60SalFilePutChar 2-60

Index-2 Centura Builder Function Reference

SalFilePutStr 2-61SalFileRead 2-61SalFileRemoveDirectory 2-62SalFileSeek 2-62SalFileSetCurrentDirectory 2-63SalFileSetDateTime 2-63SalFileSetDrive 2-63SalFileTell 2-64SalFileWrite 2-64SalFmtFieldToStr 2-64SalFmtFormatDateTime 2-65SalFmtFormatNumber 2-66SalFmtGetFormat 2-66, 2-67SalFmtGetInputMask 2-67SalFmtIsValidField 2-68SalFmtIsValidInputMask 2-69SalFmtIsValidPicture 2-69SalFmtKeepMask 2-70SalFmtSetFormat 2-71SalFmtSetInputMask 2-72SalFmtSetPicture 2-72SalFmtStrToField 2-73SalFmtUnmaskInput 2-73SalFmtValidateField 2-74SalFontGet 2-74SalFontGetNames 2-75SalFontGetSizes 2-75SalFontSet 2-76SalFormGetParmNum 2-76SalFormUnitsToPixels 2-77SalGetDataType 2-77SalGetDefButton 2-78SalGetFirstChild 2-78SalGetFocus 2-79SalGetItemName 2-79SalGetMaxDataLength 2-79SalGetNextChild 2-80SalGetProfileInt 2-80SalGetProfileString 2-81SalGetType 2-82SalGetVersion 2-82SalGetWindowLabelText 2-83SalGetWindowLoc 2-83SalGetWindowSize 2-84SalGetWindowState 2-84SalGetWindowText 2-84SalHideWindow 2-85SalHideWindowAndLabel 2-85

SalHStringToNumber 2-86SalInvalidateWindow 2-86SalIsButtonChecked 2-86SalIsNull 2-87SalIsValidDateTime 2-87SalIsValidDecimal 2-87SalIsValidInteger 2-88SalIsValidNumber 2-89SalIsWindowEnabled 2-89SalIsWindowVisible 2-89SalListAdd 2-90SalListClear 2-90SalListDelete 2-91SalListFiles 2-91SalListGetMultiSelect 2-92SalListInsert 2-92SalListPopulate 2-92SalListQueryCount 2-93SalListQueryFile 2-94SalListQueryMultiCount 2-94SalListQuerySelection 2-94SalListQueryState 2-95SalListQueryText 2-95SalListQueryTextLength 2-96SalListQueryTextX 2-95, 2-96SalListRedraw 2-96SalListSelectString 2-97SalListSetMultiSelect 2-97SalListSetSelect 2-98SalListSetTabs 2-98SalLoadApp 2-99SalLoadAppAndWait 2-99SalMapEnterToTab 2-101SalMDIArrangeIcons 2-101SalMDICascade 2-101SalMDITile 2-102SalMessageBeep 2-102SalMessageBox 2-103SalModalDialog 2-104SalModalDialogFromStr 2-106SalMoveWindow 2-106SalNumberAbs 2-107SalNumberArcCos 2-107SalNumberArcSin 2-107SalNumberArcTan 2-108SalNumberArcTan2 2-108SalNumberCos 2-108SalNumberCosH 2-109


��

SalNumberExponent 2-109SalNumberHigh 2-109SalNumberHypot 2-110SalNumberLog 2-110SalNumberLogBase10 2-110SalNumberLow 2-111SalNumberMax 2-111SalNumberMin 2-111SalNumberMod 2-112SalNumberPi 2-112SalNumberPower 2-112SalNumberRandInit 2-113SalNumberRandom 2-113SalNumberRound 2-114SalNumberSin 2-114SalNumberSinH 2-114SalNumberSqrt 2-115SalNumberTan 2-115SalNumberTanH 2-115SalNumberToChar 2-116SalNumberToHString 2-116SalNumberToStr 2-116SalNumberToStrX 2-117SalNumberToWindowHandle 2-117SalNumberTruncate 2-118SalParentWindow 2-118SalPicClear 2-119SalPicGetDescription 2-119SalPicGetString 2-120SalPicSet 2-120SalPicSetFile 2-121SalPicSetFit 2-121SalPicSetString 2-122SalPixelsToFormUnits 2-123SalPostMsg 2-123SalPrtExtractRect 2-124SalPrtGetDefault 2-124SalPrtGetParmNum 2-125SalPrtPrintForm 2-125SalPrtSetDefault 2-126SalPrtSetParmDefaults 2-126SalPrtSetParmNum 2-127SalPrtSetup 2-127SalQueryFieldEdit 2-128SalQuit 2-128SalReportClose 2-129SalReportCmd 2-129SalReportCreate 2-129

SalReportDlgOptions 2-130SalReportGetDateTimeVar 2-131SalReportGetNumberVar 2-131SalReportGetObjectVar 2-132SalReportGetStringVar 2-132SalReportPrint 2-133SalReportPrintToFile 2-134SalReportReset 2-136SalReportSetDateTimeVar 2-136SalReportSetNumberVar 2-137SalReportSetObjectVar 2-137SalReportSetStringVar 2-138SalReportTableCreate 2-138SalReportTablePrint 2-139SalReportTableView 2-140SalReportView 2-140SalScrollGetPos 2-142SalScrollGetRange 2-142SalScrollSetPos 2-143SalScrollSetRange 2-143SalSendClassMessage 2-144SalSendClassMessageNamed 2-144SalSendMsg 2-145SalSendMsgToChildren 2-145SalSendValidateMsg 2-146SalSetDefButton 2-146SalSetFieldEdit 2-147SalSetFocus 2-147SalSetMaxDataLength 2-148SalSetProfileString 2-148SalSetWindowLabelText 2-149SalSetWindowLoc 2-149SalSetWindowSize 2-149SalSetWindowText 2-150SalShowWindow 2-150SalShowWindowAndLabel 2-151SalStatusGetText 2-151SalStatusSetText 2-152SalStatusSetVisible 2-152SalStrCompress 2-152SalStrFirstC 2-153SalStrGetBufferLength 2-153SalStrIsValidCurrency 2-154SalStrIsValidDateTime 2-154SalStrIsValidNumber 2-155SalStrLeft 2-155SalStrLeftX 2-156SalStrLength 2-156


SalStrLop 2-157SalStrLower 2-157SalStrMid 2-158SalStrProper 2-158SalStrRepeat 2-159SalStrRepeatX 2-159SalStrReplace 2-159SalStrReplaceX 2-159SalStrRight 2-160SalStrRightX 2-160SalStrScan 2-161SalStrSetBufferLength 2-162SalStrToDate 2-162SalStrTokenize 2-163SalStrToNumber 2-163SalStrTrim 2-164SalStrTrimX 2-164SalStrUncompress 2-165SalStrUpper 2-165SalStrUpperX 2-165SalTBarSetVisible 2-166SalTblAnyRows 2-166SalTblClearSelection 2-167SalTblColumnAverage 2-167SalTblColumnSum 2-167SalTblCopyRows 2-168SalTblCreateColumn 2-168SalTblDefineCheckBoxColumn 2-169SalTblDefineDropDownListColumn 2-170SalTblDefinePopupEditColumn 2-170SalTblDefineRowHeader 2-171SalTblDefineSplitWindow 2-171SalTblDeleteRow 2-172SalTblDeleteSelected 2-172SalTblDestroyColumns 2-173SalTblDoDeletes 2-173SalTblDoInserts 2-174SalTblDoUpdates 2-175SalTblFetchRow 2-175SalTblFindNextRow 2-176SalTblFindPrevRow 2-177SalTblGetColumnText 2-178SalTblGetColumnTitle 2-178SalTblGetColumnWindow 2-178SalTblInsertRow 2-179SalTblKillEdit 2-179SalTblKillFocus 2-180SalTblPasteRows 2-180

SalTblPopulate 2-180SalTblQueryCheckBoxColumn 2-182SalTblQueryColumnCellType 2-182SalTblQueryColumnFlags 2-183SalTblQueryColumnID 2-183SalTblQueryColumnPos 2-183SalTblQueryColumnWidth 2-184SalTblQueryContext 2-184SalTblQueryDropDownListColumn 2-184SalTblQueryFocus 2-185SalTblQueryLinesPerRow 2-185SalTblQueryLockedColumns 2-186SalTblQueryPopupEditColumn 2-186SalTblQueryRowFlags 2-187SalTblQueryRowHeader 2-187SalTblQueryScroll 2-188SalTblQuerySplitWindow 2-188SalTblQueryTableFlags 2-189SalTblQueryVisibleRange 2-189SalTblReset 2-189SalTblScroll 2-190SalTblSetCellTextColor 2-190SalTblSetColumnFlags 2-191SalTblSetColumnPos 2-191SalTblSetColumnText 2-192SalTblSetColumnTitle 2-192SalTblSetColumnWidth 2-192SalTblSetContext 2-193SalTblSetFlagsAnyRows 2-193SalTblSetFocusCell 2-194SalTblSetFocusRow 2-195SalTblSetLinesPerRow 2-195SalTblSetLockedColumns 2-195SalTblSetRange 2-196SalTblSetRow 2-196SalTblSetRowFlags 2-197SalTblSetTableFlags 2-197SalTblSortRows 2-198SalTimerKill 2-198SalTimerSet 2-199SalTrackPopupMenu 2-199SalUpdateWindow 2-200SalUseRegistry 2-201SalValidateSet 2-201SalWaitCursor 2-202SalWindowClassName 2-202SalWindowGetProperty 2-203SalWindowHandleToNumber 2-203


��

SalWindowIsDerivedFromClass 2-203SalWinHelp 2-204SalYieldEnable 2-205SalYieldQueryState 2-205SalYieldStartMessages 2-205SalYieldStopMessages 2-206scroll bar functions 1-44SQL functions 1-44SqlClearImmediate 2-206SqlClose 2-206SqlCommit 2-207SqlConnect 2-207SqlContextClear 2-208SqlContextSet 2-208SqlContextSetToForm 2-209SqlDirectoryByName 2-209SqlDisconnect 2-209SqlDropStoredCmd 2-210SqlError 2-210SqlErrorText 2-210SqlExecute 2-211SqlExecutionPlan 2-212SqlExists 2-212SqlExtractArgs 2-212SqlFetchNext 2-213SqlFetchPrevious 2-214SqlFetchRow 2-214SqlGetError 2-214SqlGetErrorPosition 2-215SqlGetErrorText 2-215SqlGetErrorTextX 2-216SqlGetLastStatement 2-216SqlGetModifiedRows 2-217SqlGetParameter 2-217SqlGetParameterAll 2-218SqlGetResultSetCount 2-218SqlGetRollbackFlag 2-219SqlImmediate 2-219SqlImmediateContext 2-220SqlOpen 2-221SqlPLSQLCommand 2-221SqlPrepare 2-223SqlPrepareAndExecute 2-224SqlRetrieve 2-225SqlSetInMessage 2-225SqlSetIsolationLevel 2-226SqlSetLockTimeout 2-226SqlSetLongBindDatatype 2-227

SqlSetOutMessage 2-228SqlSetParameter 2-228SqlSetParameterAll 2-229SqlSetResultSet 2-229SqlStore 2-230string conversion functions 1-47

Ttable window functions 1-48

VVisArrayAppend 2-231VisArrayCopy 2-227VisArrayDeleteItem 2-233VisArrayFillDateTime 2-233VisArrayFillNumber 2-234VisArrayFillString 2-234VisArrayFindDateTime 2-235VisArrayFindNumber 2-235VisArrayFindString 2-236VisArrayInsertItem 2-237VisArraySort 2-237VisDebugAssert 2-238VisDebugBeginTime 2-239VisDebugEndTime 2-239VisDebugGetFlags 2-240VisDebugSetFlags 2-240VisDebugSetLevel 2-241VisDebugSetTime 2-241VisDebugString 2-242VisDosBuildFullName 2-242VisDosEnumDirInfo 2-243VisDosEnumDirs 2-244VisDosEnumDrives 2-244VisDosEnumFileInfo 2-245VisDosEnumFiles 2-246VisDosEnumNetConnections 2-247VisDosEnumPath 2-248VisDosEnumsShortDirInfo 2-249VisDosEnumsShortDirs 2-249VisDosEnumsShortFileInfo 2-250VisDosEnumsShortFiles 2-251VisDosExist 2-251VisDosGetCurDir 2-252VisDosGetDriveSize 2-252VisDosGetDriveType 2-253VisDosGetEnvString 2-254VisDosGetFlags 2-254


VisDosGetNetName 2-255VisDosGetVersion 2-255VisDosGetVolumeLabel 2-256VisDosIsParent 2-256VisDosMakeAllDir 2-257VisDosMakePath 2-257VisDosNetConnect 2-258VisDosNetDisconnect 2-258VisDosSetFlags 2-259VisDosSetVolumeLabel 2-259VisDosSplitPath 2-260VisErrorRecovery 2-261VisFileAppend 2-261VisFileClose 2-262VisFileCopy 2-262VisFileCreateTemp 2-263VisFileDelete 2-263VisFileExpand 2-263VisFileFind 2-264VisFileGetAttribute 2-264VisFileGetSize 2-265VisFileGetType 2-265VisFileOpen 2-266VisFileRead 2-267VisFileReadString 2-268VisFileRename 2-268VisFileSeek 2-269VisFileSetAttribute 2-269VisFileSetDateTime 2-270VisFileTell 2-271VisFileWrite 2-271VisFileWriteString 2-272VisFontEnum 2-272VisFontFree 2-273VisFontGet 2-273VisFontLoad 2-274VisGetCopyright 2-275VisGetKeyState 2-275VisGetSystemMetrics 2-275VisGetVersion 2-276VisGetWinFlags 2-276VisGetWinVersion 2-277VisListAddValue 2-277VisListArrayPopulate 2-278VisListArrayPopulateValue 2-278VisListClearSelection 2-279VisListDeleteSelected 2-279VisListFindString 2-280

VisListFindValue 2-280VisListGetDropdownState 2-281VisListGetFocusIndex 2-281VisListGetVisibleRange 2-282VisListInsertValue 2-282VisListIsMultiSelect 2-283VisListLoadOutline 2-283VisListLoadOutlineFile 2-284VisListSaveOutline 2-285VisListScroll 2-285VisListSetDropdownState 2-286VisListSetFocusIndex 2-286VisListSetScrollWidth 2-287VisMenuGetPopupHandle 2-287VisMenuGetSystemHandle 2-288VisMenuGetText 2-288VisMenuInsert 2-289VisMenuInsertFont 2-290VisMenuInsertPicture 2-291VisMenuIsChecked 2-292VisMenuIsEnabled 2-293VisMenuSetFont 2-294VisMenuSetPicture 2-295VisMenuSetText 2-296VisMenuUncheck 2-297VisMessageBox 2-297VisMessageFreeButton 2-298VisMessageLoadButton 2-299VisMessageSetBkgdColor 2-299VisNumberBitClear 2-299VisNumberBitSet 2-300VisNumberChoose 2-301VisNumberHighByte 2-301VisNumberLowByte 2-302VisNumberMakeLong 2-302VisPicFree 2-302VisPicLoad 2-303VisSendMsgString 2-304VisStrChoose 2-305VisStrExpand 2-305VisStrFind 2-306VisStrFreeTable 2-307VisStrLeftTrim 2-307VisStrLoadTable 2-307VisStrPad 2-308VisStrProper 2-308VisStrRightTrim 2-309VisStrScanReverse 2-309


��

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

Wwindow management functions 1-51


Centura Builder - Function Reference

Documents

Transcript of Centura Builder - Function Reference