PowerScript Reference

Volume 1

PowerBuilder
8
DOCUMENT ID: 37781-01-0800-01

LAST REVISED: June 2001

Copyright © 1989-2001 by Sybase, Inc. All rights reserved.

This publication pertains to Sybase database management software and to any subsequent release until otherwise indicated in new
editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished
under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.

To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other
international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled
software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic,
mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server,
Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication,
Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager,
AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, Backup Server,
ClearConnect, Client-Library, Client Services, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress,
DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution
Director, E-Anywhere, E-Whatever, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server, Enterprise Connect,
Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer,
Enterprise Work Modeler, EWA, Financial Fusion, Financial Fusion Server, Gateway Manager, ImpactNow, InfoMaker, Information
Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase,
MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MySupport,
Net-Gateway, Net-Library, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Client,
Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open
Solutions, Optima++, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, Power++, power.stop, PowerAMC, PowerBuilder,
PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite,
PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop,
PowerWare Enterprise, ProcessAnalyst, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server,
Replication Server Manager, Replication Toolkit, Resource Manager, RW-DisplayLib, RW-Library, S-Designor, SDF, Secure SQL
Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL
Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL
Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL
Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase
MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber Financial,
SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, Transact-SQL, Translation Toolkit,
UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter,
VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL
Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server and XP
Server are trademarks of Sybase, Inc. 3/01

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names used herein may be trademarks or registered trademarks of their respective companies.

Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-
7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

Contents

About This Book ......................................................................................................................... xxi

VOLUME 1

PART 1 POWERSCRIPT TOPICS

C H APTE R 1 Language Basics............................................................................. 3

Comments ........................................................................................ 4
Identifier names................................................................................ 6
Labels............................................................................................... 8
Special ASCII characters ................................................................. 9
NULL values................................................................................... 11
Reserved words ............................................................................. 13
Pronouns ........................................................................................ 14
Parent pronoun........................................................................ 15
This pronoun ........................................................................... 16
Super pronoun......................................................................... 17
Statement continuation .................................................................. 18
Statement separation ..................................................................... 20
White space ................................................................................... 21

C H APTE R 2 Data Types ..................................................................................... 23

Standard data types ....................................................................... 24
Any data type ................................................................................. 29
System object data types ............................................................... 32
Enumerated data types .................................................................. 33
PowerBuilder data types in EAServer ............................................ 34

C H APTE R 3 Declarations................................................................................... 35
Declaring variables......................................................................... 36
Where to declare variables...................................................... 36

iii
Contents

About using variables .............................................................. 37

Syntax of a variable declaration .............................................. 39
Declaring constants........................................................................ 49
Declaring arrays ............................................................................. 50
Values for array elements ....................................................... 53
Size of variable-size arrays ..................................................... 54
More about arrays ................................................................... 56
Declaring external functions ........................................................... 60
Data types for external function arguments............................. 63
Calling external functions ........................................................ 65
Defining source for external functions ..................................... 66
Declaring DBMS stored procedures as remote procedure calls (RPCs)
67

CH APT ER 4 Operators and Expressions.......................................................... 69

Operators in PowerBuilder ............................................................. 70
Arithmetic operators in PowerBuilder ...................................... 70
Relational operators in PowerBuilder ...................................... 72
Concatenation operator in PowerBuilder................................. 73
Operator precedence in PowerBuilder expressions....................... 75
Data type of PowerBuilder expressions ......................................... 76
Numeric data types in PowerBuilder ....................................... 76
String and char data types in PowerBuilder ............................ 78

CH APT ER 5 Structures and Objects ................................................................. 81

About structures ............................................................................. 82
About objects ................................................................................. 84
About user objects................................................................... 85
Instantiating objects................................................................. 86
Using ancestors and descendants .......................................... 87
Garbage collection .................................................................. 87
User objects that behave like structures ................................. 88
Assignment for objects and structures ........................................... 90

CH APT ER 6 Calling Functions and Events ...................................................... 93

About functions and events............................................................ 94
Finding and executing functions and events ........................... 96
Triggering versus posting functions and events ...................... 98
Static versus dynamic calls ................................................... 100
Overloading, overriding, and extending functions and events 106
Passing arguments to functions and events.......................... 108
Using return values of functions and events ......................... 110

iv
 Contents

Using cascaded calling and return values............................. 111

Syntax for calling PowerBuilder functions and events ................. 113
Calling functions and events in an object’s ancestor ................... 117

PART 2 STATEMENTS, EVENTS, AND FUNCTIONS

C HA PTER 7 PowerScript Statements............................................................. 123

Assignment .................................................................................. 124
CALL ............................................................................................ 127
CHOOSE CASE........................................................................... 128
CONTINUE .................................................................................. 130
CREATE....................................................................................... 131
DESTROY.................................................................................... 134
DO...LOOP................................................................................... 135
EXIT ............................................................................................. 138
FOR...NEXT ................................................................................. 139
GOTO........................................................................................... 141
HALT ............................................................................................ 142
IF...THEN ..................................................................................... 143
RETURN ...................................................................................... 145
THROW........................................................................................ 146
THROWS ..................................................................................... 147
TRY...CATCH...FINALLY...END TRY .......................................... 149

C HA PTER 8 SQL Statements .......................................................................... 151

Using SQL in scripts..................................................................... 152
CLOSE Cursor ............................................................................. 155
CLOSE Procedure ....................................................................... 156
COMMIT....................................................................................... 157
CONNECT ................................................................................... 158
DECLARE Cursor ........................................................................ 159
DECLARE Procedure................................................................... 160
DELETE ....................................................................................... 162
DELETE Where Current of Cursor............................................... 163
DISCONNECT ............................................................................. 164
EXECUTE .................................................................................... 165
FETCH ......................................................................................... 166
INSERT ........................................................................................ 167
OPEN Cursor ............................................................................... 168
ROLLBACK .................................................................................. 169
SELECT ....................................................................................... 170
SELECTBLOB.............................................................................. 172

v
Contents

UPDATE....................................................................................... 174
UPDATEBLOB ............................................................................. 175
UPDATE Where Current of Cursor .............................................. 177
Using dynamic SQL ..................................................................... 178
Dynamic SQL Format 1................................................................ 182
Dynamic SQL Format 2................................................................ 183
Dynamic SQL Format 3................................................................ 185
Dynamic SQL Format 4................................................................ 188

CH APT ER 9 PowerScript Events ..................................................................... 193

About events ................................................................................ 194
Activate ........................................................................................ 197
BeginDrag .................................................................................... 198
BeginLabelEdit ............................................................................. 201
BeginRightDrag ............................................................................ 203
Clicked ......................................................................................... 206
Close ............................................................................................ 212
CloseQuery .................................................................................. 214
ColumnClick ................................................................................. 216
ConnectionBegin .......................................................................... 218
ConnectionEnd............................................................................. 219
Constructor................................................................................... 220
DataChange ................................................................................. 221
Deactivate .................................................................................... 222
DeleteAllItems .............................................................................. 223
DeleteItem.................................................................................... 224
Destructor..................................................................................... 226
DoubleClicked .............................................................................. 227
DragDrop...................................................................................... 232
DragEnter..................................................................................... 236
DragLeave.................................................................................... 237
DragWithin ................................................................................... 239
EndLabelEdit................................................................................ 242
Error ............................................................................................. 244
ExternalException ........................................................................ 247
FileExists...................................................................................... 250
GetFocus...................................................................................... 251
Help.............................................................................................. 252
Hide.............................................................................................. 253
HotLinkAlarm................................................................................ 254
Idle ............................................................................................... 255
InputFieldSelected ....................................................................... 256
InsertItem ..................................................................................... 257
ItemActivate ................................................................................. 258

vi
 Contents

ItemChanged................................................................................ 259
ItemChanging............................................................................... 260
ItemCollapsed .............................................................................. 261
ItemCollapsing ............................................................................. 262
ItemExpanded .............................................................................. 263
ItemExpanding ............................................................................. 264
ItemPopulate ................................................................................ 265
Key ............................................................................................... 266
LineDown ..................................................................................... 268
LineLeft ........................................................................................ 269
LineRight ...................................................................................... 270
LineUp.......................................................................................... 271
LoseFocus.................................................................................... 272
Modified........................................................................................ 274
MouseDown ................................................................................. 276
MouseMove.................................................................................. 279
MouseUp...................................................................................... 283
Moved .......................................................................................... 286
Open ............................................................................................ 287
Other ............................................................................................ 290
PageDown.................................................................................... 291
PageLeft....................................................................................... 292
PageRight .................................................................................... 293
PageUp ........................................................................................ 294
PictureSelected ............................................................................ 295
PipeEnd........................................................................................ 296
PipeMeter..................................................................................... 297
PipeStart ...................................................................................... 298
PrintFooter ................................................................................... 299
PrintHeader .................................................................................. 300
PropertyChanged ......................................................................... 301
PropertyRequestEdit .................................................................... 302
RButtonDown ............................................................................... 303
RButtonUp.................................................................................... 305
RemoteExec................................................................................. 306
RemoteHotLinkStart ..................................................................... 307
RemoteHotLinkStop ..................................................................... 308
RemoteRequest ........................................................................... 309
RemoteSend ................................................................................ 310
Rename........................................................................................ 311
Resize .......................................................................................... 312
RightClicked ................................................................................. 313
RightDoubleClicked...................................................................... 316
Save ............................................................................................. 318

vii
Contents

SaveObject................................................................................... 319
Selected ....................................................................................... 320
SelectionChanged ........................................................................ 321
SelectionChanging ....................................................................... 324
Show ............................................................................................ 326
Sort............................................................................................... 327
SystemError ................................................................................. 330
SystemKey ................................................................................... 331
Timer ............................................................................................ 332
ToolbarMoved .............................................................................. 334
ViewChange................................................................................. 335

VOLUME 2

CH APT ER 10 PowerScript Functions................................................................ 337

Abs ............................................................................................... 338
ACos ............................................................................................ 339
Activate ........................................................................................ 340
AddCategory ................................................................................ 342
AddColumn .................................................................................. 344
AddData ....................................................................................... 345
AddItem........................................................................................ 348
AddLargePicture .......................................................................... 353
AddPicture.................................................................................... 354
AddSeries..................................................................................... 355
AddSmallPicture........................................................................... 357
AddStatePicture ........................................................................... 358
Arrange ........................................................................................ 359
ArrangeSheets ............................................................................. 360
Asc ............................................................................................... 361
ASin.............................................................................................. 362
ATan............................................................................................. 363
Beep............................................................................................. 364
BeginTransaction ......................................................................... 365
Blob .............................................................................................. 367
BlobEdit........................................................................................ 368
BlobMid ........................................................................................ 369
BuildModel ................................................................................... 371
Cancel .......................................................................................... 374
CanUndo ...................................................................................... 375
CategoryCount ............................................................................. 376
CategoryName ............................................................................. 377
Ceiling .......................................................................................... 378

viii
 Contents

ChangeDirectory .......................................................................... 379

ChangeMenu................................................................................ 380
Char ............................................................................................. 381
Check ........................................................................................... 382
ChooseColor ................................................................................ 383
ClassList....................................................................................... 384
ClassName................................................................................... 385
Clear............................................................................................. 387
Clipboard...................................................................................... 389
Close ............................................................................................ 392
CloseChannel............................................................................... 396
CloseTab...................................................................................... 397
CloseUserObject .......................................................................... 399
CloseWithReturn .......................................................................... 401
CollapseItem ................................................................................ 404
CommandParm ............................................................................ 405
CommitTransaction ...................................................................... 407
ConnectToNewObject .................................................................. 409
ConnectToNewRemoteObject ..................................................... 411
ConnectToObject ......................................................................... 413
ConnectToRemoteObject............................................................. 416
ConnectToServer ......................................................................... 419
Copy............................................................................................. 422
CopyRTF...................................................................................... 424
Cos............................................................................................... 426
Cpu............................................................................................... 427
CreateDirectory ............................................................................ 428
CreateInstance............................................................................. 429
CreatePage .................................................................................. 433
Cut................................................................................................ 434
DataCount .................................................................................... 436
DataSource .................................................................................. 437
Date.............................................................................................. 439
DateTime...................................................................................... 443
Day............................................................................................... 445
DayName ..................................................................................... 446
DayNumber .................................................................................. 447
DaysAfter ..................................................................................... 448
DBHandle..................................................................................... 449
DebugBreak ................................................................................. 450
Dec............................................................................................... 451
DeleteCategory ............................................................................ 452
DeleteColumn .............................................................................. 453
DeleteColumns............................................................................. 454

ix
Contents

DeleteData ................................................................................... 455

DeleteItem.................................................................................... 456
DeleteItems .................................................................................. 459
DeleteLargePicture ...................................................................... 460
DeleteLargePictures..................................................................... 461
DeletePicture................................................................................ 462
DeletePictures.............................................................................. 463
DeleteSeries................................................................................. 464
DeleteSmallPicture....................................................................... 465
DeleteSmallPictures..................................................................... 466
DeleteStatePicture ....................................................................... 467
DeleteStatePictures ..................................................................... 468
DestroyModel ............................................................................... 469
DirectoryExists ............................................................................. 470
DirList ........................................................................................... 471
DirSelect....................................................................................... 473
Disable ......................................................................................... 474
DisableCommit ............................................................................. 475
DisconnectObject ......................................................................... 476
DisconnectServer......................................................................... 477
Double.......................................................................................... 478
DoVerb ......................................................................................... 479
Drag ............................................................................................. 480
DraggedObject ............................................................................. 482
Draw............................................................................................. 483
EditLabel ...................................................................................... 484
Enable .......................................................................................... 486
EnableCommit.............................................................................. 487
EntryList ....................................................................................... 488
ExecRemote................................................................................. 489
Exp ............................................................................................... 492
ExpandAll ..................................................................................... 493
ExpandItem .................................................................................. 494
Fact .............................................................................................. 495
FileClose ...................................................................................... 496
FileCopy ....................................................................................... 497
FileDelete ..................................................................................... 498
FileExists...................................................................................... 499
FileLength .................................................................................... 500
FileMove....................................................................................... 501
FileOpen....................................................................................... 502
FileRead....................................................................................... 504
FileSeek ....................................................................................... 507
FileWrite ....................................................................................... 508

x
 Contents

Fill................................................................................................. 510
Find .............................................................................................. 511
FindCategory................................................................................ 513
FindClassDefinition ...................................................................... 515
FindFunctionDefinition ................................................................. 516
FindItem ....................................................................................... 517
FindMatchingFunction .................................................................. 523
FindNext....................................................................................... 525
FindSeries .................................................................................... 526
FindTypeDefinition ....................................................................... 527
FromAnsi...................................................................................... 529
FromUnicode................................................................................ 530
GarbageCollect ............................................................................ 532
GarbageCollectGetTimeLimit ....................................................... 533
GarbageCollectSetTimeLimit ....................................................... 534
GetActiveSheet ............................................................................ 535
GetAlignment ............................................................................... 536
GetApplication.............................................................................. 537
GetArgElement............................................................................. 538
GetAutomationNativePointer........................................................ 539
GetCertificateLabel ...................................................................... 541
GetChildrenList ............................................................................ 544
GetColumn ................................................................................... 546
GetCommandDDE ....................................................................... 548
GetCommandDDEOrigin.............................................................. 550
GetCompanyName ...................................................................... 551
GetContextKeywords ................................................................... 552
GetContextService ....................................................................... 553
GetCredentialAttribute.................................................................. 555
GetCurrentDirectory ..................................................................... 558
GetData........................................................................................ 559
GetDataDDE ................................................................................ 564
GetDataDDEOrigin....................................................................... 565
GetDataPieExplode...................................................................... 566
GetDataStyle................................................................................ 568
GetDataValue............................................................................... 574
GetDynamicDate.......................................................................... 576
GetDynamicDateTime .................................................................. 578
GetDynamicNumber..................................................................... 580
GetDynamicString ........................................................................ 581
GetDynamicTime ......................................................................... 582
GetEnvironment ........................................................................... 583
GetFileOpenName ....................................................................... 584
GetFileSaveName........................................................................ 586

xi
Contents

GetFirstSheet ............................................................................... 588

GetFixesVersion........................................................................... 589
GetFocus...................................................................................... 590
GetFolder ..................................................................................... 591
GetGlobalProperty ....................................................................... 592
GetHostObject.............................................................................. 593
GetItem ........................................................................................ 594
GetItemAtPointer.......................................................................... 597
GetLastReturn.............................................................................. 598
GetLibraryList ............................................................................... 599
GetMajorVersion .......................................................................... 600
GetMessage................................................................................. 601
GetMinorVersion .......................................................................... 602
GetName...................................................................................... 603
GetNativePointer.......................................................................... 604
GetNextSheet............................................................................... 605
GetOrigin...................................................................................... 606
GetParagraphSetting ................................................................... 607
GetParent..................................................................................... 608
GetPin .......................................................................................... 610
GetRecordSet .............................................................................. 612
GetRemote................................................................................... 613
GetSeriesStyle ............................................................................. 616
GetServerInfo............................................................................... 623
GetShortName ............................................................................. 624
GetSpacing .................................................................................. 625
GetStatus ..................................................................................... 626
GetTextColor................................................................................ 628
GetTextStyle ................................................................................ 629
GetToolbar ................................................................................... 630
GetToolbarPos ............................................................................. 632
GetTransactionName ................................................................... 635
GetURL ........................................................................................ 636
GetVersionName.......................................................................... 637
Handle.......................................................................................... 638
Hide.............................................................................................. 640
Hour ............................................................................................. 641
HyperLinkToURL.......................................................................... 642
Idle ............................................................................................... 643
ImpersonateClient ........................................................................ 645
ImportClipboard............................................................................ 646
ImportFile ..................................................................................... 648
ImportString.................................................................................. 651
IncomingCallList ........................................................................... 653

xii
 Contents

Init ................................................................................................ 655

InputFieldChangeData ................................................................. 659
InputFieldCurrentName ................................................................ 661
InputFieldDeleteCurrent ............................................................... 662
InputFieldGetData ........................................................................ 663
InputFieldInsert ............................................................................ 664
InputFieldLocate........................................................................... 665
InsertCategory.............................................................................. 667
InsertClass ................................................................................... 669
InsertColumn................................................................................ 670
InsertData..................................................................................... 671
InsertDocument............................................................................ 674
InsertFile ...................................................................................... 676
InsertItem ..................................................................................... 677
InsertItemFirst .............................................................................. 683
InsertItemLast .............................................................................. 685
InsertItemSort............................................................................... 688
InsertObject.................................................................................. 691
InsertPicture ................................................................................. 692
InsertSeries .................................................................................. 693
Int ................................................................................................. 694
Integer .......................................................................................... 695
InternetData ................................................................................. 697
IntHigh.......................................................................................... 698
IntLow........................................................................................... 699
InvokePBFunction ........................................................................ 700
_Is_A ............................................................................................ 702
IsAlive........................................................................................... 703
IsAllArabic .................................................................................... 704
IsAllHebrew .................................................................................. 705
IsAnyArabic .................................................................................. 706
IsAnyHebrew................................................................................ 707
IsArabic ........................................................................................ 708
IsArabicAndNumbers ................................................................... 709
IsCallerInRole............................................................................... 710
IsDate........................................................................................... 712
IsHebrew ...................................................................................... 713
IsHebrewAndNumbers ................................................................. 714
IsImpersonating............................................................................ 715
IsInTransaction............................................................................. 716
IsNull ............................................................................................ 717
IsNumber...................................................................................... 718
IsPreview...................................................................................... 719
IsSecurityEnabled ........................................................................ 720

xiii
Contents

IsTime .......................................................................................... 721

IsTransactionAborted ................................................................... 722
IsValid .......................................................................................... 724
KeyDown...................................................................................... 725
LastPos ........................................................................................ 728
Left ............................................................................................... 730
LeftTrim ........................................................................................ 731
Len ............................................................................................... 732
Lenw............................................................................................. 734
Length .......................................................................................... 735
LibraryCreate ............................................................................... 736
LibraryDelete ................................................................................ 737
LibraryDirectory............................................................................ 738
LibraryDirectoryEx........................................................................ 740
LibraryExport ................................................................................ 742
LibraryImport ................................................................................ 744
LineCount..................................................................................... 746
LineLength ................................................................................... 747
LineList......................................................................................... 748
LinkTo .......................................................................................... 749
Listen............................................................................................ 750
Log ............................................................................................... 751
LogTen ......................................................................................... 753
Long ............................................................................................. 754
Lookup ......................................................................................... 756
Lower ........................................................................................... 761
LowerBound ................................................................................. 762
mailAddress ................................................................................. 763
mailDeleteMessage...................................................................... 765
mailGetMessages ........................................................................ 766
mailHandle ................................................................................... 768
mailLogoff..................................................................................... 769
mailLogon..................................................................................... 770
mailReadMessage ....................................................................... 772
mailRecipientDetails..................................................................... 774
mailResolveRecipient................................................................... 776
mailSaveMessage ........................................................................ 779
mailSend ...................................................................................... 781
Match ........................................................................................... 783
Max .............................................................................................. 786
MemberDelete.............................................................................. 787
MemberExists .............................................................................. 788
MemberRename .......................................................................... 789
MessageBox ................................................................................ 790

xiv
 Contents

Mid ............................................................................................... 792

Min ............................................................................................... 795
Minute .......................................................................................... 796
Mod .............................................................................................. 797
ModifyData ................................................................................... 798
Month ........................................................................................... 801
Move ............................................................................................ 802
MoveTab ...................................................................................... 804
_Narrow........................................................................................ 805
NextActivity .................................................................................. 806
Now .............................................................................................. 808
ObjectAtPointer ............................................................................ 809
Object_To_String ......................................................................... 812
OffsetPos ..................................................................................... 813
Open ............................................................................................ 814
OpenChannel ............................................................................... 829
OpenSheet ................................................................................... 831
OpenSheetWithParm ................................................................... 833
OpenTab ...................................................................................... 836
OpenTabWithParm ...................................................................... 840
OpenUserObject .......................................................................... 845
OpenUserObjectWithParm........................................................... 849
OpenWithParm............................................................................. 854
OutgoingCallList........................................................................... 859
PageCount ................................................................................... 861
PageCreated ................................................................................ 862
ParentWindow.............................................................................. 863
Paste ............................................................................................ 865
PasteLink ..................................................................................... 867
PasteRTF ..................................................................................... 868
PasteSpecial ................................................................................ 869
Pi .................................................................................................. 870
PixelsToUnits ............................................................................... 871
PointerX ....................................................................................... 872
PointerY ....................................................................................... 873
PopMenu...................................................................................... 874
PopulateError ............................................................................... 876
Pos ............................................................................................... 878
Position ........................................................................................ 880
Post .............................................................................................. 885
PostEvent..................................................................................... 886
PostURL....................................................................................... 890
Preview ........................................................................................ 892
Print.............................................................................................. 894

xv
Contents

PrintBitmap................................................................................... 901
PrintCancel................................................................................... 902
PrintClose..................................................................................... 904
PrintDataWindow ......................................................................... 905
PrintDefineFont ............................................................................ 906
PrintGetPrinter ............................................................................. 908
PrintGetPrinters............................................................................ 909
PrintLine ....................................................................................... 910
PrintOpen ..................................................................................... 912
PrintOval ...................................................................................... 914
PrintPage ..................................................................................... 916
PrintRect ...................................................................................... 917
PrintRoundRect ............................................................................ 919
PrintScreen .................................................................................. 921
PrintSend ..................................................................................... 922
PrintSetFont ................................................................................. 924
PrintSetPrinter.............................................................................. 925
PrintSetSpacing ........................................................................... 926
PrintSetup .................................................................................... 927
PrintSetupPrinter.......................................................................... 928
PrintText....................................................................................... 929
PrintWidth..................................................................................... 931
PrintX ........................................................................................... 932
PrintY ........................................................................................... 933
ProfileInt ....................................................................................... 934
ProfileString.................................................................................. 936
Rand............................................................................................. 938
Randomize ................................................................................... 939
Read............................................................................................. 940
Real.............................................................................................. 943
RegistryDelete.............................................................................. 944
RegistryGet .................................................................................. 945
RegistryKeys ................................................................................ 947
RegistrySet................................................................................... 948
RegistryValues ............................................................................. 950
RelativeDate................................................................................. 951
RelativeTime ................................................................................ 952
ReleaseAutomationNativePointer ................................................ 953
ReleaseNativePointer .................................................................. 954
RemoteStopConnection ............................................................... 955
RemoteStopListening ................................................................... 956
RemoveDirectory ......................................................................... 957
Repair........................................................................................... 958
Replace ........................................................................................ 959

xvi
 Contents

ReplaceText ................................................................................. 961

Reset............................................................................................ 962
ResetArgElements ....................................................................... 965
ResetDataColors.......................................................................... 966
Resize .......................................................................................... 968
Resolve_Initial_References ......................................................... 969
RespondRemote .......................................................................... 971
Restart.......................................................................................... 972
ResumeTransaction ..................................................................... 973
Reverse........................................................................................ 975
RevertToSelf ................................................................................ 976
RGB ............................................................................................. 977
Right............................................................................................. 979
RightTrim...................................................................................... 980
RollbackOnly ................................................................................ 981
RollbackTransaction..................................................................... 983
Round........................................................................................... 985
RoutineList ................................................................................... 986
Run............................................................................................... 987
Save ............................................................................................. 989
SaveAs......................................................................................... 991
SaveDocument............................................................................. 999
Scroll .......................................................................................... 1000
ScrollNextPage .......................................................................... 1001
ScrollNextRow............................................................................ 1002
ScrollPriorPage .......................................................................... 1003
ScrollPriorRow ........................................................................... 1004
ScrollToRow ............................................................................... 1005
Second ....................................................................................... 1006
SecondsAfter.............................................................................. 1007
Seek ........................................................................................... 1008
SelectedColumn......................................................................... 1010
SelectedIndex ............................................................................ 1011
SelectedItem .............................................................................. 1012
SelectedLength .......................................................................... 1013
SelectedLine .............................................................................. 1014
SelectedPage............................................................................. 1015
SelectedStart.............................................................................. 1016
SelectedText .............................................................................. 1017
SelectionRange.......................................................................... 1019
SelectItem .................................................................................. 1020
SelectObject............................................................................... 1024
SelectTab ................................................................................... 1025
SelectText .................................................................................. 1026

xvii
Contents

SelectTextAll .............................................................................. 1030

SelectTextLine ........................................................................... 1031
SelectTextWord.......................................................................... 1032
Send........................................................................................... 1034
SeriesCount ............................................................................... 1036
SeriesName ............................................................................... 1037
SetAbort ..................................................................................... 1038
SetAlignment.............................................................................. 1041
SetArgElement ........................................................................... 1042
SetAutomationLocale ................................................................. 1043
SetAutomationPointer ................................................................ 1045
SetAutomationTimeout............................................................... 1047
SetColumn ................................................................................. 1049
SetComplete .............................................................................. 1050
SetConnect ................................................................................ 1053
SetData ...................................................................................... 1054
SetDataDDE............................................................................... 1056
SetDataPieExplode .................................................................... 1058
SetDataStyle .............................................................................. 1060
SetDropHighlight ........................................................................ 1066
SetDynamicParm ....................................................................... 1067
SetFirstVisible ............................................................................ 1069
SetFocus .................................................................................... 1070
SetGlobalProperty...................................................................... 1071
SetItem....................................................................................... 1072
SetLevelPictures ........................................................................ 1076
SetLibraryList ............................................................................. 1078
SetMask ..................................................................................... 1080
SetMessage ............................................................................... 1082
SetMicroHelp.............................................................................. 1083
SetNull........................................................................................ 1084
SetOverlayPicture ...................................................................... 1085
SetParagraphSetting .................................................................. 1087
SetPicture................................................................................... 1088
SetPointer .................................................................................. 1089
SetPosition ................................................................................. 1090
SetProfileString .......................................................................... 1093
SetRange ................................................................................... 1095
SetRecordSet............................................................................. 1096
SetRedraw ................................................................................. 1098
SetRemote ................................................................................. 1100
SetResultSet .............................................................................. 1103
SetSeriesStyle............................................................................ 1104
SetSpacing................................................................................. 1111

xviii
 Contents

SetState ..................................................................................... 1112

SetTextColor .............................................................................. 1113
SetTextStyle............................................................................... 1114
SetTimeout................................................................................. 1115
SetToolbar.................................................................................. 1117
SetToolbarPos ........................................................................... 1119
SetTop........................................................................................ 1123
SetTraceFileName ..................................................................... 1124
SetTransPool ............................................................................. 1125
SharedObjectDirectory............................................................... 1127
SharedObjectGet ....................................................................... 1128
SharedObjectRegister................................................................ 1131
SharedObjectUnregister............................................................. 1132
Show .......................................................................................... 1133
ShowHeadFoot .......................................................................... 1134
ShowHelp................................................................................... 1135
ShowPopupHelp ........................................................................ 1137
Sign ............................................................................................ 1138
SignalError ................................................................................. 1139
Sin .............................................................................................. 1141
Sleep .......................................................................................... 1142
Sort............................................................................................. 1143
SortAll......................................................................................... 1145
Space ......................................................................................... 1146
Sqrt............................................................................................. 1147
Start............................................................................................ 1148
StartHotLink ............................................................................... 1155
StartServerDDE ......................................................................... 1157
State........................................................................................... 1159
StepIt.......................................................................................... 1161
Stop............................................................................................ 1162
StopHotLink................................................................................ 1163
StopListening ............................................................................. 1164
StopServerDDE.......................................................................... 1165
String.......................................................................................... 1166
String_To_Object ....................................................................... 1171
SuspendTransaction .................................................................. 1174
SyntaxFromSQL......................................................................... 1176
SystemRoutine........................................................................... 1179
TabPostEvent............................................................................. 1180
TabTriggerEvent ........................................................................ 1181
Tan ............................................................................................. 1182
Text ............................................................................................ 1183
TextLine ..................................................................................... 1184

xix
Contents

Time ........................................................................................... 1185

Timer .......................................................................................... 1188
ToAnsi ........................................................................................ 1190
Today ......................................................................................... 1191
Top ............................................................................................. 1192
TotalColumns ............................................................................. 1193
TotalItems .................................................................................. 1194
TotalSelected ............................................................................. 1195
ToUnicode.................................................................................. 1196
TraceBegin................................................................................. 1197
TraceClose................................................................................. 1199
TraceDisableActivity................................................................... 1200
TraceEnableActivity ................................................................... 1202
TraceEnd.................................................................................... 1204
TraceError .................................................................................. 1205
TraceOpen ................................................................................. 1206
TraceUser .................................................................................. 1208
TriggerEvent............................................................................... 1209
TriggerPBEvent .......................................................................... 1211
Trim ............................................................................................ 1213
Truncate ..................................................................................... 1214
TrustVerify.................................................................................. 1215
TypeOf ....................................................................................... 1218
Uncheck ..................................................................................... 1220
Undo........................................................................................... 1222
UnitsToPixels ............................................................................. 1223
UpdateLinksDialog ..................................................................... 1224
Upper ......................................................................................... 1226
UpperBound ............................................................................... 1227
Which ......................................................................................... 1229
WordCap .................................................................................... 1231
WorkSpaceHeight ...................................................................... 1232
WorkSpaceWidth ....................................................................... 1234
WorkSpaceX .............................................................................. 1235
WorkSpaceY .............................................................................. 1236
Write........................................................................................... 1237
Year............................................................................................ 1238
Yield ........................................................................................... 1239

xx
About This Book

Subject This book describes syntax and usage information for the PowerScript
language, including variables, expressions, statements, events, and
functions.
Audience This book is for programmers who will be using PowerBuilder to build
client/server, multitier, and Web applications.
Two volumes The printed version of this book is divided into two volumes:
Volume Contents
Volume 1 Chapters 1-9
Volume 2 Chapter 10 (PowerScript Functions)

xxi
PART 1 PowerScript Topics
CH A PTE R 1 Language Basics

About this chapter This chapter describes general elements and conventions of PowerScript.
Contents
Topic Page
Comments 4
Identifier names 6
Labels 8
Special ASCII characters 9
NULL values 11
Reserved words 13
Pronouns 14
Statement continuation 18
Statement separation 20
White space 21

3
Comments

Comments
Description You can use comments to document your scripts and prevent statements within
a script from executing. There are two methods.
Syntax Double-slash method
Code // Comment
Slash-and-asterisk method
/* Comment */
Usage Here is how to use each method:
Method Marker Can use to Note
Double // Designate all text on the line Cannot extend to multiple
slash to the right of the marker as a lines
comment
Slash and /*...*/ Designate the text between Can extend over multiple
asterisk the markers as a comment lines (multiline comments do
Nest comments not require a continuation
character)
Can be nested

Adding comment markers

In the PowerScript and Function painters, you can use the Comment Selection
button (or select Edit>Comment Selection from the menu bar) to comment out
the line containing the cursor or a selected group of lines.

For information about adding comments to objects and library entries, see the
PowerBuilder User’s Guide.
Examples Double-slash method
// This entire line is a comment.
// This entire line is another comment.

amt = qty * cost // Rest of the line is comment.

// The following statement was commented out so that it

// would not execute.
// SetNull(amt)

4
 Chapter 1 Language Basics

Slash-and-asterisk method
/* This is a single-line comment. */

/* This comment starts here,

continues to this line,
and finally ends here. */

A = B + C /* This comment starts here.

/* This is the start of a nested comment.
The nested comment ends here. */
The first comment ends here. */ + D + E + F

5
Identifier names

Identifier names
Description You use identifiers to name variables, labels, functions, windows, controls,
menus, and anything else you refer to in scripts.
Syntax Rules for identifiers:
• Must start with a letter or an _ (underscore)
• Cannot be reserved words (see "Reserved words" on page 13)
• Can have up to 40 characters but no spaces
• Are case insensitive (PART, Part, and part are identical)
• Can include any combination of letters, numbers, and these special
characters:
- Dash
_ Underscore
$ Dollar sign
# Number sign
% Percent sign
Usage By default, PowerBuilder allows you to use dashes in all identifiers, including
in variable names in a script. This means that when you use the subtraction
operator or the -- operator in a script, you must surround it with spaces. If you
do not, PowerBuilder interprets the expression as an identifier name.
If you want to disallow dashes in variable names in scripts, you can change the
setting of the Allow Dashes in Identifiers option in the script editor’s property
sheet. This way you do not have to surround the subtraction operator and the
decrement assignment shortcut (--) with spaces.

Be careful
If you disallow dashes and have previously used dashes in variable names, you
will get errors the next time you compile.

Examples Valid identifiers

ABC_Code
Child-Id
FirstButton
response35
pay-before%deductions$
ORDER_DATE
Actual-$-amount
Part#

6
 Chapter 1 Language Basics

Invalid identifiers
2nd-quantity // Does not start with a letter
ABC Code // Contains a space
Child’sId // Contains invalid special character

7
Labels

Labels
Description You can include labels in scripts for use with GOTO statements.
Syntax Identifier :
Usage A label can be any valid identifier. You can enter it on a line by itself above the
statement or at the start of the line before the statement.
For information about the GOTO statement, see GOTO on page 141. For
information about valid identifiers, see "Identifier names" on page 6.
Examples On a line by itself above the statement
FindCity:
IF city=cityname[1] THEN ...
At the start of the line before the statement
FindCity: IF city=cityname[1] THEN ...

8
 Chapter 1 Language Basics

Special ASCII characters

Description You can include special ASCII characters in strings. For example, you may
want to include a tab in a string to ensure proper spacing or a bullet to indicate
a list item. The tilde character (~) introduces special characters. The tab is one
of the common ASCII characters that can be entered by typing a tilde followed
by a single keystroke. The bullet must be entered by typing a tilde followed by
the the decimal, hexadecimal, or octal ASCII value that represents it.
Syntax Follow these guidelines:
In this To specify Enter
category this this More information
Common Newline ~n
ASCII
characters
Tab ~t
Vertical tab ~v
Carriage return ~r
Formfeed ~f
Backspace ~b
Double quote ~"
Single quote ~’
Tilde ~~
Any Decimal ~### ### = a 3-digit number from 000 to 255
ASCII
character
Hexadecimal ~h## ## = a 2-digit hexadecimal number from
01 to FF
Octal ~o### ### = a 3-digit octal number from 000 to
377

Examples Entering ASCII characters Here is how to use special characters in strings:

String Description
"dog~n" A string containing the word dog followed by a newline
character
"dog~tcat~ttiger" A string containing the word dog, a tab character, the word cat,
another tab character, and the word tiger

9
Special ASCII characters

Using decimal, hexadecimal, and octal values Here is how to indicate a

bullet (•) in a string by using the decimal, hexadecimal, and octal ASCII values:
Value Description
"~249" The ASCII character with decimal value 249
"~hF9" The ASCII character with hexadecimal value F9
"~o371" The ASCII character with octal value 371

10
 Chapter 1 Language Basics

NULL values
Description NULL means undefined or unknown. It is not the same as an empty string or
zero or a date of 0000-00-00. For example, NULL is neither 0 nor not 0.
Typically, you work with NULL values only with respect to database values.
Usage Initial values for variables Although PowerBuilder supports NULL values
for all variable data types, it does not initialize variables to NULL. Instead,
when a variable is not set to a specific value when it is declared, PowerBuilder
sets it to the default initial value for the data type—for example, zero for a
numeric value, FALSE for boolean, and the empty string ("") for a string.
NULL variables A variable can become NULL if one of the following
occurs:
• A NULL value is read into it from the database. If your database supports
NULL, and a SQL INSERT or UPDATE statement sends a NULL to the
database, it is written to the database as NULL and can be read into a
variable by a SELECT or FETCH statement.

NULL in a variable
When a NULL value is read into a variable, the variable remains NULL
unless it is changed in a script.

• The SetNull function is used in a script to set the variable explicitly to

NULL. For example:
string city // city is an empty string.
SetNull(city) // city is set to NULL.
NULLs in functions and expressions Most functions that have a NULL
value for any argument return NULL. Any expression that has a variable with
a NULL value results in NULL.
A boolean expression that is NULL is considered undefined and therefore NOT
TRUE.
Testing for NULL To test whether a variable or expression is NULL, use the
IsNull function. You cannot use an equal sign (=) to test for NULL.
Valid This statement shows the correct way to test for NULL:
IF IsNull(a) THEN ...
Invalid This statement shows the incorrect way to test for NULL:
IF a = NULL THEN ...

11
NULL values

Examples Example 1 None of the following statements make the computer beep (the
variable nbr is set to NULL, so each statement evaluates to NOT TRUE):
int Nbr
// Set Nbr to NULL.
SetNull(Nbr)
IF Nbr =1 THEN Beep(1)
IF Nbr <> 1 THEN Beep(1)
IF NOT (Nbr = 1) THEN Beep(1)
Example 2 In this IF...THEN statement, the boolean expression evaluates to
NOT TRUE, so the ELSE is executed:
int a
SetNull(a)
IF a = 1 THEN
MessageBox("Value", "a = 1")
ELSE
MessageBox("Value", "a = NULL")
END IF
Example 3 This example is a more useful application of a NULL boolean
expression than Example 2. It displays a message if no control has focus. When
no control has focus, GetFocus returns a NULL object reference, the boolean
expression evaluates to NOT TRUE, and the ELSE is executed:
IF GetFocus( ) THEN
. . . // Some processing
ELSE
MessageBox("Important", "Specify an option!")
END IF

12
 Chapter 1 Language Basics

Reserved words
The words PowerBuilder uses internally are called reserved words and cannot
be used as identifiers. If you use a reserved word as an identifier, you get a
compiler warning. Reserved words that are marked with an asterisk (*) can be
used as function names.
alias event not static
and* execute of step
autoinstantiate exit on subroutine
call external open* super
case false or system
catch fetch parent systemread
choose finally post* systemwrite
close* first prepare then
commit for prior this
connect forward private throw
constant from privateread throws
continue function privatewrite to
create* global procedure trigger
cursor goto protected true
declare halt protectedread try
delete if protectedwrite type
describe* immediate prototypes until
descriptor indirect public update*
destroy insert readonly updateblob
disconnect into ref using
do intrinsic return variables
dynamic is rollback while
else last rpcfunc with
elseif library select within
end loop selectblob _debug
enumerated next shared

The PowerBuilder system class also includes private variables that cannot be
used as identifiers. If you use a private variable as an identifier, you get an
informational message and should rename your identifier.

13
Pronouns

Pronouns
Description PowerScript has pronouns that allow you to make a general reference to an
object or control. When you use a pronoun, the reference remains correct even
if the name of the object or control changes.
Syntax These are the pronouns:
• Parent pronoun
• This pronoun
• Super pronoun
Usage You can use pronouns in function and event scripts wherever you would use an
object’s name. For example, you can use a pronoun to:
• Cause an event in an object or control
• Manipulate or change an object or control
• Obtain or change the setting of a property
The individual pronouns Each pronoun has a specific meaning and use:

This pronoun In a script for a Refers to the

This Window, custom user object, Object or control itself
menu, application object, or
control
Parent Control in a window Window containing the control
Control in a custom user Custom user object containing the
object control
Menu Item in the menu on the level
above the current menu
Super Descendent object or control Parent
Descendent window or user Immediate ancestor of the window
object or user object
Control in a descendent Immediate ancestor of the
window or user object control’s parent window or user
object

ParentWindow property You can use the ParentWindow property of the

Menu object like a pronoun in Menu scripts. It identifies the window that the
menu is associated with when your program is running. For more information,
see the PowerBuilder User’s Guide.
The rest of this section describes the individual pronouns in detail.

14
 Chapter 1 Language Basics

Parent pronoun
Description Parent in a PowerBuilder script refers to the object that contains the current
object.
Usage You can use the pronoun Parent in scripts for:
• Controls in windows
• Custom user objects
• Menus
Where you use Parent determines what it references:
Window controls When you use Parent in a script for a control (such as a
CommandButton), Parent refers to the window that contains the control.
User object controls When you use Parent in a script for a control in a
custom user object, Parent refers to the user object.
Menus When you use Parent in a menu script, Parent refers to the menu item
on the level above the menu the script is for.
Examples Window controls If you include this statement in the script for the Clicked
event in a CommandButton within a window, clicking the button closes the
window containing the button:
Close(Parent)
If you include this statement in the script for the CommandButton, clicking the
button displays a horizontal scrollbar within the window (sets the HScrollBar
property of the window to TRUE):
Parent.HScrollBar = TRUE
User object controls If you include this statement in a script for the Clicked
event for a CheckBox in a user object, clicking the checkbox hides the user
object:
Parent.Hide( )
If you include this statement in the script for the CheckBox, clicking the
checkbox disables the user object (sets the Enabled property of the user object
to FALSE):
Parent.Enabled = FALSE
Menus If you include this statement in the script for the Clicked event in the
menu item Select All under the menu item Select, clicking Select All disables
the menu item Select:
Parent.Disable( )

15
Pronouns

If you include this statement in the script for the Clicked event in the menu item
Select All, clicking Select All checks the menu item Select:
Parent.Checked = TRUE

This pronoun
Description The pronoun This in a PowerBuilder script refers to the window, user object,
menu, application object, or control that owns the current script.
Usage Why include This Using This allows you to make ownership explicit. This
statement refers to the current object’s X property:
This.X = This.X + 50
When optional but helpful In the script for an object or control, you can
refer to the properties of the object or control without qualification. But it is
good programming practice to include This to make the script clear and easy to
read.
When required There are some circumstances when you must use This.
When a global or local variable has the same name as an instance variable,
PowerBuilder finds the global or local variable first. Qualifying the variable
with This allows you to refer to the instance variable instead of the global
variable.

EAServer restriction
You cannot use This to pass arguments in EAServer components.

Examples Example 1 This statement in a script for a menu places a checkmark next to
the menu selection:
This.Check( )
Example 2 In this function call, This passes a reference to the object
containing the script:
ReCalc(This)
Example 3 If you omit This, x in the following statement refers to a local
variable x if there is one defined (the script adds 50 to the variable x, not to the
X property of the control). But it refers to the object’s X property if there is no
local variable:
x = x + 50

16
 Chapter 1 Language Basics

Example 4 Use This to ensure that you refer to the property. For example, the
following statement in the script for the Clicked event for a CommandButton
means that clicking the button changes the horizontal position of the button
(changes the button’s X property):
This.x = This.x + 50

Super pronoun
Description When you write a PowerBuilder script for a descendant object or control, you
can call scripts written for any ancestor. You can directly name the ancestor in
the call, or you can use the reserved word Super to refer to the immediate
ancestor.
Usage Whether to use Super If you are calling an ancestor function, you only need
to use Super if the descendant has a function with the same name and the same
arguments as the ancestor function. Otherwise, you would simply call the
function with no qualifiers.
Restrictions for Super You cannot use Super to call scripts associated with
controls in the ancestor window. You can only use Super in an event or function
associated with a direct descendant of the ancestor whose function is being
called. Otherwise, the compiler returns a syntax error.
To call scripts associated with controls, use the CALL statement.
See the discussion of CALL on page 127.
Examples Example 1 This example calls the ancestor function wf_myfunc (presumably
the descendant also has a function called wf_myfunc):
Super::wf_myfunc(myarg1, myarg2)
This example has to be part of a script or function in the descendent window,
not one of the window’s controls. For example, if it is in the Clicked event of
a button on the descendent window, you get a syntax error when the script is
compiled.

Supplying arguments
Be certain to supply the correct number of arguments for the ancestor function.

Example 2 This example in a CommandButton script calls the Clicked script

for the CommandButton in the immediate ancestor window or user object:
Super::EVENT Clicked()

17
Statement continuation

Statement continuation
Description Although you typically put one statement on each line, you occasionally need
to continue a statement to more than one line. The statement continuation
character is the ampersand (&).
Syntax Start of statement &
more statement &
end of statement
The ampersand must be the last nonwhite character on the line (or the compiler
considers it part of the statement).
For information about white space, see "White space" on page 21.
Usage You do not use a continuation character for:
• Continuing comments Do not use a continuation character to continue
a comment. The continuation character is considered part of the comment
and is ignored by the compiler.
• Continuing SQL statements You do not need a continuation character
to continue a SQL statement. In PowerBuilder, SQL statements always
end with a semicolon (;), and the compiler considers everything from the
start of a SQL statement to a semicolon to be part of the SQL statement. A
continuation character in a SQL statement is considered part of the
statement and usually causes an error.
Examples Continuing a quoted string

One way You can continue a quoted string by simply placing an ampersand
in the middle of the string and continuing the string on the next line:
IF Employee_District = "Eastern United States and&
Eastern Canada" THEN ...
Note that any white space (such as tabs and spaces) before the ampersand and
at the beginning of the continued line is part of the string.
A problem This statement uses only the ampersand to continue the quoted
string in the IF...THEN statement to another line; for readability, a tab has been
added to indent the second line. The compiler includes the tab in the string,
which may result in an error:
IF Employee_District = "Eastern United States and&
Eastern Canada" THEN ...

18
 Chapter 1 Language Basics

A better way A better way to continue a quoted string is to enter a quotation

mark before the continuation character (’& or "&, depending on whether the
string is delimited by single or double quotation marks) at the end of the first
line of the string and a plus sign and a quotation mark (+’ or +") at the start of
the next line. This way you do not inadvertently include unwanted characters
(such as tabs or spaces) in the string literal:
IF Employee_District = "Eastern United States and "&
+" Eastern Canada" THEN ...
(The examples in the PowerBuilder documentation use this method to
continue quoted strings.)
Continuing a variable name Do not split a line by inserting the continuation
character within a variable name. This causes an error. This statement fails,
because the continuation character splits the variable name (Quantity):
Total-Cost = Price * Quan&
tity + (Tax + Shipping)

19
Statement separation

Statement separation
Description Although you typically put one statement on each line, you occasionally want
to combine multiple statements on a single line. The statement separation
character is the semicolon (;).
Syntax Statement1; statement2
Examples The following line contains three short statements:
A = B + C; D = E + F; Count = Count + 1

20
 Chapter 1 Language Basics

White space
Description Blanks, tabs, formfeeds, and comments are forms of white space. The compiler
treats white space as a delimiter and does not consider the number of white
space characters.
Usage White space in string literals The number of white space characters is
preserved when they are part of a string literal (enclosed in single or double
quotation marks).
Dashes in identifiers Unless you have prohibited the use of dashes in
identifiers (see "Identifier names" on page 6), you must surround a dash used
as a minus sign with spaces. Otherwise, PowerBuilder considers the dash part
of a variable name:
Order - Balance // Subtracts Balance from Order
Order-Balance // A variable named Order-Balance
Examples Example 1 Here the spaces and the comment are white space, so the compiler
ignores them:
A + B /*Adjustment factor */+C
Example 2 Here the spaces are within a string literal, so the compiler does
not ignore them:
"The value of A + B is:"

21
White space

22
CH A PTE R 2 Data Types

About this chapter This chapter describes the PowerScript data types.
Contents
Topic Page
Standard data types 24
Any data type 29
System object data types 32
Enumerated data types 33
PowerBuilder data types in EAServer 34

23
Standard data types

Standard data types

The data types The standard data types in PowerBuilder are the familiar data types that are
used in many programming languages, including char, integer, decimal, long,
and string. In PowerScript, you use these data types when you declare variables
or arrays.
These are the standard PowerScript data types:
Blob Integer or Int
Boolean Long
Char or character Real
Date String
DateTime Time
Decimal or Dec UnsignedInteger, UnsignedInt, or UInt
Double UnsignedLong or ULong

Blob Binary large object. Used to store an unbounded amount of data (for example,
generic binary, image, or large text such as a word-processing document).
Boolean Contains TRUE or FALSE.
Char or character A single ASCII character.
If you have character-based data that you will want to parse in an application,
you might want to define it as an array of type char. Parsing a char array is
easier and faster than parsing strings. If you will be passing character-based
data to external functions, you may want to use char arrays instead of strings.
For more information about passing character-based data to external functions,
see Application Techniques. For information about data type conversion when
assigning strings to chars and vice versa, see "String and char data types in
PowerBuilder" on page 78.
Using literals To assign a literal value, enclose the character in either single
or double quotation marks. For example:
char c
c = ’T’
c = "T"
Date The date, including the full year (1000 to 3000), the number of the month (01
to 12), and the day (01 to 31).
Using literals To assign a literal value, separate the year, month, and day
with hyphens. For example:
1992-12-25 // December 25, 1992

24
 Chapter 2 Data Types

1995-02-06 // February 6, 1995

DateTime The date and time in a single data type, used only for reading and writing
DateTime values from and to a database. To convert DateTime values to data
types that you can use in PowerBuilder, use:
• The Date(datetime) function to convert a DateTime value to a
PowerBuilder date value after reading from a database
• The Time(datetime) function to convert a DateTime value to a
PowerBuilder time value after reading from a database
• The DateTime (date, time) function to convert a date and (optional) time
to a DateTime before writing to a DateTime column in a database.
PowerBuilder supports microseconds in the database interface for any DBMS
that supports microseconds.
Decimal or Dec Signed decimal numbers with up to 18 digits. You can place the decimal point
anywhere within the 18 digits—for example, 123.456,
0.000000000000000001 or 12345678901234.5678.
Using literals To assign a literal value, use any number with a decimal point
and no exponent. The plus sign is optional (95 and +95 are the same). For
numbers between zero and one, the zero to the left of the decimal point is
optional (for example, 0.1 and .1 are the same). For whole numbers, zeros to
the right of the decimal point are optional (32.00, 32.0, and 32. are all the
same). For example:
12.34 0.005 14.0 -6500 +3.5555
Double A signed floating-point number with 15 digits of precision and a range from
2.2250738585073E-308 to 1.79769313486231E+308.
Integer or Int 16-bit signed integers, from -32768 to +32767.
Using literals To assign a literal value, use any whole number (positive,
negative, or zero). The leading plus sign is optional (18 and +18 are the same).
For example:
1 123 1200 +55 -32
Long 32-bit signed integers, from -2,147,483,648 to +2,147,483,647.
Using literals Use literals as for integers, but longer numbers are permitted.

Long long data type

EAServer supports a 64-bit integer data type. PowerBuilder does not support
64-bit integers.

25
Standard data types

Real A signed floating-point number with six digits of precision and a range from
1.175495E-38 to 3.402822E+38.
Using literals To assign a literal value, use a decimal value, followed by E,
followed by an integer; no spaces are allowed. The decimal number before the
E follows all the conventions specified above for decimal literals. The leading
plus sign in the exponent (the integer following the E) is optional (3E5 and
3E+5 are the same). For example:
2E4 2.5E78 +6.02E3 -4.1E-2
-7.45E16 7.7E+8 3.2E-45
String Any ASCII character with variable length (0 to 2,147,483,647).
Most of the character-based data in your application, such as names, addresses,
and so on, will be defined as strings. PowerScript provides many functions that
you can use to manipulate strings, such as a function to convert characters in a
string to uppercase and functions to remove leading and trailing blanks.
For more information about passing character-based data to external functions,
see Application Techniques. For information about data type conversion when
assigning strings to chars and vice versa, see "String and char data types in
PowerBuilder" on page 78.
Using literals To assign a literal value, enclose as many as 1024 characters
in either single or double quotes, including a string of zero length or an empty
string. For example:
string s1
s1 = ’This is a string’
s1 = "This is a string"
You can embed a quotation mark in a string literal if you enclose the literal with
the other quotation mark. For example:
string s1
s1 = "Here’s a string."
results in the string Here’s a string.
You can also use a tilde (~) to embed a quotation mark in a string literal. For
example:
string s1 = ’He said, "It~’s good!"’
Complex nesting When you nest a string within a string that is nested in
another string, you can use tildes to tell the parser how to interpret the quotation
marks. Each pass through the parser strips away the outermost quotes and
interprets the character after each tilde as a literal. Two tildes become one tilde,
and tilde-quote becomes the quote alone.

26
 Chapter 2 Data Types

Example 1 This string has two levels of nesting:

"He said ~"she said ~~~"Hi ~~~" ~" "
The first pass results in:
He said "she said ~"Hi ~" "
The second pass results in:
she said "Hi"
The third pass results in:
Hi
Example 2 A more probable example is a string for the Modify function that
sets a DataWindow property. The argument string often requires complex
quotation marks (because you must specify one or more levels of nested
strings). To figure out the quotation marks, consider how PowerBuilder will
parse the string. The following string is a possible argument for the Modify
function; it mixes single and double quotes to reduce the number of tildes:
"bitmap_1.Invert=’0~tIf(empstatus=~~’A~~’,0,1)’"
The double quotes tell PowerBuilder to interpret the argument as a string. It
contains the expression being assigned to the Invert property, which is also a
string, so it must be quoted. The expression itself includes a nested string, the
quoted A. First PowerBuilder evaluates the argument for Modify and assigns
the single-quoted string to the Invert property. In this pass through the string, it
converts two tildes to one. The string assigned to Invert becomes:
’0[tab]If(empstatus=~’A~’,0,1)’
Finally, PowerBuilder evaluates the property’s expression, converting tilde-
quote to quote, and sets the bitmap’s colors accordingly.
Example 3 There are many ways to specify quotation marks for a particular
set of nested strings. The following expressions for the Modify function all
have the same end result:
"emp.Color = ~"0~tIf(stat=~~~"a~~~",255,16711680)~""
"emp.Color = ~"0~tIf(stat=~~’a~~’,255,16711680)~""
"emp.Color = ’0~tIf(stat=~~’a~~’,255,16711680)’"
"emp.Color = ~"0~tIf(stat=’a’,255,16711680)~""
Rules for quotation marks and tildes When nesting quoted strings, the
following rules of thumb may help:
• A tilde tells the parser that the next character should be taken as a literal,
not a string terminator

27
Standard data types

• Pairs of single quotes ( ' ) can be used in place of pairs of tilde double
quotes (~")
• Pairs of tilde tilde single quotes (~~’) can be used in place of pairs of triple
tilde double quotes (~~~")
Time The time in 24-hour format, including the hour (00 to 23), minute (00 to 59),
second (00 to 59), and fraction of second (up to six digits), with a range from
00:00:00 to 23:59:59:999999.
PowerBuilder supports microseconds in the database interface for any DBMS
that supports microseconds.
Using literals The time in 24-hour format, including the hour (00 to 23),
minute (00 to 59), second (00 to 59), and fraction of second (up to six digits),
with a range from 00:00:00 to 23:59:59.999999. You separate parts of the time
with colons—except for fractional sections, which should be separated by a
decimal point. For example:
21:09:15 // 15 seconds after 9:09 pm
06:00:00 // Exactly 6 am
10:29:59 // 1 second before 10:30 am
10:29:59.9 // 1/10 sec before 10:30 am
UnsignedInteger, 16-bit unsigned integers, from 0 to 65,535.
UnsignedInt, or UInt
UnsignedLong or 32-bit unsigned integers, from 0 to 4,294,967,295.
ULong

28
 Chapter 2 Data Types

Any data type

General information PowerBuilder also supports the Any data type, which can hold any kind of
value, including standard data types, objects, structures, and arrays. A variable
whose type is Any is a chameleon data type—it takes the data type of the value
assigned to it.

Do not use Any in EAServer component definition

The PowerBuilder Any data type is specific to PowerScript and is not
supported in the IDL of an EAServer component. CORBA has a data type
called Any that can assume any legal IDL type at runtime, but it is not
semantically equivalent to the PowerBuilder Any type. You must exclude the
PowerBuilder Any data type from the component interface definition, but you
can use it within the component.

Declarations and You declare Any variables just as you do any other variable.
assignments
You assign data to Any variables with standard assignment statements. You can
assign an array to a simple Any variable. You can also declare an array of Any
variables, where each element of the array can have a different data type.
After you assign a value to an Any variable, you can test the variable with the
ClassName function and find out the actual data type:
any la_spreadsheetdata
la_spreadsheetdata = ole_1.Object.cells(1,1).value
CHOOSE CASE ClassName(la_spreadsheetdata)
CASE "integer"
...
CASE "string"
...
END CHOOSE
These rules apply to Any assignments:
• You can assign anything into an Any variable.
• You must know the content of an Any variable to make assignments from
the Any variable to a compatible data type.
Restrictions If the value of a simple Any variable is an array, you can’t access the elements
of the array until you assign the value to an array variable of the appropriate
data type. This restriction does not apply to the opposite case of an array of Any
variables—you can access each Any variable in the array.

29
Any data type

If the value of an Any variable is a structure, you can’t use dot notation to
access the elements of the structure until you assign the value to a structure of
the appropriate data type.
After a value has been assigned to an Any variable, it can’t be converted back
to a generic Any variable without a data type. Even if you set it to NULL, it
retains the data type of the assigned value until you assign another value.
Operations and You can perform operations on Any variables as long as the data type of the
expressions data in the Any variable is appropriate to the operator. If the data type isn’t
appropriate to the operator, an execution error occurs.
For example, if instance variables ia_1 and ia_2 contain numeric data, this
statement is valid:
any la_3
la_3 = ia_1 - ia_2
If ia_1 and ia_2 contain strings, you can use the concatenation operator:
any la_3
la_3 = ia_1 + ia_2
However, if ia_1 contained a number and ia_2 contained a string, you would
get an execution error.
Data type conversion functions PowerScript data type conversion
functions accept Any variables as arguments. When you call the function, the
Any variable must contain data that can be converted to the specified type.
For example, if ia_any contains a string, you can assign it to a string variable:
ls_string = ia_any
If ia_any contains a number that you want to convert to a string, you can call
the String function:
ls_string = String(ia_any)
Other functions If a function’s prototype does not allow Any as a data type
for an argument, you cannot use an Any variable without a conversion
function, even if it contains a value of the correct data type. When you compile
the script, you will get compiler errors such as Unknown function or Function
not found.

For example, the argument for the Len function refers to a string column in a
DataWindow, but the expression itself has a type of Any:
IF Len(dw_notes.Object.Notes[1]) > 0 THEN // Invalid

30
 Chapter 2 Data Types

This will work because the string value of the Any expression is explicitly
converted to a string:
IF Len(String(dw_notes.Object.Notes[1])) > 0 THEN
Expressions whose data type is Any Expressions that access data whose
type is unknown when the script is compiled have a data type of Any. These
expressions include expressions or functions that access data in an OLE object
or a DataWindow object:
myoleobject.application.cells(1,1).value
dw_1.Object.Data[1,1]
dw_1.Object.Data.empid[99]
The objects these expressions point to can change so that the type of data being
accessed changes too.
Expressions that refer to DataWindow data can return arrays and structures and
arrays of structures as Any variables. For best performance, you should assign
the DataWindow expression to the appropriate array or structure without using
an intermediate Any variable.
Overusing the Any Do not use Any variables as a substitute for selecting the correct data type in
data type your scripts. There are two reasons for this:
• At execution time, using Any variables is slow PowerBuilder must
do much more processing to determine data types before it can make an
assignment or perform an operation involving Any variables. In particular,
an operation performed many times in a loop will suffer greatly if you use
Any variables instead of variables of the appropriate type.
• At compile time, using Any variables removes a layer of error
checking from your programming The PowerBuilder compiler makes
sure data types are correct before code gets executed. With Any variables,
errors that can be caught by the compiler are not found until the code is
run.

31
System object data types

System object data types

Objects as data types System object data types are specific to PowerScript. You view a list of all the
system objects by selecting the System tab in the Browser.
In building PowerBuilder applications, you manipulate objects such as
windows, menus, CommandButtons, ListBoxes, and graphs. Internally,
PowerBuilder defines each of these kinds of objects as a data type. Usually you
don’t need to concern yourself with these objects as data types—you simply
define the objects in a PowerBuilder painter and use them.
But sometimes you need to understand how PowerBuilder maintains its system
objects in a hierarchy of data types. For example, when you need to define
instances of a window, you will define variables whose data type is window.
When you need to create an instance of a menu to pop up in a window, you will
define a variable whose data type is menu.
PowerBuilder maintains its system objects in a class hierarchy. Each type of
object is a class. The classes form an inheritance hierarchy of ancestors and
descendants.
Examples All the classes shown in the Browser are actually data types that you can use in
your applications. You can define variables whose type is any class.
For example, to define window and menu variables, you could code:
window mywin
menu mymenu
If you have a series of buttons in a window and for some reason need to keep
track of one of them (such as the last one clicked), you could declare a variable
of type CommandButton and assign it the appropriate button in the window:
// Instance variable in a window
commandbutton LastClicked
// In Clicked event for a button in the window.
// Indicates that the button was the last one
// clicked by the user.
LastClicked = This
Because it is a CommandButton, the LastClicked variable has all the properties
of a CommandButton. After the last assignment above, LastClicked’s
properties have the same values as the most recently clicked button in the
window.
To learn more about working with instances of objects through data types, see
"About objects" on page 84.

32
 Chapter 2 Data Types

Enumerated data types

About enumerated Like the system object data types, enumerated data types are specific to
data types PowerScript. Enumerated data types are used in two ways:
• As arguments in functions
• To specify the properties of an object or control
You can list all the enumerated data types and their values by selecting the
Enumerated tab in the Browser.
You cannot create your own enumerated data types. As an alternative, you can
declare a set of constant variables and assign them initial values. See
"Declaring constants" on page 49.
A variable of one of the enumerated data types can be assigned a fixed set of
values. Values of enumerated data types always end with an exclamation point
(!).
For example, the enumerated data type Alignment, which specifies the
alignment of text, can be assigned one of the following three values: Center!,
Left!, and Right!:
mle_edit.Alignment=Right!

Incorrect syntax
Do not enclose an enumerated data type value in quotation marks or you will
receive a compiler error.

Advantages of Enumerated data types have the following advantage over standard data types:
enumerated types when an enumerated data type is required, the compiler checks the data and
makes sure it is the correct type. For example, if you set an enumerated data
type variable to any other data type or to an incorrect value, the compiler will
not allow it.

33
PowerBuilder data types in EAServer

PowerBuilder data types in EAServer

All EAServer component interfaces are defined in standard CORBA IDL. This
table lists the predefined data types used in Jaguar Manager, the equivalent
CORBA IDL types, and the PowerBuilder data types that they map to.
Jaguar Manager CORBA IDL PowerBuilder
Integer (16-bit) Short Integer
Integer (32-bit) Long Long
Integer (64-bit) Long long —
Boolean Boolean Boolean
Float Float Real
Double Double Double
String String String
Binary BCD::Binary Blob
Decimal BCD::Decimal Decimal
Money BCD::Money Decimal
Date MJD::Date Date
Time MJD::Time Time
Timestamp MJD::Timestamp DateTime
ResultSet TabularResults::ResultSet ResultSet
ResultSets TabularResults::ResultSets ResultSets
Void Void None

34
CH A PTE R 3 Declarations

About this chapter This chapter explains how to declare variables, constants, and arrays and
refer to them in scripts, and how to declare remote procedure calls (RPCs)
and external functions that reside in dynamic link libraries (DLLs).
Contents
Topic Page
Declaring variables 36
Declaring constants 49
Declaring arrays 50
Declaring external functions 60
Declaring DBMS stored procedures as remote procedure calls 67
(RPCs)

35
Declaring variables

Declaring variables
General information Before you use a variable in a PowerBuilder script, you must declare it (give it
a data type and a name).
A variable can be a standard data type, a structure, or an object. Object data
types can be system objects as displayed in the Browser or they can be objects
you have defined by deriving them from those system object types. For most
variables, you can assign it a value when you declare it. You can always assign
it a value within a script.

Where to declare variables

Scope You determine the scope of a PowerScript variable by selecting where you
declare it. Instance variables have additional access keywords that restrict
specific scripts from accessing the variable.
These are the four scopes of variables.
Scope Description
Global Accessible anywhere in the application. It is independent of
any object definition
Instance Belongs to an object and is associated with an instance of
that object (you can think of it as a property of the object).
Instance variables have access keywords that determine
whether scripts of other objects can access them
Instance variables can belong to the application object, a
window, a user object, or a menu
Shared Belongs to an object definition and exists across all
instances of the object. Shared variables retain their value
when an object is closed and opened again
Shared variables are always private. They are accessible
only in scripts for the object and for controls associated
with the object
Shared variables can belong to the application object, a
window, a user object, or a menu
Local A temporary variable that is accessible only in the script in
which you define it. When the script is finished, the
variable constant ceases to exist

Global declarations Global variables can be defined in the Script view of the Application, Window,
User Object, Function, or Menu painters:

36
 Chapter 3 Declarations

• Select Declare from the first dropdown listbox in the Script view
• Select Global Variables in the second dropdown listbox of the Script view
• Type the declaration in the scripting area of the Script view
Instance and shared Instance and shared variables belong to particular objects: windows, user
declarations objects, menus, or the application object. Before you can declare them, you
must open the object in its painter. Then you must:
• Select Declare from the first dropdown listbox in the Script view
• Select Instance Variables or Shared Variables in the second dropdown
listbox of the Script view
• Type the declaration in the scripting area of the Script view
Local declarations You declare local variables for an object or control in the script for that object
or control.
Declaring SQL You can also declare SQL cursors that are global, shared, instance, or local.
cursors Open a specific script or select a variable declaration scope in the Script view
and type the DECLARE SQL statement or select Paste SQL from the
PainterBar or popup menu.

About using variables

General information To use or set a variable’s value in a PowerBuilder script, you name the variable.
The variable must be known to the compiler—in other words, it must be in
scope.
You can use a variable anywhere you need its value—for example, as a
function argument or in an assignment statement.
How PowerBuilder When PowerBuilder executes a script and finds an unqualified reference to a
looks for variables variable, it searches for the variable in the following order:
1 A local variable
2 A shared variable
3 A global variable
4 An instance variable
As soon as PowerBuilder finds a variable with the specified name, it uses the
variable’s value.

37
Declaring variables

Referring to global To refer to a global variable, you specify its name in a script. However, if the
variables global variable has the same name as a local or shared variable, the local or
shared variable will be found first.
To refer to a global variable that is masked by a local or shared variable of the
same name, use the global scope operator (::) before the name:
::globalname
For example, this statement compares the value of local and global variables,
both named total:
IF total < ::total THEN ...
Referring to instance You can refer to an instance variable in a script if there is an instance of the
variables object open in the application. Depending on the situation, you may need to
qualify the name of the instance variable with the name of the object defining
it.
Using unqualified names You can refer to instance variables without
qualifying them with the object name in the following cases:
• For application-level variables, in scripts for the application object
• For window-level variables, in scripts for the window itself and in scripts
for controls in that window
• For user-object-level variables, in scripts for the user object itself and in
scripts for controls in that user object
• For menu-level variables, in scripts for a menu object, either the highest-
level menu or scripts for the menu objects included as items on the menu
For example, if w_emp has an instance variable EmpID, then you can reference
EmpID without qualification in any script for w_emp or its controls such as:
sle_id.Text = EmpID
Using qualified names In all other cases, you need to qualify the name of
the instance variable with the name of the object using dot notation:
object.instancevariable
(Of course, this requirement applies only to Public instance variables. You
cannot reference Private instance variables outside the object at all, qualified
or not.)
For example, to refer to the w_emp instance variable EmpID from a script
outside the window, you need to qualify the variable with the window name:
sle_ID.Text = w_emp.EmpID

38
 Chapter 3 Declarations

There is another situation in which references must be qualified. Suppose that

w_emp has an instance variable EmpID and that in w_emp there is a
CommandButton that declares a local variable EmpID in its Clicked script. In
that script you must qualify all references to the instance variable:
Parent.EmpID
Using pronouns as To avoid ambiguity when referring to variables, you might decide to always
name qualifiers use qualified names for object variables. Qualified names leave no doubt about
whether a variable is local, instance, or shared.
To write generic code but still use qualified names, you can use the pronouns
This and Parent to refer to objects. Pronouns keep a script general by allowing
you to refer to the object without naming it specifically.
Window variables in window scripts In a window script, use the pronoun
This to qualify the name of a window instance variable. For example, if a
window has an instance variable called index, then the following statements
are equivalent in a script for that window, as long as there is no local or global
variable named index:
index = 5
This.index = 5
Window variables in control scripts In a script for a control in a window,
use the pronoun Parent to qualify the name of a window instance variable—the
window is the parent of the control. In this example, the two statements are
equivalent in a script for a control in that window, as long as there is no local
or global variable named index:
index = 5
Parent.index = 5
Naming errors If there is a local or global variable with the name index, then
the unqualified name refers to the local or global variable. It is a programming
error if you meant to refer to the object variable. You will get an informational
message from the compiler if you use the same name for instance and global
variables.

Syntax of a variable declaration

Simple syntax In its simplest form, a PowerScript variable declaration requires only two parts:
the data type and the variable name:
datatype variablename

39
Declaring variables

Full syntax The full syntax allows you to specify access and an initial value. Arrays and
some data types, such as blobs and decimals, accept additional information:
{ access } datatype { { size } } { { precision } } variablename { = value }
{, variablename2 { = value2 } }
Parameter Description
access (For instance variables only) Keywords specifying the
(optional) access for the variable
For information, see "Access for instance variables" on
page 45
datatype The data type of the variable. You can specify a standard
data type, a system object, or a previously defined structure
For blobs and decimals, you can specify the size or
precision of the data by including an optional value in
brackets
{ size } (For blobs only) A number, enclosed in braces, specifying
(optional) the size in bytes of the blob. If { size } is omitted, the blob
has an initial size of zero and PowerBuilder adjusts its size
each time it is used during execution
If you enter a size that exceeds the declared length in a
script, PowerBuilder truncates the blob data
{ precision } (For decimals only) A number, enclosed in braces,
(optional) specifying the number of digits after the decimal point; if
you don’t specify a precision, the variable takes the
precision assigned to it in the script
variablename The name of the variable (must be a valid PowerScript
identifier, as described in "Identifier names" on page 6)
You can define additional variables with the same data type
by naming additional variable names, separated by
commas; each variable can have a value
value A literal or expression of the appropriate data type that will
(optional) be the initial value of the variable
Blobs cannot be initialized with a value
For information, see "Initial values for variables" on page
42

Examples Declaring instance variables

integer ii_total = 100 // Total shares
date id_date // Date shares were bought
Declaring a global variable
string gs_name

40
 Chapter 3 Declarations

Declaring shared variables

time st_process_start
string ss_process_name
Declaring local variables
string ls_city = "Boston"
integer li_count
Declaring blobs This statement declares ib_Emp_Picture a blob with an
initial length of zero. The length is adjusted when data is assigned to it:
blob ib_Emp_Picture
This statement declares ib_Emp_Picture a blob with a fixed length of 100
bytes:
blob{100} ib_Emp_Picture
Declaring decimals These statements declare shared variables sc_Amount
and sc_dollars_accumulated as decimal numbers with two digits after the
decimal point:
decimal{2} sc_Amount
decimal{2} sc_dollars_accumulated
This statement declares lc_Rate1 and lc_Rate2 as decimal numbers with four
digits after the decimal point:
dec{4} lc_Rate1, lc_Rate2
This statement declares lc_Balance as a decimal with zero digits after the
decimal point:
decimal{0} lc_Balance
This statement doesn’t specify the number of decimal places for lc_Result.
After the product of lc_Op1 and lc_Op2 is assigned to it, lc_Result has four
decimal places:
dec lc_Result
dec{2} lc_Op1, lc_Op2
lc_Result = lc_Op1 * lc_Op2

Data type of a variable

A PowerScript variable can be declared as one of the following data types:
• A standard data type (such as an integer or string).
• An object or control (such as a window or CommandButton).

41
Declaring variables

• An object or structure that you have defined (such as a window called

mywindow). An object you have defined must be in a library on the
application’s library search path when the script is compiled.

Variable names
General information In a well-planned application, standards determine how you will name your
PowerScript variables. Naming conventions make scripts easy to understand
and help you avoid name conflicts. A typical approach is to include a prefix
that identifies the scope and the data type of the variable. For example, a prefix
for an instance variable’s name typically begins with i (such as ii_count or
is_empname), a local integer variable’s name would be li_total and a global
integer variable’s name would be gi_total.
For information about naming conventions, see Application Techniques.
X and Y as variable Although you may think of x and y as typical variable names, in PowerBuilder
names they are also properties that specify an object’s onscreen coordinates. If you use
them as variables and forget to declare them, you will not get a compiler error.
PowerBuilder will assume you want to move the object, which may lead to
unexpected results in your application.

Initial values for variables

General information When you declare a PowerScript variable, you can accept the default initial
value or specify an initial value in the declaration.
Default values for If you do not initialize a variable when you declare it, PowerBuilder sets the
variables variable to the default value for its data type as follows:
For this variable data type PowerBuilder sets this default value
Blob A blob of 0 length; an empty blob
Char (or character) ASCII value 0
Boolean FALSE
Date 1900-01-01 (January 1, 1900)
DateTime 1900-01-01 00:00:00
Numeric (integer, long, decimal, real, 0
double, UnsignedInteger, and
UnsignedLong)
String Empty string ("")
Time 00:00:00 (midnight)

42
 Chapter 3 Declarations

Specifying a literal as To initialize a variable when you declare it, place an equal sign (=) and a literal
a initial value appropriate for that variable data type after the variable. For information about
literals for specific data types, see "Standard data types" on page 24.
This example declares li_count as an integer whose value is 5:
integer li_count=5
This example declares li_a and li_b as integers and initializes li_a to 5 and li_b
to 10:
integer li_a=5, li_b=10
This example initializes ls_method with the string "UPS":
string ls_method="UPS"
This example initializes ls_headers to three words separated by tabs:
string ls_headers = "Name~tAddress~tCity"
This example initializes li_a to 1 and li_c to 100, leaving li_b set to its default
value of zero:
integer li_a=1, li_b, li_c=100
This example declares ld_StartDate as a date and initializes it with the date Feb
1, 1993:
date ld_StartDate = 1993-02-01
Specifying an You can initialize a variable with the value of an existing variable or
expression as an expression, such as:
initial value
integer i = 100
integer j = i
When you do this, the second variable is initialized with the value of the
expression when the script is compiled. The initialization is not reevaluated
during execution.
If the expression’s value changes Because the expression’s value is set to
the variable when the script is compiled (not during execution) make sure the
expression is not one whose value is based on current conditions. If you want
to specify an expression whose value will be different when the application is
executed, do not initialize the variable in the declaration. For such values,
declare the variable and assign the value in separate statements.
Unwanted result In this declaration, the value of d is the date the script is
compiled:
date d_date = Today( )

43
Declaring variables

Wanted result In contrast, these statements result in d being set to the date the
application is run:
date d_date
d_date = Today( )
How shared variables When you use a shared variable in a script, the variable is initialized when the
are initialized first instance of the object is opened. When the object is closed, the shared
variable continues to exist until you exit the application. If you open the object
again without exiting the application, the shared variable will have the value it
had when you closed the object.
For example, if you set the shared variable Count to 20 in the script for a
window, then close the window, and then reopen the window without exiting
the application, Count will be equal to 20.

When using multiple instances of windows

If you have multiple instances of the window in the example above, Count will
be equal to 20 in each instance. Since shared variables are shared among all
instances of the window, changing Count in any instance of the window
changes it for all instances.

How instance When you define an instance variable for a window, menu, or application
variables are object, the instance variable is initialized when the object is opened. Its initial
initialized
value is the default value for its data type or the value specified in the variable
declarations.
When you close the object, the instance variable ceases to exist. If you open the
object again, the instance variable is initialized again.
When to use multiple instances of windows When you build a script for
one of multiple instances of a window, instance variables can have a different
value in each instance of the window. For example, to set a flag based on the
contents of the instance of a window, you would use an instance variable.
When to use shared variables instead Use a shared variable instead of an
instance variable if you need a variable that:
• Keeps the same value over multiple instances of an object
• Continues to exist after the object is closed

44
 Chapter 3 Declarations

Access for instance variables

Description The general syntax for declaring PowerScript variables (see "Syntax of a
variable declaration" on page 39) showed that you can specify access keywords
in a declaration for an instance variable. This section describes those keywords.
When you specify an access right for a variable, you are controlling the
visibility of the variable or its visibility access. Access determines which
scripts recognize the variable’s name.
For a specified access right, you can control operational access with modifier
keywords. The modifiers specify which scripts can read the variable’s value
and which scripts can change it.
Syntax { access-right } { readaccess } { writeaccess } datatype variablename
Parameter Description
access-right A keyword specifying where the variable’s name will be
(optional) recognized. Values are:
• PUBLIC — (Default) Any script in the application can
refer to the variable. In another object’s script, you use
dot notation to qualify the variable name and identify the
object it belongs to
• PROTECTED — Scripts for the object for which the
variable is declared and its descendants can refer to the
variable
• PRIVATE — Scripts for the object for which the
variable is declared can refer to the variable. You cannot
refer to the variable in descendants of the object
readaccess A keyword restricting the ability of scripts to read the
(optional) variable’s value. Values are:
• PROTECTEDREAD — Only scripts for the object and
its descendants can read the variable
• PRIVATEREAD — Only scripts for the object can read
the variable
When access-right is PUBLIC, you can specify either
keyword. When access-right is PROTECTED, you can
specify only PRIVATEREAD. You cannot specify a
modifier for PRIVATE access, because PRIVATE is already
fully restricted
If readaccess is omitted, any script can read the variable

45
Declaring variables

Parameter Description
writeaccess A keyword restricting the ability of scripts to change the
(optional) variable’s value. Values are:
• PROTECTEDWRITE — Only scripts for the object and
its descendants can change the variable
• PRIVATEWRITE — Only scripts for the object can
change the variable
When access-right is PUBLIC, you can specify either
keyword. When access-right is PROTECTED, you can
specify only PRIVATEWRITE. You cannot specify a
modifier for PRIVATE access, because PRIVATE is already
fully restricted
If writeaccess is omitted, any script can change the variable
datatype A valid data type. See "Syntax of a variable declaration" on
page 39
variablename A valid identifier. See "Syntax of a variable declaration" on
page 39

Usage Access modifiers give you more control over which objects have access to a
particular object’s variables. A typical use is to declare a public variable but
only allow the owner object to modify it:
public protectedwrite integer ii_count
You can also group declarations that have the same access by specifying the
access-right keyword as a label (see "Another format for access-right
keywords" next).
When you look at exported object syntax, you may see the access modifiers
SYSTEMREAD and SYSTEMWRITE. Only PowerBuilder can access
variables with these modifiers. You cannot refer to variables with these
modifiers in your scripts and functions and you cannot use these modifiers in
your own definitions.
Examples To declare these variables, select Declare>Instance Variables in the appropriate
painter.
These declarations use access keywords to control the scripts that have access
to the variables:
private integer ii_a, ii_n
public integer ii_Subtotal
protected integer ii_WinCount
This protected variable can only be changed by scripts of the owner object;
descendants of the owner can read it:

46
 Chapter 3 Declarations

protected privatewrite string is_label

These declarations have public access (the default) but can only be changed by
scripts in the object itself:
privatewrite real ir_accum, ir_current_data
This declaration defines an integer that only the owner objects can write or read
but whose name is reserved at the public level:
public privateread privatewrite integer ii_reserved
Private variable not recognized outside its object Suppose you have
defined a window w_emp with a private integer variable ii_int:
private integer ii_int
In a script you declare an instance of the window called w_myemp. If you refer
to the private variable ii_int, you get a compiler warning that the variable is not
defined (because the variable is private and is not recognized in scripts outside
the window itself):
w_emp w_myemp
w_myemp.ii_int = 1 // Variable not defined
Public variable with restricted access Suppose you have defined a
window w_emp with a public integer variable ii_int with write access restricted
to private:
public privatewrite integer ii_int
If you write the same script as above, the compiler warning will say that you
cannot write to the variable (the name is recognized because it is public, but
write access is not allowed):
w_emp w_myemp
w_myemp.ii_int = 1 // Cannot write to variable

Another format for access-right keywords

Description You can also group declarations of PowerScript variables according to access
by specifying the access-right keyword as a label. It appears on its own line,
followed by a colon (:).
Syntax access-right:
{ readaccess } { writeaccess } datatype variablename
{ access-right } { readaccess } { writeaccess } datatype variablename
{ readaccess } { writeaccess } datatype variablename

47
Declaring variables

Within a labeled group of declarations, you can override the access on a single
line by specifying another access-right keyword with the declaration. The
labeled access takes effect again on the following lines.
Examples In these declarations, the instance variables have the access specified by the
label that precedes them. Another private variable is defined at the end, where
private overrides the public label:
Private:
integer ii_a=10, ii_b=24
string is_Name, is_Address1
Protected:
integer ii_Units
double idb_Results
string is_Lname
Public:
integer ii_Weight
string is_Location="Home"
private integer ii_test
Some of these protected declarations have restricted write access:
Protected:
integer ii_Units
privatewrite double idb_Results
privatewrite string is_Lname

48
 Chapter 3 Declarations

Declaring constants
Description Any PowerScript variable declaration of a standard data type that can be
assigned an initial value can be a constant instead of a variable. To make it a
constant, include the keyword CONSTANT in the declaration and assign it an
initial value.
Syntax CONSTANT { access } datatype constname = value
Parameter Description
CONSTANT Declares a constant instead of a variable. The CONSTANT
keyword can be before or after the access keywords
access (For instance variables only) Keywords specifying the
(optional) access for the constant
For information, see "Access for instance variables" on
page 45
datatype A standard data type for the constant. For decimals, you can
include an optional value in brackets to specify the
precision of the data. Blobs cannot be constants
For information about PowerBuilder data types, see
"Standard data types" on page 24
constname The name of the constant (must be a valid PowerScript
identifier, as described in "Identifier names" on page 6)
value A literal or expression of the appropriate data type that will
be the value of the constant. The value is required
For information, see "Initial values for variables" on page
42

Usage When declaring a constant, an initial value is required. Otherwise, a compiler

error occurs. Assigning a value to a constant after it is declared (that is,
redefining a constant in a descendant object) also causes a compiler error.
Examples Although PowerScript is not case sensitive, these examples of local constants
use a convention of capitalizing constant names:
constant string LS_HOMECITY = "Boston"
constant real LR_PI = 3.14159265

49
Declaring arrays

Declaring arrays
Description An array is an indexed collection of elements of a single data type. In
PowerBuilder, an array can have one or more dimensions. One-dimensional
arrays can have a fixed or variable size; multidimensional arrays always have
a fixed size. Each dimension of an array can have 2,147,483,647 bytes of
elements.
Any simple variable declaration becomes an array when you specify brackets
after the variable name. For fixed-size arrays, you specify the sizes of the
dimensions inside those brackets.
Syntax { access } datatype variablename { d1, ..., dn } { = { valuelist } }
Parameter Description
access (For instance variables only) Keywords specifying the
(optional) access for the variable
For information, see "Access for instance variables" on
page 45
datatype The data type of the variable. You can specify a standard
data type, a system object, or a previously defined
structure
For decimals, you can specify the precision of the data by
including an optional value in brackets after datatype (see
"Syntax of a variable declaration" on page 39):
decimal {2} variablename [ ]
For blobs, fixed-length blobs within an array are not
supported. If you specify a size after datatype, it is ignored
variablename The name of the variable (name must be a valid
PowerScript identifier, as described in "Identifier names"
on page 6)
You can define additional arrays with the same data type
by naming additional variable names with brackets and
optional value lists, separated by commas

50
 Chapter 3 Declarations

Parameter Description
[ { d1, ..., dn } ] Brackets and (for fixed-size arrays) one or more integer
values (d1 through dn, one for each dimension) specifying
the sizes of the dimensions
For a variable-size array, which is always 1-dimensional,
specify brackets only
For more information on how variable-size arrays change
size, see "Size of variable-size arrays" on page 54
For a fixed-size array, the number of dimensions is
determined by the number of integers you specify and is
limited only by the amount of available memory
For fixed-size arrays, you can use TO to specify a range of
element numbers (instead of a dimension size) for one or
more of the dimensions. Specifying TO allows you to
change the lower bound of the dimension (upperbound
must be greater than lowbound):
[
d1lowbound TO d1upperbound {, ... ,
dnlowbound TO dnupperbound }
]
{ valuelist } A list of initial values for each position of the array. The
(optional) values are separated by commas and the whole list is
enclosed in braces. The number of values cannot be greater
than the number of positions in the array. The data type of
the values must match datatype

Examples These declarations create variable-size arrays:

integer li_stats[ ] // Array of integers.
decimal {2} ld_prices[ ] // Array of decimals with
// 2 places of precision.
blob lb_data[ ] // Array of variable-size
// blobs.
date ld_birthdays[ ] // Array of dates.
string ls_city[ ] // Array of strings.
// Each string can be
// any length.
This statement declares a variable-size array of decimal number (the
declaration does not specify a precision, so each element in the array takes the
precision of the value assigned to it):
dec lc_limit[ ]
Fixed arrays These declarations create fixed-size, 1-dimensional arrays:
integer li_TaxCode[3] // Array of 3 integers.

51
Declaring arrays

string ls_day[7] // Array of 7 strings.

blob ib_image[10] // Array of 10
// variable-size blobs.
dec{2} lc_Cost[10] // Array of 10 decimal
// numbers.
// Each value has 2 digits
// following the decimal
// point.
decimal lc_price[20] // Array of 20 decimal
// numbers.
// Each takes the precision
// of the value assigned.
Using TO to change array index values These fixed-size arrays use TO to
change the range of index values for the array:
real lr_Rate[2 to 5] // Array of 4 real numbers:
// Rate[2] through Rate[5]
integer li_Qty[0 to 2] // Array of 3 integers
string ls_Test[-2 to 2] // Array of 5 strings
integer li_year[76 to 96] // Array of 21 integers
string ls_name[-10 to 15] // Array of 26 strings
Incorrect declarations using TO In an array dimension, the second number
must be greater than the first. These declarations are invalid:
integer li_count[10 to 5] // INVALID: 10 is
// greater than 5
integer li_price[-10 to -20] // INVALID: -10
// is greater than -20
Arrays with two or more dimensions This declaration creates a 6-element,
2-dimensional integer array. The individual elements are li_score[1,1],
li_score[1,2], li_score[1,3], li_score[2,1], li_score[2,2], and li_score[2,3]:
integer li_score[2,3]
This declaration specifies that the indexes for the dimensions are 1 to 5 and 10
to 25:
integer li_RunRate[1 to 5, 10 to 25]
This declaration creates a 3-dimensional 45,000-element array:
long ll_days[3, 300, 50]
This declaration changes the subscript range for the second and third
dimension:
integer li_staff[100, 0 to 20, -5 to 5]

52
 Chapter 3 Declarations

More declarations of multidimensional arrays:

string ls_plant[3,10] // 2-dimensional array
// of 30 strings
dec{2} lc_rate[3,4] // 2-dimensional array of 12
// decimals with 2 digits
// after the decimal point
This declaration creates three decimal arrays:
decimal{3} lc_first[10],lc_second[15,5],lc_third[ ]

Values for array elements

General information PowerBuilder initializes each element of an array to the same default value as
its underlying data type. For example, in a newly declared integer array:
integer li_TaxCode[3]
the elements li_TaxCode[1], li_TaxCode[2], and li_TaxCode[3] are all
initialized to zero.
For information about default values for basic data types, see "Initial values for
variables" on page 42.
Simple array In a simple array, you can override the default values by initializing the
elements of the array when you declare the array. You specify the values in a
comma-separated list of values enclosed in braces. You don’t have to initialize
all the elements of the array, but you can’t initialize values in the middle or end
without initializing the first elements.
Multidimensional array In a multidimensional array, you still provide the values in a simple, comma-
separated list. When the values are assigned to array positions, the first
dimension is the fastest-varying dimension and the last dimension is the
slowest-varying. In other words, the values are assigned to array positions by
looping over all the values of the first dimension for each value of the second
dimension, then looping over all the values of the second dimension for each
value of the third, and so on.

Assigning values
You can assign values to an array after declaring it using the same syntax of a
list of values within braces:
integer li_Arr[]
Li_Arr = {1, 2, 3, 4}

53
Declaring arrays

Examples Example 1 This statement declares an initialized 1-dimensional array of

three variables:
real lr_Rate[3]={1.20, 2.40, 4.80}
Example 2 This statement initializes a 2-dimensional array:
integer li_units[3,4] = {1,2,3, 1,2,3, 1,2,3, 1,2,3}
As a result:
Li_units[1,1], [1,2], [1,3], and [1,4] are all 1
Li_units[2,1], [2,2], [2,3], and [2,4] are all 2
Li_units[3,1], [3,2], [3,3], and [3,4] are all 3
Example 3 This statement initializes the first half of a 3-dimensional array:
integer li_units[3,4,2] = &
{1,2,3, 1,2,3, 1,2,3, 1,2,3}
As a result:
Li_units[1,1,1], [1,2,1], [1,3,1], and [1,4,1] are all 1
Li_units[2,1,1], [2,2,1], [2,3,1], and [2,4,1] are all 2
Li_units[3,1,1], [3,2,1], [3,3,1], and [3,4,1] are all 3
Li_units[1,1,2], [1,2,2], [1,3,2], and [1,4,2] are all 0
Li_units[2,1,2], [2,2,2], [2,3,2], and [2,4,2] are all 0
Li_units[3,1,2], [3,2,2], [3,3,2], and [3,4,2] are all 0

Size of variable-size arrays

General information A variable-size array consists of a variable name followed by square brackets
but no number. PowerBuilder defines the array elements by use at execution
time (subject only to memory constraints). Only 1-dimensional arrays can be
variable-size arrays.
Because you don’t declare the size, you can’t use the TO notation to change the
lower bound of the array. So the lower bound of a variable-size array is
always 1.

54
 Chapter 3 Declarations

Using arrays with a TO clause in EAServer components

When you generate a proxy for an EAServer component deployed from
PowerBuilder that contains an array that uses a TO clause, the proxy object
represents the range as a single value because CORBA IDL does not support
the TO clause. For example, Int ar1[5 TO 10] is represented as Int ar1[6], with
[6] representing the number of array elements. Client applications must declare
the array using a single value instead of a range.

How memory is Initializing elements of a variable-size array allocates memory for those
allocated elements. You specify initial values just as you do for fixed-size arrays, by
listing the values in braces. The following statement sets code[1] equal to 11,
code[2] equal to 242, and code[3] equal to 27. The array has a size of 3 initially,
but the size will change if you assign values to higher positions:
integer li_code[ ]={11,242,27}
For example, these statements declare a variable-size array and assigns values
to three array elements:
long ll_price[ ]
ll_price[100] = 2000
ll_price[50] = 3000
ll_price[110] = 5000
When these statements first execute, they allocate memory as follows:
• The statement ll_price[100]=2000 will allocate memory for 100 long
numbers ll_price[1] to ll_price[100], then assign 0 (the default for
numbers) to ll_price[1] through ll_price[99] and assign 2000 to
ll_price[100].
• The statement ll_price[50]=3000 will not allocate more memory but will
assign the value 3000 to the 50th element of the ll_price array.
• The statement ll_price[110]=5000 will allocate memory for 10 more long
numbers named ll_price[101] to ll_price[110] and then assign 0 (the
default for numbers) to ll_price[101] through ll_price[109] and assign
5000 to ll_price[110].

55
Declaring arrays

More about arrays

This section provides technical details about:
• Assigning one array to another
• Using arraylists to assign values to an array
• Errors that occur when addressing arrays

Assigning one array to another

General information When you assign one array to another, PowerBuilder uses the following rules
to map the values of one onto the other.
One-dimensional Assigning to an unbounded array The target array is the same as the
arrays source:
integer a[ ], b[ ]
a = {1,2,3,4}
b = a
Assigning to a bounded array If the source array is smaller, values from
the source array are copied to the target array and extra values are set to zero.
In this example, b[5] and b[6] are set to 0:
integer a[ ], b[6]
a = {1,2,3,4}
b = a
If the source array is larger, values from the source array are copied to the target
array until it is full (and extra values from the source array are ignored). In this
example, the array b has only the first three elements of a:
integer a[ ], b[3]
a = {1,2,3,4}
b = a
Multidimensional PowerBuilder stores multidimensional arrays in column major order, meaning
arrays the first subscript is the fastest varying—[1,1], [2,1], [3,1]).
When you assign one array to another, PowerBuilder linearizes the source
array in column major order, making it a 1-dimensional array. PowerBuilder
then uses the rules for 1-dimensional arrays (described above) to assign the
array to the target.
Not all array assignments are allowed, as described in the following rules.

56
 Chapter 3 Declarations

Assigning one multidimensional array to another If the dimensions of the

two arrays match, the target array becomes an exact copy of the source:
integer a[2,10], b[2,10]
a = b
If both source and target are multidimensional but do not have matching
dimensions, the assignment is not allowed and the compiler reports an error:
integer a[2,10], b[4,10]
a = b // Compiler error
Assigning a 1-dimensional array to a multidimensional array A 1-
dimensional array can be assigned to a multidimensional array. The values are
mapped onto the multidimensional array in column major order:
integer a[ ], b[2,2]
b = a
Multidimensional to 1-dimensional array A multidimensional array can
also be assigned to a 1-dimensional array. The source is linearized in column
major order and assigned to the target:
integer a[ ], b[2,2]
a = b
Examples Suppose you declare three arrays (a, b, and c). One (c) is unbounded and
1-dimensional; the other two (a and b) are multidimensional with different
dimensions:
integer c[ ], a[2,2], b[3,3] = {1,2,3,4,5,6,7,8,9}
Array b is laid out like this:

1 for b[1,1] 4 for b[1,2] 7 for b[1,3]

2 for b[2,1] 5 for b[2,2] 8 for b[2,3]

3 for b[3,1] 6 for b[3,2] 9 for b[3,3]

This statement causes a compiler error (because a and b have different

dimensions):
a = b // Compiler error
This statement explicitly linearizes b into c:
c = b
You can then assign the linearized version of the array to a:
a = c

57
Declaring arrays

The values in array a are laid out like this:

1 for a[1,1] 3 for a[1,2]

2 for a[2,1] 4 for a[2,2]

Initializing a with an arraylist produces the same result:

integer a[2,2] = {1,2,3,4}

Using arraylists to assign values to an array

General information In PowerBuilder, an arraylist is a list of values enclosed in braces used to
initialize arrays. An arraylist represents a 1-dimensional array, and its values
are assigned to the target array using the rules for assigning arrays described in
"Assigning one array to another" on page 56.
Examples In this declaration, a variable-size array is initialized with four values:
integer a[ ] = {1,2,3,4}
In this declaration, a fixed-size array is initialized with four values (the rest of
its values are zeros):
integer a[10] = {1,2,3,4}
In this declaration, a fixed-size array is initialized with four values (because the
array’s size is set at 4, the rest of the values in the arraylist are ignored):
integer a[4] = {1,2,3,4,5,6,7,8}
In this declaration, values 1, 2, and 3 are assigned to the first column and the
rest to the second column:
integer a[3,2] = {1,2,3,4,5,6}

1 4

2 5

3 6

If you think of a 3-dimensional array as having pages of rows and columns,

then the first column of the first page has the values 1 and 2, the second column
on the first page has 3 and 4, and the first column on the second page has 5
and 6.

58
 Chapter 3 Declarations

The second column on the second page has zeros:

integer a[2,2,2] = {1,2,3,4,5,6}

1 3 5 0

2 4 6 0

Errors that occur when addressing arrays

Fixed-size arrays In PowerBuilder, referring to array elements outside the declared size causes
an error during execution—for example:
int test[10]
test[11]=50 // This causes an execution error.
test[0]=50 // This causes an execution error.
int trial[5,10]
trial [6,2]=75 // This causes an execution error.
trial [4,11]=75 // This causes an execution error.
Variable-size arrays Assigning a value to an element of a variable-size array that is outside its
current values increases the array’s size—that is how the array works.
However, accessing a variable-size array above its largest assigned value or
below its lower bound causes an error during execution:
integer li_stock[ ]
li_stock[50]=200
// Establish array size 50 elements.
IF li_stock[51]=0 then Beep(1)
// This causes an execution error.
IF li_stock[0]=0 then Beep(1)
// This causes an execution error.

59
Declaring external functions

Declaring external functions

Description External functions are functions that are written in languages other than
PowerScript and stored in dynamic link libraries. On Windows, dynamic
libraries have the extension DLL. If you deploy a component written in
PowerBuilder to a UNIX server, the dynamic libraries it calls have the
extension .so, .sl, or .a, depending on the UNIX operating system. You can use
external functions that are written in any language that supports dynamic
libraries.
Before you can use an external function in a script, you must declare it. You
can declare two types of external functions:
• Global external functions These are available anywhere in the
application.
• Local external functions These are defined for a particular type of
window, menu, user object, or user-defined function. These functions are
part of the object’s definition and can always be used in scripts for the
object itself. You can also choose to make these functions accessible to
other scripts.
To understand how to declare and call an external function, see the
documentation from the developer of the external function library.
Syntax External function syntax Use the following syntax to declare an external
function:
{ access } FUNCTION returndatatype name ( { { REF } datatype1 arg1,
..., { REF } datatypen argn } ) LIBRARY "libname"
ALIAS FOR "extname"
External subroutine syntax You can also declare external subroutines
(which are the same as external functions except that they don’t return a value)
using this syntax:
{ access } SUBROUTINE name ( { { REF } datatype1 arg1, ...,
{ REF } datatypen argn } ) LIBRARY "libname"
ALIAS FOR "extname"
Parameter Description
access (Local external functions only) You can specify Public,
(optional) Protected, or Private to specify the access level of a local
external function (the default is Public)
For more information, see the section about specifying access
of local functions in "Usage" next

60
 Chapter 3 Declarations

Parameter Description
FUNCTION or A keyword specifying the type of call, which determines the
SUBROUTINE way return values are handled. If there is a return value, declare
it as a FUNCTION; if it returns nothing or returns VOID,
specify SUBROUTINE
returndatatype The data type of the value returned by the function
name The name of a function or subroutine that resides in a DLL
REF Specifies that you are passing by reference the argument that
follows REF. The function can store a value in arg that will be
accessible to the rest of the PowerBuilder script
datatype arg The data type and name of the arguments for the function or
subroutine. The list must match the definition of the function in
the DLL. Each datatype arg pair can be preceded by REF
For more information on passing arguments, see Application
Techniques
LIBRARY The LIBRARY keyword is followed by a string containing the
"libname" name of the dynamic library in which the function or
subroutine is stored. libname is a dynamic link library, which
is a file that usually has an extension DLL or EXE on
Windows. For components deployed to EAServer on UNIX,
the file has an extension of .so, .sl, or .a depending on the
operating system
ALIAS FOR Keywords followed by a string giving the name of the function
"extname" as defined in the dynamic library. If the name in the dynamic
(optional) library is not the name you want to use in your script or if the
name in the database is not a legal PowerScript name, you must
specify ALIAS FOR "extname" to establish the association
between the PowerScript name and the external name

Usage Specifying access of local functions When declaring a local external

function, you can specify its access level—which scripts have access to the
function:
Access
level Where you can use the local external function
Public Any script in the application
Private Scripts for events in the object for which the function is declared. You
cannot use the function in descendants of the object
Protected Scripts for the object for which the function is declared and its
descendants

Use of the access keyword with local external functions works the same as the
access-right keywords for instance variables.

61
Declaring external functions

Availability of the To be available to a PowerBuilder application running on any Windows

dynamic library during platform, the DLL must be in one of the following directories:
execution
• The current directory
• The Windows directory
• The Windows System subdirectory
• Directories on the DOS path
If you are deploying a PowerBuilder custom class user object as an EAServer
component, you must make sure any dynamic library it references is available
on the server. If you do not specify the location of the library when you declare
it, make sure it is installed in an accessible location. On a Windows server, the
DLL must be in the application path of the jagsrv executable file. On a UNIX
server, the location of the shared library must be listed in the server’s library
path environment variable (LD_LIBRARY_PATH on Solaris) or the library
must be in the lib directory of the Jaguar installation.
Examples In the examples application that comes with PowerBuilder, these external
functions are declared as local external functions in a user object called
u_external_function_win32. The scripts that call the functions are user object
functions, but since they are part of the same user object, you don’t need to use
object notation to call them.
Example 1 These declarations allow PowerBuilder to call the functions
required for playing a sound in the WINMM.DLL:
//playsound
FUNCTION boolean sndPlaySoundA (string SoundName,
uint Flags) LIBRARY "WINMM.DLL"
FUNCTION uint waveOutGetNumDevs () LIBRARY "WINMM.DLL"
A function called uf_playsound in the examples application provided with
PowerBuilder calls the external functions. Uf_playsound is called with two
arguments (as_filename and ai_option) that are passed through to
sndPlaySoundA. Values for ai_option are as defined in the Win32
documentation, as commented here:
//Options as defined in mmystem.h.
//These may be or’d together.
//#define SND_SYNC 0x0000
//play synchronously (default)
//#define SND_ASYNC 0x0001
//play asynchronously
//#define SND_NODEFAULT 0x0002
//don’t use default sound
//#define SND_MEMORY 0x0004

62
 Chapter 3 Declarations

//lpszSoundName points to a memory file

//#define SND_LOOP 0x0008
//loop the sound until next sndPlaySound
//#define SND_NOSTOP 0x0010
//don’t stop any currently playing sound

uint lui_numdevs

lui_numdevs = WaveOutGetNumDevs()
IF lui_numdevs > 0 THEN
sndPlaySoundA(as_filename,ai_option)
RETURN 1
ELSE
RETURN -1
END IF
Example 2 This is the declaration for the Win32 GetSysColor function:
FUNCTION ulong GetSysColor (int index) LIBRARY
"USER32.DLL"
This statement calls the external function. The meanings of the index argument
and the return value are specified in the Win32 documentation:
RETURN GetSysColor (ai_index)
Example 3 This is the declaration for the Win32 GetSysColor function:
FUNCTION int GetSystemMetrics (int index) LIBRARY
"USER32.DLL"
These statements call the external function to get the screen height and width:
RETURN GetSystemMetrics(1)
RETURN GetSystemMetrics(0)

Data types for external function arguments

When you declare an external function in PowerBuilder, the data types of the
arguments must correspond with the data types as declared in the function’s
source definition. This section documents the correspondence between data
types in external functions and data types in PowerBuilder. It also includes
information on byte alignment when passing structures by value.

63
Declaring external functions

Use the tables to find out what PowerBuilder data type to use in an external
function declaration. The PowerBuilder data type you select depends on the
data type in the source code for the function. The first column lists data types
in source code. The second column describes the data type so you know exactly
what it is. The third column lists the PowerBuilder data type you should use in
the external function declaration.
Boolean BOOL on Windows is 16-bit, signed. It is declared in PowerBuilder as
boolean.
Pointers
Data type in source
code Size, sign, precision PowerBuilder data type
* (any pointer) 32-bit pointer Long
char * Array of bytes of Blob
variable length

Windows 32-bit FAR pointers such as LPBYTE, LPDWORD, LPINT,

LPLONG, LPVOID, and LPWORD are declared in PowerBuilder as long data
types. HANDLE is defined as 32 bits unsigned and is declared in PowerBuilder
as an UnsignedLong.
Near-pointer data types (such as PSTR and NPSTR) are not supported in
PowerBuilder.
Characters and
strings Data type in source PowerBuilder data
code Size, sign, precision type
char 8 bits, signed Char
string 32-bit pointer to a null- String
terminated array of bytes
of variable length

The Windows 32-bit FAR pointer LPSTR is declared in PowerBuilder as

string.

Reference arguments
When you pass a string to an external function by reference, all memory
management is done in PowerBuilder. The string variable must be long enough
to hold the returned value. To ensure that this is true, first declare the string
variable and then use the Space function to fill the variable with blanks equal
to the maximum number of characters that you expect the function to return.

64
 Chapter 3 Declarations

Fixed-point values
Data type in source PowerBuilder data
code Size, sign, precision type
short 16 bits, signed Integer
unsigned short 16 bits, unsigned UnsignedInteger
int 32 bits, signed Long
unsigned int 32 bits, unsigned UnsignedLong
long 32 bits, signed Long
unsigned long 32 bits, unsigned UnsignedLong

The Windows definition WORD is declared in PowerBuilder as

UnsignedInteger and the Windows definition DWORD is declared as an
UnsignedLong. You cannot call external functions with return values or
arguments of type short.
Floating-point values
Data type in source PowerBuilder data
code Size, sign, precision type
float 32 bits, single precision Real
double 64 bits, double precision Double

PowerBuilder does not support 80-bit doubles on Windows.

Date and time The PowerBuilder data types date, DateTime, and time are structures and have
no direct equivalent for external functions in C.
Passing structures by You can pass PowerBuilder structures to external C functions as long as they
value have the same definitions and alignment as the structure’s components. The
DLL or shared library must be compiled using byte alignment, meaning no
padding is added to align fields within the structure.

Calling external functions

Global external In PowerBuilder, you call global external functions using the same syntax as
functions for calling user-defined global and system functions. As with other global
functions, global external functions can be triggered or posted but not called
dynamically.
Local external You call local functions using the same syntax as for calling object functions.
functions They can be triggered or posted and called dynamically.
For information For information, see "Syntax for calling PowerBuilder functions and events"
on page 113.

65
Declaring external functions

Defining source for external functions

You can use external functions written in any language that supports the
standard calling sequence for 32-bit platforms. If you’re calling functions on
Windows in libraries that you have written yourself, remember that you need
to export the functions. Depending on your compiler, you can do this in the
function prototype or in a linker definition (.DEF) file. For more information
about using external functions, see Application Techniques.

66
 Chapter 3 Declarations

Declaring DBMS stored procedures as remote

procedure calls (RPCs)
Description In PowerBuilder, you can use dot notation for calling non-result-set stored
procedures:
object.function
You can call database procedures in Sybase, Oracle, Informix, and other
ODBC databases with stored procedures.
RPCs provide support for Oracle PL/SQL tables and parameters that are
defined as both input and output. You can call overloaded procedures.
Applies to Transaction object
Syntax FUNCTION rtndatatype functionname ( { { REF } datatype1 arg1,...,
{ REF } datatypen argn } ) RPCFUNC { ALIAS FOR "spname" }
SUBROUTINE functionname ( { { REF } datatype1 arg1 , ...,
{ REF } datatypen argn } ) RPCFUNC { ALIAS FOR "spname" }
Argument Description
FUNCTION or A keyword specifying the type of call, which determines the
SUBROUTINE way return values are handled. If there is a return value, declare
it as a FUNCTION. If it returns nothing or returns VOID,
specify SUBROUTINE
rtndatatype In a FUNCTION declaration, the data type of the value
returned by the function
functionname The name of the database procedure as you will call it in
PowerBuilder. If the name in the DBMS is different, use
ALIAS FOR to associate the DBMS name with the
PowerBuilder name
REF Specifies that you are passing by reference the argument that
follows REF. The stored procedure can store a value in arg that
will be accessible to the rest of the PowerBuilder script
When you pass a string by reference, all memory management
is done in PowerBuilder. The string variable must be long
enough to hold the returned value. To ensure that this is true,
first declare the string variable and then use the Space function
to fill the variable with blanks equal to the maximum number
of characters that you expect the function to return.
datatype arg The data type and name of the arguments for the stored
procedure. The list must match the definition of the stored
procedure in the database. Each datatype arg pair can be
preceded by REF

67
Declaring DBMS stored procedures as remote procedure calls (RPCs)

Argument Description
RPCFUNC A keyword indicating that this declaration is for a stored
procedure in a DBMS, not an external function in a DLL
For information on declaring external functions, see
"Declaring external functions" on page 60
ALIAS FOR Keywords followed by a string naming the procedure in the
"spname" database. If the name in the database is not the name you want
(optional) to use in your script or if the name in the database is not a legal
PowerScript name, you must specify ALIAS FOR "spname" to
establish the association between the PowerScript name and
the database name

Usage If a function does not return a value (for example, it returns Void), specify the
declaration as a subroutine instead of a function.
RPC declarations are always associated with a transaction object. You declare
them as local external functions. The Declare Local External Functions dialog
has a Procedures button (if the connected database supports stored procedures),
which gives you access to a list of stored procedures in the database.
For more information, see Application Techniques.
Examples Example 1 This declaration of the GIVE_RAISE_PROC stored procedure is
declared in the User Object painter for a transaction object (the declaration
appears on one line):
FUNCTION double GIVE_RAISE(ref double SALARY) RPCFUNC
ALIAS FOR "GIVE_RAISE_PROC"
This code calls the function in a script:
double val = 20000
double rv
rv = SQLCA.give_raise(val)
Example 2 This declaration for the stored procedure SPM8 doesn’t need an
ALIAS FOR phrase, because the PowerBuilder and DBMS names are the
same:
FUNCTION integer SPM8(integer value) RPCFUNC
This code calls the SPM8 stored procedure:
int myresult
myresult = SQLCA.spm8(myresult)
IF SQLCA.sqlcode <> 0 THEN
messagebox("Error", SQLCA.sqlerrtext)
END IF

68
CH A PTE R 4 Operators and Expressions

About this chapter This chapter describes the operators supported in PowerScript and how to
use them in expressions.
Contents
Topic Page
Operators in PowerBuilder 70
Operator precedence in PowerBuilder expressions 75
Data type of PowerBuilder expressions 76

69
Operators in PowerBuilder

Operators in PowerBuilder
General information Operators perform arithmetic calculations; compare numbers, text, and
boolean values; execute relational operations on boolean values; and
concatenate strings and blobs.
Three types PowerScript supports three types of operators:
• Arithmetic operators for numeric data types
• Relational operators for all data types
• Concatenation operator for string data types

Operators used in DataWindow objects

The documentation for DataWindows describes how operators are used in
DataWindow expressions.

Arithmetic operators in PowerBuilder

Description These are the PowerBuilder arithmetic operators:
Operator Meaning Example
+ Addition Total=SubTotal+Tax
- Subtraction Price=Price–Discount
Unless you have prohibited the use of dashes in
identifier names, you must surround the minus
sign with spaces
* Multiplication Total=Quantity*Price
/ Division Factor=Discount/Price
^ Exponentiation Rank=Rating^2.5

Usage Operator shortcuts for assignments For information about shortcuts that
combine arithmetic operators with assignments (such as ++ and +=), see
Assignment on page 124.
Subtraction If the option Allow Dashes in Identifiers is checked on the
Script tab in the Options dialog box, you must always surround the subtraction
operator and the -- operator with spaces. Otherwise, PowerBuilder interprets
the expression as an identifier.
For information about dashes in identifiers, see "Identifier names" on page 6.

70
 Chapter 4 Operators and Expressions

Multiplication and division Multiplication and division are carried out to

full precision (16–18 digits). Decimal numbers are rounded (not truncated) on
assignment.
Calculation with NULL When you form an arithmetic expression that
contains a NULL value, the expression’s value is NULL.Thinking of NULL as
undefined makes this easier to understand.
For more information about NULL values, see "NULL values" on page 11.
Errors and overflows Division by zero, exponentiation of negative values,
and so on cause errors during execution.
Overflow of real, double, and decimal values causes errors during execution.
Overflow of signed or unsigned integers and longs causes results to wrap.
However, because integers are promoted to longs in calculations, wrapping
does not occur until the result is explicitly assigned to an integer variable.
For more information about type promotion, see "Data type of PowerBuilder
expressions" on page 76.
Examples Subtraction This statement always means subtract B from A:
A - B
If DashesInIdentifiers is set to 1, this statement means a variable named A-B,
but if DashesInIdentifiers is set to 0, it means subtract B from A:
A-B
Precision for division These examples show the values that result from
various operations on decimal values:
decimal {4} a,b,d,e,f
decimal {3} c
a = 20.0/3 // a contains 6.6667
b = 3 * a // b contains 20.0001
c = 3 * a // c contains 20.000
d = 3 * (20.0/3) // d contains 20.0000
e = Truncate(20.0/3, 4) // e contains 6.6666
f = Truncate(20.0/3, 5) // f contains 6.6667
Calculations with NULL When the value of variable c is NULL, the
following assignment statements all set the variable a to NULL:
integer a, b=100, c

SetNULL(c)

a = b+c // all statements set a to NULL

a = b - c

71
Operators in PowerBuilder

a = b*c
a = b/c
Overflow This example illustrates the value of the variable i after overflow
occurs:
integer i
i = 32767
i = i + 1 // i is now -32768

Relational operators in PowerBuilder

Description PowerBuilder uses relational operators in boolean expressions to evaluate two
or more operands. Logical operators can join relational expressions to form
more complex boolean expressions.
The result of evaluating a boolean expression is always TRUE or FALSE.
These are the relational and logical operators:
Operator Meaning Example
= Equals if Price=100 then Rate=.05
> Greater than if Price>100 then Rate=.05
< Less than if Price<100 then Rate=.05
<> Not equal if Price<>100 then Rate=.05
>= Greater than or equal if Price>=100 then Rate=.05
<= Less than or equal if Price<=100 then Rate=.05
NOT Logical negation if NOT Price=100 then Rate=.05
AND Logical and if Tax>3 AND Ship <5 then Rate=.05
OR Logical or if Tax>3 OR Ship<5 then Rate=.05

Usage Comparing strings When PowerBuilder compares strings, the comparison

is case sensitive. Trailing blanks are significant.
For information on comparing strings regardless of case, see the functions
Upper on page 1226 and Lower on page 761.
To remove trailing blanks, use the RightTrim function. To remove leading
blanks, use the LeftTrim function. To remove leading and trailing blanks, use
the Trim function. For information about these functions, see RightTrim on
page 980, LeftTrim on page 731, and Trim on page 1213.

72
 Chapter 4 Operators and Expressions

NULL value evaluations When you form a boolean expression that contains
a NULL value, the AND and OR operators behave differently. Thinking of
NULL as undefined (neither TRUE nor FALSE) makes the results easier to
calculate.
For more information about NULL values, see "NULL values" on page 11.
Examples Case-sensitive comparisons If you compare two strings with the same text
but different case, the comparison fails. But if you use the Upper or Lower
function, you can ensure that the case of both strings are the same so that only
the content affects the comparison:
City1="Austin"
City2="AUSTIN"
IF City1=City2 ... // Will return FALSE

City1="Austin"
City2="AUSTIN"
IF Upper(City1)=Upper(City2)... // Will return TRUE
Trailing blanks in comparisons In this example, trailing blanks in one
string cause the comparison to fail:
City1="Austin"
City2="Austin "
IF City1=City2 ... // Will return FALSE
Logical expressions with NULL values In this example, the expressions
involving the variable f, which has been set to NULL, have NULL values:
boolean d, e = TRUE, f
SetNull(f)
d = e and f // d is NULL
d = e or f // d is TRUE

Concatenation operator in PowerBuilder

Description The PowerBuilder concatenation operator joins the contents of two variables
of the same type to form a longer value. You can concatenate strings and blobs.
This is the concatenation operator:
Operator Meaning Example
+ Concatenate "cat " + "dog"

73
Operators in PowerBuilder

Examples Example 1. These examples concatenate several strings:

string Test
Test = "over" + "stock" // Test contains "overstock"
string Lname, Fname, FullName
FullName = Lname + ’, ’ + Fname
// FullName contains last name and first name,
// separated by a comma and space.
Example 2 This example shows how a blob can act as an accumulator when
reading data from a file:
integer i, fnum, loops
bflob tot_b, b
. . .
FOR i = 1 to loops
bytes_read = FileRead(fnum, b)
tot_b = tot_b + b
NEXT

74
 Chapter 4 Operators and Expressions

Operator precedence in PowerBuilder expressions

Order of precedence To ensure predictable results, all operators in a PowerBuilder expression are
evaluated in a specific order of precedence. When the operators have the same
precedence, PowerBuilder evaluates them left to right.
These are the operators in descending order of precedence:
Operator Purpose
() Grouping (see note below on overriding)
+, - Unary plus and unary minus (indicates positive or negative
number)
^ Exponentiation
*, / Multiplication and division
+, - Addition and subtraction; string concatenation
=, >, <, <=, >=, <> Relational operators
NOT Negation
AND Logical and
OR Logical or

How to override To override the order, enclose expressions in parentheses. This identifies the
group and order in which PowerBuilder will evaluate the expressions. When
there are nested groups, the groups are evaluated from the inside out.
For example, in the expression (x+(y*(a+b))), a+b is evaluated first. The sum
of a and b is then multiplied by y, and this product is added to x.

75
Data type of PowerBuilder expressions

Data type of PowerBuilder expressions

General information The data type of an expression is important when it is the argument for a
function or event. The expression’s data type must be compatible with the
argument’s definition. If a function is overloaded, the data type of the argument
determines which version of the function to call.
There are three types: numeric, string, and char data types.

Numeric data types in PowerBuilder

General information All numeric data types are compatible with each other.
What PowerBuilder PowerBuilder converts data types as needed to perform calculations and make
does assignments. When PowerBuilder evaluates a numeric expression, it converts
the data types of operands to data types of higher precedence according to the
operators and the data types of other values in the expression.

Data type promotion when evaluating numeric expressions

Order of precedence The PowerBuilder numeric data types are listed here in order of highest to
lowest precedence (the order is based on the range of values for each data type):
Double
Real
Decimal
UnsignedLong
Long
UnsignedInteger
Integer
Rules for type Data types of operands If operands in an expression have different data
promotion types, the value whose type has lower precedence is converted to the data type
with higher precedence.
Unsigned versus signed Unsigned has precedence over signed, so if one
operand is signed and the other is unsigned, both are promoted to the unsigned
version of the higher type. For example, if one operator is a long and another
UnsignedInteger, both are promoted to UnsignedLong.

76
 Chapter 4 Operators and Expressions

Operators The effects of operators on an expression’s data type are:

• +, -, * The minimum precision for addition, subtraction, and
multiplication calculations is long. Integer types are promoted to long
types before doing the calculation and the expression’s resulting data type
is, at a minimum, long. When operands have data types of higher
precedence, other operands are promoted to match based on the Data types
of operands rule above.
• / and ^ The minimum precision for division and exponentiation is
double. All types are promoted to double before doing the calculation, and
the expression’s resulting data type is double.
• Relational Relational operators do not cause promotion of numeric
types.
Data types of literals When a literal is an operand in an expression, its data type is determined by the
literal’s value. The data type of a literal affects the type promotion of the literal
and other operands in an expression.
The data type of Is
Integer literals (no decimal point or exponent) within the range Long
of longs
Integer literals beyond the range of longs UnsignedLong
Numeric literals with a decimal point (but no exponent) Decimal
Numeric literals with a decimal point and explicit exponent Double

Out of range
Integer literals beyond the range of UnsignedLong cause compiler errors.

Assignment and data types

General information Assignment is not part of expression evaluation. In an assignment statement,
the value of an expression is converted to the data type of the left-hand
variable. In the expression
c = a + b
the data type of a+b is determined by the data types of a and b. Then the result
is converted to the data type of c.
Overflow on Even when PowerBuilder performs a calculation at high enough precision to
assignment handle the results, assignment to a lower precision variable can cause overflow,
producing the wrong result.

77
Data type of PowerBuilder expressions

Example 1 Consider this code:

integer a = 32000, b = 1000
long d
d = a + b
The final value of d is 33000. The calculation proceeds like this:
Convert integer a to long
Convert integer b to long
Add the longs a and b
Assign the result to the long d
Because the variable d is a long, the value 33000 does not cause overflow.
Example 2 In contrast, consider this code with an assignment to an integer
variable:
integer a = 32000, b = 1000, c
long e
c = a + b
e = c
The resulting value of c and e is -32536. The calculation proceeds like this:
Convert integer a to long
Convert integer b to long
Add the longs a and b
Convert the result from long to integer and assign the result to c
Convert integer c to long and assign the result to e
The assignment to c causes the long result of the addition to be truncated,
causing overflow and wrapping. Assigning c to e cannot restore the lost
information.

String and char data types in PowerBuilder

General information There is no explicit char literal type.
String literals convert to type char using the following rules:
• When a string literal is assigned to a char variable, the first character of the
string literal is assigned to the variable. For example:
char c = "xyz"
results in the character x being assigned to the char variable c.

78
 Chapter 4 Operators and Expressions

• Special characters (such as newline, formfeed, octal, hex, and so on) can
be assigned to char variables using string conversion, such as:
char c = "~n"
String variables assigned to char variables also convert using these rules. A
char variable assigned to a string variable results in a one-character string.
Assigning strings to As with other data types, you can use arrays of chars. Assigning strings to char
char arrays arrays follows these rules:
• If the char array is unbounded (defined as a variable-size array), the
contents of the string are copied directly into the char array.
• If the char array is bounded and its length is less than or equal to the length
of the string, the string is truncated in the array.
• If the char array is bounded and its length is greater than the length of the
string, the entire string is copied into the array along with its zero
terminator. Remaining characters in the array are undetermined.
Assigning char arrays When a char array is assigned to a string variable, the contents of the array are
to strings copied into the string up to a zero terminator, if found, in the char array.
Using both strings and Expressions using both strings and char arrays promote the chars to strings
chars in an expression before evaluation. For example:
char c
. . .
if (c = "x") then
promotes the contents of c to a string before comparison with the string "x".
Using chars in All PowerScript functions that take strings also take chars and char arrays,
PowerScript functions subject to the conversion rules described above.

79
Data type of PowerBuilder expressions

80
CH A PTE R 5 Structures and Objects

About this chapter This chapter describes basic concepts for structures and objects and how
you define, declare, and use them in PowerScript.
Contents
Topic Page
About structures 82
About objects 84
Assignment for objects and structures 90

81
About structures

About structures
General information A structure is a collection of one or more variables (sometimes called
elements) that you want to group together under a single name. The variables
can have any data type, including standard and object data types and other
structures.
Defining structures When you define a structure in the PowerBuilder Structure painter or an object
painter (such as Window, Menu, or User Object), you are creating a structure
definition. To use the structure, you must declare it. When you declare it, an
instance of it is automatically created for you. When it goes out of scope, the
structure is destroyed.
For details about defining structures, see the PowerBuilder User’s Guide.
Declaring structures If you have defined a global structure in the Structure painter called
str_emp_data, you can declare an instance of the structure in a script or in an
object’s instance variables. If you define the structure in an object painter, you
can only declare instances of the structure in the object’s instance variables and
scripts.
This declaration declares two instances of the structure str_emp_data:
str_emp_data str_emp1, str_emp2
Referring to structure In scripts, you refer to the structure’s variables using dot notation:
variables
structurename.variable
These statements assign values to the variables in str_emp_data:
str_emp1.emp_id = 100
str_emp1.emp_lname = "Jones"
str_emp1.emp_salary = 200

str_emp2.emp_id = 101
str_emp2.emp_salary = str_emp1.salary * 1.05
Using structures as If the structure is declared as part of an object, you can qualify the structure
instance variables name using dot notation:
objectname.structurename.variable
Suppose that this declaration is an instance variable of the window
w_customer:
str_cust_data str_cust1

82
 Chapter 5 Structures and Objects

This statement in a script for the object refers to a variable of str_cust_data (the
pronoun This is optional, because the structure declaration is part of the
object):
This.str_cust1.name
This statement in a script for some other object qualifies the structure with the
window name:
w_customer.str_cust1.name

83
About objects

About objects
What an object is In object-oriented programming, an object is a self-contained module
containing state information and associated methods. Most entities in
PowerBuilder are objects: visual objects such as windows and controls on
windows, nonvisual objects such as transaction and error objects, and user
objects that you design yourself.
An object class is a definition of an object. You create an object’s definition in
the appropriate painter: Window, Menu, Application, Structure, or User Object
painter. In the painter, you add controls to be part of the object, specify initial
values for the object’s properties, define its instance variables and functions,
and write scripts for its events and functions.
An object instance is an occurrence of the object created during the execution
of your application. Your code instantiates an object when it allocates memory
for the object and defines the object based on the definition in the object class.
An object reference is your handle to the object instance. To interact with an
object, you need its object reference. You can assign an object reference to a
variable of the appropriate type.
System objects versus There are two categories of objects supported by PowerBuilder: system objects
user objects (also referred to as system classes) defined by PowerBuilder and user objects
you in define in painters.
System objects The PowerBuilder system objects or classes are inherited
from a base class PowerObject. The system classes are the ancestors of all the
objects you define. To see the system class hierarchy, look at the System tab in
the Browser.
User objects You can create user object class definitions in several painters:
Window, Menu, Application, Structure, and User Object painters. The objects
you define are inherited from one of the system classes or another of your
classes.
Some painters use many classes. In the Window and User Object painters, your
main definition is inherited from the window or user object class. The controls
you use are also inherited from the system class for that control.

84
 Chapter 5 Structures and Objects

About user objects

Two types There are two major types of user objects: visual and class.
Visual user objects A visual user object is a reusable control or set of controls that has a certain
behavior. There are three types—standard, custom, and external:
Visual user objects Description
Standard Inherited from a specific visual control. You can set
properties and write scripts so that the control is ready
for use
It has the same events and properties as the control it is
inherited from plus any that you add
Custom Inherited from the UserObject system class. You can
include many controls in the user object and write
scripts for their events
Each control in the user object has the same events and
properties as the controls from which they are inherited
plus any that you add
External A user object that displays a visual control defined in a
DLL. The control is not part of the PowerBuilder object
hierarchy. The DLL developer provides information for
setting style bits that control its presentation
Its events, functions, and properties are specified by the
developer of the DLL
An external user object is not the same as an OCX,
which you can put in an OLE control

Class user objects Class user objects consist of properties, functions, and sometimes events. They
have no visual component. There are two types—standard and custom:
Class user objects Description
Standard Inherits its definition from a nonvisual PowerBuilder
object, such as the Transaction or Error object. You can
add instance variables and functions
A few nonvisual objects have events—to write scripts
for these events, you have to define a class user object
Custom An object of your own design for which you define
instance variables, events, and functions in order to
encapsulate application-specific programming in an
object

For information on defining and using user objects, see the PowerBuilder
User’s Guide.

85
About objects

Instantiating objects
Classes versus Because of the way PowerBuilder object classes and instances are named, it’s
instances easy to think they are the same thing. For example, when you define a window
in the Window painter, you are defining an object class.
One instance When you open a window with the simplest format of the Open function, you
are instantiating an object instance. Both the class definition and the instance
have the same name. In your application, w_main is a global variable of type
w_main:
Open(w_main)
When you open a window this way, you can only open one instance of the
object.
Several instances If you want to open more than one instance of a window class, you need to
define a variable to hold each object reference:
w_main w_1, w_2
Open(w_1)
Open(w_2)
You can also open windows by specifying the class in the Open function:
window w_1, w_2
Open(w_1, "w_main")
Open(w_2, "w_main")
For class user objects, you always define a variable to hold the object reference
and then instantiate the object with the CREATE statement:
uo_emp_data uo_1, uo_2
uo_1 = CREATE uo_emp_data
uo_2 = CREATE uo_emp_data
You can have more than one reference to an object. You might assign an object
reference to a variable of the appropriate type. Or you might pass an object
reference to another object so that it can change or get information from the
object.
For more information about object variables and assignment, see "User objects
that behave like structures" on page 88.

86
 Chapter 5 Structures and Objects

Using ancestors and descendants

Descendent objects In PowerBuilder, an object class can be inherited from another class. The
inherited or descendent object has all the instance variables, events, and
functions of the ancestor. You can augment the descendant by adding more
variables, events, and functions. If you change the ancestor, even after editing
the descendant, the descendant incorporates the changes.
Instantiating When you instantiate a descendent object, PowerBuilder also instantiates all its
ancestor classes. You do not have programmatic access to these ancestor
instances, except in a few limited ways, such as when you use the scope
operator to access an ancestor version of a function or event script.

Garbage collection
What garbage The PowerBuilder garbage collection mechanism checks memory
collection does automatically for unreferenced and orphaned objects and removes any it finds,
thus taking care of most memory leaks. You can use garbage collection to
destroy objects instead of explicitly destroying them using the DESTROY
statement. This lets you avoid execution-time errors that occur when you
destroy an object that was being used by another process or had been passed by
reference to a posted event or function.
When garbage Garbage collection occurs:
collection occurs
• When a reference is removed from an object A reference to an
object is any variable whose value is the object. When the variable goes
out of scope, or when it is assigned a different value, PowerBuilder
removes a reference to the object, counts the remaining references, and
destroys the object if no references remain.
• When the garbage collection interval is exceeded When
PowerBuilder completes the execution of a system-triggered event, it
makes a garbage collection pass if the set interval between garbage
collection passes has been exceeded. The default interval is 0.5 seconds.
The garbage collection pass removes any objects and classes that cannot
be referenced, including those containing circular references (otherwise
unreferenced objects that reference each other).

87
About objects

Posting events and functions

When you post an event or function and pass an object reference, PowerBuilder
adds an internal reference to the object to prevent it from being collected
between the time of the post and the actual execution of the event or function.
This reference is removed when the event or function is executed.

Exceptions to garbage There are a few objects that are prevented from being collected:
collection
• Visual objects Any object that is visible on your screen is not collected
because when the object is created and displayed on your screen, an
internal reference is added to the object. When any visual object is closed
it is explicitly destroyed.
• Timing objects Any Timing object that is currently running is not
collected because the Start function for a Timing object adds an internal
reference. The Stop function removes the reference.
• Shared objects Registered shared objects are not collected because the
SharedObjectRegister function adds an internal reference.
SharedObjectUnregister removes the internal reference.
Controlling when Garbage collection occurs automatically in PowerBuilder, but you can use the
garbage collection functions GarbageCollect, GarbageCollectGetTimeLimit, and
occurs
GarbageCollectSetTimeLimit to force immediate garbage collection or to
change the interval between reference count checks. By setting the interval
between garbage collection passes to a very large number, you can effectively
turn off garbage collection.

User objects that behave like structures

General information In PowerBuilder, a nonvisual user object can provide functionality similar to
that of a structure. Its instance variables form a collection similar to the
variables for the structure. In scripts, you use dot notation to refer to the user
object’s instance variables, just as you do for structure variables.
Advantages of user The user object can include functions and its own structure definitions, and it
objects allows you to inherit from an ancestor class. None of this is possible with a
structure definition.

88
 Chapter 5 Structures and Objects

Memory allocation Memory allocation is different for user objects and structures. An object
differences variable is a reference to the object. Declaring the variable does not allocate
memory for the object. After you declare it, you must instantiate it with a
CREATE statement. Assignment for a user object is also different (described
in the next section).
Autoinstantiated If you want a user object that has methods and inheritance but want the memory
objects allocation of a structure, you can define an autoinstantiated object.
You do not have to create and destroy autoinstantiated objects. Like structures,
they are created when they are declared and destroyed when they go out of
scope. However, because assignment for autoinstantiated objects behaves like
structures, the copies made of the object can be a drawback.
To make a custom class user object autoinstantiated, select the Autoinstantiate
checkbox on the user object’s property sheet.

89
Assignment for objects and structures

Assignment for objects and structures

General information In PowerBuilder, assignment for objects is different from assignment for
structures or autoinstantiated objects:
• When you assign one structure to another, the whole structure is copied so
that there are two copies of the structure.
• When you assign one object variable to another, the object reference is
copied so that both variables point to the same object. There is only one
copy of the object.
Assignment for Declaring a structure variable creates an instance of that structure:
structures
str_emp_data str_emp1, str_emp2 // Two structure instances

When you assign a structure to another structure, the whole structure is copied
and a second copy of the structure data exists:
str_emp1 = str_emp2
The assignment copies the whole structure from one structure variable to the
other. Each variable is a separate instance of the structure str_emp_data.
Restriction on assignment If the structures have different definitions, you
cannot assign one to another, even if they have the same set of variable
definitions.
For example, this assignment is not allowed:
str_emp str_person1
str_cust str_person2
str_person2 = str_person1 // Not allowed
For information about passing structures as function arguments, see "Passing
arguments to functions and events" on page 108.
Assignment for Declaring an object variable declares an object reference:
objects
uo_emp_data uo_emp1, uo_emp2 // Two object references
Using the CREATE statement creates an instance of the object:
uo_emp1 = CREATE uo_emp_data
When you assign one object variable to another, a reference to the object
instance is copied. Only one copy of the object exists:
uo_emp2 = uo_emp1 // Both point to same object instance

90
 Chapter 5 Structures and Objects

Ancestor and descendent objects Assignments between ancestor and

descendent objects occur in the same way, with an object reference being
copied to the target object.
Suppose that uo_emp_data is an ancestor user object of uo_emp_active and
uo_emp_inactive.
Declare variables of the ancestor type:
uo_emp_data uo_emp1, uo_emp2
Create an instance of the descendant and store the reference in the ancestor
variable:
uo_emp1 = CREATE USING "uo_emp_active"
Assigning uo_emp1 to uo_emp2 makes both variables refer to one object that
is an instance of the descendant uo_emp_active:
uo_emp2 = uo_emp1
For information about passing objects as function arguments, see "Passing
arguments to functions and events" on page 108.
Assignment for Declaring an autoinstantiated user object creates an instance of that object (just
autoinstantiated user like a structure). The CREATE statement is not allowed for objects with the
objects
Autoinstantiate setting. In the following example, uo_emp_data has the
Autoinstantiate setting:
uo_emp_data uo_emp1, uo_emp2 // Two object instances
When you assign an autoinstantiated object to another autoinstantiated object,
the whole object is copied to the second variable:
uo_emp1 = uo_emp2
You never have multiple references to an autoinstantiated user object.
Passing to a function When you pass an autoinstantiated user object to a
function, it behaves like a structure:
• Passing by value passes a copy of the object
• Passing by reference passes a pointer to the object variable, just as for any
standard data type
• Passing as read-only passes a copy of the object but that copy cannot be
modified
Restrictions for copying Assignments are allowed between
autoinstantiated user objects only if the object types match or if the target is a
nonautoinstantiated ancestor.

91
Assignment for objects and structures

Rule 1 If you assign one autoinstantiated object to another, they must be of

the same type.
Rule 2 If you assign an autoinstantiated descendent object to an ancestor
variable, the ancestor cannot have the Autoinstantiate setting. The ancestor
variable will contain a reference to a copy of its descendant.
Rule 3 If you assign an ancestor object to a descendent variable, the ancestor
must contain an instance of the descendant or an execution error occurs.
Examples To illustrate, suppose you have these declarations.
Uo_emp_active and uo_emp_inactive are autoinstantiated objects that are
descendants of non-autoinstantiated uo_emp_data:
uo_emp_data uo_emp1 // Ancestor
uo_emp_active uo_empa, uo_empb // Descendants
uo_emp_inactive uo_empi // Another descendant
Example of rule 1 When assigning one instance to another from the user
objects declared above, some assignments are not allowed by the compiler:
uo_empb = uo_empa // Allowed, same type
uo_empa = uo_empi // Not allowed, different types
Example of rule 2 After this assignment, uo_emp1 contains a copy of the
descendent object uo_empa. Uo_emp_data (the type for uo_emp1) must not be
autoinstantiated. Otherwise, the assignment violates rule 1. If uo_emp1 is
autoinstantiated, a compiler error occurs:
uo_emp1 = uo_empa
Example of rule 3 This assignment is only allowed if uo_emp1 contains an
instance of its descendant uo_empa, which it would if the previous assignment
had occurred before this one:
uo_empa = uo_emp1
If it did not contain an instance of target descendent type, an execution error
would occur.
For more information about passing arguments to functions and events, see
"Passing arguments to functions and events" on page 108.

92
CH A PTE R 6 Calling Functions and Events

About this chapter This chapter provides background information that will help you
understand the different ways you can use functions and events. It then
provides the syntax for calling functions and events.
Contents
Topic Page
About functions and events 94
Syntax for calling PowerBuilder functions and events 113
Calling functions and events in an object’s ancestor 117

93
About functions and events

About functions and events

Importance of Much of the power of the PowerScript language resides in the built-in
functions and events PowerScript functions that you can use in expressions and assignment
statements.
Types of functions and PowerBuilder objects have built-in events and functions. You can enhance
events objects with your own user-defined functions and events, and you can declare
local external functions for an object. The PowerScript language also has
system functions that are not associated with any object. You can define your
own global functions and declare external functions and remote procedure
calls.
These are the different types of functions and events:
Category Item Definition
Events Event An action in an object or control that can start the
execution of a script. A user can initiate an event by an
action such as clicking an object or entering data, or a
statement in another script can initiate the event
User event An event you define to add functionality to an object.
You specify the arguments, return value, and whether the
event is mapped to a system message
For information about defining user events, see the
PowerBuilder User’s Guide
System or An event that is part of an object’s PowerBuilder
built-in definition. System events are usually triggered by user
event actions or system messages. PowerBuilder passes a
predefined set of arguments for use in the event’s script.
System events either return a long or don’t have a return
value

94
 Chapter 6 Calling Functions and Events

Category Item Definition

Functions Function A program or routine that performs specific processing
System A built-in PowerScript function that is not associated
function with an object
Object A function that is part of an object’s definition.
function PowerBuilder has many predefined object functions and
you can define your own
User- A function you define. You define global functions in the
defined Function painter and object functions in other painters
function with Script views
Global A function you define that can be called from any script
function (PowerScript’s system functions are globally accessible,
but they have a different place in the search order)
Local An external function that belongs to an object. You
external declare it in the Window or User Object painter. Its
function definition is in another library
Global An external function that you declare in any painter,
external making it globally accessible. Its definition is in another
function library
Remote A stored procedure in a database that you can call from
procedure a script. The declaration for an RPC can be global or
call (RPC) local (belonging to an object). The definition for the
procedure is in the database

Functions versus Functions and events have several similarities as well as a many differences:
events
Similarities Differences
Both functions and events have Events are only associated with objects.
arguments and return values Functions can be global or part of an
object’s definition
You can call object functions and PowerBuilder uses a different search order
events dynamically or statically when looking for an event versus a function
(global or system functions cannot be
called dynamically)

95
About functions and events

Similarities Differences
You can post or trigger the function or A call to an undefined event will not trigger
event call an error, but a call to an undefined function
will
Functions can be overloaded whereas
events cannot
When you define a function, you can
restrict access to it. You cannot add scope
restrictions when you define events
You can easily extend or override ancestor
events when you are writing scripts in a
descendant object, and you override
functions in the same way. To extend the
ancestor function, you can call it in the
descendant’s version of the function

Which to use Whether you write most of your code in user-defined functions
or in event scripts is one of the design decisions you will make. Because there
is no performance difference, the decision will be based on how you prefer to
interact with PowerBuilder: whether you prefer the interface for defining user
events or that for defining functions, how you want to handle errors, and
whether your design includes overloading.
It is unlikely that you will use either events or functions exclusively. But for
ease of maintenance, you will want to choose one approach for handling most
situations.

Finding and executing functions and events

General information PowerBuilder looks for a matching function or event based on its name and its
argument list. PowerBuilder can make a match between compatible data types
(such as all the numeric types)—the match doesn’t have to be exact.
PowerBuilder ranks compatible data types to quantify how closely one data
type matches another.
A major difference between functions and events is how PowerBuilder looks
for them.
Finding functions When calling a function, PowerBuilder searches until it finds a matching
function and executes it—the search ends.

96
 Chapter 6 Calling Functions and Events

Using functions with the same name but different arguments is called function
overloading. For more information, see "Overloading, overriding, and
extending functions and events" on page 106.
Unqualified function names If you don’t qualify a function name with an
object, PowerBuilder searches for the function and executes the first one it
finds that matches the name and arguments. It searches for a match in the
following order:
1 A global external function
2 A global function
3 An object function and local external function (if the object is a
descendant, PowerBuilder searches upward through the ancestor
hierarchy to find a match for the function prototype)
4 A system function
Qualified function names You can qualify an object function using dot
notation to ensure that the object function (and not a global function of the
same name) is found. With a qualified name, the search for a matching function
involves the ancestor hierarchy only (item 3 in search list above) as shown in
the following examples of function calls:
dw_1.Update( )
w_employee.uf_process_list()
This.uf_process_list()
When PowerBuilder is searching the ancestor hierarchy for a function, you can
specify that you want to call an ancestor function instead of a matching
descendent function.
For the syntax for calling ancestor functions, see "Calling functions and events
in an object’s ancestor" on page 117.
Finding events PowerBuilder events in descendent objects are by default extensions of
ancestor events. PowerBuilder searches for events in the object’s ancestor
hierarchy until it gets to the top ancestor or finds an event that overrides its
ancestor. Then it begins executing the events, from the ancestor event down to
the descendent event.

97
About functions and events

Finding functions The following illustration shows the difference between searching for events
versus events and searching for functions:

Triggering versus posting functions and events

Triggering In PowerBuilder, when you trigger a function or event, it is called immediately.
Its return value is available for use in the script.
Posting When you post a function or event, it is added to the object’s queue and
executed in its turn. In most cases, it is executed when the current script is
finished, but if other system events have occurred in the meantime, its position
in the queue may be after other scripts. Its return value is not available to the
calling script.
Because POST makes the return value unavailable to the caller, you can think
of it as turning the function or event call into a statement.
Use posting when activities need to be finished before the code checks state
information or does further processing (see Example 2 below).
PowerBuilder All events posted by PowerBuilder are processed by a separate queue from the
messages processed Windows system queue. PowerBuilder posted messages are processed before
first
Windows posted messages, so PowerBuilder events that are posted in an event
that posts a Windows message are processed before the Windows message.

98
 Chapter 6 Calling Functions and Events

For example, when a character is typed into an EditMask control, the

PowerBuilder pdm_keydown event posts the Windows message WM_CHAR
to enter the character. If you want to copy the characters as they are entered
from the EditMask control to another control, do not place the code in an event
posted in the pdm_keydown event. The processing must take place in an event
that occurs after the WM_CHAR message is processed, such as in an event
mapped to pdm_keyup.
Restrictions for POST Because no value is returned, you:
• Cannot use a posted function or event as an operand in an expression
• Cannot use a posted function or event as the argument for another function
• Can only use POST on the last call in a cascaded sequence of calls
These statements will cause a compiler error. Both uses require a return value:
IF POST IsNull( ) THEN ...
w_1.uf_getresult(dw_1.POST GetBorderStyle(2))
Asynchronous Using POST is not supported in the context of calls to EAServer components.
processing in For how to simulate asynchronous processing by posting a call to a shared
EAServer
object on an EAServer client, see the SharedObjectGet function in the online
Help. For information about asynchronous processing in EAServer, see the
EAServer documentation for the ThreadManager and MessageService
modules.

TriggerEvent and PostEvent functions

For backward compatibility, the TriggerEvent and PostEvent functions are still
available, but you cannot pass arguments to the called event. You must pass
data to the event in PowerBuilder’s Message object.

Examples of posting The following examples illustrate how to post events.

Example 1 In a sample application, the Open event of the
w_activity_manager window calls the functions uf_setup and
uf_set_tabpgsystem. (The functions belong to the user object u_app_actman.)
Because the functions are posted, the Open event is allowed to finish before the
functions are called. The result is that the window is visible while setup
processing takes place, giving the user something to look at:
guo_global_vars.iuo_app_actman.POST uf_setup()
guo_global_vars.iuo_com_actman.POST
uf_set_tabpgsystem(0)

99
About functions and events

Example 2 In a sample application, the DoubleClicked event of the

tv_roadmap TreeView control in the u_tabpg_amroadmap user object posts a
function that processes the TreeView item. If the event isn’t posted, the code
that checks whether to change the item’s picture runs before the item’s
expanded flag is set:
parent.POST uf_process_item ()

Static versus dynamic calls

Calling functions and PowerBuilder calls functions and events in three ways depending on the type
events of function or event and the lookup method defined.
Type of function Compiler typing Comments
Global and system Strongly typed. The These functions must exist and
functions function must exist when are called directly. They are not
the script is compiled polymorphic and no
substitution is ever made at
execution time
Object functions Strongly typed. The The functions are polymorphic.
with STATIC lookup function must exist when They must exist when you
the script is compiled compile, but if another class is
instantiated at execution time,
its function is called instead
Object functions Weakly typed. The The functions are polymorphic.
with DYNAMIC function does not have to The actual function called is
lookup exist when the script is determined at execution time
compiled

Specifying static or For object functions and events, you can choose when PowerBuilder looks for
dynamic lookup them by specifying static or dynamic lookup. You specify static or dynamic
lookup using the STATIC or DYNAMIC keywords. The DYNAMIC keyword
applies only to functions that are associated with an object. You cannot call
global or system functions dynamically.

Static calls
Static is the default By default, PowerBuilder makes static lookups for functions and events. This
means that it identifies the function or event by matching the name and
argument types when it compiles the code. A matching function or event must
exist in the object at compile time.

100
 Chapter 6 Calling Functions and Events

Results of static calls Static calls do not guarantee that the function or event identified at compile
time is the one that is executed. Suppose that you define a variable of an
ancestor type and it has a particular function definition. If you assign an
instance of a descendent object to the variable and the descendant has a
function that overrides the ancestor’s function (the one found at compile time),
the function in the descendant is executed.

Dynamic calls
You specify dynamic When you specify a dynamic call in PowerBuilder, the function or event does
calls not have to exist when you compile the code. You are saying to the compiler:
trust me—there will be a suitable function or event available at execution time.
For a dynamic call, PowerBuilder waits until it is time to execute the function
or event to look for it. This gives you flexibility and allows you to call functions
or events in descendants that don’t exist in the ancestor.
Results of dynamic To illustrate the results of dynamic calls, consider these objects:
calls
• Ancestor window w_a with a function Set(integer).
• Descendent window w_a_desc with two functions. Set(integer) overrides
the ancestor function. Set(string) overload of the function
Situation 1 Suppose you open the window mywindow of the ancestor
window class w_a:
w_a mywindow
Open(mywindow)
This is what happens when you call the Set function statically or dynamically:
This statement Has this result
mywindow.Set(1) Compiles correctly because function is found in
the ancestor w_a
At execution time, Set(integer) in the ancestor
is executed
mywindow.Set("hello") Fails to compile; no function prototype in w_a
matches the call
mywindow.DYNAMIC & Compiles successfully because of the
Set("hello")
DYNAMIC keyword
An error occurs at execution time because no
matching function is found

101
About functions and events

Situation 2 Now suppose you open mywindow as the descendant window

class w_a_desc:
w_a mywindow
Open(mywindow, "w_a_desc")
This is what happens when you call the Set function statically or dynamically
in the descendant window class:
This statement Has this result
mywindow.Set(1) Compiles correctly because function is found in
the ancestor w_a
At execution time, Set(integer) in the descendant
is executed
mywindow.Set("hello") Fails to compile; no function prototype in the
ancestor matches the call
mywindow.DYNAMIC & Compiles successfully because of the
Set("hello") DYNAMIC keyword
At execution time, Set(string) in the descendant
is executed

Disadvantages of Slower performance Because dynamic calls are resolved at execution

dynamic calls time, they are slower than static calls. If you need the fastest performance,
design your application to avoid dynamic calls.
Less error checking When you use dynamic calls, you are foregoing error
checking provided by the compiler. Your application is more open to
application errors, because functions that are called dynamically may be
unavailable at execution time. So do not use a dynamic call when a static call
will suffice.
Example using A sample application has an ancestor window w_datareview_frame that
dynamic call defines several functions called by the menu items of
m_datareview_framemenu. They are empty stubs with empty scripts so that
static calls to the functions will compile. Other windows that are descendants
of w_datareview_frame have scripts for these functions, overriding the
ancestor version.
The wf_print function is one of these—it has an empty script in the ancestor
and appropriate code in each descendent window:
guo_global_vars.ish_currentsheet.wf_print ()

102
 Chapter 6 Calling Functions and Events

The wf_export function called by the m_export item on the m_file menu does
not have a stubbed-out version in the ancestor window. This code for m_export
uses the DYNAMIC keyword to call wf_export. When the program is run, the
value of variable ish_currentsheet is a descendent window that does have a
definition for wf_export:
guo_global_vars.ish_currentsheet.DYNAMIC wf_export()
Errors when calling If you call a function or event dynamically, different conditions create different
functions and events results, from no effect to an execution error. The tables in this section illustrate
dynamically
this.
Functions Functions The rules for functions are similar to those for events, except
functions must exist: if a function is not found, an error always occurs. And
although events can exist without a script, if a function is defined it has to have
code.For purposes of illustration, the table below refers to these statements:
Statement 1 This statement calls a function without looking for a return
value:
object.DYNAMIC funcname( )
Statement 2 This statement looks for an integer return value:
int li_int
li_int = object.DYNAMIC funcname( )
Statement 3 This statement looks for an Any return value:
any la_any
la_any = object.DYNAMIC funcname( )

If And This occurs Example

The function Execution error 65: All the
doesn’t exist Dynamic function statements cause
not found error 65
The function is The code is looking Execution error 63: Statements 2 and
found and for a return value Function/event with 3 cause error 63
executed but is no return value used
not defined with in expression
a return value

Events Events The table below describes different error conditions and refers to
these statements:
Statement 1 This statement calls an event without looking for a return value:
object.EVENT DYNAMIC eventname( )

103
About functions and events

Statement 2 This example looks for an integer return value:

int li_int
li_int = object.EVENT DYNAMIC eventname( )
Statement 3 This example looks for an Any return value:
any la_any
la_any = object.EVENT DYNAMIC eventname( )

If And This occurs Example

The event doesn’t The code is not Nothing; the call fails Statement 1 fails
exist looking for a return silently but doesn’t cause
value an error
The code is looking A NULL of the Any La_any is set to
for a return value data type is returned NULL in
statement 3
If the expected data The assignment
type is not Any, to li_int causes
execution error 19 execution error
occurs: Cannot 19 in statement 2
convert Any in Any
variable to data type
The event is The event has a A NULL of the If eventname is
found but is not defined return value defined data type is defined to return
implemented returned integer, li_int is
(there is no set to NULL in
script) statement 2
The event does not A NULL of the Any La_any is set to
have a defined data type is returned NULL in
return value statement 3
If the expected data The assignment
type is not Any, to li_int causes
execution error 19 execution error
occurs: Cannot 19 in statement 2
convert Any in Any
variable to datatype
The event is The code is looking Execution error 63: Statements 2 and
found and for a return value Function/event with 3 cause error 63
executed but is no return value used
not defined with in expression
a return value

104
 Chapter 6 Calling Functions and Events

When an error occurs You can surround a dynamic method call in a try-
catch block to prevent the application from terminating when an execution
error occurs. Although you can also handle the error in the SystemError event,
you should not allow the application to continue once the SystemError event is
invoked—the SystemError event should only clean up and halt the application.
For information on using try-catch blocks, see the chapter on exception
handling in Application Techniques.
If the arguments don’t match Function arguments are part of the function’s
definition. Therefore, if the arguments don’t match (a compatible match, not an
exact match), it is essentially a different function. The result is the same as if
the function didn’t exist.
If you call an event dynamically and the arguments don’t match, the call fails
and control returns to the calling script. There is no error.
Error-proofing your code Calling functions and events dynamically opens
up your application to potential errors. The surest way to avoid these errors is
to always make static calls to functions and events. Short of that, your design
and testing can ensure that there will always be an appropriate function or event
with the correct return data type.
One type of error you can check for and avoid is data conversion errors.
The preceding tables illustrated that a function or event can return a NULL
value either as an Any variable or as a variable of the expected data type when
a function or event definition exists but is not implemented.
If you always assign return values to Any variables for dynamic calls, you can
test for NULL (which indicates failure) before using the value in code.
This example illustrates the technique of checking for NULL before using the
return value.
any la_any
integer li_gotvalue
la_any = object.DYNAMIC uf_getaninteger( )
IF IsNull(la_any) THEN
... // Error handling
ELSE
li_gotvalue = la_any
END IF

105
About functions and events

Overloading, overriding, and extending functions and events

Functions In PowerBuilder, when functions are inherited, you can choose to overload or
override the function definition, described in "Overloading and overriding
functions" next.
Events When events are inherited, the scripts for those events are extended by default.
You can choose to extend or override the script, described in "Extending and
overriding events" on page 107.

Overloading and overriding functions

General information Overloading means defining more than one function with the same name but
different argument lists. The additional function definitions can be in the same
object or a descendant of that object. PowerBuilder compares the argument list
of the function call and the function prototype to determine which function to
call.
To create an overloaded function, you declare the function as you would any
function using Insert>Function.
Overriding means defining a function in a descendent object that has the same
name and argument list as a function in the ancestor object. In the descendent
object, the function in the descendant is always called instead of the one in the
ancestor—unless you use the scope resolution operator (::).
To override a function, open the descendent object in the painter, select the
function in the Script view, and code the new script. The icon that indicates that
there is a script for a function is half shaded when the function is inherited from
an ancestor.
You can overload or override object functions only.
Type promotion when Good overloading When you have overloaded a function so that one version
matching arguments handles numeric values and another version handles strings, it is clear to the
for overloaded programmer what arguments to provide to call each version of the function.
functions
Overloading with unrelated data types is a good idea and can provide needed
functionality for your application.
Problematic overloading If different versions of a function have arguments
of related data types (different numeric types or strings and chars), you must
consider how PowerBuilder promotes data types in determining which
function is called. This kind of overloading is undesirable because of potential
confusion in determining which function is called.

106
 Chapter 6 Calling Functions and Events

When you call a function with an expression as an argument, the data type of
the expression may not be obvious. However, the data type is important in
determining what version of an overloaded function will be called.
Because of the intricacies of type promotion for numeric data types, you may
decide that you should not define overloaded functions with different numeric
data types. Changes someone makes later can affect the application more
drastically than expected if the change causes a different function to be called.
How type promotion works When PowerBuilder evaluates an expression, it
converts the data types of constants and variables so that it can process or
combine them correctly.
Numbers When PowerBuilder evaluates numeric expressions, it promotes
the data types of values according to the operators and the data types of the
other operands. For example, the data type of the expression n/2 is double
because it involves division—the data type of n doesn’t matter.
Strings When evaluating an expression that involves chars and strings,
PowerBuilder promotes chars to strings.
For more information on type promotion, see "Data type of PowerBuilder
expressions" on page 76.
Using conversion functions You can take control over the data types of
expressions by calling a conversion function. The conversion function ensures
that the data type of the expression matches the function prototype you want to
call.
For example, because the expression n/2 involves division, the data type is
double. However, if the function you want to call expects a long, you can use
the Long function to ensure that the function call matches the prototype:
CalculateHalf(Long(n/2))

Extending and overriding events

General information In PowerBuilder, when you are writing event scripts in a descendent object,
you can extend or override scripts that have been written in the ancestor.
Extending (the default) means executing the ancestor’s script first, then
executing code in the descendant’s event script.
Overriding means ignoring the ancestor’s script and only executing the script
in the descendant.

107
About functions and events

No overloaded events
You cannot overload an event by defining an event with the same name but
different arguments. Event names must be unique.

To select To select extending or overriding, open the script in the Script view and check
or clear the Extend Ancestor Script item in the Edit or popup menu.

Passing arguments to functions and events

Three ways In PowerBuilder, arguments for built-in or user-defined functions and events
can be passed three ways:
Method of passing Description
By value A copy of the variable is available in the function or
event script. Any changes to its value affect the copy
only. The original variable in the calling script is not
affected
By reference A pointer to the variable is passed to the function or event
script. Changes affect the original variable in the calling
script
Read-only The variable is available in the function or event. Its
value is treated as a constant—changes to the variable are
not allowed and cause a compiler error
Read-only provides a performance advantage for some
data types because it does not create a copy of the data,
as with by value. Data types for which read-only
provides a performance advantage are strings, blobs,
date, time, and DateTime
For other data types, read-only provides documentation
for other developers by indicating something about the
purpose of the argument

Passing objects When you pass an object to a function or event, the object must exist when you
refer to its properties and functions. If you call the function but the object has
been destroyed, you will get the execution error for a null object reference. This
is true whether you pass by reference, by value, or read-only.

108
 Chapter 6 Calling Functions and Events

To illustrate, suppose you have a window with a SingleLineEdit. If you post a

function in the window’s Close event and pass the SingleLineEdit, the object
won’t exist when the function executes. To use information from the
SingleLineEdit, you must pass the information itself, such as the object’s text,
rather than the object.
When passing an object, you never get another copy of the object. By reference
and by value affect the object reference, not the object itself.
Objects passed by value Here you pass a copy of the reference to the
object. That reference is still pointing to the original object. If you change
properties of the object, you are changing the original object. However, you can
change the value of the variable so that it points to another object without
affecting the original variable.
Objects passed by reference Here you pass a pointer to the original
reference to the object. Again, if you change properties of the object, you are
changing the original object. You can change the value of the variable that was
passed, but the result is different—the original reference now points to the new
object.
Objects passed as read-only Here you pass an object as read-only, and you
get a copy of the reference to the object. You cannot change the reference to
point to a new object (because read-only is equivalent to a CONSTANT
declaration), but you can change properties of the object.
Passing structures Structures as arguments behave like simple variables, not like objects.
Structures passed by value Here PowerBuilder passes a copy of the
structure. You can modify the copy without affecting the original.
Structures passed by reference Here PowerBuilder passes a reference to
the structure. When you changes values in the structure, you are modifying the
original. You will not get a null object reference, because structures always
exist until they go out of scope.
Structures passed as read-only Here you pass a structure as read-only, and
PowerBuilder passes a copy of the structure. You cannot modify any members
of the structure.
Passing arrays When an argument is an array, you specify brackets as part of the argument
name in the declaration for the function or event.
Variable-size array as an argument For example, suppose a function
named uf_convertarray accepts a variable-size array of integers. If the
argument’s name is intarray, then for Name enter intarray[ ] and for Type enter
integer.

109
About functions and events

In the script that calls the function, you will either declare an array variable or
use an instance variable or value that has been passed to you. The declaration
of that variable, wherever it is, looks like this:
integer a[]
When you call the function, omit the brackets (because you are passing the
whole array). If you specified brackets, you would be passing one value from
the array:
uf_convertarray(a)
Fixed-size array as an argument For comparison, suppose the
uf_convertarray function accepts a fixed-size array of integers of 10 elements
instead. If the argument’s name is intarray, then for Name enter intarray[10] and
for Type enter integer.
The declaration of the variable to be passed looks like this:
integer a[10]
You call the function the same way, without brackets:
uf_convertarray(a)

If the array dimensions don’t match

If the dimensions of the array variable passed do not match the dimensions
declared for the array argument, then array-to-array assignment rules apply.
For more information, see "Declaring arrays" on page 50.

Using return values of functions and events

Functions All built-in PowerScript functions return a value. You can use the return value
or ignore it.
To use the return value, assign it to a variable of the appropriate data type or
call the function wherever you can use a value of that data type.

Posting a function
If you post a function, you cannot use its return value.
User-defined functions and external functions may or may not return a value.

110
 Chapter 6 Calling Functions and Events

Examples The built-in Asc function takes a string as an argument and returns
the ASCII value of the string’s first character:
string S1 = "Carton"
int Test
Test=32+Asc(S1) // Test now contains the value
// 99 (the ASCII value of "C"
// is 67).
The SelectRow function expects a row number as the first argument. The return
value of the GetRow function supplies the row number:
dw_1.SelectRow(dw_1.GetRow(), TRUE)
To ignore a return value, call the function as a single statement:
Beep(4) // This returns a value, but it is
// rarely needed.
Events Most system events return a value. The return value is a long—numeric codes
have specific meanings for each event. You specify the event’s return code with
a RETURN statement in the event script.
When the event is triggered by user actions or system messages, the value is
returned to the system, not to a script you write.
When you trigger a system or user-defined event, the return value is returned
to your script and you can use the value as appropriate. If you post an event,
you cannot use its return value.

Using cascaded calling and return values

General information PowerBuilder dot notation allows you to chain together several object function
or event calls. The return value of the function or event becomes the object for
the following call.
This syntax shows the relationship between the return values of three cascaded
function calls:
func1returnsobject( ).func2returnsobject( ).func3returnsanything( )

111
About functions and events

Disadvantage of cascaded calls

When you call several functions in a cascade, you can’t check their return
values and make sure they succeeded. If you want to check return values (and
checking is always a good idea), you should call each function separately and
assign their return values to variables. Then you can use the verified variables
in dot notation before the final function name.

Dynamic calls If you use the DYNAMIC keyword in a chain of cascaded calls, it carries over
to all function calls that follow.
In this example, both func1 and func2 are called dynamically:
object1.DYNAMIC func1().func2()
The compiler reports an error if you use DYNAMIC more than once in a
cascaded call. This example would cause an error:
object1.DYNAMIC func1().DYNAMIC func2() // error
Posted functions and Posted functions and events do not return a value to the calling scripts.
events Therefore, you can only use POST for the last function or event in a cascaded
call. Calls before the last must return a valid object that can be used by the
following call.
System events System events can only be last in a cascaded list of calls, because their return
value is a long (or they have no return value). They don’t return an object that
could be used by the next call.
An event you have defined can have a return value whose data type is an object.
You can include such events in a cascaded call.

112
 Chapter 6 Calling Functions and Events

Syntax for calling PowerBuilder functions and events

Description This syntax is used to call all PowerBuilder functions and events. Depending
on the keywords used, this syntax can be used to call system, global, object,
user-defined, and external functions as well as system and user-defined events.
Syntax { objectname.} { type } { calltype } { when } name ( { argumentlist } )
Argument Description
objectname The name of the object where the function or event is defined
(optional) followed by a period or the descendant of that object/the
name of the ancestor class followed by two colons
If a function name is not qualified, PowerBuilder uses the
rules for finding functions and executes the first matching
function it finds
For system or global functions, omit objectname
For the rules PowerBuilder uses to find unqualified function
names, see "Finding and executing functions and events" on
page 96
type A keyword specifying whether you are calling a function or
(optional) event. Values are:
• FUNCTION (Default)
• EVENT
calltype A keyword specifying when PowerBuilder looks for the
(optional) function or event. Values are:
• STATIC (Default)
• DYNAMIC
For more information about static versus dynamic calls, see
"Static versus dynamic calls" on page 100
For more information on dynamic calls, see "Dynamic calls"
on page 101
when A keyword specifying whether the function or event should
(optional) execute immediately or after the current script is finished.
Values are:
• TRIGGER — (Default) Execute it immediately
• POST — Put it in the object’s queue and execute it in its
turn, after other pending messages have been handled
For more about triggering and posting, see "Triggering versus
posting functions and events" on page 98
name The name of the function or event you want to call

113
Syntax for calling PowerBuilder functions and events

Argument Description
argumentlist The values you want to pass to name. Each value in the list
(optional) must have a data type that corresponds to the declared data
type in the function or event definition or declaration

Usage Case insensitivity

Function and event names are not case sensitive. For example, the following
three statements are equivalent:
Clipboard("PowerBuilder")
clipboard("PowerBuilder")
CLIPBOARD("PowerBuilder")

Calling arguments The type, calltype, and when keywords can be in any
order after objectname.
Not all options in the syntax apply to all types. For example, there’s no point
in calling a system PowerScript object function dynamically. It always exists,
and the dynamic call incurs extra overhead. However, if you had a user-defined
function of the same name that applied to a different object, you might call that
function dynamically.
User-defined global functions and system functions can be triggered or posted
but they cannot be called dynamically.
Finding functions If a global function does not exist with the given name,
PowerBuilder will look for an object function that matches the name and
argument list before it looks for a PowerBuilder system function.
Calling functions and events in the ancestor If you want to circumvent
the usual search order and force PowerBuilder to find a function or event in an
ancestor object, bypassing it in the descendant, you can use the ancestor
operator (::).
For more information about the scope operator for ancestors, see "Calling
functions and events in an object’s ancestor" on page 117.
Cascaded calls Calls can be cascaded using dot notation. Each function or
event call must return an object type that is the appropriate object for the
following call.
For more information about cascaded calls, see "Using cascaded calling and
return values" on page 111.
Using return values If the function has a return value, you can call the
function on the right side of an assignment statement, as an argument for
another function, or as an operand in an expression.

114
 Chapter 6 Calling Functions and Events

External functions Before you can call an external function, you must
declare it. For information about declaring external functions, see "Declaring
external functions" on page 60.
Examples Example 1 The following statements show various function calls using the
most simple construction of the function call syntax.
This statement calls the system function Asc:
charnum = Asc("x")
This statement calls the DataWindow function in a script that belongs to the
DataWindow:
Update( )
This statement calls the global user-defined function gf_setup_appl:
gf_setup_appl(24, "Window1")
This statement calls the system function PrintRect:
PrintRect(job, 250, 250, 7500, 1000, 50)
Example 2 The following statements show calls to global and system
functions.
This statement posts the global user-defined function gf_setup_appl. The
function is executed when the calling script finishes:
POST gf_setup_appl(24, "Window1")
This statement posts the system function PrintRect. It is executed when the
calling script finishes. The print job specified in job must still be open:
POST PrintRect(job, 250, 250, 7500, 1000, 50)
Example 3 In a script for a control, these statements call a user-defined
function defined in the parent window. The statements are equivalent, because
FUNCTION, STATIC, and TRIGGER are the defaults:
Parent.FUNCTION STATIC TRIGGER wf_process( )
Parent.wf_process( )
Example 4 This statement in a DataWindow control’s Clicked script calls
the DoubleClicked event for the same control. The arguments the system
passed to Clicked are passed on to DoubleClicked. When triggered by the
system, PowerBuilder passes DoubleClicked those same arguments:
This.EVENT DoubleClicked(xpos, ypos, row, dwo)
This statement posts the same event:
This.EVENT POST DoubleClicked(xpos, ypos, row, dwo)

115
Syntax for calling PowerBuilder functions and events

Example 5 The variable iw_a is an instance variable of an ancestor window

type w_ancestorsheet:
w_ancestorsheet iw_a
A menu has a script that calls the wf_export function, but that function is not
defined in the ancestor. The DYNAMIC keyword is required so that the script
compiles:
iw_a.DYNAMIC wf_export( )
At execution time, the window that is opened is a descendant with a definition
of wf_export. That window is assigned to the variable iw_a and the call to
wf_export succeeds.

116
 Chapter 6 Calling Functions and Events

Calling functions and events in an object’s ancestor

Description In PowerBuilder, when an object is instantiated with a descendant object, even
if its class is the ancestor and that descendant has a function or event script that
overrides the ancestor’s, the descendant’s version is the one that is executed. If
you specifically want to execute the ancestor’s version of a function or event,
you can use the :: operator to call the ancestor’s version explicitly.
Syntax { objectname. } ancestorclass ::{ type } { when } name ( { argumentlist } )
Argument Description
objectname The name of the object whose ancestor contains the function you
(optional) want to execute
ancestorclass The name of the ancestor class whose function or event you want
to execute. The pronoun Super provides the appropriate reference
when ancestorobject is the immediate ancestor of the current
object
type A keyword specifying whether you are calling a function or event.
(optional) Values are:
• (Default) FUNCTION
• EVENT
when A keyword specifying whether the function or event should
(optional) execute immediately or after the current script is finished. Values
are:
• TRIGGER — (Default) Execute it immediately
• POST — Put it in the object’s queue and execute it in its turn,
after other pending messages have been handled
name The name of the object function or event you want to call
argumentlist The values you want to pass to name. Each value in the list must
(optional) have a data type that corresponds to the declared data type in the
function definition

Usage The AncestorReturnValue variable When you extend an event script in a

descendent object, the compiler automatically generates a local variable called
AncestorReturnValue that you can use if you need to know the return value of
the ancestor event script. The variable is also generated if you override the
ancestor script and use the CALL syntax to call the ancestor event script.
The data type of the AncestorReturnValue variable is always the same as the
data type defined for the return value of the event. The arguments passed to the
call come from the arguments that are passed to the event in the descendent
object.

117
Calling functions and events in an object’s ancestor

Extending event scripts The AncestorReturnValue variable is always

available in extended event scripts. When you extend an event script,
PowerBuilder generates the following syntax and inserts it at the beginning of
the event script:
CALL SUPER::event_name
You only see the statement if you export the syntax of the object or look at it in
the Source editor.
The following example illustrates the code you can put in an extended event
script:
If AncestorReturnValue = 1 THEN
// execute some code
ELSE
// execute some other code
END IF
Overriding event scripts The AncestorReturnValue variable is only
available when you override an event script after you call the ancestor event
using the CALL syntax:
CALL SUPER::event_name
or
CALL ancestor_name::event_name
The compiler cannot differentiate between the keyword SUPER and the name
of the ancestor. The keyword is replaced with the name of the ancestor before
the script is compiled.
The AncestorReturnValue variable is only declared and a value assigned when
you use the CALL event syntax. It is not declared if you use the new event
syntax:
ancestor_name::EVENT event_name( )
You can use the same code in a script that overrides its ancestor event script,
but you must insert a CALL statement before you use the AncestorReturnValue
variable.
// execute code that does some preliminary processing
CALL SUPER::uo_myevent
IF AncestorReturnValue = 1 THEN
...
For information about CALL, see CALL on page 127.

118
 Chapter 6 Calling Functions and Events

Examples Example 1 Suppose a window w_ancestor has an event ue_process. A

descendent window has a script for the same event.
This statement in a script in the descendant searches the event chain and calls
all appropriate events. If the descendant extends the ancestor script, it calls a
script for each ancestor in turn followed by the descendent script. If the
descendant overrides the ancestor, it calls the descendent script only:
EVENT ue_process( )
This statement calls the ancestor event only (this script works if the calling
script belongs to another object or the descendent window):
w_ancestor::EVENT ue_process( )
Example 2 You can use the pronoun Super to refer to the ancestor. This
statement in a descendent window script or in a script for a control on that
window calls the Clicked script in the immediate ancestor of that window.
Super::EVENT Clicked(0, x, y)
Example 3 These statements call a function wf_myfunc in the ancestor
window (presumably, the descendant also has a function called wf_myfunc):
Super::wf_myfunc( )
Super::POST wf_myfunc( )

119
Calling functions and events in an object’s ancestor

120
PART 2 Statements, Events, and
Functions
CH A PTE R 7 PowerScript Statements

About this chapter This chapter describes the PowerScript statements and how to use them in
scripts.
Contents
Topic Page
Assignment 124
CALL 127
CHOOSE CASE 128
CONTINUE 130
CREATE 131
DESTROY 134
DO...LOOP 135
EXIT 138
FOR...NEXT 139
GOTO 141
HALT 142
IF...THEN 143
RETURN 145
THROW 146
THROWS 147
TRY...CATCH...FINALLY...END TRY 149

123
Assignment

Assignment
Description Assigns values to variables or object properties or object references to object
variables.
Syntax variablename = expression
Argument Description
variablename The name of the variable or object property to which you
want to assign a value. Variablename can include dot
notation to qualify the variable with one or more object
names
expression An expression whose data type is compatible with
variablename

Usage Use assignment statements to assign values to variables. To assign a value to a

variable anywhere in a script, use the equal sign (=). For example:
String1 = "Part is out of stock"
TaxRate = .05
No multiple assignments Since the equal sign is also a logical operator, you
cannot assign more than one variable in a single statement. For example, the
following statement does not assign the value 0 to A and B:
A=B=0 // This will not assign 0 to A and B.
This statement first evaluates B=0 to TRUE or FALSE and then tries to assign
this boolean value to A. When A is not a boolean variable, this line produces
an error when compiled.
Assigning array values You can assign multiple array values with one
statement, such as:
int Arr[]
Arr = {1, 2, 3, 4}
You can also copy array contents. For example:
Arr1 = Arr2
copies the contents of Arr2 into array Arr1.
Operator shortcuts These PowerScript shortcuts for assigning values to
variables have slight performance advantages over their equivalents:
Assignment Example Equivalent to
++ i ++ i=i+1
-- i -- i=i-1
+= i += 3 i=i+3

124
 Chapter 7 PowerScript Statements

Assignment Example Equivalent to

-= i -= 3 i = i -3
*= i *= 3 i=i*3
/= i /= 3 i=i/3
^= i ^=3 i=i^3

Unless you have prohibited the use of dashes in variable names, you must leave
a space before -- and -= (otherwise, PowerScript reads the minus sign as part
of a variable name).
For more information, see "Identifier names" on page 6.
Examples Example 1 These statements each assign a value to the variable ld_date:
date ld_date
ld_date = Today( )
ld_date = 1996-01-01
ld_date = Date("January 1, 1996")
Example 2 This statement assigns the parent of the current control to a
window variable:
window lw_current_window
lw_current_window = Parent
Example 3 This statement makes a CheckBox invisible:
cbk_on.Visible = FALSE
Example 4 This statement is not an assignment—it tests the value of the
string in the SingleLineEdit sle_emp:
IF sle_emp.Text = "N" THEN Open(win_1)
Example 5 These statements concatenate two strings and assigns the value to
the string Text1:
string Text1
Text1 = sle_emp.Text+".DAT"
Operator shortcuts These assignments use operator shortcuts:
int i = 4
i ++ // i is now 5.
i -- // i is 4 again.
i += 10 // i is now 14.
i /= 2 // i is now 7.

125
Assignment

These shortcuts can be used only in pure assignment statements. They cannot
be used with other operators in a statement. For example, the following is
invalid:
int i, j
i = 12
j = i ++ // INVALID
The following is valid, because ++ is used by itself in the assignment:
int i, j
i = 12
i ++
j = i

126
 Chapter 7 PowerScript Statements

CALL
Description Calls an ancestor script from a script for a descendent object. You can call
scripts for events in an ancestor of the user object, menu, or window. You can
also call scripts for events for controls in an ancestor of the user object or
window.
When you use the CALL statement to call an ancestor event script, the
AncestorReturnValue variable is generated. For more information on the
AncestorReturnValue variable, see "About events" on page 194.
Syntax CALL ancestorobject {‘ controlname}::event
Parameter Description
ancestorobject An ancestor of the descendent object
controlname The name of a control in an ancestor window or custom
(optional) user object
event An event in the ancestor object

Usage New syntax New syntax for calling functions and events allows you to
trigger or post an event or function in an ancestor and then pass arguments. But
the new syntax does not allow you to call a script for a control in the ancestor.
For more information about the new syntax, see "Calling functions and events
in an object’s ancestor" on page 117.
Super In some circumstances, you can use the pronoun Super when
ancestorobject is the descendant object’s immediate ancestor.See the
discussion of "Super pronoun" on page 17.
Passing arguments If the call is being made to an ancestor event, the
arguments passed to the current event are automatically propagated to the
ancestor event. If you call a non-ancestor event and pass arguments, you need
to use the new syntax, otherwise NULL will be passed for each argument.
Examples Example 1 This statement calls a script for an event in an ancestor window:
CALL w_emp::Open
Example 2 This statement calls a script for an event in a control in an
ancestor window:
CALL w_emp‘cb_close::Clicked

127
CHOOSE CASE

CHOOSE CASE
Description A control structure that directs program execution based on the value of a test
expression (usually a variable).
Syntax CHOOSE CASE testexpression
CASE expressionlist
statementblock
{ CASE expressionlist
statementblock
...
CASE expressionlist
statementblock }
CASE ELSE
statementblock }
END CHOOSE
Parameter Description
testexpression The expression on which you want to base the execution
of the script
expressionlist One of the following expressions:
• A single value
• A list of values separated by commas (such as 2, 4, 6,
8)
• A TO clause (such as 1 TO 30)
• IS followed by a relational operator and comparison
value (such as IS>5)
• Any combination of the above with an implied OR
between expressions (such as 1, 3, 5, 7, 9, 27 TO 33,
IS >42)
statementblock The block of statements you want PowerBuilder to
execute if the test expression matches the value in
expressionlist

Usage At least one CASE clause is required. You must end a CHOOSE CASE control
structure with END CHOOSE.
If testexpression at the beginning of the CHOOSE CASE statement matches a
value in expressionlist for a CASE clause, the statements immediately
following the CASE clause are executed. Control then passes to the first
statement after the END CHOOSE clause.
If multiple CASE expressions exist, then testexpression is compared to each
expressionlist until a match is found or the CASE ELSE or END CHOOSE is
encountered.

128
 Chapter 7 PowerScript Statements

If there is a CASE ELSE clause and the test value does not match any of the
expressions, statementblock in the CASE ELSE clause is executed. If no CASE
ELSE clause exists and a match is not found, the first statement after the END
CHOOSE clause is executed.
Examples Example 1 These statements provide different processing based on the value
of the variable Weight:
CHOOSE CASE Weight
CASE IS<16
Postage=Weight*0.30
Method="USPS"
CASE 16 to 48
Postage=4.50
Method="UPS"
CASE ELSE
Postage=25.00
Method="FedEx"
END CHOOSE
Example 2 These statements convert the text in a SingleLineEdit control to a
real value and provide different processing based on its value:
CHOOSE CASE Real(sle_real.Text)
CASE is < 10.99999
sle_message.Text = "Real Case < 10.99999"
CASE 11.00 to 48.99999
sle_message.Text = "Real Case 11 to 48.9999
CASE is > 48.9999
sle_message.Text = "Real Case > 48.9999"
CASE ELSE
sle_message.Text = "Cannot evaluate!"
END CHOOSE

129
CONTINUE

CONTINUE
Description In a DO...LOOP or a FOR...NEXT control structure, skips statements in the
loop. CONTINUE takes no parameters.
Syntax CONTINUE
Usage When PowerBuilder encounters a CONTINUE statement in a DO...LOOP or
FOR...NEXT block, control passes to the next LOOP or NEXT statement. The
statements between the CONTINUE statement and the loop’s end statement
are skipped in the current iteration of the loop. In a nested loop, a CONTINUE
statement bypasses statements in the current loop structure.
For information on how to break out of the loop, see EXIT on page 138.
Examples Example 1 These statements display a message box twice: when B equals 2
and when B equals 3. As soon as B is greater than 3, the statement following
CONTINUE is skipped during each iteration of the loop:
integer A=1, B=1
DO WHILE A < 100
A = A+1
B = B+1
IF B > 3 THEN CONTINUE
MessageBox("Hi", "B is " + String(B) )
LOOP
Example 2 These statements stop incrementing B as soon as Count is greater
than 15:
integer A=0, B=0, Count
FOR Count = 1 to 100
A = A + 1
IF Count > 15 THEN CONTINUE
B = B + 1
NEXT
// Upon completion, a=100 and b=15.

130
 Chapter 7 PowerScript Statements

CREATE
Description Creates an object instance for a specified object type. After a CREATE
statement, properties of the created object instance can be referenced using dot
notation.
The CREATE statement returns an object instance which can be stored in a
variable of the same type.
Syntax 1 specifies the object type at compilation. Syntax 2 allows the
application to choose the object type dynamically.
Syntax Syntax 1 (specifies the object type at compilation):
objectvariable = CREATE objecttype

Parameter Description
objectvariable A global, instance, or local variable whose data type
is objecttype
objecttype The object data type

Syntax 2 (allows the application to choose the object type dynamically):

objectvariable = CREATE USING objecttypestring

Parameter Description
objectvariable A global, instance, or local variable whose data type
is the same class as the object being created or an
ancestor of that class
objecttypestring A string whose value is the name of the class data
type to be created

Usage Use CREATE as the first reference to any Class user object. This includes
standard Class user objects such as mailSession or Transaction.
The system provides one instance of several standard Class user objects:
Message, Error, Transaction, DynamicDescriptionArea, and
DynamicStagingArea. You only need to use CREATE if you declare additional
instances of these objects.
If you need a menu that is not part of an open window definition, use CREATE
to create an instance of the menu. (See the function PopMenu on page 874.)
To create an instance of a visual user object or window, use the appropriate
Open function (instead of CREATE).
You do not need to use CREATE to allocate memory for:
• A standard data type, such as integer or string

131
CREATE

• Any structure, such as the Environment object

• Any object whose AutoInstantiate setting is TRUE
• Any object that has been instantiated via a function, such as Open
Specifying the object type dynamically CREATE USING allows your
application to choose the object type dynamically. It is usually used to
instantiate an ancestor variable with an instance of one of its descendants. The
particular descendant is chosen at execution time.
For example, if uo_a has two descendants: uo_a_desc1 and uo_a_desc2, then
the application can select the object to be created based on current conditions:
uo_a uo_a_var
string ls_objectname

IF ... THEN
ls_objectname = "uo_a_desc1"
ELSE
ls_objectname = "uo_a_desc2"
END IF
uo_a_var = CREATE USING ls_objectname
Destroying objects you create When you are finished with an object you
created, you can call DESTROY to release its memory.However, you should
only call DESTROY if you are sure that the object is not referenced by any
other object. PowerBuilder’s garbage collection mechanism maintains a count
of references to each object and destroys unreferenced objects automatically.
For more information about garbage collection, see Application Techniques.
Examples Example 1 These statements create a new transaction object and stores the
object in the variable DBTrans:
transaction DBTrans
DBTrans = CREATE transaction
DBTrans.DBMS = ’ODBC’
Example 2 These statements create a user object when the application has
need of the services it provides. Because the user object may or may not exist,
the code that accesses it checks whether it exists before calling its functions.
The object that creates the service object declares invo_service as an instance
variable:
n_service invo_service

132
 Chapter 7 PowerScript Statements

The Open event for the object creates the service object:
//Open event of some object
IF (some condition) THEN
invo_service = CREATE n_service
END IF
When another script wants to call a function that belongs to the n_service class,
it checks that invo_service is instantiated:
IF IsValid(invo_service) THEN
invo_service.of_perform_some_work( )
END IF
If the service object was created, then it also needs to be destroyed:
IF isvalid(invo_service) THEN DESTROY invo_service
Example 3 When you create a DataStore object, you also have to give it a
DataObject and call SetTransObject before you can use it:
l_ds_delete = CREATE u_ds
l_ds_delete.DataObject = ’d_user_delete’
l_ds_delete.SetTransObject(SQLCA)
li_cnt = l_ds_delete.Retrieve(lstr_data.name)
Example 4 In this example, n_file_service_class is an ancestor object and
n_file_service_class_ansi and n_file_service_class_dbcs are its descendants.
They hold functions and variables that provide services for the application. The
code chooses which object to create based on whether the user is running in a
DBCS environment:
n_file_service_class lnv_fileservice
string ls_objectname
environment luo_env

GetEnvironment ( luo_env )
IF luo_env.charset = charsetdbcs! THEN
ls_objectname = "n_file_service_class_dbcs"
ELSE
ls_objectname = "n_file_service_class_ansi"
END IF

lnv_fileservice = CREATE USING ls_objectname

133
DESTROY

DESTROY
Description Eliminates an object instance that was created with the CREATE statement.
After a DESTROY statement, properties of the deleted object instance can no
longer be referenced.
Syntax DESTROY objectvariable
Parameter Description
objectvariable A variable whose data type is a PowerBuilder object

Usage When you are finished with an object that you created, you can call DESTROY
to release its memory. However, you should only call DESTROY if you are
sure that the object is not referenced by any other object. PowerBuilder’s
garbage collection mechanism maintains a count of references to each object
and destroys unreferenced objects automatically.
For more information about garbage collection, see Application Techniques.
All objects are destroyed automatically when your application terminates.
Examples Example 1 The following statement destroys the transaction object DBTrans
that was created with a CREATE statement:
DESTROY DBTrans
Example 2 This example creates an OLEStorage variable istg_prod_pic in a
window’s Open event. When the window is closed, the Close event script
destroys the object.The variable’s declaration is:
OLEStorage istg_prod_pic
The window’s Open event creates an object instance and opens an OLE storage
file:
integer li_result
istg_prod_pic = CREATE OLEStorage
li_result = stg_prod_pic.Open("PICTURES.OLE")
The window’s Close event destroys istg_prod_pic:
integer li_result
li_result = istg_prod_pic.Save( )
IF li_result = 0 THEN
DESTROY istg_prod_pic
END IF

134
 Chapter 7 PowerScript Statements

DO...LOOP
Description A control structure that is a general-purpose iteration statement used to execute
a block of statements while or until a condition is true.
DO... LOOP has four formats:
• DO UNTIL Executes a block of statements until the specified condition
is TRUE. If the condition is TRUE on the first evaluation, the statement
block does not execute.
• DO WHILE Executes a block of statements while the specified condition
is TRUE. The loop ends when the condition becomes FALSE. If the
condition is FALSE on the first evaluation, the statement block does not
execute.
• LOOP UNTIL Executes a block of statements at least once and continues
until the specified condition is TRUE.
• LOOP WHILE Executes a block of statements at least once and continues
while the specified condition is TRUE. The loop ends when the condition
becomes FALSE.
In all four formats of the DO...LOOP control structure, DO marks the
beginning of the statement block that you want to repeat. The LOOP statement
marks the end.
You can nest DO...LOOP control structures.
Syntax DO UNTIL condition
statementblock
LOOP
Parameter Description
condition The condition you are testing
statementblock The block of statements you want to repeat

DO WHILE condition
statementblock
LOOP
Parameter Description
condition The condition you are testing
statementblock The block of statements you want to repeat

135
DO...LOOP

DO
statementblock
LOOP UNTIL condition
Parameter Description
statementblock The block of statements you want to repeat
condition The condition you are testing

DO
statementblock
LOOP WHILE condition
Parameter Description
statementblock The block of statements you want to repeat
condition The condition you are testing

Usage Use DO WHILE or DO UNTIL when you want to execute a block of

statements only if a condition is TRUE (for WHILE) or FALSE (for UNTIL).
DO WHILE and DO UNTIL test the condition before executing the block of
statements.
Use LOOP WHILE or LOOP UNTIL when you want to execute a block of
statements at least once. LOOP WHILE and LOOP UNTIL test the condition
after the block of statements has been executed.
Examples DO UNTIL The following DO UNTIL repeatedly executes the Beep function
until A is greater than 15:
integer A = 1, B = 1
DO UNTIL A > 15
Beep(A)
A = (A + 1) * B
LOOP
DO WHILE The following DO WHILE repeatedly executes the Beep
function only while A is less than or equal to 15:
integer A = 1, B = 1
DO WHILE A <= 15
Beep(A)
A = (A + 1) * B
LOOP

136
 Chapter 7 PowerScript Statements

LOOP UNTIL The following LOOP UNTIL executes the Beep function and
then continues to execute the function until A is greater than 1:
integer A = 1, B = 1
DO
Beep(A)
A = (A + 1) * B
LOOP UNTIL A > 15
LOOP WHILE The following LOOP WHILE repeatedly executes the Beep
function while A is less than or equal to 15:
integer A = 1, B = 1
DO
Beep(A)
A = (A + 1) * B
LOOP WHILE A <= 15

137
EXIT

EXIT
Description In a DO...LOOP or a FOR...NEXT control structure, passes control out of the
current loop. EXIT takes no parameters.
Syntax EXIT
Usage An EXIT statement in a DO...LOOP or FOR...NEXT control structure causes
control to pass to the statement following the LOOP or NEXT statement. In a
nested loop, an EXIT statement passes control out of the current loop structure.
For information on how to jump to the end of the loop and continue looping,
see CONTINUE on page 130.
Examples Example 1 This EXIT statement causes the loop to terminate if an element in
the Nbr array equals 0:
int Nbr[10]
int Count = 1
// Assume values get assigned to Nbr array...
DO WHILE Count < 11
IF Nbr[Count] = 0 THEN EXIT
Count = Count + 1
LOOP
MessageBox("Hi", "Count is now " + String(Count) )
Example 2 This EXIT statement causes the loop to terminate if an element in
the Nbr array equals 0:
int Nbr[10]
int Count
// Assume values get assigned to Nbr array...
FOR Count = 1 to 10
IF Nbr[Count] = 0 THEN EXIT
NEXT
MessageBox("Hi", "Count is now " + String(Count) )

138
 Chapter 7 PowerScript Statements

FOR...NEXT
Description A control structure that is a numerical iteration, used to execute one or more
statements a specified number of times.
Syntax FOR varname = start TO end {STEP increment}
statementblock
NEXT
Parameter Description
varname The name of the iteration counter variable. It can be any
numerical type (integer, double, real, long, or decimal),
but integers provide the fastest performance
start Starting value of varname
end Ending value of varname
increment The increment value. Increment must be a constant and
(optional) the same data type as varname. If you enter an increment,
STEP is required. +1 is the default increment
statementblock The block of statements you want to repeat

Usage Using the start and end parameters For a positive increment, end must be
greater than start. For a negative increment, end must be less than start.
When increment is positive and start is greater than end, statementblock does
not execute. When increment is negative and start is less than end,
statementblock does not execute.
When start and end are expressions, they are reevaluated on each pass through
the loop. So if the expression’s value changes, it will affect the number of
loops. Consider this example—the body of the loop changes the number of
rows, which changes the result of the RowCount function:
FOR n = 1 TO dw_1.RowCount( )
dw_1.DeleteRow(1)
NEXT

A variable as the step increment

If you need to use a variable for the step increment, you can use one of the
DO...LOOP constructions and increment the counter yourself within the loop.

Nesting You can nest FOR...NEXT statements. You must have a NEXT for
each FOR.
You can end the FOR loop with the keywords END FOR instead of NEXT.

139
FOR...NEXT

Avoid overflow
If start or end is too large for the data type of varname, varname will overflow,
which could create an infinite loop. Consider this statement for the integer
li_int.
FOR li_int = 1 TO 50000
The end value 50000 is too large for an integer. When li_int is incremented, it
overflows to a negative value before reaching 50000, creating an infinite loop.

Examples Example 1 These statements add 10 to A as long as n is >=5 and <=25:

FOR n = 5 to 25
A = A+10
NEXT
Example 2 These statements add 10 to A and increment n by 5 as long as n
is >= 5 and <=25:
FOR N = 5 TO 25 STEP 5
A = A+10
NEXT
Example 3 These statements contain two lines that will never execute
because increment is negative and start is less than end:
FOR Count = 1 TO 100 STEP -1
IF Count < 1 THEN EXIT // These 2 lines
Box[Count] = 10 // will never execute.
NEXT
Example 4 These are nested FOR...NEXT statements:
Int Matrix[100,50,200]
FOR i = 1 to 100
FOR j = 1 to 50
FOR k = 1 to 200
Matrix[i,j,k]=1
NEXT
NEXT
NEXT

140
 Chapter 7 PowerScript Statements

GOTO
Description Transfers control from one statement in a script to another statement that is
labeled.
Syntax GOTO label
Parameter Description
label The label associated with the statement to which you
want to transfer control. A label is an identifier followed
by a colon (such as OK:). Do not use the colon with a
label in the GOTO statement

Examples Example 1 This GOTO statement skips over the Taxable=FALSE line:
Goto NextStep
Taxable=FALSE //This statement will never
//execute.
NextStep:
Rate=Count/Count4
Example 2 This GOTO statement transfers control to the statement
associated with the label OK:
GOTO OK
.
.
.
OK:
.
.
.

141
HALT

HALT
Description Terminates an application.
Syntax HALT {CLOSE}
Usage When PowerBuilder encounters Halt without the keyword CLOSE, it
immediately terminates the application.
When PowerBuilder encounters Halt with the keyword CLOSE, it immediately
executes the script for the Close event for the application and then terminates
the application. If there is no script for the Close event at the application level,
PowerBuilder immediately terminates the application.
Examples Example 1 This statement stops the application if the user enters a password
in the SingleLineEdit named sle_password that does not match the value stored
in a string named CorrectPassword:
IF sle_password.Text <> CorrectPassword THEN HALT
Example 2 This statement executes the script for the Close event for the
application before it terminates the application if the user enters a password in
sle_password that does not match the value stored in the string
CorrectPassword:
IF sle_password.Text <> CorrectPassword &
THEN HALT CLOSE

142
 Chapter 7 PowerScript Statements

IF...THEN
Description A control structure used to cause a script to perform a specified action if a
stated condition is true. Syntax 1 uses a single-line format and Syntax 2 uses a
multiline format.
Syntax Syntax 1 (the single-line format):
IF condition THEN action1 {ELSE action2}

Parameter Description
condition The condition you want to test
action1 The action you want performed if the condition is TRUE.
The action must be a single statement on the same line as
the rest of the IF statement
action2 The action you want performed if the condition is
(optional) FALSE. The action must be a single statement on the
same line as the rest of the IF statement

Syntax 2 (the multiline format):

IF condition1 THEN
action1
{ ELSEIF condition2 THEN
action2
...}
{ ELSE
action3 }
END IF

Parameter Description
condition1 The first condition you want to test
action1 The action you want performed if condition1 is TRUE.
The action can be a statement or multiple statements that
are separated by semicolons or placed on separate lines.
At least one action is required
condition2 The condition you want to test if condition1 is FALSE.
(optional) You can have multiple ELSEIF...THEN statements in an
IF...THEN control structure
action2 The action you want performed if condition2 is TRUE.
The action can be a statement or multiple statements that
are separated by semicolons or placed on separate lines
action3 The action you want performed if none of the preceding
(optional) conditions is true. The action can be a statement or
multiple statements that are separated by semicolons or
placed on separate lines

143
IF...THEN

Usage You can use continuation characters to place the single-line format on more
than one physical line in the script.
You must end a multiline IF...THEN control structure with END IF (which is
two words).
Examples Example 1 This single-line IF...THEN statement opens window w_first if
Num = 1; otherwise, w_rest is opened:
IF Num = 1 THEN Open(w_first) ELSE Open(w_rest)
Example 2 This single-line IF...THEN statement displays a message if the
value in the SingleLineEdit sle_State is TX. It uses the continuation character
to continue the single-line statement across two physical lines in the script:
IF sle_State.text="TX" THEN &
MessageBox("Hello","Tex")
Example 3 This multiline IF...THEN compares the horizontal positions of
windows w_first and w_second. If w_first is to the right of w_second, w_first
is moved to the left side of the screen:
IF w_first.X > w_second.X THEN
w_first.X = 0
END IF
Example 4 This multiline IF...THEN causes the application to:
• Beep twice if X equals Y
• Display the Parts listbox and highlight item 5 if X equals Z
• Display the Choose listbox if X is blank
• Hide the Empty button and display the Full button if none of the above
conditions is TRUE
IF X=Y THEN
Beep(2)
ELSEIF X=Z THEN
Show (lb_parts); lb_parts.SetState(5,TRUE)
ELSEIF X=" " THEN
Show (lb_choose)
ELSE
Hide(cb_empty)
Show(cb_full)
END IF

144
 Chapter 7 PowerScript Statements

RETURN
Description Stops the execution of a script or function immediately.
Syntax RETURN { expression }
Parameter Description
expression In a function, any value (or expression) you want the
function to return. The return value must be the data type
specified as the return type in the function

Usage When a user’s action triggers an event and PowerBuilder encounters RETURN
in the event script, it terminates execution of that script immediately and waits
for the next user action.
When a script calls a function or event and PowerBuilder encounters RETURN
in the code, RETURN transfers (returns) control to the point at which the
function or event was called.
Examples Example 1 This script causes the system to beep once; the second beep
statement will not execute:
Beep(1)
RETURN
Beep(1) // This statement will not execute.
Example 2 These statements in a user-defined function return the result of
dividing Arg1 by Arg2 if Arg2 is not equal to zero; they return -1 if Arg2 is
equal to zero:
IF Arg2 <> 0 THEN
RETURN Arg1/Arg2
ELSE
RETURN -1
END IF

145
THROW

THROW
Description Used to manually trigger exception handling for user-defined exceptions.
Syntax THROW exlvalue
Parameter Description
exlvalue Variable (or expression that evaluates to a valid instance of an
object) of type Throwable. Usually the object type thrown is a
user-defined exception class derived from the system Exception
class that inherits from Throwable

Usage The variable following the THROW reserved word must be a valid object
instance or an expression that produces a valid object instance that derives
from the Throwable data type. For example, you can use an expression such as:
THROW create ExceptionType
where ExceptionType is an object of type Throwable.
If you attempt to throw a noninstantiated exception, you will not get back the
exception information you want, since the only exception information you
retrieve will be a NullObjectError.
In a method script, you can only throw an exception that you declare in the
method prototype or that you handle in a TRY-CATCH block. The PowerScript
compiler displays an error message if you try to throw a user-defined exception
without declaring it in the prototype Throws statement and without
surrounding it in an appropriate TRY-CATCH block.
When a RuntimeError—or a descendant of RuntimeError—is thrown, the
instance variable containing line number information will be filled in at the
point where the THROW statement occurs. If the error is handled and thrown
again, this information will not be updated unless it has specifically been set to
NULL.
Examples long ll_result
ll_result = myConnection.ConnectToServer()

if (ll_result < > 0) then

ConnectionException ex
ex = create ConnectionException
ex.connectResult = ll_result
THROW ex
end if

146
 Chapter 7 PowerScript Statements

THROWS
Description Used to declare the type of exception that a method triggers. It is part of the
method prototype.
Syntax methodname ( {arguments} ) THROWS ExceptionType { , ExceptionType, ... }
Parameter Description
methodname Name of the method that throws an exception
arguments Arguments of the method that throws an exception. Depending
on the method, the method arguments can be optional
ExceptionType Object of type Throwable. Usually the object type thrown is a
user-defined exception class derived from the system Exception
class. If you define multiple potential exceptions for a method,
you can throw each type of exception in the same clause by
separating the exception types with commas

Usage Internal use only.

You do not type or otherwise add the THROWS clause to your method calls in
a PowerBuilder script. However, you can add a THROWS clause of any
PowerBuilder function or to any user event that is not defined by a pbm event
ID.
You add an object of type Throwable to the THROWS clause of a method by
dragging and dropping it (the exception object) from the System Tree to the
Throws box in the Prototype area of the Script view, or by typing the name of
the user object in the Throws box. If you type the names of multiple user
objects in the Throws box, use a comma to separate the object names. When
you drag-and-drop multiple user objects, PowerBuilder automatically adds the
comma separators.

How to display the THROWS clause

The THROWS clause of a method is displayable only in the Script view
Throws box for that method. You can use the leftmost toggle button in the
Script view to display or hide the Prototype area containing the Throws box.
The THROWS clause is not displayed as part of the method prototype in the
Browser, the Function List view, or in the System Tree.

147
THROWS

The exceptions you add to the THROWS clause are usually checked
exceptions. The PowerBuilder compiler checks whether a user-defined
exception thrown on a method call in a script matches an exception in the
THROWS clause for that method. PowerBuilder automatically adds the
RuntimeError object and its descendents to the THROWS clause of all
methods, so it is not necessary to add them yourself.
If you select a high-level exception or error type for the THROWS clause of a
given method, you can throw any lower-level exception or error in the method
script, but in that case you risk hiding any useful information obtainable from
the lower-level exception or error.

148
 Chapter 7 PowerScript Statements

TRY...CATCH...FINALLY...END TRY
Description Isolates code that can cause an exception, describes what to do if an exception
of a given type is encountered, and allows you to close files or network
connections (and return objects to their original state) whether or not an
exception is encountered.
Syntax TRY
statementClauseT
{ CATCH ( ThrowableType exIdentifier )
statementClauseC }
{ ... }
{ FINALLY
statementClauseF }
END TRY
Parameter Description
statementClauseT Block of code that might potentially throw an exception
ThrowableType Object type of exception or error to be caught. The CATCH
clause is optional, but for every CATCH clause in a TRY
block you must include a corresponding exception object
type and a local variable of that type
exIdentifier Local variable of type ThrowableType
statementClauseC Code to handle the exception being caught
statementClauseF Cleanup code. The FINALLY clause, like the CATCH
clause, is optional—although you cannot code a TRY block
without either a CATCH clause or a FINALLY clause

Usage Braces indicate optional parameters

Do not surround statements in a TRY, CATCH, or FINALLY clause with
braces, as in Java. The braces in the syntax are only used to indicate that the
clause contained within them is optional for a TRY block.

The TRY block is used to isolate code that might potentially throw an
exception. The statements between the TRY and CATCH keywords (or the
TRY and FINALLY keywords if there is no CATCH clause) are run
unconditionally until either the entire block of statements is executed or some
statement in the block causes an exception to be thrown.

149
TRY...CATCH...FINALLY...END TRY

Use a CATCH clause or multiple CATCH clauses to handle exceptions thrown

in a TRY block. In the event that an exception is thrown, execution of the TRY
clause is stopped and the statements in the CATCH clause are executed if and
only if the exception thrown is of the same type or a descendant of the type of
the identifier following the CATCH reserved word.
If the exception thrown is not the same type or a descendant type of the
identifier, the exception is not handled by this CATCH clause. The exception
then continues to unwind the call stack to any outer nested TRY-CATCH
blocks. (But before it unwinds the stack, the statements in the FINALLY clause
of the original TRY block are executed). If there are no outer nested blocks, the
standard SystemError event on the Application object is fired.
If no exception is thrown, execution continues at the beginning of the
FINALLY clause if one exists; otherwise, execution continues on the line
following the END TRY statement.
See also THROW

150
CH A PTE R 8 SQL Statements

About this chapter This chapter describes the embedded SQL and dynamic SQL statements
and how to use them in scripts.
Contents
Topic Page
Using SQL in scripts 152
CLOSE Cursor 155
CLOSE Procedure 156
COMMIT 157
CONNECT 158
DECLARE Cursor 159
DECLARE Procedure 160
DELETE 162
DELETE Where Current of Cursor 163
DISCONNECT 164
EXECUTE 165
FETCH 166
INSERT 167
OPEN Cursor 168
ROLLBACK 169
SELECT 170
SELECTBLOB 172
UPDATE 174
UPDATEBLOB 175
UPDATE Where Current of Cursor 177
Using dynamic SQL 178
Dynamic SQL Format 1 182
Dynamic SQL Format 2 183
Dynamic SQL Format 3 185
Dynamic SQL Format 4 188

151
Using SQL in scripts

Using SQL in scripts

General information PowerScript supports standard embedded SQL statements and dynamic SQL
statements in scripts.
In general, PowerScript supports all DBMS-specific clauses and reserved
words that occur in the supported SQL statements. For example, PowerBuilder
supports DBMS-specific built-in functions within a SELECT command.
For information about embedded SQL, see online Help.
Referencing Wherever constants can be referenced in SQL statements, PowerScript
PowerScript variables variables preceded by a colon (:) can be substituted. Any valid PowerScript
in scripts
variable can be used.
This INSERT statement uses a constant value:
INSERT INTO EMPLOYEE ( SALARY )
VALUES ( 18900 ) ;
The same statement using a PowerScript variable to reference the constant
might look like this:
int Sal_var
Sal_var = 18900
INSERT INTO EMPLOYEE ( SALARY )
VALUES ( :Sal_var ) ;
Using indicator PowerBuilder supports indicator variables, which are used to identify NULL
variables values or conversion errors after a database retrieval. Indicator variables are
integers that are specified in the HostVariableList of a FETCH or SELECT
statement.
Each indicator variable is separated from the variable it is indicating by a space
(but no comma). For example, this statement is a HostVariableList without
indicator variables:
:Name, :Address, :City
The same HostVariableList with indicator variables might look like this:
:Name :IndVar1, :Address :IndVar2, :City :IndVar3
Indicator variables have one of these values:
Numerical value Meaning
0 Valid, non-NULL value
-1 NULL value
-2 Conversion error

152
 Chapter 8 SQL Statements

Error reporting
Not all DBMSs return a conversion error when the data type of a column does
not match the data type of the associated variable.

The following statement uses the indicator variable IndVar2 to see if Address
contains a NULL value:
if IndVar2 = -1 then...
You could also use the PowerScript IsNull function to accomplish the same
result without using indicator variables:
if IsNull( Address ) then ...
This statement uses the indicator variable IndVar3 to set City to NULL:
IndVar3 = -1
You could also use the PowerScript SetNull function to accomplish the same
result without using indicator variables:
SetNull( City )
For information about the SetNull function, see SetNull on page 1084.
Error handling in The scripts shown in the SQL examples above do not include error handling,
scripts but it is good practice to test the success and failure codes (the SQLCode
attribute) in the transaction object after every statement. The codes are:
Value Meaning
0 Success
100 Fetched row not found
-1 Error; the statement failed. Use SQLErrText or SQLDBCode to obtain
the detail.

After certain statements such as DELETE, FETCH, and UPDATE, you should
also check the SQLNRows property of the transaction object to make sure the
action affected at least one row.
About SQLErrText and SQLDBCode The string SQLErrText in the
transaction object contains the database vendor–supplied error message. The
long named SQLDBCode in the transaction object contains the database
vendor–supplied status code:
IF SQLCA.SQLCode = -1 THEN
MessageBox("SQL error", SQLCA.SQLErrText)
END IF

153
Using SQL in scripts

Painting standard You can paint the following SQL statements in scripts and functions:
SQL
• Declarations of SQL cursors and stored procedures
• Cursor FETCH, UPDATE, and DELETE statements
• Noncursor SELECT, INSERT, UPDATE, and DELETE statements
For more information about scope, see "Where to declare variables" on page
36.
You can declare cursors and stored procedures at the scope of global, instance,
shared, or local variables. A cursor or procedure can be declared in the Script
view using the Paste SQL button in the PainterBar.
You can paint standard embedded SQL statements in the Script view, the
Function painter, and the Interactive SQL view in the Database painter using
the Paste SQL button in the PainterBar or the Paste Special>SQL item from the
popup menu.
Supported SQL In general, all DBMS-specific features are supported in PowerScript as long as
statements they occur within a PowerScript-supported SQL statement. For example,
PowerScript supports DBMS-specific built-in functions within a SELECT
command.

154
 Chapter 8 SQL Statements

CLOSE Cursor
Description Closes the SQL cursor CursorName; ends processing of CursorName.
Syntax CLOSE CursorName ;
Parameter Description
CursorName The cursor you want to close

Usage This statement must be preceded by an OPEN statement for the same cursor.
The USING TransactionObject clause is not allowed with CLOSE; the
transaction object was specified in the statement that declared the cursor.
CLOSE often appears in the script that is executed when the SQL code after a
fetch equals 100 (not found).

Error handling
It is good practice to test the success/failure code after executing a CLOSE
Cursor statement.

Examples This statement closes the Emp_cursor cursor:

CLOSE Emp_cursor ;

155
CLOSE Procedure

CLOSE Procedure
Description Closes the SQL procedure ProcedureName; ends processing of
ProcedureName.

DBMS-specific
Not all DBMSs support stored procedures.

Syntax CLOSE ProcedureName ;

Parameter Description
ProcedureName The stored procedure you want to close

Usage This statement must be preceded by an EXECUTE statement for the same
procedure. The USING TransactionObject clause is not allowed with CLOSE;
the transaction object was specified in the statement that declared the
procedure.
You only need to use CLOSE to close procedures that return result sets.
PowerBuilder automatically closes procedures that don’t return result sets (and
sets the return code to 100).
CLOSE often appears in the script that is executed when the SQL code after a
fetch equals 100 (not found).

Error handling
It is good practice to test the success/failure code after executing a CLOSE
Procedure statement.

Examples This statement closes the stored procedure named Emp_proc:

CLOSE Emp_proc ;

156
 Chapter 8 SQL Statements

COMMIT
Description Permanently updates all database operations since the previous COMMIT,
ROLLBACK, or CONNECT for the specified transaction object.

Using COMMIT and ROLLBACK in a server component

COMMIT and ROLLBACK commands embedded in a server component may
have different effects depending on the setting of the UseContextObject
DBParm parameter.
For information on the UseContextObject parameter see Connecting to Your
Database. For information on deploying components to a transaction server,
see Application Techniques.

Syntax COMMIT {USING TransactionObject} ;

Parameter Description
TransactionObject The name of the transaction object for which you want to
permanently update all database operations since the
previous COMMIT, ROLLBACK, or CONNECT. This
clause is required only for transaction objects other than
the default (SQLCA)

Usage COMMIT does not cause a disconnect, but it does close all open cursors or
procedures. (But note that the DISCONNECT statement in PowerBuilder does
issue a COMMIT.)

Error handling
It is good practice to test the success/failure code after executing a COMMIT
statement.

Examples Example 1 This statement commits all operations for the database specified
in the default transaction object:
COMMIT ;
Example 2 This statement commits all operations for the database specified
in the transaction object named Emp_tran:
COMMIT USING Emp_tran ;

157
CONNECT

CONNECT
Description Connects to a specified database.
Syntax CONNECT {USING TransactionObject} ;
Parameter Description
TransactionObject The name of the transaction object containing the
required connection information for the database to
which you want to connect. This clause is required only
for transaction objects other than the default (SQLCA)

Usage This statement must be executed before any actions (such as INSERT,
UPDATE, or DELETE) can be processed using the default transaction object
or the specified transaction object.

Error handling
It is good practice to test the success/failure code after executing a CONNECT
statement.

Examples Example 1 This statement connects to the database specified in the default
transaction object:
CONNECT ;
Example 2 This statement connects to the database specified in the
transaction object named Emp_tran:
CONNECT USING Emp_tran ;

158
 Chapter 8 SQL Statements

DECLARE Cursor
Description Declares a cursor for the specified transaction object.
Syntax DECLARE CursorName CURSOR FOR SelectStatement
{USING TransactionObject} ;
Parameter Description
CursorName Any valid PowerBuilder name
SelectStatement Any valid SELECT statement
TransactionObject The name of the transaction object for which you want to
declare the cursor. This clause is required only for
transaction objects other than the default (SQLCA)

Usage DECLARE Cursor is a nonexecutable command and is analogous to declaring

a variable.
To declare a local cursor, open the script in the Script view and select Paste
SQL from the PainterBar or the Edit>Paste Special menu. To declare a global,
instance, or shared cursor, select Declare from the first dropdown listbox in the
Script view and Global Variables, Instance Variables, or Shared Variables from
the second dropdown listbox, then select Paste SQL.
For information about global, instance, shared, and local scope, see "Where to
declare variables" on page 36.
Examples This statement declares the cursor called Emp_cur for the database specified in
the default transaction object. It also references the Sal_var variable, which
must be set to an appropriate value before you execute the OPEN Emp_cur
command:
DECLARE Emp_cur CURSOR FOR
SELECT employee.emp_number, employee.emp_name
FROM employee
WHERE employee.emp_salary > :Sal_var ;

159
DECLARE Procedure

DECLARE Procedure
Description Declares a procedure for the specified transaction object.

DBMS-specific
Not all DBMSs support stored procedures.

Syntax DECLARE ProcedureName PROCEDURE FOR

StoredProcedureName
@Param1=Value1, @Param2=Value2,...
{USING TransactionObject} ;
Parameter Description
ProcedureName Any valid PowerBuilder name
StoredProcedureName Any stored procedure in the database
@Paramn=Valuen The name of a parameter (argument) defined in the
stored procedure and a valid PowerBuilder
expression; represents the number of the parameter
and value
TransactionObject The name of the transaction object for which you
want to declare the procedure. This clause is required
only for transaction objects other than the default
(SQLCA)

Usage DECLARE Procedure is a nonexecutable command. It is analogous to

declaring a variable.
To declare a local procedure, open the script in the Script view and select Paste
SQL from the PainterBar or the Edit>Paste Special menu. To declare a global,
instance, or shared procedure, select Declare from the first dropdown listbox in
the Script view and Global Variables, Instance Variables, or Shared Variables
from the second dropdown listbox, then select Paste SQL.
For information about global, instance, shared, and local scope, see "Where to
declare variables" on page 36.
Examples Example 1 This statement declares the Sybase ASE procedure Emp_proc for
the database specified in the default transaction object. It references the
Emp_name_var and Emp_sal_var variables, which must be set to appropriate
values before you execute the EXECUTE Emp_proc command:
DECLARE Emp_proc procedure for GetName
@emp_name = :Emp_name_var,
@emp_salary = :Emp_sal_var ;

160
 Chapter 8 SQL Statements

Example 2 This statement declares the ORACLE procedure Emp_proc for

the database specified in the default transaction object. It references the
Emp_name_var and Emp_sal_var variables, which must be set to appropriate
values before you execute the EXECUTE Emp_proc command:
DECLARE Emp_proc procedure for GetName
(:Emp_name_var, :Emp_sal_var) ;

161
DELETE

DELETE
Description Deletes the rows in TableName specified by Criteria.
Syntax DELETE FROM TableName WHERE Criteria {USING TransactionObject} ;
Parameter Description
TableName The name of the table from which you want to delete
rows
Criteria Criteria that specify which rows to delete
TransactionObject The name of the transaction object that identifies the
database containing the table. This clause is required
only for transaction objects other than the default
(SQLCA)

Usage Error handling

It is good practice to test the success/failure code after executing a DELETE
statement. To see if the DELETE was successful, you can test SLQCode for a
failure code. However, if nothing matches the WHERE clause and no rows are
deleted, SQLCode is still set to zero. To make sure the delete affected at least
one row, check the SQLNRows property of the transaction object.

Examples Example 1 This statement deletes rows from the Employee table in the
database specified in the default transaction object where Emp_num is less
than 100:
DELETE FROM Employee WHERE Emp_num < 100 ;
Example 2 These statements delete rows from the Employee table in the
database named in the transaction object named Emp_tran where Emp_num is
equal to the value entered in the SingleLineEdit sle_number:
int Emp_num
Emp_num = Integer(sle_number.Text)
DELETE FROM Employee
WHERE Employee.Emp_num = :Emp_num ;
The integer Emp_num requires a colon in front of it to indicate it is a variable
when it is used in a WHERE clause.

162
 Chapter 8 SQL Statements

DELETE Where Current of Cursor

Description Deletes the row in which the cursor is positioned.

DBMS-specific
Not all DBMSs support DELETE Where Current of Cursor.

Syntax DELETE FROM TableName WHERE CURRENT OF CursorName ;

Parameter Description
TableName The name of the table from which you want to delete a
row
CursorName The name of the cursor in which the table was specified

Usage The USING TransactionObject clause is not allowed with this form of
DELETE Where Current of Cursor; the transaction object was specified in the
statement that declared the cursor.

Error handling
It is good practice to test the success/failure code after executing a DELETE
Where Current of Cursor statement.

Examples This statement deletes from the Employee table the row in which the cursor
named Emp_cur is positioned:
DELETE FROM Employee WHERE current of Emp_curs ;

163
DISCONNECT

DISCONNECT
Description Executes a COMMIT for the specified transaction object and then disconnects
from the specified database.
Syntax DISCONNECT {USING TransactionObject} ;
Parameter Description
TransactionObject The name of the transaction object that identifies the
database you want to disconnect from and in which you
want to permanently update all database operations since
the previous COMMIT, ROLLBACK, or CONNECT.
This clause is required only for transaction objects other
than the default (SQLCA)

Usage Error handling

It is good practice to test the success/failure code after executing a
DISCONNECT statement.

Examples Example 1 This statement disconnects from the database specified in the
default transaction object:
DISCONNECT ;
Example 2 This statement disconnects from the database specified in the
transaction object named Emp_tran:
DISCONNECT USING Emp_tran ;

164
 Chapter 8 SQL Statements

EXECUTE
Description Executes the previously declared procedure identified by ProcedureName.
Syntax EXECUTE ProcedureName ;
Parameter Description
ProcedureName The name assigned in the DECLARE statement of the
stored procedure you want to execute. The procedure
must have been declared previously. ProcedureName is
not necessarily the name of the procedure stored in the
database

Usage The USING TransactionObject clause is not allowed with EXECUTE; the
transaction object was specified in the statement that declared the procedure.

Error handling
It is good practice to test the success/failure code after executing an EXECUTE
statement.

Examples This statement executes the stored procedure Emp_proc:

EXECUTE Emp_proc ;

165
FETCH

FETCH
Description Fetches the row after the row on which Cursor | Procedure is positioned.
Syntax FETCH Cursor | Procedure INTO HostVariableList ;
Parameter Description
Cursor or Procedure The name of the cursor or procedure from which you
want to fetch a row
HostVariableList PowerScript variables into which data values will be
retrieved

Usage The USING TransactionObject clause is not allowed with FETCH; the
transaction object was specified in the statement that declared the cursor or
procedure.
If your DBMS supports formats of FETCH other than the customary (and
default) FETCH NEXT, you can specify FETCH FIRST, FETCH PRIOR, or
FETCH LAST.

Error handling
It is good practice to test the success/failure code after executing a FETCH
statement. To see if the FETCH was successful, you can test SLQCode for a
failure code. However, if nothing matches the WHERE clause and no rows are
fetched, SQLCode is still set to 100. To make sure the fetch affected at least
one row, check the SQLNRows property of the transaction object.

Examples Example 1 This statement fetches data retrieved by the SELECT clause in
the declaration of the cursor named Emp_cur and puts it into Emp_num and
Emp_name:
int Emp_num
string Emp_name
FETCH Emp_cur INTO :Emp_num, :Emp_name ;
Example 2 If sle_emp_num and sle_emp_name are SingleLineEdits, these
statements fetch from the cursor named Emp_cur, store the data in Emp_num
and Emp_name, and then convert Emp_num from an integer to a string, and
put them in sle_emp_num and sle_emp_name:
int Emp_num
string Emp_name
FETCH Emp_cur INTO :emp_num, :emp_name ;
sle_emp_num.Text = string(Emp_num)
sle_emp_name.Text = Emp_name

166
 Chapter 8 SQL Statements

INSERT
Description Inserts one or more new rows into the table specified in RestOfInsertStatement.
Syntax INSERT RestOfInsertStatement
{USING TransactionObject} ;
Parameter Description
RestOfInsertStatement The rest of the INSERT statement (the INTO clause,
list of columns and values or source)
TransactionObject The name of the transaction object that identifies the
database containing the table. This clause is required
only for transaction objects other than the default
(SQLCA)

Usage Error handling

It is good practice to test the success/failure code after executing an INSERT
statement.

Examples Example 1 These statements insert a row with the values in EmpNbr and
EmpName into the Emp_nbr and Emp_name columns of the Employee table
identified in the default transaction object:
int EmpNbr
string EmpName
...
INSERT INTO Employee (employee.Emp_nbr,
employee.Emp_name)
VALUES (:EmpNbr, :EmpName) ;
Example 2 These statements insert a row with the values entered in the
SingleLineEdits sle_number and sle_name into the Emp_nbr and Emp_name
columns of the Employee table in the transaction object named Emp_tran:
int EmpNbr
string EmpName
EmpNbr = Integer(sle_number.Text)
EmpName = sle_name.Text
INSERT INTO Employee (employee.Emp_nbr,
employee.Emp_name)
VALUES (:EmpNbr, :EmpName) USING Emp_tran ;

167
OPEN Cursor

OPEN Cursor
Description Causes the SELECT specified when the cursor was declared to be executed.
Syntax OPEN CursorName ;
Parameter Description
CursorName The name of the cursor you want to open

Usage The USING TransactionObject clause is not allowed with OPEN; the
transaction object was specified in the statement that declared the cursor.

Error handling
It is good practice to test the success/failure code after executing an OPEN
Cursor statement.

Examples This statement opens the cursor Emp_curs:

OPEN Emp_curs ;

168
 Chapter 8 SQL Statements

ROLLBACK
Description Cancels all database operations in the specified database since the last
COMMIT, ROLLBACK, or CONNECT.

Using COMMIT and ROLLBACK in a server component

COMMIT and ROLLBACK commands embedded in a server component may
have different effects depending on the setting of the UseContextObject
DBParm parameter.
For information on the UseContextObject parameter see Connecting to Your
Database. For information on deploying components to a transaction server,
see Application Techniques.

Syntax ROLLBACK {USING TransactionObject} ;

Parameter Description
TransactionObject The name of the transaction object that identifies the
database in which you want to cancel all operations since
the last COMMIT, ROLLBACK, or CONNECT. This
clause is required only for transaction objects other than
the default (SQLCA)

Usage ROLLBACK does not cause a disconnect, but it does close all open cursors and
procedures.

Error handling
It is good practice to test the success/failure code after executing a
ROLLBACK statement.

Examples Example 1 This statement cancels all database operations in the database
specified in the default transaction object:
ROLLBACK ;
Example 2 This statement cancels all database operations in the database
specified in the transaction object named Emp_tran:
ROLLBACK USING emp_tran ;

169
SELECT

SELECT
Description Selects a row in the tables specified in RestOfSelectStatement.
Syntax SELECT RestOfSelectStatement
{USING TransactionObject} ;
Parameter Description
RestOfSelectStatement The rest of the SELECT statement (the column list
INTO, FROM, WHERE, and other clauses)
TransactionObject The name of the transaction object that identifies the
database containing the table. This clause is required
only for transaction objects other than the default
(SQLCA)

Usage An error occurs if the SELECT statement returns more than one row.

Error handling
It is good practice to test the success/failure code after executing a SELECT
statement. You can test SQLCode for a failure code.

When you use the INTO clause, PowerBuilder does not verify whether the data
type of the retrieved column matches the data type of the host variable. It only
checks for the existence of the columns and tables. You are responsible for
checking that the data types match. Keep in mind that not all database data
types are the same as PowerBuilder data types.
Examples The following statements select data in the Emp_LName and Emp_FName
columns of a row in the Employee table and put the data into the
SingleLineEdits sle_LName and sle_FName (the transaction object Emp_tran
is used):
int Emp_num
string Emp_lname, Emp_fname
Emp_num = Integer(sle_Emp_Num.Text)

SELECT employee.Emp_LName, employee.Emp_FName

INTO :Emp_lname, :Emp_fname
FROM Employee
WHERE Employee.Emp_nbr = :Emp_num
USING Emp_tran ;

IF Emp_tran.SQLCode = 100 THEN

MessageBox("Employee Inquiry", &
"Employee Not Found")
ELSEIF Emp_tran.SQLCode > 0 then

170
 Chapter 8 SQL Statements

MessageBox("Database Error", &

Emp_tran.SQLErrText, Exclamation!)
END IF
sle_Lname.text = Emp_lname
sle_Fname.text = Emp_fname

171
SELECTBLOB

SELECTBLOB
Description Selects a single blob column in a row in the table specified in
RestOfSelectStatement.
Syntax SELECTBLOB RestOfSelectStatement
{USING TransactionObject} ;
Parameter Description
RestOfSelectStatement The rest of the SELECT statement (the INTO,
FROM, and WHERE clauses)
TransactionObject The name of the transaction object that identifies the
database containing the table. This clause is required
only for transaction objects other than the default
(SQLCA)

Usage An error occurs if the SELECTBLOB statement returns more than one row.

Error handling
It is good practice to test the success/failure code after executing an
SELECTBLOB statement. To make sure the update affected at least one row,
check the SQLNRows property of SQLCA or the transaction object. The
SQLCode or SQLDBCode property will not indicate the success or failure of
the SELECTBLOB statement.

You can include an indicator variable in the host variable list (target
parameters) in the INTO clause to check for an empty blob (a blob of zero
length) and conversion errors.

Database information
Sybase ASE and Microsoft SQL Server users must set the AutoCommit
property of the transaction object to True before calling the SELECTBLOB
function.
For information about the AutoCommit property, see Connecting to Your
Database.

Examples The following statements select the blob column Emp_pic from a row in the
Employee table and set the picture p_1 to the bitmap in Emp_id_pic (the
transaction object Emp_tran is used):
Blob Emp_id_pic
SELECTBLOB Emp_pic
INTO :Emp_id_pic

172
 Chapter 8 SQL Statements

FROM Employee
WHERE Employee.Emp_Num = 100
USING Emp_tran ;
p_1.SetPicture(Emp_id_pic)
The blob Emp_id_pic requires a colon to indicate it is a host (PowerScript)
variable when you use it in the INTO clause of the SELECTBLOB statement.

173
UPDATE

UPDATE
Description Updates the rows specified in RestOfUpdateStatement.
Syntax UPDATE TableName RestOfUpdateStatement {USING TransactionObject} ;
Parameter Description
TableName The name of the table in which you want to update
rows
RestOfUpdateStatement The rest of the UPDATE statement (the SET and
WHERE clauses)
TransactionObject The name of the transaction object that identifies the
database containing the table. This clause is required
only for transaction objects other than the default
(SQLCA)

Usage Error handling

It is good practice to test the success/failure code after executing a UPDATE
statement. You can test SQLCode for a failure code. However, if nothing
matches the WHERE clause and no rows are updated, SQLCode is still set to
zero. To make sure the update affected at least one row, check the SQLNRows
property of the transaction object.

Examples These statements update rows from the Employee table in the database
specified in the transaction object named Emp_tran where Emp_num is equal
to the value entered in the SingleLineEdit sle_Number:
int Emp_num
Emp_num=Integer(sle_Number.Text )
UPDATE Employee
SET emp_name = :sle_Name.Text
WHERE Employee.emp_num = :Emp_num
USING Emp_tran ;

IF Emptran.SQLNRows > 0 THEN

COMMIT USING Emp_tran ;
END IF
The integer Emp_num and the SingleLineEdit sle_name require a colon to
indicate they are host (PowerScript) variables when you use them in an
UPDATE statement.

174
 Chapter 8 SQL Statements

UPDATEBLOB
Description Updates the rows in TableName in BlobColumn.
Syntax UPDATEBLOB TableName
SET BlobColumn = BlobVariable
RestOfUpdateStatement {USING TransactionObject} ;
Parameter Description
TableName The name of the table you want to update
BlobColumn The name of the column you want to update in
TableName. The data type of this column must be
blob
BlobVariable A PowerScript variable of the data type blob
RestOfUpdateStatement The rest of the UPDATE statement (the WHERE
clause)
TransactionObject The name of the transaction object that identifies the
database containing the table. This clause is
required only for transaction objects other than the
default (SQLCA)

Usage Error handling

It is good practice to test the success/failure code after executing an
UPDATEBLOB statement. To make sure the update affected at least one row,
check the SQLNRows property of SQLCA or the transaction object. The
SQLCode or SQLDBCode property will not indicate the success or failure of
the UPDATEBLOB statement.

Database information
Sybase ASE and Microsoft SQL Server users must set the AutoCommit
property of the transaction object to True before calling the UPDATEBLOB
function.
For information about the AutoCommit property, see Connecting to Your
Database.

Examples These statements update the blob column emp_pic in the Employee table
where emp_num is 100:
int fh
blob Emp_id_pic
fh = FileOpen("c:\emp_100.bmp", StreamMode!)
IF fh <> -1 THEN
FileRead(fh, emp_id_pic)

175
UPDATEBLOB

FileClose(fh)
UPDATEBLOB Employee SET emp_pic = :Emp_id_pic
WHERE Emp_num = 100
USING Emp_tran ;
END IF

IF Emptran.SQLNRows > 0 THEN

COMMIT USING Emp_tran ;
END IF
The blob Emp_id_pic requires a colon to indicate it is a host (PowerScript)
variable in the UPDATEBLOB statement.

176
 Chapter 8 SQL Statements

UPDATE Where Current of Cursor

Description Updates the row in which the cursor is positioned using the values in
SetStatement.
Syntax UPDATE TableName SetStatement
WHERE CURRENT OF CursorName ;
Parameter Description
TableName The name of the table in which you want to update the
row
SetStatement The word SET followed by a comma-separated list of the
form ColumnName = value
CursorName The name of the cursor in which the table is referenced

Usage The USING Transaction Object clause is not allowed with UPDATE Where
Current of Cursor; the transaction object was specified in the statement that
declared the cursor.
Examples This statement updates the row in the Employee table in which the cursor
called Emp_curs is positioned:
UPDATE Employee
SET salary = 17800
WHERE CURRENT of Emp_curs ;

177
Using dynamic SQL

Using dynamic SQL

General information Because database applications usually perform a specific activity, you usually
know the complete SQL statement when you write and compile the script.
When PowerBuilder does not support the statement in embedded SQL (as with
a DDL statement) or when the parameters or the format of the statements are
unknown at compile time, the application must build the SQL statements at
execution time. This is called dynamic SQL. The parameters used in dynamic
SQL statements can change each time the program is executed.

Using Adaptive Server Anywhere

For information about using dynamic SQL with Adaptive Server Anywhere,
see the Adaptive Server Anywhere Programming Interfaces book.

Four formats PowerBuilder has four dynamic SQL formats. Each format handles one of the
following situations at compile time:
Format When used
Format 1 Non-result-set statements with no input parameters
Format 2 Non-result-set statements with input parameters
Format 3 Result-set statements in which the input parameters and result-set
columns are known at compile time
Format 4 Result-set statements in which the input parameters, the result-set
columns or both are unknown at compile time

To handle these situations, you use:

• The PowerBuilder dynamic SQL statements
• The dynamic versions of CLOSE, DECLARE, FETCH, OPEN, and
EXECUTE
• The PowerBuilder data types DynamicStagingArea and
DynamicDescriptionArea

About the examples

The examples assume that the default transaction object (SQLCA) has been
assigned valid values and that a successful CONNECT has been executed.
Although the examples do not show error checking, you should check the
SQLCode after each SQL statement.

Dynamic SQL The PowerBuilder dynamic SQL statements are:

statements

178
 Chapter 8 SQL Statements

DESCRIBE DynamicStagingArea
INTO DynamicDescriptionArea ;
EXECUTE {IMMEDIATE} SQLStatement
{USING TransactionObject} ;
EXECUTE DynamicStagingArea
USING ParameterList ;
EXECUTE DYNAMIC Cursor | Procedure
USING ParameterList ;
OPEN DYNAMIC Cursor | Procedure
USING ParameterList ;
EXECUTE DYNAMIC Cursor | Procedure
USING DESCRIPTOR DynamicDescriptionArea ;
OPEN DYNAMIC Cursor | Procedure
USING DESCRIPTOR DynamicDescriptionArea ;
PREPARE DynamicStagingArea
FROM SQLStatement {USING TransactionObject} ;
Two data types DynamicStagingArea DynamicStagingArea is a PowerBuilder data type.
PowerBuilder uses a variable of this type to store information for use in
subsequent statements.
The DynamicStagingArea is the only connection between the execution of a
statement and a transaction object and is used internally by PowerBuilder; you
cannot access information in the DynamicStagingArea.
PowerBuilder provides a global DynamicStagingArea variable named SQLSA
that you can use when you need a DynamicStagingArea variable.
If necessary, you can declare and create additional object variables of the type
DynamicStagingArea. These statements declare and create the variable, which
must be done before referring to it in a dynamic SQL statement:
DynamicStagingArea dsa_stage1
dsa_stage1 = CREATE DynamicStagingArea
After the EXECUTE statement is completed, SQLSA is no longer referenced.
DynamicDescriptionArea DynamicDescriptionArea is a PowerBuilder data
type. PowerBuilder uses a variable of this type to store information about the
input and output parameters used in Format 4 of dynamic SQL.
PowerBuilder provides a global DynamicDescriptionArea named SQLDA that
you can use when you need a DynamicDescriptionArea variable.
If necessary, you can declare and create additional object variables of the type
DynamicDescriptionArea. These statements declare and create the variable,
which must be done before referring to it in a dynamic SQL statement:

179
Using dynamic SQL

DynamicDescriptionArea dda_desc1
dsa_desc1 = CREATE DynamicDescriptionArea
For more information about SQLDA, see Dynamic SQL Format 4 on page 188.
Preparing to use When you use dynamic SQL, you must:
dynamic SQL
• Prepare the DynamicStagingArea in all formats except Format 1
• Describe the DynamicDescriptionArea in Format 4
• Execute the statements in the appropriate order
Preparing and describing the data types Since the SQLSA staging area is
the only connection between the execution of a SQL statement and a
transaction object, an execution error will occur if you do not prepare the SQL
statement correctly.
In addition to SQLSA and SQLDA, you can declare other variables of the
DynamicStagingArea and DynamicDescriptionArea data types. However, this
is required only when your script requires simultaneous access to two or more
dynamically prepared statements.
This is a valid dynamic cursor:
DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA ;
PREPARE SQLSA FROM "SELECT emp_id FROM employee" ;
OPEN DYNAMIC my_cursor ;
This is an invalid dynamic cursor (there is no PREPARE, and therefore an
execution error will occur):
DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA ;
OPEN DYNAMIC my_cursor ;
Statement order Where you place the dynamic SQL statements in your
scripts is unimportant, but the order of execution is important in Formats 2, 3,
and 4. You must execute:
1 The DECLARE and the PREPARE before you execute any other dynamic
SQL statements
2 The OPEN in Formats 3 and 4 before the FETCH
3 The CLOSE at the end
If you have multiple PREPARE statements, the order affects the contents of
SQLSA.
These statements illustrate the correct ordering:
DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA

180
 Chapter 8 SQL Statements

string sql1, sql2

sql1 = "SELECT emp_id FROM department "&
WHERE salary > 90000"
sql2 = "SELECT emp_id FROM department "&
WHERE salary > 20000"

IF deptId = 200 then

PREPARE SQLSA FROM :sql1 USING SQLCA ;
ELSE
PREPARE SQLSA FROM :sql2 USING SQLCA ;
END IF
OPEN DYNAMIC my_cursor ; // my_cursor maps to the
// SELECT that has been
// prepared.

181
Dynamic SQL Format 1

Dynamic SQL Format 1

Description Use this format to execute a SQL statement that does not produce a result set
and does not require input parameters. You can use this format to execute all
forms of Data Definition Language (DDL).
Syntax EXECUTE IMMEDIATE SQLStatement
{USING TransactionObject} ;
Parameter Description
SQLStatement A string containing a valid SQL statement. The string
can be a string constant or a PowerBuilder variable
preceded by a colon (such as :mysql). The string must be
contained on one line and cannot contain expressions
TransactionObject The name of the transaction object that identifies the
(optional) database

Examples These statements create a database table named Employee. The statements use
the string Mysql to store the CREATE statement.

For Sybase ASE and Microsoft SQL Server users

If you are connected to an ASE or SQL Server database, set AUTOCOMMIT
to TRUE before executing the CREATE.

string Mysql
Mysql = "CREATE TABLE Employee "&
+"(emp_id integer not null,"&
+"dept_id integer not null, "&
+"emp_fname char(10) not null, "&
+"emp_lname char(20) not null)"
EXECUTE IMMEDIATE :Mysql ;
These statements assume a transaction object named My_trans exists and is
connected:
string Mysql
Mysql="INSERT INTO dept Values (1234, ’Purchasing’)"
EXECUTE IMMEDIATE :Mysql USING My_trans ;

182
 Chapter 8 SQL Statements

Dynamic SQL Format 2

Description Use this format to execute a SQL statement that does not produce a result set
but does require input parameters. You can use this format to execute all forms
of Data Definition Language (DDL).
Syntax PREPARE DynamicStagingArea FROM SQLStatement
{USING TransactionObject} ;
EXECUTE DynamicStagingArea USING {ParameterList} ;
Parameter Description
DynamicStagingArea The name of the DynamicStagingArea (usually
SQLSA)
If you need a DynamicStagingArea variable other
than SQLSA, you must declare it and instantiate it
with the CREATE statement before using it
SQLStatement A string containing a valid SQL statement. The string
can be a string constant or a PowerBuilder variable
preceded by a colon (such as :mysql). The string must
be contained on one line and cannot contain
expressions
Enter a question mark (?) for each parameter in the
statement. Value substitution is positional; reserved
word substitution is not allowed
TransactionObject The name of the transaction object that identifies the
(optional) database
ParameterList A comma-separated list of PowerScript variables.
(optional) Note that PowerScript variables are preceded by a
colon (:)

Usage To specify a NULL value, use the SetNull function.

Examples These statements prepare a DELETE statement with one parameter in SQLSA
and then execute it using the value of the PowerScript variable Emp_id_var:
INT Emp_id_var = 56
PREPARE SQLSA
FROM "DELETE FROM employee WHERE emp_id=?" ;
EXECUTE SQLSA USING :Emp_id_var ;
These statements prepare an INSERT statement with two parameters in
SQLSA and then execute it using the value of the PowerScript variables
Dept_id_var and Dept_name_var (note that Dept_name_var is NULL):
INT Dept_id_var = 156
String Dept_name_var
SetNull(Dept_name_var)

183
Dynamic SQL Format 2

PREPARE SQLSA
FROM "INSERT INTO dept VALUES (?,?)" ;
EXECUTE SQLSA USING :Dept_id_var,:Dept_name_var ;

184
 Chapter 8 SQL Statements

Dynamic SQL Format 3

Description Use this format to execute a SQL statement that produces a result set in which
the input parameters and result set columns are known at compile time.
Syntax DECLARE Cursor | Procedure
DYNAMIC CURSOR | PROCEDURE
FOR DynamicStagingArea ;
PREPARE DynamicStagingArea FROM SQLStatement
{USING TransactionObject} ;
OPEN DYNAMIC Cursor
{USING ParameterList} ;
EXECUTE DYNAMIC Procedure
{USING ParameterList} ;
FETCH Cursor | Procedure
INTO HostVariableList ;
CLOSE Cursor | Procedure ;
Parameter Description
Cursor or Procedure The name of the cursor or procedure you want to use
DynamicStagingArea The name of the DynamicStagingArea (usually
SQLSA)
If you need a DynamicStagingArea variable other than
SQLSA, you must declare it and instantiate it with the
CREATE statement before using it
SQLStatement A string containing a valid SQL SELECT statement The
string can be a string constant or a PowerBuilder
variable preceded by a colon (such as :mysql). The
string must be contained on one line and cannot contain
expressions
Enter a question mark (?) for each parameter in the
statement. Value substitution is positional; reserved
word substitution is not allowed
TransactionObject The name of the transaction object that identifies the
(optional) database
ParameterList A comma-separated list of PowerScript variables. Note
(optional) that PowerScript variables are preceded by a colon (:)
HostVariableList The list of PowerScript variables into which the data
values will be retrieved

Usage To specify a NULL value, use the SetNull function.

The DECLARE statement is not executable and can be declared globally.

185
Dynamic SQL Format 3

If your DBMS supports formats of FETCH other than the customary (and
default) FETCH NEXT, you can specify FETCH FIRST, FETCH PRIOR, or
FETCH LAST.
The FETCH and CLOSE statements in Format 3 are the same as in standard
embedded SQL.
To declare a local cursor or procedure, open the script in the Script view and
select Paste SQL from the PainterBar or the Edit>Paste Special menu. To
declare a global, instance, or shared cursor or procedure, select Declare from
the first dropdown listbox in the Script view and Global Variables, Instance
Variables, or Shared Variables from the second dropdown listbox, then select
Paste SQL.
For information about global, instance, shared, and local scope, see "Where to
declare variables" on page 36.
Examples Example 1 These statements associate a cursor named my_cursor with
SQLSA, prepare a SELECT statement in SQLSA, open the cursor, and return
the employee ID in the current row into the PowerScript variable Emp_id_var:
integer Emp_id_var
DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA ;
PREPARE SQLSA FROM "SELECT emp_id FROM employee" ;
OPEN DYNAMIC my_cursor ;
FETCH my_cursor INTO :Emp_id_var ;
CLOSE my_cursor ;
You can loop through the cursor as you can in embedded static SQL.
Example 2 These statements associate a cursor named my_cursor with
SQLSA, prepare a SELECT statement with one parameter in SQLSA, open the
cursor, and substitute the value of the variable Emp_state_var for the parameter
in the SELECT statement. The employee ID in the active row is returned into
the PowerBuilder variable Emp_id_var:
DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA ;
integer Emp_id_var
string Emp_state_var = "MA"
string sqlstatement

sqlstatement = "SELECT emp_id FROM employee "&

+"WHERE emp_state = ?"
PREPARE SQLSA FROM :sqlstatement ;
OPEN DYNAMIC my_cursor using :Emp_state_var ;
FETCH my_cursor INTO :Emp_id_var ;
CLOSE my_cursor ;

186
 Chapter 8 SQL Statements

Example 3 These statements perform the same processing as the preceding

example but use a database stored procedure called Emp_select:
// The syntax of emp_select is:
// "SELECT emp_id
// FROM employee WHERE emp_state=@stateparm".
DECLARE my_proc DYNAMIC PROCEDURE FOR SQLSA ;
integer Emp_id_var
string Emp_state_var

PREPARE SQLSA FROM "emp_select @stateparm=?" ;

Emp_state_var = "MA"
EXECUTE DYNAMIC my_proc USING :Emp_state_var ;
FETCH my_proc INTO :Emp_id_var ;
CLOSE my_proc ;

187
Dynamic SQL Format 4

Dynamic SQL Format 4

Description Use this format to execute a SQL statement that produces a result set in which
the number of input parameters, or the number of result-set columns, or both
are unknown at compile time.
Syntax DECLARE Cursor | Procedure
DYNAMIC CURSOR | PROCEDURE
FOR DynamicStagingArea ;
PREPARE DynamicStagingArea FROM SQLStatement
{USING TransactionObject} ;
DESCRIBE DynamicStagingArea
INTO DynamicDescriptionArea ;
OPEN DYNAMIC Cursor | Procedure
USING DESCRIPTOR DynamicDescriptionArea ;
EXECUTE DYNAMIC Cursor | Procedure
USING DESCRIPTOR DynamicDescriptionArea ;
FETCH Cursor | Procedure
USING DESCRIPTOR DynamicDescriptionArea ;
CLOSE Cursor | Procedure ;
Parameter Description
Cursor or Procedure The name of the cursor or procedure you want to
use
DynamicStagingArea The name of the DynamicStagingArea (usually
SQLSA)
If you need a DynamicStagingArea variable other
than SQLSA, you must declare it and instantiate it
with the CREATE statement before using it
SQLStatement A string containing a valid SQL SELECT
statement. The string can be a string constant or a
PowerBuilder variable preceded by a colon (such as
:mysql). The string must be contained on one line
and cannot contain expressions
Enter a question mark (?) for each parameter in the
statement. Value substitution is positional; reserved
word substitution is not allowed
TransactionObject The name of the transaction object that identifies
(optional) the database

188
 Chapter 8 SQL Statements

Parameter Description
DynamicDescriptionArea The name of the DynamicDescriptionArea (usually
SQLDA)
If you need a DynamicDescriptionArea variable
other than SQLDA, you must declare it and
instantiate it with the CREATE statement before
using it

Usage The DECLARE statement is not executable and can be defined globally.
If your DBMS supports formats of FETCH other than the customary (and
default) FETCH NEXT, you can specify FETCH FIRST, FETCH PRIOR, or
FETCH LAST.
To declare a local cursor or procedure, open the script in the Script view and
select Paste SQL from the PainterBar or the Edit>Paste Special menu. To
declare a global, instance, or shared cursor or procedure, select Declare from
the first dropdown listbox in the Script view and Global Variables, Instance
Variables, or Shared Variables from the second dropdown listbox, then select
Paste SQL.
For information about global, instance, shared, and local scope, see "Where to
declare variables" on page 36.
Accessing attribute information When a statement is described into a
DynamicDescriptionArea, this information is available to you in the attributes
of that DynamicDescriptionArea variable:
Information Attribute
Number of input parameters NumInputs
Array of input parameter types InParmType
Number of output parameters NumOutputs
Array of output parameter types OutParmType

Setting and accessing parameter values The array of input parameter

values and the array of output parameter values are also available. You can use
the SetDynamicParm function to set the values of an input parameter and the
following functions to obtain the value of an output parameter:
GetDynamicDate
GetDynamicDateTime
GetDynamicNumber
GetDynamicString
GetDynamicTime

189
Dynamic SQL Format 4

For information about these functions, see GetDynamicDate on page 576,

GetDynamicDateTime on page 578, GetDynamicNumber on page 580,
GetDynamicString on page 581, and GetDynamicTime on page 582.
Parameter values The following enumerated data types are the valid values
for the input and output parameter types:
TypeBoolean!
TypeDate!
TypeDateTime!
TypeDecimal!
TypeDouble!
TypeInteger!
TypeLong!
TypeReal!
TypeString!
TypeTime!
TypeUInt!
TypeULong!
TypeUnknown!
Input parameters You can set the type and value of each input parameter
found in the PREPARE statement. PowerBuilder populates the SQLDA
attribute NumInputs when the DESCRIBE is executed. You can use this value
with the SetDynamicParm function to set the type and value of a specific input
parameter. The input parameters are optional; but if you use them, you should
fill in all the values before executing the OPEN or EXECUTE statement.
Output parameters You can access the type and value of each output
parameter found in the PREPARE statement. If the database supports output
parameter description, PowerBuilder populates the SQLDA attribute
NumOutputs when the DESCRIBE is executed. If the database does not
support output parameter description, PowerBuilder populates the SQLDA
attribute NumOutputs when the FETCH statement is executed.
You can use the number of output parameters in the NumOutputs attribute in
functions to obtain the type of a specific parameter from the output parameter
type array in the OutParmType attribute. When you have the type, you can call
the appropriate function after the FETCH statement to retrieve the output
value.

190
 Chapter 8 SQL Statements

Examples Example 1 These statements assume you know that there will be only one
output descriptor and that it will be an integer. You can expand this example to
support any number of output descriptors and any data type by wrapping the
CHOOSE CASE statement in a loop and expanding the CASE statements:
string Stringvar, Sqlstatement
integer Intvar
Sqlstatement = "SELECT emp_id FROM employee"
PREPARE SQLSA FROM :Sqlstatement ;
DESCRIBE SQLSA INTO SQLDA ;
DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA ;
OPEN DYNAMIC my_cursor USING DESCRIPTOR SQLDA ;
FETCH my_cursor USING DESCRIPTOR SQLDA ;
// If the FETCH is successful, the output
// descriptor array will contain returned
// values from the first row of the result set.
// SQLDA.NumOutputs contains the number of
// output descriptors.
// The SQLDA.OutParmType array will contain
// NumOutput entries and each entry will contain
// an value of the enumerated data type ParmType
// (such as TypeInteger!, or TypeString!).
CHOOSE CASE SQLDA.OutParmType[1]
CASE TypeString!
Stringvar = GetDynamicString(SQLDA, 1)
CASE TypeInteger!
Intvar = GetDynamicNumber(SQLDA, 1)
END CHOOSE
CLOSE my_cursor ;
Example 2 These statements assume you know there is one string input
descriptor and sets the parameter to MA:
string Sqlstatement
Sqlstatement = "SELECT emp_id FROM employee "&
+"WHERE emp_state = ?"
PREPARE SQLSA FROM :Sqlstatement ;

DESCRIBE SQLSA INTO SQLDA ;

// If the DESCRIBE is successful, the input

// descriptor array will contain one input
// descriptor that you must fill prior to the OPEN

DECLARE my_cursor DYNAMIC CURSOR FOR SQLSA ;

SetDynamicParm(SQLDA, 1, "MA")

191
Dynamic SQL Format 4

OPEN DYNAMIC my_cursor USING DESCRIPTOR SQLDA ;

FETCH my_cursor USING DESCRIPTOR SQLDA ;

// If the FETCH is successful, the output

// descriptor array will contain returned
// values from the first row of the result set
// as in the first example.

CLOSE my_cursor ;

192
CH A PTE R 9 PowerScript Events

About this chapter This chapter discusses events in general and then documents the
arguments, event IDs, and return codes for the events defined for all
PowerBuilder controls and objects except the DataWindow and
DataStore. Usage notes and examples provide information about what is
typically done in an event’s script.
For information about DataWindow and DataStore events, see the
DataWindow Reference.
Contents The events are listed in alphabetical order.

193
About events

About events
In PowerBuilder, there are several types of events:
Type Occurs in response to
System events with an ID User actions or other system messages or a call in
your scripts
System events without an ID PowerBuilder messages or a call in your scripts
User-defined events with an ID User actions or other system messages or a call in
your scripts
User-defined events without an A call in your scripts
ID

The following information about event IDs, arguments, and return values
applies to all types of events.
Event IDs An event ID connects an event to a system message. Events that can be
triggered by user actions or other system activity have event IDs. In
PowerBuilder’s objects, PowerBuilder defines events for commonly used
event IDs. These events are documented in this chapter. You can define your
own events for other system messages using the event IDs listed in the Event
Declaration dialog box.
Events without IDs Some system events, such as the application object’s
Open event, do not have an event ID. They are associated with PowerBuilder
activity, not system activity. PowerBuilder triggers them itself when
appropriate.
Arguments System-triggered events Each system event has its own list of zero or more
arguments. When PowerBuilder triggers the event in response to a system
message, it supplies values for the arguments, which become available in the
event script.
Events you trigger If you trigger a system event in another event script, you
specify the expected arguments. For example, in the Clicked event for a
window, you could trigger the DoubleClicked event with this statement,
passing its flags, xpos, and ypos arguments on to the DoubleClicked event.
w_main.EVENT DoubleClicked(flags, xpos, ypos)
Because DoubleClicked is a system event, the argument list is fixed—you can’t
supply additional arguments of your own.

194
 Chapter 9 PowerScript Events

Calling events without specifying their arguments

If you use the CALL statement, you can trigger a system event without
specifying its arguments. However, CALL is obsolete and you should not use
it in new applications.

Return values Where does the return value go? Most events have a return value. When
the event is triggered by the system, the return value is returned to the system.
When your script triggers a user-defined or system event, you can capture the
return value in an assignment statement:
li_rtn = w_main.EVENT process_info(mydata)
When you post an event, the return value is lost because the calling script is no
longer running when the posted script is actually run. The compiler does not
allow a posted event in an assignment statement.
Return codes System events with return values have a default return code of
0, which means take no special action and continue processing. Some events
have additional codes that you can return to change the processing that happens
after the event. For example, a return code might allow you to suppress an error
message or prevent a change from taking place.
A RETURN statement is not required in an event script, but for most events it
is good practice to include one. For events with return values, if you don’t have
a RETURN statement, the event returns 0.
Some system events have no return value. For these events, the compiler does
not allow a RETURN statement.
Ancestor event script Sometimes you want to perform some processing in an event in a descendent
return values object, but that processing depends on the return value of the ancestor event
script. You can use a local variable called AncestorReturnValue that is
automatically declared and assigned the value of the ancestor event.
For more information about AncestorReturnValue, see "Calling functions and
events in an object’s ancestor" on page 117.
User-defined events With an ID When you declare a user-defined event that will be triggered by a
system message, you select an event ID from the list of IDs. The pbm codes
listed in the Event dialog box map to system messages.
The return value and arguments associated with the event ID become part of
your event declaration. You cannot modify them.
When the corresponding system message occurs, PowerBuilder triggers the
event and passes values for the arguments to the event script.

195
About events

Without an ID When you declare a user event that will not be associated with
a system message, you do not select an event ID for the event.
You can specify your own arguments and return data type in the Event
Declaration dialog box.
The event will never be triggered by user actions or system activity. You will
trigger the event yourself in your application’s scripts.
For more information If you want to trigger events, including system events, see "Syntax for calling
PowerBuilder functions and events" on page 113 for information on the calling
syntax.
To learn more about user-defined events, see the PowerBuilder User’s Guide.

196
 Chapter 9 PowerScript Events

Activate
Description Occurs just before the window becomes active.
Event ID
Event ID Objects
pbm_activate Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When an Activate event occurs, the first object in the tab order for the window
gets focus. If there are no visible objects in the window, the window gets focus.
An Activate event occurs for a newly opened window because it is made active
after it is opened.
The Activate event is frequently used to enable and disable menu items.
Examples Example 1 In the window’s Activate event, this code disables the Sheet
menu item for menu m_frame on the File menu:
m_frame.m_file.m_sheet.Enabled = FALSE
Example 2 This code opens the sheet w_sheet in a layered style when the
window activates:
w_sheet.ArrangeSheets(Layer!)
See also Close
Open
Show

197
BeginDrag

BeginDrag
The BeginDrag event has different arguments for different objects:
Object See
ListView control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView controls

Description Occurs when the user presses the left mouse button in the ListView control and
begins dragging.
Event ID
Event ID Objects
pbm_lvnbegindrag ListView

Arguments
Argument Description
index Integer by value (the index of the ListView item being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage BeginDrag and BeginRightDrag events occur when the user presses the mouse
button and drags, whether or not dragging is enabled. To enable dragging, you
can:
• Set the DragAuto property to TRUE. If the ListView’s DragAuto property
is TRUE, a drag operation begins automatically when the user clicks
• Call the Drag function. If DragAuto is FALSE, then in the BeginDrag
event script, the programmer can call the Drag function to begin the drag
operation
Dragging a ListView item onto another control causes its standard drag events
(DragDrop, DragEnter, DragLeave, and DragWithin) to occur. The standard
drag events occur for ListView when another control is dragged within the
borders of the ListView.

198
 Chapter 9 PowerScript Events

Examples This example moves a ListView item from one ListView to another.
Ilvi_dragged_object is a window instance variable whose type is
ListViewItem. To copy the item, omit the code that deletes it from the source
ListView.
This code is in the BeginDrag event script of the source ListView.
// If the TreeView’s DragAuto property is FALSE
This.Drag(Begin!)

This.GetItem(This.SelectedIndex(), &
ilvi_dragged_object)

// To copy, rather than move, omit these two lines

This.DeleteItem(This.SelectedIndex())
This.Arrange()
This code is in the DragDrop event of the target ListView.
This.AddItem(ilvi_dragged_object)
This.Arrange()
See also BeginRightDrag
DragDrop
DragEnter
DragLeave
DragWithin

Syntax 2 For TreeView controls

Description Occurs when the user presses the left mouse button on a label in the TreeView
control and begins dragging.
Event ID
Event ID Objects
pbm_tvnbegindrag TreeView

Arguments
Argument Description
handle Long by value (handle of the TreeView item being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing

199
BeginDrag

Usage BeginDrag and BeginRightDrag events occur when the user presses the mouse
button and drags, whether or not dragging is enabled. To enable dragging, you
can:
• Set the DragAuto property to TRUE. If the TreeView’s DragAuto property
is TRUE, a drag operation begins automatically when the user clicks.
• Call the Drag function. If DragAuto is FALSE, then in the BeginDrag
event script, the programmer can call the Drag function to begin the drag
operation.
The user cannot drag a highlighted item.
Dragging a TreeView item onto another control causes the control’s standard
drag events (DragDrop, DragEnter, DragLeave, and DragWithin) to occur. The
standard drag events occur for TreeView when another control is dragged
within the borders of the TreeView.
Examples This example moves the first TreeView item in the source TreeView to another
TreeView when the user drags there. Itvi_dragged_object is a window instance
variable whose type is TreeViewItem. To copy the item, omit the code that
deletes it from the source TreeView.
This code is in the BeginDrag event script of the source TreeView:
long itemnum

// If the TreeView’s DragAuto property is FALSE

This.Drag(Begin!)
itemnum = 1
This.GetItem(itemnum, itvi_dragged_object)

// To copy, rather than move, omit these two lines

This.DeleteItem(itemnum)
This.SetRedraw(TRUE)
This code is in the DragDrop event of the target TreeView:
This.InsertItemLast(0, ilvi_dragged_object)
This.SetRedraw(TRUE)
Instead of deleting the item from the source TreeView immediately, consider
deleting it after the insertion in the DragDrop event succeeds.
See also BeginRightDrag
DragDrop
DragEnter
DragLeave
DragWithin

200
 Chapter 9 PowerScript Events

BeginLabelEdit
The BeginLabelEdit event has different arguments for different objects:
Object See
ListView control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView controls

Description Occurs when the user clicks on the label of an item after selecting the item.
Event ID
Event ID Objects
pbm_lvnbeginlabeledit ListView

Arguments
Argument Description
index Integer by value (the index of the selected ListView item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Allow editing of the label
1 Prevent editing of the label
Usage When editing is allowed, a box appears around the label with the text
highlighted. The user can replace or change the existing text.
Examples This example uses the BeginLabelEdit to display the name of the ListView
item being edited:
ListViewItem lvi
This.GetItem(index lvi)
sle_info.text = "Editing " + string(lvi.label)
See also EndLabelEdit

Syntax 2 For TreeView controls

Description Occurs when the user clicks on the label of an item after selecting the item.

201
BeginLabelEdit

Event ID
Event ID Objects
pbm_tvnbeginlabeledit TreeView

Arguments
Argument Description
handle Long by value (the handle of the selected TreeView item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Allow editing of the label
1 Prevent editing of the label
Usage When editing is allowed, a box appears around the label with the text
highlighted. The user can replace or change the existing text.
Examples This example uses the BeginLabelEdit to display the name of the TreeView
item being edited in a SingleLineEdit:
TreeViewItem tvi
This.GetItem(index, tvi)
sle_info.text = "Editing " + string(tvi.label)
See also EndLabelEdit

202
 Chapter 9 PowerScript Events

BeginRightDrag
The BeginRightDrag event has different arguments for different objects:
Object See
ListView control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView controls

Description Occurs when the user presses the right mouse button in the ListView control
and begins dragging.
Event ID
Event ID Objects
pbm_lvnbeginrightdrag ListView

Arguments
Argument Description
index Integer by value (the index of the ListView item being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage BeginDrag and BeginRightDrag events occur when the user presses the mouse
button and drags, whether or not dragging is enabled. To enable dragging, you
can:
• Set the DragAuto property to TRUE. If the ListView’s DragAuto property
is TRUE, a drag operation begins automatically when the user clicks
• Call the Drag function. If DragAuto is FALSE, then in the BeginDrag
event script, the programmer can call the Drag function to begin the drag
operation
Dragging a ListView item onto another control causes its standard drag events
(DragDrop, DragEnter, DragLeave, and DragWithin) to occur. The standard
drag events occur for ListView when another control is dragged within the
borders of the ListView.
Examples See the example for the BeginDrag event. It is effective for the
BeginRightDrag event too.
See also BeginDrag

203
BeginRightDrag

DragDrop
DragEnter
DragLeave
DragWithin

Syntax 2 For TreeView controls

Description Occurs when the user presses the right mouse button in the TreeView control
and begins dragging.
Event ID
Event ID Objects
pbm_tvnbeginrightdrag TreeView

Arguments
Argument Description
handle Long by value (the handle of the TreeView item being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage BeginDrag and BeginRightDrag events occur when the user presses the mouse
button and drags, whether or not dragging is enabled. To enable dragging, you
can:
• Set the DragAuto property to TRUE. If the TreeView’s DragAuto property
is TRUE, a drag operation begins automatically when the user clicks
• Call the Drag function. If DragAuto is FALSE, then in the BeginDrag
event script, the programmer can call the Drag function to begin the drag
operation
The user cannot drag a highlighted item.
Dragging a TreeView item onto another control causes its standard drag events
(DragDrop, DragEnter, DragLeave, and DragWithin) to occur. The standard
drag events occur for TreeView when another control is dragged within the
borders of the TreeView.
Examples See the example for the BeginDrag event. It is effective for the
BeginRightDrag event too.
See also BeginDrag
DragDrop

204
 Chapter 9 PowerScript Events

DragEnter
DragLeave
DragWithin

205
Clicked

Clicked
The Clicked event has different arguments for different objects:
Object See
Menus Syntax 1
ListView control Syntax 2
Tab control Syntax 3
TreeView control Syntax 4
Window Syntax 5
Other controls Syntax 6

For information about the DataWindow control’s Clicked event, see the
DataWindow Reference.

Syntax 1 For menus

Description Occurs when the user chooses an item on a menu.
Event ID
Event ID Objects
None Menu

Arguments None
Return codes None (do not use a RETURN statement)
Usage If the user highlights the menu item without choosing it, its Selected event
occurs.
If the user chooses a menu item that has a cascaded menu associated with it,
the Clicked event occurs and the cascaded menu is displayed.
Examples This script is for the Clicked event of the New menu item for the frame
window. The wf_newsheet function is a window function. The window
w_genapp_frame is part of the application template you can generate when you
create a new application:
/* Create a new sheet */
w_genapp_frame.wf_newsheet( )
See also Selected

206
 Chapter 9 PowerScript Events

Syntax 2 For ListView controls

Description Occurs when the user clicks within the ListView control, either on an item or
in the blank space around items.
Event ID
Event ID Objects
pbm_lvnclicked ListView

Arguments
Argument Description
index Integer by value (the index of the ListView item the user
clicked)
The value of index is -1 if the user clicks within the control
but not on a specific item

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Clicked event occurs when the user presses the mouse button. The Clicked
event can occur during a double-click, in addition to the DoubleClicked event.
In addition to the Clicked event, ItemChanging and ItemChanged events can
occur when the user clicks on an item that does not already have focus.
BeginLabelEdit can occur when the user clicks on a label of an item that has
focus.

Using the ItemActivate event for ListView controls

You can use the ItemActivate event (with the OneClickActivate property set to
TRUE) instead of the Clicked event for ListView controls.

Examples This code changes the label of the item the user clicks to uppercase:
IF index = -1 THEN RETURN 0

This.GetItem(index, llvi_current)
llvi_current.Label = Upper(llvi_current.Label)
This.SetItem(index, llvi_current)
RETURN 0
See also ColumnClick
DoubleClicked
ItemActivate
ItemChanged
ItemChanging

207
Clicked

RightClicked
RightDoubleClicked

Syntax 3 For Tab controls

Description Occurs when the user clicks on the tab portion of a Tab control.
Event ID
Event ID Objects
pbm_tcnclicked Tab

Arguments
Argument Description
index Integer by value (the index of the tab page the user clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Clicked event occurs when the mouse button is released.
When the user clicks in the display area of the Tab control, the tab page user
object (not the Tab control) gets a Clicked event.
The Clicked event can occur during a double-click, in addition to the
DoubleClicked event.
In addition to the Clicked event, the SelectionChanging and SelectionChanged
events can occur when the user clicks on a tab page label. If the user presses an
arrow key to change tab pages, the Key event occurs instead of Clicked before
SelectionChanging and SelectionChanged.
Examples This code makes the tab label bold for the fourth tab page only:
IF index = 4 THEN
This.BoldSelectedText = TRUE
ELSE
This.BoldSelectedText = FALSE
END IF
See also DoubleClicked
RightClicked
RightDoubleClicked
SelectionChanged
SelectionChanging

208
 Chapter 9 PowerScript Events

Syntax 4 For TreeView controls

Description Occurs when the user clicks an item in a TreeView control.
Event ID
Event ID Objects
pbm_tvnclicked TreeView

Arguments
Argument Description
handle Long by value (the handle of the TreeView item the user
clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Clicked event occurs when the user presses the mouse button.
The Clicked event can occur during a double-click, in addition to the
DoubleClicked event.
In addition to the Clicked event, GetFocus occurs if the control does not
already have focus.
Examples This code in the Clicked event changes the label of the item the user clicked to
uppercase:
TreeViewItem ltvi_current

This.GetItem(handle, ltvi_current)
ltvi_current.Label = Upper(ltvi_current.Label)
This.SetItem(handle, ltvi_current)
See also DoubleClicked
RightClicked
RightDoubleClicked
SelectionChanged
SelectionChanging

Syntax 5 For windows

Description Occurs when the user clicks in an unoccupied area of the window (any area
with no visible, enabled object).

209
Clicked

Event ID
Event ID Objects
pbm_lbuttonclk Window

Arguments
Argument Description
flags UnsignedLong by value (the modifier keys and mouse
buttons that are pressed)
Values are:
• 1 — Left mouse button
• 2 — Right mouse button
• 4 — SHIFT key
• 8 — CTRL key
• 16 — Middle mouse button
In the Clicked event, the left mouse button is being
released, so 1 is not summed in the value of flags
For an explanation of flags, see Syntax 2 of MouseMove
on page 279
xpos Integer by value (the distance of the pointer from the left
edge of the window’s workspace in pixels)
ypos Integer by value (the distance of the pointer from the top of
the window’s workspace in pixels)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Clicked event occurs when the user releases the mouse button.
If the user clicks on a control or menu, that object (rather than the window) gets
a Clicked event. No Clicked event occurs when the user clicks the window’s
title bar.
When the user clicks on the window, the window’s MouseDown and MouseUp
events also occur.
When the user clicks on a visible disabled control or an invisible enabled
control, the window gets a Clicked event.
Examples If the user clicks in the upper-left corner of the window, this code sets focus to
the button cb_clear:
IF (xpos <= 600 AND ypos <= 600) THEN
cb_clear.SetFocus( )
END IF

210
 Chapter 9 PowerScript Events

See also DoubleClicked

MouseDown
MouseMove
MouseUp
RButtonDown

Syntax 6 For other controls

Description Occurs when the user clicks on the control.
Event ID
Event ID Objects
pbm_bnclicked CheckBox, CommandButton, Graph, OLE, Picture,
PictureHyperLink, PictureButton, RadioButton,
StaticText, StaticHyperLink
pbm_prnclicked HProgressBar, VProgressBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage The Clicked event occurs when the user releases the mouse button.
If another control had focus, then a GetFocus and a Clicked event occur for the
control the user clicks.
Examples This code in an OLE control’s Clicked event activates the object in the control:
integer li_success
li_success = This.Activate(InPlace!)
See also GetFocus
RButtonDown

211
Close

Close
The Close event has different arguments for different objects:
Object See
Application Syntax 1
OLE control Syntax 2
Window Syntax 3

Syntax 1 For the application object

Description Occurs when the user closes the application.
Event ID
Event ID Objects
None Application

Arguments None
Return codes None (do not use a RETURN statement)
Usage The Close event occurs when the last window (for MDI applications the MDI
frame) is closed.
See also Open
SystemError

Syntax 2 For OLE controls

Description Occurs when the object in an OLE control has been activated offsite (the OLE
server displays the object in the server’s window) and that server is closed.
Event ID
Event ID Objects
pbm_omnclose OLE

Arguments None
Return codes Long. Return code: Ignored
Usage If the user closed the OLE server, the user’s choices may cause the OLE object
in the control to be updated, triggering the Save or DataChange events.

212
 Chapter 9 PowerScript Events

If you want to retrieve the ObjectData blob value of an OLE control during the
processing of this event, you must post a user event back to the control or you
will generate a runtime error.
See also DataChange
Save

Syntax 3 For windows

Description Occurs just before a window is removed from display.
Event ID
Event ID Objects
pbm_close Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When you call the Close function for the window, a CloseQuery event occurs
before the Close event. In the CloseQuery event, you can specify a return code
to prevent the Close event from occurring and the window from closing.
Do not trigger the Close event to close a window; call the Close function
instead. (Triggering the event simply runs the script and does not close the
window.)
See also CloseQuery
Open

213
CloseQuery

CloseQuery
Description Occurs when a window is closed, before the Close event.
Event ID
Event ID Objects
pbm_closequery Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Allow the window to be closed
1 Prevent the window from closing
Usage If the CloseQuery event returns a value of 1, the closing of the window is
aborted and the Close event that usually follows CloseQuery does not occur.
If the user closes the window with the Close box (instead of using buttons
whose scripts can evaluate the state of the data in the window), the CloseQuery
event still occurs, allowing you to prompt the user about saving changes or to
check whether data the user entered is valid.

Obsolete techniques
You no longer need to set the ReturnValue property of the Message object. Use
a RETURN statement instead.

Examples This statement in the CloseQuery event for a window asks if the user really
wants to close the window and if the user answers no, prevents it from closing:
IF MessageBox("Closing window", "Are you sure?", &
Question!, YesNo!) = 2 THEN
RETURN 1
ELSE
RETURN 0
END IF
This script for the CloseQuery event tests to see if the DataWindow dw_1 has
any pending changes. If it has, it asks the user whether to update the data and
close the window, close the window without updating, or leave the window
open without updating:
integer li_rc

// Accept the last data entered into the datawindow

dw_1.AcceptText()

214
 Chapter 9 PowerScript Events

//Check to see if any data has changed

IF dw_1.DeletedCount()+dw_1.ModifiedCount() > 0 THEN
li_rc = MessageBox("Closing", &
"Update your changes?", Question!, &
YesNoCancel!, 3)

//User chose to up data and close window

IF li_rc = 1 THEN
Window lw_window
lw_window = w_genapp_frame.GetActiveSheet()
lw_window.TriggerEvent("ue_update")
RETURN 0

//User chose to close window without updating

ELSEIF li_rc = 2 THEN
RETURN 0

//User canceled
ELSE
RETURN 1
END IF

ELSE
// No changes to the data, window will just close
RETURN 0
END IF

See also Close

215
ColumnClick

ColumnClick
Description Occurs when the user clicks a column header.
Event ID
Event ID Objects
pbm_lvncolumnclick ListView

Arguments
Argument Description
column The index of the clicked column

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The ColumnClicked event is only available when the ListView displays in
report view and the ButtonHeader property is set to TRUE.
Examples This example uses the ColumnClicked event to set up a instance variable for
the column argument, retrieve column alignment information, and display it to
the user:
string ls_label, ls_align
integer li_width
alignment la_align

ii_col = column
This.GetColumn(column, ls_label, la_align, &
li_width)

CHOOSE CASE la_align

CASE Right!
rb_right.Checked = TRUE
ls_align = "Right!"

CASE Left!
rb_left.Checked = TRUE
ls_align = "Left!"

CASE Center!
rb_center.Checked = TRUE
ls_align = "Center!"

CASE Justify!
rb_just.Checked = TRUE
ls_align = "Justify!"
END CHOOSE

216
 Chapter 9 PowerScript Events

sle_info.Text = String(column) &

+ " " + ls_label &
+ " " + ls_align &
+ " " + String(li_width)
See also Clicked

217
ConnectionBegin

ConnectionBegin
Description Obsolete event. Used for distributed PowerBuilder connections.

218
 Chapter 9 PowerScript Events

ConnectionEnd
Description Obsolete event. Used for distributed PowerBuilder connections.

219
Constructor

Constructor
Description Occurs when the control or object is created, just before the Open event for the
window that contains the control.
Event ID
Event ID Objects
pbm_constructor All objects

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage You can write a script for a control’s Constructor event to affect the control’s
properties before the window is displayed.
When a window or user object opens, a Constructor event for each control in
the window or user object occurs. The order of controls in a window’s Control
property (which is an array) determines the order in which Constructor events
are triggered. If one of the controls in the window is a user object, the
Constructor events of all the controls in the user object occur before the
Constructor event for the next control in the window.
When you call OpenUserObject to add a user object to a window dynamically,
its Constructor event and the Constructor events for all of its controls occur.
When you use the CREATE statement to instantiate a class (nonvisual) user
object, its Constructor event occurs.
When a class user object variable has an Autoinstantiate setting of TRUE, its
Constructor event occurs when the variable comes into scope. Therefore, the
Constructor event occurs for:
• Global variables when the system starts up
• Shared variables when the object with the shared variables is loaded
• Instance variables when the object with the instance variables is created
• Local variables when the function that declares them begins executing
Examples This example retrieves data for the DataWindow dw_1 before its window is
displayed:
dw_1.SetTransObject(SQLCA)
dw_1.Retrieve( )
See also Destructor
Open

220
 Chapter 9 PowerScript Events

DataChange
Description Occurs when the server application notifies the control that data has changed.
Event ID
Event ID Objects
pbm_omndatachange OLE

Arguments None
Return codes Long. Return code: Ignored
See also PropertyRequestEdit
PropertyChanged
Rename
ViewChange

221
Deactivate

Deactivate
Description Occurs when the window becomes inactive.
Event ID
Event ID Objects
pbm_deactivate Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When a window is closed, a Deactivate event occurs.
See also Activate
Show

222
 Chapter 9 PowerScript Events

DeleteAllItems
Description Occurs when all the items in the ListView are deleted.
Event ID
Event ID Objects
pbm_lvndeleteallitems ListView

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples This example uses the DeleteAllItems event to ensure that there’s a default
item in the ListView control:
This.AddItem("Default item", 1)
See also DeleteItem
InsertItem

223
DeleteItem

DeleteItem
The DeleteItem event has different arguments for different objects:
Object See
ListView control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView controls

Description Occurs when an item is deleted.
Event ID
Event ID Objects
pbm_lvndeleteitem ListView

Arguments
Argument Description
index Integer by value (the index of the deleted item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example for the DeleteItem event displays a message with the number of
the deleted item:
MessageBox("Message", "Item " + String(index) &
+ " deleted.")
See also DeleteAllItems
InsertItem

Syntax 2 For TreeView controls

Description Occurs when an item is deleted.
Event ID
Event ID Objects
pbm_tvndeleteitem TreeView

224
 Chapter 9 PowerScript Events

Arguments
Argument Description
handle Long by value (the handle of the deleted item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example displays the name of the deleted item in a message:
TreeViewItem ll_tvi

This.GetItem(handle, ll_tvi)
MessageBox("Message", String(ll_tvi.Label) &
+ " has been deleted.")

225
Destructor

Destructor
Description Occurs when the user object or control is destroyed, immediately after the
Close event of a window.
Event ID
Event ID Objects
pbm_destructor All objects

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When a window is closed, each control’s Destructor event destroys the control
and removes it from memory. After they’ve been destroyed, you can no longer
refer to those controls in other scripts (if you do, a runtime error occurs).
See also Constructor
Close

226
 Chapter 9 PowerScript Events

DoubleClicked
The DoubleClicked event has different arguments for different objects:
Object See
ListBox, PictureListBox, ListView, and Tab controls Syntax 1
TreeView control Syntax 2
Window Syntax 3
Other controls Syntax 4

For information about the DataWindow control’s DoubleClicked event, see the
DataWindow Reference.

Syntax 1 For ListBox, PictureListBox, ListView, and Tab controls

Description Occurs when the user double-clicks on the control.
Event ID
Event ID Objects
pbm_lbndblclk ListBox, PictureListBox
pbm_lvndoubleclicked ListView
pbm_tcndoubleclicked Tab

Arguments
Argument Description
index Integer by value
The index of the item the user double-clicked (for tabs, the
index of the tab page)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage In a ListView control, the Clicked event occurs twice during a double-click
action, before and after the DoubleClicked event. (The Clicked event occurs
the first time the button is first released; the DoubleClicked event occurs on the
second click when the button is pressed; and the Clicked event occurs again
when the second button press is released.)

227
DoubleClicked

Using the ItemActivate event for ListView controls

You can use the ItemActivate event (with the OneClickActivate property set to
FALSE) instead of the DoubleClicked event for ListView controls.

In a ListBox or PictureListBox, double-clicking on an item also triggers a

SelectionChanged event.
Examples This example uses the DoubleClicked event to begin editing the double-clicked
ListView item:
This.EditLabels = TRUE
See also Clicked
ColumnClick
ItemActivate
ItemChanged
ItemChanging
RightClicked
RightDoubleClicked
SelectionChanged
SelectionChanging

Syntax 2 For TreeView controls

Description Occurs when the user double-clicks on the control.
Event ID
Event ID Objects
pbm_tvndoubleclicked TreeView

Arguments
Argument Description
handle Long by value (the handle of the item the user double-
clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example turns on editing for the double-clicked TreeView item:
TreeViewItem ltvi_current
ltvi_current = tv_1.FindItem(CurrentTreeItem!, 0)
This.EditLabel(ltvi_current)

228
 Chapter 9 PowerScript Events

See also Clicked

RightClicked
RightDoubleClicked
SelectionChanged
SelectionChanging

Syntax 3 For windows

Description Occurs when the user double-clicks in an unoccupied area of the window (any
area with no visible, enabled object).
Event ID
Event ID Objects
pbm_lbuttondblclk Window

Arguments
Argument Description
flags UnsignedLong by value (the modifier keys and mouse
buttons that are pressed)
Values are:
• 1 — Left mouse button
• 2 — Right mouse button
• 4 — SHIFT key
• 8 — CTRL key
• 16 — Middle mouse button
In the Clicked event, the left mouse button is being
released, so 1 is not summed in the value of flags
For an explanation of flags, see Syntax 2 of MouseMove
on page 279
xpos Integer by value (the distance of the pointer from the left
edge of the window’s workspace in pixels)
ypos Integer by value (the distance of the pointer from the top
of the window’s workspace in pixels)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The xpos and ypos arguments provide the same values the functions PointerX
and PointerY return when you call them for the window.

229
DoubleClicked

See also Clicked

MouseDown
MouseMove
MouseUp
RButtonDown

230
 Chapter 9 PowerScript Events

Syntax 4 For other controls

Description Occurs when the user double-clicks on the control.
Event ID
Event ID Objects
pbm_bndoubleclicked Graph, OLE, Picture, PictureHyperLink, StaticText,
StaticHyperLink
pbm_cbndblclk DropDownListBox, DropDownPictureListBox
pbm_prndoubleclicked HProgressBar, VProgressBar
pbm_rendoubleclicked RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage The DoubleClicked event for DropDownListBoxes is only active when the
Always Show List property is on.
See also Clicked
RButtonDown

231
DragDrop

DragDrop
The DragDrop event has different arguments for different objects:
Object See
ListBox, PictureListBox, ListView, and Syntax 1
Tab controls
TreeView control Syntax 2
Windows and other controls Syntax 3

For information about the DataWindow control’s DragDrop event, see the
DataWindow Reference.

Syntax 1 For ListBox, PictureListBox, ListView, and Tab controls

Description Occurs when the user drags an object onto the control and releases the mouse
button to drop the object.
Event ID
Event ID Objects
pbm_lbndragdrop ListBox, PictureListBox
pbm_lvndragdrop ListView
pbm_tcndragdrop Tab

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)
index Integer by value (the index of the target ListView item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples For ListView controls, see the example for BeginDrag.
This example inserts the dragged ListView item:
This.AddItem(ilvi_dragged_object)
This.Arrange( )

232
 Chapter 9 PowerScript Events

See also BeginDrag

BeginRightDrag
DragEnter
DragLeave
DragWithin

Syntax 2 For TreeView controls

Description Occurs when the user drags an object onto the control and releases the mouse
button to drop the object.
Event ID
Event ID Objects
pbm_tvndragdrop TreeView

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)
handle Long by value (the handle of the target TreeView item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples This example inserts the dragged object as a child of the TreeView item it is
dropped upon:
TreeViewItem ltv_1
This.GetItem(handle, ltv_1)
This.SetDropHighlight(handle)
This.InsertItemFirst(handle, itvi_drag_object)
This.ExpandItem(handle)
This.SetRedraw(TRUE)
See also DragEnter
DragLeave
DragWithin

233
DragDrop

Syntax 3 For windows and other controls

Description Occurs when the user drags an object onto the control and releases the mouse
button to drop the object.
Event ID
Event ID Objects
pbm_bndragdrop CheckBox, CommandButton, Graph, Picture,
PictureHyperLink, PictureButton, RadioButton
pbm_cbndragdrop DropDownListBox, DropDownPictureListBox
pbm_endragdrop SingleLineEdit, EditMask, MultiLineEdit, StaticText,
StaticHyperLink
pbm_omndragdrop OLE
pbm_prndragdrop HProgressBar, VProgressBar
pbm_rendragdrop RichTextEdit
pbm_sbndragdrop HScrollBar, HTrackBar, VScrollBar, VTrackBar
pbm_uondragdrop UserObject
pbm_dragdrop Window

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage When a control’s DragAuto property is TRUE, a drag operation begins when
the user presses a mouse button.
Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples Example 1 In this example from the w_orderentry window in the ABNC
sample application, this code in the DoubleClicked event for the DataWindow
dw_orddetail starts a drag operation:
IF dw_orddetail.GetRow() > 0 THEN
dw_orddetail.Drag(Begin!)
This.DragIcon = "dragitem.ico"
END IF
Then in the DragDrop event for a trashcan Picture control, this code deletes the
row the user clicked and dragged from the DataWindow control:

234
 Chapter 9 PowerScript Events

long ll_currow
dwitemstatus ldwis_delrow

ll_currow = dw_orddetail.GetRow( )

// Save the row’s status flag for later use

ldwis_delrow = dw_orddetail.GetItemStatus &
(ll_currow, 0, Primary!)

// Now, delete the current row from dw_orddetail

dw_orddetail.DeleteRow(0)
Example 2 This example for a trashcan Picture control’s DragDrop event
checks whether the source of the drag operation is a DataWindow. If so, it asks
the user whether to delete the current row in the source DataWindow:
DataWindow ldw_Source
Long ll_RowToDelete
Integer li_Choice

IF source.TypeOf() = DataWindow! THEN

ldw_Source = source
ll_RowToDelete = ldw_Source.GetRow()

IF ll_RowToDelete > 0 THEN

li_Choice = MessageBox("Delete", &
"Delete this row?", Question!, YesNo!, 2)
IF li_Choice = 1 THEN
ldw_Source.DeleteRow(ll_RowToDelete)
END IF
ELSE
Beep(1)
END IF

ELSE
Beep(1)
END IF
See also DragEnter
DragLeave
DragWithin

235
DragEnter

DragEnter
Description Occurs when the user is dragging an object and enters the control.
Event ID
Event ID Objects
pbm_bndragenter CheckBox, CommandButton, Graph, Picture,
PictureHyperlink, PictureButton, RadioButton
pbm_cbndragenter DropDownListBox, DropDownPictureListBox
pbm_dwndragenter DataWindow
pbm_endragenter SingleLineEdit, EditMask, MultiLineEdit, StaticText,
StaticHyperLink
pbm_lbndragenter ListBox, PictureListBox
pbm_lvndragenter ListView
pbm_omndragenter OLE
pbm_prndragenter HProgressBar, VProgressBar
pbm_rendragenter RichTextEdit
pbm_sbndragenter HScrollBar, HTrackBar, VScrollBar, VTrackBar
pbm_tcndragenter Tab
pbm_tvndragenter TreeView
pbm_uondragenter UserObject
pbm_dragenter Window

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples This example for a Picture control’s DragDrop event adds a border to itself
when another Picture control (the source) is dragged within its boundaries:
IF source.TypeOf() = Picture! THEN
This.Border = TRUE
END IF
See also DragDrop
DragLeave
DragWithin

236
 Chapter 9 PowerScript Events

DragLeave
Description Occurs when the user is dragging an object and leaves the control.
Event ID
Event ID Objects
pbm_bndragleave CheckBox, CommandButton, Graph, Picture,
PictureHyperLink, PictureButton, RadioButton
pbm_cbndragleave DropDownListBox, DropDownPictureListBox
pbm_dwndragleave DataWindow
pbm_endragleave SingleLineEdit, EditMask, MultiLineEdit, StaticText,
StaticHyperLink
pbm_lbndragleave ListBox, PictureListBox
pbm_lvndragleave ListView
pbm_omndragleave OLE
pbm_prndragleave HProgressBar, VProgressBar
pbm_rendragleave RichTextEdit
pbm_sbndragleave HScrollBar, HTrackBar, VScrollBar, VTrackBar
pbm_tcndragleave Tab
pbm_tvndragleave TreeView
pbm_uondragleave UserObject
pbm_dragleave Window

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples This example checks the name of the control being dragged and if it is cb_1 it
cancels the drag operation:
IF ClassName(source) = "cb_1" THEN
cb_1.Drag(Cancel!)
END If
This example for a Picture control’s DragDrop event removes its own border
when another Picture control (the source) is dragged beyond its boundaries:

237
DragLeave

IF source.TypeOf() = Picture! THEN

This.Border = TRUE
END IF
See also DragDrop
DragEnter
DragWithin

238
 Chapter 9 PowerScript Events

DragWithin
The DragWithin event has different arguments for different objects:
Object See
ListBox, PictureListBox, ListView, and Syntax 1
Tab controls
TreeView control Syntax 2
Windows and other controls Syntax 3

For information about the DataWindow control’s DragWithin event, see the
DataWindow Reference.

Syntax 1 For ListBox, PictureListBox, ListView, and Tab controls

Description Occurs when the user is dragging an object within the control.
Event ID
Event ID Objects
pbm_lbndragwithin ListBox, PictureListBox
pbm_lvndragwithin ListView
pbm_tcndragwithin Tab

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)
index Integer by value (a reference to the ListView item under
the pointer in the ListView control)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples This example changes the background color of the ListView when a
DragObject enters its border:
This.BackColor = RGB(128, 0, 128)
See also DragDrop
DragEnter
DragLeave

239
DragWithin

Syntax 2 For TreeView controls

Description Occurs when the user is dragging an object within the control.
Event ID
Event ID Objects
pbm_tvndragwithin TreeView

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)
handle Long (a reference to the ListView item under the pointer
in the TreeView control)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
Examples This example changes the background color of the TreeView when a
DragObject enters its border:
This.BackColor = RGB(128, 0, 128)
See also DragDrop
DragEnter
DragLeave

Syntax 3 For windows and other controls

Description Occurs when the user is dragging an object within the control.
Event ID
Event ID Objects
pbm_bndragwithin CheckBox, CommandButton, Graph, Picture,
PictureHyperLink, PictureButton, RadioButton
pbm_cbndragwithin DropDownListBox, DropDownPictureListBox
pbm_endragwithin SingleLineEdit, EditMask, MultiLineEdit, StaticText,
StaticHyperLink
pbm_omndragwithin OLE
pbm_prndragwithin HProgressBar, VProgressBar
pbm_rendragwithin RichTextEdit

240
 Chapter 9 PowerScript Events

Event ID Objects
pbm_sbndragwithin HScrollBar, HTrackBar, VScrollBar, VTrackBar
pbm_uondragwithin UserObject
pbm_dragwithin Window

Arguments
Argument Description
source DragObject by value (a reference to the control being
dragged)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Obsolete functions You no longer need to call the DraggedObject function
in a drag event. Use the source argument instead.
See also DragDrop
DragEnter
DragLeave

241
EndLabelEdit

EndLabelEdit
The EndLabelEdit event has different arguments for different objects:
Object See
ListView control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView controls

Description Occurs when the user finishes editing an item’s label.
Event ID
Event ID Objects
pbm_lvnendlabeledit ListView

Arguments
Argument Description
index Integer. The index of the ListView item for which you
have edited the label
newlabel The string that represents the new label for the ListView
item

Return codes Long. Return code choices (specify in a RETURN statement):

0 Allow the new text to become the item’s label
1 Prevent the new text from becoming the item’s label
Usage The user triggers this event by pressing ENTER or TAB after editing the text.
Examples This example displays the old label and the new label in a SingleLineEdit:
ListViewItem lvi
sle_info.text = "Finished editing " &
+ String(lvi.label) &
+". Item changed to "+ String(newlabel)
See also BeginLabelEdit

Syntax 2 For TreeView controls

Description Occurs when the user finishes editing an item’s label.

242
 Chapter 9 PowerScript Events

Event ID
Event ID Objects
pbm_tvnendlabeledit TreeView

Arguments
Argument Description
handle Integer. The index of the TreeView item for which you
have edited the label
newtext The string that represents the new label for the TreeView
item

Return codes Long. Return code choices (specify in a RETURN statement):

0 Allow the new text to become the item’s label
1 Prevent the new text from becoming the item’s label
Usage The user triggers this event by pressing ENTER or TAB after editing the text.
Examples This example displays the old label and the new label in a SingleLineEdit:
TreeViewItem tvi

This.GetItem(handle, tvi)
sle_info.Text = "Finished editing " &
+ String(tvi.Label) &
+ ". Item changed to " &
+ String(newtext)
See also BeginLabelEdit

243
Error

Error
Description Occurs when an error is found in a data or property expression for an external
object or a DataWindow object. Also occurs when a communications error is
found in a client connecting to EAServer.

Improved error-handling capability in PowerBuilder

The Error event is maintained for backward compatibility. If you do not script
the Error event or change its action argument, information from this event is
passed to RuntimeError objects, such as DWRuntimeError or
OLERuntimeError. You can handle these errors in a TRY-CATCH block.

Event ID
Event ID Objects
None Connection, DataWindow, DataStore, JaguarORB, OLE,
OLEObject, OLETxnObject

Arguments
Argument Description
errornumber Unsigned integer by value (PowerBuilder’s error number)
errortext String, read-only (PowerBuilder’s error message)
errorwindowmenu String, read-only (the name of the window or menu that is
the parent of the object whose script caused the error)
errorobject String, read-only (the name of the object whose script
caused the error)
errorscript String, read-only (the full text of the script in which the
error occurred)
errorline Unsigned integer by value (the line in the script where the
error occurred)

244
 Chapter 9 PowerScript Events

Argument Description
action ExceptionAction by reference
A value you specify to control the application’s course of
action as a result of the error. Values are:
• ExceptionFail! — Fail as if this script were not
implemented. The error condition triggers any active
event handlers, or if none, the SystemError event
• ExceptionIgnore! — Ignore this error and return as if
no error occurred (use this option with caution because
the conditions that caused the error can cause another
error)
• ExceptionRetry! — Execute the function or evaluate
the expression again in case the OLE server was not
ready. This option is not valid for DataWindows
• ExceptionSubstituteReturnValue! — Use the value
specified in the returnvalue argument instead of the
value returned by the OLE server or DataWindow and
cancel the error condition
returnvalue Any by reference (a value whose data type matches the
expected value that the OLE server or DataWindow would
have returned)
This value is used when the value of action is
ExceptionSubstituteReturnValue!

Return codes None (do not use a RETURN statement)

Usage DataWindow and OLE objects are dynamic. Expressions that use dot notation
to refer to data and properties of these objects may be valid under some runtime
conditions but not others. The Error event allows you to respond to this
dynamic situation with error recovery logic.
The Error event also allows you to respond to communications errors in the
client component of a distributed application. In the Error event for a custom
connection object, you can tell PowerBuilder what action to take when an error
occurs during communications between the client and the server.
The Error event gives you an opportunity to substitute a default value when the
error is not critical to your application. Its arguments also provide information
that is helpful in debugging. For example, the arguments can help you debug
DataWindow data expressions that can’t be checked by the compiler—such
expressions can only be evaluated during execution.

245
Error

When to substitute a return value

The ExceptionSubstituteReturnValue! action allows you to substitute a return
value when the last element of an expression causes an error. Do not use
ExceptionSubstituteReturnValue! to substitute a return value when an element
in the middle of an expression causes an error. The substituted return value will
not match the data type of the unresolved object reference and will cause a
system error.
The ExceptionSubstituteReturnValue! action can be useful for handling errors
in data expressions.

For DataWindows, when an error occurs while evaluating a data or property

expression, error processing occurs like this:
1 The Error event occurs
2 If the Error event has no script or its action argument is set to
ExceptionFail!, any active exception handler for a DWRuntimeError or its
RuntimeError ancestor is invoked
3 If no exception handler exists, or if the existing exception handlers do not
handle the exception, the SystemError event is triggered
4 If the SystemError event has no script, an application error occurs and the
application is terminated
The error processing in the client component of a distributed application is the
same as for DataWindows.
For information about error processing in OLE controls, see the
ExternalException event. For information about data and property expressions
for DataWindow objects, see the DataWindow Reference.
For information about handling communications errors in a distributed
application, see the discussion of distributed applications in Application
Techniques.
Examples This example displays information about the error that occurred and allows the
script to continue:
MessageBox("Error Number " + string(errornumber)&
+ " Occurred", "Errortext: " + String(errortext))
action = ExceptionIgnore!
See also DBError in the DataWindow Reference
ExternalException
SystemError

246
 Chapter 9 PowerScript Events

ExternalException
Description Occurs when an OLE automation command caused an exception on the OLE
server.

Improved error-handling capability in PowerBuilder

The ExternalException event is maintained for backward compatibility. If you
do not script this event or change its action argument, information from this
event is passed to RuntimeError objects, such as OLERuntimeError. You can
handle these errors in a TRY-CATCH block.

Event ID
Event ID Objects
None OLE, OLEObject, OLETxnObject

Arguments
Argument Description
resultcode UnsignedLong by value (a PowerBuilder number
identifying the exception that occurred on the server)
exceptioncode UnsignedLong by value (a number identifying the error
that occurred on the server. For the meaning of the code,
see the server documentation)
source String by value (the name of the server (provided by the
server))
description String by value (a description of the exception (provided
by the server))
helpfile String by value (the name of a Help file containing
information about the exception (provided by the server))
helpcontext UnsignedLong by value (the context ID of a Help topic in
helpfile containing information about the exception
(provided by the server))

247
ExternalException

Argument Description
action ExceptionAction by reference
A value you specify to control the application’s course of
action as a result of the error. Values are:
• ExceptionFail! — Fail as if this script were not
implemented. The error condition triggers the
SystemError event
• ExceptionIgnore! — Ignore this error and return as if no
error occurred (use this option with caution because the
conditions that caused the error can cause another error)
• ExceptionRetry! — Execute the function or evaluate
the expression again in case the OLE server was not
ready
• ExceptionSubstituteReturnValue! — Use the value
specified in the returnvalue argument instead of the
value returned by the OLE server or DataWindow and
cancel the error condition
returnvalue Any by reference
A value whose data type matches the expected value that
the OLE server would have returned. This value is used
when the value of action is
ExceptionSubstituteReturnValue!

Return codes None (do not use a RETURN statement)

Usage OLE objects are dynamic. Expressions that refer to data and properties of these
objects may be valid under some runtime conditions but not others. If the
expression causes an exception on the server, PowerBuilder triggers the
ExternalException event. The ExternalException event gives you information
about the error that occurred on the OLE server.
The server defines what it considers exceptions. Some errors, such as
mismatched data types, generally do not cause an exception but do trigger the
Error event. In some cases you may not consider the cause of the exception to
be an error. To determine the reason for the exception, see the documentation
for the server.
When an exception occurs because of a call to an OLE server, error handling
occurs like this:
1 The ExternalException event occurs
2 If the ExternalException event has no script or its action argument is set to
ExceptionFail!, the Error event occurs

248
 Chapter 9 PowerScript Events

3 If the Error event has no script or its action argument is set to

ExceptionFail!, any active exception handler for an OLERuntimeError or
its RuntimeError ancestor is invoked
4 If no exception handler exists, or if the existing exception handlers do not
handle the exception, the SystemError event is triggered
5 If the SystemError event has no script, an application error occurs and the
application is terminated
Examples Suppose your window has two instance variables: one for specifying the
exception action and another of type Any for storing a potential substitute
value. Before accessing the OLE property, a script sets the instance variables
to an appropriate values:
ie_action = ExceptionSubstituteReturnValue!
ia_substitute = 0
li_currentsetting = ole_1.Object.Value
If the command fails, a script for the ExternalException event displays the Help
topic named by the OLE server, if any. It substitutes the return value you
prepared and returns. The assignment of the substitute value to
li_currentsetting works correctly because their data types are compatible:
string ls_context

// Command line switch for WinHelp numeric context ID

ls_context = "-n " + String(helpcontext)
If Len(HelpFile) > 0 THEN
Run("winhelp.exe " + ls_context + " " + helpfile)
END IF

action = ie_action
returnvalue = ia_substitute
Because the event script must serve for every automation command for the
control, you would need to set the instance variables to appropriate values
before each automation command.
See also Error

249
FileExists

FileExists
Description Occurs when a file is saved in the RichTextEdit control and the file already
exists.
Event ID
Event ID Objects
pbm_renfileexists RichTextEdit

Arguments
Argument Description
filename The name of the file

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
1 Saving of document is canceled
Usage The SaveDocument function can trigger the FileExists event.
Examples This script for FileExists checks a flag to see if the user is performing a save
(which will automatically overwrite the opened file) or wants to rename the file
using Save As. For the Save As case, the script asks the user to confirm
overwriting the file:
integer li_answer

// If user asked to Save to same file,

// don’t prompt for overwriting
IF ib_saveas = FALSE THEN RETURN 0

li_answer = MessageBox("FileExists", &

filename + " already exists. Overwrite?", &
Exclamation!, YesNo!)
MessageBox("Filename arg", filename)

// Returning a non-zero value cancels save

IF li_answer = 2 THEN RETURN 1

250
 Chapter 9 PowerScript Events

GetFocus
Description Occurs just before the control receives focus (before it is selected and becomes
active).
Applies to all controls
Event ID
Event ID Objects
pbm_bnsetfocus CheckBox, CommandButton, Graph, OLE, Picture,
PictureHyperLink, PictureButton, RadioButton
pbm_cbnsetfocus DropDownListBox, DropDownPictureListBox
pbm_dwnsetfocus DataWindow
pbm_ensetfocus SingleLineEdit, EditMask, MultiLineEdit, StaticText,
StaticHyperLink
pbm_lbnsetfocus ListBox, PictureListBox
pbm_lvnsetfocus ListView
pbm_prnsetfocus HProgressBar, VProgressBar
pbm_rensetfocus RichTextEdit
pbm_sbnsetfocus HScrollBar, HTrackBar, VScrollBar, VTrackBar
pbm_tcnsetfocus Tab
pbm_tvnsetfocus TreeView

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples Example 1 This example in a SingleLineEdit control’s GetFocus event
selects the text in the control when the user tabs to it:
This.SelectText(1, Len(This.Text))
Example 2 In Example 1, when the user clicks the SingleLineEdit rather than
tabbing to it, the control gets focus and the text is highlighted but then the click
deselects the text. If you define a user event that selects the text and then post
that event in the GetFocus event, the highlighting works when the user both
tabs and clicks. This code is in the GetFocus event:
This. EVENT POST ue_select( )
This code is in the ue_select user event:
This.SelectText(1, Len(This.Text))
See also Clicked
LoseFocus

251
Help

Help
Description Occurs when the user drags the question-mark button from the title bar to a
menu item or a control and then clicks, or when the user clicks in a control
(giving it focus) and then presses the F1 key.
Event ID
Event ID Objects
pbm_help Window, Menu, DragObject

Arguments
Argument Description
xpos Integer by value (the distance of the Help message from the
left edge of the screen, in PowerBuilder units)
ypos Integer by value (the distance of the Help message from the
top of the screen, in PowerBuilder units)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The question-mark button only appears in the title bar of response windows.
You must set the ContextHelp property to TRUE to enable this event.
You can script Help messages for individual menu items and controls.
PowerBuilder dispatches the associated Windows message to the appropriate
menu item or control.
Examples This example codes a message box to open when the user drags and clicks the
question-mark button over a TrackBar control:
MessageBox("Context Help Message", "Move the TrackBar"
&
+ " slider to~r~n change the DataWindow
magnification.")
See also ShowHelp

252
 Chapter 9 PowerScript Events

Hide
Description Occurs just before the window is hidden.
Event ID
Event ID Objects
pbm_hidewindow Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage A Hide event can occur when a sheet in an MDI frame is closed. It does not
occur when closing a main, response, or popup window.
See also Close
Show

253
HotLinkAlarm

HotLinkAlarm
Description Occurs after a Dynamic Data Exchange (DDE) server application has sent new
(changed) data and the client DDE application has received it.
Event ID
Event ID Objects
pbm_ddedata Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage After establishing a hot link with a DDE server application with the
StartHotLink function, actions on the server can trigger the HotLinkAlarm
event.
Examples This script in the HotLinkAlarm event gets information about the DDE server
application and the new data:
string ls_data, ls_appl, ls_topic, ls_item
GetDataDDEOrigin(ls_appl, ls_topic, ls_item)
GetDataDDE(ls_data)

254
 Chapter 9 PowerScript Events

Idle
Description Occurs when the Idle function has been called in an application object script
and the specified number of seconds have elapsed with no mouse or keyboard
activity.
Event ID
Event ID Objects
None Application

Arguments None
Return codes None (do not use a RETURN statement)
Examples This statement in an application script causes the Idle event to be triggered after
300 seconds of inactivity:
Idle(300)
In the Idle event itself, this statement closes the application:
HALT CLOSE

255
InputFieldSelected

InputFieldSelected
Description In a RichTextEdit control, occurs when the user has double-clicked or pressed
ENTER in an input field, allowing the user to edit the data in the field.

Event ID
Event ID Objects
pbm_reninputfieldselected RichTextEdit

Arguments
Argument Description
fieldname String by value (the name of the input field that was
selected)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This script for the InputFieldSelected event of a RichTextEdit control gets the
data in the input field the user is about to edit:
string ls_fieldvalue
ls_fieldvalue = This.InputFieldGetData(fieldname)
See also PictureSelected

256
 Chapter 9 PowerScript Events

InsertItem
Description Occurs when an item is inserted in the ListView.
Event ID
Event ID Objects
pbm_lvninsertitem ListView

Arguments
Argument Description
index An integer that represents the index of the item being
inserted into the ListView

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example displays the label and index of the inserted item:
ListViewItem lvi
This.GetItem(index, lvi)
sle_info.Text = "Inserted "+ String(lvi.Label) &
+ " into position " &
+ String(index)
See also DeleteItem

257
ItemActivate

ItemActivate
Description Occurs when a ListView item is clicked or double-clicked. The actual firing
mechanism depends on the OneClickActivate and TwoClickActivate property
settings.
Event ID
Event ID Objects
pbm_lvnitemactivate ListView

Arguments
Argument Description
Index An integer that represents the index of the item being
inserted into the ListView

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Use the ItemActivate event instead of the Clicked or DoubleClicked event in
new applications.
The following ListView property settings determine which user action fires the
event:
OneClickActivate TwoClickActivate Firing mechanism
True True Single click
True False Single click
False True Single click on selected item or
double-click on nonselected item
False False Double-click

Examples This code changes a ListView item text label to uppercase lettering. The
change is made in the second column of the item the user clicks or double-
clicks, depending on the ListView property settings:
listviewitem llvi_current

This.GetItem(index, 2, llvi_current)
llvi_current.Label = Upper(llvi_current.Label)
This.SetItem(index, 2, llvi_current)
RETURN 0
See also ItemChanged
ItemChanging

258
 Chapter 9 PowerScript Events

ItemChanged
Description Occurs when an ListView item has changed.
Event ID
Event ID Objects
pbm_lvnitemchanged ListView

Arguments
Argument Description
index The index of the item that is changing
focuschanged Boolean (specifies if focus has changed for the item)
hasfocus Boolean (specifies whether the item has focus)
selectionchange Boolean (specifies whether the selection has changed for
the item)
selected Boolean (specifies whether the item is selected)
otherchange Boolean (specifies if anything other than focus or selection
has changed for the item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example checks whether the event is occurring because focus has changed
to the item:
ListViewItem l_lvi
lv_list.GetItem(index, l_lvi)
IF focuschange and hasfocus THEN
sle1.Text = String(lvi.label) +" has gotten focus."
END IF
See also ItemChanged in the DataWindow Reference
ItemChanging

259
ItemChanging

ItemChanging
Description Occurs just before a ListView changes.
Event ID
Event ID Objects
pbm_lvnitemchanging ListView

Arguments
Argument Description
index The index of the item that has changed
focuschange Boolean (specifies if focus is changing for the item)
hasfocus Boolean (specifies whether the item has focus)
selectionchange Boolean (specifies whether the selection is changing for
the item)
selected Boolean (specifies whether the item is selected)
otherchange Boolean (specifies if anything other than focus or selection
has changed for the item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
See also ItemChanged

260
 Chapter 9 PowerScript Events

ItemCollapsed
Description Occurs when a TreeView item has collapsed.
Event ID
Event ID Objects
pbm_tvnitemcollapsed TreeView

Arguments
Argument Description
handle Long by reference (the handle of the collapsed
TreeViewItem)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example changes the picture for the collapsed item:
TreeViewItem l_tvi
integer li_level

This.GetItem(handle, l_tvi)

CHOOSE CASE l_tvi.Level

CASE 1
l_tvi.PictureIndex = 1
l_tvi.SelectedPictureIndex = 1
CASE 2
l_tvi.PictureIndex = 2
l_tvi.SelectedPictureIndex = 2
CASE 3
l_tvi.PictureIndex = 3
l_tvi.SelectedPictureIndex = 3
CASE 4
l_tvi.PictureIndex = 4
l_tvi.SelectedPictureIndex = 4
END CHOOSE
This.SetItem(handle, l_tvi)
See also ItemCollapsing

261
ItemCollapsing

ItemCollapsing
Description Occurs when a TreeView item is collapsing.
Event ID
Event ID Objects
pbm_tvnitemcollapsing TreeView

Arguments
Argument Description
handle Long by reference (the handle of the collapsing item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The ItemCollapsing event occurs before the ItemCollapsed event.
Examples This example changes the picture for the collapsing item:
TreeViewItem l_tvi
integer li_level

This.GetItem(handle, l_vti)

CHOOSE CASE l_tvi.level

CASE 1
l_tvi.PictureIndex = 1
l_tvi.SelectedPictureIndex = 1
CASE 2
l_tvi.PictureIndex = 2
l_tvi.SelectedPictureIndex = 2
CASE 3
l_tvi.PictureIndex = 3
l_tvi.SelectedPictureIndex = 3
CASE 4
l_tvi.PictureIndex = 4
l_tvi.SelectedPictureIndex = 4
END CHOOSE

This.SetItem(handle, l_tvi)
See also ItemCollapsed

262
 Chapter 9 PowerScript Events

ItemExpanded
Description Occurs when a TreeView item has expanded.
Event ID
Event ID Objects
pbm_tvnitemexpanded TreeView

Arguments
Argument Description
handle Long by reference (the handle of the expanded item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The ItemExpanded event occurs after the ItemExpanding event.
Examples This example sets the picture and selected picture for the expanded item:
TreeViewItem l_tvi
integer li_level

This.GetItem(handle, l_tvi)

CHOOSE CASE l_tvi.Level

CASE 1
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 1
CASE 2
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 2
CASE 3
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 3
CASE 4
l_tvi.PictureIndex = 4
l_tvi.SelectedPictureIndex = 5
END CHOOSE
This.SetItem(handle, l_tvi)
See also ItemExpanding

263
ItemExpanding

ItemExpanding
Description Occurs while a TreeView item is expanding.
Event ID
Event ID Objects
pbm_tvnitemexpanding TreeView

Arguments
Argument Description
handle Long by reference (the handle of the expanding
TreeView item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
1 Prevents the TreeView from expanding
Usage The ItemExpanding event occurs before the ItemExpanded event.
Examples This example sets the picture and selected picture for the expanding item:
TreeViewItem l_tvi
integer li_level

This.GetItem(handle, l_tvi)

CHOOSE CASE l_tvi.Level

CASE 1
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 1
CASE 2
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 2
CASE 3
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 3
CASE 4
l_tvi.PictureIndex = 4
l_tvi.SelectedPictureIndex = 5
END CHOOSE

This.SetItem(handle, l_tvi)
See also ItemExpanded

264
 Chapter 9 PowerScript Events

ItemPopulate
Description Occurs when a TreeView item is being populated with children.
Event ID
Event ID Objects
pbm_tvnitempopulate TreeView

Arguments
Argument Description
handle Long by reference (the handle of the TreeView item
being populated)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example displays the name of the TreeView item you are populating in a
SingleLineEdit:
TreeViewItem tvi

This.GetItem(handle, tvi)
sle_get.Text = "Populating TreeView item " &
+ String(tvi.Label) + " with children"
See also ItemExpanding

265
Key

Key
Description Occurs when the user presses a key.
Event ID
Event ID Objects
pbm_lvnkeydown ListView
pbm_renkey RichTextEdit
pbm_tcnkeydown Tab
pbm_tvnkeydown TreeView
pbm_keydown Window

Arguments
Argument Description
key KeyCode by value
A value of the KeyCode enumerated data type indicating
the key that was pressed (for example, KeyA! or KeyF1!)
keyflags UnsignedLong by value (the modifier keys that were
pressed with the key)
Values are:
1 SHIFT key
2 CTRL key
3 SHIFT and CTRL keys

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
1 Do not process the key (RichTextEdit controls only)
Usage Some PowerBuilder controls capture keystrokes so that the window is
prevented from getting a Key event. These include ListView, TreeView, Tab,
RichTextEdit, and the DataWindow edit control. When these controls have
focus you can respond to keystrokes by writing a script for an event for the
control. If there is no predefined event for keystrokes, you can define a user
event and associate it with a pbm code.
For a RichTextEdit control, pressing a key can perform document formatting.
For example, CTRL+B applies bold formatting to the selection. If you specify a
return value of 1, the document formatting associated with the key will not be
performed.

266
 Chapter 9 PowerScript Events

If the user presses a modifier key and holds it down while pressing another key,
the Key event occurs twice: once when the modifier key is pressed and again
when the second key is pressed. If the user releases the modifier key before
pressing the second key, the value of keyflags will change in the second
occurrence.
When the user releases a key, the Key event does not occur. Therefore, if the
user releases a modifier key, you don’t know the current state of the modifier
keys until another key is pressed.
Examples This example causes a beep when the user presses F1 or F2 as long as SHIFT and
CTRL are not pressed:

IF keyflags = 0 THEN
IF key = KeyF1! THEN
Beep(1)
ELSEIF key = KeyF2! THEN
Beep(20)
END IF
END IF
This line displays the value of keyflags when a key is pressed.
st_1.Text = String(keyflags)
See also SystemKey

267
LineDown

LineDown
Description Occurs when the user clicks the down arrow of the vertical scrollbar.
Event ID
Event ID Objects
pbm_sbnlinedown VScrollBar, VTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a vertical scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineUp and LineDown events; for clicks in the scrollbar background
above and below the thumb, use the PageUp and PageDown event; for
dragging the thumb itself, use the Moved event.
Examples This code in the LineDown event causes the thumb to move down when the
user clicks on the down arrow of the vertical scrollbar and displays the
resulting position in the StaticText control st_1:
IF This.Position > This.MaxPosition - 1 THEN
This.Position = MaxPosition
ELSE
This.Position = This.Position + 1
END IF

st_1.Text = "LineDown " + String(This.Position)

See also LineLeft
LineRight
LineUp
PageDown

268
 Chapter 9 PowerScript Events

LineLeft
Description Occurs when the user clicks in the left arrow of the horizontal scrollbar.
Event ID
Event ID Objects
pbm_sbnlineup HScrollBar, HTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a horizontal scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineLeft and LineRight events; for clicks in the scrollbar background
above and below the thumb, use the PageLeft and Right events; for dragging
the thumb itself, use the Moved event.
Examples This code in the LineLeft event causes the thumb to move left when the user
clicks on the left arrow of the horizontal scrollbar and displays the resulting
position in the StaticText control st_1:
IF This.Position < This.MinPosition + 1 THEN
This.Position = MinPosition
ELSE
This.Position = This.Position - 1
END IF

st_1.Text = "LineLeft " + String(This.Position)

See also LineDown
LineRight
LineUp
PageLeft

269
LineRight

LineRight
Description Occurs when right arrow of the horizontal scrollbar is clicked.
Event ID
Event ID Objects
pbm_sbnlinedown HScrollBar, HTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a horizontal scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineLeft and LineRight events; for clicks in the scrollbar background
above and below the thumb, use the PageLeft and PageRight events; for
dragging the thumb itself, use the Moved event.
Examples This code in the LineRight event causes the thumb to move right when the user
clicks on the right arrow of the horizontal scrollbar and displays the resulting
position in the StaticText control st_1:
IF This.Position > This.MaxPosition - 1 THEN
This.Position = MaxPosition
ELSE
This.Position = This.Position + 1
END IF

st_1.Text = "LineRight " + String(This.Position)

See also LineDown
LineLeft
LineUp
PageRight

270
 Chapter 9 PowerScript Events

LineUp
Description Occurs when the up arrow of the vertical scrollbar is clicked.
Event ID
Event ID Objects
pbm_sbnlineup VScrollBar, VTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a vertical scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineUp and LineDown events; for clicks in the scrollbar background
above and below the thumb, use the PageUp and PageDown events; for
dragging the thumb itself, use the Moved event.
Examples This code in the LineUp event causes the thumb to move up when the user
clicks on the up arrow of the vertical scrollbar and displays the resulting
position in the StaticText control st_1:
IF This.Position < This.MinPosition + 1 THEN
This.Position = MinPosition
ELSE
This.Position = This.Position - 1
END IF

st_1.Text = "LineUp " + String(This.Position)

See also LineDown
LineLeft
LineRight
PageUp

271
LoseFocus

LoseFocus
Description Occurs just before a control receives focus (before it becomes selected and
active).
Event ID
Event ID Description
pbm_controltypekillfocus UserObject (standard visual user objects only)
pbm_bnkillfocus CheckBox, CommandButton, Graph, OLE, Picture,
PictureHyperLink, PictureButton, RadioButton,
StaticText, StaticHyperLink
pbm_cbnkillfocus DropDownListBox, DropDownPictureListBox
pbm_dwnkillfocus DataWindow
pbm_enkillfocus SingleLineEdit, EditMask, MultiLineEdit
pbm_lbnkillfocus ListBox, PictureListBox
pbm_lvnkillfocus ListView
pbm_prnkillfocus HProgressBar, VProgressBar
pbm_renkillfocus RichTextEdit
pbm_sbnkillfocus HScrollBar, HTrackBar, VScrollBar, VTrackBar
pbm_tcnkillfocus Tab
pbm_tvnkillfocus TreeView

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage Write a script for a control’s LoseFocus event if you want some processing to
occur when the user changes focus to another control.
For controls that contain editable text, losing focus can also cause a Modified
event to occur.
In a RichTextEdit control, a LoseFocus event occurs when the user clicks on
the control’s toolbar. The control does not actually lose focus.
Because the MessageBox function grabs focus, you should not use it when
focus is changing, such as in a LoseFocus event. Instead, you might display a
message in the window’s title or a MultiLineEdit.
Examples Example 1 In this script for the LoseFocus event of a SingleLineEdit
sle_town, the user is reminded to enter information if the textbox is left empty:
IF sle_town.Text = "" THEN
st_status.Text = "You have not specified a town."
END IF

272
 Chapter 9 PowerScript Events

Example 2 Statements in the LoseFocus event for a DataWindow control

dw_emp can trigger a user event whose script validates the last item the user
entered.
This statement triggers the user event ue_accept:
dw_emp.EVENT ue_accept( )
This statement in ue_accept calls the AcceptText function:
dw_emp.AcceptText( )
This script for the LoseFocus event of a RichTextEdit control performs
processing when the control actually loses focus:
GraphicObject l_control

// Check whether the RichTextEdit still has focus

l_control = GetFocus()
IF TypeOf(l_control) = RichTextEdit! THEN RETURN 0

// Perform processing only if RichTextEdit lost focus

...
This script gets the name of the control instead:
GraphicObject l_control
string ls_name
l_control = GetFocus()
ls_name = l_control.Classname( )
See also GetFocus

273
Modified

Modified
Description Occurs when the contents in the control has changed.
Event ID
Event ID Objects
pbm_cbnmodified DropDownListBox, DropDownPictureListBox
pbm_enmodified SingleLineEdit, EditMask, MultiLineEdit
pbm_renmodified RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage For plain text controls, the Modified event occurs when the user indicates being
finished by pressing ENTER or tabbing away from the control.
For RichText Edit controls, the value of the Modified property controls the
Modified event. If the property is FALSE, the event occurs when the first
change occurs to the contents of the control. The change also causes the
property to be set to TRUE, which suppresses the Modified event. You can
restart checking for changes by setting the property back to FALSE.
Resetting the Modified property is useful when you insert a document in the
control, which triggers the event and sets the property (it is reporting the
change to the control’s contents). To find out when the user begins making
changes to the content, set the Modified property back to FALSE in the script
that opens the document. When the user begins editing, the property will be
reset to TRUE and the event will occur again.
A Modified event can be followed by a LoseFocus event.
Examples In this example, code in the Modified event performs validation on the text the
user entered in a SingleLineEdit control sle_color (if the user didn’t enter RED,
WHITE, or BLUE, a message box tells them what is valid input; for valid
input, the color of the text changes):
string ls_color

This.BackColor = RGB(150,150,150)

ls_color = Upper(This.Text)
CHOOSE CASE ls_color
CASE "RED"
This.TextColor = RGB(255,0,0)
CASE "BLUE"

274
 Chapter 9 PowerScript Events

This.TextColor = RGB(0,0,255)
CASE "WHITE"
This.TextColor = RGB(255,255,255)
CASE ELSE
This.Text = ""
MessageBox("Invalid input", &
"Enter RED, WHITE, or BLUE.")
END CHOOSE
This is not a realistic example—user input of three specific choices is more
suited to a listbox; in a real situation, the allowed input might be more general.
See also LoseFocus

275
MouseDown

MouseDown
The MouseDown event has different arguments for different objects:
Object See
RichTextEdit control Syntax 1
Window Syntax 2

Syntax 1 For RichTextEdit controls

Description Occurs when the user presses the left mouse button on the RichTextEdit
control.
Event ID
Event ID Objects
pbm_renlbuttondown RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples This code in a RichTextEdit control’s MouseDown event assigns text to the
SingleLineEdit sle_1 when the user presses the left mouse button:
sle_1.text = "Mouse Down"
See also Clicked
MouseMove
MouseUp

Syntax 2 For windows

Description Occurs when the user presses the left mouse button in an unoccupied area of
the window (any area with no visible, enabled object).
Event ID
Event ID Objects
pbm_lbuttondown Window

276
 Chapter 9 PowerScript Events

Arguments
Argument Description
flags UnsignedLong by value (the modifier keys and mouse
buttons that are pressed)
Values are:
• 1 — Left mouse button
• 2 — Right mouse button
• 4 — SHIFT key
• 8 — CTRL key
• 16 — Middle mouse button
In the MouseDown event, the left mouse button is always
down, so 1 is always summed in the value of flags
For an explanation of flags, see Syntax 2 of MouseMove
on page 279
xpos Integer by value (the distance of the pointer from the left
edge of the window’s workspace in pixels)
ypos Integer by value (the distance of the pointer from the top of
the window’s workspace in pixels)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples Example 1 This code in the MouseDown event displays the window
coordinates of the pointer as reported in the xpos and ypos arguments:
sle_2.Text = "Position of Pointer is: " + &
String(xpos) + "," + String(ypos)
Example 2 This code in the MouseDown event checks the value of the flags
argument and reports which modifier keys are pressed in the SingleLineEdit
sle_modkey:
CHOOSE CASE flags
CASE 1
sle_mkey.Text = "No modifier keys pressed"

CASE 5
sle_mkey.Text = "SHIFT key pressed"

CASE 9
sle_mkey.Text = "CONTROL key pressed"

CASE 13
sle_mkey.Text = "SHIFT and CONTROL keys

277
MouseDown

pressed"

END CHOOSE
See also Clicked
MouseMove
MouseUp

278
 Chapter 9 PowerScript Events

MouseMove
The MouseMove event has different arguments for different objects:
Object See
RichTextEdit control Syntax 1
Window Syntax 2

Syntax 1 For RichTextEdit controls

Description Occurs when the mouse has moved within the RichTextEdit control.
Event ID
Event ID Objects
pbm_renmousemove RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
See also Clicked
MouseDown
MouseUp

Syntax 2 For windows

Description Occurs when the pointer is moved within the window.
Event ID
Event ID Objects
pbm_mousemove Window

279
MouseMove

Arguments
Argument Description
flags UnsignedLong by value (the modifier keys and mouse
buttons that are pressed)
Values are:
• 1 — Left mouse button
• 2 — Right mouse button
• 4 — SHIFT key
• 8 — CTRL key
• 16— Middle mouse button
Flags is the sum of all the buttons and keys that are
pressed
xpos Integer by value (the distance of the pointer from the left
edge of the window’s workspace in pixels)
ypos Integer by value (the distance of the pointer from the top of
the window’s workspace in pixels)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Because most controls in the window do not capture MouseMove events, the
window’s MouseMove event will still be triggered when the mouse moves over
the controls.
Because flags is a sum of button and key numbers, you can find out what keys
are pressed by subtracting the largest values one by one and checking the value
that remains. For example:
• If flags is 5, the SHIFT key (4) and the left mouse button (1) are pressed.
• If flags is 14, the CTRL key (8), the SHIFT key (4), and the right mouse
button (2) are pressed.
This code handles all the buttons and keys (the local boolean variables are
initialized to FALSE by default):
boolean lb_left_button, lb_right_button
boolean lb_middle_button, lb_shift_key, lb_control_key
integer li_flags

li_flags = flags
IF li_flags 15 THEN
// Middle button is pressed
lb_middle_button = TRUE
li_flags = li_flags - 16

280
 Chapter 9 PowerScript Events

END IF

IF li_flags 7 THEN
// Control key is pressed
lb_control_key = TRUE
li_flags = li_flags - 8
END IF

IF li_flags > 3 THEN

// Shift key is pressed
lb_shift_key = TRUE
li_flags = li_flags - 4
END IF

IF li_flags > 1 THEN

// Right button is pressed
lb_lb_right_button = TRUE
li_flags = li_flags - 2
END IF

IF li_flags = 1 THEN lb_left_button = TRUE

Examples This code in the MouseMove event causes a meter OLE custom control (OCX)
to rise and fall continually as the mouse pointer is moved up and down in the
window workspace:
This.uf_setmonitor(ypos, ole_verticalmeter, &
This.WorkspaceHeight() )
The uf_setmonitor is a window function that scales the pixels to the range of
the gauge; it accepts three arguments: the vertical position of the mouse
pointer, an OLECustomControl reference, and the maximum range of the
mouse pointer for scaling purposes:
double ld_gaugemax, ld_gaugemin
double ld_gaugerange, ld_value

// Ranges for monitor-type control

ld_gaugemax = ocxitem.Object.MaxValue
ld_gaugemin = ocxitem.Object.MinValue
ld_gaugerange = ld_gaugemax - ld_gaugemin

// Horizontal position of mouse within window

ld_value = data * ld_gaugerange / range + ld_gaugemin

// Set gauge
ocxitem.Object.Value = Round(ld_value, 0)

281
MouseMove

RETURN 1
Because the OCX also has a MouseMove event, this code in its MouseMove
event keeps the gauge responding when the pointer is over the gauge (you need
to pass values for the arguments the system ordinarily handles; the mouse
position values are specified in relation to the parent window):
Parent.EVENT MouseMove(0, Parent.PointerX(), &
Parent.PointerY())
See also Clicked
MouseDown
MouseUp

282
 Chapter 9 PowerScript Events

MouseUp
The MouseUp event has different arguments for different objects:
Object See
RichTextEdit control Syntax 1
Window Syntax 2

Syntax 1 For RichTextEdit controls

Description Occurs when the user releases the left mouse button in a RichTextEdit control.
Event ID
Event ID Objects
pbm_renlbuttonup RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage A Clicked event also occurs when the mouse button is released.
Examples The following code in a RichTextEdit control’s MouseUp event assigns text to
the SingleLineEdit sle_1 when the user releases the left mouse button:
sle_1.Text = "Mouse Up"
See also Clicked
MouseDown
MouseMove

Syntax 2 For windows

Description Occurs when the user releases the left mouse button in an unoccupied area of
the window (any area with no visible enabled object).
Event ID
Event ID Objects
pbm_lbuttonup Window

283
MouseUp

Arguments
Argument Description
flags UnsignedLong by value (the modifier keys and mouse
buttons that are pressed)
Values are:
• 1 — Left mouse button
• 2 — Right mouse button
• 4 — SHIFT key
• 8 — CTRL key
• 16 — Middle mouse button
In the MouseUp event, the left mouse button is being
released, so 1 is not summed in the value of flags
For an explanation of flags, see Syntax 2 of MouseMove
on page 279
xpos Integer by value (the distance of the pointer from the left
edge of the window’s workspace in pixels)
ypos Integer by value (the distance of the pointer from the top of
the window’s workspace in pixels)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage A Clicked event also occurs when the mouse button is released.
Examples Example 1 This code in the window’s MouseUp event displays in the
SingleLineEdit sle_2 the window coordinates of the pointer when the button is
released as reported in the xpos and ypos arguments.
sle_2.Text = "Position of Pointer is: " + &
String(xpos) + "," + String(ypos)
Example 2 This code in the window’s MouseUp event checks the value of
the flags argument and reports which modifier keys are pressed in the
SingleLineEdit sle_modkey.
CHOOSE CASE flags
CASE 0
sle_mkey.Text = "No modifier keys pressed"

CASE 4
sle_mkey.Text = "SHIFT key pressed"

CASE 8
sle_mkey.Text = "CONTROL key pressed"

284
 Chapter 9 PowerScript Events

CASE 12
sle_mkey.Text = "SHIFT and CONTROL keys
pressed"

END CHOOSE
See also Clicked
MouseDown
MouseMove

285
Moved

Moved
Description Occurs when the user moves the scroll box, either by clicking on the arrows or
by dragging the box itself.
Event ID
Event ID Objects
pbm_sbnthumbtrack HScrollBar, HTrackBar, VScrollBar, VTrackBar

Arguments
Argument Description
scrollpos Integer by value (a number indicating position of the scroll
box within the range of values specified by the
MinPosition and MaxPosition properties)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Moved event updates the Position property of the scrollbar with the value
of scrollpos.
Examples This statement in the Moved event displays the new position of the scroll box
in a StaticText control:
st_1.Text = "Moved " + String(scrollpos)
See also LineDown
LineLeft
LineRight
LineUp
PageDown
PageLeft
PageRight
PageUp

286
 Chapter 9 PowerScript Events

Open
The Open event has different arguments for different objects:
Object See
Application Syntax 1
Window Syntax 2

Syntax 1 For the application object

Description Occurs when the user starts the application.
Event ID
Event ID Objects
None Application

Arguments
Argument Description
commandline String by value
Additional arguments included on the command line after
the name of the executable program

Return codes None (do not use a RETURN statement)

Usage This event can establish database connection parameters and open the main
window of the application.

On Windows
You can specify command line arguments when you use the Run command
from the Start menu or as part of the Target specification when you define a
shortcut for your application.

There is no way to specify command line values when you are testing your
application in the development environment.
In other events and functions, you can call the CommandParm function to get
the command line arguments.
For an example of parsing the string in commandline, see CommandParm on
page 405.
Examples This example populates the SQLCA global variable from the application’s
initialization file, connects to the database, and opens the main window:

287
Open

/* Populate SQLCA from current myapp.ini settings */

SQLCA.DBMS = ProfileString("myapp.ini", "database", &
"dbms", "")
SQLCA.Database = ProfileString("myapp.ini", &
"database", "database", "")
SQLCA.Userid = ProfileString("myapp.ini", "database", &
"userid", "")
SQLCA.DBPass = ProfileString("myapp.ini", "database", &
"dbpass", "")
SQLCA.Logid = ProfileString("myapp.ini", "database", &
"logid", "")
SQLCA.Logpass = ProfileString("myapp.ini", &
"database", "LogPassWord", "")
SQLCA.Servername = ProfileString("myapp.ini", &
"database", "servername", "")
SQLCA.DBParm = ProfileString("myapp.ini", "database", &
"dbparm", "")

CONNECT;

IF SQLCA.Sqlcode <> 0 THEN

MessageBox("Cannot Connect to Database", &
SQLCA.SQLErrText)
RETURN
END IF

/* Open MDI frame window */

Open(w_genapp_frame)
See also Close

Syntax 2 For windows

Description Occurs when a window is opened by one of the Open functions. The event
occurs after the window has been opened but before it is displayed.
Event ID
Event ID Objects
pbm_open Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing

288
 Chapter 9 PowerScript Events

Usage These functions trigger the Open event:

Open
OpenWithParm
OpenSheet
OpenSheetWithParm
When the Open event occurs, the controls on the window already exist (their
Constructor events have occurred). In the Open event script, you can refer to
objects in the window and affect their appearance or content. For example, you
can disable a button or retrieve data for a DataWindow.
Some actions are not appropriate in the Open event even though all the controls
exist. For example, calling the SetRedraw function for a control fails because
the window is not yet visible.

Changing the WindowState property

Do not change the WindowState property in the Open event of a window
opened as a sheet. Doing so may result in duplicate controls on the title bar. You
can change the property in other scripts once the window is open.

When a window is opened, other events occur, such as Constructor for each
control in the window, Activate and Show for the window, and GetFocus for
the first control in the window’s tab order.
When a sheet is opened in an MDI frame, other events occur, such as Show and
Activate for the sheet and Activate for the frame.
Examples When the window contains a DataWindow control, you can retrieve data for it
in the Open event. In this example, values for the transaction object SQLCA
have already been set up:
dw_1.SetTransObject(SQLCA)
dw_1.Retrieve( )
See also Activate
Constructor
Show

289
Other

Other
Description Occurs when a system message occurs that is not a PowerBuilder message.
Event ID
Event ID Objects
pbm_other Windows and controls that can be placed in windows

Arguments
Argument Description
wparam UnsignedLong by value
lparam Long by value

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Other event is no longer useful, because you can define your own user
events. You should avoid using it (it slows performance while it checks every
Windows message).

290
 Chapter 9 PowerScript Events

PageDown
Description Occurs when the user clicks in the open space below the scroll box.
Event ID
Event ID Objects
pbm_sbnpagedown VScrollBar, VTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a vertical scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineUp and LineDown events; for clicks in the scrollbar background
above and below the thumb, use the PageUp and PageDown events; for
dragging the thumb itself, use the Moved event.
Examples Example 1 This code in the VScrollBar’s PageDown event uses a
predetermined paging value stored in the instance variable ii_pagesize to
change the position of the scroll box (you would need additional code to
change the view of associated controls according to the scrollbar position):
IF This.Position > &
This.MaxPosition - ii_pagesize THEN
This.Position = MaxPosition
ELSE
This.Position = This.Position + ii_pagesize
END IF
RETURN 0
Example 2 This example changes the position of the scroll box by a
predetermined page size stored in the instance variable ii_pagesize and scrolls
forward through a DataWindow control 10 rows for each page:
long ll_currow, ll_nextrow

This.Position = This.Position + ii_pagesize

ll_currow = dw_1.GetRow()

ll_nextrow = ll_currow + 10
dw_1.ScrollToRow(ll_nextrow)
dw_1.SetRow(ll_nextrow)
See also LineDown
PageLeft
PageRight
PageUp

291
PageLeft

PageLeft
Description Occurs when the open space to the left of the scroll box is clicked.
Event ID
Event ID Objects
pbm_sbnpageup HScrollBar, HTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a horizontal scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineLeft and LineRight events; for clicks in the scrollbar background
above and below the thumb, use the PageLeft and Right events; for dragging
the thumb itself, use the Moved event.
Examples This code in the PageLeft event causes the thumb to move left a predetermined
page size when the user clicks on the left arrow of the horizontal scrollbar (the
page size is stored in the instance variable ii_pagesize):
IF This.Position < &
This.MinPosition + ii_pagesize THEN
This.Position = MinPosition
ELSE
This.Position = This.Position - ii_pagesize
END IF
See also LineLeft
PageDown
PageRight
PageUp

292
 Chapter 9 PowerScript Events

PageRight
Description Occurs when the open space to the right of the scroll box is clicked.
Event ID
Event ID Objects
pbm_sbnpagedown HScrollBar, HTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a horizontal scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineLeft and LineRight events; for clicks in the scrollbar background
above and below the thumb, use the PageLeft and Right event; for dragging the
thumb itself, use the Moved event.
Examples This code in the PageRight event causes the thumb to move right when the user
clicks on the right arrow of the horizontal scrollbar (the page size is stored in
the instance variable ii_pagesize):
IF This.Position > &
This.MaxPosition - ii_pagesize THEN
This.Position = MaxPosition
ELSE
This.Position = This.Position + ii_pagesize
END IF
See also LineRight
PageDown
PageLeft
PageUp

293
PageUp

PageUp
Description Occurs when the user clicks in the open space above the scroll box (also called
the thumb).
Event ID
Event ID Objects
pbm_sbnpageup VScrollBar, VTrackBar

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage When the user clicks in a vertical scrollbar, nothing happens unless you have
scripts that change the scrollbar’s Position property. For the scrollbar arrows,
use the LineUp and LineDown events; for clicks in the scrollbar background
above and below the thumb, use the PageUp and PageDown events; for
dragging the thumb itself, use the Moved event.
Examples Example 1 This code in the PageUp event causes the thumb to move up when
the user clicks on the up arrow of the vertical scrollbar (the page size is stored
in the instance variable ii_pagesize):
IF This.Position < &
This.MinPosition + ii_pagesize THEN
This.Position = MinPosition
ELSE
This.Position = This.Position - ii_pagesize
END IF
Example 2 This example changes the position of the scroll box by a
predetermined page size stored in the instance variable ii_pagesize and scrolls
backwards through a DataWindow control 10 rows for each page:
long ll_currow, ll_prevrow

This.Position = This.Position - ii_pagesize

ll_currow = dw_1.GetRow( )
ll_prevrow = ll_currow - 10
dw_1.ScrollToRow(ll_prevrow)
dw_1.SetRow(ll_prevrow)
See also LineUp
PageDown
PageLeft
PageRight

294
 Chapter 9 PowerScript Events

PictureSelected
Description Occurs when the user selects a bitmap in the RichTextEdit control by double-
clicking it or pressing ENTER after clicking it.
Event ID
Event ID Objects
pbm_renpictureselected RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples When the user double-clicks a picture in a RichTextEdit control rte_1, the
picture is selected. This code for the PictureSelected event selects the rest of
the contents, copies the contents to a string with RTF formatting intact, and
pastes the formatted text into a second RichTextEdit rte_2:
string ls_transfer_rtf

This.SelectTextAll()
ls_transfer_rtf = This.CopyRTF()

rte_2.PasteRTF(ls_transfer_rtf)
See also InputFieldSelected

295
PipeEnd

PipeEnd
Description Occurs when pipeline processing is completed.
Event ID
Event ID Objects
pbm_pipeend Pipeline

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage You can use the PipeEnd event to check the status of pipeline processing.
The Start and Repair functions initiate pipeline processing.
For a complete example of using a Pipeline object, see Application Techniques.
Examples This code in a Pipeline user object’s PipeEnd event reports pipeline status in a
StaticText control:
ist_status.Text = "Finished Pipeline Execution ..."
See also PipeMeter
PipeStart

296
 Chapter 9 PowerScript Events

PipeMeter
Description Occurs during pipeline processing after each block of rows is read or written.
The Commit factor specified for the Pipeline in the Pipeline painter determines
the size of each block.
Event ID
Event ID Objects
pbm_pipemeter Pipeline

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage The Start and Repair functions initiate pipeline processing.
In the Pipeline painter, you can specify a Commit factor specifying the number
of rows that will be transferred before they are committed to the database. The
PipeMeter event occurs for each block of rows as specified by the Commit
factor.
For a complete example of using a Pipeline object, see Application Techniques.
Examples This code in a Pipeline user object’s PipeMeter event report the number of rows
that have been piped to the destination database:
ist_status.Text = String(This.RowsWritten) &
+ " rows written to the destination database."
See also PipeEnd
PipeStart

297
PipeStart

PipeStart
Description Occurs when pipeline processing begins.
Event ID
Event ID Objects
pbm_pipestart Pipeline

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage You can use the PipeStart event to check the status of pipeline processing.
The Start and Repair functions initiate pipeline processing.
For a complete example of using a Pipeline object, see Application Techniques.
Examples This code in a Pipeline user object’s PipeStart event reports pipeline status in a
StaticText control:
ist_status.Text = "Beginning Pipeline Execution ..."
See also PipeEnd
PipeMeter

298
 Chapter 9 PowerScript Events

PrintFooter
Description Occurs when the footer of a page of the document in the RichTextEdit control
is about to be printed.
Event ID
Event ID Objects
pbm_renprintfooter RichTextEdit

Arguments
Argument Description
currentpage Long by value (the number of the page being printed)
totalpages Long by value (the total number of pages in the document)
If the RichTextEdit control is sharing data with a
DataWindow, totalpages is the total number of pages in a
document instance
currentrow Long by value
If the RichTextEdit control is sharing data with a
DataWindow, then the number of the row associated with
the document instance currently being printed

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
1 Do not print the header for the current page
Usage In the PrintHeader and PrintFooter events, you can change the printed page
number by setting the value of an input field that you’ve inserted for that
purpose.
When an RichTextEdit control shares data with a DataWindow, there is a
document instance for each row in the DataWindow. Each instance uses data
in the associated row to populate its input fields.
For more information about sharing data between RichTextEdit and
DataWindow controls, see the ShareData function in the DataWindow
Reference.
Examples This statement in the PrintFooter event of a RichTextEdit control reports the
progress of the print job in the StaticText st_1.
st_1.Text = "Printing footer on page " &
+ String(currentpage) + " of " &
+ String(totalpages) + " pages ...."
See also PrintHeader

299
PrintHeader

PrintHeader
Description Occurs when the header of a page of the document in the RichTextEdit control
is about to be printed.
Event ID
Event ID Objects
pbm_renprintheader RichTextEdit

Arguments
Argument Description
currentpage Long by value (the number of the page being printed)
totalpages Long by value (the total number of pages in the document)
If the RichTextEdit control is sharing data with a
DataWindow, totalpages is the total number of pages in a
document instance
currentrow Long by value
If the RichTextEdit control is sharing data with a
DataWindow, the number of the row associated with the
document instance currently being printed

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
1 Do not print the header for the current page
Usage In the PrintHeader and PrintFooter events, you can change the printed page
number by setting the value of an input field that you’ve inserted for that
purpose.
When an RichTextEdit control shares data with a DataWindow, there is a
document instance for each row in the DataWindow. Each instance uses data
in the associated row to populate its input fields.
For more information about sharing data between RichTextEdit and
DataWindow controls, see the ShareData function in the DataWindow
Reference.
Examples This statement in the PrintHeader event of a RichTextEdit control reports the
progress of the print job in the StaticText st_1:
st_1.Text = "Printing header on page " &
+ String(currentpage) + " of " &
+ String(totalpages) + " pages ...."
See also PrintFooter

300
 Chapter 9 PowerScript Events

PropertyChanged
Description Occurs after the OLE server changes the value of a property of the OLE object.
Event ID
Event ID Objects
None OLE

Arguments
Argument Description
propertyname The name of the property whose value changed. If
propertyname is an empty string, a more general change
occurred, such as changes to more than one property

Return codes None (do not use a RETURN statement)

Usage Property change notifications are not supported by all OLE servers. The
PropertyRequestEdit and PropertyChanged events only occur when the server
supports these notifications.
Property notifications are not sent when the object is being created or loaded.
Otherwise, notifications are send for all bindable properties, no matter how the
property is being changed.
The PropertyChanged event occurs after the property’s value has changed. You
can obtain the new value through the automation interface. The change can no
longer be canceled. If you want to cancel a change, write a script for the
PropertyRequestEdit event.
See also DataChange
PropertyRequestEdit
Rename
ViewChange

301
PropertyRequestEdit

PropertyRequestEdit
Description Occurs when the OLE server is about to change the value of a property of the
object in the OLE control.
Event ID
Event ID Objects
None OLE

Arguments
Argument Description
propertyname String by value (the name of the property whose value
changed)
If propertyname is an empty string, a more general
change occurred, such as changes to more than one
property
cancelchange Boolean by reference
Whether the change will be canceled. Values are:
• FALSE — (Default) The change is allowed
• TRUE — The change is canceled

Return codes None (do not use a RETURN statement)

Usage Property change notifications are not supported by all OLE servers. The
PropertyRequestEdit and PropertyChanged events only occur when the server
supports these notifications.
Property notifications are not sent when the object is being created or loaded.
Otherwise, notifications are send for all bindable properties, no matter how the
property is being changed.
The PropertyRequestEdit event gives you a chance to access the property’s old
value via the automation interface and save it. To cancel the change, set the
cancelchange argument to TRUE.
See also DataChange
PropertyChanged
Rename
ViewChange

302
 Chapter 9 PowerScript Events

RButtonDown
The RButtonDown event has different arguments for different object:
Object See
Controls and windows, except Syntax 1
RichTextEdit
RichTextEdit control Syntax 2

Syntax 1 For controls and windows, except RichTextEdit

Description For a window, occurs when the right mouse button is pressed in an unoccupied
area of the window (any area with no visible, enabled object). The window
event will occur if the cursor is over an invisible or disabled control.
For a control, occurs when the right mouse button is pressed on the control.
Event ID
Event ID Objects
pbm_rbuttondown Windows and controls that can be placed on a window,
except RichTextEdit

Arguments
Argument Description
flags UnsignedLong by value (the modifier keys and mouse
buttons that are pressed)
Values are:
• 1 — Left mouse button
• 2 — Right mouse button
• 4 — SHIFT key
• 8 — CTRL key
• 16 — Middle mouse button
In the RButtonDown event, the right mouse button is
always pressed, so 2 is always summed in the value of
flags
For an explanation of flags, see Syntax 2 of MouseMove
on page 279
xpos Integer by value (the distance of the pointer from the left
edge of the window’s workspace in pixels)
ypos Integer by value (the distance of the pointer from the top
of the window’s workspace in pixels)

303
RButtonDown

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples These statements in the RButtonDown script for the window display a popup
menu at the cursor position. Menu4 was created in the Menu painter and
includes a menu called m_language. Menu4 is not the menu for the active
window and therefore needs to be created. NewMenu is an instance of Menu4
(data type Menu4):
Menu4 NewMenu
NewMenu = CREATE Menu4
NewMenu.m_language.PopMenu(xpos, ypos)
In an MDI application, the arguments for PopMenu need to specify coordinates
relative to the MDI frame:
NewMenu.m_language.PopMenu( &
w_frame.PointerX(), w_frame.PointerY())
See also Clicked

Syntax 2 For RichTextEdit controls

Description Occurs when the user presses the right mouse button on the RichTextEdit
control and the control’s PopMenu property is set to FALSE.
Event ID
Event ID Objects
pbm_renrbuttondown RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage If the control’s PopMenu property is TRUE, the standard RichTextEdit popup
menu is displayed instead, and the RButtonDown event does not occur.
You can use the RButtonDown event to implement your own popup menu.
See also Clicked
RButtonDown

304
 Chapter 9 PowerScript Events

RButtonUp
Description Occurs when the right mouse button is released.
Event ID
Event ID Objects
pbm_renrbuttonup RichTextEdit

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
1 Prevent processing
See also RButtonDown

305
RemoteExec

RemoteExec
Description Occurs when a DDE client application has sent a command.
Event ID
Event ID Objects
pbm_ddeexecute Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
See also RemoteRequest
RemoteSend

306
 Chapter 9 PowerScript Events

RemoteHotLinkStart
Description Occurs when a DDE client application wants to start a hot link.
Event ID
Event ID Objects
pbm_ddeadvise Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples When both the DDE client and server are PowerBuilder applications, this
example in a script in the client application will trigger the
RemoteHotLinkStart event in the server application window:
StartHotLink("mysle","pb_dde_server","mytest")
In the RemoteHotLinkStart event in the server application, set a boolean
instance variable indicating that a hot link has been established:
ib_hotlink = TRUE
See also HotLinkAlarm
RemoteHotLinkStop
SetDataDDE
StartServerDDE
StopServerDDE

307
RemoteHotLinkStop

RemoteHotLinkStop
Description Occurs when a DDE client application wants to end a hot link.
Event ID
Event ID Objects
pbm_ddeunadvise Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples When both the DDE client and server are PowerBuilder applications, this
example in a script in the client application will trigger the
RemoteHotLinkStop event in the server application window:
StopHotLink("mysle","pb_dde_server","mytest")
In the RemoteHotLinkStart event in the server application, set a boolean
instance variable indicating that a hot link no longer exists:
ib_hotlink = FALSE
See also HotLinkAlarm
RemoteHotLinkStart
SetDataDDE
StartServerDDE
StopServerDDE

308
 Chapter 9 PowerScript Events

RemoteRequest
Description Occurs when a DDE client application requests data.
Event ID
Event ID Objects
pbm_dderequest Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
See also RemoteExec
RemoteSend

309
RemoteSend

RemoteSend
Description Occurs when a DDE client application has sent data.
Event ID
Event ID Objects
pbm_ddepoke Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
See also RemoteExec
RemoteRequest

310
 Chapter 9 PowerScript Events

Rename
Description Occurs when the server application notifies the control that the object has been
renamed.
Event ID
Event ID Objects
pbm_omnrename OLE

Arguments None
Return codes Long. Return code: Ignored
Usage If you want to retrieve the ObjectData blob value of an OLE control during the
processing of this event, you must post a user event back to the control or you
will generate a runtime error.
See also DataChange
PropertyRequestEdit
PropertyChanged
ViewChange

311
Resize

Resize
Description Occurs when the user or a script opens or resizes the client area of a window or
DataWindow control.
Event ID
Event ID Objects
pbm_dwnresize DataWindow
pbm_size Window

Arguments
Argument Description
sizetype UnsignedLong by value
• 0 — (SIZE_RESTORED) The window or DataWindow
has been resized, but it was not minimized or
maximized. The user may have dragged the borders or
a script may have called the Resize function
• 1 — (SIZE_MINIMIZED) The window or
DataWindow has been minimized
• 2 — (SIZE_MAXIMIZED) The window or
DataWindow has been maximized
• 3 — (SIZE_MAXSHOW) This window is a popup
window and some other window in the application has
been restored to its former size (does not apply to
DataWindow controls)
• 4 — (SIZE_MAXHIDE) This window is a popup
window and some other window in the application has
been maximized (does not apply to DataWindow
controls)
newwidth Integer by value (the width of the client area of a window
or DataWindow control in PowerBuilder units)
newheight Integer by value (the height of the client area of a window
or DataWindow control in PowerBuilder units)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing

312
 Chapter 9 PowerScript Events

RightClicked
The RightClicked event has different arguments for different objects:
Object See
ListView and Tab control Syntax 1
TreeView control Syntax 2
ProgressBar control Syntax 3

Syntax 1 For ListView and Tab controls

Description Occurs when the user clicks the right mouse button on the ListView control or
the tab portion of the Tab control.
Event ID
Event ID Objects
pbm_lvnrclicked ListView
pbm_tcnrclicked Tab

Arguments
Argument Description
index Integer by value (the index of the item or tab the user
clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage When the user clicks in the display area of the Tab control, the tab page user
object gets an RButtonDown event rather than a RightClicked event for the Tab
control.
Examples This example for the RightClicked event of a ListView control displays a
popup menu when the user clicks the right mouse button:
// Declare a menu variable of type m_main
m_main m_lv_popmenu

// Create an instance of the menu variable

m_lv_popmenu = CREATE m_main

// Display menu at pointer position

m_lv_popmenu.m_entry.PopMenu(Parent.PointerX(), &
Parent.PointerY())
See also Clicked

313
RightClicked

RightDoubleClicked

Syntax 2 For TreeView controls

Description Occurs when the user clicks the right mouse button on the TreeView control.
Event ID
Event ID Objects
pbm_tvnrclicked TreeView

Arguments
Argument Description
handle Long by value (the handle of the item the user clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example for the RightClicked event of a TreeView control displays a
popup menu when the user clicks the right mouse button:
// Declare a menu variable of type m_main
m_main m_tv_popmenu

// Create an instance of the menu variable

m_tv_popmenu = CREATE m_main

// Display menu at pointer position

m_tv_popmenu.m_entry.PopMenu(Parent.PointerX(), &
Parent.PointerY())
See also Clicked
RightDoubleClicked

Syntax 3 For ProgressBar controls

Description Occurs when the user clicks the right mouse button on a ProgressBar control.
Event ID
Event ID Objects
pbm_prnrclicked HProgressBar, VProgressBar

Arguments None

314
 Chapter 9 PowerScript Events

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
See also Clicked

315
RightDoubleClicked

RightDoubleClicked
The RightDoubleClicked event has different arguments for different objects:
Object See
ListView and Tab control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView and Tab controls

Description Occurs when the user double-clicks the right mouse button on the ListView
control or the tab portion of the Tab control.
Event ID
Event ID Objects
pbm_lvnrdoubleclicked ListView
pbm_tcnrdoubleclicked Tab

Arguments
Argument Description
index Integer by value (the index of the item or tab the user
double-clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example deletes an item from the ListView when the user right-double-
clicks on it and then rearranges the items:
integer li_rtn

// Delete the item

li_rtn = This.DeleteItem(index)

IF li_rtn = 1 THEN
This.Arrange( )
ELSE
MessageBox("Error", Deletion failed!")
END IF
See also DoubleClicked
RightClicked

316
 Chapter 9 PowerScript Events

Syntax 2 For TreeView controls

Description Occurs when the user double-clicks the right mouse button on the TreeView
control.
Event ID
Event ID Objects
pbm_tvnrdoubleclicked TreeView

Arguments
Argument Description
handle Long by value (the handle of the item the user double-
clicked)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Examples This example toggles between displaying and hiding TreeView lines when the
user right-double-clicks on the control:
IF This.HasLines = FALSE THEN
This.HasLines = TRUE
This.LinesAtRoot = TRUE
ELSE
This.HasLines = FALSE
This.LinesAtRoot = FALSE
END IF
See also DoubleClicked
RightClicked

317
Save

Save
Description Occurs when the server application notifies the control that the data has been
saved.
Event ID
Event ID Objects
pbm_omnsave OLE

Arguments None
Return codes Long. Return code: Ignored
Usage If you want to retrieve the ObjectData blob value of an OLE control during the
processing of this event, you must post a user event back to the control or you
will generate a runtime error.
Examples In this example, a table in a database tracks changes of OLE objects; when the
user saves an Excel spreadsheet in an OLE control, this code puts the current
date in a DataWindow so that the database table can be updated:
long ll_row
// Find the row with information for the Excel file
ll_row = dw_1.Find("file_name = ’expenses.xls’", &
1, 999)

IF ll_row > 0 THEN

// Make the found row current
dw_1.SetRow(ll_row)

// Put today’s date in the last_updated column

dw_1.Object.last_updated[ll_row] = Today( )

// Update and refresh the DataWindow

dw_1.Update( )
dw_1.Retrieve( )
ELSE
MessageBox("Find", "No row found")
END IF
See also Close
SaveObject

318
 Chapter 9 PowerScript Events

SaveObject
Description Occurs when the server application saves the object in the control.
Event ID
Event ID Objects
pbm_omnsaveobject OLE

Arguments None
Return codes Long. Return code: Ignored
Usage Using the SaveObject event is the preferred technique for retrieving the
ObjectData blob value of an OLE control when the server saves the data in the
embedded object. Unlike the Save and Close events, the SaveObject event does
not require you to post a user event back to the control to prevent the generation
of a runtime error.
Because of differences in the behavior of individual servers, this event is not
triggered consistently across all server applications. Using Microsoft Word 97
or Excel 97, the SaveObject event is triggered when the DisplayType property
of the control is set to DisplayAsActiveXDocument! or DisplayAsIcon!, but
not when it is set to DisplayAsContent!. For other applications, such as Paint
Shop Pro 4, the event is triggered when the display type is DisplayAsContent!
but not when it is DisplayAsActiveXDocument!.
Because some servers may also fire the PowerBuilder Save event and the
relative timing of the two events cannot be guaranteed, your program should
only handle the SaveObject event.
Examples In this example, when the user or the server application saves a Word document
in an OLE control, the data is saved as a blob in a file. The file can then be
opened as a Word document:
blob l_myobjectdata
l_myobjectdata = this.objectdata
integer l_file

l_file = FileOpen("c:\myfile.doc", StreamMode!, Write!)

FileWrite( l_file, l_myobjectdata )
FileClose( l_file )
See also Close
Save

319
Selected

Selected
Description Occurs when the user highlights an item on the menu using the arrow keys or
the mouse, without choosing it to be executed.
Event ID
Event ID Objects
None Menu

Arguments None
Return codes None (do not use a RETURN statement)
Usage You can use the Selected event to display MicroHelp for the menu item. One
way to store the Help text is in the menu item’s Tag property.
Examples This example uses the tag value of the current menu item to display Help text.
The function wf_SetMenuHelp takes the text passed (the tag) and assigns it to
a MultiLineEdit control. A Timer function and the Timer event are used to clear
the Help text.
This code in the Selected event calls the function that sets the text:
w_test.wf_SetMenuHelp(This.Tag)
This code for the wf_SetMenuHelp function sets the text in the MultiLineEdit
mle_menuhelp; its argument is called menuhelpstring:
mle_menuhelp.Text = menuhelpstring
Timer(4)
This code in the Timer event clears the Help text and stops the timer:
w_test.wf_SetMenuHelp("")
Timer(0)
See also Clicked

320
 Chapter 9 PowerScript Events

SelectionChanged
The SelectionChanged event has different arguments for different objects:
Object See
DropDownListBox, Syntax 1
DropDownPictureListBox, ListBox,
PictureListBox controls
Tab control Syntax 2
TreeView control Syntax 3

Syntax 1 For Listboxes

Description Occurs when an item is selected in the control.
Event ID
Event ID Objects
pbm_cbnselchange DropDownListBox, DropDownPictureListBox
pbm_lbnselchange ListBox, PictureListBox

Arguments
Argument Description
index Integer by value (the index of the item that has become
selected)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage For DropDownListBoxes, the SelectionChanged event applies to selections in
the dropdown portion of the control, not the edit box.
The SelectionChanged event occurs when the user clicks on any item in the list,
even if it is the currently selected item. When the user makes a selection using
the mouse, the Clicked (and if applicable the DoubleClicked event) occurs
after the SelectionChanged event.
Examples This example is for the lb_value ListBox in the window
w_graph_sheet_with_list in the PowerBuilder Examples application. When the
user chooses values, they are graphed as series in the graph gr_1 (it is a
MultiSelect ListBox so index doesn’t matter). The script checks all the items
to see if they are selected:

321
SelectionChanged

integer itemcount,i,r
string ls_colname

gr_1.SetRedraw(FALSE)

// Clear out categories, series and data from graph

gr_1.Reset(All!)

// Loop through all selected values and

// create as many series as the user specified
FOR i = 1 to lb_value.TotalItems()
IF lb_value.State(i) = 1 THEN
ls_colname = lb_value.Text(i)

// Call window function to set up the graph

wf_set_a_series(ls_colname, ls_colname, &
lb_category.text(1))
END IF

NEXT

gr_1.SetRedraw(TRUE)
See also Clicked

Syntax 2 For Tab controls

Description Occurs when a tab is selected.
Event ID
Event ID Objects
pbm_tcnselchanged Tab

Arguments
Argument Description
oldindex Integer by value (the index of the tab that was previously
selected)
newindex Integer by value (the index of the tab that has become
selected)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing

322
 Chapter 9 PowerScript Events

Usage The SelectionChanged event occurs when the Tab control is created and the
initial selection is set.
See also Clicked
SelectionChanging

Syntax 3 For TreeView controls

Description Occurs when the item is selected in a TreeView control.
Event ID
Event ID Objects
pbm_tvnselchanged TreeView

Arguments
Argument Description
oldhandle Long by value (the handle of the previously selected item)
newhandle Long by value (the handle of the currently selected item)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The SelectionChanged event occurs after the SelectionChanging event.
Examples This example tracks items in the SelectionChanged event:
TreeViewIteml_tvinew, l_tviold

//get the treeview item that was the old selection

This.GetItem(oldhandle, l_tviold)

//get the treeview item that is currently selected

This.GetItem(newhandle, l_tvinew)

//Display the labels for the two items in sle_get

sle_get.Text = "Selection changed from " &
+ String(l_tviold.Label) + " to " &
+ String(l_tvinew.Label)
See also Clicked
SelectionChanging

323
SelectionChanging

SelectionChanging
The SelectionChanging event has different arguments for different objects:
Object See
Tab control Syntax 1
TreeView control Syntax 2

Syntax 1 For Tab controls

Description Occurs when another tab is about to be selected.
Event ID
Event ID Objects
pbm_tcnselchanging Tab

Arguments
Argument Description
oldindex Integer by value (the index of the currently selected tab)
newindex Integer by value (the index of the tab that is about to be
selected)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Allow the selection to change
1 Prevent the selection from changing
Usage Use the SelectionChanging event to prevent the selection from changing or to
do processing for the newly selected tab page before it becomes visible.
If CreateOnDemand is TRUE and this is the first time the tab page is selected,
then the controls on the page do not exist yet and you can’t refer to them in the
event script.
Examples When the user selects a tab, this code sizes the DataWindow control on the tab
page to match the size of another DataWindow control. The resizing happens
before the tab page becomes visible. This example is from tab_uo in the
w_phone_dir window in the PowerBuilder Examples:
u_tab_dirluo_Tab

luo_Tab = This.Control[newindex]

luo_Tab.dw_dir.Height = dw_list.Height
luo_Tab.dw_dir.Width = dw_list.Width

324
 Chapter 9 PowerScript Events

See also Clicked

SelectionChanged

Syntax 2 For TreeView controls

Description Occurs when the selection is about to change in the TreeView control.
Event ID
Event ID Objects
pbm_tvnselchanging TreeView

Arguments
Argument Description
oldhandle Long by value (the handle of the currently selected item)
newhandle Long by value (the handle of the item that is about to be
selected)

Return codes Long. Return code choices (specify in a RETURN statement):

0 Allow the selection to change
1 Prevent the selection from changing
Usage The SelectionChanging event occurs before the SelectionChanged event.
Examples This example displays the status of changing TreeView items in a
SingleLineEdit:
TreeViewItem l_tvinew, l_tviold

// Get TreeViewItem that was the old selection

This.GetItem(oldhandle, l_tviold)

// Get TreeViewItem that is currently selected

This.GetItem(newhandle, l_tvinew)

//Display the labels for the two items in display

sle_status.Text = "Selection changed from " &
+ String(l_tviold.Label) + " to " &
+ String(l_tvinew.Label)
See also Clicked
SelectionChanged

325
Show

Show
Description Occurs just before the window is displayed.
Event ID
Event ID Objects
pbm_showwindow Window

Arguments
Argument Description
show Boolean by value (whether the window is being shown)
The value is always TRUE.
status Long by value (the status of the window)
Values are:
• 0 — The current window is the only one affected
• 1 — The window’s parent is also being minimized or a
popup window is being hidden
• 3 — The window’s parent is also being displayed or
maximized or a popup window is being shown

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage The Show event occurs when the window is opened.
See also Activate
Hide
Open

326
 Chapter 9 PowerScript Events

Sort
The Sort event has different arguments for different objects:
Object See
ListView control Syntax 1
TreeView control Syntax 2

Syntax 1 For ListView controls

Description Occurs for each comparison when the ListView is being sorted.
Event ID
Event ID Objects
pbm_lvnsort ListView

Arguments
Argument Description
index1 Integer by value (the index of one item being compared
during a sorting operation)
index2 Integer by value (the index of the second item being
compared)
column Integer by value (the number of the column containing the
items being sorted)

Return codes Long. Return code choices (specify in a RETURN statement):

-1 index1 is less than index2
0 index1 is equal to index2
1 index1 is greater than index2
Usage The Sort event allows you to fine-tune the sort order of the items being sorted.
You can examine the properties of each item and tell the Sort function how to
sort them be selecting one of the return codes.
You typically use the Sort event when you want to sort ListView items based
on multiple criteria such as a PictureIndex and Label.
The Sort event occurs if you call the Sort event, or when you call the Sort
function using the UserDefinedSort! argument.
Examples This example sorts ListView items according to PictureIndex and Label sorting
by PictureIndex first then by label:

327
Sort

ListViewItem lvi, lvi2

This.GetItem(index1, lvi)
This.GetItem(index2, lvi2)

IF lvi.PictureIndex > lvi2.PictureIndex THEN

RETURN 1
ELSEIF lvi.PictureIndex < lvi2.PictureIndex THEN
RETURN -1
ELSEIF lvi.label > lvi2.label THEN
RETURN 1
ELSEIF lvi.label < lvi2.label THEN
RETURN -1
ELSE
RETURN 0
END IF

Syntax 2 For TreeView controls

Description Occurs for each comparison when the TreeView is being sorted.
Event ID
Event ID Objects
pbm_tvnsort TreeView

Arguments
Argument Description
handle1 Long by value (the handle of one item being compared
during a sorting operation)
handle2 Long by value (the handle of the second item being
compared)

Return codes Long. Return code choices (specify in a RETURN statement):

-1 handle1 is less than handle2
0 handle1 is equal to handle2
1 handle1 is greater than handle2
Usage The Sort event allows you to fine-tune the sort order of the items being sorted.
You can examine the properties of each item and tell the Sort function how to
sort them be selecting one of the return codes.
You typically use the Sort event when you want to sort TreeView items based
on multiple criteria such as a PictureIndex and Label.

328
 Chapter 9 PowerScript Events

The Sort event occurs if you call the Sort event, or when you call the Sort
function using the UserDefinedSort! argument.
Examples This example sorts TreeView items according to PictureIndex and Label
sorting by PictureIndex first then by label:
TreeViewItem tvi, tvi2

This.GetItem(handle1, tvi)
This.GetItem(handle2, tvi2)

IF tvi.PictureIndex > tvi2.PictureIndex THEN

RETURN 1
ELSEIF tvi.PictureIndex < tvi2.PictureIndex THEN
RETURN -1
ELSEIF tvi.Label > tvi2.Label THEN
RETURN 1
ELSEIF tvi.Label < tvi2.Label THEN
RETURN -1
ELSE
RETURN 0
END IF

329
SystemError

SystemError
Description Occurs when a serious execution time error occurs (such as trying to open a
nonexistent window) if the error is not handled in a TRY-CATCH block.
Event ID
Event ID Objects
None Application

Arguments None
Return codes None (do not use a RETURN statement)
Usage If there is no script for the SystemError event, PowerBuilder displays a
message box with the PowerBuilder error number and error message text.
For information about error messages, see the PowerBuilder User’s Guide.
You can prevent the SystemError event from occuring by handling errors in
TRY-CATCH blocks. Well-designed exception-handling code gives
application users a better chance to recover from error conditions and run the
application without interruption.
For information about exception handling, see Application Techniques.
Previously, for errors involving external objects and DataWindows, you could
handle the error in the ExternalException or Error events and prevent the
SystemError event from occurring. The ExternalException and Error events
are maintained for backward compatibily only.
When a SystemError event occurs, your current script terminates and your
system may become unstable. It is generally not a good idea to continue
running the application, but you can use the SystemError event script to clean
up and disconnect from the DBMS before closing the application.
Examples This statement in the SystemError event halts the application immediately:
HALT CLOSE
See also Error
ExternalException
TRY...CATCH...FINALLY...END TRY

330
 Chapter 9 PowerScript Events

SystemKey
Description Occurs when the insertion point is not in a line edit and the user presses the ALT
key (alone or with another key).
Event ID
Event ID Objects
pbm_syskeydown Window

Arguments
Argument Description
key KeyCode by value
A value of the KeyCode enumerated data type indicating the key that
was pressed, for example, KeyA! or KeyF1!
keyflags UnsignedLong by value (the modifier keys that were pressed with the
key). The only modifier key is:
1 SHIFT key

Return codes Long. Return code choices (specify in a RETURN statement):

0 Continue processing
Usage Pressing the CTRL key prevents the SystemKey event from firing when the ALT
key is pressed.
Examples This example displays the name of the key that was pressed with the ALT key:
string ls_key

CHOOSE CASE key

CASE KeyF1!
ls_key = "F1"
CASE KeyA!
ls_key = "A"
CASE KeyF2!
ls_key = "F2"
END CHOOSE
This example causes a beep if the user presses ALT+SHIFT+F1.
IF keyflags = 1 THEN
IF key = KeyF1 THEN
Beep(1)
END IF
END IF
See also Key

331
Timer

Timer
Description Occurs when a specified number of seconds elapses after the Start or Timer
function has been called.
Event ID
Event ID Objects
pbm_timer Timing or Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Examples These examples show how to use a timing object’s Timer event and a window’s
Timer event.
Using a timing object This example uses a timing object to refresh a list of
customers retrieved from a database at specified intervals. The main window
of the application, w_main, contains a DataWindow control displaying a list of
customers and two buttons, Start Timer and Retrieve. The window’s Open even
connects to the database:
CONNECT using SQLCA;

IF sqlca.sqlcode <> 0 THEN

MessageBox("Database Connection", &
sqlca.sqlerrtext)
END IF
The following code in the clicked event of the Start Timer button creates an
instance of a timing object, nvo_timer, and opens a response window to obtain
a timing interval. Then it starts the timer with the specified interval:
MyTimer = CREATE nvo_timer
open(w_interval)
MyTimer.Start(d_interval)

MessageBox("Timer", "Timer Started. Interval is " &

+ string(MyTimer.interval) + " seconds")
In the timing object’s Constructor event, the following code creates an instance
of a datastore:
ds_datastore = CREATE datastore

332
 Chapter 9 PowerScript Events

The timing object’s Timer event calls an object-level function that refreshes the
datastore:
refresh_custlist()
Here’s refresh_custlist():
long ll_rowcount

ds_datastore.dataobject = "d_customers"
ds_datastore.SetTransObject (SQLCA)
ll_rowcount = ds_datastore.Retrieve()

RETURN ll_rowcount
The Retrieve button on w_main simply shares the data from the DataStore with
the DataWindow control:
ds_datastore.ShareData(dw_1)
Using a window object This example causes the current time to be
displayed in a StaticText control in a window. Calling Timer in the window’s
Open event script starts the timer. The script for the Timer event refreshes the
displayed time.
In the window’s Open event script, this code displays the time initially and
starts the timer:
st_time.Text = String(Now(), "hh:mm")
Timer(60)
In the window’s Timer event, which is triggered every minute, this code
displays the current time in the StaticText st_time:
st_time.Text = String(Now(), "hh:mm")

333
ToolbarMoved

ToolbarMoved
Description Occurs in an MDI frame window when the user moves any FrameBar or
SheetBar.
Event ID
Event ID Objects
pbm_tbnmoved Window

Arguments None
Return codes Long. Return code choices (specify in a RETURN statement):
0 Continue processing
Usage The event is not triggered for sheet windows.
To get information about the toolbars’ positions, call the GetToolbar and
GetToolbarPos functions.
This event occurs when you change a toolbar’s position with SetToolbarPos.

334
 Chapter 9 PowerScript Events

ViewChange
Description Occurs when the server application notifies the control that the view shown to
the user has changed.
Event ID
Event ID Objects
pbm_omnviewchange OLE

Arguments None
Return codes Long. Return code: Ignored
Usage If you want to retrieve the ObjectData blob value of an OLE control during the
processing of this event, you must post a user event back to the control or you
will generate a runtime error.
See also DataChange
PropertyRequestEdit
PropertyChanged
Rename

335
ViewChange

336
Index

Symbols Adaptive Server Enterprise 1177

AddCategory function 342
! (enumerated value) 33
AddColumn function 344
& see ampersand
AddData function 345
* (multiplication) 70
AddItem function 348
+ (addition) 70
addition operator 70
++, += (assignment shortcuts) 125
AddLargePicture function 353
/ (division) 70
AddPicture function 354
// (comments) 4
address keyword 1209
/= (assignment shortcut) 125
address, mail 763, 774, 776
; (SQL) 18
AddSeries function 355
< (less than) 72
AddSmallPicture function 357
<= (less than or equal) 72
AddStatePicture function 358
= (assignment) 43
AllowEdit property 1022
= (relational) 72
ampersand (&) 18
> (greater than) 72
ancestor
>= (greater than or equal) 72
calling function or event 117
? (dynamic SQL) 183, 185, 188
hierarchy 385
^ (exponentiation) 70
objects 87
_Is_A function 702
return values from events 117
_Narrow function 805
script, calling 127
- see dashes
AncestorReturnValue variable 117
-- (assignment shortcut) 125
AND operator 72
~ see tilde
angle
’ see quotes
calculating arccosine 339
calculating arcsine 362
calculating arctangent 363
A calculating cosine 426
calculating sine 1141
Abs function 338 calculating tangent 1182
absolute value 338 converting to/from radians 870
access levels ANSI, string conversion 529, 530, 1190, 1196
functions 61 Any data type 29
group label 47 API and database handles 449
variables 45 application
ACos function 339 closing DDE channel 396
Activate event 197 connecting to 409, 411, 413, 416
Activate function 340 elapsed time 427
active sheet 831 exporting object as syntax 742
active window 874 handle 537, 638

Index-1
Index

listing objects 738 passing as arguments 109

posting messages 885 stream 941, 1237
recreating objects from syntax 744 variable-size 54
restarting 972 arrow pointer 1089
retrieving arguments 405 Asc function 361
running 987 ASCII values
server 1157, 1165 converting characters to 361
terminating 142 of nonprinting characters 922
yielding to 1239 ASin function 362
application name 1155, 1157, 1165 assignment
Application objects, SetTransPool function 1125 arrays 53, 56, 58
Arabic functions overflow 77
IsAllArabic 704 shortcut operators 125
IsAnyArabic 706 statements 124
IsArabic 708 asterisk in text patterns 784
IsArabicAndNumbers 709 ATan function 363
arccosine 339 AttachmentFile property 773
arcsine 362 audio (beep) 364
arctangent 363 AutoCommit 1177
arguments Autoinstantiate setting 89
command line 405 automation 1043, 1045, 1047
for events 194 axis, graphs
functions and events 108 categories 342, 376, 452, 667
hot link 1155, 1163 inserting data 671
server application 1157, 1165
arithmetic operators 70
Arrange function 359
ArrangeOpen enumerated data type 831 B
ArrangeSheets function 360 back quote 127
ArrangeTypes enumerated data type 360 background color, graphs
array functions data points 568, 1060
LowerBound 762 series 617, 1104
UpperBound 1227 background layer of DataWindow 1091
arraylists 58 backslash in text patterns 783
arrays backspace, specifying 9
about 50 bands, DataWindow, moving objects to 1091
assigning values 56, 58, 124 BAT file 987
chars and strings 79 batch applications 886
copying 124 beam pointer 1089
default values 53 Beep function 364
errors 59 BeginDrag event 198
example 361 BeginLabelEdit event 201
initializing 58 BeginRightDrag event 203
input parameter for dynamic SQL 1067 BeginTransaction function 365
mailRecipient 763 birth dates 1238
message ID 765

Index-2
 Index

bitmaps cancellation
assigning to picture control 1088 allowing 1239
in rich text 692 of edits 1222
printing 901 of pipeline object 374
retrieving from clipboard 389 of printing 902
blob data type 24 CanUndo function 375
Blob function 367 capitalization
blob functions in category names 342, 667
Blob 367 in series names 355
BlobEdit 368 lowercase 761
BlobMid 369 uppercase 1226
Len 732 caret in text patterns 783
BlobEdit function 368 carriage return
BlobMid function 369 in INI files 936
blobs specifying 9
assigning to picture control 1088 cascaded windows, arranging sheets 360
converting to string 367, 1166 cascading opened windows 831
declaring 40 case sensitivity, comparisons 72
extracting values from 439, 444, 451, 695, 754, categories, graphs
943, 1185 adding data values to series 342, 345
inserting data into 368 adding to a series 342
reading streams into 941 clicked 809
selecting from database 172 counting 376
updating 175 deleting 452, 963
writing to stream 1237 identifying 376, 377
boolean data type 24 importing data 646, 648, 651
border InsertCategory function 342
determining distance from 872, 873 inserting 667
printing 914, 917, 919 new 342
bottom layer of DataWindow 1091 CategoryCount function 376
bound 762, 1227 CategoryName function 377
brackets in text patterns 784 Ceiling function 378
BuildModel function 371 century 1238
ChangeDirectory function 379
ChangeMenu function 380
channel, DDE 396, 829
C char data type
C functions about 24
decoding returned values 698, 699 array 79
passing values to 754 converting to string 78
CALL statement Char function 381
about 127 character array 1237
not using 194 characters
Cancel button 790 array 941
Cancel function 374 changing capitalization 761, 1226
converting to ASCII values 361

Index-3
Index

extracting 381, 792 windows 392

mask 1080 code
matching 783 generating DataWindow 1176
returning rightmost 979 object 742
selected 1013, 1016 reusing 887
selecting 1026 cold link 489, 613, 829, 1100
Check function 382 CollapseItem function 404
Checked property 1220 colors
child windows and edit masks 1080
obtaining parent 863 data point 568, 966, 1060
opening 816, 854 red, green, and blue components of 977
CHOOSE CASE statement 128 series 616, 1104
ChooseColor function 383 supported 583
class table of standard colors 977
contrasted with object 84 ColumnClick event 216
of object 385 columns
OLE 669 determining insertion point position 880
class hierarchy 32 in list 670
class user objects 85 pasting text into 865
ClassDefinition objects, FindMatchingFunction 523 COM file 987
ClassList function 384 command line, retrieving arguments 405
ClassName function 385 CommandParm function 405
Clear function 387 commands
clearing text 387 getting from DDE client 548
Clicked event 206, 810 receiving form DDE application 971
clipboard comments
contents as replacement text 961 in library 736
copying 422 using 4
cutting 434 COMMIT statement 157
importing data from 646 CommitTransaction function 407
pasting and linking 867 comparing
pasting from 865 numbers 694, 786, 795
retrieving and replacing contents 389 comparing strings 72
Clipboard function 389 computer
CLOSE Cursor statement 155 beeping 364
Close event 212, 392, 972 reporting CPU time 427
Close function 392 concatenation operator 74
CLOSE Procedure statement 156 condensed mode 922
CloseChannel function 396 configuration settings
CloseQuery event 214, 392 reading 934, 936
CloseTab function 397 saving 1093
CloseUserObject function 399 CONNECT statement 158
CloseWithReturn function 401 Connection objects
closing ConnectToServer function 419
DDE channel 396 CreateInstance function 431
print job 904 DisconnectServer function 477

Index-4
 Index

ConnectionBegin event 218 coordinates

ConnectionEnd event 219 ListView items 606
connections, to OLE object 409, 411 of print cursor 932, 933
ConnectToNewObject function 409 of print objects 901, 910, 914, 917, 919
ConnectToNewRemoteObject function 411 Copy function 422
ConnectToServer function 419 copying
constants importing from clipboard 646
assigning values 43 to clipboard 422
declaring 49 CopyRTF function 424
where to declare 36 CORBACurrent, initializing 655
Constructor event 220 Cos function 426
ContextInformation objects cosine 426
GetCompanyName function 551 count, of data points in a series 436
GetFixesVersion function 589 CPU
GetHostObject function 593 getting information about 583
GetMajorVersion function 600 time 427
GetMinorVersion function 602 Cpu function 427
GetName function 603 CREATE statement 131, 874
GetShortName function 624 CreateDirectory function 428
GetVersionName function 637 CreateInstance function 431
ContextKeyword objects, GetContextKeywords CreatePage function 433
function 552 cross mouse pointer 1089
context-sensitive Help 1135 crosstabs, creating from source code 1176
continuation character 18 current
CONTINUE statement 130 row and scrolling 1002, 1004
continuous line style sheet 831
setting for data points 1062 cursor
setting for series 1106 custom 1089
Control array 845, 847 displaying popup menus 874
control structures print 896
CHOOSE CASE 128 cursors, database
DO...LOOP 135 closing 155
FOR...NEXT 139 declaring 154, 159
IF...THEN 143 opening 168
controls custom class user objects 88
determining type 1218 Cut function 434
dragging 480 cutting, to clipboard 434
focus of 590, 1070
hiding 640, 802
moving 802
obtaining handle 638 D
redrawing 1098 dash line style
referencing 402 about 1062, 1106
resizing 968 setting for series 1106
yielding 1239 dashes, prohibiting in variable names 6
DashesInIdentifiers option 6

Index-5
Index

data Time 1185

adding to a graph series 345, 346 data type mappings, EAServer 34
clearing 962 data types
converting to type long 754 about 24
correcting pipeline 958 assignment 77
finding in DataWindow 511 blob 367
from OLE server 561 date 442
getting DDE 564 determining 385
importing 646 effect of operators 76
inserting into a blob 368 enumerated 33
obtaining from control 559 external functions 64
receiving from DDE application 971 literals 24, 25, 26, 28, 77
sending to DDE client 1056 mismatch when pasting 865
sharing 437 numeric 76
to OLE server 1054 promotion 76
transferring 1148 promotion for function arguments 106
writing to file 508 real 943
writing to stream 1237 setting to NULL 1084
data expressions standard 24
Any data type 31 string 1166
Data Pipeline painter 374, 1149 system object 32
data points time 1185
adding to a scatter graph 346 unknown 29
clicked 809 windows 814
deleting 452 database stored procedures 151
inserting 671 databases
reporting appearance of 568 canceling changes 169
reporting explosion percent 566 commiting changes 157
resetting colors 966 connecting to 158
setting style 1060 cursor, opening 168
value of 559, 574 deleting rows 162, 163
data type checking and conversion functions disconnecting from 164
Asc 361 fetching rows 166
Char 381 handle 449
Date 439 inserting rows 167
DateTime 443 on restart 972
Dec 451 repairing 958
Double 478 selecting rows 170
Integer 695 transactions 1125
IsDate 712 transferring data between 1148
IsNull 717 updating 174
IsNumber 718 updating cursored row 177
IsTime 721 DataChange event 221
Long 754 DataSource function 437
Real 943 DataWindow control
String 1166 data expressions and Any data type 31

Index-6
 Index

for pipline errors 1149 date, day, and time functions

DataWindow functions Day 445
CanUndo 375 DayName 446
CategoryCount 376 DayNumber 447
CategoryName 377 DaysAfter 448
Clear 387 Hour 641
Clipboard 389 Minute 796
Copy 422 Month 801
Cut 434 Now 808
DataCount 436 RelativeDate 951
FindCategory 513 RelativeTime 952
FindNext 525 Second 1006
FindSeries 526 SecondsAfter 1007
GetData 559 Today 1191
GetDataPieExplode 566 Year 1238
GetDataStyle 568 dates
GetSeriesStyle 616 checking string 712
LineCount 746 converting to 440
ObjectAtPointer 809 DateTime data type 439, 443
Paste 865 day of week 446, 447
PasteRTF 868 determining interval 448
Position 880 getting dynamic 576, 578
ReplaceText 961 in blobs 439
ResetDataColors 966 obtaining current 1191
Scroll 1000 obtaining day of month 445
SelectedLength 1013 DateTime data type 25
SelectedLine 1014 DateTime function 443
SelectedStart 1016 Day function 445
SelectedText 1017 DayName function 446
SelectText 1026 DayNumber function 447
SeriesCount 1036 DaysAfter function 448
SeriesName 1037 dBase file, importing data from 648, 651
SetDataPieExplode 1058 DBHandle function 449
SetDataStyle 1060 DDE channel
SetPosition 1091 closing 396
SetSeriesStyle 1104 requesting data 614
TextLine 1184 DDE client functions
Undo 1222 CloseChannel 396
DataWindow object ExecRemote 489
creating from SELECT statement 1176 GetDataDDE 564
deleting from libraries 737 GetDataDDEOrigin 565
exporting as syntax 742 GetRemote 613
listing 738 OpenChannel 829
recreating from syntax 744 RespondRemote 971
date data type 24 SetRemote 1100
Date function 439 StartHotLink 1155

Index-7
Index

StopHotLink 1163 DeleteStatePictures function 468

DDE server functions descendant
GetCommandDDE 548 determining class of 385
GetCommandDDEOrigin 550 opening user object 837, 838, 846, 847
GetDataDDE 564 opening window 817
GetDataDDEOrigin 565 return values from events 117
RespondRemote 971 DESTROY statement
SetDataDDE 1056 about 134
StartServerDDE 1157 ending a mail session 769
StopServerDDE 1165 DestroyModel function 469
DDL, executing through dynamic SQL 182, 183 Destructor event 226, 397, 399
Deactivate event 222 detail bands, moving objects to 1091
DebugBreak function 450 diagonal fill pattern 1064, 1107
Dec function 451 dialog
decimal data type Insert Object 691
about 25 Open File 584
converting to 451 PasteSpecial 869
declaring 40 Save File 586
declarations diamond fill pattern 1064, 1108
access levels 45 dimension 762
arrays 50 dimension of array 1227
constants 49 directory, of library 738, 740
expressions as initial values 43 DirectoryExists function 470
syntax 39 DirList function 471
variables 36 DirSelect function 473
where to declare 36 Disable function 474
DECLARE Cursor statement 159 DisableCommit function 475
DECLARE Procedure statement 160 DISCONNECT statement 164
definition, font for printing 906 DisconnectObject function 476
DELETE statement 162 DisconnectServer function 477
DELETE Where Current of Cursor statement 163 display format, applying to string 1166
DeleteAllItems event 223 distributed applications
DeleteCategory function 452 ConnectToServer function 419
DeleteColumn function 453 DisconnectServer function 477
DeleteColumns function 454 Listen function 750
DeleteData function 455 SharedObjectDirectory function 1127
DeleteItem event 224 SharedObjectGet function 1128
DeleteItem function 456 SharedObjectRegister function 1131, 1132
DeleteLargePicture function 460 StopListening function 1164
DeleteLargePictures function 461 division 797
DeletePicture function 462 division operator 70, 71
DeletePictures function 463 DLL files
DeleteSeries function 464 executing functions from 66
DeleteSmallPicture function 465 DLLs for external functions 62
DeleteSmallPictures function 466 DO...LOOP statement 135
DeleteStatePicture function 467 document windows 831

Index-8
 Index

dollar sign in text patterns 783 Print 894

dot notation Resize 968
about 38 Show 1133
instance variables 38 TypeOf 1218
structures 82 DropDownListBox control, deleting text 387
dotted line style DropDownListBox functions
setting for data points 1062 AddItem 348
setting for series 1106 Clear 387
double colon 127 Copy 422
double data type 25 Cut 434
Double function 478 DeleteItem 456
DoubleClicked event 227 DirList 471
DoubleParm property 834, 841, 843, 850, 852 DirSelect 473
DoVerb function 479 DraggedObject 482
Drag function 480 FindItem 517
DragDrop event 232 InsertItem 677
DragEnter event 236 Paste 865
DraggedObject function 482 Position 880
dragging, TreeView items 1066 Post 885
DragLeave event 237 ReplaceText 961
DragObject functions Reset 962
ClassName 385 SelectedLength 1013
Drag 480 SelectedStart 1016
Hide 640 SelectedText 1017
Move 802 SelectItem 1020
PointerX 872 SelectText 1026
PointerY 873 Text 1183
PostEvent 886 TotalItems 1194
Print 894 DropDownPictureListBox functions
Resize 968 AddItem 349
SetFocus 1070 AddPicture 354
SetPosition 1090 Clear 387
SetRedraw 1098 Copy 422
Show 1133 Cut 434
TriggerEvent 1209 DeletePicture 462
TypeOf 1218 DeletePictures 463
DragWithin event 239 FindItem 517
Draw function 483 InsertItem 678
drawing objects Paste 865
and SetFocus function 1070 Position 880
posting events 886 ReplaceText 961
setting color of 977 SelectedLength 1013
DrawObject functions SelectedStart 1016
ClassName 385 SelectedText 1017
Hide 640 SelectItem 1020
Move 802 SelectText 1026

Index-9
Index

Text 1183 EditMask functions

TotalItems 1194 CanUndo 375
DWObjects, OLE functions 340, 422, 479, 1224 Clear 387
dynamic libraries 1078 Copy 422
dynamic library (DLL) 1155 Cut 434
dynamic SQL GetData 560
about 178 LineCount 746
considerations 180 LineLength 747
DynamicDescriptionArea 179 Paste 865
DynamicStagingArea 179 Position 880
Format 1 182 ReplaceText 961
Format 2 183 Scroll 1000
Format 3 185 SelectedLength 1013
Format 4 188 SelectedLine 1014
formats listed 178 SelectedStart 1016
NULL values 183, 185 SelectedText 1017
ordering statements 180 SelectText 1026
preparing DynamicStagingArea 180 SetMask 1080
statements 178 TextLine 1184
dynamic SQL functions Undo 1222
GetDynamicDate 576 embedded SQL 151
GetDynamicDateTime 578 Enable function 486
GetDynamicNumber 580 EnableCommit function 487
GetDynamicString 581 Enabled property 640, 1098
GetDynamicTime 582 EndLabelEdit event 242
SetDynamicParm 1067 EntryList function 488
DynamicDescriptionArea enumerated data types 33
about 179 envelope, mail message header 772
properties 189 environment
DynamicStagingArea getting information about 583
about 179 TEMP variable 773
preparing 180 error checking
cascaded calls 112
compiling scripts 102
Error DataWindow 958
E Error event 244
EAServer data type mappings 34 error handling
edit control after SQL statements 153
counting lines in 746 calling functions or events 103, 105
deleting text from 387 error objects, creating 131
determining insertion point position 880 errors
inserting clipboard contents 389 displaying pipeline 1149
replacing text 961 during execution 72
selected text 1013, 1016 escape sequences 922
EditLabel function 429, 484

Index-10
 Index

events F
about 94, 194
Fact function 495
adding to queue 886
FETCH statement 166
ancestor 117
file functions
and hidden objects 640
FileClose 496
and print jobs 904
FileDelete 498
arguments 108, 194
FileExists 499
cascaded calls 111, 114
FileLength 500
defined 94
FileOpen 502
errors when calling 103
FileRead 504
extending 107
FileSeek 507
finding 97
FileWrite 508
overriding 107
GetFileOpenName 584
posting 98, 112, 1180
GetFileSaveName 586
return codes 195
FileClose function 496
return values 111, 195
FileCopy function 497
similarities to functions 95
FileDelete function 498
static and dynamic 100
FileExists event 250
system 94, 194
FileExists function 499
triggering 98, 194, 1181, 1209
FileLength function 500
user-defined 194, 195
FileMove function 501
exclamation point icon 790
FileOpen function 502
exclusive share mode 821, 824
FileRead function 504
ExecRemote function 489
files
executable
importing data from 648
returning application handle 638
linking 749
running 987
security and sharing violation 500
EXECUTE statement 165, 1067
FileSeek function 507
execution errors 102
FileWrite function 508
EXIT statement 138
Fill function
Exp function 492
about 510
ExpandAll function 493
and printing 510
ExpandItem function 494
FillPattern 570, 1063, 1107
exponent 492
filtering filenames 584, 586
exponentiation operator 70
Find function 511
expressions
FindCategory function 513
Any data type 30
FindClassDefinition function 515
checking for NULL 717
FindFunctionDefinition function 516
data type promotion 76
FindItem function 517
data types 76
FindMatchingFunction function 523
DataWindows and Any data type 31
FindNext function 525
in declaration 43
FindSeries function 526
literals 77
FindTypeDefinition function 527
operators and data types 76
flicker 1098
external functions 60
focus
ExternalException event 247
and line length 747

Index-11
Index

finding control with 590 overriding 106

selected text 1013, 1016, 1017, 1026 posting 98, 112
setting 1070 return values 110
folder 738 similarities to events 95
fonts static and dynamic 100
and string length when printing 931 system, defined 95
defining for printing 906 triggering 98
FontFamily enumerated data type 906 type promotion 106
FontPitch enumerated data type 906 user-defined 95
names and sizes 907
setting 924
when printing 897
when printing DataWindow controls 905 G
footer, moving objects to 1091 garbage collection 87, 132, 134
foreground color GarbageCollect function 532
data points 568, 1060 GarbageCollectGetTimeLimit function 533
series 617, 1104 GarbageCollectSetTimeLimit function 534
foreground layer of DataWindow 1091 GetActiveSheet function 535
Form presentation style 1176 GetAlignment function 536
formats, applying to strings 1166 GetApplication function 537
formfeed, specifying 9 GetArgElement function 538
frame window 874, 1235, 1236 GetAutomationNativePointer function 539
FromAnsi function 529 GetCertificateLabel function 541
FromUnicode function 530 GetChildrenList function 544
function object GetColumn function 546
exporting as syntax 742 GetCommandDDE function 548
listing 738 GetCommandDDEOrigin function 550
re-creating from syntax 744 GetCompanyName function 551
functions GetContextKeywords function 552
about 94 GetContextService function 553
access level for external 61 GetCredentialAttribute function 555
ancestor 117 GetCurrentDirectory function 558
arguments 108 GetData function 559
calling global and system 114 GetDataDDE function 564
cascaded calls 111, 114 GetDataDDEOrigin function 565
case sensitivity 114 GetDataPieExplode function 566
chars as arguments 79 GetDataStyle function 568
DLLs 62 GetDataValue function 574
errors when calling 103 GetDynamicDate 189
external 60 GetDynamicDate function 576
external data types 64 GetDynamicDateTime 189
external, defined 95 GetDynamicDateTime function 578
external, mail 768 GetDynamicNumber 189
external, reporting database handle 449 GetDynamicNumber function 580
finding 97 GetDynamicString 189
overloading 106 GetDynamicString function 581

Index-12
 Index

GetDynamicTime 189 AddData 345

GetDynamicTime function 582 AddSeries 355
GetEnvironment function 583 CategoryCount 376
GetFileOpenName function 584 CategoryName 377
GetFileSaveName function 586 Clipboard 390
GetFirstSheet function 588 DataCount 436
GetFixesVersion function 589 DeleteCategory 452
GetFocus event 251 DeleteData 455
GetFocus function 590 DeleteSeries 464
GetFolder function 591 FindCategory 513
GetGlobalProperty function 592 FindSeries 526
GetHostObject function 593 GetData 559
GetItem function 594 GetDataPieExplode 566
GetItemAtPointer function 597 GetDataStyle 568
GetLastReturn function 598 GetSeriesStyle 616
GetLibraryList function 599 ImportClipboard 646
GetMajorVersion function 600 ImportFile 648
GetMinorVersion function 602 ImportString 651
GetName function 603 InsertCategory 667
GetNativePointer function 604 InsertData 671
GetNextSheet function 605 InsertSeries 693
GetOrigin function 606 ModifyData 798
GetParagraphSetting function 607 Reset 962
GetParent function 608 SaveAs 991
GetPin function 610 SeriesCount 1036
GetRecordSet function 612 SeriesName 1037
GetRemote function 613 SetDataPieExplode 1058
GetSeriesStyle function 616 SetDataStyle 1060
GetServerInfo function 623 SetSeriesStyle 1104
GetShortName function 624 graphics, printing 901
GetStatus function 626 graphs
GetToolbar function 630 categories 345
GetToolbarPos function 632, 1119 overlay 621
GetTransactionName function 635 series 355
GetURL function 636 grColorType enumerated data type 568
GetVersionName function 637 grDataType enumerated data type 559, 574
global functions Grid presentation style 1176
calling 114 grObjectType enumerated data type 809
defined 95 Group presentation style 1176
global scope operator 38 grResetType enumerated data type 963
global variables grSymbolType enumerated data type 1108
about 36
scope operator 38
GOTO statement 141
Graph functions H
AddCategory 342 HALT statement 142

Index-13
Index

handle hourglass pointer 1089

database 449 HyperlinkToURL function 642
DDE 396, 829, 1157 hyphens, prohibiting in variable names 6
mailSession object 768, 1034
validating 724
Handle function 638
header band, moving objects to 1091 I
Hebrew functions icons
IsAllHebrew 705 arranging in ListView 359
IsAnyHebrew 707 arranging windows 360
IsHebrew 713 in message box 790
IsHebrewAndNumbers 714 identifier names, rules for 6
height Idle event 255
object 968 IDs for events 194
workspace 1232 IF...THEN statement
Help about 143
calling Winhelp 1135 multiline 144
displaying MicroHelp 1083 single-line 143
Help event 252 image
Help Search window 1135 assigning to picture control 1088
hidden objects 1133 retrieving from clipboard 389
Hide event 253 ImpersonateClient function 645
Hide function 640 ImportClipboard function 646
hierarchies ImportFile function 648
child items in a list 683, 685, 688 importing, data 648, 651
items in TreeView 404, 494 ImportString function 651
sorting 1145 inbox
sorting children 1143 deleting messages from 765
system 32, 385 downloading messages to 771
high word of long 698 reading mail messages 772
highlighting retrieving message IDs from 765, 766
items in lists 1020, 1159 saving messages in 779
scrolling 1004 IncomingCallList function 653
setting 1112 index
horizontal fill pattern 1064, 1108 highlight state of 1112, 1159
horizontal scrollbar for lists 348 obtaining top 1192
horizontal scrolling, when adding items to lists 348 of listbox item 1011, 1021
host variables in SQL 152 indicator variables in SQL 152
hot link Inet objects
about 1056 GetURL function 636
determining origin of 565 HyperlinkToURL function 642
determining source of data 565 PostURL function 890
establishing 1155 Information icon 790
terminating 1163 inheritance 87
HotLinkAlarm event 254 back quote 127
Hour function 641 double colon 127

Index-14
 Index

PowerBuilder objects 32 converting to 695

INI file converting to char 381
reading 934, 936 obtaining from blob 695
writing values to 1093 integer data type 25
Init function 655, 656 Integer function 695
input fields in rich text 659, 661, 662, 663, 664, 665 Intel 583
InputFieldChangeData function 659 InternetData function 697
InputFieldCurrentName function 661 InternetRequest objects, InternetData function 697
InputFieldDeleteCurrent function 662 interpersonal messages 766
InputFieldGetData function 663 interprocess messages 766
InputFieldInsert function 664 interval 1188
InputFieldLocate function 665 IntHigh function 698
InputFieldSelected event 256 IntLow function 699
Insert Object dialog 691 InvokePBFunction function 700
INSERT statement 167 Is_A ( _Is_A ) function 702
InsertCategory function 667 IsAlive function 703
InsertClass function 669 IsAllArabic function 704
InsertColumn function 670 IsAllHebrew function 705
InsertData function 671 IsAnyArabic function 706
InsertFile function 676 IsAnyHebrew function 707
inserting strings 959 IsArabic function 708
insertion point IsArabicAndNumbers function 709
character position 1010 IsCallerInRole function 710
in editable controls 747 IsDate function 712
in text line 1014, 1184 IsHebrew function 713
when pasting from clipboard 865 IsHebrewAndNumbers function 714
InsertItem event 257 IsImpersonating function 715
InsertItem function 677 IsInTransaction function 716
InsertItemFirst function 683 IsNull function 717
InsertItemLast function 685 IsNumber function 695, 718
InsertItemSort function 688 IsPreview function 719
InsertObject function 691 IsSecurityEnabled function 720
InsertPicture function 692 IsTime function 721
InsertSeries function 693 IsTransactionAborted function 722
instance variables IsValid function
about 36, 37 about 724
class of 385 and Handle function 638
dot notation 38 description 724
initialized 44 getting active sheet 535
instances getting open sheets 588, 605
checking if valid 724 ItemActivate event 258
defined 84 ItemChanging event 260
of user object 836, 840, 845, 849 ItemCollapsed event 261
Int function 694 ItemCollapsing event 262
integer ItemExpanded event 263
combining into long value 754 ItemExpanding event 264

Index-15
Index

ItemPopulate event 265 OLE stream 735

items selected text 1013
adding to lists 348, 677 string or blob 732
deleting from list 456, 962 Length function 735
determining number of selected 1195 LenW function 732, 734
determining total number of 1194 LibDirType enumerated data type 738, 740
highlight state of 1112, 1159 LibExportType enumerated data type 742
index number of 1011 libraries
linking 749 deleting objects from 738, 740
selecting 1020 pasting and linking object from 867
text of 1012, 1183 search path 599, 1078
top 1123, 1192 Library functions
LibraryCreate 736
LibraryDelete 737
LibraryDirectory 738
J LibraryDirectoryEx 740
JaguarORB, initializing 655 LibraryExport 742
LibraryImport 744
LibraryCreate function 736
LibraryDelete function 737
K LibraryDirectory function 738
Key event 266 LibraryDirectoryEx function 740
keyboard LibraryExport function 742
determining key pressed 724 LibraryImport function 744
selecting text 423 limit, numeric 378
KeyCode enumerated data type line spacing
about 724 setting 926
values 725 when printing text 896
KeyDown function 725 LineCount function 746
keywords 13 LineDown event 268
LineLeft event 269
LineLength function 747
LineList function 748
L LineRight event 270
Label presentation style 1176 lines
labels for GOTO 8 and SetFocus function 1070
language for OLE automation 1043, 1047 color for data points 568
LastPos function 728 counting number of 746
Layer enumerated data type 360 determining length 747
Layered window 833 graphs, color for data points 1060
layering opened windows 831 graphs, color for series 617, 1104
layout 905 graphs, style for data points 570, 1062
LeftTrim function 731 graphs, style for series 618, 619, 1106
Len function 732 printing 910, 929
length scrolling 1000
line 747 selected text 1014

Index-16
 Index

spacing in rich text 625 DeleteLargePicture 460

text 1184 DeleteLargePictures 461
width 570 DeleteSmallPicture 465
LineUp event 271 DeleteSmallPictures 466
linking DeleteStatePicture 467
clipboard contents 867, 869 DeleteStatePictures 468
establishing 749 EditLabel 484
LinkTo function 749 FindItem 518, 519
ListBox functions GetColumn 546
AddItem 348 GetItem 595
DeleteItem 456 GetOrigin 606
DirList 471 InsertColumn 670
DirSelect 473 InsertItem 679
FindItem 517 ListView 1193
InsertItem 677 SelectedIndex 1011
Reset 962 SetItem 1072
SelectedIndex 1011 SetOverlayPicture 1085
SelectedItem 1012 Sort 1144
SelectItem 1020 TotalItems 1194
SetState 1112 TotalSelected 1195
SetTop 1123 literals
State 1159 data types of 77
Text 1183 specifying 24, 25, 26, 28
Top 1192 local variables 36
TotalItems 1194 Log function
TotalSelected 1195 about 752
Listen function 750 inverse 751
lists natural logarithm 751
adding items 677 logarithms 751, 753
adding new item 348 logical operators 72
deleting items from 962 LogTen function
horizontal scrollbar 348 about 753
of files in listbox 471 inverse 753
of objects in libraries 738, 740 long data type
sorted 349 about 25
ListView control, columns 1073 converting to 754
ListView functions returning high word 698
AddColumn 344 returning low word 699
AddItem 350, 351 Long function 754
AddLargePicture 353 LongParm
AddSmallPicture 357 posting events 886
AddStatePicture 358 specifying values for 754
Arrange 359 triggering events 1209
DeleteColumn 453 Lookup function 756
DeleteColumns 454 loops
DeleteItem 457 about 135

Index-17
Index

iterative 139 reporting length of 747

leaving 138 setting 1080
skipping current iteration 130 Match function 783
yielding within 1239 Max function 786
LoseFocus event 272, 791 maximum value below a limit 694
low word of long 699 maximum value of two numbers 786
Lower function 761 MDI Client (MDI_1) functions
LowerBound function 762 ClassName 385
lowercase 761 Hide 640
Print 894
Resize 968
SetRedraw 1098
M Show 1133
mail functions TypeOf 1218
mailAddress 763 MDI frame
mailDeleteMessage 765 arranging windows 360
mailGetMessages 766 changing menus 380
mailHandle 768 displaying popup menus 874
mailLogoff 769 getting active 535
mailLogon 770 opening sheets 816, 831, 833
mailReadMessage 772 specifying MicroHelp text 1083
mailRecipientDetails 774 MDI frame functions
mailResolveRecipient 776 ArrangeSheets 360
mailReturnCode 770 GetActiveSheet 535
mailSaveMessage 779 GetFirstSheet 588
mailSend 781 GetNextSheet 605
mailAddress function 763 GetToolbar 630
mailDeleteMessage function 765 GetToolbarPos 632, 1119
mailHandle function 768 OpenSheet 831
mailLogoff function 769 OpenSheetWithParm 833
mailLogon function 770 Print 894
mailLogonOption enumerated data type 770 SetMicroHelp 1083
mailReadMessage function 772 SetToolbar 1117
mailReadOption enumerated data type 773 measurement 1223
mailRecipient structure 776 member, OLE 787, 788, 789
mailRecipientDetails function 774 MemberDelete function 787
mailResolveRecipient function 776 MemberExists function 788
mailReturnCode function 770 MemberRename function 789
mailSaveMessage function 779 memory
mailSend function 781 allocation for arrays 54
main window 802 and variable-sized arrays 1227
MAPI 768 releasing after mail session 769
margins 897, 922, 1087 Menu functions
masks Check 382
applying to strings 1166 ClassName 385
matching 783 Disable 474

Index-18
 Index

Enable 486 obtaining handle 638

PopMenu 874 returned messages 698, 699
Show 1133 RightToLeft version 704, 705, 706, 707, 708, 709,
TriggerEvent 1209 713, 714, 975
TypeOf 1218 Mid function 792
Uncheck 1220 Min function 795
Menu objects minimum value
exporting as syntax 742 above a limit 378
listing 738 of two numbers 795
recreating from syntax 744 Minute function 796
menus miscellaneous functions
changing 380 IsValid 724
Checked property 382 KeyDown 725
creating object 131 MessageBox 871
displaying 874 PixelsToUnits 871
for sheet 831 RGB 977
message ID array 766 SetNull 1084
Message object SetPointer 1089
accessing parameters 854 TypeOf 1218
and TriggerEvent function 1209 UnitsToPixels 1223
close return value 401 Mod function 797
creating 131 Modified event 274
determining type 1220 ModifyData function 798
extracting strings from 1167, 1170 modulus 797
open sheet parameters 833 monitor 583
PowerObjectParm property 401 Month function 801
properties 841, 843, 850, 852 month, obtaining the day of 445
specifying values for 754 More Windows menu item 832
MessageBox function 790, 912 mouse
messages selecting text 423
deleting 765 setting shape of pointer 1089
posting 885 MouseDown event 276
saving 779, 781 MouseMove event 279
sending to a window 1034 MouseUp event 283
metacharacters 783 Move function 802
MicroHelp 1083 Moved event 286
Microsoft Windows multidimensional arrays 52, 56
and DDE 613 MultiLineEdit functions
and timers 1188 CanUndo 375
calling Winhelp 1135 Clear 387
defining fonts for printing 907 Copy 422
displaying Save File response window 586 Cut 434
events and messages in 887 LineCount 746
getting filenames 584 LineLength 747
getting information about 583 Paste 865
message numbers 1034 Position 880

Index-19
Index

ReplaceText 961 random 938, 939

Scroll 1000 returning remainder 797
SelectedLength 1013 rounding 985
SelectedLine 1014 truncating 1214
SelectedStart 1016 numeric functions
SelectedText 1017 Abs 338
SelectText 1026 ACos 339
TextLine 1184 ASin 362
Undo 1222 ATan 363
multiplication operator 70, 71 Ceiling 378
MultiSelect property Cos 426
highlighted state 1112, 1163 Exp 492
selecting items 1011, 1012, 1022 Fact 495
Int 694
Log 751
Max 786
N Min 795
names, rules for 6 Mod 797
naming conventions 42 Pi 870
Narrow ( _Narrow ) function 805 Rand 938
negative numbers 1138 Randomize 939
nested OLE objects 822, 825 Round 985
newline, specifying 9 Sign 1138
NextActivity function 806 Sin 1141
NOT operator 72 Sqrt 1147
Now function 808 Tan 1182
null object references 834, 841, 843, 850, 852, 855, 857 Truncate 1214
NULL values N-Up presentation style 1176
about 11
checking 717
dynamic SQL 185
in boolean expressions 73 O
setting variables to 1084 ObjectAtPointer function 809
testing for 11 objects
numbers about 84
category 377 ancestor 87
checking string 718 assignment 90
comparing 786, 795 changing position 1091
converting char 381, 440, 451 creating instance 131
determining maximum 378 deleting from libraries 737
determining sign of 1138 destroying instance 134
getting dynamic 580 determining class of 385
logarithm of 751, 753 determining type 1218
multiplying by pi 870 garbage collection 87, 134
of day of week 447 general references 14
of lines, counting 746 hiding 640, 802

Index-20
 Index

inserting 669, 676, 691 GetNativePointer 604

instantiating 86 InsertClass 669
linking 749 InsertFile 676
loading 1078 InsertObject 691
moving 802 LinkTo 749
obtaining handle 638 Open 814
parent object 608 Paste 865
passing as arguments 108 PasteLink 867
posting events 886 PasteSpecial 869
recreating 744 ReleaseAutomationPointer 954
redrawing 1098 Save 989
reference handle 84 SaveAs 994, 995
saving OLE 989 SelectObject 1024
selecting 1024 SetAutomationLocale 1043
setting focus 1070 SetData 1054
triggering events 1209 UpdateLinksDialog 1224
under pointer 809 OLECustomControl functions
objects, Connection GetData 561
ConnectToServer function 419 GetNativePointer 604
CreateInstance function 429, 431 ReleaseAutomationPointer 954
DisconnectServer function 477 SetAutomationLocale 1043
objects, shared SetData 1054
SharedObjectDirectory function 1127 OLEObject functions
SharedObjectGet function 1128 ConnectNewToObject 409
SharedObjectRegister function 1131 ConnectToNewRemoteObject 411
SharedObjectUnregister function 1132 ConnectToObject 413
objects, Transport ConnectToRemoteObject 416
Listen function 750 DisconnectObject 476
StopListening function 1164 GetAutomationNativePointer 539
ObjectToString function 812 ReleaseAutomationPointer 953
OffsetPos function 813 SetAutomationPointer 1045
Offsite enumerated data type 340 SetAutomationTimeout 1047
OK button 790 OLEStorage functions
OLE DWObject functions Clear 387
Activate 340 Close 393
Copy 422 MemberDelete 787
DoVerb 479 MemberExists 788
UpdateLinksDialog 1224 MemberRename 789
OLE expressions and Any data type 31 Open 814
OLEControl functions SaveAs 996, 997
Activate 340 OLEStream functions
Clear 387 Close 394
Copy 422 Length 735
Cut 434 Open 814
DoVerb 479 Read 940
GetData 561 Seek 1008

Index-21
Index

Write 1237 PageLeft event 292

OPEN Cursor statement 168 PageRight event 293
Open event 287, 972 PageUp event 294
Open function 814 paging functions
OpenChannel function 829 ScrollNextPage 1001
OpenSheet function 831 ScrollPriorPage 1003
OpenSheetWithParm 833 paragraphs 1087
OpenTab function 836 parameters
OpenTabWithParm function 840 command line 405
OpenUserObject function 845 opening sheets with 833
OpenUserObjectWithParm function 849 opening tab pages with 840
OpenWithParm 854 opening user objects with 837, 838, 846, 847, 849
operating system opening windows with 854
information about 583 specifying for DynamicDescriptionArea 1067
RightToLeft version 704, 705, 706, 707, 708, 709, Parent pronoun 15
713, 714, 975 parent window
operators changing position relative to 802
about 70 obtaining 863
arithmetic 70 of open window 815, 816, 854
assignment shortcuts 124, 125 parentheses in expressions 75
concatenation 74 ParentWindow function 863
effect on data types 76 parsing strings 878
logical 72 password 770
precedence 75 Paste function 865
relational 72 PasteLink function 867
OR operator 72 PasteSpecial function 869
Original window 833 pasting
Other event 290 embedding or linking 869
OutgoingCallList function 859 from clipboard 865, 867
oval path
and SetFocus function 1070 of library file 736
printing 914 OLE storage 816
overflow on assignment 77 returning 584
overlay 621, 1109 saving files 586
overloading functions 106 pattern matching 783
overriding functions 106 PBL file
creating 736
deleting 737
listing contents of 738, 740
P pbm_dwngraphcreate event 1105
page PDB file 817
printing 916 performance
printing borders 914, 917, 919 and Yield function 1239
size 897 Any data type 31
PageCreated function 862 dynamic function and event calls 102
PageDown event 291 period in text patterns 783

Index-22
 Index

Pi function 870 Pipeline functions

Picture functions Cancel 374
ClassName 385 Repair 958
Drag 480 Start 1148
Draw 483 PipeMeter event 297
Hide 640 PipeStart event 298
Move 802 pixels 871, 1223
PointerX 872 PixelsToUnits function 871
PointerY 873 plus sign in text patterns 784
PostEvent 886 point size 906
Print 894 pointer
SetFocus 1070 determining distance from edge 872
SetPicture 1088 distance from top 873
SetPosition 1090 file 507, 508
SetRedraw 1098 read/write 1008
Show 1133 returning object under 809
TriggerEvent 1209 setting shape 1089
TypeOf 1218 PointerX function 872
PictureListBox functions PointerY function 873
AddItem 349 polymorphism for functions and events 100
AddPicture 354 PopMenu function 874
DeletePicture 462 PopulateError function 876
DeletePictures 463 popup windows
FindItem 517 moving 802
InsertItem 678 obtaining parent 863
SelectedItem 1012 opening 816, 854
SelectItem 1020 Pos function 878
SetTop 1123 position
State 1159 changing 802
Text 1183 of insertion point 880
Top 1192 setting for control 1090
TotalItems 1194 Position function 880
TotalSelected 1195 positive numbers 1138
pictures Post function 885
for TreeView items 1076 PostEvent function 886
in listboxes 354 posting functions or events 98
in rich text 692 PostURL function 890
in TreeView controls 354 PowerBuilder units 871, 1223
ListView controls 353, 357, 358 PowerBuilder, data types for external functions 64
overlay in lists 1085 PowerObject base class 32, 84
TreeView controls 358 PowerObject functions
PictureSelected event 295 ClassName 385
pie graphs 566, 1058 GetContextService 553
PIF file 987 GetParent 608
PipeEnd event 296 PowerObjectParm
and CloseWithReturn function 401

Index-23
Index

determining type 1220 PrintOpen function

opening sheets with parameters 834, 841, 843, 850, about 912
852 and message boxes 791
PowerScript statements 124 PrintOval function 914
precedence of numeric data types 76 PrintPage function 916
precedence of operators 75 PrintRect function 917
presentation styles 1176 PrintRoundRect function 919
print cursor PrintScreen function 921
getting coordinates of 932, 933 PrintSend function 922
in print jobs 896 PrintSetFont function 924
Print function 894 PrintSetPrinter function 925
print functions PrintSetSpacing function 926
Print 894 PrintSetup function 927
PrintBitmap 901 PrintSetupPrinter function 928
PrintCancel 902 PrintText function 929
PrintClose 904 PrintWidth function 931
PrintDataWindow 905 PrintX function 932
PrintDefineFont 906 PrintY function 933
PrintOpen 912 private access
PrintOval 914 functions 61
PrintPage 916 variables and constants 45
PrintRect 917 PRIVATEREAD access modifier 45
PrintRoundRect 919 PRIVATEWRITE access modifier 46
PrintScreen 921 processor 583
PrintSend 922 profile files
PrintSetFont 924 reading 934, 936
PrintSetSpacing 926 writing to 1093
PrintSetup 927 ProfileClass objects, RoutineList function 986
PrintText 929 ProfileInt function 934
PrintWidth 931 ProfileLine objects, OutgoingCallList function 859
PrintX 932 ProfileRoutine objects
PrintY 933 IncomingCallList function 653
print job 912 LineList function 748
PrintBitmap function 901 OutgoingCallList function 859
PrintCancel function 902 ProfileString function 936
PrintClose function 904 Profiling functions
PrintDataWindow function 905 BuildModel 371
PrintDefineFont function 906 ClassList 384
printer setup 922 DestroyModel 469
Printer Setup dialog box 927 RoutineList 986
PrintFooter event 299 SetTraceFileName 1124
PrintGetPrinter function 908 SystemRoutine 1179
PrintGetPrinters function 909 pronouns
PrintHeader event 300 about 14
PrintLine function 910 instance variables 39
Parent 15

Index-24
 Index

Super 17 RButtonUp event 305

This 16 Read function 940
properties read-only arguments 108
and GetFocus function 590 real data type 26
font, for printing 906 Real function 943
getting and setting 537 recipient, mail 774
Message object 834 rectangle
setting width and height 968 and SetFocus function 1070
window 815, 817 printing 917, 919
property expressions references
Any data type 31 and CloseWithReturn function 402
PropertyChanged event 301 passing arguments by 108
PropertyRequestEdit event 302 passing parameters 834, 841, 843, 850, 852, 855,
protected access 857
functions 61 Registration database 671
variables and constants 45 RegistryDelete function 944
PROTECTEDREAD access modifier 45 RegistryGet function 945
PROTECTEDWRITE access modifier 46 RegistryKeys function 947
public access RegistrySet function 948
functions 61 RegistryValues function 950
variables and constants 45 relational operators 72
RelativeDate function 951
RelativeTime function 952
ReleaseAutomationNativePointer function 953
Q ReleaseNativePointer function 954
question mark remainder 797
dynamic SQL 183, 185, 188 remote DDE application 971
icon in message box 790 remote procedure calls
in text patterns 784 declaring 67
quoted strings, continuing 18 defined 95
quotes RemoteExec event 306, 548, 1157
nesting 26 RemoteHotLink event 307
rules for 27 RemoteHotLinkStart event 1157
specifying 9 RemoteHotLinkStop event 308, 1157
with tilde 26 RemoteRequest event 309, 1056, 1157
RemoteSend event 310, 565, 1157
RemoteStopConnection function 955
RemoteStopListening function 956
R RemoveDirectory function 957
radians 870 Rename event 311
Rand function 938 Repair function 958
random numbers repairing pipeline, canceling 374
initializing generator 939 Replace function 959
obtaining 938 ReplaceText function 961
Randomize function 939 report view for ListView 595
RButtonDown event 303 reserved words 13

Index-25
Index

Reset function 962 Clear 387

ResetArgElements function 965 Copy 422
ResetDataColors function 966 CopyRTF 424
Resize event 312 Cut 434
Resize function 968 DataSource 437
ResolveInitialReferences function 969 Find 511
RespondRemote function 971 FindNext 525
response windows GetAlignment 536
closing 401 GetParagraphSetting 607
moving 802 GetSpacing 625
Restart function 972 GetTextColor 628
ResumeTransaction function 973 GetTextStyle 629
retry button 790 InputFieldChangeData 659
RETURN statement 145 InputFieldCurrentName 661
return values InputFieldDeleteCurrent 662
about 110 InputFieldGetData 663
event return codes 195 InputFieldInsert 664
from ancestor events 117 InputFieldLocate 665
from mail session 770 InsertPicture 692
TriggerEvent function 1209 IsPreview 719
Reverse function 975 LineCount 746
RevertToSelf function 976 LineLength 747
RGB function 977 Paste 865
rich text PasteRTF 868
alignment 536, 1041 Position 881
and data 437 Preview 892
copying with formatting 424, 868 Print 899
data 659, 661, 662, 663, 664, 665 ReplaceText 961
determining insertion point position 881 SaveDocument 999
editing header and footer 1134 Scroll 1000
find again 525 ScrollNextPage 1001, 1002
finding text 511 ScrollPriorPage 1003
formatting 607, 625, 629, 1087 ScrollPriorRow 1004
line spacing 1111 ScrollToRow 1005
preview 719 SelectedColumn 1010
preview document 719, 892 SelectedLength 1013
printing 899 SelectedLine 1014
save file 999 SelectedPage 1015
selecting 1027 SelectedStart 1016
selecting a line 1031 SelectedText 1017
selecting a word 1032 SelectText 1027
selecting all 1030 SelectTextAll 1030
text color 628, 1113 SelectTextLine 1031
text settings 1114 SelectTextWord 1032
RichTextEdit functions SetAlignment 1041
CanUndo 375 SetParagraphSetting 1087

Index-26
 Index

SetSpacing 1111 screen

SetTextColor 1113 changing position relative to 802
SetTextStyle 1114 display 583
ShowHeadFoot 1134 distance to workspace 1235, 1236
Undo 1222 printing 921
Right function 979 scripts
RightClicked event 313 stopping execution 972
RightDoubleClicked event 316 terminating 145
RightToLeft operating system 975 triggering events 1209
RightToLeft software 704, 705, 706, 707, 708, 709, Scroll function 1000
713, 714 ScrollHorizontal event 791
RightTrim function 980 scrolling
ROLLBACK statement 169 ListBox 1123
RollbackOnly function 981 TreeView 1069
RollbackTransaction function 983 scrolling functions
Round function 985 Scroll 1000
RoutineList function 986 ScrollNextPage 1001
rows ScrollNextRow 1002
correcting pipeline data 958 ScrollPriorPage 1003
determining insertion point position 880 ScrollPriorRow 1004
scrolling 1001, 1002, 1004, 1005 ScrollToRow 1005
rows, database Top 1192
deleting 162, 163 ScrollNextPage function 1001
fetching 166 ScrollNextRow function 1002
inserting 167 ScrollPriorPage function 1003
updating 174 ScrollPriorRow function 1004
updating cursored row 177 ScrollToRow function 1005
RPC see remote procedure calls ScrollVertical event 791
Run function 987 searching, rich text 511, 525
Second function 1006
SecondsAfter function 1007
Seek function 1008
S SeekType enumerated data type 1008
Save As dialog box 992 SELECT statement 170
Save event 318 SELECTBLOB statement 172
Save File response window 586 Selected event 320, 1083
Save function 989 SelectedColumn function 1010
SaveDocument function 999 SelectedIndex function 1011
SaveObject event 319 SelectedItem function 1012
scatter graphs SelectedLength function 1013
adding values to series 346 SelectedLine function 1014
changing data point values 799 SelectedPage function 1015
importing data 646, 648, 649, 651 SelectedStart function 1016
inserting data from strings 652 SelectedText function 1017
obtaining data point values 559 selection, clearing in list 1021
scope operator 114 SelectionChanged event 321

Index-27
Index

SelectionChanging event 324 SetData function 1054

SelectionRange function 1019 SetDataDDE function 1056
SelectItem function 1020 SetDataPieExplode function 1058
SelectObject function 1024 SetDataStyle function 1060
SelectText function SetDropHighlight function 1066
about 1026 SetDynamicParm function 1067
copying to clipboard 423 SetFirstVisible function 1069
SelectTextAll function 1030 SetFocus function 1070
SelectTextLine function 1031 SetGlobalProperty function 1071
SelectTextWord function 1032 SetItem function 1072
Send function 1034 SetLevelPictures function 1076
sender 772 SetLibraryList function 1078
SendMessage function 1034 SetMask function 1080
series, graphs SetMicroHelp function 1083
adding to 355 SetNull function 1084
adding values to 345 SetOverlayPicture function 1085
clicked 809 SetPicture function 1088
counting 1036 SetPointer function 1089
data points 436, 455, 559, 574, 798, 966 SetPosition function 1090
deleting 464, 963 SetProfileString function 1093
finding number of 526 SetRange function 1095
importing 646, 648, 651 SetRecordSet function 1096
inserting 693 SetRedraw function 1098
inserting data 671 SetRemote function 1100
obtaining name 1037 SetResultSet function 1103
reporting appearance of 616 SetSeriesStyle function 1104
setting style 1104 SetState function 1112
SeriesCount function 1036 SetTimeout function 1115
SeriesName function 1037 SetToolbar function 1117
server application SetTop function 1123
activating 340, 1024 SetTraceFileName function 1124
closing DDE channel 399 SetTransPool function 1125
connecting to 409, 411, 413, 414, 416 setup printer 922
DDE support 830 shade
pasting and linking 867 data points 568, 1060
providing data 613 series 617, 1104
sending data to 1100 shapes
sending to DDE client 1056 mouse pointer 1089
stopping 1165 printing 914, 917, 919
SetAbort function 1038 shared objects
SetAlignment function 1041 about 1129
SetArgElement function 1042 SharedObjectDirectory function 1127
SetAutomationPointer function 1045 SharedObjectGet function 1128
SetAutomationTimeout function 1047 SharedObjectRegister function 1131
SetComplete function 1050 SharedObjectUnregister function 1132
SetConnect function 1053

Index-28
 Index

shared variables Sort function 1143

about 36, 37 sort order
initialized 44 and GetCalc function 638
SharedObjectDirectory function 1127 when inserting items into lists 677
SharedObjectGet function 1128 SortAll function 1145
SharedObjectRegister function 1131 sounds (beep) 364
SharedObjectUnregister function 1132 source database 1148
sharing data 437 Space function 1146
sheets spaces
arranging 360 deleting leading 731
getting active 535 deleting trailing 980
getting first open 588 inserting in a string 1146
getting next open 605 removing from strings 1213
obtaining parent 863 special ASCII characters in strings 9
opening 816, 831, 833 SQL statements
toolbars 630, 632, 1117, 1119 about 152
Show event 326 CLOSE Cursor 155
Show function 1133 CLOSE Procedure 156
ShowHeadFoot function 1134 COMMIT 157
ShowHelp function 1135 CONNECT 158
ShowPopupHelp function 1137 continuing 18
Sign function 1138 DECLARE Procedure 160
SignalError function 1139 DISCONNECT 164
Sin function 1141 error handling 153
sine 1141 EXECUTE 165, 1067
SingleLineEdit functions FETCH 166
CanUndo 375 in pipeline execution 1149
Clear 387 INSERT 167
Copy 422 OPEN 1067
Cut 434 OPEN Cursor 168
Move 802 painting 154
Paste 865 ROLLBACK 169
Position 880 SELECT 170
ReplaceText 961 SELECTBLOB 172
SelectedLength 1013 UPDATE 174
SelectedStart 1016 UPDATE Where Current of Cursor 177
SelectedText 1017 UPDATEBLOB 175
SelectText 1026 SQLCode property 153
Undo 1222 SQLDBCode property 153
size SQLErrText property 153
changing 968 Sqrt function 1147
of screen 583 square fill pattern 1064, 1108
of string or blob 732 square root 1147
Sleep function 1142 Start function
solid fill pattern 1064, 1108 about 1148
Sort event 327 canceling pipeline 374

Index-29
Index

server application 413, 416 Char 381

StartHotLink function 1155 Fill 510
StartServerDDE function 1157 LeftTrim 731
state Len 732
of listbox items 1159 Lower 761
setting highlighted 1112 Match 783
State function 1159 Mid 792
statements, PowerScript Pos 878
assignment 124 Replace 959
CALL 127 Right 979
CHOOSE CASE 128 RightTrim 980
CONTINUE 130 Space 1146
CREATE 131 Trim 1213
DESTROY 134 Upper 1226
DO...LOOP 135 StringParm property 834, 841, 843, 850, 852
EXIT 138 strings
FOR...NEXT 139 char arrays 79
GOTO 141 comparing 72
HALT 142 concatenating 74
IF...THEN 143 continuing 18
listed 123 converting 361, 367, 440, 451, 478, 754, 943
RETURN 145 converting to char 78
separating 20 deleting leading spaces 731
StaticText control, inserting clipboard 389 detecting contents 712, 718, 721
stgShareMode enumerated data type 821, 824 determining width for printing 931
Stop function 1162 extracting 381, 792
stop sign icon 790 finding substrings 878
StopHotLink function 1163 getting dynamic 581
StopListening function 1164 importing data from 651
StopServerDDE function 1165 lowercase 761
storages, OLE nested 26
file 994 uppercase 1226
releasing 393 writing to stream 1237
saving 989 StringToObject function 1171
stored procedures structure objects
closing 156 exporting as syntax 742
declaring 154, 160 listing 738
executing 165 recreating from syntax 744
streams, OLE structures
checking 788 about 82
deleting 787 assignment 90
renaming 789 autoinstantiated user objects 89
string data type 26 for return values 401
String function 1166 mailRecipient 776
string functions passing as arguments 109
Asc 361 passing to external functions 65

Index-30
 Index

passing values as 855, 857 Post 885

substorages, OLE ProfileInt 934
checking 788 ProfileString 936
deleting 787 Restart 972
renaming 789 Run 987
saving 994 Send 1034
substrings SetProfileString 1093
extracting 792 ShowHelp 1135
finding 878 SignalError 1139
replacing 959 Yield 1239
subtraction operator 70 SystemError event 330
surrounded by spaces 21, 70 SystemKey event 331
summary, moving objects to 1091 SYSTEMREAD modifier 46
Super pronoun 17 SystemRoutine function 1179
SuspendTransaction function 1174 SYSTEMWRITE modifier 46
symbol types, graphs
data points 570, 1063
series 1107
syntax T
exporting object as 742 tab character, specifying 9
recreating objects from 744 Tab functions
SyntaxFromSQL function 1176 CloseTab 397
system MoveTab 804
date 1191 SelectTab 1025
events 194, 885 TabPostEvent 1180
events, defined 94 TabTriggerEvent 1181
functions 114 tab pages
object classes 84 changing order 804
object data types 32 CreatePage function 433
object hierarchy 32 opening user objects 836, 840
registry 944, 945, 947, 948, 950 PageCreated function 862
time 808 selecting 1025
system and environment functions tables, database, transferring data between databases
Clipboard 389 1148
CommandParm 405 Tabular presentation style 1176
DebugBreak 450 Tag property
FindClassDefinition 515 and GetFocus function 590
FindFunctionDefinition 516 storing MicroHelp text 1083
FindTypeDefinition 527 Tan function 1182
GarbageCollect 532 tangent 1182
GarbageCollectGetTimeLimit 533 target database for pipeline 1148
GarbageCollectSetTimeLimit 534 temporary files 772
GetApplication 537 terminator for string 369
GetEnvironment 583 text
Handle 638 deleting from edit controls 387
PopulateError 876 finding in RichTextEdit 511, 525

Index-31
Index

finding substrings 878 timing object

importing data from string 651 starting 1150
line spacing when printing 896 stopping 1162
metacharacters 783 title of message box 790
MicroHelp 1083 ToAnsi function 1190
obtaining current line 1183, 1184 Today function 1191
of listbox item 1012 ToolbarMoved event 334
of message box 790 toolbars 630, 632, 1117, 1119
on clipboard 389, 423, 434 top
pasting over 865 bringing object to 1133
printing 895, 929 determining distance from 873
replacing 961 moving listbox item to 1123
restoring 1222 moving objects to 1091
save rich text as ASCII 999 Top function 1192
selecting 1013, 1017, 1026 topics
setting color of 977 calling Help 1135
text file ending server application 1165
importing data from 648 starting server application 1157
saving to 991 TotalColumns function 1193
Text function 1183 TotalItems function 1194
Text property 590 TotalSelected function 1195
TextLine function 1184 ToUnicode 1196
This pronoun 16 ToUnicode function 1196
tilde Trace file functions, Open 814
in strings 26 TraceBegin function 1197
rules for 27 TraceClose function 1199
specifying 9 TraceDisableActivity function 1200
time TraceEnableActivity function 1202
checking string 721 TraceEnd function 1204
converting to data type 1185 TraceError function 1205
CPU 427 TraceFile objects
DateTime data type 443 Close function 394
getting dynamic 578, 582 NextActivity function 806
minutes 796 Reset function 963
now 808 TraceOpen function 1206
relative 952 TraceTree objects
seconds 1006, 1007 BuildModel function 371
time data type 28 DestroyModel function 469
Time function 1185 EntryList function 488
Timer event 332 SetTraceFileName function 1124
Timer function 1188 TraceTreeGarbageCollect objects, GetChildrenList
timers, triggering event 1188 function 544
timing functions TraceTreeObject objects, GetChildrenList function
CPU 427 544
Idle 643 TraceTreeRoutine objects, GetChildrenList function
Timer 1188 544

Index-32
 Index

TraceUser function 1208 TrigEvent enumerated data type 886

tracing functions TriggerEvent function 1209
TraceBegin 1197 triggering
TraceClose 1199 events 194
TraceDisableActivity 1200 functions or events 98
TraceEnableActivity 1202 TriggerPBEvent function 1211
TraceEnd 1204 Trim function 1213
TraceError 1205 Truncate function 1214
TraceOpen 1206 TrustVerify function 1215
TraceUser 1208 TypeOf function 1218
trailer, moving objects to 1091
Transaction object functions
DBHandle 449
SyntaxFromSQL 1176 U
Transaction objects, creating 131 Uncheck function 1220
transparent line style, graphs Undo function 1222
setting for data points 1062 Undo, testing 375
setting for series 1106 Unicode, string conversion 529, 530, 1190, 1196
Transport objects Uniform Data Transfer 561, 1054
Listen function 750 units
StopListening function 1164 converting from pixels 871
TreeView functions converting to pixels 1223
AddPicture 354 distance from edge 872
CollapseItem 404 UnitsToPixels function 1223
DeleteItem 458 unread messages 766
DeletePicture 462 unsigned integer data type 28
DeletePictures 463 unsigned long data type 28
DeleteStatePicture 467 UPDATE statement 174
DeleteStatePictures 468 UPDATE Where Current of Cursor statement 177
EditLabel 485 UPDATEBLOB statement 175
ExpandAll 493 Upper function 1226
ExpandItem 494 UpperBound function 1227
FindItem 521 uppercase 1226
GetItem 596 user events
InsertItem 681 defined 94
InsertItemFirst 683 pbm_dwngraphcreate 1105
InsertItemLast 685 user ID 770
InsertItemSort 688 user name 776
SelectItem 1023 user objects
SetDropHighlight 1066 about 85
SetFirstVisible 1069 autoinstantiated 89
SetItem 1074 closing 399
SetLevelPictures 1076 closing tab page 397
SetOverlayPicture 1085 creating 131
Sort 1143 creating dynamically 132
SortAll 1145 exporting as syntax 742

Index-33
Index

listing 738 Visible property

opening 836, 837, 838, 845, 846, 847, 849 and SetRedraw function 1098
pipeline 1148 displaying popup menus 874
re-creating from syntax 744 setting 1133
tab pages 836, 840 visual user objects 85
used like structures 88
user-defined events 194, 195

W
warm link 489, 614, 829, 1101
V week, day of 446, 447
value, passing arguments by 108 Which function 1229
values white space 21
adding to lists 348 width
checking for NULL 717 data point’s line 1062
data points 574 series line 1106
deleting from list 456 setting 968
detecting numeric 718 string 931
inserting into lists 677 workspace 1234
variables Window ActiveX controls
access levels 45 GetArgElement function 538
assigning literals 24, 25, 26, 28 GetLastReturn function 598
assigning values 43 InvokePBFunction function 700
checking for NULL 717 ResetArgElements function 965
data type 41 SetArgElement function 1042
declaring 36 TriggerPBEvent function 1211
declaring initial values 42 Window functions
default values 42 ArrangeSheets 360
determining data type of 385 ChangeMenu 380
extracting data from a blob 369 ClassName 385
host 152 CloseUserObject 399
indicator 152 Draw 483
initializing with expression 43 GetActiveSheet 535
inserting data into a blob 368 GetFirstSheet 588
names 42 GetNextSheet 605
OLEObject 414 Hide 640
referencing in SQL 152 Move 802
search order 37 Open 814
setting to NULL 11, 1084 OpenSheet 831
validating 725 OpenSheetWith Parm 833
where to declare 36 OpenTab 836
variable-size arrays, memory allocation 54, 1227 OpenUserObject 845
vertical fill pattern 1064, 1108 OpenWith Parm 854
video monitor 583 ParentWindow 863
ViewChange event 335 PointerX 872
PointerY 873

Index-34
 Index

PostEvent 886 WorkSpaceY function 1236

print 894 Write function 1237
Resize 968 Writes 1237
SetFocus 1070
SetMicroHelp 1083
SetPosition 1090
SetRedraw 1098 X
Show 1133 x value
TriggerEvent 1209 data point 559, 574, 799
TypeOf 1218 importing data 646, 648, 649, 651
WorkSpaceHeight 1232 inserting from strings 652
WorkSpaceWidth 1234 xValue enumerated data type 559, 574
WorkSpaceX 1235
WorkSpaceY 1236
Window objects
closing user objects 399 Y
exporting as syntax 742 y value
listing 738, 740 data point 559, 574, 799
recreating from syntax 744 importing data 646, 648, 649, 651
Window painter 845, 847 inserting from strings 652
windows Year function 1238
adding user objects 836, 845, 849 year, about 442
arranging 360, 831 Yield function 1239
changing menus 380 yValue enumerated data type 559, 574
closing 392
custom frames 1235, 1236
data type of 814
DDE conversation handle 1157 Z
getting active 535 zero, determining 1138
obtaining handle 638
obtaining workspace height 1232
obtaining workspace width 1234
opening 814, 854
posting messages 885
setting position of 1090
WordCap function 1231
WordParm field
and TriggerEvent function 1209
posting events 886
workspace
distance to screen 1235, 1236
obtaining height of 1232
obtaining width 1234
WorkSpaceHeight function 1232
WorkSpaceWidth function 1234
WorkSpaceX function 1235

Index-35