Microsoft® Dexterity

Function Library Reference

Release 12
Copyright Copyright © 2012 Microsoft Corporation. All rights reserved.

Limitation of liability This document is provided “as-is”. Information and views expressed in this document, including
URL and other Internet Web site references, may change without notice. You bear the risk of using
it.

Some examples depicted herein are provided for illustration only and are fictitious. No real
association or connection is intended or should be inferred.

Intellectual property This document does not provide you with any legal rights to any intellectual property in any
Microsoft product.

You may copy and use this document for your internal, reference purposes.

Trademarks Microsoft, Dexterity, Excel, Microsoft Dynamics, Visual Basic, Windows, Windows NT, and
Windows Server are trademarks of the Microsoft group of companies. FairCom and c-tree Plus are
trademarks of FairCom Corporation and are registered in the United States and other countries.

All other trademarks are property of their respective owners.

Warranty disclaimer Microsoft Corporation disclaims any warranty regarding the sample code contained in this
documentation, including the warranties of merchantability and fitness for a particular purpose.

License agreement Use of this product is covered by a license agreement provided with the software product. If you
have any questions, please call the Microsoft Dynamics GP Customer Assistance Department at
800-456-0025 (in the U.S. or Canada) or +1-701-281-6500.

Publication date December 2012

Contents
Introduction ................................................................................................................................. 2
What’s in this manual .................................................................................................................. 2
Symbols and conventions............................................................................................................ 2
Command syntax.......................................................................................................................... 3
Programming style ....................................................................................................................... 4

Part 1: Function Library Summary ................................................................ 6

Part 2: Function Libraries ..................................................................................... 26

Activity tracking function library .......................................................................................... 27
Activity_GetBackgroundStatus()...................................................................................... 28
Activity_GetExitMode()..................................................................................................... 29
Activity_GetResourceName() ........................................................................................... 30
Auto-complete function library .............................................................................................. 33
AutoComplete_AddStringValue().................................................................................... 34
AutoComplete_RemoveAllData() .................................................................................... 35
AutoComplete_RemoveFieldData() ................................................................................ 36
AutoComplete_RemoveStringValue() ............................................................................. 37
AutoComplete_SetMode()................................................................................................. 38
AutoComplete_SetOptions()............................................................................................. 39
Color function library ............................................................................................................... 41
Color_ConvertNameToValue() ......................................................................................... 42
Color_ConvertRGBToValue()............................................................................................ 43
Color_ConvertValueToName() ......................................................................................... 44
Color_ConvertValueToRGB()............................................................................................ 45
Color_GetFromDialog() ..................................................................................................... 46
Color_ResetSystemColor() ................................................................................................ 49
Color_SetSystemColor()..................................................................................................... 51
COM function library ............................................................................................................... 53
COM_AttachEventHandler() ............................................................................................ 54
COM_CreateObject() .......................................................................................................... 56
COM_DetachEventHandler() ........................................................................................... 57
COM_GetObject() ............................................................................................................... 58
COM_RegisterRunningObject()........................................................................................ 59
COM_RevokeRunningObject()......................................................................................... 61
Command function library ...................................................................................................... 63
Command_Execute().......................................................................................................... 64

FUNCTION LIBRARY REFERENCE i

C O N T E N T S

Command_GetAccelerator() ............................................................................................ 65
Command_GetBooleanProperty() ................................................................................... 67
Command_GetIDs ............................................................................................................. 68
Command_GetImageProperty() ...................................................................................... 69
Command_GetNamedProperty() .................................................................................... 71
Command_GetStringProperty()....................................................................................... 72
Command_GetTag() .......................................................................................................... 73
Command_GetType() ........................................................................................................ 74
Command_Reset().............................................................................................................. 75
Command_SetAccelerator() ............................................................................................. 76
Command_SetBooleanProperty() .................................................................................... 78
Command_SetImageProperty() ....................................................................................... 79
Command_SetNamedProperty() ..................................................................................... 81
Command_SetStringProperty() ....................................................................................... 82
Command bar function library .............................................................................................. 83
CommandBar_Create()...................................................................................................... 84
CommandBar_Destroy() ................................................................................................... 86
CommandBar_GetPosition() ............................................................................................ 87
Command list function library............................................................................................... 89
CommandList_Add() ........................................................................................................ 90
CommandList_CreateList() .............................................................................................. 92
CommandList_FindCommand() ..................................................................................... 94
CommandList_GetCommandByPosition() .................................................................... 95
CommandList_NumCommands()................................................................................... 96
CommandList_Remove() .................................................................................................. 97
CommandList_RemoveAll()............................................................................................. 98
CommandList_RemoveCommandByPosition() ............................................................ 99
Currency function library...................................................................................................... 101
Currency_GetDecimalSymbol() ..................................................................................... 102
Currency_GetLeadingSymbol() ..................................................................................... 103
Currency_GetLeadingZero() .......................................................................................... 104
Currency_GetNativeSymbol()........................................................................................ 105
Currency_GetNegativeAfterValue().............................................................................. 106
Currency_GetNegativeBeforeSymbol() ........................................................................ 107
Currency_GetNegativeParens() ..................................................................................... 108
Currency_GetNegativeSymbol().................................................................................... 109
Currency_GetNumberOfDecimals() ..............................................................................110
Currency_GetSymbol()..................................................................................................... 111
Currency_GetThousandsSymbol() .................................................................................112
Currency_SetDecimalSymbol() .......................................................................................113
Currency_SetLeadingSymbol() .......................................................................................114
Currency_SetLeadingZero() ............................................................................................115
Currency_SetNegativeAfterValue()................................................................................116

ii F U N C T I O N L I B R A R Y R E F E R E N C E
 C O N T E N T S

Currency_SetNegativeBeforeSymbol().......................................................................... 118
Currency_SetNegativeParens()....................................................................................... 120
Currency_SetNegativeSymbol() ..................................................................................... 122
Currency_SetNumberOfDecimals()............................................................................... 123
Currency_SetSymbol() ..................................................................................................... 124
Currency_SetThousandsSymbol().................................................................................. 125
Defaults file function library ................................................................................................ 127
Defaults_ClearUserFile() ................................................................................................. 128
Defaults_Read()................................................................................................................. 129
Defaults_ReadBoolean() .................................................................................................. 130
Defaults_ReadColor()....................................................................................................... 131
Defaults_ReadKeys()........................................................................................................ 133
Defaults_Write() ................................................................................................................ 135
Dexterity object function library .......................................................................................... 137
DexObject_AddMethod() ................................................................................................ 138
DexObject_AddProperty()............................................................................................... 140
DexObject_Create()........................................................................................................... 142
Dictionary function library.................................................................................................... 143
Dict_CountCustomResource() ........................................................................................ 144
Dict_GetCustomResourceInfo()...................................................................................... 146
Dict_GetName() ................................................................................................................ 148
Dict_GetPathname() ......................................................................................................... 149
Dict_LockCustom()........................................................................................................... 150
Dict_UnlockCustom() ...................................................................................................... 151
Dict_UpdateFormsDictionary() ...................................................................................... 152
Dict_UpdateReportsDictionary() ................................................................................... 156
Exception function library ..................................................................................................... 161
Exception_Class().............................................................................................................. 162
Exception_ClassName()................................................................................................... 163
Exception_Message()........................................................................................................ 164
Exception_Product()......................................................................................................... 165
Exception_ProductName() .............................................................................................. 166
Exception_SubClass()....................................................................................................... 167
Exception_SubClassName() ............................................................................................ 168
Field function library.............................................................................................................. 169
Field_BDLAddToSubmenu() .......................................................................................... 171
Field_BDLCreateLinkedCommandList() ...................................................................... 172
Field_BDLCreateSubmenu() ........................................................................................... 173
Field_BDLGetLinkedItemCommandTag().................................................................... 175
Field_CreateLinkedCommand()..................................................................................... 176
Field_GetBooleanProperty()............................................................................................ 178
Field_GetCaption() ........................................................................................................... 180

FUNCTION LIBRARY REFERENCE iii

C O N T E N T S

Field_GetColor()............................................................................................................... 181
Field_GetFont()................................................................................................................. 183
Field_GetImage().............................................................................................................. 184
Field_GetInsertPosFromVisualPos() ............................................................................. 185
Field_GetIntegerProperty()............................................................................................. 186
Field_GetLinkedCommandTag() ................................................................................... 187
Field_GetPosition() .......................................................................................................... 188
Field_GetRequiredStatus().............................................................................................. 189
Field_GetSelection()......................................................................................................... 190
Field_GetSize().................................................................................................................. 191
Field_GetStringProperty() .............................................................................................. 192
Field_GetVisualPosFromInsertPos() ............................................................................. 193
Field_GetToolTip() ........................................................................................................... 194
Field_InsertStringInText() ............................................................................................... 195
Field_MarkListItems() ..................................................................................................... 196
Field_ParseText() .............................................................................................................. 197
Field_SetAltLineColor() .................................................................................................. 199
Field_SetBackColor() ....................................................................................................... 201
Field_SetBooleanProperty() ............................................................................................ 202
Field_SetCaption() ........................................................................................................... 204
Field_SetCustomPromptFormat().................................................................................. 205
Field_SetFont().................................................................................................................. 207
Field_SetFontColor()........................................................................................................ 208
Field_SetFontSize() .......................................................................................................... 209
Field_SetFontStyle() ......................................................................................................... 210
Field_SetImage()................................................................................................................211
Field_SetIntegerProperty().............................................................................................. 212
Field_SetPattern()............................................................................................................. 213
Field_SetPatternColor()................................................................................................... 214
Field_SetRequiredFormat()............................................................................................. 215
Field_SetRequiredStatus()............................................................................................... 217
Field_SetSelection().......................................................................................................... 219
Field_SetStringProperty() ............................................................................................... 220
Field_SetToolTip() ............................................................................................................ 221
Field_SetZoomFormat() .................................................................................................. 222
File function library................................................................................................................ 225
File_Count() ...................................................................................................................... 226
File_Delete() ...................................................................................................................... 227
File_GetSize() .................................................................................................................... 228
File_GetTempDirectory() ................................................................................................ 229
File_Probe() ....................................................................................................................... 230
File list function library ......................................................................................................... 231
FileList_Add()................................................................................................................... 232

iv F U N C T I O N L I B R A R Y R E F E R E N C E
 C O N T E N T S

FileList_Count() ................................................................................................................ 234

FileList_Create() ................................................................................................................ 235
FileList_Destroy().............................................................................................................. 236
FileList_Get() ..................................................................................................................... 237
FileList_Remove() ............................................................................................................. 239
FileList_ShowDialog()...................................................................................................... 240
File type function library ....................................................................................................... 243
FileType_CanAppend().................................................................................................... 244
FileType_FillList() ............................................................................................................. 245
FileType_GetExtension().................................................................................................. 246
FileType_IsValid() ............................................................................................................. 248
Form function library.............................................................................................................. 249
Form_GetWindowGroup() .............................................................................................. 250
Import function library........................................................................................................... 251
Import_CloseFile() ............................................................................................................ 252
Import_GetNextField() .................................................................................................... 253
Import_GetNextRecord()................................................................................................. 255
Import_OpenFile() ............................................................................................................ 256
Help pane function library .................................................................................................... 257
HelpPane_Create()............................................................................................................ 258
HelpPane_Destroy() ......................................................................................................... 259
HelpPane_DisplayTopic()................................................................................................ 260
HelpPane_GetWidth()...................................................................................................... 262
HelpPane_SetTitle() .......................................................................................................... 263
HelpPane_SetWidth()....................................................................................................... 264
HelpPane_Show() ............................................................................................................. 265
IP function library ................................................................................................................... 267
IP_GetIPName() ................................................................................................................ 268
IP_GetIPNumber()............................................................................................................ 269
IP_PingDPS() ..................................................................................................................... 270
Launch file function library .................................................................................................. 271
Launch_CountProds() ...................................................................................................... 272
Launch_FillListWithProds() ............................................................................................ 273
Launch_GetFileInfo() ....................................................................................................... 274
Launch_GetFileName().................................................................................................... 275
Launch_GetProdID() ........................................................................................................ 276
Launch_GetProdName().................................................................................................. 277
Launch_GetProdPosition() .............................................................................................. 278
Launch_ParseFileFromPath().......................................................................................... 279
Launch_ReadDictPath()................................................................................................... 280
Launch_SelectDict().......................................................................................................... 281
Launch_SelectFile()........................................................................................................... 283

FUNCTION LIBRARY REFERENCE v

C O N T E N T S

Launch_WriteDictPath().................................................................................................. 284
List view function library...................................................................................................... 287
ListView_ColumnAdd().................................................................................................. 289
ListView_ColumnCount()............................................................................................... 291
ListView_ColumnGetAlignment() ................................................................................ 292
ListView_ColumnGetLabel().......................................................................................... 293
ListView_ColumnGetPosition() ..................................................................................... 294
ListView_ColumnGetSubitem()..................................................................................... 295
ListView_ColumnGetWidth() ........................................................................................ 296
ListView_ColumnRemove() ........................................................................................... 297
ListView_ColumnSetAlignment() ................................................................................. 299
ListView_ColumnSetLabel()........................................................................................... 300
ListView_ColumnSetPosition() ...................................................................................... 301
ListView_ColumnSetWidth() ......................................................................................... 302
ListView_GetClickItem()................................................................................................. 304
ListView_GetSortColumn() ............................................................................................ 305
ListView_GetStringWidth() ............................................................................................ 306
ListView_GetView()......................................................................................................... 307
ListView_ItemAdd() ........................................................................................................ 308
ListView_ItemCount() ..................................................................................................... 310
ListView_ItemGetCurrencySubitem()............................................................................311
ListView_ItemGetData() ................................................................................................. 312
ListView_ItemGetDateSubitem()................................................................................... 313
ListView_ItemGetImage()............................................................................................... 314
ListView_ItemGetIntSubitem() ...................................................................................... 315
ListView_ItemGetLabel() ................................................................................................ 316
ListView_ItemGetStateImage() ...................................................................................... 317
ListView_ItemGetSubitem() ........................................................................................... 318
ListView_ItemGetTimeSubitem() .................................................................................. 319
ListView_ItemMakeVisible() .......................................................................................... 320
ListView_ItemRemove().................................................................................................. 321
ListView_ItemSetCurrencySubitem()............................................................................ 322
ListView_ItemSetData() .................................................................................................. 326
ListView_ItemSetDateSubitem().................................................................................... 327
ListView_ItemSetImage()................................................................................................ 328
ListView_ItemSetIntSubitem() ....................................................................................... 329
ListView_ItemSetLabel() ................................................................................................. 330
ListView_ItemSetStateImage() ....................................................................................... 331
ListView_ItemSetSubitem() ............................................................................................ 332
ListView_ItemSetTimeSubitem() ................................................................................... 333
ListView_SelectionCount() ............................................................................................. 334
ListView_SelectionGet() .................................................................................................. 335
ListView_SelectionSet() ................................................................................................... 336

vi F U N C T I O N L I B R A R Y R E F E R E N C E
 C O N T E N T S

ListView_SetEmptyMessage() ........................................................................................ 338

ListView_SetSortColumn().............................................................................................. 339
ListView_SetView() .......................................................................................................... 341
ListView_Sort().................................................................................................................. 342
Login function library............................................................................................................. 345
Login_AlterLogin()........................................................................................................... 346
Login_CreateLogin() ........................................................................................................ 351
Login_DropLogin()........................................................................................................... 354
Login_ExitDataSource() ................................................................................................... 355
Login_GetDataSources() .................................................................................................. 356
Login_GetDBMSInfo() ..................................................................................................... 357
Login_GetInfo()................................................................................................................. 358
Login_GetLoginSettings()................................................................................................ 359
Login_LogIntoDataSource()............................................................................................ 361
Login_LogIntoDataSourceEx() ....................................................................................... 363
Login_OpenDexDialog() ................................................................................................. 367
Login_VerifyInfo() ............................................................................................................ 369
Mail function library............................................................................................................... 371
Mail_AddressListAdd() ................................................................................................... 372
Mail_AddressListCount() ................................................................................................ 373
Mail_AddressListCreate() ............................................................................................... 374
Mail_AddressListDestroy() ............................................................................................. 375
Mail_AddressListGet()..................................................................................................... 376
Mail_AddressListRemove() ............................................................................................ 378
Mail_DisplayAddressDialog() ........................................................................................ 379
Mail_DisplayReplyToDialog() ........................................................................................ 381
Mail_GetServerType() ...................................................................................................... 383
Mail_GetSessionAddress() .............................................................................................. 384
Mail_IsLoggedOn() .......................................................................................................... 385
Mail_LogOff().................................................................................................................... 386
Mail_LogOn() .................................................................................................................... 387
Mail_ResolveAddress().................................................................................................... 389
Mail_Send()........................................................................................................................ 391
Mail_SendDialog()............................................................................................................ 393
Mail_SetServerType() ....................................................................................................... 395
MAPI function library ............................................................................................................ 397
MAPI_AddAddress() ....................................................................................................... 398
MAPI_CountAddresses() ................................................................................................ 399
MAPI_CreateAddressList() ............................................................................................. 400
MAPI_DestroyAddressList()........................................................................................... 401
MAPI_DisplayDialog() .................................................................................................... 402
MAPI_DisplayReplyToDialog()...................................................................................... 403
MAPI_GetAddress()......................................................................................................... 405

FUNCTION LIBRARY REFERENCE vii

C O N T E N T S

MAPI_IsLoggedOn() ....................................................................................................... 407

MAPI_IsMailEnabled().................................................................................................... 408
MAPI_LogOff()................................................................................................................. 409
MAPI_LogOn() ................................................................................................................. 410
MAPI_ProfileGetAddress() .............................................................................................411
MAPI_PropertyListCount() ............................................................................................ 412
MAPI_PropertyListCreate()............................................................................................ 413
MAPI_PropertyListDestroy() ......................................................................................... 414
MAPI_PropertyListGetValue()....................................................................................... 415
MAPI_PropertyListGetValueByIndex() ........................................................................ 416
MAPI_PropertyListSetValue()........................................................................................ 419
MAPI_RemoveAddress() ................................................................................................ 422
MAPI_ResolveAddress()................................................................................................. 423
MAPI_Send() .................................................................................................................... 425
MAPI_SendDialog()......................................................................................................... 427
Menu bar function library..................................................................................................... 429
MenuBar_AddMenu() ..................................................................................................... 430
MenuBar_RemoveAllMenus() ....................................................................................... 431
MenuBar_RemoveMenu()............................................................................................... 432
Menu function library............................................................................................................ 433
Menu_Invoke() ................................................................................................................. 434
OLE function library .............................................................................................................. 435
OLE_CloseNote() ............................................................................................................. 436
OLE_DeleteNote()............................................................................................................ 437
OLE_Exit()......................................................................................................................... 438
OLE_IsNoteEnabled()...................................................................................................... 439
OLE_OpenNote() ............................................................................................................. 440
OLE_SaveNote()............................................................................................................... 441
Path function library .............................................................................................................. 443
Path_ChangeDefault() ..................................................................................................... 444
Path_CreateFolder()......................................................................................................... 445
Path_DoesExist() .............................................................................................................. 446
Path_GetForApp()............................................................................................................ 447
Path_MakeGeneric() ........................................................................................................ 449
Path_MakeNative() .......................................................................................................... 450
Path_ParseFileFromPath() .............................................................................................. 451
Path_ParsePathFromPath()............................................................................................. 452
Path_SelectPathname().................................................................................................... 453
Printer function library .......................................................................................................... 455
Printer_Define()................................................................................................................ 456
Printer_GetName()........................................................................................................... 457
Printer_SetDestination().................................................................................................. 458

viii F U N C T I O N L I B R A R Y R E F E R E N C E
 C O N T E N T S

Registry function library........................................................................................................ 459

Registry_DeleteKey() ....................................................................................................... 460
Registry_DeleteValue() .................................................................................................... 461
Registry_GetProtectedString() ........................................................................................ 462
Registry_GetValue() ......................................................................................................... 464
Registry_SetKeyValue() ................................................................................................... 466
Registry_SetProtectedKeyString() .................................................................................. 468
Report function library........................................................................................................... 469
Report_Begin() .................................................................................................................. 471
Report_DoubleLine()........................................................................................................ 474
Report_End() ..................................................................................................................... 475
Report_GetPageRemaining() .......................................................................................... 476
Report_GetPageSize() ...................................................................................................... 477
Report_GetStringWidth() ................................................................................................ 478
Report_NewBand()........................................................................................................... 479
Report_NewPage() ........................................................................................................... 480
Report_ReadyToRun()...................................................................................................... 481
Report_SetFont() ............................................................................................................... 482
Report_SingleLine().......................................................................................................... 483
Report_WriteText() ........................................................................................................... 484
Resource function library....................................................................................................... 485
Resource_EndSeriesFill() ................................................................................................. 486
Resource_FillSeriesList().................................................................................................. 487
Resource_GetDisplayName().......................................................................................... 489
Resource_GetID().............................................................................................................. 491
Resource_GetInfo() ........................................................................................................... 492
Resource_GetNthResource() ........................................................................................... 494
Resource_GetResourceName() ....................................................................................... 496
Resource_GetSubResourceName()................................................................................. 497
Resource_StartSeriesFill() ................................................................................................ 499
Runtime function library ....................................................................................................... 503
Runtime_GetClientType()................................................................................................ 504
Runtime_GetCPUType() .................................................................................................. 505
Runtime_GetCurrentProductID()................................................................................... 506
Runtime_GetModuleInfo().............................................................................................. 507
Runtime_GetOSBuildInfo()............................................................................................. 509
Runtime_GetOSInfo() ...................................................................................................... 510
Runtime_GetVersionNum() ............................................................................................ 512
Runtime_GetWebClientTrustLevel().............................................................................. 513
Runtime_SetAboutMenu() .............................................................................................. 514
Runtime_SetFieldEnterMode() ....................................................................................... 515
Runtime_SetIcon() ............................................................................................................ 516

FUNCTION LIBRARY REFERENCE ix

C O N T E N T S

Script log function library..................................................................................................... 517

ScriptLog_Start() .............................................................................................................. 518
ScriptLog_Stop()............................................................................................................... 519
Script profile function library .............................................................................................. 521
ScriptProfile_Clear() ........................................................................................................ 522
ScriptProfile_Save().......................................................................................................... 523
ScriptProfile_Start().......................................................................................................... 524
ScriptProfile_Stop() .......................................................................................................... 525
Shell function library ............................................................................................................. 527
Shell_DisplayNotification() ............................................................................................ 528
SQL function library .............................................................................................................. 533
SQL_Clear()....................................................................................................................... 534
SQL_Connect().................................................................................................................. 535
SQL_DescribeColumn() .................................................................................................. 536
SQL_Execute() .................................................................................................................. 538
SQL_FetchNext() .............................................................................................................. 542
SQL_GetData().................................................................................................................. 543
SQL_GetError()................................................................................................................. 544
SQL_GetNextResults() .................................................................................................... 546
SQL_GetNumCols()......................................................................................................... 547
SQL_GetNumRows()....................................................................................................... 548
SQL_Terminate() .............................................................................................................. 550
Table function library............................................................................................................. 551
Table_AutoShrink().......................................................................................................... 553
Table_Compare() .............................................................................................................. 556
Table_CopyShrinkRecords() ........................................................................................... 557
Table_CreateIndexes() ..................................................................................................... 559
Table_CreateProcedures() ............................................................................................... 560
Table_DisableErrorChecks() ........................................................................................... 563
Table_DropProcedures().................................................................................................. 564
Table_EndConversion()................................................................................................... 565
Table_EndShrink()............................................................................................................ 566
Table_FillGroupList()....................................................................................................... 569
Table_FillList() .................................................................................................................. 571
Table_FlushCache().......................................................................................................... 572
Table_GetAutoShrinkMode() ......................................................................................... 573
Table_GetDisplayName()................................................................................................ 574
Table_GetFieldList()......................................................................................................... 575
Table_GetGroup()............................................................................................................. 576
Table_GetKeyFieldList().................................................................................................. 577
Table_GetKeyInfo() .......................................................................................................... 578
Table_GetKeyOption()..................................................................................................... 580

x FU N C T I O N L I B R A R Y R E F E R E N C E
 C O N T E N T S

Table_GetNumberOfKeys()............................................................................................. 582
Table_GetOSName()......................................................................................................... 583
Table_GetRangeKey()....................................................................................................... 584
Table_GetSeries() .............................................................................................................. 585
Table_GetSQLErrorText()................................................................................................. 586
Table_IsRangeSet()............................................................................................................ 588
Table_OpenAsTemp()....................................................................................................... 589
Table_OpenNewBuffer().................................................................................................. 590
Table_RebuildIndexes() ................................................................................................... 591
Table_SetCreateMode() .................................................................................................... 593
Table_SetDBType()............................................................................................................ 595
Table_SetDeleteOptions() ................................................................................................ 596
Table_SetRefreshFlags() ................................................................................................... 598
Table_StartConversion() .................................................................................................. 599
Table_StartShrink() ........................................................................................................... 602
Table_Truncate()................................................................................................................ 604
Table_VerifyRecord() ........................................................................................................ 606
Text file function library ........................................................................................................ 609
TextFile_Close()................................................................................................................. 610
TextFile_Open()................................................................................................................. 611
TextFile_ReadLine().......................................................................................................... 613
TextFile_ReadText() .......................................................................................................... 615
TextFile_WriteDOS()......................................................................................................... 616
TextFile_WriteLine() ......................................................................................................... 617
TextFile_WriteText().......................................................................................................... 618
Timer function library ............................................................................................................ 619
Timer_Sleep()..................................................................................................................... 620
Tools function library ............................................................................................................. 621
Tools_CloseDUOSTable()................................................................................................. 622
Tools_DisableLoadBalancing() ....................................................................................... 623
Tools_EnableCommandMenus() .................................................................................... 624
Tools_EnableCustomizationMaintenance() .................................................................. 625
Tools_EnableCustomizationStatus() .............................................................................. 626
Tools_EnableImport()....................................................................................................... 627
Tools_EnableLoadBalancing()......................................................................................... 628
Tools_EnableModifier().................................................................................................... 629
Tools_EnableReportWriter()............................................................................................ 630
Tools_GetTranLevel() ....................................................................................................... 631
Tools_IsAppProcessServer()............................................................................................ 632
Tools_IsScriptRemote() .................................................................................................... 633
Tools_OpenDUOSTable()................................................................................................. 634
Tools_UseShell .................................................................................................................. 635

FUNCTION LIBRARY REFERENCE xi

C O N T E N T S

Tree view function library..................................................................................................... 637

TreeView_AddNode()...................................................................................................... 638
TreeView_CollapseNode() .............................................................................................. 640
TreeView_CountChildren()............................................................................................. 641
TreeView_CountNodes()................................................................................................. 642
TreeView_ExpandNode()................................................................................................ 643
TreeView_GetClickNode() .............................................................................................. 644
TreeView_GetCollapsingNode() .................................................................................... 645
TreeView_GetExpandingNode().................................................................................... 646
TreeView_GetFirstChild() ............................................................................................... 647
TreeView_GetNextNode()............................................................................................... 648
TreeView_GetNodeData()............................................................................................... 649
TreeView_GetNodeImage() ............................................................................................ 650
TreeView_GetNodeLabel() ............................................................................................. 651
TreeView_GetNodeStateImage().................................................................................... 652
TreeView_GetParent()...................................................................................................... 653
TreeView_GetPreviousNode()........................................................................................ 654
TreeView_GetRootNode() ............................................................................................... 655
TreeView_GetSelectedNode()......................................................................................... 656
TreeView_IsParentNode() ............................................................................................... 657
TreeView_MakeNodeVisible()........................................................................................ 658
TreeView_RemoveChildren() ......................................................................................... 659
TreeView_RemoveNode() ............................................................................................... 660
TreeView_SetNodeData()................................................................................................ 661
TreeView_SetNodeImage() ............................................................................................. 662
TreeView_SetNodeLabel() .............................................................................................. 663
TreeView_SetNodeStateImage()..................................................................................... 664
TreeView_SetSelectedNode().......................................................................................... 665
Trigger function library ......................................................................................................... 667
Trigger_CausedByProduct() ........................................................................................... 668
Trigger_DisableSingle() ................................................................................................... 669
Trigger_Enable() ............................................................................................................... 670
Trigger_EnableSingle() .................................................................................................... 671
Trigger_GetCurrentTag ................................................................................................... 672
Trigger_IsTriggerEnabled()............................................................................................. 673
Trigger_RegisterDatabase() ............................................................................................ 674
Trigger_RegisterDatabaseByName() ............................................................................. 677
Trigger_RegisterFocus() .................................................................................................. 680
Trigger_RegisterFocusByName() ................................................................................... 683
Trigger_RegisterForm() ................................................................................................... 686
Trigger_RegisterFormByName().................................................................................... 688
Trigger_RegisterFunction() ............................................................................................. 690
Trigger_RegisterFunctionByName() ............................................................................. 692

xii FU N C T I O N L I B R A R Y R E F E R E N C E
 C O N T E N T S

Trigger_RegisterProcedure() ........................................................................................... 694

Trigger_RegisterProcedureByName()............................................................................ 696
Trigger_Unregister() ......................................................................................................... 698
Utility function library ........................................................................................................... 699
Utility_DecodeString() ..................................................................................................... 700
Utility_DecryptTableString()........................................................................................... 701
Utility_EncodeString() ..................................................................................................... 702
Utility_EncryptTableString() ........................................................................................... 703
Utility_LaunchUrl() .......................................................................................................... 704
Utility_LoadDLL() ............................................................................................................ 705
Utility_SubstituteTokens()............................................................................................... 707
Utility_UnloadDLL()........................................................................................................ 708
Window function library........................................................................................................ 709
Window_ForceRedraw().................................................................................................. 710
Window_GetMainWindowTitle()................................................................................... 713
Window_GetPosition()..................................................................................................... 714
Window_GetRibbonCommandTag() ............................................................................. 715
Window_GetSize()............................................................................................................ 716
Window_GetState() .......................................................................................................... 717
Window_GetTitle() ........................................................................................................... 718
Window_GetTitleByProduct()......................................................................................... 719
Window_PullFocus()........................................................................................................ 720
Window_ScrollScrollingWindow()................................................................................. 721
Window_SetBaseSize()..................................................................................................... 723
Window_SetLineMode().................................................................................................. 724
Window_SetState() ........................................................................................................... 725
Window group function library............................................................................................ 727
WindowGroup_AddWindow() ...................................................................................... 728
WindowGroup_SetBooleanProperty()........................................................................... 729
WindowGroup_SetPosition() .......................................................................................... 731
WindowGroup_SetSize() ................................................................................................. 732
WindowGroup_SetState()................................................................................................ 733
WindowGroup_SetStringProperty() .............................................................................. 734
WinHelp function library ...................................................................................................... 735
WinHelp_ALinkLookup() ............................................................................................... 736
WinHelp_GetCurWindow() ............................................................................................ 737
WinHelp_GetFieldContextNumber() ............................................................................ 738
WinHelp_GetHelpType()................................................................................................. 739
WinHelp_GetWindowContextNumber() ...................................................................... 740
WinHelp_InvokeHelp() ................................................................................................... 741
WinHelp_LaunchUrl() ..................................................................................................... 743
WinHelp_RegisterHelpProcedure() ............................................................................... 747

FUNCTION LIBRARY REFERENCE xiii

 WinHelp_RunHelpMacro() ............................................................................................ 748
WinHelp_Search() ............................................................................................................ 749

Index ............................................................................................................................................... 751

xiv FU N C T I O N L I B R A R Y R E F E R E N C E
INTRODUCTION
Introduction
This manual provides a detailed reference for the function libraries
provided with Microsoft® Dexterity. Function libraries group related
functions based on how they are used. For example, the functions used to
manipulate fields are located in the Fields Library. For general information
about scripting, refer to Volume 2 of the Dexterity Programmer’s Guide.

What’s in this manual

The parts included in this manual are listed below, with a short description
of each.

• Part 1, Function Library Summary, provides a summary table describ-

ing all of the functions in each function library.

• Part 2, Function Libraries, each explains each function library function

in detail.

Symbols and conventions

To help you use the Dexterity documentation more effectively, we’ve used
the following symbols and conventions within the text to make specific
types of information stand out.

Symbol Description
➥ of table Items; A continuation character indicates that a script
continued from one line to the next should be
typed as one line in the Script Editor.
The light bulb symbol indicates helpful tips,
shortcuts and suggestions.

Warnings indicate situations you should be

aware of when completing tasks with Dexterity.

Margin notes summa- Margin notes call attention to critical

rize important informa- information, and direct you to other areas of the
tion. documentation where a topic is explained.
The SQL symbol indicates information that
SQL
applies only when a SQL database type is used.

2 FU N C T I O N L I B R A R Y R E F E R E N C E
 IN TRO DUCT IO N

Convention Description
Part 2, Basics Bold type indicates a part name.
Chapter 9, “Tables” Quotation marks indicate a chapter name.
Applying formats Italicized type indicates a section name.
set 'l_Item' to 1; This font is used to indicate script examples.
RUNTIME.EXE Words in uppercase indicate a file name.
Software Development Acronyms are spelled out the first time they’re
Kit (SDK) used.
TAB or ALT+M Small capital letters indicate a key or a key
sequence.

Command syntax
The syntax descriptions throughout this manual use the following
standards:

• Bold text indicates language-specific reserved words, including both

command names and words that appear literally in scripts.

• Any parentheses () are a part of the command.

• Italics indicate items to be replaced by object names or values.

• A vertical bar (|) between two or more items should be read as “or,”
and indicates that one item in the list should be chosen.

• Braces {} indicate optional items. If the braces enclose a group of items,

one of the items can be chosen.

• Square brackets [] list a group of items in which one choice is required.

In rare cases where they are part of the command syntax, they’re set in
bold text.

• Ellipses (...) indicate that other commands can appear between the key-
words of the command being described.

FUNCTION LIBRARY REFERENCE 3

I N T R O D U C T I O N

Programming style
• Script examples are shown in Courier type.

• Each statement is terminated with a semicolon.

• Comments describing a line of the script appear above or beside the

corresponding line and are enclosed in braces. A sample script state-
ment with a comment is shown below:

{Open the form to enter customer data.}

open form 'Customer Maintenance';

• A continuation character (➥) indicates that a script continued from one

line to the next should be typed as one line in the Script Editor.

4 FU N C T I O N L I B R A R Y R E F E R E N C E
PART 1: FUNCTION LIBRARY SUMMARY
 Part 1: Function Library
Summary
This part describes the functions available in the various function libraries
for Dexterity. The naming convention groups related functions into libraries
and allows each function’s purpose to be readily identified. For example, all
functions included in the Currency function library begin with the word
Currency, and are used to manipulate the formats created for use in
multicurrency applications.

The following table lists the functions in each function library, along with
brief descriptions. The next part of the manual describes each function in
detail.

6 FU N C T I O N L I B R A R Y R E F E R E N C E

Activity tracking
Activity_GetBackgroundStatus()
Activity_GetExitMode()
Activity_GetResourceName()
Auto-complete
AutoComplete_AddStringValue()
AutoComplete_RemoveAllData()
AutoComplete_RemoveFieldData()
AutoComplete_RemoveStringValue()
AutoComplete_SetMode()
AutoComplete_SetOptions()
Color
Color_ConvertNameToValue()
Color_ConvertRGBToValue()
Color_ConvertValueToName()
Color_ConvertValueToRGB()
Color_GetFromDialog()
Color_ResetSystemColor()
Color_SetSystemColor()
COM
COM_AttachEventHandler()
COM_CreateObject()
COM_DetachEventHandler()
COM_GetObject()
COM_RegisterRunningObject()
COM_RevokeRunningObject()
Command
Command_Execute()
Command_GetAccelerator()
Command_GetBooleanProperty()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Ascertains whether the runtime engine’s process queue contains any
background procedures.
Ascertains the mode used to exit the runtime engine.
Returns a string containing a resource’s display name.
Adds an auto-complete value for the specified field.
Removes all of the auto-complete data for the user currently logged
into the workstation.
Removes the auto-complete data for the specified field for the user
currently logged into the workstation.
Removes the specified string from the auto-complete data for the
specified field.
Enables or disables auto-complete for the application.
Sets options for auto-complete functionality.
Converts a Dexterity predefined color name to the corresponding
color value.
Converts red, green and blue color levels to a color value.
Converts a color value to a corresponding predefined color name.
Converts a color to its component red, green and blue color levels.
Opens a color selection dialog that allows the user to pick a color.
Sets the specified system color category back to the default value,
which is derived from the current operating system settings.
Sets a system color category to the specified color.
Attaches a callback object as an event handler.
Creates a COM object reference to a new instance of an object.
Detaches the event handler from a callback object in your Dexterity-
based application.
Retrieves a reference to the instance of an object that exists in the
running object table.
Adds the specified callback object to the running object table.
Removes a callback object from the running object table.
Performs the action for the specified command.
Retrieves the shortcut that is defined for the command.
Retrieves a specified boolean property for a command.
FUNCTION LIBRARY REFERENCE 7
PA RT 1 F U N C T I O N L IB R A R Y
Command (continued)
Command_GetIDs
Command_GetImageProperty()
Command_GetNamedProperty()
Command_GetStringProperty()
Command_GetTag()
Command_GetType()
Command_Reset()
Command_SetAccelerator()
Command_SetBooleanProperty()
Command_SetImageProperty()
Command_SetNamedProperty()
Command_SetStringProperty()
Command bar
CommandBar_Create()
CommandBar_Destroy()
CommandBar_GetPosition()
Command list
CommandList_Add()
CommandList_CreateList()
CommandList_FindCommand()
CommandList_GetCommandByPosition()
CommandList_NumCommands()
CommandList_Remove()
CommandList_RemoveAll()
CommandList_RemoveCommandByPosition()
Currency
Currency_GetDecimalSymbol()
Currency_GetLeadingSymbol()
Currency_GetLeadingZero()
8 FU N C T I O N L I B R A R Y
S U M M A R Y
Retrieves the resource IDs of the dictionary that contains the
command, the form on which the command is defined, and the
command itself.
Retrieves the specified image defined for a command.
Retrieves the value of a specific named property that has been added
to a command.
Retrieves a specified string property for a command.
Retrieves the tag associated with the specified command or
command list.
Retrieves the type of a specific command.
Returns the settings for a command back to their original state as
defined in the dictionary.
Sets the shortcut that is defined for the command.
Sets a specified boolean property for a command.
Sets the specified image defined for a command.
Temporarily adds a property with the specified name to a command.
It then sets the value for the property.
Sets a specified string property for a command.
Creates a toolbar based on the specified command list.
Removes a toolbar based on the specified command list.
Retrieves the row and position of a toolbar that is based on the
specified command list.
Adds a command or another command list to the specified command
list.
Creates a command list and associates it with a specific form.
Retrieves the position of the specified item in a command list.
Retrieves the tag for a command, based on the position in the
command list.
Retrieves the number of commands in the specified command list.
Removes the specified item from a command list.
Removes all items from the specified command list.
Removes the item from the specified position in a command list.
Returns the string used as a decimal separator.
Returns a boolean indicating whether the currency symbol is
positioned before the currency value.
Returns a boolean indicating whether a currency value less than 1 and
greater than -1 will be displayed with a leading zero.
R E F E R E N C E

Currency (continued)
Currency_GetNativeSymbol()
Currency_GetNegativeAfterValue()
Currency_GetNegativeBeforeSymbol()
Currency_GetNegativeParens()
Currency_GetNegativeSymbol()
Currency_GetNumberOfDecimals()
Currency_GetSymbol()
Currency_GetThousandsSymbol()
Currency_SetDecimalSymbol()
Currency_SetLeadingSymbol()
Currency_SetLeadingZero()
Currency_SetNegativeAfterValue()
Currency_SetNegativeBeforeSymbol()
Currency_SetNegativeParens()
Currency_SetNegativeSymbol()
Currency_SetNumberOfDecimals()
Currency_SetSymbol()
Currency_SetThousandsSymbol()
Defaults file
Defaults_ClearUserFile()
Defaults_Read()
Defaults_ReadBoolean()
Defaults_ReadColor()
Defaults_ReadKeys()
Defaults_Write()
Dexterity object
DexObject_AddProperty()
DexObject_AddMethod()
DexObject_Create()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Returns a platform-specific string displaying the dollar, pound, yen or
Euro currency symbol.
Returns a boolean value indicating whether the negative symbol is
placed after the currency value.
Returns a boolean indicating whether a leading negative symbol is
placed before a leading currency symbol.
Returns a boolean indicating whether parentheses are used to denote
a negative currency value.
Returns the string used as the negative symbol.
Returns the number of digits that will appear to the right of a currency
value’s decimal separator.
Returns the string used as a currency symbol.
Returns the string used as a thousands separator.
Defines a string to use as a decimal separator.
Specifies whether the currency symbol should appear before or after
the value.
Defines whether a leading zero will be displayed with a currency value
less than 1 and greater than -1.
Defines whether the negative symbol is placed after the value.
Defines whether a leading negative symbol is placed before or after a
leading currency symbol.
Defines whether parentheses are used to denote a negative value.
Defines a string to be used as a negative symbol.
Defines the number of digits that will appear to the right of the
decimal separator.
Defines a string to use as a currency symbol.
Defines a string to use as a thousands separator.
Clears the contents of the user-specifc DEX.INI file.
Reads the value of a setting in the Dexterity defaults file.
Reads a boolean value from the Defaults file.
Reads a color value from the Defaults file.
Reads all of the key values in the specified DEX.INI file.
Writes a setting to the Dexterity defaults file.
Adds a field to a callback object.
Adds a method to a callback object.
Creates a callback object.
FUNCTION LIBRARY REFERENCE 9
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

Dictionary
Dict_CountCustomResource() Returns the number of forms in the forms dictionary, or the number
of reports in the reports dictionary.
Dict_GetCustomResourceInfo() Returns information about a form in a forms dictionary, or a report in
a reports dictionary.
Dict_GetName() Returns the operating system name of the current dictionary.
Dict_GetPathname() Returns the generic path of various components of the current
installation, such as the runtime engine or launch file.
Dict_LockCustom() Opens and locks a forms or reports dictionary.
Dict_UnlockCustom() Releases the lock added by Dict_LockCustom().
Dict_UpdateFormsDictionary() Updates existing new and modified reports to work with the new
version of an application.
Dict_UpdateReportsDictionary() Upgrades existing modified forms to work with the new version of an
application.

Exception handling
Exception_Class() Returns the class of the current exception.
Exception_ClassName() Returns a string containing the constant for the class of the current
system exception.
Exception_Message() Returns a string describing the current exception.
Exception_Product() Returns the ID of the product that threw the current exception.
Exception_SubClass() Returns the subclass of the current exception.
Exception_SubClassName() Returns a string containing the constant for the subclass of the
current system exception.

Field
Field_BDLAddToSubmenu() Adds an item to a submenu of a button drop list control.
Field_BDLCreateLinkedCommandList() Creates a command list based on the button drop list window field
specified.
Field_BDLCreateSubmenu() Adds a submenu to a button drop list control.
Field_BDLGetLinkedItemCommandTag() Retrieves the command tag for a button drop list item that is part of
the command list for a button drop list.
Field_CreateLinkedCommand() Creates a command based on the window field specified.
Field_GetBooleanProperty() Retrieves a specified boolean property for a field.
Field_GetCaption() Retrieves the text caption for the specified field.
Field_GetColor() Retrieves color information for a field.
Field_GetFont() Retrieves the font characteristics for a field.
Field_GetImage() Retrieves the item numbers of the images associated with a push
button or button drop list field.
Field_GetInsertPosFromVisualPos() Retrieves the insertion position of an item in a list field based on its
visual position.
Field_GetIntegerProperty() Retrieves a specified integer property for a field.

10 F U N C T I O N L I B R A R Y R E F E R E N C E

Field (continued)
Field_GetLinkedCommandTag()
Field_GetPosition()
Field_GetRequiredStatus()
Field_GetSelection()
Field_GetSize()
Field_GetStringProperty()
Field_GetToolTip()
Field_GetVisualPosFromInsertPos()
Field_InsertStringInText()
Field_MarkListItems()
Field_ParseText()
Field_SetAltLineColor()
Field_SetBackColor()
Field_SetBooleanProperty()
Field_SetCaption()
Field_SetCustomPromptFormat()
Field_SetFont()
Field_SetFontColor()
Field_SetFontSize()
Field_SetFontStyle()
Field_SetImage()
Field_SetIntegerProperty()
Field_SetPattern()
Field_SetPatternColor()
Field_SetRequiredFormat()
Field_SetRequiredStatus()
Field_SetSelection()
Field_SetStringProperty()
Field_SetToolTip()
Field_SetZoomFormat()
File
File_Count()
File_Delete()
File_GetSize()
File_GetTempDirectory()
File_Probe()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Returns the command tag for the command that was created for the
field.
Returns the current coordinates of the named field’s top left corner.
Ascertains the status of the Show Required Fields menu item.
Retrieves the selected text from a text field.
Retrieves the horizontal and vertical size of a window field.
Retrieves a specified string property for a field.
Returns the tooltip associated with a window field.
Retrieves the visual position of an item in a list field based on its
insertion position.
Inserts a string or string field into a text field.
Marks and unmarks items in a non-native list box with an asterisk.
Parses a text field into string fields.
Specifies colors to use for alternate lines in scrolling windows.
Sets the background color of a field.
Sets a specified boolean property for a field.
Sets the text caption for the specified field.
Specifies display characteristics of prompts.
Sets the font characteristics for a field.
Sets the color of the font used for a field.
Sets the size of the font used for a field.
Sets the style of the font used for a field.
Specifies the default image to use for a push button or button drop
list field.
Sets a specified integer property for a field.
Sets the pattern used for a field.
Sets the color of the pattern used for a field.
Sets the style and color used for prompts linked to required fields.
Checks or unchecks the Show Required Fields menu item.
Selects text in a text field.
Sets a specified string property for a field.
Sets the tooltip for a window field.
Sets the display characteristics of text and field objects whose Zoom
property is true.
Returns the number of files currently open, currently available and the
maximum available for an application.
Deletes a file at the operating system.
Retrieves the size in bytes of the specified file.
Retrieves the complete path to the local temporary folder for the
current user.
Indicates whether a table or file exists in the specified location.
FUNCTION LIBRARY REFERENCE 11
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

File list
FileList_Add() Adds a file to a file list.
FileList_Count() Returns the number of files in the specified file list.
FileList_Create() Creates a new file list.
FileList_Destroy() Frees the memory used for a file list.
FileList_Get() Retrieves the file information for a specific position in the file list.
FileList_Remove() Removes the specified file list item from a file list.
FileList_ShowDialog() Displays a file system dialog box that allows the user to select a set of
files. The selected files are returned as a file list.

File type
FileType_CanAppend() Indicates whether a specified file type can be appended to.
FileType_FillList() Fills a list box with the available file types that the Report Writer can
export to.
FileType_GetExtension() Retrieves the file extension for a specified file type.
FileType_IsValid() Indicates whether a file type is one of the valid types the Report Writer
can export to.

Form
Form_GetWindowGroup() Creates or retrieves a window group for the specified form.

Help pane
HelpPane_Create() Creates a docked HTML Help pane on the right side of the
application’s display area
HelpPane_Destroy() Removes the docked HTML Help pane from the right side of the
application’s display area.
HelpPane_DisplayTopic() Displays the specified topic from an compiled HTML Help file in the
docked help pane.
HelpPane_GetWidth() Retrieves the width of the docked HTML Help pane in the application.
HelpPane_SetTitle() Specifies the title that will appear at the top of the docked HTML Help
pane on the right side of the application’s display area.
HelpPane_SetWidth() Specifies the width of the docked HTML Help pane on the right side of
the application area.
HelpPane_Show() Causes the docked HTML Help pane to be shown or hidden in the
application.

Import
Import_CloseFile() Closes the text file opened using Import_OpenFile().
Import_GetNextField() Returns the value of the current field, and advances to the next field in
a record.
Import_GetNextRecord() Advances to the next record or line in the text file.
Import_OpenFile() Opens a specified text file and reserves a file ID.

12 F U N C T I O N L I B R A R Y R E F E R E N C E

IP
IP_GetIPName()
IP_GetIPNumber()
IP_PingDPS()
Launch
Launch_CountProds()
Launch_FillListWithProds()
Launch_GetFileInfo()
Launch_GetFileName()
Launch_GetProdID()
Launch_GetProdName()
Launch_GetProdPosition()
Launch_ParseFileFromPath()
Launch_ReadDictPath()
Launch_SelectDict()
Launch_SelectFile()
Launch_WriteDictPath()
ListView
ListView_ColumnAdd()
ListView_ColumnCount()
ListView_ColumnGetAlignment()
ListView_ColumnGetLabel()
ListView_ColumnGetPosition()
ListView_ColumnGetSubitem()
ListView_ColumnGetWidth()
ListView_ColumnRemove()
ListView_ColumnSetAlignment()
ListView_ColumnSetLabel()
ListView_ColumnSetPosition()
ListView_ColumnSetWidth()
ListView_GetClickItem()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Returns the host name of the current workstation.
Returns the IP address of the current workstation.
Pings a Process Server workstation to determine whether the Process
Server is running.
Counts the number of products listed in the launch file.
Fills a list field with product names listed in the current launch file.
Fills list fields with product names, product IDs and dictionary
location IDs from the launch file.
Returns the full generic path and launch file name for the currently-
running application.
Returns a product ID based upon a product’s position in the launch
file.
Returns a product’s name from the launch file based upon its product
ID.
Returns the position of the product in the launch file.
Parses a file’s operating system name from a generic pathname.
Returns the location of an application, forms or reports dictionary
from the launch file.
Displays an operating system dialog box, from which you can select a
dictionary location.
Displays an operating system dialog box, from which you can select a
launch file.
Writes the location of an application, forms or reports dictionary to
the launch file.
Adds a column to the list view field.
Retrieves the total number of columns that have been added to a list
view field.
Retrieves the alignment of the specified column of a list view field.
Retrieves the label of the specified column of a list view field.
Retrieves the position of the specified column of a list view field.
Retrieves the number of the subitem associated with the column.
Retrieves the width, in pixels, of the specified column.
Removes the specified column from a list view field.
Specifies the alignment of a column in a list view field.
Sets the label of the specified column of a list view field.
Sets the position of the specified column of a list view field.
Sets the width of the specified column.
Returns the index of the item that was most recently clicked.
FUNCTION LIBRARY REFERENCE 13
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

ListView (continued)
ListView_GetSortColumn() Returns information for the column by which the list view field is
being sorted.
ListView_GetStringWidth() Returns the number of pixels required to fully display a string in the
current font of a specified list view field.
ListView_GetView() Retrieves the current view mode for the specified list view field.
ListView_ItemAdd() Adds an item to a list view field.
ListView_ItemCount() Retrieves the number of items currently in a list view field.
ListView_ItemGetCurrencySubitem() Retrieves a currency or variable currency value from the additional
component of a subitem.
ListView_ItemGetData() Retrieves the long integer data item associated with the specified list
view item.
ListView_ItemGetDateSubitem() Retrieves a date value from the additional component of a subitem.
ListView_ItemGetImage() Retrieves the item numbers of the images associated with the
specified list view item.
ListView_ItemGetIntSubitem() Retrieves an integer or long integer value from the additional
component of a subitem.
ListView_ItemGetLabel() Retrieves the label of the specified list view item.
ListView_ItemGetStateImage() Retrieves the item number of the state image associated with the
specified list view item.
ListView_ItemGetSubitem() Retrieves a subitem from the specified list view item.
ListView_ItemGetTimeSubitem() Retrieves a time value from the additional component of a subitem.
ListView_ItemMakeVisible() Makes the specified item in a list view field visible.
ListView_ItemRemove() Removes the specified item from a list view field.
ListView_ItemSetCurrencySubitem() Sets the value of the additional component of a subitem to a currency
or variable currency value.
ListView_ItemSetData() Sets the data item associated with the specified list view item.
ListView_ItemSetDateSubitem() Sets the value of the additional component of a subitem to a date
value.
ListView_ItemSetImage() Sets the item image associated with the specified list view item.
ListView_ItemSetIntSubitem() Sets the value of the additional component of a subitem to an integer
or long integer value.
ListView_ItemSetLabel() Sets the label of the specified list view item.
ListView_ItemSetStateImage() Sets the state image associated with the specified list view item.
ListView_ItemSetSubitem() Sets the value of a subitem for the specified list view item.
ListView_ItemSetTimeSubitem() Sets the value of the additional component of a subitem to a time
value.
ListView_SelectionCount() Retrieves the number of items currently selected in a list view field.
ListView_SelectionGet() Retrieves the item index of the specified item in the selection.
ListView_SelectionSet() Changes the selection in a list view field.
ListView_SetEmptyMessage() Specifies the message to display when the list view doesn’t contain
any items.
ListView_SetSortColumn() Specifies the column by which a list view field is sorted.
ListView_SetView() Sets the view mode for the specified list view field.
ListView_Sort() Sorts the items in a list view field.

14 F U N C T I O N L I B R A R Y R E F E R E N C E

Login
Login_AlterLogin()
Login_CreateLogin()
Login_DropLogin()
Login_ExitDataSource()
Login_GetDataSources()
Login_GetDBMSInfo()
Login_GetInfo()
Login_GetLoginSettings()
Login_LogIntoDataSource()
Login_LogIntoDataSourceEx()
Login_OpenDexDialog()
Login_VerifyInfo()
Mail
Mail_AddressListAdd()
Mail_AddressListCount()
Mail_AddressListCreate()
Mail_AddressListDestroy()
Mail_AddressListGet()
Mail_AddressListRemove()
Mail_DisplayAddressDialog()
Mail_DisplayReplyToDialog()
Mail_GetServerType()
Mail_GetSessionAddress()
Mail_IsLoggedOn()
Mail_LogOff()
Mail_LogOn()
Mail_ResolveAddress()
Mail_Send()
Mail_SendDialog()
Mail_SetServerType()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Changes the characteristics of a SQL login.
Creates a new SQL login.
Drops a SQL login.
Disconnects a user from the current data source.
Fills a list box or drop-down list with the names of all available data
sources.
Retrieves information about the ODBC driver and data source being
used
Returns the names of the data source and user ID associated with the
current client’s connection to the server.
Retrieves the login options for the specified SQL login.
Logs the user into the named data source.
Logs the user into the named data source. It also supports the
additional password features available for SQL Server 2005.
Logs a user into the named data source using Dexterity’s predefined
Login window.
Verifies whether the specified user ID and password are a valid
combination for access to the named data source.
Adds an address to the specified address list.
Returns the number of addresses in the specified address list.
Creates a list that will contain addresses to which a mail message will
be sent or replies returned to.
Removes the specified address list from memory.
Retrieves an address from the specified address list.
Removes an address from the specified address list.
Displays the mail message addressing dialog that allows a user to
specify who a message will be sent to.
Displays the mail message addressing dialog that allows the user to
select who message replies will be sent to
Retrieves the type of server that is being used for the current session.
Retrieves the address from the current mail profile.
Indicates whether the application is currently logged on to a mail
session.
Closes the mail session on the current workstation.
Creates a mail session on the current workstation.
Attempts to match a search string to an e-mail address in the address
book.
Sends a message to the members of a specified address list.
Sends a message to the members of a specified address list.
Specifies the type of connection to use for the mail server.
FUNCTION LIBRARY REFERENCE 15
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

MAPI
MAPI_AddAddress() Adds an address to the specified address list.
MAPI_CountAddresses() Returns the number of addresses in the specified address list.
MAPI_CreateAddressList() Creates a list that will contain addresses to which a mail message will
be sent.
MAPI_DestroyAddressList() Removes the specified address list from memory.
MAPI_DisplayDialog() Displays the MAPI message addressing dialog.
MAPI_GetAddress() Retrieves an address from the specified address list.
MAPI_IsLoggedOn() Indicates whether the application is logged on to a MAPI session.
MAPI_IsMailEnabled() Indicates whether the current workstation supports MAPI.
MAPI_ProfileGetAddress() Retrieves the name and e-mail address from the profile for the current
user.
MAPI_LogOff() Closes the MAPI session on the current workstation.
MAPI_LogOn() Creates a MAPI session on the current workstation.
MAPI_PropertyListCount() Retrieves the number of properties in a property list.
MAPI_PropertyListCreate() Creates a list that will contain properties that specify characteristics of
an e-mail message.
MAPI_PropertyListDestroy() Removes the specified property list from memory.
MAPI_PropertyListGetValue() Retrieves the value of a property from the specified property list.
MAPI_PropertyListGetValueByIndex() Retrieves the value of a property from the specified property list,
based on the index.
MAPI_PropertyListSetValue() Sets the value of a property in the specified property list.
MAPI_RemoveAddress() Removes an address from the specified address list.
MAPI_ResolveAddress() Attempts to match a search string to an e-mail address in the address
book.
MAPI_Send() Sends a message to the members of a specified address list.
MAPI_SendDialog() Sends a message to the members of a specified address list. A mail
dialog will be displayed for each message sent.

Menu
Menu_Invoke() Causes a menu item to be invoked, just as if it had been selected by
the user.

Menu bar
MenuBar_AddMenu() Adds a command list to the menu bar.
MenuBar_RemoveAllMenus() Removes all menus from the menu bar.
MenuBar_RemoveMenu() Removes the specified menu from the menu bar.

OLE
OLE_CloseNote() Closes the specified OLE container file.
OLE_DeleteNote() Closes the specified OLE container file (if open) and deletes it.
OLE_Exit() Closes the OLE container application.

16 F U N C T I O N L I B R A R Y R E F E R E N C E

OLE (continued)
OLE_IsNoteEnabled()
OLE_OpenNote()
OLE_SaveNote()
Path
Path_ChangeDefault()
Path_CreateFolder()
Path_DoesExist()
Path_GetForApp()
Path_MakeGeneric()
Path_MakeNative()
Path_ParseFileFromPath()
Path_ParsePathFromPath()
Path_SelectPathname()
Printer
Printer_Define()
Printer_GetName()
Printer_SetDestination()
Registry
Registry_DeleteKey()
Registry_DeleteValue()
Registry_GetProtectedString()
Registry_GetValue()
Registry_SetKeyValue()
Registry_SetProtectedKeyString()
Report
Report_Begin()
Report_DoubleLine()
Report_End()
Report_GetPageRemaining()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Ascertains whether the current operating environment can support
the OLE container application.
Opens the specified OLE container file and sets the window title of the
OLE container application.
Saves the specified OLE container file.
Changes the default location for tables with a Pathname table series.
Creates a new folder or directory.
Indicates whether the specified path exists.
Returns the generic path of various components of the current
installation, such as the runtime engine or launch file.
Converts a native pathname to a generic pathname.
Converts a generic pathname to a native pathname.
Parses a file’s operating system name from a generic path.
Parses the path name from a generic path.
Allows a user to indicate the location of a file, and returns a generic
pathname to that location.
Allows a Windows user to define a named printer destination.
Returns the name of a printer defined using the Printer_Define()
function.
Changes the application’s default printer destination on a Windows
workstation.
Deletes the specified key from the registry
Deletes the specified value from the registry.
Retrieves and decrypts the specified value from the
HKEY_CURRENT_USER subtree and key.
Retrieves the specified value from the registry.
Sets the specified value in the registry.
Encrypts and sets the specified value for the HKEY_CURRENT_USER
subtree and key.
Starts a Quick Report.
Draws a double line in the current band.
Completes the processing of a Quick Report.
Returns how much vertical area of the page remains, not including
the current band.
FUNCTION LIBRARY REFERENCE 17
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

Report (continued)
Report_GetPageSize() Returns the printable width and height of the page, based on the
settings for the currently-selected printer.
Report_GetStringWidth() Returns the width of a string using the font, size, and style specified.
Report_NewBand() Creates a new band in the report.
Report_NewPage() Creates a new page for the report.
Report_ReadyToRun() Verifies that a new Quick Report can be run.
Report_SetFont() Specifies the characteristics of the font to use for the Quick Report.
Report_SingleLine() Draws a single line in the current band.
Report_WriteText() Adds a text string to the current band.

Resource
Resource_EndSeriesFill() Releases resources that have been read into memory by the
Resource_StartSeriesFill() function.
Resource_FillSeriesList() Fills two list fields with the display names and technical names of
resources of a specified resource type and series.
Resource_GetDisplayName() Returns a string containing the display name of a specified resource
in an application dictionary.
Resource_GetID() Returns the resource ID for a specified resource type and name.
Resource_GetInfo() Returns the resource ID and resource name for a form, report, table or
table group for a specified series.
Resource_GetNthResource() Returns the resource ID, name, and series of the specified resource.
Resource_GetResourceName() Returns the name for a specified resource type and ID.
Resource_GetSubResourceName() Returns the name for a specified subresource of a primary resource.
Resource_StartSeriesFill() Returns the number of resources of a specific type for a series.

Runtime
Runtime_GetClientType() Returns the type of runtime engine that is processing the application.
Runtime_GetCPUType() Returns information about the processor on which the application is
being run.
Runtime_GetCurrentProductID() Returns the product ID of the application dictionary that contains the
script executing this function.
Runtime_GetModuleInfo() Retrieves the major and minor version numbers and the build
number from the application dictionary.
Runtime_GetOSBuildInfo() Returns build information for the operating system on which the
application is being run.
Runtime_GetOSInfo() Returns information about the operating system on which the
application is being run.
Runtime_GetVersionNum() Returns a string describing the current version of the runtime engine.
Runtime_GetWebClientTrustLevel() Returns an integer indicating the trust level of the Silverlight
application for the web client.
Runtime_SetAboutMenu() Allows you to change the application name in the About menu item.
Runtime_SetFieldEnterMode() Changes the functionality of the ENTER key to act as the TAB key.
Runtime_SetIcon() Allows you to specify which icons will be displayed in the application.

18 F U N C T I O N L I B R A R Y R E F E R E N C E

Script log
ScriptLog_Start()
ScriptLog_Stop()
Script profiler
ScriptProfile_Clear()
ScriptProfile_Save()
ScriptProfile_Start()
ScriptProfile_Stop()
Shell
Shell_DisplayNotification()
SQL
SQL_Clear()
SQL_Connect()
SQL_Execute()
SQL_FetchNext()
SQL_GetData()
SQL_GetError()
SQL_GetNextResults()
SQL_GetNumCols()
SQL_GetNumRows()
SQL_Terminate()
Table
Table_AutoShrink()
Table_Compare()
Table_CopyShrinkRecords()
Table_CreateIndexes()
Table_CreateProcedures()
Table_DisableErrorChecks()
Table_DropProcedures()
Table_EndConversion()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Starts logging scripts, writing the script log to the specified output
file.
Stops logging scripts, closing the current output file.
Clears the script profile currently in memory.
Saves the script profile currently in memory to the specified output
file.
Causes the application to start profiling scripts.
Causes the application to stop profiling scripts.
Causes a notification to be displayed in the lower-right corner of the
display.
Clears any results sets and errors for the specified pass-through SQL
connection.
Creates a new pass-through SQL connection.
Executes a SQL string.
Retrieves the next row from the current results set.
Returns data in the specified column in the current row of the current
results set.
Returns information about the last error that occurred.
Moves to the next results set.
Returns the number of columns in the current results set.
Returns the number of rows that were affected by a write operation.
Deletes the specified pass-through SQL connection.
Shrinks a data table and rebuilds the table’s indexes.
Compares the structure of an existing table in the current data source
to that table’s definition in the application dictionary.
Copies a record from an original table to a temporary table created
using Table_StartShrink().
Creates the indexes for the specified table on a data source.
Creates the stored procedures for the specified table on a data source.
Makes Dexterity to ignore automatic error checking for table
operations.
Drops the stored procedures for the specified table on a data source.
Finishes a table conversion.
FUNCTION LIBRARY REFERENCE 19
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

Table (continued)
Table_EndShrink() Closes the shrink table and finishes the table shrink.
Table_FillGroupList() Fills a list field with the names of the table groups from a series.
Table_FillList() Fills a list field with the names of tables from the specified table
group.
Table_FlushCache() Clears the table cache for all closed tables.
Table_GetAutoShrinkMode() Indicates whether the current database manager is capable of
conducting a table shrink using Table_AutoShrink() or rebuilding a
table’s indexes using Table_RebuildIndexes().
Table_GetDisplayName() Returns the display name for a specified table.
Table_GetFieldList() Retrieves the names of the fields in the specified table.
Table_GetKeyFieldList() Returns the list of fields that are part of the specified key
Table_GetGroup() Returns the resource ID of the table group a specified table is part of.
Table_GetKeyInfo() Returns information about a key in the specified table.
Table_GetKeyOption() Returns information about the key options for a key.
Table_GetNumberOfKeys() Returns the number of keys that are defined for the specified table.
Table_GetOSName() Returns the operating system name being used for a table.
Table_GetRangeKey() Retrieves the key used for the range applied to the specified table.
Table_GetSeries() Returns an integer corresponding to the series the specified table is
part of.
Table_GetSQLErrorText() Retrieves a block of SQL error text for the last SQL error that occurred.
Table_IsRangeSet() Ascertains whether a range is currently set for the specified table.
Table_OpenAsTemp() Creates a “clone” of the table specified. The clone will be a temporary
table with exactly the same structure as the table supplied.
Table_OpenNewBuffer() Creates a new table buffer and reference to the table specified.
Table_RebuildIndexes() Rebuilds the indexes for a table that stores data using the
c-tree Plus database manager.
Table_SetCreateMode() Allows you to choose whether tables that don’t already exist will be
created automatically at runtime.
Table_SetDBType() Sets a default database type for an application.
Table_SetDeleteOptions() Allows you to choose whether a delete all or drop will be executed
when the delete table statement is used.
Table_SetRefreshFlags() Sets the refresh flags for each client buffer associated with the named
table.
Table_StartConversion() Opens the old and new table definitions for exclusive use so data can
be converted.
Table_StartShrink() Creates a temporary data table that can be used to store data from an
original table that’s being shrunk.
Table_Truncate() Removes all records from a named table, leaving the table structure
intact in the database.
Table_VerifyRecord() Verifies the contents of the fields in a record for the specified table.

Text file
TextFile_Close() Closes a text file opened by the TextFile_Open() function.

20 F U N C T I O N L I B R A R Y R E F E R E N C E

Text file (continued)
TextFile_Open()
TextFile_ReadLine()
TextFile_ReadText()
TextFile_WriteDOS()
TextFile_WriteLine()
TextFile_WriteText()
Timer
Timer_Sleep()
Tools
Tools_CloseDUOSTable()
Tools_DisableLoadBalancing()
Tools_EnableCommandMenus()
Tools_EnableCustomizationMaintenance()
Tools_EnableCustomizationStatus()
Tools_EnableImport()
Tools_EnableLoadBalancing()
Tools_EnableModifier()
Tools_EnableReportWriter()
Tools_GetTranLevel()
Tools_IsAppProcessServer()
Tools_IsScriptRemote()
Tools_OpenDUOSTable()
Tree view
TreeView_AddNode()
TreeView_CollapseNode()
TreeView_CountChildren()
TreeView_CountNodes()
TreeView_ExpandNode()
TreeView_GetClickNode()
TreeView_GetCollapsingNode()
TreeView_GetExpandingNode()
TreeView_GetFirstChild()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Opens a specified text file.
Reads a line from a file opened by the TextFile_Open() function.
Reads a specified number of characters from a text file opened by the
TextFile_Open() function.
Writes a line to a text file opened by the TextFile_Open() function,
using the DOS text format.
Writes a line to a text file opened by TextFile_Open().
Writes a line to a text file opened by the TextFile_Open() function
without including a line feed or carriage return.
Causes the application to wait for the specified period of time.
Closes the DUOS table available to the Visual Basic® for Applications
(VBA) environment.
Disables load balancing on a process server or client workstation.
Causes command-based menus to be used for an application, rather
than resource-defined menus.
Enables the Customization Maintenance menu item.
Enables the Customization Status menu item.
Enables the Import Utility.
Enables load balancing on a process server or client workstation.
Enables the Modifier.
Enables the Report Writer.
Indicates whether a database transaction is currently active.
Returns whether the application is running on the Process Server.
Returns whether the current script is being processed remotely on a
process server.
Opens the DUOS table available to the Visual Basic for Applications
(VBA) environment.
Adds a new child node to the specified node in a tree view field.
Collapses the specified node.
Returns the number of children for the specified node.
Returns the entire number of nodes in a tree view field.
Expands the specified node.
Returns the ID of the node whose state image was clicked.
Returns the ID of the node that is being collapsed.
Returns the ID of the node that is being expanded.
Returns the ID of the first child node for the specified parent node.
FUNCTION LIBRARY REFERENCE 21
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

Tree view (continued)

TreeView_GetNextNode() Returns the ID of the next sibling for the specified node.
TreeView_GetNodeData() Returns the long integer data item associated with a node.
TreeView_GetNodeImage() Returns an integer indicating the image associated with a node.
TreeView_GetNodeLabel() Returns the label for the specified node.
TreeView_GetNodeStateImage() Retrieves the item number of the state image associated with the
specified node.
TreeView_GetParent() Returns the node ID of the parent of the specified node.
TreeView_GetPreviousNode() Returns the ID of the preceding sibling for the specified node.
TreeView_GetRootNode() Returns the ID of the first root-level node.
TreeView_GetSelectedNode() Returns the ID of the currently-selected node.
TreeView_IsParentNode() Indicates whether a specific node is a parent node.
TreeView_MakeNodeVisible() Ensures that the specified node is visible in the tree.
TreeView_RemoveChildren() Removes the child nodes for the specified parent node.
TreeView_RemoveNode() Deletes the specified node.
TreeView_SetNodeData() Sets the data item associated with the specified node.
TreeView_SetNodeImage() Specifies the image to use for the specified node.
TreeView_SetNodeLabel() Sets the label for the specified node.
TreeView_SetNodeStateImage() Sets the state image associated with the specified node.
TreeView_SetSelectedNode() Makes the specified node selected and visible.

Trigger
Trigger_CausedByProduct() Used in a trigger processing procedure of a database trigger to find
out which product caused the trigger to activate.
Trigger_DisableSingle() Disables a specific trigger.
Trigger_Enable() Enables or disables all client-side triggers for an application.
Trigger_EnableSingle() Enables a specific trigger.
Trigger_GetCurrentTag Used in a trigger processing procedure to retrieve the tag associated
with the current trigger.
Trigger_IsTriggerEnabled() Returns a boolean indicating whether a specific trigger is enabled.
Trigger_RegisterDatabase() Registers a database trigger for use with the runtime engine.
Trigger_RegisterDatabaseByName() Registers a database trigger for a table in the specified dictionary.
Trigger_RegisterFocus() Registers a focus trigger for use with the runtime engine.
Trigger_RegisterFocusByName() Registers a focus trigger for a resource in the specified dictionary.
Trigger_RegisterForm() Registers a form trigger for use with the runtime engine.
Trigger_RegisterFormByName() Registers a form trigger for a form in the specified dictionary.
Trigger_RegisterFunction() Registers a function trigger for use with the runtime engine.
Trigger_RegisterFunctionByName() Registers a function trigger for a function in the specified dictionary.
Trigger_RegisterProcedure() Registers a procedure trigger for use with the runtime engine.
Trigger_RegisterProcedureByName() Registers a procedure trigger for a procedure in the specified
dictionary.
Trigger_Unregister() Unregisters a specific trigger.

22 F U N C T I O N L I B R A R Y R E F E R E N C E

Utility
Utility_DecodeString()
Utility_DecryptTableString()
Utility_EncodeString()
Utility_EncryptTableString()
Utility_LaunchUrl()
Utility_LoadDLL()
Utility_SubstituteTokens()
Utility_UnloadDLL()
Window
Window_ForceRedraw()
Window_GetMainWindowTitle()
Window_GetPosition()
Window_GetRibbonCommandTag()
Window_GetSize()
Window_GetState()
Window_GetTitle()
Window_GetTitleByProduct()
Window_PullFocus()
Window_SetBaseSize()
Window_SetLineMode()
Window_SetState()
Window group
WindowGroup_AddWindow()
WindowGroup_SetBooleanProperty()
WindowGroup_SetPosition()
WindowGroup_SetSize()
WindowGroup_SetState()
WindowGroup_SetStringProperty()
WinHelp
WinHelp_ALinkLookup()
WinHelp_GetCurWindow()
PA RT 1 F U N C T I O N L I B R A R Y S U M M A R Y
Decodes a string that was encoded by the Utility_EncodeString()
function.
Decrypts a string that has been stored in a table in encrypted format.
Converts a string into a format that isn’t easily readable by users or
other applications.
Encrypts a string using the same method that Dexterity uses when
storing encrypted strings in tables.
Opens a web browser and displays the content of the specified URL.
Loads the specified DLL into memory.
Replaces product tokens in a string with the corresponding product
names.
Removes the specified DLL from memory.
Forces a window to be redrawn.
Returns the window title of a form’s main window.
Returns the coordinates of a window’s top left corner.
Retrieves the command tag for the root command list that defines the
ribbon for a window.
Returns the width and height, in pixels, of a window.
Retrieves the visual state for a window.
Returns the title of the specified window.
Returns the title of a window in a specified dictionary.
Pulls the focus from the specified window.
Sets the size of the window without resizing any of the controls in the
window.
Changes the window type of the scrolling window.
Sets the visual state for a window.
Adds a window to the specified window group.
Sets the value of a boolean property for the specified window group.
Changes the position of a window group.
Changes the size of a window group.
Sets the visual state for a window group.
Sets the value of a string property for the specified window group.
Starts the help engine, indicating the help file to be used, and displays
the topic corresponding to the ALink (associative link) value specified.
Returns the resource ID of the current window.
FUNCTION LIBRARY REFERENCE 23
PA RT 1 F U N C T I O N L IB R A R Y S U M M A R Y

WinHelp (continued)
WinHelp_GetFieldContextNumber() Returns the context number for the selected field.
WinHelp_GetHelpType() Returns an integer indicating the type of help requested.
WinHelp_GetWindowContextNumber() Returns the context number for the current window.
WinHelp_InvokeHelp() Starts the help engine, indicating the help file, help command and
context number to be used.
WinHelp_LaunchUrl() Launches help content for the Microsoft Dynamics GP web client.
WinHelp_RegisterHelpProcedure() Indicates which procedure script to call when help is accessed.
WinHelp_RunHelpMacro() Specifies a help file and the help macro or macros to run.
WinHelp_Search() Starts the help engine and searches for the specified keyword in the
help file indicated.

24 F U N C T I O N L I B R A R Y R E F E R E N C E
PART 2: FUNCTION LIBRARIES
 Part 2: Function Libraries
This part provides detailed descriptions of the functions available in the
various function libraries for Dexterity. Each function includes a
description, syntax, parameter list and examples of the function’s use.

26 F U N C T I O N L I B R A R Y R E F E R E N C E
 Activity tracking function library
Refer to Chapter 6, Use the functions in this library when developing an activity tracking
“Activity Tracking,” in system in your application. This library contains the following functions:
the Dexterity Stand-
Alone Application • Activity_GetBackgroundStatus()
Guide for more • Activity_GetExitMode()
information. • Activity_GetResourceName()

FUNCTION LIBRARY REFERENCE 27

A C T I V I T Y _ G E T B A C K G R O U N D S T A T U S ( )

Activity_GetBackgroundStatus()
Description
The Activity_GetBackgroundStatus() function ascertains whether the
runtime engine’s process queue contains any background procedures. You
designate background procedures using the background parameter of the
call statement.

Syntax Activity_GetBackgroundStatus()

Parameters • None

Return value A boolean indicating the result; true if the function succeeded, false if it
didn’t succeed.

Comments The runtime engine displays a message automatically if a user attempts to

exit an application when background processes remain in the process
queue.

View background processes using the Process Monitor window. Use the
Process Monitor inherited action in the Menu Definition window to allow
the Process Monitor to be opened from within an application.

Examples This example displays a message indicating whether background processes

are running.

if Activity_GetBackgroundStatus() then
warning "A background process is currently active. Display the
➥ Process Monitor to view background processes.";
else
warning "No background processes are running at this time.";
end if;

Related items Commands

call

28 F U N C T I O N L I B R A R Y R E F E R E N C E
 A C T I V I T Y _G E T E X I T M O D E ()

Activity_GetExitMode()
Description The Activity_GetExitMode() function ascertains the mode used to exit the
runtime engine. You exit the runtime engine by exiting the application, or
by accessing the Modifier or Report Writer.

Syntax Activity_GetExitMode()

Parameters • None

Return value mode – An integer representing one of the following exit modes:

Value Description
0 The runtime engine closed.
1 The Report Writer was accessed.
2 The Modifier was accessed.

Comments Add this function to a form post script for the application’s Main Menu
form. This ensures that you can determine the exit mode, regardless of
where the user chooses to exit the runtime session.

Examples This example logs the date and time the user closed the runtime engine,
accessed the Modifier, or accessed the Report Writer. It’s attached as a post
script for the Main Menu form.

local integer l_mode;

local date l_date;
local time l_time;

l_mode = Activity_GetExitMode();
l_date = sysdate();
l_time = systime();

if l_mode = 0 then
call Activity_Log, "Exited application", l_date, l_time;
elseif l_mode = 1 then
call Activity_Log, "Entered Report Writer", l_date, l_time;
else
call Activity_Log, "Entered the Modifier", l_date, l_time;
end if;

Related items Commands

Tools_EnableModifier(), Tools_EnableReportWriter()

FUNCTION LIBRARY REFERENCE 29

A C T I V I T Y _ G E T R E S O U R C E N A M E ( )

Activity_GetResourceName()
Description The Activity_GetResourceName() function returns a string containing a
resource’s display name.

Syntax Activity_GetResourceName(product_ID, resource_type, resource_ID)

Parameters • product_ID – An integer specifying the product ID of the dictionary where

the resource is located.

• resource_type – An integer specifying the type of resource. Use one of the

following constants:

Constant Description
FORMTYPE Indicates a form.
TABLETYPE Indicates a table.
GROUPTYPE Indicates a table group.
REPORTTYPE Indicates a report.

• resource_ID – An integer specifying the resource ID of the resource.

Return value A string containing the display name of the resource.

Comments If you implement activity tracking in your application, you can use this
function in conjunction with the Security procedure to retrieve names of
windows, table groups and reports accessed by the user. The Security
procedure runs each time a form, report or table is accessed. The runtime
engine automatically passes a product ID, resource type and resource ID in
parameters to this procedure. With this information, the
Activity_GetResourceName() function can determine the resource’s
display name, and store the name in an activity table (see the following
example).

The resource_type parameter automatically passed to the Security procedure

will indicate a form, report or table group, but not an individual table. To
track table access, be sure you use Dexterity Utilities to place each table into
a table group.

30 F U N C T I O N L I B R A R Y R E F E R E N C E
 A C T I V I T Y _ G E T R E S O U R C E N A M E ()

Examples The following Security procedure returns the product ID, resource type and
resource ID of a form, report or table group accessed during runtime. It
passes these values to a procedure that updates an activity table.

in integer l_prod_ID;
in integer l_resource_type;
in integer l_resource_ID;

call Add_User_Activity_Record, l_prod_ID, l_resource_type,

➥ l_resource_ID;

The product_ID, resource_type and resource_ID are passed from the Security
procedure to the Add_User_Activity_Record procedure shown in the
following example. The Activity_GetResourceName() function uses these
values to find out the display name of the resource. A new record is then
added to the Activity Master table.

in integer l_prod_ID;
in integer l_resource_type;
in integer l_resource_ID;

'Resource Name' of table 'Activity Master' =

➥ Activity_GetResourceName(l_prod_ID, l_resource_type,
➥ l_resource_ID);
'User Name' of table 'Activity Master' = 'User ID' of globals;
'System Time' of table 'Activity Master' = systime();
'System Date' of table 'Activity Master' = sysdate();
'Resource Type' of table 'Activity Master' = l_resource_type;
save table 'Activity Master';

Related items Commands

Window_GetTitle(), Window_GetMainWindowTitle(),
Window_GetTitleByProduct(), Table_GetDisplayName(), Dict_GetName()

Additional information
Chapter 5, “Security,” in the Stand-Alone Application Guide

FUNCTION LIBRARY REFERENCE 31

32 F U N C T I O N L I B R A R Y R E F E R E N C E
 Auto-complete function library
Refer to String fields Use the functions in this library when adding auto-complete capability to
on page 74 of Volume 2 fields in your application. This library contains the following functions:
of the Dexterity Pro-
grammer’s Guide for • AutoComplete_AddStringValue()
more information • AutoComplete_RemoveAllData()
about implementing • AutoComplete_RemoveFieldData()
auto-complete capabil- • AutoComplete_RemoveStringValue()
ity for fields. • AutoComplete_SetMode()
• AutoComplete_SetOptions()

FUNCTION LIBRARY REFERENCE 33

A U T O C O M P L E T E _ A D D S T R I N G V A L U E ( )

AutoComplete_AddStringValue()
Description The AutoComplete_AddStringValue() function adds an auto-complete
value for the specified field.

Syntax AutoComplete_AddStringValue(field field_name, value)

Parameters • field field_name – The field for which the auto-complete value is being
added. The field must be on a window that is currently open in the
application.

• value – A string containing the value to add.

Return value A boolean. True indicates the string was added, while false indicates it was
not.

Examples The following example is the pre script for a window. It uses the
AutoComplete_AddStringValue() function to add several auto-complete
values to the City field.

local boolean result;

result = AutoComplete_AddStringValue(field City, "Fargo");

result = AutoComplete_AddStringValue(field City, "Redmond");
result = AutoComplete_AddStringValue(field City, "Watertown");

34 F U N C T I O N L I B R A R Y R E F E R E N C E
 A U T O C O M P L E T E _ R E M O V E A L L D A T A ()

AutoComplete_RemoveAllData()
Description The AutoComplete_RemoveAllData() function removes all of the auto-
complete data for the user currently logged into the workstation.

Syntax AutoComplete_RemoveAllData()

Parameters • None

Return value A boolean. True indicates the data was removed, while false indicates it was
not.

Examples The following example uses the AutoComplete_RemoveAllData() function

to remove all auto-complete data for the user currently logged into the
workstation.

local boolean result;

result = AutoComplete_RemoveAllData();

FUNCTION LIBRARY REFERENCE 35

A U T O C O M P L E T E _ R E M O V E F I E L D D A T A ()

AutoComplete_RemoveFieldData()
Description The AutoComplete_RemoveFieldData() function removes the auto-
complete data for the specified field for the user currently logged into the
workstation.

Syntax AutoComplete_RemoveFieldData(field field_name)

Parameters • field field_name – The field for which the auto-complete value is being
removed. The field must be on a window that is currently open in the
application.

Return value A boolean. True indicates the data was removed, while false indicates it was
not.

Examples The following example is a form post script that uses the
AutoComplete_RemoveFieldData() function to remove all auto-complete
data for the City field.

local boolean result;

result = AutoComplete_RemoveFieldData(field City);

36 F U N C T I O N L I B R A R Y R E F E R E N C E
 A U T O C O M P L E T E _ R E M O V E S T R I N G V A L U E ()

AutoComplete_RemoveStringValue()
Description The AutoComplete_RemoveStringValue() function removes the specified
string from the auto-complete data for the specified field.

Syntax AutoComplete_RemoveStringValue(field field_name, value)

Parameters • field field_name – The field for which the auto-complete value is being
removed. The field must be on a window that is currently open in the
application.

• value – A string containing the value to remove.

Return value A boolean. True indicates the value was removed, while false indicates it
was not.

Examples The following example is a form post script that uses the
AutoComplete_RemoveStringValue() function to remove the value
“Fargo” from the auto-complete data for the City field.

local boolean result;

result = AutoComplete_RemoveStringValue(field City, "Fargo");

FUNCTION LIBRARY REFERENCE 37

A U T O C O M P L E T E _ S E T M O D E ( )

AutoComplete_SetMode()
Description The AutoComplete_SetMode() function enables or disables auto-complete
for the application.

Syntax AutoComplete_SetMode(mode)

Parameters • mode – A long integer that enables or disables auto-complete for the
application. The value corresponds to one of the following constants:

Constant Description
AUTOCOMPLETE_MODE_ENABLED Turns auto-complete on
AUTOCOMPLETE_MODE_DISABLED Turns auto-complete off

Return value A long integer that indicates the previous setting for the auto-complete
mode.

Comments To enable auto-complete for an individual field, you must set the
AutoComplete property for the field to True.

Examples The following example reads a setting from the DEX.INI file and uses the
AutoComplete_SetMode() function to enable or disable auto-complete for
the application.

local long prev_setting;

local string auto_complete;

auto_complete = upper(Defaults_Read("AutoComplete"));

if auto_complete = "TRUE" then

prev_setting = AutoComplete_SetMode(AUTOCOMPLETE_MODE_ENABLED);
else
prev_setting = AutoComplete_SetMode(AUTOCOMPLETE_MODE_DISABLED);
end if;

38 F U N C T I O N L I B R A R Y R E F E R E N C E
 A U T O C O M P L E T E _ S E T O P T I O N S ()

AutoComplete_SetOptions()
Description The AutoComplete_SetOptions() function sets several options for auto-
complete functionality.

Be sure this function is run only when all forms that contain auto-complete fields
have been closed. Otherwise, auto-complete items won’t be saved in the correct
location.

Syntax AutoComplete_SetOptions(folder_name, max_items, max_age)

Parameters • folder_name – A string value that specifies the name of the folder that will
contain the auto-complete files. This additional folder will be located in the
\Application Data\Microsoft Business Solutions\Product_Name\ folder for
the user currently logged into the workstation. The Product_Name will
depend on the name you’ve given your application.

Use this parameter when you want your application to have multiple sets
of auto-complete items, such as one set for each different company. If you
don’t want multiple sets of auto-complete items, specify the empty string
("").

• max_items – An optional integer that specifies the maximum number of

auto-complete items each field can have. The value can range from 6 to
32,000. If this number is exceeded for a field, the oldest auto-complete item
for the field is removed.

• max_age – An optional integer that specifies in days how long auto-

complete items should remain in the auto-complete data. Each time an
auto-complete item is selected, it is updated with the workstation’s current
system date. If the age of an auto-complete item exceeds the specified limit,
the item will be removed. The value 0 (zero) indicates auto-complete items
will be kept forever.

Return value Nothing.

Examples The following example is a portion of the form pre script for the Main Menu
form. It uses the AutoComplete_SetOptions() function to specify the
maximum number of items and age for auto-complete items.

AutoComplete_SetOptions("",100,5);

FUNCTION LIBRARY REFERENCE 39

40 F U N C T I O N L I B R A R Y R E F E R E N C E
Color function library
Several function library functions in Dexterity allow you to specify the
colors of items such as fields and prompts. These functions list the 17 colors
predefined in Dexterity. You can use the functions in the Color function
library to define new colors that can be used with any of these functions.
This library contains the following functions:

• Color_ConvertNameToValue()
• Color_ConvertRGBToValue()
• Color_ConvertValueToName()
• Color_ConvertValueToRGB()
• Color_GetFromDialog()
• Color_ResetSystemColor()
• Color_SetSystemColor()

FUNCTION LIBRARY REFERENCE 41

C O L O R _ C O N V E R T N A M E T O V A L U E ( )

Color_ConvertNameToValue()
Description The Color_ConvertNameToValue() function converts a Dexterity
predefined color name to the corresponding color value.

Syntax Color_ConvertNameToValue(color_name)

Parameters • color_name – A string containing a Dexterity predefined color name. The

following table lists the predefined color names for Dexterity:

Black Medium Gray

Blue Pink
Bright Green Red
Dark Blue Teal
Dark Red Turquoise
Dark Yellow Violet
Green White
Light Gray Yellow
Light Yellow

Return value A long integer containing the color value. If an invalid color name is passed
to this function, the value 0 is returned.

Examples In the following example, the names of the Dexterity predefined

colors have been added to the Colors drop-down list. The
Color_ConvertNameToValue() function is used to return the color value of
the selected color.

local string color_name;

local long selected_color;

if Colors <> 0 then

{A color is selected.}
color_name = itemname(Colors, Colors);
selected_color = Color_ConvertNameToValue(color_name);
else
error "No color selected.";
end if;

42 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O L O R _ C O N V E R T RG BT O V A L U E ()

Color_ConvertRGBToValue()
Description The Color_ConvertRGBToValue() function converts red, green and blue
color levels to a color value.

Syntax Color_ConvertRGBToValue(red_level, green_level, blue_level)

Parameters • red_level – An integer specifying the level of red in the color. The value must
be between 0 and 255.

• green_level – An integer specifying the level of green in the color. The value
must be between 0 and 255.

• blue_level – An integer specifying the level of blue in the color. The value
must be between 0 and 255.

Return value A long integer containing the color value.

Comments The colors created by this function look best when the system is displaying
at least 65,535 colors. Otherwise, the colors may appear dithered.

Examples The following example uses the Color_ConvertRGBToValue() function to

create a light blue color to use for alternate lines of scrolling windows.

local boolean result;

local long color_value;

color_value = Color_ConvertRGBToValue(215, 245, 251);

result = Field_SetAltLineColor(color_value, COLOR_BLACK, color_value,
➥ PATTERN_NONE);

FUNCTION LIBRARY REFERENCE 43

C O L O R _ C O N V E R T V A L U E T O N A M E ( )

Color_ConvertValueToName()
Description The Color_ConvertValueToName() function converts a color value to the
corresponding Dexterity predefined color name.

Syntax Color_ConvertValueToName(color_value)

Parameters • color_value – A long integer containing a color value.

Return value A string containing the name of the color. The following table lists the
predefined color names for Dexterity:

Black Medium Gray

Blue Pink
Bright Green Red
Dark Blue Teal
Dark Red Turquoise
Dark Yellow Violet
Green White
Light Gray Yellow
Light Yellow

If the color value is not a Dexterity predefined color, the hexadecimal

representation of the color value is returned.

Examples The following example uses the Field_GetColor() function to retrieve color
information for the Color Specifications field. The font color and back color
values are converted to their color names and written to the defaults file.

local boolean result;

local long font_color, back_color, pattern_color;
local integer pattern;

result = Field_GetColor('Color Specifications', font_color,

➥ back_color, pattern_color, pattern);

{Write the color values to the defaults file.}

result = Defaults_Write("FontColor", Color_ConvertValueToName
➥ (font_color));
result = Defaults_Write("BackColor", Color_ConvertValueToName
➥ (back_color));

44 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O L O R _ C O N V E R T V A L U E T O R G B ()

Color_ConvertValueToRGB()
Description The Color_ConvertValueToRGB() function converts a color value to its
component red, green and blue color levels.

Syntax Color_ConvertValueToRGB(color_value, red_level, green_level, blue_level)

Parameters • color_value – A long integer containing a color value.

• red_level – A returned integer containing the level of red in the color. The
value will be between 0 and 255.

• green_level – A returned integer containing the level of green in the color.

The value will be between 0 and 255.

• blue_level – A returned integer containing the level of blue in the color. The
value will be between 0 and 255.

Return value An integer containing the color value.

Examples The following example uses the Defaults_ReadColor() function to read a

color value from the defaults file. The color value is then converted into its
red, green and blue components.

local long color_value;

local integer red_level, green_level, blue_level;

{Read the color from the defaults file.}

color_value = Defaults_ReadColor("BackColor", COLOR_WHITE);

{Find the components of the color.}

color_value = Color_ConvertValueToRGB(color_value, red_level,
➥ green_level, blue_level);

FUNCTION LIBRARY REFERENCE 45

C O L O R _ G E T F R O M D I A L O G ( )

Color_GetFromDialog()
Description The Color_GetFromDialog() function opens a color selection dialog that
allows the user to pick a color.

Syntax Color_GetFromDialog(color_value {,color_mode}{,custom_colors[]})

Parameters • color_value – A long integer field or variable containing a color value. If you
supply an initial value for this parameter, that color will be the default
selection in the color selection dialog. If the user clicks OK in the color
selection dialog, the color value selected will be returned. If the user clicks
Cancel, the value -1 will be returned.

• color_mode – This optional parameter specifies what type of color will be

returned. Use one of the following constants:

Constant Description
COLOR_MODE_EXACT The exact color the user selected is returned from the
color selection dialog.
COLOR_MODE_SOLID Only solid colors can be selected and returned from the
color selection dialog,

If you don’t supply this parameter, an exact color will be returned from the
color selection dialog.

• custom_colors[] – An optional array of 16 long integer color values used to

define the custom colors that appear in the Custom colors section of the
color selection dialog. If you supply initial values for each of these array
elements, those colors will appear in the color selection dialog. When the
color selection dialog is closed, the custom color values defined in the
dialog will be returned to this array. If you don’t supply this parameter, the
16 colors in the Custom colors section of the color selection dialog will be
white.

Return value A boolean indicating which buttons was clicked. True is indicates that OK
was clicked, while false indiates that Cancel was clicked.

46 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O L O R _ G E T F R O M D I A L O G ()

Comments You can use the following constants when specifying solid colors:

Constant Constant
COLOR_BLACK COLOR_GREEN
COLOR_WHITE COLOR_DARK_YELLOW
COLOR_RED COLOR_VIOLET
COLOR_BRIGHT_GREEN COLOR_DARK_RED
COLOR_BLUE COLOR_DARK_BLUE
COLOR_TURQUOISE COLOR_MEDIUM_GRAY
COLOR_PINK COLOR_LIGHT_GRAY
COLOR_YELLOW COLOR_LIGHT_YELLOW
COLOR_TEAL

Examples The following example uses the Color_GetFromDialog() function to

specify the background color of the Buyer ID field.

local boolean color_selected;

local boolean result;
local long color;

color_selected = Color_GetFromDialog(color);
if color_selected = true then
result = Field_SetBackColor('Buyer ID', color);
end if;

The following example reads 16 custom color values from the defaults file.
It then displays the color selection dialog, allowing the user to pick a color.
After the color selection dialog has closed, the sixteen custom colors are
written to the defaults file.

local integer i;
local long color, custom_colors[16];
local boolean result;

{Read the custom colors from the defaults file.}

for i = 1 to 16 do
custom_colors[i] = value(Defaults_Read("CustomColor"+str(i)));
end for;

{Allow the user to select a color.}

result = Color_GetFromDialog(color, COLOR_MODE_EXACT, custom_colors);

FUNCTION LIBRARY REFERENCE 47

C O L O R _ G E T F R O M D I A L O G ( )

{Write the custom colors to the defaults file.}

for i = 1 to 16 do
result = Defaults_Write("CustomColor"+str(i),
➥ str(custom_colors[i]));
end for;

48 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O L O R _ R E S E T S Y S T E M C O L O R ()

Color_ResetSystemColor()
Description The Color_ResetSystemColor() function sets the specified system color
category back to the default value, which is derived from the current
operating system settings.

Syntax Color_ResetSystemColor(category)

Parameters • category – A long integer specifying the system color category to be reset.
Use one of the following constants:

SYSTEM_ACTIVE_BORDER
SYSTEM_ACTIVE_TITLE_BAR
SYSTEM_ACTIVE_TITLE_BAR_TEXT
SYSTEM_APPLICATION_WORKSPACE
SYSTEM_BUTTON_DARK_SHADOW
SYSTEM_BUTTON_FACE
SYSTEM_BUTTON_HIGHLIGHT
SYSTEM_BUTTON_LIGHT_SHADOW
SYSTEM_BUTTON_SHADOW
SYSTEM_BUTTON_TEXT
SYSTEM_DESKTOP
SYSTEM_DISABLED_TEXT
SYSTEM_HIGHLIGHT
SYSTEM_HIGHLIGHT_TEXT
SYSTEM_INACTIVE_BORDER
SYSTEM_INACTIVE_TITLE_BAR
SYSTEM_INACTIVE_TITLE_BAR_TEXT
SYSTEM_MENU_BAR
SYSTEM_MENU_TEXT
SYSTEM_SCROLLBARS
SYSTEM_TOOLTIP
SYSTEM_TOOLTIP_TEXT
SYSTEM_WINDOW_BACKGROUND
SYSTEM_WINDOW_FRAME
SYSTEM_WINDOW_TEXT
SYSTEM_STATUS_BAR
SYSTEM_TOOLBAR
SYSTEM_LIST_HEADER1
SYSTEM_LIST_HEADER1_TEXT
SYSTEM_LIST_HEADER2
SYSTEM_LIST_HEADER2_TEXT
SYSTEM_LIST_LINE1
SYSTEM_LIST_LINE1_TEXT
SYSTEM_LIST_LINE2
SYSTEM_LIST_LINE2_TEXT
SYSTEM_FIELD_BORDER
SYSTEM_BUTTON_BORDER

Return value A boolean indicating whether the system color category was reset. True
indicates it was reset, while false indicates it was not.

FUNCTION LIBRARY REFERENCE 49

C O L O R _ R E S E T S Y S T E M C O L O R ( )

Examples The following example resets the desktop color for the application back to
the default color specified by the operating system.

local boolean result;

result = Color_ResetSystemColor(SYSTEM_DESKTOP);
if result = false then
error "System color category could not be reset.";
end if;

Related items Additional information

System color support - customizable on page 152 of Volume 1 of the Dexterity
Programmer’s Guide.

50 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O L O R _ S E T S Y S T E M C O L O R ()

Color_SetSystemColor()
Description The Color_SetSystemColor() function sets a system color category to the
specified color.

Syntax Color_SetSystemColor(category, color_value)

Parameters • category – A long integer specifying the system color category to be set. Use
one of the following constants:

SYSTEM_ACTIVE_BORDER SYSTEM_SCROLLBARS
SYSTEM_ACTIVE_TITLE_BAR SYSTEM_TOOLTIP
SYSTEM_ACTIVE_TITLE_BAR_TEXT SYSTEM_TOOLTIP_TEXT
SYSTEM_APPLICATION_WORKSPACE SYSTEM_WINDOW_BACKGROUND
SYSTEM_BUTTON_DARK_SHADOW SYSTEM_WINDOW_FRAME
SYSTEM_BUTTON_FACE SYSTEM_WINDOW_TEXT
SYSTEM_BUTTON_HIGHLIGHT SYSTEM_STATUS_BAR
SYSTEM_BUTTON_LIGHT_SHADOW SYSTEM_TOOLBAR
SYSTEM_BUTTON_SHADOW SYSTEM_LIST_HEADER1
SYSTEM_BUTTON_TEXT SYSTEM_LIST_HEADER1_TEXT
SYSTEM_DESKTOP SYSTEM_LIST_HEADER2
SYSTEM_DISABLED_TEXT SYSTEM_LIST_HEADER2_TEXT
SYSTEM_HIGHLIGHT SYSTEM_LIST_LINE1
SYSTEM_HIGHLIGHT_TEXT SYSTEM_LIST_LINE1_TEXT
SYSTEM_INACTIVE_BORDER SYSTEM_LIST_LINE2
SYSTEM_INACTIVE_TITLE_BAR SYSTEM_LIST_LINE2_TEXT
SYSTEM_INACTIVE_TITLE_BAR_TEXT SYSTEM_FIELD_BORDER
SYSTEM_MENU_BAR SYSTEM_BUTTON_BORDER
SYSTEM_MENU_TEXT

• color_value – A long integer containing the color value to use.

Return value A boolean indicating whether the system color category was set. True
indicates it was set, while false indicates it was not.

FUNCTION LIBRARY REFERENCE 51

C O L O R _ S E T S Y S T E M C O L O R ( )

Comments You can use the following constants when specifying solid colors:

Constant Constant
COLOR_BLACK COLOR_GREEN
COLOR_WHITE COLOR_DARK_YELLOW
COLOR_RED COLOR_VIOLET
COLOR_BRIGHT_GREEN COLOR_DARK_RED
COLOR_BLUE COLOR_DARK_BLUE
COLOR_TURQUOISE COLOR_MEDIUM_GRAY
COLOR_PINK COLOR_LIGHT_GRAY
COLOR_YELLOW COLOR_LIGHT_YELLOW
COLOR_TEAL

Examples The following example sets the control area color, indicated by the constant
SYSTEM_TOOLBAR, to medium gray.

local boolean result;

result = Color_SetSystemColor(SYSTEM_TOOLBAR, COLOR_MEDIUM_GRAY);

if result = false then
error "System color category could not be set.";
end if;

Related items Additional information

System color support - customizable on page 152 of Volume 1 of the Dexterity
Programmer’s Guide.

52 F U N C T I O N L I B R A R Y R E F E R E N C E
 COM function library
Refer to Chapter 39, Use the functions in this library to create and manipulate COM object
“COM in sanScript,” references. This library contains the following functions:
and Chapter 40, “Call-
backs and Events,” in • COM_AttachEventHandler()
Volume 2 of the Dex- • COM_CreateObject()
terity Programmer’s • COM_DetachEventHandler()
Guide for more infor- • COM_GetObject()
mation on using these • COM_RegisterRunningObject()
functions. • COM_RevokeRunningObject()

FUNCTION LIBRARY REFERENCE 53

C O M _ A T T A C H E V E N T H A N D L E R ( )

COM_AttachEventHandler()
Description The COM_AttachEventHandler() function attaches a callback object as an
event handler.

Syntax COM_AttachEventHandler(COM_reference, callback_object {, interface_id})

Parameters • COM_reference – A reference to the object in the external application that

notifies the Dexterity-based application when events occur.

• callback_object – A reference to a callback object in the Dexterity-based

application which contains the functions that handle the events received.

• interface_id – An optional string parameter that indicates the GUID for the
class or interface that contains the event. Use this parameter if you must
attach to a specific interface that is not the default interface. If this
parameter is not specified, the function will use the default source interface.

Return value A long integer that identifies the event handler. You will use this value if
you need to detach the event handler. The value 0 indicates the event
handler could not be attached.

Comments When you attach a callback object as an event handler, your application is
notified when that event occurs. If your application no longer needs to be
notified that the event has occurred, use the COM_DetachEventHandler()
function to detach the event handler.

Examples The following example creates an event handler for the Activate event of
the currently active workbook in Microsoft Excel®. It uses the
COM_AttachEventHandler() function to attach the callback object in the
Dexterity-based application to the appropriate interface in Excel.

local Excel.Application app;

local reference callback_obj;
local long handler_id;

{Retrieve a reference to Excel.}

app = COM_GetObject("Excel.Application");

if app <> null then

{Create the callback object to handle the event.}
callback_obj = DexObject_Create();

54 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M _ A T T A C H E V E N T H A N D L E R ()

{Add the method for the Activate event.}

DexObject_AddMethod(callback_obj, "Activate", function
➥ ActivateHandler, 0x130);

{Attach the callback object.}

handler_id = COM_AttachEventHandler(app.ActiveWorkbook,
➥ callback_obj);
if handler_id = 0 then
error "Could not attach event handler.";
end if;
end if;

Related items Commands

COM_DetachEventHandler(), DexObject_Create()

FUNCTION LIBRARY REFERENCE 55

C O M _ C R E A T E O B J E C T ( )

COM_CreateObject()
Description The COM_CreateObject() function creates a COM object reference to a new
instance of an object.

Syntax COM_CreateObject(object_type {, servername})

Parameters • object_type – A string containing the fully-qualified class name of the object
to be created.

• servername – An optional string, specifying the machine where the object is

to be created.

Return value A COM object reference of the type specified with the object_type parameter.
If the object cannot be created, the value null is returned.

Comments Typically, creating an application object will produce an application that is

not visible. If you want the application to be visible, you will need to set the
appropriate property of the application object.

Examples The following example uses the COM_CreateObject() function to create a

COM object reference to a new instance of an Excel application.

local Excel.Application app;

{Create a COM object reference to an Excel application.}

app = COM_CreateObject("Excel.Application");

The following example uses the COM_CreateObject() function to create an

instance of an Excel application object on the machine named
“SystemServer”.

local Excel.Application app;

{Create a COM object reference to an Excel application on the machine

"SystemServer".}
app = COM_CreateObject("Excel.Application", "SystemServer");

Related items Commands

COM_GetObject(), new

56 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M _ D E T A C H E V E N T H A N D L E R ()

COM_DetachEventHandler()
Description The COM_DetachEventHandler() function detaches the event handler
from a callback object in your Dexterity-based application. When an event
handler is detached, your application no longer receives notifications of the
event.

Syntax COM_DetachEventHandler(COM_reference, handler_id {, interface_id})

Parameters • COM_reference – A reference to the object that registers the event and
notifies the Dexterity application.

• handler_id – A long integer that identifies the event handler. This is the
value that was returned from the COM_AttachEventHandler() function.

• interface_id – An optional string parameter that indicates the GUID for the
class or interface that contains the event. Use this parameter if you attached
to a specific interface that was not the default interface. If this parameter is
not specified, the function will attempt to detach from the default source
interface.

Return value A boolean. True indicates the event handler was detached, while false
indicates it was not.

Examples The following example uses the COM_DetachEventHandler() function to

stop the callback object from receiving event notifications from the active
Excel workbook. Handler ID is a local field that contains the value assigned
to the handler by the COM_AttachEventHandler() function.

local boolean result;

result = COM_DetachEventHandler(Excel.ActiveWorkbook,
➥ '(L) Handler ID');
if result = false then
error "Unable to detach event handler";
end if;

Related items Commands

COM_AttachEventHandler()

FUNCTION LIBRARY REFERENCE 57

C O M _ G E T O B J E C T ( )

COM_GetObject()
Description The COM_GetObject() function retrieves a reference to the instance of an
object that exists in the running object table.

Syntax COM_GetObject(object_type)

Parameters • object_type - A string containing the fully qualified class name of the object
to be retrieved.

Return value A COM object reference of the type specified. If the reference can’t be
retrieved, the value null is returned.

Examples The following example uses the COM_GetObject() function to retrieve a

running instance of an Excel application. If Excel is not running, the value
null is returned.

local Excel.Application app;

{Retrieve a reference to a running instance of Excel.}

app = COM_GetObject("Excel.Application");
if app = null then
warning "Excel is not running.";
end if;

Related items Commands

COM_CreateObject(), new

58 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M _ R E G I S T E R R U N N I N G O B J E C T ()

COM_RegisterRunningObject()
Description The COM_RegisterRunningObject() function adds the specified callback
object to the running object table.

Syntax COM_RegisterRunningObject(callback_object, object_type)

Parameters • callback_object – A reference to the callback object to be added to the running

object table.

• object_type – A string specifying the name to be given to the object when it is

added to the running object table. This is the name that must be used by
external applications when they retrieve a reference to the callback object.

Return value A long integer that identifies the COM object in the running object table.

Comments The running object table is managed by the operating system. It maintains a
list of all COM objects that can currently be accessed. For a callback object
to be accessed by external applications, you must add it to the running
object table.

If the callback object no longer needs to be accessed externally, use the

COM_RevokeRunningObject() function to remove the callback object
from the running object table.

Examples The following example creates a callback object and uses the
COM_RegisterRunningObject() function to add it to the running object
table. The object is added with the name “RESM.LoginInfo”.
local reference callback_obj;
local boolean result;
local long obj_id;

{Create the callback object}

callback_obj = DexObject_Create();

{Add fields to the callback object}

result = DexObject_AddProperty(callback_obj, "UserID",
➥ DATATYPE_STRING);
result = DexObject_AddProperty(callback_obj, "Name",
➥ DATATYPE_STRING);

{Add a method to the callback object}

result = DexObject_AddMethod(callback_obj, "VerifyPassword", function
➥ VerifyPassword);

obj_id = COM_RegisterRunningObject(callback_obj, "RESM.LoginInfo");

FUNCTION LIBRARY REFERENCE 59

C O M _ R E G I S T E R R U N N I N G O B J E C T ()

The following example is Visual Basic code that retrieves a reference to the
callback object that was added to the running object table in the previous
example. Notice that exactly the same name is used to refer to the object.

Private Sub GetObject_Click()

Dim LoginObj As Object

Set LoginObj = GetObject(, "RESM.LoginInfo")

If LoginObj Is Nothing Then
MsgBox "Could not retreive login object."
End If
End Sub

Related items Commands

COM_RevokeRunningObject()

60 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M _ R E V O K E R U N N I N G O B J E C T ()

COM_RevokeRunningObject()
Description The COM_RevokeRunningObject() function removes a callback object
from the running object table. When the callback object is removed from the
running object table, it can no longer be accessed by other applications.

Syntax COM_RevokeRunningObject(object_id)

Parameters • object_id - A long value that specifies the COM object to remove from the
running object table. This is the value that was returned from the
COM_RegisterRunningObject() function.

Return value A boolean. True indicates the object was removed, while false indicates it
was not.

Examples The following example uses the COM_RevokeRunningObject() function

to remove the callback object from the running object table. Object ID is a
local field that contains the value assigned to the object by the
COM_RegisterRunningObject() function.

local boolean result;

result = COM_RevokeRunningObject('(L) Object ID');

if result = false then
error "Unable to remove callback from the running object table";
end if;

Related items Commands

COM_RegisterRunningObject()

FUNCTION LIBRARY REFERENCE 61

62 F U N C T I O N L I B R A R Y R E F E R E N C E
 Command function library
Refer to Chapter 15, Use the functions in this library to manage command resources for your
“Commands,” in Vol- application. This library contains the following functions:
ume 1 of the Dexterity
Programmer’s Guide • Command_Execute()
for more information. • Command_GetAccelerator()
• Command_GetBooleanProperty()
• Command_GetIDs
• Command_GetImageProperty()
• Command_GetNamedProperty()
• Command_GetStringProperty()
• Command_GetTag()
• Command_GetType()
• Command_Reset()
• Command_SetAccelerator()
• Command_SetBooleanProperty()
• Command_SetImageProperty()
• Command_SetNamedProperty()
• Command_SetStringProperty()

FUNCTION LIBRARY REFERENCE 63

C O M M A N D _ E X E C U T E ( )

Command_Execute()
Description The Command_Execute() function performs the action for the specified
command.

Syntax Command_Execute(command_tag)

Parameters • command_tag – The integer tag value for the command to be performed.

Return value An integer indicating the error that occured.

Comments If the command has been disable with the disable command statement, it
will not be run. If the command is known at design time, you can use the
run command statement to perform the command’s action.

Examples The following example uses the Command_Execute() function to perform

the first command in the CL_Reports command list.

local integer menu_tag;

local integer item_tag;
local integer err_code;

menu_tag = Command_GetTag(command CL_Reports of form 'Main Menu');

item_tag = CommandList_GetCommandByPosition(menu_tag, 1);

err_code = Command_Execute(item_tag);

64 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ G E T A C C E L E R A T O R ()

Command_GetAccelerator()
Description The Command_GetAccelerator() function retrieves the shortcut that is
defined for the command.

Syntax Command_GetAccelerator(command_tag, modifier, key)

Parameters • command_tag – The integer tag value for the command whose shortcut is
being retrieved.

• modifier – A long integer specifying the modifier key combination for the
shortcut. The value is 0 (zero) if no modifier is used. Otherwise, the value
corresponds to one of the following constants:

Constant Description
COMMAND_SHORTCUT_CTRL Control
COMMAND_SHORTCUT_CTRLSHIFT Control + Shift
COMMAND_SHORTCUT_CTRLALT Control + Alt
COMMAND_SHORTCUT_ALT Alt
COMMAND_SHORTCUT_ALTSHIFT Alt + Shift
COMMAND_SHORTCUT_CTRLALTSHIFT Control + Alt + Shift

• key – A long integer containing the ASCII value of the alpha-numeric key
used for the shortcut. If the key is a function key, the value corresponds to
one of the following constants:

Constant
COMMAND_SHORTCUT_KEY_F1
COMMAND_SHORTCUT_KEY_F2
COMMAND_SHORTCUT_KEY_F3
COMMAND_SHORTCUT_KEY_F4
COMMAND_SHORTCUT_KEY_F5
COMMAND_SHORTCUT_KEY_F6
COMMAND_SHORTCUT_KEY_F7
COMMAND_SHORTCUT_KEY_F8
COMMAND_SHORTCUT_KEY_F9
COMMAND_SHORTCUT_KEY_F10
COMMAND_SHORTCUT_KEY_F11
COMMAND_SHORTCUT_KEY_F12

FUNCTION LIBRARY REFERENCE 65

C O M M A N D _ G E T A C C E L E R A T O R ( )

Return value A boolean. The value true indicates the shortcut was retrieved, while false
indicates it was not.

Examples The following example uses the Command_GetAccelerator() function to

retrieve the shortcut for the CMD_Buyers command.

local integer item_tag;

local long shortcut_key;
local long modifier;
local boolean result;

item_tag = Command_GetTag(command CMD_Buyers of form 'Main Menu');

result = Command_GetAccelerator(item_tag, modifier, shortcut_key);

66 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ G E T B O O L E A N P R O P E R T Y ()

Command_GetBooleanProperty()
Description The Command_GetBooleanProperty() function retrieves a specified
boolean property for a command.

Syntax Command_GetBooleanProperty(command_tag, property)

Parameters • command_tag – The integer tag value for the command whose property is
being retrieved.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant Description
COMMAND_PROP_CHECKED True if the command is checked in a
menu. False if it is not.
COMMAND_PROP_DISABLED True if the command is disabled. False
if it is not.
COMMAND_PROP_HIDDEN True if the command is hidden. False if
it is not.
COMMAND_PROP_MENU_SHOW_IMAGE True if the command is showing an
image in the menu. False if it is not.
COMMAND_PROP_TOOLBAR_SHOW_IMAGE True if the command is showing an
image in a toolbar. False if it is not.
COMMAND_PROP_TOOLBAR_SHOW_TEXT True if the command is showing text in
the toolbar. False if it is not.

Return value A boolean indicating how the property is set.

Examples The following example uses the Command_GetBooleanProperty() function

to find out whether the CMD_CalculateTax command is checked.

local integer tag;

local boolean result;

tag = Command_GetTag(command CMD_CalculateTax of form

➥ 'Main Menu');
result = Command_GetBooleanProperty(tag, COMMAND_PROP_CHECKED);

FUNCTION LIBRARY REFERENCE 67

C O M M A N D _ G E T I D S

Command_GetIDs
Description The Command_GetIDs() function retrieves the resource IDs of the
dictionary that contains the command, the form on which the command is
defined, and the command itself.

Syntax Command_GetIDs(command_tag, dict_ID, form_ID, command_ID)

Parameters • command_tag – The integer tag value for the command whose IDs are being
retrieved.

• dict_ID – A returned integer that contains ID of the dictionary in which the

command is defined.

• form_ID – A returned integer that contains the resource ID of the form on

which the command is defined.

• command_ID – A returned integer containing the ID of the command.

Return value A boolean. The value true indicates the IDs were retrieved, while the value
false indicates they were not.

Examples The following example uses the Command_GetIDs() function to retrieve

the IDs for the commands in the CL_Reports command list.

local integer command_list_tag, item_tag;

local integer dict_ID, form_ID, res_ID;
local integer i;
local boolean result;

{Retrieve information about each command in the list}

command_list_tag = Command_GetTag(command CL_Reports of form
➥ 'Main Menu');

for i = 1 to CommandList_NumCommands(command_list_tag) do
item_tag = CommandList_GetCommandByPosition(command_list_tag, i);
result = Command_GetIDs(item_tag, dict_ID, form_ID, res_ID);

if result = false then

error "Could not retrieve IDs for command.";
else
warning "Dict ID:" + str(dict_ID) + " Form ID:" + str(form_ID)
➥ + " Res ID:" + str(res_ID);
end if;
end for;

68 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ G E T I M A G E P R O P E R T Y ()

Command_GetImageProperty()
Description The Command_GetImageProperty() function retrieves the specified image
defined for a command.

Syntax Command_GetImageProperty(command_tag, property, dict_ID, image_type,

image_ID)

Parameters • command_tag – The integer tag value for the command whose property is
being retrieved.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant Description
COMMAND_PROP_NORMAL_IMAGE Specifies the image displayed in the normal
state.
COMMAND_PROP_CHECKED_IMAGE Specifies the image displayed in the checked
state.

• dict_ID – A returned integer that contains the ID of the dictionary

containing the image used for the command.

• image_type – An integer constant indicating the type of image. The value

corresponds to one of the following constants:

Constant Description
DT_PICT A native picture resource from the dictionary.
DT_EXTERNAL_ICON An icon resource in an external resource
assembly.

• image_ID – A returned integer containing the resource ID of the image used

for the command.

Return value A boolean. The value true indicates the property was retrieved, while the
value false indicates it was not.

FUNCTION LIBRARY REFERENCE 69

C O M M A N D _ G E T I M A G E P R O P E R T Y ()

Examples The following example uses the Command_GetImageProperty() function

to retrieve the normal image used for the CMD_Buyers command.

local integer item_tag;

local integer dict_ID;
local integer image_type;
local integer image_ID;
local boolean result;

item_tag = Command_GetTag(command CMD_Buyers of form 'Main Menu');

result = Command_GetImageProperty(item_tag,COMMAND_PROP_NORMAL_IMAGE,
➥ dict_ID, image_type, image_ID);

70 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ G E T N A M E D P R O P E R T Y ()

Command_GetNamedProperty()
Description The Command_GetNamedProperty() function retrieves the value of a
specific named property that has been added to a command.

Syntax Command_GetNamedProperty(command_tag, property_name)

Parameters • command_tag – The integer tag value for the command from which a named
property is being retrieved.

• property_name – A string specifying the name of the property being

retrieved.

Return value The string value for the named property.

Comments The named property and its value are valid only for the current session of
the application. The named property can be set with the
Command_SetNamedProperty() function.

Examples The following example uses the Command_GetNamedProperty() function

to retrieve the named property “Restriction1” for the
Command_IG_Sample command.

local integer tag;

local string prop_val;

tag = Command_GetTag(command ListObj_Leads of form Command_IG_Sample);

prop_val = Command_GetNamedProperty(tag, "Restriction1");

FUNCTION LIBRARY REFERENCE 71

C O M M A N D _ G E T S T R I N G P R O P E R T Y ()

Command_GetStringProperty()
Description The Command_GetStringProperty() function retrieves a specified string
property for a command.

Syntax Command_GetStringProperty(command_tag, property)

Parameters • command_tag – The integer tag value for the command whose property is
being retrieved.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant Description
COMMAND_PROP_ATTACHED_FORM_NAME The name of the form that is opened by
the command.
COMMAND_PROP_CLEAN_DISPLAY_NAME The text used for the command name,
but with special characters excluded.
COMMAND_PROP_DISPLAY_NAME The text used for the command name,
including any special characters.
COMMAND_PROP_TOOLTIP The tooltip displayed when the
command is used on a toolbar.
COMMAND_PROP_SECURITY_FORM_NAME The name of the security form that is
specified for the command.

Return value A string containing the property value.

Examples The following example uses the Command_GetStringProperty() function

to retrieve the display name of the CMD_HouseReport command.

local integer tag;

local string display_name;

tag = Command_GetTag(command CMD_HouseReport of form 'Main Menu');

display_name = Command_GetStringProperty(tag,
➥ COMMAND_PROP_DISPLAY_NAME);

72 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ G E T T A G ()

Command_GetTag()
Description The Command_GetTag() function retrieves the tag associated with the
specified command or command list.

Syntax Command_GetTag(command)

Parameters • command – The command for which the tag will be retrieved.

Return value An integer containing the tag for the command.

Comments You can also retrieve the tag for a command or command list if you know
the product ID, the form ID that contains the command, and the command
ID. There is no compile-time checking when a tag is retrieved this way.

Examples The following example retrieves the tag for the CL_View command list, and
then removes all of the items from the list.

local integer command_list_tag;

local boolean result;

command_list_tag = Command_GetTag(command CL_View of form

➥ 'Main Menu');
result = CommandList_RemoveAll(command_list_tag);

The following example retrieves the tag for the product ID 3333, the form
ID 22002, and the command ID 22001.

local integer command_tag;

command_tag = Command_GetTag(3333, 22002, 22001);

FUNCTION LIBRARY REFERENCE 73

C O M M A N D _ G E T T Y P E ()

Command_GetType()
Description The Command_GetType() function retrieves the type of a specific
command.

Syntax Command_GetType(command_tag)

Parameters • command_tag – The integer tag value for the command whose type is being
retrieved.

Return value An integer corresponding to one of the following constants:

Constant Description
COMMANDTYPE_NONE The specified command could not be
found.
COMMANDTYPE_SCRIPT The command runs a command script.
COMMANDTYPE_FORM The command opens a form.
COMMANDTYPE_CMDLIST The command is a command list.
COMMANDTYPE_SEPARATOR The command is a separator.

Examples The following example counts the number of sub-menus (command lists)
that appear in the Tools menu.
local integer command_list_tag, item_tag;
local integer command_type, i, count;

{Count the number of sub-menus in a menu}

command_list_tag = Command_GetTag(command CL_Tools of form
➥ 'Main Menu');

count = 0;
for i = 1 to CommandList_NumCommands(command_list_tag) do
{Get the tag for the list item}
item_tag = CommandList_GetCommandByPosition(command_list_tag, i);

{Check the type of the item}

command_type = Command_GetType(item_tag);
if command_type = COMMANDTYPE_CMDLIST then
count = count + 1;
end if;
end for;

74 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _R E S E T ()

Command_Reset()
Description The Command_Reset() function returns the settings for a command back to
their original state as defined in the dictionary.

Syntax Command_Reset(command_tag)

Parameters • command_tag – The integer tag value for the command being reset.

Return value A boolean. The value true indicates the command was reset, while false
indicates it was not.

Comments The only characteristics affected are those in the command definition. Other
characteristics, such as whether the command is visible or is checked are
not affected.

Examples The following example uses the Command_Reset() function to return to the
default settings for the CMD_Buyers command.

local integer item_tag;

local boolean result;

item_tag = Command_GetTag(command CMD_Buyers of form 'Main Menu');

result = Command_Reset(item_tag);

FUNCTION LIBRARY REFERENCE 75

C O M M A N D _ S E T A C C E L E R A T O R ( )

Command_SetAccelerator()
Description The Command_SetAccelerator() function sets the shortcut that is defined
for the command.

Syntax Command_SetAccelerator(command_tag, modifier, key)

Parameters • command_tag – The integer tag value for the command whose shortcut is
being set.

• modifier – A long integer specifying the modifier key combination for the
shortcut. The value 0 (zero) specifies no modifier is to be used. Otherwise,
the value corresponds to one of the following constants:

Constant Description
COMMAND_SHORTCUT_CTRL Control
COMMAND_SHORTCUT_CTRLSHIFT Control + Shift
COMMAND_SHORTCUT_CTRLALT Control + Alt
COMMAND_SHORTCUT_ALT Alt
COMMAND_SHORTCUT_ALTSHIFT Alt + Shift
COMMAND_SHORTCUT_CTRLALTSHIFT Control + Alt + Shift

• key – A long integer containing the ASCII value of the alpha-numeric key to
use for the shortcut. If the key is a function key, the value corresponds to
one of the following constants:

Constant
COMMAND_SHORTCUT_KEY_F1
COMMAND_SHORTCUT_KEY_F2
COMMAND_SHORTCUT_KEY_F3
COMMAND_SHORTCUT_KEY_F4
COMMAND_SHORTCUT_KEY_F5
COMMAND_SHORTCUT_KEY_F6
COMMAND_SHORTCUT_KEY_F7
COMMAND_SHORTCUT_KEY_F8
COMMAND_SHORTCUT_KEY_F9
COMMAND_SHORTCUT_KEY_F10
COMMAND_SHORTCUT_KEY_F11
COMMAND_SHORTCUT_KEY_F12

76 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ S E T A C C E L E R A T O R ()

Return value A boolean. The value true indicates the shortcut was set, while false
indicates it was not.

Examples The following example uses the Command_SetAccelerator() function to set

the shortcut for the CMD_Buyers command to Control-B.

local integer item_tag;

local boolean result;

item_tag = Command_GetTag(command CMD_Buyers of form 'Main Menu');

result = Command_SetAccelerator(item_tag, COMMAND_SHORTCUT_CTRL,

➥ ascii("B"));

FUNCTION LIBRARY REFERENCE 77

C O M M A N D _ S E T B O O L E A N P R O P E R T Y ()

Command_SetBooleanProperty()
Description The Command_SetBooleanProperty() function sets a specified boolean
property for a command.

Syntax Command_SetBooleanProperty(command_tag, property, value)

Parameters • command_tag – The integer tag value for the command whose property is
being set.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant Description
COMMAND_PROP_CHECKED True if the command is checked in a
menu. False if it is not.
COMMAND_PROP_DISABLED True if the command is disabled. False
if it is not.
COMMAND_PROP_HIDDEN True if the command is hidden. False if
it is not.
COMMAND_PROP_MENU_SHOW_IMAGE True if the command is showing an
image in the menu. False if it is not.
COMMAND_PROP_TOOLBAR_SHOW_IMAGE True if the command is showing an
image in a toolbar. False if it is not.
COMMAND_PROP_TOOLBAR_SHOW_TEXT True if the command is showing text in
the toolbar. False if it is not.

• value – A boolean indicating how to set the property. Refer to the preceding
table.

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Examples The following example uses the Command_SetBooleanProperty() function

to add a check mark to the CMD_CalculateTax command.

local integer tag;

local boolean result;

tag = Command_GetTag(command CMD_CalculateTax of form

➥ 'Main Menu');
result = Command_SetBooleanProperty(tag, COMMAND_PROP_CHECKED, true);

78 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ S E T I M A G E P R O P E R T Y ()

Command_SetImageProperty()
Description The Command_SetImageProperty() function sets the specified image
defined for a command.

Syntax Command_SetImageProperty(command_tag, property, dict_ID, image_type,

image_ID)

Parameters • command_tag – The integer tag value for the command whose property is
being set.

• property – An integer constant indicating the property to set. The value

corresponds to one of the following constants:

Constant Description
COMMAND_PROP_NORMAL_IMAGE Specifies the image displayed in the normal
state.
COMMAND_PROP_CHECKED_IMAGE Specifies the image displayed in the checked
state.

• dict_ID – An integer specifying the ID of the dictionary containing the

image to use for the command.

• image_type – An integer constant indicating the type of image. The value

corresponds to one of the following constants:

Constant Description
DT_PICT A native picture resource from the dictionary.
DT_EXTERNAL_ICON An icon resource in an external resource
assembly.

• image_ID – For native pictures, an integer specifying the resource ID of the

image to use for the command. For external icons, the resource ID of the
icon resource that defines the image.

Return value A boolean. The value true indicates the property was set, while the value
false indicates it was not.

Comments Use the Resource_GetID() function to retrieve the resource ID of a native

picture or icon resource.

FUNCTION LIBRARY REFERENCE 79

C O M M A N D _ S E T I M A G E P R O P E R T Y ( )

Examples The following example uses the Command_SetImageProperty() function

to set the normal image used for the CMD_Explorer command.

local integer item_tag, image_ID;

local boolean result;

item_tag = Command_GetTag(command CMD_Explorer of form 'Main Menu');

image_ID = Resource_GetID(0, 28 {Native pictures}, "CMD_Explorer");

result = Command_SetImageProperty(item_tag,COMMAND_PROP_NORMAL_IMAGE,
➥ 0, DT_PICT, image_ID);

The following example uses the Command_SetImageProperty() function

to set the normal image for the IG_Lead_Maintenance command. The
image is set to the “Dynamics” image defined by the icon resource in the
Microsoft Dynamics GP dictionary.

local integer item_tag, image_ID;

local boolean result;

item_tag = Command_GetTag(command IG_Lead_Maintenance of form

Command_IG_Sample);

image_ID = Resource_GetID(0, DT_EXTERNAL_ICON, "Dynamics");

result = Command_SetImageProperty(item_tag,
➥ COMMAND_PROP_NORMAL_IMAGE, 0, DT_EXTERNAL_ICON, image_ID);

80 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D _ S E T N A M E D P R O P E R T Y ()

Command_SetNamedProperty()
Description The Command_SetNamedProperty() function temporarily adds a property
with the specified name to a command. It then sets the value for the
property.

Syntax Command_SetNamedProperty(command_tag, property_name, value)

Parameters • command_tag – The integer tag value for the command for which a named
property is being added and set.

• property_name – A string specifying the name of the property being added

to the command.

• value – A string specifying the value for the property.

Return value A boolean indicating whether the named property was added and set. True
indicates the property was added and set, while false indicates it was not.

Comments The named property and its value are valid only for the current session of
the application. The named property can be retrieved with the
Command_GetNamedProperty() function.

Examples The following example uses the Command_SetNamedProperty() function

to create a named property for the Command_IG_Sample command. The
property has the name “Restriction1”. The named property’s value is set to
“Qualified”.

local integer tag;

local boolean result;

tag = Command_GetTag(command ListObj_Leads of form Command_IG_Sample);

result = Command_SetNamedProperty(tag, "Restriction1", "Qualified");

FUNCTION LIBRARY REFERENCE 81

C O M M A N D _ S E T S T R I N G P R O P E R T Y ( )

Command_SetStringProperty()
Description The Command_SetStringProperty() function sets a specified string
property for a command.

Syntax Command_SetStringProperty(command_tag, property, value)

Parameters • command_tag – The integer tag value for the command whose property is
being set.

• property – An integer constant indicating the property to set. The value

corresponds to one of the following constants:

Constant
COMMAND_PROP_DISPLAY_NAME
COMMAND_PROP_TOOLTIP
Description
The text used for the command name,
including any special characters.
The tooltip displayed when the
command is used on a toolbar.

• value – A string value indicating how to set the property.

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Examples The following example uses the Command_SetStringProperty() function

to set the tooltip for the CMD_Houses command.

local integer tag;

local boolean result;

tag = Command_GetTag(command CMD_Houses of form 'Main Menu');

result = Command_SetStringProperty(tag, COMMAND_PROP_TOOLTIP,
➥ "Houses");

82 F U N C T I O N L I B R A R Y R E F E R E N C E
 Command bar function library
Refer to Chapter 18, Use the functions in this library to create toolbars for your application. This
“Toolbars,” in Volume library contains the following functions:
1 of the Dexterity Pro-
grammer’s Guide for • CommandBar_Create()
more information. • CommandBar_Destroy()
• CommandBar_GetPosition()

FUNCTION LIBRARY REFERENCE 83

C O M M A N D B A R _ C R E A T E ( )

CommandBar_Create()
Description The CommandBar_Create() function creates a toolbar based on the
specified command list.

Syntax CommandBar_Create(command_list_tag {, sequence} {, row})

Parameters • command_list_tag – The integer tag value specifying the command list from
which the toolbar will be created.

• sequence – An optional integer that specifies the relative position of the

toolbar being created.

For applications using the multiple-document interface (MDI), the first

toolbar in the upper-left corner has the sequence value 1. The toolbar next
to it has the value 2, and so on for that row. The toolbars on the next row
simply continue the sequence. When using the sequence, you should
increment the sequence for each toolbar you create.

For applications using the single-document interface (SDI), the sequence is

the horizontal distance of the left edge of the toolbar, measured in pixels
from the left edge of the main window.

• row – An optional integer that specifies the row that the toolbar will be
added to. The value 1 indicates the first row.

Return value An integer. The value 1 indicates the toolbar was created successfully.

Comments To use the sequence parameter when adding toolbars, start the value 1 for
the first toolbar you add, the value 2 for the second, and so on. A sequence
number shouldn’t repeat.

The row parameter specifies the row you want the toolbar to appear in. The
value 1 specifies being the first row. When adding toolbars, begin by adding
those in the first row (row value 1), then those in the second row (row value
2), and so on.

As the user rearranges toolbars, the sequence and row values adjust
automatically.

84 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D B A R _ C R E A T E ()

Examples The following example uses the CommandBar_Create() function to add the
toolbars for the Real Estate Sales Manager sample application. Notice how
the sequence and row parameters are used as the four toolbars are added.
The sequence values start at 1 and increment for each additional toolbar.
The first three toolbars appear on the first row, so the row parameter is 1.
The last toolbar is placed on the second row, so its row value is 2.

local integer result;

{View items}
result = CommandBar_Create(Command_GetTag(command CL_View of form
'Main Menu'),1, 1);

{Edit items}
result = CommandBar_Create(Command_GetTag(command cmdListEdit), 2,1);

{Report items}
result = CommandBar_Create(Command_GetTag(command CL_Reports of form
'Main Menu'),3,1);

{Export items}
result = CommandBar_Create(Command_GetTag(command CL_Export of form
'Main Menu'), 4, 2);

FUNCTION LIBRARY REFERENCE 85

C O M M A N D B A R _ D E S T R O Y ()

CommandBar_Destroy()
Description The CommandBar_Destroy() function removes a toolbar based on the
specified command list.

Syntax CommandBar_Destroy(command_list_tag)

Parameters • command_list_tag – The integer tag value specifying the command list that
the toolbar to be removed is based on.

Return value The integer value 0.

Examples The following example uses the CommandBar_Destroy() function to

remove a toolbar based on the edit items built-in command list.

local integer result;

result = CommandBar_Destroy(Command_GetTag(command cmdListEdit));

86 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D B A R _ G E T P O S I T I O N ()

CommandBar_GetPosition()
Description The CommandBar_GetPosition() function retrieves the row and sequence
of a toolbar that is based on the specified command list.

Syntax CommandBar_GetPosition(command_list_tag, sequence, row)

Parameters • command_list_tag – The integer tag value specifying the command list that
the toolbar whose position is being retrieved is based on.

• sequence – A returned integer containing the relative position of the toolbar.

For applications using the multiple-document interface (MDI), the first

toolbar in the upper-left corner has the sequence value 1. The toolbar next
to it has the value 2, and so on for that row. The toolbars on the next row
simply continue the sequence.

For applications using the single-document interface (SDI), the sequence is

the horizontal distance of the left edge of the toolbar, measured in pixels
from the left edge of the main window.

• row – A returned integer containing the row that the toolbar is in. The value
1 indicates the first row.

Return value A boolean. The value true indicates the position information was retrieved,
while false indicates it was not.

Comments This function is typically used to retrieve and save the positions of all the
toolbars currently displayed in an application. The position information is
later retrieved to re-create the same toolbar arrangement.

Examples The following example uses the CommandBar_GetPosition() function to

retrieve the positions of the four toolbars for the Real Estate Sales Manager
sample application. The values are written to the DEX.INI file, to be used
when the toolbars are added.

local boolean result;

local integer seq;
local integer row;
local string setting;

FUNCTION LIBRARY REFERENCE 87

C O M M A N D B A R _ G E T P O S I T I O N ( )

{View toolbar}
result = CommandBar_GetPosition(Command_GetTag(command CL_View of
➥ form 'Main Menu'), seq, row);
setting = str(resourceid(command CL_View of form 'Main Menu')) + "," +
➥ str(resourceid(form 'Main Menu')) + "," + str(row);
result = Defaults_Write("Toolbar"+str(seq), setting);

{Reports toolbar}
result = CommandBar_GetPosition(Command_GetTag(command CL_Reports of
➥ form 'Main Menu'), seq, row);
setting = str(resourceid(command CL_Reports of form 'Main Menu')) +
➥ "," + str(resourceid(form 'Main Menu')) + "," + str(row);
result = Defaults_Write("Toolbar"+str(seq), setting);

{Edit toolbar -- a built-in command list, so use -1 as the built-in

command form}
result = CommandBar_GetPosition(Command_GetTag(command cmdListEdit),
➥ seq, row);
setting = str(resourceid(command cmdListEdit)) + "," + "-1" + "," +
➥ str(row);
result = Defaults_Write("Toolbar"+str(seq), setting);

{Export toolbar}
result = CommandBar_GetPosition(Command_GetTag(command CL_Export of
➥ form 'Main Menu'), seq, row);
setting = str(resourceid(command CL_Export of form 'Main Menu')) + ","
➥ + str(resourceid(form 'Main Menu')) + "," + str(row);
result = Defaults_Write("Toolbar"+str(seq), setting);

88 F U N C T I O N L I B R A R Y R E F E R E N C E
Command list function library
Use the functions in this library to manage command list resources for your
application. This library contains the following functions:

• CommandList_Add()
• CommandList_CreateList()
• CommandList_FindCommand()
• CommandList_GetCommandByPosition()
• CommandList_NumCommands()
• CommandList_Remove()
• CommandList_RemoveAll()
• CommandList_RemoveCommandByPosition()

FUNCTION LIBRARY REFERENCE 89

C O M M A N D L I S T _ A D D ( )

CommandList_Add()
Description The CommandList_Add() function adds a command or another command
list to the specified command list.

Syntax CommandList_Add(command_list_tag, added_item {, position})

Parameters • command_list_tag – The integer tag value specifying the command list to
which a command or command list is being added.

• added_item – The integer tag value for the command or command list to be
added.

• position – An optional integer that specifies the location of the new item. The
value 1 indicates the first position. The value 0 indicates the end of the
command list.

Return value An integer specifying the position to which the item was added to the
command list.

Comments The command that defines the command list must already be defined in the
application. The form that contains the definition of the command list must
be open when the command list is used.

Examples The following example adds items to the CL_Tools command list, which is
used to define the Tools menu in an application. It also adds commands to
the CL_Export command list, which is used as a sub-menu for the Tools
menu.

local integer result;

local integer menu_tag;
local integer submenu_tag;

{Add the Tools menu}

menu_tag = Command_GetTag(command CL_Tools of form 'Main Menu');
result = MenuBar_AddMenu(menu_tag);

{Add the CL_Export command list to the Tools menu}

CommandList_Add(menu_tag, Command_GetTag(command CL_Export of form
➥ 'Main Menu'));

{Add commands to the CL_Export command list}

submenu_tag = Command_GetTag(command CL_Export of form 'Main Menu');

90 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D L I S T _ A D D ()

CommandList_Add(submenu_tag, Command_GetTag(command CMD_ExportAccess

➥ of form 'Main Menu'));
CommandList_Add(submenu_tag, Command_GetTag(command CMD_ExportExcel
➥ of form 'Main Menu'));
CommandList_Add(submenu_tag, Command_GetTag(command CMD_ExportWord of
➥ form 'Main Menu'));
CommandList_Add(submenu_tag, Command_GetTag(command CMD_ExportXML of
➥ form 'Main Menu'));

{Add additional predefined command lists to the Tools menu}

CommandList_Add(menu_tag, Command_GetTag(command cmdListMacro));
CommandList_Add(menu_tag, Command_GetTag(command
➥ cmdListResourceDescriptions));

FUNCTION LIBRARY REFERENCE 91

C O M M A N D L I S T _ C R E A T E L I S T ()

CommandList_CreateList()
Description The CommandList_CreateList() function creates a command list and
associates it with a specific form. The command lists created with this
function are typically used for ribbons that are shown in the web client.

Syntax CommandList_CreateList(product_ID, form_ID, command_name)

Parameters • product_ID – An integer specifying the product ID that contains the form for
which a command list is being created.

• form_ID – An integer specifying the resource ID of the form for which a

command list is being created.

• command_name – A string that supplies the name to assign to the command

list that is being created.

Return value An integer specifying the tag of the command list that is created for the
form.

Examples The following example is the InitializeWindowRibbon procedure for an

AboutBox form. It uses the Command_CreateList() function to create the
command lists that define the content of the ribbon displayed for the form
in the Microsoft Dynamics GP web client.

in integer productId;
in integer formId;
in integer windowId;
in integer windowType;
inout integer ribbonTag;

local integer tag;

local integer action_group_tag;
local integer image_id;

{Create the command list for the custom ribbon}

ribbonTag = CommandList_CreateList(productId, formId,
➥ "AboutWindowRibbon");

{Create a command list for the Actions group}

action_group_tag = CommandList_CreateList(productId, formId,
➥ "ActionGroup");

92 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D L I S T _ C R E A T E L I S T ()

{Set properties for the Actions group}

Command_SetStringProperty(action_group_tag,
➥ COMMAND_PROP_DISPLAY_NAME, "Actions");

{Create a command based on the Close button}

tag = Field_CreateLinkedCommand('(L) Close' of window About,
➥ "CloseOfWindowAbout");

{Set the properties for the Close button}

image_id = Resource_GetID(0, DT_EXTERNAL_ICON, "Close");
Command_SetImageProperty(tag, COMMAND_PROP_NORMAL_IMAGE, DYNAMICS,
➥ DT_EXTERNAL_ICON, image_id);

{Add the Close button to the Actions group}

CommandList_Add(action_group_tag, tag);

{Add the Actions group to the ribbon}

CommandList_Add(ribbonTag, action_group_tag);

FUNCTION LIBRARY REFERENCE 93

C O M M A N D L I S T _ F I N D C O M M A N D ( )

CommandList_FindCommand()
Description The CommandList_FindCommand() function retrieves the position of the
specified item in a command list.

Syntax CommandList_FindCommand(command_list_tag, item_tag)

Parameters • command_list_tag – The integer tag value specifying the command list in
which to search.

• item_tag – The integer tag value for the command or command list being
searched for.

Return value An integer specifying the location of the item. The value 0 indicates the item
was not found.

Examples The following example retrieves the position of the House command
(CMD_Houses) from the CL_View command list.

local integer command_list_tag;

local integer item_tag;
local integer position;

{Retrieve the tag values for the command list and the command}
command_list_tag = Command_GetTag(command CL_View of form
➥ 'Main Menu');
item_tag = Command_GetTag(command CMD_Houses of form 'Main Menu');

position = CommandList_FindCommand(command_list_tag, item_tag);

94 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D L I S T _ G E T C O M M A N D B Y P O S I T I O N ()

CommandList_GetCommandByPosition()
Description The CommandList_GetCommandByPosition() function retrieves the tag
for a command, based on the position in the command list.

Syntax CommandList_GetCommandByPosition(command_list_tag, position)

Parameters • command_list_tag – The integer tag value specifying the command list in
which to search.

• position – An integer specifying which command tag to return. The value 1

specifies the first command in the command list.

Return value An integer containing the command tag for the specified item. If the item
can’t be found, the value 0 is returned.

Examples The following example uses the CommandList_GetCommandByPosition()

function to examine the commands in the CL_Tools command list, and
count the number of commands that are command lists.

local integer command_list_tag;

local integer item_tag;
local integer command_type;
local integer i, count;

{Count the number of sub-menus in a menu}

command_list_tag = Command_GetTag(command CL_Tools of form 'Main
Menu');

count = 0;
for i = 1 to CommandList_NumCommands(command_list_tag) do
{Get the tag for the list item}
item_tag = CommandList_GetCommandByPosition(command_list_tag, i);

{Check the type of the item}

command_type = Command_GetType(item_tag);
warning str(command_type);
if command_type = COMMANDTYPE_CMDLIST then
count = count + 1;
end if;
end for;

FUNCTION LIBRARY REFERENCE 95

C O M M A N D L I S T _ N U M C O M M A N D S ( )

CommandList_NumCommands()
Description The CommandList_NumCommands() function retrieves the number of
commands in the specified command list.

Syntax CommandList_NumCommands(command_list_tag)

Parameters • command_list_tag – The integer tag value specifying the command list for
which commands will be counted.

Return value An integer containing the number of commands.

Examples The following example counts the number of commands in the CL_View
command list.

local integer command_list_tag;

local integer count;

command_list_tag = Command_GetTag(command CL_View of form

➥ 'Main Menu');
count = CommandList_NumCommands(command_list_tag);

96 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D L I S T _ R E M O V E ()

CommandList_Remove()
Description The CommandList_Remove() function removes the specified item from a
command list.

Syntax CommandList_Remove(command_list_tag, item_tag)

Parameters • command_list_tag – The integer tag value specifying the command list from
which an item is being removed.

• item_tag – The integer tag value for the command or command list being
removed.

Return value A boolean. The value true indicates the item was removed, while false
indicates it was not.

Examples The following example removes the CMD_Houses command from the
CL_View command list.

local integer command_list_tag;

local integer item_tag;
local boolean result;

command_list_tag = Command_GetTag(command CL_View of form 'Main

Menu');
item_tag = Command_GetTag(command CMD_Houses of form 'Main Menu');

result = CommandList_Remove(command_list_tag, item_tag);

FUNCTION LIBRARY REFERENCE 97

C O M M A N D L I S T _ R E M O V E A L L ()

CommandList_RemoveAll()
Description The CommandList_RemoveAll() function removes all items from the
specified command list.

Syntax CommandList_RemoveAll(command_list_tag)

Parameters • command_list_tag – The integer tag value specifying the command list from
which all items are being removed.

Return value A boolean. The value true indicates all items were removed, while false
indicates they were not.

Examples The following example removes all items from the CL_Tools command list.

local integer command_list_tag;

local boolean result;

command_list_tag = Command_GetTag(command CL_Tools of form

➥ 'Main Menu');
result = CommandList_RemoveAll(command_list_tag);

98 F U N C T I O N L I B R A R Y R E F E R E N C E
 C O M M A N D L I S T _ R E M O V E C O M M A N D B Y P O S I T I O N ()

CommandList_RemoveCommandByPosition()
Description The CommandList_RemoveCommandByPosition() function removes the
item from the specified position in a command list.

Syntax CommandList_RemoveCommandByPosition(command_list_tag, position)

Parameters • command_list_tag – The integer tag value specifying the command list from
which an item is being removed.

• position – An integer specifying the position from which to remove the

command. The value 1 is the first position in the list.

Return value A boolean. The value true indicates the item was removed, while false
indicates it was not.

Examples The following example removes the third command from the CL_View
command list.

local integer command_list_tag;

local boolean result;

command_list_tag = Command_GetTag(command CL_View of form

➥ 'Main Menu');

result = CommandList_RemoveCommandByPosition(command_list_tag, 3);

FUNCTION LIBRARY REFERENCE 99

100 F U N C T I O N L I B R A R Y R E F E R E N C E
 Currency function library
Refer to Chapter 7, Dexterity provides the ability to define multiple currency formats that can
“Formats,” in Volume 1 be applied to fields with the currency control type. Each format you define
of the Dexterity is associated with an integer value, referred to as a multiformat value.
Programmer’s Guide Multiformat values work in conjunction with the Multiple Format Selector
for information about to apply formatting to window fields, and with per-record formats to apply
the Multiple Format formatting to report fields. Use the functions in this library to define or
Selector. retrieve the characteristics of a specific multiformat value.

Refer to Chapter 41, You may not need to use all of the possible characteristics of a multiformat
“Modifying Fields,” in value. When a characteristic isn’t set for a specific multiformat value, the
Volume 1 of the operating system default for that characteristic will be used.
Dexterity Program-
mer’s Guide for This library contains the following functions:
information about
currency formats for • Currency_GetDecimalSymbol()
reports. • Currency_GetLeadingSymbol()
• Currency_GetLeadingZero()
• Currency_GetNativeSymbol()
• Currency_GetNegativeAfterValue()
• Currency_GetNegativeBeforeSymbol()
• Currency_GetNegativeParens()
• Currency_GetNegativeSymbol()
• Currency_GetNumberOfDecimals()
• Currency_GetSymbol()
• Currency_GetThousandsSymbol()
• Currency_SetDecimalSymbol()
• Currency_SetLeadingSymbol()
• Currency_SetLeadingZero()
• Currency_SetNegativeAfterValue()
• Currency_SetNegativeBeforeSymbol()
• Currency_SetNegativeParens()
• Currency_SetNegativeSymbol()
• Currency_SetNumberOfDecimals()
• Currency_SetSymbol()
• Currency_SetThousandsSymbol()

FUNCTION LIBRARY REFERENCE 101

C U R R E N C Y _ G E T D E C I M A L S Y M B O L ( )

Currency_GetDecimalSymbol()
Description The Currency_GetDecimalSymbol() function returns the string used as a
decimal separator when the specified multiformat value is applied to a
currency field.

Syntax Currency_GetDecimalSymbol(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value String. If a decimal symbol has not been defined for the specified
multiformat value, the operating system decimal symbol will be returned.

Examples The following example uses this function to return the string used as the
decimal separator for the multiformat value 3000.

local string dec_symbol;

dec_symbol = Currency_GetDecimalSymbol(3000);

Related items Commands

Currency_SetDecimalSymbol()

102 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ G E T L E A D I N G S Y M B O L ()

Currency_GetLeadingSymbol()
Description The Currency_GetLeadingSymbol() function returns a boolean value
indicating whether the currency symbol is positioned before the currency
value when the specified multiformat value is applied to a currency field.

Syntax Currency_GetLeadingSymbol(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value Boolean. If true is returned, a leading currency symbol is used. If false is
returned, a trailing currency symbol is used.

Examples The following example uses this function to ascertain whether a leading or
trailing currency symbol is used with the multiformat value 3000.

local boolean use_leading;

use_leading = Currency_GetLeadingSymbol(3000);

Related items Commands

Currency_SetLeadingSymbol()

FUNCTION LIBRARY REFERENCE 103

C U R R E N C Y _ G E T L E A D I N G Z E R O ()

Currency_GetLeadingZero()
Description The Currency_GetLeadingZero() function returns a boolean value
indicating whether a currency value less than 1 and greater than -1 will be
displayed with a leading zero when the specified multiformat value is
applied to a currency field.

Syntax Currency_GetLeadingZero(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value Boolean. If true is returned, a leading zero is used. If false is returned, a
leading zero isn’t used.

Examples The following example uses this function to ascertain whether a leading
zero is used with the multiformat value 3000.

local boolean use_lead_zero;

use_lead_zero = Currency_GetLeadingZero(3000);

Related items Commands

Currency_SetLeadingZero()

104 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ G E T N A T I V E S Y M B O L ()

Currency_GetNativeSymbol()
Description The Currency_GetNativeSymbol() function returns a platform-specific
string displaying the dollar, pound, yen or Euro currency symbol.

Syntax Currency_GetNativeSymbol(symbol)

Parameters • symbol – An integer value specifying which currency symbol will be

returned. Use one of the following constants for this parameter:

Constant Description
DEX_DOLLAR_SYM The dollar symbol ($)
DEX_POUND_SYM The pound symbol (£)
DEX_YEN_SYM The yen symbol (¥)
DEX_EURO_SYM The Euro symbol (€)

Return value String

Comments The various currency symbols are platform-specific. This function allows
your application to always retrieve the appropriate symbol, regardless of
which operating system is being used.

For platforms that cannot display the Euro symbol, the string EUR is
returned.

Examples The following example retrieves the pound symbol.

local string pound_symbol;

pound_symbol = Currency_GetNativeSymbol(DEX_POUND_SYM);

Related items Commands

Currency_GetSymbol(), Currency_SetSymbol()

FUNCTION LIBRARY REFERENCE 105

C U R R E N C Y _ G E T N E G A T I V E A F T E R V A L U E ( )

Currency_GetNegativeAfterValue()
Description The Currency_GetNegativeAfterValue() function returns a boolean value
indicating whether the negative symbol is placed after the currency value
when the specified multiformat value is applied to a currency field.

Syntax Currency_GetNegativeAfterValue(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value Boolean. If true is returned, a trailing negative symbol is used. If false is
returned, a leading negative symbol is used.

Examples The following example uses this function to ascertain whether a trailing
negative symbol is used with the multiformat value 3000.

local boolean trailing_neg;

trailing_neg = Currency_GetNegativeAfterValue(3000);

Related items Commands

Currency_SetNegativeAfterValue()

106 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ G E T N E G A T I V E B E F O R E S Y M B O L ()

Currency_GetNegativeBeforeSymbol()
Description The Currency_GetNegativeBeforeSymbol() function returns a boolean
value indicating whether a leading negative symbol is placed before a
leading currency symbol when the specified multiformat value is applied to
a currency field.

Syntax Currency_GetNegativeBeforeSymbol(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value Boolean. If true is returned, a leading negative symbol precedes a leading
currency symbol. If false is returned, a leading negative symbol follows a
leading currency symbol.

Examples The following example uses this function to ascertain whether a leading
negative symbol precedes a leading currency symbol when the multiformat
value 3000 is used.

local boolean neg_before_symb;

neg_before_symb = Currency_GetNegativeBeforeSymbol(3000);

Related items Commands

Currency_SetNegativeBeforeSymbol()

FUNCTION LIBRARY REFERENCE 107

C U R R E N C Y _ G E T N E G A T I V E P A R E N S ( )

Currency_GetNegativeParens()
Description The Currency_GetNegativeParens() function returns a boolean value
indicating whether parentheses are used to denote a negative currency
value when the specified multiformat value is applied to a currency field.

Syntax Currency_GetNegativeParens(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value Boolean. If true is returned, parentheses are used to denote negative values.
If false is returned, parentheses aren’t used.

Comments Whether parentheses are used is specified by the

Currency_SetNegativeParens() function or the operating system’s default
currency format.

Examples The following example uses this function to ascertain whether parentheses
are used to denote a negative currency value when the multiformat value
3000 is used.

local boolean use_parens;

use_parens = Currency_GetNegativeParens(3000);

Related items Commands

Currency_SetNegativeParens()

108 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ G E T N E G A T I V E S Y M B O L ()

Currency_GetNegativeSymbol()
Description The Currency_GetNegativeSymbol() function returns the string that is
used as the negative symbol when the specified multiformat value is
applied to a currency field.

Syntax Currency_GetNegativeSymbol(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value String. If parentheses are used to denote negative values when the specified
multiformat value is applied to a currency field, this function will not
return parentheses. It will return the string defined as a negative symbol
using the Currency_SetNegativeSymbol() function. If one wasn’t defined
using that function, the operating system’s default negative string, most
commonly a minus sign (-), will be returned.

Examples The following example uses this function to retrieve the string used as a
negative symbol when the multiformat value 3000 is used.

local string neg_string;

neg_string = Currency_GetNegativeSymbol(3000);

Related items Commands

Currency_SetNegativeSymbol(), Currency_SetNegativeParens()

FUNCTION LIBRARY REFERENCE 109

C U R R E N C Y _ G E T N U M B E R O F D E C I M A L S ( )

Currency_GetNumberOfDecimals()
Description The Currency_GetNumberOfDecimals() function returns the number of
digits that will appear to the right of a currency value’s decimal separator
when the specified multiformat value is applied to a currency field.

Syntax Currency_GetNumberOfDecimals(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value Integer. If the number of decimal digits for use with the specified
multiformat value hasn’t been defined using the function
Currency_SetNumberOfDecimals(), the operating system’s default for
currency field decimal places will be used.

Comments This function ignores the currency format applied to the currency field’s
data type, should one exist.

Examples The following example uses this function to return the number of digits that
will appear to the right of the decimal separator when the multiformat
value 3000 is used.

local integer dec_digits;

dec_digits = Currency_GetNumberOfDecimals(3000);

Related items Commands

Currency_SetNumberOfDecimals()

110 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ G E T S Y M B O L ()

Currency_GetSymbol()
Description The Currency_GetSymbol() function returns the string used as a currency
symbol when the specified multiformat value is applied to a currency field.

Syntax Currency_GetSymbol(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value String. If a currency string or symbol has not been defined for the specified
multiformat value, the operating system’s currency string or symbol will be
returned.

Examples The following example uses this function to return the string used as a
currency symbol when the multiformat value 3000 is used.

local string c_symbol;

c_symbol = Currency_GetSymbol(3000);

Related items Commands

Currency_GetNegativeSymbol(), Currency_SetSymbol()

FUNCTION LIBRARY REFERENCE 111

C U R R E N C Y _ G E T T H O U S A N D S S Y M B O L ( )

Currency_GetThousandsSymbol()
Description The Currency_GetThousandsSymbol() function returns the string used as
a thousands separator when the specified multiformat value is applied to a
currency field.

Syntax Currency_GetThousandsSymbol(multiformat_value)

Parameters • multiformat_value – An integer value that was assigned to the currency

format you are inquiring about.

Return value String. If a thousands separator has not been defined for the specified
multiformat value, the operating system’s thousands separator will be
returned.

Examples The following example uses this function to return the string used as a
thousands separator when the multiformat value 3000 is used.

local string thousands_symbol;

thousands_symbol = Currency_GetThousandsSymbol(3000);

Related items Commands

Currency_SetThousandsSymbol()

112 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T D E C I M A L S Y M B O L ()

Currency_SetDecimalSymbol()
Description The Currency_SetDecimalSymbol() function defines a string to use as a
decimal separator when the specified multiformat value is applied to a
currency field.

Syntax Currency_SetDecimalSymbol(multiformat_value, decimal_symbol)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• decimal_symbol – A string value to be used as a decimal separator. This

string can be only one character in length.

Return value String specified in the decimal_symbol parameter.

Examples The following example could be used as part of the change script for the
save button in a window used to define currency formats. It uses this
function to define the decimal symbol string for the multiformat value 3000.
The value a user enters in the d_symbol field is used as the decimal_symbol
parameter. This function returns that specified value to the dec_symbol
field, which is then saved in the currency_format table.

dec_symbol of table currency_format = Currency_SetDecimalSymbol(3000,

➥ d_symbol);
save table currency_format;

Related items Commands

Currency_GetDecimalSymbol()

FUNCTION LIBRARY REFERENCE 113

C U R R E N C Y _ S E T L E A D I N G S Y M B O L ( )

Currency_SetLeadingSymbol()
Description The Currency_SetLeadingSymbol() function specifies whether the
currency symbol should appear before or after the value when the specified
multiformat value is applied to a currency field.

Syntax Currency_SetLeadingSymbol(multiformat_value, symbol_position)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• symbol_position – A boolean value indicating whether the currency symbol

will be placed before or after the currency value:

Value Description
true A leading currency symbol will be used.
false A trailing currency symbol will be used.

Return value Boolean specified in the symbol_position parameter.

Examples The following example is part of the change script for the save button in a
window used to define currency formats. It uses this function to define the
currency symbol placement for the multiformat value 3000, based upon
whether a user checked the lead_symbol check box. The result of this
function is set to the cs_placement field, which is saved in the
currency_format table.

cs_placement of table currency_format = Currency_SetLeadingSymbol

➥ (3000, lead_symbol);
save table currency_format;

Related items Commands

Currency_GetLeadingSymbol()

114 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T L E A D I N G Z E R O ()

Currency_SetLeadingZero()
Description The Currency_SetLeadingZero() function defines whether a currency value
less than 1 and greater than -1 will be displayed with a leading zero when
the specified multiformat value is applied to a currency field.

Syntax Currency_SetLeadingZero(multiformat_value, leading_zero)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• leading_zero – A boolean value indicating whether a leading zero will be

added to values less than 1 and greater than -1:

Value Description
true A leading zero will be used.
false A leading zero won’t be used.

Return value Boolean specified in the leading_zero parameter.

Examples The following example is part of the change script for the save button in a
window used to define currency formats. It uses this function to define
whether a leading zero will be used for the multiformat value 3000, based
upon whether a user checked the use_zero check box. The result of this
function is set to the lead_zero field, which is saved in the currency_format
table.

lead_zero of table currency_format = Currency_SetLeadingZero(3000,

➥ use_zero);
save table currency_format;

Related items Commands

Currency_GetLeadingZero()

FUNCTION LIBRARY REFERENCE 115

C U R R E N C Y _ S E T N E G A T I V E A F T E R V A L U E ( )

Currency_SetNegativeAfterValue()
Description The Currency_SetNegativeAfterValue() function defines whether the
negative symbol should be placed after the value when the specified
multiformat value is applied to a currency field.

Syntax Currency_SetNegativeAfterValue(multiformat_value, trailing_neg)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• trailing_neg – A boolean value indicating whether the negative symbol used

should be placed before or after the currency value:

Value Description
true A trailing negative symbol will be used.
false A leading negative symbol will be used.

Return value Boolean specified in the trailing_neg parameter.

Comments If this function is used in conjunction with the

Currency_SetNegativeBeforeSymbol() function, the negative symbol
placement defined using this function will be used.

If the Currency_SetNegativeParens() function is used to specify that

parentheses should be used to denote negative values, or if the operating
system’s default is to use parentheses for negative values, this setting will
be ignored and parentheses will be used.

Examples The following example is part of the change script for the save button in a
window used to define currency formats. It uses this function to define
whether a trailing negative symbol will be used for the multiformat value
3000, based upon whether a user checked the use_trailing check box. The
result of this function is set to the trailing_neg_sym field, which is saved in
the currency_format table.

trailing_neg_sym of table currency_format =

➥ Currency_SetNegativeAfterValue(3000, use_trailing);
save table currency_format;

116 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T N E G A T I V E A F T E R V A L U E ()

Related items Commands

Currency_GetNegativeAfterValue(), Currency_SetNegativeBeforeSymbol(),
Currency_SetNegativeParens()

FUNCTION LIBRARY REFERENCE 117

C U R R E N C Y _ S E T N E G A T I V E B E F O R E S Y M B O L ()

Currency_SetNegativeBeforeSymbol()
Description The Currency_SetNegativeBeforeSymbol() function defines whether a
leading negative symbol should be placed before or after a leading currency
symbol when the specified multiformat value is applied to a currency field.

Syntax Currency_SetNegativeBeforeSymbol(multiformat_value, neg_position)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• neg_position – A boolean value indicating the positioning of a leading

negative symbol:

Value Description
true A leading negative symbol will be placed before a
leading currency symbol.
false A leading negative symbol will be placed after a
leading currency symbol.

Return value Boolean specified in the neg_position parameter.

Comments If this function is used, it will be overridden by the following settings if they
are used and set to true:

• Currency_SetNegativeParens()
• Currency_SetNegativeAfterValue()

If the operating system’s default format for currency values uses

parentheses to denote a negative currency value, you must set the
Currency_SetNegativeParens() function to false to override the operating
system default. Until this occurs, the negative symbol and negative symbol
placement you specify will not be used.

If the operating system’s default format for currency values places the
negative symbol after the currency value, you must set the
Currency_SetNegativeAfterValue() function to false to override the
operating system default. Until this occurs, the negative symbol placement
you specify will not be used.

118 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T N E G A T I V E B E F O R E S Y M B O L ()

Examples The following example is part of the change script for the save button in a
window used to define currency formats. It uses this function to define the
position of a leading negative symbol for the multiformat value 3000, based
upon whether a user checked the neg_first check box. The result of this
function is set to the lead_neg_position field, which is saved in the
currency_format table.

lead_neg_position of table currency_format =

➥ Currency_SetNegativeBeforeSymbol(3000, neg_first);
save table currency_format;

Related items Commands

Currency_GetNegativeBeforeSymbol(), Currency_SetLeadingSymbol(),
Currency_SetNegativeAfterValue(), Currency_SetNegativeParens()

FUNCTION LIBRARY REFERENCE 119

C U R R E N C Y _ S E T N E G A T I V E P A R E N S ( )

Currency_SetNegativeParens()
Description The Currency_SetNegativeParens() function defines whether parentheses
should be used to denote a negative value when the specified multiformat
value is applied to a currency field.

Syntax Currency_SetNegativeParens(multiformat_value, use_parens)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• use_parens – A boolean value indicating whether parentheses should be

used to denote negative currency values:

Value Description
true Parentheses will be used.
false Parentheses won’t be used.

Return value Boolean specified in the use_parens parameter.

Comments If this function is used, it will override settings made by the following
functions:

• Currency_SetNegativeAfterValue()
• Currency_SetNegativeBeforeSymbol()
• Currency_SetNegativeSymbol()

If this function or the operating system’s default specifies that parentheses

should be used for a given multiformat value, then parentheses will be
used, regardless of whether the Currency_SetNegativeSymbol() function
was used to define a negative string, or the other functions were used to
define negative symbol placement. The negative string or symbol
placement specified using the other functions won’t be used with the
multiformat value until the Currency_SetNegativeParens() function is
used to explicitly state that parentheses shouldn’t be used, thus overriding
the operating system’s default.

120 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T N E G A T I V E P A R E N S ()

Examples The following example is part of the change script for the save button in a
window used to define currency formats. It uses this function to define
whether parentheses will be used for the multiformat value 3000, based
upon whether a user checked the neg_parens check box. The result of this
function is set to the use_neg_parens field, which is saved in the
currency_format table.

use_neg_parens of table currency_format = Currency_SetNegativeParens

➥ (3000, neg_parens);
save table currency_format;

Related items Commands

Currency_GetNegativeParens(), Currency_SetNegativeAfterValue(),
Currency_SetNegativeBeforeSymbol(), Currency_SetNegativeSymbol()

FUNCTION LIBRARY REFERENCE 121

C U R R E N C Y _ S E T N E G A T I V E S Y M B O L ( )

Currency_SetNegativeSymbol()
Description The Currency_SetNegativeSymbol() function defines a string to be used as
a negative symbol when the specified multiformat value is applied to a
currency field.

Syntax Currency_SetNegativeSymbol(multiformat_value, neg_string)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• neg_string – A string value to be used as a negative symbol. This string can

be up to five characters in length and can include spaces.

Return value String specified in the neg_string parameter.

Comments If the Currency_SetNegativeParens() function or the operating system’s

default specifies that parentheses should be used to indicate a negative
value, then parentheses will be used, regardless of whether the
Currency_SetNegativeSymbol() function was used to define a negative
string. The negative string won’t be used with the multiformat value until
the Currency_SetNegativeParens() function is used to explicitly state that
parentheses shouldn’t be used, thus overriding the operating system’s
default.

Examples The following example is part of the change script for the save button in a
window used to define currency formats. It uses this function to define a
string to be used as the negative symbol for the multiformat value 3000,
based upon a value entered in the neg_symbol field. The result of this
function is set to the negative_string field, which is saved in the
currency_format table.

negative_string of table currency_format = Currency_SetNegativeSymbol

➥ (3000, neg_symbol);
save table currency_format;

Related items Commands

Currency_GetNegativeSymbol(), Currency_SetNegativeParens()

122 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T N U M B E R O F D E C I M A L S ()

Currency_SetNumberOfDecimals()
Description The Currency_SetNumberOfDecimals() function defines the number of
digits that will appear to the right of the decimal separator when the
specified multiformat value is applied to a currency field.

Syntax Currency_SetNumberOfDecimals(multiformat_value, dec_digits)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• dec_digits – An integer specifying the number digits appearing to the right

of the decimal. Valid values are in the range 0-5.

Return value Integer specified in the dec_digits parameter.

Comments If this function isn’t used, the operating system’s default for currency
decimal places will be used, not the number of places specified in the
format defined for the data type the currency field is based upon.

Examples The following example uses this function to define the number of decimal
digits to be used for the multiformat value 3000. The value a user enters in
the digits field is used as the dec_digits parameter. This function returns the
specified value to the dec_number field, which is then saved in the
currency_format table.

dec_number of table currency_format to Currency_SetNumberOfDecimals

➥ (3000, digits);
save table currency_format;

Related items Commands

Currency_GetNumberOfDecimals()

FUNCTION LIBRARY REFERENCE 123

C U R R E N C Y _ S E T S Y M B O L ( )

Currency_SetSymbol()
Description The Currency_SetSymbol() function defines a string to use as a currency
symbol when the specified multiformat value is applied to a currency field.

Syntax Currency_SetSymbol(multiformat_value, currency_symbol)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• currency_symbol – A string value to be used as a currency symbol. This

string can be up to five characters in length and can include spaces.

Return value String specified in the currency_symbol parameter.

Examples The following example uses this function to define the currency symbol
string for the multiformat value 3000. The value a user enters in the
c_symbol field is used as the currency_symbol parameter. This function
returns the specified value to the curr_symbol field, which is then saved in
the currency_format table.

curr_symbol of table currency_format = Currency_SetSymbol(3000,

➥ c_symbol);
save table currency_format;

Related items Commands

Currency_GetNativeSymbol(), Currency_GetSymbol()

124 F U N C T I O N L I B R A R Y R E F E R E N C E
 C U R R E N C Y _ S E T T H O U S A N D S S Y M B O L ()

Currency_SetThousandsSymbol()
Description The Currency_SetThousandsSymbol() function defines a string to use as a
thousands separator when the specified multiformat value is applied to a
currency field.

Syntax Currency_SetThousandsSymbol(multiformat_value, thousands_symbol)

Parameters • multiformat_value – An integer value that you assign to the currency format
being defined. If your application is integrating with Microsoft Dynamics
GP (and your integrating dictionary has a product ID that is not zero), this
value must be in the 3000-4999 range. If you’re creating a stand-alone
application, this value must be in the 1000-2999 range.

• thousands_symbol – A string value to be used as a thousands separator. This

string can be only one character in length.

Return value String specified in the thousands_symbol parameter.

Examples The following example uses this function to define the thousands separator
for the multiformat value 3000. The value a user enters in the t_symbol field
is used as the thousands_symbol parameter. This function returns the
specified value to the thou_symbol field, which is then saved in the
currency_format table.

thou_symbol of table currency_format = Currency_SetThousandsSymbol

➥ (3000, t_symbol);
save table currency_format;

Related items Commands

Currency_GetThousandsSymbol()

FUNCTION LIBRARY REFERENCE 125

126 F U N C T I O N L I B R A R Y R E F E R E N C E
 Defaults file function library
Refer to descriptions of
Dexterity defaults file
settings in the
Dexterity online help
for more information.
Use the functions in this library when working with the defaults file
(DEX.INI) in your application. This library contains the following functions:
• Defaults_ClearUserFile()
• Defaults_Read()
• Defaults_ReadBoolean()
• Defaults_ReadColor()
• Defaults_ReadKeys()
• Defaults_Write()
FUNCTION LIBRARY REFERENCE 127
D E F A U L T S _ C L E A R U S E R F I L E ( )

Defaults_ClearUserFile()
Description The Defaults_ClearUserFile() function clears the contents of the user-
specifc DEX.INI file.

Parameters • None

Return value None

Comments This function is typically used when “switch user” functionality is

implemented in a stand-alone application.

Examples Refer to the example for the Defaults_ReadKeys() function.

128 F U N C T I O N L I B R A R Y R E F E R E N C E
 D E F A U L T S _ R E A D ()

Defaults_Read()
Description The Defaults_Read() function reads the value of a setting in the Dexterity
defaults file.

Syntax Defaults_Read(setting {, target})

Parameters • setting – A string specifying the setting to read.

• target – An optional integer parameter that applies when the per-user

defaults file is enabled. The following constants can be used to specify the
value:

Constant Description
USER_INI Accesses the user-specific DEX.INI file, found in the user’s
temporary folder.
GLOBAL_INI Accesses the global DEX.INI file, found in the Data folder
of the application.

When specifying the optional target parameter, you can add the constant
values together (USER_INI + GLOBAL_INI) to read the value from the
user-specific DEX.INI file, and then from the global DEX.INI file. This is the
default behavior when the per-user defaults file is enabled, and you don’t
specify the target.

Return value A string indicating the value of setting. If the setting doesn’t exist, the
returned string will be empty.

Examples The following example reads the value of the Pathname setting in the
defaults file and sets a window field.

'Pathname' = Defaults_Read("Pathname");

The following example reads the value of the AutomaticLogout setting in

the from the user-specific DEX.INI file. If the per-user defaults file
functionality isn’t active, the value is read from the global DEX.INI file.
local string auto_logout;

auto_logout = Defaults_Read("AutomaticLogout", USER_INI);

Related items Additional information

The defaults file settings in the Dexterity online help

FUNCTION LIBRARY REFERENCE 129

D E F A U L T S _ R E A D B O O L E A N ( )

Defaults_ReadBoolean()
Description The Defaults_ReadBoolean() function reads a boolean value from the
Defaults file.

Syntax Defaults_ReadBoolean(setting, default_value {, target})

Parameters • setting – A string specifying the setting to read.

• default_value – A boolean specifying the boolean value to return if the setting

isn’t found in the defaults file.

• target – An optional integer parameter that applies when the per-user

defaults file is enabled. The following constants can be used to specify the
value:

Constant Description
USER_INI Accesses the user-specific DEX.INI file, found in the user’s
temporary folder.
GLOBAL_INI Accesses the global DEX.INI file, found in the Data folder
of the application.

When specifying the optional target parameter, you can add the constant
values together (USER_INI + GLOBAL_INI) to read the value from the
user-specific DEX.INI file, and then from the global DEX.INI file. This is the
default behavior when the per-user defaults file is enabled, and you don’t
specify the target.

Return value A boolean containing the value. If the setting isn’t found, the default
boolean value is returned.

Comments The string value retrieved from the defaults file is converted to uppercase
and compared with the string “TRUE”. If the strings match, then true is
returned. Otherwise, false is returned.

Examples The following example uses the Defaults_ReadBoolean() function to read a

boolean value from the Defaults file. If the RememberLastUser setting isn’t
found, the boolean value false is returned.
local boolean remember_last_user;

{Read the setting from the Defaults file.}

remember_last_user = Defaults_ReadBoolean("RememberLastUser", false);

130 F U N C T I O N L I B R A R Y R E F E R E N C E
 D E F A U L T S _ R E A D C O L O R ()

Defaults_ReadColor()
Description The Defaults_ReadColor() function reads a color value from the Defaults
file.

Syntax Defaults_ReadColor(setting, default_color_value {, target})

Parameters • setting – A string specifying the setting to read.

• default_color_value – A long integer specifying the color value to return if the

setting isn’t found in the defaults file.

• target – An optional integer parameter that applies when the per-user

defaults file is enabled. The following constants can be used to specify the
value:

Constant Description
USER_INI Accesses the user-specific DEX.INI file, found in the user’s
temporary folder.
GLOBAL_INI Accesses the global DEX.INI file, found in the Data folder
of the application.

When specifying the optional target parameter, you can add the constant
values together (USER_INI + GLOBAL_INI) to read the value from the
user-specific DEX.INI file, and then from the global DEX.INI file. This is the
default behavior when the per-user defaults file is enabled, and you don’t
specify the target.

Return value A long integer containing the color value. If the setting isn’t found, the
default color value is returned.

Comments The color value in the defaults file can be the name of a predefined
Dexterity color. It can also be a color value in decimal or hexadecimal
format. The following table lists the predefined color names for Dexterity.

Black Green Teal

Blue Light Gray Turquoise
Bright Green Light Yellow Violet
Dark Blue Medium Gray White
Dark Red Pink Yellow
Dark Yellow Red

FUNCTION LIBRARY REFERENCE 131

D E F A U L T S _ R E A D C O L O R ( )

Examples The following example uses the Defaults_ReadColor() function to read a

color value from the Defaults file. If the FieldColor setting isn’t found,
the color value for white is returned.

local long color_value;

{Read the color from the Defaults file.}

color_value = Defaults_ReadColor("FieldColor", COLOR_WHITE);

Related items Additional information

Color function library

132 F U N C T I O N L I B R A R Y R E F E R E N C E
 D E F A U L T S _ R E A D K E Y S ()

Defaults_ReadKeys()
Description The Defaults_ReadKeys() function reads all of the key values in the
specified DEX.INI file.

Syntax Defaults_ReadKeys(key_list {, target})

Parameters • key_list – A list field that will contain the key values that were retrieved
from the specified DEX.INI file.

• target – An optional integer parameter that applies when the per-user

defaults file is enabled. The following constants can be used to specify the
value:

Constant Description
USER_INI Accesses the user-specific DEX.INI file, found in the user’s
temporary folder.
GLOBAL_INI Accesses the global DEX.INI file, found in the Data folder
of the application.

Return value A boolean. The value true indicates that the key values were retrieved. The
value false indicates that an error occurred.

Examples The following example shows a script that is run when a different user is
logging into a stand-alone application. If the user-specific defaults file is
being used, then the Defaults_ReadKeys() function settings reads the keys
from that file, and a helper procedure saves the values to the appropriate
table in the database. Finally, the Defaults_ClearUserFile() function
removes the user’s settings from the defaults file to prepare it for the new
user that is logging in.

local boolean result;

{Is a user-specific defaults file being used?}

if Defaults_ReadBoolean("EnablePerUserIni",false, GLOBAL_INI) then

{Read the user-specific DEX.INI values.}

result = Defaults_ReadKeys('(L) KeyValues', USER_INI);

{Were the keys successfully read?}

if result = true then

{Call a helper procedure that saves the INI values to the

FUNCTION LIBRARY REFERENCE 133

D E F A U L T S _ R E A D K E Y S ( )

database.}
call SaveINIValues, '(L) KeyValues', UserID of globals;

{Clear the user-specific DEX.INI for the next user.}

Defaults_ClearUserFile();

end if;
end if;

134 F U N C T I O N L I B R A R Y R E F E R E N C E
 D E F A U L T S _ W R I T E ()

Defaults_Write()
Description The Defaults_Write() function writes a setting to the Dexterity defaults file.

Syntax Defaults_Write(setting, value {, target})

Parameters • setting – A string indicating the setting in the file you want to write to. If
setting doesn’t exist, one is created.

• value – A string specifying a value for setting.

• target – An optional integer parameter that applies when the per-user

defaults file is enabled. The following constants can be used to specify the
value:

Constant Description
USER_INI Accesses the user-specific DEX.INI file, found in the user’s
temporary folder.
GLOBAL_INI Accesses the global DEX.INI file, found in the Data folder
of the application.

If the per-user defaults file is not enabled, the setting will be written to the
global DEX.INI file found in the Data folder of the application. If the per-
user defaults file is enabled, but the target is not specified, the value will be
written to the user-specific DEX.INI file.

Return value The boolean value true.

Examples This example writes a new pathname to the Pathname setting in the global
defaults file. It opens a dialog box using the Path_SelectPathname()
function, and returns a pathname. The Defaults_Write() function then
writes this pathname to the Pathname setting in the global defaults file.

local boolean l_result;

if Path_SelectPathname('New Pathname') then

l_result = Defaults_Write("Pathname", 'New Pathname', GLOBAL_INI);
end if;

Related items Additional information

The defaults file settings listed in the Dexterity online help

FUNCTION LIBRARY REFERENCE 135

136 F U N C T I O N L I B R A R Y R E F E R E N C E
 Dexterity object function library
Refer to Chapter 40, Use the functions in this library to create COM callback objects. The
“Callbacks and Events,” function library contains the following functions:
in Volume 2 of the Dex-
terity Programmer’s • DexObject_AddMethod()
Guide for more infor- • DexObject_AddProperty()
mation about creating • DexObject_Create()
and using callback
objects.

FUNCTION LIBRARY REFERENCE 137

D E X O B J E C T _ A D D M E T H O D ()

DexObject_AddMethod()
Description The DexObject_AddMethod() function adds a method to a callback object.

Syntax DexObject_AddMethod(callback_object, method_name, function script

{, dispatch_id})

Parameters • callback_object – A reference to the callback object to which the method is

being added.

• method_name – A string specifying the name for the method. Each method
in the callback object must have a unique name.

• function script – A user-defined function that is run when the method in the
callback object is invoked.

• dispatch_id – An optional long integer that uniquely identifies the method in

the callback object. It is typically represented as a hexadecimal value. This
value is required if the callback object is being used as an event handler.

Return value A boolean indicating whether the method was added. True indicates that
the method was added, while false indicates that it was not.

Comments If you are creating a callback object to handle events from another
application, be sure the method has exactly the same name as the
corresponding method in the COM interface for that application. The name
is case-sensitive.

Examples The following example creates a callback object that allows external
applications to access information about the user currently logged into the
application. The DexObject_AddMethod() function is used to add the
“VerifyPassword” method to the callback object. A user-defined function
with the name “VerifyPassword” has already been added to the application,
and will be run when the VerifyPassword method is invoked.

local reference callback_obj;

local boolean result;
local long obj_id;

{Create the callback object}

callback_obj = DexObject_Create();

138 F U N C T I O N L I B R A R Y R E F E R E N C E
 D E X O B J E C T _ A D D M E T H O D ()

{Add properties to the callback object}

result = DexObject_AddProperty(callback_obj, "UserID", FT_STRING);
result = DexObject_AddProperty(callback_obj, "Name", FT_STRING);

{Add a method to the callback object}

result = DexObject_AddMethod(callback_obj, "VerifyPassword", function
➥ VerifyPassword);

{Add the callback to the running object table}

obj_id = COM_RegisterRunningObject(callback_obj, "RESM.LoginInfo");

The following example creates an event handler for the Activate event of
the currently active workbook in Microsoft Excel. It uses the
DexObject_AddMethod() function to add the “Activate” method to the
callback object. Because the method is being used in a callback to handle the
“Activate” event, the name must match the event name specified in the
type library for Excel.

local Excel.Application app;

local reference callback_obj;
local long handler_id;

{Retrieve a reference to Excel.}

app = COM_GetObject("Excel.Application");

if app <> null then

{Create the callback object to handle the event.}
callback_obj = DexObject_Create();

{Add the method for the Activate event.}

DexObject_AddMethod(callback_obj, "Activate", function
➥ ActivateHandler);

{Attach the callback object.}

handler_id = COM_AttachEventHandler(app.ActiveWorkbook,
➥ callback_obj);
if handler_id = 0 then
error "Could not attach event handler.";
end if;
end if;

FUNCTION LIBRARY REFERENCE 139

D E X O B J E C T _ A D D P R O P E R T Y ( )

DexObject_AddProperty()
Description The DexObject_AddProperty() function adds a property to a callback
object.

Syntax DexObject_AddProperty(callback_object, name, type {, dispatch_id})

Parameters • callback_object – A reference to the callback object to which a property is

being added.

• name – A string specifying the name for the property being added to the
callback. Each property in the callback object must have a unique name.

• type – An integer that specifies the property type. The following values are
valid types.

DATATYPE_BOOLEAN DATATYPE_INTEGER
DATATYPE_CURRENCY DATATYPE_LONG_INTEGER
DATATYPE_VCURRENCY DATATYPE_REFERENCE
DATATYPE_DATE DATATYPE_STRING
DATATYPE_DATETIME DATATYPE_TIME

• dispatch_id - An optional long integer that specifies the identifier for the
property. It is typically represented as a hexadecimal value.

Return value A boolean indicating whether the property was added. True indicates that
the property was added, while false indicates that it was not.

Comments If you are creating a callback object to handle events from another
application, be sure the property has exactly the same name as the
corresponding property in the COM interface for that application. The
name is case-sensitive.

140 F U N C T I O N L I B R A R Y R E F E R E N C E
 D E X O B J E C T _ A D D P R O P E R T Y ()

Examples The following example creates a callback object that allows external
applications to access information about the user currently logged into the
application. The DexObject_AddProperty() function is used to add the
“UserID” and “Name” properties to the callback object.

local reference callback_obj;

local boolean result;
local long obj_id;

{Create the callback object}

callback_obj = DexObject_Create();

{Add properties to the callback object}

result = DexObject_AddProperty(callback_obj, "UserID",
➥ DATATYPE_STRING);
result = DexObject_AddProperty(callback_obj, "Name",
➥ DATATYPE_STRING);

{Add a method to the callback object}

result = DexObject_AddMethod(callback_obj, "VerifyPassword", function
➥ VerifyPassword);

obj_id = COM_RegisterRunningObject(callback_obj, "RESM.LoginInfo");

FUNCTION LIBRARY REFERENCE 141

D E X O B J E C T _ C R E A T E ( )

DexObject_Create()
Description The DexObject_Create() function creates a callback object.

Syntax DexObject_Create()

Parameters • None

Return value A reference to the created callback object.

Examples The following example uses the DexObject_Create() function to create a

callback object that can be referenced by other applications.

local reference callback_obj;

local boolean result;
local long obj_id;

{Create the callback object}

callback_obj = DexObject_Create();

{Add properties to the callback object}

result = DexObject_AddProperty(callback_obj, "UserID",
➥ DATATYPE_STRING);
result = DexObject_AddProperty(callback_obj, "Name",
➥ DATATYPE_STRING);

{Add a method to the callback object}

result = DexObject_AddMethod(callback_obj, "VerifyPassword", function
➥ VerifyPassword);

obj_id = COM_RegisterRunningObject(callback_obj, "RESM.LoginInfo");

Related items Commands

DexObject_AddProperty(), DexObject_AddMethod()

142 F U N C T I O N L I B R A R Y R E F E R E N C E
 Dictionary function library
Use the functions in this library when working with dictionaries in your
application. This library contains the following functions:

• Dict_CountCustomResource()
• Dict_GetCustomResourceInfo()
• Dict_GetName()
• Dict_GetPathname()
• Dict_LockCustom()
• Dict_UnlockCustom()
• Dict_UpdateFormsDictionary()
• Dict_UpdateReportsDictionary()

Some of the functions in this library work together to perform certain

operations. The related functions are grouped in the following lists.

These functions read information about the resources in the forms and
reports dictionaries for an application.

• Dict_CountCustomResource()
• Dict_GetCustomResourceInfo()
• Dict_LockCustom()
• Dict_UnlockCustom()

Refer to Chapter 60, These functions update the forms and reports dictionaries when you
“Updating an Applica- upgrade your application from one version to the next. Typically, these
tion,” in Volume 1 of functions are used in a utility application that migrates users from the
the Dexterity Program- current version of your application to the next version.
mer's Guide for more
information about • Dict_UpdateFormsDictionary()
updating applications. • Dict_UpdateReportsDictionary()

FUNCTION LIBRARY REFERENCE 143

D I C T _ C O U N T C U S T O M R E S O U R C E ( )

Dict_CountCustomResource()
Description The Dict_CountCustomResource() function returns the number of forms in
the forms dictionary, or the number of reports in the reports dictionary.

Syntax Dict_CountCustomResource(product_ID, resource_type)

Parameters • product_ID – The product ID of the dictionary whose forms or reports

dictionaries contain forms or reports you’re counting.

• resource_type – An integer, represented by the following constants,

indicating the resource type you want to count:

Constant Description
REPORTTYPE Count reports in the reports dictionary.
FORMTYPE Count forms in the forms dictionary.

Return value An integer indicating the number of forms or reports in the forms or reports
dictionary.

Comments With a form or report count, you can use the

Dict_GetCustomResourceInfo() function to fill a list with resources from a
selected series.

Counting forms or reports in a custom dictionary will work only if your application
is opened with the runtime engine. Dexterity test mode has no provisions for
accessing information for forms and reports dictionaries.

Check the availability of the custom dictionary using the

Dict_LockCustom() function prior to using this function. Use the
Dict_UnlockCustom() function to release the lock on a custom dictionary.

144 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ C O U N T C U S T O M R E S O U R C E ()

Examples This example uses the Dict_CountCustomResource() function to count the

number of forms in the forms dictionary, then fills a list field with
the names of the forms. The script passes the returned count to the
Dict_GetCustomResourceInfo() function in a for do...end for statement to
add each form in the forms dictionary to the list field.

local integer l_form_ID, l_count, l_resource_ID, l_index,

➥ l_form_flag, l_report_flag;
local string l_form_name;
local boolean l_result;

l_result = Dict_LockCustom(3333, l_form_flag, l_report_flag);

if l_form_flag = 0 then
l_count = Dict_CountCustomResource(3333, FORMTYPE);
for l_index equals 1 to l_count do
l_form_ID = Dict_GetCustomResourceInfo(3333, FORMTYPE,
➥ l_index, 10, l_form_name);
if l_form_ID <> 0 then
add item l_form_name to '(L) Form List';
end if;
end for;
redraw field '(L) Form List';
elseif l_form_flag = 1 then
warning "No forms dictionary exists.";
elseif l_form_flag = 2 then
warning "The forms dictionary is already in use.";
end if;
l_result = Dict_UnlockCustom(3333);

FUNCTION LIBRARY REFERENCE 145

D I C T _ G E T C U S T O M R E S O U R C E I N F O ( )

Dict_GetCustomResourceInfo()
Description The Dict_GetCustomResourceInfo() function returns information about a
form in a forms dictionary, or a report in a reports dictionary.

Syntax Dict_GetCustomResourceInfo(product_ID, resource_type, index, series,

resource_name)

Parameters • product_ID – The product ID of the dictionary whose forms or reports

dictionaries contain forms or reports you’re retrieving information about.

• resource_type – An integer specifying the type of resource for which you

want information returned. Use one of the following constants:

Constant Description
REPORTTYPE Indicates a report resource type.
FORMTYPE Indicates a form resource type.

• index – An integer specifying a resource in the forms or reports dictionary.

An index of 1 specifies the first form or report in the selected series, 2
specifies the second, and so on.

• series – An integer specifying the series from which you want to retrieve
form or report information. The following table lists all series that can be
applied to forms and reports and their corresponding integer values.

1–Financial 6–Project 11–Macro System

2–Sales 7–System 12–Palette
3–Purchasing 8–Company 13–Dexterity
4–Inventory 9–Online Documentation 14–Dexterity System
5–Payroll 10–3rd Party 15–Report Writer

• resource_name – A returned string containing the name of the form or report.

For forms, this is the display name of the first window in the form.

Return value An integer containing the resource ID for the form or report for which
information was retrieved.

Comments Use the count returned by Dict_CountCustomResource() in a for do...end

for loop to fill a list with the values for the resource_name.

146 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ G E T C U S T O M R E S O U R C E I N F O ()

Counting forms or reports in a custom dictionary will work only if your application
is opened with the runtime engine. Dexterity test mode has no provisions for
accessing information for forms and reports dictionaries.

Check the availability of the custom dictionary using the

Dict_LockCustom() function prior to using this function. Use the
Dict_UnlockCustom() function to release the lock on a custom dictionary.

Examples Refer to the example for the Dict_CountCustomResource() function.

FUNCTION LIBRARY REFERENCE 147

D I C T _ G E T N A M E ()

Dict_GetName()
Description The Dict_GetName() function returns the operating system name of the
current application dictionary.

Syntax Dict_GetName()

Parameters • None

Return value A string containing the name of the dictionary.

Comments This function returns the operating system name of the “current”
application dictionary. In a multidictionary environment, this is the
dictionary whose form is currently active, or topmost.

Examples This example sets a window field to the name of the current dictionary:

'Dictionary Name' = Dict_GetName();

148 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ G E T P A T H N A M E ()

Dict_GetPathname()
Description The Dict_GetPathname() function returns the generic path of various
components of the current installation, such as the runtime engine or
launch file.

Syntax Dict_GetPathname(option)

Parameters • option – An integer specifying the type of pathname:

Constant Value Description

PATH_EXEFOLDER 1 The path of the folder containing the runtime
engine (Dynamics.exe).
PATH_SETFOLDER 2 In test mode, the path of the folder containing the
application dictionary currently in use. With the
runtime engine, the path of the folder containing
the launch file used to start the application.
PATH_DATAFOLDER 3 The path to the “Data” folder for the installation.
Files writable by the user are stored in this folder.
PATH_USERDEXINIFILE 4 The path of the user-specific Dex.ini file currently
being used. If per-user defaults files are not
active, the path to the global Dex.ini is returned.
PATH_SETFILE 5 The path of the launch file (.set file) currently
being used.
PATH_GLOBALDEXINIFILE 6 The path to the global Dex.ini file, found in the
“Data” folder for the installation.

Return value A string containing the path requested in generic format.

Comments The path that’s returned is in a generic format. Generic pathnames use a
colon (:) before and after DOS drive letters. The characters that separate
folders and directories are forward slashes (/).

Native pathname Generic pathname

C:\DEX\TOOLS\ :C:DEX/TOOLS/

Examples This example sets a window field to the path that contains the current
application dictionary or launch file being used:
'(L) Pathname' = Dict_GetPathname(PATH_SETFOLDER);

Related items Commands

Launch_SelectDict(), Launch_ReadDictPath(), Launch_WriteDictPath(),
File_GetTempDirectory(), getfile()

FUNCTION LIBRARY REFERENCE 149

D I C T _ L O C K C U S T O M ( )

Dict_LockCustom()
Description The Dict_LockCustom() function attempts to open a forms or reports
dictionary. If it can, it locks the dictionary, preventing other users from
accessing the dictionary.

Syntax Dict_LockCustom(product_ID, form_flag, report_flag)

Parameters • product_ID – An integer specifying the application’s product ID.

• form_flag – A returned integer indicating whether the forms dictionary is

available:

Value Description
0 No error
1 No dictionary
2 Unable to open

If the result is no error (0), the forms dictionary is opened and locked.

• report_flag – A returned integer indicating whether the reports dictionary is

available:

Value Description
0 No error
1 No dictionary
2 Unable to open

If the result is no error (0), the reports dictionary is opened and locked.

Return value A boolean representing the result; true only if both the forms and reports
dictionaries are available, and false if one or both are unavailable.

Comments Always use the Dict_UnlockCustom() function to release a lock on a

custom dictionary.

This function will work only if your application is opened with the runtime engine.
Dexterity test mode has no provisions for accessing information for forms and
reports dictionaries.

Examples Refer to the example for the Dict_CountCustomResource() function.

150 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ U N L O C K C U S T O M ()

Dict_UnlockCustom()
Description The Dict_UnlockCustom() function releases the dictionary lock imposed
by the Dict_LockCustom() function.

Syntax Dict_UnlockCustom(product_ID)

Parameters • product_ID – An integer for the application’s product ID.

Return value The boolean value true.

Comments Always unlock any custom dictionary opened and locked using the
Dict_LockCustom() function.

Examples Refer to the example for the Dict_CountCustomResource() function.

FUNCTION LIBRARY REFERENCE 151

D I C T _ U P D A T E F O R M S D I C T I O N A R Y ()

Dict_UpdateFormsDictionary()
Description The Dict_UpdateFormsDictionary() function updates a forms dictionary to
work with the new version of your application. This function attempts to
preserve the modifications made to the forms in the forms dictionary.

Syntax Dict_UpdateFormsDictionary(main_product_dictionary,
previous_application_dictionary, new_application_dictionary, forms_dictionary,
exception_script, progress_script)

Parameters • main_product_dictionary – A string containing the complete path, in generic

format, to the main product dictionary. If the forms dictionary being
updated isn’t part of a product that integrates with a main product like
Microsoft Dynamics GP, set this parameter to the empty string (""). If the
forms dictionary being updated is part of a product that integrates with
Microsoft Dynamics GP, set this parameter to the path to the Dynamics.dic
dictionary.

• previous_application_dictionary – A string containing the complete path, in

generic format, to the previous version of the application dictionary.

• new_application_dictionary – A string containing the complete path, in

generic format, to the new version of the application dictionary.

• forms_dictionary – A string containing the complete path, in generic format,

to the forms dictionary being updated.

• exception_script – A form-level procedure that is called when exceptions are

encountered during the update process.

• progress_script – A form-level procedure that is called to indicate the

progress of the update process.

Return value An integer corresponding to one of the following constants:

Constant
STATUS_SUCCESS
STATUS_PRIMARY_DICT_MISSING
STATUS_OLD_PROD_DICT_MISSING
STATUS_NEW_PROD_DICT_MISSING
STATUS_FORM_DICT_MISSING
STATUS_VERSION_INCOMPATIBLE
STATUS_ERROR
Description
No error occurred.
Unable to open main product dictionary.
Unable to open previous application dictionary.
Unable to open new application dictionary.
Unable to open forms dictionary.
The forms dictionary is not compatible with the
previous application dictionary.
An unknown error occurred.

152 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ U P D A T E F O R M S D I C T I O N A R Y ()

Comments The updating operation performed by this function is also performed

automatically during the unchunking process.

The exception script is a form-level procedure that is called each time an

exception occurs during the update process. Typically, you will save the
exception information to a log file. This procedure must have the following
parameters:

• source_file – A string in parameter containing the name of the source file

being processed when the exception occurred.

• phase – A string in parameter containing the name of the phase being

executed when the exception occurred.

• error_text – A string in parameter describing the exception that

occurred.

• resource_type – A string in parameter identifying the type of resource for

which the exception occurred.

• resource_name – A string in parameter identifying the resource for

which the exception occurred.

The progress script is a form-level procedure that is called periodically

during the update process. This procedure must have the following
parameters:

• total_phases – An integer in parameter containing the total number of

phases needed to complete the update process.

• current_phase – An integer in parameter indicating the phase currently

being processed.

• total_steps – An integer in parameter containing the total number of

steps needed to complete the current phase.

• current_step – An integer in parameter indicating the step currently

being processed.

• source_file – A string in parameter containing the name of the source file

currently being processed.

• phase – A string in parameter containing the name of the phase cur-

rently being processed.

FUNCTION LIBRARY REFERENCE 153

D I C T _ U P D A T E F O R M S D I C T I O N A R Y ()

Examples The following example updates the forms dictionary for the RESM sample
application. The exception and progress scripts are part of the
Progress_Control form, which will show the progress of the update process.
The previous version of the application was renamed RESM4.DIC. All
dictionaries needed to perform the update are in the same location as the
runtime engine.

local string main_product_dictionary;

local string previous_application_dictionary;
local string new_application_dictionary;
local string forms_dictionary;
local string path;
local integer result;

{Get the location of the runtime engine.}

path = Path_GetForApp(1);

{Set up the locations of the dictionaries.}

main_product_dictionary = ""; {Not an integrating application.}
previous_application_dictionary = path + "RESM4.DIC";
new_application_dictionary = path + "RESM.DIC";
forms_dictionary = path + "RESMFORM.DIC";

{Perform the update.}

result = Dict_UpdateFormsDictionary(main_product_dictionary,
➥ previous_application_dictionary,new_application_dictionary,
➥ forms_dictionary, script Log_Exceptions of form Progress_Control,
➥ script Update_Progress of form Progress_Control);

{Did an error occur?}

case result
in [STATUS_OLD_PROD_DICT_MISSING]
error "Could not open the previous version of the application
➥ dictionary.";
in [STATUS_NEW_PROD_DICT_MISSING]
error "Could not open the new version of the application
➥ dictionary.";
in [STATUS_FORM_DICT_MISSING]
error "Could not open the forms dictionary.";
in [STATUS_VERSION_INCOMPATIBLE]
error "The forms dictionary is not compatible with the
➥ previous version of the application dictionary.";
end case;

154 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ U P D A T E F O R M S D I C T I O N A R Y ()

Related items Additional information

Chapter 60, “Updating an Application,” in Volume 1 of the Dexterity Programmer’s
Guide
Chapter 49, “Updating an Application,” in the Integration Guide

FUNCTION LIBRARY REFERENCE 155

D I C T _ U P D A T E R E P O R T S D I C T I O N A R Y ()

Dict_UpdateReportsDictionary()
Description
The Dict_UpdateReportsDictionary() function updates a reports
dictionary to work with the new version of your application. This function
attempts to preserve the modifications made to the reports in the reports
dictionary. The update is performed in two parts. The first part updates
resources in the reports dictionary. The second part updates reports to make
them compatible with database changes in the application.

Syntax Dict_UpdateReportsDictionary(main_product_dictionary,
previous_application_dictionary, new_application_dictionary, reports_dictionary,
exception_script, progress_script, from_version, to_version, input_file,
output_file)

Parameters • main_product_dictionary – A string containing the complete path, in generic

format, to the main product dictionary. If the reports dictionary being
updated isn’t part of a product that integrates with a main product like
Microsoft Dynamics GP, set this parameter to the empty string (""). If the
reports dictionary being updated is part of a product that integrates with
Microsoft Dynamics GP, set this parameter to the path to the Dynamics.dic
dictionary.

• previous_application_dictionary – A string containing the complete path, in

generic format, to the previous version of the application dictionary. If you
don’t want to perform the first part of the report update process, specify the
empty string ("") for this parameter.

• new_application_dictionary – A string containing the complete path, in

generic format, to the new version of the application dictionary.

• reports_dictionary – A string containing the complete path, in generic format,

to the reports dictionary being updated.

• exception_script – A form-level procedure that is called when exceptions are

encountered during the update process.

• progress_script – A form-level procedure that is called to indicate the

progress of the update process.

• from_version – A string specifying the product version to update from. This

value is used to indicate which sections of the input file will be used when
performing the second part of the report update. If you want the second
part of the report update process to simply perform a “cleanup” operation,
specify the empty string ("") for this parameter.

156 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ U P D A T E R E P O R T S D I C T I O N A R Y ()

• to_version – A string specifying the product version to update to. This value
is used to indicate which sections of the input file will be used when
performing the second part of the report update. If you want the second
part of the report update process to simply perform a “cleanup” operation,
specify the empty string ("") for this parameter.

• input_file – A string specifying the complete path, in generic format, to the

input file containing information for the second part of the report update. If
you want the second part of the report update process to simply perform a
“cleanup” operation, specify the empty string ("") for this parameter.

• output_file – A string specifying the complete path, in generic format, to a

text file that will contain a log of all the changes applied to the reports
dictionary.

Return value An integer corresponding to one of the following constants:

Constant
STATUS_SUCCESS
STATUS_PRIMARY_DICT_MISSING
STATUS_OLD_PROD_DICT_MISSING
STATUS_NEW_PROD_DICT_MISSING
STATUS_REPORT_DICT_MISSING
STATUS_ERROR_OPENING_LOG
STATUS_ERROR_OPENING_INPUT
STATUS_INPUT_FILE_ERROR
STATUS_VERSION_INCOMPATIBLE
STATUS_ERROR
Description
No error occurred.
Unable to open main product dictionary.
Unable to open previous application dictionary.
Unable to open new application dictionary.
Unable to open reports dictionary.
Unable to open the log file.
Unable to open the input file.
An error exists in the input file contents.
The reports dictionary is not compatible with the
previous application dictionary.
An unknown error occurred.

Comments The first part of the the updating operation performed by this function is
also performed automatically during the unchunking process. If the first
part of the report update (updating resources in the reports dictionary) was
performed as part of unchunking, we recommend that you use the
Dict_UpdateReportsDictionary() function in an installation script to
perform the second part of the update process. If you haven’t made any
database changes or don’t have an input file, we still recommend
performing the second part of the update because it performs some
“cleanup” operations on the reports dictionary.

FUNCTION LIBRARY REFERENCE 157

D I C T _ U P D A T E R E P O R T S D I C T I O N A R Y ()

The exception script is a form-level procedure that is called each time an

exception occurs during the update process. Typically, you will save the
exception information to a log file. This procedure must have the following
parameters:

• source_file – A string in parameter containing the name of the source file

being processed when the exception occurred.

• phase – A string in parameter containing the name of the phase being

executed when the exception occurred.

• error_text – A string in parameter describing the exception that

occurred.

• resource_type – A string in parameter identifying the type of resource for

which the exception occurred.

• resource_name – A string in parameter identifying the resource for

which the exception occurred.

The progress script is a form-level procedure that is called periodically

during the update process. This procedure must have the following
parameters:

• total_phases – An integer in parameter containing the total number of

phases needed to complete the update process.

• current_phase – An integer in parameter indicating the phase currently

being processed.

• total_steps – An integer in parameter containing the total number of

steps needed to complete the current phase.

• current_step – An integer in parameter indicating the step currently

being processed.

• source_file – A string in parameter containing the name of the source file

currently being processed.

• phase – A string in parameter containing the name of the phase cur-

rently being processed.

158 F U N C T I O N L I B R A R Y R E F E R E N C E
 D I C T _ U P D A T E R E P O R T S D I C T I O N A R Y ()

Examples The following example shows how you would update the reports
dictionary for the RESM sample application. The exception and progress
scripts are part of the Progress_Control form, which will show the progress
of the update process. The previous version of the application was renamed
RESM4.DIC. All dictionaries needed to perform the update are in the same
location as the runtime engine.

local string main_product_dictionary;

local string previous_application_dictionary;
local string new_application_dictionary;
local string reports_dictionary;
local string input_file;
local string output_file;
local string path;
local integer result;

{Get the location of the runtime engine.}

path = Path_GetForApp(1);

{Set up the locations of the dictionaries.}

main_product_dictionary = ""; {Not an integrating application.}
previous_application_dictionary = path + "RESM4.DIC";
new_application_dictionary = path + "RESM.DIC";
reports_dictionary = path + "RESMREPT.DIC";
input_file = path + "Update.txt";
output_file = path + "RESM_LOG.txt";

{Perform the update.}

result = Dict_UpdateReportsDictionary(main_product_dictionary,
➥ previous_application_dictionary, new_application_dictionary,
➥ reports_dictionary, script Log_Exceptions of form Progress_Control,
➥ script Update_Progress of form Progress_Control, "RESM 4.0",
➥ "RESM 5.0", input_file, output_file);

{Did an error occur?}

case result
in [STATUS_OLD_PROD_DICT_MISSING]
error "Could not open the previous version of the application
➥ dictionary.";
in [STATUS_NEW_PROD_DICT_MISSING]
error "Could not open the new version of the application
➥ dictionary.";

FUNCTION LIBRARY REFERENCE 159

D I C T _ U P D A T E R E P O R T S D I C T I O N A R Y ()

in [STATUS_REPORT_DICT_MISSING]
error "Could not open the reports dictionary.";
in [STATUS_ERROR_OPENING_LOG]
error "Could not open the log file.";
in [STATUS_ERROR_OPENING_INPUT]
error "Could not open the input file.";
in [STATUS_INPUT_FILE_ERROR]
error "An error was found in the input file.";
in [STATUS_ERROR]
error "An unknown error occurred during the update process.";
end case;

Related items Additional information

Chapter 60, “Updating an Application,” in Volume 1 of the Dexterity Programmer’s
Guide
Chapter 49, “Updating an Application,” in the Integration Guide

160 F U N C T I O N L I B R A R Y R E F E R E N C E
 Exception function library
Refer to Chapter 26, Use the functions in this library when implementing exception handling in
“Structured Exception your application. The functions in this library are used to retrieve
Handler,” in Volume 2 information about an exception that was thrown. This library contains the
of the Dexterity following functions:
Programmer’s Guide
for more information • Exception_Class()
about exception • Exception_ClassName()
handling. • Exception_Message()
• Exception_Product()
• Exception_ProductName()
• Exception_SubClass()
• Exception_SubClassName()

FUNCTION LIBRARY REFERENCE 161

E X C E P T I O N _ C L A S S ( )

Exception_Class()
Description The Exception_Class() function returns the class of the current exception.

Syntax Exception_Class()

Parameters • None

Return value A long integer containing the class of the current exception.

Comments The Exception_Class() function must be used in the catch or else block of
the try...end try statement.

Examples This procedure contains sanScript code to handle the exception that can
occur when you reference an invalid form by name. If an invalid name is
supplied to the open form with name statement, a system exception is
thrown. If any other exception is thrown, the Exception_Product(),
Exception_Class(), Exception_SubClass(), and Exception_Message()
functions are used to retrieve information about the exception. If the
exception was thrown by another product, the exception is rethrown.
Otherwise, information about the exception is displayed.

in string form_name;

try
{Open the named form.}
open form with name form_name;
catch [EXCEPTION_CLASS_FORM_MISSING]
{Catch the exception if the form is missing.}
error "Cannot find the form " + form_name + ". Error in script "+
➥ _script_ + ".";
else
{Some other exception occurred.}
if Exception_Product() = 3333 then
{It's our exception. Display information.}
error "An unknown exception occurred. Class: " +
➥ str(Exception_Class()) + " Subclass: " +
➥ str(Exception_SubClass()) + " Message:" +
➥ Exception_Message();
else
{It's not our exception. Rethrow it.}
throw;
end if;
end try;

162 F U N C T I O N L I B R A R Y R E F E R E N C E
 E X C E P T I O N _ C L A S S N A M E ()

Exception_ClassName()
Description The Exception_ClassName() function returns a string containing the
constant for the class of the current system exception.

Syntax Exception_ClassName({class})

Parameters • class – An optional long integer containing the value of a system exception
class. If this parameter is supplied, the constant for the specified system
exception class will be returned.

Return value A string containing an exception class constant.

Comments Use the class parameter with this function when you know the long integer
class value of a system exception, but want a string containing the constant
for the exception class.

If you include the class parameter, you can use this function anywhere in
your code. If you don’t include the class parameter, you can use this
function only in a catch or else block of a try...end try statement.

Examples Several system exceptions have been logged and saved in a table.
The contents of this table are displayed in a scrolling window.
The following is the fill script for the scrolling window. As records
are read from the Exception_Log table, the Exception_ClassName(),
Exception_SubClassName() and Exception_ProductName() functions
convert the exception class, subclass and product values into strings that
are displayed in the scrolling window.

{Look up the exception class.}

'Exception Class' of window Exception_Scroll =
➥ Exception_ClassName(Class of table Exception_Log);

{Look up the exception subclass.}

'Exception SubClass' of window Exception_Scroll =
➥ Exception_SubClassName(Class of table Exception_Log,
➥ SubClass of table Exception_Log);

{Look up the product.}

'Product' of window Exception_Scroll =
➥ Exception_ProductName(Product of table Exception_Log);

FUNCTION LIBRARY REFERENCE 163

E X C E P T I O N _ M E S S A G E ( )

Exception_Message()
Description The Exception_Message() function returns a string describing the current
exception.

Syntax Exception_Message()

Parameters • None

Return value A text value containing a message describing the current exception.

Comments The Exception_Message() function must be used in the catch or else block
of the try...end try statement.

Examples See the example for Exception_Class().

164 F U N C T I O N L I B R A R Y R E F E R E N C E
 E X C E P T I O N _ P R O D U C T ()

Exception_Product()
Description The Exception_Product() function returns the ID of the product that threw
the current exception.

Syntax Exception_Product()

Parameters • None

Return value An integer containing the ID of the product that threw the current
exception.

Comments The Exception_Product() function must be used in the catch or else block of
the try...end try statement.

Examples See the example for Exception_Class().

FUNCTION LIBRARY REFERENCE 165

E X C E P T I O N _ P R O D U C T N A M E ()

Exception_ProductName()
Description The Exception_ProductName() function returns a string containing the
name of the product that threw the current exception.

Syntax Exception_ProductName({product_ID})

Parameters • product_ID – An optional integer containing the ID of a product.

Return value A string containing the name of a product.

Comments Use the product_ID parameter with this function when you know the
product ID, but need a string containing the name of the product.

If you include the product_ID parameter, you can use this function
anywhere in your code. If you don’t include the product_ID parameter, you
can use this function only in a catch or else block of a try...end try
statement.

Examples See the example for Exception_ClassName().

166 F U N C T I O N L I B R A R Y R E F E R E N C E
 E X C E P T I O N _ S U B C L A S S ()

Exception_SubClass()
Description The Exception_SubClass() function returns the subclass of the current
exception.

Syntax Exception_SubClass()

Parameters • None

Return value A long integer containing the subclass of the current exception.

Comments The Exception_SubClass() function must be used in the catch or else block
of the try...end try statement.

Examples See the example for Exception_Class().

FUNCTION LIBRARY REFERENCE 167

E X C E P T I O N _ S U B C L A S S N A M E ( )

Exception_SubClassName()
Description The Exception_SubClassName() function returns a string containing the
constant for the subclass of the current system exception.

Syntax Exception_SubClassName({class, subclass})

Parameters • class – An optional long integer containing the value of a system exception
class.

• subclass – An optional long integer containing the value of a system

exception subclass. If both the class and subclass parameters are supplied,
the constant for the specified system exception subclass will be returned.

Return value A string containing an exception subclass constant.

Comments Use the class and subclass parameters with this function when you know the
long integer values of a system exception class and subclass, but need a
string containing the constant for the system exception subclass.

If you include the class and subclass parameters, you can use this function
anywhere in your code. If you don’t include the class and subclass
parameters, you can use this function only in a catch or else block of a
try...end try statement.

Examples See the example for Exception_ClassName().

168 F U N C T I O N L I B R A R Y R E F E R E N C E
Field function library
Use the functions in this library to work with fields. This library contains
the following functions:

• Field_BDLAddToSubmenu()
• Field_BDLCreateLinkedCommandList()
• Field_BDLCreateSubmenu()
• Field_BDLGetLinkedItemCommandTag()
• Field_CreateLinkedCommand()
• Field_GetBooleanProperty()
• Field_GetCaption()
• Field_GetColor()
• Field_GetFont()
• Field_GetImage()
• Field_GetInsertPosFromVisualPos()
• Field_GetIntegerProperty()
• Field_GetLinkedCommandTag()
• Field_GetPosition()
• Field_GetRequiredStatus()
• Field_GetSelection()
• Field_GetSize()
• Field_GetStringProperty()
• Field_GetToolTip()
• Field_GetVisualPosFromInsertPos()
• Field_InsertStringInText()
• Field_MarkListItems()
• Field_ParseText()
• Field_SetAltLineColor()
• Field_SetBackColor()
• Field_SetBooleanProperty()
• Field_SetCaption()
• Field_SetCustomPromptFormat()
• Field_SetFont()
• Field_SetFontColor()
• Field_SetFontSize()
• Field_SetFontStyle()
• Field_SetImage()
• Field_SetIntegerProperty()
• Field_SetPattern()
• Field_SetPatternColor()
• Field_SetRequiredFormat()
• Field_SetRequiredStatus()

FUNCTION LIBRARY REFERENCE 169

 • Field_SetSelection()
• Field_SetStringProperty()
• Field_SetToolTip()
• Field_SetZoomFormat()

170 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ B D L A D D T O S U B M E N U ()

Field_BDLAddToSubmenu()
Description The Field_BDLAddToSubmenu() function adds an item to a submenu of a
button drop list control.

Syntax Field_BDLAddToSubmenu(field, parent_ID, string_expression {, value})

Parameters • field – A button drop list field.

• parent_ID – The ID of the submenu to which the new item is being added.
Use the constant BDL_ROOT if the item is being added at the first level of
the button drop list.

• string_expression – A string containing the text for the submenu item.

• value – An optional long integer value that will be associated with new
item. If this parameter isn’t used, 0 will be associated with the new item.

Return value A boolean indicating the result; true indicates the item was successfully
added, while false indicates it was not.

Comments Each new item will be added to the end of the specified button drop list or
submenu. The numeric position assigned to the new item is based on the
order items were added to the button drop list.

Examples Refer to the example for Field_BDLCreateSubmenu().

FUNCTION LIBRARY REFERENCE 171

F I E L D _ B D L C R E A T E L I N K E D C O M M A N D L I S T ( )

Field_BDLCreateLinkedCommandList()
Description The Field_BDLCreateLinkedCommandList() function creates a command
list based on the button drop list window field specified. This function is
used only in the InitializeRibbon procedure for a form.

Syntax Field_BDLCreateLinkedCommandList(field, command_name {, hide_field})

Parameters • field – The button drop list field for which the command list is being created.

• command_name – A string value that supplies a name for the command list
that is being created. Typically, a string with the fully-qualified name of the
button drop list is used.

• hide_field – An optional boolean that indicates whether the button drop list
field will be hidden on the window when the command list is created. If
you do not supply this parameter, the button drop list will always be
hidden when this function is used for the web client.

Return value An integer containing the command tag for the command list that is
created.

Comments When the command list is created, the following occurs:

• A link is established between the button drop list and the command list.
This link is valid as long as the form remains open.

• Each item in the command list inherits the properties of the

corresponding button drop list item, such as enabled/disable, or
checked/unchecked.

After the command list for the button drop list has been created, the content
of the button drop list should be considered static. Do not add or remove
items from the corresponding button drop list.

The command list that is created will not have its display name set. If you
want to display the command list in the ribbon, you should use the
Command_GetStringProperty() function to set the display name for the
command list.

Examples Refer to the example for Field_CreateLinkedCommand().

172 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ B D L C R E A T E S U B M E N U ()

Field_BDLCreateSubmenu()
Description The Field_BDLCreateSubmenu() function adds a submenu to a button
drop list control.

Syntax Field_BDLCreateSubmenu(field, parent_ID, string_expression {, value})

Parameters • field – A button drop list field.

• parent_ID – The ID of the submenu to which the new submenu is being

added. Use the value 0 if the submenu is being added at the first level of the
button drop list.

• string_expression – A string containing the text for the submenu item.

• value – An optional long integer value that will be associated with submenu
item. If this parameter isn’t used, 0 will be associated with the submenu
item.

Return value An integer containing the ID of the new submenu.

Comments Each new submenu will be added to the end of the specified button drop
list or submenu.

Examples The following example creates the items for the Reports button drop list.
Notice that there are data items associated with each item added to the
button drop list. These data items will be used to find out the item chosen
when the user makes a selection.

local integer submenu_ID;

local boolean result;

submenu_ID = Field_BDLCreateSubmenu('Reports Button',BDL_ROOT,

➥ "Daily");
result = Field_BDLAddToSubmenu('Reports Button',submenu_ID,
➥ "Sales", 1);
result = Field_BDLAddToSubmenu('Reports Button', submenu_ID,
➥ "Inventory", 2);
submenu_ID = Field_BDLCreateSubmenu('Reports Button',BDL_ROOT,
➥ "Monthly");
result = Field_BDLAddToSubmenu('Reports Button',submenu_ID,"Sales");
result = Field_BDLAddToSubmenu('Reports Button',submenu_ID,
➥ "Inventory", 4);

FUNCTION LIBRARY REFERENCE 173

F I E L D _ B D L C R E A T E S U B M E N U ()

The following illustration shows the button drop list created.

The following is the change script for the button drop list. It shows how the
data item can be retrieved from the item selected in the button drop list. The
data item can then be used to perform the appropriate action in the
application.

local integer selection;

selection = itemdata('Reports Button', 'Reports Button');

174 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ B D LG E T L I N K E D I T E M C O M M A N D T A G ()

Field_BDLGetLinkedItemCommandTag()
Description The Field_BDLGetLinkedItemCommandTag() function retrieves the
command tag for a button drop list item that is part of the command list
that was created for the button drop list by the
Field_BDLCreateLinkedCommandList() function.

Syntax Field_BDLGetLinkedItemCommandTag(window_field, position)

Parameters • window_field – The button drop list field.

• position – An integer indicating the numeric position of the item in the

button drop list. The first position in the list had the value 1.

Return value An integer containing the command tag for the button drop list item.

Examples Refer to the example for Field_GetLinkedCommandTag().

FUNCTION LIBRARY REFERENCE 175

F I E L D _ C R E A T E L I N K E D C O M M A N D ( )

Field_CreateLinkedCommand()
Description
The Field_CreateLinkedCommand() function creates a command based on
the window field specified. Typically, this will be a push button field on the
window. This function is used only in the InitializeRibbon procedure for a
form.

Syntax Field_CreateRibbonCommand(field, command_name {, hide_field})

Parameters • field – The field for which the command is being created.

• command_name – A string value that supplies a name for the command that
is being created. Typically, a string with the fully-qualified name of the field
is used.

• hide_field – An optional boolean that indicates whether the field will be

hidden on the window when the command is created. If you do not supply
this parameter, the field will always be hidden when this function is used
for the web client.

Return value An integer containing the command tag for the command that is created.

Comments When the command is created, the following occurs:

• A link is established between the field and the command. This link is
valid as long as the form remains open.

• The command inherits the properties of the field, such as enabled/

disable, or hidden/shown.

The command that is created will not have its display name set. If you want
to display the command in the ribbon, you should use the
Command_GetStringProperty() function to set the display name for the
command.

Examples The following example is the InitializeRibbon procedure for an About Box
form. This procedure creates a custom ribbon that is shown when the form
is displayed in the Microsoft Dynamics GP web client. The procedure uses
the Field_CreateLinkedCommand() function to create a command based
on the Close box that is in the window. The command is used in the ribbon.

176 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ C R E A T E L I N K E D C O M M A N D ()

in integer productId;
in integer formId;
in integer windowId;
in integer windowType;
inout integer ribbonTag;

local integer tag;

local integer action_group_tag;
local integer image_id;

{Create the command list for the custom ribbon}

ribbonTag = CommandList_CreateList(productId, formId,
➥ "AboutWindowRibbon");

{Create a command list for the Actions group}

action_group_tag = CommandList_CreateList(productId, formId,
➥ "ActionGroup");

{Set properties for the Actions group}

Command_SetStringProperty(action_group_tag,
➥ COMMAND_PROP_DISPLAY_NAME, "Actions");

{Create a command based on the Close button}

tag = Field_CreateLinkedCommand('(L) Close' of window About,
➥ "CloseOfWindowAbout");

{Set the properties for the Close button}

image_id = Resource_GetID(0, DT_EXTERNAL_ICON, "Close");
Command_SetImageProperty(tag, COMMAND_PROP_NORMAL_IMAGE, DYNAMICS,
➥ DT_EXTERNAL_ICON, image_id);

{Add the Close button to the Actions group}

CommandList_Add(action_group_tag, tag);

{Add the Actions group to the ribbon}

CommandList_Add(ribbonTag, action_group_tag);

FUNCTION LIBRARY REFERENCE 177

F I E L D _ G E T B O O L E A N P R O P E R T Y ( )

Field_GetBooleanProperty()
Description The Field_GetBooleanProperty() function retrieves a specified boolean
property for a field.

Syntax Field_GetBooleanProperty(field_name, property)

Parameters • field_name – The name of a window field.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant
FIELD_PROP_AUTOCOMPLETE
FIELD_PROP_BDL_DROP_INDICATOR
FIELD_PROP_CANCEL
FIELD_PROP_DEFAULT
FIELD_PROP_DISABLED
FIELD_PROP_EDITABLE
FIELD_PROP_FOCUS
FIELD_PROP_HYPERSPACE
FIELD_PROP_LOCKED
FIELD_PROP_REQUIRED
FIELD_PROP_SURROUNDING_BOX
FIELD_PROP_TAB_STOP
FIELD_PROP_VISIBLE
FIELD_PROP_ZOOM
Description
True if the string field has AutoComplete
enabled. False if it does not.
True if the drop indicator for a button drop list
is displayed. False if it is not.
True if the field is the Default Cancel for the
window. False if it is not.
True if the field is the Default OK field for the
window. False if it is not.
True if the field is disabled. False if it is not.
True if the field is editable. False otherwise.
True if the field currently contains the focus.
False if it does not. This property is
independent of whether the window is active
or inactive.
True if the field is marked as Hyperspace. False
if it is not.
True if the field is locked. False if it is not.
True if the field is required. False if it is not.
True if the field is drawn with a border. False if
it is not.
True if the field is in the tab sequence. False if it
is not.
True if the field is visiable. False if it is not.
True if the field is set to show the zoom pointer.
False if it is not.

Return value A boolean indicating how the property is set.

178 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T B O O L E A N P R O P E R T Y ()

Comments Use the Field_GetBooleanProperty() and Field_SetBooleanProperty()

functions to dynamically control which fields in a window are the Default
OK and Default Cancel.

Be aware that the required() function will not consider disabled fields
required, even though they have the Required property set to true.
However, the value retrieved from the FIELD_PROP_REQUIRED property
will be true, even if the field is disabled.

Examples The following example uses the Field_GetBooleanProperty() function to

find out whether the OK button is the Default OK button for the window.

local boolean result;

result = Field_GetBooleanProperty('OK', FIELD_PROP_DEFAULT);

Related items Commands

Field_SetBooleanProperty()

FUNCTION LIBRARY REFERENCE 179

F I E L D _ G E T C A P T I O N ()

Field_GetCaption()
Description The Field_GetCaption() function retrieves the text caption for the specified
field, such as a push button or button drop list. If the field doesn’t have a
caption, the prompt linked to the field is returned.

Syntax Field_GetCaption(field_name)

Parameters • field_name – The name of a window field.

Return value A string containing the caption for the field.

Examples The following example retrieves the caption used for the Save button.

local string caption;

caption = Field_GetCaption('Save Button');

Related items Commands

Field_SetCaption()

180 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T C O L O R ()

Field_GetColor()
Description The Field_GetColor() function retrieves color information for a field.

Syntax Field_GetColor(field, font_color, back_color, pattern_color, pattern)

Parameters • field – The field for which color information will be retrieved.

• font_color – A return long integer containing the font color. The value
corresponds to one of the following constants:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

• back_color – A returned long integer containing the back color. The value
corresponds to one of the constants listed for font_color.

• pattern_color – A returned long integer containing the pattern color. The

value corresponds to one of the constants listed for font_color.

• pattern – A returned integer containing the pattern. The value corresponds

to one of the following constants:

Constant Pattern Constant Pattern

PATTERN_NONE PATTERN_VERTICAL

PATTERN_25_SHADING PATTERN_UP_DIAGONAL

PATTERN_50_SHADING PATTERN_DOWN_DIAGONAL

PATTERN_75_SHADING PATTERN_GRID

PATTERN_HORIZONTAL PATTERN_TRELLIS

FUNCTION LIBRARY REFERENCE 181

F I E L D _ G E T C O L O R ()

Return value A boolean. True indicates color information was retrieved, while false
indicates it was not.

Examples The following example retrieves the color and pattern information from the
Buyer ID field.

local boolean result;

local long font_color;
local long back_color;
local long pattern_color;
local integer pattern;

result = Field_GetColor('Buyer ID', font_color, back_color,

➥ pattern_color, pattern);

Related items Additional information

Color function library

182 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T F O N T ()

Field_GetFont()
Description The Field_GetFont() function retrieves the font characteristics for a field.

Syntax Field_GetFont(text_field, font, size, style)

Parameters • text_field – The field for which the font characteristics will be retrieved.

• font – A returned integer corresponding to one of the following constants:

Constant Description
FONT_COURIER Courier
FONT_HELVETICA Helvetica
FONT_TIMES Times
FONT_SYSTEM The default system font

• size – A returned integer specifying the size of the font in points.

• style – A returned integer corresponding to one of the following constants:

Constant Description
FONT_STYLE_PLAIN Plain
FONT_STYLE_BOLD Bold
FONT_STYLE_ITALIC Italic
FONT_STYLE_UNDERLINE Underline

If several styles are applied to the field, the sum of the appropriate
constants will be returned. For example, if the bold and underline
styles are applied, a value corresponding to FONT_STYLE_BOLD +
FONT_STYLE_UNDERLINE will be returned.

Return value A boolean. True indicates the font characteristics were retrieved, while false
indicates they were not.

Examples The following example retrieves the font used for the Buyer ID field.

local boolean result;

local long font;

result = Field_GetFont('Buyer ID', font);

FUNCTION LIBRARY REFERENCE 183

F I E L D _ G E T I M A G E ( )

Field_GetImage()
Description The Field_GetImage() function retrieves the item numbers of the images
associated with a push button or button drop list field.

Syntax Field_GetImage(field, image_type)

Parameters • field – The push button or button drop list for which an image number will
be retrieved.

• image_type – An integer specifying which image type to retrieve. Use one of

the following constants:

Constant Description
IMAGE_UP The button up image
IMAGE_DOWN The button down image
IMAGE_OVER The mouse-over image

Return value A integer indicating the image. This value corresponds to the item number
of the image listed in the Button Items window.

Examples The following example retrieves the item number for the button up image
of the Reports button drop list.

local integer image_item;

image_item = Field_GetImage('Reports', IMAGE_UP);

184 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T I N S E R T P O S F R O M V I S U A L P O S ()

Field_GetInsertPosFromVisualPos()
Description The Field_GetInsertPosFromVisualPos() function retrieves the insertion
position of an item in a list field (list box, drop-down list, button drop list,
or visual switch) based on its visual position.

Syntax Field_GetInsertPosFromVisualPos(list_field, visual_pos)

• list_field – The list field for which information is being retrieved.

• visual_pos – An integer specifying the visual position of the item for which
the insertion position is being returned. The value 1 indicates the first item
at the top of the list.

Return value An integer containing the insertion position of the item.

Comments When static items are added to list fields, either in the data type definition
or with sanScript, they are added in insertion order. The value of the list
field is based on the insertion position of the item selected. If the list is
sorted, the visual order of the items may be different than the insertion
order. If you know the visual position of an item, use this function to
retrieve the item’s insertion position.

If you are using the add item statement to add items to a list field, be sure to use
the redraw statement to resort the items before using the
Field_GetInsertPosFromVisualPos() function.

Examples The following example retrieves the insertion position of the first item
listed in the House Type drop-down list.

local integer insert_pos;

insert_pos = Field_GetInsertPosFromVisualPos('House Type', 1);

Related items Commands

Field_GetVisualPosFromInsertPos()

FUNCTION LIBRARY REFERENCE 185

F I E L D _ G E T I N T E G E R P R O P E R T Y ( )

Field_GetIntegerProperty()
Description The Field_GetIntegerProperty() function retrieves a specified integer
property for a field.

Syntax Field_GetIntegerProperty(field_name, property)

Parameters • field_name – The name of a window field.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant Description/Return values

FIELD_PROP_BDL_DROP_POS_X
FIELD_PROP_BDL_DROP_POS_Y
FIELD_PROP_BUTTON_STYLE
Specifies the distance in pixels the drop indicator
will be drawn from the right edge of the control.
Specifies the distance in pixels the drop indicator
will be drawn from the bottom edge of the control.
Indicates the style used for the push button. The
value returned by the function corresponds to one
of the following constants:
BUTTON_STYLE_TEXT_ONLY
BUTTON_STYLE_TEXT_ON_LEFT
BUTTON_STYLE_TEXT_ON_RIGHT
BUTTON_STYLE_TEXT_ON_TOP
BUTTON_STYLE_TEXT_ON_BOTTOM
BUTTON_STYLE_GRAPHIC_ONLY

Return value An integer specifying how the field was set. Refer to the preceding table for
a list of integer properties and their corresponding values.

Examples The following example uses the Field_GetIntegerProperty() function to

find out the style used for the Buyers button.

local integer result;

result = Field_GetIntegerProperty('Buyers', FIELD_PROP_BUTTON_STYLE);

Related items Commands

Field_SetIntegerProperty()

186 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T L I N K E D C O M M A N D T A G ()

Field_GetLinkedCommandTag()
Description The Field_GetLinkedCommandTag() function returns the command tag
for the command that was created for the field by the
Field_CreateLinkedCommand() function.

Syntax Field_GetLinkedCommandTag(field)

Parameters • field – The field for which the command tag of the linked command is being
returned.

Return value An integer containing the command tag. If the field does not have a linked
command, the value 0 is returned.

Examples The following example retrieves the command tag for the command that
was created based on the Note Absent Button that appears in the Customer
Maintenance window. The display name for the command is changed.

local integer note_item_tag;

{Find the Note command in the ribbon}

note_item_tag = Field_GetLinkedCommandTag('Note Absent Button -
➥ Toolbar ' of window RM_Customer_Maintenance of form
➥ RM_Customer_Maintenance);

{Set the property}

Command_SetStringProperty(note_item_tag, COMMAND_PROP_DISPLAY_NAME,
➥ "Note");

FUNCTION LIBRARY REFERENCE 187

F I E L D _ G E T P O S I T I O N ( )

Field_GetPosition()
Description The Field_GetPosition() function returns the current coordinates of the
named field’s top left corner.

Syntax Field_GetPosition(field_name, h_position, v_position)

Parameters • field_name – The name of the field for which you want to retrieve a position.

• h_position – An integer field or variable to which the specified field’s

horizontal coordinate is returned.

• v_position – An integer field or variable to which the specified field’s

vertical coordinate is returned.

Return value A boolean. True indicates the field position was returned, while false
indicates it was not.

Comments The coordinates are expressed in pixels. The coordinates 0,0 specify the
upper left corner of the window.

Examples The following example returns the coordinates of the Seller ID field.

local integer x, y;
local boolean result;

result = Field_GetPosition('Seller ID', x, y);

Related items Commands

Field_GetSize(), move field

188 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T R E Q U I R E D S T A T U S ()

Field_GetRequiredStatus()
Description The Field_GetRequiredStatus() function ascertains the current status of the
Show Required Fields menu item. If the item is checked, required fields are
being displayed.

Syntax Field_GetRequiredStatus()

Parameters • None

Return value Boolean

Comments The boolean value denotes the status of the Show Required Fields menu
item. When the Show Required Fields menu item is checked, the prompts
linked to required fields in a window will be displayed as defined by the
Field_SetRequiredFormat() function.

This function can be used in the Main Menu post script to ascertain whether
the Show Required Fields menu item was checked, so that the information
can be saved in a user preferences table.

Examples The following example can be part of a Main Menu post script. It uses the
Field_GetRequiredStatus() function to ascertain the current status of the
Show Required Fields menu item, then saves the returned value to the
User_Preferences table.

local boolean show_required;

show_required = Field_GetRequiredStatus();
UserID of table User_Preferences = UserID of globals;
change table User_Preferences;
'Show Required' of table User_Preferences = show_required;
save table User_Preferences;

FUNCTION LIBRARY REFERENCE 189

F I E L D _ G E T S E L E C T I O N ( )

Field_GetSelection()
Description The Field_GetSelection() function retrieves the text currently selected in a
text field.

Syntax Field_GetSelection(text_field, {start_position, length})

Parameters • text_field – The text field from which you are retrieving the selection.

• start_position – A returned integer containing the starting position of the

selection.

• length – A returned integer containing the length of the selection. If no text

is selected, 0 is returned.

Return value A string containing the selected text. Up to 255 characters can be returned.

Comments If more than 255 characters are selected, only the first 255 characters are
returned. You can use the substring() function to retrieve the additional
characters.

Examples The following example retrieves the current selection in the Description text
field. If no text is selected, an error is displayed.

local string selected_text;

local integer start_position, selection_length;

selected_text = Field_GetSelection(Description, start_position,

➥ selection_length);
if selection_length = 0 then
error "No text was selected.";
end if;

190 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T S I Z E ()

Field_GetSize()
Description The Field_GetSize() function retrieves the horizontal and vertical size of a
window field.

Syntax Field_GetSize(field, horizontal, vertical)

Parameters • field – A window field.

• horizontal – A returned integer containing the horizontal size of the field,

measured in pixels.

• vertical – A returned integer containing the vertical size of the field,

measured in pixels.

Return value A boolean. True indicates the field size was returned, while false indicates it
was not.

Examples The following example retrieves the size of the Buyers button.

local boolean result;

local integer x,y;

result = Field_GetSize('Buyers Button', x, y);

Related items Commands

Field_GetPosition(), resize field

FUNCTION LIBRARY REFERENCE 191

F I E L D _ G E T S T R I N G P R O P E R T Y ( )

Field_GetStringProperty()
Description The Field_GetStringProperty() function retrieves a specified string
property for a field.

Syntax Field_GetStringProperty(field_name, property)

Parameters • field_name – The name of a window field.

• property – An integer constant indicating the property to retrieve. The value

corresponds to one of the following constants:

Constant Description
FIELD_PROP_AUTOCOMPLETE_ For auto-complete fields that have a linked-lookup
LOOKUP_ITEM button, specifies the text to display for the auto-
complete item that opens the lookup.
FIELD_PROP_CAPTION The caption to use for the field.

Return value A string containing the property value.

Examples The following example uses the Field_GetStringProperty() function to

retrieve the caption used for the Buyers button.

local string caption;

caption = Field_GetStringProperty('Buyers', FIELD_PROP_CAPTION);

Related items Commands

Field_SetStringProperty()

192 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ G E T V I S U A L P O S F R O M I N S E R T P O S ()

Field_GetVisualPosFromInsertPos()
Description The Field_GetVisualPosFromInsertPos() function retrieves the visual
position of an item in a list field (list box, drop-down list, button drop list,
or visual switch) based on its insertion position.

Syntax Field_GetVisualPosFromInsertPos(list_field, insert_pos)

• list_field – The list field for which information is being retrieved.

• insert_pos – An integer specifying the insertion position of the item for

which the visual position is being returned. The value 1 indicates the first
item that was added to the list.

Return value An integer containing the visual position of the item.

Comments When static items are added to list fields, either in the data type definition
or with sanScript, they are added in insertion order. The value of the list
field is based on the insertion position of the item selected. If the list is
sorted, the visual order of the items may be different than the insertion
order. If you know the insertion position of an item, use this function to
retrieve the item’s visual position.

If you are using the add item statement to add items to a list field, be sure to use
the redraw statement to resort the items before using the
Field_GetVisualPosFromInsertPos() function.

Examples The following example retrieves the visual position of the item that is
currently selected in the House Type drop-down list.

local integer visual_pos;

visual_pos = Field_GetVisualPosFromInsetPos('House Type',

➥ 'House Type');

Related items Commands

Field_GetInsertPosFromVisualPos()

FUNCTION LIBRARY REFERENCE 193

F I E L D _ G E T T O O L T I P ( )

Field_GetToolTip()
Description Returns the tooltip associated with a window field.

Syntax Field_GetToolTip(field_name)

Parameters • field_name – The name of a window field.

Return value A string containing the tooltip.

Examples The following example returns the tooltip associated with the Print button
of the RESM Explorer window.

local string tooltip;

tooltip = Field_GetToolTip('Print Button' of window RESM_Explorer

➥ of form RESM_Explorer);

194 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ I N S E R T S T R I N G I N T E X T ()

Field_InsertStringInText()
Description The Field_InsertStringInText() function inserts a string or string field into
a text field.

Syntax Field_InsertStringInText(text_field, string_expression)

Parameters • text_field – The text field into which you wish to add the string.

• string_expression – The static string or string field you want to insert into the
text field.

Return value The boolean value true.

Comments This function inserts the string_expression into the text_field at the current
position of the cursor in the text field. If characters are highlighted in the
text field, they will be deleted before the string is inserted. Once the string is
added to the text field, the field is redrawn to include the newly-added
information.

Examples In the following example, the contents of a Customer_Quote field are added
to the Contact Comments field:

local boolean l_boolean;

l_boolean = Field_InsertStringInText('Contact Comments',

➥ Customer_Quote);

Related items Commands

Field_ParseText()

FUNCTION LIBRARY REFERENCE 195

F I E L D _ M A R K L I S T I T E M S ( )

Field_MarkListItems()
Description The Field_MarkListItems() function marks or unmarks the selected item in
a non-native list box. An asterisk appears to the left of a marked item.

Syntax Field_MarkListItems(list_field)

Parameters • list_field – The non-native list box field containing the item to mark.

Return value The boolean value true.

Comments Each item must be added to the list using the add item statement and
should be preceded by a leading blank to allow appropriate space for the
asterisk. The list should not contain static text values.

The following illustration shows how the non-native list box will appear
when items in it are marked using this function:

Marked

In this illustration, the asterisk appears in place of the leading blank.

Without the leading blank, the “i” in “item” would be replaced by the
asterisk.

Use a nonproportional font, such as Courier, for items in a list box. Then items in
the list will appear in alignment when displayed with or without an asterisk.

Examples The following example is a change script for a button that marks and
unmarks items in the “Item List” non-native list box. The list is initially
filled using the add item statement in the window pre script; each item is
added so that a leading blank appears in front of the item name. When an
item is selected in the list and the button is clicked, an asterisk will appear
next to the item.
local boolean l_boolean;

l_boolean = Field_MarkListItems('(L) Item List');

redraw '(L) Item List';
focus '(L) Item List';

196 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ P A R S E T E X T ()

Field_ParseText()
Description The Field_ParseText() function breaks up, or parses, a text field into strings.

Syntax Field_ParseText(text_field, number_of_chars, start_position)

Parameters • text_field – The text field you want to parse. The text_field can be a window
field, table field or text local variable.

• number_of_chars – An integer indicating the maximum number of characters

to be returned. This has an absolute maximum of 255 characters.

• start_position – An integer variable indicating the position in text_field from

which to begin parsing. The beginning of the field is position 1. As text_field
is parsed, the start_position variable is incremented by number_of_chars
automatically. When the end of the text field is reached, the start_position
variable is set to zero.

Return value String

Comments This function returns characters to a string field until the specified
number_of_chars for the string is reached, or until a carriage return is
encountered.

This function can be used in a loop (see the following example) to retrieve
consecutive sections of a text field, and return the retrieved strings to an
array field. If a carriage return is encountered, no more characters will be
returned to the current string. The characters returned to the string in the
next loop will begin immediately following the carriage return.

The defined number_of_chars may not be returned each time this function is
used, since the string values returned will never stop in the middle of a word.

Returned strings always break at spaces. For example, if you split the
following line into 30-character strings, the string returned would break
before the word “this” instead of breaking after the “h” in “this.” Therefore,
only 28 characters will be returned.

28 characters

Please enter an account for this customer.

30 characters

FUNCTION LIBRARY REFERENCE 197

F I E L D _ P A R S E T E X T ( )

Examples In the following example, a text field (Comments) is parsed into an array of
10 30-character strings.

local integer ind, start_position, old_start_position;

local string return_string[10];

start_position = 1;

for ind = 1 to 10 do
old_start_position = start_position;
return_string[ind] = Field_ParseText(Comments, 30,
➥ start_position);
{Set each array element to the corresponding returned string.}
'(L) Text_Array'[ind] = return_string[ind];
if old_start_position = start_position then
{The text field has been read.}
exit for;
end if;
end for;

Related items Commands

Field_InsertStringInText()

198 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T A L T L I N E C O L O R ()

Field_SetAltLineColor()
Description The Field_SetAltLineColor() function specifies colors for alternate lines in
scrolling windows whose AltLineColor property is true and whose
BackColor, FontColor, Pattern and PatternColor properties are Custom.

Syntax Field_SetAltLineColor(back_color, font_color, pattern_color, pattern)

Parameters • back_color – A long integer specifying the back color of the scrolling window
line. Use the following constants to set the back color:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

• font_color – A long integer specifying the font color of the scrolling window
line. Use the constants listed above to set the font color.

• pattern_color – A long integer specifying the pattern color of the scrolling

window line. Use the constants listed above to set the pattern color.

• pattern – An integer specifying the pattern of the scrolling window line. Use
the following constants to set the pattern:

Constant Pattern Constant Pattern

PATTERN_NONE PATTERN_VERTICAL

PATTERN_25_SHADING PATTERN_UP_DIAGONAL

PATTERN_50_SHADING PATTERN_DOWN_DIAGONAL

PATTERN_75_SHADING PATTERN_GRID

PATTERN_HORIZONTAL PATTERN_TRELLIS

FUNCTION LIBRARY REFERENCE 199

F I E L D _ S E T A L T L I N E C O L O R ()

Return value The boolean value true.

Comments The Field_SetAltLineColor() function automatically adds several entries to

the defaults file for your application. These entries store the characteristics
that were just specified, and begin with the word “Custom”. If these entries
exist in the defaults file, Dexterity or the runtime engine will automatically
apply them when your application is run.

You can use the User Interface Conversion Utility in Dexterity Utilities to
update your application to use custom colors for scrolling windows. Mark
the Use Custom Colors for Scrolling Windows option when you run the
utility. The utility will set the AltLineColor property to true, and the
BackColor, FontColor, Pattern and PatternColor properties to Custom for all
scrolling windows in your application.

If you don’t use the Field_SetAltLineColor() function, scrolling windows

whose AltLineColor property is true will appear with the following set of
default display characteristics:

Attribute Default display

Back color System
Font color System
Pattern None
Pattern color White

Examples The following example causes the alternate lines of scrolling windows to
appear light yellow.

local boolean l_result;

l_result = Field_SetAltLineColor(COLOR_LIGHT_YELLOW, COLOR_BLACK,

➥ COLOR_WHITE, PATTERN_50_SHADING);

Related items Additional information

Color function library

200 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T B A C K C O L O R ()

Field_SetBackColor()
Description The Field_SetBackColor() function sets the background color of a field.

Syntax Field_SetBackColor(field, color)

Parameters • field – The field for which the back color will be set.

• color – A long integer specifying the color to use. The value corresponds to
one of the following constants:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

Return value A boolean. True indicates the back color was set, while false indicates it was
not.

Examples The following example sets the background color used for the Buyer ID
field to white.

local boolean result;

result = Field_SetBackColor('Buyer ID', COLOR_WHITE);

Related items Additional information

Color function library

FUNCTION LIBRARY REFERENCE 201

F I E L D _ S E T B O O L E A N P R O P E R T Y ()

Field_SetBooleanProperty()
Description The Field_SetBooleanProperty() function sets a specified boolean property
for a field.

Syntax Field_SetBooleanProperty(field_name, property, value)

Parameters • field_name – The name of a window field.

• property – An integer constant indicating the property to set. The value

corresponds to one of the following constants:

Constant
FIELD_PROP_AUTOCOMPLETE
FIELD_PROP_BDL_DROP_INDICATOR
FIELD_PROP_CANCEL
FIELD_PROP_DEFAULT
FIELD_PROP_DISABLED
FIELD_PROP_EDITABLE
FIELD_PROP_FOCUS
FIELD_PROP_HYPERSPACE
FIELD_PROP_LOCKED
FIELD_PROP_REQUIRED
FIELD_PROP_SURROUNDING_BOX
FIELD_PROP_TAB_STOP
FIELD_PROP_VISIBLE
FIELD_PROP_ZOOM
Description
True if the string field has AutoComplete
enabled. False if it does not.
True if the drop indicator for a button drop list
is displayed. False if it is not.
True if the field is the Default Cancel for the
window. False if it is not.
True if the field is the Default OK field for the
window. False if it is not.
True if the field is disabled. False if it is not.
True if the field is locked or disable. False
otherwise.
True if the field currently contains the focus.
False if it does not. This property is
independent of whether the window is active
or inactive.
True if the field is marked as Hyperspace. False
if it is not.
True if the field is locked. False if it is not.
True if the field is required. False if it is not.
True if the field is drawn with a border. False if
it is not.
True if the field is in the tab sequence. False if
it is not.
True if the field is visiable. False if it is not.
True if the field is set to show the zoom
pointer. False if it is not.

• value – A boolean indicating how to set the property. Refer to the preceding
table.

202 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T B O O L E A N P R O P E R T Y ()

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Comments Use the Field_GetBooleanProperty() and Field_SetBooleanProperty()

functions to dynamically control which fields in a window are the Default
OK and Default Cancel.

Be aware that the required() function will not consider disabled fields
required, even though they have the FIELD_PROP_REQUIRED property
set to true.

Examples The following example uses the Field_SetBooleanProperty() function to

make the Insert button the Default OK button for the window.

local boolean result;

result = Field_SetBooleanProperty('Insert', FIELD_PROP_DEFAULT,

➥ true);

Related items Commands

Field_GetBooleanProperty()

FUNCTION LIBRARY REFERENCE 203

F I E L D _ S E T C A P T I O N ( )

Field_SetCaption()
Description The Field_SetCaption() function sets the text caption for the specified field,
such as a push button or button drop list.

Syntax Field_SetCaption(field_name, caption)

Parameters • field_name – The name of a window field.

• caption – A string containing the caption to use for the field.

Return value The boolean value true.

Examples The following example sets the caption of the Save button to Sa&ve. The
ampersand indicates an access key will be available for the push button.

local boolean result;

result = Field_SetCaption('Save Button', "Sa&ve");

Related items Commands

Field_GetCaption()

204 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T C U S T O M P R O M P T F O R M A T ()

Field_SetCustomPromptFormat()
Description The Field_SetCustomPromptFormat() function sets the display
characteristics for all text and field objects in an application whose
BackColor, FontColor, PatternColor and Pattern properties are Custom.

Syntax Field_SetCustomPromptFormat(back_color, font_color, pattern_color, pattern)

Parameters • back_color – A long integer speciying the back color of the object. Use the
following constants to set the back color:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

• font_color – A long integer specifying the font color of the object. Use the
constants listed above to set the font color.

• pattern_color – A long integer specifying the pattern color of the object. Use
the constants listed above. COLOR_SYSTEM is not valid for this parameter.

• pattern – An integer specifying the pattern of the object. Use the following
constants to set the pattern:

Constant Pattern Constant Pattern

PATTERN_NONE PATTERN_VERTICAL

PATTERN_25_SHADING PATTERN_UP_DIAGONAL

PATTERN_50_SHADING PATTERN_DOWN_DIAGONAL

PATTERN_75_SHADING PATTERN_GRID

PATTERN_HORIZONTAL PATTERN_TRELLIS

FUNCTION LIBRARY REFERENCE 205

F I E L D _ S E T C U S T O M P R O M P T F O R M A T ( )

Return value The boolean value true.

Comments The Field_SetCustomPromptFormat() function automatically adds several

entries to the defaults file for your application. These entries store the
characteristics that were just specified, and begin with the word “Custom”.
If these entries exist in the defaults file, Dexterity or the runtime engine will
automatically apply them when your application is run.

The User Interface Conversion Utility in Dexterity Utilities changes the

BackColor, FontColor, Pattern and PatternColor properties for an
application’s prompts (text objects that appear within a cyan rectangle
that’s 18 pixels high) to Custom. The utility leaves properties for all other
text objects unchanged.

If you don’t use the Field_SetCustomPromptFormat() function, objects that

use the Custom setting for BackColor, FontColor, Pattern and PatternColor
properties will appear with the following set of default display
characteristics:

Attribute Default display

Back color Turquoise (Cyan)
Font color Black
Pattern None
Pattern color Black

These defaults do not apply to static text items for controls such as push
buttons, check boxes and radio buttons. Your operating system color
settings control the display characteristics for those objects if you chose the
Use System Colors option in the User Interface Application Utility.

Examples The following example causes the custom prompts and fields to have a
dark green background color.

local boolean l_result;

l_result = Field_SetCustomPromptFormat(COLOR_TEAL, COLOR_BLACK,

➥ COLOR_GREEN, PATTERN_75_SHADING);

Related items Additional information

Color function library

206 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T F O N T ()

Field_SetFont()
Description The Field_SetFont() function sets the font characteristics for a field.

Syntax Field_SetFont(text_field, font, size, style)

Parameters • text_field – The field for which the font will be set.

• font – An integer corresponding to one of the following constants:

Constant Description
FONT_COURIER Courier
FONT_HELVETICA Helvetica
FONT_TIMES Times
FONT_SYSTEM The default system font

• size – An integer specifying the size of the font in points.

• style – An integer corresponding to one of the following constants:

Constant Description
FONT_STYLE_PLAIN Plain
FONT_STYLE_BOLD Bold
FONT_STYLE_ITALIC Italic
FONT_STYLE_UNDERLINE Underline

You can apply multiple styles to a field by adding the style

constants together. For example, to specify bold and underline, use
FONT_STYLE_BOLD + FONT_STYLE_UNDERLINE.

Return value A boolean. True indicates the font characteristics were set, while false
indicates they were not.

Examples The following example sets the font used for the Description field to 10
point Courier and applies the bold style.

local boolean result;

result = Field_SetFont('Description', FONT_COURIER, 12,

➥ FONT_STYLE_BOLD);

FUNCTION LIBRARY REFERENCE 207

F I E L D _ S E T F O N T C O L O R ( )

Field_SetFontColor()
Description The Field_SetFontColor() function sets the color of the font used for a field.

Syntax Field_SetFontColor(text_field, color)

Parameters • text_field – The field for which the font color will be set.

• color – A long integer specifying the color to use. The value corresponds to
one of the following constants:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

Return value A boolean. True indicates the font color was set, while false indicates it was
not.

Examples The following example sets the font color used for the Description field to
red.

local boolean result;

result = Field_SetFontColor('Description', COLOR_RED);

Related items Additional information

Color function library

208 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _S E T F O N T S I Z E ()

Field_SetFontSize()
Description The Field_SetFontSize() function sets the size of the font used for a field.

Syntax Field_SetFontSize(text_field, size)

Parameters • text_field – The field for which the font size will be set.

• size – An integer specifying the size of the font in points.

Return value A boolean. True indicates the font size was set, while false indicates it was
not.

Examples The following example sets the font size used for the Description field to 14
points.

local boolean result;

result = Field_SetFontSize('Description', 14);

FUNCTION LIBRARY REFERENCE 209

F I E L D _ S E T F O N T S T Y L E ()

Field_SetFontStyle()
Description The Field_SetFontStyle() function sets the style of the font used for a field.

Syntax Field_SetFontStyle(text_field, style)

Parameters • text_field – The field for which the font style will be set.

• style – An integer corresponding to one of the following constants:

Constant Description
FONT_STYLE_PLAIN Plain
FONT_STYLE_BOLD Bold
FONT_STYLE_ITALIC Italic
FONT_STYLE_UNDERLINE Underline

You can apply multiple styles to a field by adding the style

constants together. For example, to specify bold and underline, use
FONT_STYLE_BOLD + FONT_STYLE_UNDERLINE.

Return value A boolean. True indicates the font style was set, while false indicates it was
not.

Examples The following example sets the style used for the Description field to plain.

local boolean result;

result = Field_SetFontStyle('Description', FONT_STYLE_PLAIN);

210 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T I M A G E ()

Field_SetImage()
Description The Field_SetImage() function specifies the default image to use for a push
button or button drop list field.

Syntax Field_SetImage(field, image_type, index)

Parameters • field – The push button or button drop list whose image will be set.

• image_type – An integer specifying which image type to use. The value

corresponds to one of the following constants:

Constant Description
IMAGE_UP The button up image
IMAGE_DOWN The button down image
IMAGE_OVER The mouse-over image

• index – An integer specifying which image to use. This value corresponds to

the item number of the image listed in the Button Items window.

Return value A boolean indicating whether the image was changed. True indicates the
image was changed, while false indicates it was not.

Comments You must use the redraw statement to display the images specified.

Examples The following example sets the button up image for the Reports button
drop list to use the third image for the field.

local boolean result;

result = Field_SetImage('Reports', IMAGE_UP, 3);

redraw field 'Reports';

FUNCTION LIBRARY REFERENCE 211

F I E L D _ S E T I N T E G E R P R O P E R T Y ( )

Field_SetIntegerProperty()
Description The Field_SetIntegerProperty() function sets a specified integer property
for a field.

Syntax Field_SetIntegerProperty(field_name, property, value)

Parameters • field_name – The name of a window field.

• property – An integer constant indicating the property to set. The value

corresponds to one of the following constants:

Constant
FIELD_PROP_BDL_DROP_POS_X
FIELD_PROP_BDL_DROP_POS_Y
FIELD_PROP_BUTTON_STYLE
Description/Values
Specifies the distance in pixels the drop indicator
will be drawn from the right edge of the control.
Specifies the distance in pixels the drop indicator
will be drawn from the bottom edge of the control.
Indicates the style for the push button. The
possible values correspond to one of the following
constants:
BUTTON_STYLE_TEXT_ONLY
BUTTON_STYLE_TEXT_ON_LEFT
BUTTON_STYLE_TEXT_ON_RIGHT
BUTTON_STYLE_TEXT_ON_TOP
BUTTON_STYLE_TEXT_ON_BOTTOM
BUTTON_STYLE_GRAPHIC_ONLY

• value – An integer value indicating how to set the property. Refer to the
preceding table.

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Examples The following example uses the Field_SetIntegerProperty() function to set

the style of the Buyers button.

local integer result;

result = Field_SetIntegerProperty('Buyers', FIELD_PROP_BUTTON_STYLE,

➥ BUTTON_STYLE_TEXT_RIGHT);

Related items Commands

Field_GetIntegerProperty()

212 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T P A T T E R N ()

Field_SetPattern()
Description The Field_SetPattern() function sets the pattern used for a field.

Syntax Field_SetPattern(field, pattern)

Parameters • field – The field for which the pattern will be set.

• pattern – An integer specifying the pattern to use. The value corresponds to

one of the following constants:

Constant Pattern Constant Pattern

PATTERN_NONE PATTERN_VERTICAL

PATTERN_25_SHADING PATTERN_UP_DIAGONAL

PATTERN_50_SHADING PATTERN_DOWN_DIAGONAL

PATTERN_75_SHADING PATTERN_GRID

PATTERN_HORIZONTAL PATTERN_TRELLIS

Return value A boolean. True indicates the pattern was set, while false indicates it was
not.

Examples The following example sets the pattern used for the Buyer ID field to 50%
shading.

local boolean result;

result = Field_SetPattern('Buyer ID', PATTERN_50_SHADING);

FUNCTION LIBRARY REFERENCE 213

F I E L D _ S E T P A T T E R N C O L O R ( )

Field_SetPatternColor()
Description The Field_SetPatternColor() function sets the color of the pattern used for a
field.

Syntax Field_SetPatternColor(field, color)

Parameters • field – The field for which the pattern color will be set.

• color – A long integer specifying the color to use. The value corresponds to
one of the following constants:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

Return value A boolean. True indicates the pattern color was set, while false indicates it
was not.

Examples The following example sets the pattern color used for the Buyer ID field to
yellow.

local boolean result;

result = Field_SetPatternColor('Buyer ID', COLOR_YELLOW);

Related items Additional information

Color function library

214 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _S E T R E Q U I R E D F O R M A T ()

Field_SetRequiredFormat()
Description The Field_SetRequiredFormat() function sets the font style and color to use
for prompts linked to required fields when the Show Required Fields menu
item is selected.

Syntax Field_SetRequiredFormat(font_style, font_color)

Parameters • font_style – An integer that sets one of the following options:

Value Description
0 Plain text
1 Bold
2 Italic
3 Bold and italic

• font_color – An integer that sets one of the following options:

Value Description
0 Black
1 Red

Return value The boolean value true.

Comments For a prompt to appear with the characteristics defined using this function,
the prompt must be linked to a field in the Layout window, and the field’s
Required property in the Properties window must be set to true. When a
user chooses the Show Required Fields menu item, all prompts linked to
required fields will appear in the specified font style and color.

Use -1 as a parameter value if you do not want to change that format. For
example, use 1 as the font_style and -1 as the font_color to change the style to
bold and to leave the color unchanged.

FUNCTION LIBRARY REFERENCE 215

F I E L D _ S E T R E Q U I R E D F O R M A T ()

Examples The following example allows a user of your application to set the display
characteristics of prompts for required fields. Two check boxes (CB_Bold
and CB_Italic) are used to specify the font_style, and a radio group
(RG_Font_Color) containing two radio button fields (Black and Red) is used
to define the font_color.

local integer color_choice, style_choice;

local boolean l_boolean;

{Ascertain the desired prompt style for required fields.}

if CB_Bold=true and CB_Italic=true then
{Set the prompt to bold and italic.}
style_choice = 3;
elseif CB_Italic=true then
{Set the prompt to italic.}
style_choice = 2;
elseif CB_Bold=true then
{Set the prompt to bold.}
style_choice = 1;
else
{The prompt style is plain.}
style_choice = 0;
end if;

{Ascertain the desired the prompt color for required fields.}

if RG_Font_Color = 0 then
{Black was selected as the desired color.}
color_choice = 0;
else
{Red was selected.)
color_choice = 1;
end if;

{Finally, specify that the selected characteristics be used for

required fields.}
l_boolean = Field_SetRequiredFormat(style_choice, color_choice);

Related items Commands

Field_SetRequiredStatus()

216 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T R E Q U I R E D S T A T U S ()

Field_SetRequiredStatus()
Description The Field_SetRequiredStatus() function either checks or unchecks the
Show Required Fields menu item.

Syntax Field_SetRequiredStatus(mode)

Parameters • mode – A boolean that sets one of the following options:

Value Description
true Sets the Show Required Fields menu item to checked.
false Sets the Show Required Fields menu item to unchecked.

Return value Boolean. The value returned denotes the status of the Show Required Fields
menu item before if it was changed using this function.

Comments When the Show Required Fields menu item is checked, the prompts linked
to required fields in a window will be displayed as defined by the
Field_SetRequiredFormat() function.

This function can be used in your application’s Main Menu pre script to set
the Show Required Fields menu item to the status stored in a user
preferences table. Conversely, it can be used in the Main Menu post script to
ascertain whether the Show Required Fields menu item was checked, so
that the information could be saved in a user preferences table.

Examples The following example can be part of a Main Menu pre script. It retrieves a
record containing information about the current user’s desired settings
from the user_prefs table. It then uses the information in the show_req field
as the mode parameter for the Field_SetRequiredStatus() function.

local boolean l_boolean, req_pref;

{Read the current user's record from the user_prefs table.}

user_ID of table user_prefs = current_user of globals;
get table user_prefs by user_ID_key;
{Retrieve the user's preference for required fields, and check or
uncheck the Show Required Fields menu item as needed.}
req_pref = show_req of table user_prefs;
l_boolean = Field_SetRequiredStatus(req_pref);

FUNCTION LIBRARY REFERENCE 217

F I E L D _ S E T R E Q U I R E D S T A T U S ( )

The following example can be part of a Main Menu post script. It ascertains
whether the current user checked the Show Required Fields menu item
using the Field_SetRequiredStatus() function, and reads the returned
value. If false is returned, the menu command wasn’t checked; if true is
returned, the menu command was checked. The returned value is then
saved to the user_prefs table.

local boolean req_pref;

req_pref = Field_SetRequiredStatus(true);
user_ID of table user_prefs = current_user of globals;
get table user_prefs by user_ID_key;
show_req of table user_prefs = req_pref;
save table user_prefs;

Related items Commands

Field_SetRequiredFormat()

218 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _S E T S E L E C T I O N ()

Field_SetSelection()
Description The Field_SetSelection() function selects text in a text field.

Syntax Field_SetSelection(text_field, start_position, length)

Parameters • text_field – The text field in which you are setting the selection.

• start_position – An integer specifying the starting position of the selection.

• length – An integer specifying the length of the selection. If 0 is specified, no

text is selected.

Return value The boolean value true.

Examples The following example selects the first 10 characters in the Description text
field.

local boolean result;

result = Field_SetSelection(Description, 1, 10);

FUNCTION LIBRARY REFERENCE 219

F I E L D _ S E T S T R I N G P R O P E R T Y ( )

Field_SetStringProperty()
Description The Field_SetStringProperty() function sets a specified string property for
a field.

Syntax Field_SetStringProperty(field_name, property, value)

Parameters • field_name – The name of a window field.

• property – An integer constant indicating the property to set. The value

corresponds to one of the following constants:

Constant Description
FIELD_PROP_AUTOCOMPLETE_ For auto-complete fields that have a linked-lookup
LOOKUP_ITEM button, specifies the text to display for the auto-
complete item that opens the lookup.
FIELD_PROP_CAPTION The caption to use for the field.

• value – A string value indicating how to set the property.

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Examples The following example uses the Field_SetStringProperty() function to set

the caption of the Save button to Sa&ve. The ampersand indicates an access
key will be available for the push button.

local boolean result;

result = Field_SetStringProperty('Save Button', FIELD_PROP_CAPTION,

➥ "Sa&ve");

Related items Commands

Field_GetStringProperty()

220 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T T O O L T I P ()

Field_SetToolTip()
Description Sets the tooltip for a window field.

Syntax Field_SetToolTip(field_name, tooltip)

Parameters • field_name – The name of a window field whose tooltip is being set.

• tooltip – A string containing the tooltip for the field.

Return value The boolean value true.

Examples The following example sets the tooltip for the Print button of the RESM
Explorer window to “Disabled”.

local boolean result;

result = Field_SetToolTip('Print Button' of window RESM_Explorer

➥ of form RESM_Explorer, "Disabled");

FUNCTION LIBRARY REFERENCE 221

F I E L D _ S E T Z O O M F O R M A T ( )

Field_SetZoomFormat()
Description The Field_SetZoomFormat() function sets the display characteristics of text
and field objects (string, currency, integer, long, date and time) whose Zoom
property is true.

Syntax Field_SetZoomFormat(font_underline, font_color)

Parameters • font_underline – A boolean specifying whether a line appears beneath the

text or field object. If true, the item will appear underlined.

• font_color – A long integer specifying the color of the text or field object. Use
the following constants:

Constant Constant
COLOR_SYSTEM COLOR_TEAL
COLOR_TRANSPARENT COLOR_GREEN
COLOR_BLACK COLOR_DARK_YELLOW
COLOR_WHITE COLOR_VIOLET
COLOR_RED COLOR_DARK_RED
COLOR_BRIGHT_GREEN COLOR_DARK_BLUE
COLOR_BLUE COLOR_MEDIUM_GRAY
COLOR_TURQUOISE COLOR_LIGHT_GRAY
COLOR_PINK COLOR_LIGHT_YELLOW
COLOR_YELLOW

Return value The boolean value true.

Comments For text objects used for prompts, use these visual indicators to indicate the
presence of a zoom field. The following illustration shows one way a zoom
field’s prompt can look:

Don’t confuse the Zoom property for field and text objects with the Zoom property
for push buttons. When set to true, the Zoom property for push buttons displays a
different mouse pointer, indicating the presence of a zoom field.

222 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I E L D _ S E T Z O O M F O R M A T ()

The Field_SetZoomFormat() function automatically adds several entries to

the defaults file for your application. These entries store the characteristics
that were just specified, and begin with the word “Zoom”. If these entries
exist in the defaults file, Dexterity or the runtime engine will automatically
apply them when your application is run.

The User Interface Conversion Utility in Dexterity Utilities searches for all
prompts that appear beneath zoom buttons and sets each prompt’s Zoom
property to true. Once you’ve converted your application’s user interface
using this utility, use this function to specify the characteristics of zoom
field prompts throughout your application. If you don’t use this function,
zoom field prompts will automatically appear with an underline and a
black font color.

Examples The following example shows the change script for an Apply button in a
user options window. The window allows the user to specify whether to
show underlines for zoom field prompts (using the CB_Use_Underlines
field), and the color of those prompts (a selection from a drop-down list):

local boolean l_result;

local long l_zoom_color;

{Check the selected color in the button drop list.}

case '(L) DDL_Zoom_Color_List'
in [1]
l_zoom_color = COLOR_SYSTEM;
in [2]
l_zoom_color = COLOR_TRANSPARENT;
in [3]
l_zoom_color = COLOR_BLACK;
in [4]
l_zoom_color = COLOR_WHITE;
in [5]
l_zoom_color = COLOR_RED;
in [6]
l_zoom_color = COLOR_BLUE;
else
l_zoom_color = COLOR_SYSTEM;
end case;

{Apply the changes.}

l_result = Field_SetZoomFormat('(L) CB_Use_Underlines',
➥ l_zoom_color);

FUNCTION LIBRARY REFERENCE 223

224 F U N C T I O N L I B R A R Y R E F E R E N C E
File function library
Use the functions in this library when inquiring about or manipulating
operating system files. This library contains the following functions:

• File_Count()
• File_Delete()
• File_GetSize()
• File_GetTempDirectory()
• File_Probe()

FUNCTION LIBRARY REFERENCE 225

F I L E _ C O U N T ( )

File_Count()
Description The File_Count() function returns the number of files currently open,
currently available and the maximum available for an application.

Syntax File_Count(files_available, max_files)

Parameters • files_available – A returned integer indicating the number of buffers

available in an application at a given moment. This number is the max_files
value less the number of open files.

• max_files – A returned integer indicating the maximum number of files that

can be opened by an application on the current workstation. The maximum
number of files will vary depending upon the computer, database type, and
the operating system software you use.

Return value An integer indicating the number of files currently open in an application.

Comments Use this function to check whether enough file buffers are available before
starting a process. The number of available file buffers is depleted
whenever a table is opened. A large number of file buffers can be depleted
in the following ways:

• If a background procedure script accesses several tables, or calls several

other procedure scripts.

• If the user opens several forms.

While it’s unlikely that a Dexterity application will encounter a file open
limitation under normal processing, precautions should be taken to ensure
that extensive processes that access several tables, such as posting, have
enough buffer resources to run to completion.

Examples The following example checks for the number of available buffers before a
posting routine is started. If the number of buffers available is lower than 20
(the number of tables required for the routine), then the user is warned and
processing is stopped. Otherwise, the posting process can continue.
local integer l_available, l_open, l_max;

l_open = File_Count(l_available, l_max);

if l_available <= 20 then
warning "Not enough file resources available to complete posting.
➥ Close all windows and be sure other processing is complete.";
else
call Post_Items;
end if;

226 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E _ D E L E T E ()

File_Delete()
Description The File_Delete() function deletes a file from the operating system.

Syntax File_Delete(file_name)

Parameters • file_name – A string indicating the generic pathname of the file you want to
delete. A generic pathname can be set using either the getfile() function or
the Path_SelectPathname() function.

Return value The boolean value true.

Comments This function deletes any file from the operating system. You also can use
the delete table statement to delete a table from the operating system, but
this statement works for Dexterity data tables only.

Examples The following example is attached to a Delete button and deletes a file
that’s listed in the File Name field. This field displays a generic pathname
returned by the getfile() function.

local integer l_answer;

local boolean result;

l_answer = ask("This will delete the file. Proceed with delete?",

➥ "Yes", "No","");
if l_answer = ASKBUTTON1 then
{The user chose to delete the file.}
result = File_Delete('File Name');
restart form;
end if;

Related items Commands

delete table, getfile(), Path_SelectPathname()

FUNCTION LIBRARY REFERENCE 227

F I L E _ G E T S I Z E ( )

File_GetSize()
Description The File_GetSize() function retrieves the size in bytes of the specified file.

Syntax File_GetSize(path)

Parameters • path – The complete path to the file, in generic format.

Return value A long integer containing the size of the file in bytes.

Examples The following example displays a dialog box that allows the user to select a
graphics file. When the user selects the file, the size of the file is retrieved
and displayed in a message.

local boolean result;

local string path;
local long size;

result = getfile("Select a file", 1, path, "Image (*.gif, *.jpg,

*.png)|*.gif;*.jpg;*.png");

if result = true then

{Retrieve the size of the file}

size = File_GetSize(Path_MakeNative(path));

{Convert the size to kilobytes}

size = size / 1024;

{Display the size}

warning str(size) + " KB";

end if;

228 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E _ G E T T E M P D I R E C T O R Y ()

File_GetTempDirectory()
Description The File_GetTempDirectory() function retrieves the complete path to the
local temporary folder for the current user.

Syntax File_GetTempDirectory()

Parameters • None

Return value A string containing the complete path to the local temporary folder. The
path is in native format.

Examples The following example retrieves the path to the local temporary folder for
the current user.

local string temp_directory;

temp_directory = File_GetTempDirectory();

FUNCTION LIBRARY REFERENCE 229

F I L E _ P R O B E ( )

File_Probe()
Description The File_Probe() function indicates whether a table or file exists in the
specified location and can be opened.

Syntax File_Probe(pathname)

Parameters • pathname – A string containing a generic pathname indicating the location

and name of the table or file.

Return value A boolean indicating whether the table or file exists in the specified location
and can be opened.

Value Description
true The table or file exists in the specified location and can be opened.
false The table or file doesn’t exist in the specified location or can’t be
opened.

Comments This function is typically used in the Main Menu form pre script to
ascertain whether the pathnames in the Pathnames table specify valid
locations.

Examples The following example uses the File_Probe() function to verify whether the
USERS.DAT file exists in the DEX subdirectory.

local boolean result;

result = File_Probe(":C:DEX/USERS.DAT");

Related items Commands

Path_DoesExist()

230 F U N C T I O N L I B R A R Y R E F E R E N C E
File list function library
Use the functions in this library to build a list of files to be used for other
processes in the application, such as the list of attachments in an e-mail
message. This library contains the following functions:

• FileList_Add()
• FileList_Count()
• FileList_Create()
• FileList_Destroy()
• FileList_Get()
• FileList_Remove()
• FileList_ShowDialog()

FUNCTION LIBRARY REFERENCE 231

F I L E L I S T _ A D D ( )

FileList_Add()
Description The FileList_Add() function adds a file to a file list.

Syntax FileList_Add(filelist, full_path {, file_format}{, filename})

Parameters • filelist – A long integer specifying the file list that the file is being added to.

• full_path – A string specifying the complete path of the file to be added,

including the filename and extension.

• file_format – An optional integer parameter that identifies the type of file

being added to the file list. The value typically corresponds to one of the
following constants:

Constant Description
TEXTFILE A text file
TABFILE A tab-delimited file
COMMAFILE A comma-delimited file
HTMLFILE An HTML file
PDFFILE A PDF file
XMLFILE An XML file
DOCXFILE A Microsoft Word file
XLSXFILE A Microsoft Excel file

• filename – An optional string parameter that contains the filename and

extension for the file added to the file list.

Return value A boolean. The value true indicates the file was added to the list, while false
indicates it was not.

Examples The following example created a file list and stores the ID in a local field.
Then it displays a file dialog that allows the user to select a graphics file.
When the user selects a file and clicks Open, the file is added to the file list
identified by the value in the (L) Picture_List local field.

local boolean result;

local string path;

{Create the file list}

'(L) Picture_List' of window Houses of form Houses =FileList_Create();

232 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E L I S T _ A D D ()

{Ask the user for the file to add}

result = getfile("Select a file", 1, path, "Image (*.gif, *.jpg,
➥ *.png)|*.gif;*.jpg;*.png");

if result = true then

{Add the result to the file list}
result = FileList_Add('(L) Picture_List' of window Houses of form
➥ Houses, path);

if result = false then

error "File was not added to the list.";
end if;
end if;

FUNCTION LIBRARY REFERENCE 233

F I L E L I S T _ C O U N T ()

FileList_Count()
Description The FileList_Count() function returns the number of files in the specified
file list.

Syntax FileList_Count(filelist)

Parameters • filelist – A long integer specifying the file list for which the files are being
counted.

Return value An integer containing the number of files in the file list.

Comments The file list count is -1 if the file list has not been created.

Examples The ID for a file list is stored in the (L) Picture_List local field for a window.
The following example retrieves the number of file list items in this file list
and displays the file paths in a dialog box.

local text content;

local integer count;
local integer i;
local string path;
local boolean result;

{Display the files in the file list}

count = FileList_Count('(L) Picture_List');

for i = 1 to count do

result = FileList_Get('(L) Picture_List', i, path);

if result = true then

content = content + path + char(13);
end if;

end for;

234 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E L I S T _ C R E A T E ()

FileList_Create()
Description The FileList_Create() function creates a new file list.

Syntax FileList_Create()

Parameters • None

Return value A long integer containing the ID of the file list.

Examples The following example creates a file list and stores the ID in the local field
(L) Picture_List.

{Create a list of files}

'(L) Picture_List' = FileList_Create();

FUNCTION LIBRARY REFERENCE 235

F I L E L I S T _ D E S T R O Y ( )

FileList_Destroy()
Description The FileList_Destroy() function frees the memory used for a file list.

Syntax FileList_Destroy(filelist)

Parameters • filelist – A long integer specifying the file list for which the memory is being
freed.

Return value A boolean. The value true indicates the memory for the file list was freed,
while false indicates it was not.

Examples The following example frees the memory for the file list identified by the ID
value stored in the (L) Picture_List local field.

local boolean result;

result = FileList_Destroy('(L) Picture_List');

if result = false then
error "Memory for file list could not be freed.";
end if;

236 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E L I S T _ G E T ()

FileList_Get()
Description The FileList_Get() function retrieves the file information for a specific
position in the file list.

Syntax FileList_Get(filelist, index, full_path {, file_format}{, filename})

Parameters • filelist – A long integer specifying the file list from which file information is
being retrieved.

• index – An integer specifying the file list item to be retrieved from the file
list. The value 1 indicates the first item.

• full_path – A returned string containing the full path of the file list item.

• file_format – An optional returned integer that identifies the type of file for
the file list item. The value typically corresponds to one of the following
constants:

Constant Description
TEXTFILE A text file
TABFILE A tab-delimited file
COMMAFILE A comma-delimited file
HTMLFILE An HTML file
PDFFILE A PDF file
XMLFILE An XML file
DOCXFILE A Microsoft Word file
XLSXFILE A Microsoft Excel file

• filename – An optional returned string that contains the filename and

extension for the file list item.

Return value A boolean. The value true indicates the file list item was retrieved, while
false indicates it was not.

FUNCTION LIBRARY REFERENCE 237

F I L E L I S T _ G E T ( )

Examples The following example retrieves all of the file list items for the file list
identified by the ID value stored in the local field (L) Picture_List. The file
paths are displayed in a dialog box.

local text content;

local integer count;
local integer i;
local string path;
local boolean result;

{Display the files in the file list}

count = FileList_Count('(L) Picture_List');

for i = 1 to count do

result = FileList_Get('(L) Picture_List', i, path);

if result = true then

content = content + path + char(13);
end if;

end for;

238 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E L I S T _ R E M O V E ()

FileList_Remove()
Description The FileList_Remove() function removes the specified file list item from a
file list.

Syntax FileList_Remove(filelist, index)

Parameters • filelist – A long integer specifying the file list from which a file list item is
being removed.

• index – An integer specifying the file list item to be removed from the file
list. The value 1 indicates the first item.

Return value A boolean. The value true indicates the file list item was removed, while
false indicates it was not.

Examples The following example removes the first file list item from the file list
identified by the ID value stored in the local field (L) Picture_List.

local boolean result;

result = FileList_Remove('(L) Picture_List', 1);

if result = false then

error "Remove failed.";
end if;

FUNCTION LIBRARY REFERENCE 239

F I L E L I S T _ S H O W D I A L O G ()

FileList_ShowDialog()
Description The FileList_ShowDialog() function displays a file system dialog box that
allows the user to select a set of files. The selected files are returned as a file
list.

Syntax FileList_ShowDialog(prompt, default_filter, default_path {, custom_filter})

Parameters • prompt – A string that will be displayed in the title bar of the dialog box.

• default_filter – An integer indicating the type of file you’re searching for. If

you are using one of the predefined filters, this value corresponds to one of
the following constants:

Constant Description
APPFILE Displays only application files
DICTIONARY Displays only dictionary files (.DIC)
LAUNCH Displays only launch files (.SET)
MACROFILE Displays only Dexterity macro files (.MAC)
XMLFILE Displays only XML files
TEXTFILE Displays all files

If you are using a custom filter, the default_filter parameter indicates which
filter in the custom filter set will be used by default. For instance, assume
three filter types are defined in the custom filter. To specify that the second
filter type be used as the default, use 2 for this parameter.

• default_path – A string specifying the complete path of the location to be

displayed in the dialog box. The path is in native format. If you do not
supply a path, the current path for the application will be used.

• custom_filter – An optional parameter that defines the set of custom filters to

use. The value can be a string or a list field that has been filled using the
FileType_FillList() function.

If a string is used to specify the custom filter list, the following syntax is
used:

description |filter{;filter}|

The description parameter is a string that describes the filter, such as

“Dictionaries (*.DIC)”. It must be followed by a pipe (|) character.

240 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E L I S T _ S H O W D I A L O G ()

The filter parameter specifies a file extension, such as “*.DIC”. When this
filter is used, files that match this extension will be displayed in the dialog
box. The filter parameter should not contain spaces. To specify multiple
filters, separate them with a semicolon (;). End the list of filters with a pipe
(|) character. Several custom filters can be concatenated within the
custom_filter string.

Return value A long integer containing the ID of the file list. If the user clicks Cancel, the
value 0 is returned.

Examples The following example displays a file dialog that allows the user to select
multiple dictionary files from the Dynamics GP folder. The selected files are
returned in a file list.
local long file_list;

file_list = FileList_ShowDialog("Select dictionaries", DICTIONARY,

➥ "C:\Program Files\Microsoft Dynamics\GP");

The following example displays a file dialog that allows the user to select
graphics files from a folder. A custom filter is used so that only graphics
files are displayed. No default path is specified, so the current path for the
application is used.
local long file_list;

file_list = FileList_ShowDialog("Select graphics", 1, "",

➥ "GIF (*.gif)|*.gif|PNG (*.png)|*.png|JPEG (*.jpg)|*.jpg|");

The following example uses the FileType_FillList() function to add the

standard output types to a local list box. It then displays a file dialog that
allows the user to select a set of files for the selected type. Notice how the
list box is passed as the custom filter.
local long file_list;
local boolean result;

{Fill the file list with available types.}

clear '(L) FileTypes';
result = FileType_FillList('(L) FileTypes');

{Display the file dialog, with Tab-delimited file type selected.}

file_list = FileList_ShowDialog("Select the source files", 2, "",
➥ '(L) FileTypes');

FUNCTION LIBRARY REFERENCE 241

242 F U N C T I O N L I B R A R Y R E F E R E N C E
File type function library
Use the functions in this library when working with files for the standard
output types for a Dexterity-based application. This library contains the
following functions:

• FileType_CanAppend()
• FileType_FillList()
• FileType_GetExtension()
• FileType_IsValid()

FUNCTION LIBRARY REFERENCE 243

F I L E T Y P E _ C A N A P P E N D ()

FileType_CanAppend()
Description The FileType_CanAppend() function indicates whether a specified file
type can be appended to.

Syntax FileType_CanAppend(file_type)

Parameters • file_type – An integer specifying the file type. The value typically
corresponds to one of the following file type constants:

Constant Description Can append

TEXTFILE Text file Yes
TABFILE Tab-delimited file Yes
COMMAFILE Comma-delimited file Yes
HTMLFILE HTML file No
XMLFILE XML file No
PDFFILE PDF file No

Return value A boolean. True indicates the file type can be appended to, while false
indicates that it cannot.

Comments Typically, the value passed to this function will come from the item data for
the list field filled by the FileType_FillList() function.

Examples The following example is the change script for a list box that contains file
types added by the FileType_FillList() function. It retrieves the item data
for the selected item, and then sets a check box based on whether the
selected file type can be appended to.

local integer itemdata_value;

{Retrieve the item data value containing the file type.}

itemdata_value = integer(itemdata('(L) FileTypes', '(L) FileTypes'));

{Can the file type be appended to?}

'(L) CanAppend' = FileType_CanAppend(itemdata_value);

244 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E T Y P E _ F I L L L I S T ()

FileType_FillList()
Description The FileType_FillList() function fills a list box with the available file types
that the Report Writer can export to.

Syntax FileType_FillList(list_field)

Parameters • list_field – A list box that will contain the available file types. The item data
for each item contains the file type value for that item.

Return value A boolean. The value true indicates the file types were added to the list,
while false indicates they were not.

Comments The following file types will be added to the list box:

File type Comments

Text file
Tab-delimited file
Comma-delimited file
HTML file
PDF file Added only if PDF output is available.
XML Data file

Examples The following example fills the (L) FileType list box field with the available
file types.

local boolean result;

{Fill the file list with available types.}

clear '(L) FileTypes';
result = FileType_FillList('(L) FileTypes');

FUNCTION LIBRARY REFERENCE 245

F I L E T Y P E _ G E T E X T E N S I O N ()

FileType_GetExtension()
Description The FileType_GetExtension() function retrieves the file extension for a
specified file type.

Syntax FileType_GetExtension(file_type)

Parameters • file_type – An integer specifying the file type for which the extension will be
returned. The following table lists the constants for the file types of which
an extension can be returned.

Constant Description
TEXTFILE Text file
TABFILE Tab-delimited file
COMMAFILE Comma-delimited file
HTMLFILE HTML file
PDFFILE PDF file
XMLFILE XML file
APPFILE Application file
DICTIONARY Dictionary file
LAUNCH Launch file
MACROFILE Macro file
DOCXFILE Microsoft Word file
XLSXFILE Microsoft Excel file
XPSFILE XPS file
RTFFILE Rich Text file

Return value A string containing the file type extension. The extension does not include
the initial period character.

Examples The following example retrieves the first item in a file list. Then it retrieves
the file extension based on the file type for the item.

local string file_extension;

local string file_path;
local integer file_type;
local boolean result;

{Retrieve the first item in the file list.}

result = FileList_Get('(L) FileList', 1, file_path, file_type);

246 F U N C T I O N L I B R A R Y R E F E R E N C E
 F I L E T Y P E _ G E T E X T E N S I O N ()

if result = true then

file_extension = FileType_GetExtension(file_type);
end if;

FUNCTION LIBRARY REFERENCE 247

F I L E T Y P E _ I S V A L I D ( )

FileType_IsValid()
Description The FileType_IsValid() function indicates whether a file type is one of the
valid types the Report Writer can export to.

Syntax FileType_IsValid(file_type)

Parameters • file_type – An integer specifying the file type.

Return value A boolean. The value true indicates the file type is valid for the Report
Writer to export to, while false indicates it is not.

Examples The following example is the change script for a list box that contains file
types added by the FileType_FillList() function. It retrieves the item data
for the selected item, and then sets a check box based on whether the
selected file type can be exported to.

local integer itemdata_value;

{Retrieve the item data value containing the file type.}

itemdata_value = integer(itemdata('(L) FileTypes', '(L) FileTypes'));

{Can the file type be exported to?}

'(L) CanExport' = FileType_IsValid(itemdata_value);

248 F U N C T I O N L I B R A R Y R E F E R E N C E
Form function library
Use the functions in this library to perform special actions for forms. This
library contains the following function:

• Form_GetWindowGroup()

FUNCTION LIBRARY REFERENCE 249

F O R M _ G E T W I N D O W G R O U P ( )

Form_GetWindowGroup()
Description The Form_GetWindowGroup() function creates a window group for the
specified form. If the window group already exists for the form, the ID for
the window group is retrieved.

Syntax Form_GetWindowGroup(form formname, window_group_ID)

Parameters • formname – The technical name of the form for which the window group is
being created or retrieved.

• window_group_ID – A returned long integer containing the ID of the

window group.

Return value A boolean. The value true indicates that the window group did not exist
and was created. The value false indicates that the window group already
existed.

Examples The following example is the trigger processing procedure that runs in
response to the SetupWindowGroup procedure for the
RM_Customer_Maintenance form. The trigger processing procedure
retrieves the window group for the Customer Maintenance window. It adds
the Contact History window to the end of the window group.
local long windowGroupId;
local integer tag;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

{Get the tag for the command that runs when the new tab is clicked.}
tag = Command_GetTag(command 'IG_Contact_History_Tab' of form
➥ 'Command_IG_Sample');

{Add the window to the end of the window group.}

WindowGroup_AddWindow(windowGroupId, window 'Contact History' of form
➥ 'IG_Contact_History', tag, 0);

250 F U N C T I O N L I B R A R Y R E F E R E N C E
Import function library
Use the functions in this library to read, or import text records (lines) as
large as 2048 characters, with fields as large as 255 characters, from a tab- or
comma-delimited text file. These functions will not write to a text file. This
library contains the following functions:

• Import_CloseFile()
• Import_GetNextField()
• Import_GetNextRecord()
• Import_OpenFile()

FUNCTION LIBRARY REFERENCE 251

I M P O R T _ C L O S E F I L E ()

Import_CloseFile()
Description The Import_CloseFile() function closes the text file opened by
Import_OpenFile() and releases the file_ID.

Syntax Import_CloseFile(file_ID)

Parameters • file_ID – The unique file ID assigned by Import_OpenFile().

Return value An integer indicating the result of the file close. If 0 is returned, the function
closed the file successfully. If the file_ID is returned, the function couldn’t
close the file successfully.

Comments Always close a text file once you’ve completed reading it, or if you receive
an error condition while opening it using Import_OpenFile().

Examples See the example of Import_GetNextField().

252 F U N C T I O N L I B R A R Y R E F E R E N C E
 I M P O R T _ G E T N E X T F I E L D ()

Import_GetNextField()
Description The Import_GetNextField() function returns the value of the current field,
and advances to the next field in the record. A field is a set of characters
separated from other characters in the record by a comma or a tab.

Syntax Import_GetNextField(file_ID)

Parameters • file_ID – The unique file ID assigned by Import_OpenFile().

Return value A string representing the text in the current field (not the field you’re
advancing to). The maximum return value is 255 characters.

If you need to read more than 255 characters for a given field, use the
TextFile_ReadText() function to read the field, instead.

Comments This function moves to the next field in a text record. The following
illustration shows how the Import_GetNextField() function interprets a
comma-delimited text file:

A field is text separated from

other text by a delimeter
(a comma or a tab).

An empty field appears

as two consecutive
delimeters.

Execute this function multiple times for the same record to return values for
each field in the record. You ascertain the number of fields in
the record using the num_fields parameter of the Import_OpenFile()
function. Once you’ve read all the fields in the record, use
Import_GetNextRecord() to advance to the next record. Then continue by
using Import_GetNextField().

FUNCTION LIBRARY REFERENCE 253

I M P O R T _ G E T N E X T F I E L D ( )

Examples The following example opens a text file for importing. It returns a
pathname using the getfile() function, then opens the file for that pathname
using the Import_OpenFile() function. The script then loops through each
record in the file using Import_GetNextRecord(), and returns field values
for each record using Import_GetNextField(). Once processing reaches the
end of the file, or if the script encounters an error, the script closes the text
file using Import_CloseFile().

local integer l_num_fields,l_file_ID,l_result,l_index,l_delimiter;

local string l_pathname, l_text;
local boolean l_EOF;

l_delimiter = COMMAFILE; {Comma delimited.}

if getfile("Choose an import file:", TEXTFILE, l_pathname) then

l_file_ID = Import_OpenFile(3333, l_pathname, l_delimiter,
➥ l_num_fields);
{Display the pathname in the window.}
'(L) TextFile_Pathname' = l_pathname;
{Check for errors opening the file.}
if (l_file_ID = 0) or (l_num_fields = 0) then
{The file couldn’t be opened.}
warning "There was an error opening the text file.";
{Release the file ID.}
l_result = Import_CloseFile(l_file_ID);
abort script;
end if;
{Loop through the file to examine each record.}
l_EOF = Import_GetNextRecord(l_file_ID);
while not l_EOF do
{Loop through each record to get field values.}
for l_index = 1 to l_num_fields do
l_text = Import_GetNextField(l_file_ID);
warning l_text;
end for;
l_EOF = Import_GetNextRecord(l_file_ID);
end while;
l_result = Import_CloseFile(l_file_ID);
end if;

254 F U N C T I O N L I B R A R Y R E F E R E N C E
 I M P O R T _ G E T N E X T R E C O R D ()

Import_GetNextRecord()
Description The Import_GetNextRecord() advances to the next record, or “line” in the
text file. A record is made up of all the fields between carriage returns in a
text file.

Syntax Import_GetNextRecord(file_ID)

Parameters • file_ID – The unique file ID assigned by Import_OpenFile().

Return value A boolean representing an end of file (EOF) error. If false, there are
additional records in the file. If true, processing reached the end of the file.

Comments This function moves to the next record in a text file. The following
illustration shows how the Import_GetNextRecord() function interprets a
comma-delimited text file:

A record is made up of
fields that are separated
by a delimeter.

A carriage return
indicates the end of a
record.

Examples See the example of Import_GetNextField().

FUNCTION LIBRARY REFERENCE 255

I M P O R T _ O P E N F I L E ( )

Import_OpenFile()
Description The Import_OpenFile() function opens a specified text file and reserves a
file ID. This file ID must be used with the remainder of the functions in the
Import library.

Syntax Import_OpenFile(product_ID, pathname, delimiter_type, num_fields)

Parameters • product_ID – An integer indicating the dictionary’s ID.

• pathname – A string specifying the full generic path and file name for the
text file.

• delimiter_type – An integer indicating the delimiter (tab or comma) used by

the text file. Use one of the following constants:

Constant Description
COMMAFILE Comma delimiter
TABFILE Tab delimiter

• num_fields – An integer returned by this function representing the number

of fields. This is the number of text items separated by the delimiter
character (comma or tab) in the first record (line). If the file can’t be opened,
this function returns num_fields as zero (0).

Return value An integer representing a unique file ID. This file ID must be used in the
remainder of the functions in the Import library. If this value is 0, an open
error occurred.

Comments Each record in the import file is limited to 2047 total characters (including
the CR/LF combination at the end of the record). If the imported line
exceeds this length, the remainder of the line will be truncated.

Always close a text file using Import_CloseFile() once you’ve opened it

using Import_OpenFile().

Examples See the example of Import_GetNextField().

256 F U N C T I O N L I B R A R Y R E F E R E N C E
Help pane function library
Use the functions in this library to implement a docked HTML Help pane in
an application. This library contains the following functions:

• HelpPane_Create()
• HelpPane_Destroy()
• HelpPane_DisplayTopic()
• HelpPane_GetWidth()
• HelpPane_SetTitle()
• HelpPane_SetWidth()
• HelpPane_Show()

FUNCTION LIBRARY REFERENCE 257

H E L P P A N E _ C R E A T E ( )

HelpPane_Create()
Description The HelpPane_Create() function creates a docked HTML Help pane on the
right side of the application’s display area. This pane can be used to display
topics from a compiled HTML Help (.chm) file.

Syntax HelpPane_Create()

Parameters • None

Return value A boolean. The value true indicates the help pane was created, while false
indicates it was not.

Comments The HelpPane_Create() function creates the help pane, but does not display
it. Use the HelpPane_Show() function to display the help pane.

Examples The following example is a command script that creates a docked help pane
in the Real Estate Sales Manager sample application.

local boolean result;

local string path;
local integer tag;

path = Path_GetForApp(2);
tag = Command_GetTag(command CMD_HelpPane of form 'Main Menu');

{Check the status of the command}

if Command_GetBooleanProperty(tag, COMMAND_PROP_CHECKED) = false then
{Create the help pane and show the default topic}
result = HelpPane_Create();
result = HelpPane_Show(true);
result = HelpPane_DisplayTopic(path + "RESM.chm", "RESMTOC.htm");

{Mark the Help Pane menu item}

Command_SetBooleanProperty(tag, COMMAND_PROP_CHECKED, true);
else
{Destroy the help pane}
result = HelpPane_Destroy();

{Unmark the Help Pane menu item}

Command_SetBooleanProperty(tag, COMMAND_PROP_CHECKED, false);
end if;

258 F U N C T I O N L I B R A R Y R E F E R E N C E
 H E L P P A N E _ D E S T R O Y ()

HelpPane_Destroy()
Description The HelpPane_Destroy() function removes the docked HTML Help pane
from the right side of the application’s display area.

Syntax HelpPane_Destroy()

Parameters • None

Return value A boolean. The value true indicates the help pane was removed, while false
indicates it was not.

Examples The following example saves the width of the docked HTML Help pane,
and then uses the HelpPane_Destroy() function to remove it from the
application.

local boolean result;

local integer pane_width;

pane_width = HelpPane_GetWidth();
result = Defaults_Write("HelpPaneWidth", str(pane_width));

{Destroy the help pane}

result = HelpPane_Destroy();

FUNCTION LIBRARY REFERENCE 259

H E L P P A N E _ D I S P L A Y T O P I C ()

HelpPane_DisplayTopic()
Description The HelpPane_DisplayTopic() function displays the specified topic from
an compiled HTML Help file in the docked help pane.

Syntax HelpPane_DisplayTopic(help_file, topic {, error_code, error_string})

Parameters • help_file – A string specifying the complete path (in generic format) to the
compiled HTML Help file (.chm) from which a topic will be displayed.

• topic – A string or long integer that specifies the help topic to display. If a
string value is used, supply the HTML filename of the topic to be displayed
from the compiled help file. If a long integer value is used, supply the
context number for the topic to be displayed from the compiled help file.

• error_code – An optional long integer returned from the HTML Help engine
that indicates what specific HTML Help error occurred. The value 0
indicates that no error was detected.

No error code is returned if you specify an invalid HTML filename for the topic to
be displayed in the compiled help file.

• error_string – An optional string returned from the HTML Help engine that
describes the specific HTML Help error that occurred. If no error was
detected, the empty string ("") is returned.

Return value A boolean. The value true indicates the command to display the topic was
successful, while false indicates it was not.

Examples The following example uses the HelpPane_DisplayTopic() function to

display a named HTML file from the RESM.chm HTML Help file.

local boolean result;

local integer pane_width;

{Create the help pane}

result = HelpPane_Create();

{Set the title}

result = HelpPane_SetTitle("RESM Help");

{Set the pane width and show it}

pane_width = value(Defaults_Read("HelpPaneWidth"));

260 F U N C T I O N L I B R A R Y R E F E R E N C E
 H E L P P A N E _ D I S P L A Y T O P I C ()

if pane_width > 20 then

result = HelpPane_SetWidth(pane_width);
end if;
result = HelpPane_Show(true);

{Display a default topic}

result = HelpPane_DisplayTopic(path + "RESM.chm", "RESMTOC.htm");

The following example is a portion of the help processing script for the Real
Estate Sales Manager sample application. If the docked help pane has been
created, the HelpPane_DisplayTopic() function is used to display the help
topic for the currently-active window in it. Notice how the optional return
values from the function are used to display any error returned from the
HTML Help engine.

local long context_number, HTML_err;

local boolean bool_result;
local string help_path_and_file, HTML_err_string;

help_path = Dict_GetPathname(2);
help_path_and_file = help_path + "RESM.chm";

{Get the context number for the item chosen.}

context_number = WinHelp_GetWindowContextNumber();

{Is the docked help pane open? If so, use it instead.}

if HelpPane_GetWidth() = 0 then
{The docked help pane wasn't open, so don't use it.
{Call the help engine, displaying help for the current window.}
result = WinHelp_InvokeHelp(help_path_and_file, HELP_CMD_CONTEXT,
➥ context_number);
else
{The docked help pane is open, so use it.}
bool_result = HelpPane_DisplayTopic(help_path_and_file,
➥ context_number, HTML_err, HTML_err_string);
if HTML_err <> 0 then
error HTML_err_string;
end if;
end if;

FUNCTION LIBRARY REFERENCE 261

H E L P P A N E _ G E T W I D T H ( )

HelpPane_GetWidth()
Description The HelpPane_GetWidth() function retrieves the width of the docked
HTML Help pane in the application.

Syntax HelpPane_GetWidth()

Parameters • None

Return value An integer containing the width of the help pane.

Comments If the help pane hasn’t been created, this function returns the value 0 (zero).
The default width for the help pane is 250 pixels. The minimum width is 20
pixels.

Examples The following example uses the HelpPane_GetWidth() function to retrieve

the width of the help pane and save the value in the Dex.ini file.

local boolean result;

local integer pane_width;

pane_width = HelpPane_GetWidth();
result = Defaults_Write("HelpPaneWidth", str(pane_width));

262 F U N C T I O N L I B R A R Y R E F E R E N C E
 H E L P P A N E _ S E T T I T L E ()

HelpPane_SetTitle()
Description The HelpPane_SetTitle() function specifies the title that will appear at the
top of the docked HTML Help pane on the right side of the application’s
display area.

Syntax HelpPane_SetTitle(title)

Parameters • title – A string specifying the title to display.

Return value A boolean. The value true indicates the title was set, while false indicates it
was not.

Examples The following example uses the HelpPane_SetTitle() function to set the
title of the help pane, and then displays the help pane.

local boolean result;

{Create the help pane}

result = HelpPane_Create();

{Set the title}

result = HelpPane_SetTitle("RESM Help");

{Show the help pane}

result = HelpPane_Show(true);

FUNCTION LIBRARY REFERENCE 263

H E L P P A N E _ S E T W I D T H ( )

HelpPane_SetWidth()
Description The HelpPane_SetWidth() function specifies the width of the docked
HTML Help pane on the right side of the application area.

Syntax HelpPane_SetWidth(width)

Parameters • width – An integer specifying the width of the docked help pane.

Return value A boolean. The value true indicates the width was set, while false indicates
it was not.

Comments The default width for the docked help pane is 250 pixels.

Return value A boolean. The value true indicates the width of the help pane was set,
while false indicates it was not.

Examples The following example reads the help pane width from the Dex.ini file and
then uses the HelpPane_SetWidth() function to set the width of the docked
help pane.

local boolean result;

local integer pane_width;

pane_width = value(Defaults_Read("HelpPaneWidth"));
if pane_width > 20 then
result = HelpPane_SetWidth(pane_width);
end if;
result = HelpPane_Show(true);

264 F U N C T I O N L I B R A R Y R E F E R E N C E
 H E L P P A N E _ S H O W ()

HelpPane_Show()
Description The HelpPane_Show() function causes the docked HTML Help pane to be
shown or hidden in the application.

Syntax HelpPane_Show(action)

Parameters • action – A boolean. The value true specifies that the help pane should be
shown, while false specifies it should be hidden.

Return value A boolean. The value true indicates the action was completed successfully,
while false indicates it was not.

Comments You must use the HelpPane_Create() function to create the help pane
before you can show it.

Examples The following example uses the HelpPane_Show() function to hide the
help pane in the application.

local boolean result;

result = HelpPane_Show(false);

FUNCTION LIBRARY REFERENCE 265

266 F U N C T I O N L I B R A R Y R E F E R E N C E
 IP function library
Refer to the Chapter Use the functions in this library when working with TCP/IP addresses or
12, “Process Server,” in numbers in your application. This library contains the following functions:
the Stand-alone Appli-
cation Guide for more • IP_GetIPName()
information about dis- • IP_GetIPNumber()
tributed processing. • IP_PingDPS()

FUNCTION LIBRARY REFERENCE 267

I P_ G E T I P N A M E ( )

IP_GetIPName()
Description The IP_GetIPName() function returns the host name of the current
workstation.

Syntax IP_GetIPName()

Parameters • None

Return value A string containing the host name of the workstation.

Examples This example displays a warning message with the host name of the current
workstation:

warning "Host name is " + IP_GetIPName();

Related items Additional information

Chapter 12, “Process Server,” in the Dexterity Stand-alone Application Guide

268 F U N C T I O N L I B R A R Y R E F E R E N C E
 I P _ G E T I PN U M B E R ()

IP_GetIPNumber()
Description The IP_GetIPNumber() function returns the IP address of the current
workstation.

Syntax IP_GetIPNumber()

Parameters • None

Return value A string containing the IP address of the workstation.

Examples This example displays a warning message with the IP address of the current
workstation:

warning "Host name is " + IP_GetIPNumber();

Related items Additional information

Chapter 12, “Process Server,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 269

I P_ P I N G D P S ( )

IP_PingDPS()
Description The IP_PingDPS() function “pings” a Process Server workstation to find
out whether the Process Server is running. The “ping” procedure sends a
small piece of data from one computer to another to test connectivity
between the two.

Syntax IP_PingDPS(address, error_message)

Parameters • address – The IP address of the Process Server you want to ping. This can be
the IP number, or if name resolution exists for your system (such as a
domain names server or a hosts file), the IP name.

• error_message – A string describing the error that occurred if this function

returns false. The message returned is “Server address is not available.” If
this function returns true, error_message isn’t returned.

Return value A boolean indicating the status: if true, the ping was successful and the
connection between sending and receiving workstations is valid. If false,
the ping wasn’t successful and no connection between the sending and
receiving workstations exists.

Examples This example checks to determine whether a server is currently active at the
IP address JAX.GPS.COM.

local boolean l_result;

local string l_error_message;

if IP_PingDPS("JAX.GPS.COM", l_error_message) then

warning "This Process Server workstation is available.";
else
warning l_error_message;
end if;

Related items Additional information

Chapter 12, “Process Server,” in the Dexterity Stand-alone Application Guide

270 F U N C T I O N L I B R A R Y R E F E R E N C E
 Launch file function library
Refer to Chapter 58, Use the functions in this library when working with launch files in your
“Using Launch Files,” application. This library contains the following functions:
in Volume 1 of the
Dexterity • Launch_CountProds()
Programmer’s Guide • Launch_FillListWithProds()
for more information. • Launch_GetFileInfo()
• Launch_GetFileName()
• Launch_GetProdID()
• Launch_GetProdName()
• Launch_GetProdPosition()
• Launch_ParseFileFromPath()
• Launch_ReadDictPath()
• Launch_SelectDict()
• Launch_SelectFile()
• Launch_WriteDictPath()

FUNCTION LIBRARY REFERENCE 271

L A U N C H _ C O U N T P R O D S ( )

Launch_CountProds()
Description The Launch_CountProds() function counts the number of products listed in
the launch file. This function will work only when your application is
opened with the runtime engine.

Syntax Launch_CountProds()

Parameters • None

Return value An integer specifying the number of products.

Examples The following example returns the number of products listed in the launch
file.

'Current Products' = Launch_CountProds();

Related items Commands

Launch_FillListWithProds(), Launch_GetProdID()

272 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ F I L L L I S T W I T H P R O D S ()

Launch_FillListWithProds()
Description The Launch_FillListWithProds() function fills a list field (a field that uses a
list box, combo box, drop-down list, or button drop list data type) with
product names listed in the current launch file. This function will work only
when your application is opened with the runtime engine.

Syntax Launch_FillListWithProds(list_field)

Parameters • list_field – A list field filled with product names returned by this function.

Return value The boolean value true.

Comments If you access the application in test mode, this function fills list_field with
the dictionary name, not the product name.

Examples The following example fills a list field named Product List with products in
the current launch file.

local boolean l_result;

open form 'Product Info';

{Fill the list with products in the current launch file.}
l_result = Launch_FillListWithProds('Product List');

Related items Commands

Launch_GetProdID(), Launch_CountProds()

FUNCTION LIBRARY REFERENCE 273

L A U N C H _ G E T F I L E I N F O ()

Launch_GetFileInfo()
Description The Launch_GetFileInfo() function fills list fields (fields that use a drop-
down list, list box, non-native list or button drop list data type) with
product names, product IDs and dictionary location IDs from the launch
file. This function will work only when your application is opened with the
runtime engine.

Syntax Launch_GetFileInfo(launch_file_location, product_ID, product_name,

dictionary_location_ID)

Parameters • launch_file_location – A string representing the full generic path to the

launch file, including the name of the launch file. Both the
Launch_SelectFile() and Launch_GetFileName() functions return the full
path and name of a launch file.

• product_ID – A list field filled with product IDs returned from

launch_file_location.

• product_name – A list field filled with product names returned from

launch_file_location.

• dictionary_location_ID – A list field filled with dictionary location IDs

returned from launch_file_location.

Return value The boolean value true.

Comments Product IDs, product names and dictionary location IDs are required
parameters when you read a dictionary pathname using
Launch_ReadDictPath() or change a dictionary pathname using
Launch_WriteDictPath().

Examples The following example opens a system dialog using Launch_SelectFile().

When the user selects a launch file, the path and name of the launch file is
used with the Launch_GetFileInfo() function to fill list fields with
information about that launch file.
local boolean l_result;
local string l_pathname;

if Launch_SelectFile(l_pathname) then
l_result = Launch_GetFileInfo(l_pathname, 'Product IDs',
➥ 'Products', 'Dictionary Location IDs');
end if;

274 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ G E T F I L E N A M E ()

Launch_GetFileName()
Description The Launch_GetFileName() function returns the full generic path and
name of the launch file for the current application. This function will work
only when your application is opened with the runtime engine.

Syntax Launch_GetFileName()

Parameters • None

Return value A string containing the full generic pathname.

Comments Use this function to perform operations on the launch file used by the
currently running application. This is in contrast to Launch_SelectFile(),
which opens a dialog box that allows you to select any launch file.

Examples This example returns the location of the launch file for the current
application. Using this location, the Launch_GetFileInfo() function fills list
fields with product names, product IDs and dictionary location IDs from
the current launch file:

local string l_launch_file_location;

local boolean l_result;

l_launch_file_location = Launch_GetFileName();
l_result = Launch_GetFileInfo(l_launch_file_location,
➥ 'Product IDs', 'Products', 'Dictionary Location IDs');

FUNCTION LIBRARY REFERENCE 275

L A U N C H _ G E T P R O D I D ( )

Launch_GetProdID()
Description The Launch_GetProdID() function returns a product ID based upon a
product’s position in the launch file. This function will work only when
your application is opened with the runtime engine.

Syntax Launch_GetProdID(index)

Parameters • index – An integer corresponding to the position of a product name in the

launch file. For instance, to return a product ID for the first product in the
launch file, use an index of 1; to return a product ID for the third product in
the launch file, use an index of 3, and so on.

Return value An integer specifying the product ID.

Comments You can ascertain the index by referencing the position of a product in a list
field. Use the Launch_FillListWithProds() function to fill a list field with
product names. The position of each name in the list then corresponds to
the position of the product in the launch file.

Examples This example uses the selected product’s position in the list as the index. The
Launch_GetProdID() function uses this position to return the
corresponding product ID:

'(L) Product ID' = Launch_GetProdID('Product List');

276 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ G E T P R O D N A M E ()

Launch_GetProdName()
Description The Launch_GetProdName() function returns a product’s name from the
launch file based upon its product ID. This function will work only when
your application is opened with the runtime engine.

Syntax Launch_GetProdName(product_ID)

Parameters • product_ID – An integer designating the product ID. You can return a
product ID using Launch_GetProdID().

Return value A string indicating the product name.

Examples The following example returns the product name “Lead Maintenance” from
the launch file. In the launch file, the Lead Maintenance application’s ID is
4549.

'Product Name' = Launch_GetProdName(4549);

Related items Commands

Launch_GetProdID(), Launch_GetFileInfo()

FUNCTION LIBRARY REFERENCE 277

L A U N C H _ G E T P R O D P O S I T I O N ( )

Launch_GetProdPosition()
Description The Launch_GetProdPosition() function returns the position of a product
in the launch file. This function will work only when your application is
opened with the runtime engine.

Syntax Launch_GetProdPosition(product_ID)

Parameters • product_ID – An integer designating the product ID. You can return a
product ID using Launch_GetProdID().

Return value An integer designating the product position.

Examples The following example returns the position of a Lead Maintenance

application. In the launch file, the Lead Maintenance application’s ID is
4549.

local integer l_position;

l_position = Launch_GetProdPosition(4549);

Related items Commands

Launch_GetProdID(), Launch_GetFileInfo()

278 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ P A R S E F I L E F R O M P A T H ()

Launch_ParseFileFromPath()
Description The Launch_ParseFileFromPath() function parses a file’s operating system
name from a generic pathname.

Syntax Launch_ParseFileFromPath(file_path)

Parameters • file_path – A string containing a pathname in generic format.

Return value A string containing the file’s operating system name.

Comments The file_path must be in a generic format prior to parsing the file name from
it using this function. All Dexterity commands that return pathnames will
do so in generic format. The following illustration shows a generic path and
the resulting operating system name that’s parsed:

A generic pathname

:C:DEXAPPS/SYSTEM/SYSTEM.DIC

The file’s O/S

name returned
by this function.

Examples This example parses a launch file’s operating system name from a generic
path returned by the getfile() function.

local string l_file_path;

if getfile("Select a file", LAUNCH, l_file_path) then

'Launch File Name' = Launch_ParseFileFromPath(l_file_path);
end if;

FUNCTION LIBRARY REFERENCE 279

L A U N C H _ R E A D D I C T P A T H ( )

Launch_ReadDictPath()
Description The Launch_ReadDictPath() function returns the location of an
application, forms, or reports dictionary from the launch file. This function
will work only when your application is opened with the runtime engine.

Syntax Launch_ReadDictPath(launch_file_location, product_ID, dictionary_type,

dictionary_location_ID)

Parameters • launch_file_location – A string containing the full generic path to the launch
file, including the file name. Both Launch_SelectFile() and
Launch_GetFileName() return the full path and name of a launch file.

• product_ID – An integer indicating the product ID for the application,

forms, or reports dictionary pathname you want returned. You can return a
product ID using either the Launch_GetProdID() or the
Launch_GetFileInfo() functions.

• dictionary_type – An integer indicating the type of dictionary for which the

pathname is being returned. Use the following integer values:

Value Description
0 Application dictionary
1 Forms dictionary
2 Reports dictionary

• dictionary_location_ID – A string indicating the dictionary location ID. This

can be returned using the Launch_GetFileInfo() function.

Return value A string indicating the dictionary path.

Comments Once you read a dictionary location using this function, you can then
modify the location, and write changes to the launch file using
Launch_WriteDictPath().

Examples This example retrieves the forms dictionary path for a product whose
launch file information is already displayed in a window:
'Form Dict Path' = Launch_ReadDictPath('Launch File', 'Product ID',
➥ 1, 'Dictionary Location ID');

Related items Commands

Launch_WriteDictPath(), Launch_SelectDict()

280 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ S E L E C T D I C T ()

Launch_SelectDict()
Description The Launch_SelectDict() function displays an operating system dialog box,
from which you can select a dictionary location.

Syntax Launch_SelectDict(dictionary_name, pathname)

Parameters • dictionary_name – The name of the dictionary as it will appear in the File
Name field within the dialog box.

• pathname – A returned string for the generic path. The dictionary_name will
appear at the end of this path.

Return value A boolean indicating the result; true if the user selected a launch file, false if
the user clicked Cancel.

Comments The dialog box displays the dictionary_name in the File Name field. This
name appears as a reference only and shouldn’t be modified. The dialog
box is shown in the following illustration:

Once a location is specified and the user clicks OK, the returned pathname
includes the dictionary_name that initially appeared in the file dialog box.

You can add the pathname returned by this function to a launch file using
the Launch_WriteDictPath() function. This pathname is in a generic format
and must remain in this format when added to the launch file.

FUNCTION LIBRARY REFERENCE 281

L A U N C H _ S E L E C T D I C T ( )

Examples The following example displays a file dialog box, allowing the user to
choose a location for a dictionary. The new location is then saved to the
launch file using the Launch_WriteDictPath() function.

local string l_pathname;

local boolean l_result;

if Launch_SelectDict('Form_Dict_Name', l_pathname) then

{The user chose a dictionary location.}
'Form_Dic_Location' = l_pathname;
{Change the location of the forms dictionary in the launch file.}
l_result = Launch_WriteDictPath('Launch File', 'Product ID',
➥ 1, l_pathname, "MACINTOSH");
end if;

Related items Commands

getfile(), Launch_SelectFile(), Launch_ReadDictPath(), Launch_WriteDictPath()

282 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ S E L E C T F I L E ()

Launch_SelectFile()
Description The Launch_SelectFile() function displays an operating system dialog, in
which you can select a launch file.

Syntax Launch_SelectFile(pathname)

Parameters • pathname – A returned string containing the generic pathname to the

selected launch file.

Return value A boolean indicating the result; true if the user selected a launch file, false if
the user clicked Cancel.

Comments The *.SET will appear in the File of type field, and all launch files in the
current directory will be displayed in the dialog box.

Examples This example uses Launch_SelectFile() to display a dialog box. The launch
file returned by this function is then used in the Launch_GetFileInfo()
function to fill list fields:

local boolean l_result;

local string l_pathname;

if Launch_SelectFile(l_pathname) then
{The user chose a launch file.}
l_result = Launch_GetFileInfo(l_pathname, 'Product IDs',
➥ 'Products', 'Dictionary Location IDs');
end if;

Related items Commands

getfile(), Launch_GetFileName()

FUNCTION LIBRARY REFERENCE 283

L A U N C H _ W R I T E D I C T P A T H ( )

Launch_WriteDictPath()
Description The Launch_WriteDictPath() function writes the location of an application,
forms or reports dictionary to the launch file.

Syntax Launch_WriteDictPath(launch_file_location, product_ID, dictionary_type,

dictionary_path, dictionary_location_ID)

Parameters • launch_file_location – A string containing the full generic path to the launch
file, including the file name. Both the Launch_SelectFile() and
Launch_GetFileName() functions return the full path and name of a launch
file.

• product_ID – An integer indicating the product ID for the application,

forms, or reports dictionary pathname you want returned. You can return a
product ID using either the Launch_GetProdID() or the
Launch_GetFileInfo() functions.

• dictionary_type – An integer indicating the type of dictionary for which the

pathname is being returned. Use the following integer values:

Value Description
0 Application dictionary
1 Forms dictionary
2 Reports dictionary

• dictionary_path – A string indicating the pathname added to the launch file.

To change the existing path in the launch file, set this parameter to the path
returned by the Launch_SelectDict() function.

• dictionary_location_ID – A string indicating the dictionary location ID. This

can be returned using the Launch_GetFileInfo() function.

Return value The boolean value true.

284 F U N C T I O N L I B R A R Y R E F E R E N C E
 L A U N C H _ W R I T E D I C T P A T H ()

Comments If you choose to modify dictionary pathnames in the launch file, be aware
of the following:

• Modified pathnames written to the launch file will take effect only after
you restart the application.

• Be sure to move an application dictionary to its new location after

updating its path in the launch file. If an application dictionary isn’t
moved to the location specified in the launch file, your application will
be unable to launch with the runtime engine. If a forms or reports dic-
tionary isn’t moved to the location specified in the launch file, each will
be re-created in the specified location when you access the Modifier or
the Report Writer.

• Pathnames must be in a generic format when written to the launch file.

Be sure to convert any native pathnames to a generic format using the
Path_MakeGeneric() function prior to updating the launch file.

Examples This example displays a dialog box using the Launch_SelectDict() function.
The pathname returned by this function is then written to the launch file
using the Launch_WriteDictPath() function.

local string l_dictionary_name, l_pathname;

local boolean l_result;

if Launch_SelectDict(l_dictionary_name, l_pathname) then

{The user chose a dictionary file.}
{Write the selected location to the launch file.}
l_result = Launch_WriteDictPath('Current Launch File',
➥ 'Product ID', 1, l_pathname, 'Dictionary Location ID');
end if;

Related items Commands

Launch_SelectDict()

FUNCTION LIBRARY REFERENCE 285

286 F U N C T I O N L I B R A R Y R E F E R E N C E
 List view function library
Refer to Chapter 13,
“List View,” in Volume
2 of the Dexterity
Programmer’s Guide
for more information.
Use the functions in this library when adding list view fields to your
application. This library contains the following functions:
• ListView_ColumnAdd()
• ListView_ColumnCount()
• ListView_ColumnGetAlignment()
• ListView_ColumnGetLabel()
• ListView_ColumnGetPosition()
• ListView_ColumnGetSubitem()
• ListView_ColumnGetWidth()
• ListView_ColumnRemove()
• ListView_ColumnSetAlignment()
• ListView_ColumnSetLabel()
• ListView_ColumnSetPosition()
• ListView_ColumnSetWidth()
• ListView_GetClickItem()
• ListView_GetSortColumn()
• ListView_GetStringWidth()
• ListView_GetView()
• ListView_ItemAdd()
• ListView_ItemCount()
• ListView_ItemGetCurrencySubitem()
• ListView_ItemGetData()
• ListView_ItemGetDateSubitem()
• ListView_ItemGetImage()
• ListView_ItemGetIntSubitem()
• ListView_ItemGetLabel()
• ListView_ItemGetStateImage()
• ListView_ItemGetSubitem()
• ListView_ItemGetTimeSubitem()
• ListView_ItemMakeVisible()
• ListView_ItemRemove()
• ListView_ItemSetCurrencySubitem()
• ListView_ItemSetData()
• ListView_ItemSetDateSubitem()
• ListView_ItemSetImage()
• ListView_ItemSetIntSubitem()
• ListView_ItemSetLabel()
• ListView_ItemSetStateImage()
• ListView_ItemSetSubitem()
• ListView_ItemSetTimeSubitem()
FUNCTION LIBRARY REFERENCE 287
 • ListView_SelectionCount()
• ListView_SelectionGet()
• ListView_SelectionSet()
• ListView_SetEmptyMessage()
• ListView_SetSortColumn()
• ListView_SetView()
• ListView_Sort()

288 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ C O L U M N A D D ()

ListView_ColumnAdd()
Description The ListView_ColumnAdd() function adds a column to the list view field,
based on the data for the specified subitem.

Syntax ListView_ColumnAdd(list_view_field, column_name, subitem {, width}

{, alignment} {, position})

Parameters • list_view_field – The list view field to which a column is being added.

• column_name – A string containing the display name of the column. This

name will appear in the column heading when the ShowHeadings property
for the list view field is set to true and the list is displayed in report view
mode.

• subitem – An integer specifying the subitem whose data will be displayed in

the column. To add a column based on the item label, specify subitem 0 or
use the LV_ITEM_LABEL constant.

• width – An optional integer specifying the width of the column, measured

in pixels. If no value is supplied, the column will be wide enough to fully
display the column name. If you are adding a column that contains the icon
image for the item, include the constant LV_ICON_WIDTH to account for
the width of the image.

• alignment – An optional integer specifying how the data in the column will
be aligned. The value corresponds to one of the following constants:

Constant Description
LV_ALIGN_LEFT Items will be left-aligned.
LV_ALIGN_CENTER Items will be center-aligned.
LV_ALIGN_RIGHT Items will be right-aligned.

If no value is supplied, items will be left-aligned.

• position – An optional integer specifying the location of the new column.

The value 1 indicates the first column in the list. If no value is specified, the
column will be added at the end of the list.

Return value An integer containing the index of the new column. The value 1 indicates
the first column that was added to the list, 2 indicates the second column
that was added, and so on.

FUNCTION LIBRARY REFERENCE 289

L I S T V I E W _ C O L U M N A D D ( )

Comments If the list view field is shown in report view mode, add all of the items and
subitems before adding columns. This prevents the list view field from
flashing as items are added, because the items are shown only after
columns are added.

Examples The following example uses the ListView_ColumnAdd() function to add a

column to the Explorer List list view field, based on the item label. Notice
that subitem value 0 is used to specify the item label.

local integer column_index;

column_index = ListView_ColumnAdd('Explorer List' of window

➥ RESM_Explorer, "Address", 0);

The following example uses the ListView_ColumnAdd() function to add a

column to the Explorer List list view field, based on subitem 5, the asking
price. The none keyword is used to indicate that no value is being supplied
for the column width.

local integer column_index;

column_index = ListView_ColumnAdd('Explorer List' of window

➥ RESM_Explorer, "Asking Price", 5, none, LV_ALIGN_CENTER);

290 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ C O L U M N C O U N T ()

ListView_ColumnCount()
Description The ListView_ColumnCount() function retrieves the total number of
columns that have been added to a list view field.

Syntax ListView_ColumnCount(list_view_field)

Parameters • list_view_field – The list view field whose columns will be counted.

Return value An integer containing the total number of columns that have been added to
the list view field.

Examples The following example uses the ListView_ColumnCount() function to

retrieve the number of columns for the Explorer List list view field. Then
the ListView_ColumnSetWidth() function resizes each column to fully
display the items in the column.

local integer column_count;

local integer i;
local integer previous_width;

{Get the number of columns in the list.}

column_count = ListView_ColumnCount('Explorer List');

for i = 1 to column_count do
{Resize the column.}
previous_width = ListView_ColumnSetWidth('Explorer List', i,
➥ LV_AUTO_SIZE);
end for;

FUNCTION LIBRARY REFERENCE 291

L I S T V I E W _ C O L U M N G E T A L I G N M E N T ( )

ListView_ColumnGetAlignment()
Description The ListView_ColumnGetAlignment() function retrieves the alignment of
the specified column of a list view field.

Syntax ListView_ColumnGetAlignment(list_view_field, column_index)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose

alignment is being retrieved. The value 1 indicates the first column that was
added to the list view field.

Dragging a column to a different position in the list view does not affect the column
index.

Return value An integer value corresponding to one of the following constants:

Constant Description
LV_ALIGN_LEFT Items will be left-aligned.
LV_ALIGN_CENTER Items will be center-aligned.
LV_ALIGN_RIGHT Items will be right-aligned.

Examples The following example uses the ListView_ColumnGetAlignment()

function to retrieve the alignment of the second column that was added to
the Explorer List list view field.

local integer column_alignment;

column_alignment = ListView_ColumnGetAlignment('Explorer List', 2);

Related items Commands

ListView_ColumnSetAlignment()

292 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _C O L U M N G E T L A B E L ()

ListView_ColumnGetLabel()
Description The ListView_ColumnGetLabel() function retrieves the label of the
specified column of a list view field.

Syntax ListView_ColumnGetLabel(list_view_field, column_index)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose label is

being retrieved. The value 1 indicates the first column that was added to the
list view field.

Dragging a column to a different position in the list view does not affect the column
index.

Return value A string containing the column label.

Examples The following example uses the ListView_ColumnGetLabel() function to

retrieve the label of the second column that was added to the Explorer List
list view field.

local string column_label;

column_label = ListView_ColumnGetLabel('Explorer List', 2);

Related items Commands

ListView_ColumnSetLabel()

FUNCTION LIBRARY REFERENCE 293

L I S T V I E W _ C O L U M N G E T P O S I T I O N ( )

ListView_ColumnGetPosition()
Description The ListView_ColumnGetPosition() function retrieves the position of the
specified column of a list view field.

Syntax ListView_ColumnGetPosition(list_view_field, column_index)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose label is

being retrieved. The value 1 indicates the first column that was added to the
list view field.

Dragging a column to a different position in the list view does not affect the column
index.

Return value An integer containing the column position. The value 1 indicates the first
column in the list.

Examples The following example uses the ListView_ColumnGetPosition() function

to retrieve the position of the second column that was added to the Explorer
List list view field.

local integer column_position;

column_position = ListView_ColumnGetPosition('Explorer List', 2);

Related items Commands

ListView_ColumnSetPosition()

294 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ C O L U M N G E T S U B I T E M ()

ListView_ColumnGetSubitem()
Description The ListView_ColumnGetSubitem() function retrieves the number of the
subitem associated with the column.

Syntax ListView_ColumnGetSubitem(list_view_field, column_index)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose

subitem is being retrieved. The value 1 indicates the first column that was
added to the list view field.

Dragging a column to a different position in the list view does not affect the column
index.

Return value An integer indicating the subitem associated with the column.

Comments You can specify the subitem associated with a column only when you add
the column to the list view field. If you want to change the subitem
associated with a column, you must remove the column and then re-add it
based on the new subitem.

Examples The following example uses the ListView_ColumnGetSubitem() function

to retrieve the subitem associated with the first column added to the
Explorer List list view field.

local integer subitem;

subitem = ListView_ColumnGetSubitem('Explorer List', 1);

FUNCTION LIBRARY REFERENCE 295

L I S T V I E W _ C O L U M N G E T W I D T H ()

ListView_ColumnGetWidth()
Description The ListView_ColumnGetWidth() function retrieves the width, in pixels,
of the specified column.

Syntax ListView_ColumnGetWidth(list_view_field, column_index)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose width

is being retrieved. The value 1 indicates the first column that was added to
the list view field.

Dragging a column to a different position in the list view does not affect the column
index.

Return value An integer containing the width of the column in pixels.

Examples The following example uses the ListView_ColumnGetWidth() function to

retrieve the width of the first column added to the Explorer List list view
field.

local integer column_width;

column_width = ListView_ColumnGetWidth('Explorer List', 1);

Related items Commands

ListView_ColumnSetWidth()

296 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ C O L U M N R E M O V E ()

ListView_ColumnRemove()
Description The ListView_ColumnRemove() function removes the specified column
from a list view field.

Syntax ListView_ColumnRemove(list_view_field, column_index)

Parameters • list_view_field – The list view field from which a column is being removed.

• column_index – An integer specifying the index of the column that is being

removed. The value 1 indicates the first column that was added to the list
view field. To remove all columns from the list view field, specify the
constant LV_ALL.

Dragging a column to a different position in the list view does not affect the column
index.

Return value A boolean indicating whether the column was removed. True indicates the
column was removed, while false indicates it was not.

Comments When you remove a column, the column indexes for the remaining
columns may change. The column indexes greater than that of the column
removed will decrease by one. For example, the list view field in the
following illustration has six columns. Column four is removed.

Column index: 1 2 3 4 5 6

This column is
being removed.

The column whose column index was 5 now has the column index 4.
Likewise, the column whose index was 6 now has the column index 5.

Column index: 1 2 3 4 5

The column indexes for

these two columns have
decreased by one.

FUNCTION LIBRARY REFERENCE 297

L I S T V I E W _ C O L U M N R E M O V E ( )

Examples The following example uses the ListView_ColumnRemove() function to

remove all the columns from the Explorer List list view field.

local boolean result;

result = ListView_ColumnRemove('Explorer List', LV_ALL);

Related items Commands

ListView_ColumnAdd()

298 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _C O L U M N S E T A L I G N M E N T ()

ListView_ColumnSetAlignment()
Description The ListView_ColumnSetAlignment() function specifies the alignment of
a column in a list view field.

Syntax ListView_ColumnSetAlignment(list_view_field, column_index, alignment)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose

alignment is being set. The value 1 indicates the first column that was
added to the list view field.

Dragging a column to a different position in the list view does not affect the column
index.

• alignment – An integer corresponding to one of the following constants:

Constant Description
LV_ALIGN_LEFT Items will be left-aligned.
LV_ALIGN_CENTER Items will be center-aligned.
LV_ALIGN_RIGHT Items will be right-aligned.

Return value An integer value indicating the previous alignment of the column. The
value corresponds to one of the constants listed for the alignment parameter.

Examples The following example uses the ListView_ColumnSetAlignment()

function to make every column of the Explorer List list view field center-
aligned.
local integer column_count, i, previous_alignment;

{Get the number of columns in the list.}

column_count = ListView_ColumnCount('Explorer List');

for i = 1 to column_count do
{Set the column alignment.}
previous_alignment = ListView_ColumnSetAlignment('Explorer List',
➥ i, LV_ALIGN_CENTER);
end for;

Related items Commands

ListView_ColumnGetAlignment()

FUNCTION LIBRARY REFERENCE 299

L I S T V I E W _ C O L U M N S E T L A B E L ()

ListView_ColumnSetLabel()
Description The ListView_ColumnSetLabel() function sets the label of the specified
column of a list view field.

Syntax ListView_ColumnSetLabel(list_view_field, column_index, label)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose label is

being set. The value 1 indicates the first column that was added to the list
view field.

Dragging a column to a different position in the list view does not affect the column
index.

• label – A string specifying the label for the column.

Return value A boolean indicating whether the column label was changed. True indicates
the label was changed, while false indicates it was not.

Examples The following example uses the ListView_ColumnSetLabel() function to

set the label of the first column of the Explorer List list view field to
“Location”.

local boolean result;

result = ListView_ColumnSetLabel('Explorer List', 1, "Location");

Related items Commands

ListView_ColumnGetLabel()

300 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ C O L U M N S E T P O S I T I O N ()

ListView_ColumnSetPosition()
Description The ListView_ColumnSetPosition() function sets the position of the
specified column of a list view field.

Syntax ListView_ColumnSetPosition(list_view_field, column_index, position)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose

position is being set. The value 1 indicates the first column that was added
to the list view field.

Dragging a column to a different position in the list view does not affect the column
index.

• position – An integer specifying the position for the column. The value 1
indicates the first column in the list.

Return value An integer indicating the previous position of the column.

Comments Use the ListView_ColumnSetPosition() function to set all of the column

positions. Then use the redraw statement to update the appearance of the
list view field.

Examples The following example uses the ListView_ColumnSetPosition() function

to set the position of the second column that was added to the Explorer List
list view field to 4.

local integer prev_position;

prev_position = ListView_ColumnSetPosition('Explorer List', 2, 4);

redraw field 'Explorer List';

Related items Commands

ListView_ColumnGetPosition()

FUNCTION LIBRARY REFERENCE 301

L I S T V I E W _ C O L U M N S E T W I D T H ( )

ListView_ColumnSetWidth()
Description The ListView_ColumnSetWidth() function sets the width of the specified
column.

Syntax ListView_ColumnSetWidth(list_view_field, column_index, width)

Parameters • list_view_field – The list view field containing the specified column.

• column_index – An integer specifying the index of the column whose width

is being set. The value 1 indicates the first column that was added to the list
view field.

Dragging a column to a different position in the list view does not affect the column
index.

• width – An integer specifying the column width in pixels. If you are setting
the width of a column that contains the icon image or state image for the
item, include the constant LV_ICON_WIDTH to account for the width of
the image.

To automatically set the width of the column, use one of the following
constants:

Constant Description
LV_AUTO_SIZE Sets the width of the column so that the widest item in
the column will be fully displayed.
LV_AUTO_FIT This constant can be used only for the last column.
The column will be resized to fill the remaining space
in the list view field.

Return value An integer indicating the previous width of the column.

Examples The following example uses the ListView_ColumnSetWidth() function to

set the width of the first column of the Explorer List list view field. This
column contains the icon image for each item, so the LV_ICON_WIDTH
constant is included to account for the image width.

local integer previous_width;

previous_width = ListView_ColumnSetWidth('Explorer List', 1,

➥ 50 + LV_ICON_WIDTH);

302 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ C O L U M N S E T W I D T H ()

The following example uses the ListView_ColumnSetWidth() function to

automatically set the size of every column in the Explorer List list view
field. The last column is resized to fill the remaining space in the list view
field.

local integer column_count;

local integer i;
local integer previous_width;

{Get the number of columns in the list.}

column_count = ListView_ColumnCount('Explorer List');

for i = 1 to (column_count - 1) do
{Resize the column.}
previous_width = ListView_ColumnSetWidth('Explorer List', i,
➥ LV_AUTO_SIZE);
end for;

{Resize the last column.}

previous_width = ListView_ColumnSetWidth('Explorer List',
➥ column_count, LV_AUTO_FIT);

Related items Commands

ListView_ColumnGetWidth(), ListView_GetStringWidth()

FUNCTION LIBRARY REFERENCE 303

L I S T V I E W _ G E T C L I C K I T E M ( )

ListView_GetClickItem()
Description The ListView_GetClickItem() function returns the index of the item that
was most recently clicked.

Syntax ListView_GetClickItem(list_view_field {,column_index})

Parameters • list_view_field – The list view field containing the item that was clicked.

• column_index – An optional returned integer parameter containing the

column index of the column in which the user clicked. If the user did not
click in a column, the value 0 is returned.

Return value A long integer containing the index of the item that was clicked. The value
LV_INVALID is returned if no item was clicked.

Comments This function is typically used only in the state click script or double-click
script for a list view field. In those scripts, it retrieves the item index and
column index indicating where the user clicked.

Examples The following example is the state click script for the Explorer List list view
field. It uses the ListView_GetClickItem() function to find out which
item’s state image was clicked. The script then toggles the state image
between the checked and unchecked icons.

local long click_item;

local integer prev_image;

{Find which item's state image was clicked.}

click_item = ListView_GetClickItem('Explorer List');

{Get the current state image for the item.}

if ListView_ItemGetStateImage('Explorer List', click_item) = 1 then
{The clicked item is shown. Show the unclicked item.}
prev_image = ListView_ItemSetStateImage('Explorer List',
➥ click_item, 2);
else
{The unclicked item is shown. Show the clicked item.}
prev_image = ListView_ItemSetStateImage('Explorer List',
➥ click_item, 1);
end if;

304 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ G E T S O R T C O L U M N ()

ListView_GetSortColumn()
Description The ListView_GetSortColumn() function returns the index of the column
by which the list view field is being sorted. It also returns whether items in
the column are sorted in ascending or descending order.

Syntax ListView_GetSortColumn(list_view_field, sort_order)

Parameters • list_view_field – The list view field from which sorting information is being
retrieved.

• sort_order – An integer indicating how the column is sorted. The value

corresponds to one of the following constants:

Constant Description
LV_SORT_ASCENDING The column items are sorted in ascending order.
LV_SORT_DESCENDING The column items are sorted in descending order.

Return value An integer containing the index of the column by which the list view field is
being sorted.

Examples The following example uses the ListView_GetSortColumn() function to

retrieve sorting information from the Explorer List list view field. Then the
Defaults_Write() function writes the sorting information to the defaults
file.

local boolean result;

local integer sort_column, sort_mode;

{Get the sort column.}

sort_column = ListView_GetSortColumn('Explorer List' of window
➥ RESM_Explorer, sort_mode);

{Write the items to the defaults file.}

result = Defaults_Write("ExpSortCol", str(sort_column));
result = Defaults_Write("ExpSortMode", str(sort_mode));

Related items Commands

ListView_SetSortColumn()

FUNCTION LIBRARY REFERENCE 305

L I S T V I E W _ G E T S T R I N G W I D T H ( )

ListView_GetStringWidth()
Description The ListView_GetStringWidth() function returns the number of pixels
required to fully display a string in the current font of a specified list view
field.

Syntax ListView_GetStringWidth(list_view_field, string)

Parameters • list_view_field – The list view field in which the string will be displayed.

• string – The string whose width is being returned.

Return value An integer containing the number of pixels required to fully display the
string.

Comments This function is typically used to find out whether a specific string will fit in
a column of a list view field. If necessary, use the
ListView_ColumnSetWidth() function to change the width of a column to
display the string without truncating.

Examples The following example uses the ListView_GetStringWidth() function to

find out the width of a string that will be used as a column heading in the
Explorer List list view field. Then the column width is set to the appropriate
value, based on the string width.

local integer string_width;

local integer previous_width;

{Find out the new string width}

string_width = ListView_GetStringWidth('Explorer List', "Location");

{Set the width of the column.}

previous_width = ListView_ColumnSetWidth('Explorer List', 1,
➥ string_width);

306 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ G E T V I E W ()

ListView_GetView()
Description The ListView_GetView() function retrieves the current view mode for the
specified list view field.

Syntax ListView_GetView(list_view_field)

Parameters • list_view_field – The list view field for which the view mode is being
returned.

Return value An integer corresponding to one of the following constants:

Constant Description
LV_SMICON_VIEW Small icon view
LV_LGICON_VIEW Large icon view
LV_LIST_VIEW List view
LV_REPORT_VIEW Report view

Examples The following example uses the ListView_GetView() function to retrieve

view mode information from the Explorer List list view field. Then the
Defaults_Write() function writes the information to the defaults file.

local integer view_mode;

local boolean result;

{Get the current view mode.}

view_mode = ListView_GetView('Explorer List');

{Write the item to the defaults file}

result = Defaults_Write("ExpMode", str(view_mode));

Related items Commands

ListView_SetView()

FUNCTION LIBRARY REFERENCE 307

L I S T V I E W _ I T E M A D D ()

ListView_ItemAdd()
Description The ListView_ItemAdd() function adds an item to a list view field.

Syntax ListView_ItemAdd(list_view_field, label, data {, image}{, state_image})

Parameters • list_view_field – The list view field to which a new item is being added.

• label – A string specifying the text that will appear with the item.

• data – A long integer specifying the data value to associate with the item.

• image – An optional integer specifying the picture to display with the item.
The value corresponds to the item number of an item image listed in the
ListView Images window.

• state_image – An optional integer specifying the state image to display with

the item when the list view is shown in report view mode. The value
corresponds to the item number of a state image listed in the ListView
Images window.

Return value A long integer containing the index of the new list view item.

Comments Be aware that the index of an item may change. For example, when the list
is re-sorted, a list view item may appear in a different location in the list.
Thus, its index value will have changed.

Each new item is added to the bottom of the list, regardless of the sorting
option specified for the list view field. After adding new list view items,
you can use the ListView_Sort() function to re-sort the entire list.

To add subitems to the list view item, use the ListView_ItemSetSubitem()

function.

Examples The following example uses the ListView_ItemAdd() function to add items
from the Seller Data table to the Explorer List list view field. Then the
ListView_ItemSetSubitem() function is used to set the subitems for the
new list view item. Finally, the ListView_ColumnAdd() function is used to
add the columns to the list.

308 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M A D D ()

local long seller_count, i;

local integer column_index;
local boolean result;

{Find out how many items to add}

seller_count = countrecords(table Seller_Data);

{Add a list item and subitems for each seller.}

get first table Seller_Data;
for i = 1 to seller_count do
{Add the item. The second icon and state image are displayed for
each item.}
item_index = ListView_ItemAdd('Explorer List' of window
➥ RESM_Explorer, 'Seller First Name' of table Seller_Data +
➥ " " + 'Seller Last Name' of table Seller_Data, 0, 2, 2);
{Now add the subitems.}
result = ListView_ItemSetSubitem('Explorer List' of window
➥ RESM_Explorer, item_index, 1, 'Seller ID' of table Seller_Data);
result = ListView_ItemSetSubitem('Explorer List' of window
➥ RESM_Explorer, item_index, 2, 'Address' of table Seller_Data);
result = ListView_ItemSetSubitem('Explorer List' of window
➥ RESM_Explorer, item_index, 3, 'City' of table Seller_Data);
result = ListView_ItemSetSubitem('Explorer List' of window
➥ RESM_Explorer, item_index, 4, 'State' of table Seller_Data);
get next table Seller_Data;
end for;

{Add the columns for the list.}

column_index = ListView_ColumnAdd('Explorer List' of window
➥ RESM_Explorer, "Name", 0);
column_index = ListView_ColumnAdd('Explorer List' of window
➥ RESM_Explorer, "ID", 1);
column_index = ListView_ColumnAdd('Explorer List' of window
➥ RESM_Explorer, "Address", 2);
column_index = ListView_ColumnAdd('Explorer List' of window
➥ RESM_Explorer, "City", 3);
column_index = ListView_ColumnAdd('Explorer List' of window
➥ RESM_Explorer, "State", 4);

Related items Commands

ListView_ColumnAdd(), ListView_ItemRemove(), ListView_ItemSetSubitem(),
ListView_Sort()

FUNCTION LIBRARY REFERENCE 309

L I S T V I E W _ I T E M C O U N T ( )

ListView_ItemCount()
Description The ListView_ItemCount() function retrieves the number of items
currently in a list view field.

Syntax ListView_ItemCount(list_view_field)

Parameters • list_view_field – The list view field whose items are being counted.

Return value A long integer containing the number of items in the list view field.

Examples The following example uses the ListView_ItemCount() function to retrieve

the number of items in the Explorer List list view field.

local long item_count;

item_count = ListView_ItemCount('Explorer List');

310 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M G E T C U R R E N C Y S U B I T E M ()

ListView_ItemGetCurrencySubitem()
Description The ListView_ItemGetCurrencySubitem() function retrieves a currency or
variable currency value from the additional component of a subitem.

Syntax ListView_ItemGetCurrencySubitem(list_view_field, item_index, subitem)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item from which a
currency subitem is being retrieved.

• subitem – An integer specifying the subitem to retrieve from. To retrieve the

additional component associated with the label of a list view item, specify 0
as the subitem to retrieve from.

Return value A currency or variable currency value containing the subitem.

Examples The following example uses the ListView_ItemGetCurrencySubitem()

function to retrieve the currency value from subitem 1 of the item currently
selected in the Explorer List list view field.

local currency currency_value;

local long selected_item;

selected_item = ListView_SelectionGet('Explorer List', 1);

currency_value = ListView_ItemGetCurrencySubitem('Explorer List',
selected_item, 1);

Related items Commands

ListView_ItemSetCurrencySubitem()

FUNCTION LIBRARY REFERENCE 311

L I S T V I E W _ I T E M G E T D A T A ( )

ListView_ItemGetData()
Description The ListView_ItemGetData() function retrieves the long integer data item
associated with the specified list view item.

Syntax ListView_ItemGetData(list_view_field, item_index)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose data item is
being retrieved.

Return value A long integer containing the data item for the specified list view item.

Examples The following example uses the ListView_ItemGetData() function to

retrieve the data item from the first item in the Explorer List list view field.

local long data_item;

data_item = ListView_ItemGetData('Explorer List', 1);

Related items Commands

ListView_ItemSetData()

312 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M G E T D A T E S U B I T E M ()

ListView_ItemGetDateSubitem()
Description The ListView_ItemGetDateSubitem() function retrieves a date value from
the additional component of a subitem.

Syntax ListView_ItemGetDateSubitem(list_view_field, item_index, subitem)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item from which a date
subitem is being retrieved.

• subitem – An integer specifying the subitem to retrieve from. To retrieve the

additional component associated with the label of a list view item, specify 0
as the subitem to retrieve from.

Return value A date value containing the subitem.

Examples The following example uses the ListView_ItemGetDateSubitem() function

to retrieve the date value from subitem 6 of the item currently selected in
the Explorer List list view field.

local date date_value;

local long selected_item;

selected_item = ListView_SelectionGet('Explorer List', 1);

date_value = ListView_ItemGetDateSubitem('Explorer List',
selected_item, 6);

Related items Commands

ListView_ItemSetDateSubitem()

FUNCTION LIBRARY REFERENCE 313

L I S T V I E W _ I T E M G E T I M A G E ()

ListView_ItemGetImage()
Description The ListView_ItemGetImage() function retrieves the item numbers of the
images associated with the specified list view item.

Syntax ListView_ItemGetImage(list_view_field, item_index {, overlay_image})

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose image item
number is being retrieved.

• overlay_image – A long integer indicating the overlay image. This value

corresponds to the item number of an item image in the ListView Images
window. If no overlay image is associated with the item, the LV_NOIMAGE
constant is returned.

Return value An integer indicating the image. This value corresponds to the item number
of an item image listed in the ListView Images window. If no image is
associated with the item, the LV_NOIMAGE constant is returned.

Examples The following example uses the ListView_ItemGetImage() function to

retrieve the image item number from the first item in the Explorer List list
view field.

local long image_item;

image_item = ListView_ItemGetImage('Explorer List', 1);

Related items Commands

ListView_ItemSetImage()

314 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M G E T I N T S U B I T E M ()

ListView_ItemGetIntSubitem()
Description The ListView_ItemGetIntSubitem() function retrieves an integer or long
integer value from the additional component of a subitem.

Syntax ListView_ItemGetIntSubitem(list_view_field, item_index, subitem)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item from which an
integer or long integer subitem is being retrieved.

• subitem – An integer specifying the subitem to retrieve from. To retrieve the

additional component associated with the label of a list view item, specify 0
as the subitem to retrieve from.

Return value An integer or long integer value containing the subitem.

Examples The following example uses the ListView_ItemGetIntSubitem() function

to retrieve the integer value from subitem 6 of the item currently selected in
the Explorer List list view field.

local integer int_value;

local long selected_item;

selected_item = ListView_SelectionGet('Explorer List', 1);

int_value = ListView_ItemGetIntSubitem('Explorer List',
selected_item, 6);

Related items Commands

ListView_ItemSetIntSubitem()

FUNCTION LIBRARY REFERENCE 315

L I S T V I E W _ I T E M G E T L A B E L ( )

ListView_ItemGetLabel()
Description The ListView_ItemGetLabel() function retrieves the label of the specified
list view item.

Syntax ListView_ItemGetLabel(list_view_field, item_index)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose label is
being retrieved.

Return value A string containing the label of the specified item.

Examples The following example uses the ListView_ItemGetLabel() function to

retrieve the label of the first item selected in the Explorer List list view field.

local long selected_item;

local string item_label;

{Retrieve the selected item.}

selected_item = ListView_SelectionGet('Explorer List');

if selected_item <> LV_INVALID then

item_label = ListView_ItemGetLabel('Explorer List',
➥ selected_item);
end if;

Related items Commands

ListView_ItemSetLabel()

316 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _I T E M G E T S T A T E I M A G E ()

ListView_ItemGetStateImage()
Description The ListView_ItemGetStateImage() function retrieves the item number of
the state image associated with the specified list view item.

Syntax ListView_ItemGetStateImage(list_view_field, item_index)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose state image
item number is being retrieved.

Return value An integer indicating the image. This value corresponds to the item number
of a state image listed in the ListView Images window. If no state image is
associated with the item, the LV_NOIMAGE constant is returned.

Examples The following example is the state click script for the Explorer List list view
field. It uses the ListView_GetStateImage() function to find out which state
image is displayed for the item the user clicked. Then the state image is
toggled between the checked and unchecked icon.

local long click_item;

local integer prev_image;

{Find which item's state image was clicked.}

click_item = ListView_GetClickItem('Explorer List');

{Get the current state image for the item.}

if ListView_ItemGetStateImage('Explorer List', click_item) = 1 then
{The clicked item is shown. Show the unclicked item.}
prev_image = ListView_ItemSetStateImage('Explorer List',
➥ click_item, 2);
else
{The unclicked item is shown. Show the clicked item.}
prev_image = ListView_ItemSetStateImage('Explorer List',
➥ click_item, 1);
end if;

Related items Commands

ListView_ItemSetStateImage()

FUNCTION LIBRARY REFERENCE 317

L I S T V I E W _ I T E M G E T S U B I T E M ( )

ListView_ItemGetSubitem()
Description The ListView_ItemGetSubitem() function retrieves a subitem from the
specified list view item.

Syntax ListView_ItemGetSubitem(list_view_field, item_index, subitem)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item from which a
subitem is being retrieved.

• subitem – An integer specifying the subitem to retrieve.

Return value A string containing the subitem.

Comments You can use the ListView_ItemGetSubitem() function to retrieve the label
of a list view item by specifying 0 or the constant LV_ITEM_LABEL as the
subitem to retrieve.

Examples The following example uses the ListView_ItemGetSubitem() function to

retrieve the first subitem of the selected item in the Explorer List list view
field. The value retrieved, the Buyer ID, is used to display information for
the selected buyer.
local long item_index;
local string item_ID;
local boolean result;

{Get the first item that is selected.}

item_index = ListView_SelectionGet('Explorer List');

if item_index <> LV_INVALID then

{Get the ID of the buyer.}
item_ID = ListView_ItemGetSubitem('Explorer List', item_index, 1);

{Display the item in the Buyers window.}

open form Buyers;
result = Window_PullFocus(window Buyers of form Buyers);
set 'Buyer ID' of window Buyers of form Buyers to item_ID;
run script 'Buyer ID' of window Buyers of form Buyers;
end if;

Related items Commands

ListView_ItemSetData()

318 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M G E T T I M E S U B I T E M ()

ListView_ItemGetTimeSubitem()
Description The ListView_ItemGetTimeSubitem() function retrieves a time value from
the additional component of a subitem.

Syntax ListView_ItemGetTimeSubitem(list_view_field, item_index, subitem)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item from which a time
subitem is being retrieved.

• subitem – An integer specifying the subitem to retrieve from. To retrieve the

additional component associated with the label of a list view item, specify 0
as the subitem to retrieve from.

Return value A time value containing the subitem.

Examples The following example uses the ListView_ItemGetTimeSubitem()

function to retrieve the time value from subitem 6 of the item currently
selected in the Explorer List list view field.

local time time_value;

local long selected_item;

selected_item = ListView_SelectionGet('Explorer List', 1);

time_value = ListView_ItemGetTimeSubitem('Explorer List',
➥ selected_item, 6);

Related items Commands

ListView_ItemSetTimeSubitem()

FUNCTION LIBRARY REFERENCE 319

L I S T V I E W _ I T E M M A K E V I S I B L E ()

ListView_ItemMakeVisible()
Description The ListView_ItemMakeVisible() function makes the specified item in a
list view field visible. If necessary, the contents of the list view field will be
scrolled to make the specified item visible.

Syntax ListView_ItemMakeVisible(list_view_field, item_index)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item to make visible.

Return value A boolean indicating whether the item was made visible. True indicates the
item was made visible, while false indicates it was not.

Comments Making an item visible does not select the item. To select the item, use
ListView_SelectionSet().

Examples The following example uses the ListView_ItemMakeVisible() function to

make the currently-selected item in the Explorer List list view field visible.

local long item_index;

local boolean result;

{Get the first item that is selected.}

item_index = ListView_SelectionGet('Explorer List');

if item_index <> LV_INVALID then

{Make the selected item visible.}
result = ListView_ItemMakeVisible('Explorer List', item_index);
end if;

Related items Commands

ListView_SelectionSet()

320 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M R E M O V E ()

ListView_ItemRemove()
Description The ListView_ItemRemove() function removes the specified item from a
list view field.

Syntax ListView_ItemRemove(list_view_field, item_index)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item to remove. To

remove all items from the list view field, specify the constant LV_ALL.

Return value A boolean indicating whether the item was removed. True indicates the
item was removed, while false indicates it was not.

Comments When an item is removed from a list view field, all of its subitems are
removed as well.

Examples The following example uses the ListView_ItemRemove() function to

remove all items from the Explorer List list view field.

local boolean result;

result = ListView_ItemRemove('Explorer List', LV_ALL);

Related items Commands

ListView_ItemAdd()

FUNCTION LIBRARY REFERENCE 321

L I S T V I E W _ I T E M S E T C U R R E N C Y S U B I T E M ( )

ListView_ItemSetCurrencySubitem()
Description The ListView_ItemSetCurrencySubitem() function sets the value of the
additional component of a subitem to a currency or variable currency value.

Syntax ListView_ItemSetCurrencySubitem(list_view_field, item_index, subitem,

value)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item for which a
currency or variable currency subitem is being set.

• subitem – An integer specifying the subitem to set. You can set the
additional component for the label of a list view item by by specifying 0 as
the subitem to set.

• value – A currency or variable currency containing the new value.

Return value A boolean indicating whether the subitem was set. True indicates the
subitem was set, while false indicates it was not.

Comments Each subitem of a list view item can have a string , which is shown when
the list view is displayed in report view mode. A subitem can also have a
currency, integer, date, or time component that stores a value to be used for
sorting the contents of the list.

By default, a list view will use the string component of a subitem when
sorting a column in the list view. The list view items will be sorted in ASCII
order, which may not be appropriate if the column contains currency,
integer, date or time values. If the subitems in the column have currency,
integer, date or time components, those will be used to sort the list, rather
than the string values.

If a subitem has a currency, integer, date or time component, but no string

component, the currency, integer, date or time component will be displayed
in report view mode.

322 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M S E T C U R R E N C Y S U B I T E M ()

Examples The following example uses the ListView_ItemSetCurrencySubitem()

function to add a currency subitem for the Asking Price column of the list
view. Notice that the ListView_ItemSetSubitem() function is used to add a
string value for the value that will be displayed in the
Asking Price column. The currency value added by the
ListView_ItemSetCurrencySubitem() function will be used when the list
view is sorted based on the Asking Price column.

local long house_count;

local long item_index;
local integer column_index, j;
local long i;
local boolean result;
local integer item_width, prev_image, column_width[10]; {Assume a
maximum of ten columns in list.}

{Add Houses to the Explorer list}

{Find out how many items to add}

house_count = countrecords(table House_Data);

{Clear out the list.}

result = ListView_ItemRemove(Explorer_List of window RESM_Explorer,
➥ LV_ALL);

{Delete any existing columns in the list.}

result = ListView_ColumnRemove(Explorer_List of window RESM_Explorer,
➥ LV_ALL);

{Add a list item and subitems for each buyer.}

get first table House_Data;
for i = 1 to house_count do
{Add the item}
item_index = ListView_ItemAdd(Explorer_List of window
➥ RESM_Explorer, 'Address' of table House_Data, 0, 3, 2);

{Now add the subitems}

result = ListView_ItemSetSubitem(Explorer_List of window
➥ RESM_Explorer, item_index, 1, itemname('House Type' of window
➥ RESM_Explorer,'House Type' of table House_Data));

FUNCTION LIBRARY REFERENCE 323

L I S T V I E W _ I T E M S E T C U R R E N C Y S U B I T E M ( )

{Add an integer subitem so the House ID will sort numerically.}

result = ListView_ItemSetSubitem(Explorer_List of window
➥ RESM_Explorer, item_index, 2, 'House ID' of table House_Data);
result = ListView_ItemSetIntSubitem(Explorer_List of window
➥ RESM_Explorer, item_index, 2, integer(value('House ID' of
➥ table House_Data)));

result = ListView_ItemSetSubitem(Explorer_List of window

➥ RESM_Explorer, item_index, 3, 'City' of table House_Data);
result = ListView_ItemSetSubitem(Explorer_List of window
➥ RESM_Explorer, item_index, 4, 'State' of table House_Data);

{Add a currency subitem so the Asking Price will sort

➥ numerically.}
result = ListView_ItemSetSubitem(Explorer_List of window
➥ RESM_Explorer, item_index, 5, format('Asking Price' of table
➥ House_Data, true, true, 2, SYSTEMNEG));
result = ListView_ItemSetCurrencySubitem(Explorer_List of window
➥ RESM_Explorer, item_index, 5, 'Asking Price' of table
➥ House_Data);

{Find out how wide the items are that were added.}
for j = 1 to 6 do
item_width = ListView_GetStringWidth(Explorer_List of window
➥ RESM_Explorer, ListView_ItemGetSubitem(Explorer_List of
➥ window RESM_Explorer, item_index, j-1));
if item_width > column_width[j] then
column_width[j] = item_width;
end if;
end for;

{Find out whether the house has been sold. If so, set the
➥ appropriate state image.}
if Sold of table House_Data = true then
prev_image = ListView_ItemSetImage(Explorer_List of window
➥ RESM_Explorer of form RESM_Explorer, item_index, 3, 4);
end if;

get next table House_Data;

end for;

324 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M S E T C U R R E N C Y S U B I T E M ()

{Add the columns for the list.}

column_index = ListView_ColumnAdd(Explorer_List of window
➥ RESM_Explorer, "Address", 0, max(column_width[1],
➥ ListView_GetStringWidth(Explorer_List of window RESM_Explorer,
➥ "Address")) +LV_ICON_WIDTH);
column_index = ListView_ColumnAdd(Explorer_List of window
➥ RESM_Explorer, "Type", 1, max(column_width[2],
➥ ListView_GetStringWidth(Explorer_List of window
➥ RESM_Explorer,"Type")));
column_index = ListView_ColumnAdd(Explorer_List of window
➥ RESM_Explorer, "ID", 2, max(column_width[3],
➥ ListView_GetStringWidth(Explorer_List of window
➥ RESM_Explorer,"ID")));
column_index = ListView_ColumnAdd(Explorer_List of window
➥ RESM_Explorer, "City", 3, max(column_width[4],
➥ ListView_GetStringWidth(Explorer_List of window
➥ RESM_Explorer,"City")));
column_index = ListView_ColumnAdd(Explorer_List of window
➥ RESM_Explorer, "State", 4, max(column_width[5],
➥ ListView_GetStringWidth(Explorer_List of window
➥ RESM_Explorer,"State")));
column_index = ListView_ColumnAdd(Explorer_List of window
➥ RESM_Explorer, "Asking Price", 5, max(column_width[6],
➥ ListView_GetStringWidth(Explorer_List of window
➥ RESM_Explorer,"Asking Price")));

{Force the items to be sorted.}

result = ListView_Sort(Explorer_List of window RESM_Explorer);

Related items Commands

ListView_ItemGetCurrencySubitem()

FUNCTION LIBRARY REFERENCE 325

L I S T V I E W _ I T E M S E T D A T A ( )

ListView_ItemSetData()
Description The ListView_ItemSetData() function sets the data item associated with
the specified list view item.

Syntax ListView_ItemSetData(list_view_field, item_index, item_data)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose data item is
being set.

• item_data – A long integer containing the data item.

Return value A long integer containing the previous data item for the specified list view
item.

Examples The following example uses the ListView_ItemSetData() function to set the
data item of every item in the Explorer List list view field to -1.

local long item_count;

local long i;
local long previous_value;

{Get the number of items in the list.}

item_count = ListView_ItemCount('Explorer List');

for i = 1 to item_count do
{Set the data value to -1.}
previous_value = ListView_ItemSetData('Explorer List', i, -1);
end for;

Related items Commands

ListView_ItemGetData()

326 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M S E T D A T E S U B I T E M ()

ListView_ItemSetDateSubitem()
Description The ListView_ItemSetDateSubitem() function sets the value of the
additional component of a subitem to a date value.

Syntax ListView_ItemSetDateSubitem(list_view_field, item_index, subitem, value)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item for which a date
subitem is being set.

• subitem – An integer specifying the subitem to set. You can set the
additional component for the label of a list view item by by specifying 0 as
the subitem to set.

• value – A date containing the new date value.

Return value A boolean indicating whether the subitem was set. True indicates the
subitem was set, while false indicates it was not.

Comments Each subitem of a list view item can have a string , which is shown when
the list view is displayed in report view mode. A subitem can also have a
currency, integer, date, or time component that stores a value to be used for
sorting the contents of the list.

By default, a list view will use the string component of a subitem when
sorting a column in the list view. The list view items will be sorted in ASCII
order, which may not be appropriate if the column contains currency,
integer, date or time values. If the subitems in the column have currency,
integer, date or time components, those will be used to sort the list, rather
than the string values.

If a subitem has a currency, integer, date or time component, but no string

component, the currency, integer, date or time component will be displayed
in report view mode.

Examples Refer to the example for ListView_ItemSetCurrencySubitem() to see how

an additional component of a subitem can be used to control how the list
view is sorted.

Related items Commands

ListView_ItemGetDateSubitem()

FUNCTION LIBRARY REFERENCE 327

L I S T V I E W _ I T E M S E T I M A G E ()

ListView_ItemSetImage()
Description The ListView_ItemSetImage() function sets the item image associated with
the specified list view item.

Syntax ListView_ItemSetImage(list_view_field, item_index, image {, overlay_image})

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose item image
is being set.

• image – An integer specifying the image to use. The value corresponds to

the item number of an item image listed in the ListView Images window. If
no image will be displayed, use the LV_NOIMAGE constant.

• overlay_image – An optional integer specifying the image to use as the

overlay image. The value corresponds to the item number of an item image
listed in the ListView Images window.

Return value An integer containing the item number of the previous item image for the
specified list view item. If no item image was associated with the list view
item, the constant LV_NOIMAGE is returned.

Examples The following example uses the ListView_ItemSetImage() function to

make every item in the Explorer List list view field not display an image.

local long item_count;

local long i;
local integer previous_image;

{Get the number of items in the list.}

item_count = ListView_ItemCount('Explorer List');

for i = 1 to item_count do
{Set the image to LV_NOIMAGE.}
previous_image = ListView_ItemSetImage('Explorer List', i,
➥ LV_NOIMAGE);
end for;

Related items Commands

ListView_ItemGetImage()

328 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M S E T I N T S U B I T E M ()

ListView_ItemSetIntSubitem()
Description The ListView_ItemSetIntSubitem() function sets the value of the
additional component of a subitem to an integer or long integer value.

Syntax ListView_ItemSetIntSubitem(list_view_field, item_index, subitem, value)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item for which an
integer or long integer subitem is being set.

• subitem – An integer specifying the subitem to set. You can set the
additional component for the label of a list view item by by specifying 0 as
the subitem to set.

• value – An integer or long integer containing the new value.

Return value A boolean indicating whether the subitem was set. True indicates the
subitem was set, while false indicates it was not.

Comments Each subitem of a list view item can have a string , which is shown when
the list view is displayed in report view mode. A subitem can also have a
currency, integer, date, or time component that stores a value to be used for
sorting the contents of the list.

By default, a list view will use the string component of a subitem when
sorting a column in the list view. The list view items will be sorted in ASCII
order, which may not be appropriate if the column contains currency,
integer, date or time values. If the subitems in the column have currency,
integer, date or time components, those will be used to sort the list, rather
than the string values.

If a subitem has a currency, integer, date or time component, but no string

component, the currency, integer, date or time component will be displayed
in report view mode.

Examples Refer to the example for ListView_ItemSetCurrencySubitem() to see how

an additional component of a subitem can be used to control how the list
view is sorted.

Related items Commands

ListView_ItemGetIntSubitem()

FUNCTION LIBRARY REFERENCE 329

L I S T V I E W _ I T E M S E T L A B E L ( )

ListView_ItemSetLabel()
Description The ListView_ItemSetLabel() function sets the label of the specified list
view item.

Syntax ListView_ItemSetLabel(list_view_field, item_index, label)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose label is
being set.

• label – A string containing the new label.

Return value A boolean indicating whether the item label was changed. True indicates
the label was changed, while false indicates it was not.

Examples The following example uses the ListView_ItemSetImage() function to set

the label of the first item selected in the Explorer List list view field.

local long selected_item;

local string new_label;
local boolean result;

{Retrieve the selected item.}

selected_item = ListView_SelectionGet('Explorer List');

if selected_item <> LV_INVALID then

{Ask the user to enter a new label.}
if getstring("Enter a new label", false, new_label) = true then
{Set the new label.}
result = ListView_ItemSetLabel('Explorer List',
➥ selected_item, new_label);
end if;
end if;

Related items Commands

ListView_ItemGetLabel()

330 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M S E T S T A T E I M A G E ()

ListView_ItemSetStateImage()
Description The ListView_ItemSetStateImage() function sets the state image associated
with the specified list view item.

Syntax ListView_ItemSetStateImage(list_view_field, item_index, image)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item whose state image
is being set.

• image – An integer specifying the image to use. The value corresponds to

the item number of a state image listed in the ListView Images window. If
no image will be displayed, use the LV_NOIMAGE constant.

Return value An integer containing the item number of the previous state image for the
specified list view item. If no state image was associated with the list view
item, the constant LV_NOIMAGE is returned.

Examples The following example is the state click script for the Explorer List list view
field. The ListView_ItemSetStateImage() function toggles the state image
between the checked and unchecked icon.

local long click_item;

local integer prev_image;

{Find which item's state image was clicked.}

click_item = ListView_GetClickItem(Explorer_List);

{Get the current state image for the item.}

if ListView_ItemGetStateImage(Explorer_List, click_item) = 1 then
{The clicked item is shown. Show the unclicked item.}
prev_image = ListView_ItemSetStateImage(Explorer_List,
➥ click_item, 2);
else
{The unclicked item is shown. Show the clicked item.}
prev_image = ListView_ItemSetStateImage(Explorer_List,
➥ click_item, 1);
end if;

Related items Commands

ListView_ItemGetStateImage()

FUNCTION LIBRARY REFERENCE 331

L I S T V I E W _ I T E M S E T S U B I T E M ( )

ListView_ItemSetSubitem()
Description The ListView_ItemSetSubitem() function sets the value of a subitem for
the specified list view item.

Syntax ListView_ItemSetSubitem(list_view_field, item_index, subitem, value)

Parameters • list_view_field – The list view field containing the specified item.

• item_index – A long integer specifying the list view item for which a subitem
is being set.

• subitem – An integer specifying the subitem to set.

• value – A string containing the new subitem.

Return value A boolean indicating whether the subitem was set. True indicates the
subitem was set, while false indicates it was not.

Comments You can use the ListView_ItemSetSubitem() function to set the label of a
list view item by specifying 0 or the constant LV_ITEM_LABEL as the
subitem to set.

Examples Refer to the example for ListView_ItemAdd().

Related items Commands

ListView_ItemGetSubitem()

332 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ I T E M S E T T I M E S U B I T E M ()

ListView_ItemSetTimeSubitem()
Description The ListView_ItemSetTimeSubitem() function sets the value of the
additional component of a subitem to a time value.

Syntax ListView_ItemSetTimeSubitem(list_view_field, item_index, subitem, value)

Parameters • list_view_field – The list view containing the specified item.

• item_index – A long integer specifying the list view item for which a time
subitem is being set.

• subitem – An integer specifying the subitem to set. You can set the
additional component for the label of a list view item by by specifying 0 as
the subitem to set.

• value – A time containing the new time value.

Return value A boolean indicating whether the subitem was set. True indicates the
subitem was set, while false indicates it was not.

Comments Each subitem of a list view item can have a string , which is shown when
the list view is displayed in report view mode. A subitem can also have a
currency, integer, date, or time component that stores a value to be used for
sorting the contents of the list.

By default, a list view will use the string component of a subitem when
sorting a column in the list view. The list view items will be sorted in ASCII
order, which may not be appropriate if the column contains currency,
integer, date or time values. If the subitems in the column have currency,
integer, date or time components, those will be used to sort the list, rather
than the string values.

If a subitem has a currency, integer, date or time component, but no string

component, the currency, integer, date or time component will be displayed
in report view mode.

Examples Refer to the example for ListView_ItemSetCurrencySubitem() to see how

an additional component of a subitem can be used to control how the list
view is sorted.

Related items Commands

ListView_ItemGetTimeSubitem()

FUNCTION LIBRARY REFERENCE 333

L I S T V I E W _ S E L E C T I O N C O U N T ( )

ListView_SelectionCount()
Description The ListView_SelectionCount() function retrieves the number of items
currently selected in a list view field.

Syntax ListView_SelectionCount(list_view_field)

Parameters • list_view_field – The list view field for which the selection count is being
returned.

Return value A long integer containing the number of items that are selected.

Examples The following example uses the ListView_SelectionCount() function to

retrieve the number of items selected in the Explorer List list view field. The
ListView_SelectionGet() function retrieves each item in the selection. Then
the Buyers report is printed based on the item.

local long selection_count, item_index, i;

local string item_ID;

{Retrieve the number of items selected.}

selection_count = ListView_SelectionCount('Explorer List');

if selection_count > 0 then

{Print the selected items.}
for i = 1 to selection_count do
{Get the index of the next selected node.}
item_index = ListView_SelectionGet('Explorer List', i);
item_ID = ListView_ItemGetSubitem('Explorer List', item_index,
➥ 1);
{Print the report.}
run report 'Buyer Report' with restriction 'Buyer ID' of table
➥ Buyer_Data = item_ID destination true, false;
end for;
else
{No items selected to print.}
warning "No item selected to print.";
end if;

Related items Commands

ListView_SelectionGet()

334 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ S E L E C T I O N G E T ()

ListView_SelectionGet()
Description The ListView_SelectionGet() function retrieves the item index of the
specified item in the selection.

Syntax ListView_SelectionGet(list_view_field {, offset})

Parameters • list_view_field – The list view field for which the selection count is being
returned.

• offset – An optional long integer that specifies which item in the selection
will be returned. The value 1 indicates the first item in the selection, 2 the
second item, and so on. If this parameter is not included, the first item in the
selection is returned.

This parameter should be used only for list view fields that have the MultiSel
property set to true.

Return value A long integer containing the item index of the specified item in the
selection.

Examples Refer to the example for ListView_SelectionCount().

Related items Commands

ListView_SelectionSet()

FUNCTION LIBRARY REFERENCE 335

L I S T V I E W _ S E L E C T I O N S E T ()

ListView_SelectionSet()
Description The ListView_SelectionSet() function changes the selection in a list view
field.

Syntax ListView_SelectionSet(list_view_field, item_index {, mode})

Parameters • list_view_field – The list view field whose selection is being changed.

• item_index – A long integer specifying the item that is being selected, added
to the selection or removed from the selection. You can also use one of the
following constants:

Constant Description
LV_ALL Specifies that all items will be selected.
LV_NONE Specifies that no items will be selected.

• mode – An optional integer parameter that is used for list view fields that
allow multiple selections. The value corresponds to one of the following
constants:

Constant Description
LV_SELECTION_ADD Adds the specified item to the current selection.
LV_SELECTION_REMOVE Removes the specified item from the current selection.

If this parameter isn’t included, the selection is changed to include only the
specified item.

Return value A boolean indicating whether the selection was set. True indicates the
selection was set, while false indicates it was not.

Comments The selection changed script runs after the ListView_SelectionSet()

function is executed.

Examples The following example selects the first item in the Explorer List list view
field.

local boolean result;

result = ListView_SelectionSet('Explorer List', 1);

336 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _S E L E C T I O N S E T ()

The following example adds the third item of the Explorer List list view
field to the current selection.

local boolean result;

result = ListView_SelectionSet('Explorer List', 3, LV_SELECTION_ADD);

The following example selects all items in the Explorer List list view field.

local boolean result;

result = ListView_SelectionSet('Explorer List', LV_ALL);

The following example clears the selection of the Explorer List list view
field.

local boolean result;

result = ListView_SelectionSet('Explorer List', LV_NONE);

Related items Commands

ListView_ItemMakeVisible(), ListView_SelectionGet()

FUNCTION LIBRARY REFERENCE 337

L I S T V I E W _ S E T E M P T Y M E S S A G E ( )

ListView_SetEmptyMessage()
Description The ListView_SetEmptyMessage() function specifies the message to
display when the list view doesn’t contain any items.

Syntax ListView_SetEmptyMessage(list_view_field, message)

Parameters • list_view_field – The list view field for which the empty message is being set.

• message – A string containing the message to display when the list view
contains no items.

Return value A boolean indicating whether the message was set. True indicates the
message was set, while false indicates it was not.

Examples The following example uses the ListView_SetEmptyMessage() function to

specify that the Explorer List list view field will display the message “No
items to display” when it contains no items.

local boolean result;

result = ListView_SetEmptyMessage('Explorer List',

➥ "No items to display");

338 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ S E T S O R T C O L U M N ()

ListView_SetSortColumn()
Description The ListView_SetSortColumn() function specifies the column by which a
list view field is sorted.

Syntax ListView_SetSortColumn(list_view_field, column_index, sort_order {, refresh)

Parameters • list_view_field – The list view field for which sorting is being specified.

• column_index – An integer specifying the column to sort. The value 1

indicates the first column that was added to the list view.

Dragging a column to a different position in the list view does not affect the column
index.

• sort_order – An integer corresponding to one of the following constants:

Constant Description
LV_SORT_ASCENDING The column will be sorted in ascending order.
LV_SORT_DESCENDING The column will be sorted in descending order.

• refresh – An optional boolean. If set to true, the list view field is re-sorted
immediately. If set to false, the list view field must be updated manually
using the ListView_Sort() function.

Return value An integer containing the column index of the column by which the list was
previously sorted.

Comments For the ListView_SetSortColumn() function to work properly, the

SortMethod property for the list view field must be set to Column.

A list view can be sorted by only one column at a time.

FUNCTION LIBRARY REFERENCE 339

L I S T V I E W _ S E T S O R T C O L U M N ( )

Examples The following example uses the ListView_SetSortColumn() function to set

the sorting characteristics of the Explorer List list view field, based on
settings in the defaults file.

local integer sort_column;

local integer sort_mode;

sort_column = value(Defaults_Read("ExpSortCol"));
sort_mode = value(Defaults_Read("ExpSortMode"));

sort_column = ListView_SetSortColumn('Explorer List' of window

➥ RESM_Explorer, sort_column, sort_mode, true);

Related items Commands

ListView_GetSortColumn(), ListView_Sort()

340 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ S E T V I E W ()

ListView_SetView()
Description The ListView_SetView() function sets the view mode for the specified list
view field.

Syntax ListView_SetView(list_view_field, view_mode)

Parameters • list_view_field – The list view field for which the view mode is being set.

• view_mode – An integer specifying the view mode. The value corresponds to

one of the following constants:

Constant Description
LV_SMICON_VIEW Small icon view
LV_LGICON_VIEW Large icon view
LV_LIST_VIEW List view
LV_REPORT_VIEW Report view

Return value An integer containing the previous view mode for the list view field. The
value corresponds to one of the constants listed for the view_mode
parameter.

Examples The following example uses the ListView_SetView() function to set the
view mode of the Explorer List list view field, based on a defaults file
setting.

local string defaults_value;

local integer view_mode;

defaults_value = Defaults_Read("ExpMode");

if defaults_value = "" then

view_mode = LV_LGICON_VIEW;
else
view_mode = value(defaults_value);
end if;

view_mode = ListView_SetView('Explorer List', view_mode);

Related items Commands

ListView_GetView()

FUNCTION LIBRARY REFERENCE 341

L I S T V I E W _ S O R T ( )

ListView_Sort()
Description The ListView_Sort() function sorts the items in a list view field.

Syntax ListView_Sort(list_view_field {, sort_method})

Parameters • list_view_field – The list view field that is being sorted.

• sort_method – An optional integer parameter that specifies the sorting

method to use. The value corresponds to one of the following constants:

Constant Description
LV_SORT_ASCENDING Items are sorted in ascending order based on the item
label.
LV_SORT_DESCENDING Items are sorted in descending order based on the
item label.
LV_SORT_COLUMN Items are sorted based on a column in the list.
LV_SORT_NONE Items are not sorted.
LV_SORT_DEFAULT Items are sorted using the method specified by the
SortMethod property.

If this parameter isn’t included, the list view field will be re-sorted based on
the current sorting method.

Return value A boolean indicating whether the list view field was sorted. True indicates
the list view was sorted, while false indicates it was not.

Comments Using the ListView_Sort() function to specify a sorting method will

override the sorting method specified by the list view field’s SortMethod
property.

When items are added to a list view field, they are added at the bottom of
the list, regardless of how the list is currently being sorted. You can use the
ListView_Sort() function after adding items to re-sort the list.

Examples The following example uses the ListView_Sort() function to sort the
Explorer List list view field. The items in the list will be sorted in
descending order.

local boolean result;

result = ListView_Sort('Explorer List', LV_SORT_DESCENDING);

342 F U N C T I O N L I B R A R Y R E F E R E N C E
 L I S T V I E W _ S O R T ()

The following example re-sorts the Explorer List list view field using the
sorting method specified by the SortMethod property of the field.

local boolean result;

result = ListView_Sort('Explorer List', LV_SORT_DEFAULT);

FUNCTION LIBRARY REFERENCE 343

344 F U N C T I O N L I B R A R Y R E F E R E N C E
 Login function library
Refer to Chapter 44, Use the functions in this library to manage data source connections if your
“Logins and Connec- application uses the SQL database type. This library contains the following
tions,” in Volume 1 of functions:
the Dexterity
Programmer’s Guide • Login_AlterLogin()
for more information • Login_CreateLogin()
about logins and data • Login_DropLogin()
sources. • Login_ExitDataSource()
• Login_GetDataSources()
• Login_GetDBMSInfo()
• Login_GetInfo()
• Login_GetLoginSettings()
• Login_LogIntoDataSource()
• Login_LogIntoDataSourceEx()
• Login_OpenDexDialog()
• Login_VerifyInfo()

FUNCTION LIBRARY REFERENCE 345

L O G I N _ A L T E R L O G I N ( )

Login_AlterLogin() SQL

Description The Login_AlterLogin() function is used to change the characteristics of a

SQL login.

Syntax Login_AlterLogin(data_source, user_ID, login_options, return_code

{,new_password} {,previous_password})

Parameters • data_source – A string specifying the data source to use to connect to the
SQL server.

• user_ID – A string specifying the ID of the user login that is being altered.

• login_options – A long integer that specifying the option settings to use for
the SQL login. This is a bitmask value. The following table lists the options
and their corresponding hexadecimal values:

Option Value
Enforce password policy 0x01000000
Enforce password expiration 0x02000000
Change password on next login 0x00800000

These options apply only to logins for SQL Server 2005. They are ignored for SQL
Server 2000.

• return_code – A returned long integer indicating the results of the command.

This is a bitmask value. The following table lists the values that can be
returned.

Return code Value

Successful login 0x00000001
Failed login 0x00000002
Create or alter failed 0x00000004
Create or alter succeeded 0x00000008
Password expired 0x00010000
Exception caught 0x00020000
Login locked 0x00040000
Password too short 0x00100000
Password too long 0x00200000
Password not complex 0x00400000

346 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ A L T E R L O G I N ()

• new_password – An optional string that specifies the new password to use

for the SQL login.

• previous_password – An optional string that specifies the previous password

for the login. This parameter is used when a user is changing their own
password. If this parameter is supplied, the login_options parameter is
ignored.

Return value An integer specifying the status of the operation. The following table lists
the constants that correspond to the values that can be returned.

Constant
STATUS_SUCCESS
STATUS_MEMORY_ERROR
STATUS_TOO_MANY_CONNECTIONS
STATUS_DATASOURCE_REJ
STATUS_UNABLE_TO_CONNECT
STATUS_LOGIN_LOCKED
STATUS_LOGIN_PASSWORD_HISTORY
STATUS_LOGIN_PASSWORD_SHORT
STATUS_LOGIN_PASSWORD_LONG
STATUS_LOGIN_PASSWORD_SIMPLE
STATUS_LOGIN_PASSWORD_UNKNOWN
STATUS_LOGIN_PASSWORD_POLICY
STATUS_LOGIN_INVALID
STATUS_INVALID_PERMISSIONS
STATUS_NOT_LOGGED_IN
Description
Operation was successful.
A memory error occurred.
Too many SQL connection in use to
perform the operation.
The SQL server rejected the operation.
Unable to connect to the data source.
Login is locked.
Password supplied violates password
history.
Password specified is too short.
Password specified is too long.
Password specified is too simple.
Password is unknown.
The password specified violates the
password policy.
The login is not valid to perform the
operation.
The login had invalid permissions to
perform the operation.
No user is logged in to perform the
operation.

Comments A SQL administrator can use this command to change any specific user’s
password or login options. A user can use this command to change only
their own password.

Examples The following example shows how a SQL administrator can set the login
options for a specific login on SQL Server 2005. The options are set to
enforce the password policy and password expiration.

FUNCTION LIBRARY REFERENCE 347

L O G I N _ A L T E R L O G I N ( )

local integer status;

local long retcode;
local long login_options;

{Specify the login options}

login_options = 0x01000000 + 0x02000000;

status = Login_AlterLogin("GPSDK", "STEVE", login_options, retcode);

case status
in [STATUS_SUCCESS]
warning "Login successfully updated.";
in [STATUS_MEMORY_ERROR]
warning "Memory error.";
in [STATUS_LOGIN_FAILED]
warning "Login failed.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "Too many connections.";
in [STATUS_DATASOURCE_REJ]
warning "Datasource rejection.";
in [STATUS_UNABLE_TO_CONNECT]
warning "Unable to connect.";
in [STATUS_LOGIN_INVALID]
warning "Login invalid.";
in [STATUS_INVALID_PERMISSIONS]
warning "Invalid permissions.";
in [STATUS_NOT_LOGGED_IN]
warning "Not logged in.";
end case;

The following example shows how a SQL administrator can set the
password for a specific login. In this case, the password for the login
“STEVE” is changed to “GreenRoutine5”.
local integer status;
local long retcode;
local long login_options;

{Retrieve the existing login options}

status = Login_GetLoginSettings("STEVE", login_options);

status = Login_AlterLogin("GPSDK", "STEVE", login_options, retcode,

➥ "GreenRoutine5");

348 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ A L T E R L O G I N ()

case status
in [STATUS_SUCCESS]
warning "Login successfully updated.";
in [STATUS_MEMORY_ERROR]
warning "Memory error.";
in [STATUS_LOGIN_FAILED]
warning "Login failed.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "Too many connections.";
in [STATUS_DATASOURCE_REJ]
warning "Datasource rejection.";
in [STATUS_UNABLE_TO_CONNECT]
warning "Unable to connect.";
in [STATUS_LOGIN_INVALID]
warning "Login invalid.";
in [STATUS_INVALID_PERMISSIONS]
warning "Invalid permissions.";
in [STATUS_NOT_LOGGED_IN]
warning "Not logged in.";
in [STATUS_LOGIN_PASSWORD_SIMPLE]
warning "Password is too simple.";
in [STATUS_LOGIN_PASSWORD_SHORT]
warning "Password is too short.";
in [STATUS_LOGIN_PASSWORD_LONG]
warning "Password is too long.";
in [STATUS_LOGIN_PASSWORD_HISTORY]
warning "Password violates password history.";
end case;

The following example shows how a user can change their own password.
In this case, the password for the user “STEVE” is being changed from
“GreenRoutine5” to “PolarJoy8”.

local integer status;

local long retcode;
local long login_options;

{Specify the login options, which will be ignored.}

login_options = 0;

status = Login_AlterLogin("GPSDK", "STEVE", login_options, retcode,

➥ "PolarJoy8", "GreenRoutine5");

FUNCTION LIBRARY REFERENCE 349

L O G I N _ A L T E R L O G I N ( )

case status
in [STATUS_SUCCESS]
warning "Login successfully updated.";
in [STATUS_MEMORY_ERROR]
warning "Memory error.";
in [STATUS_LOGIN_FAILED]
warning "Login failed.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "Too many connections.";
in [STATUS_DATASOURCE_REJ]
warning "Datasource rejection.";
in [STATUS_UNABLE_TO_CONNECT]
warning "Unable to connect.";
in [STATUS_LOGIN_INVALID]
warning "Login invalid.";
in [STATUS_INVALID_PERMISSIONS]
warning "Invalid permissions.";
in [STATUS_NOT_LOGGED_IN]
warning "Not logged in.";
in [STATUS_LOGIN_PASSWORD_SIMPLE]
warning "Password is too simple.";
in [STATUS_LOGIN_PASSWORD_SHORT]
warning "Password is too short.";
in [STATUS_LOGIN_PASSWORD_LONG]
warning "Password is too long.";
in [STATUS_LOGIN_PASSWORD_HISTORY]
warning "Password violates password history.";
end case;

350 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ C R E A T E L O G I N ()

Login_CreateLogin() SQL

Description The Login_CreateLogin() function is used to create a new SQL login.

Syntax Login_CreateLogin(data_source, user_ID, password, login_options,

return_code)

Parameters • data_source – A string specifying the data source to use to connect to the
SQL server.

• user_ID – A string specifying the ID of the user login that is being created.

• password – An string that specifies the password to use for the SQL login.

• login_options – A long integer that specifying the option settings to use for
the SQL login. This is a bitmask value. The following table lists the options
and their corresponding hexadecimal values:

Option Value
Enforce password policy 0x01000000
Enforce password expiration 0x02000000
Change password on next login 0x00800000

These options apply only to logins for SQL Server 2005. They are ignored for SQL
Server 2000.

• return_code – A returned long integer indicating the results of the command.

This is a bitmask value. The following table lists the values that can be
returned.

Return code Value

Successful login 0x00000001
Failed login 0x00000002
Create or alter failed 0x00000004
Create or alter succeeded 0x00000008
Password expired 0x00010000
Exception caught 0x00020000
Login locked 0x00040000
Password too short 0x00100000
Password too long 0x00200000
Password not complex 0x00400000

FUNCTION LIBRARY REFERENCE 351

L O G I N _ C R E A T E L O G I N ()

Return value An integer specifying the status of the operation. The following table lists
the constants that correspond to the values that can be returned.

Constant
STATUS_SUCCESS
STATUS_MEMORY_ERROR
STATUS_TOO_MANY_CONNECTIONS
STATUS_DATASOURCE_REJ
STATUS_UNABLE_TO_CONNECT
STATUS_LOGIN_LOCKED
STATUS_LOGIN_PASSWORD_HISTORY
STATUS_LOGIN_PASSWORD_SHORT
STATUS_LOGIN_PASSWORD_LONG
STATUS_LOGIN_PASSWORD_SIMPLE
STATUS_LOGIN_PASSWORD_UNKNOWN
STATUS_LOGIN_EXISTS
STATUS_LOGIN_PASSWORD_POLICY
STATUS_LOGIN_INVALID
STATUS_INVALID_PERMISSIONS
STATUS_NOT_LOGGED_IN
Description
Operation was successful.
A memory error occurred.
Too many SQL connection in use to
perform the operation.
The SQL server rejected the operation.
Unable to connect to the data source.
Login is locked.
Password supplied violates password
history.
Password specified is too short.
Password specified is too long.
Password specified is too simple.
Password is unknown.
The login already exists.
The password specified violates the
password policy.
The login is not valid to perform the
operation.
The login had invalid permissions to
perform the operation.
No user is logged in to perform the
operation.

Comments The current user must have SQL administrative privileges to create a new
login.

Examples The following example creates a new SQL login for the GPSDK data source.
The SQL options specify that the password for the new login must be
changed when the login is first used.
local integer status;
local long retcode;
local long login_options;

login_options = 0x01000000 + 0x02000000 + 0x00800000;

status = Login_CreateLogin("GPSDK", "TEST", "PolarJoy8",

➥ login_options, retcode);

352 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ C R E A T E L O G I N ()

case status
in [STATUS_SUCCESS]
warning "Login successfully created.";
in [STATUS_MEMORY_ERROR]
warning "Memory error.";
in [STATUS_LOGIN_FAILED]
warning "Login failed.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "Too many connections.";
in [STATUS_DATASOURCE_REJ]
warning "Datasource rejection.";
in [STATUS_UNABLE_TO_CONNECT]
warning "Unable to connect.";
in [STATUS_LOGIN_LOCKED]
warning "Login locked.";
in [STATUS_LOGIN_PASSWORD_HISTORY]
warning "Login violated password history.";
in [STATUS_LOGIN_PASSWORD_SHORT]
warning "Password too short.";
in [STATUS_LOGIN_PASSWORD_LONG]
warning "Password too long.";
in [STATUS_LOGIN_PASSWORD_SIMPLE]
warning "Password too simple.";
in [STATUS_LOGIN_PASSWORD_UNKNOWN]
warning "Password unknown.";
in [STATUS_LOGIN_PASSWORD_EXPIRED]
warning "Password expired.";
in [STATUS_LOGIN_PASSWORD_MUST_CHANGE]
warning "Password must change.";
in [STATUS_LOGIN_EXISTS]
warning "Login already exists.";
in [STATUS_LOGIN_PASSWORD_POLICY]
warning "Password violates password policy.";
in [STATUS_LOGIN_INVALID]
warning "Login invalid.";
in [STATUS_INVALID_PERMISSIONS]
warning "Invalid permissions to create login.";
in [STATUS_NOT_LOGGED_IN]
warning "Not logged in.";
end case;

FUNCTION LIBRARY REFERENCE 353

L O G I N _ D R O P L O G I N ( )

Login_DropLogin() SQL

Description The Login_DropLogin() function is used to drop a SQL login.

Syntax Login_DropLogin(user_ID)

Parameters • user_ID – A string specifying the ID of the user login that is being dropped.

Return value An integer specifying the status of the operation. The following table lists
the constants that correspond to the values that can be returned.

Constant
STATUS_SUCCESS
STATUS_MEMORY_ERROR
STATUS_TOO_MANY_CONNECTIONS
STATUS_DATASOURCE_REJ
STATUS_UNABLE_TO_CONNECT
STATUS_LOGIN_LOCKED
STATUS_LOGIN_INVALID
STATUS_INVALID_PERMISSIONS
STATUS_NOT_LOGGED_IN
Description
Operation was successful.
A memory error occurred.
Too many SQL connection in use to
perform the operation.
The SQL server rejected the operation.
Unable to connect to the data source.
Login is locked.
The login is not valid to perform the
operation.
The login had invalid permissions to
perform the operation.
No user is logged in to perform the
operation.

Comments The current user must have SQL administrative privileges to drop a login.

Examples The following example drops the login “STEVE” from the current data
source.

local integer status;

status = Login_DropLogin("STEVE");

if status <> STATUS_SUCCESS then

warning "Drop failed.";
end if;

354 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ E X I T D A T A S O U R C E ()

Login_ExitDataSource() SQL

Description The Login_ExitDataSource() function disconnects a user from the current

data source.

Syntax Login_ExitDataSource()

Parameters • None

Return value An integer corresponding to one of the following constants:

Constant Description
STATUS_SUCCESS The user logout was successful.
STATUS_ERROR An unknown error occurred.
STATUS_CANT_LOGOUT There are still open connections associated with this
user.
STATUS_NOT_LOGGED_IN The user isn’t logged into a data source.

Comments A user must log into a data source before his or her first connection can be
established. Subsequent connections to that data source for that user are
associated with the initial login. If one of those connections is being used to
access a table, Dexterity won’t allow the user to log out until the table is
closed and the connection is released.

Examples The following could be attached to a logout button change script.

local integer status;

set status to Login_ExitDataSource();

case status
in [STATUS_CANT_LOGOUT]
warning "Unable to log out due to open connection.";
in [STATUS_ERROR]
warning "An unknown error has occurred.";
in [STATUS_NOT_LOGGED_IN]
warning "A user isn't logged into a data source.";
end case;

Related items Commands

Login_LogIntoDataSource(), Login_LogIntoDataSourceEx()

FUNCTION LIBRARY REFERENCE 355

L O G I N _ G E T D A T A S O U R C E S ( )

Login_GetDataSources() SQL

Description The Login_GetDataSources() function fills a list box or drop-down list with
the names of all available data sources.

Syntax Login_GetDataSources(listbox)

Parameters • listbox – The name of the list box or drop-down list to be filled with a list of
available data source names.

Return value An integer corresponding to one of the following constants:

Constant Description
STATUS_SUCCESS The list box was filled successfully.
STATUS_ERROR The list box wasn’t filled, due to an error.

Comments The data sources that are included in the list will vary from client to client.
Only the data sources that have been set up using a computer’s ODBC
driver manager will be included in the list displayed at that computer.

Examples The following example uses this function to fill the Data_Source_LB list
box, from which a user can select a data source to log into.

local integer status;

status = Login_GetDataSources(Data_Source_LB);
if status <> STATUS_SUCCESS then
{Display a message.}
warning "Unable to fill the data source list.";
end if;

356 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ G E T D BM SI N F O ()

Login_GetDBMSInfo() SQL

Description The Login_GetDBMSInfo() function retrieves information about the

ODBC driver and data source being used.

Syntax Login_GetDBMSInfo(ODBC_version, driver_version, DBMS,

DBMS_version)

Parameters • ODBC_version – A returned string describing the version of ODBC to which

the driver manager conforms.

• driver_version – A returned string describing the version of the driver used

to access the ODBC data source.

• DBMS – A returned string describing the DBMS being accessed.

• DBMS_version – A returned string describing the version of the DBMS

being accessed.

Return value An integer indicating whether information was retrieved. The constant
STATUS_SUCCESS indicates information was retrieved. Any other value
indicates information could not be retrieved.

Comments You must be logged into a SQL data source for the Login_GetDBMSInfo()
function to retrieve information.

Examples The following example uses the Login_GetDBMSInfo() function to

retrieve information about the current ODBC driver and data source being
used. The information is displayed in an about box for the application.

local integer status;

local string ODBC_version, driver_version, DBMS, DBMS_version;

status = Login_GetDBMSInfo(ODBC_version, driver_version, DBMS,

➥ DBMS_version);
if status = STATUS_SUCCESS then
'(L) ODBC Version' = ODBC_version;
'(L) Driver Version' = driver_version;
'(L) DBMS' = DBMS;
'(L) DBMS Version' = DBMS_version;
end if;

FUNCTION LIBRARY REFERENCE 357

L O G I N _ G E T I N F O ( )

Login_GetInfo() SQL

Description The Login_GetInfo() function returns the name of the data source, the user
ID and session ID associated with the current session.

Syntax Login_GetInfo(data_source, user_ID, session_ID)

Parameters • data_source – A returned string containing the data source the current client
is logged into.

• user_ID – A returned string containing the current user’s user ID.

• session_ID – A returned long integer containing the session ID assigned to

the current login session.

Return value An integer corresponding to one of the following constants:

Constant Description
STATUS_SUCCESS The login information was successfully retrieved.
STATUS_NOT_LOGGED_IN A user isn’t logged in.
STATUS_ERROR An unknown error occurred.

Examples The following example uses this function in a script attached to a

connection status button. If the function is completed successfully, the
current user ID and data source values are displayed to the user.

local string data_source, user_ID;

local long session_ID;
local integer status;

status = Login_GetInfo(data_source, user_ID, session_ID);

if status = STATUS_SUCCESS then
warning "User" + user_ID + "is logged into data source" +
➥ data_source + ".";
elseif status = STATUS_NOT_LOGGED_IN then
warning "Client is currently not logged in.";
else
warning "An unknown error has occurred.";
end if;

358 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ G E T L O G I N S E T T I N G S ()

Login_GetLoginSettings() SQL

Description The Login_GetLoginSettings() function is used to retrieve the login

options for the specified SQL login.

Syntax Login_GetLoginSettings(user_ID, login_options)

Parameters • user_ID – A string specifying the ID of the user login for which settings are
being retrieved.

• login_options – A long integer that specifying the option settings to use for
the SQL login. This is a bitmask value. The following table lists the options
and their corresponding hexadecimal values:

Option Value
Enforce password policy 0x01000000
Enforce password expiration 0x02000000
Change password on next login 0x00800000

These options apply only to logins for SQL Server 2005. They are ignored for SQL
Server 2000.

Return value An integer specifying the status of the operation. The following table lists
the constants that correspond to the values that can be returned.

Constant Description
STATUS_SUCCESS Operation was successful.
STATUS_MEMORY_ERROR A memory error occurred.
STATUS_TOO_MANY_CONNECTIONS Too many SQL connection in use to
perform the operation.
STATUS_DATASOURCE_REJ The SQL server rejected the operation.
STATUS_UNABLE_TO_CONNECT Unable to connect to the data source.
STATUS_LOGIN_INVALID The login is not valid.
STATUS_INVALID_PERMISSIONS The login had invalid permissions to
perform the operation.
STATUS_NOT_LOGGED_IN No user is logged in to perform the
operation.

FUNCTION LIBRARY REFERENCE 359

L O G I N _ G E T L O G I N S E T T I N G S ( )

Examples The following example shows how a SQL administrator can set the
password for a specific login. In this case, the login options are retrieved so
that the same values will be used when the login is updated.

local integer status;

local long retcode;
local long login_options;

{Retrieve the existing login options}

status = Login_GetLoginSettings("STEVE", login_options);

status = Login_AlterLogin("GPSDK", "STEVE", login_options, retcode,

➥ "GreenRoutine5");

if status = STATUS_SUCCESS then

warning "Login successfully updated.";
else
error "Password change failed.";
end if;

Related items Commands

Login_AlterLogin()

360 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ L O G I N T O D A T A S O U R C E ()

Login_LogIntoDataSource() SQL

Description The Login_LogIntoDataSource() function logs the user into the named
data source using the specified user ID and password.

Syntax Login_LogIntoDataSource(data_source, user_ID, password)

Parameters • data_source – A string specifying the data source to log into.

• user_ID – A string specifying the user ID to use when logging into the data
source.

• password – A string specifying the password to use when logging into the
named data source.

Return value An integer corresponding to one of the following constants:

Constant
STATUS_SUCCESS
STATUS_ERROR
STATUS_ALREADY_LOGGED_IN
STATUS_LOGIN_FAILED
STATUS_LOGIN_LOCKED
STATUS_TOO_MANY_CONNECTIONS
STATUS_DATASOURCE_REJ
STATUS_UNABLE_TO_CONNECT
STATUS_LOGIN_PASSWORD_EXPIRED
STATUS_LOGIN_PASSWORD_MUST_
CHANGE
Description
The login was successful.
An unknown error occurred.
That user is already logged in.
The login information was invalid.
Login is locked.
The maximum number of connections to
the database was reached.
The server acknowledged the connection
attempt, but rejected it. The problem was
server-based.
The client computer’s ODBC drivers were
unable to establish a connection to the
server. The problem was client-based.
Password has expired.
The password must be changed before the
user can log in.

Comments This command allows you to use your own login window, rather than the
predefined login window the Login_OpenDexDialog() function opens.

FUNCTION LIBRARY REFERENCE 361

L O G I N _ L O G I N T O D A T A S O U R C E ( )

Examples The following example uses this function in a change script attached to the
OK button of a login window. The user selects a data source from a drop-
down list named Data_Source_DDL and enters a user ID and password.

local string data_source_name;

local integer status;

data_source_name = itemname(Data_Source_DDL, Data_Source_DDL);

User_ID of table User_Verify = User_ID of window Log_in_Window;
Password of table User_Verify = Password of window Log_in_Window;
status = Login_LogIntoDataSource(data_source_name, User_ID,
➥ Password);
if status <> STATUS_SUCCESS then
case status
in [STATUS_ALREADY_LOGGED_IN]
warning "You're already logged in.";
in [STATUS_LOGIN_FAILED]
warning "Your user ID or password was invalid. Try again.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "No connections are available. Try later.";
else
{A status denoting a problem was returned.}
warning "An error has occurred.";
end case;
end if;

Related items Commands

Login_ExitDataSource(), Login_OpenDexDialog()

362 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ L O G I N T O D A T A S O U R C E E X ()

Login_LogIntoDataSourceEx() SQL

Description The Login_LogIntoDataSourceEx() function logs the user into the named
data source using the specified user ID and password. It also supports the
additional password features available for SQL Server 2005.

Syntax Login_LogIntoDataSourceEx(data_source, user_ID, password, return_code

{,previous_password})

Parameters • data_source – A string specifying the data source to log into.

• user_ID – A string specifying the user ID to use when logging into the data
source.

• password – A string specifying the password to use when logging into the
named data source.

• return_code – A returned long integer indicating the results of the command.

This is a bitmask value. The following table lists the values that can be
returned.

Return code Value

Successful login 0x00000001
Failed login 0x00000002
Create or alter failed 0x00000004
Create or alter succeeded 0x00000008
Password expired 0x00010000
Exception caught 0x00020000
Login locked 0x00040000
Password too short 0x00100000
Password too long 0x00200000
Password not complex 0x00400000

• previous_password – An optional string parameter that is used when the

current user is required to change their password when initially logging
into the data source. This option is supported only on SQL Server 2005.

FUNCTION LIBRARY REFERENCE 363

L O G I N _ L O G I N T O D A T A S O U R C E E X ()

Return value An integer corresponding to one of the following constants:

Constant Description
STATUS_SUCCESS The login was successful.
STATUS_ERROR An unknown error occurred.
STATUS_ALREADY_LOGGED_IN That user is already logged in.
STATUS_LOGIN_FAILED The login information was invalid.
STATUS_LOGIN_LOCKED Login is locked.
STATUS_TOO_MANY_CONNECTIONS The maximum number of connections to
the database was reached.
STATUS_DATASOURCE_REJ The server acknowledged the connection
attempt, but rejected it. The problem was
server-based.
STATUS_UNABLE_TO_CONNECT The client computer’s ODBC drivers were
unable to establish a connection to the
server. The problem was client-based.
STATUS_LOGIN_PASSWORD_EXPIRED Password has expired.
STATUS_LOGIN_PASSWORD_MUST_ The password must be changed before the
CHANGE user can log in.

Comments To support all of the login features in SQL Server 2005, you must be using
the SQL Native Client driver for your ODBC connection.

Examples The following example is the change script for the Login button on a
custom login window. It attempts to connect to the specified data source. If
the password must be changed on the initial login, the
Login_LogIntoDataSourceEx() function is used to specify the new
password and connect to the data source.

local string data_source_name;

local string old_password;
local string new_password;
local integer status;
local long ret_value;

data_source_name = itemname('(L) Data Sources', '(L) Data Sources');

status = Login_LogIntoDataSource(data_source_name, '(L) Login',
➥ '(L) Password');
if status <> STATUS_SUCCESS then
case status
in [STATUS_ALREADY_LOGGED_IN]
warning "You're already logged in.";

364 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ L O G I N T O D A T A S O U R C E E X ()

in [STATUS_LOGIN_FAILED]
warning "Your user ID or password was invalid. Try again.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "No connections are available. Try later.";
in [STATUS_LOGIN_PASSWORD_MUST_CHANGE]
warning "Password must be changed.";

if getstring ("Please enter your old password", true,

➥ old_password) then
if getstring ("Please enter your new password", true,
new_password) then
{Call the login, supplying the information needed
to change the password}
status = Login_LogIntoDataSourceEx
➥ (data_source_name, '(L) Login', new_password,
➥ ret_value, old_password);

if status <> STATUS_SUCCESS then

case status
in [STATUS_MEMORY_ERROR]
warning "Memory error.";
in [STATUS_LOGIN_FAILED]
warning "Login failed.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "Too many connections.";
in [STATUS_DATASOURCE_REJ]
warning "Datasource rejection.";
in [STATUS_UNABLE_TO_CONNECT]
warning "Unable to connect.";
in [STATUS_LOGIN_LOCKED]
warning "Login locked.";
in [STATUS_LOGIN_PASSWORD_HISTORY]
warning "Password already in history.";
in [STATUS_LOGIN_PASSWORD_SHORT]
warning "New password is too short.";
in [STATUS_LOGIN_PASSWORD_LONG]
warning "New password is too long.";
in [STATUS_LOGIN_PASSWORD_SIMPLE]
warning "New password is too simple.";
in [STATUS_LOGIN_PASSWORD_UNKNOWN]
warning "Password unknown.";
in [STATUS_LOGIN_PASSWORD_EXPIRED]
warning "Password has expired.";

FUNCTION LIBRARY REFERENCE 365

L O G I N _ L O G I N T O D A T A S O U R C E E X ()

in [STATUS_LOGIN_PASSWORD_MUST_CHANGE]
warning "Password must be changed.";
in [STATUS_LOGIN_PASSWORD_POLICY]
warning "New password violates policy.";
in [STATUS_LOGIN_INVALID]
warning "Login invalid.";
in [STATUS_INVALID_PERMISSIONS]
warning "Invalid permissions.";
end case;
else
{Login and password change were successful, so
close the Login form}
close form Login;
end if;
end if;
end if;
else
{A status denoting a problem was returned.}
warning "An error has occurred.";
warning "Error: " + str(status);
end case;
else
{Login was successful, so close the login form.}
close form Login;
end if;

366 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ O P E N D E X D I A L O G ()

Login_OpenDexDialog() SQL

Description The Login_OpenDexDialog() function allows the user to log into the
named data source using Dexterity’s predefined Login window.

Syntax Login_OpenDexDialog()

Parameters • None

Return value An integer corresponding to one of the following constants:

Constant
STATUS_SUCCESS
STATUS_ERROR
STATUS_ALREADY_LOGGED_IN
STATUS_LOGIN_FAILED
STATUS_CANCEL
STATUS_TOO_MANY_CONNECTIONS
STATUS_DATASOURCE_REJ
STATUS_UNABLE_TO_CONNECT
Description
The login was successful.
An unknown error occurred.
That user is already logged in.
The login information was invalid.
The user pressed the Cancel button.
The maximum number of connections to the
database was reached.
The server acknowledged the connection
attempt, but rejected it. The problem was
server-based.
The client computer’s ODBC drivers were
unable to establish a connection to the server.
The problem was client-based.

Comments This function opens a predefined Login window that prompts the user for a
data source, user ID and password. To use a login window you’ve created,
use the Login_LogIntoDataSource() function.

If the SQLDataSource and SQLUser default settings are included in the

defaults file for the current client, those values will be displayed in the Data
Source and User_ID fields, and the user will be prompted for a password. If
the SQLPassword setting is also included in the defaults file, then the Login
window will be bypassed and the connection will be attempted
automatically.

To assure your application’s security and data integrity, we recommend that you
don’t use the SQLPassword defaults file setting.

FUNCTION LIBRARY REFERENCE 367

L O G I N _ O P E N D E X D I A L O G ( )

If the SQLDataSource and SQLUser settings aren’t included in the defaults

file, the values displayed in the Data Source and User_ID fields of the Login
window will be the values currently in the SQLLastDataSource and
SQLLastUser settings of the defaults file, which are generated
automatically by Dexterity.

The following illustration shows the window opened by this command:

Examples The following example, which could be used in a pre script attached to an
application’s Main Menu, uses this function to log a user into a server using
the Dexterity’s predefined Login window.

local integer status;

status = Login_OpenDexDialog();
if status <> STATUS_SUCCESS then
case status
in [STATUS_ALREADY_LOGGED_IN]
warning "You're already logged in.";
in [STATUS_LOGIN_FAILED]
warning "Your user ID or password was invalid.";
in [STATUS_TOO_MANY_CONNECTIONS]
warning "No connections are available. Try later.";
else
{A status denoting a problem was returned.}
warning "An error has occurred.";
end case;
end if;

Related items Commands

Login_LogIntoDataSource()

368 F U N C T I O N L I B R A R Y R E F E R E N C E
 L O G I N _ V E R I F Y I N F O ()

Login_VerifyInfo() SQL

Description The Login_VerifyInfo() function verifies whether the specified user ID and
password are a valid combination for access to the named data source.

Syntax Login_VerifyInfo(data_source, user_ID, password)

Parameters • data_source – A string specifying the data source to verify access for.

• user_ID – A string specifying the user ID for which access to the data source
should be verified.

• password – A string specifying the password associated with the user ID to

be verified.

Return value An integer corresponding to one of the following constants:

Constant
STATUS_SUCCESS
STATUS_ERROR
STATUS_LOGIN_FAILED
STATUS_TOO_MANY_CONNECTIONS
STATUS_DATASOURCE_REJ
STATUS_UNABLE_TO_CONNECT
STATUS_LOGIN_PASSWORD_EXPIRED
STATUS_LOGIN_PASSWORD_MUST_
CHANGE
Description
The login was successful.
An unknown error occurred.
The login information was invalid.
The maximum number of connections to the
database was reached.
The server acknowledged the connection
attempt, but rejected it. The problem was
server-based.
The client computer’s ODBC drivers were
unable to establish a connection to the
server. The problem was client-based.
Password has expired.
The password must be changed before the
user can log in.

Comments This function is intended to simplify the process of switching a user’s login
from one data source to another. Using this function, you can verify
whether the specified user is able to log into another data source before
logging the user out of the data source he or she is currently connected to. If
you’re developing an application that integrates with Microsoft Dynamics
GP, this function will be useful when switching users between companies,
where the information for each company is stored in different data sources.

FUNCTION LIBRARY REFERENCE 369

L O G I N _ V E R I F Y I N F O ()

Examples The following example verifies whether a user has access to a data source
other than the one he or she is currently logged into. If the user has access to
the named data source, the user is logged out of the current data source and
logged into the new one. If the user is unable to access the named data
source, he or she remains logged into the current data source.

local string data_source_name, user_ID, password;

local integer status, status2, status3;

data_source_name = itemname(Data_Source_DDL of window 'Switch_User',

➥ Data_Source_DDL);
user_ID = User_ID of window Switch_User;
password = Password of window Switch_User;
{Verify that this user can access the named data source.}
status = Login_VerifyInfo(data_source_name, user_ID, password);
{If the user can access the new data source, log out of the current
data source and log into the new data source.}
if status = STATUS_SUCCESS then
status2 = Login_ExitDataSource();
if status2 = STATUS_SUCCESS then
status3 = Login_LogIntoDataSource(data_source_name, user_ID,
➥ password);
end if;
else
warning "Unable to switch data sources.";
end if;

370 F U N C T I O N L I B R A R Y R E F E R E N C E
Mail function library
Use the functions in this library when adding mail support to your
application. The functions in the Mail function library can send mail
through Exchange Web Services (EWS). EWS uses a web service interface to
communicate directly with a Microsoft Exchange or Office 365 server to
send mail. No e-mail client is required.

This library contains the following functions:

• Mail_AddressListAdd()
• Mail_AddressListCount()
• Mail_AddressListCreate()
• Mail_AddressListDestroy()
• Mail_AddressListGet()
• Mail_AddressListRemove()
• Mail_DisplayAddressDialog()
• Mail_DisplayReplyToDialog()
• Mail_GetServerType()
• Mail_GetSessionAddress()
• Mail_IsLoggedOn()
• Mail_LogOff()
• Mail_LogOn()
• Mail_ResolveAddress()
• Mail_Send()
• Mail_SendDialog()
• Mail_SetServerType()

FUNCTION LIBRARY REFERENCE 371

M A I L _ A D D R E S S L I S T A D D ( )

Mail_AddressListAdd()
Description The Mail_AddressListAdd() function adds an address to the specified
address list.

Syntax Mail_AddressListAdd(address_list_ID, mail_type, recipient_name, address)

Parameters • address_list_ID – The ID of the address list to which an address is being

added.

• mail_type – An integer specifying how the message is to be sent to the

recipient. Use one of the following constants:

Constant Description
MAIL_TO Send the message directly to the recipient.
MAIL_CC Send the message to the recipient as a carbon copy.
MAIL_BCC Send the message to the recipient as a blind carbon copy.
MAIL_REPLY_TO Send the message reply to the recipient.

• recipient_name – A string specifying the name of the recipient. The name can
be up to 80 characters.

• address – A string specifying the e-mail address of the recipient. The address
can be up to 255 characters.

Return value A boolean. True indicates the address was added to the list, while false
indicates it was not.

Examples The following example uses the Mail_AddressListAdd() function to add an

address to a new address list.
local long address_list_ID;
local boolean result;

{Create a new address list.}

address_list_ID = Mail_AddressListCreate();

{Add an address to the list.}

result = Mail_AddressListAdd(address_list_ID, MAIL_TO, "Steve K",
➥ "stevek@example.com");
if result = false then
error "Address couldn't be added to address list.";
end if;

372 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ A D D R E S S L I S T C O U N T ()

Mail_AddressListCount()
Description The Mail_AddressListCount() function returns the number of addresses in
the specified address list.

Syntax Mail_AddressListCount(address_list_ID)

Parameters • address_list_ID – The ID of the address list whose addresses will be counted.

Return value An integer containing the number of addresses in the address list.

Examples The following example uses the Mail_AddressListCount() function to

retrieved the number of addresses in the specified address list. The value is
used in a message displayed to the user.

local integer address_count, answer;

local integer result;
local boolean bool_result;
local string count_string;

{Count the number of addresses in the address list.}

address_count = Mail_AddressListCount('Address List');
count_string = str(address_count);

{Verify that the user wants to send the message.}

answer = ask("This message will be sent to " + count_string +
➥ " users. Do you want to send the message?", "Yes", "No", "");
if answer = ASKBUTTON1 then
{Send the message.}
result = Mail_Send('Address List', 'Subject', 'Message Text');
if result <> MAIL_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
bool_result = Mail_AddressListDestroy('Address List');
end if;
end if;

FUNCTION LIBRARY REFERENCE 373

M A I L _ A D D R E S S L I S T C R E A T E ( )

Mail_AddressListCreate()
Description The Mail_AddressListCreate() function creates a list that will contain
addresses to which a mail message will be sent or replies returned to.

Syntax Mail_AddressListCreate()

Parameters • None

Return value A long integer containing the ID of the address list.

Examples The following example uses the Mail_AddressListCreate() function to

create a new address list. Then the Mail dialog is displayed, allowing the
user to specify the recipients.

local boolean result;

{Create the address list.}

'Address List' = Mail_AddressListCreate();

{Display the address dialog.}

result = Mail_DisplayAddressDialog('Address List', "Send to...");

374 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ A D D R E S S L I S T D E S T R O Y ()

Mail_AddressListDestroy()
Description The Mail_AddressListDestroy() function removes the specified address list
from memory.

Syntax Mail_AddressListDestroy(address_list_ID)

Parameters • address_list_ID – The ID of the address list to remove from memory.

Return value A boolean. True indicates the address list was removed from memory,
while false indicates it was not.

Comments After you are done using an address list, be sure to use the
Mail_AddressListDestroy() function to release memory used by the list.

Examples The following example uses the Mail_AddressListDestroy() function to

free memory after a message has been sent successfully.

local integer address_count, answer;

local integer result;
local boolean bool_result;
local string count_string;

{Count the number of addresses in the address list.}

address_count = Mail_AddressListCount('Address List');
count_string = str(address_count);

{Verify that the user wants to send the message.}

answer = ask("This message will be sent to " + count_string +
➥ " users. Do you want to send the message?", "Yes", "No", "");
if answer = ASKBUTTON1 then
{Send the message.}
result = Mail_Send('Address List', 'Subject', 'Message Text');
if result <> MAIL_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
bool_result = Mail_AddressListDestroy('Address List');
end if;
end if;

FUNCTION LIBRARY REFERENCE 375

M A I L _ A D D R E S S L I S T G E T ( )

Mail_AddressListGet()
Description The Mail_AddressListGet() function retrieves an address from the
specified address list.

Syntax Mail_AddressListGet(address_list_ID, index, mail_type, recipient_name,

address {, address_type})

Parameters • address_list_ID – The ID of the address list from which an address will be
retrieved.

• index – An integer specifying which address in the list to retrieve; 1 specifies

the first address, 2 specifies the second, and so on.

• mail_type – A returned integer indicating how the message is to be sent to

the recipient. The value corresponds to one of the following constants:

Constant Description
MAIL_TO Send the message directly to the recipient.
MAIL_CC Send the message to the recipient as a carbon copy.
MAIL_BCC Send the message to the recipient as a blind carbon copy.
MAIL_REPLY_TO Send the message reply to the recipient.

• recipient_name – A returned string containing the name of the recipient. The

name can be up to 255 characters.

• address – A returned string containing the e-mail address of the recipient.

The address can be up to 255 characters.

• address_type – An optional inout integer parameter that specifies the type of

address to retrieve. The value corresponds to one of the following
constants:

Constant
MAIL_ADDRESS_EXCHANGE
MAIL_ADDRESS_SMTP
MAIL_ADDRESS_DEFAULT
Description
The Exchange e-mail address is returned.
The SMTP e-mail address is returned.
The default format of the e-mail address is returned.
The value of the address_type parameter will be set
to the constant indicating the address type returned.

Return value A boolean. True indicates an address was retrieved, while false indicates it
was not.

376 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ A D D R E S S L I S T G E T ()

Examples The following example uses the Mail_AddressListGet() function to retrieve

the addresses from an address list and save them in a table.

local boolean result;

local integer address_count, i, mail_type;
local string list_name, recipient_name, recipient_address;

{Ask the user for a list name.}

if getstring("Please name the address list.", false, list_name) then
{Count the number of addresses in the address list.}
address_count = Mail_AddressListCount('Address List');
'List Name' of table Mailing_List = list_name;
for i = 1 to address_count do
{Retrieve the address information.}
result = Mail_AddressListGet('Address List', i, mail_type,
➥ recipient_name, recipient_address);
{Save each address item.}
'Mail Type' of table Mailing_List = mail_type;
'Name' of table Mailing_List = recipient_name;
'Address' of table Mailing_List = recipient_address;
save table Mailing_List;
end for;
end if;

FUNCTION LIBRARY REFERENCE 377

M A I L _ A D D R E S S L I S T R E M O V E ( )

Mail_AddressListRemove()
Description The Mail_AddressListRemove() function removes an address from the
specified address list.

Syntax Mail_AddressListRemove(address_list_ID, index)

Parameters • address_list_ID – The ID of the address list from which an address will be
removed.

• index – An integer specifying which address in the list to remove; 1 specifies

the first address, 2 specifies the second, and so on.

Return value A boolean. True indicates an address was removed, while false indicates it
was not.

Examples The following example uses the Mail_AddressListRemove() function to

remove all addresses from an address list.

local boolean result;

local integer count;

{Count the number of addresses in the address list.}

address_count = Mail_AddressListCount('Address List');

for i = 1 to address_count do
{Remove the address.}
result = Mail_AddressListRemove('Address List', i);
end for;

378 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ D I S P L A Y A D D R E S S D I A L O G ()

Mail_DisplayAddressDialog()
Description The Mail_DisplayAddressDialog() function displays the mail message
addressing dialog that allows a user to specify who a message will be sent
to. An existing address list can be displayed in this dialog.

Syntax Mail_DisplayAddressDialog(address_list_ID, dialog_title {, focus})

Parameters • address_list_ID – The ID of the address list that contains addresses to

display and to which an address list will be returned.

• dialog_title – A string specifying the title that appears at the top of the
addressing dialog.

• focus – An optional integer field that specifies the field that is focused when
the addressing dialog is displayed. The value corresponds to one of the
following constants:

Constant Description
MAIL_TO Focus in the To field.
MAIL_CC Focus in the CC field.
MAIL_BCC Focus in the BCC field.

Return value A boolean that is returned when the user clicks Close. The value true
indicates no error occurred, while false indicates that an error occurred.

Comments The mail addressing dialog is shown in the following illustration.

FUNCTION LIBRARY REFERENCE 379

M A I L _ D I S P L A Y A D D R E S S D I A L O G ()

Examples The following example creates a new address list. Then the
Mail_DisplayAddressDialog() function displays the mail addressing
dialog, allowing the user to specify the recipients.

local boolean result;

{Create the address list.}

'Address List' = Mail_AddressListCreate();

{Display the address dialog.}

result = Mail_DisplayAddressDialog('Address List', "Send to...");

380 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _D I S P L A Y R E P L Y T O D I A L O G ()

Mail_DisplayReplyToDialog()
Description The Mail_DisplayReplyToDialog() function displays the mail message
addressing dialog that allows the user to select who message replies will be
sent to. An existing address list can be displayed in this dialog.

Syntax Mail_DisplayReplyToDialog(reply_to_list_ID, dialog_title)

Parameters • reply_to_list_ID – The ID of the address list that contains addresses to

display and to which replies to the message will be sent.

• dialog_title – A string specifying the title that appears at the top of the
addressing dialog.

Return value A boolean that is returned when the user clicks Close. The value true
indicates no error occurred, while false indicates that an error occurred.

Comments A typical Mail addressing dialog is shown in the following illustration.

FUNCTION LIBRARY REFERENCE 381

M A I L _ D I S P L A Y R E P L Y T O D I A L O G ( )

Examples The following example creates a new address list that replies to a message
will be sent to. Then the Mail_DisplayReplyToDialog() function displays
the mail addressing dialog, allowing the user to specify the recipients the
reply will be sent to.

local boolean result;

{Create the address list.}

'Reply To List' = Mail_AddressListCreate();

{Display the reply to dialog.}

result = Mail_DisplayReplyToDialog('Reply To List', "Reply to...");

382 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ G E T S E R V E R T Y P E ()

Mail_GetServerType()
Description The Mail_GetServerType() function retrieves the type of server that is
being used for the current session.

Syntax Mail_GetServerType()

Parameters • None

Return value An integer corresponding to one of the following constants:

Constant
MAIL_SERVER_SIMPLE_MAPI
MAIL_SERVER_EXTENDED_MAPI
MAIL_SERVER_EWS
MAIL_SERVER_SMTP
Description
A simple MAPI mail server
An extended MAPI mail server
An Exchange mail server through Exchange Web
Services
An SMTP mail server

Examples The following example uses the Mail_GetServerType() function to retrieve

the type of server that is being used.

local integer server_type;

{Retrieve the type of mail server currently being accessed}

server_type = Mail_GetServerType();

FUNCTION LIBRARY REFERENCE 383

M A I L _ G E T S E S S I O N A D D R E S S ()

Mail_GetSessionAddress()
Description The Mail_GetSessionAddress() function retrieves the address from the
current mail profile.

Syntax Mail_GetSessionAddress(name, address {, address_type})

Parameters • name – A returned string containing the display name for the profile
address. The name can be up to 255 characters.

• address – A returned string containing the e-mail address for the profile
address. The address can be up to 255 characters.

• address_type – An optional inout integer parameter that specifies the type of

address to retrieve. The value corresponds to one of the following
constants:

Constant
MAIL_ADDRESS_EXCHANGE
MAIL_ADDRESS_SMTP
MAIL_ADDRESS_DEFAULT
Description
The Exchange e-mail address is returned.
The SMTP e-mail address is returned.
The default format of the e-mail address is returned.
The value of the address_type parameter will be set
to the constant indicating the address type returned.

Return value A boolean. True indicates the address was retrieved, while false indicates it
was not.

Examples The following example uses the Mail_GetSessionAddress() function to

retrieve the address associated with the current mail profile.

local string email_name;

local string email_address;
local boolean result;

{Retrieve the address for the current mail profile}

result = Mail_GetSessionAddress(email_name, email_address);

384 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ I S L O G G E D O N ()

Mail_IsLoggedOn()
Description The Mail_IsLoggedOn() function indicates whether the application is
currently logged on to a mail session.

Syntax Mail_IsLoggedOn()

Parameters • None

Return value A boolean. True indicates the application is logged on to a mail session,
while false indicates it is not.

Examples The following script example uses the Mail_IsLoggedOn() function to

check whether a mail session is currently active. If one is not, the
Mail_LogOn() function is used to create one.

{Does a Mail session need to be created?}

if Mail_IsLoggedOn() = false then

{Set the server type}

Mail_SetServerType(MAIL_SERVER_EWS);

{Attempt to log on to a Mail session}

if Mail_LogOn() = true then
warning "Log on successful";
else
error "Log on failed";
end if;
end if;

FUNCTION LIBRARY REFERENCE 385

M A I L _ L O G O F F ( )

Mail_LogOff()
Description The Mail_LogOff() function closes the mail session on the current
workstation.

Syntax Mail_LogOff()

Parameters • None

Return value None

Examples The following example uses the Mail_LogOff() function to close the current
Mail session.

Mail_LogOff();

386 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ L O G O N ()

Mail_LogOn()
Description The Mail_LogOn() function creates a mail session on the current
workstation.

Syntax Mail_LogOn({string1}{, string2}{, string3})

Parameters • string1 – An optional string parameter. If you are connecting to a MAPI

mail server, this string specifies the profile to use for the mail session. An
error message will be displayed if you supply the name of a profile name
that does not exist.

If you are connecting to an Exchange server through the Exchange Web

Service, this string can be used to specify the URL of the Exchange server.
The URL will be similar to the following example:

https://computername.domain.contoso.com/EWS/Exchange.asmx

If you are using auto-discovery to connect to an Exchange server, this string

can be used to specify the e-mail address for the connection.

• string2 – An optional string parameter.If you are using auto-discovery to

connect to an Exchange server, this string specifies the user name for the
connection. The format of the user name is Domain\UserName.

• string3 – An optional string parameter. If you are using auto-discovery to

connect to an Exchange server, this string specifies the password for the
connection.

Return value A boolean. True indicates the mail session was successfully created, while
false indicates it was not.

Comments You must call the Mail_SetServerType() function before you use the
Mail_LogOn() function. Any existing mail session is automatically closed
before the new session is created.

If you are connecting to a MAPI mail server and don’t specify a profile, a
dialog box is automatically displayed that allows the user to choose a
profile to use. If you are connecting to an Exchange server through the
Exchange Web Service and don’t specify the URL or the auto-discovery
parameters, a dialog box is automatically displayed that allows the user to
supply their credentials.

FUNCTION LIBRARY REFERENCE 387

M A I L _ L O G O N ( )

Examples The following script example checks whether a mail session is currently
active. If one is not, the Mail_LogOn() function is used to create a
connection through the Exchange Web Service.

{Does a Mail session need to be created?}

if Mail_IsLoggedOn() = false then

{Set the server type}

Mail_SetServerType(MAIL_SERVER_EWS);

{Attempt to log on to a Mail session}

if Mail_LogOn() = true then
warning "Log on successful";
else
error "Log on failed";
end if;
end if;

388 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ R E S O L V E A D D R E S S ()

Mail_ResolveAddress()
Description The Mail_ResolveAddress() function attempts to match a search string to
an e-mail address in the address book.

Syntax Mail_ResolveAddress(search_name, show_dialog, name, email

{, address_type})

Parameters • search_name – A string containing the name or e-mail address to search for.

• show_dialog – A boolean. True specifies that the resolve dialog will be

displayed if the search name cannot be resolved. False indicates that the
dialog will not be displayed.

• name – A returned string containing the display name for the e-mail address
that was found. If the search name could not be resolved, the empty string
is returned.

• email – A returned string containing the e-mail address that was found. If
the search name could not be resolved, the empty string is returned.

• address_type – An optional inout integer parameter that specifies the type of

address to find. The value corresponds to one of the following constants:

Constant Description
MAIL_ADDRESS_EXCHANGE The Exchange e-mail address is returned.
MAIL_ADDRESS_SMTP The SMTP e-mail address is returned.
MAIL_ADDRESS_DEFAULT The default format of the e-mail address is returned.
The value of the address_type parameter will be set
to the constant indicating the address type returned.

Return value A boolean. True indicates that a search result was found and returned,
while false indicates that no result was found.

FUNCTION LIBRARY REFERENCE 389

M A I L _ R E S O L V E A D D R E S S ( )

Examples The following example attempts to resolve the search name “Steve K” to
find the corresponding e-mail address and display name. If no result can be
found, the resolve dialog will be displayed.

local string display_name;

local string email;
local boolean result;

result = Mail_ResolveAddress("Steve K", true, display_name, email);

if result = true then

warning display_name + ": " + email;
end if;

390 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ S E N D ()

Mail_Send()
Description The Mail_Send() function sends a message to the members of a specified
address list.

Syntax Mail_Send(address_list_ID, subject, message_text {,attachment|filelist_ID}

{, reply_to_list}{, property_list})

Parameters • address_list_ID – The ID of the address list to which the message will be
sent.

• subject – A string specifying the subject line of the message.

• message_text – A text field or variable containing the text for the message.
This parameter can also be an integer specifying which attachment in the
attachment list to use for the message text. The value 1 indicates the first
attachment.

• attachment|filelist_ID – An optional parameter that specifies the attachment

or list of attachments for the message. If the parameter is a string, the string
specifies the path (in generic format) of a file to attach to the message. If the
parameter is a long integer, the value specified ID of the file list that
contains the files to attach to the message.

• reply_to_list – An optional parameter that specifies the ID of the address list

to which the replies to the message will be sent.

• property_list – An optional parameter that specifies the ID of the property

list that contains properties to apply to the message. This allows you to
apply additional properties that are not exposed through the Mail
functions.

These properties are set using the Property functions from the MAPI function
library.

FUNCTION LIBRARY REFERENCE 391

M A I L _ S E N D ( )

Return value An integer corresponding to one of the following constants:

MAIL_SUCCESS
MAIL_AMBIGUOUS_RECIPIENT
MAIL_ATTACHMENT_NOT_FOUND
MAIL_ATTACHMENT_OPEN_FAILURE
MAIL_BAD_RECIPTYPE
MAIL_INSUFFICIENT_MEMORY
MAIL_INVALID_RECIPS
MAIL_BODY_INDEX_OUT_OF_RANGE
MAIL_LOGIN_FAILURE
MAIL_TEXT_TOO_LARGE
MAIL_TOO_MANY_FILES
MAIL_TOO_MANY_RECIPIENTS
MAIL_UNKNOWN_RECIPIENT
MAIL_USER_ABORTED
MAIL_BAD_MAPI_PROPERTIES
MAIL_UNKNOWN

Comments When using an attachment for the message body, the file attachment will
typically be in text, HTML, or RTF format. The attachment used for the
message text will not appear as an attachment for the message.

Examples The following example uses the Mail_Send() function to send a message to
the members of the specified address list.

local integer address_count;

local integer answer;
local integer send_result;
local boolean result;
local string count_string;

{Count the number of addresses in the address list.}

address_count = Mail_AddressListCount('Address List');
count_string = str(address_count);

{Verify that the user wants to send the message.}

answer = ask("This message will be sent to " + count_string +
➥ " users. Do you want to send the message?", "Yes", "No", "");
if answer = ASKBUTTON1 then
{Send the message.}
send_result = Mail_Send('Address List','Subject','Message Text');
if send_result <> MAIL_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = Mail_AddressListDestroy('Address List');
end if;
end if;

392 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ S E N D D I A L O G ()

Mail_SendDialog()
Description The Mail_SendDialog() function opens the Compose window that allows a
message to be composed and sent.

Syntax Mail_Send(address_list_ID, subject, message_text {,attachment|filelist_ID}

{, reply_to_list}{, property_list})

Parameters • address_list_ID – The ID of the address list to which the message will be
sent.

• subject – A string specifying the subject line of the message.

• message_text – A text field or variable containing the text for the message.
This parameter can also be an integer specifying which attachment in the
attachment list to use for the message text. The value 1 indicates the first
attachment.

• attachment|filelist_ID – An optional parameter that specifies the attachment

or list of attachments for the message. If the parameter is a string, the string
specifies the path (in generic format) of a file to attach to the message. If the
parameter is a long integer, the value specified ID of the file list that
contains the files to attach to the message.

• reply_to_list – An optional parameter that specifies the ID of the address list

to which the replies to the message will be sent.

• property_list – An optional parameter that specifies the ID of the property

list that contains properties to apply to the message. This allows you to
apply additional Mail properties that are not exposed through the Mail
functions.

These properties are set using the Property functions from the MAPI function
library.

FUNCTION LIBRARY REFERENCE 393

M A I L _ S E N D D I A L O G ( )

Return value An integer corresponding to one of the following constants:

MAIL_SUCCESS MAIL_LOGIN_FAILURE
MAIL_AMBIGUOUS_RECIPIENT MAIL_TEXT_TOO_LARGE
MAIL_ATTACHMENT_NOT_FOUND MAIL_TOO_MANY_FILES
MAIL_ATTACHMENT_OPEN_FAILURE MAIL_TOO_MANY_RECIPIENTS
MAIL_BAD_RECIPTYPE MAIL_UNKNOWN_RECIPIENT
MAIL_INSUFFICIENT_MEMORY MAIL_USER_ABORTED
MAIL_INVALID_RECIPS MAIL_BAD_MAPI_PROPERTIES
MAIL_BODY_INDEX_OUT_OF_RANGE MAIL_UNKNOWN

Comments If any of the address list, reply to list, subject, message text, or attachments
parameters are supplied with values, those values will appear in the
Compose window when it is displayed.

When using an attachment for the message body, the file attachment will
typically be in text, HTML, or RTF format. The attachment used for the
message text will not appear as an attachment for the message.

Examples The following example uses the Mail_SendDialog() function to send a

message to the members of the specified address list.

local integer send_result;

local boolean result;

{Send the message.}

send_result = Mail_SendDialog('Address List','Subject',
➥ 'Message Text');
if send_result <> MAIL_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = Mail_AddressListDestroy('Address List');
end if;

394 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A I L _ S E T S E R V E R T Y P E ()

Mail_SetServerType()
Description The Mail_SetServerType() function specifies the type of connection to use
for the mail server. This function must be used before you use the
Mail_LogOn() function.

Syntax Mail_SetServerType(type)

Parameters • type – An integer corresponding to one of the following constants:

Constant
MAIL_SERVER_SIMPLE_MAPI
MAIL_SERVER_EXTENDED_MAPI
MAIL_SERVER_EWS
Description
A simple MAPI mail server
An extended MAPI mail server
An Exchange mail server through Exchange Web
Services

Return value None

Examples The following script example checks whether a mail session is currently
active. If one is not, Mail_SetServerType() is used to specify the connection
type and then the Mail_LogOn() function is used to create a connection.

{Does a Mail session need to be created?}

if Mail_IsLoggedOn() = false then

{Set the server type}

Mail_SetServerType(MAIL_SERVER_EWS);

{Attempt to log on to a Mail session}

if Mail_LogOn() = true then
warning "Log on successful";
else
error "Log on failed";
end if;
end if;

FUNCTION LIBRARY REFERENCE 395

M A I L _ S E T S E R V E R T Y P E ( )

396 F U N C T I O N L I B R A R Y R E F E R E N C E
MAPI function library
Use the functions in this library when adding MAPI support to your
application. To send mail, these functions require a 32-bit compatible MAPI
mail client on the current workstation.

We recommend that you use the functions in the Mail function library when
implementing mail support for your application. The functions in the Mail
function library can send mail through Exchange Web Services (EWS). EWS
uses a web service interface to communicate directly with a Microsoft
Exchange or Office 365 server to send mail. No e-mail client is required.

This library contains the following functions:

• MAPI_AddAddress()
• MAPI_CountAddresses()
• MAPI_CreateAddressList()
• MAPI_DestroyAddressList()
• MAPI_DisplayDialog()
• MAPI_DisplayReplyToDialog()
• MAPI_GetAddress()
• MAPI_IsLoggedOn()
• MAPI_IsMailEnabled()
• MAPI_LogOff()
• MAPI_LogOn()
• MAPI_ProfileGetAddress()
• MAPI_PropertyListCount()
• MAPI_PropertyListCreate()
• MAPI_PropertyListDestroy()
• MAPI_PropertyListGetValue()
• MAPI_PropertyListGetValueByIndex()
• MAPI_PropertyListSetValue()
• MAPI_RemoveAddress()
• MAPI_ResolveAddress()
• MAPI_Send()
• MAPI_SendDialog()

FUNCTION LIBRARY REFERENCE 397

MA PI _A D D A D D R E S S ()

MAPI_AddAddress()
Description The MAPI_AddAddress() function adds an address to the specified
address list.

Syntax MAPI_AddAddress(address_list_ID, mail_type, recipient_name, address)

Parameters • address_list_ID – The ID of the address list to which an address is being

added.

• mail_type – An integer specifying how the message is to be sent to the

recipient. Use one of the following constants:

Constant Description
MAIL_TO Send the message directly to the recipient.
MAIL_CC Send the message to the recipient as a carbon copy.
MAIL_BCC Send the message to the recipient as a blind carbon copy.
MAIL_REPLY_TO Send the message reply to the recipient.

• recipient_name – A string specifying the name of the recipient. The name can
be up to 80 characters.

• address – A string specifying the e-mail address of the recipient. The address
can be up to 255 characters. The address should also specify the transport
protocol to use for the message, such as SMTP (Simple Mail Transport
Protocol). Refer to the example for more information.

Return value A boolean. True indicates the address was added to the list, while false
indicates it was not.

Examples The following example uses the MAPI_AddAddress() function to add an

address to a new address list. SMTP protocol is used for the message.
local long address_list_ID;
local boolean result;

{Create a new address list.}

address_list_ID = MAPI_CreateAddressList();

{Add an address to the list.}

result = MAPI_AddAddress(address_list_ID, MAIL_TO, "Steve K",
➥ "smtp:skubis@gps.tw.com");
if result = false then
error "Address couldn't be added to address list.";
end if;

398 F U N C T I O N L I B R A R Y R E F E R E N C E
 MA PI _C O U N T A D D R E S S E S ()

MAPI_CountAddresses()
Description The MAPI_CountAddresses() function returns the number of addresses in
the specified address list.

Syntax MAPI_CountAddresses(address_list_ID)

Parameters • address_list_ID – The ID of the address list whose addresses will be counted.

Return value An integer containing the number of addresses in the address list.

Examples The following example uses the MAPI_CountAddresses() function to

retrieved the number of addresses in the specified address list. The value is
used in a message displayed to the user.

local integer address_count;

local boolean answer, result;
local string count_string;

{Count the number of addresses in the address list.}

address_count = MAPI_CountAddresses('Address List');
count_string = str(address_count);

{Verify that the user wants to send the message.}

answer = ask("This message will be sent to " + count_string +
➥ " users. Do you want to send the message?", "Yes", "No", "");
if answer = ASKBUTTON1 then
{Send the message.}
result = MAPI_Send('Address List', 'Subject', 'Message Text');
if result = false then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = MAPI_DestroyAddressList('Address List');
end if;
end if;

FUNCTION LIBRARY REFERENCE 399

MA PI _C R E A T E A D D R E S S L I S T ( )

MAPI_CreateAddressList()
Description The MAPI_CreateAddressList() function creates a list that will contain
addresses to which a mail message will be sent or replies returned to.

Syntax MAPI_CreateAddressList()

Parameters • None

Return value A long integer containing the ID of the address list.

Examples The following example uses the MAPI_CreateAddressList() function to

create a new address list. Then the MAPI dialog is displayed, allowing the
user to specify the recipients.

local boolean result;

{Create the address list.}

'Address List' = MAPI_CreateAddressList();

{Display the address dialog.}

result = MAPI_DisplayDialog('Address List', "Send to...");

400 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A PI _ D E S T R O Y A D D R E S S L I S T ()

MAPI_DestroyAddressList()
Description The MAPI_DestroyAddressList() function removes the specified address
list from memory.

Syntax MAPI_DestroyAddressList(address_list_ID)

Parameters • address_list_ID – The ID of the address list to remove from memory.

Return value A boolean. True indicates the address list was removed from memory, while
false indicates it was not.

Comments After you are done using an address list, be sure to use the
MAPI_DestroyAddressList() function to release memory used by the list.

Examples The following example uses the MAPI_DestroyAddressList() function to

free memory once a message has been sent successfully.

local integer address_count;

local boolean answer, result;
local string count_string;

{Count the number of addresses in the address list.}

address_count = MAPI_CountAddresses('Address List');
count_string = str(address_count);

{Verify that the user wants to send the message.}

answer = ask("This message will be sent to " + count_string +
➥ " users. Do you want to send the message?", "Yes", "No", "");
if answer = ASKBUTTON1 then
{Send the message.}
result = MAPI_Send('Address List', 'Subject', 'Message Text');
if result = false then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = MAPI_DestroyAddressList('Address List');
end if;
end if;

FUNCTION LIBRARY REFERENCE 401

MA PI _D I S P L A Y D I A L O G ()

MAPI_DisplayDialog()
Description The MAPI_DisplayDialog() function displays the MAPI message
addressing dialog that allows a user to specify who a message will be sent
to. An existing address list can be displayed in this dialog.

Syntax MAPI_DisplayDialog(address_list_ID, dialog_title)

Parameters • address_list_ID – The ID of the address list that contains addresses to display
and to which an address list will be returned.

• dialog_title – A string specifying the title that appears at the top of the
addressing dialog.

Return value A boolean. True indicates that the user clicked OK and no error occurred.
False indicates that either the user clicked Cancel or an error occurred.

Comments A typical MAPI addressing dialog is shown in the following illustration.

Examples The following example creates a new address list. Then the
MAPI_DisplayDialog() function displays the MAPI addressing dialog,
allowing the user to specify the recipients.

local boolean result;

{Create the address list.}

'Address List' = MAPI_CreateAddressList();

{Display the address dialog.}

result = MAPI_DisplayDialog('Address List', "Send to...");

402 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I _D I S P L A Y R E P L Y T O D I A L O G ()

MAPI_DisplayReplyToDialog()
Description The MAPI_DisplayReplyToDialog() function displays the MAPI message
addressing dialog that allows the user to select who message replies will be
sent to. An existing address list can be displayed in this dialog.

Syntax MAPI_DisplayReplyToDialog(reply_to_list_ID, dialog_title)

Parameters • reply_to_list_ID – The ID of the address list that contains addresses to

display and to which replies to the message will be sent.

• dialog_title – A string specifying the title that appears at the top of the
addressing dialog.

Return value A boolean. True indicates that the user clicked OK and no error occurred.
False indicates that either the user clicked Cancel or an error occurred.

Comments A typical MAPI addressing dialog is shown in the following illustration.

FUNCTION LIBRARY REFERENCE 403

MA PI _D I S P L A Y R E P L Y T O D I A L O G ( )

Examples Thlle following example creates a new address list that replies to a message
will be sent to. Then the MAPI_DisplayReplyToDialog() function displays
the MAPI addressing dialog, allowing the user to specify the recipients the
reply will be sent to.

local boolean result;

{Create the address list.}

'Reply To List' = MAPI_CreateAddressList();

{Display the reply to dialog.}

result = MAPI_DisplayReplyToDialog('Reply To List', "Reply to...");

404 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I_ G E T A D D R E S S ()

MAPI_GetAddress()
Description The MAPI_GetAddress() function retrieves an address from the specified
address list.

Syntax MAPI_GetAddress(address_list_ID, index, mail_type, recipient_name, address

{, address_type})

Parameters • address_list_ID – The ID of the address list from which an address will be
retrieved.

• index – An integer specifying which address in the list to retrieve; 1 specifies

the first address, 2 specifies the second, and so on.

• mail_type – A returned integer indicating how the message is to be sent to

the recipient. The value corresponds to one of the following constants:

Constant Description
MAIL_TO Send the message directly to the recipient.
MAIL_CC Send the message to the recipient as a carbon copy.
MAIL_BCC Send the message to the recipient as a blind carbon copy.
MAIL_REPLY_TO Send the message reply to the recipient.

• recipient_name – A returned string containing the name of the recipient. The

name can be up to 255 characters.

• address – A returned string containing the e-mail address of the recipient.

The address can be up to 255 characters.

• address_type – An optional inout integer parameter that specifies the type of

address to retrieve. The value corresponds to one of the following
constants:

Constant
MAPI_ADDRESS_EXCHANGE
MAPI_ADDRESS_SMTP
MAPI_DEFAULT_ADDRESS
Description
The Exchange e-mail address is returned.
The SMTP e-mail address is returned.
The default format of the e-mail address is returned.
The value of the address_type parameter will be set
to the constant indicating the address type returned.

Return value A boolean. True indicates an address was retrieved, while false indicates it
was not.

FUNCTION LIBRARY REFERENCE 405

MA PI _G E T A D D R E S S ( )

Examples The following example uses the MAPI_GetAddress() function to retrieve

the addresses from an address list and save them in a table.

local boolean result;

local integer address_count, i, mail_type;
local string list_name, recipient_name, recipient_address;

{Ask the user for a list name.}

if getstring("Please name the address list.", false, list_name) then
{Count the number of addresses in the address list.}
address_count = MAPI_CountAddresses('Address List');
'List Name' of table Mailing_List = list_name;
for i = 1 to address_count do
{Retrieve the address information.}
result = MAPI_GetAddress('Address List', i, mail_type,
➥ recipient_name, recipient_address);
{Save each address item.}
'Mail Type' of table Mailing_List = mail_type;
'Name' of table Mailing_List = recipient_name;
'Address' of table Mailing_List = recipient_address;
save table Mailing_List;
end for;
end if;

406 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I_ I S L O G G E D O N ()

MAPI_IsLoggedOn()
Description The MAPI_IsLoggedOn() function indicates whether the application is
currently logged on to a MAPI session.

Syntax MAPI_IsLoggedOn()

Parameters • None

Return value A boolean. True indicates the application is logged on to a MAPI session,
while false indicates it is not.

Examples The following script example uses the MAPI_IsLoggedOn() function to

check whether a MAPI session is currently active. If one is not, the
MAPI_LogOn() function is used to create one.

{Does a MAPI session need to be created?}

if MAPI_IsLoggedOn() = false then
{Attempt to log on to a MAPI session}
if MAPI_LogOn() = true then
warning "Log on successful";
else
error "Log on failed";
end if;
end if;

FUNCTION LIBRARY REFERENCE 407

MA PI _I S M A I L E N A B L E D ( )

MAPI_IsMailEnabled()
Description The MAPI_IsMailEnabled() function indicates whether the current
workstation supports MAPI. It can also be used to find out what level of
MAPI support is available.

Syntax MAPI_IsMailEnabled({level})

Parameters • level – An optional integer parameter that specifies what level of MAPI
support to check. The value corresponds to one of the following constants:

Constant Description
MAPI_SIMPLE Simple MAPI
MAPI_EXTENDED Extended MAPI

If this parameter is not supplied, the function will return true if either
simple or extended MAPI is supported.

Return value A boolean. True indicates the specified level of MAPI is supported, while
false indicates it is not.

Comments Before you use features of extended MAPI, you should explicitly check
whether extended MAPI is supported.

Examples The following example uses the MAPI_IsMailEnabled() function to find

out whether MAPI is supported on the current workstation. If it is, the
MAPI Enabled system variable is set to true.

if MAPI_IsMailEnabled() = true then

'MAPI Enabled’ of globals = true;
else
'MAPI Enabled' of globals = false;
end if;

408 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I_ L O G O F F ()

MAPI_LogOff()
Description The MAPI_LogOff() function closes the MAPI session on the current
workstation.

Syntax MAPI_LogOff()

Parameters • None

Return value None

Examples The following example uses the MAPI_LogOff() function to close the
current MAPI session.

MAPI_LogOff();

FUNCTION LIBRARY REFERENCE 409

MA PI _L O G O N ()

MAPI_LogOn()
Description The MAPI_LogOn() function creates a MAPI session on the current
workstation.

Syntax MAPI_LogOn({profile})

Parameters • profile – An optional string parameter that specifies the profile to use for the
MAPI session. An error message will be displayed if you supply the name
of a profile name that does not exist.

Return value A boolean. True indicates the MAPI session was successfully created, while
false indicates it was not.

Comments Any existing MAPI session is automatically closed before the new session is
created. If you don’t specify a profile, a dialog box is automatically
displayed that allows the user to choose a profile to use.

Examples The following script example checks whether a MAPI session is currently
active. If one is not, the MAPI_LogOn() function is used to create one.

{Does a MAPI session need to be created?}

if MAPI_IsLoggedOn() = false then
{Attempt to log on to a MAPI session}
if MAPI_LogOn() = true then
warning "Log on successful";
else
error "Log on failed";
end if;
end if;

410 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I_ P R O F I L E G E T A D D R E S S ()

MAPI_ProfileGetAddress()
Description The MAPI_ProfileGetAddress() function retrieves the name and e-mail
address from the profile for the current user.

This function requires Extended MAPI support.

Syntax MAPI_ProfileGetAddress(name, email {, address_type})

Parameters • name – A returned string containing the display name for the e-mail address
of the current user.

• email – A returned string containing the e-mail address of the current user.

• address_type – An optional inout integer parameter that specifies the type of

address to retrieve. The value corresponds to one of the following
constants:

Constant
MAPI_ADDRESS_EXCHANGE
MAPI_ADDRESS_SMTP
MAPI_DEFAULT_ADDRESS
Description
The Exchange e-mail address is returned.
The SMTP e-mail address is returned.
The default format of the e-mail address is returned.
The value of the address_type parameter will be set
to the constant indicating the address type returned.

Return value A boolean. True indicates the display name and e-mail address were
successfully returned, while false indicates they were not.

Examples The following example retrieves the e-mail address and display name for
the current user.

local string display_name;

local string email;
local boolean result;

{Get the e-mail address and display name for the current user.}
result = MAPI_ProfileGetAddress(display_name, email);

FUNCTION LIBRARY REFERENCE 411

MA PI _P R O P E R T Y L I S T C O U N T ( )

MAPI_PropertyListCount()
Description The MAPI_PropertyListCount() function retrieves the number of
properties in a property list.

Syntax MAPI_PropertyListCount(property_list_ID)

Parameters • property_list_ID – A long integer specifying the property list for which the
number of properties is being returned.

Return value An integer containing the number of properties.

Examples The following global procedure example counts the number of properties in
the property list passed into the script.

in long property_list_ID;

local integer count;

count = MAPI_PropertyListCount(property_list_ID);

412 F U N C T I O N L I B R A R Y R E F E R E N C E
 MA PI _P R O P E R T Y L I S T C R E A T E ()

MAPI_PropertyListCreate()
Description The MAPI_PropertyListCreate() function creates a list that will contain
properties that specify characteristics of an e-mail message.

Syntax MAPI_PropertyListCreate()

Parameters • None

Return value A long integer containing the ID of the property list.

Examples Refer to the example for MAPI_PropertyListSetValue().

FUNCTION LIBRARY REFERENCE 413

MA PI _P R O P E R T Y L I S T D E S T R O Y ( )

MAPI_PropertyListDestroy()
Description The MAPI_PropertyListDestroy() function removes the specified property
list from memory.

Syntax MAPI_PropertyListDestroy(property_list_ID)

Parameters • property_list_ID – A long integer specifying the property list to remove from
memory.

Return value A boolean. True indicates the property list was removed from memory,
while false indicates it was not.

Examples Refer to the example for MAPI_PropertyListSetValue().

414 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A PI _ P R O P E R T Y L I S T G E T V A L U E ()

MAPI_PropertyListGetValue()
Description The MAPI_PropertyListGetValue() function retrieves the value of a
property from the specified property list.

Syntax MAPI_PropertyListGetValue(property_list_ID, property_ID, property_value)

Parameters • property_list_ID – A long integer specifying the property list from which a
value is being retrieved.

• property_ID – A long integer specifying the ID of the property being

retrieved.

• property_value – A returned value containing the property value. The type

will depend on the property being returned.

Return value A boolean. True indicates the property value was successfully returned,
while false indicates it was not.

Comments The MAPI properties are available in the library on MSDN

(msdn.microsoft.com). They are also found in the MAPITags.h source file of
the Windows SDK. The MAPI property values are found in the
MAPIDefS.h source file of the Windows SDK.

Examples The following example retrieves the value of the PR_SUBJECT property.
This is a string property with value 0x0037 (55 decimal).

local boolean result;

local string prop_val;

{Retrieve the subject property.}

result = MAPI_PropertyListGetValue(property_list, 55, prop_val);

FUNCTION LIBRARY REFERENCE 415

MA PI _P R O P E R T Y L I S T G E T V A L U E B Y I N D E X ( )

MAPI_PropertyListGetValueByIndex()
Description The MAPI_PropertyListGetValueByIndex() function retrieves the value of
a property from the specified property list, based on the index.

Syntax MAPI_PropertyListGetValueByIndex(property_list_ID, index, property_ID,

property_value)

Parameters • property_list_ID – A long integer specifying the property list from which a
value is being retrieved.

• index – An integer specifying which property to return. The value 1

indicates the first property in the list.

• property_ID – A returned long integer specifying the ID of the property that

was retrieved.

• property_value – A returned value containing the property value. The type

will depend on the property being returned. If the data type of the variable
that the MAPI property value is returned to does not match the data type of
the MAPI property, no value will be returned.

Return value A boolean. True indicates the property value was successfully returned,
while false indicates it was not.

Comments The MAPI properties are available in the library on MSDN

(msdn.microsoft.com). They are also found in the MAPITags.h source file of
the Windows SDK. The MAPI property values are found in the
MAPIDefS.h source file of the Windows SDK.

Examples The following example counts the number of properties in a MAPI property
list, and then retrieves the ID and value of each property. The list of
properties is displayed in a warning message.

local integer count;

local integer i;
local boolean result;
local long property_ID;
local integer integer_property_value;
local long long_property_value;
local boolean boolean_property_value;
local datetime datetime_property_value;
local string string_property_value;
local text message;

416 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I _ P R O P E R T Y L I S T G E T V A L U E B Y I N D E X ()

{Count the number of items in the property list. The ID of the list}
{is stored by a local long integer window field.}
count = MAPI_PropertyListCount('(L) MAPI_Properties');

for i = 1 to count do

{Try retrieving each property until it is found.}

{String type}
result = MAPI_PropertyListGetValueByIndex('(L) MAPI_Properties',
➥ i, property_ID, string_property_value);
if result = true then
message = message + "Property ID: " + str(property_ID) +
➥ " Value: " + str(string_property_value) + char(13);
continue for;
end if;

{Integer type}
result = MAPI_PropertyListGetValueByIndex('(L) MAPI_Properties',
➥ i, property_ID, integer_property_value);
if result = true then
message = message + "Property ID: " + str(property_ID) +
➥ " Value: " + str(integer_property_value) + char(13);
continue for;
end if;

{Long type}
result = MAPI_PropertyListGetValueByIndex('(L) MAPI_Properties',
➥ i, property_ID, long_property_value);
if result = true then
message = message + "Property ID: " + str(property_ID) +
➥ " Value: " + str(long_property_value) + char(13);
continue for;
end if;

{Boolean type}
result = MAPI_PropertyListGetValueByIndex('(L) MAPI_Properties',
➥ i, property_ID, boolean_property_value);
if result = true then
message = message + "Property ID: " + str(property_ID) +
➥ " Value: " + str(boolean_property_value) + char(13);
continue for;
end if;

FUNCTION LIBRARY REFERENCE 417

MA PI _P R O P E R T Y L I S T G E T V A L U E B Y I N D E X ( )

{Datetime type}
result = MAPI_PropertyListGetValueByIndex('(L) MAPI_Properties',
➥ i, property_ID, datetime_property_value);
if result = true then
message = message + "Property ID: " + str(property_ID) +
➥ " Value: " + str(datetime_property_value) + char(13);
continue for;
end if;

end for;

if message <> "" then

warning message;
end if;

418 F U N C T I O N L I B R A R Y R E F E R E N C E
 MA PI _P R O P E R T Y L I S T S E T V A L U E ()

MAPI_PropertyListSetValue()
Description The MAPI_PropertyListSetValue() function sets the value of a property in
the specified property list.

Syntax MAPI_PropertyListSetValue(property_list_ID, property_ID, property_value)

Parameters • property_list_ID – A long integer specifying the property list in which a

value is being set.

• property_ID – A long integer specifying the ID of the property being set.

• property_value – A variable containing the property value. The variable type

will depend on the property being set.

Return value A boolean. True indicates the property value was successfully set, while
false indicates it was not.

Comments The MAPI properties are available in the library on MSDN

(msdn.microsoft.com). They are also found in the MAPITags.h source file of
the Windows SDK. The MAPI property values are found in the
MAPIDefS.h source file of the Windows SDK.

Examples The following example sends an e-mail message to the current user. A
property list is included with the message so that the message can be
flagged as important and a read receipt requested.

The PR_IMPORTANCE property for MAPI controls the importance setting

for the message. From the MAPITags.h source file in the Windows SDK, this
property has a value 0x0017. This corresponds to 23 in decimal. From the
MAPIDefS.h source file in the Windows SDK, the values for the
PR_IMPORTANCE property are 0, 1, or 2. These are defined as long integer
values (PT_LONG) so they must be converted to long integers when they
are passed to the MAPI_PropertyListSetValue() function.

The PR_READ_RECEIPT_REQUESTED property for MAPI controls

whether a read receipt will be requested when the recipient reads the
message. From the MAPITags.h source file in the Windows SDK, this
property has a value 0x0029. This corresponds to 41 in decimal.

After the message is successfully sent, the address list and property list are
removed from memory.

FUNCTION LIBRARY REFERENCE 419

MA PI _P R O P E R T Y L I S T S E T V A L U E ()

local integer send_result;

local boolean result;
local long property_list;
local long 'Address List';
local string display_name;
local string email;
local string 'Subject' = "Important Message";
local string 'Message Text' = "This is an important message.";

{Create the address list.}

'Address List' = MAPI_CreateAddressList();

{Get the e-mail address and display name for the current user.}
result = MAPI_ProfileGetAddress(display_name, email);

{Add the current user to the address list.}

result = MAPI_AddAddress('Address List', MAIL_TO, display_name,
email);

{Create a property list so that additional properties can be set for

the message.}
property_list = MAPI_PropertyListCreate();

{Add the 'Importance' property to the list.}

{
PR_IMPORTANCE property value: 0x0017 (23 in decimal)
IMPORTANCE_LOW value: 0
IMPORTANCE_NORMAL value: 1
IMPORTANCE_HIGH value: 2
}

{Set the property value. Note how it is converted to a long integer.}

result = MAPI_PropertyListSetValue(property_list, 23, long(2));

{Add the 'Read Receipt" property to the list.}

{
PR_READ_RECEIPT_REQUESTED property value: 0x0029 (41 in decimal)
}

result = MAPI_PropertyListSetValue(property_list, 41, true);

420 F U N C T I O N L I B R A R Y R E F E R E N C E
 MA PI _P R O P E R T Y L I S T S E T V A L U E ()

if result = true then

{Send the message.}
send_result = MAPI_Send('Address List','Subject', 'Message Text',
➥ none, none, property_list);
if send_result <> MAPI_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = MAPI_DestroyAddressList('Address List');
result = MAPI_PropertyListDestroy(property_list);
end if;
end if;

FUNCTION LIBRARY REFERENCE 421

MA PI _R E M O V E A D D R E S S ()

MAPI_RemoveAddress()
Description The MAPI_RemoveAddress() function removes an address from the
specified address list.

Syntax MAPI_RemoveAddress(address_list_ID, index)

Parameters • address_list_ID – The ID of the address list from which an address will be
removed.

• index – An integer specifying which address in the list to remove; 1 specifies

the first address, 2 specifies the second, and so on.

Return value A boolean. True indicates an address was removed, while false indicates it
was not.

Examples The following example uses the MAPI_RemoveAddress() function to

remove all addresses from an address list.

local boolean result;

local integer count;

{Count the number of addresses in the address list.}

address_count = MAPI_CountAddresses('Address List');

for i = 1 to address_count do
{Remove the address.}
result = MAPI_RemoveAddress('Address List', i);
end for;

422 F U N C T I O N L I B R A R Y R E F E R E N C E
 MA PI _R E S O L V E A D D R E S S ()

MAPI_ResolveAddress()
Description The MAPI_ResolveAddress() function attempts to match a search string to
an e-mail address in the address book.

This function requires Extended MAPI support.

Syntax MAPI_ResolveAddress(search_name, show_dialog, name, email

{, address_type})

Parameters • search_name – A string containing the name or e-mail address to search for.

• show_dialog – A boolean. True specifies that the resolve dialog will be

displayed if the search name cannot be resolved. False indicates that the
dialog will not be displayed.

• name – A returned string containing the display name for the e-mail address
that was found. If the search name could not be resolved, the empty string
is returned.

• email – A returned string containing the e-mail address that was found. If
the search name could not be resolved, the empty string is returned.

• address_type – An optional inout integer parameter that specifies the type of

address to find. The value corresponds to one of the following constants:

Constant Description
MAPI_ADDRESS_EXCHANGE The Exchange e-mail address is returned.
MAPI_ADDRESS_SMTP The SMTP e-mail address is returned.
MAPI_DEFAULT_ADDRESS The default format of the e-mail address is returned.
The value of the address_type parameter will be set
to the constant indicating the address type returned.

Return value A boolean. True indicates that a search result was found and returned,
while false indicates that no result was found.

FUNCTION LIBRARY REFERENCE 423

MA PI _R E S O L V E A D D R E S S ()

Examples The following example attempts to resolve the search name “Steve K” to
find the corresponding e-mail address and display name. If no result can be
found, the resolve dialog will be displayed.

local string display_name;

local string email;
local boolean result;

result = MAPI_ResolveAddress("Steve K", true, display_name, email);

if result = true then

warning display_name + ": " + email;
end if;

424 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I_ S E N D ()

MAPI_Send()
Description The MAPI_Send() function sends a message to the members of a specified
address list.

Syntax MAPI_Send(address_list_ID, subject, message_text {,attachment|filelist_ID}

{, reply_to_list}{, property_list})

Parameters • address_list_ID – The ID of the address list to which the message will be
sent.

• subject – A string specifying the subject line of the message.

• message_text – A text field or variable containing the text for the message.
This parameter can also be an integer specifying which attachment in the
attachment list to use for the message text. The value 1 indicates the first
attachment.

• attachment|filelist_ID – An optional parameter that specifies the attachment

or list of attachments for the message. If the parameter is a string, the string
specifies the path (in generic format) of a file to attach to the message. If the
parameter is a long integer, the value specified ID of the file list that
contains the files to attach to the message.

• reply_to_list – An optional parameter that specifies the ID of the address list

to which the replies to the message will be sent.

• property_list – An optional parameter that specifies the ID of the property

list that contains properties to apply to the message. This allows you to
apply additional MAPI properties that are not exposed through the MAPI
functions.

Return value An integer corresponding to one of the following constants:

MAPI_SUCCESS MAPI_LOGIN_FAILURE
MAPI_AMBIGUOUS_RECIPIENT MAPI_TEXT_TOO_LARGE
MAPI_ATTACHMENT_NOT_FOUND MAPI_TOO_MANY_FILES
MAPI_ATTACHMENT_OPEN_FAILURE MAPI_TOO_MANY_RECIPIENTS
MAPI_BAD_RECIPTYPE MAPI_UNKNOWN_RECIPIENT
MAPI_INSUFFICIENT_MEMORY MAPI_USER_ABORTED
MAPI_INVALID_RECIPS MAPI_BAD_MAPI_PROPERTIES
MAPI_BODY_INDEX_OUT_OF_RANGE MAPI_UNKNOWN

FUNCTION LIBRARY REFERENCE 425

MA PI _S E N D ( )

Comments When using an attachment for the message body, the file attachment will
typically be in text, HTML, or RTF format. The attachment used for the
message text will not appear as an attachment for the message.

Examples The following example uses the MAPI_Send() function to send a message
to the members of the specified address list.

local integer address_count;

local integer answer;
local integer send_result;
local boolean result;
local string count_string;

{Count the number of addresses in the address list.}

address_count = MAPI_CountAddresses('Address List');
count_string = str(address_count);

{Verify that the user wants to send the message.}

answer = ask("This message will be sent to " + count_string +
➥ " users. Do you want to send the message?", "Yes", "No", "");
if answer = ASKBUTTON1 then
{Send the message.}
send_result = MAPI_Send('Address List','Subject','Message Text');
if send_result <> MAPI_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = MAPI_DestroyAddressList('Address List');
end if;
end if;

426 F U N C T I O N L I B R A R Y R E F E R E N C E
 M A P I_ S E N D D I A L O G ()

MAPI_SendDialog()
Description The MAPI_SendDialog() function sends a message to the members of a
specified address list. A mail dialog will be displayed for each message
sent.

Syntax MAPI_Send(address_list_ID, subject, message_text {,attachment|filelist_ID}

{, reply_to_list}{, property_list})

Parameters • address_list_ID – The ID of the address list to which the message will be
sent.

• subject – A string specifying the subject line of the message.

• message_text – A text field or variable containing the text for the message.
This parameter can also be an integer specifying which attachment in the
attachment list to use for the message text. The value 1 indicates the first
attachment.

• attachment|filelist_ID – An optional parameter that specifies the attachment

or list of attachments for the message. If the parameter is a string, the string
specifies the path (in generic format) of a file to attach to the message. If the
parameter is a long integer, the value specified ID of the file list that
contains the files to attach to the message.

• reply_to_list – An optional parameter that specifies the ID of the address list

to which the replies to the message will be sent.

• property_list – An optional parameter that specifies the ID of the property

list that contains properties to apply to the message. This allows you to
apply additional MAPI properties that are not exposed through the MAPI
functions.

Return value An integer corresponding to one of the following constants:

MAPI_SUCCESS MAPI_LOGIN_FAILURE
MAPI_AMBIGUOUS_RECIPIENT MAPI_TEXT_TOO_LARGE
MAPI_ATTACHMENT_NOT_FOUND MAPI_TOO_MANY_FILES
MAPI_ATTACHMENT_OPEN_FAILURE MAPI_TOO_MANY_RECIPIENTS
MAPI_BAD_RECIPTYPE MAPI_UNKNOWN_RECIPIENT
MAPI_INSUFFICIENT_MEMORY MAPI_USER_ABORTED
MAPI_INVALID_RECIPS MAPI_BAD_MAPI_PROPERTIES
MAPI_BODY_INDEX_OUT_OF_RANGE MAPI_UNKNOWN

FUNCTION LIBRARY REFERENCE 427

MA PI _S E N D D I A L O G ( )

Comments When using an attachment for the message body, the file attachment will
typically be in text, HTML, or RTF format. The attachment used for the
message text will not appear as an attachment for the message.

Examples The following example uses the MAPI_SendDialog() function to send a

message to the members of the specified address list.

local integer send_result;

local boolean result;

{Send the message.}

send_result = MAPI_SendDialog('Address List','Subject',
➥ 'Message Text');
if send_result <> MAPI_SUCCESS then
error "An error occurred. Unable to send the message.";
else
{Message was sent successfully.}
result = MAPI_DestroyAddressList('Address List');
end if;

428 F U N C T I O N L I B R A R Y R E F E R E N C E
 Menu bar function library
Refer to Chapter 16, Use the functions in this library to work with command-based menus for an
“Command-based application. This library contains the following functions:
Menus,” in Volume 1 of
the Dexterity Program- • MenuBar_AddMenu()
mer’s Guide for more • MenuBar_RemoveAllMenus()
information. • MenuBar_RemoveMenu()

FUNCTION LIBRARY REFERENCE 429

M E N U B A R _ A D D M E N U ( )

MenuBar_AddMenu()
Description The MenuBar_AddMenu() function adds a command list to the menu bar.

Syntax MenuBar_AddMenu(command_list_tag {, position})

Parameters • command_list_tag – The integer tag value specifying the command list to
add to the menu bar.

• position – An optional integer that specifies the location of the menu. The
value 1 indicates the left-most position. The value 0 specifies the menu will
be added on the right end of the menu bar.

Return value An integer indicating whether the menu was added. The value 1 indicates
the menu was added, while the value 0 indicates it was not.

Comments When a menu is added at a specified position, any menus already added
are shifted one position to the right to make room for the new menu.

Examples The following example adds the Windows menu to the menu bar in the
fourth position. The command list added is the built-in command list for
the list of open windows in the application.

local integer result;

result = MenuBar_AddMenu(Command_GetTag(command cmdWindowList), 4);

430 F U N C T I O N L I B R A R Y R E F E R E N C E
 M E N U B A R _ R E M O V E A L L M E N U S ()

MenuBar_RemoveAllMenus()
Description The MenuBar_RemoveAllMenus() function removes all menus from the
menu bar.

Syntax MenuBar_RemoveAllMenus()

Parameters • None

Return value A boolean. The value false indicates the menus were removed, while the
value true indicates they were not.

Examples The following example removes all of the menus for the application.

local boolean result;

result = MenuBar_RemoveAllMenus();

FUNCTION LIBRARY REFERENCE 431

M E N U B A R _ R E M O V E M E N U ( )

MenuBar_RemoveMenu()
Description The MenuBar_RemoveMenu() function removes the specified menu from
the menu bar.

Syntax MenuBar_RemoveMenu(command_list_tag)

Parameters • command_list_tag – The integer tag value specifying the command list used
for the menu that is to be removed from the menu bar.

Return value A boolean. The value false indicates the menu was successfully removed.
The value true indicates the menu was not removed.

Examples The following example removes the View menu from the menu bar. The
menu was defined using the command list CL_View on the Main Menu
form.

local boolean result;

local integer menu_tag;

menu_tag = Command_GetTag(command CL_View of form 'Main Menu');

result = MenuBar_RemoveMenu(menu_tag);

432 F U N C T I O N L I B R A R Y R E F E R E N C E
Menu function library
Use the functions in this library when working with menus. This library
contains the following function:

• Menu_Invoke()

FUNCTION LIBRARY REFERENCE 433

M E N U _ I N V O K E ( )

Menu_Invoke()
Description The Menu_Invoke() function causes a menu item to be invoked, just as if it
had been selected by the user.

Syntax Menu_Invoke(action)

Parameters • action – An integer that specifies the action to perform. Use one of the
following constants:

Constant
MENU_ACTION_PRINT
MENU_ACTION_PRINTSETUP
MENU_ACTION_HELPCONTENTS
MENU_ACTION_HELPSEARCH
MENU_ACTION_HELPFIELD
MENU_ACTION_HELPWINDOW
MENU_ACTION_HELPABOUT
MENU_ACTION_HELPONHELP
MENU_ACTION_SHOWREQUIRED
MENU_ACTION_UNDO
MENU_ACTION_CUT
MENU_ACTION_COPY
MENU_ACTION_PASTE
MENU_ACTION_CLEAR
MENU_ACTION_SELECTALL
MENU_ACTION_DELETEROW
MENU_ACTION_INSERTROW
Description
Print menu item
Print Setup menu item
Help Contents menu item
Help Search menu item
Field Help menu item
Window Help menu item
About menu item
Help on Help menu item
Show Required menu item
Undo menu item
Cut menu item
Copy menu item
Paste menu item
Clear menu item
Select All menu item
Delete Row menu item
Insert Row menu item

Return value A boolean indicating whether the menu item was invoked. True indicates it
was invoked, while false indicates it was not.

Comments The menu item to be invoked must be in the set of menu items for the
application. You can’t invoke a menu item that isn’t included in a menu.
Menu items will be invoked, regardless of whether they are enabled or
disabled in the menu.

Examples The following example displays the contents of the current help file.
local boolean result;

result = Menu_Invoke(MENU_ACTION_HELPCONTENTS);

434 F U N C T I O N L I B R A R Y R E F E R E N C E
 OLE function library
Refer to Appendix C, Use the functions in this library when implementing OLE container support
“OLE Container,”, in in your application. This library contains the following functions:
the Stand-alone Appli-
cation Guide for more • OLE_CloseNote()
information about • OLE_DeleteNote()
implenting OLE con- • OLE_Exit()
tainer support. • OLE_IsNoteEnabled()
• OLE_OpenNote()
• OLE_SaveNote()

FUNCTION LIBRARY REFERENCE 435

O L E _ C L O S E N O T E ( )

OLE_CloseNote()
Description The OLE_CloseNote() function closes the specified OLE container file. The
OLE container application will remain open.

Syntax OLE_CloseNote(OLE_doc_path, save_flag)

Parameters • OLE_doc_path – The complete path of the OLE container file you want to
close. The path is in generic format.

• save_flag – A string specifying whether the objects in the OLE container file
should be saved when the file is closed. Passing the string “true” indicates
the objects should be saved, while “false” indicates the objects should not
be saved.

Return value The boolean value true.

Examples The following example closes the OLE container file ID1001.OLE, saving
any changes to the objects stored in the file.

local boolean result;

result = OLE_CloseNote(":C:RESM/OLE/ID1001.OLE","true");

436 F U N C T I O N L I B R A R Y R E F E R E N C E
 O L E _ D E L E T E N O T E ()

OLE_DeleteNote()
Description The OLE_DeleteNote() function closes the specified OLE container file (if it
is open) and deletes the file. The OLE container application will remain
open.

Syntax OLE_DeleteNote(OLE_doc_path)

Parameters • OLE_doc_path – The complete path of the OLE container file you want to
delete. The path is in generic format.

Return value The boolean value true.

Examples The following example deletes the OLE container file ID1001.OLE.

local boolean result;

result = OLE_DeleteNote(":C:RESM/OLE/ID1001.OLE");

FUNCTION LIBRARY REFERENCE 437

O L E _ E X I T ()

OLE_Exit()
Description The OLE_Exit() function closes the OLE container application.

Syntax OLE_Exit()

Parameters • None

Return value The boolean value true.

Examples The following example closes the OLE container application.

local boolean result;

result = OLE_Exit();

438 F U N C T I O N L I B R A R Y R E F E R E N C E
 O L E _ I S N O T E E N A B L E D ()

OLE_IsNoteEnabled()
Description The OLE_IsNoteEnabled() function ascertains whether the current
operating environment can support the OLE container application.

Syntax OLE_IsNoteEnabled()

Parameters • None

Return value A boolean value indicating whether the OLE container application can be
supported; true if the container application can be supported, false if it
can’t.

Examples The following example ascertains whether the OLE container application
can be supported. If it can be, the Picture button is enabled.

local boolean result;

result = OLE_IsNoteEnabled();
if result = true then
enable field Picture;
else
disable field Picture;
end if;

FUNCTION LIBRARY REFERENCE 439

O L E _ O P E N N O T E ()

OLE_OpenNote()
Description The OLE_OpenNote() function opens the specified OLE container file and
sets the window title of the OLE container application. If the OLE container
application wasn’t already open, it will be opened.

Syntax OLE_OpenNote(OLE_doc_path, window_title)

Parameters • OLE_doc_path – The complete path of the OLE container file to open. The
path is in generic format.

• window_title – A string containing the text that will appear in the title bar of
the OLE container application.

Return value The boolean value true.

Comments The OLE container application opens the container file for exclusive use.
This means that only one user at a time can access a specific OLE container
file.

Examples The following example opens the OLE container file ID1001.OLE,
specifying “House ID 1001” as the window title to display.

local boolean result;

result = OLE_OpenNote(":C:RESM/OLE/ID1001.OLE","House ID 1001");

440 F U N C T I O N L I B R A R Y R E F E R E N C E
 O L E _ S A V E N O T E ()

OLE_SaveNote()
Description The OLE_SaveNote() function saves the specified OLE container file. The
OLE container file and OLE container application will remain open.

Syntax OLE_SaveNote(OLE_doc_path)

Parameters • OLE_doc_path – The complete path of the OLE container file to save. The
path is in generic format.

Return value The boolean value true.

Examples The following example saves the OLE container file ID1001.OLE.

local boolean result;

result = OLE_SaveNote(":C:RESM/OLE/ID1001.OLE");

FUNCTION LIBRARY REFERENCE 441

442 F U N C T I O N L I B R A R Y R E F E R E N C E
 Path function library
Refer to Chapter 2, Use the functions in this library when working with pathnames. This
“Pathnames,” in the library contains the following functions:
Dexterity Stand-alone
Application Guide for • Path_ChangeDefault()
more information • Path_CreateFolder()
about pathnames. • Path_DoesExist()
• Path_GetForApp()
• Path_MakeGeneric()
• Path_MakeNative()
• Path_ParseFileFromPath()
• Path_ParsePathFromPath()
• Path_SelectPathname()

FUNCTION LIBRARY REFERENCE 443

P A T H _ C H A N G E D E F A U L T ( )

Path_ChangeDefault()
Description The Path_ChangeDefault() function changes the default location for tables
with a Pathname table series.

Syntax Path_ChangeDefault(pathname)

Parameters • pathname – A string specifying the alternate pathname. This must be a

generic pathname.

Return value The boolean value true.

Comments By default, tables in the Pathname series are stored in the same location as
the application dictionary. Some Dexterity applications use the defaults file
to store the path to tables in the Pathname series and use the
Path_ChangeDefault() function to specify the location. The
Defaults_Write() and Defaults_Read() functions are used to store a
pathname in the Dexterity defaults file.

Examples In the following example, a local variable is used to indicate a new

pathname that’s entered by the user while the application is running.

local string l_Pathname;

local boolean result;

l_Pathname = New_Pathname of window Locate_Pathnames;

result = Path_ChangeDefault(l_Pathname);

Related items Commands

Defaults_Read(), Defaults_Write(), Path_MakeGeneric()

444 F U N C T I O N L I B R A R Y R E F E R E N C E
 P A T H _ C R E A T E F O L D E R ()

Path_CreateFolder()
Description The Path_CreateFolder() function creates a new folder or directory. When
used with the savefile() function, a dialog box will appear, allowing the
location and name of the new directory or folder to be specified by the user.

Syntax Path_CreateFolder(pathname)

Parameters • pathname – A string containing the entire path and name of the new
directory or folder. This path must exist at the operating system, or the
directory or folder won’t be created. When the savefile() function is used,
the folder/directory location and name should be returned to pathname.

Return value An integer that returns the value 0 if the directory was created successfully,
or the value 1 if an error occurred.

Comments To open a dialog box and allow the user to specify a default location, use the
savefile() function. Normally, this function will display a dialog box used to
specify a file name and location; however, when used with the
Path_CreateFolder() function, a folder or directory can be created instead.

If you use the savefile() function, ignore the file format selection in the dialog box.
It doesn’t apply when creating a folder.

Examples The following example displays a dialog box, prompting the user to enter
the name of a new folder. The pathname (l_location) is returned to the
Path_CreateFolder() function, and the folder is created at that location.

local string l_location, l_Pathname;

local integer l_result, l_filetype;

if savefile ("Enter a folder name:", l_filetype, l_location) then

l_result = Path_CreateFolder(l_location);
end if;

Related items Commands

savefile(), Path_SelectPathname()

FUNCTION LIBRARY REFERENCE 445

P A T H _ D O E S E X I S T ( )

Path_DoesExist()
Description The Path_DoesExist() function indicates whether the specified path exists.

Syntax Path_DoesExist(path)

Parameters • path – A string containing the path to verify. The path must be in native
format.

Return value A boolean. True indicates the path exists, while false indicates it does not.

Examples The following example uses the Path_DoesExist() function to verify that
the path to the RESM directory exists.

local boolean result;

result = Path_DoesExist("C:\RESM\");

Related items Commands

File_Probe()

446 F U N C T I O N L I B R A R Y R E F E R E N C E
 P A T H _ G E T F O R A P P ()

Path_GetForApp()
Description The Path_GetForApp() function returns the generic path of various
components of the current installation, such as the runtime engine or
launch file.

Syntax Path_GetForApp(option)

Parameters • option – An integer indicating which path to return:

Constant Value Description

PATH_EXEFOLDER 1 The path of the folder containing the runtime
engine (Dynamics.exe).
PATH_SETFOLDER 2 In test mode, the path of the folder containing the
application dictionary currently in use. With the
runtime engine, the path of the folder containing
the launch file used to start the application.
PATH_DATAFOLDER 3 The path to the “Data” folder for the installation.
Files writable by the user are stored in this folder.
PATH_USERDEXINIFILE 4 The path of the user-specific Dex.ini file currently
being used. If per-user defaults files are not active,
the path to the global Dex.ini is returned.
PATH_SETFILE 5 The path of the launch file (.set file) currently
being used.
PATH_GLOBALDEXINIFILE 6 The path to the global Dex.ini file, found in the
“Data” folder for the installation.

Return value A string containing the path requested in generic format.

Comments The path that’s returned is in a generic format. Generic pathnames use a
colon (:) before and after DOS drive letters. The characters that separate
folders and directories are forward slashes (/).

Native pathname Generic pathname

C:\DEX\TOOLS\ :C:DEX/TOOLS/

Examples In the following example, the local string variable is used to store the
pathname of the folder containing the runtime engine.
local string pathname;

pathname = Path_GetForApp(PATH_EXEFOLDER);
'(L) Dictionary Location' of window 'Dictionary Maintenance' =
➥ pathname;

FUNCTION LIBRARY REFERENCE 447

P A T H _ G E T F O R A P P ()

Related items Commands

Path_MakeNative(), File_GetTempDirectory()

448 F U N C T I O N L I B R A R Y R E F E R E N C E
 P A T H _ M A K E G E N E R I C ()

Path_MakeGeneric()
Description The Path_MakeGeneric() function converts a native pathname to a generic
pathname.

Syntax Path_MakeGeneric(pathname)

Parameters • pathname – A string containing a pathname in native format.

Return value A string containing the pathname in generic format.

Comments Generic pathnames have been designed to allow several different operating
environments access to the same set of data in a Dexterity application.
Generic pathnames use a colon (:) before and after DOS drive letters. The
characters that separate folders and directories are forward slashes (/).

Native pathname Generic pathname

C:\DEX\TOOLS\ :C:DEX/TOOLS/

Examples The following example converts a native pathname to a generic pathname

and stores the result in a table at a network location, where workstations
can share pathname information.

local string l_path;

{Set the local variable to the pathname the user enters.}

l_path = 'Native_Pathname';
{Convert the pathname to a generic pathname.}
l_path = Path_MakeGeneric(l_path);
Generic_Pathname of table Pathnames = l_path;
save table Pathnames;

Related items Commands

Path_MakeNative()

FUNCTION LIBRARY REFERENCE 449

P A T H _ M A K E N A T I V E ( )

Path_MakeNative()
Description The Path_MakeNative() function converts a generic pathname to a native
pathname.

Syntax Path_MakeNative(pathname)

Parameters • pathname – A string containing the pathname in generic format.

Return value A string containing the pathname in a format native to the operating
system.

Comments Generic pathnames have been designed to allow several different operating
environments access to the same set of data in a Dexterity application.
Generic pathnames use a colon (:) before and after DOS drive letters. The
characters that separate folders and directories are forward slashes (/).

Native pathname Generic pathname

C:\DEX\TOOLS\ :C:DEX/TOOLS/

Examples In the following example, a generic pathname is returned using the

Path_SelectPathname() function, then converted to a native pathname
using Path_MakeNative().

local boolean result;

local string l_Path;

{Open the file dialog box and return the generic pathname.}
result = Path_SelectPathname(l_Path);
if result = true then
'(L) Pathname' = Path_MakeNative(l_Path);
end if;

Related items Commands

Path_MakeGeneric()

450 F U N C T I O N L I B R A R Y R E F E R E N C E
 P A T H _ P A R S E F I L E F R O M P A T H ()

Path_ParseFileFromPath()
Description The Path_ParseFileFromPath() function parses a file’s operating system
name from a generic path.

Syntax Path_ParseFileFromPath(file_path)

Parameters • file_path – A string containing the generic pathname from which the file
name will be parsed.

Return value A string containing the operating system name of the file.

Comments The file_path must be in a generic format prior to parsing it using

Path_ParseFileFromPath(). All Dexterity commands that return pathnames
will do so in generic format. The following illustration shows a generic path
and the resulting operating system name that’s parsed:

A generic pathname

:C:DEXAPPS/SYSTEM/SYSTEM.DIC

The file’s O/S

name returned
by this function.

Examples This example parses the operating system name from a generic path
returned by the getfile() function.

local string l_path;

if getfile("Select a file", TEXTFILE, l_path) then

'File Name' = Path_ParseFileFromPath(l_path);
end if;

Related items Commands

getfile(), Path_MakeGeneric()

FUNCTION LIBRARY REFERENCE 451

P A T H _ P A R S E P A T H F R O M P A T H ( )

Path_ParsePathFromPath()
Description The Path_ParsePathFromPath() function parses the path name from a
generic path.

Syntax Path_ParsePathFromPath(file_path)

Parameters • file_path – A string containing the generic pathname from which the path
will be parsed.

Return value A string containing the path where the file is located.

Comments The file_path must be in a generic format prior to parsing it using

Path_ParsePathFromPath(). All Dexterity commands that return
pathnames will do so in generic format. The following illustration shows a
generic path and the resulting operating system name that’s parsed:

A generic pathname

:C:DEXAPPS/SYSTEM/SYSTEM.DIC

The path
returned by this
function.

Examples This example parses the path from a generic path returned by the getfile()
function.

local string l_path;

if getfile("Select a file", TEXTFILE, l_path) then

'Path' = Path_ParsePathFromPath(l_path);
end if;

Related items Commands

getfile(), Path_MakeGeneric()

452 F U N C T I O N L I B R A R Y R E F E R E N C E
 P A T H _ S E L E C T P A T H N A M E ()

Path_SelectPathname()
Description The Path_SelectPathname() function displays a file dialog box, allowing a
user to indicate the location of a file, and returns a generic pathname to that
location.

Syntax Path_SelectPathname(pathname)

Parameters • pathname – A string variable to which the pathname selected by the user.
The pathname is returned in generic format. You can set the value of this
variable before calling the Path_SelectPathname() function to specify the
default location that will appear in the dialog box. You supply the path in
native format. Be sure to end the path with the trailing slash (\).

Return value A boolean indicating one of the following situations:

Value Description
false Cancel was clicked.
true OK was clicked.

Comments The pathname that’s returned to pathname is in generic format. Generic

pathnames use a colon (:) before and after DOS drive letters. The characters
that separate folders and directories are forward slashes (/).

Native pathname Generic pathname

C:\DEX\TOOLS\ :C:DEX/TOOLS/

The getfile() function allows a user to return a pathname for a particular file by
selecting that file from a list of files with specific file type extensions, such as .DIC
or .MAC.

Examples The following example shows how a pathname can be set to indicate the
location of a file. Note that the returned generic pathname is converted to a
native pathname using the Path_MakeNative() function.
local boolean result;
local string l_Path;

result = Path_SelectPathname(l_Path);
if result = true then
{Convert the pathname to a native format.}
'Data Pathname' = Path_MakeNative(l_Path);
end if;

FUNCTION LIBRARY REFERENCE 453

P A T H _ S E L E C T P A T H N A M E ( )

The following example displays a dialog allowing the user to select a path.
The default location displayed in the dialog is set before the dialog is
opened.

local boolean result;

local string l_Path;

{Set the default location}

l_Path = "C:\Data\";

result = Path_SelectPathname(l_Path);
if result = true then
{Convert the pathname to a native format.}
'Data Pathname' = Path_MakeNative(l_Path);
end if;

Related items Commands

getfile(), Path_MakeNative()

454 F U N C T I O N L I B R A R Y R E F E R E N C E
Printer function library
Use the functions in this library when implementing named printer support
for your application. This library contains the following functions:

• Printer_Define()
• Printer_GetName()
• Printer_SetDestination()

FUNCTION LIBRARY REFERENCE 455

P R I N T E R _ D E F I N E ( )

Printer_Define()
Description The Printer_Define() function allows a user to define a new named printer
destination. This function opens the Print Setup dialog box in which the
user can select a printer, the print orientation, paper size and other printer
options.

Syntax Printer_Define(printer_settings)

Parameters • printer_settings – A text field into which all the printer-related options
selected by the user are stored. The text field must have a keyable length of
at least 5004 characters. The stored data includes information such as the
printer’s name, the desired paper orientation, and whether to use a header
page.

While the printer_settings field must be a text field, the data is stored in it will be
unreadable if displayed.

Return value A boolean value that is set depending upon which button was clicked to
close the Print Setup window. True indicates the OK button was clicked.
False indicates the Cancel button was clicked.

Comments The data stored in the printer_settings parameter is typically saved in a table
for use in the printer clause of the run report and run report with name
statements.

Examples See the Printer_GetName() function example.

Related items Commands

Printer_GetName(), run report, run report with name

456 F U N C T I O N L I B R A R Y R E F E R E N C E
 P R I N T E R _ G E T N A M E ()

Printer_GetName()
Description The Printer_GetName() function returns the name of a named printer
defined using the Printer_Define() function.

Syntax Printer_GetName(printer_settings)

Parameters • printer_settings – A text field containing the printer-related options selected

by the user when the named printer was defined.

While the printer_settings field must be a text field, the data is stored in it will be
unreadable if displayed.

Return value A string containing the name of the printer associated with the specified
printer_settings parameter.

Examples The following example uses the Printer_Define() function to open the Print
Setup window and allow a user to define a named printer. If the user clicks
OK to close the Print Setup window, the Printer_GetName() function is
used to retrieve the name of the printer. Then, the printer’s name and the
text field containing all of the defined printer options are saved in the
Printer_Options table.

local string l_name;

local boolean l_result;

l_result = Printer_Define(Printer_Settings of table Printer_Options).

if l_result then
l_name = Printer_GetName(Printer_Settings of table
➥ Printer_Options);
Printer_Name of table Printer_Options = l_name;
save table Printer_Options;
end if;

Related items Commands

Printer_Define(), run report, run report with name

FUNCTION LIBRARY REFERENCE 457

P R I N T E R _ S E T D E S T I N A T I O N ( )

Printer_SetDestination()
Description The Printer_SetDestination() function changes the default printer for the
current application to the one specified in the printer_settings parameter.

Syntax Printer_SetDestination(printer_settings)

Parameters • printer_settings – A text field containing the printer-related options selected

by the user when the named printer was defined.

Return value A boolean value indicating whether the current printer was changed. True
indicates the current printer was changed. False indicates it wasn’t.

Comments This function can be useful if you are creating a custom application for
which the reports must always be printed to a specific printer.

Use this function with caution. It changes the default printer setting for the current
application, not just the current report.

Instead of using this function to change the application’s default printer

destination, we suggest you specify named printers only on a report-by-
report basis. This can be done using the printer clause of the run report or
run report with name statement.

Examples The following example uses the Printer_SetDestination() function to

change the application’s default printer to one selected in a local drop-
down list named printer_list. This list was filled with printer names from
the Printer_Options table. If the default printer couldn’t be set, a warning is
displayed, indicating that the default printer hasn’t been changed.
local boolean l_result;
local string l_name;

l_name = itemname('(L) printer_list', '(L) printer_list');

{Set the table's key and retrieve the matching record.}
Printer_Name of table Printer_Options = l_name;
get table Printer_Options;
l_result = Printer_SetDestination(Settings of table Printer_Options);
{If the printer change was not successful, warn the user.}
if not l_result then
warning "Your default printer hasn't changed.";
end if;

Related items Commands

Printer_GetName(), run report, run report with name

458 F U N C T I O N L I B R A R Y R E F E R E N C E
Registry function library
Use the functions in this library when working with data in the Windows
registry. This library contains the following functions:

• Registry_DeleteKey()
• Registry_DeleteValue()
• Registry_GetProtectedString()
• Registry_GetValue()
• Registry_SetKeyValue()
• Registry_SetProtectedKeyString()

FUNCTION LIBRARY REFERENCE 459

R E G I S T R Y _ D E L E T E K E Y ( )

Registry_DeleteKey()
Description The Registry_DeleteKey() function deletes the specified key from the
registry.

Syntax Registry_DeleteKey(subtree, key {, error_code})

Parameters • subtree – An integer specifying the registry subtree. The value corresponds
to one of the following constants:

Constant
REGKEY_CLASSES_ROOT
REGKEY_CURRENT_USER
REGKEY_LOCAL_MACHINE
REGKEY_CURRENT_CONFIG
Description
HKEY_CLASSES_ROOT subtree
HKEY_CURRENT_USER subtree
HKEY_LOCAL_MACHINE subtree
HKEY_CURRENT_CONFIG subtree

• key – A string specifying the path of the key to delete from the registry. The
key cannot have any subkeys. If it does, you must delete the subkeys first.

• error_code – An optional returned long integer that contains the error code
that was returned. The error codes are defined in the WinError.h file of the
Windows SDK.

Return value A boolean indicating the result. The value true indicates the function
succeeded, while false indicates it did not.

Examples The following example deletes the “LicenseTerms” subkey for the specified
path in the registry.

local boolean result;

local long error_code;

result = Registry_DeleteKey(REGKEY_LOCAL_MACHINE,
➥ "SOFTWARE\Microsoft\Dynamics\4.0\Setup\LicenseTerms\", error_code);

if result = false then

{Display the error that occurred}
warning "An error occurred deleting the registry key: " +
➥ string(error_code);
end if;

460 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E G I S T R Y _ D E L E T E V A L U E ()

Registry_DeleteValue()
Description The Registry_DeleteValue() function deletes the specified value from the
registry.

Syntax Registry_DeleteValue(subtree, key, value_name {, error_code})

Parameters • subtree – An integer specifying the registry subtree. The value corresponds
to one of the following constants:

Constant
REGKEY_CLASSES_ROOT
REGKEY_CURRENT_USER
REGKEY_LOCAL_MACHINE
REGKEY_CURRENT_CONFIG
Description
HKEY_CLASSES_ROOT subtree
HKEY_CURRENT_USER subtree
HKEY_LOCAL_MACHINE subtree
HKEY_CURRENT_CONFIG subtree

• key – A string specifying the path of the key that contains the value to
delete. The path value begins with the key name followed by the subkey
names. The values in the path are separated by backslash (\) characters.

• value_name – The name of the value to delete.

• error_code – An optional returned long integer that contains the error code
that was returned. The error codes are defined in the WinError.h file of the
Windows SDK.

Return value A boolean indicating the result. The value true indicates the function
succeeded, while false indicates it did not.

Examples The following example deletes the value “LicenseTermsVersion” from the
specified path in the registry.
local boolean result;
local long error_code;

result = Registry_DeleteValue(REGKEY_LOCAL_MACHINE,
➥ "SOFTWARE\Microsoft\Dynamics\4.0\Setup\LicenseTerms\",
➥ "LicenseTermsVersion", error_code);

if result = false then

{Display the error that occurred}
warning "An error occurred deleting the registry value: " +
➥ string(error_code);
end if;

FUNCTION LIBRARY REFERENCE 461

R E G I S T R Y _ G E T P R O T E C T E D S T R I N G ( )

Registry_GetProtectedString()
Description The Registry_GetProtectedString() function retrieves and decrypts the
specified value from the HKEY_CURRENT_USER subtree and key.

Syntax Registry_GetProtectedString(key, value_name, value {, entropy}

{, error_code})

Parameters • key – A string specifying the path of the key that contains the value to
retrieve. The path value begins with the key name followed by the subkey
names. The values in the path are separated by backslash (\) characters.

• value_name – The name of the value to retrieve.

• value – A returned string containing the value.

• entropy – An optional string that contains additional characters, such as a

password, that are used when decrypting the value. If an entropy value was
used when the protected string was set, that same entropy value must be
used when the string is read from the registry.

• error_code – An optional returned long integer that contains the error code
that was returned. The error codes are defined in the WinError.h file of the
Windows SDK.

Return value A boolean indicating the result. The value true indicates the function
succeeded, while false indicates it did not.

Examples The following example retrieves the “Password” value of the specified key
in the HKEY_CURRENT_USER subtree of the registry. The entropy value
“12345” was used when the key was written, so this same entropy value is
used when the key is retrieved. If the password is retrieved, it is displayed
in a warning dialog.

local boolean result;

local long error_code;
local string string_value;

result = Registry_GetProtectedString(
➥ "SOFTWARE\Microsoft\Dynamics GP\", "Password", string_value,
➥ "12345", error_code);

462 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E G I S T R Y _ G E T P R O T E C T E D S T R I N G ()

if result = false then

{Display the error that occurred}
warning "An error occurred retrieving the registry value: " +
➥ string(error_code);
else
warning "Password: " + string_value;
end if;

FUNCTION LIBRARY REFERENCE 463

R E G I S T R Y _ G E T V A L U E ()

Registry_GetValue()
Description The Registry_GetValue() function retrieves the specified value from the
registry.

Syntax Registry_GetValue(subtree, key, value_name, value {, error_code})

Parameters • subtree – An integer specifying the registry subtree. The value corresponds
to one of the following constants:

Constant
REGKEY_CLASSES_ROOT
REGKEY_CURRENT_USER
REGKEY_LOCAL_MACHINE
REGKEY_CURRENT_CONFIG
Description
HKEY_CLASSES_ROOT subtree
HKEY_CURRENT_USER subtree
HKEY_LOCAL_MACHINE subtree
HKEY_CURRENT_CONFIG subtree

• key – A string specifying the path of the key that contains the value to
retrieve. The path value begins with the key name followed by the subkey
names. The values in the path are separated by backslash (\) characters.

• value_name – The name of the value to return.

• value – The value returned from the registry. The data type depends on the
type of value being retrieved from the registry.

• error_code – An optional returned long integer that contains the error code
that was returned. The error codes are defined in the WinError.h file of the
Windows SDK.

Return value A boolean indicating the result. The value true indicates the function
succeeded, while false indicates it did not.

Examples The following example retrieves a string value from the registry that
contains the location of the default instance of Dexterity. The complete path
of the value is:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Dexterity\1033\
DEFAULT\SETUP\AppPath

local string string_value;

local boolean result;
local long error_code;

464 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E G I S T R Y _ G E T V A L U E ()

{Retrieve a value from the registry}

result = Registry_GetValue(REGKEY_LOCAL_MACHINE,
➥ "SOFTWARE\Microsoft\Dexterity\1033\DEFAULT\SETUP\", "AppPath",
➥ string_value, error_code);

if result = true then

{Value was successfully returned}
warning string_value;
else
{Display the error that occurred}
warning "An error occurred reading the registry value: " +
➥ string(error_code);
end if;

FUNCTION LIBRARY REFERENCE 465

R E G I S T R Y _ S E T K E Y V A L U E ( )

Registry_SetKeyValue()
Description The Registry_SetKeyValue() function sets the specified value in the
registry.

Syntax Registry_SetKeyValue(subtree, key, value_name, value {, error_code})

Parameters • subtree – An integer specifying the registry subtree. The value corresponds
to one of the following constants:

Constant
REGKEY_CLASSES_ROOT
REGKEY_CURRENT_USER
REGKEY_LOCAL_MACHINE
REGKEY_CURRENT_CONFIG
Description
HKEY_CLASSES_ROOT subtree
HKEY_CURRENT_USER subtree
HKEY_LOCAL_MACHINE subtree
HKEY_CURRENT_CONFIG subtree

• key – A string specifying the path of the key that contains the value to set.
The path value begins with the key name followed by the subkey names.
The values in the path are separated by backslash (\) characters. If the path
doesn’t exist in the registry, it will be created.

• value_name – The name of the value to set.

• value – The value to set. The data type depends on the type of value being
set in the registry.

• error_code – An optional returned long integer that contains the error code
that was returned. The error codes are defined in the WinError.h file of the
Windows SDK.

Return value A boolean indicating the result. The value true indicates the function
succeeded, while false indicates it did not.

Examples The following example sets the UserName value of the specified registry
key to “Steve”.

local boolean result;

local long error_code;

result = Registry_SetKeyValue(REGKEY_LOCAL_MACHINE,
➥ "SOFTWARE\Microsoft\Dynamics\4.0\Application\", "UserName",
➥ "Steve", error_code);

466 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E G I S T R Y _ S E T K E Y V A L U E ()

if result = false then

{Display the error that occurred}
warning "An error occurred setting the registry value: " +
➥ string(error_code);
end if;

FUNCTION LIBRARY REFERENCE 467

R E G I S T R Y _ S E T P R O T E C T E D K E Y S T R I N G ( )

Registry_SetProtectedKeyString()
Description The Registry_SetProtectedKeyString() function encrypts and sets the
specified string value for the HKEY_CURRENT_USER subtree and key.

Syntax Registry_SetProtectedKeyString(key, value_name, value {, entropy}

{, error_code})

Parameters • key – A string specifying the path of the key that contains the value to set.
The path value begins with the key name followed by the subkey names.
The values in the path are separated by backslash (\) characters. If the path
doesn’t exist in the registry, it will be created.

• value_name – The name of the value to set.

• value – A string containing the value to set.

• entropy – An optional string that contains additional characters, such as a

password, that are used when encrypting the value. If an entropy value is
used when setting a protected string, that same entropy value must be used
when the string is read from the registry.

• error_code – An optional returned long integer that contains the error code
that was returned. The error codes are defined in the WinError.h file of the
Windows SDK.

Return value A boolean indicating the result. The value true indicates the function
succeeded, while false indicates it did not.

Examples The following example sets the “Password” value of the specified key in the
HKEY_CURRENT_USER subtree of the registry. The entropy value “12345”
is used, so this same entropy value must be used when the key is retrieved.
local boolean result;
local long error_code;

result = Registry_SetProtectedKeyString(
➥ "SOFTWARE\Microsoft\Dynamics GP\", "Password", Password of globals,
➥ "12345", error_code);

if result = false then

{Display the error that occurred}
warning "An error occurred setting the registry value: " +
➥ string(error_code);
end if;

468 F U N C T I O N L I B R A R Y R E F E R E N C E
Report function library
Use the functions in this library to create Quick Reports for your
application. Quick Reports are generated completely from sanScript,
making them flexible and fast. They are typically used for reports that must
be produced quickly and won’t require user modifications.

Quick Report concepts

A Quick Report is generated one page at a time. Each page is composed of
bands, which specify areas of the report in which you insert text. A Quick
Report must have at least one band, and typically has one band for each line
of text in the report. Bands are shown in the following illustration.

Reports are composed of

bands. Typically, there is
one band for each line of
text in the report.

The first band of the report always starts in the upper left corner and
extends the width of the page. You specify the band’s height. Once a band is
created, you add text items to it. Typically, you will add only one text item
to the band, but you can add several items if necessary. When you have
finished adding text to the current band, you create a new one. The new
band starts immediately below the previous band, extends the width of the
page, and has the height you specify.

A new band starts

immediately below the
previous band.

When you have added enough bands to fill the page, you must start a new
page and continue the process until the report is complete.

FUNCTION LIBRARY REFERENCE 469

 Creating a Quick Report
This library contains the following functions:

• Report_Begin()
• Report_DoubleLine()
• Report_End()
• Report_GetPageRemaining()
• Report_GetPageSize()
• Report_GetStringWidth()
• Report_NewBand()
• Report_NewPage()
• Report_ReadyToRun()
• Report_SetFont()
• Report_SingleLine()
• Report_WriteText()

When you create a Quick Report, you will typically use these functions in
the following manner:

Refer to the • The Report_Begin() function starts the Quick Report.

Report_Begin()
function for an • The Report_GetPageSize() function returns the dimension of the page.
example script that The values are returned are in points. There are 72 points per inch. You
generates a Quick will use the page dimensions to calculate how many lines will fit on a
Report. page.

• The Report_NewBand() function creates a new band on the report.

• The Report_SetFont() function specifies characteristics of the text that

will be written to the report.

• The Report_WriteText() function writes a text item to the current band.

• When the current page is complete, the Report_NewPage() function

adds a new page to the report.

• The Report_End() function completes the Quick Report.

470 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ B E G I N ()

Report_Begin()
Description The Report_Begin() function starts a Quick Report. This function must be
run before any other functions from the Reports function library.

Syntax Report_Begin(screen_boolean, printer_boolean, filename)

Parameters • screen_boolean – A boolean specifying whether you want the report to be

printed to the screen:

Value Description
true Sends the report to the screen.
false Prevents the report from being sent to the screen.

• printer_boolean – A boolean specifying whether you want the report to be

printed to the printer:

Value Description
true Sends the report to the printer.
false Prevents the report from being sent to the printer.

• filename – A string containing the complete pathname of the text file to

export the report to. You can export the report to a text file only if you are
not sending the report to the screen or to the printer. The pathname must be
in generic format.

Return value A boolean indicating whether the report was started; false if it could be
started, true if it could not.

Comments You must execute the Report_Begin() function before you use any other
functions from the Reports function library.

Reports can be sent to both the screen and the printer by setting the
screen_boolean and printer_boolean variables to true.

FUNCTION LIBRARY REFERENCE 471

R E P O R T _ B E G I N ( )

Examples This procedure script creates a Quick Report that lists all of the current
sellers in Seller_Data file of the Real Estate Sales Manager sample
application. The procedure is called to run in the background.

local boolean result, print_to_screen, print_to_printer;

local string filename;
local integer font, font_size, font_style;
local integer page_height, page_width, lines_per_page, current_line;

{Is a report running? If yes, don't start the Quick Report.}

repeat
result = Report_ReadyToRun();
until result = true;

{Specify where to direct the report. Print it to only the screen.}

print_to_screen = true;
print_to_printer = false;
filename = "";

{Begin the quick report.}

result = Report_Begin(print_to_screen, print_to_printer, filename);

if result = false then

{Report was started successfully.}
{Get the printable page size.}
result = Report_GetPageSize(page_width, page_height);

{Print a report header on the first page.}

{Specify the font characteristics.}
font = FONT_HELVETICA;
font_size = 18; {18 point}
font_style = FONT_STYLE_BOLD;
result = Report_SetFont(font, font_size, font_style);

{Write the header}

result = Report_NewBand(30);
result = Report_WriteText(0,0, page_width, 20, ALIGN_CENTER,
➥ "Current Sellers");

{Add a double line to the header}

result = Report_DoubleLine(0, 21, page_width);

472 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ B E G I N ()

{Print the seller records.}

{Specify the font characteristics.}
font = FONT_HELVETICA;
font_size = 12; {12 point}
font_style = FONT_STYLE_PLAIN;
result = Report_SetFont(font, font_size, font_style);
{Calculate the number of lines of text per page.}
lines_per_page = page_height / 16; {Each line is 16 points.}

{Have already used three lines for the header.}

current_line = 3;

get first table Seller_Data;

while err() <> EOF do
{Is the current page full?}
if current_line > lines_per_page then
{Create a new page.}
result = Report_NewPage();
current_line = 1;
end if;

{Create a new band for the seller information.}

result = Report_NewBand(16);
result = Report_WriteText(0, 0, page_width, 14, ALIGN_LEFT,
➥ 'Seller First Name' of table Seller_Data + " " +
➥ 'Seller Last Name' of table Seller_Data);

{Increment the line count.}

increment current_line;

{Read the next seller record.}

get next table Seller_Data;
end while;

{Finish the Quick Report.}

result = Report_End();
else
{The report wasn't run.}
warning "Report not started.";
end if;

FUNCTION LIBRARY REFERENCE 473

R E P O R T _ D O U B L E L I N E ( )

Report_DoubleLine()
Description The Report_DoubleLine() function draws a double line in the current
band. The double line is three points thick. It consists of a one-point line, a
one-point space and another one-point line.

Syntax Report_DoubleLine(left_pos, vertical_pos, width)

Parameters • left_pos – The location of the left end of the double line, relative to the left
edge of the current band, measured in points.

• vertical_pos – The location of the top of the double line, relative to the top of
the current band, measured in points.

• width – The width of the double line, measured in points.

Return value The boolean value true.

Examples This example draws a double line 100 points wide in the current band. The
line starts at the left edge and 5 points below the top of the band.

local boolean result;

set result to Report_DoubleLine(0, 5, 100);

474 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ E N D ()

Report_End()
Description The Report_End() function completes the processing of a Quick Report.

Syntax Report_End()

Parameters • None

Return value The boolean value true.

Examples Refer to the example for Report_Begin().

FUNCTION LIBRARY REFERENCE 475

R E P O R T _ G E T P A G E R E M A I N I N G ()

Report_GetPageRemaining()
Description The Report_GetPageRemaining() function returns how much vertical area
of the page remains, not including the current band. The value is measured
in points.

Syntax Report_GetPageRemaining()

Parameters • None

Return value An integer containing a measurement of the vertical area of the page that
remains, measured in points.

Comments Use this function to find out how much of the page remains when you want
to insert a new band. If there is not enough vertical space for an item to fit,
you can start a new page with the Report_NewPage() function, then insert
the new band.

This function should be used only for reports that you print to the screen or to the
printer. It does not return consistent results when you send a report only to a file.

Examples This example adds a band that is 24 points tall to the current report. The
Report_GetPageRemaining() function is used to verify that enough space
remains on the page for the band. If there is not enough space, a new page is
started.

local boolean result;

if Report_GetPageRemaining() < 24 then

{There is not enough space to print the band. Start a new page.}
set result to Report_NewPage();
end if;
result = Report_NewBand(24);
result = Report_WriteText(0, 0, 250, 24, LEFT, "Total Sales");

476 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ G E T P A G E S I Z E ()

Report_GetPageSize()
Description The Report_GetPageSize() function returns the printable width and height
of the page, based on the settings for the currently-selected printer.

Syntax Report_GetPageSize(width, height)

Parameters • width – An integer containing the printable width of the page. The width is
measured in points.

• height – An integer containing the printable height of the page. The height is
measured in points.

Return value The boolean value true.

Comments You can use this function to calculate how many lines of text will fit on a
page. The page height in points divided by the number of points in each
line of text results in the number of lines per page.

Examples Refer to the example for Report_Begin().

FUNCTION LIBRARY REFERENCE 477

R E P O R T _ G E T S T R I N G W I D T H ( )

Report_GetStringWidth()
Description The Report_GetStringWidth() returns the width of a string using the font,
font size and font style specified.

Syntax Report_GetStringWidth(font, font_size, font_style, string)

Parameters • font – An integer specifying the font to use for the text. The value
corresponds to one of the following constants:

Constant Description
FONT_COURIER Courier font
FONT_HELVETICA Helvetica font
FONT_TIMES Times font

• font_size – An integer specifying the size of the font, measured in points.

• font_style – An integer specifying the style to use for the font. The values
correspond to the following constants:

Constant Description
FONT_STYLE_PLAIN Plain text
FONT_STYLE_BOLD Boldface text
FONT_STYLE_UNDERLINE Underlined text
FONT_STYLE_ITALIC Italicized text

You can add these constants together to apply multiple style characteristics.
For example, FONT_STYLE_BOLD+FONT_STYLE_UNDERLINE causes
the text to be boldfaced and underlined.

• string – The string whose width will be returned.

Return value An integer containing the width of the string, measured in points.

Comments You can use the Report_GetStringWidth() function to verify that a string
will fit on a page.

Examples This example calculates the width of the specified string when it is
displayed in Courier 12 point bold type.
local integer string_size;

string_size = Report_GetStringWidth(FONT_COURIER, 12,

➥ FONT_STYLE_BOLD, "Total Sales");

478 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ N E W B A N D ()

Report_NewBand()
Description The Report_NewBand() creates a new band in the report.

Syntax Report_NewBand(height)

Parameters • height – An integer specifying the height of the band. The height is
measured in points.

Return value The boolean value true.

Comments The first band for a report starts in the upper left corner of the report,
extends the width of the page, and has the height you specify. Any
additional band you add starts immediately below the previous band.

Examples Refer to the example for Report_Begin().

FUNCTION LIBRARY REFERENCE 479

R E P O R T _ N E W P A G E ( )

Report_NewPage()
Description The Report_NewPage() function creates a new page for the report.

Syntax Report_NewPage()

Parameters • None

Return value The boolean value true.

Examples Refer to the example for Report_Begin().

480 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ R E A D Y T O R U N ()

Report_ReadyToRun()
Description The Report_ReadyToRun() function verifies that a new Quick Report can
be run. A Quick Report can’t be started if any type of report is being
displayed on the screen.

Syntax Report_ReadyToRun()

Parameters • None

Return value A boolean value indicating whether the new report can begin; true
indicates the report can begin running, false indicates it can’t.

Examples This example uses a repeat loop to delay processing until the Quick Report
can be started. This example should be used in a script that runs only in the
background.

repeat
result = Report_ReadyToRun();
until result = true;

FUNCTION LIBRARY REFERENCE 481

R E P O R T _ S E T F O N T ( )

Report_SetFont()
Description The Report_SetFont() function specifies the characteristics of the font to use
for the Quick Report.

Syntax Report_SetFont(font, font_size, font_style)

Parameters • font – An integer specifying the font to use for the text. The value
corresponds to one of the following constants:

Constant Description
FONT_COURIER Courier font
FONT_HELVETICA Helvetica font
FONT_TIMES Times font

• font_size – An integer specifying the size of the font, measured in points.

• font_style – An integer specifying the style to use for the font. The values
correspond to the following constants:

Constant Description
FONT_STYLE_PLAIN Plain text
FONT_STYLE_BOLD Boldface text
FONT_STYLE_UNDERLINE Underlined text
FONT_STYLE_ITALIC Italicized text

You can add these constants together to apply multiple style characteristics.
For example, FONT_STYLE_BOLD+FONT_STYLE_UNDERLINE causes
the text to be boldfaced and underlined.

Return value The boolean value true.

Examples Refer to the example for Report_Begin().

482 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E P O R T _ S I N G L E L I N E ()

Report_SingleLine()
Description The Report_SingleLine() function draws a single line in the current band.
The line is one point thick.

Syntax Report_SingleLine(left_pos, vertical_pos, width)

Parameters • left_pos – The location of the left end of the line, relative to the left edge of
the current band, measured in points.

• vertical_pos – The location of the top of the line, relative to the top of the
current band, measured in points.

• width – The width of the line, measured in points.

Return value The boolean value true.

Examples This example draws a line 100 points wide in the current band. The line
starts at the left edge and 5 points below the top of the band.

local boolean result;

result = Report_SingleLine(0, 5, 100);

FUNCTION LIBRARY REFERENCE 483

R E P O R T _ W R I T E T E X T ( )

Report_WriteText()
Description The Report_WriteText() function adds a text string to the current band.

Syntax Report_WriteText(left_pos, top_pos, width, height, alignment, string)

Parameters • left_pos – The location of the left edge of the text rectangle, relative to the left
edge of the current band, measured in points.

• top_pos – The location of the top edge of the text rectangle, relative to the top
of the current band, measured in points.

• width – The width of the text rectangle, measured in points.

• height – The height of the text rectangle, measured in points.

• alignment – An integer specifying the alignment of the string in the text

rectangle. The value corresponds to one of the following constants:

Constant Description
ALIGN_LEFT Left aligned
ALIGN_CENTER Center aligned
ALIGN_RIGHT Right aligned

• string – The string that will be displayed in the text rectangle.

Return value The boolean value true.

Comments When specifying the width and height of the text rectangle, keep in mind
that the text in the rectangle will be positioned at the top of the text
rectangle, allowing appropriate space for accented characters. If the
text rectangle is not large enough, the text will but cut off on the right and
bottom.

Examples Refer to the example for Report_Begin().

484 F U N C T I O N L I B R A R Y R E F E R E N C E
 Resource function library
Use the functions in this library when you are working with lists of
resources in an application. This library contains the following functions:

• Resource_EndSeriesFill()
• Resource_FillSeriesList()
• Resource_GetDisplayName()
• Resource_GetID()
• Resource_GetInfo()
• Resource_GetNthResource()
• Resource_GetResourceName()
• Resource_GetSubResourceName()
• Resource_StartSeriesFill()

Refer to Chapter 5, Some of the functions in this library work together to perform certain
“Security,” in the operations. The functions in the following list read the list of forms, reports,
Stand-alone tables and table groups from the application dictionary. They are typically
Application Guide for used in the implementation of application security.
more information
about application • Resource_StartSeriesFill()
security. • Resource_GetInfo()
• Resource_EndSeriesFill()

FUNCTION LIBRARY REFERENCE 485

R E S O U R C E _ E N D S E R I E S F I L L ( )

Resource_EndSeriesFill()
Description The Resource_EndSeriesFill() function releases resources that have been
read into memory by the Resource_StartSeriesFill() function.

Syntax Resource_EndSeriesFill()

Parameters • None

Return value The boolean value true.

Comments When you are finished working with the resources, the
Resource_EndSeriesFill() function should be used to release the resources
that were read into memory by the Resource_StartSeriesFill() function.
This frees up memory used to store information about the resources.

Examples See the example for Resource_StartSeriesFill().

Related items Commands

Resource_StartSeriesFill(), Resource_GetInfo()

486 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ F I L L S E R I E S L I S T ()

Resource_FillSeriesList()
Description The Resource_FillSeriesList() function fills two list fields (fields that use a
list box or drop-down list control type) with the display names and
technical names of resources of a specified resource type and series.

Syntax Resource_FillSeriesList(product_ID, type, series, dnames_list, tnames_list)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which resource information is being retrieved.

• type – An integer specifying the type of resource whose names will fill the
list fields dnames_list and tnames_list. The types, and their corresponding
integer values, are shown in the following table.

Value Description
40 Forms
43 Tables
44 Table Groups
45 Reports

• series – An integer specifying the series of the forms, reports, tables and
table groups whose names will fill the list fields dnames_list and tnames_list.
The following table lists all the series and their corresponding integer
values.

Series for forms and windows

1 – Financial 6 – Project 11 – Macro System
2 – Sales 7 – System 12 – Palette
3 – Purchasing 8 – Company 13 – Dexterity
4 – Inventory 9 – Online Documentation 14 – Dexterity System
5 – Payroll 10 – 3rd Party 15 – Report Writer

Series for tables and table groups

1 – Financial 7 – System 12 – Pathname
2 – Sales 8 – Company 13 – Design Document
3 – Purchasing 9 – Online Documentation 14 – Dexterity
4 – Inventory 10 – 3rd Party 15 – Dexterity System
5 – Payroll 11 – Payroll Tax 16 – Report Writer
6 – Project

FUNCTION LIBRARY REFERENCE 487

R E S O U R C E _ F I L L S E R I E S L I S T ( )

• dnames_list – A window list field that displays the returned display names
of the specified resources.

• tnames_list – A window field that displays the internal technical names for
the specified resources. Names in this list must be used when referring to
resource names in scripts.

Return value The boolean value true.

Comments Resource_FillSeriesList() returns two different names for a given resource;

the display name (added to a window field specified by dnames_list) and
the technical name (added to a list field specified by tnames_list).

If there is no main window for a form, the display name for the form will be
“Main Window Missing”.

Be sure the series resource lists are up to date before you use this function. You can
use the Series Resources utility in Dexterity Utilities to update series resources.

Examples The following example returns the names of forms (ID=40) from the third-
party series (ID=10) to two list box window fields. The Display Names field
contains display names, while the Technical Names field contains technical
names. The product ID is represented by the constant INVENT_PRODID.

local boolean result;

result = Resource_FillSeriesList(INVENT_PRODID, 40, 10,

➥ 'Display Names', 'Technical Names';

Related items Commands

Table_FillList()

Additional information
Updating series resources on page 50 of the Dexterity Utilities manual.

488 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ G E T D I S P L A Y N A M E ()

Resource_GetDisplayName()
Description The Resource_GetDisplayName() function returns a string containing the
display name of a specified resource in an application dictionary.

Syntax Resource_GetDisplayName(product_ID, resource_type, resource_ID)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the resource display name is being retrieved.

• resource_type – An integer specifying the type of resource to identify. Use

one of the following constants:

Constant Description
FORMTYPE Indicates a form.
TABLETYPE Indicates a table.
GROUPTYPE Indicates a table group.
REPORTTYPE Indicates a report.

• resource_ID – An integer specifying the resource ID of the resource.

Return value A string containing the display name of the resource. If there is no main
window for the form, the string “[No Display Name]” is returned.

Comments If you implement activity tracking in your application, you can use this
function in conjunction with the Security procedure to retrieve the display
name of a selected resource. The Security procedure runs each time a form,
report, or table is accessed. A dictionary ID, resource type and a resource ID
for the resource being accessed are automatically passed as in parameters
for the Security procedure. With this information,
Resource_GetDisplayName() can ascertain the resource’s display name,
then store the name in an activity table (see the following example).

The resource_type parameter automatically passed to the Security procedure

will indicate a form, report or table group, but not an individual table. To
track table access, be sure you use place each table into a table group.

FUNCTION LIBRARY REFERENCE 489

R E S O U R C E _ G E T D I S P L A Y N A M E ( )

Examples The following Security procedure returns the dictionary ID, resource type
and resource ID of the currently active form, report or table group. It passes
these values to a procedure that updates the Activity Master table.

{Procedure Name: Security}

in integer l_prod_ID;
in integer l_resource_type;
in integer l_resource_ID;
out string l_Alias;

call Add_Activity_Record, l_prod_ID, l_resource_type, l_resource_ID;

The in integer parameters l_prod_ID, l_resource_type and l_resource_ID are

passed from the Security procedure to the Add_Activity_Record procedure
(shown in the following example). The Resource_GetDisplayName()
function uses these values to find out the display name of the resource. A
new record is then added to the Activity Master table.

{Procedure Name: Add_Activity_Record}

in integer l_prod_ID;
in integer l_resource_type;
in integer l_resource_ID;

local string l_display_name;

{Return the display name of the resource accessed by the user.}

l_display_name = Resource_GetDisplayName(l_prod_ID, l_resource_type,
➥ l_resource_ID);

{Set the fields in the Activity Master table.}

'User Name' of table 'Activity Master' = 'User ID' of globals;
'System Time' of table 'Activity Master' = systime();
'System Date' of table 'Activity Master' = sysdate();
'Resource Type' of table 'Activity Master' = l_resource_type;
'Resource Name' of table 'Activity Master' = l_display_name;
save table 'Activity Master';
if err()<>OKAY then
warning "Cannot save activity record.";
end if;

Related items Additional information

Chapter 5, “Security,” and Chapter 6, “Activity Tracking,” in the Stand-alone Application
Guide

490 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ G E T ID ()

Resource_GetID()
Description The Resource_GetID() function returns the resource ID for a specified
resource type and name.

Syntax Resource_GetID(product_ID, resource_type, resource_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the resource ID is being retrieved.

• resource_type – An integer specifying a resource type. The available types

and their corresponding integer values are in the following list:

Integer values for resource types

1 – Tables 15 – Generic pictures 29 – Mac Pictures
2 – Forms 18 – Fields 30 – Messages
6 – Data types 21 – Procedure scripts 42 – Table Groups
7 – Composites 23 – Reports 48 – Constants
8 – Formats 26 – Global variables 62 – Functions
9 – Strings 28 – Metafiles

• resource_name – A string specifying the technical name of the resource that

you want the resource ID for. For tables, this is the name that appears in the
Table Name field in the Table Definition window, not the display name.

Return value An integer containing the resource ID for the specified resource. If the
resource can’t be located, 0 is returned.

Examples The following example returns the resource ID of the Inventory Data Table
to a local variable. The product ID is represented by the constant
INVENT_PRODID.

local integer l_resource_ID;

l_resource_ID = Resource_GetID(INVENT_PRODID, 1, "Inventory_Data");

FUNCTION LIBRARY REFERENCE 491

R E S O U R C E _ G E T I N F O ( )

Resource_GetInfo()
Description The Resource_GetInfo() function returns the resource ID and resource
name for a form, report, table or table group for a specified series.

Syntax Resource_GetInfo(product_ID, type, index, name)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which resource information is being retrieved.

• type – An integer specifying the type of resource for which information is

being retrieved. Use the following integer values for resource types:

Value Description
40 Forms
43 Tables
44 Table Groups
45 Reports

You should consider setting up constants for each of these integer values if you plan
to use this function frequently.

• index – An integer specifying the position in the series resource list from
which information is returned. This number must be between 1 and the
number of resources of the specified type and series returned by
Resource_StartSeriesFill(). Typically, the counter variable for a for loop is
used to increment the index parameter from 1 to the number of resources
returned by Resource_StartSeriesFill(). For each iteration of the loop, the
name and resource ID are read for the resource indicated by the counter
variable.

• name – A returned string containing the resource’s display name. Form and
table names returned here aren’t technical names as you’ve defined them in
your dictionary. Rather, the display name of the main window in the form is
returned for forms and the display name of the table is returned for tables.

Return value An integer containing the resource ID of the resource. If the resource can’t
be found, the value 0 is returned.

492 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ G E T I N F O ()

Comments Be sure you use Resource_StartSeriesFill() to count the number of

resources for the given type and series before you use this function. The
returned count from Resource_StartSeriesFill() can be used as the index
limit for a for do...end for statement. The index can be passed to
Resource_GetInfo() to add each resource to a list field.

Be sure the series resource lists are up to date before you use this function. You can
use the Series Resources utility in Dexterity Utilities to update series resources.

Examples Refer to the example for Resource_StartSeriesFill().

Related items Commands

Resource_StartSeriesFill(), Resource_EndSeriesFill()

Additional information
Updating series resources on page 50 of the Dexterity Utilities manual.

FUNCTION LIBRARY REFERENCE 493

R E S O U R C E _ G E T N T H R E S O U R C E ( )

Resource_GetNthResource()
Description The Resource_GetNthResource() function returns the resource ID, name,
and series of the specified resource.

Syntax Resource_GetNthResource(product_ID, type, index, name, series)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the resource information is being retrieved.

• type – An integer specifying the type of resource for which information is

being retrieved. The available types and their corresponding integer values
are shown in the following list:

Integer values for resource types

1 – Tables 15 – Generic pictures 29 – Mac Pictures
2 – Forms 18 – Fields 30 – Messages
6 – Data types 21 – Procedure scripts 42 – Table Groups
7 – Composites 23 – Reports 48 – Constants
8 – Formats 26 – Global variables 62 – Functions
9 – Strings 28 – Metafiles

• index – An integer specifying the resource for which information is being

retrieved. The value 1 indicates the first resource, 2 indicates the second
resource, and so on. The resources are retrieved in resource ID order.

• name – A returned string containing the resource’s technical name. If the

resource cannot be found, the string “[Not Found]” or the empty string will
be returned.

• series – An integer indicating the series the resource is assigned to. The
possible values are shown in the following list:

Series
1 – Financial
2 – Sales
3 – Purchasing
4 – Inventory
5 – Payroll
6 – Project
7 – System

494 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ G E T N T H R E S O U R C E ()

Return value An integer containing the resource ID of the specified resource. If the
resource doesn’t exist, the value 0 is returned.

Examples The following example uses the Resource_GetNthResource() function to

retrieve all of the data types in the current dictionary and add their names
to a list box. The PROD_ID constant represents the current product ID.

local integer resource_ID;

local integer i;
local integer resource_series;
local string resource_name;

i = 1;
repeat
resource_ID = Resource_GetNthResource(PROD_ID, 6, i,
➥ resource_name, resource_series);
if resource_ID <> 0 then
add item resource_name to '(L) Resources';
end if;
i = i + 1;
until resource_ID = 0;
redraw field '(L) Resources';

FUNCTION LIBRARY REFERENCE 495

R E S O U R C E _ G E T R E S O U R C E N A M E ( )

Resource_GetResourceName()
Description The Resource_GetResourceName() function returns the technical name for
a specified resource type and ID. This is not the display name.

Syntax Resource_GetResourceName(product_ID, resource_type, resource_ID)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the resource name is being retrieved.

• resource_type – An integer specifying a resource type. The available types

and their corresponding integer values are shown in the following list:

Integer values for resource types

1 – Tables 15 – Generic pictures 29 – Mac Pictures
2 – Forms 18 – Fields 30 – Messages
6 – Data types 21 – Procedure scripts 42 – Table Groups
7 – Composites 23 – Reports 48 – Constants
8 – Formats 26 – Global variables 62 – Functions
9 – Strings 28 – Metafiles

• resource_ID – An integer specifying the resource ID of the resource whose

name is being retrieved.

Return value A string containing the resource’s technical name. If the resource can’t be
found, the string [Not Found] is returned.

Examples The following example returns the name of the field whose resource ID is
22000. The product ID is represented by the constant RESM_PRODID.

local string resource_name;

resource_name = Resource_GetResourceName(RESM_PRODID, 18, 22000);

496 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ G E T S U B R E S O U R C E N A M E ()

Resource_GetSubResourceName()
Description The Resource_GetSubResourceName() function returns the name for a
specified subresource of a primary resource.

Syntax Resource_GetSubResourceName(product_ID, primary_resource_type,

primary_resource_ID, subresource_type, subresource_ID)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the resource name is being retrieved.

• primary_resource_type – An integer specifying a primary resource type.

Specify MT_FORM for forms or MT_REPORT for reports.

• primary_resource_ID – An integer specifying the resource ID of the primary

resource that contains the subresource.

• subresource_type – An integer specifying a secondary resource type. Use a

constant value such as DT_COMMAND for commands.

• subresource_ID – An integer specifying the resource ID of the subresource

for which the name is being retrieved.

Return value A string containing the resource name. If the resource can’t be found, the
string [Not Found] is returned.

Examples The following example returns the names of the commands in the the
CL_Reports command list.

local integer command_list_tag, item_tag;

local integer dict_ID, form_ID, res_ID;
local integer i;
local boolean result;
local string command_name;

{Retrieve information about each command in the list}

command_list_tag = Command_GetTag(command CL_Reports of form
➥ 'Main Menu');

for i = 1 to CommandList_NumCommands(command_list_tag) do
item_tag = CommandList_GetCommandByPosition(command_list_tag, i);
result = Command_GetIDs(item_tag, dict_ID, form_ID, res_ID);
command_name = Resource_GetSubResourceName(dict_ID, MT_FORM,
➥ form_ID, DT_COMMAND, res_ID);

FUNCTION LIBRARY REFERENCE 497

R E S O U R C E _ G E T S U B R E S O U R C E N A M E ( )

if result = false then

error "Could not retrieve IDs for command.";
else
warning "Dict ID:" + str(dict_ID) + " Form ID:" + str(form_ID)
➥ + " Res ID:" + str(res_ID) + " Name:" + command_name;
end if;
end for;

498 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ S T A R T S E R I E S F I L L ()

Resource_StartSeriesFill()
Description The Resource_StartSeriesFill() function returns the number of resources of
a specific type (forms, reports, tables or table groups) for a specified series.

Syntax Resource_StartSeriesFill(product_ID, type, series)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which resource information is being retrieved.

• type – An integer specifying the type of resource. Use the following integer
values for resource types:

Value Description
40 Forms
43 Tables
44 Table Groups
45 Reports

You should consider setting up constants for each of these integer values if you plan
to use this function frequently.

• series – An integer specifying the series of the forms, reports, tables, or table
groups for which the count will be returned. The
Resource_StartSeriesFill() function will count only resources of the
specified type from the series you indicate here.

The following table lists the series that can be applied to forms and reports
and the series’ corresponding integer values. You apply a series to a form
using the Form Definition window or to a report using the Report
Definition window.

Form and report series

1 – Financial 6 – Project 11 – Macro System
2 – Sales 7 – System 12 – Palette
3 – Purchasing 8 – Company 13 – Dexterity
4 – Inventory 9 – Online Documentation 14 – Dexterity System
5 – Payroll 10 – 3rd Party 15 – Report Writer

FUNCTION LIBRARY REFERENCE 499

R E S O U R C E _ S T A R T S E R I E S F I L L ()

The following table lists the series that can be applied to tables and table
groups and the series’ corresponding integer values. You can apply a series
to a table in the Table Definition window. You apply a series to a Table
Group when you create it using Dexterity Utilities.

Table and table group series

1 – Financial 7 – System 12 – Pathname
2 – Sales 8 – Company 13 – Design Document
3 – Purchasing 9 – Online Documentation 14 – Dexterity
4 – Inventory 10 – 3rd Party 15 – Dexterity System
5 – Payroll 11 – Payroll Tax 16 – Report Writer
6 – Project

Return value An integer containing the number of the forms, reports, tables or table
groups in the specified series.

Comments Resource_StartSeriesFill() can be used with Resource_GetInfo() to fill a

list field (a field that uses a list box or drop-down list control type) with the
display names of resources from a specified series. The return value can be
used as a counter in a for do...end for loop to indicate how many resources
should fill the list (see the following example). Then the
Resource_GetInfo() function can be used to return the resource IDs and
names to be used to fill a list field.

Although Resource_FillSeriesList() allows you to fill a list with the names

of resources of a specified type for a given series, it simply fills the list with
all resources that meet the criteria. Using Resource_StartSeriesFill() and
Resource_GetInfo() allows each resource to be examined with a conditional
expression and added to the list if the condition is met. This can be useful if
you want to compare individual resources in a list with the contents of a
user security file to determine whether the resource is accessible for the
current user.

Be sure the series resource lists are up to date before you use this function. You can
use the Series Resources utility in Dexterity Utilities to update series resources.

500 F U N C T I O N L I B R A R Y R E F E R E N C E
 R E S O U R C E _ S T A R T S E R I E S F I L L ()

Examples The following example uses Resource_StartSeriesFill(),

Resource_GetInfo() and Resource_EndSeriesFill() to fill a list with
resources for a specified series and resource type. In this example,
Resource_StartSeriesFill() counts all forms (resource type=40) in the Sales
series (series ID=2). The returned count is used as the upper limit in a for
do...end for statement along with Resource_GetInfo() to add each form to
a list box field. The Resource_EndSeriesFill() function is then used to
release the form resources that have been accessed by
Resource_StartSeriesFill().

local integer restype,l_Series,count,i,resid;

local string item1;
local boolean result;

{Set resource type to forms.}

restype = 40;
{Set series to Sales.}
l_Series = 2;

{Count number of forms in the Sales series. The count variable will
return the number of forms. The product ID is 0.}
count = Resource_StartSeriesFill(0, restype, l_Series);

{Complete for loop using the returned number of forms.}

for i = 1 to count do
{Return form names to item1.}
resid = Resource_GetInfo(0, restype, i, item1);
{Fill list box with form names.}
add item item1 to '(L) List box';
end for;
redraw field '(L) List box';
{Finish series fill.}
result = Resource_EndSeriesFill();

Related items Commands

Resource_GetInfo(), Resource_EndSeriesFill(), for do...end for

Additional information
Updating series resources on page 50 of the Dexterity Utilities manual.

FUNCTION LIBRARY REFERENCE 501

502 F U N C T I O N L I B R A R Y R E F E R E N C E
Runtime function library
Use the functions in this library to specify characteristics and retrieve
information about the current Dexterity runtime environment. This library
contains the following functions:

• Runtime_GetClientType()
• Runtime_GetCPUType()
• Runtime_GetCurrentProductID()
• Runtime_GetModuleInfo()
• Runtime_GetOSBuildInfo()
• Runtime_GetOSInfo()
• Runtime_GetVersionNum()
• Runtime_GetWebClientTrustLevel()
• Runtime_SetAboutMenu()
• Runtime_SetFieldEnterMode()
• Runtime_SetIcon()

FUNCTION LIBRARY REFERENCE 503

R U N T I M E _ G E T C L I E N T T Y P E ( )

Runtime_GetClientType()
Description The Runtime_GetClientType() function returns information about the
runtime engine that is processing the application.

Syntax Runtime_GetClientType()

Parameters • None

Return value An integer. The value corresponds to one of the following constants.

Constant
DEX_CLIENT_TYPE_STANDARD
DEX_CLIENT_TYPE_WEB
DEX_CLIENT_TYPE_NO_UI
Description
The standard runtime engine for Windows.
The runtime engine for the web client.
The runtime engine that does not directly present a
user interface, such as the Process Server.

Comments This function is typically used when writing code that can be performed
only for a specific client type.

Examples The following code is a portion of a form procedure script that registers a
third-party workflow for Microsoft Dynamics GP. Because workflow is
supported only on the standard client, the Runtime_GetClientType()
function is used to find out whether the code should be run.
local string assembly_path;
local long delay;

{Workflow works only on the standard client.}

if Runtime_GetClientType() = DEX_CLIENT_TYPE_STANDARD then
{Can the client assembly for the sample workflow be found?}
assembly_path = Path_GetForApp(1) +
➥ "Microsoft.Dynamics.GP.Workflow.Samples.Client.dll";
if File_Probe(assembly_path) = true then
{Open the Workflow Status window to retrieve the status}
open window WorkflowStatus;
Window_ForceRedraw(window WorkflowStatus);

{Sleep for 5 seconds}

delay = Timer_Sleep(5000);

{Close the window}

close window WorkflowStatus;
end if;
end if;

504 F U N C T I O N L I B R A R Y R E F E R E N C E
 R U N T I M E _ G E T C P U T Y P E ()

Runtime_GetCPUType()
Description The Runtime_GetCPUType() function returns information about the
central processing unit (CPU) on which the application is being run.

Syntax Runtime_GetCPUType(specific_class)

Parameters • specific_class – A returned integer indicating the specific class of CPU:

Constant Description
DEX_CPU_I486 Intel 486
DEX_CPU_PENTIUM Intel Pentium
DEX_CPU_PENTIUM_II Intel Pentium II
DEX_CPU_PENTIUM_III Intel Pentium III

Return value An integer indicating the general class of CPU:

Constant Description
DEX_CPU_UNKNOWN Unknown CPU
DEX_CPU_Ix86 Intel X86

Examples The following example uses the Runtime_GetCPUType() function to

retrieve information about the CPU on which the application is being run.
The information is displayed in a warning dialog box.
local integer general_CPU_class, specific_CPU_class;
local string CPU_description;

general_CPU_class = Runtime_GetCPUType(specific_CPU_class);
if general_CPU_class <> 0 then
case general_CPU_class
in [DEX_CPU_Ix86]
CPU_description = "Intel 80X86";
else
CPU_description = "Unknown CPU type";
end case;
else
CPU_description = "Unknown CPU type";
end if;
warning CPU_description;

FUNCTION LIBRARY REFERENCE 505

R U N T I M E _ G E T C U R R E N T P R O D U C T I D ( )

Runtime_GetCurrentProductID()

Description The Runtime_GetCurrentProductID() function returns the product ID of

the application dictionary that contains the script executing this function.

Syntax Runtime_GetCurrentProductID()

Parameters • None

Return value An integer containing the product ID.

Comments The Runtime_GetCurrentProductID() function returns correct values only

when an application is used with the runtime engine. In test mode, it will
always return the value 0.

Examples The following example uses the Runtime_GetCurrentProductID() function

to retrieve the current application’s product ID.

local integer product_ID;

product_ID = Runtime_GetCurrentProductID();

506 F U N C T I O N L I B R A R Y R E F E R E N C E
 R U N T I M E _ G E T M O D U L E I N F O ()

Runtime_GetModuleInfo()
Description The Runtime_GetModuleInfo() function retrieves the major and minor
version and the build number from the application dictionary. The values
returned correspond to the selections made in one of the following
locations:

• The Install Information window in Dexterity

• The Create Chunk Dictionary window in Dexterity Utilities
• The Auto-Chunk window in Dexterity Utilities

Syntax Runtime_GetModuleInfo(product_ID, module, minor_version, build_number)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which module information is being retrieved.

• module – An integer indicating the module for which version numbers are
being retrieved.

• minor_version – A returned integer value containing the minor version of

the specified module.

• build_number – A returned integer value containing the build number of the

specified module.

Return value An integer indicating the major version of the specified module.

Comments When you use the Create Chunk Dictionary window or the Auto-Chunk
window in Dexterity Utilities to create a chunk dictionary, you specify a
module and the major and minor version numbers and build number
associated with that module. When the chunk dictionary is “unchunked,”
the major and minor version numbers and build number for the specified
accounting module are written to the application dictionary. Typically, the
version numbers are retrieved from the application dictionary and
displayed in the application’s About Box.

When an application is updated, the update chunk should use updated

version numbers. This allows the new version numbers to be written to the
application dictionary when the update chunk is installed. The updated
version numbers will appear wherever you’ve used them in the
application. Note that the same module must have been specified for both
the original and the update dictionary chunks so the proper set of version
numbers will be updated.

FUNCTION LIBRARY REFERENCE 507

R U N T I M E _ G E T M O D U L E I N F O ( )

For example, assume the chunk dictionary used to install the first version of
an application had a major version number of 1, a minor version number of
0 (Version 1.0), and a build number of 1. When the application is updated,
the chunk dictionary for the update could be assigned a major version
number of 1, a minor version number of 1 (Version 1.1), and a build number
of 2.

Examples In the following example, the version information for module 47 is

retrieved and displayed in an application’s About Box. The product ID is
represented by the constant INVENT_PRODID.

local integer major_version, minor_version, build_number;

{Read the version information for the module 47.}

major_version = Runtime_GetModuleInfo(INVENT_PRODID, 47,
➥ minor_version, build_number);

{Display the version information.}

Version of window 'About Box' = str(major_version) + "." +
➥ str(minor_version);
'Build Number' of window 'About Box' = str(build_number);

Related items Additional information

Part 11, Packaging Applications, in Volume 1 of the Dexterity Programmer’s Guide

508 F U N C T I O N L I B R A R Y R E F E R E N C E
 R U N T I M E _ G E T O SB U I L D I N F O ()

Runtime_GetOSBuildInfo()

Description The Runtime_GetOSBuildInfo() function returns build information for the

operating system on which the application is being run.

Syntax Runtime_GetOSBuildInfo(build_number, build_description)

Parameters • build_number – A returned long integer indicating the build number of the
current operating system.

• build_description – A returned string describing the build of the current

operating system.

Return value The boolean value true.

Comments Not all operating systems will return build information.

Examples The following example uses the Runtime_GetOSBuildInfo() function to

retrieve build information for the current operating system.

local long build_number;

local string build_description;
local boolean result;

result = Runtime_GetOSBuildInfo(build_number, build_description);

FUNCTION LIBRARY REFERENCE 509

R U N T I M E _ G E T OSI N F O ( )

Runtime_GetOSInfo()
Description The Runtime_GetOSInfo() function returns information about the
operating system on which the application is being run.

Syntax Runtime_GetOSInfo(major_version, minor_version)

Parameters • major_version – A returned integer indicating the major version.

• minor_version – A returned integer indicating the minor version.

Return value An integer indicating the specific type of operating system being used:

Constant Description
DEX_OS_UNKNOWN Unknown operating system
DEX_OS_WINDOWS_NT Windows NT®
DEX_OS_WINDOWS_95 Windows 95
DEX_OS_WINDOWS_98 Windows 98
DEX_OS_WINDOWS_MILLENNIUM Windows ME
DEX_OS_WINDOWS_2000 Windows 2000
DEX_OS_WINDOWS_XP Windows XP
DEX_OS_WINDOWS_VISTA Windows Vista
DEX_OS_WINDOWS_SERVER_2003 Windows Server® 2003
DEX_OS_WINDOWS_SERVER_2008 Windows Server 2008
DEX_OS_WINDOWS_SERVER_2008R2 Windows Server 2008 R2
DEX_OS_WINDOWS_SERVER_2012 Windows Server 2012
DEX_OS_WINDOWS_7 Windows 7
DEX_OS_WINDOWS_8 Windows 8

Examples The following example uses the Runtime_GetOSInfo() function to retrieve

information about the operating system on which the application is being
run. The information is displayed in a warning dialog box.
local integer operating_system, major_version, minor_version;
local string OS_info;

operating_system = Runtime_GetOSInfo(major_version, minor_version);

if operating_system <> 0 then

case operating_system
in [DEX_OS_WINDOWS_NT]

510 F U N C T I O N L I B R A R Y R E F E R E N C E
 R U N T I M E _ G E T O SI N F O ()

OS_info = "Microsoft Windows NT ";

in [DEX_OS_WINDOWS_95]
OS_info = "Microsoft Windows 95 ";
in [DEX_OS_WINDOWS_98]
OS_info = "Microsoft Windows 98 ";
in [DEX_OS_WINDOWS_MILLENNIUM]
OS_info = "Microsoft Windows ME ";
in [DEX_OS_WINDOWS_2000]
OS_info = "Microsoft Windows 2000 ";
in [DEX_OS_WINDOWS_XP]
OS_info = "Microsoft Windows XP ";
in [DEX_OS_WINDOWS_SERVER_2003]
OS_info = "Microsoft Windows Server 2003 ";
in [DEX_OS_WINDOWS_SERVER_2008]
OS_info = "Microsoft Windows Server 2008 ";
in [DEX_OS_WINDOWS_SERVER_2008R2]
OS_info = "Microsoft Windows Server 2008 R2 ";
in [DEX_OS_WINDOWS_SERVER_2012]
OS_info = "Microsoft Windows Server 2012 ";
in [DEX_OS_WINDOWS_VISTA]
OS_info = "Microsoft Windows Vista ";
in [DEX_OS_WINDOWS_7]
OS_info = "Microsoft Windows 7 ";
in [DEX_OS_WINDOWS_8]
OS_info = "Microsoft Windows 8 ";
else
OS_info = "Unknown ";
end case;
OS_info = OS_info + str(major_version) + "." + str(minor_version);
else
set OS_info to "Unknown operating system";
end if;
warning OS_info;

FUNCTION LIBRARY REFERENCE 511

R U N T I M E _ G E T V E R S I O N N U M ( )

Runtime_GetVersionNum()
Description The Runtime_GetVersionNum() function returns a string describing the
current version of the runtime engine.

Syntax Runtime_GetVersionNum()

Parameters • None

Return value A string containing the version number of the runtime engine.

Comments The string that the version number is returned to should be 255 characters
long. This ensures that string overflow errors won’t occur when the version
string is returned.

Examples In the following example, the current version of the runtime engine is
returned to the Version field in the window named About_Box.

Version of window About_Box = Runtime_GetVersionNum();

512 F U N C T I O N L I B R A R Y R E F E R E N C E
 R U N T I M E _ G E T W E B C L I E N T T R U S T L E V E L ()

Runtime_GetWebClientTrustLevel()
Description The Runtime_GetWebClientTrustLevel() function returns an integer
indicating the trust level of the Silverlight application for the web client.

Syntax Runtime_GetWebClientTrustLevel()

Parameters • None

Return value An integer corresponding to one of the following constants:

Constant
TRUST_LEVEL_FULL
TRUST_LEVEL_SANDBOXED
Description
The Silverlight application for the web client is
running in fully-trusted mode.
The Silverlight application for the web client is
running in sandboxed mode.

Comments By default, the Silverlight application for the web client runs in
“sandboxed” mode. This means it has restricted access to local system
resources. When a user attempts to perform an action (such as
downloading a file that was created by a report) the sandboxed mode may
prevent them from doing so. The local system can be configured to run the
Silverlight application for the web client with enhanced trust level,
allowing these formerly restricted actions.

Examples In the following example, the current trust level of the web client
application is examined. If the application is being run in trusted mode, an
export routine is called. Otherwise, a message is displayed to the user.

if Runtime_GetWebClientTrustLevel() = TRUST_LEVEL_FULL then

call ExportCurrentRecords;
else
error "Not in full-trust mode. Records cannot be exported.";
end if;

FUNCTION LIBRARY REFERENCE 513

R U N T I M E _ S E T A B O U T M E N U ( )

Runtime_SetAboutMenu()
Description The Runtime_SetAboutMenu() function allows you to change the
application name in the About menu item. This name will also appear on
system dialogs, like those displayed when using the error and warning
statements. This function will change the title of the application in the
runtime engine’s title bar.

Syntax Runtime_SetAboutMenu(application_name)

Parameters • application_name – The string that will appear in the About menu item.

Return value The boolean value true.

Comments The runtime engine will automatically open any form named “About Box”
when the About menu item is chosen.

Examples In the following example, the string “Time and Billing” is concatenated
with the default text in the About menu to set the menu item to “About
Time and Billing.”

local boolean result;

result = Runtime_SetAboutMenu("Time and Billing");

Related items Additional information

Description of the About Box form in Chapter 10, “Forms,” of Volume 1 of the Dexterity
Programmer’s Guide

514 F U N C T I O N L I B R A R Y R E F E R E N C E
 R U N T I M E _ S E T F I E L D E N T E R M O D E ()

Runtime_SetFieldEnterMode()
Description The Runtime_SetFieldEnterMode() function allows users to press the
ENTERkey instead of the TAB key to move the focus from field to field in a
window.

Syntax Runtime_SetFieldEnterMode(mode)

Parameters • mode – An integer that sets one of the following modes:

Value Description
0 Enables the TAB key mode.
1 Disables the TAB key mode.

Return value The boolean value true.

Comments Dexterity applications use the TAB key as the default method of data entry.
This function allows a user to choose the preferred method of data entry.
When the ENTER key is used to move the focus, SHIFT+RETURN or
SHIFT+ENTER must be used to activate a push button field with the Default
property set to true or a push button currently focused in a window.

Examples The following example disables TAB key mode, allowing the ENTER key to
move the focus from field to field in a tab sequence.

local boolean result;

result = Runtime_SetFieldEnterMode(1);

The following example enables TAB key mode, allowing the TAB key to
move the focus from field to field. In this case, the ENTER key will activate a
push button field with the Default property set to true or a push button
currently focused in a window.

local boolean result;

result = Runtime_SetFieldEnterMode(0);

FUNCTION LIBRARY REFERENCE 515

R U N T I M E _ S E T I C O N ( )

Runtime_SetIcon()
Description The Runtime_SetIcon() function allows you to specify which icons will be
displayed in the application.

Syntax Runtime_SetIcon(type, icon_value)

Parameters • type – An integer specifying which icon type is being specified. Use one of
the following constants:

Constant Description
APPLICATION_ICON This is the icon displayed in the application’s title
bar.
PRIMARY_ICON This is the icon displayed in the title bar of all
primary window.

• icon_value – An integer specifying which icon to use. The following icons

are available:

Constant Description
ICON_GREATPLAINS The logo for Great Plains.
ICON_GRAYFORM A plain “form” icon to be used as an icon in
primary windows.
ICON_GREATPLAINSFORM A “form” icon that contains the logo for Great
Plains.

Return value A boolean. True indicates the icon was set, while false indicates it was not.

Examples The following example is part of the Main Menu form pre script. It sets the
icon to use for the application to be the logo for Great Plains.

local boolean result;

result = Runtime_SetIcon(APPLICATION_ICON, ICON_GREATPLAINS);

516 F U N C T I O N L I B R A R Y R E F E R E N C E
Script log function library
Use the functions in this library to access the script logging capability from
within sanScript. Refer to Chapter 29, “Script Logger,” in Volume 2 of the
Dexterity Programmer’s Guide for information about the Script Logger.
This library contains the following functions:

• ScriptLog_Start()
• ScriptLog_Stop()

FUNCTION LIBRARY REFERENCE 517

S C R I P T L O G _ S T A R T ( )

ScriptLog_Start()
Description The ScriptLog_Start() function starts logging scripts, writing the script log
to the specified output file.

Syntax ScriptLog_Start(path)

Parameters • path – A string specifying the path and filename for the script log being
written. The path must be in native format.

Return value A boolean. The value true indicates the script log could be written, while
the value false indicates it could not.

Examples The following example writes a script log named ExplorerScripts.log in the
root folder.
local boolean result;

result = ScriptLog_Start("c:\ExporerScripts.log");
if result = false then
error "Script log could not be written.";
end if;

518 F U N C T I O N L I B R A R Y R E F E R E N C E
 S C R I P T L O G _ S T O P ()

ScriptLog_Stop()
Description The ScriptLog_Stop() function stops logging scripts, closing the current
output file.

Syntax ScriptLog_Stop()

Parameters • None

Return value The boolean value true.

Examples The following example closes the current script log.

local boolean result;

result = ScriptLog_Stop();

FUNCTION LIBRARY REFERENCE 519

520 F U N C T I O N L I B R A R Y R E F E R E N C E
Script profile function library
Use the functions in this library to access the script logging capability from
within sanScript. Refer to Chapter 28, “Script Profiler,” in Volume 2 of the
Dexterity Programmer’s Guide for information about the Script Profiler.
This library contains the following functions:

• ScriptProfile_Clear()
• ScriptProfile_Save()
• ScriptProfile_Start()
• ScriptProfile_Stop()

FUNCTION LIBRARY REFERENCE 521

S C R I P T P R O F I L E _ C L E A R ( )

ScriptProfile_Clear()
Description The ScriptProfile_Clear() function clears the script profile currently in
memory.

Syntax ScriptProfile_Clear()

Parameters • None

Return value The boolean value true.

Comments The script profile remains in memory until you clear it.

Examples The following example clears the script profile in memory.

local boolean result;

result = ScriptProfile_Clear();

522 F U N C T I O N L I B R A R Y R E F E R E N C E
 S C R I P T P R O F I L E _ S A V E ()

ScriptProfile_Save()
Description The ScriptProfile_Save() function saves the script profile currently in
memory to the specified output file.

Syntax ScriptProfile_Save(path, format)

Parameters • path – A string specifying the path and filename for the script profile being
written. The path must be in native format.

• format – An integer specifying the format to use for the script profile
information. Use one of the following constants:

Constant Description
TEXTFILE Script profile written as plain text.
TABFILE Script profile written with tab characters between
items.

Return value A boolean. The value true is returned if an output path has been specified.
The value false is returned in no output path has been specified.

Examples The following example saves the current script profile to the file named
ExplorerProfile.txt in the root folder.

local boolean result;

ScriptProfile_Save("c:\ExplorerProfile.txt", TEXTFILE);

FUNCTION LIBRARY REFERENCE 523

S C R I P T P R O F I L E _ S T A R T ()

ScriptProfile_Start()
Description The ScriptProfile_Start() function causes the application to start profiling
scripts.

Syntax ScriptProfile_Start()

Parameters • None

Return value The boolean value true.

Comments You may want to use the ScriptProfile_Clear() function to clear the current
script profile before starting the script profiler. Otherwise, the results will be
included with the current profile information in memory.

Examples The following example starts the process of profiling scripts.

local boolean result;

result = ScriptProfile_Clear();
result = ScriptProfile_Start();

524 F U N C T I O N L I B R A R Y R E F E R E N C E
 S C R I P T P R O F I L E _ S T O P ()

ScriptProfile_Stop()
Description The ScriptProfile_Stop() function causes the application to stop profiling
scripts.

Syntax ScriptProfile_Start()

Parameters • None

Return value The boolean value true.

Comments This function leaves the profile information in memory. Use the
ScriptProfile_Clear() function to clear the current script profile.

Examples The following example stops the process of profiling scripts.

local boolean result;

result = ScriptProfile_Stop();

FUNCTION LIBRARY REFERENCE 525

526 F U N C T I O N L I B R A R Y R E F E R E N C E
Shell function library
Use the functions in this library to access features of the single-document
interface (SDI) shell in Dexterity. This library contains the following
function:

• Shell_DisplayNotification()

FUNCTION LIBRARY REFERENCE 527

S H E L L _ D I S P L A Y N O T I F I C A T I O N ()

Shell_DisplayNotification()
Description The Shell_DisplayNotification() function causes a notification to be
displayed in the lower-right corner of the display. Notifications can be used
only when the SDI shell is being used for the application.

Syntax Shell_DisplayNotification(style, image_dict_ID, image_type, image_res_ID,

subject, message, dex_link)

Parameters • style – An integer specifying the style used for the notification. The value
corresponds to one of the following constants:

Constant Display timing

NOTIFICATION_STYLE_INFO 15 seconds
NOTIFICATION_STYLE_SUCCESS 15 seconds
NOTIFICATION_STYLE_FAILURE 15 seconds with a single display. 20
seconds when the system has multiple
displays.
NOTIFICATION_STYLE_SYSEVENT 15 seconds with a single display. 20
seconds when the system has multiple
displays.
NOTIFICATION_STYLE_USERINTERACTION 15 seconds with a single display. 20
seconds when the system has multiple
displays.

• image_dict_ID – An integer specifying the ID of the dictionary containing

the image to display for the notification.

• image_type – An integer specifying the type of image to use for the

notification. Use the constant DT_METAFILE to specify that native pictures
will be used.

• image_res_ID – An integer specifying the resource ID of the image to display

for the notification.

• subject – A string containing the subject line to display for the notification.

• message – A string or text value containing the text to display for the
notification.

• dex_link – A string containing the link that indicates the action to be

performed when the user clicks on the notification. The action is not
performed if the user clicks the close box in the notification. If no action is to
be performed, set this parameter to the empty string ("").

528 F U N C T I O N L I B R A R Y R E F E R E N C E
 S H E L L _ D I S P L A Y N O T I F I C A T I O N ()

Return value A boolean. The value true indicates the notification was successfully
displayed, while false indicates it was not.

Comments The following illustration shows a notification displayed for the user.

When there is user activity in the application, or the application is running

in the background, the notification will be displayed for the period
indicated for the notification style before it is automatically dismissed. If the
application is running in the foreground, but there is no user activity, the
notification will remain open until there is activity.

If multiple notifications are opened at once, they will be stacked vertically.

Try to keep the number of notifications displayed at once to three or fewer.

The string for the link specifies the procedure or form-level procedure to be
run when the user clicks the notification. The following syntax is used to
execute a global procedure when the notification is clicked:

http://dexterity/product=prod_ID/script=procedure/args=arg_val

The following syntax is used to execute a form-level procedure when the

notification is clicked:

http://dexterity/product=prod_ID/script=procedure/form=form/
args=arg_val

The prod_ID is the dictionary ID of the product that contains the procedure
to be run. The procedure value specifies the procedure to be run. The form
value is supplied to specify the form the form-level procedure to be run is
defined for. The arg_val is used to pass an integer value or string value to
the procedure being run. If an argument is to be passed from the
notification, the procedure being run must have an “in” parameter of type
integer or string to receive the value. If a string value is passed, the value
must be enclosed in single quotes. (''). If no argument is passed, it can be
omitted from the link string.

FUNCTION LIBRARY REFERENCE 529

S H E L L _ D I S P L A Y N O T I F I C A T I O N ()

Examples The following example displays a notification for the user. No action is
performed when the user clicks the notification.

local boolean result;

local integer iPicID;

{Retrieve the resource ID of the native picture}

iPicID = Resource_GetID(DYNAMICS, DT_METAFILE, "VS_Error_Icon_P_2");

{Display the notification}

result = Shell_DisplayNotification(NOTIFICATION_STYLE_SYSEVENT,
DYNAMICS,
DT_METAFILE,
iPicID,
"System Maintenance",
"Please exit the system before 6:00 pm so an update can be
➥ installed.",
"");

The following example displays a notification indicating a lead has been

qualified. When the user clicks the notification, an action is performed that
opens the lead for editing. The “Open” procedure defined for the form
IG_Lead_Maintenance is run when the user clicks the notification. The args
value of the link is used to pass the ID of the lead to display.

local boolean result;

local integer iPicID;

{Retrieve the resource ID of the native picture}

iPicID = Resource_GetID(DYNAMICS, DT_METAFILE, "VS_Error_Icon_P_1");

530 F U N C T I O N L I B R A R Y R E F E R E N C E
 S H E L L _ D I S P L A Y N O T I F I C A T I O N ()

{Display the notification}

result=Shell_DisplayNotification(NOTIFICATION_STYLE_USERINTERACTION,
DYNAMICS,
DT_METAFILE,
iPicID,
"Lead Qualified",
"The following lead has been qualified: 1003 -- Proseware, Inc.",
"http://dexterity/product=3333/script=Open/form=IG_Lead_Maintenance/
args='1003'");

The following is the “Open” procedure for the IG_Lead_Maintenance form

that is run when the user clicks the notification. It has one string “in”
parameter to receive the argument value passed from the notification.

in string LeadID;

open form IG_Lead_Maintenance;

'Lead ID' of window 'Lead Maintenance' = LeadID;
run script 'Lead ID' of window 'Lead Maintenance';

FUNCTION LIBRARY REFERENCE 531

532 F U N C T I O N L I B R A R Y R E F E R E N C E
 SQL function library
Refer to Chapter 49, Use the functions in this library to implement pass-through SQL in your
“Pass-through SQL,” in application. This library contains the following functions:
Volume 1 of the
Dexterity • SQL_Clear()
Programmer’s Guide • SQL_Connect()
for more information • SQL_DescribeColumn()
about using pass- • SQL_Execute()
through SQL. • SQL_FetchNext()
• SQL_GetData()
• SQL_GetError()
• SQL_GetNextResults()
• SQL_GetNumCols()
• SQL_GetNumRows()
• SQL_Terminate()

FUNCTION LIBRARY REFERENCE 533

SQ L_C L E A R ( )

SQL_Clear() SQL

Description The SQL_Clear() function clears any results sets and errors for the specified
pass-through SQL connection.

Syntax SQL_Clear(SQL_connection)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection for which results sets and errors will be cleared.

Return value A long integer indicating the status. The value 0 is returned if the results set
was successfully cleared. Any other value indicates an error occurred.

Comments Use the SQL_Clear() function if you will be executing several sets of SQL
statements using one pass-through SQL connection.

Examples The following example clears the results sets and errors for the pass-
through SQL connection indicated by the SQL_connection variable.

local long status;

{Clear the results sets and errors.}

status = SQL_Clear(SQL_connection);
if status <> 0 then
error "An error occurred clearing the pass-through SQL
➥ connection.";
end if;

534 F U N C T I O N L I B R A R Y R E F E R E N C E
 S Q L _ C O N N E C T ()

SQL_Connect() SQL

Description The SQL_Connect() function creates a new pass-through SQL connection

using the current SQL login.

Syntax SQL_Connect(SQL_connection)

Parameters • SQL_connection – A returned long integer containing the ID of the new pass-
through SQL connection.

Return value A long integer indicating the status of the pass-through SQL connection.
The value 0 is returned if the connection was successfully created. Any
other value indicates an error occurred.

Comments The pass-through SQL connection is active until you use the
SQL_Terminate() function to terminate it.

Examples The following example creates a pass-through SQL connection to the

current SQL data source.

local long SQL_connection;

local long status;

{Connect to the SQL data source.}

status = SQL_Connect(SQL_connection);
if status <> 0 then
error "An error occurred creating the pass-through SQL
➥ connection.";
end if;

FUNCTION LIBRARY REFERENCE 535

SQ L_D E S C R I B E C O L U M N ()

SQL_DescribeColumn() SQL

Description The SQL_DescribeColumn() function retrieves information about the

specified column of the current results set for the specified pass-through
SQL connection.

Syntax SQL_DescribeColumn(SQL_connection, column, column_name, datatype,

precision, scale)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection to use.

• column – An integer specifying the column in the current results set for
which information will be returned. The value 1 indicates the first column.

• column_name – A string containing the physical name of the column.

• datatype – An integer indicating the datatype associated with the column.

The value corresponds to one of the following constants:

DATATYPE_BOOLEAN DATATYPE_LONG_INTEGER
DATATYPE_VCURRENCY DATATYPE_STRING
DATATYPE_DATE DATATYPE_TEXT
DATATYPE_INTEGER DATATYPE_TIME

Currency and variable currency columns always return the value

DATATYPE_VCURRENCY.

• precision – If the column contains currency or variable currency data, a long

integer indicating the precision (total number of digits available) for each
value.

• scale – If the column contains currency or variable currency data, an integer

indicating the scale (the number of decimal digits) for each value.

Return value A long integer indicating whether information was retrieved. The value 0 is
returned if description information was successfully retrieved. Any other
value indicates an error occurred.

536 F U N C T I O N L I B R A R Y R E F E R E N C E
 SQ L _ D E S C R I B E C O L U M N ()

Examples The following example retrieves information about the second column in
the current results set for the pass-through SQL connection specified by the
SQL_connection variable.

local long status;

local string name;
local integer type;
local long precision;
local integer scale;

status = DescribeColumn(SQL_connection, 2, name, type, precision,

➥ scale);
if status <> 0 then
error "Unable to retrieve the column description.";
end if;

FUNCTION LIBRARY REFERENCE 537

SQ L_E X E C U T E ()

SQL_Execute() SQL

Description The SQL_Execute() function executes the SQL string using the pass-
through SQL connection specified.

Syntax SQL_Execute(SQL_connection, SQL_string)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection through which the SQL string will be executed.

• SQL_string – A text field containing the SQL statements to be executed. The

text field can be a window field, table field or text local variable.

Return value A long integer indicating the status of the SQL execution. The value 0 is
returned if the statements were executed successfully. Any other value
indicates an error occurred.

Comments Use the SQL_GetError() function to retrieve specific information about any
error that occurred while executing SQL statements.

In certain cases, you may need to execute more than 32K of SQL statements
at one time. You can do this using an array of text fields. Copy the first 32K
of SQL statements into the first element of the text array, the next 32K of
statements into the second element, and so on. Then pass the first element
of the array to the SQL_Execute() function. The array elements will
automatically be assembled and the SQL statements will be executed in the
appropriate order. For example, the following statement executes the SQL
statements in the SQL_Statements array field.
status = SQL_Execute(SQL_connection, field SQL_Statements[1]);

If you use the same text field array to execute several sets of SQL statements, be
sure to clear out any unused elements of the array before you execute additional
statements. Otherwise, you may inadvertently run some SQL statements from the
previous set.

Examples The following example uses pass-through SQL to retrieve information from
SQL tables for the Real Estate Sales Manager sample application. First,
a SQL statement is executed to switch to the RESM database. Then two
more SQL statements are executed that retrieve seller and house
information for a specified seller. Two results sets are returned. The first
contains seller information, while the second contains house information.
The retrieved information is formatted and displayed in a warning message
displayed to the user.

538 F U N C T I O N L I B R A R Y R E F E R E N C E
 SQ L _ E X E C U T E ()

local long SQL_connection, status;

local string seller_ID;
local boolean result;
local 'Query_Results' query_results; {A global text field definition}

{Query information}
local string seller_first_name, seller_last_name;
local string house_address, house_city;

{SQL error information}

local long GPS_error_number, SQL_error_number;
local string SQL_error_string, ODBC_error_string;

{Connect to the SQL data source.}

status = SQL_Connect(SQL_connection);
if status = 0 then
{Build SQL statement to use the appropriate database.}
SQL_Statements = "use RESM";
{Execute the SQL statements.}
status = SQL_Execute(SQL_connection, field SQL_Statements);
if status = 0 then
{Were able to switch to the RESM database.}
{Ask which Seller to display information for.}
result = getstring("Enter a Seller ID", false, seller_ID);
if result = true then
{Build the SQL statements. Store them in a hidden window
field.}
SQL_Statements = "select * from SELLDAT where Seller_ID "
➥ + "= '" + seller_ID + "'" + char(13) +
➥ "select * from HOUSEDAT where Seller_ID = '" +
➥ seller_ID + "'";
{Execute the SQL statements.}
status = SQL_Execute(SQL_connection, field
➥ SQL_Statements);
if status = 0 then
{Retrieve data from the first results set.}
status = SQL_FetchNext(SQL_connection);
if status <> 31 then
{Get the information about the seller.}
status = SQL_GetData(SQL_connection, 2,
➥ seller_first_name);
status = SQL_GetData(SQL_connection, 3,
➥ seller_last_name);

FUNCTION LIBRARY REFERENCE 539

SQ L_E X E C U T E ()

{Begin building the output.}

query_results = "Seller ID: " + seller_ID +
➥ char(13) + "Seller Name: " + seller_first_name +
➥ " " + seller_last_name + char(13) + "Houses: " +
➥ char(13);
{Retrieve data from the next results set.}
status = SQL_GetNextResults(SQL_connection);
if status = 0 then
{There is house information.}
status = SQL_FetchNext(SQL_connection);
while status <> 31 do
status = SQL_GetData(SQL_connection, 5,
➥ house_address);
status = SQL_GetData(SQL_connection, 6,
➥ house_city);
query_results = query_results +
➥ house_address + ", " + house_city +
➥ char(13);
status = SQL_FetchNext(SQL_connection);
end while;
end if;
{Finished processing the results. Display them.}
warning query_results;
else
error "No information available for this seller.";
end if;
else
error "An error occurred executing SQL statements.";
{Retrieve the specific error information.}
status = SQL_GetError(SQL_connection,
➥ GPS_error_number, SQL_error_number,
➥ SQL_error_string, ODBC_error_string);
if status = 0 then
warning "GPS Error: " + str(GPS_error_number);
warning "SQL Error: " + str(SQL_error_number) + " "
➥ + SQL_error_string;
warning "ODBC Error: " + ODBC_error_string;
else
error "Unable to retrieve SQL error information.";
end if;
end if;
end if;

540 F U N C T I O N L I B R A R Y R E F E R E N C E
 SQ L _ E X E C U T E ()

else
error "Could not switch to the correct database.";
end if;
{Disconnect from the SQL data source.}
status = SQL_Terminate(SQL_connection);
else
{An error occurred creating the pass-through SQL connection.}
warning "An error occurred creating the pass-through SQL
➥ connection: " + str(status);
end if;

FUNCTION LIBRARY REFERENCE 541

SQ L_F E T C H N E X T ( )

SQL_FetchNext() SQL

Description The SQL_FetchNext() function retrieves the next row from the current
results set for the specified pass-through SQL connection.

Syntax SQL_FetchNext(SQL_connection)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection.

Return value A long integer indicating the status of the fetch operation. The value 0
indicates a row was successfully retrieved. The value 31 indicates there is
no more data in the results set. Any other value indicates another error
occurred while retrieving the next row in the results set.

Comments You must execute the SQL_FetchNext() function one time to move to the
first row in the current results set.

Once you have moved to the next row in a results set, you can’t return to
the previous row. If the number of rows in the results set is not known, use
the SQL_FetchNext() function to move to the next row in the results set
until error 31 is returned.

Use the SQL_GetData() function to retrieve data from the current line in
the results set.

Examples Refer to the example for SQL_Execute().

542 F U N C T I O N L I B R A R Y R E F E R E N C E
 SQ L_G E T D A T A ()

SQL_GetData() SQL

Description The SQL_GetData() function returns the data in the specified column in the
current row of the current results set for the specified pass-through SQL
connection.

Syntax SQL_GetData(SQL_connection, column, data)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection to use.

• column – A long integer specifying the column in the current results set
from which data will be returned. The value 1 indicates the first column.

• data – The data returned. The storage type of this variable or field must be
compatible with the value returned. When possible, the value returned will
be converted to the storage type of the variable or field.

Return value A long integer indicating the status of the retrieval operation. The value 0
indicates data was successfully retrieved. Any other value indicates an
error occurred.

Examples Refer to the example for SQL_Execute().

FUNCTION LIBRARY REFERENCE 543

SQ L_G E T E R R O R ( )

SQL_GetError() SQL

Description The SQL_GetError() function returns information about the last error that
occurred for the current results set of the specified pass-through SQL
connection.

Syntax SQL_GetError(SQL_connection, internal_error_number, SQL_error_number,

SQL_error_string, ODBC_error_string)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection for which error information will be returned.

• internal_error_number – A long integer containing the internal error code

corresponding to the error that occurred. The following table lists the
common error codes:

Value Description
0 No error
41 Can’t find specified column
56 Can’t find specified table
58 Syntax error in SQL statement

• SQL_error_number – A long integer containing the native SQL Server™

error code for the error that occurred.

• SQL_error_string – A string containing the text for the native SQL Server
error that occurred.

• ODBC_error_string – A string containing the ODBC error that occurred.

Return value A long integer indicating whether error information was available and
successfully retrieved. If the value is 0, error information was available
and successfully retrieved.

544 F U N C T I O N L I B R A R Y R E F E R E N C E
 SQL _ G E T E R R O R ()

Examples The following example retrieves and displays information about the last
error that occurred for the pass-through SQL connection specified by the
SQL_connection variable. The errors are displayed in a series of messages
for the user.

local long status, GPS_error_number, SQL_error_number;

local string SQL_error_string, ODBC_error_string;

status = SQL_GetError(SQL_connection, GPS_error_number,

➥ SQL_error_number, SQL_error_string, ODBC_error_string);
if status = 0 then
error "GPS Error: " + str(GPS_error_number);
error "SQL Error: " + str(SQL_error_number) + " " +
➥ SQL_error_string;
error "ODBC Error: " + ODBC_error_string;
else
error "Unable to retrieve SQL error information.";
end if;

FUNCTION LIBRARY REFERENCE 545

SQ L_G E T N E X T R E S U L T S ()

SQL_GetNextResults() SQL

Description The SQL_GetNextResults() function moves to the next results set for the
specified pass-through SQL connection.

Syntax SQL_GetNextResults(SQL_connection)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection for which the next results set will be selected.

Return value A long integer indicating whether the operation was successful. The value 0
indicates the next results set was successfully moved to. The value 31
indicates there are no more results sets for the pass-through SQL
connection. Any other value indicates another error occurred.

Comments Once you have moved to the next results set, you can’t return to the
previous results set. If the number of results sets is not known, use the
SQL_GetNextResults() function to move to the next results set until error
31 is returned.

Examples Refer to the example for SQL_Execute().

546 F U N C T I O N L I B R A R Y R E F E R E N C E
 S Q L _ G E T N U M C O L S ()

SQL_GetNumCols() SQL

Description The SQL_GetNumCols() function returns the number of columns in the

current results set for the specified pass-through SQL connection.

Syntax SQL_GetNumCols(SQL_connection, num_columns)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection to use.

• num_columns – A returned long integer containing the number of columns

in the current results set.

Return value A long integer indicating whether the operation was successful. The value 0
indicates the number of columns was successfully retrieved. Any other
value indicates an error occurred.

Examples The following example retrieves the number of columns in the current
results set for the pass-through SQL connection specified by the
SQL_connection variable.

local long status;

local long num_cols;

status = SQL_GetNumCols(SQL_connection, num_cols);

if status <> 0 then
error "Unable to retrieve the number of columns.";
end if;

FUNCTION LIBRARY REFERENCE 547

SQ L_G E T N U M R O W S ( )

SQL_GetNumRows() SQL

Description The SQL_GetNumRows() function returns the number of rows that were
affected by a write operation for the specified pass-through SQL
connection.

Syntax SQL_GetNumRows(SQL_connection, num_rows)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection to use.

• num_rows – A returned long integer containing the number of rows that

were affected by a write operation.

Return value A long integer indicating whether the operation was successful. The value 0
indicates that the number of rows affected was successfully retrieved. Any
other value indicates an error occurred.

Comments The SQL_GetNumRows() function does not return the number of rows in a
results set.

For this function to properly return the number of rows affected, the
“nocount” flag must be turned off for the pass-through SQL connection.
You can turn this flag off by executing the following SQL statement:

set nocount off

After you have finished executing SQL statements and using the
SQL_GetNumRows() function to find out how many rows were affected,
be sure to set the “nocount” flag to on. Do this using the following SQL
statement:

set nocount on

This is the state that Dexterity expects the pass-through SQL connection to
be in.

548 F U N C T I O N L I B R A R Y R E F E R E N C E
 S Q L _ G E T N U M R O W S ()

Examples The following example deletes rows from the HOUSEDAT table where the
City is Fargo. The SQL_GetNumRows() function retrieves the number of
rows that were affected.

local long SQL_connection, status, num_rows;

status = SQL_Connect(SQL_connection);
if status = 0 then
{Be sure the nocount flag is set properly.}
SQL_Statements = "set nocount off";
status = SQL_Execute(SQL_connection, field SQL_Statements);
{Store the SQL statement in hidden window field.}
SQL_Statements = "delete from HOUSEDAT where City = 'Fargo'";
{Execute the SQL statement.}
status = SQL_Execute(SQL_connection, field SQL_Statements);
if status = 0 then
{Display the number of rows affected.}
status = SQL_GetNumRows(SQL_connection, num_rows);
warning "Number of rows affected: " + str(num_rows);
else
error "An error occurred executing the SQL statement.";
end if;
status = SQL_Terminate(SQL_connection);
else
error "Unable to create the pass-through SQL connection.";
end if;

FUNCTION LIBRARY REFERENCE 549

SQ L_T E R M I N A T E ( )

SQL_Terminate() SQL

Description The SQL_Terminate() function deletes the specified pass-through SQL

connection.

Syntax SQL_Terminate(SQL_connection)

Parameters • SQL_connection – A long integer specifying the pass-through SQL

connection that will be deleted.

Return value A long integer indicating whether the terminate operation was successful.
The value 0 indicates the pass-through SQL connection was successfully
terminated. Any other value indicates an error occurred.

Comments Pass-through SQL connections are active until you use the
SQL_Terminate() function to terminate them.

Examples The following example terminates the pass-through SQL connection

indicated by the SQL_connection variable.

local long status;

{Terminate the pass-through SQL connection.}

status = SQL_Terminate(SQL_connection);
if status <> 0 then
error "An error occurred terminating the pass-through SQL
➥ connection.";
end if;

550 F U N C T I O N L I B R A R Y R E F E R E N C E
Table function library
Use the functions in this library when implementing table maintenance
routines or specifying special options for tables. This library contains the
following functions:

• Table_AutoShrink()
• Table_Compare()
• Table_CopyShrinkRecords()
• Table_CreateIndexes()
• Table_CreateProcedures())
• Table_DisableErrorChecks()
• Table_DropProcedures()
• Table_EndConversion()
• Table_EndShrink()
• Table_FillGroupList()
• Table_FillList()
• Table_FlushCache()
• Table_GetAutoShrinkMode()
• Table_GetDisplayName()
• Table_GetFieldList()
• Table_GetGroup()
• Table_GetKeyFieldList()
• Table_GetKeyInfo()
• Table_GetKeyOption()
• Table_GetNumberOfKeys()
• Table_GetOSName()
• Table_GetRangeKey()
• Table_GetSeries()
• Table_GetSQLErrorText()
• Table_IsRangeSet()
• Table_OpenAsTemp()
• Table_OpenNewBuffer()
• Table_RebuildIndexes()
• Table_SetCreateMode()
• Table_SetDBType()
• Table_SetDeleteOptions()
• Table_SetRefreshFlags()
• Table_StartConversion()
• Table_StartShrink()
• Table_Truncate()
• Table_VerifyRecord()

FUNCTION LIBRARY REFERENCE 551

 Some of the functions in this library work together to perform certain
operations. The related functions are grouped in the following lists.

Refer to Chapter 26, These functions list table groups and the tables in table groups:
“Table Groups,” in Vol-
ume 1 of the Dexterity • Table_FillGroupList()
Programmer’s Guide • Table_FillList()
for more information
about table groups. These functions are used for automatically shrinking and rebuilding tables
and indexes:

Refer to Chapter 11, • Table_AutoShrink()

“Table Maintenance,” • Table_GetAutoShrinkMode()
in the Stand-alone • Table_RebuildIndexes()
Application Guide for
more information These functions are used to manually shrink and rebuild tables and
about table mainte- indexes:
nance routines.
• Table_StartShrink()
• Table_VerifyRecord()
• Table_CopyShrinkRecords()
• Table_EndShrink()

Refer to Chapter 60, These functions are used to convert data for tables that have had their table
“Updating an Applica- definitions changed:
tion,” in Volume 1 of
the Dexterity • Table_StartConversion()
Programmer’s Guide • Table_EndConversion()
for information about
converting data. These functions are used for SQL tables:

• Table_Compare()
• Table_CreateIndexes()
• Table_CreateProcedures()
• Table_SetDeleteOptions()
• Table_DropProcedures()
• Table_SetRefreshFlags()
• Table_Truncate()

552 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ A U T O S H R I N K ()

Table_AutoShrink()
Description The Table_AutoShrink() function shrinks a data table and rebuilds the
table’s indexes if the current database manager is capable of performing
such operations. The Table_GetAutoShrinkMode() function must be used
prior to this function to ascertain whether the current database manager has
these capabilities.

Syntax Table_AutoShrink(table table_name)

Parameters • table table_name – The name of the table you want to shrink.

Return value An integer containing the error code returned by the database manager. A
return value of zero indicates no error occurred. Consult your database
manager’s reference manual for a list of error codes.

Comments Since some database managers have provisions for performing table
shrinks, this function transfers the shrink process to the database manager.
Currently, c-tree and Pervasive.SQL tables can be shrunk using
Table_AutoShrink().

Shrinking is the process of removing unused space in a data table. The

removal of unused space in this manner is called a “shrink” because the
table will invariably be smaller after the unused space is removed. The
shrink process copies the contents of the original table to a secondary table.
After the copy is complete, the original table is deleted and the secondary
table is renamed to take the place of the first table. The process of copying
records to the new table eliminates the unused space.

The c-tree Plus database manager also rebuilds the table’s indexes during
the shrink. Indexes are stored in the .IDX file with the same name to the left
of the extension as the data table. You can use Table_RebuildIndexes() if
you want to rebuild the indexes without shrinking the table.

We recommend that you shrink data tables frequently as part of periodic application
maintenance. This will help ensure data integrity and optimal
application performance. It will also optimize disk space usage where tables are
stored.

FUNCTION LIBRARY REFERENCE 553

T A B L E _ A U T O S H R I N K ( )

Examples The following example uses Table_GetAutoShrinkMode() to ascertain

whether the current database manager supports automatic table shrinks. If
so, the table is shrunk using Table_AutoShrink(). Otherwise, the shrink
process is carried out using Table_StartShrink(), Table_VerifyRecord(),
Table_CopyShrinkRecords() and Table_EndShrink(). The product ID is
represented by the constant INVENT_PRODID.

local string l_field_name;

local integer l_result, l_errorcode;

{Find out whether the database manager shrinks tables. If it does,

perform the shrink using Table_AutoShrink().}

close table Inventory_Data;

{Find out whether the database manager can perform a table shrink
automatically.}
l_result = Table_GetAutoShrinkMode(table Inventory_Data);
if l_result = 0 then
{Use the automatic table shrink function.}
l_result = Table_AutoShrink(table Inventory_Data);
close table Inventory_Data;
if l_result <> 0 then
warning "An error occurred when shrinking the table.";
end if;
else
{The database manager doesn't shrink tables. Shrink tables manually
using Table_StartShrink(), Table_VerifyRecord(),
Table_CopyShrinkRecords() and Table_EndShrink() instead.}
{Open the selected table with exclusive use.}
open table Inventory_Data, exclusive;
if err()<>OKAY then
warning "This table is already in use.";
abort script;
end if;

{Create the temporary table.}

l_errorcode = Table_StartShrink(INVENT_PRODID, table
➥ Inventory_Data, "");
if l_errorcode<>0 then
error "Unable to create the temporary table for the table
➥ shrink.";
else
{The temporary table was created successfully.}

554 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ A U T O S H R I N K ()

change first table Inventory_Data;

while err()<>EOF do
{Verify the record using Table_VerifyRecord().}
l_errorcode = Table_VerifyRecord(INVENT_PRODID, table
➥ Inventory_Data, l_field_name);
if l_errorcode < 600 or l_errorcode > 610 then
{The integrity of the record has been verified,
so attempt to transfer it.}
l_errorcode = Table_CopyShrinkRecords (INVENT_PRODID,
➥ table Inventory_Data);
if l_errorcode <> 0 then
{An error occurred while attempting to
transfer the record to the temporary table.}
warning "Error number " + str(l_errorcode)
➥ +" occurred while transferring shrink record.";
end if;
else
{The integrity of the record couldn't be verified.
Display an error message.}
warning "Error number " + str(l_errorcode) +
➥ " occurred for field " + l_field_name;
end if;
{Release the lock on the current record and read the
next.}
release table Inventory_Data;
change next table Inventory_Data;
end while;
{Use Table_EndShrink() to finish the table shrink.}
l_errorcode = Table_EndShrink(INVENT_PRODID, table
➥ Inventory_Data);
if l_errorcode <> 0 then
error "Unable to complete the table shrink.";
end if;
end if;
end if;

Related items Commands

Table_GetAutoShrinkMode(), Table_StartShrink(), Table_CopyShrinkRecords(),
Table_EndShrink(), Table_VerifyRecord()

Additional information
Chapter 11, “Table Maintenance,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 555

T A B L E _ C O M P A R E ()

Table_Compare() SQL

Description The Table_Compare() function compares the structure of an existing table

on the current data source to that table’s definition in the application
dictionary.

Syntax Table_Compare(table table_name)

Parameters • table table_name – The name of the table to be validated.

Return value An integer corresponding to one of the following constants:

Constant Description
STATUS_SUCCESS The table structure and table definition match.
STATUS_ERROR Discrepancies were found between the table structure
and the table definition, or some other error occurred.

Comments If you create your own tables outside of Dexterity, or are creating a
Dexterity application to access data in an existing SQL table, use the
Table_Compare() function to verify that the application dictionary’s table
definition matches the actual table in the data source.

Examples The following example compares the structure of the Inventory table on the
current data source to the table definition of the Inventory table in the
current application dictionary.

local integer status;

status = Table_Compare(table Inventory);

if status = STATUS_SUCCESS then
warning "The table structure and table definition match.";
else
warning "An error occurred. The table structure and table
➥ definition may not match.";
end if;

556 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ C O P Y S H R I N K R E C O R D S ()

Table_CopyShrinkRecords()
Description The Table_CopyShrinkRecords() function copies a record from the
original table to the temporary table created using Table_StartShrink().

Syntax Table_CopyShrinkRecords(product_ID, table table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table being shrunk.

• table table_name – The original table being shrunk.

Return value An integer describing the result of the transfer. The result is 0 if the record
was copied successfully. Any other value indicates a record transfer error.
The following list shows the errors and their corresponding integer values:

0 – No error 20 – Transaction in progress

1 – Low on memory
2 – Database manager not initialized
3 – Database manager not supported
4 – Too many tables opened
5 – Record length too long
6 – Too many keys for database type
7 – Too many segments
8 – Table not registered
9 – Table not found
10 – Locked record
11 – Table name error
12 – Table not open
13 – Table not opened exclusive
14 – Invalid command sent to database
manager
15 – Key number doesn’t exist
16 – End of file
17 – Duplicate record
18 – Table is missing
19 – A set is already active
21 – Not a variable length table
22 – No table definition could be found
23 – Attempted to lock two records
24 – No lock on update
25 – Table doesn’t match definition
26 – The disk is full
27 – Unknown error
28 – A non-modifiable key changed
29 – Not a variable length field
30 – A record was changed with a passive
lock
31 – Deadlocked
32 – Path not found
33 – Buffer error
34 – Error in creating a P.SQL table
35 – Invalid key definition
36 – Maximum number of SQL connections
reached.
37 – Error accessing SQL data
38 – Error converting SQL data
39 – Error generating SQL data

FUNCTION LIBRARY REFERENCE 557

T A B L E _ C O P Y S H R I N K R E C O R D S ()

Comments This function is used in the table shrinking process. Shrinking is the process
of removing unused space from a data table. The
Table_CopyShrinkRecords() function copies the contents of the original
table to the temporary table created with Table_StartShrink(). This transfer
allows the temporary table to store only records from the original table;
excess space in the original table isn’t transferred to the temporary table.
After all records have been copied, Table_EndShrink() finishes the table
shrink.

Examples Refer to the example following the description of Table_EndShrink().

Related items Commands

Table_StartShrink(), Table_EndShrink(), Table_VerifyRecord()

Additional information
Chapter 11, “Table Maintenance,” in the Dexterity Stand-alone Application Guide

558 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ C R E A T E I N D E X E S ()

Table_CreateIndexes() SQL

Description The Table_CreateIndexes() function creates the indexes for the specified
table on a data source.

Syntax Table_CreateIndexes(product_ID, table table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table for which indexes are being created.

• table table_name – The table for which indexes are being created.

Return value An integer indicating whether indexes were created. The result is 0 if the
indexes were created successfully. Any other value indicates indexes could
not be created.

Comments If you have altered the indexes for tables on the data source, you can use
this function to re-create the indexes for tables in your application.

Before you use the Table_CreateIndexes() function, the table must not have
any indexes (including primary key constraints) that have the same names
as those created by Dexterity. If any indexes with these names exist for the
table, the Table_CreateIndexes() function will fail.

If you will be using bulk copy (bcp) to copy data to your application’s SQL
tables, you may want to drop all indexes for the tables you’re copying data
to. By removing the indexes, the bulk copy operations can be performed
much faster. Once all of the data has been copied, use the
Table_CreateIndexes() function to re-create the indexes for the tables.

Keep in mind that creating indexes for a large data set can take a considerable
amount of time.

Examples The following example creates the indexes for the Seller_Data table. The
product ID is represented by the constant RESM_PRODID.

local integer status;

status = Table_CreateIndexes(RESM_PRODID, table Seller_Data);

if status <> 0 then
error "Indexes could not be created for table Seller_Data.";
end if;

FUNCTION LIBRARY REFERENCE 559

T A B L E _ C R E A T E P R O C E D U R E S ( )

Table_CreateProcedures() SQL

Description The Table_CreateProcedures() function creates the stored procedures for

the specified table on a data source.

Syntax Table_CreateProcedures(product_ID, table table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table for which stored procedures will be created.

• table table_name – The table for which stored procedures will be created.

Return value An integer indicating whether stored procedures were created. The result is
0 if the stored procedures were created successfully. Any other value
indicates stored procedures could not be created.

Comments When you use Dexterity to create a table, Dexterity automatically generates
several stored procedures for the table, which are used to optimize database
performance. Typically, Dexterity generates these stored procedures the
first time it opens the table. If you create a table by some means other than
Dexterity, you must use this function to generate the stored procedures for
the table.

Before you use the Table_CreateProcedures() function, the table must not
have any stored procedures that have the same names as those created by
Dexterity. If any stored procedures with these names exist for the table, the
Table_CreateProcedures() function will fail. Names of stored procedures
created by Dexterity have the form zDP_ followed by the table physical
name and a code indicating the purpose of the stored procedure. The
following table lists the various stored procedures created by Dexterity.

Stored Purpose Quantity Comments

procedure code
Insert SI One per table Created only if the table
doesn’t contain text or picture
fields.
Delete SD One per table Created only if active locking
is not allowed for the table.
Select SS One for each key
First F One for each key
Last L One for each key
Next N One for each key
Unpositioned next UN One for each non-
unique key

560 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ C R E A T E P R O C E D U R E S ()

For example, the Seller_Data table has the physical name SELLDAT. The
table has three keys, one of which is unique. Dexterity creates 13 stored
procedures for this table. The stored procedures are listed in the following
table.

Stored procedure Description

zDP_SELLDATSI Insert stored procedure
zDP_SELLDATSD Delete stored procedure
zDP_SELLDATSS_1 Select stored procedures (one for each key)
zDP_SELLDATSS_2
zDP_SELLDATSS_3
zDP_SELLDATF_1 Select first stored procedure (one for each key)
zDP_SELLDATF_2
zDP_SELLDATF_3
zDP_SELLDATL_1 Select last stored procedure (one for each key)
zDP_SELLDATL_2
zDP_SELLDATL_3
zDP_SELLDATN_1 Select next stored procedure (one for each key)
zDP_SELLDATN_2
zDP_SELLDATN_3
zDP_SELLDATUN_2 Unpositioned next procedures (one for each
zDP_SELLDATUN_3 non-unique key)

As new versions of Dexterity are released, the auto-generated stored

procedures often are enhanced to improve SQL performance. To take
advantage of the updated auto-generated stored procedures, you need to
update the stored procedures for your application. First, you must remove
the existing stored procedures and use Dexterity to create new ones. You
can use the Table_DropProcedures() function to drop the existing
procedures, and then use the Table_CreateProcedures() function to create
the new stored procedures.

After you’ve created the new stored procedures, be sure to grant privileges to the
appropriate users.

FUNCTION LIBRARY REFERENCE 561

T A B L E _ C R E A T E P R O C E D U R E S ( )

Examples The following example uses the Table_DropProcedures() function to delete

the auto-generated stored procedures for the Inventory_Data table. Then
the Table_CreateProcedures() function creates new stored procedures for
the table. The product ID is represented by the constant INVENT_PRODID.

local integer result;

{Drop the stored procedures.}

result = Table_DropProcedures(INVENT_PRODID, table Inventory_Data);
if result = 0 then
{Stored procedures were successfully dropped; create new ones.}
result = Table_CreateProcedures(INVENT_PRODID, table
➥ Inventory_Data);
if result <> 0 then
error "Stored procedures were not successfully created.";
end if;
else
error "Stored procedures could not be dropped.";
end if;

Related items Commands

Table_DropProcedures()

562 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ D I S A B L E E R R O R C H E C K S ()

Table_DisableErrorChecks()
Description The Table_DisableErrorChecks() function allows Dexterity to ignore
automatic error checking for table operations.

Syntax Table_DisableErrorChecks(disable)

Parameters • disable – A boolean that sets the error checking status. The value true
disables error checking; false enables error checking.

Return value The boolean value true.

Comments If you disable error checking, the Dexterity Data Management Subsystem
will ignore the following errors for table operations:
0 – No error
1 – Low on memory
2 – Database manager not initialized
3 – Database manager not supported
4 – Too many tables opened
5 – Record length too long
6 – Too many keys for database type
7 – Too many segments
8 – Table not registered
9 – Table not found
10 – Locked record
11 – Table name error
12 – Table not open
13 – Table not opened exclusive
14 – Invalid command sent to database
manager
15 – Key number doesn’t exist
16 – End of file
17 – Duplicate record
18 – Table is missing
19 – A set is already active
20 – Transaction in progress
21 – Not a variable length table
22 – No table definition could be found
23 – Attempted to lock two records
24 – No lock on update
25 – Table doesn’t match definition
26 – The disk is full
27 – Unknown error
28 – A non-modifiable key changed
29 – Not a variable length field
30 – A record was changed with a passive
lock
31 – Deadlocked
32 – Path not found
33 – Buffer error
34 – Error in creating a P.SQL table
35 – Invalid key definition
36 – Maximum number of SQL connections
reached
37 – Error accessing SQL data
38 – Error converting SQL data
39 – Error generating SQL data

When you use this function to disable error checking, always enable error checking
before the script is completed.

Examples The following example shuts off automatic error checking:

local boolean result;

result = Table_DisableErrorChecks(true);

FUNCTION LIBRARY REFERENCE 563

T A B L E _ D R O P P R O C E D U R E S ()

Table_DropProcedures() SQL

Description The Table_DropProcedures() function drops the stored procedures for the
specified table on a data source.

Syntax Table_DropProcedures(product_ID, table table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table for which stored procedures will be dropped.

• table table_name – The table for which stored procedures will be dropped.

Return value An integer indicating whether stored procedures were dropped. The result
is 0 if the stored procedures were dropped successfully. Any other value
indicates stored procedures could not be dropped.

Comments Applications based on Dexterity 4.0 and later don’t require as many auto-
generated stored procedures as applications based on Dexterity 3.X. If you
created auto-generated stored procedures with Dexterity 3.X and executed
the Table_DropProcedures() function from Dexterity 4.0 or later, not all of
the stored procedures will be dropped. These “leftover” stored procedures
from Dexterity 3.X aren’t used by Dexterity 4.0 or later, and will cause no
problems; they simply take a small amount of space in the database.

Examples Refer to the example for Table_CreateProcedures().

Related items Commands

Table_CreateProcedures()

564 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ E N D C O N V E R S I O N ()

Table_EndConversion()
Description The Table_EndConversion() function finishes a table conversion. If the
table was converted successfully, this function deletes the source table and
renames the destination temporary table to take the place of the source
table. If the table was not converted successfully, the source table is kept
and the destination temporary table is deleted.

The Table_End_Conversion() function can be used only for c-tree and

Pervasive.SQL tables. It can’t be used for SQL tables.

Syntax Table_EndConversion(table source_table, table destination_table,

l_converted)

Parameters • table source_table – The technical name of the source table. (Note that unlike
Table_StartConversion(), this isn’t a string parameter.)

• table destination_table – The technical name of the destination table. (Note

that unlike Table_StartConversion(), this isn’t a string parameter.)

• l_converted – A boolean indicating whether the table conversion was

successful. If true is passed to this parameter, the source table will be
deleted and the destination temporary table will be renamed to take the
place of the source table. If false is passed to this parameter, the source table
will be kept and the destination temporary table will be deleted.

Return value An integer value indicating whether any table errors occurred while the
source and destination tables were being renamed or deleted. The values
returned correspond to those returned by the err() function.

Comments During the table conversion process, you must monitor whether any
unexpected table errors occurred. If any unexpected errors occur, false
should be passed to the l_converted parameter so the original table won’t be
deleted.

Examples Refer to the example for Table_StartConversion().

Related items Commands

Table_StartConversion()

Additional information
Chapter 60, “Updating an Application,” in Volume 1 of the Dexterity Programmer’s
Guide

FUNCTION LIBRARY REFERENCE 565

T A B L E _ E N D S H R I N K ( )

Table_EndShrink()
Description The Table_EndShrink() function closes the shrink table and finishes the
table shrink.

Syntax Table_EndShrink(product_ID, table table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table being shrunk.

• table table_name – The name of the original table being shrunk.

Return value An integer containing the result of the function. The result is 0 if the shrink
table was successfully closed.

Comments This function is used to complete the table shrinking process. Shrinking is
the process of removing unused space from a data table. The
Table_CopyShrinkRecords() function copies the contents of the original
table to the temporary table created with Table_StartShrink(). This transfer
allows the temporary table to store only records from the original table;
excess space in the original table isn’t transferred to the temporary table.

After the copy is complete, the Table_EndShrink() function completes the

table shrink. Depending upon the location of the temporary table,
Table_EndShrink() will do one of the following:

• If the temporary table created by Table_StartShrink() is created in the

same directory as the original table, the original table is removed and the
temporary is renamed. Thus, the temporary table becomes the new table.

• If the temporary table is created in a different directory, the original

table is deleted and re-created, and this command copies all the records
from the temporary table to the new original table. The temporary table
is then deleted.

Examples The following example uses the functions Table_StartShrink(),

Table_CopyShrinkRecords() and Table_EndShrink() to shrink a table.
The Table_VerifyRecord() function also is used to verify the contents of
each record processed during the shrink. Although this example displays a
warning indicating any errors returned by Table_VerifyRecord(), you may
want to save any errors to a log file so they can be reviewed in their entirety
after the shrink is complete. The product ID is represented by the constant
INVENT_PRODID.

566 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ E N D S H R I N K ()

local string l_field_name;

local integer l_error_code;

{Open the selected table for exclusive use.}

open table Inventory_Data, exclusive;
if err()<>OKAY then
warning "This table is already in use.";
abort script;
end if;
{Create the temporary table.}
l_error_code = Table_StartShrink(INVENT_PRODID, table
➥ Inventory_Data,"");
if l_error_code<>0 then
error "Unable to create the temporary table for the table
➥ shrink.";
else
{The temporary file was created successfully, so transfer the
➥ records.}
change first table Inventory_Data;
while err()<>EOF do
{Verify the record using Table_VerifyRecord().}
l_error_code = Table_VerifyRecord(INVENT_PRODID,
➥ table Inventory_Data, l_field_name);
if l_error_code < 600 or l_error_code > 610 then
{The integrity of the record has been verified, so attempt
➥ to transfer it.}
l_error_code = Table_CopyShrinkRecords( INVENT_PRODID,
➥ table Inventory_Data);
if l_error_code <> 0 then
{An error occurred while attempting to transfer the
➥ record to the temporary table.}
warning "Error number " + str(l_error_code) +
➥ " occurred while transferring shrink record.";
end if;
else
warning "Error number " + str(l_error_code) +
➥ " occurred for field " + l_field_name;
end if;
{Release the lock on the current record and read the
➥ next record.}
release table Inventory_Data;
change next table Inventory_Data;
end while;

FUNCTION LIBRARY REFERENCE 567

T A B L E _ E N D S H R I N K ( )

{Finish the table shrink.}

l_error_code = Table_EndShrink(INVENT_PRODID, table
➥ Inventory_Data);
if l_error_code <> 0 then
error "Unable to complete the table shrink.";
end if;
end if;

Related items Commands

Table_StartShrink(), Table_CopyShrinkRecords(), Table_VerifyRecord()

Additional information
Chapter 11, “Table Maintenance,” in the Dexterity Stand-alone Application Guide

568 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ F I L L G R O U P L I S T ()

Table_FillGroupList()
Description The Table_FillGroupList() function fills a list field (typically a list box or
drop-down list) with the names of the table groups from a series, providing
the table group contains at least two tables.

Syntax Table_FillGroupList(product_ID, series, dname_list, tname_list)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which table group names are being retrieved.

• series – An integer indicating the table group series from which table group
names will be read. The following table lists all table and table group series
and their corresponding integer values.

Series for tables and table groups

1 – Financial 7 – System 12 – Pathname
2 – Sales 8 – Company 13 – Design Document
3 – Purchasing 9 – Online Documentation 14 – Dexterity
4 – Inventory 10 – 3rd Party 15 – Dexterity System
5 – Payroll 11 – Payroll Tax 16 – Report Writer
6 – Project

• dname_list – A window list field that displays the returned display names of
the specified table groups.

• tname_list – A window list field that displays the technical names of the
specified table groups.

Return value The boolean value true.

Comments Table groups are a method of grouping related tables. You can create table
groups using the Table Group Definition window in Dexterity.

FUNCTION LIBRARY REFERENCE 569

T A B L E _ F I L L G R O U P L I S T ( )

Examples The following example returns the names of the table groups in the series
selected in the Table Series field (a list box displaying all available series).
The table group display names are displayed in the LB_Table_Groups list
box and the technical names are displayed in the LB_Tname_List list box.
The countitems() function is used to ascertain if any table groups are
displayed. If not, a warning message is displayed. The product ID for the
dictionary is 0.

local boolean result;

result = Table_FillGroupList(0, 'Table Series', 'LB_Table_Groups',

➥ 'LB_Tname_List');
if countitems('LB_Table_Groups') = 0 then
warning "This series contains no table groups.";
end if;

Related items Commands

countitems(), Table_FillList()

Additional information
Chapter 26, “Table Groups,” in Volume 1 of the Dexterity Programmer’s Guide.

570 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ F I L L L I S T ()

Table_FillList()
Description The Table_FillList() function fills a list field (typically a list box or drop-
down list) with the names of tables from the specified table group.

Syntax Table_FillList(product_ID, table_group_name, name_list)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the table names are being retrieved.

• table_group_name – A string specifying the technical name of the table

group.

• name_list – A list field that’s filled with the technical names of the tables in
the specified table group.

Return value An integer containing the number of tables in the specified table group.

Comments This function can display the tables that belong to a table group selected
from a list that was filled by the Resource_FillSeriesList() function.

Table groups are a method of grouping related tables. You can create table
groups using the Table Group Definition window in Dexterity.

Examples The following example displays the tables in the table group named
Inventory_Items in the list field named Tables_List. The product ID for the
dictionary is 0.

local integer count;

count = Table_FillList(0, "Inventory_Items", Tables_List);

Related items Commands

countitems(), Table_FillGroupList()

Additional information
Chapter 26, “Table Groups,” in Volume 1 of the Dexterity Programmer’s Guide.

FUNCTION LIBRARY REFERENCE 571

T A B L E _ F L U S H C A C H E ( )

Table_FlushCache()
Description The Table_FlushCache() function clears the table cache for all closed tables.

Syntax Table_FlushCache()

Parameters • None

Return value The boolean value true.

Comments The table cache contains information such as the pathname used to access a
table. The cache is created when the application starts. When a table is
closed, the cache information is kept to improve application performance if
the table is reopened. In some cases, you may want a table to be reopened in
another location, but then the information in the table cache will be
incorrect. The Table_FlushCache() function can be used to clear the table
cache before the table is reopened.

Examples The following example is the form pre script for the Login form. It uses the
Table_FlushCache() function to clear the table cache, because the new user
may be accessing tables in different locations than the previous user.

local boolean result;

result = Table_FlushCache();

572 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T A U T O S H R I N K M O D E ()

Table_GetAutoShrinkMode()
Description The Table_GetAutoShrinkMode() function indicates whether the current
database manager is capable of conducting a table shrink using
Table_AutoShrink() or rebuilding a table’s indexes using
Table_RebuildIndexes(). Currently, these functions can be used with c-tree
and Pervasive.SQL tables.

Syntax Table_GetAutoShrinkMode(table table_name)

Parameters • table table_name – The table that’s being shrunk.

Return value An integer indicating whether the automatic shrink can take place.

If a zero is returned, an automatic shrink can take place using

Table_AutoShrink().

If a non-zero value is returned, the table can’t be shrunk

automatically. The Table_StartShrink(), Table_VerifyRecord(),
Table_EndShrink() and Table_CopyShrinkRecords() functions must be
used to shrink the table instead. Non-zero values will be returned if a
database manager-specific error occurred, if the database manager used by
the named table doesn’t support automatic table shrinks, or if the defaults
file contains the CTShrink = FALSE setting. Consult the documentation for
your database manager for a list of error codes for that database manager.

Comments Shrinking is the process of removing unused space from a data table. The
removal of unused space in this manner is called a “shrink” because the file
will invariably be smaller after the unused space is removed.

You must close the table before using Table_GetAutoShrinkMode().

If the CTShrink setting is included in the defaults file and is set to FALSE,
the Table_GetAutoShrinkMode() function will always return a non-zero
value, regardless of the database manager used by the named table.

Examples See the example for Table_AutoShrink().

Related items Commands

Table_AutoShrink(), Table_StartShrink(), Table_VerifyRecord(),
Table_CopyShrinkRecords(), Table_EndShrink(), Table_RebuildIndexes()

Additional information
Chapter 11, “Table Maintenance,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 573

T A B L E _ G E T D I S P L A Y N A M E ( )

Table_GetDisplayName()
Description The Table_GetDisplayName() function returns the display name for a
specified table.

Syntax Table_GetDisplayName(product_ID, table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the table display name is being retrieved.

• table_name – A string containing the technical name of the table. This is the
name entered in the Table Name field of the Table Definition window.

Return value A string containing the display name of the table. This is the name entered
in the Display Name field of the Table Definition window.

Examples The following example returns the display name for the Inventory_Data
table to the local variable named l_table_name. The product ID is
represented by the constant INVENT_PRODID.

local string l_table_name;

l_table_name = Table_GetDisplayName(INVENT_PRODID, "Inventory_Data");

574 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T F I E L D L I S T ()

Table_GetFieldList()
Description The Table_GetFieldList() function retrieves the names of the fields in the
specified table.

Syntax Table_GetFieldList(product_ID, table_name, field_list)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the table field names are being retrieved.

• table_name – A string containing the technical name of the table. This is the
name entered in the Table Name field of the Table Definition window.

• field_list – A list field that will be filled with the names of the fields from the
specified table.

Return value The boolean value true.

Examples The following example returns the field name for the Inventory_Data table
to the Field List list box field. The product ID is represented by the constant
INVENT_PRODID.

local boolean result;

result = Table_GetFieldList(INVENT_PRODID, "Inventory_Data",

➥ 'Field List');

FUNCTION LIBRARY REFERENCE 575

T A B L E _ G E T G R O U P ( )

Table_GetGroup()
Description The Table_GetGroup() function returns the resource ID of the table group a
specified table is part of.

Syntax Table_GetGroup(product_ID, table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary in

which the table is located.

• table_name – A string containing the technical name of the table for which
the table group resource ID is being returned.

Return value An integer containing the resource ID of the table group. The value 0 is
returned if the table is not part of a table group.

Examples The following example uses the Table_GetGroup() function to retrieve the
resource ID of the table group the House_Descriptions table is part of. It
then uses the Resource_GetDisplayName() function to retrieve the name
of the table group. The product ID is represented by the constant
RESM_PRODID.

local integer resource_id;

local string table_group_name;

resource_id = Table_GetGroup(RESM_PRODID, "House_Descriptions");

table_group_name = Resource_GetDisplayName(RESM_PRODID, GROUPTYPE,
➥ resource_id);

576 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T K E Y F I E L D L I S T ()

Table_GetKeyFieldList()
Description The Table_GetKeyFieldList() function returns the list of fields that are part
of the specified key.

Syntax Table_GetKeyFieldList(product_ID, table_name, key_number, key_fields_list)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the key fields are being retrieved.

• table_name – A string specifying the technical name of the table.

• key_number – An integer specifying a key in the table.

• key_fields_list – A list field that’s filled with the names of the fields in the
specified key.

Return value The boolean value true.

Comments Use the Table_GetNumberOfKeys() function to retrieve the number of

keys for a table.

Examples The following example uses the Table_GetKeyFieldList() function to

retrieve the list of fields in the third key of the Buyer_Data table. The key
fields are returned to the Key Field List list box field. The product ID is
represented by the constant RESM_PRODID.

local boolean result;

result = Table_GetKeyFieldList(RESM_PRODID, "Buyer_Data", 3,

➥ 'Key Field List');

FUNCTION LIBRARY REFERENCE 577

T A B L E _ G E T K E Y I N F O ( )

Table_GetKeyInfo()
Description The Table_GetKeyInfo() function returns information about a key in the
specified table.

This function is obsolete. Use the Table_GetKeyOption() function instead.

Syntax Table_GetKeyInfo(table_ID, key_number, duplicates, modifiable, compress,

primary, index, unique, clustered)

Parameters • table_ID – An integer specifying the resource ID of the table for which key
information will be returned.

• key_number – An integer specifying a key in the table.

• duplicates – A returned boolean indicating whether duplicates are allowed.

• modifiable – A returned boolean indicating whether key fields are

modifiable.

• compress – A returned boolean indicating whether key values are

compressed.

• primary – A returned boolean indicating whether the key is the primary key
for the table. This applies only to SQL tables.

• index – A returned boolean indicating whether an index will be created for

the table. This applies only to SQL tables.

• unique – A returned boolean indicating whether the key values for each
record in the table must be unique. This applies only to SQL tables.

• clustered – A returned boolean indicating whether the key is a clustered key.

This applies only to SQL tables.

Return value The boolean value true.

Comments This function does not work properly when used for third-party
dictionaries that integrate with Microsoft Dynamics GP. It should be used
only in the main product dictionary.

578 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T K E Y I N F O ()

Examples The following example uses the Table_GetKeyInfo() function to retrieve

information about the first key in the Seller_Data table. The product ID is
represented by the constant RESM_PRODID.

local integer l_resource_ID;

local boolean l_result, l_duplicates, l_modifiable, l_compress,
➥ l_primary, l_index, l_unique, l_clustered;

{Retrieve the resource ID of the Seller_Data table.}

l_resource_ID = Resource_GetID(RESM_PRODID, 1, "Seller_Data");
l_result = Table_GetKeyInfo(l_resource_ID, 1, l_duplicates,
➥ l_modifiable, l_compress, l_primary, l_index, l_unique,
➥ l_clustered);

FUNCTION LIBRARY REFERENCE 579

T A B L E _ G E T K E Y O P T I O N ()

Table_GetKeyOption()
Description The Table_GetKeyOption() function returns information about the key
options for a key in the specified table.

Use this function instead of the Table_GetKeyInfo() function.

Syntax Table_GetKeyOption(product_ID, table_name, key_number, key_option)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the key option information is being retrieved.

• table_name – A string specifying the technical name of the table.

• key_number – An integer specifying a key in the table.

• key_option – An integer that specifies which key option is being examined.

Use one of the following constants:

Constant Key Option

KEY_OPTION_ALLOW_DUPLICATES Duplicates
KEY_OPTION_IS_MODIFIABLE Modifiable
KEY_OPTION_SQL_PRIMARY Primary
KEY_OPTION_SQL_CREATE_INDEX Create Index
KEY_OPTION_SQL_UNIQUE Unique
KEY_OPTION_SQL_CLUSTERED Clustered
KEY_OPTION_SQL_DISABLE_FIRST_PROCS Disable Firsts
KEY_OPTION_SQL_DISABLE_LAST_PROCS Disable Lasts
KEY_OPTION_SQL_DISABLE_NEXT_PROCS Disable Nexts
KEY_OPTION_SQL_DISABLE_SAVE_PROCS Disable Selects
KEY_OPTION_SQL_DISABLE_DELETE_PROCS Disable Deletes
KEY_OPTION_SQL_DISABLE_INSERT_PROCS Disable Inserts

Return value A boolean. The value true indicates the key option is marked, while false
indicates it is not.

580 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T K E Y O P T I O N ()

Examples The following example uses the Table_GetKeyOption() function to find

out whether the third key of the Buyer_Data table allows duplicates. The
product ID is represented by the constant RESM_PRODID.

local boolean result;

result = Table_GetKeyOption(RESM_PRODID, "Buyer_Data", 3,

➥ KEY_OPTION_ALLOW_DUPLICATES);

FUNCTION LIBRARY REFERENCE 581

T A B L E _ G E T N U M B E R O F K E Y S ( )

Table_GetNumberOfKeys()
Description The Table_GetNumberOfKeys() function returns the number of keys that
are defined for the specified table.

Syntax Table_GetNumberOfKeys(product_ID, table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary from

which the number of keys is being retrieved.

• table_name – A string specifying the technical name of the table.

Return value An integer containing the number of keys defined for the table.

Examples The following example uses the Table_GetNumberOfKeys() function to

retrieve the number of keys defined for the Buyer_Data table. The product
ID is represented by the constant RESM_PRODID.

local integer num_keys;

num_keys = Table_GetNumberOfKeys(RESM_PRODID, "Buyer_Data");

582 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T O S N A M E ()

Table_GetOSName()
Description The Table_GetOSName() function returns the operating system name and
path (in generic format) for the specified table. The operating system name
is also known as the physical name.

Syntax Table_GetOSName(table table_name)

Parameters • table table_name – The name of the table for which the operating system
name is being returned.

Return value A string containing the operating system name and path (in generic format)
of the table. If the path is not available, only the operating system name is
returned.

Comments This function can also return the operating system name being used for
temporary tables. This is especially useful for SQL tables when stored
procedures need to work with data in SQL temporary tables.

A script that uses the Table_GetOSName() function must have access to

the table buffer for the table whose name is being returned. Procedures and
functions have access to all tables in the application. Other scripts have
access only to the tables attached to the form the scripts are part of.

Examples The following example uses the Table_GetOSName() function to retrieve

the operating system name of the House_Data table.

local string OS_name;

OS_name = Table_GetOSName(table House_Data);

FUNCTION LIBRARY REFERENCE 583

T A B L E _ G E T R A N G E K E Y ()

Table_GetRangeKey()
Description The Table_GetRangeKey() function retrieves the key used for the range
applied to the specified table.

Syntax Table_GetRangeKey(table table_name)

Parameters • table table_name – The name of the table from which the range key is being
returned.

Return value An integer containing the number corresponding to the key used for the
range. If no range is set for the table, the constant TABLE_NORANGE is
returned.

Examples The following example retrieves the key used for a range on the
Buyer_Data table.

local integer range_key;

range_key = Table_GetRangeKey(table Buyer_Data);

Related items Commands

Table_IsRangeSet()

584 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T S E R I E S ()

Table_GetSeries()
Description The Table_GetSeries() function returns an integer corresponding to the
series the specified table is part of.

Syntax Table_GetSeries(product_ID, table_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary in

which the table is located.

• table_name – A string containing the technical name of the table for which
the series is being returned.

Return value An integer corresponding to the table series. The following table lists all the
series and their corresponding integer values.

Series for tables

1 – Financial 7 – System 12 – Pathname
2 – Sales 8 – Company 13 – Design Document
3 – Purchasing 9 – Online Documentation 14 – Dexterity
4 – Inventory 10 – 3rd Party 15 – Dexterity System
5 – Payroll 11 – Payroll Tax 16 – Report Writer
6 – Project

Examples The following example uses the Table_GetSeries() function to retrieve the
series of the House_Data table. The product ID is represented by the
constant RESM_PRODID.

local integer table_series;

table_series = Table_GetSeries(RESM_PRODID, "House_Data");

FUNCTION LIBRARY REFERENCE 585

T A B L E _ G E T SQL E R R O R T E X T ( )

Table_GetSQLErrorText() SQL

Description The Table_GetSQLErrorText() function retrieves a block of SQL error text

for the last SQL error that occurred. This function should be used only in
the SQLError procedure.

Syntax Table_GetSQLErrorText(table_ID, error_text, native_error_ID)

Parameters • table_ID – A long integer specifying the table for which SQL error text is
being returned. Use the internal_table_ID value passed into the SQLError
procedure.

• error_text – A returned string containing the SQL error text.

• native_error_ID – A returned long integer containing the native SQL error

number.

Return value An integer indicating whether SQL error text was retrieved. The constant
STATUS_SUCCESS indicates error text was retrieved. Any other value
indicates error text was not retrieved.

Comments When a SQL error occurs, several blocks of SQL error text may result. When
using the Table_GetSQLErrorText() function to retrieve the SQL error text,
be sure to retrieve all of the blocks of error text. Otherwise, other
applications won’t be able to properly retrieve SQL error text.

When using Table_GetSQLErrorText() to retrieve SQL error text, don’t use the
naterr() function. These two functions are not compatible and shouldn’t be used
together.

Examples The following example is a sample SQLError procedure. It uses the

Table_GetSQLErrorText() function to retrieve the SQL error information.
Notice that all blocks of SQL error text are retrieved.

in long internal_table_ID;
in integer dict_ID;
in integer table_series;
in integer table_ID;
in integer operation;
in string resource_name;
inout integer error_response;

586 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ G E T S Q L E R R O R T E X T ()

local integer status;

local string error_text;
local long native_error_number;

{Log the SQL error that has occurred.}

get last table SQL_Error_Log;
if err() = EOF then
{This is the first error to log.}
'Sequence Number' of table SQL_Error_Log = 0;
else
{Log the next SQL error.}
increment 'Sequence Number' of table SQL_Error_Log;
end if;
{Read the SQL error information.}
status = Table_GetSQLErrorText(internal_table_ID, error_text,
➥ native_error_number);

{Read each block of SQL error text until all text has been read.}
while status = STATUS_SUCCESS do
{Successfully read an entry in the error text, so log the error.}
'Log Date' of table SQL_Error_Log = sysdate();
'Log Time' of table SQL_Error_Log = systime();
'Resource' of table SQL_Error_Log = resource_name;
'Native Error' of table SQL_Error_Log = native_error_number;
'Error Text' of table SQL_Error_Log = error_text;
save table SQL_Error_Log;

{Read the next portion of the SQL error text.}

status = Table_GetSQLErrorText(internal_table_ID, error_text,
➥ native_error_number);
end while;

{Use the default behavior to display the SQL error to the user.}
error_response = 0;

FUNCTION LIBRARY REFERENCE 587

T A B L E _ I S R A N G E S E T ( )

Table_IsRangeSet()
Description The Table_IsRangeSet() function ascertains whether a range is currently
set for the specified table.

Syntax Table_IsRangeSet(table table_name)

Parameters • table table_name – The name of a table.

Return value A boolean. True indicates a range is set, while false indicates no range is set.

Comments This function cannot be used to verify whether the range where statement
was used to specify a range for a table.

Examples The following example ascertains whether a range is set for the Buyer_Data
table. If a range is set, the items in the range are removed.

if Table_IsRangeSet(table Buyer_Data) then

remove range table Buyer_Data;
end if;

Related items Commands

Table_GetRangeKey()

588 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ O P E N A S T E M P ()

Table_OpenAsTemp()
Description The Table_OpenAsTemp() function creates a “clone” of the table specified.
The clone will be a temporary table with exactly the same structure as the
table supplied. The clone table will contain no data.

Syntax Table_OpenAsTemp(table table_name)

Parameters • table table_name – The technical name of the table whose table structure will
be copied and used for the new clone table.

Return value A reference to the table.

Comments This function can be used when data in a table must be processed, but you
don’t want the original data affected.

Examples The following example creates a clone of the Inventory_Data table. The
range copy statement is used to fill the clone table with data. In this
example, the data in the clone table is displayed, and then the clone table is
closed.

local reference refTable;

local integer nStatus;

{Create a clone of the Inventory_Data table}

refTable = Table_OpenAsTemp(table Inventory_Data);

{Copy some items into the temp table}

range copy table Inventory_Data to table(refTable) by number 1;

{Perform processing on the records in the temporary table}

get first table(refTable);
while err() = OKAY do
warning 'Description' of table(refTable);
get next table(refTable);
end while;

{Close the table when processing is finished}

close table(refTable);

FUNCTION LIBRARY REFERENCE 589

T A B L E _ O P E N N E W B U F F E R ()

Table_OpenNewBuffer()
Description The Table_OpenNewBuffer() function creates a new table buffer and
reference to the table specified. This allows you to create multiple table
buffers for a table, within a single script.

Syntax Table_OpenNewBuffer(table table_name)

Parameters • table table_name – The technical name of the table for which a table buffer
will be created and a table reference returned.

Return value A reference to the table.

Examples The following example creates two table buffers for the Inventory_Data
table. The first table buffer is set to the first record in the table. The second
table buffer is set to the last record in the table. The content of both table
buffers is displayed in a message to the user.

local reference InventoryTable1;

local reference InventoryTable2;

{Create two references to the Inventory_Data table}

InventoryTable1 = Table_OpenNewBuffer(table Inventory_Data);
InventoryTable2 = Table_OpenNewBuffer(table Inventory_Data);

{For the first instance, get the first record in the table}
get first table(InventoryTable1);

{For the second instance, get the last record in the table}
get last table(InventoryTable2);

warning "First: " + 'Part Number' of table(InventoryTable1)

➥ + " Last: " + 'Part Number' of table(InventoryTable2);

590 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ R E B U I L D I N D E X E S ()

Table_RebuildIndexes()
Description The Table_RebuildIndexes() function rebuilds the indexes for a table that
stores data using the c-tree Plus database manager. The
Table_GetAutoShrinkMode() function must be used prior to this function
to ascertain whether the database manager used to create the table supports
this capability.

Syntax Table_RebuildIndexes(table table_name)

Parameters • table table_name – The table for which indexes are being rebuilt.

Return value An integer indicating the error code returned by the database manager. If
the return value is 0, no error occurred. Consult your c-tree Plus reference
manual for a list of error codes.

Comments Like Table_AutoShrink(), this function removes and then rebuilds the
indexes for an existing c-tree Plus data table. These indexes are stored in the
.IDX file with the same name to the left of the extension as the data table.
For example, the indexes for the INVENT.DAT data table are stored in the
INVENT.IDX index file.

However, unlike Table_AutoShrink(), which also shrinks the data table by

removing the unused portions of that table before rebuilding the indexes,
this function doesn’t change the data table in any way. It simply reads from
the data table, gathering the information it needs to successfully rebuild the
indexes.

The Table_RebuildIndexes() function is useful if you want to rebuild the

indexes for a large data table that isn’t deleted from very often, and
therefore rarely has any unused space in it. Also, this function is useful if
you have a large data table and don’t have the amount of free hard disk
space needed to perform a shrink, which copies the data table to a new
table, eliminating unused space in the process.

Since the functionality of this function is accomplished by Table_AutoShrink(),

and Table_AutoShrink() also removes unused portions of the data table, under
normal circumstances, we recommend that you use Table_AutoShrink() instead.

FUNCTION LIBRARY REFERENCE 591

T A B L E _ R E B U I L D I N D E X E S ()

Examples The following example uses Table_GetAutoShrinkMode() to find out

whether the database manager used with the table Inventory_Data
supports the rebuilding of the data table’s indexes. If it does,
Table_RebuildIndexes() is used to automatically rebuild the indexes.

local integer result;

close table Inventory_Data;

{Check whether the database manager supports rebuilding the table's
➥ indexes.}
result = Table_GetAutoShrinkMode(table Inventory_Data);
if result = 0 then
{Rebuild the table's indexes.}
result = Table_RebuildIndexes(table Inventory_Data);
close table Inventory_Data;
if result <> 0 then
error "An error occurred during the index rebuild.";
end if;
end if;

Related items Commands

Table_GetAutoShrinkMode(), Table_AutoShrink()

592 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ S E T C R E A T E M O D E ()

Table_SetCreateMode()
Description The Table_SetCreateMode() function allows you to choose whether tables
that don’t already exist will be created automatically when they are
accessed at runtime.

Syntax Table_SetCreateMode(option)

Parameters • option – A boolean that sets the table creation mode:

Value Description
true Automatically creates the table if it isn’t found.
false Doesn’t create the table if it isn’t found.

Return value The boolean value true.

Comments Dexterity’s default functionality is to automatically create the table if it isn’t

found. When a table operation is issued to run against a given table, a two-
step process is performed. Dexterity first checks the database to verify
whether the table exists. If the table doesn’t exist, Dexterity will create it.
Once the existence of the table is verified, Dexterity returns to the database
to execute the issued command. If you set the autocreate option to false, the
verification step will be skipped, which may improve application
performance. However, if the table isn’t found, an error message will be
displayed.

Typically, the Table_SetCreateMode() function is used when a table is

accessed the first time in the application. Automatic table creation is turned
off, error reporting is turned off, and a get first operation is performed on
the specific table. If an error occurred when a table was accessed, the table
didn’t exist in the location indicated. The application can then respond
appropriately by allowing the user to locate the table or tables that couldn’t
be accessed. Once the table has been located and successfully opened,
automatic table creation and error checking can be turned back on.

Regardless of which functionality is chosen, temporary tables will be

automatically created as needed.

When Table_SetCreateMode() is set to false, explicitly opening a SQL table with

the open table statement will never produce an error, even if the table does not
exist.

FUNCTION LIBRARY REFERENCE 593

T A B L E _ S E T C R E A T E M O D E ( )

Examples The following example uses Table_SetCreateMode() in the pre script on

the Main_Menu form. Automatic table creation and table error reporting
are turned off. The Users table is accessed to ascertain whether it exists in
the location specified by the Pathname procedure script. If the table exists,
automatic table creation and table error reporting are turned on and the
application continues. Otherwise, the user is prompted to locate the Users
table or specify a new location.

local boolean result, selected_path;

local string pathname;

{If a table doesn't previously exist in the location indicated by the

➥ Pathnames table, don't create the table.}
result = Table_SetCreateMode(false);
{Don’t display any table errors to the user.}
result = Table_DisableErrorChecks(true);

get first table Users;

if err() <> OKAY then
{The Users table isn't in the location specified.}
warning "The Users table can't be located. Please locate
➥ the Users table or specify a new location.";
selected_path = Path_SelectPathname(pathname);
if selected_path then
call SavePath, "Users", pathname;
else
warning "The application will be closed.";
close application;
end if;
close table Users;
else
close table Users;
end if;

{Turn on automatic table creation.}

result = Table_SetCreateMode(true);
{Turn table error reporting back on.}
result = Table_DisableErrorChecks(false);

Related items Commands

delete table, Table_DisableErrorChecks(), Table_SetDeleteOptions()

594 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ S E T DBT Y P E ()

Table_SetDBType()
Description The Table_SetDBType() function sets a default database type for an
application.

Syntax Table_SetDBType(type)

Parameters • type – An integer that sets the database type to one of the following:

Value Description
1 c-tree Plus
2 Pervasive.SQL
3 SQL

Return value The boolean value true.

Comments The default database type you set with this function is used if the database
type is set to Default in the Table Definition window. This command can be
used to force tables to be of a specific database type without indicating a
specific database type in the table’s definition.

Examples The following example sets the default database type to Pervasive.SQL.

local boolean result;

result = Table_SetDBType(2);

Related items Additional information

Chapter 9, “Tables,” in Volume 1 of the Dexterity Programmer’s Guide

FUNCTION LIBRARY REFERENCE 595

T A B L E _ S E T D E L E T E O P T I O N S ( )

Table_SetDeleteOptions() SQL

Description The Table_SetDeleteOptions() function allows you to choose whether a

delete all or drop will be executed when the delete table statement is used.

Syntax Table_SetDeleteOptions(option)

Parameters • option – A boolean that sets the delete table functionality:

Value Description
true Use the drop functionality, which removes the data and the table from
the database. This also removes the auto-generated stored procedures
for the table.
false Use the delete all functionality, which removes all of the data in the
table, leaving the empty table intact in the database.

Return value The boolean value true.

Comments Drop is the default setting for the Dexterity delete table statement, so if this
function isn’t used in your application, the delete table statement will
always use the drop functionality.

Your application’s performance may be slower when the drop functionality

is used, since tables that have been dropped must be re-created the next
time a user attempts to access them. However, using the drop functionality
ensures that any changes made to the table definition will be incorporated
in the table the next time it is created.

Be sure to take the Table_SetCreateMode() function into consideration when

deciding which delete functionality to use. If Table_SetCreateMode() is set to
false (not creating tables if they aren’t found), then a deleted table won’t be created
automatically and an error message will be displayed the next time a user tries to
access it. To have Dexterity automatically create a dropped table the next time a
user tries to access it, you must use Table_SetCreateMode() to set the autocreate
functionality to true, before the user attempts to access the table.

596 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ S E T D E L E T E O P T I O N S ()

Examples This example uses Table_SetDeleteOptions() to switch the functionality of

the delete table statement for one task, then switch it back. This script
copies the contents of the Current_Years_Purchases table to the
Old_Purchases table, and then deletes the rows in the
Current_Years_Purchases table, leaving the table structure intact.

local boolean result;

{Ensure that the delete table statement will use the delete all
➥ functionality.}
result = Table_SetDeleteOptions(false);
{Open the table. Include the exclusive option so that the delete table
➥ statement can be used.}
open table Current_Years_Purchases, exclusive;
{Retrieve each row in the Current_Years_Purchases table and copy it to
➥ the Old_Purchases table.}
get first table Current_Years_Purchases;
while err() = OKAY do
copy from table Current_Years_Purchases to table Old_Purchases;
save table Old_Purchases;
get next table Current_Years_Purchases;
end while;
{Delete all rows in the Current_Years_Purchases table.}
delete table Current_Years_Purchases;
{Change the delete table statement functionality back to drop.}
result = Table_SetDeleteOptions(true);

Related items Commands

delete table, Table_SetCreateMode()

FUNCTION LIBRARY REFERENCE 597

T A B L E _ S E T R E F R E S H F L A G S ( )

Table_SetRefreshFlags() SQL

Description The Table_SetRefreshFlags() function sets the refresh flags for each client
buffer associated with the named table. When this flag is set for a given
client buffer, the next time Dexterity attempts to access that client buffer, the
buffer will be refreshed before it is accessed. Using this function can ensure
that any client buffers associated with the named table will contain the most
current information.

Syntax Table_SetRefreshFlags(table table_name)

Parameters • table table_name – The name of the table for which the refresh flags are to be
set.

Return value An integer corresponding to one of the following constants:

Constant Description
STATUS_SUCCESS The refresh flag was set for each of the table’s client
buffers.
STATUS_ERROR An error occurred, causing the function to be unable to
set the refresh flag for each of the table’s client buffers.

Comments This function should be used after a stored procedure has run. It will ensure
that the data in the client buffers is updated to reflect any changes made to
the table as a result of the stored procedure.

Examples The following example runs a stored procedure named “Supply Statistics,”
which manipulates data in the Inventory table. If the stored procedure was
successful, Table_SetRefreshFlags() is used to set the refresh flag for the
client buffers associated with the Inventory table, so the next time these
buffers are accessed, they will contain updated data.

sproc returns long sproc_status;

local integer status;

call sproc "Supply Statistics", sproc_status;

if sproc_status = SQL_SPROC_ERROR then
warning "The stored procedure failed.";
else
status = Table_SetRefreshFlags(table Inventory);
end if;

598 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ S T A R T C O N V E R S I O N ()

Table_StartConversion()
Description The Table_StartConversion() function is used when a table definition has
been modified and existing data must be converted so it can be used with
the modified table definition. This function opens the old and new table
definitions for exclusive use so data can be converted.

The Table_Start_Conversion() function can be used only for c-tree and

Pervasive.SQL tables. It can’t be used for SQL tables.

Syntax Table_StartConversion(source_table, destination_table)

Parameters • source_table – A string containing the technical name of the table from which
records will be transferred.

• destination_table – A string containing the technical name of the table to

which records will be transferred.

Return value An integer indicating whether the source and destination tables were
opened successfully. The values returned correspond to those returned by
the err() function.

Comments This function opens the source and destination tables for exclusive use. The
destination table is actually a temporary table in the same directory as the
source table being converted. After both tables are open, records can then
be transferred from the source table to the destination table. Then
Table_EndConversion() is used to finish the table conversion.

Before you can use this function, you must have a table definition for the
source table and the destination table. Typically, you will use the Duplicate
Resources utility in Dexterity Utilities to duplicate the source table
definition. The duplicate table definition is saved and becomes the source
table.

Examples In the following example, a procedure script is being used to convert the
existing data in the RM_MSTR table so it can be used with an updated table
definition. The original table definition was duplicated using Dexterity
Utilities. The duplicate table definition was named RM_MSTR_OLD. (This
will become the source table.) The necessary changes were made to the
RM_MSTR table definition. (This will become the destination table.)

FUNCTION LIBRARY REFERENCE 599

T A B L E _ S T A R T C O N V E R S I O N ( )

local integer l_error; {Used to handle the error code.}

local boolean l_converted;{Used to set value for conversion.}
{Open the source and destination tables.}
l_error = Table_StartConversion("RM_MSTR_OLD", "RM_MSTR");

l_converted = false;

if l_error = OKAY then

{Successfully able to open both tables, so continue.}
l_converted = true;
get first table RM_MSTR_OLD;
while err() = OKAY and l_converted do
{Set old fields into the new table.}
'Customer ID' of table RM_MSTR = 'Customer ID' of table
➥ RM_MSTR_OLD;
'Customer Name' of table RM_MSTR = 'Customer Name' of table
➥ RM_MSTR_OLD;
Address of table RM_MSTR = Address of table RM_MSTR_OLD;
City of table RM_MSTR = City of table RM_MSTR_OLD;
State of table RM_MSTR = State of table RM_MSTR_OLD;
'Zip Code' of table RM_MSTR = 'Zip Code' of table RM_MSTR_OLD;
Phone of table RM_MSTR = Phone of table RM_MSTR_OLD;

{Set default values for new table fields.}

'Customer Type' of table RM_MSTR = 1;
{Save the table.}
save table RM_MSTR;
if err() <> OKAY then
l_converted = false;
end if;
{Read the next record from the source table.}
get next table RM_MSTR_OLD;
end while;

if err() <> EOF then

l_converted = false;
end if;

{Use Table_EndConversion() to finish the table conversion.}

l_error = Table_EndConversion(table RM_MSTR_OLD, table RM_MSTR,
➥ l_converted);
end if;

600 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ S T A R T C O N V E R S I O N ()

Related items Commands

Table_EndConversion()

Additional information
Chapter 60, “Updating an Application,” in the Dexterity Programmer’s Guide

FUNCTION LIBRARY REFERENCE 601

T A B L E _ S T A R T S H R I N K ()

Table_StartShrink()
Description The Table_StartShrink() function creates a temporary data table that can
be used to store data from an original table that’s being shrunk.

Syntax Table_StartShrink(product_ID, table table_name, pathname)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table being shrunk.

• table table_name – The name of the table being shrunk.

• pathname – A string indicating the full generic pathname where the

temporary file is to be created. Use an empty string ("") if you’re storing the
temporary table in the same folder as the original table.

Return value An integer describing the result of the temporary table initialization. The
result is 0 if the temporary table was created successfully. Any other value
indicates an error. The following list shows the errors and their
corresponding integer values:

0 – No error 20 – Transaction in progress

1 – Low on memory
2 – Database manager not initialized
3 – Database manager not supported
4 – Too many tables opened
5 – Record length too long
6 – Too many keys for database type
7 – Too many segments
8 – Table not registered
9 – Table not found
10 – Locked record
11 – Table name error
12 – Table not open
13 – Table not opened exclusive
14 – Invalid command sent to database
manager
15 – Key number doesn’t exist
16 – End of file
17 – Duplicate record
18 – Table is missing
19 – A set is already active
21 – Not a variable length table
22 – No table definition could be found
23 – Attempted to lock two records
24 – No lock on update
25 – Table doesn’t match definition
26 – The disk is full
27 – Unknown error
28 – A non-modifiable key changed
29 – Not a variable length field
30 – A record was changed with a passive
lock
31 – Deadlocked
32 – Path not found
33 – Buffer error
34 – Error in creating a P.SQL table
35 – Invalid key definition
36 – Maximum number of SQL connections
reached
37 – Error accessing SQL data
38 – Error converting SQL data
39 – Error generating SQL data

602 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ S T A R T S H R I N K ()

Comments Shrinking is the process of removing unused space from a data table. The
process is called a “shrink” because the table will invariably be smaller after
the unused space is removed. The Table_CopyShrinkRecords() function
copies the contents of the original table to the temporary table created by
Table_StartShrink(). This transfer allows the temporary table to store only
records from the original table; excess space in the original table isn’t
transferred to the temporary table. After the copy is complete, the
Table_EndShrink() function finishes the table shrink.

If no location is specified in the pathname parameter, the shrink table will be

created in the same location as the original table. If there’s limited disk
space at the location of the original table, use the pathname parameter to
select a different location for the temporary table that has adequate space to
hold the temporary table.

This function will create a temporary table named SRHNKXXX.DAT, with

XXX representing a value from 001 to 999, ensuring a unique temporary
table name.

Examples Refer to the example following the description of Table_EndShrink().

Related items Commands

Table_CopyShrinkRecords(), Table_EndShrink(), Table_VerifyRecord()

Additional information
Chapter 11, “Table Maintenance,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 603

T A B L E _ T R U N C A T E ( )

Table_Truncate() SQL

Description The Table_Truncate() function removes all records from a SQL table,
leaving the table structure intact in the database.

Syntax Table_Truncate(table table_name)

Parameters • table table_name – The name of the table from which the records are to be
removed.

Return value An integer corresponding to one of the following values:

Value Description
0 The records were removed successfully.
1 There wasn’t enough memory to complete the operation.
3 Table not supported.
27 An unknown error occurred.
37 A SQL truncate command was successfully generated by Dexterity, but
it was unable to be completed at the data source.
41 The operation couldn’t be completed because a user wasn’t logged into
the data source.

Comments This function performs the same function as the delete table statement that
uses the delete all functionality, but performs this task differently.
Table_Truncate() removes records faster than the delete table statement.
However, unlike the delete table statement, it ignores any locks another
user may have on records in the table.

If a user executes this function while another user has records from the
named table in a client buffer, the second user will continue to see those
buffered values even after the table’s records have been deleted. Should the
second user save records to the table before this function is successfully
completed, those records will be deleted when the command is completed.
If the second user saves records to the table after the function is successfully
completed, those records will be added to the table.

If the named table isn’t open when Table_Truncate() is executed, it will be

opened. If the named table doesn’t exist on the current data source, this
function will create it, unless Table_SetCreateMode() was used to prevent
tables from being automatically created. If the table can’t be created, the
error value 27 is returned from Table_Truncate().

604 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _ T R U N C A T E ()

Table_Truncate() should be used with caution since it doesn’t respect locks. It

generates a SQL truncate command that is not logged in the database’s transaction
log. This may cause records to reappear if the database is restored from a backup.
We strongly suggest that you use the delete table statement instead of this
function unless you are thoroughly familiar with the implications of issuing a SQL
truncate command.

Examples The following example removes all records from the Inventory table.

local integer status;

status = Table_Truncate(table Inventory);

if status = 0 then
warning "All data in the table was successfully removed.";
elseif status = 1 then
warning "There wasn't enough memory to remove all the data in the
➥ table.";
elseif status = 27 then
warning "An unknown error occurred.";
elseif status = 37 then
warning "An unknown error occurred at the data source, causing
➥ the operation to fail.";
elseif status = 41 then
warning "A user must be logged into a data source before data can
➥ be removed from a table.";
end if;

FUNCTION LIBRARY REFERENCE 605

T A B L E _ V E R I F Y R E C O R D ()

Table_VerifyRecord()
Description The Table_VerifyRecord() function verifies the contents of the fields in a
record for the specified table.

Syntax Table_VerifyRecord(product_ID, table table_name, field_name)

Parameters • product_ID – An integer specifying the product ID of the dictionary

containing the table for which records are being verified.

• table table_name – The table containing records being verified.

• field_name – A returned string indicating the name of the first field for
which an error was encountered.

Return value An integer specifying the error code for the verify operation. If the value
returned is zero, no error occurred. Any other number indicates that an
error was encountered. The following table lists each error code and its
corresponding description.

Value Description
600 Negative value for a list field
601 Invalid value for check box field
602 Invalid value for boolean field
603 Invalid digits for currency field
604 Invalid length string for combo box field
605 Invalid length for string field
606 Invalid date field
607 Invalid time field
608 Negative length for a text field
609 Negative length for a picture field
610 Invalid digits for a variable currency field

Comments This function is used to rebuild tables. It will check for the following
conditions:

• Negative values for list fields, such as list boxes, drop-down lists, radio
groups and visual switches. Any other checking for values within a
specific range must be completed in a script.

• Values other than 0 or 1 for boolean fields.

606 F U N C T I O N L I B R A R Y R E F E R E N C E
 T A B L E _V E R I F Y R E C O R D ()

• Invalid digits for currency fields (characters other than 0-9).

• Invalid length bytes for strings and combo box strings. The length byte
for these fields must be less than the combined length of the storage
size and length byte.

• Invalid dates and times.

• Invalid lengths for text fields and pictures. (Neither can be a negative
value.)

Examples The following example verifies the contents of a table named

Inventory_Data. If an error is encountered, a warning message displays the
error code and the field where the error occurred. Rather than displaying a
warning message, you may want to store encountered errors in an error log
file or a text file. You may also want to display a progress control dialog box
that displays records as they’re verified. Refer to the
Window_ForceRedraw() function for an example of a progress control
dialog. The product ID is represented by the constant INVENT_PRODID.

local integer l_errcode;

local string l_field_name;

{Read the first record in the table to be verified.}

get first table Inventory_Data;
while err() <> EOF do
errcode = Table_VerifyRecord(INVENT_PRODID, table
➥ Inventory_Data, l_field_name);
if l_errcode <> 0 then
warning "Error # " + str(l_errcode) + " occurred for field "
➥ + l_field_name;
end if;
get next table Inventory_Data;
end while;

Related items Commands

Window_ForceRedraw()

Additional information
Chapter 11, “Table Maintenance,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 607

608 F U N C T I O N L I B R A R Y R E F E R E N C E
Text file function library
Use the functions in this library when working with text files in your
application. This library contains the following functions:

• TextFile_Close()
• TextFile_Open()
• TextFile_ReadLine()
• TextFile_ReadText()
• TextFile_WriteDOS()
• TextFile_WriteLine()
• TextFile_WriteText()

FUNCTION LIBRARY REFERENCE 609

T E X T F I L E _ C L O S E ( )

TextFile_Close()
Description The TextFile_Close() function closes a text file opened by the
TextFile_Open() function.

Syntax TextFile_Close(file_ID)

Parameters • file_ID – An integer returned by TextFile_Open() that’s used to uniquely

identify this file.

Return value The boolean value true.

Examples Refer to the examples for TextFile_ReadLine(), TextFile_WriteDOS() or

TextFile_WriteLine().

Related items Commands

TextFile_Open()

610 F U N C T I O N L I B R A R Y R E F E R E N C E
 T E X T F I L E _ O P E N ()

TextFile_Open()
Description The TextFile_Open() function opens a specified text file.

Syntax TextFile_Open(pathname, mode, access)

Parameters • pathname – A string containing the complete generic pathname to the text
file, including the name of the file. If the file specified by pathname doesn’t
exist, it will be created.

• mode – An integer corresponding to one of the following file open modes:

Value Description
0 The file will be opened at the beginning of the text file, allowing you to
overwrite or read existing text.
1 The file will be opened at the end of the text file, allowing you to
append new text to the file.

• access – An integer that sets the following access rights to the file:

Value Description
0 Allows write exclusive access.
1 Allows read-only shared access.
2 Allows write shared access.

Return value An integer returned from the operating system that’s used to uniquely
identify this file. This value is used with the TextFile_Close(),
TextFile_ReadLine(), TextFile_ReadText(), TextFile_WriteDOS(),
TextFile_WriteLine() and TextFile_WriteText() functions.

Comments When you open a text file at the beginning (where the mode parameter is set
to 0), with write access (where the access parameter is set to either 0 or 2)
any text currently in the file will be deleted in preparation for writing new
data. To avoid deleting existing data, open a text file at the end of the file
(using a mode of 1) when using write access.

After you open a text file, the insertion point is determined by the mode
parameter. The following illustration shows a text file and the insertion
points that can be determined by mode:

FUNCTION LIBRARY REFERENCE 611

T E X T F I L E _ O P E N ()

Use a 0 with the mode

parameter to access a
text file at the beginning Item 11-223 (Cement Trowel) is selling
and read the contents of slowly, so reorder quantities have been
the file. lowered.

Additional heavy-labor items have also

been moving slower than expected
due to the building situation in the
state.

There has been a boom in the home-

Use a 1 with the mode improvement supplies.
parameter to add text to
the end of a file.

A carriage return
indicates the end of a
line.

If you open a text file at its beginning, use TextFile_ReadLine() to read a

line in the file, and return it to a text field in your application. If you open a
text file at the end of the file, use TextFile_WriteLine() to write text from
your application to the file.

Examples This example opens a text file using the getfile() function. It opens the
selected file at the end of the file, with exclusive access. It then displays the
name of the text file once it’s been parsed using the
Path_ParseFileFromPath() function:

local string l_Pathname;

local integer l_File_ID;

if getfile("Select a text file:", TEXTFILE, l_Pathname) then

l_File_ID = TextFile_Open(l_Pathname, 1, 0);
'(L) TextFileName' = Path_ParseFileFromPath(l_Pathname);
end if;

Related items Commands

TextFile_Close(), TextFile_ReadLine(), TextFile_ReadText(),
TextFile_WriteDOS(), TextFile_WriteLine(), TextFile_WriteText()

612 F U N C T I O N L I B R A R Y R E F E R E N C E
 T E X T F I L E _ R E A D L I N E ()

TextFile_ReadLine()
Description The TextFile_ReadLine() function reads a line from a file opened by the
TextFile_Open() function.

Syntax TextFile_ReadLine(file_ID, return_string)

Parameters • file_ID – An integer returned by TextFile_Open() that’s used to uniquely

identify this file.

• return_string – A string containing text (up to 255 characters) returned from

the text file.

Return value A boolean indicating a file error status; true if a file error occurred, false if
no file error occurred. If an error occurs, typically it will be an end-of-file
error (EOF).

Comments When the file is opened using TextFile_Open(), you must specify that the
file be opened at the beginning. The TextFile_ReadLine() function begins
reading from the current position until 255 characters have been read or the
end of the line is encountered. (The end of a line is indicated by a carriage
return or carriage return/line feed combination of characters.) The
characters read are returned to the return_string parameter. The carriage
return or carriage return/line feed characters are not returned. Then,
depending on whether a complete line was read, the current position is set
to immediately after the end of the line or after the last character read.

To return the entire contents of a text file, you can use a loop to retrieve each
line in the file until the end of the file is encountered.

The TextFile_ReadLine()
function reads characters
until 255 characters have
been read or it encounters
the end of the line.
Item 11-223 (Cement Trowel) is selling
slowly, so reorder quantities have been
lowered.
Additional heavy-labor items have also
been moving slower than expected due to
the building situation in the state.

There has been a boom in the home-

improvement suppplies.

[End of file]

FUNCTION LIBRARY REFERENCE 613

T E X T F I L E _ R E A D L I N E ( )

Examples This example writes the contents of a text file to a text field. The getfile()
function returns a text file location, then TextFile_Open() opens the file at
that location. The TextFile_ReadLine() function is in a loop that reads each
line in the file and appends it to the text field until the end of the file is
reached:

local string l_Pathname, l_Returned_String;

local integer l_File_ID;
local boolean l_File_Error, l_Result;

if getfile("Select a text file:", TEXTFILE, l_Pathname) then

l_File_ID = TextFile_Open(l_Pathname, 0, 1);
'(L) TextFileName' = Path_ParseFileFromPath(l_Pathname);
l_File_Error = false;
while l_File_Error = false do
l_File_Error = TextFile_ReadLine(l_File_ID,
➥ l_Returned_String);
'(L) TextFileText' = '(L) TextFileText' + l_Returned_String;
end while;
l_Result = TextFile_Close(l_File_ID);
end if;

Related items Commands

TextFile_Open(), TextFile_Close()

614 F U N C T I O N L I B R A R Y R E F E R E N C E
 T E X T F I L E _ R E A D T E X T ()

TextFile_ReadText()
Description The TextFile_ReadText() function reads a specified number of characters
from a text file opened by theTextFile_Open() function.

Syntax TextFile_ReadText(file_ID, length, return_string)

Parameters • file_ID – An integer returned by TextFile_Open() that’s used to uniquely

identify this file.

• length – An integer indicating the number of characters to read in the text

file. Up to 32767 characters can be read at a time.

• return_string – A string containing the text returned from the text file.

Return value A boolean indicating a file error status; true if a file error occurred, false if
no file error occurred. If an error occurs, typically it will be an end-of-file
(EOF) error.

Comments Once this function reads the number of characters indicated by the length
parameter, it sets the current position to immediately after the last character
read. This function will include the end of line marker (a carriage return or
carriage return/line feed combination) just as if they were ordinary
characters.

Examples This example reads the number of characters specified and displays the text
in a window field:

local string l_pathname;

local integer l_file_ID;
local boolean l_file_error, l_result;

if getfile("Select a text file:", TEXTFILE, l_pathname) then

l_file_ID = TextFile_Open(l_pathname, 0, 1);
'(L) TextFileName' = Path_ParseFileFromPath(l_pathname);
l_result = TextFile_ReadText(l_file_ID,'(L) length',
➥ '(L) return text');
end if;

Related items Commands

TextFile_Open(), TextFile_Close()

FUNCTION LIBRARY REFERENCE 615

T E X T F I L E _ W R I T E D O S( )

TextFile_WriteDOS()
Description The TextFile_WriteDOS() function writes a line to a text file opened by the
TextFile_Open() function. It’s the same as the TextFile_WriteLine()
function, except that it enforces a DOS text format.

Syntax TextFile_WriteDOS(file_ID, text)

Parameters • file_ID – An integer returned by TextFile_Open() that’s used to uniquely

identify this file.

• text – A string containing the text that’s written to the text file.

Return value A long integer containing the number of characters written to the text file.

Comments DOS text formatting requires that a carriage return and line feed follow
each line written to the text file. The TextFile_WriteLine() function
automatically follows this format when used with Windows.

Examples This example writes the contents of a window field to a text file selected
with the getfile() function and opened with the TextFile_Open() function.
It then closes the text file using the TextFile_Close() function:

local long l_characters_written;

local boolean l_result;
local string l_pathname;
local integer l_file_ID;

if getfile("Select a text file", TEXTFILE, l_pathname) then

l_file_ID = TextFile_Open(l_pathname, 1, 2);
l_characters_written = TextFile_WriteDOS(l_file_ID,
➥ '(L) TextFileString');
l_result = TextFile_Close(l_file_ID);
end if;

Related items Commands

TextFile_Open(), TextFile_Close(), TextFile_WriteLine()

616 F U N C T I O N L I B R A R Y R E F E R E N C E
 T E X T F I L E _ W R I T E L I N E ()

TextFile_WriteLine()
Description The TextFile_WriteLine() function writes a line to a text file opened by the
TextFile_Open() function.

Syntax TextFile_WriteLine(file_ID, text)

Parameters • file_ID – An integer returned by TextFile_Open() that’s used to uniquely

identify this file.

• text – A string or text value containing the text that’s written to the text file.

Return value A long integer indicating the number of characters written to the file.

Comments A carriage return and a line feed will follow each line (DOS format). To
enforce a DOS format regardless of the platform you’re using, use the
TextFile_WriteDOS() function. To write characters to a text file without a
carriage return and a line feed, use the TextFile_WriteText() function.

Examples This example writes the contents of a window field to a text file opened
with the getfile() function. It then closes the text file using the
TextFile_Close() function.

local long l_characters_written;

local boolean l_result;
local string l_pathname;
local integer l_file_ID;

if getfile("Select a text file", TEXTFILE, l_pathname) then

l_file_ID = TextFile_Open(l_pathname, 1, 2);
l_characters_written = TextFile_WriteLine(l_file_ID,
➥ '(L) TextFileString');
l_result = TextFile_Close(l_file_ID);
end if;

Related items Commands

TextFile_Open(), TextFile_Close()

FUNCTION LIBRARY REFERENCE 617

T E X T F I L E _ W R I T E T E X T ( )

TextFile_WriteText()
Description The TextFile_WriteText() function writes a line to a text file opened by the
TextFile_Open() function without including a line feed or carriage return.
In contrast, the TextFile_WriteDOS() function includes a line feed and
carriage return.

Syntax TextFile_WriteText(file_ID, text)

Parameters • file_ID – An integer returned by TextFile_Open() that’s used to uniquely

identify this file.

• text – A string or text value containing the text that’s written to the text file.

Return value A long integer indicating the number of characters written to the text file.

Comments You can write a line to a text file, enforcing a line feed and carriage return at
the end of each line, using TextFile_WriteDOS().

You can also write a line using the TextFile_WriteLine() function.

However, this function writes a line to a text file differently, depending
upon the platform you’re using. A carriage return and a line feed will
follow each line (a DOS format).

Examples This example writes the contents of a window field to a text file opened
with the getfile() function. It then closes the text file using the
TextFile_Close() function.
local long l_characters_written;
local boolean l_result;
local string l_pathname;
local integer l_file_ID;

if getfile("Select a text file", TEXTFILE, l_pathname) then

l_file_ID = TextFile_Open(l_pathname, 1, 2);
l_characters_written = TextFile_WriteText(l_file_ID,
➥ '(L) TextFileString');
l_result = TextFile_Close(l_file_ID);
end if;

Related items Commands

TextFile_Open(), TextFile_Close(), TextFile_WriteDOS(), TextFile_WriteLine()

618 F U N C T I O N L I B R A R Y R E F E R E N C E
Timer function library
Use the functions in this library to access timing capabilities within
Dexterity. This library contains the following function:

• Timer_Sleep()

FUNCTION LIBRARY REFERENCE 619

T I M E R _ S L E E P ()

Timer_Sleep()
Description The Timer_Sleep() function causes the application to wait for the specified
period of time.

Syntax Timer_Sleep(duration)

Parameters • duration – A long integer specifying the number of milliseconds to have the
application wait. This is the minimum amount of time the application will
wait. Depending on the other processes running on the system, the actual
waiting time may be somewhat longer.

Return value A long integer containing the number of milliseconds the application was
told to wait.

Comments The Timer_Sleep() function is used to add delays to an application, such as

when deadlock exceptions are being handled for transactions.

Examples The following example produces a delay of five seconds (5000

milliseconds).
local long delay;

delay = Timer_Sleep(5000);

620 F U N C T I O N L I B R A R Y R E F E R E N C E
Tools function library
Use the functions in this library when working with Dexterity system tools
in your application. This library contains the following functions:

• Tools_CloseDUOSTable()
• Tools_DisableLoadBalancing()
• Tools_EnableCommandMenus()
• Tools_EnableCustomizationMaintenance()
• Tools_EnableCustomizationStatus()
• Tools_EnableImport()
• Tools_EnableLoadBalancing()
• Tools_EnableModifier()
• Tools_EnableReportWriter()
• Tools_GetTranLevel()
• Tools_IsAppProcessServer()
• Tools_IsScriptRemote()
• Tools_OpenDUOSTable()

FUNCTION LIBRARY REFERENCE 621

T O O L S _ C L O S E D U O S T A B L E ()

Tools_CloseDUOSTable()
Description The Tools_CloseDUOSTable() function closes the DUOS table available to
the Visual Basic for Applications (VBA) environment.

Syntax Tools_CloseDUOSTable()

Parameters • None

Return value The boolean value true.

Comments You need to close the DUOS table if you want to reopen it in another
location.

Examples The following example closes the DUOS table.

local boolean result;

result = Tools_CloseDUOSTable();

622 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ D I S A B L E L O A D B A L A N C I N G ()

Tools_DisableLoadBalancing()
Description The Tools_DisableLoadBalancing() function causes load balancing to be
disabled for a process server or client workstation.

Syntax Tools_DisableLoadBalancing()

Parameters • None

Return value The boolean value true.

Comments When load balancing is disabled on a process server, the process server
unregisters itself with the Distributed Process Manager (DPM) so no
processes will be sent to it. When load balancing is disabled on a client, the
DPM is no longer consulted when processes are sent to process servers.

Examples The following example uses the Tools_DisableLoadBalancing() function to

disable load balancing.

local boolean result;

result = Tools_DisableLoadBalancing();

FUNCTION LIBRARY REFERENCE 623

T O O L S _ E N A B L E C O M M A N D M E N U S ( )

Tools_EnableCommandMenus()
Description The Tools_EnableCommandMenus() function causes command-based
menus to be used for an application, rather than resource-defined menus.

Syntax Tools_EnableCommandMenus()

Parameters • None

Return value None

Comments The Tools_EnableCommandMenus() function should be run in the Startup

or Startup_Main procedure for the application.

Examples The following example is part of the Startup script for the Real Estate Sales
Manager sample application. It enables command menus for the
application.

Tools_EnableCommandMenus();

624 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ E N A B L E C U S T O M I Z A T I O N M A I N T E N A N C E ()

Tools_EnableCustomizationMaintenance()
Description The Tools_EnableCustomizationMaintenance() function enables the
Customization Maintenance menu item.

Syntax Tools_EnableCustomizationMaintenance(mode)

Parameters • mode – A boolean that enables or disables the menu item:

Value Description
true Enables the Customization Maintenance menu item.
false Disables the Customization Maintenance menu item.

Return value The boolean value true.

Examples This example enables the Customization Maintenance menu item from the
form pre script for the main menu:

local boolean result;

result = Tools_EnableCustomizationMaintenance(true);

FUNCTION LIBRARY REFERENCE 625

T O O L S _ E N A B L E C U S T O M I Z A T I O N S T A T U S ( )

Tools_EnableCustomizationStatus()
Description The Tools_EnableCustomizationStatus() function enables the
Customization Status menu item.

Syntax Tools_EnableCustomizationStatus(mode)

Parameters • mode – A boolean that enables or disables the menu item:

Value Description
true Enables the Customization Status menu item.
false Disables the Customization Status menu item.

Return value The boolean value true.

Examples This example enables the Customization Status menu item from the form
pre script for the main menu:

local boolean result;

result = Tools_EnableCustomizationStatus(true);

626 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ E N A B L E I M P O R T ()

Tools_EnableImport()
Description The Tools_EnableImport() function enables the Table Import menu item.

Syntax Tools_EnableImport(mode)

Parameters • mode – A boolean that enables or disables the menu item:

Value Description
true Enables the Table Import menu item.
false Disables the Table Import menu item.

Return value The boolean value true.

Comments Refer to your Dexterity license agreement before you enable this item.

Examples This example enables the Table Import menu item from the form pre script
for the main menu:

local boolean result;

result = Tools_EnableImport(true);

Related items Additional information

Chapter 14, “Using the Import Utility,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 627

T O O L S _ E N A B L E L O A D B A L A N C I N G ( )

Tools_EnableLoadBalancing()
Description The Tools_EnableLoadBalancing() function causes load balancing to be
enabled for a process server or client workstation.

Syntax Tools_EnableLoadBalancing()

Parameters • None

Return value The boolean value true.

Comments When load balancing is enabled on a process server, the process server
registers itself with the Distributed Process Manager (DPM) so processes
will be sent to it. This is typically done in the dpsInit procedure. When load
balancing is enabled on a client, the DPM is consulted when processes are
sent to process servers to ascertain which is the best process server to
receive the process.

You must use Tools_EnableLoadBalancing() on all client and process server

workstations for load balancing to work properly.

Examples The following example uses the Tools_EnableLoadBalancing() function to

enable load balancing.

local boolean result;

result = Tools_EnableLoadBalancing();

628 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ E N A B L E M O D I F I E R ()

Tools_EnableModifier()
Description The Tools_EnableModifier() function enables the Modifier menu items.
The Modifier is available only when your application is opened with the
runtime engine.

Syntax Tools_EnableModifier(mode)

Parameters • mode – A boolean that enables or disables the Modifier menu items:

Value Description
true Enables the Modifier menu items.
false Disables the Modifier menu items.

Return value The boolean value true.

Comments Refer to your Dexterity license agreement before you enable this item.

Examples This example enables the Modifier from the form pre script for the main
menu:

local boolean result;

result = Tools_EnableModifier(true);

Related items Additional information

Chapter 15, “Using the Modifier,” in the Dexterity Stand-alone Application Guide

FUNCTION LIBRARY REFERENCE 629

T O O L S _ E N A B L E R E P O R T W R I T E R ( )

Tools_EnableReportWriter()
Description The Tools_EnableReportWriter() function enables the Report Writer menu
items. The Report Writer is available only when your application is opened
with the runtime engine.

Syntax Tools_EnableReportWriter(mode)

Parameters • mode – A boolean that enables or disables the Report Writer menu items:

Value Description
true Enables the Report Writer menu items.
false Disables the Report Writer menu items.

Return value The boolean value true.

Comments Add this function to the form pre script for the main menu form. This will
ensure that the Report Writer is available when your application is
launched. Refer to your Dexterity license agreement before you enable this
item.

Examples This example enables the Report Writer from the form pre script for the
main menu:

local boolean result;

result = Tools_EnableReportWriter(true);

Related items Additional information

Chapter 16, “Using the Report Writer,” in the Dexterity Stand-alone Application Guide

630 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ G E T T R A N L E V E L ()

Tools_GetTranLevel()
Description The Tools_GetTranLevel() function indicates whether a database
transaction is currently active.

Syntax Tools_GetTranLevel()

Parameters • None

Return value An integer. The value 0 indicates no transaction is currently active. Any
other value indicates a transaction is active.

Examples Refer to the example for transaction begin.

FUNCTION LIBRARY REFERENCE 631

T O O L S _ I S A P P P R O C E S S S E R V E R ()

Tools_IsAppProcessServer()
Description The Tools_IsAppProcessServer() function returns whether the application
is being run by the Process Server application.

Syntax Tools_IsAppProcessServer()

Parameters • None

Return value A boolean value indicating whether the application is being run by the
Process Server application. True indicates the application is being run by
the Process Server; false indicates the application is being run by Dexterity
or the runtime engine.

Examples The following example uses the Tools_IsAppProcessServer() function in

the Main Menu form pre script. If the application is not being run by the
Process Server, the Login window is opened.

local boolean result;

result = Tools_IsAppProcessServer();

if result = false then

open form Login;
end if;

632 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ I S S C R I P T R E M O T E ()

Tools_IsScriptRemote()
Description The Tools_IsScriptRemote() function returns whether the current script is
being processed remotely on a Process Server.

Syntax Tools_IsScriptRemote()

Parameters • None

Return value A boolean value indicating whether the current script is being processed
remotely by a Process Server. True indicates the script is being
processed remotely on a Process Server; false indicates the script is
being processed locally.

Comments When procedures are run on a Process Server, they should not display the
Report Destination window. This function is used in procedures that can
generate reports to ascertain whether the procedure is being processed on a
Process Server. If it is, the parameters of the run report and run report with
name statements should be set to not display the Report Destination
window.

Examples The following example uses the Tools_IsScriptRemote() function to

ascertain whether the procedure is being processed on a Process Server. If it
is, the report is printed to the printer.

if Tools_IsScriptRemote() = true then

run report 'Customer List' destination false, true;
else
run report 'Customer List';
end if;

FUNCTION LIBRARY REFERENCE 633

T O O L S _ O P E N D U O S T A B L E ( )

Tools_OpenDUOSTable()
Description The Tools_OpenDUOSTable() function opens the DUOS table available to
the Visual Basic for Applications (VBA) environment.

Syntax Tools_OpenDUOSTable()

Parameters • None

Return value A boolean indicating whether the DUOS table can be opened. True
indicates the DUOS table can be opened. False indicates it can’t.

If you use the Tools_OpenDUOSTable() function before the VBA environment

has been initialized, it may return incorrect status information. VBA
initialization occurs immediately after the Main Menu form pre script has finished.
You should use the Tools_OpenDUOSTable() function only after that point.

Comments The application must contain the definition for the DUOS table. The DUOS
table must be named SY_User_Object_Store. Refer to Chapter 15, “Using
the Modifier,” in the Stand-alone Application Guide for more information
about implementing the DUOS table. Refer to the VBA Developer’s Guide
for information about using the DUOS.

Examples The following example opens the DUOS table.

local boolean result;

result = Tools_OpenDUOSTable();
if result = false then
error "Could not open the DUOS table for the VBA environment.";
end if;

634 F U N C T I O N L I B R A R Y R E F E R E N C E
 T O O L S _ U S E S H E L L

Tools_UseShell
Description The Tools_UseShell() function specifies which type of application shell
will be used for the Dexterity-based application.

Syntax Tools_UseShell(type, options)

Parameters • type – An integer that specifies which type of application shell to use. The
value corresponds to one of the following constants:

Constant Description
SHELL_TYPE_WIN32_MDI
SHELL_TYPE_MANAGED_SDI

• options – A long integer that specifies options for the selected shell. The
value corresponds to one of the following constants:

Constant Description
SHELL_OPTION_DEFAULT Use the default options for the application shell.
SHELL_OPTION_CREATE_HIDDEN Prevents the application shell from being
displayed.

Return value Nothing.

Comments This function must be run from the Startup_Main procedure in the
application dictionary.

FUNCTION LIBRARY REFERENCE 635

636 F U N C T I O N L I B R A R Y R E F E R E N C E
 Tree view function library
Refer to Chapter 12,
“Tree View,” in Volume
2 of the Dexterity
Programmer’s Guide
for information about
using tree view fields.
Use the functions in this library when adding tree view fields to your
application. This library contains the following functions:
• TreeView_AddNode()
• TreeView_CollapseNode()
• TreeView_CountChildren()
• TreeView_CountNodes()
• TreeView_ExpandNode()
• TreeView_GetClickNode()
• TreeView_GetCollapsingNode()
• TreeView_GetExpandingNode()
• TreeView_GetFirstChild()
• TreeView_GetNextNode()
• TreeView_GetNodeData()
• TreeView_GetNodeImage()
• TreeView_GetNodeLabel()
• TreeView_GetNodeStateImage()
• TreeView_GetParent()
• TreeView_GetPreviousNode()
• TreeView_GetRootNode()
• TreeView_GetSelectedNode()
• TreeView_IsParentNode()
• TreeView_MakeNodeVisible()
• TreeView_RemoveChildren()
• TreeView_RemoveNode()
• TreeView_SetNodeData()
• TreeView_SetNodeImage()
• TreeView_SetNodeLabel()
• TreeView_SetNodeStateImage()
• TreeView_SetSelectedNode()
FUNCTION LIBRARY REFERENCE 637
T R E E V I E W _ A D D N O D E ( )

TreeView_AddNode()
Description The TreeView_AddNode() function adds a new child node to the specified
node in a tree view field.

Syntax TreeView_AddNode(tree_view_field, label, data, parent_node_ID

{, contains_children} {, unselected_image} {, selected_image} {, state_image})

Parameters • tree_view_field – The tree view field to which a new node will be added.

• label – A string specifying the label to use for the new node.

• data – A long integer specifying the data value to associate with the node.

• parent_node_ID – A long integer specifying the ID of the parent node to

which a new child node will be added. If you are adding a new node at the
root level, use the constant TV_ROOT.

• contains_children – An optional boolean indicating whether the new node is

expected to contain children. If the new node will contain children, specify
true. Otherwise, specify false. Specifying true causes the node to display the
expansion button, even though the node has no children. This is useful
when child nodes are added dynamically as a node is expanded. If this
parameter is not supplied, it is assumed the new node won’t contain
children.

• unselected_image – An optional integer specifying the picture to display

when the node is not selected. The value corresponds to the item number of
an item listed in the TreeView Images window.

• selected_image – An optional integer specifying the picture to display for the

node when it is selected. Like the unselected_image parameter, this value
corresponds to an item in the TreeView Images window.

• state_image – An optional integer specifying the state image to display with

the node. The value corresponds to the item number of a state image listed
in the TreeView Images window.

Return value A long integer containing the ID of the new node.

638 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ A D D N O D E ()

Examples The following example adds five nodes to the Address List tree view field,
one for each region. The nodes are added at the root level, so the parent
node is TV_ROOT. Each node has two associated images. When the node is
selected, an image of a cardfile and hand is shown. When a node is not
selected, an image of a cardfile is shown. The item numbers of these two
images are 1 and 2 in the TreeView Images window.

local integer i;
local long node_ID;

for i = 1 to 5 do
node_ID = TreeView_AddNode('Address List', "Region " + str(i), 0,
➥ TV_ROOT, true, 2, 1);
end for;

This example code produces the following tree view field:

When a node is selected,

the selected image is
displayed. Otherwise, the
unselected image is
displayed.

FUNCTION LIBRARY REFERENCE 639

T R E E V I E W _ C O L L A P S E N O D E ( )

TreeView_CollapseNode()
Description The TreeView_CollapseNode() function collapses the specified node in a
tree view field.

Syntax TreeView_CollapseNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the node to be collapsed.

• node_ID – A long integer specifying the ID of the node to be collapsed.

Return value A boolean indicating whether the node was successfully collapsed. True
indicates the node was successfully collapsed. False indicates the node was
already collapsed.

Examples The following example collapses every root-level node in the Address List
tree view field.

local long node_ID;

local boolean result;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT);
while node_ID <> TV_NODEINVALID do
{Collapse the node.}
result = TreeView_CollapseNode('Address List', node_ID);
{Get the next root-level node.}
node_ID = TreeView_GetNextNode('Address List', node_ID);
end while;

640 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ C O U N T C H I L D R E N ()

TreeView_CountChildren()
Description The TreeView_CountChildren() function returns the number of children
for the specified node in a tree view field.

Syntax TreeView_CountChildren(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the node whose children will
be counted.

• node_ID – A long integer specifying the ID of the node whose children will
be counted.

Return value A long integer containing the number of child nodes.

Examples The following example counts the number of child nodes in the first root-
level node in the Address List tree view field.

local long node_ID;

local long child_count;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT);
if node_ID <> TV_NODEINVALID then
{Count the child nodes.}
child_count = TreeView_CountChildren('Address List', node_ID);
end if;

FUNCTION LIBRARY REFERENCE 641

T R E E V I E W _ C O U N T N O D E S ()

TreeView_CountNodes()
Description The TreeView_CountNodes() function returns the entire number of nodes
in a tree view field.

Syntax TreeView_CountNodes(tree_view_field)

Parameters • tree_view_field – The tree view field whose nodes will be counted.

Return value A long integer containing the number of nodes in the tree, including nodes
that are not visible. This value does not include the invisible node
TV_ROOT.

Examples The following example counts all nodes in the Address List tree view field.

local long node_count;

node_count = TreeView_CountNodes('Address List');

642 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ E X P A N D N O D E ()

TreeView_ExpandNode()
Description The TreeView_ExpandNode() function expands the specified node in a
tree view field.

Syntax TreeView_ExpandNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the node to be expanded.

• node_ID – A long integer specifying the ID of the node to be expanded.

Return value A boolean indicating whether the node was successfully expanded. True
indicates the node was successfully expanded. False indicates the node was
already expanded.

Examples The following example expands the currently-selected node for the
Address List tree view field.

local long node_ID;

local boolean result;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Expand the selected node.}
result = TreeView_ExpandNode('Address List', node_ID);
else
warning "No item is selected in the Address List field.";
end if;

FUNCTION LIBRARY REFERENCE 643

T R E E V I E W _ G E T C L I C K N O D E ()

TreeView_GetClickNode()
Description The TreeView_GetClickNode() function returns the ID of the node whose
state image was clicked.

Syntax TreeView_GetClickNode(tree_view_field)

Parameters • tree_view_field – The tree view field containing the node whose state image
was clicked.

Return value A long integer containing the node ID of the node whose state image was
clicked. The value TV_NODEINVALID is returned if no node state image
was clicked.

Comments The TreeView_GetClickNode() should be used only in the state click script
for the tree view field.

Examples The following is the state click script for the Address List tree view field. It
toggles the state image displayed when a node’s state image is clicked.

local long click_node;

local integer previous_image;

{Find which node’s state image was clicked.}

click_node = TreeView_GetClickNode('Address List');

if TreeView_GetNodeStateImage('Address List', click_node) = 1 then

{The clicked item is shown. Show the unclicked item.}
previous_image = TreeView_SetNodeStateImage('Address List',
➥ click_node, 2);
else
{The unclicked item is shown. Show the clicked item.}
previous_image = TreeView_SetNodeStateImage('Address List',
➥ click_item, 1);
end if;

644 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ G E T C O L L A P S I N G N O D E ()

TreeView_GetCollapsingNode()
Description The TreeView_GetCollapsingNode() function returns the ID of the node
that is being collapsed in a tree view field.

Syntax TreeView_GetCollapsingNode(tree_view_field)

Parameters • tree_view_field – The tree view field containing the node being collapsed.

Return value A long integer containing the node ID of the node being collapsed. The
value TV_NODEINVALID is returned if no node is being collapsed.

Comments This function is typically used only in the collapse script for a tree view
field to retrieve the ID of the node being collapsed.

Examples The following is the collapse script for the Address List tree view field. It
removes the child nodes from the node being collapsed.

local long node_ID;

local long number_removed;

{Get the ID of the collapsing node.}

node_ID = TreeView_GetCollapsingNode('Address List');
{Remove the children from the node.}
number_removed = TreeView_RemoveChildren('Address List', node_ID);

FUNCTION LIBRARY REFERENCE 645

T R E E V I E W _ G E T E X P A N D I N G N O D E ( )

TreeView_GetExpandingNode()
Description The TreeView_GetExpandingNode() function returns the ID of the node
that is being expanded in a tree view field.

Syntax TreeView_GetExpandingNode(tree_view_field)

Parameters • tree_view_field – The tree view field containing the node being expanded.

Return value A long integer containing the node ID of the node being expanded. The
value TV_NODEINVALID is returned if no node is being expanded.

Comments This function is typically used only in the expand script for a tree view field
to retrieve the ID of the node being expanded.

Examples The following is the expand script for the Address List tree view field. It
adds child nodes containing customer information to the node being
expanded.

local long node_ID;

local long new_node;
local string node_label;

{Get the ID of the expanding node.}

node_ID = TreeView_GetExpandingNode('Address List');
{Get the label for the node.}
node_label = TreeView_GetNodeLabel('Address List', node_ID);

{Set the appropriate range for the Customer_Data table.}

range clear table Customer_Data;
set 'Region' of table Customer_Data to node_label;
range start table Customer_Data by key 3;
range end table Customer_Data by key 3;

{Read the customer records for the region.}

get first table Customer_Data;
while err() <> EOF do
{Add the new node with customer information. Use the index card
image.}
new_node = TreeView_AddNode('Address List', 'Customer Name' of
➥ table Customer_Data, 0, node_ID, false, 3, 3);
get next table Customer_Data;
end while;

646 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ G E T F I R S T C H I L D ()

TreeView_GetFirstChild()
Description The TreeView_GetFirstChild() function returns the ID of the first child
node for the specified parent node in a tree view field.

Syntax TreeView_GetFirstChild(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the parent node.

• node_ID – A long integer specifying the ID of the parent node.

Return value A long integer containing the node ID of the first child of the specified
parent node. If the specified node contains no children, the
TV_NODEINVALID constant is returned.

Examples The following example retrieves the first child of the currently-selected
node in the Address List tree view field.

local long node_ID;

local long child_node_ID;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Get the ID of the first child for the selected node.}
child_node_ID = TreeView_GetFirstChild('Address List', node_ID);
else
warning "No item is selected in the Address List field.";
end if;

FUNCTION LIBRARY REFERENCE 647

T R E E V I E W _ G E T N E X T N O D E ( )

TreeView_GetNextNode()
Description The TreeView_GetNextNode() function returns the ID of the next sibling
for the specified node in a tree view field.

Syntax TreeView_GetNextNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose next sibling
will be returned.

Return value A long integer containing the node ID of the next sibling of the specified
node. If the specified node has no additional sibling, TV_NODEINVALID is
returned.

Examples The following example collapses every root-level node in the Address List
tree view field.

local long node_ID;

local boolean result;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT);
while node_ID <> TV_NODEINVALID do
{Collapse the node.}
result = TreeView_CollapseNode('Address List', node_ID);
{Get the next root-level node.}
node_ID = TreeView_GetNextNode('Address List', node_ID);
end while;

648 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ G E T N O D E D A T A ()

TreeView_GetNodeData()
Description The TreeView_GetNodeData() function returns the long integer data item
associated with the specified node.

Syntax TreeView_GetNodeData(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose data item will
be returned.

Return value A long integer containing the data item for the specified node.

Examples The following example retrieves the data item of the currently-selected
node in the Address List tree view field.

local long node_ID;

local long node_data;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Get the data item for the selected node.}
node_data = TreeView_GetNodeData('Address List', node_ID);
else
warning "No item is selected in the Address List field.";
end if;

FUNCTION LIBRARY REFERENCE 649

T R E E V I E W _ G E T N O D E I M A G E ( )

TreeView_GetNodeImage()
Description The TreeView_GetNodeImage() function returns an integer indicating the
image associated with the specified node.

Syntax TreeView_GetNodeImage(tree_view_field, node_ID, image_type

{, overlay_image})

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose image index
will be returned.

• image_type – An integer specifying which image type to return. Use the

TV_SELECTEDIMAGE constant to specify the image displayed when
the node is selected. Use the TV_NORMALIMAGE constant to specify the
image displayed when the node is not selected.

• overlay_image – An optional integer indicating the overlay image. This value

corresponds to the item number of an item image in the TreeView Images
window. If no overlay image is associated with the item, the
TV_NOIMAGE constant is returned.

Return value An integer indicating the image. This value corresponds to the item number
of an item image in the TreeView Images window. If no image is associated
with the node, the TV_NOIMAGE constant is returned.

Examples The following example retrieves an integer indicating the image used for
the selected state of the currently-selected node in the Address List tree
view field.

local long node_ID;

local integer node_image;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Get the integer indicating the image being used.}
node_image = TreeView_GetNodeImage('Address List', node_ID,
➥ TV_SELECTEDIMAGE);
else
warning "No item is selected in the Address List field.";
end if;

650 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ G E T N O D E L A B E L ()

TreeView_GetNodeLabel()
Description The TreeView_GetNodeLabel() function returns the label for the specified
node.

Syntax TreeView_GetNodeLabel(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose label will be
returned.

Return value A string containing the label for the specified node.

Examples The following example retrieves the label of the currently-selected node in
the Address List tree view field.

local long node_ID;

local string node_label;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Get the node label.}
node_label = TreeView_GetNodeLabel('Address List', node_ID);
else
warning "No item is selected in the Address List field.";
end if;

FUNCTION LIBRARY REFERENCE 651

T R E E V I E W _ G E T N O D E S T A T E I M A G E ( )

TreeView_GetNodeStateImage()
Description The TreeView_GetNodeStateImage() function retrieves the item number
of the state image associated with the specified node.

Syntax TreeView_GetNodeStateImage(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose state image is
being returned.

Return value An integer indicating the image. This value corresponds to the item number
of a state image listed in the TreeView Images window. If no state image is
associated with the node, the TV_NOIMAGE constant is returned.

Examples Refer to the example for TreeView_GetClickNode().

652 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ G E T P A R E N T ()

TreeView_GetParent()
Description The TreeView_GetParent() function returns the node ID of the parent of
the specified node.

Syntax TreeView_GetParent(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose parent will be
returned.

Return value A long integer containing the node ID of the parent of the specified node. If
the specified node is a root-level node, the value TV_ROOT is returned.

Examples The following example ascertains whether the currently-selected node in

the Address List tree view field is a root-level node.

local long node_ID;

local long parent_node_ID;
local boolean is_root_level;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Get the node's parent.}
parent_node_ID = TreeView_GetParent('Address List', node_ID);
if parent_node_ID = TV_ROOT then
is_root_level = true;
else
is_root_level = false;
end if;
else
warning "No item is selected in the Address List field.";
end if;

FUNCTION LIBRARY REFERENCE 653

T R E E V I E W _ G E T P R E V I O U S N O D E ()

TreeView_GetPreviousNode()
Description The TreeView_GetPreviousNode() function returns the ID of the
preceding sibling for the specified node.

Syntax TreeView_GetPreviousNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose preceding

sibling will be returned.

Return value A long integer containing the node ID of the preceding sibling of the
specified node. If the specified node has no preceding sibling,
TV_NODEINVALID is returned.

Examples The following example ascertains whether the current node is the first child
node in the current group of sibling nodes.

local long node_ID;

local long sibling_node_ID;
local boolean is_first_child;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Get the previous node.}
sibling_node_ID = TreeView_GetPreviousNode('Address List',
➥ node_ID);
if sibling_node_ID = TV_NODEINVALID then
is_first_child = true;
else
is_first_child = false;
end if;
else
warning "No item is selected in the Address List field.";
end if;

654 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ G E T R O O T N O D E ()

TreeView_GetRootNode()
Description The TreeView_GetRootNode() function returns the ID of the first root-
level node in a tree view field.

Syntax TreeView_GetRootNode(tree_view_field)

Parameters • tree_view_field – The tree view field containing the specified node.

Return value A long integer containing the node ID of the first root-level node. If the tree
has no nodes, TV_NODEINVALID is returned.

Examples The following example collapses every root-level node in the Address List
tree view field.

local long node_ID;

local boolean result;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetRootNode('Address List');
while node_ID <> TV_NODEINVALID then
{Collapse the node.}
result = TreeView_CollapseNode('Address List', node_ID);
{Get the next root-level node.}
node_ID = TreeView_GetNextNode('Address List', node_ID);
end while;

FUNCTION LIBRARY REFERENCE 655

T R E E V I E W _ G E T S E L E C T E D N O D E ( )

TreeView_GetSelectedNode()
Description The TreeView_GetSelectedNode() function returns the ID of the currently-
selected node in a tree view field.

Syntax TreeView_GetSelectedNode(tree_view_field)

Parameters • tree_view_field – The tree view field containing the selected node.

Return value A long integer containing the node ID of the selected node. If the tree
doesn’t have a node selected, TV_NODEINVALID is returned.

Examples The following example expands the currently-selected node for the
Address List tree view field.

local long node_ID;

local boolean result;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Expand the selected node.}
result = TreeView_ExpandNode('Address List', node_ID);
else
warning "No item is selected in the Address List field.";
end if;

656 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ I S P A R E N T N O D E ()

TreeView_IsParentNode()
Description The TreeView_IsParentNode() function indicates whether a specific node
in a tree view field is a parent node.

Syntax TreeView_IsParentNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the node.

• node_ID – A long integer specifying the ID of the node whose status will be
determined.

Return value A long integer corresponding to one of the following constants:

Constant Description
TV_NODE_NONPARENT The node is not a parent.
TV_NODE_PARENT_COLLAPSED The node is a parent and is in the collapsed state.
TV_NODE_PARENT_EXPANDED The node is a parent and is in the expanded state.

Examples The following example returns whether the first root-level node in the
Address List tree view field is a parent.

local long node_ID;

local long is_parent;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT).
if node_ID <> TV_NODEINVALID then
{Is the node a parent?}
is_parent = TreeView_IsParentNode('Address List', node_ID);
end if;

FUNCTION LIBRARY REFERENCE 657

T R E E V I E W _ M A K E N O D E V I S I B L E ( )

TreeView_MakeNodeVisible()
Description The TreeView_MakeNodeVisible() function ensures that the specified
node is visible in the tree. If necessary, the contents of the tree will be
scrolled to make the specified node visible.

Syntax TreeView_MakeNodeVisible(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node to be made visible.

Return value A boolean indicating whether the node was made visible. True indicates the
node was made visible, while false indicates it was not.

Comments Making a node visible does not select the node. To select the node, use the
TreeView_SetSelectedNode() function.

Examples The following example makes the currently-selected node for the Address
List tree view field visible to the user.

local long node_ID;

local boolean result;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Make the selected node visible to the user.}
result = TreeView_MakeNodeVisible('Address List', node_ID);
else
warning "No item is selected in the Address List field.";
end if;

658 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ R E M O V E C H I L D R E N ()

TreeView_RemoveChildren()
Description The TreeView_RemoveChildren() function removes the child nodes for
the specified parent node.

Syntax TreeView_RemoveChildren(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view containing the parent node.

• node_ID – A long integer specifying the ID of the parent node.

Return value A long integer containing the number of child nodes removed. This value
does not include the descendants of the child nodes removed.

Comments To remove all nodes from a tree, specify TV_ROOT as the parent node.

Examples The following example removes all nodes from the Address List tree view
field.

local long nodes_removed;

nodes_removed = TreeView_RemoveChildren('Address List', TV_ROOT);

FUNCTION LIBRARY REFERENCE 659

T R E E V I E W _ R E M O V E N O D E ( )

TreeView_RemoveNode()
Description The TreeView_RemoveNode() function deletes the specified node from a
tree view field.

Syntax TreeView_RemoveNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the node to remove.

• node_ID – A long integer specifying the ID of the node to remove.

Return value A boolean indicating whether the node was successfully removed. True
indicates the node was successfully removed. False indicates the node was
not removed.

Comments When a node is removed, all of its children are removed as well. To remove
all nodes from a tree, use the TreeView_RemoveChildren(), specifying the
node TV_ROOT.

Examples The following example removes the first root-level node in the Address List
tree view field.

local long node_ID;

local boolean result;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT);
if node_ID <> TV_NODEINVALID then
{Remove the node.}
result = TreeView_RemoveNode('Address List', node_ID);
end if;

660 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ S E T N O D E D A T A ()

TreeView_SetNodeData()
Description The TreeView_SetNodeData() function sets the data item associated with
the specified node.

Syntax TreeView_SetNodeData(tree_view_field, node_ID, node_data)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose data item will
be set.

• node_data – A long integer containing the node data.

Return value A long integer containing the previous data item for the specified node.

Examples The following example sets the data item of the currently-selected node in
the Address List tree view field to -1.

local long node_ID;

local long previous_value;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Set the data item for the selected node.}
previous_value = TreeView_SetNodeData('Address List', node_ID,
➥ -1);
else
warning "No item is selected in the Address List field.";
end if;

FUNCTION LIBRARY REFERENCE 661

T R E E V I E W _ S E T N O D E I M A G E ( )

TreeView_SetNodeImage()
Description The TreeView_SetNodeImage() function specifies which image to use for
the specified node.

Syntax TreeView_SetNodeImage(tree_view_field, node_ID, image_type, index

{, overlay_image})

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose image will be
set.

• image_type – An integer specifying which image type to set. Use the

TV_SELECTEDIMAGE constant to specify the image displayed when
the node is selected. Use the TV_NORMALIMAGE constant to specify the
image displayed when the node is not selected.

• index – An integer specifying the image to use. The value corresponds to the
item number of an item image listed in the TreeView Images window. If no
image will be displayed for the node, use the TV_NOIMAGE constant.

• overlay_image – An optional integer specifying the image to use as the

overlay image. The value corresponds to the item number of an item image
listed in the TreeView Images window.

Return value An integer containing the item number for the image previously associated
with the specified node.

Examples The following example causes every root-level node in the Address List tree
view field to not display an image.

local long node_ID;

local integer previous_image;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT);
while node_ID <> TV_NODEINVALID then
{Set the node's selected and unselected images.}
previous_image = TreeView_SetNodeImage('Address List', node_ID,
➥ TV_SELECTEDIMAGE, TV_NOIMAGE);
previous_image = TreeView_SetNodeImage('Address List', node_ID,
➥ TV_NORMALIMAGE, TV_NOIMAGE);
node_ID = TreeView_GetNextNode('Address List', node_ID);
end while;

662 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ S E T N O D E L A B E L ()

TreeView_SetNodeLabel()
Description The TreeView_SetNodeLabel() function sets the label for the specified
node.

Syntax TreeView_SetNodeLabel(tree_view_field, node_ID, label)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose label will be
set.

• label – A string containing the new label.

Return value A boolean indicating whether the label was set. True indicates the label was
set, while false indicates it was not.

Examples The following example allows the user to specify a new label for the current
node in the Address List tree view field.

local long node_ID;

local string new_label;
local boolean result;

{Get the ID of the selected node.}

node_ID = TreeView_GetSelectedNode('Address List');
if node_ID <> TV_NODEINVALID then
{Ask the user to enter a new label.}
if getstring("Enter a new label", false, new_label) = true then
{Set the new label.}
result = TreeView_SetNodeLabel('Address List', node_ID,
➥ new_label);
end if;
else
warning "No item is selected to edit.";
end if;

FUNCTION LIBRARY REFERENCE 663

T R E E V I E W _ S E T N O D E S T A T E I M A G E ( )

TreeView_SetNodeStateImage()
Description The TreeView_SetNodeStateImage() function sets the state image
associated with the specified node.

Syntax TreeView_SetNodeStateImage(tree_view_field, node_ID, image)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node whose state image is
being set.

• image – An integer specifying the state image to use. The value corresponds
to the item number of a state image listed in the TreeView Images window.
If no image will be displayed, use the TV_NOIMAGE constant.

Return value An integer containing the item number of the previous state image for the
specified node. If no state image is associated with the tree view node, the
constant TV_NOIMAGE is returned.

Examples Refer to the example for TreeView_GetClickNode().

664 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R E E V I E W _ S E T S E L E C T E D N O D E ()

TreeView_SetSelectedNode()
Description The TreeView_SetSelectedNode() function makes the specified node
selected and visible in the tree view field.

Syntax TreeView_SetSelectedNode(tree_view_field, node_ID)

Parameters • tree_view_field – The tree view field containing the specified node.

• node_ID – A long integer specifying the ID of the node that will be selected.

Return value A boolean indicating whether the node was selected. True indicates the
node was selected, while false indicates it was not.

Examples The following example selects the first node in the Address List tree view
field.

local long node_ID;

local boolean result;

{Retrieve the node ID for the first root-level node.}

node_ID = TreeView_GetFirstChild('Address List', TV_ROOT);
{Set the selected node.}
result = TreeView_SetSelectedNode('Address List', node_ID);

FUNCTION LIBRARY REFERENCE 665

666 F U N C T I O N L I B R A R Y R E F E R E N C E
 Trigger function library
Refer to Part 3, Object
Triggers, in the Inte-
gration Guide for more
information.
Use the functions in this library when working with triggers in your
application. This library contains the following functions:
• Trigger_CausedByProduct()
• Trigger_DisableSingle()
• Trigger_Enable()
• Trigger_EnableSingle()
• Trigger_GetCurrentTag
• Trigger_IsTriggerEnabled()
• Trigger_RegisterDatabase()
• Trigger_RegisterDatabaseByName()
• Trigger_RegisterFocus()
• Trigger_RegisterFocusByName()
• Trigger_RegisterForm()
• Trigger_RegisterFormByName()
• Trigger_RegisterFunction()
• Trigger_RegisterFunctionByName()
• Trigger_RegisterProcedure()
• Trigger_RegisterProcedureByName()
• Trigger_Unregister()
FUNCTION LIBRARY REFERENCE 667
T R I G G E R _ C A U S E D B Y P R O D U C T ( )

Trigger_CausedByProduct()
Description The Trigger_CausedByProduct() function is used in a trigger processing
procedure of a database trigger to find out which product caused the
trigger to activate.

Syntax Trigger_CausedByProduct()

Parameters • None

Return value An integer containing the ID of the product that caused the trigger to
activate. The value -1 is returned if the trigger is activated by a script that is
running in the background. Currently, you can’t find what product caused a
trigger if processing is occurring in the background.

Comments This function is useful if you want to selectively run a database trigger
processing script based on the product that caused the trigger to activate.

Examples The following example is a trigger processing procedure for a trigger

registered for the RM_Customer_MSTR table. It uses the
Trigger_CausedByProduct() function to find out which product caused the
trigger to activate. If the ID of the product that caused the trigger is 15, no
processing is performed.

inout table RM_Customer_MSTR;

in integer table_operation;

if Trigger_CausedByProduct() <> 15 then

'Customer Number' of table Customer_Contacts = 'Customer Number'
➥ of table Customers;
release table Customer_Contacts;
change table Customer_Contacts by number 1;
if err() = OKAY then
remove table Customer_Contacts;
end if;
end if;

668 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ D I S A B L E S I N G L E ()

Trigger_DisableSingle()
Description The Trigger_DisableSingle() function disables a specific trigger.

Syntax Trigger_DisableSingle(tag)

Parameters • tag – An integer that uniquely identifies a trigger. The tag was assigned
when the trigger was registered.

Return value A boolean. True indicates the trigger was successfully disabled, while false
indicates it was not.

Examples The following example disables a single trigger. The tag for the trigger is
stored in the Trigger_List global variable, which is an array.

local boolean result;

result = Trigger_DisableSingle(Trigger_List[3] of globals);

if result = false then
error "Could not disable trigger.";
end if;

FUNCTION LIBRARY REFERENCE 669

T R I G G E R _ E N A B L E ( )

Trigger_Enable()
Description The Trigger_Enable() function enables or disables all object triggers for a
given application.

Syntax Trigger_Enable(product_ID, flag)

Parameters • product_ID – An integer specifying the product ID of the application whose

triggers you’re disabling or enabling.

• flag – A boolean that enables or disables triggers. Values are:

Value Description
true Triggers are enabled for the specified product.
false Triggers are disabled for the specified product.

Return value A boolean indicating the result; true if the function succeeded, false if it
didn’t succeed.

Comments You can use this function or the Customization Status window to disable all
triggers for a given application. Use the Trigger_DisableSingle() and
Trigger_EnableSingle() functions to disable and enable individual triggers.

Examples This example disables triggers for a stand-alone application.

if Trigger_Enable(3333, false) then

warning "Triggers are disabled for Item Tracking.";
end if;

Related items Additional information

Chapter 7, “Using Triggers,” in the Integration Guide

670 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ E N A B L E S I N G L E ()

Trigger_EnableSingle()
Description The Trigger_EnableSingle() function enables a specific trigger.

Syntax Trigger_EnableSingle(tag)

Parameters • tag – An integer that uniquely identifies a trigger. The tag was assigned
when the trigger was registered.

Return value A boolean. True indicates the trigger was successfully enabled, while false
indicates it was not.

Examples The following example enables a single trigger. The tag for the trigger is
stored in the Trigger_List global variable, which is an array.

local boolean result;

result = Trigger_EnableSingle(Trigger_List[3] of globals);

if result = false then
error "Could not enable trigger.";
end if;

FUNCTION LIBRARY REFERENCE 671

T R I G G E R _ G E T C U R R E N T T A G

Trigger_GetCurrentTag
Description The Trigger_GetCurrentTag() function is used in a trigger processing
procedure to retrieve the tag associated with the current trigger.

Syntax Trigger_GetCurrentTag()

Parameters • None

Return value An integer containing the tag for the current trigger.

Examples The following example is a trigger processing procedure. It retrieves the tag
for the current trigger, and then disables the trigger.

local integer tag;

local boolean result;

tag = Trigger_GetCurrentTag();
result = Trigger_Unregister(tag);

672 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ I S T R I G G E R E N A B L E D ()

Trigger_IsTriggerEnabled()
Description The Trigger_IsTriggerEnabled() function returns a boolean indicating
whether a specific trigger is enabled.

Syntax Trigger_IsTriggerEnabled(tag)

Parameters • tag – An integer that uniquely identifies a trigger. The tag was assigned
when the trigger was registered.

Return value A boolean. True indicates the trigger is enabled, while false indicates it is
not.

Examples The following example examines the state of a single trigger. The tag for the
trigger is stored in the Trigger_List global variable, which is an array. If the
trigger is currently enabled, it will be disabled.

local boolean result;

if Trigger_IsTriggerEnabled(Trigger_List[3] of globals) then

result = Trigger_DisableSingle(Trigger_List[3] of globals);
if result = false then
error "Could not disable trigger.";
end if;
end if;

FUNCTION LIBRARY REFERENCE 673

T R I G G E R _ R E G I S T E R D A T A B A S E ( )

Trigger_RegisterDatabase()
Description
The Trigger_RegisterDatabase() function registers a database trigger for
use with the runtime engine. Database triggers are activated by successful
table operations in an application, such as saving a record, deleting a record
or reading a record.

Syntax Trigger_RegisterDatabase(anonymous(table table_name),

form form_name , table_operations, script processing_procedure {, tag})

Parameters • table table_name – A table resource in the application dictionary. This is the
table for which the trigger will be registered. Use the anonymous() function
with this parameter to avoid implicitly opening the table.

• form form_name – The restriction for the database trigger. The form_name is
a form resource in the application. This restricts the trigger to database
operations that originate from the table buffer for the form form_name. Use a
zero (0) if no form restriction applies.

• table_operations – An integer identifying which table operation activates

the trigger. The following constants represent these operations; add
values together to activate a trigger for more than one table operation.
For instance, the integer “3” activates a database trigger for all
types of database read operations (TRIGGER_ON_DB_READ +
TRIGGER_ON_DB_READ_LOCK).

Constant Value Description

TRIGGER_ON_DB_READ
TRIGGER_ON_DB_READ_LOCK
TRIGGER_ON_DB_ADD
TRIGGER_ON_DB_UPDATE
TRIGGER_ON_DB_DELETE
1 Occurs when the application reads an
existing record in table_name without
locking it, such as done by the get
statement.
2 Occurs when the application reads an
existing record in table_name and passively
or actively locks it, such as done by the
change or edit table statements.
4 Occurs when the application adds a new
record to table_name.
8 Occurs when the application updates an
existing record in table_name.
16 Occurs when the application deletes a
record in table_name.

674 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R D A T A B A S E ()

• script processing_procedure – The procedure you write that’s run (called the
trigger processing procedure) when the database trigger is activated. Upon a
successful table operation, the database trigger passes the current record
buffer to this procedure as an inout parameter.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.

Comments Upon a successful table operation, a database trigger is activated and passes
the table buffer on which the table operation occurred to the trigger
processing procedure as an inout parameter. This buffer is always available
to the processing procedure, regardless of the table operation successfully
completed. Successful table operations that occur for a range of records will
activate a database trigger for each record in the range. Each record’s buffer
is then passed to the processing procedure.

You can include a second optional integer in parameter in the trigger

processing procedure. If this parameter is included, a value is automatically
passed in indicating the table operation that activated the trigger. The value
corresponds to the constants listed in the table_operations parameter.

A database trigger with a form restriction is activated only if that form’s

record buffer is used for the table operation. For instance, if another form
performs an operation on the same table, the database trigger won’t be
activated, because the other form has its own table buffer for the table.

FUNCTION LIBRARY REFERENCE 675

T R I G G E R _ R E G I S T E R D A T A B A S E ( )

Examples This example registers a database trigger used to delete a customer contact
record when the user deletes its corresponding customer record.

{Name: Startup}
local integer l_result;

l_result = Trigger_RegisterDatabase(anonymous(table Customers), form

➥ Customers, TRIGGER_ON_DB_DELETE, script Delete_Customer_Contacts);
if l_result<>SY_NOERR then
warning "Database trigger registration failed.";
end if;

When the trigger is activated, this processing procedure deletes the

customer contacts record corresponding to the deleted customer record.

{Name: Delete_Customer_Contacts}
inout table Customers;
in integer table_operation;

'Customer Number' of table Customer_Contacts = 'Customer Number' of

➥ table Customers;
release table Customer_Contacts;
change table Customer_Contacts by number 1;
if err() = OKAY then
remove table Customer_Contacts;
restart form;
end if;

Related items Additional information

Chapter 10, “Database Triggers,” in the Integration Guide
Chapter 20, “Procedures,” in Volume 2 of the Dexterity Programmer’s Guide

676 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R D A T A B A S E B Y N A M E ()

Trigger_RegisterDatabaseByName()
Description The Trigger_RegisterDatabaseByName() function registers a database
trigger for a table in the specified dictionary. Database triggers are activated
by successful table operations in an application, such as saving a record,
deleting a record or reading a record.

Syntax Trigger_RegisterDatabaseByName(product_ID, table_name, form_name,

table_operations, script processing_procedure {, tag})

Parameters • product_ID – An integer specifying the ID of the product that contains the
table for which the trigger is being registered.

• table_name – A string specifying the table for which the trigger is being
registered.

• form_name – A string specifying any form restriction for the database

trigger. This restricts the trigger to database operations that originate from
the table buffer for the form form_name. Use an empty string ("") if no form
restriction applies.

• table_operations – An integer identifying which table operation activates

the trigger. The following constants represent these operations; add
values together to activate a trigger for more than one table operation.
For instance, the integer “3” activates a database trigger for all
types of database read operations ( TRIGGER_ON_DB_READ +
TRIGGER_ON_DB_READ_LOCK).

Constant Value Description

TRIGGER_ON_DB_READ
TRIGGER_ON_DB_READ_LOCK
TRIGGER_ON_DB_ADD
TRIGGER_ON_DB_UPDATE
TRIGGER_ON_DB_DELETE
1 Occurs when the application reads an
existing record in table_name without
locking it, such as done by the get
statement.
2 Occurs when the application reads an
existing record in table_name and passively
or actively locks it, such as done by the
change or edit table statements.
4 Occurs when the application adds a new
record to table_name.
8 Occurs when the application updates an
existing record in table_name.
16 Occurs when the application deletes a
record in table_name.

FUNCTION LIBRARY REFERENCE 677

T R I G G E R _ R E G I S T E R D A T A B A S E B Y N A M E ()

• script processing_procedure – The procedure you write that’s run (called the
trigger processing procedure) when the database trigger is activated. Upon a
successful table operation, the database trigger passes the current record
buffer to this procedure as an inout parameter.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.
SY_INVALID_OBJECT 4 The object for which the trigger is being registered
cannot be found.

Comments Upon a successful table operation, a database trigger is activated and passes
the table buffer on which the table operation occurred to the trigger
processing procedure as an anonymous inout parameter. This buffer is
always available to the processing procedure, regardless of whether the
table operation successfully completed. Use the column() function to
retrieve specific fields from the table buffer.

Successful table operations that occur for a range of records will activate a
database trigger for each record in the range. Each record’s buffer is then
passed to the processing procedure.

You can include a second optional integer in parameter in the trigger

processing procedure. If this parameter is included, a value is automatically
passed in indicating the table operation that activated the trigger. The value
corresponds to the constants listed in the table_operations parameter.

A database trigger with a form restriction is activated only if that form’s

record buffer is used for the table operation. For instance, if another form
performs an operation on the same table, the database trigger won’t be
activated, because the other form has its own table buffer for the table.

678 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R D A T A B A S E B Y N A M E ()

Examples This example registers a database trigger used to delete an Internet

information record when the user deletes the corresponding applicant
record.

{Name: Startup}
local integer result;

{Register the database trigger that runs when deleting the applicant
record.}
result = Trigger_RegisterDatabaseByName(414, "HR_Applicant", "",
TRIGGER_ON_DB_DELETE, script Delete_Applicant_Internet_Info);
if result <> SY_NOERR then
warning "Database trigger 3 registration failed.";
end if;

When the trigger is activated, this processing procedure deletes the Internet
information record corresponding to the applicant record that was deleted.

{Name: Delete_Applicant_Internet_Info}
inout anonymous table 'Triggered Table';

release table Appl_Internet_Info;

'Applicant Number' of table Appl_Internet_Info =
➥ column("Applicant Number") of table 'Triggered Table';
change table Appl_Internet_Info;
if err() = OKAY then
remove table Appl_Internet_Info;
end if;

FUNCTION LIBRARY REFERENCE 679

T R I G G E R _ R E G I S T E R F O C U S ( )

Trigger_RegisterFocus()
Description The Trigger_RegisterFocus() function registers a focus trigger for use with
the runtime engine. Focus triggers are activated by “focus” events in an
application, such as a window opening or closing, or the focus moving from
one field to the next. Focus triggers can be linked to any location where
Dexterity allows you to attach a script, such as window pre and post scripts,
or field pre, change and post scripts.

Syntax Trigger_RegisterFocus(anonymous (qualified_resource), focus_type,

attach_type, script processing_procedure {, tag})

Parameters • qualified_resource – A resource fully qualified using the “form,” “window,”

and “menu” sanScript qualifiers, such as:

• ‘Field1’ of window ‘Window1’ of form ‘Form1’.

• form ‘Form1’.
• window ‘Window1’ of form ‘Form1’.
• window ‘Scrollwin1’ of form ‘Form1’.
• menu ‘Menu1’ of form ‘Form1’.
• command ‘Command Name’ of form ‘Form1’.

Typically, you should use the anonymous() function with this parameter to
avoid implicitly opening the resource.

• focus_type – An integer identifying which focus event activates the trigger.

Use either the integer value or its corresponding constant:

Constant Value
TRIGGER_FOCUS_PRE 0
TRIGGER_FOCUS_CHANGE 1
TRIGGER_FOCUS_POST 2
TRIGGER_FOCUS_PRINT 3
TRIGGER_FOCUS_ACTIVATE 4
TRIGGER_FOCUS_FILL 5
TRIGGER_FOCUS_INSERT 6
TRIGGER_FOCUS_DELETE 7
TRIGGER_FOCUS_CONTEXT_MENU 9

680 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F O C U S ()

If the qualified_resource is a menu, focus_type indicates which menu item

activates the trigger. If the qualified_resource is a button field, only change
events (TRIGGER_FOCUS_CHANGE) activate a focus trigger.

• attach_type – An integer indicating when the focus trigger runs relative to

the original focus event:

Constant Value
TRIGGER_BEFORE_ORIGINAL 1
TRIGGER_AFTER_ORIGINAL 2

• script processing_procedure – A procedure you write that’s run when the

focus trigger is activated.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.
SY_INVALID_FOCUS 3 The focus_type is not valid for the
qualified_resource.

FUNCTION LIBRARY REFERENCE 681

T R I G G E R _ R E G I S T E R F O C U S ( )

Comments It’s important to remember that focus triggers are activated by focus events
regardless of whether a script already exists for that focus event. You can create
focus triggers that are activated by the following types of objects and focus
events:

Object Available focus events

Field pre, change, post, or context menu
(Note: Button fields run triggers for change focus events only.)
Form pre or post
Window pre, post, activate, print, or context menu
Scrolling Window pre line, change line, post line, fill line, insert line, delete line, or
context menu
Menu change (for the menu item)
Command change (only for commands of type Script)

Examples This example registers a focus trigger that is activated when the Customers
form closes.

{Name: Startup}
local integer l_result;

l_result = Trigger_RegisterFocus(anonymous(window Customers of form

➥ Customers), TRIGGER_FOCUS_POST, TRIGGER_AFTER_ORIGINAL, script
➥ Close_Customer_Contacts);
if l_result <> SY_NOERR then
warning "Focus trigger registration failed.";
end if;

When the trigger is activated, this trigger processing procedure simply

closes the Customer_Contacts form:

{Name: Close_Customer_Contacts}
close form Customer_Contacts;

Related items Additional information

Chapter 9, “Focus Triggers,” in the Integration Guide

682 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F O C U S B Y N A M E ()

Trigger_RegisterFocusByName()
Description The Trigger_RegisterFocusByName() function registers a focus trigger for
a resource in the specified dictionary. Focus triggers are activated by
“focus” events in an application, such as a window opening or closing, or
the focus moving from one field to the next. Focus triggers can be linked to
any location where Dexterity allows you to attach a script, such as window
pre and post scripts, or field pre, change and post scripts.

Syntax Trigger_RegisterFocusByName(product_ID, qualified_resource, focus_type,

attach_type, script processing_procedure {, tag})

Parameters • product_ID – An integer specifying the ID of the product that contains the
form for which the trigger is being registered.

• qualified_resource – A string containing the fully qualified name of the

resource. It must use the “form,” “window,” and “menu” sanScript
qualifiers, such as:

• ‘Field1’ of window ‘Window1’ of form ‘Form1’.

• form ‘Form1’.
• window ‘Window1’ of form ‘Form1’.
• window ‘Scrollwin1’ of form ‘Form1’.
• menu ‘Menu1’ of form ‘Form1’.
• command ‘Command Name’ of form ‘Form1’.
Any resource names that contain spaces must be enclosed in single quotes.

• focus_type – An integer identifying which focus event activates the trigger.

Use either the integer value or its corresponding constant:

Constant Value
TRIGGER_FOCUS_PRE 0
TRIGGER_FOCUS_CHANGE 1
TRIGGER_FOCUS_POST 2
TRIGGER_FOCUS_PRINT 3
TRIGGER_FOCUS_ACTIVATE 4
TRIGGER_FOCUS_FILL 5
TRIGGER_FOCUS_INSERT 6
TRIGGER_FOCUS_DELETE 7
TRIGGER_FOCUS_CONTEXT_MENU 9

FUNCTION LIBRARY REFERENCE 683

T R I G G E R _ R E G I S T E R F O C U S B Y N A M E ( )

If the qualified_resource is a menu, focus_type indicates which menu item

activates the trigger. If the qualified_resource is a button field, only change
events (TRIGGER_FOCUS_CHANGE) activate a focus trigger.

• attach_type – An integer indicating when the focus trigger runs relative to

the original focus event:

Constant Value
TRIGGER_BEFORE_ORIGINAL 1
TRIGGER_AFTER_ORIGINAL 2

• script processing_procedure – A procedure you write that’s run when the

focus trigger is activated.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR
SY_UNKNOWN
SY_INVALID_SCRIPT
SY_INVALID_FOCUS
SY_INVALID_OBJECT
0 No error occurred.
1 An unknown error occurred and the trigger was not
registered.
2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.
3 The focus_type is not valid for the
qualified_resource.
4 The object for which the trigger is being registered
cannot be found.

684 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F O C U S B Y N A M E ()

Comments It’s important to remember that focus triggers are activated by focus events
regardless of whether a script already exists for that focus event. Focus triggers
are activated by the following types of objects and focus events:

Object Available focus events

Field pre, change, post, or context menu
(Note: Button fields run triggers for change focus events only.)
Form pre or post
Window pre, post, activate, print, or context menu
Scrolling Window pre line, change line, post line, fill line, insert line, delete line, or
context menu
Menu change (for the menu item)
Command change (only for commands of type Script)

Examples The following example registers a focus trigger that runs when the
Applicants window restarts.

{Name: Startup}
{Register the focus trigger that runs when the Applicants window
restarts.}
result = Trigger_RegisterFocusByName(414,
➥ "window 'HR Applicant Tracking' of form 'HR Applicant'",
➥ TRIGGER_FOCUS_PRE, TRIGGER_AFTER_ORIGINAL,
➥ script Restart_Applicant_Internet_Info);
if result <> SY_NOERR then
warning "Focus trigger registration failed.";
end if;

When the trigger is activated, this processing procedure clears the

Applicant_Internet_Info form.
{Name: Restart_Applicant_Internet_Info}

if isopen(form Applicant_Internet_Info) then

clear form Applicant_Internet_Info;
end if;

FUNCTION LIBRARY REFERENCE 685

T R I G G E R _ R E G I S T E R F O R M ( )

Trigger_RegisterForm()
Description The Trigger_RegisterForm() function registers a form trigger for use with
the runtime engine. When a form trigger is registered, an “Extras” menu
will appear when the specified form is opened.

Syntax Trigger_RegisterForm(form form_name, menu_item_name, accelerator_key,

script processing_procedure {, tag})

Parameters • form form_name – The name of the form for which the trigger is registered.
The Extras menu will appear when this form is open.

• menu_item_name – The name of the menu item as it will appear in the Extras
menu.

• accelerator_key – The accelerator key used with the menu_item_name. This is

the key that, when used with the CONTROL key, chooses menu_item_name.
For instance, specifying “1” will enable an accelerator key of CTRL+1 for a
Windows application. Be sure that this key doesn’t conflict with any
existing accelerator keys. If you don’t want an accelerator key, indicate an
empty string ("").

• script processing_procedure – The procedure you write that will run when
you choose the menu_item_name from the Extras menu.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.

686 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F O R M ()

Comments You can disable all triggers for a given application using the
Trigger_Enable() function or the Customization Status window. If you
disable a form trigger for a form that’s currently open, the Extras menu
won’t disappear until the form is closed. If the user chooses the menu item
before closing the form, the message “Cannot run form trigger” will appear.

Examples This example registers a form trigger for the Customers form. It adds the
menu item “Customer Contacts” to the Extras menu displayed when the
Customers form is open. When the user chooses the menu item, the
procedure named Open_Customer_Contacts is called.

{Name: Startup}
local integer l_result;

l_result = Trigger_RegisterForm(form Customers, "Customer Contacts",

➥ "", script Open_Customer_Contacts);
if l_result<>SY_NOERR then
warning "Form trigger registration failed.";
end if;

When the user chooses Customer Contacts from the Extras menu, this
processing procedure is run. It opens the form named Customer_Contacts,
sets window fields, and retrieves a record from the Customer Contacts
table.

{Name: Open_Customer_Contacts}
open form Customer_Contacts;

if isopen(form Customers) then

'Customer Number' of window Customer_Contacts of form
➥ Customer_Contacts = 'Customer Number' of window Customers of
➥ form Customers;
run script 'Customer Number' of window Customer_Contacts of form
➥ Customer_Contacts;
end if;

Related items Additional information

Chapter 8, “Form Triggers,” in the Integration Guide

FUNCTION LIBRARY REFERENCE 687

T R I G G E R _ R E G I S T E R F O R M B Y N A M E ()

Trigger_RegisterFormByName()
Description The Trigger_RegisterFormByName() function registers a form trigger for a
form in the specified dictionary. When a form trigger is registered, an
“Extras” menu will appear when the specified form is opened.

Syntax Trigger_RegisterFormByName(product_ID, form_name, menu_item_name,

accelerator_key, script processing_procedure {, tag})

Parameters • product_ID – An integer specifying the ID of the product that contains the
form for which the trigger is being registered.

• form_name – A string containing the name of the form for which the trigger
is registered. The Extras menu will appear when this form is open.

• menu_item_name – A string containing the name of the menu item as it will

appear in the Extras menu.

• accelerator_key – The accelerator key used with the menu_item_name. This is

the key that, when used with the CONTROL key, chooses menu_item_name.
For instance, specifying “1” will enable an accelerator key of CTRL+1 for a
Windows application. Be sure that this key doesn’t conflict with any
existing accelerator keys. If you don’t want an accelerator key, indicate the
empty string ("").

• script processing_procedure – The procedure you write that will run when
you choose the menu_item_name from the Extras menu.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.
SY_INVALID_OBJECT 4 The object for which the trigger is being registered
cannot be found.

688 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F O R M B Y N A M E ()

Comments You can disable all triggers for a given application using the
Trigger_Enable() function or the Customization Status window. If you
disable a form trigger for a form that’s currently open, the Extras menu
won’t disappear until the form is closed. If the user chooses the menu item
before closing the form, the message “Cannot run form trigger” will appear.

Examples This example registers a form trigger for the HR_Applicant form. It adds
the menu item “Internet Information” to the Extras menu displayed when
the HR_Applicant form is open. When the user chooses the menu item, the
procedure named Open_Applicant_Internet_Info is called.

{Name: Startup}
local integer result;

result = Trigger_RegisterFormByName(414, "HR_Applicant",

➥ "Internet Information","", script Open_Applicant_Internet_Info);
if result <> SY_NOERR then
warning "Form trigger registration failed.";
end if;

When the user chooses Internet Information from the Extras menu, this
processing procedure is run. It opens the form named
Applicant_Internet_Info and uses the GetWindowValue() user-defined
function to retrieve the appropriate record from the
Applicant_Internet_Info table.

{Name: Open_Applicant_Internet_Info}
local anonymous appl_number;
local integer result;
local integer datatype;

open form Applicant_Internet_Info;

{Get the Applicant Number.}

result = GetWindowValue(414, "HR_Applicant", "HR_Applicant_Tracking",
➥ "'Applicant Number'", appl_number, datatype);
if result = 0 then
'Applicant Number' of window Applicant_Internet_Info of form
➥ Applicant_Internet_Info = currency(appl_number);
run script 'Applicant Number' of window Applicant_Internet_Info
➥ of form Applicant_Internet_Info;
end if;

FUNCTION LIBRARY REFERENCE 689

T R I G G E R _ R E G I S T E R F U N C T I O N ()

Trigger_RegisterFunction()
Description The Trigger_RegisterFunction() function registers a function trigger for use
with the runtime engine. A function trigger is activated when a specified
function is run.

Syntax Trigger_RegisterFunction(function function_name {of form form_name},

attach_type, [function processing_function | script processing_procedure]
{, tag})

Parameters • function function_name – A function in the application for which the

function trigger is registered. When this function is run, the function trigger
is activated.

• of form form_name – An optional parameter specifying a form name. Use

this only if function_name is a form function.

• attach_type – An integer indicating when the function trigger is activated,

relative to the original function:

Constant Value
TRIGGER_BEFORE_ORIGINAL 1
TRIGGER_AFTER_ORIGINAL 2

• function processing_function | script processing_procedure – A function or

procedure you write that runs in response to the function trigger.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.

690 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F U N C T I O N ()

Comments If a function runs in response to the function trigger, it must have exactly
the same set of parameters as the function that is being triggered on. If a
procedure runs in response to the function, it can’t have any parameters.

Examples This example registers a trigger that is activated when the GetNoteIndex
function is run.

{Name: Startup}
local integer l_result;

l_result = Trigger_RegisterFunction(function GetNoteIndex,

➥ TRIGGER_AFTER_ORIGINAL, function VerifyIndex);
if l_result <> SY_NOERR then
warning "The verify index trigger is not registered.";
end if;

Related items Additional information

Chapter 12, “Function Triggers,” in the Integration Guide

FUNCTION LIBRARY REFERENCE 691

T R I G G E R _ R E G I S T E R F U N C T I O N B Y N A M E ( )

Trigger_RegisterFunctionByName()
Description The Trigger_RegisterFunctionByName() function registers a function
trigger for a function in the specified dictionary. A function trigger is
activated when a specified function is run.

Syntax Trigger_RegisterFunctionByName(product_ID, function_name, attach_type,

[function processing_function | script processing_procedure] {, tag})

Parameters • product_ID – An integer specifying the ID of the product that contains the
function for which the trigger is being registered.

• function_name – A string containing the name of the function for which the
function trigger is registered. When this function is run, the function trigger
is activated. If the function is a form function, be sure to include the of form
form_name clause in the name.

• attach_type – An integer indicating when the function trigger is activated,

relative to the original function:

Constant Value
TRIGGER_BEFORE_ORIGINAL 1
TRIGGER_AFTER_ORIGINAL 2

• function processing_function | script processing_procedure – A function or

procedure you write that runs in response to the function trigger.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger was not
registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not found
or had the wrong number of parameters. The
trigger was not registered.
SY_INVALID_OBJECT 4 The object for which the trigger is being registered
cannot be found.

692 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R F U N C T I O N B Y N A M E ()

Comments If a function runs in response to the function trigger, it must have exactly
the same set of parameters as the function that is being triggered on. If a
procedure runs in response to the function, it can’t have any parameters.

Examples The following example registers a trigger that is activated when the
ValidateApplicant function is called.

local integer result;

result = Trigger_RegisterFunctionByName(414, "ValidateApplicant",

➥ TRIGGER_AFTER_ORIGINAL, script Handle_Validation);

FUNCTION LIBRARY REFERENCE 693

T R I G G E R _ R E G I S T E R P R O C E D U R E ( )

Trigger_RegisterProcedure()
Description The Trigger_RegisterProcedure() function registers a procedure trigger for
use with the runtime engine. A procedure trigger is activated when the
specified procedure is run.

Syntax Trigger_RegisterProcedure(script procedure {of form form_name},

attach_type, script processing_procedure {, tag})

Parameters • script procedure – The procedure for which the procedure trigger is
registered. When this procedure is run, the procedure trigger is activated.

• of form form_name – An optional parameter specifying a form name. Use

this only if procedure is a form procedure.

• attach_type – An integer indicating when the procedure trigger is activated,

relative to the original procedure:

Constant Value
TRIGGER_BEFORE_ORIGINAL 1
TRIGGER_AFTER_ORIGINAL 2

• script processing_procedure – A procedure you write that runs in response to

the procedure trigger.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger
was not registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not
found or had the wrong number of
parameters. The trigger was not registered.

694 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R P R O C E D U R E ()

Examples This example registers a trigger that is activated when the Security
procedure runs. The runtime engine calls a procedure named Security
automatically whenever the user opens a form. Refer to Chapter 5,
“Security,” in the Dexterity Stand-Alone Application Guide for information
about using the Security procedure.

{Name: Startup}
local integer l_result;

l_result = Trigger_RegisterProcedure(script Security,

➥ TRIGGER_AFTER_ORIGINAL, script Activity_Tracking);
if l_result <> SY_NOERR then
warning "The activity tracking trigger is not registered.";
end if;

When the trigger is activated, this processing procedure updates an activity

table. It uses the same parameters passed to the Security procedure.

{Name: Activity Tracking}

in integer l_prod_ID;
in integer l_resource_type;
in integer l_resource_ID;
out string l_alias;

'Resource Name' of table 'Activity Master' =

➥ Activity_GetDisplayName(l_prod_ID, l_resource_type, l_resource_ID);
'User Name' of table 'Activity Master' = 'User ID' of globals;
'System Time' of table 'Activity Master' = systime();
'System Date' of table 'Activity Master' = sysdate();
'Resource Type' of table 'Activity Master' = l_resource_type;
if err() = OKAY then
save table 'Activity Master';
else
warning "Cannot save activity record.";
end if;

Related items Additional information

Chapter 11, “Procedure Triggers,” in the Integration Guide

FUNCTION LIBRARY REFERENCE 695

T R I G G E R _ R E G I S T E R P R O C E D U R E B Y N A M E ( )

Trigger_RegisterProcedureByName()
Description The Trigger_RegisterProcedureByName() function registers a procedure
trigger for a procedure in the specified dictionary. A procedure trigger is
activated when the specified procedure is run.

Syntax Trigger_RegisterProcedureByName(product_ID, procedure_name,

attach_type, script processing_procedure {, tag})

Parameters • product_ID – An integer specifying the ID of the product that contains the
procedure for which the trigger is being registered.

• procedure_name – A string containing the name of the procedure for which

the procedure trigger is registered. When this procedure is run, the
procedure trigger is activated. If the procedure is a form procedure, be sure
to include the of form form_name clause in the name.

• attach_type – An integer indicating when the procedure trigger is activated,

relative to the original procedure:

Constant Value
TRIGGER_BEFORE_ORIGINAL 1
TRIGGER_AFTER_ORIGINAL 2

• script processing_procedure – A procedure you write that runs in response to

the procedure trigger.

• tag – An optional returned integer that uniquely identifies the trigger. This
value is used when you want to unregister, enable or disable the trigger
individually.

Return value An integer corresponding to the following constants:

Constant Value Description

SY_NOERR 0 No error occurred.
SY_UNKNOWN 1 An unknown error occurred and the trigger
was not registered.
SY_INVALID_SCRIPT 2 The trigger processing script was either not
found or had the wrong number of
parameters. The trigger was not registered.
SY_INVALID_OBJECT 4 The object for which the trigger is being
registered cannot be found.

696 F U N C T I O N L I B R A R Y R E F E R E N C E
 T R I G G E R _ R E G I S T E R P R O C E D U R E B Y N A M E ()

Examples The following example registers a trigger that is activated when the
Process_Applicant form procedure runs.

local integer result;

result = Trigger_RegisterProcedureByName(414,
➥ "Process_Applicant of form HR_Applicant_Tracking",
➥ TRIGGER_AFTER_ORIGINAL, script Applicant_PostProcessing);

FUNCTION LIBRARY REFERENCE 697

T R I G G E R _ U N R E G I S T E R ( )

Trigger_Unregister()
Description The Trigger_Unregister() function unregisters a specific trigger.

Syntax Trigger_Unregister(tag)

Parameters • tag – An integer that uniquely identifies a trigger. The tag was assigned
when the trigger was registered.

Return value A boolean. True indicates the trigger was successfully unregistered, while
false indicates it was not.

Comments When you unregister a trigger, its tag becomes invalid. If you reregister the
trigger, a new tag will be assigned.

Examples The following example unregisters a single trigger. The tag for the trigger is
stored in the Trigger_List global variable, which is an array. Since the tag is
no longer valid, the array element that stored the tag is cleared.

local boolean result;

result = Trigger_Unregister(Trigger_List[3] of globals);

if result = true then
{Clear the element of the array.}
clear Trigger_List[3] of globals;
else
error "Could not unregister trigger.";
end if;

698 F U N C T I O N L I B R A R Y R E F E R E N C E
Utility function library
Use the functions in this library for various utility operations you may need
to perform in your application. This library includes the following
functions:

• Utility_DecodeString()
• Utility_DecryptTableString()
• Utility_EncodeString()
• Utility_EncryptTableString()
• Utility_LaunchUrl()
• Utility_LoadDLL()
• Utility_SubstituteTokens()
• Utility_UnloadDLL()

FUNCTION LIBRARY REFERENCE 699

U T I L I T Y _ D E C O D E S T R I N G ()

Utility_DecodeString()
Description The Utility_DecodeString() function decodes a string that was encoded by
the Utility_EncodeString() function.

Syntax Utility_DecodeString(source_string)

Parameters • source_string – The string to be decoded.

Return value A string containing the value in decoded format.

Examples The following example uses the Utility_DecodeString() function to decode

the value in the Password field of the Users table.

local string user_entry;

if getstring ("Please enter password", true, user_entry) then

if user_entry = Utility_DecodeString(Password of table Users) then
open window Toolbar;
end if;
end if;

700 F U N C T I O N L I B R A R Y R E F E R E N C E
 U T I L I T Y _ D E C R Y P T T A B L E S T R I N G ()

Utility_DecryptTableString()
Description The Utility_DecryptTableString() function decrypts a string that has been
stored in a table in encrypted format.

Syntax Utility_DecryptTableString(source_string)

Parameters • source_string – The string to be decrypted.

Return value A string containing the value in decrypted format.

Examples The following example decrypts the value stored in the Password field of
the Users table. The Encrypt option for the table field was unmarked, so the
field was read without being decrypted by the database manager.

local string password;

UserID of table Users = UserID of globals;

get table Users;
if err() = OKAY then
password = Utility_DecryptTableString(Password of table Users);
end if;

FUNCTION LIBRARY REFERENCE 701

U T I L I T Y _ E N C O D E S T R I N G ( )

Utility_EncodeString()
Description The Utility_EncodeString() function converts a string into a format that
isn’t easily readable by users or other applications.

Syntax Utility_EncodeString(source_string)

Parameters • source_string – The string to be encoded.

Return value A string containing the value in encoded format.

Comments The encoded string will be up to 40% longer than the original string. When
you specify the storage size of the string in the table, be sure to allow for the
increased size. For example, if the string field allows up to 8 characters to be
entered by the user, be sure the storage size of the field allows for up to 12
characters to be stored.

Examples The following example uses the Utility_EncodeString() function to encode

the Password field stored in the Users table.

local string user_password;

if getstring("Please enter password", false, user_password) then

UserID of table Users = UserID of globals;
Password of table Users = Utility_EncodeString(user_password);
save table Users;
end if;

702 F U N C T I O N L I B R A R Y R E F E R E N C E
 U T I L I T Y _ E N C R Y P T T A B L E S T R I N G ()

Utility_EncryptTableString()
Description The Utility_EncryptTableString() function encrypts a string using the
same method that Dexterity uses when storing encrypted strings in tables.

Syntax Utility_EncryptTableString(source_string)

Parameters • source_string – The string to be encrypted.

Return value A string containing the value in encrypted format.

Examples The following example encrypts the string “Steve”.

local string encrypted_result;

encrypted_result = Utility_EncryptTableString("Steve");

FUNCTION LIBRARY REFERENCE 703

U T I L I T Y _ L A U N C H U R L ( )

Utility_LaunchUrl()
Description The Utility_LaunchUrl() function opens a web browser and displays the
content of the specified URL.

Syntax Utility_LaunchUrl(URL)

Parameters • URL – A string specifying the complete URL to launch.

Return value None

Examples The following example displays the Microsoft web site in a browser
window.

Utility_LaunchUrl("http://www.microsoft.com");

704 F U N C T I O N L I B R A R Y R E F E R E N C E
 U T I L I T Y _ L O A D D L L ()

Utility_LoadDLL()
Description The Utility_LoadDLL() function loads the specified DLL into memory. The
DLL remains in memory until it is unloaded or the application is closed.

Syntax Utility_LoadDLL(DLL_name)

Parameters • DLL_name – A string specifying the name of the DLL to load into memory.
The DLL must be in the current directory, or in a directory included in the
PATH variable for the system.

Return value A long integer containing the handle to the DLL. You must save this value
to use when unloading the DLL from memory.

Comments You will use the Utility_LoadDLL() function when a DLL must maintain
state information between calls. Use this function to load the DLL into
memory, make the necessary calls, and then use the Utility_UnloadDLL()
function to remove the DLL from memory.

Examples The following example uses the Crystal Print Engine (CRPE32.DLL) to
print a report. The DLL is loaded into memory, and several calls are issued
to print the report. Then the DLL is unloaded from memory.

local long handle;

local long result;
local long long_zero = 0;
local long long_true = 1;
local integer err_code;
local integer print_job;

{Load the DLL into memory}

handle = Utility_LoadDLL("CRPE32.DLL");

{Print the report}

call 'PEOpenEngine@CRPE32.DLL', result;
call 'PEOpenPrintJob@CRPE32.DLL', print_job, "C:\RESM\Sellers.rpt";
call 'PEGetErrorCode@CRPE32.DLL', err_code, print_job;
call 'PEOutputToWindow@CRPE32.DLL', result, print_job, "Sellers",
➥ 1, 1, 994, 695, long_zero, long_zero;
call 'PEStartPrintJob@CRPE32.DLL', result, print_job, long_true;

{Wait until the user is finished with the report}

warning "Click OK when finished with the report.";

FUNCTION LIBRARY REFERENCE 705

U T I L I T Y _ L O A D D L L ( )

call 'PEClosePrintJob@CRPE32.DLL', result, print_job;

call 'PECloseEngine@CRPE32.DLL', result;

{Unload the DLL from memory.}

Utility_UnloadDLL(handle);

Related items Commands

Utility_UnloadDLL()

Additional information
Chapter 22, “Dynamic Link Libraries,” in Volume 2 of the Dexterity Programmer’s Guide

706 F U N C T I O N L I B R A R Y R E F E R E N C E
 U T I L I T Y _ S U B S T I T U T E T O K E N S ()

Utility_SubstituteTokens()
Description The Utility_SubstituteTokens() function replaces product tokens in a
string with the corresponding product names.

Syntax Utility_SubstituteTokens(string)

Parameters • string – The string in which tokens will be substituted.

Return value A string in which product tokens have been substituted.

Comments Rather than hard-coding product names in strings, we recommend that you
use tokens to represent product names. The token to indicate the product
name in a string is @PRODprodID@ where prodID is the product ID of the
product whose name you want to include in the message. The product
name will be read automatically from the launch file.

If the token specifies a product for which a product name cannot be found,
the string [unknown] is substituted.

Examples The following example replaces the product tokens in a string with the
corresponding product names, and then the string is used to display a
message.

local string message_text;

message_text = "The current product is @PROD3333@.";

message_text = Utility_SubstituteTokens(message_text);
warning message_text;

FUNCTION LIBRARY REFERENCE 707

U T I L I T Y _ U N L O A D D L L ()

Utility_UnloadDLL()
Description The Utility_UnloadDLL() function removes the specified DLL from
memory.

Syntax Utility_UnloadDLL(handle)

Parameters • handle – A long integer that is the handle of the DLL to unload. This is the
value that was returned from the Utility_LoadDLL() function.

Return value None

Comments You will use the Utility_LoadDLL() function when a DLL must maintain
state information between calls. Use this function to load the DLL into
memory, make the necessary calls, and then use the Utility_UnloadDLL()
function to remove the DLL from memory.

Examples Refer to the example for Utility_LoadDLL()

.
Related items Commands
Utility_LoadDLL()

Additional information
Chapter 22, “Dynamic Link Libraries,” in Volume 2 of the Dexterity Programmer’s Guide

708 F U N C T I O N L I B R A R Y R E F E R E N C E
 Window function library
Refer to Chapter 11, Use the functions in this library to manipulate window resources in your
“Windows,” in Volume dictionary. Most of these functions deal with window titles and window
1 of the Dexterity names. A window title is the string that appears at the top of a window when
Programmer’s Guide it’s displayed in test mode or at runtime. A window’s name is the string
for more information. that’s used to refer to the window in sanScript.

This library includes the following functions:

• Window_ForceRedraw()
• Window_GetMainWindowTitle()
• Window_GetPosition()
• Window_GetRibbonCommandTag()
• Window_GetSize()
• Window_GetState()
• Window_GetTitle()
• Window_GetTitleByProduct()
• Window_PullFocus()
• Window_ScrollScrollingWindow()
• Window_SetBaseSize()
• Window_SetLineMode()
• Window_SetState()

FUNCTION LIBRARY REFERENCE 709

W I N D O W _ F O R C E R E D R A W ( )

Window_ForceRedraw()
Description The Window_ForceRedraw() function forces a window to be redrawn. Its
primary use is to redraw a progress control window when it is first opened.

Syntax Window_ForceRedraw(window window_name)

Parameters • window window_name – The name of the window to be redrawn.

Return value The boolean value true.

Comments During normal processing, a newly-opened window is not drawn until all
foreground scripts have finished processing. This function redraws the
window immediately after it is executed. Thus, it forces the window to be
redisplayed, even while foreground script processing is occurring.

Typically once a window has been drawn, any set statements used to
update window fields will automatically redraw the window. Thus, it is
usually necessary to call the Window_ForceRedraw() function only once
when the window is opened, rather than each time the window is updated.

Avoid setting the BackColor property for fields to Transparent. These fields are not
updated automatically by the set statement. If you use fields that have the
BackColor property set to Transparent, you must use Window_ForceRedraw()
each time these fields are changed in order for the changes to be displayed.

710 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ F O R C E R E D R A W ()

Examples In the following example, Window_ForceRedraw() forces the

Progress_Window to be drawn when it is first opened, even though no idle
time is available. A procedure named Progress_Control (shown following
this script) is then called in a while do...end while loop and will update
window fields for each record read from the table buffer using the change
first and change next statements:

local integer l_count, l_number_of_records, l_index;

local string l_table_name;
local boolean l_boolean;

{Set local variables.}

l_count = 1;
l_table_name = "Inventory Data";
{Return the total number of records.}
l_number_of_records = countrecords(table Inventory_Data);
l_index = 1;
{Open the progress control.}
open form Progress_Control;
{Force the Progress_Control window to be drawn.}
l_boolean = Window_ForceRedraw(window Progress_Window of form
➥ Progress_Control);
{Read the first record in the table.}
change first table Inventory_Data by Inventory_Data_Key1;

{Complete the while loop for the procedure.}

while err() <> EOF do
call Progress_Control, l_table_name, 'Part Number' of table
➥ Inventory_Data, l_count, l_number_of_records;
release table Inventory_Data;
{Read next record in table.}
change next table Inventory_Data by Inventory_Data_Key1;
{Increment counter.}
l_count = l_count + 1;
end while;
close form Progress_Control;

FUNCTION LIBRARY REFERENCE 711

W I N D O W _ F O R C E R E D R A W ( )

The following procedure updates window fields in the Progress_Window

as a record is read from the Inventory_Data table. When this procedure is
called, the window will display the table and record being processed and
the percentage completed.

If you’re developing in the Dynamics.dic dictionary, a procedure named

Progress_Control will display the table name, the record processed, and the
percentage completed in the Progress_Control form.

in string l_Table_name;
in string l_Record;
in long l_Current_Records;
in long l_Total_Records;

local integer l_index;

if isopen(form Progress_Control) then

if l_Table_name <> '(L) Table_Processed' of window
➥ Progress_Window of form Progress_Control then
'(L) Table_Processed' of window Progress_Window of form
➥ Progress_Control = substring(l_Table_name, 1, 45);
end if;
'(L) Record_Processed' of window Progress_Window of form
➥ Progress_Control = substring(l_Record, 1, 45);
if l_Current_Records > l_Total_Records then
'(L) Percentage_Complete' of window Progress_Window of form
➥ Progress_Control to 100;
else
{Divide by the number of records returned in the countrecords
function to calculate a % complete.}
'(L) Percentage_Complete' of window Progress_Window of form
➥ Progress_Control = (l_Current_Records*1.0/l_Total_Records)
➥ *100.0;
end if;
end if;

712 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ G E T M A I N W I N D O W T I T L E ()

Window_GetMainWindowTitle()
Description The Window_GetMainWindowTitle() function returns the window title of
a form’s main window.

Syntax Window_GetMainWindowTitle(prod_ID, form_name)

Parameters • prod_ID – An integer representing the product ID of the dictionary

containing the form for which you wish to retrieve the main window’s title.

• form_name – A string containing the name of the form for which you wish to
retrieve the main window’s title.

Return value String

Comments A window’s title is the string that appears in the window’s title bar in test
mode or at runtime. The title is specified in the window’s Title property.

If you are in tools mode, or have yet to add product information to your
dictionary, the product ID for your dictionary will be zero. The product ID
for Dynamics.dic is always zero.

This function returns the title of the first window listed for the form in the
Form Definition window. This is also referred to as the form’s parent, or
main window. A main window will open first when the form opens.

Examples The following example returns the window title of a form’s main window
to a local string field. The form is located in a dictionary with the product
ID 3333.

{Return the title of the Lead_Maintenance form's main window.}

'(L) Window Title' = Window_GetMainWindowTitle(3333,
➥ "Lead_Maintenance");

Related items Commands

Window_GetTitle(), Window_GetTitleByProduct()

FUNCTION LIBRARY REFERENCE 713

W I N D O W _ G E T P O S I T I O N ( )

Window_GetPosition()
Description The Window_GetPosition() function returns the current coordinates of the
named window’s top left corner.

Syntax Window_GetPosition(window window_name, h_position, v_position)

Parameters • window window_name – The name of the window for which you wish to
retrieve a position.

• h_position – An integer field or variable to which the specified window’s

horizontal coordinate is returned.

• v_position – An integer field or variable to which the specified window’s

vertical coordinate is returned.

Return value The boolean value true.

Comments The coordinates are expressed in pixels. The coordinates 0,0 specify the
upper left corner of the screen. If a toolbar is present, the vertical position 0
is located below the bottom of the toolbar.

If the specified window is closed, the h_position and v_position parameters

are set to 0.

Use the isopen() function to see if the specified window is open before using this
function. Then, you’ll know that the 0,0 coordinates returned by this function
represent the location of the window, not the fact that the window is closed.

Examples The following example returns the coordinates of the Customer Data
window’s current location.

local boolean return_value;

return_value = Window_GetPosition(window 'Customer Data' of form

➥ Customer_Info, '(L) horizontal_coord', '(L) vertical_coord');

Related items Commands

move window, resize window, Window_GetSize()

714 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ G E T R I B B O N C O M M A N D T A G ()

Window_GetRibbonCommandTag()
Description The Window_GetRibbonCommandTag() function retrieves the command
tag for the root command list that defines the ribbon for a window.

Syntax Window_GetRibbonCommandTag(window window_name)

Parameters • window window_name – The window for which the ribbon command tag is
being retrieved.

Return value An integer containing the command tag. If the window is not open, or the
ribbon has not been created for the window, the value 0 is returned.

Examples The following example uses the Window_GetRibbonCommandTag()

function to retrieve the command list used for the ribbon the Customer
Maintenance window. The command list for the last group in the ribbon is
retrieved, and the About command is added to that group.

local integer ribbon_tag;

local integer help_group;
local integer about_tag;
local integer count;

{Get the tag for the ribbon command list}

ribbon_tag = Window_GetRibbonCommandTag(window
➥ RM_Customer_Maintenance of form RM_Customer_Maintenance);

{Get the last group in the ribbon}

count = CommandList_NumCommands(ribbon_tag);
help_group = CommandList_GetCommandByPosition(ribbon_tag, count);

{Get the tag for the About command}

about_tag = Command_GetTag(command cmdAboutBox);

{Add the command to the Help group}

CommandList_Add(help_group, about_tag);

FUNCTION LIBRARY REFERENCE 715

W I N D O W _ G E T S I Z E ( )

Window_GetSize()
Description The Window_GetSize() function returns the current height and width, in
pixels, of a specified window.

Syntax Window_GetSize(window window_name, width, height)

Parameters • window window_name – The name of the window for which you wish to
retrieve the height and width.

• width – An integer field or variable to which the specified window’s width

is returned.

• height – An integer field or variable to which the specified window’s height

is returned.

Return value The boolean value true.

Comments The height and width are expressed in pixels. If the specified window is
closed, the width and height parameters are set to 0.

Examples The following example returns the current width and height of the Sales
Data window.

local boolean return_value;

return_value = Window_GetSize(window Sales_Data of form Sales_Data,

➥ '(L) width_value', '(L) height_value');

Related items Commands

move window, resize window, Window_GetPosition()

716 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ G E T S T A T E ()

Window_GetState()
Description The Window_GetState() function retrieves the visual state for a window.

Syntax Window_GetState(window window_name)

Parameters • window window_name – The window whose state is being retrieved.

Return value An integer indicating the window state. The value corresponds to one of the
following constants:

Constant
WINDOW_STATE_MAXIMIZED
WINDOW_STATE_MINIMIZED
WINDOW_STATE_NORMAL
WINDOW_STATE_MODAL
WINDOW_STATE_UNKNOWN
Description
The window is in the maximized state.
The window is in the minimized state.
The window is in the normal state.
The window is modal.
The window is in an unknown state.

Examples The following example retrieves the state of the Buyers window.

local integer window_state;

window_state = Window_GetState(window Buyers);

Related items Commands

Window_SetState()

FUNCTION LIBRARY REFERENCE 717

W I N D O W _ G E T T I T L E ( )

Window_GetTitle()
Description The Window_GetTitle() function returns the title of the specified window.

Syntax Window_GetTitle(window window_name)

Parameters • window window_name – The name of the window for which you want to
retrieve the title.

Return value String

Comments A window title is the string that appears in the window’s title bar in test
mode or at runtime. The title is specified in the window’s Title property.

This function will return the window title of a window in the current
dictionary only. To retrieve the name of a window in another dictionary, use
the Window_GetTitleByProduct() function.

Examples The following example displays a warning message if the user doesn’t enter
all required fields when attempting to save a record. The
Window_GetTitle() function is used to retrieve the window title for use in
the warning dialog.

local string l_window_title;

if required (form Items) then

copy to table Item_Table;
save table Item_Table;
restart form;
else
l_window_title = Window_GetTitle(window Item_Maintenance of form
➥ Items);
warning "Not all required fields have been entered in the "
➥ + l_window_title + " window.";
end if;

Related items Commands

Window_GetMainWindowTitle(), Window_GetTitleByProduct()

718 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ G E T T I T L E B Y P R O D U C T ()

Window_GetTitleByProduct()
Description The Window_GetTitleByProduct() function returns the title of a window
in a specified form in a specified dictionary. If the window title has been
modified using the Modifier, the revised window title is not returned.

Syntax Window_GetTitleByProduct(prod_ID, form_name, window_name)

Parameters • prod_ID – An integer specifying the product ID of the dictionary containing

the window for which you wish to retrieve the title.

• form_name – A string containing the name of the form containing the

window for which you wish to retrieve the title.

• window_name – The string containing the name of the window whose title
you want to retrieve.

Return value String

Comments If you are in tools mode, or have yet to add product information to your
dictionary, the product ID for your dictionary will be zero. The product ID
for Dynamics.dic is always zero.

Examples The following example returns a window title to the local variable
l_win_title. The product ID is represented by the constant
INVENT_PRODID.

local string l_win_title;

l_win_title = Window_GetTitleByProduct(INVENT_PRODID,
➥ '(L) form_name', '(L) window_name');
'(L) Window_Title' of window Title_Test = l_win_title;

Related items Commands

Window_GetMainWindowTitle(), Window_GetTitle()

FUNCTION LIBRARY REFERENCE 719

W I N D O W _ P U L L F O C U S ( )

Window_PullFocus()
Description The Window_PullFocus() function pulls the focus from the specified
window. Any pending change or post scripts for the currently-focused field
will be run.

Syntax Window_PullFocus(window window_name)

Parameters • window window_name – The name of the window from which you want to
pull the focus.

Return value The boolean value true.

Comments The Window_PullFocus() function is typically used in the processing

procedure for focus triggers. In certain instances, the pending change and
post scripts for the currently-focused field need to be run so the processing
procedure can perform the necessary actions.

After the focus has been pulled from the window, no item in the window
will be focused.

Examples The following example pulls the focus from the Houses window of the
Houses form.

local boolean result;

result = Window_PullFocus(window Houses of form Houses);

720 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ S C R O L L S C R O L L I N G W I N D O W ()

Window_ScrollScrollingWindow()
Description The Window_ScrollScrollingWindow() function causes the contents of a
scrolling window to scroll to the next or previous record. It is intended for
use within single-line scrolling windows.

Syntax Window_ScrollScrollingWindow(window window_name, scroll_type)

Parameters • window window_name – The scrolling window to be scrolled.

• scroll_type – An integer indicating how the scrolling window should be

scrolled. Use one of the following constants:

Constant Description
SCROLLTYPE_NEXT Scrolls to the next record.
SCROLLTYPE_PREV Scrolls to the previous record.

Return value An integer corresponding to one of the following constants:

Constant Description
FOCUS_OK The scrolling window was scrolled successfully.
FOCUS_DENIED The scrolling window could not be scrolled because a line
was already locked in the scrolling window.
FOCUS_DIVERTED The scrolling window could not be scrolled because a
focus statement prevented the focus from remaining on
the same field in the new line to be displayed.
FOCUS_RESTART The scrolling window could not be scrolled because a
restart field statement prevented the focus from
moving.
FOCUS_NOEXIST The scrolling window could not be scrolled because the
record to be displayed has been deleted.
FOCUS_NOEXIST_EOF The scrolling window could not be scrolled because the
end of the table was reached.
FOCUS_NOEXIST_SOF The scrolling window could not be scrolled because the
beginning of the table was reached.
FOCUS_NOT_IN_SWIN Attempted to call the function from outside of the
scrolling window.

FUNCTION LIBRARY REFERENCE 721

W I N D O W _ S C R O L L S C R O L L I N G W I N D O W ( )

Comments A single-line scrolling window is created when the small line item or the
big line item is set to use the entire scrolling window area. When used in
this way, a scrolling window displays only one record of information at a
time. Push buttons in the scrolling window are typically used to move to
the next or previous records. The change scripts attached to these push
buttons use the Window_ScrollScrollingWindow() function to perform the
scrolling.

When the Window_ScrollScrollingWindow() function is used to scroll the

scrolling window, it attempts to maintain the focus on the same field that
was focused in the previous line.

This function cannot be used in a change script for a push button that has the
Hyperspace property set to true.

Examples The following example is the change script of the Previous button in a
single-line scrolling window. It attempts to display the previous record
from the table linked to the scrolling window.

local integer result;

result = Window_ScrollScrollingWindow(window CustomerListScroll,

➥ SCROLLTYPE_PREV);
if (result <> FOCUS_OK) then
if result = FOCUS_NOEXIST_SOF then
beep ERRORSOUND;
else
warning "Record could not be displayed";
end if;
end if;

722 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ S E T B A S E S I Z E ()

Window_SetBaseSize()
Description The Window_SetBaseSize() function sets the size of the window without
resizing any of the controls in the window.

Syntax Window_SetBaseSize(window name, h-size, v-size)

Parameters • name – The name of the window to be resized.

• h-size – An integer indicating the new horizontal width of the window,

measured in pixels.

• v-size – An integer indicating the new vertical height of the window,

measured in pixels.

Return value A boolean. True indicates the window was resized, while false indicates it
was not.

Comments If one of the dimensions is to remain unchanged, use -1 as the parameter. If

the window size is reduced, fields located outside the new size may no
longer be accessible.

The Window_SetBaseSize() function will resize the window, regardless of

how the Resizeable property for the window is set. To resize the window
and also have the controls in the window resized, use the resize window
statement.

Examples In the following example, the base size of the Customer Maintenance
window is resized to 250 pixels wide, while the height is unchanged.

local boolean result;

result = Window_SetBaseSize(window 'Customer Maintenance', 250, -1);

Related items Commands

resize window

FUNCTION LIBRARY REFERENCE 723

W I N D O W _ S E T L I N E M O D E ()

Window_SetLineMode()
Description The Window_SetLineMode() function changes the window type of the
scrolling window.

Syntax Window_SetLineMode(window window_name, mode)

Parameters • window window_name – The scrolling window whose type will be changed.

• mode – An integer specifying the mode to use. The value corresponds to one
of the following constants:

Constant Mode
LINEMODE_BROWSE_ONLY Browse-only scrolling window
LINEMODE_EDITABLE Editable scrolling window
LINEMODE_ADDS_ALLOWED Adds-allowed scrolling window

Return value A boolean. True indicates the scrolling window mode was changed, while
false indicates it was not.

Comments To ensure the scrolling window is in a consistent state, use the fill window
statement to refill the scrolling window after you change the window type.

Examples The following example uses the Window_SetLineMode function to change

the window type of the Sellers_Scroll scrolling window to editable.

local boolean result;

result = Window_SetLineMode(window Sellers_Scroll,LINEMODE_EDITABLE);

fill window Sellers_Scroll;

724 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W _ S E T S T A T E ()

Window_SetState()
Description The Window_SetState() function sets the visual state for a window.

Syntax Window_SetState(window window_name, state)

Parameters • window window_name – The window whose state is being set.

• state – An integer indicating the window state. The value corresponds to

one of the following constants:

Constant
WINDOW_STATE_MAXIMIZED
WINDOW_STATE_MINIMIZED
WINDOW_STATE_NORMAL
Description
Sets the window to its maximized state.
Sets the window to its minimized state.
Restores the window from the minimized
or maximized state.

Return value A boolean. True indicates the window state was set, while false indicates it
was not.

Examples The following example sets the Buyers window to the minimized state.

local boolean result;

result = Window_SetState(window Buyers, WINDOW_STATE_MINIMIZED);

Related items Commands

Window_GetState()

FUNCTION LIBRARY REFERENCE 725

726 F U N C T I O N L I B R A R Y R E F E R E N C E
Window group function library
Use the functions in this library to work with window groups for a form.
This library contains the following functions:

• WindowGroup_AddWindow()
• WindowGroup_SetBooleanProperty()
• WindowGroup_SetPosition()
• WindowGroup_SetSize()
• WindowGroup_SetState()
• WindowGroup_SetStringProperty()

FUNCTION LIBRARY REFERENCE 727

 W I N D O W G R O U P _ A D D W I N D O W ()

WindowGroup_AddWindow()
Description The WindowGroup_AddWindow() function adds a window to the
specified window group.

Syntax WindowGroup_AddWindow(window_group_ID, window, command_tag

{,visual_position})

Parameters • window_group_ID – A long integer specifying the window group to which

you are adding a window.

• window – The window that is being added to the window group.

• command_tag – An integer specifying the tag for the command that will be
run when the window in the group is activated.

• visual_position – An optional integer that specifies the visual position of the

window in the group. The value 1 specifies the first position. The value 0
specifies that the window will appear at the end of the group. This is the
default value if none is supplied.

Return value A boolean. The value true indicates the window was added successfully,
while false indicates that it was not.

Examples The following example is the trigger processing procedure that runs in
response to the SetupWindowGroup procedure for the
RM_Customer_Maintenance form. The trigger processing procedure
retrieves the window group for the Customer Maintenance window. It uses
the WindowGroup_AddWindow() function to add the Contact History
window to the end of the window group.
local long windowGroupId;
local integer tag;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

{Get the tag for the command that runs when the new tab is clicked.}
tag = Command_GetTag(command 'IG_Contact_History_Tab' of form
➥ 'Command_IG_Sample');

{Add the window to the end of the window group.}

WindowGroup_AddWindow(windowGroupId, window 'Contact History' of form
➥ 'IG_Contact_History', tag, 0);

728 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W G R O U P _ S E T B O O L EA N P R O P ER TY ()

WindowGroup_SetBooleanProperty()
Description The WindowGroup_SetBooleanProperty() function sets the value of a
boolean property for the specified window group.

Syntax WindowGroup_SetBooleanProperty(window_group_ID, property, value)

Parameters • window_group_ID – A long integer specifying the window group for which
a boolean property is being set.

• property – An integer constant indicating the property to be set. The value

corresponds to one of the following constants:

Constant
WG_PROP_HONOR_WINDOW_SIZE
WG_PROP_CAN_MINIMIZE
WG_PROP_CAN_USER_RESIZE
WG_PROP_HAS_CLOSE_BOX
WG_PROP_IS_MODAL
Description
Specifies whether the window group will
automatically resize based on the size of the
window currently being displayed by the
window group. True indicates the window
group will automatically resize. False indicates
it will not.
Specifies whether the window group can be
minimized.
Specifies whether the user can resize the
window group.
Specifies whether the window group displays
the close box.
Specifies whether the window group displays
as a modal window.

• value – A boolean indicating how to set the property. Refer to the preceding
table.

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Examples The following example prevents the user from being able to resize the
window group for the Customer Maintenance form.

local long windowGroupId;

local boolean result;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

FUNCTION LIBRARY REFERENCE 729

 W IN D O WG R O U P_ S E T B O O L EA N P R O P E R TY ()

{Prevent the user from resizing the window group.}

result = WindowGroup_SetBooleanProperty(windowGroupId,
➥ WG_PROP_CAN_USER_RESIZE, false);

730 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N D O W G R O U P_ S ET P O S I TI O N ()

WindowGroup_SetPosition()
Description The WindowGroup_SetPosition() function changes the position of a
window group.

Syntax WindowGroup_SetPosition(window_group_ID, h-position, v-position)

Parameters • window_group_ID – A long integer specifying the window group to be

moved.

• h-position – The new horizontal position of the upper left corner of the
window group. This value is measured from the left edge of the screen.

• v-position – The new vertical position of the upper left corner of the window
group. This value is measured from the top edge of the screen.

Return value A boolean indicating whether the window group position was set. True
indicates the position was set, while false indicates it was not.

Comments The positions are expressed in pixels. The coordinates 0,0 specify the upper
left corner of the screen.

To leave one of the coordinates unchanged, use -1 as the parameter.

Examples The following example sets the position of the window group for the
Customer Maintenance form.

local long windowGroupId;

local boolean result;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

{Set the position for the window group.}

result = WindowGroup_SetPosition(windowGroupId, 25, 25);

FUNCTION LIBRARY REFERENCE 731

 WI N DO W G R O U P _ S E T S IZ E ()

WindowGroup_SetSize()
Description The WindowGroup_SetSize() function changes the size of a window
group.

Syntax WindowGroup_SetSize(window_group_ID, h-size, v-size)

Parameters • window_group_ID – A long integer specifying the window group to be

resized.

• h-size – An integer representing the new horizontal width of the window

group, measured in pixels.

• v-size – An integer representing the new vertical height of the window

group, measured in pixels.

Return value A boolean indicating whether the window group size was set. True
indicates the size was set, while false indicates it was not.

Comments This function doesn’t change the top, left position of the window group. It
only changes the overall horizontal or vertical size. If the window group
size is reduced, fields located outside of the new size may no longer be
accessible.

Examples The following example resizes the window group for the Customer
Maintenance form. The width is set to 400, and the height is set to 600.

local long windowGroupId;

local boolean result;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

{Set the size for the window group.}

result = WindowGroup_SetPosition(windowGroupId, 400, 600);

732 F U N C T I O N L I B R A R Y R E F E R E N C E
 WI N DO W G R O U P _ S E T S T AT E ()

WindowGroup_SetState()
Description The WindowGroup_SetState() function sets the visual state for a window
group.

Syntax WindowGroup_SetState(window_group_ID, state)

Parameters • window_group_ID – A long integer specifying the window group for which
the visual state is being set.

• state – An integer constant indicating the window state. The value

corresponds to one of the following constants:

Constant
WG_STATE_MAXIMIZED
WG_STATE_MINIMIZED
WG_STATE_NORMAL
Description
Sets the window group to its maximized state.
Sets the window group to its minimized state.
Restores the window group from the
minimized or maximized state.

Return value A boolean. True indicates the window group state was set, while false
indicates it was not.

Examples The following example minimizes the window group for the Customer
Maintenance form.

local long windowGroupId;

local boolean result;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

{Minimize the window group.}

result = WindowGroup_SetState(windowGroupId, WG_STATE_MINIMIZED);

FUNCTION LIBRARY REFERENCE 733

 W I N D O W G R O U P _ S E TS TR IN G P R O P E R TY ()

WindowGroup_SetStringProperty()
Description The WindowGroup_SetStringProperty() function sets the value of a string
property for the specified window group.

Syntax WindowGroup_SetStringProperty(window_group_ID, property, value)

Parameters • window_group_ID – A long integer specifying the window group for which
a string property is being set.

• property – An integer constant indicating the property to be set. The value

corresponds to one of the following constants:

Constant Description
WG_PROP_INTERNAL_NAME An internal string used to identify the window
group.
WG_PROP_TITLE A string that is displayed in the title bar for the
ribbon group.

• value – A string indicating how to set the property. Refer to the preceding
table.

Return value A boolean indicating whether the property was set. True indicates the
property was set, while false indicates it was not.

Examples The following example sets the title of the window group for the Customer
Maintenance form.

local long windowGroupId;

local boolean result;

{Get the window group ID for the RM_Customer_Maintenance form.}

Form_GetWindowGroup(form RM_Customer_Maintenance, windowGroupId);

{Set the title of the window group.}

result = WindowGroup_SetStringProperty(windowGroupId, WG_PROP_TITLE,
➥ "Customers");

734 F U N C T I O N L I B R A R Y R E F E R E N C E
 WinHelp function library
Refer to Chapter 7,
“Windows Help,” and
Chapter 8, “HTML
Help,” in the Dexterity
Stand-alone Applica-
tion Guide for informa-
tion about online help
support for Dexterity
applications.
Use the functions in this library when implementing Windows help or
HTML Help for Dexterity applications. They allow you to find out the type
of help requested, find the correct topic in the help file, display a help topic,
and run help macros.
This library contains the following functions:
• WinHelp_ALinkLookup()
• WinHelp_GetCurWindow()
• WinHelp_GetFieldContextNumber()
• WinHelp_GetHelpType()
• WinHelp_GetWindowContextNumber()
• WinHelp_InvokeHelp()
• WinHelp_LaunchUrl()
• WinHelp_RegisterHelpProcedure()
• WinHelp_RunHelpMacro()
• WinHelp_Search()
FUNCTION LIBRARY REFERENCE 735
W I N H E L P _ A L I N K L O O K U P ()

WinHelp_ALinkLookup()
Description The WinHelp_ALinkLookup() function starts the help engine, indicating
the help file to be used, and displays the topic corresponding to the ALink
(associative link) value specified.

Syntax WinHelp_ALinkLookup(help_file, ALink)

Parameters • help_file – A string containing the name and complete path to the help file to
be accessed. The path is in generic format.

• ALink – A string containing the ALink value that indicates which help topic
to display.

Return value An integer indicating the status. If 0 is returned, no error occurred. If any
other value is returned, an error occurred while invoking help.

Comments Associative links are used to identify topics in HTML Help files. They are
useful in cases where the context number or HTML filename associated
with the topic might change. The ALink can remain constant, allowing the
topic to be found.

To display a topic using its ALink, you must know the ALink value that
was defined for the topic in the help file.

Examples The following example displays the topic from the Dexterity help file that
has the ALink value “close window”. This is the help topic for the close
window statement.

local integer result;

{Display the topic with the specific ALink value.}

result = WinHelp_ALinkLookup(":C:Dexterity/Dex.chm", "close window");
if result <> 0 then
error "An error occurred while attempting to access help.";
end if;

736 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ G E T C U R W I N D O W ()

WinHelp_GetCurWindow()
Description The WinHelp_GetCurWindow() function returns the resource ID of the
currently-active window.

Syntax WinHelp_GetCurWindow()

Parameters • None

Return value An integer containing the resource ID of the current window.

Comments This function is typically used in the help processing procedure script for
applications that integrate with Microsoft Dynamics GP. When help is
accessed for a window or window field, the WinHelp_GetCurWindow()
function is used to find out whether help was requested for an alternate
Microsoft Dynamics GP window or a third-party window. If the resource
ID returned is below 20,000, then the currently-active window is a
Microsoft Dynamics GP window. If the resource ID returned is 22,000 or
greater, the window is a third-party window.

Examples The following example retrieves the resource ID for the current window.

local integer res_ID;

res_ID = WinHelp_GetCurWindow();

FUNCTION LIBRARY REFERENCE 737

W I N H E L P _ G E T F I E L D C O N T E X T N U M B E R ()

WinHelp_GetFieldContextNumber()
Description The WinHelp_GetFieldContextNumber() function returns the context
number (a long integer) for the currently-selected field.

Syntax WinHelp_GetFieldContextNumber()

Parameters • None

Return value Long integer

Comments This function is typically used in the help processing procedure script. It
returns the context number for the window field for which help was
requested.

Examples The following example handles requests for field-level help. The context
number for the current field is returned and passed to the help engine.

local long context_number;

local integer result;

{Get the context number for the field chosen.}

context_number = WinHelp_GetFieldContextNumber();

{Call the help engine, displaying help for the field.}

result = WinHelp_InvokeHelp(":C:RESM/RESM.CHM", HELP_CMD_CONTEXT,
➥ context_number);

Related items Commands

WinHelp_GetWindowContextNumber(), WinHelp_InvokeHelp()

738 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ G E T H E L P T Y P E ()

WinHelp_GetHelpType()
Description The WinHelp_GetHelpType() function returns an integer indicating the
type of help the user requested.

Syntax WinHelp_GetHelpType()

Parameters • None

Return value An integer corresponding to one the following constants.

Constant Help type

HELP_TYPE_CONTENTS Display help contents
HELP_TYPE_SEARCH Search
HELP_TYPE_HELP_KEY Help key processing (F1 key)
HELP_TYPE_WHATS_THIS_WIN Window-level help
HELP_TYPE_WHATS_THIS_FIELD Field-level help
HELP_TYPE_WHATS_THIS_MODE “What's this?” mode
HELP_TYPE_DIALOG_HELP Modal dialog help

Comments This function is typically used in the help processing procedure script to
find out the type of help the user requested.

Examples The following example is part of the help processing procedure script for an
application. The WinHelp_GetHelpType() function is used to indicate the
type of help requested by the user.

local integer help_type;

{Get the help_type the user requested.}

help_type = WinHelp_GetHelpType();

FUNCTION LIBRARY REFERENCE 739

W I N H E L P _ G E T W I N D O W C O N T E X T N U M B E R ( )

WinHelp_GetWindowContextNumber()
Description The WinHelp_GetWindowContextNumber() function returns the context
number (a long integer) for the current (front-most) window.

Syntax WinHelp_GetWindowContextNumber()

Parameters • None

Return value Long integer

Comments This function is typically used in the help processing procedure script. It
returns the context number for the current window. If your application
supports only window-level help, this function can be used to retrieve the
context number for the current window when help is requested using the
keyboard or “What’s this?” mode.

Examples The following example handles requests for window-level help. The
context number for the current window is returned and passed to the help
engine.

local long context_number;

local integer result;

{Get the context number for the current window.}

context_number = WinHelp_GetWindowContextNumber();

{Call the help engine, displaying help for the window.}

result = WinHelp_InvokeHelp(":C:RESM/RESM.CHM", HELP_CMD_CONTEXT,
➥ context_number);

Related items Commands

WinHelp_GetFieldContextNumber(), WinHelp_InvokeHelp()

740 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ I N V O K E H E L P ()

WinHelp_InvokeHelp()
Description The WinHelp_InvokeHelp() function starts the help engine, indicating the
help file, help command, and context number (a long integer) to be used.

Syntax WinHelp_InvokeHelp(help_file, help_command, context_number)

Parameters • help_file – A string containing the name and complete path to the help file to
be accessed. The path is in generic format.

• help_command – An integer indicating how help is to be invoked. The

integer corresponds to one of the following constants.

Constant
HELP_CMD_CONTENTS
HELP_CMD_CONTEXT
HELP_CMD_CONTEXTPOPUP
Command
Display help contents topic.
Display context-sensitive help in a
standard help window.
Display context-sensitive help in a pop-
up window. This is available only for
Windows Help.

• context_number – A long integer indicating which help topic to display. If

the help contents topic is being displayed, this parameter should be set to 0.

Return value An integer indicating the status. If 0 is returned, no error occurred. If any
other value is returned, an error occurred while invoking help.

Examples The following example displays help for the current window. The context
number for the current window is returned and help is invoked, displaying
the topic in a standard help window.

local long context_number;

local integer result;

{Get the context number for the current window.}

context_number = WinHelp_GetWindowContextNumber();
{Call the help engine, displaying help for the window.}
result = WinHelp_InvokeHelp(":C:RESM/RESM.CHM", HELP_CMD_CONTEXT,
➥ context_number);
if result <> 0 then
error "An error occurred while attempting to access help.";
end if;

FUNCTION LIBRARY REFERENCE 741

W I N H E L P _ I N V O K E H E L P ( )

The following example displays the Contents topic for the RESM.CHM help
file.

local integer result;

{Call the help engine, displaying the contents topic.}

result = WinHelp_InvokeHelp(":C:RESM/RESM.CHM", HELP_CMD_CONTENTS,0);
if result <> 0 then
error "An error occurred while attempting to access help.";
end if;

742 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ L A U N C H U R L ()

WinHelp_LaunchUrl()
Description The WinHelp_LaunchUrl() function launches help content for the
Microsoft Dynamics GP web client. The content is displayed in a new web
browser window.

Syntax WinHelp_LaunchUrl(url)

Parameters • url – A string that specifies the URL of the content to be displayed in a new
web browser window. The URL can be a complete URL or a partial URL.

Return value None

Comments If you are specifying a complete URL, the URL should begin with http:// or
https:// and contains the full path to the content to be displayed.

If you are specifying a relative URL, the relative URL should begin with a
forward slash (/) and provide the remaining path to the content after the
server name. The Microsoft Dynamics GP web client runtime will
automatically prepend the server name to the relative URL.

The content is displayed in new web browser window that has a special
name assigned to it. If this browser window is left open, subsequent calls to
the WinHelp_LaunchUrl() function will replace the content of this browser
window.

Examples The following is the IG_Help_Processing procedure for the sample

integrating application that is included with Dexterity. This help processing
procedure handles sample application help requests for both the desktop
client and the web client. The Runtime_GetClientType() function is used
to find out which type of client is requesting help.

The code in the second half of the procedure processes the help requests
that originate from the web client. The procedure uses the
WinHelp_GetHelpType() function to find out the type of help being being
requested.

The value of the WebClientHelpServer defaults file setting is retrieved. If

this setting contains a value, then a full URL is constructed. If this setting
does not contain a value, then a relative URL is constructed. The parts of the
URL are the “Help” folder, the “Develop” folder, and the base file that
displays the help content. For context-sensitive help, the “Context”
parameter is added to the query string for the URL. After the parts of the

FUNCTION LIBRARY REFERENCE 743

W I N H E L P _ L A U N C H U R L ( )

URL are assembled, the WinHelp_LaunchUrl() function displays the help

content. A typical relative URL will look like the following example:

/Help/Develop/Frameset.htm?Context=532480

For the sample help collection, the Frameset.htm file contains JavaScript
code that parses the Context parameter and displays the appropriate topic.

local integer help_type, result;

local long context_number;
local string help_path_and_file, url, server, help_folder, collection,
➥ base_file;

{Is help being processed on the Windows client or the Web client?}
if Runtime_GetClientType() = DEX_CLIENT_TYPE_STANDARD then

{Return the location of the current dictionary.}

help_path_and_file = Dict_GetPathname(2);

{Set the complete path to the help file.}

help_path_and_file = help_path_and_file + "DEVELOP.CHM";

{Get the help type for the current situation.}

help_type = WinHelp_GetHelpType();

case help_type
in [HELP_TYPE_WHATS_THIS_MODE, HELP_TYPE_HELP_KEY,
➥ HELP_TYPE_WHATS_THIS_WIN]
{Get the context number for the current window.}
context_number = WinHelp_GetWindowContextNumber();
{Call the help engine, displaying the help for the window.}
result = WinHelp_InvokeHelp(help_path_and_file,
➥ HELP_CMD_CONTEXT, context_number);
in [HELP_TYPE_DIALOG_HELP]
{Process the help for modal dialogs.}
{Get the context number for the item chosen.}
context_number = WinHelp_GetFieldContextNumber();
{Call the help engine, displaying help for the dialog.}
result = WinHelp_InvokeHelp(help_path_and_file,
➥ HELP_CMD_CONTEXT, context_number);
in [HELP_TYPE_CONTENTS]
{Invoke the Contents topic.}
result = WinHelp_InvokeHelp(help_path_and_file,

744 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ L A U N C H U R L ()

➥ HELP_CMD_CONTENTS, 0);
in [HELP_TYPE_SEARCH]
{Invoke the search engine.}
result = WinHelp_Search(help_path_and_file, "");
else
{Invoke the Contents topic.}
result = WinHelp_InvokeHelp(help_path_and_file,
➥ HELP_CMD_CONTENTS, 0);
end case;

else

{Get the help type for the current situation.}

help_type = WinHelp_GetHelpType();

{Retrieve the base URL of any web client help server.}

server = Defaults_Read("WebClientHelpServer");

{Specify the name of the help folder.}

help_folder = "Help";

{Specify the name of the help collection.}

collection = "Develop";

{Specify the name of the base file for the collection.}

base_file = "Frameset.htm";

{Build the base URL.}

url = server + "/" + help_folder + "/" + collection + "/" +
base_file;

case help_type
in [HELP_TYPE_WHATS_THIS_MODE, HELP_TYPE_HELP_KEY,
➥ HELP_TYPE_WHATS_THIS_WIN]
{Get the context number for the current window.}
context_number = WinHelp_GetWindowContextNumber();

{Call the help set, displaying the help for the window.}
url = url + "?Context=" + str(context_number);
WinHelp_LaunchUrl(url);

in [HELP_TYPE_CONTENTS]
{Invoke the Contents topic.}

FUNCTION LIBRARY REFERENCE 745

W I N H E L P _ L A U N C H U R L ( )

WinHelp_LaunchUrl(url);

else
{Invoke the Contents topic.}
WinHelp_LaunchUrl(url);
end case;

end if;

746 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ R E G I S T E R H E L P P R O C E D U R E ()

WinHelp_RegisterHelpProcedure()
Description The WinHelp_RegisterHelpProcedure() function indicates which
procedure script will be called when help is accessed.

Syntax WinHelp_RegisterHelpProcedure(script procedure_script)

Parameters • script procedure_script – The name of the procedure script to be called each
time help is accessed.

Return value An integer indicating the status. If 0 is returned, no error occurred. If any
other value is returned, an error occurred while registering the help
processing procedure.

Comments For stand-alone applications, the help processing procedure script is

registered in the Main Menu form pre script. For applications that integrate
with Microsoft Dynamics GP, the help processing procedure script is
registered in the Startup procedure script.

Examples The following example is part of the Main Menu pre script for the Real
Estate Sales manager. It registers the RESM_Help_Processing procedure
script as the help processing procedure script.

local integer result;

result = WinHelp_RegisterHelpProcedure(script RESM_Help_Processing);

if result <> 0 then
error "An error occurred. Unable to register help processing
➥ procedure.";
end if;

FUNCTION LIBRARY REFERENCE 747

W I N H E L P _ R U N H E L P M A C R O ( )

WinHelp_RunHelpMacro()
Description The WinHelp_RunHelpMacro() function specifies a help file and the help
macro or macros to run.

Syntax WinHelp_RunHelpMacro(help_file, macros)

Parameters • help_file – A string containing the name and complete path to the help file to
be accessed. The path is in generic format.

• macros – A string containing the names of the macro or macros to be run. If

more than one macro is to be run, the names of the macros must be
separated by semicolons.

Return value An integer indicating the status. If 0 is returned, no error occurred. If any
other value is returned, an error occurred while attempting to run the help
macro or macros.

Examples The following example uses the History help macro to display the viewing
history of the RESM.HLP help file.

local integer result;

result = WinHelp_RunHelpMacro(":C:RESM/RESM.HLP", "History()");

if result <> 0 then
error "An error occurred while attempting to run a macro.";
end if;

The following example uses two help macros to resize the help window and
display the contents topic. Notice that double quotation marks are used to
enclose one of the macro parameters in quotation marks.

local integer result;

result = WinHelp_RunHelpMacro(":C:RESM/RESM.HLP",
➥ "PositionWindow(0,0,512,512,1,""main""); Contents()");

748 F U N C T I O N L I B R A R Y R E F E R E N C E
 W I N H E L P _ S E A R C H ()

WinHelp_Search()
Description The WinHelp_Search() function starts the help engine and searches for the
specified keyword in the help file indicated.

Syntax WinHelp_Search(help_file, search_string)

Parameters • help_file – A string containing the name and complete path to the help file to
be searched. The path is in generic format.

• search_string – A string containing the keyword to be searched for. If you

want to display the Index tab without searching for a keyword, pass in an
empty string ("") as the search string.

Return value An integer indicating the status. If 0 is returned, no error occurred. If any
other value is returned, an error occurred while attempting to start the
search.

Comments If there is one exact match for the keyword in the help file, that help topic is
displayed. If there is more than one match, the Topics found dialog is
displayed listing the topics with the keyword. If there is no match, the
Index tab is displayed, allowing you to select a keyword from the list.

Examples The following example searches for the keyword “sellers” in the
RESM.CHM help file.

local integer result;

result = WinHelp_Search(":C:RESM/RESM.CHM", "sellers");

if result <> 0 then
error "An error occurred while attempting to search the help
➥ file.";
end if;

FUNCTION LIBRARY REFERENCE 749

750 F U N C T I O N L I B R A R Y R E F E R E N C E
Index
A boolean
About menu item, changing name 514
accelerator key, for commands 65, 76
Activity tracking function library 27-31
Activity_GetBackgroundStatus() 28
Activity_GetExitMode() 29
Activity_GetResourceName() 30
address
resolving e-mail address 389, 423
retrieving from user profile 411
address lists
adding addresses 372, 398
counting addresses 373, 399
creating 374, 400
destroying 375, 401
message addressing dialog 379,
381, 402, 403
removing addresses 378, 422
retrieving addresses 376, 405
ALinks, for HTML Help 736
applications
changing icons 516
changing name in title bar 514
returning path of from launch file
280
auto-complete
adding items 34
disabling 38
enabling 38
options 39
removing items 35, 36, 37
Auto-complete function library 33-39
AutoComplete_AddStringValue() 34
AutoComplete_RemoveAllData() 35
AutoComplete_RemoveFieldData() 36
AutoComplete_RemoveStringValue()
37
AutoComplete_SetMode() 38
AutoComplete_SetOptions() 39
auto-generated stored procedures
creating 560
deleting 564
B
background processing, checking for
colors
converting
items in process queue 28 name to value 42
RGB to value 43
properties, retrieving with scripts value to name 44
178 value to RGB 45
properties, setting with scripts 202 predefined colors for Dexterity 42,
reading from defaults file 130 44, 131
Border, setting with script 202 reading from defaults file 131
build numbers, reading from a resetting system color category 49
dictionary 507 retrieving for fields 181
button drop lists retrieving from dialog 46
adding submenus 171, 173 setting system color category 51
creating command list for 172 specifying for fields 201
returning command tag for item columns, for list view fields
175 adding 289
specifying images 184, 211 counting 291
removing 297
C retrieving
callback objects alignment 292
adding fields 140 label 293
adding methods 138 position 294
attaching to event handlers 54 subitem 295
creating 142 width 296
detaching from event handlers 57 specifying
captions alignment 299
retrieving with scripts 180 label 300
setting with scripts 204 position 301
cascading menus, for button drop lists width 302
171, 173 COM
child nodes adding objects to running object
counting 641 table 59
removing 659 creating objects 56
classes, retrieving for exceptions 162, removing objects from running
163 object table 61
client, retrieving type of 504 retrieving objects 58
clone tables, creating as temporary COM function library 53-61
tables 589 COM_AttachEventHandler() 54
Color function library 41-52 COM_CreateObject() 56
Color_ConvertNameToValue() 42 COM_DetachEventHandler() 57
Color_ConvertRGBToValue() 43 COM_GetObject() 58
Color_ConvertValueToName() 44 COM_RegisterRunningObject() 59
Color_ConvertValueToRGB() 45 COM_RevokeRunningObject() 61
Color_GetFromDialog() 46 Command bar function library 83-88
Color_ResetSystemColor() 49 command bars, see toolbars
Color_SetSystemColor() 51 Command function library 63-82
Command list function library 89-99
FUNCTION LIBRARY REFERENCE 751
I N D E X

command lists commands (continued) commands (continued)

adding commands 90 adding to command lists 90 shortcut key
adding other command lists 90 checking 78 retrieving 65
creating for ribbons 92 creating for window field 176 setting 76
deleting all commands 98 deleting from command lists 97, showing 78
deleting commands 97, 99 98, 99 syntax conventions 3
finding commands 94 disabling 78 tags 73, retrieving for window
finding commands by postion 95 enabling 78 field 187
function library 89-99 executing 64 tags, retrieving 73
number of commands in 96 finding in command lists 94, 95 types 74
removing all commands 98 focus triggers 680, 683 unchecking 78
removing commands 97, 99 function library 63-82 comparing, table definition to table
Command_Execute() 64 hiding 78 structure 556
Command_GetAccelerator() 65 IDs 68 composites
Command_GetBooleanProperty() 67 images 69, 79 returning a names for 494, 496
Command_GetIDs() 68 removing from command lists 97, returning a resource ID for 491,
Command_GetImageProperty() 69 98, 99 494
Command_GetNamedProperty() 71 resetting 75 constants
Command_GetStringProperty() 72 retrieving returning a names for 494, 496
Command_GetTag() 73 attached form name 72 returning a resource ID for 491,
Command_GetType() 74 boolean properties 67 494
Command_Reset() 75 checked state 67 container, see OLE container
Command_SetAccelerator() 76 clean display name 72 context menus, focus triggers for 680,
Command_SetBooleanProperty() 78 display name 72 683
Command_SetImageProperty() 79 enabled state 67 conventions, in documentation 2
Command_SetNamedProperty() 81 IDs 68 converting data tables
Command_SetStringProperty() 82 image properties 69 finishing conversion 565
CommandBar_Create() 84 named properties 71 starting conversion 599
CommandBar_Destroy() 86 shortcut key 65 CPU information 505
CommandBar_GetPosition() 87 string properties 72 Currency function library 101-125
command-based menus tag 73 currency symbols
adding 430 technical name 497 dollar symbol 105
enabling 624 tooltip 72 Euro symbol 105
removing 432 type 74 pound symbol 105
removing all menus 431 visible state 67 returning
CommandList_Add() 90 running from scripts 64 position for multiformat
CommandList_CreateList() 92 setting value 103
CommandList_FindCommand() 94 boolean properties 78 string used for multiformat
CommandList_GetCommandByPositio checked state 78 value 111
n() 95 display name 82 specifying
CommandList_NumCommands() 96 enabled state 78 position of for multiformat
CommandList_Remove() 97 image properties 79 value 114
CommandList_RemoveAll() 98 named properties 81 string to use for multiformat
CommandList_RemoveCommandByP shortcut key 76 value 124
osition() 99 string properties 82 yen symbol 105
commands tooltip 82 Currency_GetDecimalSymbol() 102
accelerator key 65, 76 visible state 78 Currency_GetLeadingSymbol() 103

752 F U N C T I O N L I B R A R Y R E F E R E N C E

Currency_GetLeadingZero() 104
Currency_GetNativeSymbol() 105
Currency_GetNegativeAfterValue()
106
Currency_GetNegativeBeforeSymbol()
107
Currency_GetNegativeParens() 108
Currency_GetNegativeSymbol() 109
Currency_GetNumberOfDecimals()
110
Currency_GetSymbol() 111
Currency_GetThousandsSymbol() 112
Currency_SetDecimalSymbol() 113
Currency_SetLeadingSymbol() 114
Currency_SetLeadingZero() 115
Currency_SetNegativeAfterValue() 116
Currency_SetNegativeBeforeSymbol()
118
Currency_SetNegativeParens() 120
Currency_SetNegativeSymbol() 122
Currency_SetNumberOfDecimals() 123
Currency_SetSymbol() 124
Currency_SetThousandsSymbol() 125
custom colors
for prompts 205
for scrolling windows 199
for zoom fields 222
Customization Maintenance window,
enabling 625
Customization Status window,
enabling 626
D Defaults_ClearUserFile() 128
data entry mode, changing 515
Data folder, returning path to 149, 447
data sources
changing password on login 363
filling a list box with the names of
356
logging into 361, 363
logging into using Dexterity Login
window 367
logging out of 355
returning information for 357
returning name of current 358
switching between 369
verifying access 369
data types
returning a names for 494, 496
returning a resource ID for 491,
494
database managers, setting default
database type 595
database triggers
action to trigger off of 674, 677
applying restrictions to 675, 678
registering 674, 677
DBMS, returning information for 357
decimal digits
returning number used for a
multiformat value 110
specifying number to use for
multiformat value 123
decimal separators
returning string used for
multiformat value 102
specifying string to use for
multiformat value 113
decoding, strings 700
defaults file
clearing user-specific defaults file
128
reading a boolean value from 130
reading a color from 131
reading a value from 129
reading all key values from 133
returning path to 149, 447
writing a value to 135
Defaults file function library 127-135
Defaults_Read() 129
Defaults_ReadBoolean() 130
Defaults_ReadColor() 131
Defaults_ReadKeys() 133
Defaults_Write() 135
delays, adding to scripts 620
deleting, files from operating system
227
Dex link syntax, for notifications 529
DEX.INI file, returning path to 149, 447
DexObject_AddField() 140
DexObject_AddMethod() 138
DexObject_Create() 142
FUNCTION
I N D E X
Dexterity object function library
137-142
dialog boxes, using
FileList_ShowDialog() 240
Dict_CountCustomResource() 144
Dict_GetCustomResourceInfo() 146
Dict_GetName() 148
Dict_GetPathname() 149
Dict_LockCustom() 150
Dict_UnlockCustom() 151
Dict_UpdateFormsDictionary 152
Dict_UpdateReportsDictionary 156
dictionaries
returning the name of 148
selecting for launch file 281
Dictionary function library 143-160
directories
creating 445
temp directory location 229
disabling, triggers 669, 670, 671
disconnecting from a data source 355
display names
returning for a resource 30, 489
returning for a table 574
DLLs, loading 705, 708
docked help pane, HTML Help 257
documentation, symbols and
conventions 2
dollar symbol, returning native symbol
105
DUOS
closing DUOS table 622
opening DUOS table 634
E
e-mail address
resolving 389, 423
retrieving from profile 411
embedded help, HTML Help 257
empty message, for list view fields 338
enabling, triggers 670
encoding, strings 702
encrypting, strings 701, 703
ENTER key, changing to act as TAB key
515
LIBRARY REFERENCE 753
I N D E X
errors
disabling automatic error checking
563
error codes explained 563, 606
for pass-through SQL 544
Euro symbol, returning native symbol
105
event handlers
attaching to callback objects 54
detaching from callback objects 57
examples
programming style 4
see individual command
Exception function library 161-168
Exception_Class() 162
Exception_ClassName() 163
Exception_Message() 164
Exception_Product() 165
Exception_ProductName() 166
Exception_SubClass() 167
Exception_SubClassName() 168
exceptions
retrieving class 162, 163
retrieving message 164
retrieving product 165, 166
retrieving subclass 167, 168
extensions, for file types 246
F Field_SetZoomFormat() 222
Field function library 169-223
Field_BDLAddToSubmenu() 171
Field_BDLCreateLinkedCommandList
() 172
Field_BDLCreateSubmenu() 173
Field_BDLGetLinkedItemCommandTa
g() 175
Field_CreateLinkedCommand() 176
Field_GetBooleanProperty() 178
Field_GetCaption() 180
Field_GetColor() 181
Field_GetFont() 183
Field_GetImage() 184
Field_GetInsertPosFromVisualPos()
185
Field_GetIntegerProperty() 186
Field_GetLinkedCommandTag() 187
Field_GetPosition() 188
754 F U N C T I O N L I B R A R Y
Field_GetRequiredStatus() 189
Field_GetSelection() 190
Field_GetSize() 191
Field_GetStringProperty() 192
Field_GetToolTip() 194
Field_GetVisualPosFromInsertPos()
193
Field_InsertStringInText() 195
Field_MarkListItems() 196
Field_ParseText() 197
Field_SetAltLineColor() 199
Field_SetBackColor() 201
Field_SetBooleanProperty() 202
Field_SetCaption() 204
Field_SetCustomPromptFormat() 205
Field_SetFont() 207
Field_SetFontColor() 208
Field_SetFontSize() 209
Field_SetFontStyle() 210
Field_SetImage() 211
Field_SetIntegerProperty() 212
Field_SetPattern() 213
Field_SetPatternColor() 214
Field_SetRequiredFormat() 215
Field_SetRequiredStatus() 217
Field_SetSelection() 219
Field_SetStringProperty() 220
Field_SetToolTip() 221
fields
colors
retrieving 181
specifying 201
fonts
retrieving 183
specifying color 208
specifying font 207
specifying size 209
specifying style 210
list of fields in table 575
patterns
specifying color 214
specifying pattern 213
returning
names of 494, 496
position of 188
resource ID of 491, 494
R E F E R E N C E
fields (continued)
returning
size of 191
file dialog boxes,
FileList_ShowDialog() 240
File function library 225-230
File list function library 231-241
file list items
adding to file lists 232
counting 234
removing from file lists 239
retrieving from file lists 237
file lists
adding file list items 232
counting file list items 234
creating 235
dialog to select files 240
freeing memory 236
removing file list items 239
retrieving file list items 237
File type function library 243-248
file types
appending to 244
file extensions for 246
filling list box with 245
valid for exporting to 248
File_Count() 226
File_Delete() 227
File_GetSize() 228
File_GetTempDirectory() 229
File_Probe() 230
FileList_Add() 232
FileList_Count() 234
FileList_Create() 235
FileList_Destroy() 236
FileList_Get() 237
FileList_Remove() 239
FileList_ShowDialog() 240
files
deleting from operating system
227
parsing O/S name from pathname
451
parsing path from pathname 452
returning
maximum number allowed
by an application 226
 I N D E X

files (continued) forms dictionaries (continued) HTML Help (continued)

returning
number available 226
number open 226
pathname for 453
size of in bytes 228
verifying existence of 230
FileType_CanAppend() 244
FileType_FillList() 245
FileType_GetExtension() 246
FileType_IsValid() 248
focus, pulling from a window 720
focus triggers
registering 680, 683
specifying event to trigger off of
680, 683
folders
creating 445
temp folder location 229
verifying existence 446
fonts
for required field prompts 215
retrieving for fields 183
specifying color for fields 208
specifying for fields 207
specifying size for fields 209
specifying style for fields 210
Form function library 249-250
form triggers, registering 686, 688
Form_GetWindowGroup() 250
formats
returning names for 494, 496
returning resource ID for 491, 494
forms
counting by series 499
displaying list of for a given series
487
returning
display name of 489
main window’s title 713
names for 494, 496
resource ID for 491, 494
resource IDs and names of 492
forms dictionaries
opening and locking 150
returning
information for a form 146
returning
number of forms in 144
path of from launch file 280
unlocking 151
updating 152
function triggers, registering 690, 692
G showing 265
generic pathnames
converting from native 449
converting to native 450
displaying the pathname dialog
box 453
returning a pathname for a file 453
using to retrieve a file’s O/S name
279
global defaults file, returning path to
149, 447
global variables
returning names for 494, 496
returning resource ID for 491, 494
H
help pane
creating 258
displaying topics 260
errors displaying topics 260
hiding 265
HTML Help 257
removing 259
showing 265
title 263
width
retrieving 262
setting 264
Help pane function library 257-265
HelpPane_Create() 258
HelpPane_Destroy() 259
HelpPane_DisplayTopic() 260
HelpPane_GetWidth() 262
HelpPane_SetTitle() 263
HelpPane_SetWidth() 264
HelpPane_Show() 265
host name, returning for current
workstation 268
HTML Help
displaying help by ALink 736
docked help pane 257
help pane 257
creating 258
displaying topics 260
errors displaying topics 260
hiding 265
removing 259
title 263
width
retrieving 262
setting 264
help procedure, registering 747
invoking help 741
retrieving
field context number 738
help type 739
resource ID of current
window 737
window context number 740
searching for keywords 749
types of help 739
I
icons, changing for application 516
images
specifying for button drop lists
184, 211
specifying for push buttons 184,
211
Import function library 251-256
Import utility, enabling 627
Import_CloseFile() 252
Import_GetNextField() 253
Import_GetNextRecord() 255
Import_Open File() 256
importing text files into tables 251
indexes
rebuilding for a table 591
verifying rebuild capability of
database manager 573
integers
properties, retrieving with scripts
186
properties, setting with scripts 212

FUNCTION LIBRARY REFERENCE 755

I N D E X

internet addresses, returning for L list fields, retrieving positions of items

current workstation 269 Launch file function library 271-285 185, 193
IP addresses, returning for current launch files list view
workstation 269 adding adding columns 289
IP function library 267-270 pathname to application adding items 308
IP name, returning for current dictionary 284 counting columns 291
workstation 268 pathname to forms dictionary counting items 310
IP_GetIPName() 268 284 empty message 338
IP_GetIPNumber() 269 pathname to reports getting currency subitems 311
IP_PingDPS() 270 dictionary 284 getting date subitems 313
items, for list view fields returning getting integer subitems 315
adding 308 dictionary locations from 274 getting long integer subitems 315
counting 310 name for current application getting time subitems 319
getting currency values 311 275 making an item visible 320
getting date values 313 names of products in 273 removing columns 297
getting integer values 315 number of products in 272 removing items 321
getting long integer values 315 path of application dictionary retrieving
getting time values 319 280 clicked item 304
making visible 320 path of forms dictionary 280 column alignment 292
removing 321 path of reports dictionary 280 column label 293
retrieving position of given product ID column position 294
item data 312 278 column subitem 295
item image 314 product data from 274 column width 296
item label 316 product IDs from 274 item data 312
state image 317 product names from 274, 277 item image 314
subitem 318 returning location of 149, 447 item label 316
setting currency values 322 returning path to 149, 447 item state image 317
setting date values 327 selecting launch file 283 item subitem 318
setting integer values 329 Launch_CountProds() 272 selection 335
setting long integer values 329 Launch_FillListWithProds() 273 selection count 334
setting time values 333 Launch_GetFileInfo() 274 sort column 305
specifying Launch_GetFileName() 275 view mode 307
item data 326 Launch_GetProdID() 276 setting currency subitems 322
item image 328 Launch_GetProdName() 277 setting date subitems 327
item label 330 Launch_GetProdPosition() 278 setting integer subitems 329
state image 331 Launch_ParseFileFromPath() 279 setting long integer subitems 329
subitem 332 Launch_ReadDictPath() 280 setting time subitems 333
Launch_SelectDict() 281 sorting items 342
K Launch_SelectFile() 283 specifying
keys column alignment 299
Launch_WriteDictPath() 284
returning key fields 577 column label 300
leading zeros
returning key information 578 column position 301
specifying use for multiformat
returning key option information column width 302
value 115
580 item data 326
status for multiformat value 104
returning key used for range 584 item image 328
light bulb symbol 2
returning number of keys 582 item label 330
list boxes, marking items in non-native
list boxes 196 item state image 331

756 F U N C T I O N L I B R A R Y R E F E R E N C E

list view (continued)
specifying
item subitem 332
selection 336
sort column 339
view mode 341
string widths 306
List view function library 287-343
ListView_ColumnAdd() 289
ListView_ColumnCount() 291
ListView_ColumnGetAlignment() 292
ListView_ColumnGetLabel() 293
ListView_ColumnGetPosition() 294
ListView_ColumnGetSubitem() 295
ListView_ColumnGetWidth() 296
ListView_ColumnRemove() 297
ListView_ColumnSetAlignment() 299
ListView_ColumnSetLabel() 300
ListView_ColumnSetPostion() 301
ListView_ColumnSetWidth() 302
ListView_GetClickItem() 304
ListView_GetSortColumn() 305
ListView_GetStringWidth() 306
ListView_GetView() 307
ListView_ItemAdd() 308
ListView_ItemCount() 310
ListView_ItemGetCurrencySubitem()
311
ListView_ItemGetData() 312
ListView_ItemGetDateSubitem() 313
ListView_ItemGetImage() 314
ListView_ItemGetIntSubitem() 315
ListView_ItemGetLabel() 316
ListView_ItemGetStateImage() 317
ListView_ItemGetSubitem() 318
ListView_ItemGetTimeSubitem() 319
ListView_ItemMakeVisible() 320
ListView_ItemRemove() 321
ListView_ItemSetCurrencySubitem()
322
ListView_ItemSetData() 326
ListView_ItemSetDateSubitem() 327
ListView_ItemSetImage() 328
ListView_ItemSetIntSubitem() 329
ListView_ItemSetLabel() 330
ListView_ItemSetStateImage() 331
ListView_ItemSetSubitem() 332
ListView_ItemSetTimeSubitem() 333
ListView_SelectionCount() 334
ListView_SelectionGet() 335
ListView_SelectionSet() 336
ListView_SetEmptyMessage() 338
ListView_SetSortColumn() 339
ListView_SetView() 341
ListView_Sort() 342
load balancing
disabling 623
enabling 628
locking
forms dictionaries 150
reports dictionaries 150
logging out of a data source 355
Login function library 345-370
Login window, using to log into a data
source 367
Login_AlterLogin() 346
Login_CreateLogin() 351
Login_DropLogin() 354
Login_ExitDataSource() 355
Login_GetDataSources() 356
Login_GetDBMSInfo() 357
Login_GetInfo() 358
Login_GetLoginSettings() 359
Login_LogIntoDataSource() 361
Login_LogIntoDataSourceEx() 363
Login_OpenDexDialog() 367
Login_VerifyInfo() 369
logins
altering 346
creating 351
dropping 354
retrieving settings for 359
M Mail_Send() 391
mail
address lists
adding addresses 372
counting addresses 373
creating 374
destroying 375
removing addresses 378
retrieving addresses 376
addresses
adding to list 372
FUNCTION
I N D E X
mail (continued)
addresses
dialog box for 379
removing from list 378
reply to dialog box for 381
resolving 389
retrieving from list 376
retrieving from session 384
attachments
adding to messages 391, 393
using as message body 391,
393
logging off 386
logging on 387
message addressing dialog 379,
381
retrieving server type 383
returning logon status 385
sending mail 391, 393
setting server type 395
mail connectivity, see also MAPI
Mail function library 371-395
Mail_AddressListAdd() 372
Mail_AddressListCount() 373
Mail_AddressListCreate() 374
Mail_AddressListDestroy() 375
Mail_AddressListGet() 376
Mail_AddressListRemove() 378
Mail_DisplayAddressDialog() 379
Mail_DisplayReplyToDialog() 381
Mail_GetServerType() 383
Mail_GetSessionAddress() 384
Mail_IsLoggedOn() 385
Mail_LogOff() 386
Mail_LogOn() 387
Mail_ResolveAddress() 389
Mail_SendDialog() 393
Mail_SetServerType() 395
MAPI
address lists
adding addresses 398
counting addresses 399
creating 400
destroying 401
removing addresses 422
retrieving addresses 405
LIBRARY REFERENCE 757
I N D E X
MAPI (continued)
addresses
adding to list 398
dialog box for 402
removing from list 422
reply to dialog box for 403
resolving 423
retrieving from list 405
retrieving from user profile
411
attachments
adding to messages 425, 427
using as message body 425,
427
extended MAPI 408
logging off 409
logging on 410
message addressing dialog 402,
403
properties for messages 419
property lists
counting properties 412
creating 413
removing from memory 414
retrieving values 415, 416
setting values 419
returning logon status 407
returning status 408
sending mail 425, 427
simple MAPI 408
MAPI function library 397-428
MAPI_AddAddress() 398
MAPI_CountAddresses() 399
MAPI_CreateAddressList() 400
MAPI_DestroyAddressList() 401
MAPI_DisplayDialog() 402
MAPI_DisplayReplyToDialog() 403
MAPI_GetAddress() 405
MAPI_IsLoggedOn() 407
MAPI_IsMailEnabled() 408
MAPI_LogOff() 409
MAPI_LogOn() 410
MAPI_ProfileGetAddress() 411
MAPI_PropertyListCount() 412
MAPI_PropertyListCreate() 413
MAPI_PropertyListDestroy() 414
MAPI_PropertyListGetValue() 415
758 F U N C T I O N L I B R A R Y
MAPI_PropertyListGetValueByIndex()
416
MAPI_PropertyListSetValue() 419
MAPI_RemoveAddress() 422
MAPI_ResolveAddress() 423
MAPI_Send() 425
MAPI_SendDialog() 427
margin notes 2
maximizing window groups 733
maximizing windows 725
Menu bar function library 429-432
Menu function library 433-434
Menu_Invoke() 434
MenuBar_AddMenu() 430
MenuBar_RemoveAllMenus() 431
MenuBar_RemoveMenu() 432
menus
invoking items from scripts 434
menu function library 429
messages
returning a names for 494, 496
returning a resource ID for 491,
494
metafiles
returning a names for 494, 496
returning a resource ID for 491,
494
minimizing window groups 733
minimizing windows 725
Modifier, enabling 629
modules
list of names and integer values
507
reading build and version
numbers from a dictionary 507
multiformat values
returning
currency symbol used with
111
decimal separator used 102
negative symbol string used
109
number of decimal digits
used 110
position of leading currency
symbol 103
R E F E R E N C E
multiformat values (continued)
returning
position of negative symbol
106, 107
string used as thousands
separator 112
whether leading zero is used
104
whether parentheses are used
for negatives 108
specifying
location of currency symbol
114
location of leading negative
symbol 118
location of negative symbol
116
number of decimal digits 123
string to use as currency
symbol 124
string to use as decimal
separator 113
string to use as negative
symbol 122
string to use as thousands
separator 125
whether parentheses are used
for negatives 120
whether to use leading zero
115
N
named printers
defining a named printer 456
returning name of 457
specifying printer to use 458
names
retrieving display name for a
resource 30
retrieving for a resource 494, 496,
497
retrieving name for a dictionary
148
native pathnames
converting from generic 450
converting to generic 449
 I N D E X

negative symbols O passwords, changing when logging

returning object triggers, see also triggers into data source 363
position for multiformat OLE container Path function library 443-454
value 106, 107 availability 439 Path_ChangeDefault() 444
status for multiformat value closing a container file 436 Path_CreateFolder() 445
108 deleting a container file 437 Path_DoesExist() function 446
string for multiformat value exiting 438 Path_GetForApp() 447
109 opening a container file 440 Path_MakeGeneric() 449
specifying saving a container file 441 Path_MakeNative() 450
location of for multiformat OLE function library 435-441 Path_ParseFileFromPath() 451
value 116 OLE_CloseNote() 436 Path_ParsePathFromPath() 452
location of leading symbol for OLE_DeleteNote() 437 Path_SelectPathname() 453
multiformat value 118 OLE_Exit() 438 pathnames
string to use for multiformat OLE_IsNoteEnabled() 439 adding to a launch file 284
value 122 OLE_OpenNote() 440 changing default location for
nodes, for tree view fields OLE_SaveNote() 441 tables in Pathnames series 444
adding 638 opening converting from generic to native
collapsing 640 forms dictionaries 150 450
counting 642 reports dictionaries 150 converting from native to generic
determining if parent 657 operating system 449
expanding 643 returning build information 509 displaying the pathname dialog
making visible 658 returning current 510 box 453
removing 660 operating system name, returning for parsing O/S name from 451
removing children 659 tables 583 parsing path name from 452
retrieving path for current application
first child 647 P dictionary 149, 447
first root node 655 pane help, HTML Help 257 path for forms dictionary 280
label 651 parameters, for commands, see path for launch file 275
next node 648 individual command path for reports dictionary 280
node data 649 parentheses, using to denote negative path for the runtime engine 149,
node image 650 values for multiformat value 120 447
parent 653 parsing text fields into string fields 197 returning a pathname for a file 453
previous node 654 pass-through SQL verifying existence 446
selected node 656 creating connections 535 patterns
state image 652 describing columns 536 specifying color for fields 214
setting errors 544 specifying for fields 213
node data 661 executing SQL statements 538 per-user defaults file, returning path to
node image 662 results sets 149, 447
node label 663 clearing 534 pictures (resource)
selected node 665 number of columns 547 returning a names for 494, 496
state image 664 reading data from 543 returning a resource ID for 491,
non-native list boxes, marking items in retrieving next results 546 494
196 retrieving rows 542 pinging a Process Server 270
notifications rows affected by write operations positioning, toolbars 87
Dex link syntax 529 548 pound symbol, returning native
display times for 528 terminating connections 550 symbol 105
displaying in shell 528 write operations 548 Printer function library 455-458

FUNCTION LIBRARY REFERENCE 759

I N D E X
Printer_Define() 456
Printer_GetName() 457
Printer_SetDestination() 458
printers
defining a named printer 456
returning name of a named printer
457
specifying printer to use 458
printing reports 469
procedure triggers, registering 694, 696
procedures (resource)
ascertaining whether executing on
process server 633
returning a names for 494, 496
returning a resource ID for 491,
494
process servers
ascertaining if running 270
ascertaining whether executing on
632
pinging 270
product IDs
returning based upon position in
launch file 276
returning for current product 506
using to retrieve product names
from launch file 277
using to return position of product
in launch file 278
product names, using in strings 707
progress dialogs, redrawing 710
prompts
custom colors 205
retrieving from scripts 180
specifying color and font for
required fields 215
properties
retrieving 178, 186, 192
setting 202, 212, 220
push buttons, specifying images 184,
211
Q Registry_GetProtectedString() 462
Quick Reports
adding
double line 474
new bands 479
760 F U N C T I O N L I B R A R Y
Quick Reports (continued)
adding
single line 483
text 484
concepts 469
creating 470
ending 475
fonts 482
new page 480
page remaining 476
page size 477
starting 471, 481
string width 478
R displaying list of for a given series
ranges
ascertaining if set 588
returning key used 584
rebuilding indexes, see indexes
records
removing all from a table 604
verifying contents of fields 606
redrawing, windows 710
refreshing table buffers 598
registering
database triggers 674, 677
focus triggers 680, 683
form triggers 686, 688
function triggers 690, 692
help processing procedure 747
procedure triggers 694, 696
registry
deleting keys 460
deleting values 461
encrypted values 462, 468
retrieving protected strings 462
retrieving values 464
setting protected strings 468
setting values 466
Registry function library 459-468
Registry_DeleteKey() 460
Registry_DeleteValue() 461
Registry_GetValue() 464
Registry_SetKeyValue() 466
Registry_SetProtectedKeyString() 468
Report Writer (runtime), enabling 630
R E F E R E N C E
Report_Begin() 471
Report_DoubleLine() 474
Report_End() 475
Report_GetPageRemaining() 476
Report_GetPageSize() 477
Report_GetStringWidth() 478
Report_NewBand() 479
Report_NewPage() 480
Report_ReadyToRun() 481
Report_SetFont() 482
Report_SingleLine() 483
Report_WriteText() 484
reports
counting by series 499
487
Quick Reports, see Quick Reports
returning
a names for 494, 496
a resource ID for 491, 494
display name of 489
resource IDs and names of 492
reports dictionaries
opening and locking 150
returning
information for a report 146
number of reports in 144
path of from launch file 280
unlocking 151
updating 156
Reports function library 469-484
required fields
ascertaining status of Show
Required Fields menu item 189
marking Show Required Fields
menu item 217
setting with script 202
specifying color and font for
prompts 215
Resource function library 485-501
resource IDs
returning for commands 68
returning for resources 491, 492,
494
Resource_EndSeriesFill() 486
Resource_FillSeriesList() 487
Resource_GetDisplayName() 489

Resource_GetID() 491
Resource_GetInfo() 492
Resource_GetNthResource() 494
Resource_GetResourceName() 496
Resource_GetSubResourceName() 497
Resource_StartSeriesFill() 499
resources
counting by series 499
releasing series resources from
memory 486
returning
display name of 489
names for 494, 496, 497
resource IDs and names 492
resource IDs for 491, 494
resource names 494, 496, 497
results sets
clearing 534
number of columns 547
reading data 543
retrieving next results 546
retrieving rows 542
RETURN key, changing to act as TAB
key 515
RGB
components of color value 45
converting to color value 43
ribbons
creating command lists for 92
retrieving command list for 715
using button drop lists in 172
running object table
adding objects 59
removing objects 61
runtime, retrieving type of 504
runtime engine
determining how exited 29
displaying version number of 512
returning the path for 149, 447
status of process queue 28
Runtime function library 503-516
Runtime_GetClientType() 504
Runtime_GetCPUType() 505
Runtime_GetCurrentProductID() 506
Runtime_GetModuleInfo() 507
Runtime_GetOSBuildInfo() 509
Runtime_GetOSInfo() 510
I N D E X
Runtime_GetVersionNum() 512 Shell function library 527-531
Runtime_GetWebClientTrustLevel() Shell_DisplayNotification() 528
513 shortcut keys
Runtime_SetAboutMenu() 514 retrieving for commands 65
Runtime_SetFieldEnterMode() 515 setting for commands 76
Runtime_SetIcon() 516 Show Required Fields menu item
ascertaining status 189
S checking and unchecking 217
script examples shrinking and rebuilding tables
comments in 3 described 553, 566, 602
format of 3 verifying capability of database
Script log function library 517-519 manager 573
script logger single-line scrolling windows,
starting 518 described 721
stopping 519 sorting, list view fields 342
Script profile function library 521-525 SQL
script profiler logins
accessing from scripts 521 altering 346
clearing the profile 522 creating 351
saving the profile 523 dropping 354
starting and stopping 524, 525 retrieving settings for 359
ScriptLog_Start() 518 SQL function library 533-550
ScriptLog_Stop() 519 SQL symbol 2
ScriptProfile_Clear() 522 SQL tables
ScriptProfile_Save() 523 auto-generated stored procedures
ScriptProfile_Start() 524 creating 560
ScriptProfile_Stop() 525 deleting 564
scrolling windows creating indexes 559
changing types 724 SQL_Clear() 534
custom colors 199 SQL_Connect() 535
scrolling from scripts 721 SQL_DescribeColumn() 536
setting line mode 724 SQL_Execute() 538
single-line scrolling windows 721 SQL_FetchNext() 542
selection, for list view fields SQL_GetData() 543
retrieving 335 SQL_GetError() 544
retrieving selection count 334 SQL_GetNextResults() 546
specifying 336 SQL_GetNumCols() 547
series, returning for tables 585 SQL_GetNumRows() 548
series resources SQL_Terminate() 550
counting and returning number of SQLError procedure
499 reading error information 586
filling list fields with resources’ sample 586
physical names and display state images
names 487 retrieving clicked image 644
releasing from memory 486 retrieving for list view items 317
session ID, of current session 358 retrieving for tree view nodes 652
SET files, see launch files setting for tree view nodes 664
FUNCTION LIBRARY REFERENCE 761
I N D E X
state images (continued)
specifying for list view items 331
static text values
retrieving with scripts 180
setting with scripts 204
static values
retrieving with scripts 180
setting with scripts 204
strings
creating from parsed text fields
197
decoding 700
encoding 702
encrypting 701, 703
inserting into text fields 195
properties, retrieving with scripts
192
properties, setting with scripts 220
returning a names for 494, 496
returning a resource ID for 491,
494
substituting product tokens 707
subclasses, retrieving for exceptions
167, 168
symbols in documentation 2
syntax, for commands 3
T Table_GetRangeKey() 584
TAB key, making ENTER and RETURN
keys act like 515
tab sequence, setting with script 202
table buffers
opening additional instances 590
refreshing 598
returning number available 226
table conversions, see converting data
tables
Table function library 551-607
table groups
counting by series 499
displaying list of for a given series
487
filling a list of tables in 571
listing for a series 569
returning a names for 494, 496
returning a resource ID for 491,
494, 576
762 F U N C T I O N L I B R A R Y
table groups (continued)
returning resource IDs and names
of 492
table operations
disabling error checking 563
list of error codes 563
Table_AutoShrink() 553
Table_Compare() 556
Table_CopyShrinkRecords() 557
Table_CreateIndexes() 559
Table_CreateProcedures() 560
Table_DisableErrorChecks() 563
Table_DropProcedures() 564
Table_EndConversion() 565
Table_EndShrink() 566
Table_FillGroupList() 569
Table_FillList() 571
Table_FlushCache() 572
Table_GetAutoShrinkMode() 573
Table_GetDisplayName() 574
Table_GetFieldList() 575
Table_GetGroup() 576
Table_GetKeyFieldList() 577
Table_GetKeyInfo() 578
Table_GetKeyOption() 580
Table_GetNumberOfKeys() 582
Table_GetOSName() 583
Table_GetSeries() 585
Table_GetSQLErrorText() 586
Table_IsRangeSet() 588
Table_OpenAsTemp() 589
Table_OpenNewBuffer() 590
Table_RebuildIndexes() 591
Table_SetCreateMode() 593
Table_SetDBType() 595
Table_SetDeleteOptions() 596
Table_SetRefreshFlags() 598
Table_StartConversion() 599
Table_StartShrink() 602
Table_Truncate() 604
Table_VerifyRecord() 606
tables
auto-generated stored procedures
creating 560
deleting 564
R E F E R E N C E
tables (continued)
changing default location for
tables in Pathname series 444
clone tables 589
comparing table definition to table
structure 556
converting data 565, 599
counting by series 499
creating, indexes 559
creation mode 593
deleting
all records 604
delete all functionality 596
drop functionality 596
disabling error checking 563
displaying list of for a given series
487
encrypting strings 703
errors, list of 563
flushing table cache 572
in a table group, displaying names
of 571
list of table fields 575
opening additional table buffers
590
ranges
ascertaining if set 588
ascertaining key used 584
rebuilding indexes 553, 591
refreshing the buffer for 598
removing unused space from 557
returning
display name of 489, 574
key fields 577
key information 578
key option information 580
names for 494, 496
number of keys 582
operating system name 583
resource ID for 491, 494
resource IDs and names of 492
series of 585
setting a default database type 595
shrinking 557, 566, 602
by database manager 553
verifying capability of
database manager 573

tables (continued)
table conversion
finishing conversion 565
starting conversion 599
verifying contents of records in
606
verifying existence of 230
tags
for commands 73
retrieving for triggers 672
temp folder, retrieving location of 229
temporary tables, clone tables 589
text fields
inserting strings into 195
parsing into string fields 197
returning selection 190
setting selection 219
Text file function library 609-618
text files
access mode 611
closing 610
importing 251
opening 611
position in at opening 611
reading a line from 613
reading a number of characters
from 615
writing to 617, 618
writing to DOS text files 616
TextFile_Close() 610
TextFile_Open() 611
TextFile_ReadLine() 613
TextFile_ReadText() 615
TextFile_WriteDOS() 616
TextFile_WriteLine() 617
TextFile_WriteText() 618
thousands separator
returning string used for
multiformat value 112
specifying string to use for
multiformat value 125
Timer function library 619-620
Timer_Sleep() 620
title, for docked help pane 263
tokens, substituting in strings 707
toolbars
creating 84
toolbars (continued)
function library 83-88
removing 86
retrieving position 87
Tools function library 621-635
Tools_CloseDUOSTable() 622
Tools_DisableLoadBalancing() 623
Tools_EnableCommandMenus() 624
Tools_EnableCustomizationMaintenan
ce() 625
Tools_EnableCustomizationStatus()
626
Tools_EnableImport() 627
Tools_EnableLoadBalancing() 628
Tools_EnableModifier() 629
Tools_EnableReportWriter() 630
Tools_GetTranLevel() 631
Tools_IsAppProcessServer() 632
Tools_IsScriptRemote() 633
Tools_OpenDUOSTable() 634
tooltips
retrieving 194
setting 221
transactions, retrieving transaction
level 631
tree view
adding nodes 638
child nodes
counting 641
removing 659
clicked node, retrieving 644
collapsing node, retrieving 645
collapsing nodes 640
expanding node, retrieving 646
expanding nodes 643
images 638
nodes, see nodes for tree view
fields
Tree view function library 637-665
TreeView_AddNode() 638
TreeView_CollapseNode() 640
TreeView_CountChildren() 641
TreeView_CountNodes() 642
TreeView_ExpandNode() 643
TreeView_GetClickNode() 644
TreeView_GetCollapsingNode() 645
TreeView_GetExpandingNode() 646
FUNCTION
I N D E X
TreeView_GetFirstChild() 647
TreeView_GetNextNode() 648
TreeView_GetNodeData() 649
TreeView_GetNodeImage() 650
TreeView_GetNodeLabel() 651
TreeView_GetNodeStateImage() 652
TreeView_GetParent() 653
TreeView_GetPreviousNode() 654
TreeView_GetRootNode() 655
TreeView_GetSelectedNode() 656
TreeView_IsParentNode() 657
TreeView_MakeNodeVisible() 658
TreeView_RemoveChildren() 659
TreeView_RemoveNode() 660
TreeView_SetNodeData() 661
TreeView_SetNodeImage() 662
TreeView_SetNodeLabel() 663
TreeView_SetNodeStateImage() 664
TreeView_SetSelectedNode() 665
Trigger function library 667-698
Trigger_CausedByProduct() 668
Trigger_DisableSingle() 669
Trigger_Enable() 670
Trigger_EnableSingle() 671
Trigger_GetCurrentTag() 672
Trigger_IsTriggerEnabled() 673
Trigger_RegisterDatabase() 674
Trigger_RegisterDatabaseByName()
677
Trigger_RegisterFocus() 680
Trigger_RegisterFocusByName() 683
Trigger_RegisterForm() 686
Trigger_RegisterFormByName() 688
Trigger_RegisterFunction() 690
Trigger_RegisterFunctionByName()
692
Trigger_RegisterProcedure() 694
Trigger_RegisterProcedureByName()
696
Trigger_Unregister() 698
triggers
ascertaining status 673
disabling all 670
disabling one 669
enabling all 670
enabling one 671
LIBRARY REFERENCE 763
I N D E X
triggers (continued)
registering
database triggers 674, 677
focus triggers 680, 683
form triggers 686, 688
function triggers 690, 692
procedure triggers 694, 696
retrieving tag 672
unregistering 698
trust level, for Silverlight web client
application 513
U automatic resizing 729
unlocking
forms dictionaries 151
reports dictionaries 151
unregistering, triggers 698
updating
forms dictionaries 152
reports dictionaries 156
user IDs, returning for current login
358
user-defined functions
returning a names for 494, 496
returning a resource ID for 491,
494
Utility function library 699-708
Utility_DecodeString() 700
Utility_DecryptTableString() 701
Utility_EncodeString() 702
Utility_EncryptTableString() 703
Utility_LoadDLL() 705
Utility_SubstituteTokens() 707
Utility_UnloadDLL() 708
V 727-734
verifying records in a table 606
version numbers
for a module, reading from a
dictionary 507
for the runtime engine 512
view mode, for list view fields
retrieving 307
specifying 341
W adding to a window group 728
warning symbol 2
764 F U N C T I O N L I B R A R Y
web client
invoking help 743
retrieving trust level for 513
window fields
creating command for 176
retrieving command tag for 187
retrieving size of 191
Window function library 709-725
window groups
adding to existing window groups
728
as modal windows 729
minimizing or maximizing 733
resizing 732
setting position for 731
specifying display characteristics
729
state 733
title for 734
Window_ForceRedraw() 710
Window_GetMainWindowTitle() 713
Window_GetPosition() 714
Window_GetRibbonCommandTag()
715
Window_GetSize() 716
Window_GetState() 717
Window_GetTitle() 718
Window_GetTitleByProduct() 719
Window_PullFocus() 720
Window_ScrollScrollingWindow() 721
Window_SetBaseSize() 723
Window_SetLineMode() 724
Window_SetState() 725
WindowGroup function library
WindowGroup_AddWindow() 728
WindowGroup_SetBooleanProperty()
729
WindowGroup_SetPosition() 731
WindowGroup_SetSize() 732
WindowGroup_SetState() 733
WindowGroup_SetStringProperty()
734
windows
forcing to redraw 710
R E F E R E N C E
windows (continued)
minimizing or maximizing 725
pulling the focus 720
resizing 723
retrieving
command list for ribbon 715
height and width of 716
main window’s title 713
position of 714
title of window in a specific
dictionary 719
window title 718
state 717, 725
Windows Help
help procedure, registering 747
invoking help 741
retrieving
field context number 738
help type 739
resource ID of current
window 737
window context number 740
running help macros 748
searching for keywords 749
types of help 739
Windows registry, see registry
WinHelp function library 735-749
WinHelp_ALinkLookup() 736
WinHelp_GetCurWindow() 737
WinHelp_GetFieldContextNumber()
738
WinHelp_GetHelpType() 739
WinHelp_GetWindowContextNumber
() 740
WinHelp_InvokeHelp() 741
WinHelp_LaunchUrl() 743
WinHelp_RegisterHelpProcedure() 747
WinHelp_RunHelpMacro() 748
WinHelp_Search() 749
Y
yen symbol, returning native symbol
105
Z
zooms, custom colors 222