Release 12.

ClearBasic Object
Reference

M30031-00E12050000
March 2004
© 1995–2004, Amdocs. All Rights Reserved.
Amdocs Confidential
This manual and the software described herein are subject to your Amdocs Software License and are copyrighted with
all rights reserved. This manual and the software may not be copied, in whole or in part, without written consent of
Amdocs, except as permitted by your Amdocs Software License.
The information in this manual is furnished for informational use only by authorized persons, is subject to change
without notice, and should not be construed as a commitment by Amdocs. Amdocs assumes no responsibility or
liability for any errors or inaccuracies that may appear in this book.
The trademark and service marks of the respective Amdocs companies, including the Amdocs mark and logo, are the
exclusive property of such companies, and may not be used without permission. All other marks mentioned in this
material are the property of their respective owners.

For technical assistance, visit http://clearanswer.clarify.com to submit a case at any time.

Contents

About This Guide

Audience for This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
How to Use This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
What’s New in This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

App object

CallCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
CLTransition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
ConvertCurrencyValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
CreateColorScheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
DoDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
ExecuteCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
ExecuteMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
ExitApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
GenerateID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
GetContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
GetCurrentDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
GetFormInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
GetUserPopupListLevel1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
GetUserPopupListLevel2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
InputBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
LogSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
MsgBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
SetColorScheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
ShowAttachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
ShowCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

ClearBasic Object Reference 3

Contents

ShowContact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ShowContract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
ShowCR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
ShowDefaultMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
ShowEmployee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
ShowFTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
ShowSelect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
ShowSite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ShowSubcase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
TransferPart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
UseClarifyDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
UseDefaultDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
ValidateUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
CurrentDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
DatabaseName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
EmployeeObjId. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
EXEName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
QuerySize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
ServerName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
UserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
UserObjId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

AppMenu object

AddItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
AddSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
CheckItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Enable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
IsEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
IsItemChecked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
RenameItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
SetFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Show. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
MenuBarId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

BulkRetrieve object

AppendFilter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
AppendSort. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
EntryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
GetRecordList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
GetRelatedRecordList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

4
ClearBasic Object Reference
 Contents

Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
RetrieveRecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
SetRoot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
SetRootById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
SimpleQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
TraverseFromParent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
TraverseFromRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

BulkSave object

CancelRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
ChangeRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
CountByType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
DeleteRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
DeleteRecordByID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
GetRecordByIndex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
InsertRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
RelateRecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
RelateRecordsFromID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
RelateRecordsFromToID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
RelateRecordsToID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
UnrelateRecords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
UpdateRecord. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Save_Aborted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

ClarifyDB object

Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Connected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
DatabaseName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
ServerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
UserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Clipboard object
Clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
GetFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
GetText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
SetText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

CommonDialog object

Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
CancelError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

5
ClearBasic Object Reference
Contents

Copies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
DefaultExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
DialogId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
DialogTitle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
ElapsedSeconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
FileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
FileTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
FromPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
InitDir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
ToPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

ContextualObject object

AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Empty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
GetContents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
IsNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
DataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
ForeColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
SubType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

DDE object

DDEExecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
DDEInitiate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
DDERequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
DDETerminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
DDETimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Debug object

Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

6
ClearBasic Object Reference
 Contents

Show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

EventLogger object

ActivateEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
AddNewEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
SetLogData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
UpdateAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
SetBulk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Form object

AppendContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
CheckRequired. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
ClearContextMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
ConvertCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
DisableControls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
DisableControlsDeep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
DoDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
EnableControls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
EnableControlsDeep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
ForceRedraw. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
GetCBCObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
GetChildKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
GetCObjFieldList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
GetCObjFieldStaticItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
GetCObjFieldStaticList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
GetCObjList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
GetCObjMethodKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
GetCObjMethodList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
GetCObjPropertyKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
GetControlByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
GetDisplayCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
GetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
GetMethodValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
GetPropertyValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
GetUserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
InheritCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Notify. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
NotifyById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
NotifyByKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

7
ClearBasic Object Reference
Contents

NotifyChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
NotifyParent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
NotifyTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
NotifyTabParent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
SetContextMenuEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
SetContextMenuVisible. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
SetDisplayCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
SetFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
SetParent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
SetTargetCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
SetUserData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Show. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
ShowControls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
ShowControlsDeep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
ActiveControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
BackColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
DataChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
hWnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
ParentKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
ReadOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Top . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
WindowState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Activate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
ContextMenuDisplaying. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
ContextMenu_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
DblClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Deactivate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Form_Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Form_Save. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Form_Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
MouseDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
MouseUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

8
ClearBasic Object Reference
 Contents

Resize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Global Constants

SetValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

List object

AppendItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Concat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
ExtractList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
FindFirstIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
GetItemByIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
ItemByIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
ListByIndex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
RemoveByIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
ReplaceByIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
AllowDuplicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
ItemType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Sorted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

PowerQuery object

AppendFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
AppendSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
GetCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
RetrieveIDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
RetrieveRecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
SetObjectType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
SetSortOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Printer object

EndDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
NewPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
TextHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
TextWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

9
ClearBasic Object Reference
 Contents

Continuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
CurrentX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
CurrentY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
DrawMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
DrawStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
DrawWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
FontBold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
FontFamily . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
FontItalic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
FontSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
RightMargin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Truncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Wrap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Record object

ChangeToNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
CopyFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
CreateView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
GetField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
GetObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
GetTextField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
IsDirty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
IsExactly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
IsMaxDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
IsMinDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
IsNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
SetField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
RecordType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

Screen object

AllSpaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

ServiceMessage object

Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Write. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

10
ClearBasic Object Reference
 Contents

SQLDB object

Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Disconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
ExecuteProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Connected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

Appendix A Supported Objects, Methods, Properties and Events

Object and Method Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Object and Property Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Object and Event Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

Appendix B APIs

APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
faEditAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
faGetAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
faSetAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
faGetAttributeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
faSetAttributeList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
faGetAllAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
faGetRelation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
faSetRelation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
faGetPossibleAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
faDeleteAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Flexible Attribute Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Related Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

Appendix C Creating Java and EJB Objects Using ClearBasic APIs

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Global Basic Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
ConnectEjbServerImpl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
DisconnectEjbServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
CreateJavaObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
CreateEjbObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
CallStaticJavaFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
GetStaticJavaField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
GetObjectStaticJavaField. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
CreateJavaArray. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
CreateJavaObjectArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Basic Object Type and JavaObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
JavaObject::IsArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

11
ClearBasic Object Reference
 Contents

JavaObject::GetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
JavaObject::GetAtObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
JavaObject::Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
JavaObject::ClassName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
JavaObject::IsNull. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
JavaObject::SetNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
JavaObject::Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
JavaObject::CallObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
JavaObject::Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
JavaObject::GetObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
JavaObject::Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Single Signon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Java Exception to ClearBasic Error Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Java Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Configuration Settings in the clarify.env File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Extending the EJB host Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

Index

12
ClearBasic Object Reference
About This Guide

This reference provides information about the ClearBasic objects and their methods,
properties, and events. It is a companion volumn to the ClearBasic Control Reference,
which provides information about the ClearBasic controls. This reference is also a
companion to the ClearBasic Programmer’s Guide, which provides information about
using ClearBasic to customize Clarify eFrontOffice, and to the ClearBasic Language
Reference, which documents the ClearBasic language.

Audience for This Guide

This reference is intended for developers involved in extending and customizing the
Clarify eFrontOffice (CeFO) applications and databases.

Related Documentation
The following referenced documentation is available on the CeFO Documentation
CD-ROM:
■ ClearBasic Control Reference
■ ClearBasic Programmer’s Guide
■ ClearBasic Language Reference
■ ClearBasic Customization Guide
■ User Interface Editor Guide

How to Use This Guide

This guide describes the ClearBasic objects defined for use with Clarify eFrontOffice.
This guide contains the following sections:
■ A table of contents.
■ An alphabetical list of objects, with accompanying descriptions. Immediately
following the description of each object are descriptions of its methods,
properties, and events.
■ An appendix with a comprehensive list of the methods, properties, and events
associated with each object, organized in tables for quick reference.
■ An index containing an alphabetical list of all of the objects, methods,
properties, and events in this guide.

ClearBasic Object Reference 13

 What’s New in This Document
This reference introduces a new way of organizing ClearBasic objects, methods,
properties, and events. The new organization groups the methods, properties, and
events related to a object with the description for that object. The new organization
lets you search for related methods and properties of the object quickly. Refer to the
improved index if you want to view an alphabetical listing of objects, methods,
properties, and events.
The online version of this document also introduces the use of live links. The object
description contains the list of methods, properties, and events for the object. Clicking
one of these entries takes you to the description of that entry. In addition, the See Also
sections associated with individual entries now contain live links to entries within this
book. References to objects, controls, methods, properties, or events outside of this
book do not use live links.

Conventions
These special formats are used:

NOTE: Provides additional information that is useful but not always essential.

More Information: Refers you to other sections of this guide or to other documents for more
information.

IMPORTANT: Highlights key considerations to keep in mind.

CAUTION: Highlights important situations that could potentially damage data or

cause system failure.

■ Monospace is used for programming elements (such as code fragments,

objects, methods, parameters, and HTML tags) and system elements (such as
file names, directories, paths, and URLs).
■ Monospace bold is used in syntax descriptions to identify statement
elements you must type exactly as shown
■ Monospace italic is used in syntax descriptions to identify placeholders,
which are general names that you replace with names in your code
■ Straight brackets signal options in command-line syntax.
deRead [-llf log_filename] [-debug]
■ An underscore character [_] at the end of a code line indicates that the
ClearBasic statement continues on the next line.

14 About This Guide

ClearBasic Object Reference
 App object

Description The App object is the global application object. This object provides access to system-
level information and provides ways to get and modify that information.

You use the App object to perform the following tasks:

■ manage color schemes
■ execute ClearBasic functions
■ execute menu commands
■ get global settings and info
■ get system resources (strings, popup lists)
■ display user-interaction dialogs
■ display specific windows

Each session provides a single instance of the App object for you to use. You never
create App objects directly in your own code. Instead, you access application-level
functionality using the App keyword.
You can use the App keyword in any form modules or global modules to access the
methods and properties of the App object. For example, to call the UseDefaultDB
method, you would write the following code:
App.UseDefaultDB

Color Management The App object provides several methods for handling color management in
applications. ClarifyCRM uses color schemes to group related colors. A color scheme
is a list of one or more colors grouped together for a common purpose. Each color in
the color scheme has an associated label that is independent of the color. By using the
same labels in multiple color schemes, you can change several colors at once by
changing the current color scheme.

At initialization time, you must define all of the color schemes you plan to use in your
Initialize_App global routine. You define a color scheme using the
CreateColorScheme method.

Only one color scheme at a time may be active. To set the current color scheme, use
the SetColorScheme method. Once you have set the current color scheme, any
controls that use color refer to the labels in that color scheme.

Executing Code The App object provides access to baseline functionality of the current application and
also provides methods for executing custom functionality.

For baseline functionality, you can use the ExecuteMenu method to perform a
command defined on the current application’s menubar. If you have customized
portions of the application, you can use the DoDefault method to perform the
default behavior in addition to your customizations.

ClearBasic Object Reference 15

 App object

The CallCB method executes a custom ClearBasic function either locally or on a

remote system server. You can use this method to perform tasks that require access to
other parts of the system, such as remote databases. You can also use this method in
your implementation of Flexible Deployment to execute ClearBasic routines in an n-
tier environment.

Getting System The properties and methods of the App object give you access to many system-level
Information properties. Using the properties of the App object, you can retrieve information about
the database associated with the current session. You can also retrieve information
about the current user logged into the session.

Another system-level property you can access from the App object is the global select
item (GSI). The GSI is any workflow object that can be placed into a WIPbin. For
example, Cases and Opportunities are both examples of GSI objects. To retrieve the
current GSI, use the GetContext method.

Getting Database The App object provides several methods for accessing database resources. Using
Resources these methods, you can retrieve information such as strings and user-defined popup
lists.

The GetString method returns a string defined in the string_db table. This table
contains system strings such as error messages and can also be used to store custom
string information.

The GetUserPopupListLevel1 and GetUserPopupListLevel2 methods

retrieve first and second level user-popup lists defined in the Policies and Customers
application. The user defines these lists for use in list-related controls such as
dropdown lists boxes. Your code can use the returned list information to populate list
controls dynamically.

Interacting With the The App object provides simple alert dialogs for displaying messages and getting user
User input. You can use these dialogs in situations where you do not need to define a
custom form for displaying or retrieving information.

You can use the MsgBox method to display operation results, error messages,
confirmation dialogs, or any other message that requires minimal user interaction.
Using this method, you can provide the user with a set of options from which to
choose.

To obtain additional information from the user, you can use the InputBox method.
This method displays a simple alert dialog into which the user can type some text.
The InputBox method returns the typed text for your application to process.

Managing Forms The App object provides methods to display specific forms and to access existing
forms. You can use the Show method to display custom forms. You can also use other
methods such as ShowCase, ShowCR, and ShowAttachments to show specific
baseline forms.
In addition to displaying forms, you can retrieve a reference to an existing form using
the GetFormInstance method. This method returns the Form object for any form
that is currently being displayed.

16
ClearBasic Object Reference
 App object

Methods This object defines the following methods:

■ CallCB method
■ CLTransition method
■ ConvertCurrencyValue method
■ CreateColorScheme method
■ DoDefault method
■ ExecuteCB method
■ ExecuteMenu method
■ ExitApp method
■ GenerateID method
■ GetContext method
■ GetCurrentDB method
■ GetFormInstance method
■ GetString method
■ GetUserPopupListLevel1 method
■ GetUserPopupListLevel2 method
■ InputBox method
■ LogSQL method
■ MsgBox method
■ SetColorScheme method
■ ShowAttachments method
■ ShowCase method
■ ShowContact method
■ ShowContract method
■ ShowCR method
■ ShowDefaultMenu method
■ ShowEmployee method
■ ShowFTS method
■ ShowSelect method
■ ShowSite method
■ ShowSubcase method
■ TransferPart method
■ UseClarifyDB method
■ UseDefaultDB method
■ ValidateUser method

17
ClearBasic Object Reference
 App object

Properties This object defines the following properties:

■ CurrentDate property
■ DatabaseName property
■ EmployeeObjId property
■ EXEName property
■ QuerySize property
■ ServerName property
■ UserName property
■ UserObjId property

18
ClearBasic Object Reference
 App object

method CallCB

Syntax Status = App.CallCB CallString, option

Applies To App

Description The CallCB method executes a ClearBasic global subroutine. You can call this
method to execute a routine in both a normal 2-tier environment and an n-tier
environment.

The CallString parameter specifies the calling sequence of the ClearBasic subroutine.
You must format this string to include any parameters or return values that are
appropriate for your subroutine. When specifying parameters, you may use constant
values or variables from the current subroutine. If you specify a return value, you
must specify a variable to receive the value.

To specify variables in the CallString parameter, simply add the name of the variable
to the text of the parameter. The parameters you specify in your call string may be
constant values or they may correspond to variables in the current subroutine. If you
specify a return value, it must correspond to the name of a variable.

The CallCB method always passes arguments to your function by reference (ByRef),
even if the parameter was declared with the ByVal keyword. When you use variables
in the CallString parameter, your variables must be of the following data types:
■ short
■ long
■ single
■ string
■ List

The List elements may contain any of the simple data types listed above or it may
contain Record objects. The CallCB method does not support the use of user-
defined types (UDTs) either as parameters or as elements of a list.

Using CallCB in an In a 2-tier environment, you can use this method to call a ClearBasic subroutine
n-tier Environment directly. When you use this method in a 2-tier environment, you must not specify any
options in the Options parameter.

NOTE: In a 2-tier environment, you can use only the call_string parameter; you cannot use
any option shown in the syntax.

In an n-tier environment, CallCB allows you to remotely execute ClearBasic

subroutines on the ClarifyCRM Application Server. You can execute the remote
subroutines in synchronous or asynchronous mode. See Example 2 on page 21.

More Information: For detailed information about using the CallCB method in an n-tier
environment, refer to the Flexible Deployment Guide.

CallCB 19
ClearBasic Object Reference
 App object

Parameters This method accepts the following parameters:

Parameter Type Description

CallString String Specify the string to execute. If your function contains a return
value, assign the value to a variable in your call string, as in the
following example:
“retValue = MyFunc(param1,param2)”
option Long Specify the calling mode to use when executing the function. This
parameter is optional. If you do not specify this parameter, CallCB
executes the function in synchronous mode.
If you are using this method in an n-tier programming environment,
you may also use the following options:
Option Description
cbCallAsync Execute the subroutine asynchronously.
cbCallBack Execute the subroutine as a callback.
cbCallLocal Execute the subroutine locally.

NOTE: If you execute a function in synchronous mode (no option) in an n-tier environment,
the client’s clarify.env file must include the string REMOTE_CB=TRUE.

Return Values Returns one of the following Long integer values:

Value Meaning
0 Operation was successful
1 Missing subroutine or function name
3 Could not parse subroutine arguments
from the provided string
4 Could not set return variables
5 Invalid subroutine or function; or error
occurred in execution

Example 1 The following example shows you how to call a sample function (MyFunction) using
variables. In the example, MyFunction receives the value 1 from myVar1 and puts
the result in myResult.
Sub MyMainRoutine()
Dim myVar1 As Long
Dim myResult As Long

myVar1 = 1

App.CallCB “myResult = MyFunction(myVar1)”

if myResult = 1 Then
...
End If
End Sub

20 CallCB
ClearBasic Object Reference
 App object

Example 2 The following example illustrates the use of the CallCB method in an n-tier
environment.
Sub UseCallCBOnClient()
Dim tmpCallString As String
Dim tmpReturnStatus As Integer

On Error Goto ErrorHandler

tmpCallString = "CallFunctionOnServer"
tmpReturnStatus = App.CallCB(tmpCallString)

If tmpReturnStatus <> 0 Then

Debug.Print "Error occurred when calling
remote CB."
Else
Debug.Print "Remote CB is executed
successfully."
End If

Exit Sub

ErrorHandler:
Debug.Message Error$, STR$(Erl)
End Sub

CallCB 21
ClearBasic Object Reference
 App object

method CLTransition

Syntax App.CLTransition fromCondition, toCondition, requestType

Applies To App

Description The CLTransition method validates a ClearLogistics transition state. You use this
method to validate a transition associated with an existing part request
(demand_dtl) record.

This method verifies that the transition between the specified conditions is legal for
the specified part request type. This method also verifies that the current user’s
privilege class is sufficient for performing this transition.

Parameters This method accepts the following parameters:

Parameter Type Description

fromCondition String Specify the title of the source condition. You can get this value
from the title field of a "condition" record.
toCondition String Specify the title of the destination condition. You can get this
value from the title field of a "condition" record.
requestType String Specify the title of the request type. You can get this value from
the request_type field of a "demand_dtl" record.

Return Values Returns one of the following Long integer values:

Value Description
0 The transition is authorized.
1 The transition is not authorized.
2 The transition is not authorized because of insufficient privileges.

See Also TransferPart method

22 CLTransition
ClearBasic Object Reference
 App object

method ConvertCurrencyValue

Syntax Set ToValue = App.CurrencyConvertValue (FromCurrency,

ToCurrency, ConversionDate, FromValue)

Applies To App

Description The ConvertCurrencyValue method converts a single currency value using the
provided information. You can use this method to perform an immediate currency
conversion without using the Currency Conversion dialog or any forms.

You should not use this method to convert currency values in the controls of a form.
Instead, use the ConvertCurrency method of the form to perform form-level
conversions.

Parameters This method accepts the following parameters:

Parameter Type Description

FromCurrency Record Specify a record of type "currency" corresponding to the
currency denomination of the FromValue parameter.
ToCurrency Record Specify a record of type "currency" corresponding to the
currency denomination of the return value.
ConversionDate String Specify the date of the transaction.
FromValue Long Specify the value you want to convert. This value must be a
Short currency whose denomination is specified by the
Double FromCurrency parameter.
Single

Return Values Returns the converted currency value. The type of this return value matches the type
of the FromValue parameter.

Example The following example implements a button Click event handler. When the user
presses the button, the event handler gets the value in the MyTxtBox1 text box
control, converts it to the new currency and puts the result back in the control. You
could use this example to implement a currency calculator.
Sub MyBtn1_Click
Dim rec1 as Record
Dim list1 as New List
Dim rec2 as New Record
Dim bulk1 as New BulkRetrieve
Dim date1 as Date
Dim FromValue as String
Dim ToValue as Single

date1 = App.CurrentDate

' Get the value to convert

ConvertCurrencyValue 23
ClearBasic Object Reference
 App object

FromValue = MyTxtBox1.Value

' Get the currency records

bulk1.SimpleQuery 0, "currency"
bulk1.RetrieveRecords

' Get the first two currencies in the list.

' These will be the source and target
' currencies.
Set list1 = bulk1.GetRecordList(0)
set rec1 = list1.ItemByIndex(0)
Set rec2 = list1.ItemByIndex(1)

' Perform the conversion

ToValue = App.ConvertCurrency (rec1, rec2, _
CStr(date1), CSng(FromValue))

' Put the new value back in the text box

MyTxtBox1.Value = CStr(ToValue)
End Sub

See Also ConvertCurrency method (Form object)

SetDisplayCurrency method (Form object)
SetTargetCurrency method (Form object)

24 ConvertCurrencyValue
ClearBasic Object Reference
 App object

method CreateColorScheme

Syntax App.CreateColorScheme SchemeName, LabelList, ColorList

Applies To App

Description The CreateColorScheme method defines a new color scheme for use in your
application. If your application uses color, you must use this method to define at least
one color scheme. See Color Management on page 15 for more information about color
schemes.

Call this method from your Initialize_App global routine to create a new color
scheme for the application. The name of the color scheme must be unique among the
other system color schemes. The labels you specify in the LabelList parameter do not
have to be unique. In fact, you can use the same set of labels in multiple color schemes
to simplify the process of changing colors in your application.

Each label in the LabelList parameter maps to the color at the same index in the
ColorList parameter. Both lists must contain the same number of entries.

After you create the color scheme, you must put it into effect for the form by invoking
the SetColorScheme method in the form load event. Only after this is done can you
actually color the form and controls using the BackColor and ForeColor
properties.

Parameters This method accepts the following parameters:

Parameter Type Description

SchemeName String Specify the name of the color scheme. This string must be unique
among all of the color scheme names.
LabelList List Specify a list containing one or more strings. Each string represents
the label for one color.
This method associates each label in this list with the color at the
same index in the ColorList parameter. The number of entries in
this list must match the number of entries in the ColorList
parameter.
ColorList List Specify a list that contains one or more strings. Each string contains
the name of a system color. See Valid Colors for a list of system color
names.

Valid Colors The following table contains the names of the valid system colors you may add to the
ColorList parameter.
Table 1 Valid system colors
Snow Black Paleturquoise Darkkhaki Orange
Ghostwhite Darkslategray Darkturquoise Khaki Darkorange
Whitesmoke DimGray Mediumturquoise Palegoldenrod Coral
Gainsboro SlateGray Turquoise Lightgoldenrodyellow Lightcoral

CreateColorScheme 25
ClearBasic Object Reference
 App object

Table 1 Valid system colors

Floralwhite LightSlateGray Cyan Lightyellow Tomato
Oldlace Gray Lightcyan Yellow Orangered
Linen Lightgray Cadetblue Gold Red
Antiquewhite Midnightblue Mediumaquamarine Lightgoldenrod Hotpink
Papayawhip Navy Aquamarine Goldenrod Deeppink
Blanchedalmond Navyblue Darkgreen Darkgoldenrod Pink
Bisque Cornflowerblue Darkolivegreen Rosybrown Lightpink
Peachpuff Darkslateblue Darkseagreen Indianred Palevioletred
Navajowhite Slateblue Seagreen Saddlebrown Maroon
Moccasin Mediumslateblue Mediumseagreen Sienna Mediumvioletred
Cornsilk Lightslateblue Lightseagreen Peru Violetred
Ivory Mediumblue Palegreen Burlywood Magenta
Lemonchiffon Royalblue Springgreen Beige Violet
Seashell Blue Lawngreen Wheat Plum
Honeydew Dodgerblue Green Sandybrown Mediumorchid
Mintcream Deepskyblue Chartreuse Tan Darkorchid
Azure Skyblue Mediumspringgreen Chocolate Darkviolet
Aliceblue Lightskyblue Greenyellow Firebrick Blueviolet
Lavender Steelblue Limegreen Brown Purple
Lavenderblush Lightsteelblue Yellowgreen Darksalmon Mediumpurple
Mistyrose Lightblue Forestgreen Salmon Thistle
White Powderblue Olivedrab Lightsalmon

Example The following example creates a color scheme in the global initialization routine.
'In the Global Module

Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", _
"Important", "Weak"

ColorList1.AppendItem "red", "cyan", "blue"

App.CreateColorScheme "Form2020", _
LabelList1, ColorList1
End Sub

The following table shows the color scheme that results from this method.

Label Color
Urgent red
Important cyan
Weak blue

26 CreateColorScheme
ClearBasic Object Reference
 App object

With the color scheme defined, the following example uses that color scheme to set
the ForeColor and BackColor properties of two controls on a form. As a result of this
code, both the text box and label control use the color red for their text.
'In the Form Module
Sub Form_Load
App.SetColorScheme "Form2020"
TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also SetColorScheme method

CreateColorScheme 27
ClearBasic Object Reference
 App object

method DoDefault

Syntax App.DoDefault

Applies To App

Description The DoDefault method performs the default application behavior in contexts where
you do not have access to a form. For example, you may call this method from the
event handler of an application menu item to perform the default behavior of the
menu item.

This method is similar to the DoDefault method of the Form object, except that it
handles application-level behavior rather than form-level behavior.

Parameters None

Return Values This method returns one of the following values:

Value Description
0 The default behavior was performed.
cbNoDefault There was no default behavior to perform.

See Also DoDefault method (Form object)

28 DoDefault
ClearBasic Object Reference
 App object

method ExecuteCB

Syntax RetInt = App.ExecuteCB ("CBCallString")

Applies to App

Description The ExecuteCB method executes the ClearBasic routine specified by the
CBCallString parameter. The specified routine must be declared in a global module.

IMPORTANT: This method is provided for backwards compatibility but otherwise its use is
deprecated. Use the CallCB method instead.

Parameters This method accepts the following parameters:

Parameter Type Description

CBCallString String You must supply a string consisting of the name of the ClearBasic
procedure and any arguments, with a single space separating the
procedure from the arguments and a single space separating each
argument.
If an argument is a string, place double quotes around it. Integer
values and float values are automatically evaluated.

Return Values This method returns a Long integer with one of the following values:

Code Description
0 The ClearBasic function was executed normally
1 No ClearBasic function name was provided
2 The ClearBasic function name provided could not be found

Example The following code snippet illustrates one use of this method.

RetInt = App.ExecuteCB("MyProc")

If RetInt <>0 Then

App.MsgBox "Called procedure did not execute"
End If

See Also CallCB method

ExecuteCB 29
ClearBasic Object Reference
 App object

method ExecuteMenu

Syntax App.ExecuteMenu "PulldownMenuName", "MenuLabel"

RetInt = App.ExecuteMenu ("PulldownMenuName", _
"MenuLabel)"

Applies To App

Description The ExecuteMenu method executes the Click event handler for the specified menu
item. You can use this method to simulate user selections in the current menubar.

This method works only for items in the current menu bar. As a consequence, you
cannot use this method to execute a command in a different application. If the
specified menu item is disabled, this method does not execute the item’s Click event
handler.

Parameters This method accepts the following parameters

Parameter Type Description

PulldownMenuName String Specify the name of a pulldown menu on the current
menubar.
MenuLabel String Specify the name of a menu item on the pulldown menu.
The menu item name is the same as the text displayed for
the item in the pulldown menu.

Return Values This method returns a Long integer with one of the following values:

Value Description
0 The menu item was executed.
1 The menu item was not found.
2 The menu item is disabled.

Example The following code snippet illustrates one use of this method:
‘Your procedure code here

RetInt = App.ExecuteMenu ("New", "Case")

If RetInt <>0 Then
App.MsgBox "Menu item did not execute"
Else
...
End If

Here is another code snippet example. This one shows how to use ExecuteMenu to
programmatically execute Log Email.
App.ExecuteMenu "Actions", "Log Email"

30 ExecuteMenu
ClearBasic Object Reference
 App object

method ExitApp

Syntax App.ExitApp ReturnValue

Applies To App

Description The ExitApp method exits the application immediately. This method also returns an
optional value back to the operating system prior to terminating the application. You
can use the returned value to identify errors during the debugging of your
customizations.

Parameters This method accepts the following parameter:

Parameter Type Description

ReturnValue Long Specify an optional return value to send back to the native operating
system. If you do not specify a value, this method automatically
returns the value 0.

Return Values None

Example The following button click procedure passes a return value of 1 before terminating.
Sub Exit_Now_Click
App.ExitApp 1
End Sub

ExitApp 31
ClearBasic Object Reference
 App object

method GenerateID

Syntax App.GenerateID schemeName

Applies To App

Description The GenerateID method returns the next ID in the specified numbering scheme. Use
the Policies & Customers application to define the numbering schemes for your
application.

Parameters This method accepts the following parameter:

Parameter Type Description

schemeName String Specify the name of the desired numbering scheme.
If you are retrieving this information from the database, you must
specify the name field from a record belonging to the
num_scheme table.

Return Values Returns a String containing the next ID in the sequence.

32 GenerateID
ClearBasic Object Reference
 App object

method GetContext

Syntax Set YourRecord = App.GetContext()

If App.GetContext() = Nothing Then
...

Applies To App

Description The GetContext method returns a copy of the currently selected global select item
(GSI) object. A GSI object is any system object that can be placed in a WIPbin. For
example, Cases and Opportunities are both examples of GSI objects.

CAUTION: Do not attempt to change the returned GSI object and save those changes back to
the database. This record is a copy of the original. Changes to the original are not reflected in
the copy.

You can use this method in situations where you need to access the information in the
currently selected GSI object. You can read values from the fields of the object or use it
to display related windows. You can also enable or disable custom menu items based
on the currently selected GSI object.

NOTE: You do not need to enable or disable ClarifyCRM menu items. ClarifyCRM enables or
disables its own menu items automatically based on the current GSI object.

Parameters None

Return Values Returns a Record object containing the information for the current GSI object. (Use the
RecordType property to determine the type of the returned record.) If no GSI object
is set, this method returns the null object (Nothing).

Example The following code fragment illustrates the use of the GetContext method:

Dim MyRec as Record

Dim RecType As String

Set MyRec = App.GetContext()

‘Test to see if there is no GSI

If MyRec = Nothing Then
'Do this
End If

RecType = MyRec.RecordType

GetContext 33
ClearBasic Object Reference
 App object

See Also Record object

RecordType property (Record object)

34 GetContext
ClearBasic Object Reference
 App object

method GetCurrentDB

Syntax Set YourCurrent_ClarifyDB = App.GetCurrentDB (DBType)

Applies To App

Description The GetCurrentDB method gets the ClarifyDB object associated with the current
session. When ClarifyCRM has open connections to multiple ClarifyCRM databases,
you can use this method to determine which database is currently being used.

Before calling this method, you must create a new ClarifyDB object to receive the
database information. If the current database is a remote database, the method copies
the database information into your object. If the current database is the default
database, this method sets your ClarifyDB object to NULL.

Parameters This method accepts the following parameter:

Parameter Type Description

DBType Long Specify a variable containing a long integer. On return, this
parameter contains the value 0 if the database is the default database,
or this parameter contains the value 1 if the database is a remote
database.

Return Values Returns the database information and assigns it to your new ClarifyDB object. If the
current database is the default database, this method sets your ClarifyDB object to
NULL

Example The following example illustrates the use of the GetCurrentDB method:
Sub FindCurrentDB
Dim OutMessage As String
Dim CurrentDBObject As New ClarifyDB
Dim RetVal As Long
Dim DBServer As String

Set CurrentDBObject = App.GetCurrentDB (RetVal)

If RetVal = 1 Then
DBServer = CurrentDBObject.ServerName
OutMessage = "The current database _
server is" + DBServer

App.MsgBox OutMessage
Else
'That is, if RetVal is zero

App.Msg "The current database is the _

default database, the one you logged into _

GetCurrentDB 35
ClearBasic Object Reference
 App object

originally. The CurrentDBObject is set to _

NULL."
End If

'Additional code goes here

End Sub

See Also UseClarifyDB method

UseDefaultDB method
ClarifyDB object

36 GetCurrentDB
ClearBasic Object Reference
 App object

method GetFormInstance

Syntax status = App.GetFormInstance FormKey

Applies To App

Description The GetFormInstance method returns a specific instance of a posted form. The
FormKey parameter identifies the instance of the form you want. To obtain a value for
the key parameter, you must save the value in the form’s Key property when you
create the form.

Parameters This method accepts the following parameter:

Parameter Type Description

FormKey Long Specify the unique key associated with the form.

Return Values Returns the Form object corresponding to the specified key.

Example The following code snippet illustrates the use of this method:
Dim F1 As New Form
Dim F2 As New Form
Dim F3 As Form
Dim Key1 As Integer
Dim Key2 As Integer

F1.Show 5080, 0
Key1 = F1.Key

F2.Show 5080, 0
Key2 = F2.Key

Set F3 = App.GetFormInstance (Key2)

'Do something in F3
F3.Caption = "Instance 2"

See Also Key property (Form object)

GetFormInstance 37
ClearBasic Object Reference
 App object

method GetString

Syntax App.GetString stringID, outString, replaceString1,

replaceString2, replaceString3, replaceString4,
replaceString5

Applies To App

Description The GetString method retrieves a string_db resource from the database and
sequentially replaces any "%s" markers with the specified replacement strings. You
can use this method to retrieve both ClarifyCRM string resources and user-defined
string resources.

If the specified string resource could not be found in the database, this method returns
False instead of generating an error. If the string resource requires more arguments
than are supplied, this method replaces any missing strings with an empty string.

Parameters This method accepts the following parameters:

Parameter Type Description

stringID Long Specify the ID of the desired database string. This ID corresponds
to the ID field of the string_db resource, not an object ID.
outString String Specify a variable of type String. On return, this variable contains
the string formed from the specified database string and the
optional replacement strings.
replaceString1 String Specify a string to replace a marker of the format "%s" in the
string. This parameter is optional.
replaceString2 String Specify a string to replace a marker of the format "%s" in the
string. This parameter is optional.
replaceString3 String Specify a string to replace a marker of the format "%s" in the
string. This parameter is optional.
replaceString4 String Specify a string to replace a marker of the format "%s" in the
string. This parameter is optional.
replaceString5 String Specify a string to replace a marker of the format "%s" in the
string. This parameter is optional.

Return Values Returns True if the specified string was found, otherwise False.

38 GetString
ClearBasic Object Reference
 App object

Example The following code fragment loads a string from the database and displays it in a
modal dialog. The string accepts one formatted argument indicating an object type.
The ID of the string resource is specified by the cbMyString constant.
Dim outString as String

If App.GetString(cbMyString, outString, _
"employee") Then
App.MsgBox outString
End If

GetString 39
ClearBasic Object Reference
 App object

method GetUserPopupListLevel1

Syntax Set ItemList = App.GetUserPopupListLevel1 (ListName)

Applies To App

Description The GetUserPopupListLevel1 method retrieves the items from a first-level user
popup list. This method retrieves the names of each item in the list.

The ClarifyCRM application comes with several predefined user popup lists. Your
ClarifyCRM system administrator can define additional lists using the Policies and
Customers application.

Parameters This method accepts the following parameter:

Parameter Type Description

ListName String Specify the name of the user popup list whose items you
want to retrieve.

Return Values Returns a List object containing zero or more strings. Each string contains the title of
an item in the specified popup list.

Example The following code fragment retrieves the items from the “BILL_TO_EXPENSE” user
popup list.
Dim myList As New List

Set myList = App.GetUserPopupListLevel1 ("BILL_TO_EXPENSE")

See Also GetUserPopupListLevel2 method

40 GetUserPopupListLevel1
ClearBasic Object Reference
 App object

method GetUserPopupListLevel2

Syntax Set ItemList = App.GetUserPopupListLevel2 (ListName,

Level1Item)

Applies To App

Description The GetUserPopupListLevel2 method retrieves the items for a second-level user
popup list. To identify a particular second-level popup list, you must provide the top-
level list name, and one of the items from the first-level popup-list.

The ClarifyCRM application comes with several predefined user popup lists. Your
ClarifyCRM system administrator can define additional lists using the Policies and
Customers application.

Parameters This method accepts the following parameter:

Parameter Type Description

ListName String Specify the name of the user popup list whose items you want to
retrieve.
Level1Item String Specify the name of an item in the level 1 popup list. This parameter
determines which set of level 2 items are returned.

Return Values Returns a List object containing zero or more strings. Each string contains the title of
an item in the level 2 popup list.

Example The following code fragment retrieves the items from the second level popup list of
“CR_DESC”. The first level of this list contains the CPU types, while the second level
list contains the available OS versions for that CPU.
Dim myList As New List

' Get the Mac OS versions

Set myList = App.GetUserPopupListLevel2("CR_DESC", "Mac")

See Also GetUserPopupListLevel1 method

GetUserPopupListLevel2 41
ClearBasic Object Reference
 App object

method InputBox

Syntax YourRetStr = App.InputBox ("Prompt", "DialogTitle",

"DefaultText")

Applies To App

Description The InputBox method displays a dialog box that prompts the user for information.
The dialog box contains a text box control for receiving user input as well as Cancel
and OK buttons. If the user clicks OK, this method returns the string the user typed in
the text box control; otherwise, if the user clicks Cancel, this method returns an empty
string.

Parameters This method accepts the following parameters:

Parameter Type Description

Prompt String Specify a text prompt string to display to the user. This string may be
up to 200 characters long and should indicate what type of
information the user must provide.
DialogTitle String Specify an optional title to apply to the dialog box. If you do not
specify this string, no title appears for the dialog box.
DefaultText String Specify the default text to display in the text box control. This
parameter is optional.

Return Values Returns a String containing the text the user typed in the dialog’s text box control. If a
user dismissed the dialog using the Cancel button, this method returns an empty
string ("").

See Also MsgBox method

42 InputBox
ClearBasic Object Reference
 App object

method LogSQL

Syntax App.LogSQL "LogFile", OnOrOff, OverWrite

Applies To App

Description The LogSQL method sets the current log file and enables or disables the logging of
SQL commands. You can use this method to track the SQL commands between
ClarifyCRM and the ClarifyCRM database. You can use this information to debug
your customizations.

Parameters This method accepts the following parameters:

Parameter Type Description

LogFile String Specify the name of the log file name. If you include path
information in this parameter, the method uses the file at the
specified path. If you specify a partial path, your path must start in
the current working directory of the application.
OnOrOff Boolean Specify True to enable logging, otherwise False to disable logging.
This parameter is optional and is set to True by default.
OverWrite Boolean Specify True to overwrite the existing contents of the log file before
adding any new log entries. Specify False to append new log
entries to the end of the file.
This parameter is optional and is set to True by default.

Return Values None

LogSQL 43
ClearBasic Object Reference
 App object

method MsgBox

Syntax RetInt = App.MsgBox (Prompt, DialogType, DialogTitle)

Applies To App

Description The MsgBox method displays a message to the user and accepts a user response using
a set of command buttons. You can use this method to display a confirmation dialog
or other informative dialog that requires a user choice. You can also use this method
to display a simple notification dialog box.

Parameters This method accepts the following parameters:

Parameter Type Description

Prompt String Specify the text string to display in the dialog box.
DialogType Long Specify a constant indicating the types of buttons you want the dialog
to display.
This parameter is optional and is set to cbOK by default. The
following list contains the valid constants and dialog types:

Constant Buttons on Form

cbOK OK button. This is the default option.
cbOKCancel OK and CANCEL buttons
cbAbortRetryIgnore ABORT, RETRY, and IGNORE buttons
cbYesNoCancel YES, NO, and CANCEL buttons
cbYesNo YES and NO buttons
cbRetryCancel RETRY and CANCEL buttons
cbSaveDiscardCancel SAVE, DISCARD, and CANCEL
buttons
DialogTitle String Specify a string to appear in the caption bar of the dialog box. This
parameter is optional and is set to the empty string ("") by default.

For the DialogType parameter, the first button listed in the "Buttons on Form" column
is the default button. To make the second button the default button, add the value 256
to the corresponding constant. To make the third button the default button, add the
value 512 to the corresponding constant.

Return Values This method returns a constant indicating which button the user pressed. This
method returns one of the following constants:

Button Pressed Return Constant

OK cbIdOK
CANCEL cbIdCancel
ABORT cbIdAbort

44 MsgBox
ClearBasic Object Reference
 App object

Button Pressed Return Constant

RETRY cbIdRetry
IGNORE cbIdIgnore
YES cbIdYes
NO cbIdNo
SAVE cbIdSave
DISCARD cbIdDiscard

Example The following example shows you how to display a confirmation dialog box using the
MsgBox method.
Sub MySaveField
Dim whichBtn As Long

whichBtn = App.MsgBox ("Save changes?", _

cbSaveDiscardCancel, "Confirm changes")

Select Case (whichBtn)

Case cbIDSave
' Save changes to the field
Case cbIdDiscard
' Discard changes
Case cbIdCancel
' Abort the procedure
Case Else
' Error. No other buttons should be
' available.
End Select
End Sub

See Also InputBox method

MsgBox 45
ClearBasic Object Reference
 App object

method SetColorScheme

Syntax App.SetColorScheme SchemeName

Applies To App

Description The SetColorScheme method sets the currently active color scheme. Any
subsequent references to color use the definitions in the specified color scheme. This
method does not change any colors set prior to this method call.

You can call this method at any time to set the color scheme for the application or for
the subsequently loaded forms. For example, you can call this method from a
Form_Load event handler to set the color scheme for that form.

NOTE: Before calling this method, you must create at least one color scheme using the
CreateColorScheme method.

Parameters This method accepts the following parameter:

Parameter Type Description

SchemeName String Specify the name of an existing color scheme. If the specified
scheme does not exist, this method generates a runtime error.

Example The following code illustrates how you use color in ClearBasic. (You are not required
to set color in the form load event procedure.)

Before you can use color, you must create a color scheme and then put it into effect
using the SetColorScheme method, as shown in the example. Only then can you
color the object you want to color. In the example a text box label and the textbox
foreground text are assigned the same color, red, and the background color for the text
box is set to cyan.
'In the global module
Sub Initialize_App
Dim LabelList1 As New List
Dim ColorList1 As New List

LabelList1.AppendItem "Urgent", _
"Important", "Weak"

ColorList1.AppendItem "red", "cyan", "blue"

App.CreateColorScheme"Form2020", _
LabelList1,ColorList1
End Sub

'In the form module

Sub Form_Load

46 SetColorScheme
ClearBasic Object Reference
 App object

App.SetColorScheme "Form2020"

TextBox1_Label.ForeColor = "Urgent"
TextBox1.ForeColor = "Urgent"
TextBox1.BackColor = "Important"
End Sub

See Also CreateColorScheme method

ColorCells method (Grid object in the ClearBasic Control Reference)
BackColor property (Text Box object in the ClearBasic Control Reference)
ForeColor property (Text Box object in the ClearBasic Control Reference)

SetColorScheme 47
ClearBasic Object Reference
 App object

method ShowAttachments

Syntax App.ShowAttachments YourRecord, numAttachments

Ret_Boolean = App.ShowAttachments (YourRecord, numAttachments)

Applies To App

Description The ShowAttachments method displays the Attachment window for the specified
record. If the record has not been saved to the database, this method generates an
error.

Not all records support attachments. The specified record must belong to one of the
following database tables:
■ bug
■ campaign
■ case
■ contract
■ diag_hint
■ eco_dtl
■ eco_hdr
■ site
■ site_part
■ subcase
■ workaround

Parameters This method accepts the following parameters:

Parameter Type Description

YourRecord Record Specify the record whose attachments you want to show.
Not all records support attachments. See the discussion
following this table for a list of records that support attachments.
numAttchments Long Specify a variable of type Long. On return, this variable contains
the number of attachments related to the record.

Return Values Returns True if the user added or deleted any attachments, otherwise returns False.

48 ShowAttachments
ClearBasic Object Reference
 App object

Example The following procedure posts the attachments window. If the method finds any
attachments for the record, the posted window contains the count of attachments:
Sub Attachments_Click
Dim parentRecord As Record
Dim numAttachments As Long
Dim retValue As boolean

Set parentRecord = Cobj_case.Contents

retValue = App.ShowAttachments _
(parentRecord, numAttachments)

If (retValue = cbAttachmentsMade) Then

Cobj_numAttactments.Fill numAttachments
End If
End Sub

See Also ShowCase method

ShowContact method
ShowContract method
ShowCR method
ShowEmployee method
ShowFTS method
ShowSelect method
ShowSite method
ShowSubcase method
Show method (Form object)

ShowAttachments 49
ClearBasic Object Reference
 App object

method ShowCase

Syntax App.ShowCase YourCaseRecord

Set YourCaseForm = App.ShowCase(YourCaseRecord)

Applies To App

Description The ShowCase method displays the Edit Case window for the specified case. Because
the Edit Case window is modeless, this method returns before any user interaction
with the window begins.

Once it is displayed, the Edit Case window is self-sufficient. The ClearBasic code for
that window handles any user interactions with the case information. You do not
need to perform any other actions.

Parameters This method accepts the following parameters:

Parameter Type Description

YourCaseRecord Record Specify the case record you want to display in the Edit
Case window.

Return Values Returns a reference to the Form object representing the Edit Case window containing
the specified case.

Example In the following example, the "Case By ID" item is added to the Select pulldown menu
in the ClearQuality application. When the user selects the menu item, the event
handler for the item prompts the user for a case ID and then locates the corresponding
record in the database. The ShowCase method then displays the record returned by
the query.
'In global module
Sub Initialize_App
Dim DefaultMenu As New AppMenu

DefaultMenu.MenubarID = 1007
DefaultMenu.AddItem "Select", _
"Case By Id","PostCase"

App.ShowDefaultMenu
End Sub

' Menu item event handler

Sub PostCase_Click
Dim CaseForm As form
Dim IdStr As string
Dim Rec As Record
Dim BulkR As New BulkRetrieve
Dim RecList As List

50 ShowCase
ClearBasic Object Reference
 App object

IdStr = App.InputBox("Enter Case ID:")

If IdStr <> "" then

BulkR.SimpleQuery 0, "case"
BulkR.AppendFilter 0, "id_number", cbEqual, _
IdStr
BulkR.RetrieveRecords

Set RecList = BulkR.GetRecordList (0)

If RecList.Count > 0 then

Set Rec = RecList.ItemByIndex(0)
Set CaseForm = App.ShowCase(Rec)
End If
End If
End Sub

See Also ShowCR method

ShowFTS method
ShowSubcase method
Show method (Form object)

ShowCase 51
ClearBasic Object Reference
 App object

method ShowContact

Syntax App.ShowContact YourContactRecord, Options

Set YourContactForm = App.ShowContact(YourContactRecord,
Options)

Applies To App

Description The ShowContact method posts either a new (empty) Contact window or one filled
with data from an existing contact record. If the objid field of the specified record is
set to 0, this method posts a window for creating a new contact. If the record has a
valid object ID, this method posts a window for editing the specified contact.

If you do not want the user to edit the specified contact record, you can specify the
constant cbShowContactReadOnly option for the Options parameter. This option
forces the contact record to be displayed as read-only.

Once it is displayed, the Contact window is self-sufficient. The ClearBasic code for
that window handles any user interactions with the contact information. You do not
need to perform any other actions.

Parameters This method accepts the following parameters:

Parameter Type Description

YourContactRecord Record Specify a record belonging to the rol_contct database
table. If you specify a record already in the database, this
method posts a form for editing the record. If you specify a
new, empty record, this method posts a form for creating a
new contact record.
Options Long Specify the constant cbShowContactReadOnly to display
the contact record in read-only mode. This parameter is
optional. By default, this method displays contact records as
editable.

Return Values Returns a reference to the Form object representing the Contact window containing
the specified contact record.

Example The following example displays a window for creating a new contact.
Sub CreateNewContact
Dim ContactForm As Form
Dim ContactRec As New Record

ContactRec.RecordType = "rol_contct"
set ContactForm = App.ShowContact _
(ContactRec)
End Sub

52 ShowContact
ClearBasic Object Reference
 App object

See Also ShowCase method

ShowContract method
ShowCR method
ShowEmployee method
ShowFTS method
ShowSelect method
ShowSite method
ShowSubcase method
Show method (Form object)

ShowContact 53
ClearBasic Object Reference
 App object

method ShowContract

Syntax App.ShowContract YourContractRecord, Options

Set YourContractForm = App.ShowContract (YourContractRecord,
Options)

Applies To App

Description The ShowContract method posts either a new (empty) Contract window or one
filled with data from an existing contact record. If the objid field of the specified
record is set to 0, this method posts a window for creating a new contact. If the record
has a valid object ID, this method posts a window for editing the specified contract.

If you do not want the user to edit the specified contract record, you can specify the
constant cbShowContactReadOnly option for the Options parameter. This option
forces the contract record to be displayed as read-only.

Once it is displayed, the Contract window is self-sufficient. The ClearBasic code for
that window handles any user interactions with the contract information. You do not
need to perform any other actions.

Parameters This method accepts the following parameters:

Parameter Type Description

YourContractRecord Record Specify a record belonging to the contract database table.
If you specify a record already in the database, this method
posts a form for editing the record. If you specify a new,
empty record, this method posts a form for creating a new
contract record.
Options Long Specify the constant cbShowContractReadOnly to
display the contact record in read-only mode. This
parameter is optional. By default, this method displays
contract records as editable.

Return Values Returns a reference to the Form object representing the Contract window containing
the specified contact record.

Example The following example displays a window for creating a new contract.
Sub CreateNewContract
Dim ContractForm As Form
Dim ContractRec As New Record

ContractRec.RecordType = "contract"
set ContractForm = App.ShowContract _
(ContractRec)
End Sub

54 ShowContract
ClearBasic Object Reference
 App object

See Also ShowCase method

ShowContact method
ShowCR method
ShowEmployee method
ShowFTS method
ShowSelect method
ShowSite method
ShowSubcase method
Show method (Form object)

ShowContract 55
ClearBasic Object Reference
 App object

method ShowCR

Syntax App.ShowCR YourCRRecord

Set YourCRForm = App.ShowCR(YourCRRecord)

Applies To App

Description The ShowCR method displays a window containing the specified change request.
Because the Edit CR window is modeless, this method returns before any user
interaction with the window begins.

Once it is displayed, the Edit CR window is self-sufficient. The ClearBasic code for
that window handles any user interactions with the case information. You do not
need to perform any other actions.

Parameters This method accepts the following parameter:

Parameter Type Description

YourCRRecord Record Specify the bug record you want to display in the Edit CR
window.

Return Values Returns a reference to the Form object representing the CR window containing the
specified change request record.

Example In the following example, the "CR By ID" item is added to the Select pulldown menu
in the ClearSupport application. When the user selects the menu item, the event
handler for the item prompts the user for a CR ID and then locates the corresponding
record in the database. The ShowCR method then displays the record returned by the
query.
Sub Initialize_App
Dim DefaultMenu As New AppMenu

DefaultMenu.MenubarID = 1002
DefaultMenu.AddItem "Select", _
"CR By ID","PostCR"
App.ShowDefaultMenu
End Sub

Sub PostCR_Click
Dim CRForm As form
Dim IdStr As string
Dim Rec As Record
Dim BulkR As New BulkRetrieve
Dim RecList As List

IdStr = App.InputBox("Enter CR ID:")

56 ShowCR
ClearBasic Object Reference
 App object

If IdStr <> "" then

BulkR.SimpleQuery 0, "bug"
BulkR.AppendFilter 0, "id_number", _
cbEqual, IdStr
BulkR.RetrieveRecords

Set RecList = BulkR.GetRecordList (0)

If RecList.Cont > 0 then

Set Rec = RecList.ItemByIndex(0)
Set CRForm = App.ShowCR(Rec)
End If
End If
End Sub

See Also ShowCase method

ShowFTS method
ShowSubcase method
Show method (Form object)

ShowCR 57
ClearBasic Object Reference
 App object

method ShowDefaultMenu

Syntax App.ShowDefaultMenu

Applies To App

Description The ShowDefaultMenu method displays the ClearSupport menubar, which is the
default application menubar. Normally, you would use this method in the
Initialize_App after invoking any methods to permanently modify the
ClarifyCRM application menubar.

You also need to use this method whenever you modify a menu item in any of your
non-global modules and then want to return to the default application (ClearSupport)
menubar.

Parameters None

Return Values None

Example Typical usage of this method is as follows:

Sub Initialize_App
Dim CS_bar As New Appmenu

CS_bar.MenuBarId = 1008
CS_bar.Show
CS_bar.AddItem "Actions", "NewCourse", _
"PostNewCrse"

App.ShowDefaultMenu
End Sub

Note that the App.ShowDefaultMenu statement will select the default application
ClearSupport. However, when you select ClearQuality, the application corresponding
to 1008, it will display the menu changes.

See Also AppMenu object

AddItem method (AppMenu object)
RenameItem method (AppMenu object)
SetFunction method (AppMenu object)
RemoveItem method (AppMenu object)

58 ShowDefaultMenu
ClearBasic Object Reference
 App object

method ShowEmployee

Syntax App.ShowEmployee YourEmployeeRecord, Options

Set YourEmployeeForm = App.ShowEmployee(YourEmployeeRecord,
Options)

Applies To App

Description The ShowContract method posts either a new (empty) Employee window or one
filled with data from an existing employee record. If the objid field of the specified
record is set to 0, this method posts a window for creating a new employee. If the
record has a valid object ID, this method posts a window for editing the specified
employee.

If you do not want the user to edit the specified employee record, you can specify the
constant cbShowContactReadOnly option for the Options parameter. This option
forces the employee record to be displayed as read-only.

Once it is displayed, the Employee window is self-sufficient. The ClearBasic code for
that window handles any user interactions with the employee information. You do
not need to perform any other actions.

Parameters This method accepts the following parameter:

Parameter Type Description

YourEmployeeRecord Record Specify a record belonging to the empl_user database
table. If you specify a record already in the database, this
method posts a form for editing the record. If you specify
a new, empty record, this method posts a form for creating
a new employee record.
Options Long Specify the constant cbShowEmployeeReadOnly to
display the employee record in read-only mode. This
parameter is optional. By default, this method displays
employee records as editable.

Return Values Returns a reference to the Form object representing the CR window containing the
specified change request record.

Example The following example displays a window for creating a new employee record.
Sub CreateNewEmployee
Dim EmployeeForm As Form
Dim EmployeeRec As New Record

EmployeeRec.RecordType = "empl_user"
set EmployeeForm = App.ShowEmployee _
(EmployeeRec)
End Sub

ShowEmployee 59
ClearBasic Object Reference
 App object

See Also ShowCase method

ShowContact method
ShowCR method
ShowEmployee method
ShowFTS method
ShowSelect method
ShowSite method
ShowSubcase method
Show method (Form object)

60 ShowEmployee
ClearBasic Object Reference
 App object

method ShowFTS

Syntax App.ShowFTS ParentForm, ParentRecord

Applies To App

Description The ShowFTS method posts the standard FTS (full text search) window for the
specified parent form and record. You post the FTS window from a Case, Subcase, or
CR form.

Parameters This method accepts the following parameters:

Parameter Type Description

ParentForm Form Specify the form from which you are posting the FTS
window.
ParentRecord Record Specify the record that is to receive the focus of the FTS
window.

See Also ShowCase method

ShowCR method
ShowSubcase method
Show method (Form object)

ShowFTS 61
ClearBasic Object Reference
 App object

method ShowSelect

Syntax App.ShowSelect RecordType, Control, RecordFilter, BulkRetrieve,

Options
Ret_Integer = App.ShowSelect(RecordType, Control, RecordFilter,
BulkRetrieve, Options)

Applies To App

Description The ShowSelect method displays a child form with which the user can select one or
more records. When you call this method, you must specify the type of records to
display in the child form and any filters or query parameters to use when retrieving
records from the database.

Normally, this method displays a list of the returned records. If only one record
matches the specified type and query parameters, this method displays the details for
that record directly in the parent window. If no records match the given criteria, this
method displays an appropriate message to the user.

The RecordFilter and BulkRetrieve parameters let you specify additional

information to use when querying the database. Both of these parameters are
optional.

To use the RecordFilter parameter, create a record object of the same type as specified
by the RecordType parameter. This method compares the non-empty field values in
that record object with the corresponding values in the database records and returns
any records that match.

In addition to the RecordFilter parameter, you can use the BulkRetrieve

parameter to specify additional query parameters. Set up your BulkRetrieve object
as you would to retrieve a list of records. This method applies the BulkRetrieve
query parameters after the RecordFilter parameters.

Typically, your application calls this method from the Click event handler of a
command button; however, you may call this method from other event handlers as is
appropriate for your application.

When the user selects one or more records and clicks the Use/Done button of the
child form, this method calls the UseSelect callback method of the specified control
to process the selection. The syntax for the UseSelect callback is as follows:
Sub Control_UseSelect(myList As List,
how As Integer)

IMPORTANT: If you do not specify a RecordFilter parameter, this method displays an

empty selection dialog box, which the user can use to query for specific records.

Parameters The following parameters are accepted.

62 ShowSelect
ClearBasic Object Reference
 App object

Parameter Type Description

RecordType Long Required. You must specify one of the following record
names:
These parameters are system-defined constants.
ConstantRequired Record type
cbSelBusinessCalendar biz_cal_ast
cbSelContact rol_contct
cbSelContracts contract
cbSelEmployee empl_user
cbSelInstalledPart addrsitepmhpml
(you can also use
part_inst)
cbSelLiterature literature
cbSelPartNumber part_num
cbSelSCM scrn_view
cbSelSite site_view
Control Control Required. The control through which the user invokes the
method. Usually, this is a command button.
Note, you must specify the control object and not the name of
the control for this parameter.
RecordFilter Record Optional. This parameter is a record which specifies criteria
for filtering (preselecting) records from the database. For
example, to select records of type "site," where you could use:
RecordFilter.RecordType = "site_view"
RecordFilter.SetField "name", "Jet"
BulkRetrieve BulkRetrieve Optional. This parameter may be specified to use conditions
in addition to those specified by the RecordFilter parameter
when selecting records for display.
Options Long Optional. You may specify any combination of the following
constants. To specify more than one constant, add them
together.
cbShowSelFrontIfUp
Front the select window if it is already displayed. Do not
create a new window.
cbShowSelMultiple
Allow the selection of multiple items from the select window.
The underlying ClarifyCRM application must support
multiple selections for this option to work.
cbShowSelNoPrefilter
Do not retrieve any records from the database upon
displaying the select window. If you specify a valid
BulkRetrieve object in the BulkRetrieve parameter, this option
has no effect.

Return Values Returns cbSelFormPosted if the method succeeds; otherwise, returns 0 if it fails to
post the window.

ShowSelect 63
ClearBasic Object Reference
 App object

Example In the following code, the SelSite_Click procedure posts a window that contains a
list of site records, if any, whose names start with Xe. This happens when the SelSite
control is clicked in the parent window. If at least one specified record is found, the
SelSite control is disabled. Otherwise, the SelSite control remains enabled.

Then, when a record is selected and the Use/Done button is clicked, the
SelSite_UseSelect procedure is executed and the selected record is passed to the
procedure. The procedure shows the site form and then, the SelSite control is enabled.
Sub SelSite_Click
Dim ret_val As integer
Dim filterRec As New Record

'Get all sites whose name starts with "Xe"

filterRec.RecordType = "site_view"
filterRec.SetField("name", "Xe%")

Ret_Val = App.ShowSelect(cbSelSite,SelSite _
filterRec)

If Ret_Val = cbSelWindowPosted Then

' Disable the SelSite button
SelSite.Enabled = False
End If
End Sub

Sub SelSite_UseSelect (myList As List,

how As Integer)
Dim index As Integer
Dim myRec As Record

For index = 0 to myList.count-1

Set myRec = myList.ItemByIndex(index)
App.ShowSite myRec
Next

SelSite.Enabled = True
End Sub

See Also ShowContact method

ShowContract method
ShowEmployee method
ShowSite method
Show method (Form object)

64 ShowSelect
ClearBasic Object Reference
 App object

method ShowSite

Syntax App.ShowSite YourSiteRecord, Options

Set YourSiteForm = App.ShowSite(YourSiteRecord, Options)

Applies To App

Description The ShowSite method posts either a new (empty) Site window or one filled with
data from an existing site record. If the objid field of the specified record is set to 0,
this method posts a window for creating a new site. If the record has a valid object ID,
this method posts a window for editing the specified site.

If you do not want the user to edit the specified site record, you can specify the
constant cbShowSiteReadOnly option for the Options parameter. This option forces
the site record to be displayed as read-only.

Once it is displayed, the Site window is self-sufficient. The ClearBasic code for that
window handles any user interactions with the employee information. You do not
need to perform any other actions.

Parameters The following parameters are accepted:

Parameter Type Description

YourSiteRecord Record Specify a record belonging to the site_view database table. If
you specify a record already in the database, this method posts
a form for editing the record. If you specify a new, empty
record, this method posts a form for creating a new site record.
Options Long Specify the constant cbShowSiteReadOnly to display the
site record in read-only mode. This parameter is optional. By
default, this method displays site records as editable.

Return Values Returns a reference to the Form object representing the CR window containing the
specified change request record.

Example The following example displays a window for creating a new site record.
Sub CreateNewSite
Dim SiteForm As Form
Dim SiteRec As New Record

SiteRec.RecordType = "empl_user"
set SiteForm = App.SiteForm (SiteRec)
End Sub

ShowSite 65
ClearBasic Object Reference
 App object

See Also ShowCase method

ShowContract method
ShowCR method
ShowEmployee method
ShowFTS method
ShowSelect method
ShowSubcase method
Show method (Form object)

66 ShowSite
ClearBasic Object Reference
 App object

method ShowSubcase

Syntax App.ShowSubcase YourSubcaseRecord

Set YourSubForm = App.ShowSubcase (YourSubcaseRecord)

Applies To App

Description The ShowSubcase method displays a window containing the specified subcase.
Because the Edit Subcase window is modeless, this method returns before any user
interaction with the window begins.

Once it is displayed, the Edit Subcase window is self-sufficient. The ClearBasic code
for that window handles any user interactions with the case information. You do not
need to perform any other actions.

Parameters The following parameter is accepted:

Parameter Type Description

YourSubcaseRecord Record You must specify the subcase record to be posted in
the subcase window.

Return Values This method returns a new form variable for the subcase window: you can use this in
subsequent ClearBasic code if you wish.

Example In the following example, the "SubCase By ID" item is added to the Select pulldown
menu in the ClearQuality application. When the user selects the menu item, the event
handler for the item prompts the user for a subcase ID and then locates the
corresponding record in the database. The ShowSubcase method then displays the
record returned by the query.
Sub initialize_app
Dim DefaultMenu As New AppMenu

DefaultMenu.MenubarID = 1008
DefaultMenu.AddItem "Select", _
"SubCase By Id","PostSubCase"

App.ShowDefaultMenu
End Sub

Sub PostSubcase_Click
Dim SubCaseForm As form
Dim IdStr As string
Dim Rec As Record
Dim BulkR As New BulkRetrieve
Dim RecList As List

IdStr = App.InputBox("Enter subcase ID:")

ShowSubcase 67
ClearBasic Object Reference
 App object

If Idstr <> "" Then

BulkR.SimpleQuery 0, "subcase"
BulkR.AppendFilter 0, "id_number", _
cbEqual, IdStr
BulkR.RetrieveRecords

Set RecList = BulkR.GetRecordList (0)

If RecList.Count > 0 Then

Set Rec = RecList.ItemByIndex(0)
Set SubcaseForm = App.ShowSubcase(Rec)
End If
End If
End Sub

See Also ShowCase method

ShowContact method
ShowContract method
ShowCR method
ShowEmployee method
ShowFTS method
ShowSite method
ShowSelect method
Show method (Form object)

68 ShowSubcase
ClearBasic Object Reference
 App object

method TransferPart

Syntax Status = App.TransferPart (partRec, quantity, serialNo,

fromBin, toBin, refId, notes, fromStatus, toStatus,
transactionType, transactionId)

Applies To App

Description The TransferPart method uses the ClearLogistics transaction engine to move an
inventory part from one location to another. You must specify the To and From bins
for the part as well as other information about the transaction.

The values you specify for the quantity and serialNo parameters depend on the
type of the part. If the part requires a serial number, you must specify 1 for the
quantity parameter and an appropriate serial number for serialNo. If the part is
tracked by quantity, specify an appropriate value in the quantity parameter and an
empty string in serialNo.

This method verifies that the To and From bins exist but does not verify whether or
not these bins are active. You must verify that the bins are active before calling this
method.

In addition to transferring the specified part, this method logs a part transaction
record. The part transaction record stores information about the transaction for the
part history.

Parameters This method uses the following parameters:

Parameter Type Description

partRec Record Specify a view of type "partnum_view". This view identifies the
part to transfer.
quantity Long Specify the quantity to transfer.
serialNo String Specify the serial number of the part. This parameter is used
only for parts that require a serial number. If the part is tracked
by quantity or serial numbers are assigned dynamically, this
parameter is ignored.
fromBin Long Specify the object ID of the source inventory bin. The part is
removed from this bin.
toBin Long Specify the object ID of the destination inventory bin. The part
is transferred to this bin.
refId String Specify a reference number to associate with the transaction.
Specify a maximum of 19 bytes of information.
notes String Specify any notes you want to associate with the transfer.
Specify a maximum of 59 bytes of information.

TransferPart 69
ClearBasic Object Reference
 App object

Parameter Type Description

fromStatus Long Specify one of the following values to indicate the status of the
item in the "From" bin:
Value Status
0 Good
1 Bad
toStatus Long Specify one of the following values to indicate the status of the
item in the "To" bin:
Value Status
0 Good
1 Bad
transactionType Long Specify one of the following values to indicate the type of the
transaction:
Value Transaction type
1 Fulfill
2 Receive
3 Remove
4 Transfer
5 Install
6 Reconcile inventory
transactionId String Specify a String variable. On return, this variable contains the
transaction ID.

Return Values Returns a Long integer indicating the success of the operation. If this value is 0, the
method completed successfully. A non-zero value indicates an error occurred.

See Also CLTransition method

70 TransferPart
ClearBasic Object Reference
 App object

method UseClarifyDB

Syntax RetValue = App.UseClarifyDB (Remote_ClarifyDB)

Applies To App

Description The UseClarifyDB method changes the current database for the session. You can
use this method to switch to a remote database to perform some operation on that
database. Before calling this method, you must create a new ClarifyDB object and
establish a connection to the desired database.

NOTE: Do not use this method to switch the default database; use the UseClarifyDB
method instead.

Switching to a different database does not close the connection to the previous
database. If the previous database was a remote database, you do not need to close its
connection until you are completely finished using that database. You must not close
the connection to the current session’s default database. The system closes the default
database when the user logs out.

Parameters This method requires the following parameter:

Parameter Type Description

RemoteClarifyDB ClarifyDB Specify the remote database object you want to access. The
database must have the same schema version as the default
database for the current session. See the ClarifyDB object on
page 151 for more information.

Return Values Returns 0 if the operation succeeds or 1 if the operation fails.

Example The following example illustrates the use of the UseClarifyDB method:
Sub SwitchDB
Dim RemClarifyDB As New ClarifyDB
Dim RetVal As Long

RetVal = App.UseClarifyDB (RemClarifyDB)

If RetVal = 0 Then
App.MsgBox "Switching to the remote _
database was successful. The current _
database is now" + _
RemClarifyDB.DataBaseName
Else
'That is, if RetVal is one
App.Msg "Switching to the remote database _
was unsuccessful."

UseClarifyDB 71
ClearBasic Object Reference
 App object

End If

'Additional code goes here

End Sub

See Also GetCurrentDB method

UseDefaultDB method
ClarifyDB object

72 UseClarifyDB
ClearBasic Object Reference
 App object

method UseDefaultDB

Syntax RetValue = App.UseDefaultDB

Applies To App

Description The UseDefaultDB method restores the default database as the current database.
Use this method after one or more calls to UseClarifyDB to reinstate the default
database as the current database.

This method does not close any previous database connections. When you are done
with the remote database, you must use the methods of the ClarifyDB object to close
the connection.

Parameters None

Return Values Returns a Long integer value of 0 if the operation succeeds or 1 if the operation fails.

Example The following example illustrates the use of the UseDefaultDB method:
Sub Switch2DefaultDB
Dim RetVal As Long

RetVal = App.UseDefaultDB

If RetVal = 0 Then
App.MsgBox "Switching to the default _
database was successful."
Else
'That is, if RetVal is one
App.Msg "Switching to the default database _
was unsuccessful."
End If

'Additional code goes here

End Sub

See Also GetCurrentDB method

UseClarifyDB method
ClarifyDB object

UseDefaultDB 73
ClearBasic Object Reference
 App object

method ValidateUser

Syntax ValidUser = App.ValidateUser (UserLogin, Password, Timeout)

Applies To App

Description The ValidateUser method returns a boolean value indicating whether the specified
user is valid. This method verifies that the specified user login and password exist in
the database.

You can use this method on any user login except the “sa” account. If you specify “sa”
for the UserLogin parameter, this method returns False regardless of the password
you specify. This is a security feature to prevent the system administrator password
from being identified.

Parameters This method requires the following parameter:

Parameter Type Description

UserLogin String Specify the login name of the user you want to validate.
Password String Specify the unencrypted password associated with the
specified user’s account. This method encrypts the
password before sending it to the database.
Timeout Long Specify the number of seconds to wait for a response.
This parameter is optional and is set to 5 seconds by default.

Return Values Returns True if the user login and password are valid, otherwise False. This method
always returns False for the “sa” user login. This method also returns False if the
timeout value is reached before a response is received from the database.

See Also UserName property

74 ValidateUser
ClearBasic Object Reference
 App object

property CurrentDate

Syntax DateSetting = App.CurrentDate

Applies To App

Description The CurrentDate property contains a string with the current system date and time.
The format of the string is determined by the current CLOCK_MODE setting, which
you set in the clarify.env file or using a config_itm. This setting may indicate the local
workstation time, the server time, or a synchronization between the server and
workstation.

This property is read-only.

NOTE: For more information on the CLOCK_MODE setting, see the System Administration
Guide.

For more information on using this and similar properties, see the chapter in the
ClearBasic Programmer’s Guide titled Handling Date and Time.

CurrentDate 75
ClearBasic Object Reference
 App object

property DatabaseName

Syntax YourChar = App.DatabaseName

Applies To App

Description The Database property contains the name of the current database. This is the default
database the application uses when retrieving data.

This property is read-only.

76 DatabaseName
ClearBasic Object Reference
 App object

property EmployeeObjId

Syntax EmployeeID = App.EmployeeObjId

Applies To App

Description The EmployeeObjId property contains a Long integer that uniquely identifies the
user currently logged into the database. This unique ID corresponds to the object ID of
the employee record for that user.

This property is read-only.

EmployeeObjId 77
ClearBasic Object Reference
 App object

property EXEName

Syntax ApplicationName = App.EXEName

Applies To App

Description The EXEName property contains a string with the name of the currently-running
ClarifyCRM application.

Example In the following code snippet, a message box is posted if the ClearSupport application
is not running when the code is executed:

ReturnString = App.ExeName

If RetString <> "Clarify" Then

App.MsgBox "Clarify is not running"
End If

78 EXEName
ClearBasic Object Reference
 App object

property QuerySize

Syntax App.QuerySize = BlocksPerRoundTrip

BlocksPerRoundTrip = App.QuerySize

Applies To App

Description The QuerySize property contains a Long integer indicating the number of blocks
available for specifying a query. By default, this property is set to 10 blocks but you
can modify this value as needed.

The queries contained in a BulkRetrieve object are translated into SQL statements
before they are sent to the database. Depending on the number and type of queries,
the amount of SQL statements that is generated can be quite large. If the number of
generated SQL statements do not fit into the 10 blocks (default allocation) of client
memory, the application will encounter a runtime error. By allocating a larger number
of blocks, you can accommodate larger number of SQL statements.

Remember, however, that the database platforms, such as Oracle or Sybase, place
limits on the number of incoming blocks of SQL statements that can be serviced. So,
depending on the average number of SQL statements, the ideal number of blocks for
the QuerySize must lie somewhere between 10 and the maximum acceptable to the
database.

NOTE: If you set QuerySize to a value greater than that acceptable to the database, the
application will encounter a runtime error.

Because all this activity is carried out by the ClarifyCRM system, it is entirely
transparent and you do not have to change anything in your ClearBasic code except
for setting the QuerySize property, if necessary.

Settings This method accepts the following values:

Setting Description
BlocksPerRoundTrip Required. You must specify the number (positive integer) of "blocks"
into which the SQL statements from the BulkRetrieve queries are
placed. The parameter is called BlocksPerRoundTrip because each set
of blocks containing statements requires a separate round trip.
For most purposes, the value 25 is optimal and is recommended.
You can reset the parameter to its default value by setting QuerySize
to 10, 0, or -1.

Comments You can set this property once in initialize_app to put it into effect for all
BulkRetrieve operations. Or, you can set this property in form modules to selectively
change its setting. Once this property is set, it remains in effect until it is set again.

QuerySize 79
ClearBasic Object Reference
 App object

You can also set the QuerySize property to any value by setting the environment
variable MAX_PER_BATCH to that value in the clarify.env file. Note, however,
that the value set by any ClearBasic code overrides the value specified for
MAX_PER_BATCH.

80 QuerySize
ClearBasic Object Reference
 App object

property ServerName

Syntax YourChar = App.ServerName

Applies To App

Description The ServerName property contains a string with the name of the current database
server. Normally, this property contains the server name of the default database.
However, if you use the UseClarifyDB method to change the current database, this
property contains the server name of the remote database.

This property is read-only.

See Also UseClarifyDB method

ServerName 81
ClearBasic Object Reference
 App object

property UserName

Syntax App.UserName

Applies To App

Description The UserName property contains a string with the name of the user currently logged
into the ClarifyCRM client application.

This property is read-only.

Example In the following example, the current user name is passed to the AppendFilter
method. The filter limits the set of returned records to those whose login_name field
contains the name of the current user.
Dim userName as String
Dim bulkGet as New BulkRetrieve

userName = App.UserName
Debug.print "userName=", username

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", _
cbEqual, userName
BulkGet.RetrieveRecords

82 UserName
ClearBasic Object Reference
 App object

property UserObjId

Syntax App.UserObjId

Applies To App

Description The UserObjId property contains a long integer with the object ID of the user
record corresponding to the current user. This is the user who is currently logged into
the ClarifyCRM client application.

This property is read-only.

UserObjId 83
ClearBasic Object Reference
 App object

84 UserObjId
ClearBasic Object Reference
 AppMenu object

Overview The AppMenu object provides an interface for manipulating the application menus.
Using this object, you can add new menu items or change the behavior of existing
menu items. You can also enable or disable specific menu items.

Typically, the Initialize_App global subroutine is where you set up the menubars
for your applications. The system calls this subroutine at startup to give your
application an opportunity to execute any customization code. However, you are not
limited to modifying menus only at startup time. You may use the AppMenu object at
any time during the current session to modify the menus.

Menu Structure Each ClarifyCRM application has its own menubar and set of pulldown menus. You
can add menu items to existing menu bars or rename existing menu items and change
their functionality. When you add new menu items, they are always added to the end
of the pulldown menu. You cannot create an entirely new pulldown menu.
Each menubar is distinct, so changes to one menubar do not affect the others. For
example, to add a new item to the Desktop menu in three applications, you must
create three instances of the AppMenu object, one for each application. Using those
objects, you must then add the menu item to the Desktop menu of each menubar.

Modifying Menus When you want to modify an application’s menubar, you must first create a new
instance of the AppMenu object. After creating this object, specify which menubar you
want to work on by assigning the appropriate menubar ID to the MenuBarID
property of the object. You may then call any other methods to modify the menus of
that menubar.

NOTE: You should create a separate AppMenu object for each menubar you want to modify.

Before adding any custom menu items to a menubar, you may want to add a
separator line to distinguish your custom items from any existing items. You can use
the AddSeparator method to add separator lines to pulldown menus. The AddItem
method lets you add custom menu items to the end of the menu.

After you have finished making all of your modifications, you must tell the
application to display those changes. The ShowDefaultMenu method of the App
object applies any changes to the current set of menus. Call this method immediately
after making your changes.

ClearBasic Object Reference 85

 AppMenu object

Methods This object defines the following methods:

■ AddItem method
■ AddSeparator method
■ CheckItem method
■ Enable method
■ IsEnabled method
■ IsItemChecked method
■ RemoveItem method
■ RenameItem method
■ SetFunction method
■ Show method

Properties This object defines the following property:

■ MenuBarId property

86
ClearBasic Object Reference
 AppMenu object

method AddItem

Syntax YourAppMenu.AddItem MenuName, ItemName, EventProcedure

Applies To AppMenu

Description The AddItem method adds a menu item to the end of the specified pulldown menu.
When chosen at runtime, the menu item triggers the Click event handler for the
specified procedure.

This method modifies the pulldown menu of the current menubar. Before calling this
method, you must specify the current menubar by assigning the appropriate ID to the
MenuBarID property of the AppMenu object.

After you have finished making changes to the application menubars, call the
ShowDefaultMenu method of the App object. You need to call ShowDefaultMenu
only once to show all of your menu changes.

IMPORTANT: You cannot use this method on the File or Windows pulldown menus.

Parameters The AddItem method accepts the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu to which you want to
append the menu item. This name must correspond to an existing
pulldown menu on the current menubar.
You cannot add menu items to the File or Windows pulldown
menus.
ItemName String Specify the menu-item label you want displayed in the pulldown
menu. You can use this string in subsequent method calls to
identify the menu item.
EventProcedure String Specify the name of the event procedure to call when the menu
item is selected. When the menu item is chosen, a corresponding
Click event for the event procedure is generated.
For example, if you specify the string "YourEvent" for this
parameter, the application calls the YourEvent_Click event
handler when the menu item is selected.

Return Values None

AddItem 87
ClearBasic Object Reference
 AppMenu object

Example The following code illustrates the use of the AddItem method. The menu item
TestWindow is added to (and subsequently displayed in) the Actions pulldown of
the ClearSupport menu. When this item is selected by the user, the event procedure
DoThis_Click is invoked.
Sub initialize_app
Dim CS_bar As New Appmenu

' ID 1002 is the ClearSupport menubar

CS_bar.MenuBarID = 1002
CS_bar.AddItem "Actions", "TestWindow",
"DoThis"

App.ShowDefaultMenu
End Sub

Sub DoThis_Click
App.MsgBox "Test window chosen!"
End Sub

See Also RemoveItem method

RenameItem method
SetFunction method
MenuBarId method
ShowDefaultMenu method (App object)

88 AddItem
ClearBasic Object Reference
 AppMenu object

method AddSeparator

Syntax YourAppMenu.AddSeparator MenuName

Applies To AppMenu

Description The AddSeparator method adds a separator line to the end of the specified
pulldown menu. You can use separators to visually group related menu items on a
pulldown menu. Separator lines are always disabled and therefore cannot be selected.

This method modifies the pulldown menu of the current menubar. Before calling this
method, you must specify the current menubar by assigning the appropriate ID to the
MenuBarID property of the AppMenu object.

After you have finished making changes to the application menubars, call the
ShowDefaultMenu method of the App object. You need to call ShowDefaultMenu
only once to show all of your menu changes.

Parameters The method accepts the following parameter:

Parameter Type Description

MenuName String Specify the name of the pulldown menu to which you want to
append the separator line. This name must correspond to an
existing pulldown menu on the current menubar.
You cannot add menu items to the File or Windows pulldown
menus.

Return Values None

Example The following code fragment adds several menu items and separator lines to the Edit
menu of the ClearSupport menubar.
Dim MyAppMenu New As Appmenu

' ID 1002 is the ClearSupport menubar

MyAppMenu.MenuBarID = 1002

‘In the Edit pulldown menu, add the Undo command

MyAppMenu.AddItem "Edit", "Undo", "Revert"

‘Insert a separator
MyAppMenu.AddSeparator "Edit"

‘Add couple of more commands

MyAppMenu.AddItem "Edit", "Cut", "Remove"
MyAppMenu.AddItem "Edit", "Paste", "Insert"

AddSeparator 89
ClearBasic Object Reference
 AppMenu object

‘Insert another separator separator

MyAppMenu.AddSeparator "Edit"
App.ShowDefaultMenu

See Also AddItem method

RemoveItem method
RenameItem method
SetFunction method
MenuBarId method
ShowDefaultMenu method (App object)

90 AddSeparator
ClearBasic Object Reference
 AppMenu object

method CheckItem

Syntax YourAppMenu.CheckItem MenuName, ItemName, State

Applies To AppMenu

Description The CheckItem method displays or hides the checkmark for the specified menu
item. Typically, you use this method in conjunction with the IsItemChecked
method to toggle the display of the checkmark for a given menu item. You can also
use this method to set the initial state of the checkmark in your Initialize_App
routine.

Parameters The method accepts the following parameter:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the desired
menu item. This name must correspond to an existing pulldown
menu on the current menubar.
ItemName String Specify the name of the menu item. This name is the same as the
menu-item text displayed in the pulldown menu.
State Boolean Specify True to display a checkmark next to the menu item;
otherwise specify False to hide the checkmark.

Return Values None

Example See the example for the IsItemChecked method.

See Also IsItemChecked method

CheckItem 91
ClearBasic Object Reference
 AppMenu object

method Enable

Syntax YourAppMenu.Enable MenuName, ItemName, State

WasSuccessful = YourAppMenu.Enable (MenuName, ItemName, State)

Applies To AppMenu

Description The Enable method modifies the enable state of the specified menu item. You use
this method to enable or disable a menu item. Enabled menu items may be selected by
the user to trigger the designated action. Disabled menu items appear grayed out on
the pulldown menu and cannot be selected.

This method modifies the pulldown menu of the current menubar. Before calling this
method, you must specify the current menubar by assigning the appropriate ID to the
MenuBarID property of the AppMenu object.

Parameters This method accepts the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the desired
menu item you want to enable or disable. This name must
correspond to an existing pulldown menu on the current
menubar.
ItemName String Specify the name of the menu item as displayed in the pulldown
menu.
State Boolean Specify True to enable the menu item, otherwise False to disable
the item.

Return Values Returns True if the state of the menu item was successfully changed, otherwise False
to indicate no change occurred. This method returns False if the item was already in
the requested state.

Example The following code fragment disables the Cut menu item in the Edit menu.
MyAppMenu.Enable "Edit", "Cut", False

See Also AddItem method

IsEnabled method
MenuBarId method

92 Enable
ClearBasic Object Reference
 AppMenu object

method IsEnabled

Syntax RetBoolean = YourAppMenu.IsEnabled (MenuName, ItemName)

If YourAppMenu.IsEnabled (MenuName, ItemName) Then
...

Applies To AppMenu

Description The IsEnabled method returns a boolean value indicating whether or not the
specified menu item is enabled. Enabled menu items may be selected by the user to
trigger the designated action. Disabled menu items appear grayed out on the
pulldown menu and cannot be selected.

Before calling this method, you must specify the current menubar by assigning the
appropriate ID to the MenuBarID property of the AppMenu object.

Parameters This method accepts the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the desired menu
item. This name must correspond to an existing pulldown menu on
the current menubar.
MenuItem String Specify the name of the menu item. This name is the same as the
menu-item text displayed in the pulldown menu.

Return Values Returns True if the menu item is enabled, otherwise False.

Example The following code fragment illustrates the use of the IsEnabled method:
‘Enable the "Paste" menu item.
Result = CurrentMenu.IsEnabled ("Edit", "Paste")

If (Result = False) Then

CurrentMenu.Enable "Edit", "Paste", True
End If

You can also write the above code as follows:

If (CurrentMenu.IsEnabled ("Edit", "Paste") _
= False) Then
CurrentMenu.Enable "Edit", "Paste", True
End If

See Also Enable method

IsEnabled 93
ClearBasic Object Reference
 AppMenu object

method IsItemChecked

Syntax RetBoolean = YourAppMenu.IsItemChecked (MenuName, ItemName)

Applies To AppMenu

Description The IsItemChecked method returns a boolean value indicating whether the
specified menu item has a checkmark next to it. Typically, you use this method in
conjunction with the CheckItem method to toggle the display of the checkmark for a
given menu item. You can also use this method to get the initial state of the checkmark
at any time.

Parameters This method accepts the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the desired menu
item. This name must correspond to an existing pulldown menu on
the current menubar.
ItemName String Specify the name of the menu item. This name is the same as the
menu-item text displayed in the pulldown menu.

Return Values Returns True if the menu item has a checkmark next to it, otherwise False.

Example The following example implements a menu event handler for a menu item with a
checkmark. In this event handler, the state of the checkmark is toggled whenever the
user selects the menu item.
Sub MySettingHandler_Click
Dim curMBar As New Appmenu

' ID 1002 is the ClearSupport menubar

curMBar.MenuBarID = 1002
If curMBar.IsItemChecked("Actions", "My Setting") Then
curMBar.CheckItem "Actions", "My Setting", False
Else
curMBar.CheckItem "Actions", "My Setting", True
End If
End Sub

See Also CheckItem method

94 IsItemChecked
ClearBasic Object Reference
 AppMenu object

method RemoveItem

Syntax AppMenu.RemoveItem MenuName, ItemName

Applies To Appmenu

Description The RemoveItem method removes the specified menu item from the pulldown
menu. You can use this method to remove both custom menu items and items from
the baseline menus.

This method modifies the pulldown menu of the current menubar. Before calling this
method, you must specify the current menubar by assigning the appropriate ID to the
MenuBarID property of the AppMenu object.

After you have finished making changes to the application menubars, call the
ShowDefaultMenu method of the App object. You need to call ShowDefaultMenu
only once to show all of your menu changes.

Parameters This method accepts the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the menu
item you want to remove. This name is case sensitive and must
correspond to an existing pulldown menu on the current
menubar.
ItemName String Specify the name of the menu item you want to remove. This
name is the same as the menu-item text displayed in the
pulldown menu and is case-sensitive.

Return Values None

See Also AddItem method

MenuBarId property
ShowDefaultMenu method (App object)

RemoveItem 95
ClearBasic Object Reference
 AppMenu object

method RenameItem

Syntax AppMenu.RenameItem MenuName, ItemName, NewName

Applies To AppMenu

Description The RenameItem method replaces the text of an existing menu-item text with the
new text you specify. This method changes both the text displayed in the menu and
the way you refer to the item in subsequent method calls. After calling this method,
any additional changes must identify the menu item using the new name. This
method does not change the event procedure associated with the menu item.

This method modifies the pulldown menu of the current menubar. Before calling this
method, you must specify the current menubar by assigning the appropriate ID to the
MenuBarID property of the AppMenu object.

After you have finished making changes to the application menubars, call the
ShowDefaultMenu method of the App object. You need to call ShowDefaultMenu
only once to show all of your menu changes.

Parameters This method accepts the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the menu
item you want to rename. This name is case sensitive and must
correspond to an existing pulldown menu on the current
menubar.
ItemName String Specify the name of the menu item you want to rename. This
name is the same as the menu-item text displayed in the
pulldown menu and is case-sensitive.
NewName String Specify the new name of the menu item.

Return Values None

See Also AddItem method

RemoveItem method
MenuBarId property

96 RenameItem
ClearBasic Object Reference
 AppMenu object

method SetFunction

Syntax AppMenu.SetFunction MenuName, ItemName, EventProcedure

Applies To AppMenu

Description The SetFunction method associates a new event procedure with an existing menu
item. You can use this method to redefine the behavior of existing ClarifyCRM menu
items or change the event procedure associated with your custom menu items.

The EventProcedure parameter contains the base name of your event handler. The
actual name of your event handler should be comprised of this base name plus the
suffix _Click. For example, if you specify the string "MyHandleItem" for the
EventProcedure parameter, ClarifyCRM would expect your event handler to be called
MyHandleItem_Click.

This method modifies the pulldown menu of the current menubar. Before calling this
method, you must specify the current menubar by assigning the appropriate ID to the
MenuBarID property of the AppMenu object.

After you have finished making changes to the application menubars, call the
ShowDefaultMenu method of the App object. You need to call ShowDefaultMenu
only once to show all of your menu changes.

IMPORTANT: If you are changing the event procedure for the "Exit" menu item do not call the
App.DoDefault method. Instead, call App.ExitApp at the end of your subroutine. The
ExitApp method properly shuts down the ClearBasic engine before exiting the application.

Parameters This method requires the following parameters:

Parameter Type Description

MenuName String Specify the name of the pulldown menu containing the menu
item whose event procedure you want to change. This name is
case sensitive and must correspond to an existing pulldown
menu on the current menubar.
ItemName String Specify the name of the menu item whose event procedure you
want to change. This name is the same as the menu-item text
displayed in the pulldown menu and is case-sensitive.
EventProcedure String Specify the name of the event procedure to call when the menu
item is selected. When the menu item is chosen, a
corresponding Click event for the event procedure is generated.
For example, if you specify the string "YourEvent" for this
parameter, the application calls the YourEvent_Click event
handler when the menu item is selected.

Return Values None

SetFunction 97
ClearBasic Object Reference
 AppMenu object

See Also AddItem method

RenameItem method

98 SetFunction
ClearBasic Object Reference
 AppMenu object

method Show

Syntax AppMenu.Show

Applies To AppMenu

Description The Show method displays the menubar associated with this object. In general, you
should use the ShowDefaultMenu method instead of this method to show the current
menu bar.

Parameters None

Return Values None

See Also ShowDefaultMenu method (App object)

Show 99
ClearBasic Object Reference
 AppMenu object

property MenuBarId

Syntax YourAppMenu.MenuBarID = Setting

Applies To AppMenu

Description The MenuBarID property contains the ID of the current menubar. You must always
set this property before calling any methods of the AppMenu object.

If you do not set this property, you can experience unexpected results. The menubar
of each ClarifyCRM application contains several pulldown menus with the same
names as those on other menubars. If you forget to set this property, you may change
the menu items on the wrong menubar.

You may set this property to one of the following values:

ID ClarifyCRM Application
1000 Startup menubar
1001 Policies and Customers
1002 ClearSupport/ClearHelpDesk
1005 Product Manager
1007 ClearLogistics
1008 ClearQuality
1011 ClearContracts
1012 ClearSales
1013 ClearCallCenter

Example The following code shows the declaration of two AppMenu objects: one for
ClearSupport, the other for ClearQuality. In each of these menubars, the menu item
LogNotes is removed from the Actions pulldown menu.
Sub Initialize_App
Dim CS_bar New AppMenu
Dim CQ_bar New AppMenu

CS_bar.MenuBarId = 1002
CS_bar.RemoveItem "Actions", "Log Notes"
CQ_bar.MenuBarId = 1008
CQ_bar.RemoveItem "Actions", "Log Notes"

App.ShowDefaultMenu
End Sub

100 MenuBarId
ClearBasic Object Reference
 BulkRetrieve object

Description The BulkRetrieve object retrieves records from database tables and views. You use
this method to search the database for records that match the filter criteria you specify.
The returned records are sorted according to the sort criteria you specify.

You can use the BulkRetrieve object to perform multiple queries simultaneously.
Grouping queries together reduces the number of round trips to the database and
generally improves performance. You specify the filters and sort criteria for each
query using the methods of BulkRetrieve.

IMPORTANT: You may need to use the QuerySize property (for the App object) if the
BulkRetrieve object contains multiple queries. See the QuerySize on page 79 for more
information.

Whenever you want to perform a new query, create a new instance of the
BulkRetrieve object. You declare a BulkRetrieve object in your event procedure
as follows:
Dim YourBulkRetrieve As New BulkRetrieve

Query Types The BulkRetrieve object supports three types of queries:

■ simple queries
■ root traversal queries
■ parent traversal queries

A simple query retrieves records from a single database table or view. The query
returns the records only in the specified table or view. It does not retrieve any related
records. Use the SimpleQuery method to add a simple query to the BulkRetrieve
object.

A root traversal query searches a relation of a specified record. The query returns any
records that are linked to the root record through the specified relation. Use the
SetRoot or SetRootById methods to specify the root record. Use the
TraverseFromRoot method to add a root traversal query to the BulkRetrieve
object.
A parent traversal query is similar to a root traversal query except that it can operate
on more than one root record. This query type uses an existing query to specify one or
more root records. For each root record, the query retrieves the list of records that are
linked to the root record through the specified relation. Use the
TraverseFromParent method to add a parent traversal query to the
BulkRetrieve object.

Adding Filter and Filters let you compare a field from the target record to a designated value. You can
Sort Criteria add one or more filters to each query in the BulkRetrieve object. Use the
AppendFilter method to add a new filter to a single query.

ClearBasic Object Reference 101

 BulkRetrieve object

For each query, you can add sort criteria to the query to determine the order in which
the records are returned. The sort criteria you add are applied in the order you add
them. Use the AppendSort method to add a new sort criteria to a single query.

Performing Queries Once you have created the desired queries, along with any filter and sort criteria, use
the RetrieveRecords method to execute the queries. The RetrieveRecords
method executes the queries in order, returning the result sets to the BulkRetrieve
object. You can use the GetRecordList and GetRelatedRecordList methods to
retrieve a list of the records returned by the query.

Methods This object defines the following methods:

■ AppendFilter method
■ AppendSort method
■ Clear method
■ EntryCount method
■ GetRecordList method
■ GetRelatedRecordList method
■ Print method
■ RetrieveRecords method
■ SetRootById method
■ SetRoot method
■ SimpleQuery method
■ TraverseFromParent method
■ TraverseFromRoot method

102
ClearBasic Object Reference
 BulkRetrieve object

method AppendFilter

Syntax YourBulkRetrieve.AppendFilter EntryIndex, "fieldname",

Operator, Value

Applies To BulkRetrieve

Description The AppendFilter method appends one filter condition to the specified query in a
BulkRetrieve object. If you want to append more than one filter condition, you
must use this method once for each condition you want to append.

CAUTION: You must specify the field name as specified in the data dictionary. This parameter
is case sensitive and will generate an error if supplied incorrectly.

Appending several conditions. If you append several filter conditions to a single

query, all of the appended filter conditions are ANDed together when the
RetrieveRecords method is executed.

Functional equivalency to OR. The AppendFilter method does not allow you to
use OR. However, you can achieve the same result as using OR by using this method
as follows:
YourBulkRetrieve.AppendFilter EntryIndex, "fieldname", _
cbIn, ValueList
where ValueList is the list you already created and filled with the integer, string, or
float values you want. The result is the same as if you had ORed conditions with those
values.

IMPORTANT: All of the filter conditions appended to a query are ANDed together when the
RetrieveRecords method is executed. The OR operator is not supported.

Parameters This method accepts the following parameters:

AppendFilter 103
ClearBasic Object Reference
 BulkRetrieve object

Parameter Type Description

EntryIndex Long Specify the BulkRetrieve entry index (or name) associated with
String the query you want to filter. This is the index (or name) you
associated with the query when you created it using the
SimpleQuery, TraverseFromRoot, or TraverseFromParent method.
FieldName String Specify the name of the field you want to use in the filter. This
parameter is case sensitive and the field name must be defined in
the data dictionary.
Operator Long Specify a comparison operator to use when comparing the specified
field and value. You may specify one of the following constants:
cbEqual
cbNotEqual
cbGreater
cbGreaterOrEqual
cbLess
cbLessOrEqual
cbLike
cbNotLike
cbSoundsLike
cbIn
Value Long Specify the value to compare the field against. The type of the value
Short you specify must match the type of the field in the FieldName
String parameter.
Double For most operators, you specify a single value; however, if you
Float create a filter with the cbIn operator, you may specify a list of
values.
cbIn only
List

Return Values None

Example In this example, a filter condition is appended to the query at the bulkGet entry
index of 0. It specifies the retrieval of only those database records of type user whose
field Login_name contains userName.
Dim userName As String
Dim bulkGet As New BulkRetrieve

userName = App.UserName
BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", _
cbEqual, UserName
BulkGet.RetrieveRecords

See Also AppendSort method

SimpleQuery method

104 AppendFilter
ClearBasic Object Reference
 BulkRetrieve object

method AppendSort

Syntax YourBulkRetrieve.AppendSort EntryIndex, "fieldname", SortOrder

Applies To BulkRetrieve

Description The AppendSort method specifies a sorting order for a record field and appends this
sort condition to the specified query in the BulkRetrieve object. If you want to sort
several fields in a particular order for a given query, you need to use this method once
for each field.

CAUTION: You must specify the field name as used in the data dictionary.This parameter is
case sensitive and will generate an error if supplied incorrectly.

You can use this method several times if you want to append several sort fields to a
single query: in this case the sort fields are applied in the order the are appended.

Parameters The method accepts the following parameters:

Parameter Type Description

EntryIndex Long You must specify the entry index (or name) associated with the query
String you want to sort.
fieldname String You must specify the name of the field that you want sorted as it
appears in the data dictionary. This parameter is case sensitive.
SortOrder Long To sort in ascending order, specify the constant cbAscending
To sort in descending order, specify the constant cbDescending

Return Values None

Example In the following example, AppendSort is used after a simple query. The sort condition
it specifies is that the field title is sorted in ascending order.
Dim BulkGet As New BulkRetrieve

BulkGet.SimpleQuery 0, "case"
BulkGet.AppendSort 0, "title", cbAscending
BulkGet.RetrieveRecords

See Also AppendFilter method

SimpleQuery method

AppendSort 105
ClearBasic Object Reference
 BulkRetrieve object

method Clear

Syntax YourBulkRetrieve.Clear

Applies To BulkRetrieve

Description The Clear method removes the contents of the BulkRetrieve object. This method
removes the current set of filters, sort criteria, and result sets.

Parameters None

Return Values None

106 Clear
ClearBasic Object Reference
 BulkRetrieve object

method EntryCount

Syntax YourRetInt = YourBulkRetrieve.EntryCount

For i = 0 to YourBulkRetrieve.EntryCount -1

Applies To BulkRetrieve

Description The EntryCount method returns the total number of entries in the BulkRetrieve
object.

The number returned represents the number of queries in the BulkRetrieve object,
because there is a one to one correspondence between the number of entries and the
number of queries in the BulkRetrieve object.
The number also represents the number of lists returned in the BulkRetrieve object
after the RetrieveRecords method is invoked. Each query returns a list (sometimes
an empty list) of records that is stored at the same entry index (or entry name) that
was occupied by the query.

Parameters None

Return Values This method returns an integer value representing the number of entries in the
BulkRetrieve object.

EntryCount 107
ClearBasic Object Reference
 BulkRetrieve object

method GetRecordList

Syntax Set YourList = YourBulkRetrieve.GetRecordList (EntryIndex,

Options)

Applies To BulkRetrieve

Description The GetRecordList method returns the list of records in the BulkRetrieve object
that was returned by the query (SimpleQuery or TraverseFromRoot) associated
with the specified entry index (or name).

You use this method where there is only one list residing at the entry index, which is
the case with SimpleQuery and TraverseFromRoot returns. You cannot use this
method where multiple lists reside at the index, which can be the case with
TraverseFromParent queries: use GetRelatedRecordList instead in this case.

Parameters This method accepts the following parameters:

Parameter Type Description

EntryIndex Long Specify the index (or name) of the entry in the BulkRetrieve object
String that contains the list of records. The integer or string value you specify
must match the one you associated with the query when you created
the query.
Options Long An optional parameter. If you do not specify this parameter, the
default is cbByRef.
Specify cbByValue if you want each record returned to the list to be a
separate copy of the corresponding record in the BulkRetrieve
object. The copy is a completely separate copy of the original,
including the same objid.
Specify cbByRef if you want each record returned to the list to be the
same record that is in the BulkRetrieve object. This is useful if you
want to update the records in the BulkRetrieve object; you can
change the record in the BulkRetrieve simply by changing the
record that is returned to the list.

Return Values If you specified cbByValue, the list returned by this method contains separate copies
of the specified records in the BulkRetrieve, including the same objid.
If you specified cbByRef (explicitly or by using the default), the list returned by this
method contains the same records that are in the BulkRetrieve. That is, any
changes made to the returned records result in an identical change in the
BulkRetrieve records.

Comments You must load records from the database into the BulkRetrieve object using the
query methods and the RetrieveRecords method before you can use this method
to get a list of records.

108 GetRecordList
ClearBasic Object Reference
 BulkRetrieve object

Return Values This method returns a list of records.

Example In the following example, records of type user are obtained from the database into
BulkGet and are retrieved from BulkGet with the GetRecordList method and
placed into RList. Notice the parameter 0 that is supplied to GetRecordList: this
means that the list of records returned by the query at entry index 0 are placed into
RList.
Dim userName As String
Dim RList As List
Dim bulkGet As New BulkRetrieve

userName = App.UserName

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", cbEqual, _
userName

BulkGet.RetrieveRecords

Set RList = BulkGet.GetRecordList(0)

See Also GetRelatedRecordList method

SimpleQuery method
TraverseFromRoot method
TraverseFromParent method

GetRecordList 109
ClearBasic Object Reference
 BulkRetrieve object

method GetRelatedRecordList

Syntax Set YourList = YourBulkRetrieve.GetRelatedRecordList

(ParentRecord, "RelationName", Options)

Applies To BulkRetrieve

Description The GetRelatedRecordList method returns a list of records from the

BulkRetrieve object, using a parent record and a relation name to point to the list
you want. You must use this method to get any of the multiple lists of records
returned by a TraverseFromParent query. Normally, you would use this in a loop
where the parent records in the parent query are cycled through, to retrieve the list of
related records for each parent record.
You must load records from the database into the BulkRetrieve object using the
query methods and the RetrieveRecords method before you can use this method
to get a list of records.

You must specify a valid relation name. Valid relation names for each database object
type are listed in the Data Dictionary Guide

Parameters This method accepts the following parameters:

Parameter Type Description

ParentRecord Record Specify the (parent) record in the BulkRetrieve object from
which you want to derive the list of related records.
RelationName String Specify the relation name used to traverse from the parent record
to the directly related records in the database. You must specify a
valid relation name. (See the Data Dictionary Guide for a list of valid
relations for each database object type.)
Options Long An optional parameter. If you do not specify this parameter, the
default is cbByRef.
Specify cbByValue if you want each record returned to the list to
be a separate copy of the corresponding record in the
BulkRetrieve object. The copy is a completely separate copy of
the original, including the same objid.
Specify cbByRef if you want each record returned to the list to be
the same record that is in the BulkRetrieve object. This is useful
if you want to update the records in the BulkRetrieve object;
you can change the record in the BulkRetrieve simply by
changing the record that is returned to the list.

Return Values This method returns a list of records.

If you specified cbByValue, the list returned by this method contains separate copies
of the specified records in the BulkRetrieve, including the same object ID.

110 GetRelatedRecordList
ClearBasic Object Reference
 BulkRetrieve object

If you specified cbByRef (explicitly or by using the default), the list returned by this
method contains the same records that are in the BulkRetrieve. That is, any
changes made to the returned records result in an identical change in the
BulkRetrieve records.

Example See the chapter titled Accessing the ClarifyCRM Database, in the ClearBasic
Programmer’s Guide for more information.

See Also GetRecordList method

GetRelatedRecordList 111
ClearBasic Object Reference
 BulkRetrieve object

method Print

Syntax YourBulkRetrieve.Print

UDTs Supported This method supports user defined types.

Applies To BulkRetrieve

Description The Print method prints all the records in each entry index of the BulkRetrieve
object. (It sends the information to the standard output.

This method prints information to the standard output, which varies by platform. On
Unix systems, the standard output can be specified to be a file or device, depending
on your environment. On Windows and Macintosh systems, the standard output is
the file standard.out, which is located in the directory or folder where ClarifyCRM
starts

Parameters None

Return Values None

See Also Printer object

112 Print
ClearBasic Object Reference
 BulkRetrieve object

method RetrieveRecords

Syntax YourBulkRetrieve.RetrieveRecords Options

Applies To BulkRetrieve

Description The RetrieveRecords method performs all of the queries specified in the
BulkRetrieve object and stores the retrieved records in the BulkRetrieve object.

If the Options parameter is not specified and more than record has the same record
objid, this method retrieves the first such record and discards all other records that
have same objid.

On the other hand, if you specify cbIgnoreDups for the Options parameter and
more than one record has the same record objid, this method retrieves all occurrences
of such records with actual values in their individual fields. The field values in these
records may or may not be identical.

Parameters This method accepts the following parameter:

Parameter Type Description

Options Long This parameter is optional.
Specify cbIgnoreDups to retrieve all records, even records that have
duplicate object IDs.
If this option is omitted, only the first record from the records that
have the same objid is retrieved. All other records with the same objid
are discarded.

Return Values None

Example In the following example, the RetrieveRecords method is invoked on MyBulk to

obtain the records specified in the SimpleQuery. Since the cbIgnoreDups option is
specified, the records that have identical record objid are treated as unique records
and actual values from these records are retrieved.
Sub Form_Load
Dim Clist As New list
Dim MyBulk As New BulkRetrieve
Dim ListCount As String

'In the next statement, "xx_mod_sec_type_def" is

'a previously defined record type, or view.
MyBulk.SimpleQuery 0, "x_mod_sec_type_def"
MyBulk.RetrieveRecords cbIgnoreDups
Set Clist = MyBulk.GetRecordList(0)

RetrieveRecords 113
ClearBasic Object Reference
 BulkRetrieve object

ListCount = str$(Clist.count)

Debug.Print " List Count: " & ListCount

End Sub

Assuming the retrieved records contained fields x_def_objid and x_def_name,

depending on whether the cbIgnoreDup option was specified or not, the count of
records retrieved could be different, as shown and explained below.

The following is an example of records retrieved when the cbIgnoreDups option was
used. Notice that the objid of the first two records is identical but the field values are
different.
objid x_def_objid x_def_name
268435461 268435484 Book
268435461 268435483 Entry Line
268435472 268435478 Scheduled Time

The following is an example of records retrieved when the cbIgnoreDups option was
not used. Notice that only two records are retrieved. The second record shown in the
example above is discarded because its objid was identical to objid of the first record.
objid x_def_objid x_def_name
268435461 268435484 Book
268435472 268435478 Scheduled Time

114 RetrieveRecords
ClearBasic Object Reference
 BulkRetrieve object

method SetRoot

Syntax YourBulkRetrieve.SetRoot RootRecord

Applies To BulkRetrieve

Description The SetRoot method sets the root record for a BulkRetrieve object. The root
record specified by this method must be locally available (that is, the record must be
retrieved from the database before it can be used as root record). Once you specify the
root record, it is used by all subsequent TraverseFromRoot queries in the specified
BulkRetrieve object.

You can use this method or the SetRootById method to set the root record for the
BulkRetrieve object. To use this method, you must supply a record as the
parameter. To use SetRootById, you don’t supply a record, but you must supply the
object type and object ID of the root record.

Parameters This method accepts the following parameter.

Parameter Type Description

RootRecord Record The database record that you want to use as the root record. This
record must be a permanent database record.

Return Values None

Example In the following example, the database is accessed twice, using the BulkRetrieve
object BulkGet. The first access uses a SimpleQuery to return records, one of which is
subsequently placed into userObj.

The second access uses a TraverseFromRoot query. Notice that the root has been
set (using SetRoot) to userObj, which contains the record retrieved from the database
in the first access.
Dim userName As String
Dim bulkGet As New BulkRetrieve
Dim RList As List
Dim usrObj as Record

userName = App.UserName

'This is the first database access

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", _
cbEqual, userName
BulkGet.RetrieveRecords
set RList = BulkGet.GetRecordList(0)

'Get a record to use As root.

set userObj = RList.ItemByIndex(0)

SetRoot 115
ClearBasic Object Reference
 BulkRetrieve object

'Second database access--first set the

'root record.
BulkGet.SetRoot userObj
BulkGet.TraverseFromRoot 0, "user2dataset"
BulkGet.RetrieveRecords

NOTE: This could be done more efficiently using a TraverseFromParent in the first
retrieve.

See Also SetRootById method

TraverseFromRoot method

116 SetRoot
ClearBasic Object Reference
 BulkRetrieve object

method SetRootById

Syntax YourBulkRetrieve.SetRootById "Type", ObjectId

Applies To BulkRetrieve

Description This method sets the root record for the BulkRetrieve object, using the object type
and object ID that you provide. The root object that you establish, using this method,
is used by all subsequent TraverseFromRoot queries for the specified
BulkRetrieve object.

You can use this method or the SetRoot method to set the root record for the
BulkRetrieve object. To use the SetRoot method, you must supply a record as the
parameter. To use this method, you don’t supply a record, but you must supply the
object type and object ID of the root record

Parameters The method accepts the following parameters:

Parameter Type Description

Type String The type of the root object. The type is case-sensitive.
ObjectID Long The object ID of the root object.

Return Values None

Example Bulkget.SetRootById "user", App.UserObjId

Bulkget.TraverseFromRoot 0, "user2employee"
Bulkget.RetrieveRecords

See Also SetRoot method

TraverseFromRoot method

SetRootById 117
ClearBasic Object Reference
 BulkRetrieve object

method SimpleQuery

Syntax YourBulkRetrieve.SimpleQuery EntryIndex, "Type"

Applies To BulkRetrieve

Description The SimpleQuery method creates an entry in a BulkRetrieve object, associates it

with the specified entry index number, and places a query in that entry. When the
simple query is performed, all of the database records of the type specified in the
simple query are retrieved and placed into a list in the BulkRetrieve. (The list is
located at the entry index used by the query.)

IMPORTANT: If you load multiple queries into a single BulkRetrieve object, you may
need to increase the value in the QuerySize property (App object). See the QuerySize on
page 79 for more information.

Parameters The method accepts the following parameters.

Parameter Type Description

EntryIndex Long The index to be associated with the query.
Type String The object type of the database records to be retrieved by the simple
query.

Comments When you specify entry index values for queries, make sure you assign index values
sequentially to queries in the BulkRetrieve object (using any combination of
SimpleQuery, TraverseFromParent, or TraverseFromRoot methods). Assign
the values sequentially from 0, with 0 assigned to the first query, 1 assigned to the
second query, and so on. Otherwise you’ll get an error at run time.

After you create a simple query using the SimpleQuery method, you can create filter
conditions and sort conditions for the query using the AppendFilter or
AppendSort methods.

Return Values This method returns no values. Although it does retrieve a list of records from the
database and places them in the BulkRetrieve, you must use the GetRecordList
or GetRelatedRecordList methods to get those records out of the
BulkRetrieve object.

118 SimpleQuery
ClearBasic Object Reference
 BulkRetrieve object

Example In the following example, the SimpleQuery method is invoked on BulkGet to obtain
all records of type user. (The appended filter condition narrows this query to those
user records whose field login_name contains userName.) The query is assigned the
BulkGet entry index of 0.
Dim userName As String
Dim bulkGet As New BulkRetrieve

userName = App.UserName

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", _
cbEqual, userName
BulkGet.RetrieveRecords

See Also AppendFilter method

AppendSort method
RetrieveRecords method
TraverseFromRoot method
TraverseFromParent method

SimpleQuery 119
ClearBasic Object Reference
 BulkRetrieve object

method TraverseFromParent

Syntax YourBulkRetrieve.TraverseFromParent EntryIndex, "RelationName",

ParentEntryIndex

Applies To BulkRetrieve

Description The TraverseFromParent method creates a TraverseFromParent query in a

BulkRetrieve object at the specified entry index, using the specified parent query
and relation name. The method retrieves each directly related record that is related by
RelationName to the records retrieved by the parent query.

You use this method if you want to retrieve records that are related by RelationName to
a list of records returned by the parent query. For example, if the parent query returns
a list of case records, you would use this method to retrieve all of the log notes for
each of the case records in the list. (If you expect the parent query to always return
only one record, you might want to use TraverseFromRoot instead.)

Notice that this method can return several lists of records, one list for each parent
record: to access these lists, you must use GetRelatedRecordList, rather than
GetRecordList.

IMPORTANT: If you load multiple queries into a single BulkRetrieve object, you may need to
increase the value in the QuerySize property (App object). See the QuerySize on page 79 for
more information.

In order to use this method, the name or index of the specified parent query must be
an existing entry in the BulkRetrieve object.

When you specify index values for queries, make sure you assign index values
sequentially to queries in the BulkRetrieve object (using any combination of
SimpleQuery, TraverseFromParent, or TraverseFromRoot methods). Assign
the values sequentially from 0, with 0 assigned to the first query, 1 assigned to the
second query, and so on. Otherwise you’ll get an error at run time.

After you create a query using the TraverseFromParent method, you can create
filter conditions and sort conditions for the query using the AppendFilter or
AppendSort methods.

120 TraverseFromParent
ClearBasic Object Reference
 BulkRetrieve object

Parameters This method accepts the following parameters:

Parameter Type Description

EntryIndex Long The index (or name) to be associated with the query.
Short Normally, you should specify an integer value because this
String makes coding easier, but you can use a string value if you
want.
RelationName String The relation name used to traverse from the parent object to
the directly related (child) objects in the database. You must
specify a valid relation name. (See the Data Dictionary Guide
for a list of valid relations for each database object type.)
ParentEntryIndex Long The name or index of the parent query.
Short
String

Return Values This method returns no values. Although it does retrieve a list of records from the
database and places them in the BulkRetrieve object, you must use the
GetRelatedRecordList method to get those records out of the BulkRetrieve
object.

Example The example below illustrates the use of the TraverseFromParent method. Refer to
Chapter 6, Accessing the Database, in the ClearBasic Programmer’s Guide for more
information.
Dim bulkget As New BulkRetrieve
Dim UserList As List
Dim UserRec As Record
Dim emplist As List
Dim empRec As Record

bulkget.SimpleQuery 0, "User"
bulkget.AppendFilter "login_name", cbEqual, _
App.UserName
bulkget.TraverseFromParent 1, "user2employee", 0
bulkget.RetrieveRecords

Set UserList = bulkget.GetRecordList(0)

Set UserRec = UserList.ItemByIndex(0)
Set emplist = bulkget.GetRelatedRecordList _
(UserRec, "user2employee")
Set empRec = emplist.ItemByIndex(0)

See Also GetRelatedRecordList method

RetrieveRecords method
SimpleQuery method
TraverseFromRoot method

TraverseFromParent 121
ClearBasic Object Reference
 BulkRetrieve object

method TraverseFromRoot

Syntax YourBulkRetrieve.TraverseFromRoot EntryIndex, "RelationName"

Applies To BulkRetrieve

Description The TraverseFromRoot method creates a query in a BulkRetrieve object at the

specified entry index. When the query is performed, it retrieves all of the database
records related by RelationName to the root record specified for the BulkRetrieve
object.

Use this method if you only want records related to one root record. If you want
records related to a list of records, use TraverseFromParent.

IMPORTANT: If you load multiple queries into a single BulkRetrieve object, you may need to
increase the value in the QuerySize property (App object). See the QuerySize on page 79 for
more information.

Before using this method, you must use the SetRoot or SetRootByID methods to
specify the record in the BulkRetrieve object to be used as the root record.
When you specify index values for queries, make sure you assign index values
sequentially to queries in the BulkRetrieve object (using any combination of
SimpleQuery, TraverseFromParent, or TraverseFromRoot methods). Assign
the values sequentially from 0, with 0 assigned to the first query, 1 assigned to the
second query, and so on.

After you create a query using the TraverseFromRoot method, you can create filter
conditions and sort conditions for the query using the AppendFilter or
AppendSort methods

Parameters This method accepts the following parameters:

Parameter Type Description

EntryIndex Long The index (or name) to be associated with the query.
Short Normally, you should specify an integer value because this makes
String coding easier, but you can use a string value if you want.
RelationName String The relation name used to traverse from the root object to the
related objects in the database.
You must specify a valid relation name. (See the Data Dictionary
Guide for a list of valid relations for each database object type.)

Return Values This method returns no values. Although it does retrieve a list of records from the
database and places them in the BulkRetrieve object, you must use the
GetRecordList method to get those records out of the BulkRetrieve object.

122 TraverseFromRoot
ClearBasic Object Reference
 BulkRetrieve object

Example In the following example, the database is accessed twice, using the BulkRetrieve
object BulkGet. The first access uses a SimpleQuery to return records, one of which is
subsequently placed into userObj. The purpose of performing this first access is to get
a record from the database to use as the root record.

The second access uses a TraverseFromRoot query. Notice that the root has been
set to userObj, which contains the record retrieved from the database in the first access.
The query is assigned an entry index of 0.
Dim userName As String
Dim bulkGet As New BulkRetrieve
Dim RList As List
Dim UserObj As Record

userName = App.UserName

' This is the first database access

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", cbEqual, _
userName
BulkGet.RetrieveRecords

set RList = BulkGet.GetRecordList(0)

set userObj = RList.ItemByIndex(0)

' Second access--you must set the root first.

BulkGet.SetRoot userObj
BulkGet.TraverseFromRoot 0, "user2dataset"
BulkGet.RetrieveRecords

See Also RetrieveRecords method

SetRoot method
SetRootById method
SimpleQuery method
TraverseFromParent method

TraverseFromRoot 123
ClearBasic Object Reference
 BulkRetrieve object

124 TraverseFromRoot
ClearBasic Object Reference
 BulkSave object

Description The BulkSave object encapsulates a set of database updates into one database
operation. You can use this object to perform the following database operations:
■ add new records
■ change the data in existing records
■ delete records
■ add relations to a record
■ delete relations from a record

This object complements the BulkRetrieve and PowerQuery objects, which read
information from the database. You may use the BulkSave object in conjunction with
these other objects to modify or delete existing records.

Normally, you create an instance of the BulkSave object using code similar to the
following:
Dim YourBulkSave as New BulkSave

After you create the new object, you can call its methods to specify your database
modifications. You can add records, modify records, delete records, add relations, or
delete relations. When you are ready to commit your changes to the database, call the
Save method.

During its execution, the Save method attempts to call the Form_Save event
handlers of the form. The Form_Save event handlers give you one last opportunity to
verify the changes and abort them if needed. See the Form_Save on page 316 for more
information about implementing Form_Save event handlers.

Working With You can use a BulkSave object to add records, change records, or delete records.
Records When you work with records, you must first acquire an appropriate instance of the
Record object. If you are modifying an existing record, use a BulkRetrieve object
to retrieve the record from the database. If you are adding a new record, create a new
instance of the Record object directly.

The InsertRecord method adds a new record to the BulkSave object. When you call
the Save method, the new record is assigned an object ID and added to the database.
To modify an existing record, first acquire the record using a BulkRetrieve object. If
you change the fields of the record, use the UpdateRecord method to register those
changes with the BulkSave object. To delete the record altogether, call the
DeleteRecord method.

In a Form_Save event handler, you can use the CancelRecord and ChangeRecord
methods to modify the contents of the BulkSave object. The CancelRecord method
cancels any pending changes to a specific record. The ChangeRecord method adds
additional changes to the record before it is committed. You can use the
GetRecordByIndex and CountByType methods to locate records in the BulkSave
object.

ClearBasic Object Reference 125

 BulkSave object

Working With In addition to adding or modifying records, you can add or change the relations
Relations between records. Use the RelateRecords, RelateRecordsFromID,
RelateRecordsFromToID, and RelateRecordsToID methods to add new
relations between two records. Use the UnrelateRecords method to remove a
relation.

You can modify relations before or after you call the Save method of the BulkSave
object. If you are creating new records, you can relate the record to one or more other
records. In a Form_Save event handler, you can add or remove relations as
appropriate.

Methods This object defines the following methods:

■ CancelRecord method
■ ChangeRecord method
■ CountByType method
■ DeleteRecord method
■ DeleteRecordByID method
■ GetRecordByIndex method
■ InsertRecord method
■ Print method
■ RelateRecords method
■ RelateRecordsFromID method
■ RelateRecordsFromToID method
■ RelateRecordsToID method
■ Save method
■ UnrelateRecords method
■ UpdateRecord method

Properties This object defines the following property:

■ Save_Aborted property

126
ClearBasic Object Reference
 BulkSave object

method CancelRecord

Syntax YourBulkSave.CancelRecord RecordToCancel

Applies To BulkSave

Description The CancelRecord method removes one record from the BulkSave object only (not
from the database) and is used prior to the Save method or in the Form_Save
callback. It does not affect records in the database. After you remove a record from the
BulkSave object, that record is not saved to the database when you use the Save
method.

This method should not be confused with the DeleteRecord method, which deletes
a record from the database.

If you added a relation to a record using the RelateRecords method, you do not
need to delete the relation before using this method to remove the record from the
BulkSave object.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordToCancel Record The record you want to remove from the BulkSave
object.

Return Values None

See Also ChangeRecord method

DeleteRecord method
GetRecordByIndex method
Form_Save event (Form object)

CancelRecord 127
ClearBasic Object Reference
 BulkSave object

method ChangeRecord

Syntax Set YourRetRecord = YourBulkSave.ChangeRecord (RecordToChange,

Options)

Applies To BulkSave

Description The ChangeRecord method updates a record that was previously placed in the
BulkSave object by the InsertRecord or UpdateRecord methods. It allows you
to make changes to BulkSave records prior to the execution of the Save method or
in the Form_Save callback.

IMPORTANT: This method supports the optional parameters cbByRef and cbByValue,
which are briefly described here. For more information on these options, see the chapter titled
"Accessing the ClarifyCRM Database," in the ClearBasic Programmer’s Guide.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordToChange Record Specifies the record that you want to change in the BulkSave
object.
Options Long An optional parameter. If you do not specify this parameter,
the default is cbByRef.
Specify cbByValue if you want the record returned by this
method to be a copy of the record added to the BulkSave
object. The copy is a completely separate copy of the original,
including the same objid.
Specify cbByRef if you want the record returned by this
method to be the same record that is added to the BulkSave
object. This is useful if you want to update the record in the
BulkSave; you can change the record in the BulkSave simply
by changing the returned record.

Return Values If you specified cbByValue, this method returns a separate copy of the record that is
in the BulkSave object, including the same objid. This returned record can be used in
a loop that sets the objid field to 0 and makes any desired changes to other fields prior
to loading it back into the BulkSave as new record. (You have to set the objid field to
0 to identify it as a new record; a new, valid objid is assigned when the Save method
is executed.)

For limitations on using cbByValue, see RelateRecords, RelateRecordsFromID,

and RelateRecordsToID.

If you specified cbByRef explicitly or by using the default, this method returns the
same record that was added to the BulkSave object. That is, any changes made to the
record in the BulkSave results in an identical change in the returned record.
Likewise, any change made to the returned record results in an identical change in the
BulkSave record.

128 ChangeRecord
ClearBasic Object Reference
 BulkSave object

However, this behavior means that you cannot use the returned record in any kind of
a loop that changes field values then dumps the record back into the BulkSave. If
you did this, you would only overwrite the record in the BulkSave with each
iteration of the loop.

See Also CancelRecord method

GetRecordByIndex method
Save method

ChangeRecord 129
ClearBasic Object Reference
 BulkSave object

method CountByType

Syntax YourVar = YourBulkSave.CountByType (ObjectType)

Applies To BulkSave

Description If you provide the optional parameter ObjectType, this method returns the number of
records of the specified type in a BulkSave object. If you do not provide the object
type, this method returns the count of all of the records in the BulkSave object.

Parameters This method accepts the following parameter:

Parameter Type Description

ObjectType String This parameter is optional. If you want a count of a particular type
of record, you must specify the object type (string value). Valid
object types are listed in the Data Dictionary for Objects.
Omit this parameter to get a count of all of the records in the
BulkSave.

Return Values This method returns an integer value indicating the number of records of the specified
type in this object.

See Also GetRecordByIndex method

130 CountByType
ClearBasic Object Reference
 BulkSave object

method DeleteRecord

Syntax YourBulkSave.DeleteRecord Record, Options

Set YourRetRec = YourBulkSave.DeleteRecord (Record, Options)

Applies To BulkSave

Description The DeleteRecord method is used to delete a record in the database. However, the
record you specify with the DeleteRecord method is not actually deleted from the
database until the Save method is executed. Notice that DeleteRecord
automatically removes relations to the deleted record. You do not need to delete any
relations to a record using UnrelateRecords before you use DeleteRecord.

Parameters This method accepts the following parameters:

Parameter Type Description

Record Record Specify the record you want to delete from the database.
Options Long An optional parameter. If you do not specify this parameter, the
default is cbByRef.
Specify cbByValue if you want the record returned by this method
to be a copy of the record added to the BulkSave object. The copy is
a completely separate copy of the original, including the same objid.
Specify cbByRef if you want the record returned by this method to
be the same record that is added to the BulkSave object. This is
useful if you want to update the record in the BulkSave; you can
change the record in the BulkSave simply by changing the returned
record.

Comments Don’t confuse this method with the CancelRecord method. DeleteRecord deletes
a record from the database; CancelRecord removes a record from the BulkSave
object only and does not affect the database.

Return Values If you specified cbByValue, this method returns a separate copy of the record that is
in the BulkSave object, including the same objid. This returned record can be used in
a loop that sets the objid field to 0 and makes any desired changes to other fields prior
to loading it back into the BulkSave as new record. (You have to set the objid field to
0 to identify it as a new record; a new objid is assigned when the Save method is
executed.)

If you specified cbByRef (explicitly or by using the default), this method returns the
same record that was added to the BulkSave object. That is, any changes made to the
record in the BulkSave results in an identical change in the returned record.
Likewise, any change made to the returned record results in an identical change in the
BulkSave record.

DeleteRecord 131
ClearBasic Object Reference
 BulkSave object

However, this behavior means that you cannot use the returned record in any kind of
a loop that changes field values then dumps the record back into the BulkSave; if
you did this, you would only overwrite the record in the BulkSave with each
iteration of the loop.

Example In the following loop, the records in a list are deleted from the database. Note that
Save is invoked outside the loop. If you use Save inside the loop, it generates a
network round-trip for each iteration of the loop.
For i=0 to fldList.count-1
Set Rec1 = fldList.ItemByIndex (i)
MyBulkSave.DeleteRecord Rec1
Next i

MyBulkSave.Save

See Also CancelRecord method

ChangeRecord method
DeleteRecordByID method

132 DeleteRecord
ClearBasic Object Reference
 BulkSave object

method DeleteRecordByID

Syntax YourBulkSave.DeleteRecordByID RecordType, ObjectId

Applies To BulkSave

Description The DeleteRecordByID method is used to delete a record in the database, using the
object ID of the record to be deleted. However, the record you specify with the
DeleteRecord method is not actually deleted from the database until the Save
method is performed on the BulkSave object.

DeleteRecordByID automatically removes relations to the deleted record. You do

not need to delete any relations to a record (i.e., using UnrelateRecords) before
using DeleteRecordByID.

IMPORTANT: If the record you are deleting is a ClarifyCRM-defined object and contains a
relation that is marked as a UNIQUE index, then the relation will not be removed. To delete
this kind of relation, both the parent and the child need to be deleted at the same time. To
determine whether a record type has UNIQUE relations, see the Data Dictionary Guide.

Don’t confuse this method with the CancelRecord method. DeleteRecordByID

deletes a record from the database; CancelRecord removes a record from the
BulkSave object only and does not affect the database.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordType String You must provide the type name of the record you want to delete.
Valid database object type names are listed in the Data Dictionary
for Objects.
ObjectId Long You must provide the object id value of the object to be deleted.
This value is the value of the objid field in the record to be deleted.
(The record must be a permanent record retrieved from the
database.)

Return Values None

Example In the following loop, the records in a list are read into a BulkSave object to be
deleted from the database.
For i=0 to fldList.count-1
Set Rec1 = fldList.ItemByIndex (i)
MyBulkSave.DeleteRecordByID "case", _
Rec1.GetField ("objid")
Next i

MyBulkSave.Save

DeleteRecordByID 133
ClearBasic Object Reference
 BulkSave object

See Also CancelRecord method

ChangeRecord method
DeleteRecord method
InsertRecord method
UpdateRecord method

134 DeleteRecordByID
ClearBasic Object Reference
 BulkSave object

method GetRecordByIndex

Syntax Set YourRecord = YourBulkSave.GetRecordByIndex (Index, "Type")

Applies To BulkSave

Description The GetRecordByIndex method returns the record in the BulkSave object that is
associated with the index value you provide. (An index is automatically assigned to
records when they are placed into the BulkSave.)

If you specify the record type, the index value you specify is based on the index of
only those records of that specified type. For example, if you specify case as the record
type, and specify the nth record, this method returns the nth case record.

If you don’t specify the record type, the index value you specify is based on all the
records in the BulkSave object. For example, if you specify the nth record, but do not
specify which type of record you want, this method returns the nth record of the
BulkSave object, regardless of type.

Parameters This method accepts the following parameters:

Parameter Type Description

Index Long The index value of the record. You must supply an integer value. (The
first record has the value 0, the second has the value 1, and so on.)
Type String This parameter is optional. To specify a record type, supply the type
name. You must use a string.

Return Values This method returns the record at the specified index.

See Also CancelRecord method

ChangeRecord method
CountByType method

GetRecordByIndex 135
ClearBasic Object Reference
 BulkSave object

method InsertRecord

Syntax YourBulkSave.InsertRecord RecordToInsert, Options

Set YourRec = YourBulkSave.InsertRecord (RecordToInsert,
Options)

Applies To BulkSave

Description You use this method to insert a new record into the database. This method adds the
specified record to the BulkSave object. (The record is actually inserted into the
database when the Save method is executed.)

This method inserts a NEW record into the database. If you want to save an existing
record that was originally retrieved from the database, use the UpdateRecord
method.

IMPORTANT: This method supports the optional parameters cbByRef and cbByValue,
which are briefly described here. For more information on these options, see the chapter titled
"Accessing the ClarifyCRM Database," in the ClearBasic Programmer’s Guide

Parameters This method accepts the following parameters:

Parameter Type Description

RecordToInsert Record Specify the record you want to insert into the database.
Options Long An optional parameter. If you do not specify this parameter, the
default is cbByRef.
Specify cbByValue if you want the record returned by this
method to be a copy of the record added to the BulkSave object.
The copy is a completely separate copy of the original, including
the same objid.
Specify cbByRef if you want the record returned by this method
to be the same record that is added to the BulkSave object. This
is useful if you want to update the record in the BulkSave; you
can change the record in the BulkSave simply by changing the
returned record.

Return Values If you specified cbByValue, this method returns a separate copy of the record that is
in the BulkSave object, including the same objid. This returned record can be used in
a loop that sets the objid field to 0 and makes any desired changes to other fields prior
to loading it back into the BulkSave as new record. (You have to set the objid field to
0 to identify it as a new record; a new objid is assigned when the Save method is
executed.)
For limitations on using cbByValue, see RelateRecords,
RelateRecordsFromID, and RelateRecordsToID.

136 InsertRecord
ClearBasic Object Reference
 BulkSave object

If you specified cbByRef (explicitly or by using the default), this method returns the
same record that was added to the BulkSave object. That is, any changes made to the
record in the BulkSave results in an identical change in the returned record.
Likewise, any change made to the returned record results in an identical change in the
BulkSave record.

However, this behavior means that you cannot use the returned record in any kind of
a loop that changes field values then dumps the record back into the BulkSave; if
you did this, you would only overwrite the record in the BulkSave with each
iteration of the loop.

Example The following example shows the typical use of this method. In the example, a copy of
a record is obtained from a contextual object and placed into saveObj; and saveObj is
changed to a new record. Because the record is now a New record, it is placed into the
BulkSave object for insertion into the database using the InsertRecord method.
Dim qryObj As Record
Dim saveObj As Record
Dim bulk As New BulkSave

set qryObj = Cobj_EDIT_QUERY.Contents

set saveObj = qryObj.Copy

saveObj.ChangeToNew
bulk.InsertRecord saveObj
bulk.Save

See Also DeleteRecord method

UpdateRecord method

InsertRecord 137
ClearBasic Object Reference
 BulkSave object

method Print

Syntax YourBulkSave.Print

Applies To BulkSave

Description The Print method prints the records and relations stored in the BulkSave object to
the standard output.

This method prints information to the standard output, which varies by platform. On
Unix systems, the standard output can be specified to be a file or device, depending
on your environment. On Windows systems, the standard output is the file
standard.out, which is located in the directory or folder where ClarifyCRM starts.

Parameters None

Return Values None

See Also Printer object

138 Print
ClearBasic Object Reference
 BulkSave object

method RelateRecords

Syntax YourBulkSave.RelateRecords SourceRecord, TargetRecord,

RelationName

Applies To BulkSave

Description Use this method to create a relation between two specified records. The records you
want to relate must be already in a BulkSave object. The new relation is saved into
the database along with the records when the Save method is performed on the
BulkSave object.

IMPORTANT: If you place a record in a BulkSave object with the parameter cbByValue, you
cannot use this method to relate that record to another record, unless that record has a valid
objid. For more information, see Chapter 6, "Accessing the Database," in the ClearBasic
Programmer’s Guide.

If the relation you specified is not valid for the records you are relating, an error
message will be generated at run time (the compiler does not flag this type of error).
A list of valid relations for each object type is provided in the Data Dictionary for
Objects.

Parameters This method accepts the following parameters:

Parameter Type Description

SourceRecord Record You must specify the record that is the source of the relation.
TargetRecord Record You must specify the record that is the target of the relation.
RelationName String You must specify a valid relation name. Valid relations for each
ClarifyCRM object type are listed in the Data Dictionary for
Objects. Names are case-sensitive.

Return Values None

Example The following example shows the typical use of this method. In the example, a copy of
a record is obtained from a contextual object and placed into saveObj; saveObj is
changed to a new record and placed into the BulkSave object for insertion into the
database. Finally, saveObj is related to another record, userObj, that was previously
placed into the BulkSave object.

Notice the order of operation: the records are placed into the BulkSave object before
they are related by RelateRecords; the records are related before they are saved
back to the database by Save.
Dim qryObj As Record
Dim saveObj As Record
Dim bulk As New BulkSave
Dim br As New BulkRetrieve

RelateRecords 139
ClearBasic Object Reference
 BulkSave object

Dim userList As List

Dim userObj As Record

br.SimpleQuery 0, "user"
br.AppendFilter 0, "login_name", cbEqual, _
App.UserName
br.RetrieveRecords

Set userList = br.GetRecordList(0)

Set userObj = userList.ItemByIndex(0)
bulk.UpdateRecord userObj

set qryObj = Cobj_EDIT_QUERY.Contents

set saveObj = qryObj.Copy
saveObj.ChangeToNew

bulk.InsertRecord saveObj
bulk.RelateRecords userObj, saveObj, _
"originator2query"
bulk.Save

See Also RelateRecordsFromID method

RelateRecordsFromToID method
RelateRecordsToID method
UnrelateRecords method

140 RelateRecords
ClearBasic Object Reference
 BulkSave object

method RelateRecordsFromID

Syntax YourBulkSave.RelateRecordsFromID "SourceRecordType",

SourceRecordObjid, TargetRecord, "RelationName"

Applies To BulkSave

CAUTION: You must supply a valid Objid! No checking is done to detect an invalid Objid.

Description Use this method to create a relation between a record in the BulkSave object and a
record in the database using the database record’s object ID (objid). The new relation
is saved into the database along with the target record when the Save method is
executed. Notice that you must place the source record into the BulkSave with the
InsertRecord or UpdateRecord method if you want to save the source record.

IMPORTANT: If you place the target record in a BulkSave object with the parameter
cbByValue, you cannot use this method to relate that record to another record, unless that
record has a valid objid. For more information, see Chapter 6, "Accessing the Database," in the
ClearBasic Programmer’s Guide.

If the relation you specified is not valid for the records you are relating, an error
message will be generated at run time (the compiler does not flag this type of error).

A list of valid relations for each object type is provided in the Data Dictionary for
Objects.

Parameters This method accepts the following parameters:

Parameter Type Description

SourceRecordType String You must specify the record type of the record that is the
source of the relation. (For example, "case.") The record type
is case-sensitive.
SourceRecordObjid Long You must supply the Objid of the record that is the source of
the relation. (The record must be an existing database
record.)
TargetRecord Record You must specify the record that is the target of the relation.
The record can be an existing record or a new record, but it
must be placed into the BulkSave object before you can
invoke this method.
RelationName String You must specify a valid relation name. Valid relations for
each ClarifyCRM object type are listed in the Data
Dictionary for Objects. The name is case-sensitive.

Return Values None

RelateRecordsFromID 141
ClearBasic Object Reference
 BulkSave object

See Also RelateRecordsFromID method

RelateRecordsToID method
UnrelateRecords method

142 RelateRecordsFromID
ClearBasic Object Reference
 BulkSave object

method RelateRecordsFromToID

Syntax YourBulkSave.RelateRecorFromToID "SourceRecordType",

SourceRecordObjId, "TargetRecordType", TargetRecordObjId,
"RelationName"

Applies To BulkSave

CAUTION: You must supply valid Objids! No checking is done to detect invalid Objids.

Description Use this method to create a relation between two database records using their objids.
If you modified these records locally (you cannot modify the objid field!), you must
use UpdateRecord to place the records into the BulkSave object in order to save
them along with the relation. If you don’t put the modified records in the BulkSave,
only the relation is saved back and your modifications are lost. The new relation is
saved into the database when the Save method is executed.

If the relation you specified is not valid for the records you are relating, an error
message will be generated at run time (the compiler does not flag this type of error).

A list of valid relations for each object type is provided in the Data Dictionary for
Objects.

Parameters This method accepts the following parameters:

Parameter Type Description

SourceRecordType String You must specify the record type of the record that is the
source of the relation. (For example, "case.") The record type is
case-sensitive
SourceRecordObjid Long You must supply the Objid of the record that is the source of
the relation. (The record must be an existing database record.)
TargetRecordType String You must specify the record type of the record that is the target
of the relation. The record type is case-sensitive.
TargetRecordObjid Long You must supply the Objid of the record that is the target of the
relation. (The record must be an existing database record.)
RelationName String You must specify a valid relation name. Valid relations for each
ClarifyCRM object type are listed in the Data Dictionary for
Objects. The name is case-sensitive.

Return Values None

See Also RelateRecordsFromID method

RelateRecordsToID method
UnrelateRecords method

RelateRecordsFromToID 143
ClearBasic Object Reference
 BulkSave object

method RelateRecordsToID

Syntax YourBulkSave.RelateRecordsToID SourceRecord,

"TargetRecordType", TargetRecordObjid, "RelationName"

Applies To BulkSave

CAUTION: You must supply a valid Objid! No checking is done to detect an invalid Objid.

Description Use this method to create a relation between a source record in the BulkSave object
and a record in the database using the database record’s object ID (objid). The new
relation is saved into the database along with the source record when the Save
method is executed. Notice that you must place the target record into the BulkSave
with the UpdateRecord method if you want to save the target record.

IMPORTANT: If you place the source record in a BulkSave object with the parameter
cbByValue, you cannot use this method to relate that record to another record, unless that
record has a valid objid. For more information, see Chapter 6, "Accessing the Database," in the
ClearBasic Programmer’s Guide.

If the relation you specified is not valid for the records you are relating, an error
message will be generated at run time (the compiler does not flag this type of error).

A list of valid relations for each object type is provided in the Data Dictionary for
Objects.

Parameters This method accepts the following parameters:

Parameter Type Description

SourceRecord Record You must specify the record that is the source of the relation.
(For example, "case.") The record is case-sensitive.
TargetRecordType String You must specify the record type of the record that is the
target of the relation.
TargetRecordObjid Long You must supply the Objid of the record that is the target of
the relation. (The record must be an existing database record.)
RelationName String You must specify a valid relation name. Valid relations for
each ClarifyCRM object type are listed in the Data
Dictionary for Objects. The name is case-sensitive.

Return Values None

See Also RelateRecordsFromID method

RelateRecordsFromToID method
UnrelateRecords method

144 RelateRecordsToID
ClearBasic Object Reference
 BulkSave object

method Save

Syntax RetValue = YourBulkSave.Save

Applies To BulkSave

Description The Save method commits the records and relations contained in the BulkSave
object to database.

Parameters None

Return Values Returns an Integer indicating the status of the Save operation. A return value of 0
indicates that the operation was successful. A return value of 101 indicates that the
operation was aborted.

Example In the following example, a permanent database record is read from a contextual
object into qryObj, which is then placed into a BulkSave object and saved back to the
database, overwriting the original record. (You can’t tell from this code that qryObj is a
permanent database record, so you have to take our word for it.)
Dim qryObj As Record
Dim bulk As New BulkSave

Set qryObj = Cobj_EDIT_QUERY.Contents

bulk.UpdateRecord qryObj
bulk.Save

See Also Form_Save event (Form object)

Save 145
ClearBasic Object Reference
 BulkSave object

method UnrelateRecords

Syntax YourBulkSave.UnrelateRecords FromRecord, ToRecord,

"RelationName"

Applies To BulkSave

Description The UnrelateRecords method is used to delete a relation between two records in
the database. However, the relation you specify with the UnrelateRecords method
is not actually deleted from the database until the Save method is performed on the
BulkSave object.

IMPORTANT: DeleteRecord automatically removes relations to the deleted record. You do

not need to use UnrelateRecords on a record you delete with DeleteRecord.

If the relation you specified is not valid for the records you are relating, an error
message will be generated at run time (the interpreter does not flag this type of error
at compile time).

A list of valid relations for each object type is provided in the Data Dictionary for
Objects.

Parameters This method accepts the following parameters:

Parameter Type Description

FromRecord Record You must specify the record that is the source of the relation.
ToRecord Record You must specify the record that is the target of the relation.
RelationName String You must specify a valid relation name. Valid relations for each
ClarifyCRM object type are listed in the Data Dictionary for
Objects.

Return Values None

See Also RelateRecords method

Save method

146 UnrelateRecords
ClearBasic Object Reference
 BulkSave object

method UpdateRecord

Syntax YourBulkSave.UpdateRecord RecordToUpdate, Options

Applies To BulkSave

Description You must use this method if you want to overwrite an existing record in the database
with a version of the record that is modified locally. This method loads the specified
record into the BulkSave object and marks it as a modified record. When the Save
method is executed, the record is saved back to the database, overwriting the original
version.

This method works only on records that were retrieved from the database and
modified locally. If you want to save a new record that you created, use the
InsertRecord method.

IMPORTANT: This method supports the optional parameters cbByRef and cbByValue, which
are briefly described here. For more information on these options, see Chapter 6 "Accessing the
Database," in the ClearBasic Programmer’s Guide.

Parameters This method accepts the following parameters:

Parameter Type Description

RecordToUpdate Record Specify the record you want to save back to the database,
overwriting the original version.
Options Long An optional parameter. If you do not specify this parameter,
the default is cbByRef.
Specify cbByValue if you want the record returned by this
method to be a copy of the record added to the BulkSave object.
The copy is a completely separate copy of the original,
including the same objid.
Specify cbByRef if you want the record returned by this
method to be the same record that is added to the BulkSave
object. This is useful if you want to update the record in the
BulkSave; you can change the record in the BulkSave simply by
changing the returned record.

Return Values If you specified cbByValue, this method returns a separate copy of the record that is
in the BulkSave object, including the same objid. This returned record can be used in
a loop that sets the objid field to 0 and makes any desired changes to other fields prior
to loading it back into the BulkSave as new record. (You have to set the objid field to
0 to identify it as a new record; a new objid is assigned when the Save method is
executed.)
For limitations on using cbByValue, see RelateRecords,
RelateRecordsFromID, and RelateRecordsToID.

UpdateRecord 147
ClearBasic Object Reference
 BulkSave object

If you specified cbByRef (explicitly or by using the default), this method returns the
same record that was added to the BulkSave object. That is, any changes made to the
record in the BulkSave results in an identical change in the returned record.
Likewise, any change made to the returned record results in an identical change in the
BulkSave record.

However, this behavior means that you cannot use the returned record in any kind of
a loop that changes field values then dumps the record back into the BulkSave; if
you did this, you would only overwrite the record in the BulkSave with each
iteration of the loop.

Example In the following example, a permanent database record is read from a contextual
object into qryObj, which is then placed into a BulkSave object and saved back to the
database, overwriting the original record.
Dim qryObj As Record
Dim bulk As New BulkSave

Set qryObj = Cobj_EDIT_QUERY.Contents

Debug.print "qryObj=", qryObj
bulk.UpdateRecord qryObj
bulk.Save

See Also DeleteRecord method

InsertRecord method
Save method

148 UpdateRecord
ClearBasic Object Reference
 BulkSave object

property Save_Aborted

Syntax YourBulkSaveObj.Save_Aborted

Applies To BulkSave

Description When this property is set to True inside a Form_Save1 callback, the save operation is
aborted.

NOTE: This property can only be used in Form_Save1. This means that a save can only be
aborted from within a Form_Save1.

Furthermore, you can use this approach to abort a save operation only if you are working with Form
411 (New Case) or 420 (Edit Case). Using this approach to abort from other forms can result in
unexpected errors.

Example The following example illustrates the use of the Save_Aborted property inside a
Form_Save1 callback.
Sub Form_Save1(BSaveObj as BulkSsave)
Dim MyRec As Record
Dim NewRec As Record
Dim BulkSav As BulkSave

If(Invalid) Then
'Invalid is pseudo code for some condition
BSaveObj.Save_Aborted = TRUE
App.msgbox"Save was aborted"

Exit Sub
Else
Set MyRec = Cobj_CustList.Contents
Bulksav.InsertRecord MyRec
BulkSav.Save
End If
End Sub

See Also GetLastError method (Form object)

Form_Save event (Form object)

Save_Aborted 149
ClearBasic Object Reference
 BulkSave object

150 Save_Aborted
ClearBasic Object Reference
 ClarifyDB object

Description You use the ClarifyDB object to access a ClarifyCRM database other than the one
you are currently logged into. You can use multiple ClarifyDB objects to connect to
multiple ClarifyCRM databases at the same time.

There are some limitations, however. The schemas must be the same for all of the
databases, and in some cases, the windows/resource configs must be the same. For
example, if your CB code relies on such similarities, you need to make sure those
similarities exist.

IMPORTANT: These requirements are not checked by this object! You are responsible for
checking schema and window/resource compatibilities.

One use of this object would be to redirect queries to databases other than the one you
are currently logged into. The following example logs into a separate database and
uses that database to handle a Click event for a ClarifyCRM button.
sub FindButton_Click
Dim rmDB_1 as new ClarifyDB
Dim status as Int

' Log into a remote database "Database2" on

' server "Server2" using the account
' "User1" with the specified password.
status = rmDB_1.Login "Server2", _
"Database2", "User1", "Password"
if status = 0 Then
status = App.UseClarifyDB rmDB_1
if status = 0 Then
me.DoDefault
End If
Else
Debug.Print _
"Could not connect to remote db."
End If

App.UseDefaultDB
rmDB_1.Logout
end sub

Methods This object defines the following methods:

■ Login method
■ Logout method

ClearBasic Object Reference 151

 ClarifyDB object

Properties This object defines the following properties:

■ Connected method
■ DatabaseName method
■ ServerName method
■ UserName method

152
ClearBasic Object Reference
 ClarifyDB object

method Login

Syntax ReturnVal = YourClarifyDB.Login ("DBServer", "DBName",

"UserName, "Password", Timeout)

Applies To ClarifyDB

Description The Login method creates a connection between the specified ClarifyDB object and
the database server and database specified in the Login parameters. If this method
call is successful, all subsequent ClarifyCRM database operations will be performed
on that database.

Parameters This method accepts the following parameters.

Parameter Type Description

DBServer String You must specify the server name (string value) where the database
is located.
DBName String You must specify the name of the database (string value) to which
you want to log into.
UserName String You must supply a valid user name (string value).
Password String You must supply a valid password (string value).
Timeout Long You can specify the number of seconds (integer) to wait until failing
the attempt to log in. The default is 5 seconds.

Return Values The value returned is a long integer of one of the following values:

Value Result
0 Login successful
1 Login failed
2 This ClarifyDB object is already logged into
some database

Login 153
ClearBasic Object Reference
 ClarifyDB object

method Logout

Syntax ReturnVal = YourClarifyDB.Logout

Applies To ClarifyDB

Description The Logout method terminates a connection between the specified ClarifyDB
object and the database server and database it is logged into. You must call this
method when you want to switch to another database or return to the login database.

Return Values This method returns 0 (long integer) if the logout was successful.

154 Logout
ClearBasic Object Reference
 ClarifyDB object

property Connected

Syntax YourBoolean = YourClarifyDB.Connected

Applies To ClarifyDB

Description The Connected property is read-only. It is True if there is valid connection to the
database, False if there is no connection.

Connected 155
ClearBasic Object Reference
 ClarifyDB object

property DatabaseName

Syntax YourChar = YourClarifyDB.DatabaseName

Applies To ClarifyDB

Description The DatabaseName property is read-only. It returns the name of the database to
which the ClarifyDB object is currently connected.

156 DatabaseName
ClearBasic Object Reference
 ClarifyDB object

property ServerName

Syntax YourChar = YourClarifyDB.ServerName

Applies To ClarifyDB.

Description The ServerName property is read-only. It returns the name of the database server to
which the ClarifyDB object is currently connected.

ServerName 157
ClearBasic Object Reference
 ClarifyDB object

property UserName

Syntax ClarifyDB.UserName

Applies To ClarifyDB

Description The UserName property contains the name of the user currently logged into the
ClarifyCRM database.

Example In the following example, UserName is used to pass the currently logged-in user as an
argument for AppendFilter; it is used to specify which of the records of type user
are to be retrieved: namely those whose field login_name contains username.
Dim userName as String
Dim bulkGet as New BulkRetrieve

userName = App.UserName
Debug.print "userName=", username

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", _
cbEqual, userName
BulkGet.RetrieveRecords

158 UserName
ClearBasic Object Reference
 Clipboard object

Description The Clipboard object provides a platform-independent clipboard to allow a user to

cut, copy, and paste text data. The clipboard object sends data to, retrieves data from,
and queries the native platform’s clipboard.

The clipboard holds only the last piece of text data that was sent to the clipboard. If
the user sends more text data to the clipboard, the new data overwrites the existing
text data in the clipboard.

Up to 32K bytes of text data at a time can be sent to the clipboard.

Comments This object is created automatically; you do not declare it in your code. To access it,
simply use the keyword Clipboard, as follows:
Clipboard.Clear

Methods This object defines the following methods:

■ Clear method
■ GetFormat method
■ GetText method
■ SetText method

ClearBasic Object Reference 159

 Clipboard object

method Clear

Syntax Clipboard.Clear

Applies To Clipboard

Description The Clear method removes any data currently on the clipboard.

Parameters None

Return Values None

See Also Empty method (ContextualObject object)

160 Clear
ClearBasic Object Reference
 Clipboard object

method GetFormat

Syntax RetBoolean = Clipboard.GetFormat (Format)

Applies To Clipboard

Description The GetFormat method determines whether an item having the specified format is
currently in the native platform clipboard.

Parameters This method accepts the following parameter:

Parameter Type Description

Format Integer Specify the constant of the format you want to check for.
To specify text, specify cbFormatText.
To specify images, specify cbFormatBitmap.

Return Values This method returns the value True (-1) if an item having the specified format is
currently in the native platform clipboard. Otherwise it returns the value False (0).

Example The following code fragment checks the Clipboard for text data and prints the
appropriate message.
RetVal = Clipboard.GetFormat (cbFormatText)

If RetVal = True Then

Print "Clipboard contains text."
Else
Print "Clipboard contains no text."
End If

See Also GetText method

SetText method

GetFormat 161
ClearBasic Object Reference
 Clipboard object

method GetText

Syntax YourVariable = Clipboard.GetText

Applies To Clipboard

Description The GetText method gets the text that is currently in the Clipboard. Memory for
the text is dynamically allocated.

Parameters None

Return Values This method returns the text in the Clipboard.

Example In the following code fragment, the clipboard is checked for text; if there is text in the
clipboard, that text is checked for the presence of the string caseID and the
appropriate messages are printed.
If Clipboard.GetFormat(cbFormatText) Then
If Instr(Clipboard.GetText, "caseID", 1) _
= False Then
Print "Clipboard doesn’t contain caseID."
Else
Print "Clipboard contains caseID."
End If
Else
Print "Clipboard contains no text."
End If

See Also GetFormat method

SetText method

162 GetText
ClearBasic Object Reference
 Clipboard object

method SetText

Syntax Clipboard.SetText Text

Applies To Clipboard

Description The SetText method places text into the Clipboard.

Parameters This method accepts the following parameter:

Parameter Type Description

Text String You must specify the variable that contains the text to be placed
into the clipboard.

Return Values This method returns the text in the Clipboard.

See Also GetFormat method

GetText method

SetText 163
ClearBasic Object Reference
 Clipboard object

164 SetText
ClearBasic Object Reference
 CommonDialog object

Description The CommonDialog object implements common dialogs, which are the dialogs
provided by the native windowing environment for applications to use. Examples of
common dialogs are the open file/save file dialogs that are the same from application
to application.

In ClearBasic, the following common dialogs are supported:

■ Open File (cbOpenFile)
■ Save File (cbSaveFile)
■ Page Setup (cbPageSetup)
■ Date Time (cbDateTime)
■ Elapsed Time (cbElapsedTime)

Comments You declare a CommonDialog object variable as follows:

Dim YourCommonDialog As New CommonDialog

Properties This object defines the following properties:

■ Action property
■ CancelError property
■ Copies property
■ DataChanged property
■ DateTime property
■ DefaultExt property
■ DialogId property
■ DialogTitle property
■ ElapsedSeconds property
■ FileName property
■ FileTitle property
■ FromPage property
■ InitDir property
■ Tag property
■ ToPage property

ClearBasic Object Reference 165

 CommonDialog object

Example The following event procedure illustrates the use of the CommonDialog object. The
procedure posts the Page Setup dialog with the title "Page Setup".
Sub PostSetup_Click
Dim cd1 As New Commondialog

cd1.DialogTitle = "Page Setup"

cd1.Action = cbCDPageSetup
End Sub

166
ClearBasic Object Reference
 CommonDialog object

property Action

Syntax YourCommonDialog.Action = Constant

Applies To CommonDialog

Description Setting this property posts the specified common dialog to the screen. The common
dialog then has control until unposted.

The posted common dialog is modal and therefore must be closed or dismissed before
you can perform any other tasks.

Settings You must use the following constants to set the Action property:

Constant Common Dialog Posted

cbCDOpen Open File
cbCDSaveFile Save File
cbCDPageSetup Print Setup
cbCDDateTime DateTime
cbCDElapsedTime ElapsedTime

Return Values When read, this property returns the last value set. You can read this property to
determine which dialog was last posted.

Example The following event procedure posts the Page Setup dialog.
Sub PostSetup_Click
Dim cd1 As New Commondialog
cd1.Action = cbCDPageSetup
End Sub

Action 167
ClearBasic Object Reference
 CommonDialog object

property CancelError

Syntax YourCommonDialog.CancelError = Setting

Applies To CommonDialog

Description The CancelError property affects the Cancel button in common dialogs. If you
don’t set this property, or if you set this property to False, the default behavior is that
the Cancel button does not post an error message when clicked. If you set this
property to True an error message is posted whenever the user clicks on Cancel.

IMPORTANT: If you set this property to True so that the Cancel button generates an error
when clicked, your program must handle the error.

CancelError is for use with common dialogs in those instances where you don’t
want the user to press Cancel or you don’t want the user to press Cancel before
completing some task. Because you cannot disable the Cancel button in a common
dialog, you need to set this property to True to trap the Cancel event, then handle the
error as you wish, for example by posting some sort of message.

Settings The following settings can be used for this property:

Setting Action
True Set the property to True if you want an error to be generated whenever the user
clicks the Cancel button.
False This is the default setting. Set the property to False if you do not want an error to
be generated when the user clicks the Cancel button.

Return Values In read mode, this property returns the current value of the property.

Example In the following fragment of a click event procedure, the Open File dialog is posted
with CancelError turned on. If the user clicks Cancel in this dialog, a message box
is posted with the prompt "Don’t Press Cancel."
Sub CancelGotPressed_Click
Dim CMDialog1 As New CommonDialog
Dim Ret1 As integer

On Error Goto Cancel

CMDialog1.CancelError = True
CMDialog1.Action = cbCDOpen

Exit Sub

Cancel:
App.MsgBox "Don’t Press Cancel"

168 CancelError
ClearBasic Object Reference
 CommonDialog object

Resume Next
.
.
End Sub

See Also The On Error statement in the ClearBasic Language Reference.

CancelError 169
ClearBasic Object Reference
 CommonDialog object

property Copies

Syntax YourRetVal = YourCommonDialog.Copies

Applies To CommonDialog

Description The Copies property is a read-only property that applies to the PrintSetup common
dialog. It returns the number of copies that were requested in the Copies text box in
the dialog.

Return Values This property returns positive integer values.

See Also FromPage property

ToPage property

170 Copies
ClearBasic Object Reference
 CommonDialog object

property DataChanged

Syntax RetBoolean= YourCommonDialog.DataChanged

Applies To CommonDialog

Description You can read this property to determine whether modifications were made by the
user. This property indicates whether modifications were made to the common dialog
by user interaction.

You can interactively set this property for a common dialog.

IMPORTANT: DataChanged indicates that modifications were made by the user.

Modifications made programmatically through code do not affect this property.

For the DateTime and ElapsedSeconds common dialogs, the DataChanged property
is set to False just before the dialog is posted. If the user presses Cancel, the
DataChanged property remains False; if the user changes the value and presses OK,
it is set to True. If the user does not change the value but presses OK the property
stays False.

Return Values This property contains True if modifications were made to the dialog, otherwise False.

Examples The following is a code snippet illustrating one use of this property.
Dim MyDialog As New CommonDialog

MyDialog.Action = cbCDDateTime

If MyDialog.DataChanged = True Then

‘Do This
Else
‘Do That
End If

Here is another example that illustrates the use of the DataChanged property.
Sub Close_Click
Dim Ret As Integer

If Me.DataChanged Then
Ret = App.MsgBox ("Save; interrupted?", _
cbSaveDiscardCancel)

If Ret = cbidSave Then

Save.Value = True
Me.Datachanged = False
ElseIf Ret = cbidDiscard Then
Me.Datachanged = False
Else

DataChanged 171
ClearBasic Object Reference
 CommonDialog object

Exit Sub
End If

Me.DoDefault
End If
End Sub

172 DataChanged
ClearBasic Object Reference
 CommonDialog object

property DateTime

Syntax YourCommonDialog.DateTime
YourCommonDialog.DateTime = "DateString TimeString"

Applies To CommonDialog

Description You can use this property to set the date and time displayed in the DateTime common
dialog when it is posted. You can also read this property to get the date and time
settings that were either last set for this property or that were last entered by the user
when the DateTime common dialog was posted.

IMPORTANT: For more information on using this and similar properties, see the chapter in the
ClearBasic Programmer’s Guide titled "Handling Date and Time."

Settings This property accepts the following setting:

Setting Description
"DateString TimeString" Supply the date string, a space, and the time string all
surrounded by double quotes.
These settings depend on the country selected in Windows.
For United States, the date string is normally formatted as mm/
dd/yy. and the time string is formatted as h:m:s.
However, the exact format of the date and time strings varies
depending on the underlying database platforms: Oracle, Sybase,
or Microsoft NT SQL Server. See the ClarifyCRM system
administration documentation for each of these platforms to
determine which date and time formats to use.

Comments For this common dialog, the DataChanged property is set to False just before the
dialog is posted. If the user presses Cancel, the DataChanged property will remain
False. But if the user presses OK, the property is set to True if the user changes the
value.

Example In the following example, the DateTime common dialog is posted with an initial date
and time.
Sub DateTimePost_Click
Dim cd1 As New Commondialog

cd1.Action = cbCDDateTime
txtStartDate.text = cd1.DateTime
'txtStartDate is a text box
End Sub

DateTime 173
ClearBasic Object Reference
 CommonDialog object

property DefaultExt

Syntax YourCommonDialog.DefaultExt = "ExtensionName"

Applies To CommonDialog

Description This property specifies the default file extension to be used by the Open File and Save
File common dialogs.

Settings This property accepts the following settings:

Parameter Type Description

ExtensionName String Specify a valid filename extension, such as TXT. You must use a
string of no more than three characters.

Return Values When read, this property returns the last value set.

Example The following procedure posts the Save File common dialog with the default filename
extension of doc.
Sub SetExtension_Click
Dim CMDialog1 As New CommonDialog

CMDialog1.DefaultExt = "doc"
CMDialog1.Action = cbCDSaveFile
DebugPrint "User selected file name", _
CMDialog1.FileName
End Sub

See Also InitDir property

174 DefaultExt
ClearBasic Object Reference
 CommonDialog object

property DialogId

Syntax YourCommonDialog.DialogId = formID

formID = YourCommonDialog.DialogId

Applies To CommonDialog

Description The DialogId property contains the ID of your custom DateTime dialog. Use this
property only if you want to replace the standard DateTime dialog with a custom
version you create. The form you create to implement the dialog must define the same
set of contextual objects as the standard DateTime dialogs (ID 1004).

To display your custom dialog, set the Action property to 102.

Example The following procedure posts a custom DateTime dialog with form ID 1500.
Function MyGetDate () As String
Dim CMDialog1 As New CommonDialog

CMDialog1.DialogId = 1500
CMDialog1.Action = 102

MyGetDate = CMDialog1.DateTime
End Sub

DialogId 175
ClearBasic Object Reference
 CommonDialog object

property DialogTitle

Syntax YourCommonDialog.DialogTitle = "Title"

Applies To CommonDialog (Open File and Save File)

Description If you do not want to use the default common dialog titles for the common dialogs,
you can specify another title to be displayed in the title bar of the dialog.

Settings This property accepts the following setting:

Setting Type Description

Title String Specify the title (string value) you want displayed in the dialog title
bar. This can function as a prompt.

Return Values When read, this property returns the last title set for this property.

Example The following procedure posts the Open File dialog with the prompt "Please
select a file".
Sub SetTitles
Dim CMDialog1 As New CommonDialog

CMDialog1.DialogTitle = "Please select a file"

CMDialog1.Action = cbCDOpen

DebugPrint "User selected file", _

CMDialog1.FileName
End Sub

176 DialogTitle
ClearBasic Object Reference
 CommonDialog object

property ElapsedSeconds

Syntax YourCommonDialog.ElapsedSeconds = TotalSeconds

Applies To CommonDialog

Description Use this property to set the time displayed in the Elapsed Time dialog when it is
posted. (The value supplied is automatically translated into weeks, days, hours, and
minutes.)

Settings This property can be set with the following settings:

Setting Description
TotalSeconds Supply an integer value representing the number of seconds.

Comments DataChanged is set to False just before this dialog is posted. If the user presses
Cancel, DataChanged remains False. If the user presses OK, the property is set to
True, even if the user does not change the value.

Return Values When read, this property returns the last value set or entered.

Example The following sample sets the ElapsedSeconds property, posts the ElapsedTime
dialog, and checks the property after posting the dialog.
Sub EStest
Dim cd1 As New Commondialog
Dim Logstr As string

cd1.ElapsedSeconds = 155555555
cd1.Action = cbCDElapsedTime

If cd1.ElapsedSeconds = 155555555 Then

Logstr = "ElapsedTime not changed"
Else
Logstr = "ElapsedTime changed"
End If
End Sub

See Also DateTime property

ElapsedSeconds 177
ClearBasic Object Reference
 CommonDialog object

property FileName

Syntax YourCommonDialog.FileName = "File"

Applies To CommonDialog

Description The FileName property applies to the Save File common dialog and contains the
name of the selected file, including the path. It can be set in your code, or it can be set
as the result of user input.

If you set this property in your code before you set the Action property, the common
dialog is displayed with the specified filename in the FileName text box.

If you don’t set this property, the FileName property is automatically set to the
filename that was selected by the user, provided that the user exits the dialog by
clicking the OK button.

Settings This method accepts the following settings:

Setting Description
File The name of the selected file, including the path.

Return Values When read, this property returns the last (string) value set for this property or the full
path name of the file selected by the user when the Save File dialog was posted.

Example The following procedure posts the Open File common dialog with a filename already
filled in.
Sub SetFilename
Dim CMDialog1 As New CommonDialog

Print "Open File Dialog: Setting FileName"

CMDialog1.FileName = "/usr/alice/.Xdefaults"
CMDialog1.Action = cbCDOpen
DebugPrint "User selected file name",
CMDialog1.FileName
End Sub

See Also FileTitle property

178 FileName
ClearBasic Object Reference
 CommonDialog object

property FileTitle

Syntax YourCommonDialog.FileTitle

Applies To CommonDialog

Description This read-only property applies to the Open File and Save File common dialogs. It
returns the filename (string) that was selected by the user or supplied
programmatically (see FileName) with all the path information deleted. One use of
this property is to use it to title the dialog window that contains the opened file.

Example The following procedure posts a Save File common dialog with an initial directory
and filename, then reads FileTitle into str1. The variable str1 is compared to the
FileName that was provided, and the appropriate message box is posted. Of course,
this procedure always posts the first message box.
Sub SetTitle
Dim str1 As string
Dim cd1 As New CommonDialog

cd1.InitDir = "C:\Dog\Fetch"
cd1.FileName = "Owl.h"
cd1.Action = cbCDSaveFile

str1 = cd1.FileTitle

If str1 = "Owl.h" Then

App.MsgBox "User did not change file"
Else
App.MsgBox "User changed file"
End If
End Sub

See Also FileName property

FileTitle 179
ClearBasic Object Reference
 CommonDialog object

property FromPage

Syntax YourCommonDialog.FromPage

Applies To CommonDialog

Description This read-only property applies to the Print common dialog. It returns the last value
that was entered into the FromPage text box by the user.

Example The following example posts the Page Setup common dialog, then prints the current
values for FromPage and ToPage.
Sub CheckFromTo
Dim cd1 As New CommonDialog

cd1.Action = cbCDPageSetup

Print "FromPage is: "; Cd1.FromPage, _

"ToPage is:"; Cd1.ToPage
End Sub

See Also Copies property

180 FromPage
ClearBasic Object Reference
 CommonDialog object

property InitDir

Syntax YourCommonDialog.InitDir = "DirectoryPath"

Applies To CommonDialog

Description You can use this property with the Open File and Save File common dialogs to specify
a particular directory to be displayed in the dialog when it is posted. If you don’t
specify a directory, using this property, the current directory is used by default.

Settings This property accepts the following setting:

Setting Description
DirectoryPath Specify the directory you want to use, including the path.

Return Values When read, this property returns the last value (string) set.

Example In the following procedure, the Save File common dialog is posted with the initial
directory /user/mike/mailbox.
Sub SetInitDir
Dim CMDialog1 As New CommonDialog

Print "Save File Dialog: Setting InitDir"

CMDialog1.InitDir = "/usr/mike/mailbox/"
CMDialog1.Action = cbCDSaveFile
DebugPrint "User chose filename", _
CMDialog1.FileName
End Sub

See Also DefaultExt property

FileName property

InitDir 181
ClearBasic Object Reference
 CommonDialog object

property Tag

Syntax YourCommonDialog.Tag = "YourStringHere"

ControlTag = YourCommonDialog.Tag

Applies To CommonDialog

Description The Tag property contains a custom string that you assign at runtime. You can use
this string to identify the dialog internally to your application. You can also use this
property to store extra information about the dialog.

182 Tag
ClearBasic Object Reference
 CommonDialog object

property ToPage

Syntax YourCommonDialog.ToPage

Applies To CommonDialog

Description This read-only property applies to the Print common dialog. It returns the last value
that was entered into the To Page text box by the user.

Example The following example posts the Page Setup common dialog, then prints the current
values for FromPage and ToPage.
Sub CheckFromTo
Dim cd1 As New CommonDialog

cd1.Action = cbCDPageSetup

Print "FromPage is: "; Cd1.FromPage, _

"ToPage is:"; Cd1.ToPage
End Sub

See Also Copies property

FromPage property

ToPage 183
ClearBasic Object Reference
 CommonDialog object

184 ToPage
ClearBasic Object Reference
 ContextualObject object

Description At form design time in the User Interface Editor, a contextual object is linked to a form
first, then is subsequently linked to a control as a source or destination for that control.
When a contextual object is specified at design time, an object variable is also
automatically created for it. Your ClearBasic code that moves data into and out of a
contextual object must use the object variable for that contextual object.

The name of the object variable for a given contextual object is

Cobj_ContextualObjectName where ContextualObjectName is the name of the contextual
object assigned at design time. Each object variable for a contextual object is available
only to the form in which it is located (that is, it is form-scoped).

NOTE: For a description of ClarifyCRM contextual objects, see the chapter titled "Contextual
Objects and the ClarifyCRM GUI" in the ClearBasic Programmer’s Guide

Comments An object variable for a contextual object is created automatically and therefore is not
explicitly declared in your code.

Methods This object defines the following methods:

■ AppendItem method
■ Empty method
■ Fill method
■ GetContents method
■ IsNew method
■ Refresh method
■ Sort method

Properties This object defines the following properties:

■ BackColor property
■ Caption property
■ Contents property
■ DataChanged property
■ DataType property
■ ForeColor property
■ List property
■ Name property
■ SubType property

ClearBasic Object Reference 185

 ContextualObject object

method AppendItem

Syntax Cobj_Yours.AppendItem ItemToAppend

Applies To ContextualObject

Description The AppendItem method appends one item or one list of items to a contextual object
that has the List data type. You can use this method to append user-defined types
(UDTs) to a contextual object.

This method can be used to add items only to those contextual objects that have the
List primitive data type. This method generates an error if the type of data item does
not match the type expected by the contextual object.

NOTE: Using AppendItem on a control automatically updates the contextual object linked
to the control.

Parameters The method accepts the following parameters:

Parameters Values
ItemToAppend You must specify the item to add to a contextual object.The data type for
the item must match the type expected by that contextual object.Typically,
controls are linked to collections of strings.

Return Values None

Example In the following example, new_item is appended to Cobj_List_item and then

Cobj_List_item is refreshed to update any controls linked to it.
Sub AddToCobj_Click
Cobj_List_item.AppendItem "new_item"
Cobj_List_item.Refresh
End Sub

186 AppendItem
ClearBasic Object Reference
 ContextualObject object

method Empty

Syntax Cobj_Yours.Empty

Applies To ContextualObject

Description The Empty method clears the contents of a contextual object regardless of the type of
value present in it. This method works for all data types, including user-defined types
(UDTs).

You can use this method to reset a contextual object to empty (blank). Later, you can
use the Fill method to reinitialize the contextual object with desired values.

Like the Fill method, this method also modifies the user interface of the controls
linked to the contextual object. In this case, control will show only the default values,
if any, assigned from the User Interface Editor.

Parameters None

Return Values None

Example The following code fragment illustrates the use of the Empty method.
Dim myString As String
Dim retString As String

myString = "AssignedValue"
Cobj_Source_String.Fill myString
Cobj_Source_String.Empty

retString = Cobj_Source_String.Contents
Debug.print ">", myString, "< >", retString, "<"

This code should print the following string:

>AssignedValue< ><

See Also Fill method

Empty 187
ClearBasic Object Reference
 ContextualObject object

method Fill

Syntax Cobj_Yours.Fill ItemToUse, Options

Applies To ContextualObject

Description The Fill method fills a contextual object with new data. (The new data is
automatically updated into the control(s) linked to the contextual object.) Any
existing data in the contextual object is overwritten. You can use this method to fill the
contextual object with data from a user-defined type.

You can use this method to initialize a contextual object with desired values during
the Form_Load event or you can also use it to reinitialize a contextual object with
new data after the Form_Load event.

Parameters This method accepts the following parameters.

Parameter Type Description

ItemToUse variable You must specify the variable that contains the data that you
want to fill into this contextual object. The data type of the
variable must match the data type that was assigned to this
contextual object at form or control design time.
Options Long Optional. Specify the constant cbFillUseClientTime to convert the
server time to the client time and then insert it into the contextual
object.

Return Values None

Example The following code fragment shows a very common use of the Fill method. Very
frequently, Fill is invoked after records are retrieved with a BulkRetrieve object.
The example shows one contextual object being filled with values from the list and
another contextual object being filled with the count of items in that list. The example
also inserts the server time after converting it to the client time.
Bulk.RetrieveRecords
Set RList = Bulk.GetRecordList(0)
Cobj_DATASET.Fill RList, cbFillUseClientTime
Cobj_TOTAL_NUM.Fill RList.count

See Also AppendItem method

188 Fill
ClearBasic Object Reference
 ContextualObject object

method GetContents

Syntax Cobj_Yours.GetContents MyContents

Applies To ContextualObject

Description The GetContents method places the current value in the specified contextual object
into the specified return parameter (MyContents). It can be used to return user defined
types.

Parameters This method accepts the following parameter:

Parameter Type Description

MyContents UDT Specify a variable of the same type as the value you expect to be
obtained from the contextual object. On return, this variable
contains the data in the contextual object.

Return Values None

Example The following code illustrates a use of this method. It gets a user-defined type from a
contextual object and places it into a UDT variable, changes one field value and fills
the UDT back into a contextual object.
Dim MyVar As MyUDT

Cobj_MyUDT.GetContents MyVar

MyVar.Val=1
Cobj_MyVar.Fill MyVar

GetContents 189
ClearBasic Object Reference
 ContextualObject object

method IsNew

Syntax YourBoolean = Cobj_Yours.IsNew()

Applies To ContextualObject

Description The IsNew method can be used on records or contextual objects that contain records.
It returns True if the record is not a permanent record (was not retrieved from the
database). It returns False if it is a new record created locally or if it is a permanent
record that has been changed to a new record via the ChangeToNew method.

If the value of the contextual object is a primitive type or a user defined type, an error
is posted.

Parameters None

Return Values This method returns False if the record is a permanent record and True if it is not a
permanent record.

Example The following micro snippet of code shows a typical way to use this method to check
for a new record prior to carrying out some action.
If Cobj_Case.IsNew Then
' save the case
...
End If

190 IsNew
ClearBasic Object Reference
 ContextualObject object

method Refresh

Syntax Cobj_Yours.Refresh

Applies To ContextualObject

Description Use this method to handle all the updating of displayed controls that are linked to a
contextual object.

Refreshing contextual objects (instead of the individual controls) is sometimes a more

maintainable way of coding, because refreshing a contextual object refreshes all of the
controls linked to that contextual object.

Refreshing either a control or the contextual object linked to that control results in the
display of the updated information from the contextual object. Whether it is optimal
to update the control or the contextual object depends on what you want to
accomplish: refreshing a contextual object updates all the controls that are linked to
that contextual object; whereas refreshing a control only updates that one control.

Parameters None

Return Values None

Example In the following code snippet, an item in a list (trgFildList) is replaced by a new
value and the list is then loaded into a contextual object with the Fill method. Finally,
a custom list control that is linked to the contextual object (take our word for it, since
you can’t see the linkage from the code) is refreshed.

Notice that the control itself is refreshed. The contextual object (Cobj_tTxnFldRec)
could have been refreshed instead. Doing the refresh in this way means that no other
controls that are linked to this contextual object are refreshed.
trgFildList.ReplaceByIndex lnkIndex, trgLnk
Cobj_tTxnFldRec.Fill trgFildList
WIN_1_Field_Arra_014.Refresh

Refresh 191
ClearBasic Object Reference
 ContextualObject object

method Sort

Syntax Cobj_Yours.Sort sortfield1, Options, sortfield2, ... sortfield7

Applies To ContextualObject

Description The Sort method sorts a list or a contextual object that contains a list in ascending
order. If you use the Options parameter to specify a reverse order, then the sorting is
done in descending order.

For lists of records, the field specified by SortField is sorted according to simple
comparisons: alphabetic for strings, arithmetic for numeric values.

Parameters This method takes the following parameters:

Parameter Type Description

sortfield1 String This parameter specifies the field to be used to sort a list of records by. It
must be a valid field name in the records you are sorting.
This parameter is required for lists of records. This parameter is
ignored if it is supplied for a list of simple values (strings, integers,
etc.).
Options Long For normal operation, supply a value of 0.
If you want to inverse the sort order, supply a value of 1. For strings,
this inverses the collating order. For numerics, this sorts in order of
decreasing value.
sortfield2 String You can specify additional fields to sort by if you need to. You can
... specify up to seven fields. However, if more fields are specified than are
sortfield7 required to carry out the sort, then the unneeded fields are not used.
You must specify valid field names in the records you are sorting.

Return Values None

192 Sort
ClearBasic Object Reference
 ContextualObject object

property BackColor

Syntax Cobj_Yours.BackColor = "ColorLabel"

Applies To ContextualObject

Description You can use this property only after using the SetColorScheme method to specify
the current color scheme.

The BackColor property allows you to set the background color of a control. You can
set this property for a control indirectly by setting the property on the contextual
object that is linked to the control.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label must
be in the color scheme that is currently in effect for the form in which you are
performing color operations. (See CreateColorScheme and
SetColorScheme.)

See Also ForeColor property

CreateColorScheme method (App object)
SetColorScheme method (App object)

BackColor 193
ClearBasic Object Reference
 ContextualObject object

property Caption

Syntax Setting = Cobj_Yours.Caption

Applies To ContextualObject

Description The Caption property contains a string with the caption assigned to the object in the
User Interface Editor. You can use this property as a display name for the contextual
object. You cannot use this name to refer to the contextual object in your code.

This property is read-only.

194 Caption
ClearBasic Object Reference
 ContextualObject object

property Contents

Syntax YourSimpleVar = Cobj_Yours.Contents

Set YourRecord = Cobj_Yours.Contents
Set YourList = Cobj_Yours.Contents

Applies To ContextualObject

Description The Contents property returns the current value or list of values in the contextual
object. You must declare the return variable properly as a Record, or a List or as
some primitive type, depending on the data type of the contextual object.

IMPORTANT: This property does not work with user defined types. To get the value of a
contextual object that contains user defined types, use the GetContents method.

This property is read-only.

Return Values This method returns the current value in a contextual object. The data type depends
on the data type of the contextual object.

See Also List property

Contents 195
ClearBasic Object Reference
 ContextualObject object

property DataChanged

Syntax RetBoolean= Cobj_Yours.DataChanged

Applies To ContextualObject

Description You can read this property to determine whether modifications were made by the
user. This property indicates whether modifications were made to the contextual
object.

This property is read-only.

IMPORTANT: DataChanged indicates that modifications were made by the user.

Modifications made programmatically through code do not affect this property.

Return Values This property contains the value True if the user modified the contents of the
contextual object, otherwise False.

196 DataChanged
ClearBasic Object Reference
 ContextualObject object

property DataType

Syntax Setting = Cobj_Yours.DataType

Applies To ContextualObject

Description The DataType property contains a string with the data type associated with the
contextual object. This property may contain the name of a specific record or view.
This property may also contain one of the following strings indicating a primitive
data type:
■ "Date"
■ "elapsed time"
■ "List"
■ "Long"
■ "Single"
■ "String"

This property is read-only.

See Also SubType property

DataType 197
ClearBasic Object Reference
 ContextualObject object

property ForeColor

Syntax Cobj_Yours.ForeColor = "ColorLabel"

Applies To ContextualObject

Description You can use this property only after using the SetColorScheme method to specify
the current color scheme.

The ForeColor property allows you to modify the control associated with a
contextual object. Setting this property changes the text color of the linked control.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

If you perform color operations on controls that do not support color, no errors are
generated; the controls simply won’t be colored. This may be useful information if
you want to use multiplatform color operations where color may not be universally
supported for a given control type. For example, the Command Button may be
colored in UNIX, but not on the Macintosh.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label must
be in the color scheme that is currently in effect for the form in which you are
performing color operations. (See CreateColorScheme and
SetColorScheme.)

See Also BackColor property

CreateColorScheme method (App object)
SetColorScheme method (App object)

198 ForeColor
ClearBasic Object Reference
 ContextualObject object

property List

Syntax Set YourRetList = Cobj_Yours.List

Applies To ContextualObject

Description The List property is a read-only property that returns the list associated with the
contextual object, if the contextual object has a list type.

List 199
ClearBasic Object Reference
 ContextualObject object

property Name

Syntax Cobj_Yours.Name

Applies To ContextualObject

Description The Name property contains the name of the contextual object. The returned string
includes the text "CObj_" at the beginning of the object name. Thus, the returned name
is the name you use in your ClearBasic code to identify the contextual object.

This property is read-only. You set this property at design time using the User
Interface Editor.

Example In the following example, if the name of the contextual object is MyContacts, Name
would return Cobj_MyContacts, as shown in the following code fragment.:
Dim MyVal As string

MyVal = Cobj_MyContacts.Name

' MyVal contains the string "Cobj_MyContacts"

200 Name
ClearBasic Object Reference
 ContextualObject object

property SubType

Syntax Setting = Cobj_Yours.SubType

Applies To ContextualObject

Description The SubType property contains a string with the subtype associated with the
contextual object. The subtype property indicates whether the contextual object
contains a single item or a list of items.

This property applies to contextual objects containing a data type that is a record or
view and may contain one of the following strings:
■ "Record"
■ "Record List"

This property is read-only.

See Also DataType property

SubType 201
ClearBasic Object Reference
 ContextualObject object

202 SubType
ClearBasic Object Reference
 DDE object

Description The DDE global object is used to send DDE messages to an external DDE server
application in UNIX environments. This object enables a ClarifyCRM client to access a
server application (such as a CTI application) using DDE messaging in cold link
mode.

Methods This object defines the following methods:

■ DDEExecute method
■ DDEInitiate method
■ DDERequest method
■ DDETerminate method
■ DDETimeout method

ClearBasic Object Reference 203

 DDE object

method DDEExecute

Syntax Dde.DDEExecute channel, cmd$

Applies To DDE

Description The DDEExecute method executes a command in a server application when DDE
functionality is required. The command is defined by the value of cmd$.

NOTE: Refer to the example included in this section that illustrates how the value of cmd$ is
called by the DDEExecute method in CB code.

Parameters The following parameters are accepted by this method:

Parameter Type Description

channel Long This parameter is a long data type representing the DDE channel
number returned from the DDEInititate method.
cmd$ String This parameter is a string data type containing the command to be
executed. The format used by cmd$ is dependent on the receiving
server application.

Example The following example shows how DDEExecute substitutes the value of cmd$ as the
command to be executed:
cmd$ = “CTI_ShowCase,1”
Dde.DDEExecute channel, cmd$

NOTE: In the above example, the 1 represents a required parameter for the ClearBasic
CTI_ShowCase subroutine.

See Also DDEInitiate method

204 DDEExecute
ClearBasic Object Reference
 DDE object

method DDEInitiate

Syntax channel = Dde.DDEInitiate (application$, topic$)

Applies To DDE

Description The DDEInitiate method initializes a DDE link to another application and returns a
unique long number that is subsequently used to refer to the open DDE channel.

Parameters The following parameters are accepted by this method:

Parameter Type Description

application$ String This parameter is a string containing the name of the application
with which a DDE connection will be established.
topic$ String This parameter is a string containing the name of the connection
topic. The possible values for this parameter are determined by your
server application.

Example The following code fragment establishes a DDE conversation, then executes the script
named "CTI_ShowCase".
Sub cmdExecute_click()
Dim channel as long

channel = Dde.DDEInitiate(“ClarifyApp”, _
”Clarify”)
Dde.DDETimeout(2000)
cmd$ = “CTI_ShowCase,1”
Dde.DDEExecute channel, cmd$
Dde.DDETerminate channel
End Sub

Note that the name of the server application is "ClarifyApp", and the connection topic
is "Clarify."

See Also DDEExecute method

DDETerminate method
DDETimeout method

DDEInitiate 205
ClearBasic Object Reference
 DDE object

method DDERequest

Syntax Dde.DDERequest (channel, DataItem$)

Applies To DDE

Description The DDERequest method returns the value of the given data in the receiving
application associated with the open DDE channel. The value returned is a string
variant.

Parameters The following parameter is accepted by this method:

Parameter Type Description

channel Long This parameter is an integer used to refer to an open DDE channel.
DataItem$ String This parameter is a string variant representing a global application
object data item in the receiving server application associated with
the open DDE channel.

Example The following code fragment tells the ClarifyCRM application server to execute the
script named "CTI_ShowCaseNoID" with no return parameter value.
Sub cmdDdeRequest_Click()
Dim channel as long
channel = Dde.DDEInitiate(“ClarifyApp”,”Clarify”)
Dde.DDETimeout(2000)
Dde.DDERequest(channel, “CTI_SHOWCaseNoID”)
Dde.DDETerminate channel
End Sub

See Also DDEExecute method

206 DDERequest
ClearBasic Object Reference
 DDE object

method DDETerminate

Syntax Dde.DDETerminate channel

Applies To DDE

Description The DDETerminate method closes the specified DDE channel after execution.

Parameters The following parameter is accepted by this method:

Parameter Type Description

channel Long This parameter is a long data type containing the DDE channel
number returned from the DDEInititate method.

Example The following code fragment tells the ClarifyCRM application server to close the
connection to the DDE channel after execution.
Sub cmdDdeRequest_Click()
Dim channel as long

channel = Dde.DDEInitiate(“ClarifyApp”,”Clarify”)
Dde.DDETimeout(2000)
Dde.DDERequest(channel, “CTI_SHOWCaseNoID”) _
Dde.DDETerminate channel
End Sub

See Also DDEInitiate method

DDETerminate 207
ClearBasic Object Reference
 DDE object

method DDETimeout

Syntax Dde.DDETimeout milliseconds

Applies To Dde

Description The DDETimeout method sets the time (in milliseconds) that must elapse before any
DDE command times out.

Parameters The following parameters are accepted by this method:

Parameter Type Description

milliseconds Long This parameter is a long data type representing the number of
seconds that must elapse before the DDE command times out. The
default value is 10,000 (ten seconds).

Example The following code fragment tells the DDE command to time out in two (2) seconds.
Sub cmdDdeRequest_Click()
Dim channel as long

channel = Dde.DDEInitiate(“ClarifyApp”,”Clarify”)
Dde.DDETimeout(2000)
App.MsgBox Dde.DDERequest(channel, _
“CTI_SHOWCaseNoID”)
Dde.DDETerminate channel
End Sub

See Also DDEInitiate method

208 DDETimeout
ClearBasic Object Reference
 Debug object

Description The Debug object is used to display debugging information during the execution of
ClearBasic code.

Comments You don’t declare the Debug object; it is created automatically and you just refer to it
as follows:
Debug.Print "Your string here."

Methods This object defines the following methods:

■ Clear method
■ Print method
■ Show method

ClearBasic Object Reference 209

 Debug object

method Clear

Syntax Debug.Clear

Applies To Debug

Description The Clear method clears the contents of the currently posted Debug window. If no
window is posted, nothing is cleared and no error is generated.

Parameters None

Return Values None

210 Clear
ClearBasic Object Reference
 Debug object

method Print

Syntax Debug.Print Item1, Item2, ... Item10

Applies To Debug.

Description The Print method prints the specified items to the Debug window in the order
specified. This method prints all of the items on the same line unless they are
automatically wrapped by the Debug window.

This method supports the printing of user-defined types. Only the first parameter can
be a user defined type. Subsequent parameters can be of any other type. Each call to
this method adds a newline character at the end of the printed items.

Parameters This method accepts the following parameters:

Parameter Type Description

Item1 variable You can specify up to 10 items to print. However, only the first
Item2 item can be a user defined type.
...
Item10

Return Values None

Example The first example below shows a typical use of the Print method used with the
Debug object. The second example shows how you might set some printer properties
before you invoke the Print method on the Printer object.

In the first example, Print is invoked after selList is filled with a list of values.
Debug.Print is used to display the text "The selected list" followed by the values in
selList.
Sub FIELD_ARRAY_Click
Dim selList As List

Set selList = Cobj_SELECT_LIST.Contents

Debug.print "The selected list ", selList
End Sub

Print 211
ClearBasic Object Reference
 Debug object

method Show

Syntax YourDebug.Show

Applies To Debug

Description The Show method displays the debug window during the execution of ClearBasic
code.

IMPORTANT: You cannot use this method to post a standard ClarifyCRM form because this
method does not post any of the standard ClarifyCRM code associated with those forms. If you
use this method to post a default ClarifyCRM form, the form may be displayed, but it will not
function, even if you use the DoDefault method.

Parameters None

Return Values None

212 Show
ClearBasic Object Reference
 EventLogger object

Description You use the EventLogger object to programmatically log data change events to
da_evt_queue table and da_evt_qstatus table. You add rows to these tables to
let other applications know that data in the ClarifyCRM database has changed. For
more information about logging data change events, see the Integration Gateway
Implementation Guide.

The following sample code illustrates how to use the EventLogger object to
programatically log events in the database.
/*Note: This example assumes that “evt1” is defined as a
programmable event*/
Sub TestEventLogger ()
Dim evtLgr As New EventLogger
Dim bulkS As New BulkSave
Dim i As Integer
Dim cRec As New Record
/*Insert a new contact record into bulk object*/
cRec.RecordType = "contact"
cRec.SetField "first_name" , "Mike"
cRec.SetField "last_name", "Smith"
cRec.SetField "phone", "4089657000"
cRec.SetField "e_mail", "mikes@amdocs.com"
bulkS.InsertRecord cRec

/*Set the bulk object into event logger. We want a single

transaction.*/
evtLgr.SetBulk bulkS
evtLgr.AddNewEvent
"evt1","ContactNew","LoggerBo","","","","","",false
evtLgr.SetLogData "TestData-set1-cb", false

/*After save, the events must be created in a single

transaction. Check sqllog*/
bulks.Save
End Sub

Methods This object defines the following methods:

■ ActivateEvents method
■ AddNewEvent method
■ SetLogData method
■ UpdateAll method
■ SetBulk method

Properties None

ClearBasic Object Reference 213

 EventLogger object

method ActivateEvents

Syntax ReturnVal = evtLgr.ActivateEvents ("eventName", "triggerName",

"focusObjid”, "externData", “publisherName")

Applies To ClarifyDB

Description The ActiveEvents method activates the programmatic events specified in the
ExternData parameter. This method gets rows from da_evt_queue table with
fields with values that you specify as parameters. If the operation field in this table
says that the event was programmatically generated by an EventLogger business
object, this method sets the status_code field in the related rows in
da_evt_qstats table to unprocessed (activate). This method is used with
AddNewEvent() method to create deferred events that are processed at a later time.

This method is not supported if called using cbbatch on UNIX.

Parameters This method accepts the following parameters.

Parameter Type Description

eventName String You specify the event name. This parameter value can be null or
empty.
triggerName String You specify the name of the trigger. This parameter value can be
null or empty.
focusObjid String You specify the OBJID of the focus object. This parameter value
can be null or empty.
externData String Specifies the extern_data field.
publisherName String You specify the name of the publisher. This parameter value can
be null or empty.

Return Values None

214 ActivateEvents
ClearBasic Object Reference
 EventLogger object

method AddNewEvent

Syntax ReturnVal = AddNewEvent(“eventName”, “triggerName”,

“eventSource”)
ReturnVal = AddNewEvent(“eventName”, “triggerName”,
“eventSource”, “focusObjectName”, “focusObjid”,
“triggerObjectName”, “triggerObjid”, “externData”, boolean
deferEvent)

Applies To ClarifyDB

Description The AddNewEvent method adds a new row for a data change event to
da_evt_queue table.

If EventLogger finds event metadata for the specified event name, it adds rows to
the da_evt_qstatus table for all the publisher names configured in da_evt_hdr
table. If EventLogger finds no metadata for the event name, then the rows are not
written and an exception is thrown.

Parameters This method accepts the following parameters.

Parameter Type Description

eventName String Specifies the event_name field. This value cannot be null.
triggerName String Specifies the trig_name field.
eventSource String Specifies the event_source field.
focusObjectName String Specifies the focus_obj_type field (such as “case” or
“site”).
focusObjid String Specifies the focus_objid field.
triggerObjectName String Specifies the trig_obj_type field.
triggerObjid String Specifies the trig_objid field.
externData String Specifies the extern_data field.
deferEvent boolean Specifies the status_code field in
table_da_evt_queue. The default is False.
If True, the Clarify publisher does not poll for the event.
You can activate a deferred event by calling
activateEvent.
If you are calling the method from cbbatch on UNIX, do
not pass True for this argument. The activateEvent
method is not supported if called using cbbatch on UNIX.

Return Values None

AddNewEvent 215
ClearBasic Object Reference
 EventLogger object

method SetLogData

Syntax ReturnVal = SetLogData(“logdata”, false)

ReturnVal = SetLogData(“xmlelement”, true)

Applies To ClarifyDB

Description The setLogData method sets the log_data field (event details) in the
da_evt_queue table for the event you added.

Parameters This method accepts the following parameters.

Parameter Type Description

logData String Specifies the log_data field in the form of string value.
EventLogger prepends an uppercase “S” to this value.
xmlElement String Specifies the log_data field in an XML format expected by the
event handler.

Return Values None

216 SetLogData
ClearBasic Object Reference
 EventLogger object

method UpdateAll

Syntax ReturnVal = UpdateAll()

Applies To ClarifyDB

Description The updateAll method adds the rows in memory that you created with
addNewEvent to the da_evt_queue table. Once the events are committed to the
database, they are no longer available to the EventLogger Object.

IMPORTANT: If a bulk object is not set, this method does not commit any events to the
database. For information on setBulk method, see SetBulk on page 218.

Parameters None.

UpdateAll 217
ClearBasic Object Reference
 EventLogger object

method SetBulk

Syntax ReturnVal = evtLgr.SetBulk bulkS

Applies To ClarifyDB

Description This method sets bulk save object for the EventLogger. A valid bulk object needs to be
set in order to call UpdateAll() correctly.

Parameters This method accepts the following parameters.

Parameter Type Description

bulkS BulkSave Bulk Save object

218 SetBulk
ClearBasic Object Reference
 Form object

Description The Form object implements the runtime behavior of a form. A form is a resource
specification that you use to create windows and dialogs in ClarifyCRM. You create
and modify forms using the User Interface Editor.

A form itself is simply a rectangular window onto which you place controls for the
user to manipulate. At runtime, you use the Form object to perform the following
tasks:
■ manage the form and its controls
■ manage the form’s contextual objects
■ manage the form’s context-sensitive menus
■ perform currency conversions
■ process inter-form messages

When you customize the behavior of a form using event handlers, the application
automatically provides the Me keyword as a way to access the Form object. The Me
keyword refers to the form object associated with the current event handler. You can
use this keyword to access any methods and properties of the Form object.

When you want to display a new form, you must create an instance of the Form object
and call its Show method. The Show method loads a specified form resource from the
database and associates it with your Form object.

At runtime, you can close a form by calling the Close method from one of the form’s
event handlers. To hide a form or show a previously hidden form, change the value in
the form’s Visible property.

Managing Forms Most forms contain at least one control with which the user can interact. Many forms
contain multiple controls to display or receive data and to manage the form
interactions. The Form object defines several methods that you can use to manage the
controls on the form.

You can use the Form object to enable or disable all of the controls on the form. The
EnableControls and EnableControlsDeep methods enable all of the controls on
the form and on any child forms, respectively. The DisableControls and
DisableControlsDeep methods let you disable controls.

In addition to manipulating the form’s controls, you can manipulate information

contained on the form itself. You can use the SetUserData method to associate
custom information with the form and then use the GetUserData method to retrieve
that information.

During long operations, you can use the Refresh and ForceRedraw methods to
force rendering updates for the form. Many operations do not update the form
automatically. You can use these methods to redraw the form in these situations.

ClearBasic Object Reference 219

 Form object

Managing The Form object interface includes several methods for managing the contextual
Contextual Objects objects associated with the form. The GetCObjList and GetCBCObj methods return
information about the form’s contextual objects. You can use this information to
retrieve a ContextualObject instance or to retrieve related contextual object
information.

If your form uses extended contextual objects, you can use the methods of the Form
object to retrieve property information for a specific field or method. Each property
consists of a key/value pair that you define at design time using the User Interface
Editor. Each key identifies an important piece of information that can change from
one extended contextual object to another.
You use key/value pairs in your custom code to implement configurable forms. Your
ClearBasic code uses the key/value pair information to configure the form in a
specific way. Changing the form’s configuration requires changes only to the values
assigned to specific keys.

Managing Context- Forms support the display of a context-sensitive menu. The form automatically
Sensitive Menus provides several form-related menu items. Using the methods of the Form object, you
may add additional context-sensitive menu items.

If you add context-sensitive menu items to a form, you must provide an event handler
to respond to the selection of your menu items. The ContextMenu_Select event
handler lets you handle the selection of all your context-sensitive menu items. You
may also implement a ContextMenuDisplaying event handler to modify the state
of your menu items immediately before the menu is displayed.

Working With When a form is first displayed, it uses the default currency associated with it in the
Currency database. The Form object includes methods for managing currency conversions. You
can use these methods to set the form’s currency denomination and to perform
automatic conversions for designated fields.

You use the SetDisplayCurrency method to assign a new default currency to the
form. The SetTargetCurrency method assigns a new destination currency to use
during conversions. To perform a conversion from the default currency to the target
currency, use the ConvertCurrency method.
You can link the currency of one form to another form using the InheritCurrency
method. The forms do not need to be related to each other through a parent-child
relationship.

Sending Messages You can change the relationships between two forms at runtime using the
SetParent method. This method establishes a link between two forms at runtime.
You can use this link to send messages between the two forms.

To send messages, you can use any of the notification methods of the Form object. The
NotifyChild, NotifyParent, NotifyTab, and NotifyTabParent methods pass
messages between a parent and child form. To pass messages between to unrelated
forms, use the Notify, NotifyById, or NotifyByKey methods.

220
ClearBasic Object Reference
 Form object

Methods This object defines the following methods:

■ AppendContextMenu method
■ CheckRequired method
■ ClearContextMenu method
■ Close method
■ ConvertCurrency method
■ DisableControls method
■ DisableControlsDeep method
■ DoDefault method
■ EnableControls method
■ EnableControlsDeep method
■ ForceRedraw method
■ GetCBCObj method
■ GetChildKeyList method
■ GetCObjFieldList method
■ GetCObjFieldStaticItem method
■ GetCObjFieldStaticList method
■ GetCObjList method
■ GetCObjMethodKeyList method
■ GetCObjMethodList method
■ GetCObjPropertyKeyList method
■ GetControlByName method
■ GetDisplayCurrency method
■ GetLastError method
■ GetMethodValue method
■ GetPropertyValue method
■ GetUserData method
■ InheritCurrency method
■ Move method
■ Notify method
■ NotifyById method
■ NotifyByKey method
■ NotifyChild method
■ NotifyParent method
■ NotifyTab method
■ NotifyTabParent method
■ Refresh method

221
ClearBasic Object Reference
 Form object

■ SetContextMenuEnabled method
■ SetContextMenuVisible method
■ SetDisplayCurrency method
■ SetFocus method
■ SetParent method
■ SetTargetCurrency method
■ SetUserData method
■ Show method
■ ShowControls method
■ ShowControlsDeep method

Properties This object defines the following properties:

■ ActiveControl property
■ BackColor property
■ Caption property
■ DataChanged property
■ Height property
■ hWnd property
■ Id property
■ Key property
■ Left property
■ Name property
■ ParentKey property
■ ReadOnly property
■ Tag property
■ Top property
■ Visible property
■ Width property
■ WindowState property

222
ClearBasic Object Reference
 Form object

Events This object supports the following events:

■ Activate event
■ ContextMenuDisplaying event
■ ContextMenu_Select event
■ DblClick event
■ Deactivate event
■ Form_Load event
■ Form_Save event
■ MouseDown event
■ MouseUp event
■ Resize event

223
ClearBasic Object Reference
 Form object

method AppendContextMenu

Syntax YourForm.AppendContextMenu ItemName, ItemLabel, AppMenuName,

Separator

Applies To Form

Description The AppendContextMenu method adds a new menu item to the end of the form’s
context-sensitive menu. You can use this method to supplement the menu items
specified using the User Interface Editor.

In addition to adding menu items, you can use this method to add a separator after an
existing menu item. To add a separator, specify True for the Separator parameter.

The menu items you add using this method are enabled and visible initially. To
change the appearance of an item, call the SetContextMenuEnabled or
SetContextMenuVisible method. You can also add code to a
ContextMenuDisplaying event handler to update the appearance of menu items
dynamically.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify an identification string for the menu item. Your
application uses this string to identify the menu item when
calling menu-related methods. This name does not have to be
the same as the menu item’s label.
ItemLabel String Specify the menu-item label. This is the string the user sees in
the menu.
AppMenuName String Specify the menu name associated with the context-sensitive
menu, if any. If the menu item is unique, specify an empty
string ("") for this parameter.
Specify a value for this parameter only if the menu item is
already associated with one of the application menus. When
you specify a value for this parameter, this method links to an
existing menu item rather than create a new one.
Separator Boolean Specify True if the item should be a separator, otherwise
False. If you specify True for this parameter, the ItemLabel
and AppMenuName parameters are ignored.

Return Values None

See Also ContextMenuDisplaying method

SetContextMenuEnabled method
SetContextMenuVisible method

224 AppendContextMenu
ClearBasic Object Reference
 Form object

method CheckRequired

Syntax RetInt = YourForm.CheckRequired(ControlList, SearchChildren)

Applies To Form

Description The CheckRequired method determines if all of the required controls on a form and
its associated tabs are populated. This method checks only text box and multiline text
box controls.

You can use this method to ensure that the user specifies the minimum amount of
information before dismissing the form.

If one or more of the required controls contain no value (or contain only whitespace
characters), this method returns the names of the unpopulated controls in the
ControlList parameter. This method also returns the number of unpopulated controls
as a return value.
The white space characters are not valid entries for populating the text boxes.

Parameters This method uses the following parameter:

Parameter Type Description

ControlList List Output. This parameter must be specified. After the method
execution, this parameter contains a list of the names of the
unpopulated controls, if any.
SearchChildren Long Specify 1 to search the parent form and all of its children for
required fields. Specify 0 to search only the parent form.
This parameter is optional and is set to 1 by default.

Return Values This method returns an integer value that corresponds to the number of required
controls that are unpopulated.

Example The following example code, which should be in a form module, illustrates the use of
the CheckRequired method:
Dim CtrlNameList As New List
Dim Count As Integer
Dim CtrlName As String
Dim Index As Integer

CtrlNameList.ItemType = "String"

Count = Me.CheckRequired(CtrlNameList)

If (Count > 0) then

For Index = 0 to Count - 1

CheckRequired 225
ClearBasic Object Reference
 Form object

'extracting the control name from the list

CtrlName = CtrlNameList.ItemByIndex(Index)

'error-handling code goes here

...
Next Index
End If

See Also IsDirty method (Record object)

226 CheckRequired
ClearBasic Object Reference
 Form object

method ClearContextMenu

Syntax YourForm.ClearContextMenu

Applies To Form

Description The ClearContextMenu method removes custom menu items from the form’s
context-sensitive menu. This method removes only menu items that were added
using the AppendContextMenu method of the form. This method does not remove
application-specific menu items or menu items added in the User Interface Editor.

Parameters None

Return Values None

See Also AppendContextMenu method

ClearContextMenu 227
ClearBasic Object Reference
 Form object

method Close

Syntax YourForm.Close Options

Applies To Form

Description The Close method closes a form that is currently displayed and removes it from the
screen.

If you want to close child forms when you close the parent, use the Options parameter
to send a message to all child forms to close themselves. Notice that this requires the
child forms to have a message handling procedure to handle that close message.

IMPORTANT: If you use the Options parameter, all children must "agree" to close themselves
or the parent will not be closed. If a child form refuses to close, the parent is not closed and an
error message is posted to indicate that the close operation was cancelled.

Parameters This method accepts the following parameter:

Parameter Type Description

Options Long Optional. Use this parameter to close all child forms before closing
the parent.
If you want to use this parameter, you must supply the constant
cbCloseChildren

Return Values None

Example The following example illustrates a common use of Close, namely invoked on a form
as a result of a Done button click event.
Sub Done_Click
Me.Close
End Sub

See Also Show method

Visible method

228 Close
ClearBasic Object Reference
 Form object

method ConvertCurrency

Syntax YourForm.ConvertCurrency

Applies To Form

Description The ConvertCurrency method converts the currency values in the form using the
current conversion settings. Before calling this method you must call the
SetTargetConversion method to set the target currency. You may also call the
SetDisplayConversion method to specify a source currency other than the
default.

Parameters None

Return Values None

Example The following example implements a button Click event handler. When the user
presses the button, the event handler converts the values in all currency controls to
the new currency (specified by the SetTargetCurrency method).
Sub MyBtn1_Click
Dim rec1 as Record
Dim list1 as New List
Dim rec2 as New Record
Dim bulk1 as New BulkRetrieve
Dim date1 as Date
Dim convertAll as Boolean

date1 = App.CurrentDate
convertAll = TRUE

bulk1.SimpleQuery 0, "currency"
bulk1.RetrieveRecords

' Set the source currency to the first

' currency object in the bulkretrieve.
Set list1 = bulk1.GetRecordList(0)
set rec1 = list1.ItemByIndex(0)
Me.SetDisplayCurrency rec1, convertAll

' Set the target currency to the second

' currency object in the bulkretrieve.
Set rec2 = list1.ItemByIndex(1)
Me.SetTargetCurrency rec2, cstr(date1)

' Perform the conversion

Me.ConvertCurrency
End Sub

ConvertCurrency 229
ClearBasic Object Reference
 Form object

See Also SetDisplayCurrency method

SetTargetCurrency method]
ConvertCurrencyValue method (App object)

230 ConvertCurrency
ClearBasic Object Reference
 Form object

method DisableControls

Syntax YourForm.DisableControls "C1", "C2", ..."C10"

RetInt = YourForm.DisableControls ("C1", "C2", ..."C10")

Applies To Form

Description You can use this method to disable multiple controls on a form. Although you could
use the Enabled property to disable individual controls in a form, this method is the
quickest way to disable several controls.

You can supply either single control names as the input to this method, or you can
supply a list or lists of control names.
If you try to disable a control that is already disabled, no error results, the disabled
control is simply unaffected.

The use of this method affects the Enabled property so that Enabled contains the
correct control state (enabled/disabled) after this method is invoked.

Parameters This method takes the following parameters:

Parameter Type Description

C1 String You must specify a control name string to disable, or a list of control
name strings.
C2 ... C10 String These parameters are optional. You can specify up to 10 control name
strings or up to 10 lists of control strings.

Return Values This method returns the number of controls actually disabled.

Example The following code snippet shows a typical use of the DisableControls method.
Notice that the value is checked to make sure both controls are disabled.
RetInt = me.DisableControls("REVIEW","REPLACE")

If RetInt <> 2 Then

‘do something
End If

See Also DisableControlsDeep method

EnableControls method
EnableControlsDeep method

DisableControls 231
ClearBasic Object Reference
 Form object

method DisableControlsDeep

Syntax YourForm.DisableControlsDeep "C1", "C2", ..."C10"

RetInt = YourForm.DisableControlsDeep ("C1", "C2", ... C10)

Applies To Form

Description You can use this method from as parent form to disable multiple controls on tabs,
frames, and the parent from itself.

You can supply either single control names as the input to this method, or you can
supply a list or lists of control names.

If a control with the same name exists on the parent form, on one or more of the tabs,
and/or on a frame, the method searches for the control first in the parent form, then in
the fronted tab, followed by other tabs and any posted frames. The method disables
only the control that it encounters first and then processes the next specified control if
any.

NOTE: This method cannot be used to disable controls on a child form created by CB code.

If you try to disable a control that is already disabled, no error results, the disabled
control is simply unaffected.

The use of this method affects the Enabled property so that Enabled contains the
correct control state (enabled/disabled) after this method is invoked.

Parameters This method takes the following parameters:

Parameter Type Description

C1 String You must specify a control name string to disable, or a list of control
name strings.
C2 ... C10 String These parameters are optional. You can specify up to 10 control name
strings or up to 10 lists of control strings.

Return Values This method returns the number of controls actually disabled that the method
disabled. Previously disabled controls are not counted.

Example The following code snippet shows a typical use of the DisableControlsDeep
method. Notice that the value is checked to make sure both controls are disabled. The
controls can be existing on the parent form, tabs, and/or frames.
RetInt = me.DisableControlsDeep("REVIEW","REPLACE")

If RetInt <> 2 Then

‘do something
End If

232 DisableControlsDeep
ClearBasic Object Reference
 Form object

See Also DisableControls method

EnableControls method
EnableControlsDeep method

DisableControlsDeep 233
ClearBasic Object Reference
 Form object

method DoDefault

Syntax YourForm.DoDefault
RetLong = YourForm.DoDefault()

Applies To Form

Description The ClarifyCRM applications consist of forms and controls that have a predefined
default behavior. For example, the Case window has default behavior for the Find
Caller button.

If you write your own Form_Load event procedure for one of these forms, you must
invoke DoDefault in that Form_Load procedure, preferably near the beginning of
the procedure. Otherwise, the standard default ClarifyCRM behavior will not be
performed in that form.

If you are performing modifications to non form areas, say the main ClarifyCRM
application menubar, where you want to add behavior to a standard menu item, you
need to call App.DoDefault inside your event handler for that menu item click.

IMPORTANT: If you do not invoke DoDefault in the Form_Load of a ClarifyCRM default

form, subsequent calls to DoDefault in other event procedures in the form will not work.

Parameters None

Return Values This method returns the following values:

Value Description
cbNoDefault No ClarifyCRM default is defined.
cbDefClosedWindow The default causes the form to close

See Also DoDefault method (App object)

234 DoDefault
ClearBasic Object Reference
 Form object

method EnableControls

Syntax YourForm.EnableControls "C1", "C2", ... "C10"

RetInt = YourForm.EnableControls ("C1", "C2", ... "C10")

Applies To Form

Description You can use this method to enable multiple controls on a form. Although you could
use the Enabled property to enable individual controls in a form, this method is the
quickest way to enable several controls.

You can supply either single control names as the input to this method, or you can
supply a list or lists of control names.
If you try to enable a control that is already enabled, no error results, the enabled
control is simply unaffected.

The use of this method affects the Enabled property so that Enabled contains the
correct control state (enabled/disabled) after this method is invoked.

Parameters This method takes the following parameters:

Parameter Type Description

C1 String You must specify a control name string to enable, or a list of control
List name strings.
C2 ... C10 String These parameters are optional. You can specify up to 10 control name
List strings or up to 10 lists of control strings.

Return Values This method returns the number of controls actually enabled.

Example The following code snippet shows a typical use of the EnableControls method.
Notice that the value is checked to make sure both controls are enabled.
RetInt = me.EnableControls("REVIEW","REPLACE")
If RetInt <> 2 Then
‘do something
End If

See Also DisableControls method

DisableControlsDeep method
EnableControlsDeep method

EnableControls 235
ClearBasic Object Reference
 Form object

method EnableControlsDeep

Syntax YourForm.EnableControlsDeep "C1", "C2", ... "C10"

RetInt = YourForm.EnableControlsDeep ("C1", "C2", ... "C10")

Applies To Form

Description You can use this method from a parent from to enable multiple controls on tabs, on
frames, as well as on the parent form itself

You can supply either single control names as the input to this method, or you can
supply a list or lists of control names.

If a control with the same name exists on the parent form, on one or more of the tabs,
and/or on a frame, the method searches for the control first in the parent form, then in
the fronted tab, followed by other tabs and any posted frames. The method enables
only the control that it encounters first and then processes the next specified control if
any.

NOTE: This method cannot be used to enable controls on a child form created by CB code.

If you try to enable a control that is already enabled, no error results, the enabled
control is simply unaffected.

The use of this method affects the Enabled property so that Enabled contains the
correct control state (enabled/disabled) after this method is invoked.

Parameters This method takes the following parameters:

Parameter Type Description

C1 String You must specify a control name string to enable, or a list of control
List name strings.
C2 ... C10 String These parameters are optional. You can specify up to 10 control name
List strings or up to 10 lists of control strings.

Return Values This method returns the number of controls actually enabled that the method enables.
The previously enabled controls are not counted.

Example The following code snippet shows a typical use of the EnableControls method.
Notice that the value is checked to make sure both controls are enabled. The controls
can be existing on the parent form, tabs, and/or frames.
RetInt = me.EnableControlsDeep("REVIEW","REPLACE")
If RetInt <> 2 Then
‘do something
End If

236 EnableControlsDeep
ClearBasic Object Reference
 Form object

See Also DisableControls method

DisableControlsDeep method
EnableControls method

EnableControlsDeep 237
ClearBasic Object Reference
 Form object

method ForceRedraw

Syntax YourForm.ForceRedraw

Applies To Form

Description During the execution of a ClearBasic procedure, redraw is delayed until the entire
procedure is finished in order to obtain better performance. In most cases, this works
transparently.

However, in some cases this behavior may be undesirable, especially where your code
manipulates the GUI in ways that affect user access to forms or controls, such as
operations that enable or disable controls. What could happen here, is that controls
may not actually be disabled (or enabled) until the entire procedure is finished
executing. This could result in unexpected results or crashes.

In these situations, use the ForceRedraw method to force execution of the code up to
the point where ForceRedraw is called.

Parameters None

Return Values None

Example In the following procedure, a command button is disabled, then ForceRedraw is

invoked, then some other code (not shown) is executed. If you don’t invoke
ForceRedraw immediately after the button is disabled, the user can still generate
click events up until the completion of the rest of the procedure.
Sub My_Btn_Click
My_Btn.Enabled = False
Me.ForceRedraw

'The rest of the event procedure code follows.

...

End Sub

See Also Refresh method

238 ForceRedraw
ClearBasic Object Reference
 Form object

method GetCBCObj

Syntax Set RetCObj = YourForm.GetCBCObj (CObjName)

Applies To Form

Description The GetCBCObj method returns a ContextualObject instance corresponding to

the contextual object with the specified name. You can use the returned object to
manipulate the contents of the contextual object.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the desired extended contextual object.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.

Return Values Returns the ContextualObject instance with the specified name.

Example The following example iterates through the contextual objects in the form. For each
contextual object, the example retrieves the corresponding ContextualObject
instance and manipulates the contextual object data.
Dim cobjList as New List
Dim cobjName as String
Dim i as Long
Dim myCObj as ContextualObject

set cobjList = Me.GetCObjList

for i = 0 to cobjList.Count
cobjName = cobjList.ItemByIndex(i)
myCObj = Me.GetCBCObj(cobjName)

’ Manipulate the CObj contents here.

Next

See Also GetCObjList method

ContextualObject object

GetCBCObj 239
ClearBasic Object Reference
 Form object

method GetChildKeyList

Syntax Set KeyList = YourForm.GetChildKeyList

Applies To Form

Description The GetChildListKey method returns the list of child window keys associated
with the form. The child windows associated with this form can be tabs or frames
associated with the form at design time. You can also assign child windows to the
form using the SetParentKey method at runtime.

This method returns keys for only those windows that are currently loaded into
memory. When a form is loaded, only the default tab is loaded automatically. Other
tabs are loaded on demand as they are clicked. In addition, child frames are only
loaded as needed when the user clicks the corresponding frame command button.

You can use this method in conjunction with the GetFormInstance method to
retrieve a Form object for a given child window. You can then use the Form object to
perform additional operations on the child window.

Parameters None

Return Values Returns a List object containing zero or more Long integers. Each integer in the list
corresponds to the Key property of an existing child form.

Example The following example iterates through the child forms of the parent and refreshes
their contents.
Dim keyList as New List
Dim key as Long
Dim currentForm as Form

set keyList = Me.GetChildKeyList

for i = 0 to keyList.Count
key = keyList.ItemByIndex(i)
set currentForm = App.GetFormInstance(key)

currentForm.Refresh
Next

See Also Key method

GetFormInstance method (App object)

240 GetChildKeyList
ClearBasic Object Reference
 Form object

method GetCObjFieldList

Syntax Set FieldList = YourForm.GetCObjFieldList (eCObjName)

Applies To Form

Description The GetCObjFieldList method returns the names of the fields associated with an
extended contextual object. You can use the returned field names in subsequent
method calls to access the properties for that field.

The fields of a contextual object are the same as the fields of the corresponding record.
You cannot add extra fields to the extended contextual object. An extended contextual
object that represents primitive types such as strings and integers does not have fields.

Parameters This method accepts the following parameters:

Parameter Type Description

eCObjName String Specify the name of the desired extended contextual object.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.

Return Values Returns a List object containing one or more strings. Each string contains the name
of a field belonging to the extended contextual object. The strings in the list are in no
particular order.

Example The following example iterates through the key/value pairs of the first field in a
contextual object.
Dim cobjList as New List
Dim fieldList as New List
Dim keyList as New List
Dim cobjName as String
Dim fieldName as String
Dim keyName as String
Dim value As String
Dim i as Long

' Get the first extended contextual object of the form

set cobjList = Me.GetCObjList
if cobjList.Count > 1 Then
cobjName = cobjList.ItemByIndex(0)
set fieldList = _
Me.GetCObjFieldList(cobjName)

' Get the first field of the cobj

if fieldList.Count > 1 Then
fieldName = fieldList.ItemByIndex(0)
set keyList = Me.GetCObjPropertyKeyList _

GetCObjFieldList 241
ClearBasic Object Reference
 Form object

(cobjName, fieldName)

' Iterate through the key/value pairs

for i = 0 to keyList.Count
keyName = keyList.ItemByIndex(i)
value = Me.GetPropertyValue _
(cobjName, fieldName, keyName)

' Process the key/value information

End If
End If

See Also GetCObjPropertyKeyList method

242 GetCObjFieldList
ClearBasic Object Reference
 Form object

method GetCObjFieldStaticItem

Syntax YourForm.GetCObjFieldStaticItem CObjName, FieldName, ItemName,

UserData, IsDefault

Applies To Form

Description The GetCObjFieldStaticItem method retrieves information about an item in a

static dropdown list. This method is provided as a convenience for accessing grid
information stored in an extended contextual object. If your form does not use
extended contextual objects, use the methods of the Grid control to retrieve the
dropdown list information instead.
When calling this method, you must specify the names of the extended contextual
object and the field containing the dropdown list. Use the
GetCObjFieldStaticList method to get a list of the items in the dropdown list.

NOTE: If the field does not use a static dropdown list control, this method raises an error.

Parameters This method takes the following parameters:

Parameter Type Description

CObjName String Specify the name of the extended contextual object.
The name you specify must not include the "cobj_" string
normally prepended to the name of the contextual object.
FieldName String Specify the name of a field in the contextual object. The field must
be displayed in the grid and must use a dropdown list control to
display its contents.
ItemName String Specify the name of the item in the dropdown list of the field.
UserData String Specify an empty String object. On return, this string contains the
user data associated with the item.
IsDefault Boolean Specify an empty Boolean variable. On return, this variable
contains True if the specified item is the default item, otherwise it
contains False.

Return Value None

Example The following example retrieves the user data for the first item in a grid dropdown
list. The dropdown list is associated with the ownership field of the lorBusOrg
extended contextual object. This field uses a static list to store the types of ownership
available to an organization.
Dim myList as New List
Dim myItem as String
Dim myData as String
Dim itemDefault as Boolean

GetCObjFieldStaticItem 243
ClearBasic Object Reference
 Form object

set myList = Me.GetCObjFieldStaticList _

("lorBusOrg", "ownership")

If myList.Count > 0 Then

myItem = myList.ItemByIndex(0)
Me.GetCObjFieldStaticItem "lorBusOrg", _
"ownership", myItem, myData, _
itemDefault

' Process the item...

End If

See Also GetCObjFieldStaticList method

GetUserPopupListLevel1 method
GetUserPopupListLevel2 method
GetChoiceListUserData method (Grid object in the ClearBasic Control Reference)
GetChoiceListDefault method (Grid object in the ClearBasic Control Reference)

244 GetCObjFieldStaticItem
ClearBasic Object Reference
 Form object

method GetCObjFieldStaticList

Syntax Set ItemList = YourForm.GetCObjFieldStaticList (CObjName,

FieldName)

Applies To Form

Description The GetCObjFieldStaticList method retrieves the dropdown list items for the
specified field. This method is provided as a convenience for accessing grid
information stored in an extended contextual object. If your form does not use
extended contextual objects, use the methods of the Grid control to retrieve the
dropdown list information instead.
When calling this method, you must specify the names of the extended contextual
object and field containing the dropdown list. The dropdown list associated with the
field must be a static dropdown list.

NOTE: If the field does not use a static dropdown list control, this method raises an error.

Parameters This method takes the following parameters:

Parameter Type Description

CObjName String Specify the name of the extended contextual object.
The name you specify must not include the "cobj_" string normally
prepended to the name of the contextual object.
FieldName String Specify the name of a field in the contextual object. The field must be
displayed in the grid and must use a dropdown list control to
display its contents. If the field does not use a dropdown list, this
method raises an error.

Return Value Returns a List object containing one or more strings. Each string corresponds to an
item in the field’s dropdown list.

Example The following example retrieves the user data for the first item in a grid dropdown
list. The dropdown list is associated with the ownership field of the lorBusOrg
extended contextual object. This field uses a static list to store the types of ownership
available to an organization.
Dim myList as New List
Dim myItem as String
Dim myData as String
Dim itemDefault as Boolean

set myList = Me.GetCObjGridDropDownList _

("lorBusOrg", "ownership")

If myList.Count > 0 Then

GetCObjFieldStaticList 245
ClearBasic Object Reference
 Form object

myItem = myList.ItemByIndex(0)
Me.GetCObjGridDropDownItem "lorBusOrg", _
"ownership", myItem, myData, _
itemDefault

' Process the item...

End If

See Also GetCObjFieldStaticItem method

246 GetCObjFieldStaticList
ClearBasic Object Reference
 Form object

method GetCObjList

Syntax Set CObjList = YourForm.GetCObjList

Applies To Form

Description The GetCObjList method returns the names of the contextual objects linked to the
form. The name of each contextual object does not include the "CObj_" string
normally found at the beginning of a contextual object name.

Parameters None

Return Values Returns a List object containing zero or more strings. Each string in the list contains
the name of one contextual object associated with the form. The strings in the list are
in no particular order.

Example The following example iterates through the contextual objects in the form.
Dim cobjList as New List
Dim cobjName as String
Dim i as Long
Dim myCObj as ContextualObject

set cobjList = Me.GetCObjList

for i = 0 to cobjList.Count
cobjName = cobjList.ItemByIndex(i)
myCObj = Me.GetCBCObj(cobjName)

’ Manipulate the CObj contents here.

Next

See Also GetCBCObj method

GetCObjList 247
ClearBasic Object Reference
 Form object

method GetCObjMethodKeyList

Syntax Set KeyList = YourForm.GetCObjMethodKeyList (CObjName,

MethodName)

Applies To Form

Description The GetCObjMethodKeyList method returns the keys associated with the specified
method. You can use each key to retrieve its corresponding value.
You must define the key/value pairs of a method at design time using the User
Interface Editor. At runtime, you can retrieve key/value pairs and use the returned
information to provide additional information for the method.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the contextual object containing the
desired method.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.
MethodName String Specify the name of the desired method.

Return Values Returns a List object containing zero or more strings. Each string contains one key
associated with the method. The strings in the list are in no particular order.

Example The following example iterates through the key/value pairs of the first field in a
contextual object.
Dim cobjList as New List
Dim methodList as New List
Dim keyList as New List
Dim cobjName as String
Dim methodName as String
Dim keyName as String
Dim value As String
Dim i as Long

' Get the first contextual object of the form

set cobjList = Me.GetCObjList
if cobjList.Count > 1 Then
cobjName = cobjList.ItemByIndex(0)
set methodList = _
Me.GetCObjMethodList(cobjName)

' Get the first method of the cobj

if methodList.Count > 1 Then
methodName = methodList.ItemByIndex(0)

248 GetCObjMethodKeyList
ClearBasic Object Reference
 Form object

set keyList = Me.GetCObjMethodKeyList _

(cobjName, methodName)

' Iterate through the key/value pairs

for i = 0 to keyList.Count
keyName = keyList.ItemByIndex(i)
value = Me.GetMethodValue _
(cobjName, methodName, keyName)

' Process the key/value information

End If
End If

See Also GetMethodValue method

GetCObjMethodKeyList 249
ClearBasic Object Reference
 Form object

method GetCObjMethodList

Syntax Set MethodList = YourForm.GetCObjMethodList (CObjName)

Applies To Form

Description The GetCObjMethodList returns the names of the methods associated with the
specified contextual object. Each method represents a specific action that can be
performed on the contextual object’s data.

You must define methods at design time using the User Interface Editor. For each
method you define, you must define a minimal set of key/value pairs. For a list of
these key/value pairs, see the User Interface Editor Guide.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the contextual object containing the
desired method.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.

Return Values Returns a List object containing zero or more strings. Each string contains the name
of a method associated with the contextual object. The strings in the list are in no
particular order.

Example The following example iterates through the key/value pairs of the first field in a
contextual object.
Dim cobjList as New List
Dim methodList as New List
Dim keyList as New List
Dim cobjName as String
Dim methodName as String
Dim keyName as String
Dim value As String
Dim i as Long

' Get the first contextual object of the form

set cobjList = Me.GetCObjList
if cobjList.Count > 1 Then
cobjName = cobjList.ItemByIndex(0)
set methodList = _
Me.GetCObjMethodList(cobjName)

' Get the first method of the cobj

if methodList.Count > 1 Then
methodName = methodList.ItemByIndex(0)

250 GetCObjMethodList
ClearBasic Object Reference
 Form object

set keyList = Me.GetCObjMethodKeyList _

(cobjName, methodName)

' Iterate through the key/value pairs

for i = 0 to keyList.Count
keyName = keyList.ItemByIndex(i)
value = Me.GetMethodValue _
(cobjName, methodName, keyName)

' Process the key/value information

End If
End If

See Also GetCObjMethodKeyList method

GetCObjMethodList 251
ClearBasic Object Reference
 Form object

method GetCObjPropertyKeyList

Syntax Set PropList = YourForm.GetCObjPropertyKeyList (CObjName,

FieldName)

Applies To Form

Description The GetCObjPropertyKeyList method returns the keys associated with the
specified field. You can also use this method to retrieve the keys associated with the
contextual object itself.

You must define the key/value pairs of a field at design time using the User Interface
Editor. At runtime, you can retrieve key/value pairs and use the returned information
to manipulate the field.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the contextual object containing the desired
field and property values.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.
FieldName String Specify the name of a field belonging to the contextual object.
To retrieve the keys associated with the contextual object itself,
specify an empty string for this parameter.

Return Values Returns a List object containing zero or more strings. Each string contains one key
associated with the field. The strings in the list are in no particular order.

Example The following example iterates through the key/value pairs of the first field in a
contextual object.
Dim cobjList as New List
Dim fieldList as New List
Dim keyList as New List
Dim cobjName as String
Dim fieldName as String
Dim keyName as String
Dim value As String
Dim i as Long

' Get the first contextual object of the form

set cobjList = Me.GetCObjList
if cobjList.Count > 1 Then
cobjName = cobjList.ItemByIndex(0)
set fieldList = _
Me.GetCObjFieldList(cobjName)

252 GetCObjPropertyKeyList
ClearBasic Object Reference
 Form object

' Get the first field of the cobj

if fieldList.Count > 1 Then
fieldName = fieldList.ItemByIndex(0)
set keyList = Me.GetCObjPropertyKeyList _
(cobjName, fieldName)

' Iterate through the key/value pairs

for i = 0 to keyList.Count
keyName = keyList.ItemByIndex(i)
value = Me.GetPropertyValue _
(cobjName, fieldName, keyName)

' Process the key/value information

End If
End If

See Also GetCObjFieldList method

GetPropertyValue method

GetCObjPropertyKeyList 253
ClearBasic Object Reference
 Form object

method GetControlByName

Syntax Set MyControl = YourForm.GetControlByName ("ControlName")

Applies To Form

Description The GetControlByName method gets the control by its internal name (not label).
The control must exist in the current form, tab, or frame.

Parameters The method accepts the following parameter:

Parameter Type Description

ControlName String Specify the name of the control you want. The name you
specify is the internal name of the control, not the label
displayed to the user.

Return Value This method returns the control specified by Control Name.

Example The following code snippet illustrates the use of this method:
Dim Cont_1 As Control

Set Control_1 = Me.GetControlByName ("Test")

Control_1.Enabled = False

254 GetControlByName
ClearBasic Object Reference
 Form object

method GetDisplayCurrency

Syntax YourForm.GetDisplayCurrency CurrencyRec Convertible

Applies To Form

Description The GetDisplayCurrency method returns the default currency denomination of

the form. By default, this method returns the currency denomination specified by the
system administrator in the Policies and Customers application. However, you may
change this currency using the SetDisplayCurrency method.

The Convertible parameter indicates whether the form’s currency controls display
converted values when a conversion is performed. This setting overrides the control’s
own Convertible property, which you set using the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

CurrencyRec Record Specify an empty record of type "currency". On return, this record
contains information about the default currency.
Convertible Boolean Specify an empty Boolean variable. On return, this variable
contains a value which indicates whether currency controls
display converted values.

Return Values None

Example The following example retrieves the default currency denomination and uses the
name of that currency to set the default contents of a text box (TxtBox1).
Sub Form_Load
Dim rec1 as Record
Dim curName as String
Dim editable as Boolean

rec1.recordType = "currency"

Me.GetDisplayCurrency rec1, editable

curName = rec1.GetField("name")
TextBox1.Value = curName
End Sub

See Also SetDisplayCurrency method

GetDisplayCurrency 255
ClearBasic Object Reference
 Form object

method GetLastError

Syntax RetInt = YourForm.GetLastError(ErrorString, noReset)

Applies To Form

Description The value returned by this method indicates whether the save operation was
successful or was aborted via a Form_Save1 callback. Normally you use it after the
Me.DoDefault to determine whether a save operation behind Me.DoDefault, if
there was one, was successfully completed or aborted because of certain conditions
encountered in a Form_Save1 callback.

If the noReset parameter is specified as FALSE or is omitted, the return value is reset
before any subsequent call to GetLastError under similar conditions. This way,
GetLastError returns a new value after the subsequent call.

If the noReset parameter is specified as TRUE, the return value is not reset and is
retained until explicitly reset. You can use this functionality to execute additional code
based on the return value of the previous GetLastError operation; that is, based on
whether the previous save was successful or not. In such cases, you must make sure
that you reset the return value before calling GetLastError again after a new
BulkSave.Save operation.
You can reset the return value by calling GetLastError without the noReset
parameter.

Parameters This method uses the following parameters:

Parameter Type Description

ErrorString String Specify an empty string variable. On return, this variable contains
the text describing the error.
noReset Boolean Optional. Boolean TRUE or FALSE. If omitted, default is FALSE.

Return Values Returns a Long integer containing the error code associated with the last save
operation. If the operation was successful, this value is zero; otherwise, this method
returns the value cbSaveAborted.

Example In the following example, a user initiates the Save_Click subroutine by clicking the
Save button. Then, the following sequence of events occur:

1. Assuming that the Me.DoDefault statement has a save operation behind it, it
passes control to Form_Save1.

2. In Form_Save1, if a specified condition is not met, the

BulkSave.Save_Aborted property is set to TRUE and the save is aborted. If,
however, the condition is met, the save is performed.

256 GetLastError
ClearBasic Object Reference
 Form object

3. If save is not aborted, control passes to Form_Save2 and/or Form_Save3, if

present in the form module. After that, control returns to the statement
immediately following the Me.DoDefault statement.

4. If save is aborted, the execution exits Form_Save1 and control returns to the
statement immediately following the Me.DoDefault statement.

5. The call to the GetLastError method inserts the return value in ErrorCode.
The return value is either a non-zero (equal to cbSaveAborted) if the save
was aborted or a zero if the save was performed successfully.

6. Since GetLastError was called with the second parameter set to TRUE, the
return value in ErrorCode is retained until explicitly reset.

7. Subroutine UpdateRecord is called and GetLastError is again called to

check what the last error was, which will be the same as is returned in Step 4
above.

Since GetLastError is called without the second parameter, ErrorCode

contains a return value that is reset before GetLastError is called again.

8. UpdateRecord checks ErrorCode to determine whether the save was

performed or aborted. It then performs the appropriate operation. (Inserts the
record or generates an error message.)
Sub Save_Click()

Dim ErrorCode As Integer

Dim ErrorString As String

Me.DoDefault
ErrorCode = Me.GetLastError(Errorstring, TRUE)
If Not ErrorCode Then
Debug.print "ErrorCode:" & Str$(Errorcode)
Debug.print "ErrorString:" & Errorstring
End If

UpdateRecord
End Sub

Sub Form_Save1(BSaveObj as BulkSsave)

Dim MyRec As Record
Dim NewRec As Record
Dim BulkSav As BulkSave

If(Invalid) Then
'Invalid is pseudo code for some condition

BSaveObj.SaveAborted = TRUE
Exit Sub
Else
Set MyRec = Cobj_CustList.Contents
Bulksav.InsertRecord MyRec
BulkSav.Save
End If
End Sub

Sub UpdateRecord()

GetLastError 257
ClearBasic Object Reference
 Form object

Dim MyRec As Record

Dim BulkSav As BulkSave
Dim ErrorCode As Long
Dim ErrorString As String

ErrorCode = Me.GetLastError(ErrorString)

If ErrorCode <> cbSaveAborted Then

Set MyRec = Cobj_CusList.Contents
BulkSav.UpdateRecord MyRec
BulkSav.Save
Else
App.msgbox"Record was not inserted, so no _
need to update."
End If
End Sub

See Also Form_Save method

Save_Aborted property (BulkSave object)

258 GetLastError
ClearBasic Object Reference
 Form object

method GetMethodValue

Syntax Value = YourForm.GetMethodValue(CObjName, MethodName, KeyName)

Applies To Form

Description The GetMethodValue method returns the value associated with the specified key of
a method. You use key/value pairs to store design information along with the
method.

You must define the key/value pairs of a method at design time using the User
Interface Editor. At runtime, you can retrieve key/value pairs and use the returned
information to provide additional information for the method.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the contextual object containing the
desired method.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.
MethodName String Specify the name of the desired method.
KeyName String Specify the desired key.

Return Values Returns a string containing the value that corresponds to the specified key.

Example The following example iterates through the key/value pairs of the first field in a
contextual object.
Dim cobjList as New List
Dim methodList as New List
Dim keyList as New List
Dim cobjName as String
Dim methodName as String
Dim keyName as String
Dim value As String
Dim i as Long

' Get the first contextual object of the form

set cobjList = Me.GetCObjList
if cobjList.Count > 1 Then
cobjName = cobjList.ItemByIndex(0)
set methodList = _
Me.GetCObjMethodList(cobjName)

' Get the first method of the cobj

if methodList.Count > 1 Then
methodName = methodList.ItemByIndex(0)

GetMethodValue 259
ClearBasic Object Reference
 Form object

set keyList = Me.GetCObjMethodKeyList _

(cobjName, methodName)

' Iterate through the key/value pairs

for i = 0 to keyList.Count
keyName = keyList.ItemByIndex(i)
value = Me.GetMethodValue _
(cobjName, methodName, keyName)

' Process the key/value information

End If
End If

See Also GetCObjMethodKeyList method

260 GetMethodValue
ClearBasic Object Reference
 Form object

method GetPropertyValue

Syntax Value = YourForm.GetPropertyValue(CObjName, FieldName, KeyName)

Applies To Form

Description The GetPropertyValue method returns a value associated with a field. Use this
method to retrieve the value portion of a key/value pair associated with the field.

You must define the key/value pairs of a field at design time using the User Interface
Editor. At runtime, you can retrieve key/value pairs and use the returned information
to manipulate the field.

Parameters This method accepts the following parameters:

Parameter Type Description

CObjName String Specify the name of the contextual object containing the
desired field.
The name you specify must not include the "Cobj_" string
normally used when referring to a contextual object in code.
FieldName String Specify the name of the desired field.
KeyName String Specify the key string that corresponds to the desired value.

Return Values Returns a string containing the value that corresponds to the specified key.

Example The following example iterates through the key/value pairs of the first field in a
contextual object.
Dim cobjList as New List
Dim fieldList as New List
Dim keyList as New List
Dim cobjName as String
Dim fieldName as String
Dim keyName as String
Dim value As String
Dim i as Long

' Get the first contextual object of the form

set cobjList = Me.GetCObjList
if cobjList.Count > 1 Then
cobjName = cobjList.ItemByIndex(0)
set fieldList = _
Me.GetCObjFieldList(cobjName)

' Get the first field of the cobj

if fieldList.Count > 1 Then
fieldName = fieldList.ItemByIndex(0)
set keyList = Me.GetCObjPropertyKeyList _

GetPropertyValue 261
ClearBasic Object Reference
 Form object

(cobjName, fieldName)

' Iterate through the key/value pairs

for i = 0 to keyList.Count
keyName = keyList.ItemByIndex(i)
value = Me.GetPropertyValue _
(cobjName, fieldName, keyName)

' Process the key/value information

End If
End If

See Also GetCObjPropertyKeyList method

262 GetPropertyValue
ClearBasic Object Reference
 Form object

method GetUserData

Syntax Set UserDataList = YourForm.GetUserData

Applies To Form

Description The GetUserData method returns any user-specific data items associated with the
form. Use this method to retrieve information you added with the SetUserData
method.

Parameters None

Return Values Returns a List object containing your form-specific data.

Example The following example retrieves the user data

Sub Form_Load
Me.DoDefault
End Sub

Sub MyBtn2_Click()
Dim parentInst as Variant
Dim parentForm as New Form
Dim myList As New List

parentInst = Me.ParentKey
Set parentForm =
App.GetFormInstance(parentInst)
Set myList = parentForm.GetUserData

' Do something with the user data...

End Sub

See Also SetUserData method

GetUserData 263
ClearBasic Object Reference
 Form object

method Hide

Syntax YourForm.Hide

Applies To Form

Description The Hide method hides the form. Call this method after displaying the form with the
Show method. To show a form after hiding it, set its Visible property to True.

Parameters None

Return Values None

See Also Show method

Visible property

264 Hide
ClearBasic Object Reference
 Form object

method InheritCurrency

Syntax YourForm.InheritCurrency FormInstance, Inherit

Applies To Form

Description The InheritCurrency method lets your form inherit its currency behavior from
another form. You can use this method on a child form to allow it to inherit the
currency behavior of its parent form. However, a form may also inherit the currency
behavior of a form that is not its parent.

If a form already inherits its currency behavior from another form, you can also use
this method to remove that dependence. Specify False for the Inherit parameter to
remove the dependence.

Parameters This method uses the following parameters:

Parameter Type Description

FormInstance Form Specify the Form object from which to inherit the currency
behavior.
Inherit Boolean Specify True if you want the form to inherit its currency behavior
from the form specified in the FormInstance parameter. Specify
False to

Return Values None

Example The following example associates a child form with a parent form. The key of the
parent form is stored in the parentKey global variable.
Global parentKey as GlobalLong

Sub Form_Load
Dim inherit as Boolean
Dim ParentForm as Form

Set ParentForm = _
App.GetFormInstance(parentKey)
inherit = TRUE

Me.InheritCurrency ParentForm, inherit

End Sub

See Also SetDisplayCurrency method

InheritCurrency 265
ClearBasic Object Reference
 Form object

method Move

Syntax YourForm.Move Left, Top, Width, Height

Applies To Form

Description The Move method moves a form from one location to another on the screen. The form
must be visible in order to be moved.

Parameters This method accepts the following parameters:

Parameter Type Description

Left Long You must specify a positive integer for the new coordinate of the left
edge of the form. This number specifies the distance in pixels from the
left edge of the display.
Top Long This parameter is optional. Specify a positive integer for the new
coordinate of the top of the form. The number specifies the distance in
pixels from the top of the display.
If you don’t specify this parameter, the previous value for the top of the
form is used.
Width Long This parameter is optional. Specify a positive integer for the width of
the form. The number specifies the width in pixels of the form.
If you don’t specify this parameter, the previous value for the width of
the form is used.
Height Long This parameter is optional. Specify a positive integer for the height of
the form. The number specifies the height in pixels of the form.
If you don’t specify this parameter, the previous value for the height of
the form is used.

Return Values None

266 Move
ClearBasic Object Reference
 Form object

method Notify

Syntax FormToNotify.Notify MessageNumber, "MessageString"

Applies To Form

Description Use this method to send a message to an unrelated form (that is, to a form that is not a
child form or a parent form). Messages can be ClarifyCRM defined messages that are
sent as the result of default ClarifyCRM behavior, or user-defined messages.

The advantage of this method, as compared to NotifyById, is that this is an instance

method. That is, you can notify the exact instance of a form, which is useful if you
post multiple instances of a form.

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must have the following
prototype:
Sub Message(ByVal MessageNumber As Long, _
ByVal MessageString As String)
Select Case MessageNumber
Case cbCloseMessage
Me.Close
...
Case Else
Me.DoDefault
End Select

...
End Sub

There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

MessageNumber Long You must specify a constant that identifies the message. You can
specify one of the following ClarifyCRM-defined messages:
cbCloseMessage
cbRefreshMessage
You can also specify your own message, for example,
cbFirstMessage. See the chapter titled "Message Handling,"
in the ClearBasic Programmer’s Guide for more information.
MessageString String This parameter is optional. You can specify any string you want
to pass with the message.

Return Values None

Notify 267
ClearBasic Object Reference
 Form object

Example See the chapter titled Message Handling, in the ClearBasic Programmer’s Guide for more
information.

See Also NotifyById method

NotifyByKey method
NotifyChild method
NotifyParent method
NotifyTab method
NotifyTabParent method

268 Notify
ClearBasic Object Reference
 Form object

method NotifyById

Syntax YourForm.NotifyById FormID, MessageNumber, MessageString

Applies To Form

Description Use this method to send a message from a form to all instances of the form with the
specified FormID. NotifyById uses the design time form id, not an instance id. For
example, if you were going to do Me.NotifyById 411, 5122, "Hey You", and
you had two new instances of Form 411 posted, NotifyById sends that same message
to all instances of that FormId In this case, you might want to use Notify or
NotifyByKey instead.

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must include the following
prototype:
Sub Message(ByVal MessageNumber As Long, _
ByVal MessageString As String)
...
End Sub

There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

FormID Long You must specify the FormID of the form you want to send the
message to. (The FormID for a form is created at design time.)
MessageNumber Long You must specify a value or constant that identifies the
message.You can specify one of the following ClarifyCRM-
defined messages:
cbCloseMessage
cbRefreshMessage
You can also specify your own message, e.g., cbFirstMessage.
See the chapter titled "Message Handling," in the ClearBasic
Programmer’s Guide for more information.
MessageString String This parameter is optional. You can specify any string you want
to pass with the message.

Return Values None

NotifyById 269
ClearBasic Object Reference
 Form object

Example The following code illustrates the use of this method.

Sub USE_DONE_Click
Me.NotifyById 1051, 9005
Debug.print "Did my NotifyById"
Me.Close
End Sub

See the chapter titled Message Handling, in the ClearBasic Programmer’s Guide for more
information.

See Also Notify method

NotifyByKey method
NotifyChild method
NotifyParent method

270 NotifyById
ClearBasic Object Reference
 Form object

method NotifyByKey

Syntax YourForm.NotifyByKey Key, MessageNumber, "MessageString"

Applies To Form

Description You use this method to send a notification from one instance of a form to an instance
(identified by key) of the same or another form.

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must include the following
prototype:
Sub Message(ByVal MessageNumber As Long, _
ByVal MessageString As String)
'Sample message-handling code
If MessageNumber = 1051 Then
Debug.Print "Form got the message."
Else
Debug.Print "Form did not get the message"
End If
End Sub

There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

Key Long Long. You must specify the Key for a specific instance of the
form you want to send the message to. (Each instance of a form
is identified by a unique key.)
MessageNumber Long Long. You must specify a value or constant that identifies the
message.You can specify one of the following ClarifyCRM-
defined messages:
cbCloseMessage
cbRefreshMessage
You can also specify your own message, e.g., cbFirstMessage.
See the chapter titled "Message Handling," in the ClearBasic
Programmer’s Guide for more information.
MessageString String String. This parameter is optional. You can specify any string
you want to pass with the message.

Return Values None

NotifyByKey 271
ClearBasic Object Reference
 Form object

Example The following code illustrates the use of this method.

Sub USE_DONE_Click
Dim newform1 As New Form

newform1.Show 1051, 0

Me.NotifyByKey newform1.key, 1051

Debug.print "Did my NotifyByKey"
Me.Close
End Sub

See the chapter titled Message Handling, in the ClearBasic Programmer’s Guide for more
information.

See Also Notify method

NotifyById method
NotifyChild method
NotifyParent method
NotifyTab method
NotifyTabParent method

272 NotifyByKey
ClearBasic Object Reference
 Form object

method NotifyChild

Syntax ParentForm.NotifyChild MessageNumber, "MessageString"

Applies To Form

Description Use this method to send a message from a parent form to a child form. (You must use
the SetParent method to create the parent form/child form relation before you use
this method.) This notifies all of the parent’s child forms.

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must include the following
prototype:
Sub Message(ByVal MessageNumber As Long, _
ByVal MessageString As String)

There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

MessageNumber Long You must specify a value or constant that identifies the message.
You can specify one of the following ClarifyCRM-defined
messages:
cbCloseMessage
cbRefreshMessage
You can also specify your own message, e.g.,
cbFirstMessage. See the chapter titled "Message Handling,"
in the ClearBasic Programmer’s Guide for more information.
MessageString String This parameter is optional. You can specify any string you want
to pass with the message.

Return Values None

Example The following code illustrates this method: it sends a message to child forms to close
before closing the parent form.
Sub DONE_Click
Me.NotifyChild cbCloseMessage
Me.Close
End Sub

NotifyChild 273
ClearBasic Object Reference
 Form object

See Also Notify method

NotifyById method
NotifyByKey method
NotifyParent method
NotifyTab method
NotifyTabParent method
SetParent method

274 NotifyChild
ClearBasic Object Reference
 Form object

method NotifyParent

Syntax ChildForm.NotifyParent MessageNumber, "MessageString"

Applies To Form

Description Use this method to send a message from a child form to a parent form. (You must use
the SetParent method to create the parent form/child form relation before you use this
method.)

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must include the following
prototype:
Sub Message(ByVal MessageNumber As Long, _
ByVal MessageString As String)

There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

MessageNumber Long You must specify a value or constant that identifies the message.
You can specify one of the following ClarifyCRM-defined
messages:
cbCloseMessage
cbRefreshMessage
You can also specify your own message, e.g., cbFirstMessage.
See the chapter titled "Message Handling," in the ClearBasic
Programmer’s Guide for more information.
MessageString String This parameter is optional. You can specify any string you want
to pass with the message.

Return Values None

Example The following example illustrates the use of this method:

Sub Done_Click
Me.NotifyParent cbFirstMessage + 1, _
"Enable button"
Me.Close
End Sub

NotifyParent 275
ClearBasic Object Reference
 Form object

See Also Notify method

NotifyById method
NotifyByKey method
NotifyChild method
NotifyTab method
NotifyTabParent method

276 NotifyParent
ClearBasic Object Reference
 Form object

method NotifyTab

Syntax YourForm.NotifyTab MessageNum, "MessageString", TabId

Applies To Form

Description This method passes MessageNum and the optional MessageString from a parent form
or from another tab to the tab identified by TabId. If TabId is omitted, the
MessageNum is passed to all tabs and posted frames if any.

NOTE: You cannot use this method from a child to notify a tab of the parent.

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must include the following
prototype:
Sub Message(ByVal MessageNumber As Long, _
ByVal MessageString As String)

There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

MessageNum Long Required. This is the message number you want to pass to the
tab(s). The valid value for this parameter is cbFirstMessage and
up. For example, you could specify cbFirstMessage+1,
cbFirstMessage+2, etc.
MessageString String This parameter is optional. You can specify any string you want to
pass with the message.
TabId Long Optional. Tab window Id. Identifies the tab to be notified. It must
be specified if you want to notify a specific tab.

Return Value None

See Also NotifyTabParent method

NotifyTab 277
ClearBasic Object Reference
 Form object

method NotifyTabParent

Syntax YourForm.NotifyTabParent MessageNum, "MessageString"

Applies To Form

Description This method passes MessageNum and the optional MessageString from a tab to its
parent form. You can also use this method to notify the parent form itself.

NOTE: You cannot use this method to notify the parent form from a child form created by CB
code.

If you want a form to receive messages that are sent by this or other methods, or from
the normal operation of the ClarifyCRM application, the form must include a
procedure to handle the messages, and that procedure must include the following
prototype:
Sub Message(ByVal MessageNumber As Long, ByVal
MessageString As String)
There can only be one message procedure for a form.

Parameters This method accepts the following parameters:

Parameter Type Description

MessageNum Long Long. Required. This is the message number you want to pass from
the tab to the parent form. The valid value for this parameter is
cbFirstMessage and up. For example, you could specify
cbFirstMessage+1, cbFirstMessage+2, etc.
MessageString String This parameter is optional. You can specify any string you want to
pass with the message.

Return Value None

See Also Notify method

NotifyById method
NotifyByKey method
NotifyChild method
NotifyParent method
NotifyTab method
SetParent method

278 NotifyTabParent
ClearBasic Object Reference
 Form object

method Refresh

Syntax YourForm.Refresh

Applies To Form

Description Use this method to force the redrawing of a form, normally to force redraws in the
middle of an event procedure. For example, if an event procedure updates values in a
form, and then calls MsgBox, calling this method before MsgBox forces an update of
the form.

Parameters None

Return Values None

Example In the following code snippet, an item in a list (trgFildList) is replaced by a new
value and the list is then loaded into a contextual object with the Fill method.
Finally, a custom list control that is linked to the contextual object (take our word for
it, since you can’t see the linkage from the code) is refreshed.

Notice that the control itself is refreshed. The contextual object (Cobj_tTxnFldRec)
could have been refreshed instead. Doing the refresh in this way means that no other
controls that are linked to this contextual object are refreshed.
trgFildList.ReplaceByIndex lnkIndex, trgLnk
Cobj_tTxnFldRec.Fill trgFildList
WIN_1_Field_Arra_014.Refresh

See Also ForceRedraw method

Refresh 279
ClearBasic Object Reference
 Form object

method SetContextMenuEnabled

Syntax YourForm.SetContextMenuEnabled ItemName, Enabled

Applies To Form

Description The SetContextMenuEnabled method enables or disables a menu item in a

context-sensitive menu. Disabled menu items are displayed in the menu but cannot be
selected by the user. Enabled menu items can be selected and generate an appropriate
menu item event.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The enabled state of the item does not
change until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default enabled state of a
permanent menu item, you must modify the item’s entry in the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This is
the string you assigned to the item in the User Interface Editor or
using the AppendContextMenu method.
Enabled Boolean Specify True to enable the menu item; specify False to disable it.

Return Values None

See Also AppendContextMenu method

SetContextMenuVisible method
ContextMenuDisplaying event
ContextMenu_Select event

280 SetContextMenuEnabled
ClearBasic Object Reference
 Form object

method SetContextMenuVisible

Syntax YourForm.SetContextMenuVisible ItemName, Visible

Applies To Form

Description The SetContextMenuVisible method sets the visibility of a menu item in a

context-sensitive menu. The visibility of a menu item determines whether or not the
item appears in the menu. Calling this method with the Visible parameter set to
False removes the item from the menu. Specifying True for the Visible parameter
displays the item to its original place in the menu.

You can call this method from a ContextMenuDisplaying event handler to adjust
the appearance of the items in the menu. The visible state of the item does not change
until you call this method again.

You may use this method to modify both permanent menu items and those added
using the AppendContextMenu method. To set the default visible state of a
permanent menu item, you must modify the item’s entry in the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

ItemName String Specify the identification string of the desired menu item. This is
the string you assigned to the item in the User Interface Editor or
using the AppendContextMenu method.
Visible Boolean Specify True to make the menu item visible; specify False to hide it.

Return Values None

See Also AppendContextMenu method

SetContextMenuEnabled method
ContextMenuDisplaying event
ContextMenu_Select event

SetContextMenuVisible 281
ClearBasic Object Reference
 Form object

method SetDisplayCurrency

Syntax YourForm.SetDisplayCurrency CurrencyRec, Convertible

Applies To Form

Description The SetDisplayCurrency method sets the default currency denomination used by
the form. Normally, forms use the default currency specified in the Policies and
Customers application. However, you can use this method to assign a different
default currency as appropriate for your form.

The currency you set using this method becomes the source currency during
conversions. The Currency Conversion dialog displays this value in the "From
currency" list by default.

You can use the Convertible parameter to override the Convertible property for
the form’s currency controls. If you specify True for this parameter, all of the form’s
controls display converted values after the user performs a currency conversion. If
you specify False, each control uses its own Convertible property to determine
whether or not to convert its value.

NOTE: You cannot modify the Convertible property of a currency control using
ClearBasic code. To set this property, you must use the User Interface Editor.

Parameters This method uses the following parameters:

Parameter Type Description

CurrencyRec Record Specify a record of type "currency" that corresponds to the new
default display currency.
Convertible Boolean Specify True if you want all currency-related controls to support
conversions.
This parameter is optional and is set to False by default.

Return Values None

Example The following example changes the default currency of the form. The Form_Load
routine queries the database for all records of type "currency" and then sets the default
currency to the first record in the BulkRetrieve object’s result set.
Sub Form_Load
Dim rec1 as Record
Dim list1 as New List
Dim bulk1 as New BulkRetrieve

bulk1.SimpleQuery 0, "currency"
bulk1.RetrieveRecords

282 SetDisplayCurrency
ClearBasic Object Reference
 Form object

Set list1 = bulk1.GetRecordList(0)

Set rec1 = list1.ItemByIndex(1)

Me.SetDisplayCurrency rec1
End Sub

See Also ConvertCurrency method

GetDisplayCurrency method
SetTargetCurrency method

SetDisplayCurrency 283
ClearBasic Object Reference
 Form object

method SetFocus

Syntax YourForm.SetFocus

Applies To Form

Description The SetFocus method sets the focus to the form. When used on a form that is
covered by other forms, this method fronts the form.

The form must be visible for this method to work. This method generates an
Activate event for the form.

Parameters None

Return Values None

See Also Activate event

Deactivate event

284 SetFocus
ClearBasic Object Reference
 Form object

method SetParent

Syntax YourForm.SetParent ParentForm

Applies To Form

Description The parent/child mechanism is useful because it is sometimes difficult to keep track
of whether a child is posted, whether it has a parent, how many children a parent has,
etc. If you use SetParent to set up this relation, then you don't have to worry about
keeping track of children. Forms can be written so that they cooperate; for example, a
form might always send a certain message to its children upon processing a certain
event.

This relationship is maintained in the parent and child form until either form is
closed. Also note that a form can never have more than one parent form

Messages can be forwarded from one form to another form, so that a chain of
messages may result from a single initial message.

Parameters This method accepts the following parameter:

Parameter Type Description

ParentForm Form You must specify the parent form.

Example The following code illustrates the use of this method.

Sub ADD_OBJ_Click
Dim add_obj_win As New Form

add_obj_win.Show 1005, 0
add_obj_win.SetParent me
add_obj.enabled=False
End Sub

See Also Notify method

NotifyChild method
NotifyParent method

SetParent 285
ClearBasic Object Reference
 Form object

method SetTargetCurrency

Syntax YourForm.SetTargetCurrency CurrencyRec, DateString

Applies To Form

Description The SetTargetCurrency method sets the target currency for this form. Normally,
forms use the default currency specified in the Policies and Customers application as
the target currency. However, you can use this method to assign a different target
currency to your form.

The currency you set using this method becomes the destination currency during
conversions. The Currency Conversion dialog displays this value in the "To currency"
list by default.

Parameters This method uses the following parameters:

Parameter Type Description

CurrencyRec Record Specify a record of type "currency" that corresponds to the new
target currency.
DateString String Specify a string containing the conversion date. This information is
used by the Currency Conversion dialog.

Return Values None

Example The following example sets the default and target currencies for the form. When the
user performs a currency conversion, the Currency Conversion dialog displays the
specified target currency in the "To currency" list.
Sub Form_Load
Dim rec1 as Record
Dim list1 as New List
Dim rec2 as New Record
Dim bulk1 as New BulkRetrieve
Dim date1 as Date

date1 = App.CurrentDate

bulk1.SimpleQuery 0, "currency"
bulk1.RetrieveRecords

' Set the default currency

Set list1 = bulk1.GetRecordList(0)
Set rec1 = list1.ItemByIndex(0)
Me.SetCurrencyDisplay rec1

286 SetTargetCurrency
ClearBasic Object Reference
 Form object

' Set the target currency

Set rec2 = list1.ItemByIndex(1)
Me.SetTargetCurrency rec2, cstr(date1)
End Sub

See Also ConvertCurrency method

SetDisplayCurrency method

SetTargetCurrency 287
ClearBasic Object Reference
 Form object

method SetUserData

Syntax YourForm.SetUserData UserDataList

Applies To Form

Description The SetUserData method associates a list of user-specific data items with the form.
You can use this method to store information your code needs for form-specific
operations.

This method does not make a copy of the list in the UserDataList parameter.
Instead, it maintains a reference to the original List object. The example for this
method demonstrates the way to use a form-scoped variable to store the list items.

Parameters This method accepts the following parameters:

Parameter Type Description

UserDataList List Specify the list of items you want to associate with the form.

Return Values None

Example The following example stores the IDs for any child forms as user data with the form.
The Form_Load procedure creates a new List object and assigns it to the variable
myList, which is global to the form module routines. When the user clicks the
specified button, the button event handler retrieves the list of IDs and calls
SetUserData to save them with the form.
' Define a new list variable in the
' form module. This variable is deleted
' automatically when the form is closed.
Dim myList As List

Sub Form_Load()
' Create a new list object
Set myList = New List
End Sub

Sub MyBtn_Click()
Set myList = Me.GetChildKeyList
Me.SetUserData myList
End Sub

See Also GetUserData method

288 SetUserData
ClearBasic Object Reference
 Form object

method Show

Syntax YourForm.Show Form_ID, Options

YourForm.Show Form_ID, Options, "Tag", TagEntity

Applies To Form

Description Use this method to display a new user-created (non-ClarifyCRM) form. The form is
modeless, since ClearBasic does not support modal forms. This method posts the
form along with the ClearBasic code associated with that form. (The form must be a
form created as a new window in the User Interface Editor.)

NOTE: If you want to post a ClarifyCRM form, refer to the appropriate Show method
described later in this document. For example to post the edit contact window, use
ShowContact.

If a form is posted by the Show command, then it is assumed to be a ClearBasic form,

and therefore must have a Form_Load routine. Note the important difference
between ClearBasic forms and ClarifyCRM forms. Forms loaded with ClearBasic do
not have any default behavior.

If your application displays more than one instance of the same form, use the
TagEntity parameter to distinguish between instances of the form. For example, if
your application has a parent form that posts a child form and there can be more than
one instance of the parent, use the TagEntity parameter to uniquely identify the
correct child form.

You can also use this method to display the debug window during the execution of
ClearBasic code.

IMPORTANT: You cannot use this method to post a standard ClarifyCRM form because this
method does not post any of the standard ClarifyCRM code associated with those forms. If you
use this method to post a default ClarifyCRM form, the form may be displayed, but it will not
function, even if you use the DoDefault method.

When this method is used to post a form onto the screen, the Form_Load event is
generated for the form. If the form module contains a Form_Load event procedure,
the procedure is called before the form is drawn on the screen.

Parameters When used on a Form object, this method accepts the following parameters:

Show 289
ClearBasic Object Reference
 Form object

Parameter Type Description

Form_Id Long You must specify the form ID. For example, 1050. This is the ID of a
form you have created in the UI Editor.
Options Long cbFrontIfUp. Supply this constant to prevent multiple instances of a
form from being posted.
cbErrIfNotUp. Use this option in conjunction with the cbFrontIfUp
option to generate an error if any given attribute does not match any
of the posted forms.
If you do not specify the cbFrontIfUp option (or if you specify 0 for
this parameter), this method posts a new instance of the form
regardless of whether an existing instance is open.
TagEntity Variable Specify a unique value for identifying the form. This value must
correspond to the value in the Tag property of the form.
This parameter is optional. Use it to identify a specific instance of a
form when there is more than one to choose from.

Return Values None

Example See the example for the SetParent.

See Also ShowCase method (App object)

ShowContact method (App object)
ShowContract method (App object)
ShowCR method (App object)
ShowEmployee method (App object)
ShowFTS method (App object)
ShowSelect method (App object)
ShowSite method (App object)
ShowSubcase method (App object)

290 Show
ClearBasic Object Reference
 Form object

method ShowControls

Syntax RetInt = YourForm.ShowControls (ControlList, ShowOption)

Applies To Form

Description The ShowControls method shows or hides one or more controls on the specified
form.

When you use this method to hide or show controls, the Visible property for those
controls is set appropriately.

Parameters This method accepts the following parameters:

Parameter Type Description

ControlList List You must provide a list of the control names (string values) that you
want to hide or show. These controls must already exist on the form.
ShowOptions Long Supply a value of 1 to show the controls in the list.
Supply a value of 0 to hide the controls in the list.

Return Values This method returns the number of controls actually shown or hidden.

Example Dim myList As New List

myList.AppendItem "Add", "Replace"

me.ShowControls myList, 0

See Also Visible property

ShowControls 291
ClearBasic Object Reference
 Form object

method ShowControlsDeep

Syntax YourForm.ShowControlsDeep ControlList, ShowOption

RetInt = YourForm.ShowControlsDeep (ControlList, ShowOption)

Applies To Form

Description The ShowControlsDeep method shows or hides one or more controls on the
specified form, its tabs, or frames.

If a control with the same name exists on the parent form, on one or more of the tabs,
and/or on a frame, the method searches for the control first in the parent form, then in
the fronted tab, followed by other tabs and any posted frames. The method shows/
hides only the control that it encounters first and then processes the next specified
control if any.

NOTE: This method cannot be used to show/hide controls on a child form created by CB code.

When you use this method to hide or show controls, the Visible property for those
controls is set appropriately.

Parameters This method accepts the following parameters:

Parameter Type Description

ControlList List You must provide a list of the control names (string values) that you
want to hide or show. These controls must already exist on the form.
ShowOption Long Supply a value of 1 to show the controls in the list.
Supply a value of 0 to hide the controls in the list.

Return Values This method returns the number of controls actually shown or hidden by this control.
Previously hidden/shown controls are not counted.

See Also Visible property

292 ShowControlsDeep
ClearBasic Object Reference
 Form object

property ActiveControl

Syntax Set YourControlVar = YourForm.ActiveControl

Applies To Form

Description The ActiveControl property is a read-only property that allows you to write code
that manipulates the methods and properties of whatever control happens to be
active, without having to write specific code for each control. For example, using the
ActiveControl property would be an efficient way to assign special color attributes
to controls when they get the focus.

When ActiveControl is read, it returns the last active control for the form.

Example In the following sample procedure, the active control is returned to ctrls and is
assigned the caption New.
Sub Test1_Click
Dim ctrls As Control
Set ctrls = form5025.ActiveControl
ctrls.Caption = "New"
End Sub

ActiveControl 293
ClearBasic Object Reference
 Form object

property BackColor

Syntax YourForm.BackColor = ColorLabel

Applies To Form

Description The BackColor property allows you to set the background color of the form. You can
use this property only after using the SetColorScheme method to specify the
current color scheme.

IMPORTANT: Before you can set back or fore colors, you must first create a color scheme (see
CreateColorScheme) that maps available system colors to labels. Then you must use
SetColorScheme to assign that color-to-label mapping to the form where you want to
perform the coloring. The reason for this is that you must specify the label, not the system
color, when you set BackColor or ForeColor.

Settings This property accepts the following settings:

Setting Description
ColorLabel You must specify a label that is mapped to a valid system color. The label must
be in the color scheme that is currently in effect for the form in which you are
performing color operations. (See CreateColorScheme and
SetColorScheme.)

See Also CreateColorScheme method (App object)

SetColorScheme method (App object)

294 BackColor
ClearBasic Object Reference
 Form object

property Caption

Syntax YourForm.Caption = "CaptionTextString"

CaptionString = YourForm.Caption

Applies To Form

Description When used on a form, this property sets the title displayed in the title bar.

IMPORTANT: On some platforms, your caption changes may persist when you display or
redisplay the form. If this happens, set the caption in the Form_Load event procedure for that
form. Also, if the control supports labeling through use of a source contextual object, and you
make this source link at design time, you can use the Fill method on the contextual object to
get the caption to display properly.

Settings This property accepts the following settings:

Setting Description
CaptionTextString Specify the text string.
The default caption is the string defined for the form or control at design
time using the User Interface Editor.

Return Values In read mode, this property returns the title of the form.

Example The following example shows how the caption property can be used for the purposes
of a string comparison.
Sub CompareCaption_Click
Dim str1 As String

Me.Caption = "Instance 1"

str1 = Me.Caption

If str1 = "Instance 1" Then

App.MsgBox "Form is Instance1"
Else
App.MsgBox "Form is not Instance1"
End If
End Sub

Caption 295
ClearBasic Object Reference
 Form object

property DataChanged

Syntax RetBoolean = YourForm.DataChanged

Applies To Form

Description You can read this property to determine whether modifications were made by the
user. This property indicates whether modifications were made to the form by user
interaction (it does not indicate changes made through code).

You can interactively set this property for a form.

IMPORTANT: DataChanged indicates that modifications were made by the user.

Modifications made programmatically through code do not affect this property.

Return Values This property contains the value True if the user made changes to the form, otherwise
False.

Examples The following example shows an event handler used to close the form. If the contents
of the form changed, this handler prompts the user to save the changes.
Sub Close_Click
Dim Ret As Integer

If Me.DataChanged Then
Ret = App.MsgBox ("Save; interrupted?", _
cbSaveDiscardCancel)

If Ret = cbidSave Then

Save.Value = True
Me.Datachanged = False
ElseIf Ret = cbidDiscard Then
Me.Datachanged = False
Else
Exit Sub
End If

Me.DoDefault
End If
End Sub

296 DataChanged
ClearBasic Object Reference
 Form object

property Height

Syntax YourForm.Height = Setting

Setting = YourForm.Height

Applies To Form

Description Use this property to specify the height of a form.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

Return Values This property returns an integer value indicating the current height (in pixels) of the
form.

See Also Width property

Left property
Top property

Height 297
ClearBasic Object Reference
 Form object

property hWnd

Syntax Window = YourForm.hWnd

Applies To Form

Description This read-only property returns the native platform designator (handle) for the form
or control. It is normally used to pass the control or form handle to a C function
available at runtime. Because the value in hWnd can change during runtime, you
should pass hWnd directly to a function rather than store it in a variable.

Return Values The data type of the value returned by hWnd varies by platform:

Platform Data Type

Macintosh WindowPtr
Unix Window
Windows HWND

Example In the following test procedure, a check box handle is returned as a string to be
displayed in a text box. The text box Text property is then checked to make sure the
handle was passed properly.
Sub CheckHandle
Results_TBox.text=str$(Checkbox1.hWnd)

If Results_TBox.text <> "" and _

val(Results_TBox.Text) <> 0 Then
App.MsgBox "Displaying the value"
Else
App.MsgBox "Not Displaying the value"
End If
End Sub

298 hWnd
ClearBasic Object Reference
 Form object

property Id

Syntax FormID = YourForm.Id

Applies To Form

Description This read-only property returns the ID (integer value) of the form. This value is
assigned to the form at design time in the User Interface Editor.

Id 299
ClearBasic Object Reference
 Form object

property Key

Syntax RetInt = YourForm.Key

Applies To Form

Description This read-only property returns the run time instance ID of the posted form, as
opposed to the design time ID. This is useful if you want to post multiple instances of
a form and need to keep track of them.

Return Values This property returns the run time integer ID that was assigned to the form at load
time by the system.

Example The following code snippet illustrates the use of this property.
Dim newform1 As New Form
Dim newform2 As New Form

'create two instances of the same form resource

newform1.Show 1010, 0
newform2.Show 1010, 0

Debug.print "newform1's key is ", newform1.key

Debug.print "newform2's key is ", newform2.key

'The two values should be different

See Also ParentKey property

300 Key
ClearBasic Object Reference
 Form object

property Left

Syntax YourForm.Left = Setting

Setting = YourForm.Left

Applies To Form

Description You can use the Left and Top properties to specify the location (in pixels) of the left
and top side of the form, respectively.

Return Values When read, Left returns the location (in pixels) of the left side of the control or form;
Top returns the location (in pixels) of the top of the control or form.

See Also Move method

Height property
Width property
Top property

Left 301
ClearBasic Object Reference
 Form object

property Name

Syntax FormName = YourForm.Name

Applies To Form

Description This read-only property returns the name (string) that was assigned to the form at
design time in the User Interface Editor.

Example In the following example, if the name of the contextual object is MyContacts, Name
would return Cobj_MyContacts, as follows:
Dim MyVal As string

MyVal = Cobj_MyContacts.Name

‘MyVal contains Cobj_MyContacts

302 Name
ClearBasic Object Reference
 Form object

property ParentKey

Syntax RetLongInt = YourForm.ParentKey

Applies To Form

Description This read-only property returns the run time instance ID of the parent form, as
opposed to the design time ID. The ParentKey property only applies if you have
used SetParent on the form. This is useful if you want to post multiple instances of
a form and need to keep track of them.

Return Values This property returns the run time integer ID that was assigned to the form at load
time by the system.

Example See the example provided for the Key.

See Also SetParent method

Key property

ParentKey 303
ClearBasic Object Reference
 Form object

property ReadOnly

Syntax YourForm.ReadOnly = Setting

Setting = YourForm.ReadOnly

Applies To Form

Description You can use this property to put a form in read-only mode to disable any controls that
could affect data in contextual objects, such as text boxes, custom lists, combo boxes,
and so on. (Command buttons are not disabled.)

You can also test this property on other controls in the form, for example, command
buttons, to make sure that they do not function when the form is read-only.
This property accepts the following settings:

Setting Description
True Set the form in read-only mode.
False Return the form to normal read/write
mode.

304 ReadOnly
ClearBasic Object Reference
 Form object

property Tag

Syntax YourForm.Tag = "YourStringHere"

TagString = YourForm.Tag

Applies To Form

Description The Tag property allows you to assign a string to the object, with no affect other than
identifying the object in some way or providing extra data about it.

Tag 305
ClearBasic Object Reference
 Form object

property Top

Syntax YourForm.Top = Setting

Setting = YourForm.Top

Applies To Form

Description You can use the Left and Top properties to specify the location (in pixels) of the left
and top side of the form, respectively.

Return Values When read, Left returns the location (in pixels) of the left side of the form; Top
returns the location (in pixels) of the top of the form.

See Also Move method

Height property
Width property
Left property

306 Top
ClearBasic Object Reference
 Form object

property Visible

Syntax YourForm.Visible = Setting

Setting = YourForm.Visible

Applies To Form

Description The Visible property contains a boolean value that determines whether the form is
hidden or visible. You can read this property to determine the form’s current visibility
or you can set the property to change the visibility.

Set this property to False to hide the form. Set it to True to make the form visible.

See Also Hide method

Visible property (Control object in the ClearBasic Control Reference)

Visible 307
ClearBasic Object Reference
 Form object

property Width

Syntax YourForm.Width = Setting

Setting = YourForm.Width

Applies To Form

Description You can use this property to specify (integer value) the current width in pixels of the
form.

IMPORTANT: At design time in the User Interface Editor, the size of the form is created with
machine-independent coordinates. At runtime, these coordinates are replaced with machine-
dependent coordinates, which can result in slight variations in size properties for forms.

Return Values When read, this property returns an integer value indicating the current height (in
pixels) of the form.

See Also Height property

Left property
Top property

308 Width
ClearBasic Object Reference
 Form object

property WindowState

Syntax YourForm.WindowState = Setting

Setting = YourForm.WindowState

Applies To Form

Description The WindowState property can be used in the Windows platform to specify whether
the form is maximized, minimized or at its normal size.

The following settings are used:

Setting Description
0 Normal
1 Minimized
2 Maximized

WindowState 309
ClearBasic Object Reference
 Form object

event Activate

Syntax Sub Form_Activate

Applies To Form

Description The Activate event for a form occurs when it becomes the active form. A form can
be made active through user activity such as clicking on a form or on a control in the
form, or it can be made active programmatically by invoking the Show or SetFocus
methods in your code.

This event occurs only on forms that have either been posted (Show method) or that
have their Visible property set to True.

Avoiding Infinite You cannot use MsgBox and InputBox in your Deactivate event handler. Suppose
Loops. you have following line of code in your form module:
Sub Form_Deactivate()
App.Msgbox "Form deactivate"
End Sub

Also, suppose that at some point you post another form. When you attempt to close
that second form the deactivate event will keep posting this msgbox every time you
try to close second form.

310 Activate
ClearBasic Object Reference
 Form object

event ContextMenuDisplaying

Syntax Sub Form_ContextMenuDisplaying

Applies To Form

Description The Form_ContextMenuDisplaying event notifies your form that its context-
sensitive menu is about to be displayed. Use this event to update the appearance of
the menu and its items. You can enable or disable items, set the visibility of items, or
add items to the menu as appropriate.

The form sends this event in response to a user request to display the context-sensitive
menu. The event is sent before the menu is displayed.

In your ContextMenuDisplaying event handler, modify the menu and its

appearance to reflect the current state of the form. For example, you can enable or
disable menu items or set the visibility of items.

See Also AppendContextMenu method

SetContextMenuEnabled method
SetContextMenuVisible method
ContextMenu_Select event

ContextMenuDisplaying 311
ClearBasic Object Reference
 Form object

event ContextMenu_Select

Syntax Sub Form_ContextMenu_Select (EventName)

Applies To Form

Description The ContextMenu_Select event notifies your application that the user chose an
item from the form’s context-sensitive menu. In your event handler, perform the task
associated with the menu item.

You must provide an event handler for each menu item you define in the context-
sensitive menu. You can define menu items at design time using the User Interface
Editor or at runtime using the AppendContextMenu method.

Parameters This event receives the following parameter:

Parameter Type Description

EventName String Contains the name you assigned to the menu item using the User
Interface Editor. If you used the AppendContextMenu method
to create the item, this parameter contains the value you
specified in the ItemName parameter of that method.

See Also AppendContextMenu method

ContextMenuDisplaying event

312 ContextMenu_Select
ClearBasic Object Reference
 Form object

event DblClick

Syntax Sub Form_DblClick

Applies To Form

Description The DblClick event occurs when the user double clicks on the form. It normally is
used to indicate a selection of an item.

DblClick 313
ClearBasic Object Reference
 Form object

event Deactivate

Syntax Sub Form_Deactivate

Applies To Form

Description The Deactivate event for a form occurs just before another form becomes the active
form.

This event occurs only on forms that have either been posted (Show method) or that
have their Visible property set to False.

Avoiding Infinite You cannot use MsgBox and InputBox in your Deactivate event handler. Suppose
Loops you have following line of code in your form module:
Sub Form_Deactivate()
App.Msgbox "Form deactivate"
End Sub

Also, suppose that at some point you post another form. When you attempt to close
that second form the deactivate event will keep posting this msgbox every time you
try to close the second form.

314 Deactivate
ClearBasic Object Reference
 Form object

event Form_Load

Syntax Sub Form_Load

Applies To Form

Description The Form_Load event occurs when a form is posted, normally with the Show
method. In tabbed forms, the parent form’s Form_Load event happens first, then the
default tab’s Form_Load event is processed. The other tabbed forms in that same
parent form have their Form_Load events only in response to subsequent user or
programmatic activity.

In the event procedure for a Form_Load event, you normally need to perform various
types of initialization, such as filling the contextual objects with values, enabling
controls, and so on.

Example For more information regarding how you must code a Form_Load event procedure,
see the ClearBasic Programmer’s Guide.

See Also DoDefault method

Show method

Form_Load 315
ClearBasic Object Reference
 Form object

event Form_Save

Syntax Sub Form_Save1(BulkSaveObj As BulkSave)

Sub Form_Save2(BulkSaveObj As BulkSave)
Sub Form_Save3(BulkSaveObj As BulkSave)

Applies To Form

Description When the ClarifyCRM executable saves data to the database, it uses the same
mechanism that the ClearBasic BulkSave object uses, which is BulkSave.Save.
New and modified objects and relations are added to a BulkSave and committed in a
single transaction. If there is an error, the transaction is automatically rolled back and
deadlocks are automatically detected. Retries are attempted until the transaction
succeeds or a certain configured number of failures is reached.

The three callbacks listed above let you intercept the save operation at various stages
of the save operation as described below.

NOTE: These callbacks are optional. You are not required to use any of them.

Form_Save1 intercepts the save operation before any objids (object IDs) have been
assigned to the new records that are to be committed to the database, including those
which you might have added.

At this stage, based on the conditions you specify, you can do the following:
■ Validate any data and then if the validation fails, abort the save operation.
You do this by setting the Save_Aborted property of the BulkSave
parameter to True and exiting the callback.

NOTE: The Save_Aborted property can only be used when you are working
with Form 411 or 420.

■ Modify and/or add records and relations in the BulkSave object and then
continue with the remainder of the save operation.

Form_Save2 intercepts the save operation after objids have been assigned to the new
records but before committing them to the database.

At this stage, since objids are available, you can fetch the IDs and other pertinent
information about the objects. Then, continue with the save operation.

NOTE: You cannot add records using the existing BulkSave object (or using a new
BulkSave object) from the Form_Save2 callback. You must add new records before calling
the Save method or from the Form_Save1 callback.

Form_Save3 does not intercept the save operation. However, it does allow you to
perform tasks after the completion of a save operation.

316 Form_Save
ClearBasic Object Reference
 Form object

At this stage, you have already committed your BulkSave object to the database.
You can perform some last-minute tasks, such as rolling back the database.

When a save operation is initiated, it automatically scans the appropriate form

module for the presence of any of these callbacks and if found, executes the code in
them prior to actually performing the save operation.

NOTE: For more information about using these Form_Save callbacks, see the ClearBasic
Programmer’s Guide.

Form_Save1 and Me.DoDefault

Suppose you use a Me.DoDefault statement that triggers the save operation in a
subroutine in your form module. Further suppose that you also use Form_Save1
callback in the same form module to abort the save under certain conditions. In such a
situation, you can check if the save operation that might have been specified inside
the Me.DoDefault method was aborted.

NOTE: You can use the Form_Save1 callback to conditionally abort a save operation only
when you are working with Form 411 or 420.

To do this, you use the Me.GetLastError method. A zero return value from this
method indicates that the save operation was not aborted, which in turn means that
either the save was not aborted or the code behind Me.DoDefault did not contain a
save operation. A non-zero value (equal to the constant cbSaveAborted) indicates
that there was a save operation specified inside Me.DoDefault and it was aborted.

Form_Save Scoping You can define globally scoped Form_Save callbacks or you can associate the
callbacks with specific forms. The scope of a set of callbacks is determined by their
location. If you put the callbacks in a form module, they are available only to that
form. If you put them in a global module, they are available to all of your forms and
global routines.

It is preferable to associate a set of Form_Save callbacks with a specific form.

Callbacks associated with a form can be customized to better suit the needs of that
form. In addition, global callbacks do not always execute in multi-tiered
environments. The problem occurs when trying to execute the callback from the
server instead of the client. Two-tiered systems support this operation but three-tiered
systems do not.

IMPORTANT: If your system uses the CallCB method to execute ClearBasic code on the
server, be careful when saving records to the database. Performing a save operation from the
server may not call your Form_Save callbacks as expected.

Calling Sequence When you save a set of records, the ClearBasic Engine searches your code modules for
the appropriate Form_Save callbacks. You may define Form_Save callbacks with a
form module for individual forms or in a global module for use with all forms. The
engine begins looking for callbacks in the current module and calls only the first set of
callbacks it finds.

Form_Save 317
ClearBasic Object Reference
 Form object

For example, when a BulkSave.Save operation is triggered from a Tab, the

ClearBasic Engine looks for Form_Save callbacks in the following modules (in
order):
■ The Tab module
■ The parent module of the tab
■ The global module

If you trigger a BulkSave.Save operation from a global module that is not

associated with a form, the Form_Save callback of a form may still be executed along
with the global callbacks. The rules for executing the form-level callbacks are as
follows:
■ If a workflow object form is active, such as a form for a case or opportunity, the
Form_Save callback of that form is called if it exists.
■ If the active form does not display a workflow object, but a workflow object
form is inactive and in the current context, the active form’s Form_Save
callback is called if it exists.
■ If the active form does not display a workflow object and does not have a
Form_Save callback, but a workflow object form is inactive and in the current
context, then the inactive workflow object form’s Form_Save callback is called.

The current context is determined by calling the GetContext method of the App
object.

Return Value None

Examples The following example illustrates the use of Form_Save1 callback for aborting the
save operation.

NOTE: The save operation can only be aborted from within a Form_Save1 callback and only if
you are working with Form 411 or 420.

Sub Form_Save1(BSaveObj as BulkSsave)

Dim MyRec As Record

Dim NewRec As Record
Dim BulkSav As BulkSave

If(Invalid) Then
'Invalid is pseudo code for some condition

BSaveObj.Save_Aborted = TRUE
App.msgbox"Save was aborted"

Exit Sub
Else
Set MyRec = Cobj_CustList.Contents
Bulksav.InsertRecord MyRec
BulkSav.Save
End If
End Sub

318 Form_Save
ClearBasic Object Reference
 Form object

Sub Save_Click
Dim ErrorCode As Integer
Dim ErrorString As String

Me.DoDefault

ErrorCode = Me.GetLastError(ErrorString)

If ErrorCode = cbSaveAborted
'Error-handling routine goes here
Else
'Continue or do something else
End If
End Sub

When the above code executes and the validation fails, the system executes the error-
handling routine. Also, depending on the value returned in ErrorCode, appropriate
additional code, if any, is executed.

See Also GetLastError method

GetContext method (App object)
CancelRecord method (BulkSave object)
ChangeRecord method (BulkSave object)
CountByType method (BulkSave object)
GetRecordByIndex method (BulkSave object)
Save method (BulkSave object)
Save_Aborted property (BulkSave object)

Form_Save 319
ClearBasic Object Reference
 Form object

event Form_Unload

Syntax Sub Form_Unload

Applies To Form

Description The Form_Unload event occurs when the form is closed, either by a program or user
action. Use this event to clean up any global variables or data structures you created
for the form.

320 Form_Unload
ClearBasic Object Reference
 Form object

event MouseDown

Syntax Sub Form_MouseDown

Applies To Form

Description The MouseDown event occurs when the mouse button is pressed. If the user performs
a double-click, a mouse down event occurs, a mouse up event occurs, and then a
double-click event occurs.

Example The following code segment illustrates the use of this event:
Sub form_MouseDown
App.Msgbox "Mouse is down"
End Sub

See Also DblClick event

MouseDown 321
ClearBasic Object Reference
 Form object

event MouseUp

Syntax Sub Form_MouseUp

Applies To Form

Description The MouseUp event occurs when the mouse button is released. If the user performs a
double-click, a mouse down event occurs, a mouse up event occurs, and then a
double-click event occurs.

Example The following code segment illustrates the use of this event:
Sub form_MouseUp
App.Msgbox "Mouse button was released"
End Sub

See Also DblClick event

MouseDown event

322 MouseUp
ClearBasic Object Reference
 Form object

event Resize

Syntax Sub Form_Resize

Applies To Form

Description The Resize event occurs when a form is resized.

Resize 323
ClearBasic Object Reference
 Form object

324 Resize
ClearBasic Object Reference
 Global Constants

Description If you want to use a global constant in your implementation, you can declare a Global
constant object in the global module. If more than one constant is desired, you must
declare one Global constant object for each constant you want to use.

Declare in global module and in each form. For example, to declare a global string
constant, insert a line like the following in the global module and in each form module
that uses that constant:
Global MyString As GlobalString

Set the value. Then, in the initialize_app procedure, you must instantiate that
global and set its value as follows
Set MyString = New GlobalString
MyString.SetValue "Hello"
Once you set the value of a Global constant object, you cannot reset that value during
the application session. Doing so will result in a runtime error.

Using the constant. When you want to use the constant, simply read its value, for
example:
Debug.Print MyString.Value

IMPORTANT: You must declare the correct type of global constant for the value you want to
use. For example, if you want to use a global constant for an integer value, you must declare
that global as a GlobalInteger. See below for supported types.

Types Supported The following data types can be used with this object:

Type Global Constant

Integer GlobalInteger
Long integer GlobalLong
Float, single GlobalSingle
Float, double GlobalDouble
String GlobalString

ClearBasic Object Reference 325

 Global Constants

The Global constants are declared as follows:

Global MyIntGlob As GlobalInteger
Global MyLongInt As GlobalLong
Global MySingle As GlobalSingle
Global MyDouble As GlobalDouble
Global MyString As GlobalString

Methods This object defines the following method:

■ SetValue method

Properties This object defines the following property:

■ Value property

326
ClearBasic Object Reference
 Global Constants

method SetValue

Syntax YourGlobalConstant.SetValue YourValue

Applies To Global Constants

Description After you declare a Global constant object in the global module, you must invoke
SetValue to set its value, in the Initialize_App procedure in the global module.
That value cannot be reset during the application session. If you try to reset this value,
a runtime error is generated.

See Example ' Global module

Dim gstr As GlobalString
...

Sub initialize_app
Set gstr = New GlobalString
gstr.setvalue "Hello World!"
End Sub

See Also Value property

SetValue 327
ClearBasic Object Reference
 Global Constants

property Value

Syntax YourControl.Value = Setting

Applies To Global Constants

Description The Value property contains the current value stored in the global constant. When
read, this property returns the current value of the global constant.

See Also SetValue method

328 Value
ClearBasic Object Reference
 List object

Description The List object is used for dynamic lists of objects. A List object can contain any
number of other objects (such as controls) or simple values (such as strings). It is more
flexible than an array because the number of values is not fixed.

Although you can explicitly set the type of the list (integer, or string, or Record, etc.),
you are not required to do this. You can simply declare the list then add items to it; the
first item added sets the type of the list, so the AppendItem method implicitly sets
the type of list.

NOTE: You must set the ItemType property for a List object before attempting to set other
properties, such as AllowDuplicates, for that List.

IMPORTANT: The types currency and double are NOT supported for List objects. See the
ItemType on page 353.

Comments To declare a list and set its type (our example sets it to Record type), do the following:
Dim YourList As New List
YourList.ItemType = "Record"

To declare a list without explicitly setting its type, do the following:

Dim YourList As New List
YourList.AppendItem 2

This automatically sets YourList to be a list of integers.

ClearBasic Object Reference 329

 List object

Methods This object defines the following methods:

■ AppendItem method
■ Clear method
■ Concat method
■ Contains method
■ Down method
■ ExtractList method
■ FindFirstIndex method
■ GetItemByIndex method
■ ItemByIndex method
■ ListByIndex method
■ RemoveByIndex method
■ ReplaceByIndex method
■ Sort method
■ Up method

Properties This object defines the following properties:

■ AllowDuplicates property
■ Count property
■ ItemType property
■ Sorted property

330
ClearBasic Object Reference
 List object

method AppendItem

Syntax YourList.AppendItem ItemToAppend1, ItemToAppend2, ...

ItemToAppend9

Applies To List

Description The AppendItem method performs different tasks depending on the object type it is
applied to. This method supports user-defined types.
This method allows you to append up to nine new items or nine lists of items to a list.

For List objects, you can use the AllowDuplicates property to allow or disallow
duplicate values into the list. (But you must set the ItemType of the list first.)

Parameters The method accepts the following parameters:

Parameters Type Values

ItemToAppend1, variable You must specify the first item or list of items you want to
ItemToAppend2, append. The appended item data type must match the data
... type of the list.
ItemToAppend9 IMPORTANT! Only the first parameter (ItemToAppend1) can
be used to append a user defined type or a list of user defined
types.
Specify the second item or list of items you want to add.
You can specify up to nine items or lists of items to add.

Return Values None

Example In the follow sample, testList is set to allow the insertion of duplicate values, then
AppendItem is used to fill testList with duplicate values. If the count of items
appended is not what is expected, the actual count is placed in logStr.
Sub AllowDuplicates_Click
Dim testList As New List
Dim logStr As String

TestList.AllowDuplicates = False
TestList.AppendItem "a","b","c","a","b"

If TestList.count <> 3 Then

logStr = "Append Failed;Got:"+str$ _
(testList.count)
End If
End Sub

AppendItem 331
ClearBasic Object Reference
 List object

See Also Clear method

RemoveByIndex method

332 AppendItem
ClearBasic Object Reference
 List object

method Clear

Syntax YourList.Clear

Applies To List

Description The Clear method removes all of the items from the list. This method does not delete
the items; it disassociates them from the List object.

You must call this method before attempting to change the type of the list using the
ItemType property.

Return Values None

See Also AppendItem method

ItemType property

Clear 333
ClearBasic Object Reference
 List object

method Concat

Syntax YourList.Concat Item1, Item2, ... Item5

Applies To List

Description The Concat method accepts up to five items. These items can be single strings or lists.
If you supply single strings, the string items are concatenated together to form a
single string which is then placed in the specified List object (YourList). If you
supply lists, any non-string values in the lists are converted into strings and
concatenated into a single list, which is then placed in the specified List object
(YourList).

The number of strings in the resulting list is determined by the longest input item. If
all input items are single strings, then the resulting list will contain a single string that
is the concatenation of all the input single strings. If any of the input items are lists,
then the resulting list will contain a number of strings equal to the longest input list.

Using single strings. If you concatenate several single strings, for example "a", "b",
"c", "d", "e", the list object will contain a single string, in this case, "abcde".
Using lists. If you concatenate lists or a combination of lists and strings, a single list is
returned to the list object. The following table shows the resulting list (return list) that
you receive when you concatenate some string constants with some lists
(ReturnList.Concat (Constant1, List1, Constant2, List2, List3):

Constant1 List 1 Constant2 List2 List3 Return List

"A" 0 "B" 2 5 "A0B25"
"A" 1 "B" 3 6 "A1B36"
"A" "B" 4 7 "AB47"
"A" "B" 8 "AB8"

Notice that the return list contains as many strings as List3, which is the list that
contains the most items.

Parameters This method accepts the following parameters:

Parameter Type Description

Item1 List You must specify one string or one list of strings.
String
Item2 List You must specify a second string or list of strings.
String

334 Concat
ClearBasic Object Reference
 List object

Parameter Type Description

Item3 List Optional. You may specify a third string or list of strings.
String
Item4 List Optional. You may specify a fourth string or list of strings.
String
Item5 List Optional. You may specify a fifth string or list of strings.
String

Example The following procedure concatenates a string constant (Part) with 5 items in a list.
The resulting concatenated list (ConList) contains the following five items: Part0,
Part1, Part2, Part3, and Part4.
Sub ConcatParts
Dim PartStr As string
Dim NumList As New List
Dim ConList As New List

PartStr = "Part"
NumList.AppendItem 0, 1, 2, 3, 4
ConList.Concat PartStr, NumList

If ConList.Count <> 5 Then

App.MsgBox "Concat unsuccessful"
Else
App.MsgBox "Concat successful"
End Sub

Concat 335
ClearBasic Object Reference
 List object

method Contains

Syntax YourBoolean = YourList.Contains (ItemToFind)

Applies To List

Description The Contains method searches the list to determine whether an item currently exists
in the list.

Parameters This method takes the following parameter:

Parameter Type Description

ItemToFind variable Specify the item you want to check in the list. The data type of this
parameter must match the type of the items in the list.

Return Values This method returns True if the item is already in the control or list, and False if the
item is not in the control or list.

Example The following test routine shows one use of the Contains method. In the example,
Contains is used to verify that an item has been properly added to a control.

Notice that the count of items in the control is taken before the new item is added.
This means that the index of Clover should be equal to the count.
Sub TestSub_Click
Dim I As integer
Dim J As integer

I= ComboBox1.ListCount
ComboBox1.AppendItem "Clover"
ComboBox1.Refresh
J= ComboBox1.NewIndex

If (J = I) Then
If ComboBox1.Contains("Clover") Then
App.MsgBox "Clover is here!"
Else
App.MsgBox "Clover is not here!"
End If
Else
App.MsgBox "Item not added properly"
End If
End Sub

336 Contains
ClearBasic Object Reference
 List object

method Down

Syntax ItemsMoved = YourList.Down ListToMove

Applies To List

Description The Down method moves the specified item or items in a list down one position.

This method takes an index or list of indexes of the items to move down. The indexes
must be valid for the list that this method is being applied to. The indexed items are
then moved down one spot in the list. If the item is already at the bottom, or if all
items below it are also included in the list to move, then the item remains where it is.

You can use the control methods that return indexes (such as SelectedIndexes) to
return a list of indexes of currently selected items. This list of indexes can be passed
directly to this method to implement a 'Down' button behavior on both single and
multi-select list controls.

Parameters This method accepts the following parameter:

Parameter Type Description

ListToMove List An index or list of indexes of items to move. Each index must be
in the range from 0 to the number of items - 1.

Example In the following example, a loop loads five strings into an empty dropdown combo
box. The strings are sequenced Item 1 to Item 5, and Item 2 is moved down. At this
point, the index of Item 2 should become 2 and the index of Item 3 should become 1.
GetList is used to check this, returning the item at index 1 in the control. If Item 3 is at
that index, the appropriate notification is stored in Logstr.
Sub DownTest
Dim Hold1 As string
Dim Logstr As string

Combo1.clear

For i = 1 to 5
Combo1.AppendItem "item"+Str$(i)
Combo1.Refresh
Next i

Combo1.setSelected "item 2"

Combo1.down 1
Combo1.refresh

Hold1 = Combo1.GetList(1)

If Hold1 = "item 3" Then

Logstr = "Second item moved one position _

Down 337
ClearBasic Object Reference
 List object

down"
Else
Logstr = "Second item did not move down"
End If
End Sub

See Also Up method

338 Down
ClearBasic Object Reference
 List object

method ExtractList

Syntax YourList.ExtractList TargetList,

"sourcefield1", "targetField1",
"sourcefield2", "targetfield2",
...
"sourcefield5", "targetfield5"

Applies To List

Description The ExtractList method copies values from one or more fields in a source list of
records (the records must have the same record type!) and places the values into
specified fields of the corresponding target list of records. For example, if you
specified EmployeeID as the source field and NewEmployeeID as the target field, the
value for EmployeeID is copied from each record in the source list and placed into the
field NewEmployeeID in the target list.

CAUTION: You must specify the field names exactly as defined in the schema. These
parameters are case sensitive and will generate an error if supplied incorrectly.

If you supply only one source field, and do not specify any target field, then this field
is placed into the destination list directly. This is a good way of getting a simple list of
values from a list of records.

Parameters This method accepts the following parameters:

Parameter Type Description

TargetList List You must specify the list into which you want to place the copied
values.
sourcefield1 String You must specify a valid field name in the source list.
targetfield1 String Optional. If you don’t specify the first target field, the values from
sourcefield1 are placed directly into TargetList, which becomes a list
containing simple values, and you cannot specify any additional
source fields.
If you do specify the target field, specify a valid field in TargetList
into which to place the values from sourcefield1.
sourcefield2 String Optional. You can specify a second valid field name in the source list.
targetfield2 String Optional. However, if you specify a field for sourcefield2, you must
specify a field for targetfield2.
sourcefield5 String Optional. You can specify up to five valid fields in the source list.
targetfield5 String Optional. You must specify a valid target field for each source field
that is specified.

ExtractList 339
ClearBasic Object Reference
 List object

Example In the following snippet, contact records are retrieved from a BulkRetrieve object that
already contains the records and are then placed into another list. Then each of the
values in the last_name field in those records is copied over into NameList using
the ExtractList method.
Set ContactList = MyBulk.GetRecordList (0)
ContactList.ExtractList NameList, "last_name"

340 ExtractList
ClearBasic Object Reference
 List object

method FindFirstIndex

Syntax Index = YourList.FindFirstIndex (Value1, "fieldname1", Value2,

"fieldname2", ... Value5, "fieldname5")

Applies To List

Description The FindFirstIndex method searches a list of records using the specified field
name and value. It stops searching when it finds the first record in the list that has a
field name AND value that matches the ones specified. The method returns the index
of that record, or -1 if there is no match. You can specify up to five value and field
name pairs.
For example, if you specify a field named FieldA, and specify Value1 as 1, this method
returns the index of the first record in the list that has FieldA equal to 1.

CAUTION: You must specify the field names exactly as defined in the data dictionary. These
parameters are case sensitive and generate errors if supplied incorrectly.

Parameters This method accepts the following parameters:

Parameter Type Description

Value1 variable You must specify a value to match.
FieldName1 String Optional.
If you are searching a list of simple values of the same type as the
one specified, omit this parameter. If you are searching a list of
records, you must specify the field name to be searched for Value1.
Value2 variable Optional. Specify a second value to match.
FieldName2 String Optional. Specify the field name to be searched for Value2.
Value5 variable Optional. You can specify up to five values to match.
FieldName5 String Optional. You can specify up to five field names to be searched.

Return Values This returns the index of the found entry, or -1 if no match is found.

Example The following code fills some data fields in three records, then appends the records to
a list. FindFirstIndex is used to get the index of the first record whose field city
contains the value Cincinnati. That index is passed to ItemByIndex to get the
actual record, which is dumped into a variable and checked for the value
Cincinnati in field city.
Sub FindFirstTest
Dim SrcList As New List
Dim SRec1 As New Record
Dim SRec2 As New Record
Dim SRec3 As New Record

FindFirstIndex 341
ClearBasic Object Reference
 List object

Dim FoundRec As New Record

Dim RetInd As integer
Dim City As string

SRec1.RecordType = "contact"
SRec1.SetField "first_name", "Jane"
SRec1.SetField "city", "Dayton"

SRec2.RecordType = "contact"
SRec2.SetField "first_name", "Bob"
SRec2.SetField "city", "Cincinnati"

SRec3.RecordType = "contact"
SRec3.SetField "first_name", "Jim"
SRec3.SetField "city", "Cleveland"

SrcList.AppendItem SRec1, SRec2, SRec3

RetInd = SrcList.FindFirstIndex("Cincinnati","city")
Set FoundRec = SrcList.ItemByIndex(RetInd)
City = FoundRec.GetField ("first_name")

If City <> "Cincinnati" Then

App.MsgBox "Test failed."
End If
End Sub

See Also GetItemByIndex method

ItemByIndex method
ListByIndex method

342 FindFirstIndex
ClearBasic Object Reference
 List object

method GetItemByIndex

Syntax YourList.GetItemByIndex Index, ReturnedItem

Applies To List

Description The GetItemByIndex method places the item at the specified index into the
specified return parameter. It can be used with user defined types. This method
generates an error if the index given is out of range or if you specify an empty list for
Index.

Parameters This method accepts the following parameter:

Parameter Type Description

Index Long You can specify either an integer value or a list.
List If you specify an integer value, the index must be an integer
between 0 and the number of items in the list minus 1.
If you specify a list, only the first value in the list is used as the
index.
ReturnedItem variable Specify a variable whose type matches the type of the expected
return value. On return, this parameter contains the value at the
specified index.

Return Values This method places the record at the location given by index into the specified return
parameter.

Example In the following example, the first record in List1 is retrieved into MyTypeRec.
Dim List1 As New List
Dim MyTypeRec As myDefinedType

List1.ItemType = "myDefinedType"

‘Write code here to fill the list

‘after list is filled, get item from list

List1.GetByItemIndex 0, MyTypeRec

GetItemByIndex 343
ClearBasic Object Reference
 List object

method ItemByIndex

Syntax YourSimpleVar = YourList.ItemByIndex (Index)

Set YourRecord = YourList.ItemByIndex (Index)

Applies To List

Description The ItemByIndex method returns the item at the specified index. It does not support
user defined types. (Use GetItemByIndex for user defined types.)

This method generates an error if the index given is out of range or if you specify an
empty list for Index.

Parameters This method takes the following parameter:

Parameter Type Description

Index Long You must specify either an integer value or a list.
List If you specify an integer value, the index must be an integer between 0
and the number of items in the list minus 1.
If you specify a list, the first value in the list is used as the index.

Return Values This method returns the object at the location given by index. If the list is empty, an
error is generated.

Example In the following example, records of type user are obtained from the database into
BulkGet and retrieved from BulkGet into a list (RList). Then ItemByIndex is used to
get the first value in RList.
Dim userName As String
Dim userObj As Record
Dim RList As List
Dim bulkGet As New BulkRetrieve

userName = App.UserName

BulkGet.SimpleQuery 0, "user"
BulkGet.AppendFilter 0, "login_name", cbEqual, _
userName

BulkGet.RetrieveRecords

Set RList = BulkGet.GetRecordList(0)

Set userObj = RList.ItemByIndex(0)

Debug.print "userObj=", userObj

344 ItemByIndex
ClearBasic Object Reference
 List object

See Also GetItemByIndex method

ListByIndex method

ItemByIndex 345
ClearBasic Object Reference
 List object

method ListByIndex

Syntax Set YourReturnList = YourList.ListByIndex (Index)

Applies To List

Description The ListByIndex method returns a list of objects from another list, according to the
index or list of indexes supplied.

Parameters This method accepts the following parameter.

Parameter Type Description

Index Long You must specify the integer index of the object or a list of indexes of
List the objects.

Return Values This method returns a list of the same type as the input list.

See Also GetItemByIndex method

ItemByIndex method

346 ListByIndex
ClearBasic Object Reference
 List object

method RemoveByIndex

Syntax YourList.RemoveByIndex ItemToRemove

Applies To List

Description The RemoveByIndex method removes one item or a list of items from a list, based on
the index or list of indexes provided.

Parameters This method accepts the following parameter:

Parameter Type Description

ItemToRemove Long You must supply either an integer index or list of indexes of the
Short items to remove. If any of the indexes given are out of range, then
List an error is generated

Example The following procedure loops through a list of records, comparing the case_id field
in each record to a supplied case ID (caseStr) and deletes all records whose case ID
matches the one supplied.
Sub RemByCase (ByVal caseStr As String,
recList As List)
Dim obj As New Record
Dim origCount As integer
Dim index As integer
Dim TempStr As String

origCount = recList.Count

For index=origCount-1 to 0 step -1

set obj = recList.ItemByIndex (index)
TempStr = obj.GetField ("case_id")

If caseStr = TempStr Then

recList.RemoveByIndex index
End If
Next index
End Sub

See Also ItemByIndex method

ListByIndex method

RemoveByIndex 347
ClearBasic Object Reference
 List object

method ReplaceByIndex

Syntax YourList.ReplaceByIndex ItemToReplace, NewValue

Applies To List

Description The ReplaceByIndex method allows you to replace an item in a list with an item of
a user defined type. (The list must be set up to contain values of that type.)

This method replaces one or more values in the list with the specified value. The
method accepts an integer index or list of indexes.

Parameters This method accepts the following parameters:

Parameter Type Description

ItemToReplace Long Specify either the index (integer value) or a list containing the
List indexes of the items you want to replace.
NewValue variable Specify the new value to be placed into the specified index or
indexes. You can specify a user defined type if the list is set up
to contain values of that type.

Example The following example shows one way to use this method. The example is an event
procedure for a custom list click event. The index of the selected item is returned to
selIndex and the new replacement value is read from a contextual object into newObj.
The contents of the custom list’s contextual object is dumped into a list (recList) and
the ReplaceByIndex method is then invoked on that list.
Sub TIME_L_REPLC_Click
Dim newObj As Record
Dim selIndex As Integer
Dim recList As List

selIndex = TimeLogCustList.SelectedIndexes
Set newObj = Cobj_EDIT_TIME_LOG.Contents
Set recList = Cobj_TIME_LOG.Contents

recList.ReplaceByIndex selIndex, newObj

End Sub

See Also ItemByIndex method

ListByIndex method
RemoveByIndex method

348 ReplaceByIndex
ClearBasic Object Reference
 List object

method Sort

Syntax YourList.Sort sortfield1, Options, sortfield2, ... sortfield7

Applies To List

Description The Sort method sorts a list or a contextual object that contains a list in ascending
order. If you use the Options parameter to specify a reverse order, then the sorting is
done in descending order.

This method sorts either a list of simple values (such as strings) or a list of records. If
the list contains only simple values, no parameters are required. If the list contains
records, then you must specify one or more fields (you can specify a maximum of
seven fields) to sort by.

CAUTION: These parameters are case sensitive and will generate an error if supplied
incorrectly.

For lists of records, the field specified by SortField is sorted according to simple
comparisons: alphabetic for strings, arithmetic for numeric values.

Parameters This method takes the following parameters:

Parameter Type Description

sortfield1 String This parameter specifies the field to be used to sort a list of records by.
It must be a valid field name in the records you are sorting.
This parameter is required for lists of records. This parameter is
ignored if it is supplied for a list of simple values (strings, integers,
etc.).
Options Long For normal operation, supply a value of 0.
If you want to inverse the sort order, supply a value of 1. For strings,
this inverses the collating order. For numerics, this sorts in order of
decreasing value.
sortfield2 String You can specify additional fields to sort by if you need to. You can
... specify up to seven fields. However, if more fields are specified than
sortfield7 are required to carry out the sort, then the unneeded fields are not
used.
You must specify valid field names in the records you are sorting.

Return Values None

Sort 349
ClearBasic Object Reference
 List object

method Up

Syntax YourList.Up ListToMove

Applies To List

Description The Up method will move one or more items in a list up one position.

This method takes a list of indexes of the items to move up. The indexes must be valid
for the given list (i.e. the list that this method is being applied to). The indexed items
are then moved up one spot in the list. If the item is already at the top, or all items
above it are also included in the list to move, then the item remains where it is.

Parameters This method takes the following parameter:

Parameter Type Description

ListToMove List List of indexes of the items to move. Each index must be in the
range of 0 to the number of items minus one.

Return Values When used on List objects, this method returns the number of items that actually
moved up one position. Note that if an item is at the beginning of the list, or all items
above it are also designated as to be moved up, then this value may be less than the
number of items supplied.

See Also Down method

350 Up
ClearBasic Object Reference
 List object

property AllowDuplicates

Syntax YourList.AllowDuplicates = Setting

Setting = YourList.AllowDuplicates

Applies To List

Description You use the AllowDuplicates property to specify whether duplicate values are to
be allowed in a list when items are added to the list. If you don’t set this property,
duplicate items are allowed.

NOTE: Before you can use this property for a List object, you must set the ItemType
property for that List.

IMPORTANT: AllowDuplicates must be set prior to appending items into the list. If
duplicate values are in a list, setting this property to False doesn’t remove the duplicates.

Settings This property accepts the following settings:

Setting Description
True Allow duplicate values in the list (default).
False Don’t allow duplicate values.

Example In the following sample, testList is set to allow the insertion of duplicate values,
then is filled with duplicate values. If the count of items appended to the list is not
what is expected, the actual count is placed in logStr.
Sub AllowDuplicates_Click
Dim testList As New List
Dim logStr As string

TestList.AllowDuplicates = False
TestList.AppendItem "a","b","c","a","b"

If TestList.count <> 3 Then

logStr = "Append Failed;Got:" _
+str$(testList.count)
End If
End Sub

See Also AppendItem method

AllowDuplicates 351
ClearBasic Object Reference
 List object

property Count

Syntax NumOfItems = YourList.Count

Applies To List

Description The Count property is a read-only property that returns the number of items in the
specified list.

This property returns an integer value which is the number of items in the list. It
returns 0 if there are no items in the list. Lists that have been declared but never used
also have a count of 0.

Example In the following code snippet, Count is used as a statement in an expression.

Dim MyList As New List

MyList.AppendItem "a", "b", "c"

If MyList.Count <> 3 Then

App.MsgBox "Count failed"
End If

352 Count
ClearBasic Object Reference
 List object

property ItemType

Syntax YourList.ItemType = "TypeString"

Applies To List

Description Use this property to specify the type of items that can be placed into the list. (This
restricts the list to receiving only that specified type of item.) Notice that although
record is a valid type, you cannot specify the type of record, for example, you cannot
specify "window_db".

You can set the ItemType property for a List object either explicitly or implicitly by
using the AppendItem method. Once you set the ItemType for a list, you must use
the Clear method before changing to another ItemType.

IMPORTANT: You must set this property for a List object before attempting to set other
properties, such as AllowDuplicates, for that List.

If you use this property on a list that already contains items, those items are cleared
from the list and then the type is set.

Settings This property accepts the following setting:

Setting Valid Values

TypeString "long", "integer", "single", "string", "record", "variant ", "UserDefinedType"
(Use the name string for the user defined type.)
Note: The types currency and double are NOT supported for List objects.

CAUTION: If you assign an ItemType of "variant," you can only use the AppendItem
method on that list. Variant lists are primarily intended to allow you to supply a list of
different types of values as input to stored procedures when you invoke ExecuteProc.

Return Values When read, this property returns (string value) either the item type that was set for
the list or the type of items that are currently in the list.

ItemType 353
ClearBasic Object Reference
 List object

property Sorted

Syntax YourList.Sorted

Applies To List

Description The Sorted property contains a Boolean value indicating whether the contents of the
list are sorted. This property contains the value True if the contents are sorted,
otherwise False.

This property is read-only.

354 Sorted
ClearBasic Object Reference
 PowerQuery object

Description The PowerQuery object provides a mechanism for performing secured queries
spanning multiple object types. The PowerQuery object operates in parallel with the
BulkRetrieve object to provide query-related functionality for your code.

The secured queries feature of PowerQuery objects lets the system administrator
control user access to information in the database. Typically, secured queries let the
system administrator limit the query result set to the subset of records belonging to
the current user. However, you or your system administrator may define additional
rules as needed for your site.

Using PowerQuery You use the PowerQuery object in a similar manner as the BulkRetrieve object.
Objects After you create the object, the first thing you must do is create a new query set by
calling the SetObjectType method. A query set incorporates search and sort criteria
for a single database table. You can add extra query sets as needed to the
PowerQuery object.

For each query set in the PowerQuery object, you can add filters and sort criteria
using the AppendFilter and AppendSort methods, respectively. A filter specifies a
comparison to perform between a field of the database table and a fixed value. During
a query, each filter is applied to each row of the database table. Only those rows that
match all of the criteria are returned in the result set. The sort criteria specifies the
order in which to return the matching rows.

Once you have specified your filters and sort criteria, call the Query method to
execute the query. To retrieve the rows returned by the query, use the RetrieveIDs
or RetrieveRecords method.

Methods This object defines the following methods:

■ AppendFilter method
■ AppendSort method
■ GetCount method
■ Query method
■ RetrieveIDS method
■ RetrieveRecords method
■ SetObjectType method
■ SetSortOrder method

See Also BulkRetrieve object

BulkSave object

ClearBasic Object Reference 355

 PowerQuery object

method AppendFilter

Syntax YourPowerQuery.AppendFilter Index, Path, Operator, Value

Applies To PowerQuery

Description The AppendFilter method adds a single filter to the specified query set. You can
call this method any number of times to add additional filters to a query set. During a
query, only those rows that match all of the filters are returned.

When specifying a value for the Path parameter, you do not need to include the name
of the driving object type in the path. To specify fields of the driving object type,
specify only the name of the field. To specify a field in another object, use relations to
build a complete path to the desired field.

You must set the driving object type of the query set before calling this method.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify the index of the query set to receive the filter information.
Path String Specify the path to the field whose contents you want to use in the
filter.
For fields belonging to the query set’s driving object type, you
need only specify the field name. For fields associated with other
tables, you must use relations to build a path from the driving
object to the field.
Operator String Specify the comparison operator for the filter.This value can be
one of the following strings:
greater than does not start with
greater than or equal to does not end with
less than does not contain
less than or equal to exists
is equal to does not exist
is not equal to today
starts with yesterday
ends with within last (days)
contains within last (hours)
is in between
is not in not between
sounds like
Value String Specify the target value to use in the filter comparison.

Return Values None

356 AppendFilter
ClearBasic Object Reference
 PowerQuery object

Example The following example adds two filters to a new query set. The first filter sets limits
the returned addresses to those that are in California. The second filter limits the
returned address to those where the corresponding company name starts with the
letter "m". For the second filter, the path parameter contains a relation that links the
filter to a field in another table.
Dim MyQuery as New PowerQuery

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", _
"is equal to", "CA",
MyQuery.AppendFilter 0, _
"bus_primary2bus_org:name", _
"starts with", "m"

' Retrieve the records

MyQuery.Query

See Also AppendSort method

SetObjectType method

AppendFilter 357
ClearBasic Object Reference
 PowerQuery object

method AppendSort

Syntax YourPowerQuery.AppendSort Index, Path

Applies To PowerQuery

Description The AppendSort method adds a single sort condition to the specified query set. You
can call this method any number of times to add additional sort conditions to a query
set. During a query, sort conditions are applied in the order they were added to the
query set.

This method assigns the current sort order to the sort condition. The sort order is set
to "descending" by default. To change the sort order you must call the
SetSortOrder method prior to calling this method.

When specifying a value for the Path parameter, you do not need to include the name
of the driving object type in the path. To specify fields of the driving object type,
specify only the name of the field. To specify a field in another object, use relations to
build a complete path to the desired field.

You must set the driving object type of the query set before calling this method.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify the index of the query set to receive the sort condition
information.
Path String Specify the path to the field whose contents you want to use for
the sort condition.
For fields belonging to the query set’s driving object type, you
need only specify the field name. For fields associated with other
tables, you must use relations to build the path to the field.

Return Values None

Example The following example creates a new query set and adds a filter and a sort condition
to it. The sort condition sorts rows based on the city field of the address table. The
sort order is set to ascending.
Dim MyQuery as New PowerQuery

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", "CA", _
"is equal to"
MyQuery.SetSortOrder 0, "ascending"
MyQuery.AppendSort 0, "city"

' Retrieve the records

MyQuery.Query

358 AppendSort
ClearBasic Object Reference
 PowerQuery object

See Also SetSortOrder method

AppendSort 359
ClearBasic Object Reference
 PowerQuery object

method GetCount

Syntax Count = YourPowerQuery.GetCount (Index)

Applies To PowerQuery

Description The GetCount method returns the total number of database rows in the result set for
the specified query set. Call this method after performing the query to determine how
many rows were returned for the query set.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify the index of the desired query set.

Return Values Returns an integer value indicating the number of rows in the result set of the
specified query set.

See Also Query method

RetrieveRecords method

360 GetCount
ClearBasic Object Reference
 PowerQuery object

method Query

Syntax YourPowerQuery.Query

Applies To PowerQuery

Description The Query method executes the queries of every query set in the PowerQuery object.
Only the object IDs of the affected rows are retrieved initially. The rest of the row
information is retrieved when you call the RetrieveRecords method.

Parameters None

Return Values None

Example The following example queries the database for all addresses in the state of California.
Dim MyQuery as New PowerQuery
Dim idList as New List

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", "CA", _
"is equal to"

' Retrieve the records

MyQuery.Query

' Get the query results

set idList = MyQuery.RetrieveIDS 0

See Also RetrieveIDS method

RetrieveRecords method
SetObjectType method

Query 361
ClearBasic Object Reference
 PowerQuery object

method RetrieveIDS

Syntax Set IDList = YourPowerQuery.RetrieveIDS (Index)

Applies To PowerQuery

Description The RetrieveIDS method returns the complete list of object IDs currently in the
specified result set. Prior to calling this method, you must call the Query method to
execute the PowerQuery object’s queries and fill the corresponding result sets with
data. This method retrieves no additional data from the database.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify the index of the query set containing the desired object
IDs.

Return Values Returns a List object containing one or more Long integers. Each long integer in the
list is an object ID returned by the most recent query.

Example The following example queries the database for all addresses in the state of California.
Dim MyQuery as New PowerQuery
Dim idList as New List

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", "CA", _
"is equal to"
MyQuery.Query

set idList = MyQuery.RetrieveIDS (0)

See Also Query method

RetrieveRecords method

362 RetrieveIDS
ClearBasic Object Reference
 PowerQuery object

method RetrieveRecords

Syntax Set RecordList = YourPowerQuery.RetrieveRecords (Index,

ViewType, Start, End)

Applies To PowerQuery

Description The RetrieveRecords method returns the specified rows from the result set. When
you execute this method, the PowerQuery object retrieves the remaining row
information from the database. If you specify the name of a view in the ViewType
parameter, this method performs any necessary joins to bring in the associated
information.
You can use the Start and End parameters to retrieve a subset of records for
immediate use. To get the total number of records in the result set, use the GetCount
method.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify the index of the desired query set.
ViewType String Specify the name of the object type you want this method to
return. You can specify the driving object type of the query set or
you can specify a view that incorporates the driving object type.
Start Long Specify the index of the first row you want to retrieve from the
result set. This index is zero-based, that is, the first row is at index
0, the second at index 1, and so on.
End Long Specify the index of the last row you want to retrieve from the
result set. This index is zero-based, that is, the first row is at index
0, the second at index 1, and so on.
This parameter is optional. To retrieve all records from the Start
parameter to the end of the result set, specify the value -1 or
specify no value at all.

Return Values Returns a List object containing the rows from the result set. If the query has not
been performed or it returned no rows, the List object is empty.

Example The following example queries the database for addresses in the state of California. To
limit the size of the query, the example retrieves only the first 100 rows. By setting the
ViewType parameter of RetrieveRecords to "site_view", this method retrieves
the site information associated with each address.
Dim MyQuery as New PowerQuery
Dim rowList as New List
Dim endRow as Long

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", "CA", _

RetrieveRecords 363
ClearBasic Object Reference
 PowerQuery object

"is equal to"

' Retrieve the records

MyQuery.Query

' Get only the first 100 rows from

' the result set
endrow = MyQuery.GetCount (0)
If endRow >= 100 Then
endRow = 99
End If

' Get the site info associated with each

' address in the result set.
set rowList = MyQuery.RetrieveRecords (0. _
"site_view", 0, endRow)

See Also Query method

RetrieveIDS method

364 RetrieveRecords
ClearBasic Object Reference
 PowerQuery object

method SetObjectType

Syntax YourPowerQuery.SetObjectType Index, DBObjName

Applies To PowerQuery

Description The SetObjectType method initializes a query set and sets its driving object type.
You may call this method multiple times to add new query sets to the PowerQuery
object. You may use the same driving object type for multiple query sets in the same
PowerQuery object.

You must create a query set before adding any filters or sort criteria. The driving
object type you specify determines which database table to use during queries. In
addition, any filters and sort conditions you add to the query set rely on the driving
object type to validate the filter and sort information.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify an index for the new query set. You must use this index in
successive method calls to identify the query set.
Within a given PowerQuery object, the index of each query set
must be unique. However, indexes do not need to be sequential.
DBObjName String Specify the driving object type of the query set. This string must
correspond to the name of a database table. Do not specify the
name of a view.

Return Values None

Example The following example adds one query set to the PowerQuery object. The driving
object for the query set is the address table.
Dim MyQuery as New PowerQuery

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", "CA", _
"is equal to"

' Retrieve the records

MyQuery.Query

See Also AppendFilter method

AppendSort method

SetObjectType 365
ClearBasic Object Reference
 PowerQuery object

method SetSortOrder

Syntax YourPowerQuery.SetSortOrder Index, Order

Applies To PowerQuery

Description The SetSortOrder method sets the sort order of existing query sets. Call this
method after adding one or more sort criteria to the query set. This sort order applies
to all sort conditions in the query set.

Sort conditions for a query set are set to "ascending" by default. You can intersperse
calls to this method with calls to AppendSort to change the sort order for individual
sort conditions.

NOTE: If you specify any string other than "ascending" or "descending" for the Order
parameter, this method applies an ascending sort order automatically.

Parameters This method requires the following parameters:

Parameter Type Description

Index Long Specify the index of the query set. The query set must already
exist.
Order String Specify one of the following values:

String Sort order

"ascending" Alphabetical from A to Z.
"descending" Reverse alphabetical from Z to A

Return Values None

Example The following example creates a new query set and adds a filter and a sort condition
to it. The sort condition sorts rows based on the city field of the address table. The
sort order is set to ascending.
Dim MyQuery as New PowerQuery

MyQuery.SetObjectType 0, "address"
MyQuery.AppendFilter 0, "state", "CA", _
"is equal to"
MyQuery.SetSortOrder 0, "ascending"
MyQuery.AppendSort 0, "city"

' Retrieve the records

MyQuery.Query

366 SetSortOrder
ClearBasic Object Reference
 PowerQuery object

A query that returned three records whose city fields contained the values "Stockton",
"Modesto", and "San Jose" would result in those records being sorted into the
following order:

Result Set Ascending order

Item 0 "Modesto"
Item 1 "San Jose"
Item 2 "Stockton"

See Also AppendSort method

SetSortOrder 367
ClearBasic Object Reference
 PowerQuery object

368 SetSortOrder
ClearBasic Object Reference
 Printer object

Description The Printer object is automatically created at application startup and is used to
print text and graphics on a page and send a print job to the printer. Any property
settings for this object continue in effect until the application terminates, unless
explicitly changed.

Methods This object defines the following methods:

■ EndDoc method
■ Line method
■ NewPage method
■ Print method
■ TextHeight method
■ TextWidth method

Properties This object defines the following properties:

■ Continuation property
■ CurrentX property
■ CurrentY property
■ DrawMode property
■ DrawStyle property
■ DrawWidth property
■ FontBold property
■ FontFamily property
■ FontItalic property
■ FontSize property
■ Height property
■ Page property
■ RightMargin property
■ Truncate property
■ Width property
■ Wrap property

ClearBasic Object Reference 369

 Printer object

method EndDoc

Syntax Printer.EndDoc

Applies To Printer

Description The EndDoc method sends your print job to the printer. This method finishes the
current print job, spools it to the printer, and resets for a new print job.

Parameters None

Return Values None

Example In the following subroutine, a short line of text is printed. Notice that a blank line is
printed just before and just after the line of text. The entire print job is sent to the
printer when EndDoc is invoked.
Sub PrintTest
Printer.Print
Printer.Print "This is only a test."
Printer.Print
Printer.EndDoc
End Sub

See Also NewPage method

Print method

370 EndDoc
ClearBasic Object Reference
 Printer object

method Line

Syntax Printer.Line x1, y1, x2, y2, flags

Applies To Printer

Description The Line method draws a line from the absolute position in an object specified by x1
and y1 coordinates to the absolute position specified in the same object specified by
the coordinates x2 and y2.

The thickness of the line is controlled by DrawWidth

Parameters The Line method accepts the following parameters:

Parameter Type Description

x1, y1 Float Coordinates for the starting position of the line to be drawn.
x2, y2 Float Coordinates for the ending position of the line to be drawn.
flags Long Specify options for how this method should interpret other
parameters. You can specify any combination of the following values:
Value Description
2 Interpret x2, y2 as a delta from x1, y1
8 Use the 2 points as corners to draw a box

Example The following example prints some strings and a line. First, the example prints the
string "Hello World" at the top of a page. It follows by printing a vertical line down
the page starting at the end of the "Hello World" string. It then prints a second string
at the end of the line.
Sub btn_Print_Click()
Dim YPos as Integer

Printer.CurrentY = 0.0
Printer.Print "Hello, World"
Printer.Print
YPos = Printer.CurrentY
Printer.Line 0, YPos, 5000, YPos, 0, 0
Printer.Print
Printer.Print "Hello, again"

End Sub

See Also DrawMode property

DrawStyle property
DrawWidth property

Line 371
ClearBasic Object Reference
 Printer object

method NewPage

Syntax Printer.NewPage

Applies To Printer

Description The NewPage method forces an advance to a new page. The print job will start or
resume in the upper left corner of the page.

Parameters None

Return Values None

372 NewPage
ClearBasic Object Reference
 Printer object

method Print

Syntax Printer.Print ItemToPrint

UDTs Supported This method supports user defined types.

Applies To Printer

Description The Print method prints the specified item at the current location on the page, as
specified by the current Printer property settings. If no item is specified, a blank
line is printed. This method prints to the current default printer.

This method prints the specified string according to the Printer properties that have
been set.

Parameters This method accepts the following parameters.

Parameter Type Description

ItemToPrint variable Specify a string or a variable containing strings

Return Values None

Example The example shows how you might set some printer properties before you invoke the
Print method on the Printer object.
Sub PrintTest
Printer.Print "This is a simple string"
Printer.Print
Printer.Print "This is a string preceeded _
by an empty 'Print'"

Printer.FontFamily = 0
Printer.Print "This is a simple string"
Printer.FontFamily = 1
Printer.Print "This is a simple string"

Printer.FontFamily = 2
Printer.FontBold = 1
Printer.Print "This is a simple string"
Printer.EndDoc
End Sub

Print 373
ClearBasic Object Reference
 Printer object

method TextHeight

Syntax RetFloat = Printer.TextHeight (StringToCheck)

Applies To Printer

Description The TextHeight method returns a float value representing the physical height of the
specified text string on the printed page if printed with the current font.

Parameters This method accepts the following parameter:

Parameter Type Description

StringToCheck String You must provide a string or a string variable to be evaluated for
text height.

Return Values Returns the height of the text string as a floating-point value, measured in pixels.

Example The following example prints out the height of the supplied string:
Sub WhatsMyTextHeight
Dim TestStr As string

TestStr = "This is only a test."

Debug.Print "The height of a string _
in the current font is", _
Printer.TextHeight(TestStr), " pixels"
End Sub

See Also TextWidth method

FontSize property
FontBold property
FontFamily property
FontItalic property

374 TextHeight
ClearBasic Object Reference
 Printer object

method TextWidth

Syntax RetFloat = Printer.TextWidth (StringToCheck)

Applies To Printer

Description The TextWidth method returns a float value representing the physical width in
pixels of the specified text string on the printed page if printed with the current font.

Parameters This method accepts the following parameter:

Parameter Type Description

StringToCheck String You must provide a string or a string variable to be evaluated for
text width.

Return Values Returns the width of the text string as a floating-point value, measured in pixels.

Example The following example prints out the width of the supplied string:
Sub WhatsMyTextWidth
Dim TestStr As string

TestStr = "This is only a test."

Debug.Print "The width of a string _

in the current font is", _
Printer.TextWidth(TestStr), "pixels"
End Sub

See Also TextHeight property

FontSize property
FontBold property
FontFamily property
FontItalic property

TextWidth 375
ClearBasic Object Reference
 Printer object

property Continuation

Syntax Printer.Continuation = "String"

ContinueSetting = Printer.Continuation

Applies To Printer

Description If you have turned truncation on (see the Truncate property), you can set this
property to specify which characters are used to indicate that a truncation of the
printed text has occurred. (Truncation can occur if the text exceeds the limits specified
by the RightMargin property.) If you do not set this property but do turn on
truncation, the default characters are three period characters (...).

You can also read this property to determine which characters were last used.

Parameters This method takes the following parameter:

Parameter Type Description

String String Specify up to three characters. These characters are printed at the
right margin when printed text is truncated to indicate that a
truncation has occurred.
Although you can specify any characters you want, the conventional
way to indicate a continuation is to use three period characters (...).

Return Values When this property is read, it returns the characters last used.

Example The following subroutine prints a long string that wanders off the right margin of the
page. The print job gets chopped-off at that point, with three continuation characters
(---) printed at the margin to indicate that the print job wasn’t entirely successful.

Notice that Truncate is turned on and the RightMargin is set. If you don’t turn
Truncate on, no continuation characters are printed at the point where the print job is
stopped. If you don’t set the RightMargin, continuation characters are not printed
where the print job goes off the page. Notice also that Wrap is not turned off because
by default Wrap is off.
Sub TruncatePrint_Click
Dim long_string As String

long_string = "While moving the cursor _

across the_ toolbar, the Clarify _
desktop becomes enabled then disabled, _
as evidenced by the desktop perimeter_
changing from white to ""lined"", etc. _
This can be_ a limitless source of _
entertainment when things are slow at the _
office."

376 Continuation
ClearBasic Object Reference
 Printer object

Printer.Truncate = True
Printer.RightMargin = 400.0
Printer.Continuation = "---"
Printer.Print long_string
End Sub

See Also RightMargin property

Truncate property
Wrap property

Continuation 377
ClearBasic Object Reference
 Printer object

property CurrentX

Syntax Printer.CurrentX = Setting

Setting = Printer.CurrentX

Applies To Printer

Description The CurrentX property contains a floating-point number corresponding to a

horizontal coordinate on the page. Together with the CurrentY property, this
property specifies the location at which future printing commands will occur. You can
modify this property to change the location of the next printing command.

See Also CurrentY property

378 CurrentX
ClearBasic Object Reference
 Printer object

property CurrentY

Syntax Printer.CurrentY = Setting

Setting = Printer.CurrentY

Applies To Printer

Description The CurrentY property contains a floating-point number corresponding to a vertical

coordinate on the page. Together with the CurrentX property, this property specifies
the location at which future printing commands will occur. You can modify this
property to change the location of the next printing command.

See Also CurrentX property

CurrentY 379
ClearBasic Object Reference
 Printer object

property DrawMode

Syntax Printer.DrawMode = Setting

Setting = Printer.DrawMode

Applies To Printer

Description Use this property to change the appearance of printed graphics or text. Valid settings
are listed below. (Invalid settings are ignored.)

Settings This property accepts the following setting:

Setting Description
1 Black pen.
2 Don’t combine pen color and display color. (This is the inverse of setting 15.)
4 Don’t use the color set in the ForeColor property. (This is the inverse of setting
13.)
6 Use the inverse of the display color.
7 XOrPen
8 Don’t combine common pen and display colors.
9 Combine common pen and display colors.
10 Inverse of XOrPen
13 Use the color set in the ForeColor property
15 Combine pen color and display color.
16 White pen.

Return Values When read, this property returns the last (integer) value set.

See Also DrawStyle property

DrawWidth property

380 DrawMode
ClearBasic Object Reference
 Printer object

property DrawStyle

Syntax Printer.DrawStyle = Setting

Setting = Printer.DrawStyle

Applies To Printer

Description The DrawStyle property sets the drawing style used for drawing lines. If this
property is not set, the default is to draw solid lines.

Settings This property accepts the following setting:

Setting Description
0 Solid line (default)
1 Dashed line
2 Dotted line.

Return Values When read, this property returns the last (integer) value set.

See Also DrawMode property

DrawWidth property

DrawStyle 381
ClearBasic Object Reference
 Printer object

property DrawWidth

Syntax Printer.DrawWidth = Value

Value = Printer.DrawWidth

Applies To Printer

Description The DrawWidth property sets the pen width (in pixels) used in drawing lines.

Settings This property accepts the following setting:

Setting Description
Value You can specify any positive integer. By default, the value 1 is used.

Return Values When read, this property returns the last (integer) value set.

See Also DrawMode property

DrawStyle property

382 DrawWidth
ClearBasic Object Reference
 Printer object

property FontBold

Syntax Printer.FontBold = Setting

Setting = Printer.FontBold

Applies To Printer

Description The FontBold property sets the bold style for printing text.

Settings This property accepts the following setting:

Setting Description
True Turn bold on.
False Turn bold off.

Return Values When read, this property returns the last value set.

Example In the following subroutine, several printer properties are set prior to invoking
Print: bold and italic are turned on, the font Helvetica is specified, and a font size of
10 points is specified. A simple text string is then printed with those attributes.

After the font size is reset, another text string is printed. Notice that this second line of
text is printed with the currently set values of bold, italic, and Helvetica, because only
FontSize is changed. EndDoc is invoked to send the print job to the printer.

Print is invoked three times without parameters to print a blank line. The first blank
line is whatever size is currently in effect (the current FontSize setting). The second
blank line is 10 points, and the third blank line is 20 points.
Sub PrintTest
Printer.Print
Printer.FontFamily = 3
Printer.FontBold = True
Printer.FontItalic = True

Printer.FontSize = 10
Printer.Print "This is a simple string"
Printer.Print
Printer.Print Printer.FontSize = 20

Printer.Print "This is a bigger size _

simple string"
Printer.Print
Printer.EndDoc
End Sub

FontBold 383
ClearBasic Object Reference
 Printer object

See Also EndDoc method

Print method
FontFamily property
FontItalic property
FontSize property

384 FontBold
ClearBasic Object Reference
 Printer object

property FontFamily

Syntax Printer.FontFamily = Setting

Setting = Printer.FontFamily

Applies To Printer

Description The FontFamily property sets the font to be used for printing text, according to the
values listed below. (Values not listed are ignored.) If you don’t set this property, by
default the system font is used.

Settings This property accepts the following setting:

Setting Description
0 Use system font.
1 Use a monospace font (fixed-width)
2 Use Times font.
3 Use Helvetica font.

Return Values When read, this property returns the last value set.

Example See the example for FontBold.

See Also EndDoc method

Print method
FontBold property
FontItalic property
FontSize property

FontFamily 385
ClearBasic Object Reference
 Printer object

property FontItalic

Syntax Printer.FontItalic = Setting

Setting = Printer.FontItalic

Applies To Printer

Description The FontItalic property sets the italic style for printing text.

Settings This property accepts the following setting:

Setting Description
True Turn italic on.
False Turn italic off.

Return Values When read, this property returns the last value set.

Example See the example for FontBold.

See Also EndDoc method

Print method
FontBold property
FontFamily property
FontSize property

386 FontItalic
ClearBasic Object Reference
 Printer object

property FontSize

Syntax Printer.FontSize = Size

Size = Printer.FontSize

Applies To Printer

Description The FontSize property sets the size of the font for printing text.

Settings This property accepts the following setting:

Setting Description
Size Specify a positive integer to set the font size. The default value is 8.

Return Values When read, this property returns the last value set.

Example See the example for FontBold.

See Also EndDoc method

Print method
FontBold property
FontFamily property
FontItalic property

FontSize 387
ClearBasic Object Reference
 Printer object

property Height

Syntax Setting = Printer.Height

Applies To Printer

Description The Height property contains an integer value indicating the current height of the
printed page, measured in pixels.

This property is read-only.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

Example The following line illustrates the use of this property.

Print "The current page height is ", _
Printer.Height," pixels"

See Also Width property

388 Height
ClearBasic Object Reference
 Printer object

property Page

Syntax PageNumber = Printer.Page

Applies To Printer

Description The Page property is a read-only property that returns the current page number.

Page 389
ClearBasic Object Reference
 Printer object

property RightMargin

Syntax Printer.RightMargin = DistanceFromEdge

DistanceFromEdge = Printer.RightMargin

Applies To Printer

Description You use this property to set the right margin by specifying the distance (in pixels)
from the right edge of the page where the margin is to be placed. Printed text is
truncated or wrapped upon reaching this margin, depending on the setting of the
Wrap and Truncate properties.

Settings This property accepts the following setting:

Setting Description
DistanceFromEdge Specify the distance, in pixels, from the right edge of the page. The
right margin will be placed at this location.

Return Values When read, this property returns the last value set.

Example The following subroutine prints a long string that wanders off the right margin of the
page. The print job gets chopped-off at that point, with three continuation characters (--
-) printed at the margin to indicate that the print job wasn’t entirely successful.

Notice that Truncate is turned on and the RightMargin is set. If you don’t turn
Truncate on, no continuation characters are printed at the point where the print job is
stopped. If you don’t set the RightMargin, continuation characters are not printed
where the print job goes off the page. Notice that by default Wrap is off.
Sub TruncatePrint
Dim long_string As String

long_string = "While moving the cursor _

across the toolbar, the Clarify desktop _
becomes enabled then disabled, As _
evidenced by the desktop perimeter _
changing from white to ""lined"", etc. _
This can be a cheap source of _
entertainment while you are waiting for _
your code to compile."

Printer.Truncate = True
Printer.RightMargin = 400.0
Printer.Continuation = "---"
Printer.Print long_string
End Sub

390 RightMargin
ClearBasic Object Reference
 Printer object

See Also Truncate property

Wrap property

RightMargin 391
ClearBasic Object Reference
 Printer object

property Truncate

Syntax Printer.Truncate = Setting

Setting = Printer.Truncate

Applies To Printer

Description The Truncate property specifies whether the printed text is truncated when it
reaches the right margin.

Using the Wrap property, you can wrap (see Wrap) the printed text to the next line
when the margin is reached; however, if don’t want to do this, you might want to set
Truncate to True because doing so will result in the printing of continuation characters
to alert you that the print job has exceeded the margins.

Settings This property accepts the following setting:

Setting Description
True Truncate
False Don’t Truncate

Return Values When read, this property returns the last value set.

Example The following subroutine prints a long string that wanders off the right margin of the
page. The print job gets chopped-off at that point, with three continuation characters
(---) printed at the margin to indicate that the print job wasn’t entirely successful.

Notice that Truncate is turned on and the RightMargin is set. If you don’t turn
Truncate on, no continuation characters are printed at the point where the print job is
stopped. If you don’t set the RightMargin, continuation characters are not printed
where the print job goes off the page. Notice also that Wrap is not turned off because
by default Wrap is off.
Sub TruncatePrint
Dim long_string As String

long_string = "While moving the cursor _

across the toolbar, the Clarify desktop _
becomes enabled then disabled, as _
evidenced by the desktop perimeter _
changing from white to ""lined"", etc. _
This can be only slightly less _
entertaining than a game of darts at the _
local establishment."

Printer.Truncate = True

392 Truncate
ClearBasic Object Reference
 Printer object

Printer.RightMargin = 400.0
Printer.Continuation = "---"
Printer.Print long_string
End Sub

See Also Continuation property

RightMargin property
Wrap property

Truncate 393
ClearBasic Object Reference
 Printer object

property Width

Syntax Width = Printer.Width

Applies To Printer

Description The Width property contains an integer value indicating the current width of the
printed page, measured in pixels.

This property is read-only.

IMPORTANT: At design time in the User Interface Editor, the size of the form and controls are
created with machine-independent coordinates. At runtime, these coordinates are replaced
with machine-dependent coordinates, which can result in slight variations in size properties
for forms and controls.

Example The following subroutine prints out the current page width.
Sub PrintMyWidth
Print "The width of the printer page is ", _
Printer.Width, " pixels"
End Sub

See Also Height property

394 Width
ClearBasic Object Reference
 Printer object

property Wrap

Syntax Printer.Wrap = Setting

Setting = Printer.Wrap

Applies To Printer

Description You can set this property to specify whether the printed text wraps to the next line
when the right margin is reached. If you don’t set this property, by default Wrap is
turned off.

Settings This property accepts the following setting:

Setting Description
True Wrap the text to the next line when margin is reached.
False Don’t wrap. This is the default setting. The text will either be truncated, if the
Truncate property is set, or it will "continue" off the page.

Return Values When read, this property returns the last value set.

See Also Continuation property

RightMargin property
Truncate property

Wrap 395
ClearBasic Object Reference
 Printer object

396 Wrap
ClearBasic Object Reference
 Record object

Description A Record object is used to contain either a record retrieved from the database or a
new record created locally at the client workstation. Records that are retrieved from
the database are called permanent records; new records created locally are called
temporary records. When a permanent record is saved back (using BulkSave) to the
database, it overwrites the previous version of the record in the database. When a
temporary record is saved to the database, no database record is overwritten, but a
new record is added to the database.

To retrieve a record from the database you use the various query methods available
for the BulkRetrieve object. To create a new record locally at the client you create a
variable, set its record type (RecordType), and fill the fields in with the values you
want (SetField).

Comments You declare and set the type of a Record object variable as follows:
Dim YourRecord As New Record
YourRecord.RecordType = "DatabaseObjectName"

Methods This object defines the following methods:

■ ChangeToNew method
■ Copy method
■ CopyFields method
■ CreateView method
■ Format method
■ GetField method
■ GetObject method
■ GetTextField method
■ IsDirty method
■ IsExactly method
■ IsMaxDate method
■ IsMinDate method
■ IsNew method
■ Print method
■ SetField method

Properties This object defines the following property:

■ RecordType property

ClearBasic Object Reference 397

 Record object

method ChangeToNew

Syntax YourRecord.ChangeToNew

Applies To Record

Description Use this method on a record retrieved from the database that you want to insert back
into the database as a new record. (See InsertRecord.) You must invoke this
method on the record prior to placing the record into the BulkSave object. (See the
Copy method for an alternate way to change a record to a new record.)

This method changes a permanent record retrieved from the database to be a

temporary (new) record. Accordingly, when you save this changed record back to the
database, it does not overwrite the original database record but is added as an entirely
new record.

Parameters None

Return Values None

See Also Copy method

BulkSave object
ChangeRecord method (BulkSave object)

398 ChangeToNew
ClearBasic Object Reference
 Record object

method Copy

Syntax Set CopyOfYourRecord = YourRecord.Copy (Options)

Applies To Record

Destination The Copy method returns a copy of the current record. A copy of a record is useful for
those situations where you want to keep two (or more) instances of the same record
separate. For example, you might want to display a record in a read-only custom list
and also in an text box in the same form. In this case, you might not want to have
modifications to the record in the text box apply to the original record displayed in the
custom list.

Parameters This method accepts the following parameter:

Parameter Type Description

Options Long This parameter is optional.
If you want the copy to be exactly the same as the original,
including the same object ID, do not use this option. (This is the
default.)
If you want the copy to be exactly the same as the original EXCEPT
for the object ID, in order to make it a new record, specify the
parameter cbChangeToNew.

Comments If you used the same object ID for the original and the copy, which is the default
behavior of the Copy method, then you should be aware of the potential problems.
For example, saving the copy to the database can overwrite an existing record in the
database.

Return Values This method returns a copy of a record.

If you did not specify the optional parameter cbChangeToNew, the copy returned has
the same object ID as the original record.
If you did specify the optional parameter cbChangeToNew, the copy returned has a
new object ID.

Example In the following example, a permanent database record (SourceRec) is copied into
NewRec using the option cbChangeToNew. Using this option flags NewRec as a new
record. (You could also use the ChangeToNew method on NewRec, but the
cbChangeToNew option saves a step.)
Set NewRec = SourceRec.Copy (cbChangeToNew)

See Also ChangeToNew method

Copy 399
ClearBasic Object Reference
 Record object

method CopyFields

Syntax DestRec.CopyFields SourceRecord, SourceFieldList,

DestinationFieldList

Applies To Record

Description The CopyFields method allows you to copy as many fields as you want from one
record (SourceRecord) to corresponding fields in another record (DestRec). The records
can be of different types but the corresponding source and destination fields must be
of the same primitive type. The first element of SourceFieldList copies into the first
element of DestinationFieldList, the second element copies into the second element,
and so on.
A common use for CopyFields would be to create a record which mirrored an
existing database object. (That is, the destination field list would be a list of the fields
of a record that was not yet in the database but is about to be created with this
method.)

Both the destination record and the source record must be of valid database types.

Parameters This method accepts the following parameters:

Parameter Type Description

SourceRecord Record Specify the record from which you are copying fields.
SourceFieldList List Specify the list of fields to be copied.
DestinationFieldList List Specify the list of fields in the destination record that
receive the copies.

Return Values None

Example In the following example, some case records are retrieved from the database and put
into a list (CaseList). The first record in the list (CaseRec) is used as the source record
in a CopyFields operation. The values in the title and id_number fields in CaseRec
are then copied into the label and number fields of MyCaseRec, respectively.
Dim FieldList As New List
Dim MyList As New List
Dim CaseList As List
Dim CaseRec As Record
Dim MyCaseRec As New Record
Dim BulkGet As New BulkRetrieve

BulkGet.SimpleQuery 0, "case"
BulkGet.AppendFilter 0, "id_number", cbLess, 145
BulkGet.RetrieveRecords

set CaseList = BulkGet.GetRecordList(0)

400 CopyFields
ClearBasic Object Reference
 Record object

set CaseRec = CaseList.ItemByIndex(0)

FieldList.AppendItem "title", "id_number"

MyList.AppendItem "title", "id_number"

MyCaseRec.RecordType = "case"

MyCaseRec.CopyFields CaseRec, FieldList, MyList

CopyFields 401
ClearBasic Object Reference
 Record object

method CreateView

Syntax YourRecord.CreateView ViewType, MyRec

Applies To Record

Description The CreateView method uses the fields in a record to build a new view object. Call
this method from a new view object, specifying both the type of the view and a record
from which to extract the view data. This method initializes this view (if it has not yet
been initialized) and copies the data from the record to the view.

You can call this method more than once to copy the fields from multiple records to
this view. This method copies only the relevant fields from the record object without
disturbing the other fields in the view. This method copies only those fields that are
common to both the view definition and the record definition. Any fields not used by
the view definition are ignored.

Parameters This method uses the following parameters:

Parameter Type Description

ViewType String Specify the view type you want to create using this view.
MyRec Record Specify an empty Record object. On return, this object is set to the
type specified in ViewType and contains the relevant information
from this record.

Return Values None

Example The following example builds a view object from existing form data and appends the
view to the form’s grid control. The form stores several currently selected elements in
contextual objects. The example uses these selections to build the view object before
adding it to the grid control.
Sub btnAddView_Click
Dim ReqSumRec as New Record

' Build the view.

ReqSumRec.CreateView "req_sum", _
CObj_demand_dtl.Contents
ReqSumRec.CreateView "req_sum", _
CObj_demand_hdr.Contents
ReqSumRec.CreateView "req_sum", _
CObj_part_num.Contents
ReqSumRec.CreateView "req_sum", _
CObj_mod_level.Contents
ReqSumRec.CreateView "req_sum", _
CObj_condition.Contents

402 CreateView
ClearBasic Object Reference
 Record object

' Append the new view to the grid

clbRequests.AppendItem ReqSumRec
End Sub

See Also GetObject method

CreateView 403
ClearBasic Object Reference
 Record object

method Format

Syntax RetString = YourRecord.Format ("%Format1,%Format2, %Format3",

Item1,Item2, Item3)

Applies To Record

Description The Format method is useful if you want a particular format for record field values
that you want to store in the database, or present to users in messages, or display in
the controls in a form. This method formats the specified fields in the record according
to the format specifiers used, and returns an output string with the field values in the
proper format.

CAUTION: These parameters are case sensitive and will generate an error if supplied
incorrectly.

You can specify up to three field name strings ("Item1", "Item2", "Item3"). Or, instead
of using field names, you can specify up to three lists that contain field name strings
(Item1, Item2, Item3). The number of formats specified
("%Format1,%Format2,%Format3") must match the number of field names or lists
specified. That is, if you specify Item1 as the item to format, you must
specify%Format1; likewise if you specify Item1 and Item2, you must specify%Format1
and%Format2.

%Format1 applies to the item or list of items in Item1;%Format2 applies to the item or
list of items in Item2, and%Format3 applies to the item or list of items in Item3.

All of the fields in a record are of one of three basic data types: integer, string, floating
point. Therefore, because you can specify up to three lists of field names, you can
apply formats to all of the fields in the record.

Formats and format modifiers. The format and format modification scheme used by
this method is very similar to the ones used by the standard C printf() and scanf()
functions. If you aren’t familiar with these functions, a description is provided below.

Valid formats. The following table lists the valid formats that can be used with this
method:

Format Description
%c Single character
%d Signed decimal integer
%e Floating point, e-notation
%E Floating point, E-notation
%f Floating point, decimal notation
%g Use the shorter of %f or %e
%G Use the shorter of %f or %E
%i Signed decimal integer
%o Unsigned octal integer

404 Format
ClearBasic Object Reference
 Record object

Format Description
%p Pointer
%s Character string
%u Unsigned decimal integer
%x Unsigned hexadecimal integer, using
digits o through f
%X Unsigned hexadecimal integer, using
digits O through F

Format modifiers. The following table lists the format modifiers that can be used.
These modifiers must be inserted between the% and the format character.

Modifier Description
digits One or more digits indicating minimum field width, for example,%4s. If the value
can’t fit in the field, the width is automatically expanded.
.digits One or more digits indicating precision. For %e, %E, and %f, this specifies the
number of digits to print on the right side of the decimal. For example,%4.3f prints
a float value in a field 4 characters wide with a maximum of three digits printed
after the decimal point.
For %g and %G, it specifies the number of significant digits.
For %s, it specifies the maximum number of characters.
For integer formats, it specifies the minimum number of digits to print, using
leading zeros to pad if necessary.
h Specifies a short integer or short unsigned integer value. For example, %hu or
%4.2hd
l Specifies a long integer or unsigned long integer. For example,%ld or %8ld.
L Specifies a long double value, for example,%Lf or %6.4Le
- Prints the value left justified with the left of the field, for example,
%-10s.
+ Prints a plus or minus in front of positive or negative signed values, for
example,%+7.3f.
space Prints a leading space in front of positive signed values and a minus in front of
character negative signed values, for example, % 7.3f. (A space character modifier overrides
a + modifier.)
# Prints an initial 0 for octals and an initial 0x for hexadecimals. For floats, it forces a
decimal point to be printed. For %g and %G, it prevents removal of trailing zeros.
0 This pads fields with leading zeros (for numeric values only) rather than spaces.
This modifier is overridden by the - modifier. For integer values, this modifier is
overridden by the use of the.digits modifier that specifies precision.

Format 405
ClearBasic Object Reference
 Record object

Parameters This method accepts the following parameters:

Parameter Type Description

%Format1 String You must specify a format for the field name or list of field names in
Item1. Valid formats are listed under the Comments for this method.
You must specify this format if you specify Item2.
%Format2 You must specify this format if you specify Item2.
%Format3
Item1 String You must specify a valid field name or list of field names that are in
List the current record object (YourRecord).
Item2 You may specify a second field name or list of field names.
Item3 You may specify a third field name or list of field names.

Return Values This method returns an output string consisting of the formatted values in the
specified fields.

Example The following code fragment shows one use of this method. Two items are added to
the list: these are field names in YourRecord. The value in the objid record field is
formatted as a signed integer (long); the value in the id_number field is formatted as
a character string.
Dim RList As List

RList.AppendItem "objid"
RList.AppendItem "id_number"
Set FormattedList = _
str$(YourRecord.Format("%ld, %s", RList))

406 Format
ClearBasic Object Reference
 Record object

method GetField

Syntax YourFieldVariable = YourRecord.GetField (FieldName)

Applies To Record

Description The GetField method returns the value of the specified field in the current record.

CAUTION: This parameter is case sensitive and will generate an error if supplied incorrectly.

Parameters This method accepts the following parameter:

Parameter Type Description

FieldName String Specify the name of the record field from which you want to
retrieve the current value.

Return Values The return type can be an Integer, a String, or a Float, depending on the type of field
specified.

Example In the following code fragment, the value in the record field field_name (in record
elmObj) is returned to fldName:
fldName = elmObj.GetField ("field_name")

In the second fragment, GetField is used in an expression which provides a value for
the AppendFilter method.
BulkRet.AppendFilter 0, "description", _
cbLike, fltObj.GetField("description") + "%"

See Also SetField method

GetField 407
ClearBasic Object Reference
 Record object

method GetObject

Syntax YourRecord.GetObject RecordType, MyRec

Applies To Record

Description The GetObject method extracts record information from this view object. You must
specify which record you want to extract and provide a new Record object to receive
the extracted data. This method copies the relevant fields from this object to the
MyRec parameter.

The Record object you use to call this method must contain a valid view and the
specified RecordType must be a valid record in the view definition. This method
copies only those fields that are common to both the view definition and the record
definition. Any fields not used in the view definition are left empty in the returned
record.

IMPORTANT: If the view definition does not contain the objid field of the desired record, the
returned record is equivalent to a new record.

Parameters This method uses the following parameters:

Parameter Type Description

RecordType String Specify the record type you want to extract from this view. The
record type you specify must exist in the view.
MyRec Record Specify an empty Record object. On return, this object is set to the
type specified in RecordType and contains the information that
was extracted from the view.

Return Values None

Example The following example implements a button event handler. When fired, the event
handler gets the currently selected view from the form’s grid control. The grid control
displays views of type "scm_view", but the event handler extracts the "site_part"
record from the view and calls the MyDisplayPart subroutine to display the record
information.
Sub btnViewInfo_Click
Dim scmView as Record
Dim sitePartRec as New Record

' Extract a record from the selected view.

clb_Available_TLAs.GetSelected scmView
scmView.GetObject "site_part", sitePartRec

408 GetObject
ClearBasic Object Reference
 Record object

' Call a subroutine to display the record.

MyDisplayPart sitePartRec
End Sub

See Also CreateView method

GetObject 409
ClearBasic Object Reference
 Record object

method GetTextField

Syntax OutputText = YourRecord.GetTextField (FieldName, IsTruncated)

Applies To Record

Description The GetTextField method returns a string corresponding to the value in the
specified field. The field may contain a string or text data type. You may also use this
method to retrieve the values from a date/time field.

If the field contains a string with more than 32000 characters, this method truncates
the string and returns only the first 32000 characters. If truncation is necessary, this
method assigns the value 1 to the IsTruncated parameter.

Parameters This method uses the following parameters:

Parameter Type Description

FieldName String Specify the name of the field you want to retrieve.
IsTruncated Long Specify a long integer variable. On return, this variable contains
the value 1 if the returned string had to be truncated; otherwise,
this variable contains 0 to indicate no truncation took place. This
parameter is optional.

Return Values Returns a string containing the text in the field.

See Also GetField method

SetField method

410 GetTextField
ClearBasic Object Reference
 Record object

method IsDirty

Syntax RetBoolean = YourRecord.IsDirty

RetBoolean = YourRecord.IsDirty ("YourRecordField")

Applies To Record

Description The IsDirty method determines if the contents of any field of a record are dirty, that
is, have been modified. If the method detects a modified field, it returns the Boolean
value TRUE; otherwise, it returns the Boolean value FALSE.

If YourRecordField option is not specified, the method checks all fields in the record for
any modification. If YourRecordField option is specified, the method checks only that
field, ignoring modifications in other fields.

NOTE: The method returns the Boolean value FALSE if the record variable is not initialized,
that is the variable is declared but nothing has been copied into it.

Parameters This method accepts the following optional parameter:

Parameter Type Description

YourRecordField String Optional. It corresponds to the name of the field you want to
check for dirtiness. The field name must be an existing field in
the record.

Return Values The method returns the Boolean TRUE if it detects a dirty field in the record;
otherwise, it returns the Boolean FALSE.

Example The following example illustrates the use of the IsDirty method:
Sub Rec_IsChanged
Dim RecBuf1 As Record
Dim BulkR As New BulkRetrieve
Dim RecList As List

BulkR.simpleQuery 0, "window_db"
BulkR.retrieveRecords

Set RecList = BulkR.GetRecordList (0)

Set RecBuf1 = RecList.ItemByIndex (0)

‘Additional CB code goes here

...

If RecBuf1.IsDirty () = TRUE Then

App.MsgBox "The record has been modified."
Else

IsDirty 411
ClearBasic Object Reference
 Record object

App.MsgBox "The record has not been _

modified."
End If

...
End Sub

412 IsDirty
ClearBasic Object Reference
 Record object

method IsExactly

Syntax RetBoolean = Record_1.IsExactly (Record_2)

Applies To Record

Description The IsExactly method compares all the fields, including objid, in two records for
equality.

Parameters None

Return Values If the records are identical, the method returns the Boolean value TRUE; otherwise, it
returns the Boolean value FALSE.

Example The following code fragment illustrates the use of the IsExactly method:
Sub Rec_Compare
Dim RecBuf1 As New Record
Dim RecBuf2 As New Record
Dim Result as Boolean

RecBuf1.RecordType = "window_db"
RecBuf2.RecordType = "window_db"
RecBuf1.setField "title", "CCC"
RecBuf1.setField "id", 103
RecBuf1.setField "dialog_name", "CCCCCCCCCC"

RecBuf2.setField "title", "CCC"

RecBuf2.setField "id", 103
RecBuf2.setField "dialog_name", "CCCCCCCCCC"

...

Result = RecBuf1.IsExactly(RecBuf2)

If Result = TRUE Then

App.MsgBox "The records are identical."
Else
App.MsgBox "The records are not identical."
End If
End Sub

IsExactly 413
ClearBasic Object Reference
 Record object

method IsMaxDate

Syntax RetBool = YourRecord.IsMaxDate (FieldName)

Applies To Record

Description The IsMaxDate method determines whether the specified date field contains the
maximum allowable system date. You can use this method to assess the validity of the
specified field.

Parameters This method uses the following parameters:

Parameter Type Description

FieldName String Specify the name of the field you want to check. The field must
contain a date value.

Return Values Returns True if the specified field contains the maximum allowable system date,
otherwise False.

See Also IsMinDate method

414 IsMaxDate
ClearBasic Object Reference
 Record object

method IsMinDate

Syntax RetBool = YourRecord.IsMinDate (FieldName)

Applies To Record

Description The IsMinDate method determines whether the specified date field contains the
minimum allowable system date. You can use this method to assess the validity of the
specified field.

When you create new records, any date fields in the record are set to the minimum
date by default. You can use this method to determine if the specified field has been
initialized.

Parameters This method uses the following parameters:

Parameter Type Description

FieldName String Specify the name of the field you want to check. The field must
contain a date value.

Return Values Returns True if the specified field contains the minimum allowable system date,
otherwise False.

See Also IsMaxDate method

IsMinDate 415
ClearBasic Object Reference
 Record object

method IsNew

Syntax YourBoolean = Cobj_Yours.IsNew()

YourBoolean = YourRecord.IsNew()

Applies To Record

Description The IsNew method can be used on records or contextual objects that contain records.
It returns True if the record is not a permanent record (was not retrieved from the
database). It returns False if it is a new record created locally or if it is a permanent
record that has been changed to a new record via the ChangeToNew method.

If the value of the contextual object is a primitive type or a user defined type, an error
is posted.

Parameters None

Return Values Returns True if the record is not in the database, otherwise False.

Example The following code fragment shows a typical way to use this method to check for a
new record prior to carrying out some action.
If Cobj_Case.IsNew Then
' save the case
...
End If

416 IsNew
ClearBasic Object Reference
 Record object

method Print

Syntax YourRecord.Print

UDTs Supported This method supports user defined types.

Applies To Record

Description The Print method prints the contents of the record to standard output. This method
prints the values of each field.

Standard output varies on each platform. On UNIX systems, the standard output
depends on your environment, but is usually a file or device. On Windows systems,
standard output is the file standard.out, which is located in the ClarifyCRM folder.

Parameters None

Return Values None

See Also Printer object

Print 417
ClearBasic Object Reference
 Record object

method SetField

Syntax YourRecord.SetField FieldName, Value

Applies To Record

Description The SetField method assigns a new value to the specified field of the record. The
changes you make using this method are stored in memory by the Record object. To
save these changes to the database, you must save this record using a BulkSave
object.

The field name you specify for the FieldName parameter must represent a valid field
name of the current record type. If you specify an invalid field name, this method
generates an error.

Parameters This method accepts the following parameters:

Parameter Type Description

FieldName String Specify the name of the field you want to set. The name of this field
is case sensitive.
Value variable Specify an Integer, a String, or a Float value, depending on the type
of field you are placing it into.

Example The following example creates a new record and uses the SetField method to assign
values to four fields.
Dim obj as New Record
obj.RecordType = "query_elm"

obj.SetField "field_name", "case_id"

obj.SetField "field_value", elm.case_id
obj.SetField "oper_id", 4
obj.SetField "oper_name", "is equal to"

See Also GetField method

418 SetField
ClearBasic Object Reference
 Record object

property RecordType

Syntax RecType = YourRecord.RecordType

YourRecord.RecordType = "Type"

Applies To Record

Description The RecordType property contains a string value that identifies the name of the table
or view represented by this object. You can get this property to view the type of a
record. You can also set this property to associate the Record object with a new type.

If you receive a Record object in your ClearBasic code, you can use this property to
determine the type of the record before you process it. Once you know the type, you
can get and set fields of the corresponding database row safely.
When you first create a Record object, you must set the value of this property to the
name of a specific database table or view. If the Record object already contains data,
setting this property clears that data and creates a new empty record of the specified
type, even if the new type is the same as the old type. Setting this property only affects
the data in the Record object and does not affect existing database rows.

Settings This property accepts the following settings:

Setting Type Description

Type String You must supply the object type name. This must be a valid database
object name or view name (string). Valid names are listed in the Data
Dictionary Guide. Names are case-sensitive.

Example The following example creates a new record for the query table. After setting some
initial fields, the code relates the object to the current user and saves the record in the
database.
Dim qryObj As New Record
Dim BulkSave As New BulkSave

qryObj.RecordType = "query"
qryObj.SetField "title", "Case Query 1"
qryObj.SetField "obj_type", 0

BulkSave.InsertRecord qryObj
BulkSave.RelateRecordsFromID "user", _
App.UserObjid, qryObj, "originator2query"
BulkSave.Save

RecordType 419
ClearBasic Object Reference
 Record object

420 RecordType
ClearBasic Object Reference
 Screen object

Description You use the Screen object to obtain information about the current form or control.

Comments Because the Screen object is a system object, you don’t need to declare it in your
code.

Methods This object defines the following method:

■ AllSpaces method

ClearBasic Object Reference 421

 Screen object

method AllSpaces

Syntax YourBoolean = Screen.AllSpaces(StringToCheck)

Applies To Screen

Description You can use this method to determine whether the specified string contains all space
characters.

NOTE: Tabs and newline characters are considered spaces.

Parameters This method accepts the following parameter:

Parameter Type Description

StringToCheck String You must specify the string or string variable that you want to
check.

Return Values This method returns True if a string contains all spaces, False if the string does not
contain all spaces.

422 AllSpaces
ClearBasic Object Reference
 ServiceMessage object

Description The ServiceMessage object provides mechanism for communication between the
ClarifyCRM Application Server and the external components in a TUXEDO service
environment.

NOTE: This object can only be used in an N-tier programming environment. For detailed
information about using the ServiceMessage object and the associated methods in an N-
tier environment, refer to the Flexible Deployment Guide.

Comments You declare an ServiceMessage object as follows:

Dim YourServiceMessage As New ServiceMessage

You use the usual syntax to pass the ServiceMessage as an argument to a

subroutine. For example,
Sub YourSub (YourServiceMessage As ServiceMessage)

Methods This object defines the following methods:

■ Call method
■ Read method
■ Write method

ClearBasic Object Reference 423

 ServiceMessage object

method Call

Syntax YourServiceMessage.Call Callback_name, mode

Applies To ServiceMessage

Description The Call method calls the function (Callback_name) present in an external component
in a Tuxedo service environment. Depending on the mode specified, the call can be
synchronous or asynchronous.

IMPORTANT: This method can only be used with the ServiceMessage object, which in
turn can only be used in an N-tier programming environment. For detailed information about
using the ServiceMessage object and the associated methods in an N-tier environment,
refer to the Flexible Deployment Guide.

Parameters The following parameters are accepted by this method:

Parameter Type Description

Callback_name String Required. Name of the function that resides in the external
component
mode Long Optional. Default is 1
0 specifies synchronous
1 specifies asynchronous
You can specify the cbCallAsync constant instead of 1.

Return Values None

Example The following example illustrates the use of the Call method:
' Subroutine for app server
Sub UseSMOCall()
Dim tmpOccurence As Integer ' field
Dim tmpEquip_ID As Integer ' buffer
Dim tmpFieldValue As Integer ' field value
Dim tmpFieldName As String ' field name
Dim tmpExtFunctName As String
Dim tmpSMO As New ServiceMessage

On Error Goto ErrorHandler

' Set the name of the Tuxedo function

' This function must not have any
' parameters
tmpExtFunctName = "ExtFunct1"

' Set up the field information

424 Call
ClearBasic Object Reference
 ServiceMessage object

tmpFieldName = "EQUIP_ID"
tmpOccurence = 0
tmpFieldValue = 1

' Write a value to the field

tmpSMO.Write tmpFieldName, tmpOccurence, _
tmpFieldValue

' Call the external component’s function

' asynchronously.
tmpSMO.Call tmpExtFunctName, cbCallAsync '
End Sub

See Also Read method

Write method
CallCB method (App object)

Call 425
ClearBasic Object Reference
 ServiceMessage object

method Read

Syntax RetInt = YourServiceMessage.Read (field_name, occurrence,

contents)

Applies To ServiceMessage

Description The Read method reads the specified occurrence (occurrence) of a named field
(field_name) in the fld.tbl table in the message and places the a copy of the contents
in the variable contents. The variable contents must be of the same data type as the
data read from the named field.

IMPORTANT: This method can only be used with the ServiceMessage object, which in
turn can only be used in an N-tier programming environment. For detailed information about
using the ServiceMessage object and the associated methods in an N-tier environment,
refer to the Flexible Deployment Guide.

Parameters The following parameters are required and accepted by this method:

Parameter Type Description

field_name String Required. The field to be read from fml.tbl.
occurrence Long Required. The occurrence of this field to be read.
contents variable Optional. The Read method inserts the actual value read in this
variable.

Return Values This method can return any of the following values:

0 = Read value is valid

1 = Invalid field ID
2 = Unsupported field type
3 = Invalid field type
4 = TUXEDO FML error

Example The following example illustrates the use of the Read method:
Sub UseSMORead(InSMO As ServiceMessage)
Dim tmpOccurence As Integer 'Field occurence
Dim tmpEquip_ID As Integer 'temp buffer for a field
Dim tmpReturnStatus As Integer 'Return status
Dim tmpFieldName As String 'Field name in fld.tbl

On Error Goto ErrorHandler

tmpFieldName = "EQUIP_ID"
tmpOccurence = 0 '//Set occurence to default//

' Read 1st occurence of a field

426 Read
ClearBasic Object Reference
 ServiceMessage object

tmpReturnStatus = InSMO.Read(tmpFieldName, _
tmpOccurence, tmpEquip_ID)

If tmpReturnStatus <> 0 Then

Debug.Message "Error occurs when reading _
field from ServiceMessage object."
Else
Debug.Message "No errors."
End If

Exit Sub

ErrorHandler:
Debug.Message Error$, STR$(Erl)
End Sub

See Also Call method

Write method

Read 427
ClearBasic Object Reference
 ServiceMessage object

method Write

Syntax YourServiceMessage.Write Field_name, Occurrence, Value

Applies To ServiceMessage

Description The Write method writes the contents of the Value parameter to the specified
occurrence (Occurrence) of a named field (Field_Name) in the message.

You cannot specify a literal value for the Value parameter. You must first assign a
value to this parameter. Refer to the example below.

IMPORTANT: This method can only be used with the ServiceMessage object, which in
turn can only be used in an N-tier programming environment. For detailed information about
using the ServiceMessage object and the associated methods in an N-tier environment,
refer to the Flexible Deployment Guide.

Parameters The following parameters are required and accepted by this method:

Parameter Type Description

Field_name String The field to be read from fml.tbl.
Occurrence Long The occurrence of the field to be written to.
Value variable The contents of the field to be written.

Return Values None

Example The following example illustrates the use of the Write method:
Sub UseSMOWrite()
Dim tmpOccurence As Integer 'field occurence
Dim tmpEquip_ID As Integer 'temproary buffer

'Actual field value

Dim tmpFieldValue As Integer

'Field name in fld.tbl

Dim tmpFieldName As String
'Declare and initialize a ServiceMessage
' object
Dim tmpSMO As New ServiceMessage

On Error Goto ErrorHandler

tmpFieldName = "EQUIP_ID"
tmpOccurence = 0 'Set occurence to default
tmpFieldValue = 1 'Assign a field value

428 Write
ClearBasic Object Reference
 ServiceMessage object

'Write a value to the field

tmpSMO.Write tmpFieldName, tmpOccurence, _
tmpFieldValue

Exit Sub

ErrorHandler:
Debug.Message Error$, STR$(Erl)
End Sub

See Also Call method

Read method

Write 429
ClearBasic Object Reference
 ServiceMessage object

430 Write
ClearBasic Object Reference
 SQLDB object

Description The SQLDB object is used for direct interaction with databases via SQL statements.
The methods for this object allow database interaction with different databases that
are of the same type as the one the user is currently logged into. The different
databases can be on the same server or different servers.

This method creates an auxiliary connection to a database for the purpose of using
SQL type communication with the database. Making such a connection does not sever
the connection with the database the user is currently logged into. The database to
which the connection is being made may be on the same server as the login database,
or on a different server. The database to be connected need not be a database with a
ClarifyCRM schema. The only restriction is that the server must be of the same type
and release number as the login server. This means that if you log into a Sybase 4.9-
served database, you cannot connect to an Oracle database, or even a Sybase 10-
served database.

NOTE: If you want to use the wildcard character % in your statements in the SQLDB object, you
must specify it twice. For example, the following statement will select all customers whose names
start with "Ma"

Select Name from Customer where Name

like ’Ma%%’

SQLDB and MS The Traveller component of the ClarifyCRM suite uses a Microsoft Access database to
Access manage database transactions on the offline client. The SQL commands associated
with MS Access databases are sometimes different from standard SQL. As a result, MS
Access database do not recognize all of the defined SQL keywords. For example, you
cannot use the following keywords in an MS Access database: CONVERT,
SUBSTRING, and GETDATE().
If you are using the SQLDB object to customize Traveller, make sure you use SQL
commands that are supported by MS Access databases. To achieve this goal, you may
need to implement a separate version of your ClarifyCRM application specifically for
offline clients.

Methods This object defines the following methods:

■ Connect method
■ Disconnect method
■ Execute method
■ ExecuteProc method
■ Select method

ClearBasic Object Reference 431

 SQLDB object

Property This object defines the following property:

■ Connected property

432
ClearBasic Object Reference
 SQLDB object

method Connect

Syntax YourSQLDB.Connect "Server", "DBName", "UserName", "Password",

Timeout

Applies To SQLDB

Description You use this method to connect to a database with which you want to communicate
using SQL-type statements. The database you are connecting to can be on the same
server or a different server as the login database. However, the database you are
connecting to must be of the same type and version as the login database. For example
if you are logged into a Sybase 4.9 database, you cannot log into an Oracle database or
a Sybase 10 database.
Using this method does not stop any existing database connections.

NOTE: The database you are connecting to can be a database that was created with the
ClarifyCRM schema or it can be a database that does not have the ClarifyCRM schema.

If you do not use the Connect method, the SQLDB object is automatically connected to the
ClarifyCRM database.

Parameters This method takes the following parameters:

Parameter Type Description

Server String You must specify the name (string value) of the server you want to
connect to.
DBName String You must specify the name of database (string value) you want to
connect to.
UserName String You must specify a valid user name (string value).
Password String You must specify the user password (string value).
Timeout Long This parameter is optional. If you want, you can specify the number
of seconds (integer value) to wait before aborting the connection
attempt.

Return Values This method returns no values.

Connect 433
ClearBasic Object Reference
 SQLDB object

Example In the following code, in response to a user selection from a grid and subsequent
button click, a record field in the database is filled with the current date and the
display of that record is updated with the current date. Notice that everything that
can be done is done before calling Connect, to minimize connection time. Notice also
that GetContents is used, rather than Contents, because it is applied to a user-
defined type.
Sub Update_Click
Dim Ind As Integer
Dim SqlState As String
Dim theDate As String
Dim ordRecord As Order_Record
Dim ordList As New List
Dim toDB As New SQLDB

'Get current date to update the record field,

'then get index of the selected item in the
'grid. The index is needed later to
'get the selected record.
theDate = App.CurrentDate
Ind = Order_Array.ListIndex

'Put list of records in the control into

'ordList, then use index of the selected item
'to get the record.
ordList.ItemType = "Order_Record"
Cobj_ord_record.GetContents ordList
ordList.GetItemByIndex Ind, ordRecord

'Set up sql statement to update the record

'field.
SqlState = "update order_tbl set _
notify_dt = '" & theDate & " ' _
where uId = " & ordRecord.uId

'Connect to DB, execute SQL, then disconnect.

toDB.Connect "SUSM", "cbforeign", "sa", _
"sax"
toDB.Execute SqlState
toDB.Disconnect

'Update the displayed record to match DB

'record.
ordRecord.notify_dt = theDate
ordList.ReplaceByIndex Ind, ordRecord
Cobj_ord_record.Fill ordList
End Sub

See Also Disconnect method

Execute method
Select method
Connected property

434 Connect
ClearBasic Object Reference
 SQLDB object

method Disconnect

Syntax YourSQLDB.Disconnect

Applies To SQLDB

Description The Disconnect method terminates a connection that was created with the
Connect method for SQLDB objects. However, this method cannot be used to
terminate the connection to the database that the user originally logged into.

You should invoke this method when you are finished with a particular connection. If
you don’t, server and network performance can be adversely affected.

Parameters None

Return Values None

Example See the example provided under Connect.

See Also Connect method

Execute method
Select method

Disconnect 435
ClearBasic Object Reference
 SQLDB object

method Execute

Syntax YourSQLDB.Execute SQLStatement

Applies To SQLDB

Description The Execute method can be used to issue any SQL statement that does not return
values, such as insert, update, or delete operations. (You cannot use this method for
Select operations.) Before invoking this method, you must successfully establish a
connection to the database using the Connect method.

IMPORTANT: If you are using the SQLDB object to customize Traveller, make sure you use
SQL commands that are supported by MS Access databases. To achieve this goal, you may
need to implement a separate version of your ClarifyCRM application specifically for offline
clients.

Parameters This method accepts the following parameter:

Parameter Type Description

SQLStatement String You must supply a string variable. The length of the statement
string in the string variable can be a maximum of 6144 characters.

Return Values None

Example In the following code, in response to a user selection from a grid and subsequent
button click, a record field in the database is filled with the current date and the
display of that record is updated with the current date. Notice that the SQL statement
is built up before calling Connect.
Sub Update_Click
Dim Ind As Integer
Dim SqlState As String
Dim theDate As String
Dim ordRecord As Order_Record
Dim ordList As New List
Dim toDB As New SQLDB

'Get current date to update the record field,

'then get index of the selected item in the
'grid. The index is needed later to
'get the selected record.
theDate = App.CurrentDate
Ind = Order_Array.ListIndex

'Put list of records in the control into

'ordList, then use index of the selected item
'to get the record.

436 Execute
ClearBasic Object Reference
 SQLDB object

ordList.ItemType = "Order_Record"
Cobj_ord_record.GetContents ordList
ordList.GetItemByIndex Ind, ordRecord

'Set up sql statement to update the record

'field.
SqlState = "update order_tbl set notify_dt='" _
& theDate & "' where uId=" & ordRecord.uId

'Connect to DB, execute SQL, then disconnect.

toDB.Connect "SUSM", "cbforeign", "sa","sax"
toDB.Execute SqlState
toDB.Disconnect

'Update the displayed record to match DB

'record.
ordRecord.notify_dt = theDate
ordList.ReplaceByIndex Ind, ordRecord
Cobj_ord_record.Fill ordList
End Sub

See Also Connect method

Disconnect method
Execute method
Select method

Execute 437
ClearBasic Object Reference
 SQLDB object

method ExecuteProc

Syntax YourSQLDB.ExecuteProc ProcName, InputList, ReturnVal

Applies To SQLDB

Description Use this method to invoke a database stored procedure with a list of the input values
required by the stored procedure. This method supports user defined types. In fact, it
requires the values returned to be stored in a UDT.

NOTE: If the stored procedure requires a list of input values of different data types, you must
set the ItemType of the List object containing those values to Variant before placing the
values in the List. Notice that the only method that can be used on a Variant List is
AppendItem.

Parameters This method accepts the following parameters

Parameter Type Description

ProcName String You must specify the name of a stored procedure that is currently in
the database.
InputList List You must specify a list of one or more values to be used as inputs to
the stored procedure.
The values in the input list can be any combination of the following
types: integer, long, single, string.
ReturnVal UDT You must use this parameter to contain returned values in a user-
defined type, which defines the types of the values.

Return Values None

Example The following sample procedure contains a Sub procedure that invokes
ExecuteProc.

First, an input list (InList) is filled with values required by the stored procedure
(Test1). Notice that the list is set to the type variant. You must use the list type of
variant if the list contains values of different types, in our example string and integer.
After the input list for the stored procedure is filled, ExecuteProc is called with the
values in InList provided as the inputs to the Test1 stored procedure. Test1
returns values to OutVals, which has a user-defined type (MyType). From the type
definition, notice the sorts of values expected back, objid, name, status, privclass, etc.
Type MyType
ObjId As Integer
Name As String * 255
Status As Integer
PrivClass As Long
Test1 As String * 255

438 ExecuteProc
ClearBasic Object Reference
 SQLDB object

End Type

Sub TestExecuteProc
Dim DB As New SQLDB
Dim InList As New List
Dim OutVals As MyType

InList.ItemType = "variant"
InList.AppendItem 1
InList.AppendItem "alpo"

DB.ExecuteProc "Test1", InList, OutVals

End Sub

NOTE: This example does not use the Connect method. Therefore, the ExecuteProc
method executes the stored procedure in the default ClarifyCRM database, that is, the database
into which the user originally logged in.

ExecuteProc 439
ClearBasic Object Reference
 SQLDB object

method Select

Syntax RetInteger = YourSQLDB.Select (SQLStatement, DestinationList,

DestinationFields)

Applies To SQLDB

Description The Select method issues an SQL select statement to the database that the SQLDB
object is connected to by the Connect method. Any results are placed into the
specified output list. You need to define a type that contains the fields you select, then
specify that the DestinationList parameter is of your user-defined type.

IMPORTANT: If you are using the SQLDB object to customize Traveller, make sure you use
SQL commands that are supported by MS Access databases. To achieve this goal, you may
need to implement a separate version of your ClarifyCRM application specifically for offline
clients.

The Select method requires that DestinationList is a list with HeadType which is a
UDT corresponding to the columns selected by the SQL statement.

Parameters This method accepts the following parameter:

Parameter Type Description

SQLStatement String You must supply the variable or constant containing the select
statement string, which must begin with the verb "select." The
maximum length of the statement string is 6144 characters.
DestinationList UDT You must provide the name of the list that is to contain the
List results from the select operation. This list contains user defined
types.
DestinationFields List This parameter is optional.
If you only want the values of certain fields returned, you can
supply a list of the field names that you want filled. Only values
from those fields are placed into the UDT in DestinationList.

Return Values Returns a Long value indicating the number of records obtained as a result of the
select operation.

440 Select
ClearBasic Object Reference
 SQLDB object

Example In the following example, a SQL statement is constructed. The columns are read into
the fields of a user-defined type (Order_Record). A connection to the database is
made, the Select statement is executed and the requested records are put in ordList.
The list of records is looped through and each record is checked for a certain date: if
found, that date field is cleared and the revised record replaces the original in ordList.
When the loop completes, the list is loaded into obj_ord_record where it is
displayed in a grid control.
Sub Form_Load
Dim Ind As Integer
Dim SqlStatement As String
Dim ordRecord As Order_Record
Dim ordList As New List
Dim toDB As New SQLDB

ordList.ItemType = "Order_Record"
SqlStatement = "select uId, site_id, _
ord_nr," & "description,_
convert(char(8),due_dt,1)," & _
"convert(char(8),notify_dt,1)," & _
"amount from order_tbl" & _
"where site_id='" & gSiteVal & "'"

toDB.Connect "MUGS", "cbforin", "sa", "sax"

toDB.Select SqlStatement, ordList
toDB.Disconnect

For Ind=0 to ordList.Count - 1

ordList.GetItemByIndex Ind,ordRecord

If ordRecord.notify_dt = "01/01/00" Then

ordRecord.notify_dt = " "
ordList.ReplaceByIndex Ind, ordRecord
End If
Next Ind

Cobj_ord_record.Fill ordList
End Sub

See Also Connect method

Disconnect method
Execute method

Select 441
ClearBasic Object Reference
 SQLDB object

property Connected

Syntax YourBoolean = YourSQLDB.Connected

Applies To SQLDB

Description The Connected property contains a boolean value indicating whether there is a valid
connection to the database. This property contains the value True if there is a valid
connection, otherwise False.

This property is read-only.

442 Connected
ClearBasic Object Reference
Appendix A
Supported Objects, Methods,
Properties and Events

In This Appendix
Object and Method Matrix . . . . . . . . . . . . . . . . . . . . 444
Object and Property Matrix . . . . . . . . . . . . . . . . . . . 449
Object and Event Matrix . . . . . . . . . . . . . . . . . . . . . 451

ClearBasic Object Reference 443

 Supported Objects, Methods, Properties and Events

Object and Method Matrix

Table 2 lists the ClearBasic objects and the methods supported by each.

Table 2 Supported methods for objects

Global Constants
ContextualObject

ServiceMessage
CommonDialog
Object

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug
Form
App

Dde

List
Method
Action
AddItem •
AddItems
AddSeparator •
AllSpaces •
AppendContextMenu •
AppendFilter • •
AppendItem • •
AppendSort • •
Call •
CallCB •
CancelRecord •
ChangeRecord •
ChangeToNew •
CheckItem •
CheckRequired •
Clear • • • •
ClearContextMenu •
Close •
CLTransition •
Concat •
Connect •
Contains •
ConvertCurrency •
ConvertCurrencyValue •
Copy •
CopyFields •
CountByType •
CreateColorScheme •
CreateView •
DDEExecute •
DDEInitiate •
DDERequest •

444 Object and Method Matrix

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Table 2 Supported methods for objects (Continued)

Global Constants
ContextualObject

ServiceMessage
CommonDialog
Object

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug
Form
App

Dde

List
Method
DDETerminate •
DDETimeout •
DeleteRecord •
DeleteRecordById •
DisableControls •
DisableControlsDeep •
Disconnect •
DoDefault • •
Down •
Empty •
Enable •
EnableControls •
EnableControlsDeep •
EndDoc •
EntryCount •
Execute •
ExecuteCB •
ExecuteMenu •
ExecuteProc •
ExitApp •
ExtractList •
Fill •
FindFirstIndex •
ForceRedraw •
Format •
GenerateID •
GetCBCObj •
GetChildKeyList •
GetCObjFieldList •
GetCObjGridFieldStaticItem •
GetCObjGridFieldStaticList •
GetCObjList •
GetCObjMethodKeyList •
GetCObjMethodList •
GetCObjPropertyKeyList •
GetContents •

Object and Method Matrix 445

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Table 2 Supported methods for objects (Continued)

Global Constants
ContextualObject

ServiceMessage
CommonDialog
Object

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug
Form
App

Dde

List
Method
GetContext •
GetControlByName •
GetCount •
GetCurrentDB •
GetDisplayCurrency •
GetField •
GetFormat •
GetFormInstance •
GetItemByIndex •
GetLastError •
GetMethodValue •
GetObject •
GetPropertyValue •
GetRecordByIndex •
GetRecordList •
GetRelatedRecordList •
GetString •
GetText •
GetTextField •
GetUserData •
GetUserPopupListLevel1 •
GetUserPopupListLevel2 •
Hide •
InheritCurrency •
InputBox •
InsertRecord •
IsDirty •
IsEnabled •
IsExactly •
IsItemChecked •
IsMaxDate •
IsMinDate •
IsNew • •
ItemByIndex •
Line •
ListByIndex •

446 Object and Method Matrix

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Table 2 Supported methods for objects (Continued)

Global Constants
ContextualObject

ServiceMessage
CommonDialog
Object

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug
Form
App

Dde

List
Method
Login •
Logout •
LogSQL •
Move •
MsgBox •
NewPage •
Notify •
NotifyById •
NotifyByKey •
NotifyChild •
NotifyParent •
NotifyTab •
NotifyTabParent •
Print • • • • •
Query •
Read •
Refresh • •
RelateRecords •
RelateRecordsFromID •
RelateRecordsFromToID •
RelateRecordsToID •
RemoveByIndex •
RemoveItem •
RenameItem •
ReplaceByIndex •
RetrieveIDS •
RetrieveRecords • •
Save •
Select •
SetColorScheme •
SetContextMenuEnabled •
SetContextMenuVisible •
SetDisplayCurrency •
SetField •
SetFocus •
SetFunction •

Object and Method Matrix 447

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Table 2 Supported methods for objects (Continued)

Global Constants
ContextualObject

ServiceMessage
CommonDialog
Object

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug
Form
App

Dde

List
Method
SetObjectType •
SetParent •
SetRoot •
SetRootById •
SetSortOrder •
SetTargetCurrency •
SetText •
SetUserData •
SetValue •
Show • • •
ShowAttachments •
ShowCase •
ShowContact •
ShowContract •
ShowControls •
ShowControlsDeep •
ShowCR •
ShowDefaultMenu •
ShowEmployee •
ShowFTS •
ShowSelect •
ShowSite •
ShowSubcase •
SimpleQuery •
Sort • •
TextHeight •
TextWidth •
TransferPart •
TraverseFromParent •
TraverseFromRoot •
UnrelateRecords •
Up •
UpdateRecord •
UseClarifyDB •
UseDefaultDB •
Write •

448 Object and Method Matrix

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Object and Property Matrix

Table 3 lists the ClearBasic objects and the properties supported by each. In the table,
R signifies Read-only, W signifies write-only, and ” • “ signifies both read and write at
run time.

Table 3 Supported properties for objects

ContextualObject

Global constants

ServiceMessage
CommonDialog
Object>

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug

Form
App

Dde

List
Property
Action •
ActiveControl R
AllowDuplicates •
BackColor • •
CancelError •
Caption • •
Connected R •
Contents R
Continuation •
Copies R
Count R
CurrentDate R
CurrentX •
CurrentY •
DatabaseName R R
DataChanged • • •
DataType •
DateTime •
DefaultExt •
DialogId •
DialogTitle •
DrawMode •
DrawStyle •
DrawWidth •
ElapsedSeconds •
EmployeeObjID R
EXEName R
FileName •
FileTitle R
FontBold •
FontFamily •

Object and Property Matrix 449

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Table 3 Supported properties for objects (Continued)

ContextualObject

Global constants

ServiceMessage
CommonDialog
Object>

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug

Form
App

Dde

List
Property
FontItalic •
FontSize •
ForeColor •
FromPage R
Height • R
hWnd R
Id R
InitDir •
ItemType •
Key R
Left •
List R
MenuBarID •
Name R R
Page R
ParentKey R
QuerySize •
ReadOnly •
RecordType •
RightMargin •
Save_Aborted •
ServerName R R
Sorted R
SubType •
Tag • •
Top •
ToPage R
Truncate •
UserName R R
UserObjID R
Value •
Visible •
Width • R
WindowState •
Wrap •

450 Object and Property Matrix

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

Object and Event Matrix

Table 4 lists the ClearBasic objects and the events supported by each.

Table 4 Supported events for objects

ContextualObject

Global constants

ServiceMessage
CommonDialog
Object>

BulkRetrieve

PowerQuery
Clipboard
ClarifyDB
AppMenu

BulkSave

SQLDB
Record
Screen
Printer
Debug
Form
App

Dde

List
Events
Activate •
ContextMenuDisplaying •
ContextMenu_Select •
DblClick •
Deactivate •
Form_Load •
Form_Save •
Form_Unload •
MouseDown •
MouseUp •
Resize •

Object and Event Matrix 451

ClearBasic Object Reference
 Supported Objects, Methods, Properties and Events

452 Object and Event Matrix

ClearBasic Object Reference
Appendix B
APIs

In This Appendix
APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Flexible Attribute Constants. . . . . . . . . . . . . . . . . . . 472
Related Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

ClearBasic Object Reference 453

 APIs

APIs
The application programming interfaces (APIs) are provided to help your customer
perform specific customization without requiring the customer to code read and write
access to the data schema.

The APIs are developed using ClarifyCRM’s ClearBasic Objects to set or customize
Flexible Attributes without using the graphical user interfaces (GUIs). See the
ClearBasic Object Reference for additional information.

The Flexible Attribute APIs use the Persistent Object Management Server (POMS) to
set, retrieve, update and delete data in the ClarifyCRM database. The customer uses
the ClarifyCRM Client to set, update and retrieve the Flexible Attributes. They have
been developed to indirectly access the database.

There are ten APIs used for Flexible Attributes.

■ faEditAttributes
■ faGetAttribute
■ faSetAttribute
■ faGetAttributeList
■ faSetAttributeList
■ API
■ faGetRelation
■ faSetRelation
■ API
■ faDeleteAttributes

454 APIs
ClearBasic Object Reference
 APIs

API faEditAttributes
This API displays the View Attributes form (Figure 5: on page 455) in ClarifyCRM
Client. The form displays the Flexible Attributes values.

Declaration Sub faEditAttributes (frmFocus As Form, recFocus As Record, Optional avReadOnly

As Variant)

Parameters

Parameter Direction Description

frmFocus In The calling form
recFocus In The focus object instance receiving the attributes.
vReadOnly In This is an optional parameter:
• If set and equal to 0, then the Line Items form (Figure 5:) is
opened in read-only mode.
• Otherwise, the form opens in read/write mode.

Figure 5: View Attributes form

faEditAttributes 455
ClearBasic Object Reference
 APIs

faEditAttribute The faEditAttributes API is called to open the Edit Attributes Form in read/write
Example mode for the attributes associated to case ID 1.

Declare Sub faEditAttributes(frm As Form, recFocus As

Record,_
Optional avReadOnly As Variant)
Dim brCaseAs New BulkRetrieve
Dim lstCaseAs List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

faEditAttributes Me, recCase, 1

456 faEditAttributes
ClearBasic Object Reference
 APIs

API faGetAttribute
This API returns the value of a single Flexible Attribute. It does not return relation
attributes. To obtain a relation attribute, use the faGetRelation function.

Declaration Function faGetAttribute (recFocus As Record, zName As String) As Variant

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified attribute.
zName In The specified attribute name.

Return value
Return value Description
value The value of the specified Flexible Attribute.
null A null is returned if the specified attribute is not set.

faGetAttribute The faGetAttribute API is used to return the value of the attribute named
Example “accountnum” for the case identified by ID number 1.

Declare Function faGetAttribute (arecFocus As Record,

astrName As String)_
As Variant
Dim vAttrValueAs Variant
Dim brCaseAs New BulkRetrieve
Dim lstCase As List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

vAttrValue = faGetAttribute(recCase, "accountnum")

faGetAttribute 457
ClearBasic Object Reference
 APIs

API faSetAttribute
The faSetAttribute API updates the value stored in the N_AttributeValue table for a
single Flexible Attribute. The database is updated by this call. For relations, use
faSetRelation.

Declaration Function faSetAttribute (recFocus As Record, zName As String, vValue As Variant,

Optional vType As Variant, Optional vBasic As Variant) As Integer

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified attribute.
zName In The specified attribute name.
vValue In The value set for the specified attribute.
vType In This is an optional parameter.
• If this parameter is set and is negative, then it is the negative of
the attribute type of the new value that is inserted.
• If the parameter is set and is positive, then it is the object ID of
the value to be updated.
• If the parameter is not set, the faGetAllAttributes API subroutine
is called to verify that the attribute specified is valid for the focus
object instance.
vBasic In This is an optional parameter.
• If this parameter is set, a basic read of the N_AttributeValue table
is performed.
• If it is not set and the Process Manager software is present, the
stored procedures are used to read the N_AttributeValue table.

Return Values
Return Value Description
faOK OK
faNotDefined The specified attribute name is not defined for this focus object instance.
faInvalidValue The passed record is invalid for the target object type.
faDBError This is a database error that occurred during the save operation.

458 faSetAttribute
ClearBasic Object Reference
 APIs

faSetAttribute The faSetAttribute API is called to set the value of the attribute named “color” to
Example “magenta” for the case identified by ID number 1.

Declare Function faSetAttribute (arecFocus As Record,

astrName As String,_ avValue As Variant, Optional avType
As Variant,_ Optional avBasic As Variant)_ As Integer

Dim intRetCodeAs Integer

Dim brCaseAs New BulkRetrieve
Dim lstCaseAs List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

intRetCode = faSetAttribute(recCase, "color", "magenta")

faSetAttribute 459
ClearBasic Object Reference
 APIs

API faGetAttributeList
The faGetAttributeList API returns a list of the attribute values and corresponding
data types. The values are retrieved using one database read.

Declaration Sub faGetAttributeList (recFocus As Record, 1stName As List, 1stType As List,

1stValue As List)

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified attributes.
1stName In The list of attribute names (List of Strings) to get.
1stType Out The list of data types (List of Longs) which corresponds to the
value type of each string in the 1stValue parameter.
1stValue Out The list (List of Strings) in which the values of the specified
attributes are returned. If the attributes are not set, a null is
returned as 1stValue.

460 faGetAttributeList
ClearBasic Object Reference
 APIs

faGetAttributeList The faGetAttributeList API is used to return a list of values for the attributes provided
Example in the lstName list for the case identified by ID number 1.

Declare Sub faGetAttributeList (arecFocus As Record,

alstName As List,_
alstType As List, alstValue As List)
Dim lstNameAs New List
Dim lstValueAs New List
Dim lstTypeAs New List
Dim brCase As New BulkRetrieve
Dim lstCase As List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

lstName.ItemType = "String"
lstName.AppendItem "color"
lstName.AppendItem "price"
lstName.AppendItem "flag"

lstValue.ItemType = "String"

lstType.ItemType = "Long"

faGetAttributeList recCase, lstName, lstType, lstValue

faGetAttributeList 461
ClearBasic Object Reference
 APIs

API faSetAttributeList
The faSetAttributeList API sets a list of attributes using one database transaction.

Declaration Function faSetAttributeList (recFocus As Record, 1stName As List, 1stValue as List,

1stStatus As List, Optional vBasic As Variant) As Integer

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified attributes.
1stName In The list of attribute names (List of Strings) to get.
1stValue In The list (List of Strings) contains the values to be returned
for the specified attributes.
1stStatus Out The list of status. These are the return code for each of the
attributes to be set: faOK, faNotDefined and
faInvalidValue.
vBasic In This is an optional parameter.
If it is set, a basic read of the N_AttributeValue will be
performed.
If it is not set and the Process Manager software is present,
the stored procedures will be used to read the
N_AttributeValue table.

Return Values

Return Value Description

faOK OK
faError At least one of the attributes failed to have its value set. The status
values returned in 1stStatus need to be examined to determine which
attribute(s) failed.

462 faSetAttributeList
ClearBasic Object Reference
 APIs

faSetAttributeList The faSetAttributeList API is called to set the values of the attributes contained in the
Example list lstName to the values contained in the list lstValue for the case identified by ID
number 1.
Declare Function faSetAttributeList (arecFocus As Record,
alstName As_
List, alstValue As List, alstStatus As List, Optional avBasic
As Variant ) As_ Integer

Dim intRetCodeAs Integer

Dim lstNameAs New List
Dim lstValueAs New List
Dim lstStatusAs New List
Dim brCaseAs New BulkRetrieve
Dim lstCase As List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

lstName.ItemType = "String"
lstName.AppendItem "color"
lstName.AppendItem "price"
lstName.AppendItem "flag"

lstValue.ItemType = "String"
lstValue.AppendItem "red"
lstValue.AppendItem "39.99"
lstValue.AppendItem "0"

lstStatus.ItemType = "Long"
lstStatus.AppendItem 0
lstStatus.AppendItem 0
lstStatus.AppendItem 0

intRetCode = faSetAttributeList(recCase, lstName, lstValue,

lstStatus, 1)

faSetAttributeList 463
ClearBasic Object Reference
 APIs

API faGetAllAttributes
This API returns a list of all the valid N_AttributeValue records currently defined for
the focus object instance whether or not the attribute value has been set. Valid
attributes are found three ways:
■ Valid attributes which already have values are retrieved from the
N_AttributeValue table.
■ The product path in the N_AttributeDefinition table is used to find any
properties which have been defined using the configurator.
■ The tables N_AttributeDefinition, N_AttributeCondition and N_Templates are
read to determine which of the attributes in the N_Attribute table are valid for
the focus object instance, but have not been assigned a value yet.
■ faGetAllAttributes is used to return N_Required copied from the
definition for new attributes. For existing attribute values, the value of
N_Required is not relevant.

Declaration Sub faGetAllAttributes (recFocus As Record, 1stAttributeValue As List)

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified attributes.
lstAttributeValue Out The list in which the N_AttributeValue records are
returned.

464 faGetAllAttributes
ClearBasic Object Reference
 APIs

faGetAllAttributes The faGetAllAttribute API is used to return a list containing all valid attributes for the
Example case identified by ID number 1.

Declare Sub faGetAllAttributes (arecFocus As Record,

alstAttributeValue_
As List )
Dim lstAttrValAs List
Dim brCaseAs New BulkRetrieve
Dim lstCaseAs List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

faGetAllAttributes recCase, lstAttrVal

faGetAllAttributes 465
ClearBasic Object Reference
 APIs

API faGetRelation
The faGetRelation API returns a record which is related to the focus object using a
Flexible Attribute relation.

Declaration Function faGetRelation (recFocus As Record, zName As String) As Record

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified
attribute.
zName In The specified attribute name.

Return Values

Return Value Description

record The related record of the specified Flexible Attribute.
new record A new record is returned if the attribute is not set or if the attribute is not
defined as a relation.

faGetRelation The faGetRelation API is used to return the record related to the case, identified by ID
Example number 1, through the attribute named “primary”.

Declare Function faGetRelation (arecFocus As Record,

astrName As String )_
As Record
Dim recRelatedAs New Record
Dim brCase As New BulkRetrieve
Dim lstCase As List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

Set recRelated = faGetRelation(recCase, "primary")

466 faGetRelation
ClearBasic Object Reference
 APIs

API faSetRelation
This API relates the focus object record to a target record using the specified flexible
relation.

Declaration Function faSetRelation (recFocus As Record, zName As String, recTarget As Record,

vObjid As Variant) As Integer

Parameters

Parameter Direction Description

recFocus In The focus object instance owning the specified attribute.
zName In The specified attribute name.
recTarget In The target record of the relation.
vObjid In This is an optional parameter:
• If missing, then faGetAllAttributes is called to validate the
name of the attribute.
• If set and numeric, then it contains the objid of the attribute
value to update.
• If set and non-numeric, then it contains the name of the target
field for an attribute value to insert.

Return Values

Return Value Description

faOK OK
faNotDefined The specified attribute name is not defined for this focus object instance.
faInvalidValue The passed record is invalid for the target object type.
faDBError This is a database error that occurred during the save operation.

faSetRelation 467
ClearBasic Object Reference
 APIs

faSetRelation The faSetRelation API is called to set the relation between the focus object instance
Example (case ID number 1) and the target object instance (case ID number 2). This relation is
stored in the attribute named “primary”.

Declare Function faSetRelation (arecFocus As Record,

astrName As_
String, arecTarget As Record, Optional avObjid As Variant)
As Integer

Dim intRetCodeAs Integer

Dim brCase As New BulkRetrieve
Dim lstCaseAs List
Dim recFocusAs New Record
Dim recTargetAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recFocus = lstCase.ItemByIndex(0)

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘2’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recTarget = lstCase.ItemByIndex(0)

intRetCode = faSetRelation(recFocus, "relation", recTarget)

468 faSetRelation
ClearBasic Object Reference
 APIs

API faGetPossibleAttributes
The subroutine faGetPossibleAttributes returns a list of all valid N_Attribute records
which are possible for the focus object type. Possible attributes are found in two ways:
■ The product path in the N_AttributeDefinition table is used to find any
properties which have been defined using the configurator.
■ The tables N_AttributeDefinition and N_Templates are read to determine
which of the attributes in the N_Attribute table are possible for the focus object
type.

Declaration Sub faGetPossibleAttributes (varObjType As Variant, 1stAttribute As List)

Parameters

Parameter Direction Description

varObjType As Variant In The type_id or type_name of the focus object
1stAttribute Out List of N_Attribute records

faGetPossibleAttrib The faGetPossibleAttribute API is used to return a list containing all possible
utes Example attributes for the contr_itm object.

Declare Sub faGetPossibleAttributes( avarObjType As

Variant,_
alstAttribute As List )

Dim lstAttrAs List

faGetPossibleAttributes "contr_itm", lstAttr

faGetPossibleAttributes 469
ClearBasic Object Reference
 APIs

API faDeleteAttributes
The faDeleteAttributes function deletes all attribute values which have been set for
the given focus object instance.

Declaration Function faDeleteAttributes (recFocus As Record, Optional avCheck As Variant) As

Integer

Parameters

Parameter Direction Description

recFocus In Focus object instance owning the attributes
avCheck In Optional parameter:
• If missing or set to True then verify that the focus object
instance does not exist in the database prior to deleting the
attribute values.
• Otherwise, delete attribute values without checking for the
existence of the focus object instance.

Return Values

Return Value Description

faOK Attribute values deleted successfully
faError Unable to delete attributes, recFocus exists
faDBError Database error occurred during the save operation.

470 faDeleteAttributes
ClearBasic Object Reference
 APIs

faDeleteAttributes The faDeleteAttributes API is called to remove all attribute values which have been
Example assigned for case ID number 1.

Declare Function faDeleteAttributes ( arecFocus As Record,

Optional_
avCheck As Variant ) As Integer

Dim intRetCodeAs Integer

Dim recCase As New Record
Dim brCase As New BulkRetrieve
Dim bsCaseAs New BulkSave
Dim lstCaseAs List
Dim recCaseAs New Record

brCase.Clear
brCase.SimpleQuery 0, "case"
brCase.AppendFilter 0, "id_number", cbEqual, ‘1’
brCase.RetrieveRecords
Set lstCase = brCase.GetRecordList(0)
Set recCase = lstCase.ItemByIndex(0)

bsCase.deleteRecordByID "case", recCase.GetField(“objid”)

bsCase.Save

intRetCode = faDeleteAttributes( recCase )

faDeleteAttributes 471
ClearBasic Object Reference
 APIs

Flexible Attribute Constants

Table 6 lists the constants that have been defined for Flexible Attributes
.

Table 6

Name Value Comments

faNotSet -1 The value is not set
faOK 0 Module completed
successfully
faNotDefined 1 Attribute not defined
faInvalidValue 2 Invalid value for attribute
faDBError 3 Database error occurred
during Save
faError 1 One attribute in list failed
faRelation 0 Relation attribute
faLong 3 Long attribute
faFloat 4 Float attribute
faDecimal 6 Decimal attribute
faDatetime 7 DateTime attribute
faString 8 String attribute
faBoolean 11 Boolean attribute
faDateOnly 17 DateOnly attribute

472 Flexible Attribute Constants

ClearBasic Object Reference
 APIs

Related Tables
There are six tables related to these APIs.
■ N_Templates
■ N_Properties
■ N_AttributeDefinition
■ N_AttributeCondition
■ N_Attribute
■ N_AttributeValue

Related Tables 473

ClearBasic Object Reference
 APIs

474 Related Tables

ClearBasic Object Reference
Appendix C
Creating Java and EJB
Objects Using
ClearBasic APIs

In This Appendix
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Global Basic Methods . . . . . . . . . . . . . . . . . . . . . . . 476
Basic Object Type and JavaObject . . . . . . . . . . . . . 488
Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 501
Single Signon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Java Exception to ClearBasic Error Mapping . . . . . 505
Java Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Configuration Settings in the clarify.env File . . . . . . 508
Extending the EJB host Type. . . . . . . . . . . . . . . . . . 509

ClearBasic Object Reference 475

 Creating Java and EJB Objects Using ClearBasic APIs

Overview
This guide describes how to create Java and EJB (Enterprise Java Beans) objects and to
call methods on these objects using the ClearBasic interface. This feature can be used
by all ClarifyCRM application customers.

This guide also contains information on agent Single Signon and Billing System
Launching. This function allows users to launch a connection to a billing system using
the ClarifyCRM application interface. It also allows a single login feature so that users
can log in to both systems at the same time.

Global Basic Methods

You can call these global methods from any location using Basic script. All of these
methods can set the Basic Script Error object. These methods are implemented in the
Summit Extension module.

476 Overview
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method ConnectEjbServerImpl

Syntax Function ConnectEjbServerImpl ( [HostUrl as String],

[ UserName as String
],
[ Password as String
],
[ Domain as String ],
[ HostType as String ] ) as
String

Table 1 describes the ConnectEjbServerImpl parameters.

Table 1 ConnectEjbServerImpl Parameters

Parameter Name Description

HostUrl The Host Server URL. The URL includes the protocol. For example: t3:/
/www.amdocs.com. If this parameter is not specified, the setting in the
clarify.env file is used (Ejb_HostUrl). If the Ejb_HostUrl parameter
is not specified in the clarify.env file, the program returns an error
message.
UserName The user name for authentication. If the Ejb_UserName parameter in
the clarify.env file contains a value, that setting overrides the
UserName value, and the system uses a global proxy used for all
authentication.
Password The password for authentication. If the Ejb_Password setting in the
clarify.env file contains a value, that setting overrides this value,
and the system uses a global proxy used for all authentication.
Domain This domain is used when the host requires a domain value. If no value
is given (or set), the Ejb_Domain setting in the clarify.env file is
used.
HostType This value specifies the type of the EJB host. This value is case sensitive.
It is a combination of the EJB container and EJB application types. The
only host types supported is WlsGeneric. WlsAmdocs and WlsCSM are
reference implementations that must be customized for your system.
You must use the fully qualified path name of the host type, for example
com.cb2ejb.WlsCSM.
If this value is empty, the Ejb_HostType setting in the clarify.env
file is used.
If this value is empty and the Ejb_HostType setting in the
clarify.env file does not exist, the EJB connection may fail and EJB
access may not work correctly. You must provide a correct
Ejb_HostType either as a function parameter or as a clarify.env file
setting.
You can extend this functionality to include new host types.

Return Values This method returns a ConnectionId String. This string gives a unique identity for an
authenticated connection to the EJB server. It can be used across processes by the
Amdocs API. This string typically contains the remote server URL, the security
context, and other information.

ConnectEjbServerImpl 477
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Basic scripts must call this method before they create any EJB objects. This method
establishes a connection with a Web Logic EJB server and authenticates a user.

Usage Applications do not use this method directly. To connect to the server they use the
ConnectEjbServer() Basic script method substitutes the Password and
UserName value if required and calls the ConnectEjbServerImpl method.

478 ConnectEjbServerImpl
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method DisconnectEjbServer

Syntax Sub DisconnectEjbServer ( ConnectionId as String )

Description The ConnectionId is the string returned by the ConnectEjbServerImp method.

This method releases all resources held by the connection string. After this method is
called, the application must not use the ConnectionId.

DisconnectEjbServer 479
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method CreateJavaObject

Syntax Function CreateJavaObject (ClassName as String,

[ Param1 as Variant ],
[ Param2 as Variant ],
...
[ Param27 as Variant ] ) as JavaObject

Parameters Table 2 describes the CreateJavaObject parameters.

Table 2 CreateJavaObject Parameters

Name Description
ClassName The fully qualified class name. If this is an empty string, a null Java object is
created. If this is not an empty string, this class must exist in the Java class
path.
Param1 to These are optional parameters that must match an existing constructor. If no
Param27 parameters are passed, the default constructor is invoked.

Description This method creates a Java Object instance from the ClassName. It creates a local Java
Object and returns it as a Basic Object with the type set to JavaObject. The
JavaObject type is a Basic application object that is implemented in the Extension
library.
You must call Set <Variable>=<Object Ref>. This method calls a constructor
with matching parameters. To create a null Java object pass this method an empty
ClassName string.

480 CreateJavaObject
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method CreateEjbObject

Syntax function CreateEjbObject ( ConnectionId as String,

EjbJndiName as String,
HomeInterfaceClassName as String,
ProxyClassName as String ) as JavaObject

Parameters Table 3 describes the CreateEjbObject parameters.

Table 3 CreateEjbObject Parameters

Name Description
ConnectionId This parameter is the string returned by the ConnectEjbServerImpl
method.
EjbJndiName This parameter is the JNDI name for the EJB class.
HomeInterfaceCl The fully qualified class name for the Home class interface
assName
ProxyClassName The fully qualified class name for the local client proxy

Description This method creates an EJB object and returns the Proxy instance as a JavaObject. The
JavaObject is a Basic application object that is implemented in the Extension DLL
library. It has life-time semantics similar to ActiveX objects. You must call Set
<variable> = <Object Ref>.

Example The ClearBasic implementation of this function can look like the following:
gCmBean = “amdocsBeans.”
gCmHomePath = “amdocs.csm3g.sessions.interfaces.home.”
gCmApiPath = “amdocs.csm3g.sessions.interfaces.api.”
set CreateCustomer = CreateEjbObject
(gBillingConnId,gCmBean+”NewCustomerConvHome”,gCmHomePat
h+”NewCustomerConvHome”,gCmApiPath+”NewCustomerConv”)

CreateEjbObject 481
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method CallStaticJavaFunction

Syntax Function CallStaticJavaFunction ( ClassName as String,

MethodName as String,
[Param1 as Variant ]
[Param2 as Variant ],
...
[ Param26 as Variant ],
) as Variant

Parameters Table 4 describes the CallStaticJavaFunction parameters.

Table 4 CallStaticJavaFunction Parameters

Name Description
ClassName The fully qualified class name. This class must exist in the Java class path.
MethodName The name of the method. This parameter is case sensitive.
Param1 to These are optional parameters. The parameters you use must match the
Param26 parameters of the Java method.

Description This method calls a static Java method and returns the value as a Variant type. If the
return value of the Java method’s is Void, this method returns an empty Variant
value.

The parameters are matched with the Java parameter data types. For more
information see, Data Type Mapping on page 501

482 CallStaticJavaFunction
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method GetStaticJavaField

Syntax Function GetStaticJavaField (ClassName as String,

FieldName as String ) as Variant

Parameters Table 5 describes the GetStaticJavaField parameters.

Table 5 GetStaticJavaField Parameters

Name Description
ClassName The fully qualified class name. This class must exist in the Java class path.
FieldName The field name. This parameter is case sensitive.

Description This function accesses a static field member from a Java class. For example, to write to
the output stream you must access the System.out object. The returned Java type is
converted to a Basic type. If the Java method returns a JavaObject this function returns
a Basic JavaObject type. For more information see Data Type Mapping on page 501.

GetStaticJavaField 483
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method GetObjectStaticJavaField

Syntax Function GetObjectStaticJavaField ( ClassName as String,

FieldName as String ) as Variant

Parameters Table 6 describes the GetObjectStaticJavaField parameters.

Table 6 GetObjectStaticJavaField Parameters

Name Description
ClassName The fully qualified class name. This class must exist in the Java class path.
FieldName The name of the field from which you want to retrieve a value. This
parameter is case sensitive.

Description This method retrieves a field value from a static class and returns it as a JavaObject. If
the field represents a Java primitive type this method converts it to the corresponding
JavaObject. The type Int is converted to the java.lang.Integer type.

484 GetObjectStaticJavaField
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method CreateJavaArray

Syntax Function CreateJavaArray ( CbArray as Array,

[CoercionType as String ] ) as JavaObject

Parameters Table 7 describes the CreateJavaArray Parameters.

Table 7 CreateJavaArray Parameters

Name Description
CbArray This is a ClearBasic array. The array must be of Basic primitive type.
CoercionType Some Basic data types can be coerced into Java types. For more information
see Data Type Mapping on page 501

Description This method creates a new Java Array object from a ClearBasic array. It copies the data
from the ClearBasic array to the Java array and returns a JavaObject. Java array
indexes always start at 0 and the ClearBasic lower bound value is mapped to Index 0.

If the ClearBasic array is a multi-dimensional array, this method converts it to a single

dimension Java array.

For example the following Basic array:

dim a(2,3) ‘Basic array

is converted to the following Java array:

a(0,0) Low address (0 index)
a(0,1)
a(0,2)
a(0,3)
a(1,0)
a(1,1)
a(1,2)
a(1,3)
a(2,0)
a(2,1)
a(2,2)
a(2,3) High address (size-1 index)

In some cases you can use the CoercionType string parameter to coerce the Basic data
type to a specific Java type. This action allows you to call Java methods that take
byte[] or char[] parameters from ClearBasic. The CoercionType string parameter is not
case sensitive. This function supports only Basic primitive types. If you need to create
a JavaObject array, use the CreateJavaObjectArray function. For more information see
Data Type Mapping on page 501

Table 8 describes the legal values for coercing Basic data types to Java types.
Table 8 Legal Values for Coercing Basic Data Types to Java Types

Basic Array Element Type Java Array Element Type Coercion Type
Integer short
Integer byte Byte

CreateJavaArray 485
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Table 8 Legal Values for Coercing Basic Data Types to Java Types (Continued)

Basic Array Element Type Java Array Element Type Coercion Type
Integer char Char
Long int
Long Long Long
String java.lang.String
Single Long Long
Single float
Double Long Long
Double double
Date java.util.Date
Boolean boolean
Currency <not supported>

486 CreateJavaArray
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

method CreateJavaObjectArray

Syntax Function CreateJavaObjectArray ( CbArray as Array ) as

JavaObject

Parameters Table 9 describes the CreateJavaObject Array parameters.

Table 9 CreateJavaObjectArray Parameters

Name Description
CbArray This is a ClearBasic array. The array elements must be of JavaObject type.

This method creates a new Java array object from the ClearBasic array. It creates a Java
array of Java Objects. It returns a JavaObject. Java array indexes always start from 0
and the ClearBasic Lower Bound value is mapped to Index 0.

If the ClearBasic array is a multi-dimensional array, this method converts it to a single

dimension Java array.

For example the following Basic array:

dim a(2,3) ‘Basic array

is converted to the following Java array:

a(0,0) Low address (0 index)
a(0,1)
a(0,2)
a(0,3)
a(1,0)
a(1,1)
a(1,2)
a(1,3)
a(2,0)
a(2,1)
a(2,2)
a(2,3) High address (size-1 index)

CreateJavaObjectArray 487
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Basic Object Type and JavaObject

The JavaObject represents a local Java object in Java Virtual Machine (JVM). It has the
same life-time semantics as an ActiveX object. The JavaObject represents all Java
Objects, including Java arrays and Java null objects.

488 Basic Object Type and JavaObject

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::IsArray

Syntax Function IsArray () as Boolean

Description This function returns a True value if the JavaObject references a Java array.

JavaObject::IsArray 489
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::GetAt

Syntax Function GetAt ( index as Long ) as Variant

Description The index parameter specifies a location in a 0-based index for a Java array. This
function returns the array element at the specifed index location. If the source
JavaObject does not reference a Java array, an error occurs. The JavaObject is
converted to a Basic type. For more information see Data Type Mapping on page 501.

490 JavaObject::GetAt
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::GetAtObject

Syntax Function GetAtObject ( index as Long ) as JavaObject

Description The index parameter specifies a location in a 0-based index for a Java array. This
function returns the array element at the specifed index location. If the source
JavaObject does not reference a Java array, an error occurs.

The array element is always converted to a JavaObject. If the array element is a

primitive type, it is converted to the corresponding Java object.

JavaObject::GetAtObject 491
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::Size

Syntax Function Size () as Long

Description This method returns the size of a Java array. An error occurs if the JavaObject does not
reference a Java array.

492 JavaObject::Size
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::ClassName

Syntax Function ClassName () as String

Description This function returns the fully qualified Java class name of the Java Object.

JavaObject::ClassName 493
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::IsNull

Syntax Function IsNull () as Boolean

Description This function returns a True value if the Java Object is null.

494 JavaObject::IsNull
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::SetNull

Syntax Sub SetNull()

Description If the object references a null object, <null> is returned.

JavaObject::SetNull 495
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::Call

Syntax Function Call ( MethodName as String,

[ Param1 as Variant ],
[ Param2 as Variant ],
...
[ Param27 as Variant ],
) as Variant
Sub Call ( Method Name as String,
[Param1 as Variant ],
[Param2 as Variant ],
...
[Param27 as Variant ],
)

Parameters Table 10 describes the JavaObjectCall:: parameters.

Table 10 JavaObjectCall:: Parameters

Name Description
MethodName The name of the method you want to call.
Param1 to These are optional parameters. The parameters you use must match the
Param27 parameters of the Java method. You cannot use a ClearBasic array as a
parameter. If you need to use the values in a ClearBasic array as parameters,
you must convert the array to a Java array. Use the CreateJavaArray() global
function and the JavaObject as a parameter to carry out the conversion.

Description This function calls a Java method on a Java object instance and returns the value. If the
Java method returns a Void value, this method returns an empty Variant value. Basic
parameter types are converted to Java types. Returned Java types are converted to
Basic type. If the Java method returns a Java Object, this function returns a Basic
JavaObject type. For more information on Basic to Java type mapping see Data Type
Mapping on page 501.

496 JavaObject::Call
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::CallObject

Syntax Function CallObject ( MathodName as String,

[ Param1 as Variant ],
[ Param2 as Variant ],
...
[Param27 as Variant ],
) as Variant

Parameters Table 11 describes the JavaObject::CallObject parameters.

Table 11 JavaObject::CallObject Parameters

Name Description
MethodName The method name. This parameter is case sensitive.
Param1 to These are optional parameters. The parameters you use must match the
Param27 parameters of the Java method. You cannot use a ClearBasic array as a
parameter. If you need to use the values in a ClearBasic array as parameters,
you must convert the array to a Java array. Use the CreateJavaArray() global
function and the JavaObject as a parameter to carry out the conversion.

Description This function calls a Java method on a Java object instance and returns the value as a
JavaObject. Java primitive types are converted to their corresponding Java Objects (for
example, int is converted to java.lang.Integer). This allows programs to access
string types as java.lang.String objects and to access each character code using
the charAt() method.

JavaObject::CallObject 497
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::Get

Syntax Function Get ( FieldName as String ) as Variant

Parameters Table 12 describes the JavaObject::Get parameters.

Table 12 JavaObject::Get Parameters

Name Description
FieldName This is the name of the field you want to access. This is a case sensitive
parameter.

This function returns a field value. The returned Java type is converted to a Basic type.
If the Java method returns a Java Object, the Basic JavaObject type is returned. For
more information on type mapping between Basic and Java types, see Data Type
Mapping on page 501.

498 JavaObject::Get
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::GetObject

Syntax Function GetObject ( FieldName as String ) as JavaObject

Parameters Table 13 describes the JavaObject::GetObject parameters.

Table 13 JavaObject::GetObject Parameters

Name Description
FieldName This is the name of the field you want to access. This is a case sensitive
parameter.

Description This function returns a field value as a JavaObject. If the field represents a Java
primitive type, it is converted to the corresponding JavaObject. For example, int is
converted to java.lang.Integer.

JavaObject::GetObject 499
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

JavaObject JavaObject::Set

Syntax Sub Set ( FieldName as String, value as Variant )

Parameters Table 14 describes the JavaObject::Set parameters.

Table 14 JavaObject::Set Parameters

Name Description
FieldName The name of the field you want to access. This parameter is case sensitive.
value The value you want to set in the field.

Description This function sets a field value. Any basic type is converted to a Java type. For more
information on type mapping between Basic and Java types, see Data Type Mapping on
page 501.

500 JavaObject::Set
ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Data Type Mapping

If the Basic type is Variant, Variant type is used to map to a Java type. Table 15
describes the mapping from Basic types to Java types.
Table 15 Basic type to Java type mappings

Basic Type Java Type Also compatible with Java

types
Integer short int, byte, char, long, float, double
Long int long, float, double
String java.lang.String
Single float long, double
Double double long, float
JavaObject Object, Array
Date java.util.Date
Boolean boolean
Currency This conversion is not directly supported.
You can convert to a double type and use
that value if accuracy is not important.
Array This conversion is not directly supported.
You must convert the array to a JavaObject
using the CreateJavaArray() function.

Table 16 describes the mapping from Java types to Basic types.

Table 16 Java type to Basic type mappings

Java type Basic type

int Long
short Integer
char Integer (16 bit unicode value)
byte Integer
float Single
double Double
long Double (some loss can occur)
boolean Boolean
java.lang.String String
java.util.Date Date
Object (Except String and Date) JavaObject

Data Type Mapping 501

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Single Signon
The Single Signon feature utilizes user login information that is given as part of the
classic client authentication process to connect to the EJB server. The ClearBasic
engine has been enhanced to support the ConnectEjbServerImpl() method. If
you do not specify all the parameters required by this method, then the method uses
the settings in the clarify.env file. You must implement a ClearBasic wrapper routine
to call the ConnectEjbServerImpl() function. This routine can access user details
including the AltUserName value that is exposed by the App object. The
AltUserName corresponds to the SUM authentication name.

The following is a recommended function for implementing the ClearBasic wrapper

routine:
Function ConnectEjbServer ( [HostUrl as String ],
[ UserName as String ],
[ Password as String ],
[ Domain as String ],
[ HostType as String ],
[ RemoteCB as Boolean ] ) as String

Parameters Table 17 describes the ConnectEjbServer function parameters.

Table 17 ConnectEjbServer function parameters

Name Description
HostUrl The Host Server URL. The URL includes the protocol, for example: t3://
www.amdocs.com. If this parameter is empty, the function uses the default
value in the clarify.env file
UserName The user name for authentication.
If the UserName parameter contains a value, this value is used for
authentication.
If the UserName parameter is empty, the user name value from the
ClarifyCRM login process is used for authentication.
The Basic App object exposes two properties, UserName and AltUserName.
User_Name corresponds to the login_name field in the table_user table.
AltUserName corresponds to the alt_user_name field in the table_user
table.
If the AltUserName property contains information, the AltUserName value
is used for authentication.
If the AltUserName property is empty, the UserName value is used for
authentication.
If the Ejb_UserName parameter in the clarify.env file is not empty, that
setting overrides both values, and the Ejb_UserName value is used for
authentication.
Password The password for authentication.
If the Password parameter is not empty, this value is used for
authentication.
If the Password parameter is empty, the password value from the
ClarifyCRM login process is used for authentication.
If the Ejb_Password setting in the clarify.env file is not empty, that
setting overrides both values, and the system use the Ejb_Password for
authentication.
Domain This is used when the host requires a domain value. If this value is empty,
the Ejb_Domain setting in the clarify.env file is used.

502 Single Signon

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Table 17 ConnectEjbServer function parameters (Continued)

Name Description
HostType This value specifies the EJB host type. This value is case sensitive. It is a
combination of the EJB container and EJB application types. The currently
supported host types are:
• com.clarify.cb2ejb.WlsAmdocs
• com.clarify.cb2ejb.WlsGeneric
You must use the fully qualified path name of the host type, for example
com.Cb2ejb.WlsCSM
If this value is empty, the Ejb_HostType setting in the clarify.env file is
used.
If this value is empty and the Ejb_HostType setting in the clarify.env
file does not exist, the default value is WlsAmdocs.
You can extend this functionality to include new host types.
RemoteCB If this parameter is set to True, the connection to the EJB server is
established from a FD server machine by calling the
ConnectEjbServerImpl() method remotely. The default value for the
RemoteCB parameter is False.

Return Values This method returns a ConnectionId String. This string uniquely identifies an
authenticated connection to the EJB server and can be used across processes by the
Amdocs API. This string typically contains the remote server URL, the security
context, and other information.
Basic scripts must call this method before they create any EJB objects. This method
establishes a connection with a Web Logic EJB server and authenticates a user.

Implementation You can implement this method as a ClearBasic function. This method calls the
ConnectEjbServerImpl() method which establishes an EJB connection. The purpose of
this wrapper function is to hide the logic for extracting the user name and password
values from the client login process.

Sample Function ConnectEjbServer (HostUrl as String, UserName as

Implementation String, Password as String, Domain as String, HostType as
String, RemoteCB as Boolean ) as String
Dim RemoteCBTmp as String
Dim ConnId as String
If UserName=”” Then
UserName=app.AltUserName
If UserName=”” Then
UserName=app.UserName
End If
If Password = ““ Then Password = App.Passwd
If RemoteCB = TRUE Then
Dim tmpRtnStatus as Integer
Dim strCID as String
tmpRtnStatus = App.CallCB (“strCID=ConnectEjbServerImpl
(HostUrl,UserName,Password,Domain,HostType)”)
ConnectEjbServer=strCID

Single Signon 503

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Else
ConnectEjbServer=ConnectEjbServerImpl
(HostUrl,UserName,Password,Doamin,HostType)
End If
End Function

504 Single Signon

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Java Exception to ClearBasic Error Mapping

When Basic Script calls a method, an error can occur in the Extension library of the
Java subsystem. The Java subsystem captures Java local exceptions. The Extension
library converts the exceptions into Basic errors. If the Java Native invocation API fails
or a data type conversion fails, the Extension library generates an error.

The Extension DLL uses Basic Error codes in the range 14000 to 14099 to report all
errors.

Properties Table 7 describes the Basic Err object properties.

Table 7 Basic Err object properties

Property Value
Err.Description Error description
Err.HelpContext 0
Err.HelpFile ““
Err.LastDLLError 0
Err.Number An error number in the range 14000 to 14099
Err.Source For a Java exception this is the class name of the
exception. For other errors this is the Extension library
method name that causes the error.

Java Exception to ClearBasic Error Mapping 505

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Java Output
The Java System Object has an out device to which messages are sent. Java code uses
the System.out device to print alert messages. When you launch the Java Virtual
Machine (JVM) it creates a log file called JavaOutput.log, it assigns this file to the
System.out and System.err devices. Any text that is sent to the output device is
written to this file. It creates the file in the current working directory. If the file
creation process fails, no errors are reported and all output is lost.

The clarify.env file contains a Java_Trace setting. To activate tracing, set this value
to Y. To disable tracing, set this value to ‘N’. If this value is set to ‘Y’, all calls to the
Java subsystem are sent to the JavaOutput.log file.

The output from the trace process lists all JVM arguments that the Extension library
passes to the JVM and records each call made to the Java subsystem. The trace listing
specifies the type of operation performed and the parameters used. If the parameter is
null, string null is written. If the parameter is a primitive type, a Date or a String,
the value of the parameter is written. For all other parameter type the class name is
written.

If an operation causes a Java exception, the error details are written to the
JavaOuput.log file. If any Java code writes data to the System.out device, it is written
into the JavaOuput.log file. Each operation written to the JavaOutput.log file is
separated by a short dashed line.

506 Java Output

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

String Handling
ClearBasic strings use a multibyte value to represent a character. Each character in a
ClearBasic string has a value between 0 and 255. Java uses a 16bit Unicode value to
represent a character.

When Java returns a string value, the default code page of the operating system is
used to convert the string from a Unicode to a multibyte value. This multibyte string
is passed to ClearBasic.

When a ClearBasic string is passed as a parameter to a Java method, the operating

system default code page is used to convert it from a multibyte characters to Unicode.
The Unicode string is passed to Java.
If Java encodes a value using a character set that is not part of the default code page of
the FD server or the classic client, some characters are lost when the string is
converted to a ClearBasic string. To avoid this, you can use the CallObject(),
GetAtObject(), or GetObject() methods. These methods return the Java string as a Java
String Object. The ClearBasic program can access each character using the charAt()
method. This character is returned as a Basic Integer type and contains the Unicode
code value.

String Handling 507

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Configuration Settings in the clarify.env File

Table 1 describes the configuration keys used by the Extension library
Table 1 Extension library clarify.env settings

Name Description
Java_ClassPath The JVM uses this value to locate all proxy classes and local classes. If you
do not specify this value, the system uses the current working directory as
the classpath value.
Java_LibPath The JVM library path. The JVM uses this value to load modules. This is
normally empty.
Java_Args These are additional arguments for the JVM. They are specific to the JVM
and depend on the JVM platform. For example, they can specify the stack
size and the type of compiler.
Java_Trace To activate tracing, set this value to Y. To disable tracing, set this value to N.
If this value is set to Y, all calls to the Java subsystem are sent to the
JavaOutput.log file.
Ejb_HostType The EJB server type. This value is case sensitive. The supported host types is
com.clarify.cb2ejb.WlsCSM.
Ejb_HostUrl The URL to the EJB server. This URL includes the protocol, for example: t3:/
/www.clarify.com.
Ejb_Domain The EJB server uses this value to locate authentication information. Typical
values for this variable are either SUM or LDAP.
Ejb_UserName The global user name. This value is used for authentication.
Ejb_Password The global password value. This value is used for authentication.

508 Configuration Settings in the clarify.env File

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

Extending the EJB host Type

You can implement new EJB Host types to support options other than the WlsCSM
type. To add a new EJB Host type:

1. Choose a Host type name which is a fully qualified Java class name. You will be
implementing this class.

2. Implement a Java class using the Host Type Name. This class must be a
subclass of the com.clarify.cb3ejb.EjbAccessor class.

3. Implement the three abstract methods (connect(), disconnect(), and

createEjbObject()).

4. The system ignores all constructors except the class default constructor.

5. The system creates only one instance of this class. All methods must be
multithread safe and possibly stateless.

6. The EjbAccessor class contains a helper implementation that creates an

EjbObject from the javax.naming.Context object.

com.clarify.cb2ejb.E To implement a new EJB HostType, create a subclass of the

jbAccessor Class com.clarify.cb2ejb.EjbAccessor abstract class. This class has no constructor and has
three abstract methods:
■ connect on page 509
■ disconnect on page 510
■ createEjbObject on page 510

connect

This method returns a string value representing a connection.

public abstract String connect (String strHostUrl, String
strUsr, String stPwd, String strDomain)

Table 2 describes the connect method parameters.

Table 2 Connect method parameters

Name Description
strHostUrl The URL of the Host server. The URL includes the protocol and port, for
example: t3://www.clarify.com:7020
strUsr The user name. This value is used for authentication.
strPwd The password. This value is used for authentication.
strDomain Use this string if the Host requires an additional Domain value.

Extending the EJB host Type 509

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

disconnect

This method closes the connection and releases all resources used by the connection.
public abstract void disconnect (String strHostUrl, String
strConnection)

Table 3 describes the disconnect method parameters

Table 3 Disconnect method parameters

Name Description
strHostUrl The URL you used to create the connection with the connect() method.
strConnectio The string value returned by the connect() method.
n

createEjbObject

This method creates an EjbObject instance on the server and returns the proxy client
class instance as an object.
public abstract Object createEjbObject (String strHostUrl,
String strConnection, String JndiHomeName, String
proxyHomeClassName, String proxyClassName)

Table 4 describes the createEjbObject method parameters.

Table 4 createEjbObject method parameters

Name Description
strhostUrl The URL you used to create the connection with the connect() method.
strConnection The string value returned by the connect() method.
JndiHomeName The Jndi name for this object.
proxyHomeClas The fully qualified class name for the Home class interface.
sName
proxyClassNam The fully qualified proxy class name.
e

510 Extending the EJB host Type

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

WlsCSM class This section describes the WlsCSM class implementation. Use this as a reference when
implementation you extend the host type.
//-----------------------------------------------------
// WlsCSM class implementation.
//----------------------------------------------------
package com.clarify.cb2ejb;
import javax.naming.*;
import java.util.*;
public class WlsCSM extends EjbAccessor {
// Connect to EJB server and return the aunthetication
// ticket. If Domain is empty, use SUM as default domain
public String connect( String strHostUrl, String strUsr,
String strPwd, String strDomain) {
// No authentication done. Just return some dummy string.
// Customer may need to implement this
String strTicket = new String("test");
return strTicket;
}
// Disconnect from EJB Server
// strConn is the authentication ticket returned by
// connect() method
// strHostUrl is the URL used in connect() method
public void disconnect(String strHostUrl, String strConn) {
// Customer may need to implement this.
}

// Create Ejb OBject identified by JndiHomeName.

// The client side proxy object must be of type
// proxyClassName
// strConn is the authentication ticket returned by
// connect() method

Extending the EJB host Type 511

ClearBasic Object Reference
 Creating Java and EJB Objects Using ClearBasic APIs

// strHostUrl is the URL used in connect() method

// Retrieve Context from ticket
// Use the helper method in EjbAccessor to create the EJB
// Object
public Object createEjbObject( String strHostUrl,
String strConn,
String JndiHomeName,
String proxyHomeClassName,
String proxyClassName )
{
Context initialContext = null;
Properties h = new Properties();
// Initilization of Home Interfaces of CSM beans with
// received ticket
h.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
h.put(Context.PROVIDER_URL, strHostUrl);
try
{
initialContext = new InitialContext(h);
}
catch (javax.naming.NamingException e)
{
throw new RuntimeException("Error in createEjbObject:
NamingException " + e.getMessage());
}
catch (Exception e)
{
throw new RuntimeException("Error in createEjbObject:
Exception " + e.getMessage());
}
return createEjbObject( initialContext, JndiHomeName,
proxyHomeClassName, proxyClassName );
}
}

512 Extending the EJB host Type

ClearBasic Object Reference
Index
Numerics DatabaseName property 76
2-tier programming 19 DoDefault method 28
EmployeeObjId property 77
A ExecuteCB method 29
Action property 167 ExecuteMenu method 30
Activate event 310 EXEName property 78
ActivateEvents Method 214 ExitApp method 31
active control 293 GenerateID method 32
ActiveControl property 293 GetContext method 33
AddItem method 87 GetCurrentDB method 35
AddNewEvents Method 215 GetFormInstance method 37
AddSeparator method 89 GetString method 38
AllowDuplicates property 351 GetUserPopupListLevel1 method 40
AllSpaces method 422 GetUserPopupListLevel2 method 41
API InputBox method 42
faDeleteAttributes, values 470 LogSQL method 43
faEditAttributes MsgBox method 44
Edit Flexible Attribute form 455 QuerySize property 79
values 455 ServerName property 81
faGetAllAttributes, values 464
SetColorScheme method 46
faGetAttribute, values 457
ShowAttachments method 48
faGetAttributeList, values 460
ShowCase method 50
faGetPossibleAttributes, values 469
ShowContact method 52
faGetRelation, values 466
ShowContract method 54
faSetAttribute, values 458
ShowCR method 56
faSetAttributeList, values 462
ShowDefaultMenu method 58
faSetRelation, values 467
ShowEmployee method 59
APIs
ShowFTS method 61
Application Programming Interfaces 454
ShowSelect method 62
Flexible Attributes constants 472
ShowSite method 65
related tables 473
ShowSubcase method 67
App object
TransferPart method 69
described 15–18
UseClarifyDB method 71
CallCB method 19
UseDefaultDB method 73
CLTransition method 22
UserName property 82
ConvertCurrencyValue method 23
UserObjId property 83
CreateColorScheme method 25
ValidateUser method 74
CurrentDate property 75

ClearBasic Object Reference 513

 AppendContextMenu method 224 AppendFilter method 103
AppendFilter method 103, 356 AppendSort method 105
AppendItem method 186, 331 Clear method 106
AppendSort method 105, 358 EntryCount method 107
Application Programming Interfaces, APIs 454 GetRecordList method 108
application, exiting 31 GetRelatedRecordList method 110
AppMenu object Print method 112
described 85–86 RetrieveRecords method 113
AddItem method 87 SetRoot method 115
AddSeparator method 89 SetRootById method 117
CheckItem method 91 SimpleQuery method 118
Enable method 92 TraverseFromParent method 120
IsEnabled method 93 TraverseFromRoot method 122
IsItemChecked method 94 BulkSave object
MenuBarId property 100 described 125–126
RemoveItem method 95 CancelRecord method 127
RenameItem method 96 ChangeRecord method 128
SetFunction method 97 CountByType method 130
Show method 99 DeleteRecord method 131
asynchronous mode 19 DeleteRecordByID method 133
Attachment window, displaying 48 GetRecordByIndex method 135
InsertRecord method 136
B Print method 138
BackColor property 193, 294 RelateRecords method 139
basic object and java object 488 RelateRecordsFromID method 141
JavaObject RelateRecordsFromToID method 143
Call 496 RelateRecordsToID method 144
description 496
Save method 145
CallObject 497
description 497 Save_Aborted property 149
UnrelateRecords method 146
ClassName 493
description 493 UpdateRecord method 147
Get 498
GetAt 490
C
description 490 Call method 424
GetAtObject 491 CallCB method 19
description 491 Cancel button, intercepting clicks 168
GetObject 499 CancelError property 168
description 499 CancelRecord method 127
IsArray 489 Caption property 194, 295
description 489 Case window, displaying 50
IsGetAt 490 cbByRef option 108, 128, 131
IsNull 494
description 494 cbByValue option 108, 128, 131
Set 500 cbCallAsync constant 424
description 500 cbCDDateTime constant 167
SetNull 495 cbCDElapsedTime constant 167
description 495 cbCDOpen constant 167
Size 492 cbCDPageSetup constant 167
description 492 cbCDSaveFile constant 167
bold font, See fonts cbCloseChildren constant 228
BulkRetrieve object cbCloseMessage constant 267
described 101–102 cbEqual constant 104

514 Index
ClearBasic Object Reference
cbErrIfNotUp 290 elapsed time 177
cbFrontIfUp constant 290 overview 165
cbGreater constant 104 setting default path and file names for 178
cbGreaterOrEqual constant 104 specifying the default directory 181
cbIn constant 104 specifying the title 176
cbLess constant 104 CommonDialog object
cbLessOrEqual constant 104 described 165–166
cbLike constant 104 Action property 167
cbNotEqual constant 104 CancelError property 168
cbNotLike constant 104 Copies property 170
cbRefreshMessage constant 267 DataChanged property 171
cbSoundsLike constant 104 DateTime property 173
ChangeRecord method 128 DefaultExt property 174
ChangeToNew method 398 DialogId property 175
CheckItem method 91 DialogTitle property 176
checkmarks 91 ElapsedSeconds property 177
CheckRequired method 225 FileName property 178
child forms, See forms FileTitle property 179
ClarifyCRM databases, See databases FromPage property 180
ClarifyDB object InitDir property 181
described 151–152 Tag property 182
Connected property 155 ToPage property 183
DatabaseName property 156 communicating with TUXEDO, See TUXEDO
Login method 153 Concat method 334
Logout method 154 configuration settings in the clarify.env file 508
ServerName property 157 Connect method 433
UserName property 158 Connected property 155, 442
Clear method 106, 160, 210, 333 constants, See global constants
ClearBasic, calling routines 19 Contact form, displaying 52
ClearContextMenu method 227 Contains method 336
clipboard Contents property 195
clearing 160 ContextMenu_Select event 312
getting text 162 ContextMenuDisplaying event 311
getting the format 161 contextual objects
maximum size 159 adding items 186
overview 159 applying color to controls 193, 198
setting text 163 getting data 189, 195, 199
Clipboard object loading data 188
described 159 overview 185
Clear method 160 refreshing data 191
GetFormat method 161 sorting 192
GetText method 162 working with UDTs 189
SetText method 163 ContextualObject object
Close method 228 described 185
CLTransition method 22 AppendItem method 186
code, debugging 209 BackColor property 193
color schemes Caption property 194
creating 25 Contents property 195
common dialogs DataChanged property 196
cancelling 168 DataType property 197
displaying 167 Empty method 187

Index 515
ClearBasic Object Reference
 Fill method 188 terminating a connection 435
ForeColor property 198 using SQL statements 436
GetContents method 189 DataChanged property 171, 196, 296
IsNew method 190 DataType property 197
List property 199 date, getting and setting 173
Name property 200 DateTime common dialog 165
Refresh method 191 DateTime property 173
Sort method 192 DblClick event 313
SubType property 201 DDE
continuation characters, specifying 376 executing commands 204
Continuation property 376 initializing a link 205
Contract window, displaying 54 sending messages 203
controls setting timeouts 208
disabling 231, 232 DDE object
displaying 291 described 203
enabling 235, 236 DDEExecute method 204
getting height of 388 DDEInitiate method 205
getting the name 254 DDERequest method 206
getting width of 394 DDETerminate method 207
hiding 291, 292 DDETimeout method 208
showing 292 DDEExecute method 204
ConvertCurrency method 229 DDEInitiate method 205
ConvertCurrencyValue method 23 DDERequest method 206
Copies property 170 DDETerminate method 207
Copy method 399 DDETimeout method 208
CopyFields method 400 Deactivate event 314
Count property 352 Debug object
CountByType method 130 described 209
CR window, displaying 56 Clear method 210
CreateColorScheme method 25 Print method 211
CreateView method 402 Show method 212
CTI application 203 Debug window
current clearing 210
print job page 389 printing to 211
CurrentDate property 75 showing 212
CurrentX property 378 debugging tools 209
CurrentY property 379 default behavior, calling 234
default file extension, setting 174
D DefaultExt property 174
data type mapping 501 DeleteRecord method 131
DatabaseName property 76, 156 DeleteRecordByID method 133
databases determining text height 374
ClarifyCRM database overview 151 DialogId property 175
connecting 153 DialogTitle property 176
disconnecting 154 directory, default 181
establishing a connection 433 DisableControls method 231
getting the current user 158 DisableControlsDeep method 232
getting the server name 157 Disconnect method 435
invoking stored procedures 438 DoDefault method 28, 234
logging in 153 Down method 337
logging out 154 DrawMode property 380

516 Index
ClearBasic Object Reference
DrawStyle property 381 turning on italic 386
DrawWidth property 382 FontBold property 383
FontFamily property 385
E FontItalic property 386
ElapsedSeconds property 177 fonts
ElapsedTime common dialog 165
Employee window, displaying 59 italic font 386
EmployeeObjId property 77 bold 383
Empty method 187 family information 385
Enable method 92 font family 385
EnableControls method 235 font size 387
EnableControlsDeep method 236 FontSize property 387
EndDoc method 370 ForceRedraw method 238
EntryCount method 107 ForeColor property 198
error codes, getting 256 Form object
EventLogger Object described 219–223
ActivateEvents Method 214 Activate event 310
AddNewEvent Method 215 ActiveControl property 293
SetBulk Method 218 AppendContextMenu method 224
SetLogData Method 216 BackColor property 294
UpdateAll Method 217 Caption property 295
EventLogger Object CheckRequired method 225
described 213 ClearContextMenu method 227
Execute method 436 Close method 228
ExecuteCB method 29 ContextMenu_Select event 312
ExecuteMenu method 30 ContextMenuDisplaying event 311
ExecuteProc method 438 ConvertCurrency method 229
EXEName property 78 DataChanged property 296
ExitApp method 31 DblClick event 313
extended contextual objects, See contextual objects Deactivate event 314
extending the EJB host type 509 DisableControls method 231
connect 509 DisableControlsDeep method 232
ExtractList method 339 DoDefault method 234
EnableControls method 235
F EnableControlsDeep method 236
fields, copying 400
ForceRedraw method 238
FileName property 178
Form_Load event 315
FileTitle property 179
Form_Save event 316
Fill method 188
Form_Unload event 320
filters
GetCBCObj method 239
adding 103
GetChildKeyList method 240
specifying operators 104
GetCObjFieldList method 241
FindFirstIndex method 341
GetCObjFieldStaticItem method 243
finishing a print job 370
GetCObjFieldStaticList method 245
Flexible Attributes
GetCObjList method 247
constants 472
GetCObjMethodKeyList method 248
focus, setting 284
GetCObjMethodList method 250
font
GetCObjPropertyKeyList method 252
available fonts 385
GetControlByName method 254
family, specifying 385
GetDisplayCurrency method 255
size 387
GetLastError method 256
turning on bold 383

Index 517
ClearBasic Object Reference
 GetMethodValue method 259 disabling controls 231, 232
GetPropertyValue method 261 displaying 289
GetUserData method 263 enabling controls 235, 236
Height property 297 getting control names 254
Hide method 264 getting dimensions 297, 301, 306
hWnd property 298 getting native handle 298
Id property 299 getting the ID 299
InheritCurrency method 265 getting the name 302
Key property 300 getting the parent 303
Left property 301 handling default behavior 234
MouseDown event 321 handling double-clicks 313
MouseUp event 322 handling mouse events 321
Move method 266 hiding controls 291, 292
Name property 302 identifying instances 300
Notify method 267 making read-only 304
NotifyById method 269 maximizing 309
NotifyByKey method 271 minimizing 309
NotifyChild method 273 moving 266
NotifyParent method 275 notifying a tab 277
NotifyTab method 277 notifying a tab parent 278
NotifyTabParent method 278 notifying child forms 273
ParentKey property 303 notifying parent forms 275
ReadOnly property 304 redrawing 238
Refresh method 279 resizing 323
Resize event 323 sending notifications 267, 269, 271
SetContextMenuEnabled method 280 setting a parent 285
SetContextMenuVisible method 281 setting the color 294
SetDisplayCurrency method 282 setting the focus 284
SetFocus method 284 showing controls 291, 292
SetParent method 285 FromPage property 180
SetTargetCurrency method 286 FTS window, displaying 61
SetUserData method 288
Show method 289
G
ShowControls method 291 GenerateID method 32
ShowControlsDeep method 292 GetCBCObj method 239
Tag property 305 GetChildKeyList method 240
Top property 306 GetCObjFieldList method 241
Visible property 307 GetCObjFieldStaticItem method 243
Width property 308 GetCObjFieldStaticList method 245
WindowState property 309 GetCObjList method 247
Form_Load event 315 GetCObjMethodKeyList method 248
Form_Save event 316 GetCObjMethodList method 250
Form_Unload event 320 GetCObjPropertyKeyList method 252
Format method 404 GetContents method 189
format modifiers 404 GetContext method 33
forms GetControlByName method 254
activating 310 GetCount method 360
adding user data 305 GetCurrentDB method 35
checking errors 256 GetDisplayCurrency method 255
closing 228 GetField method 407
deactivating 314 GetFormat method 161

518 Index
ClearBasic Object Reference
GetFormInstance method 37 I
GetItemByIndex method 343 Id property 299
GetLastError method 256 InheritCurrency method 265
GetMethodValue method 259 InitDir property 181
GetObject method 408 InputBox method 42
GetPropertyValue method 261 InsertRecord method 136
GetRecordByIndex method 135 IsDirty method 411
GetRecordList method 108 IsEnabled method 93
GetRelatedRecordList method 110 IsExactly method 413
GetString method 38 IsItemChecked method 94
GetText method 162 IsMaxDate method 414
GetTextField method 410 IsMinDate method 415
GetUserData method 263 IsNew method 190, 416
GetUserPopupListLevel1 method 40 isql, See SQL
GetUserPopupListLevel2 method 41 italic font, turning on 386
global basic methods 476 ItemByIndex method 344
CallStaticJavFfunction 482 ItemType property 353
description 482
ConnectEjbServerlmpl 477 J
return value 477 java exception to ClearBasic error mapping 505
usage 478
java output 506
CreateJavAarray 485
description 485 K
CreateJavaObject 480
Key property 300
description 480
CreateJavaObjectArray 487
L
CreatEjbObject
Left property 301
description 481
example 481 Line method 371
createjbobject 481 lines, printing 381
DisconnectEjbServer 479 List object
description 479 described 329–330
GetObjectStaticJavaField 484 AllowDuplicates property 351
description 484 AppendItem method 331
GetStaticJavaField 483
Clear method 333
description 483
Concat method 334
Global constants
Contains method 336
described 325–326
Count property 352
global constants
Down method 337
setting 327
ExtractList method 339
using 325
FindFirstIndex method 341
GlobalDouble type 325
GetItemByIndex method 343
GlobalInteger type 325
ItemByIndex method 344
GlobalLong type 325
ItemType property 353
GlobalSingle type 325
ListByIndex method 346
GlobalString type 325
RemoveByIndex method 347
H ReplaceByIndex method 348
Height property 297, 388 Sort method 349
height, getting for form, control, printer 388 Sorted property 354
Hide method 264 Up method 350
hWnd property 298 List property 199
ListByIndex method 346
lists

Index 519
ClearBasic Object Reference
 adding items 331 sending to a tab parent 278
allowing duplicate items 351 sending to child forms 273
concatenating 334 sending to parent forms 275
counting items 352 Notify method 267
creating 329 NotifyById method 269
extracting information 339 NotifyByKey method 271
extracting items 346 NotifyChild method 273
getting items 343, 344 NotifyParent method 275
initializing 353 NotifyTab method 277
removing items 347 NotifyTabParent method 278
replacing items 348 n-tier environment 423
searching 341
setting the item type 353
O
sorting 349 Open File common dialog 165
Login method 153 Oracle database
Logout method 154 connecting to 433
LogSQL method 43 terminating a connection 435
overview 476
M
Me keyword 219
P
menu items Page property 389
adding 87 ParentKey property 303
changing the behavior 97 pen width 382
disabling 92 power query, See queries
enabling 92 PowerQuery object
executing 30 described 355
removing 95 AppendFilter method 356
renaming 96 AppendSort method 358
menu separators, adding 89, 91 GetCount method 360
MenuBarId property 100 Query method 361
menubars RetrieveIDS method 362
adding checkmarks 91 RetrieveRecords method 363
adding items 87 SetObjectType method 365
adding separators 89 SetSortOrder method 366
removing items 95 print job
renaming items 96 determining text height 374
showing 58, 99 determining width 375
specifying the menu 100 terminating 370
messages, See notifications truncating 392
MouseDown event 321 Print method 112, 138, 211, 373, 417
MouseUp event 322 Printer object
Move method 266 described 369
MsgBox method 44 Continuation property 376
CurrentX property 378
N CurrentY property 379
Name property 200, 302 DrawMode property 380
NewPage method 372 DrawStyle property 381
notifications DrawWidth property 382
sending 267 EndDoc method 370
sending by ID 269 FontBold property 383
sending by key 271 FontFamily property 385
sending to a tab 277 FontItalic property 386

520 Index
ClearBasic Object Reference
 FontSize property 387 deleting records 131, 133
Height property 388 filter operators 104
Line method 371 getting records 108, 135
NewPage method 372 getting related records 110
Page property 389 overview 125, 355
Print method 373 performing 113, 361
RightMargin property 390 printing 112, 138
TextHeight method 374 relating records 139, 141, 143, 144
TextWidth method 375 retrieving records 362, 363
Truncate property 392 saving records 145
Width property 394 setting the root record 115, 117
Wrap property 395 setting the type 365
printing sorting 358, 366
advancing the page 372 specifying the query size 79
continuation characters 376 traversing from the parent 120
default font 385 traversing from the root 122
determining text height 374 updating records 147
determining text width 375 Query method 361
enabling word wrap 395 QuerySize property 79
forcing a new page 372
form height 388
R
getting currentpage 389 Read method 426
getting page width 394 ReadOnly property 304
getting the current page 389 Record object
getting the job page range 180, 183 described 397
page height 388 ChangeToNew method 398
pen width 382 Copy method 399
queries 112 CopyFields method 400
right margin 390 CreateView method 402
setting font size 387 Format method 404
setting line type 381 GetField method 407
setting the draw mode 380 GetObject method 408
setting the pen width 382 GetTextField method 410
setting the right margin 390 IsDirty method 411
specifying continuation characters 376 IsExactly method 413
specifying current font family 385 IsMaxDate method 414
truncating print job 392 IsMinDate method 415
turning on bold font 383 IsNew method 416
turning on italics 386 Print method 417
turning on word wrap 395 RecordType property 419
PrintSetup common dialog 165 SetField method 418
records
Q checking for modifications 411
queries comparing 413
aborting 149 copying 398, 399
adding filters 103, 356 copying fields 400
appending sort criteria 105 creating 136
cancelling an update 127 declaring 397
changing records 128 deleting permanently 131, 133
creating records 136 formatting fields 404
creating simple queries 118 getting fields 407

Index 521
ClearBasic Object Reference
 relating 139, 141, 143, 144 SetRootById method 117
removing relations 146 SetSortOrder method 366
saving 145 SetTargetCurrency method 286
selecting 62 SetText method 163
setting the type 419 SetUserData method 288
updating 147 SetValue method 327
RecordType property 419 Show method 99, 212, 289
redrawing a form 238 ShowAttachments method 48
Refresh method 191, 279 ShowCase method 50
related records, retrieving 110 ShowContact method 52
RelateRecords method 139 ShowContract method 54
RelateRecordsFromID method 141 ShowControls method 291
RelateRecordsFromToID method 143 ShowControlsDeep method 292
RelateRecordsToID method 144 ShowCR method 56
RemoveByIndex method 347 ShowDefaultMenu method 58
RemoveItem method 95 ShowEmployee method 59
RenameItem method 96 ShowFTS method 61
ReplaceByIndex method 348 ShowSelect method 62
Resize event 323 ShowSite method 65
RetrieveIDS method 362 ShowSubcase method 67
RetrieveRecords method 113, 363 SimpleQuery method 118
right margin 390 single signon 502
RightMargin property 390 implementation 503
root record, setting 115, 117 return value 503
sample implementation 503
S Site window, displaying 65
Save File common dialog 165 size, font 387
Save method 145 sort conditions, appending to a query 105
Save_Aborted property 149 Sort method 192, 349
Screen object Sorted property 354
described 421 sorting, in contextual objects 192
AllSpaces method 422 SQL
Select method 440 establishing a database connection 433
ServerName property 81, 157 executing statements 436
ServiceMessage object using Select statements 440
described 423 SQLDB object
Call method 424 described 431–432
Read method 426 Connect method 433
Write method 428 Connected property 442
SetBulk Method 218 Disconnect method 435
SetColorScheme method 46 Execute method 436
SetContextMenuEnabled method 280 ExecuteProc method 438
SetContextMenuVisible method 281 Select method 440
SetDisplayCurrency method 282 string handling 507
SetField method 418 strings
SetFocus method 284 checking for spaces 422
SetFunction method 97 concatenating 334
SetLogData Method 216 SubCase window, displaying 67
SetObjectType method 365 subroutines, calling 19
SetParent method 285 SubType property 201
SetRoot method 115 Sybase database

522 Index
ClearBasic Object Reference
 terminating a connection 435
Sybase database, connecting to 433
synchronous mode 19

T
Tag property 182, 305
text
getting height 374
getting width 375
Text Box control
Tag property 182
TextHeight method 374
TextWidth method 375
time, getting and setting 173
time, specifying duration 177
Top property 306
ToPage property 183
TransferPart method 69
TraverseFromParent method 120
TraverseFromRoot method 122
Truncate property 392
TUXEDO environment
calling functions 424
reading data 426
using 423
writing data 428

U
UnrelateRecords method 146
Up method 350
UpdateAll Method 217
UpdateRecord method 147
UseClarifyDB method 71
UseDefaultDB method 73
user, getting 158
user-defined types
using in contextual objects 189
UserName property 82, 158
UserObjId property 83

V
ValidateUser method 74
Value property 328
Visible property 307

W
Width property 308, 394
window state 309
WindowState property 309
Wrap property 395
Write method 428

Index 523
ClearBasic Object Reference
524 Index
ClearBasic Object Reference