Powerbuilder®: Powerbuilder Apis and Interfaces

PowerBuilder APIs and Interfaces
PowerBuilder®
Version 6.0
DC00000-01-
00000-
00
October
1997
Copyright © 1991-1997 by Sybase, Inc. All rights reserved.
This publication pertains to Sybase 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 trademarks can be viewed at the Sybase trademarks page at http://www.sybase.com/detail?id=1011207. Sybase and the marks listed
are trademarks of Sybase, Inc. ® indicates registration in the United States of America.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.
All other company and product names mentioned may be trademarks of the respective companies with which they are associated.
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., One Sybase Drive, Dublin, CA 94568.
About This Book
Subject This book describes two PowerBuilder interfaces that tool vendors can use
to integrate their applications with PowerBuilder. The interfaces are:
♦ PowerBuilder Test A set of OLE interfaces that allow an external
program to examine the properties of PowerBuilder applications,
DataWindow objects, and RichTextEdit controls
♦ PBSCC A set of standard functions that PowerBuilder calls in a
DLL implemented by a source control vendor
The book provides the information needed to write programs that work
with PowerBuilder in these areas.
Audience This book is for tool vendors who are developing applications that work
with PowerBuilder. The information provided is not needed to develop
PowerBuilder applications.
Test tool vendors can use PowerBuilder Test to look inside a
PowerBuilder application and examine the values of object properties.
Source control vendors can use the SCC specification and the information
in this book about its PowerBuilder implementation to write source
control provider DLLs. Source control systems that implement this
standard automatically make their source control systems accessible to
PowerBuilder users, as well as any other development environment that
uses the SCC specification.
iii
CH A PTE R 1 PowerBuilder Test OLE
Interfaces
About this chapter This chapter describes the PowerBuilder Test OLE interfaces with
reference documentation for the properties and methods. Visual Basic
code examples show how to use the OLE interfaces in a program.
FOR INFO Since some of the methods are similar to PowerBuilder
functions, you can get more information about how to use the functions
in the PowerScript Reference.
Contents
Topic Page
Using the PowerBuilder Test interfaces 1
PowerBuilder.Test 7
PowerBuilder.Test_DW 12
PowerBuilder.Test_RTE 21
Using the PowerBuilder Test interfaces

PowerBuilder Test implements three OLE interfaces:
♦ PowerBuilder.Test for getting version information and general
object information
♦ PowerBuilder.Test_DW for testing DataWindow objects
♦ PowerBuilder.Test_RTE for testing RichTextEdit controls and
DataWindow objects
Constraints You must use a tool other than PowerBuilder to program for this interface.
1
Because of the design of OLE, you can’t reliably connect to the PowerBuilder
Test interface from another PowerBuilder program. There is no way to specify
which application you will connect to. The system connects to the first instance
of the interface it finds, which may well be your test application instead of the
application being tested. PowerBuilder provides other techniques for
communicating information between PowerBuilder programs.
You can use any other programming tool that lets you connect to an OLE
interface. The examples in this introduction are in Visual Basic.
Global variable An object variable belongs in the global variable section:

Dim MainObj As Object
Connecting to an To use an interface, you must connect to it. In Visual Basic, call the
interface CreateObject function:
Set MainObj = CreateObject("PowerBuilder.Test")
If MainObj Is Nothing Then
MsgBox "could not create 'Test' server"
Exit Sub
End If
To connect to the RichTextEdit or DataWindow interface, specify the name of

that interface in the CreateObject function:
Dim DWObj As Object
Set MainObj = CreateObject("PowerBuilder.Test_DW")
Dim RTEObj As Object
Set RTEObj = CreateObject("PowerBuilder.Test_RTE")
In other development environments, call the function that connects to an OLE

interface.
Which interfaces do The three PowerBuilder Test interfaces are independent. You can connect to
you need? any interface that is installed in the system registry and use its functionality
without connecting to another.
However, if you don’t want to register the RichTextEdit or DataWindow
interfaces, you can use the PowerBuilder Test function ObjectFactory to
connect to an unregistered interface.
The first call to ObjectFactory uses the class ID for the Test_DW interface:
Dim MainObj As Object
Dim bRet As Boolean
Dim TestObj As Object
2
Chapter 1 PowerBuilder Test OLE Interfaces
Set MainObj = CreateObject("PowerBuilder.Test")

bRet = MainObj.ObjectFactory(0, "{9537EB52-52CC-11d0-
9945-080009AC61A9}", TestObj)
This call to ObjectFactory uses the programmatic identifier for the interface:
bRet = MainObj.ObjectFactory(0,
"PowerBuilder.Test_DW", TestObj)
Getting version When you connect to the PowerBuilder.Test interface, you can find out the
information PowerBuilder version of the program being tested.
To get the full version number as a float, query the Version property. In this
code, Text1 is a textbox:
Dim VerFloat As Single
Dim Success As Boolean
VerFloat = MainObj.Version
Text1 = "Version " + Str$(VerFloat)
Text1 would hold the value "Version 6.0".

To get various version details, call the VersionDetails method:
Dim Success As Boolean
Success = MainObj.VersionDetails(Major, Minor, Maint,
Build, Flags)
Text1 = "Major=" + Str$(Major) + ", Minor=" +
Str$(Minor) + ", Maint=" + Str$(Maint) + " Build=" +
Str$(Build)
Getting window To access a PowerBuilder object, you need its system handle. On Windows NT
handles and Windows 95, you call the external functions FindWindow and
FindWindowEx. The declarations for Windows NT look like this:
Declare Function FindWindow Lib "USER32"
Alias "FindWindowA"
(ByVal lpClassName As Any,
ByVal lpWindowName As Any)
As Long
Declare Function FindWindowEx Lib "USER32"

Alias "FindWindowExA"
(ByVal hwndParent As Long,
ByVal hwndStartingChild As Long,
ByVal lpClassName As Any,
ByVal lpWindowName As Any)
3
As Long
You may have to traverse a hierarchy of windows to get the one you want. This
sample code finds the MDI frame, then the client area, and then the sheet to get
the DataWindow control on the sheet. Each FindWindow call uses the handle
from the previous one. The handle for the DataWindow is stored in the
efSource text box as hexadecimal string. Text1 and Text2 are also textboxes:
Dim hwndDW As Long
Dim hwndFrameTop As Long
Dim hwndFrame As Long
Const lpDWClassName = "pbdw60"

Const lpMDIClassName = "MDIClient"
Const lpFrameClassName = "FNWND360"
hwndFrameTop = FindWindow(lpFrameClassName, 0&)

hwndFrame = FindWindowEx(hwndFrameTop, 0&,
lpMDIClassName, 0&)
hwndFrame = FindWindowEx(hwndFrame, 0&,
lpFrameClassName, 0&)
hwndDW = FindWindowEx(hwndFrame, 0, lpDWClassName, 0&)
efSource = "&H" + Hex(hwndDW) + "&"

Text1 = "Frame Window is &H" + Hex(hwndFrame) + "&"
Text2 = "Data Window is &H" + Hex(hwndDW) + "&"
PowerBuilder window In the Windows operating system, all elements on the screen are windows
classes themselves and have classes and handles. They may or may not have a title,
which serves as the window’s name. When you call FindWindow, you can
identify a window by its class or its name.
As an example, in one build of PowerBuilder 6.0, objects had these class
names:
Object Class name
Window, MDI frame, and MDI sheet FNWND60
MDI client area MDIClient
RichTextEdit control PBRTC60
DataWindow control PBDW60
Runtime SDI window FNWND360
4
Window class names will change

The window class names may change with any new version of
PowerBuilder, including minor updates. Your application should not depend
on these class names remaining constant.
Testing a RichTextEdit This code finds a window handle for a RichTextEdit control, connects to the
control RichTextEdit interface, initializes the RTE control, and calls the
GetInsertionPoint and SetSelection functions. Text1 and Text2 are textboxes.
RTEObj is a global variable:
Dim RTEObj As Object
The first subroutine does all the initialization:

Dim hwndRTE As Long
Dim MyBool As Boolean
Dim MyLong As Long
Const lpRTEClassName = "PBRTC60"


lpMDIClassName, 0&)
hwndRTE = FindWindowEx(hwndFrame, 0&,
lpRTEClassName, 0&)
If hwndRTE = 0 Then
Exit Sub
End If
Set RTEObj = Nothing

Set RTEObj = CreateObject("PowerBuilder.Test_RTE")
If RTEObj Is Nothing Then
MsgBox "could not create 'Test_RTE' server"
Exit Sub
End If
5
MyBool = RTEObj.Init(hwndRTE)
Text1 = "Init returned " + Str$(MyBool)
MyLong = RTEObj.LineCount
Text2 = "Line Count Is " + Str$(MyLong)
Another subroutine checks the insertion point:

Dim line As Long
Dim col As Long
line = 99
col = 99
Exit Sub
End If
MyBool = RTEObj.GetInsertionPoint(line, col)

Text1 = "Insertion Point"
Text2 = "Line=" + Str$(line) + " Col=" + Str$(col)
The next subroutine sets the selection to some arbitrary values:

Dim fl As Long
Dim fc As Long
Dim tl As Long
Dim tc As Long
fl = 2
fc = 3
tl = 5
tc = 6
Exit Sub
End If
MyBool = RTEObj.SetSelection(fl, fc, tl, tc)

Text1 = "SetSelection returned " + Str$(MyBool)
Testing a The code for a DataWindow is similar: it finds a handle for a DataWindow
DataWindow control control, connects to the Test_DW interface, initializes the DataWindow
control, and calls the Describe method. Text1 and Text2 are textboxes:
Dim DWObj As Object
6
Dim hwndDW As Long

Const lpDWClassName = "pbdw60"

lpMDIClassName, 0&)
hwndDW = FindWindowEx(hwndFrame, 0, lpDWClassName, 0&)
If hwndDW = 0 Then
Exit Sub
End If
Set DWObj = Nothing

Set DWObj = CreateObject("PowerBuilder.Test_DW")
If DWObj Is Nothing Then
MsgBox "could not create 'Test_DW' server"
Exit Sub
End If
MyBool = DWObj.Init(hwndDW)
Text1 = MyBool
Text2 = DWObj.Describe(
"DataWindow.Bands DataWindow.Objects")
PowerBuilder.Test
The PowerBuilder.Test interface provides basic version information for the
PowerBuilder application being tested. You can also use it to access the
DataWindow and RichTextEdit interfaces if you don’t want to rely on those
interfaces being registered.
7
IsPowerBuilderObject
PowerBuilder.Test must be registered in the system registry. When you install

PowerBuilder or use the deployment kit, all the OLE interfaces are registered
automatically and each time you run PowerBuilder the interfaces are
reregistered.
Properties
Property Data type Description
Version float (Read-only) The version of
PowerBuilder
Methods
Data type
Method returned Description
IsPowerBuilderObject BOOL Reports whether an object is a
PowerBuilder object
ObjectClassName string Gets the class of an object
ObjectFactory BOOL Creates an interface (for future use)
ObjectIUnknown IUnknown Establishes a basic IUnknown

interface to an object
VersionDetails BOOL Provides full version information for

a PowerBuilder program
IsPowerBuilderObject
Description Reports whether the object handle is a reference to a PowerBuilder object.
Syntax BOOL IsPowerBuilderObject ( HWND Object )
Argument Description
Object An object handle
Return value BOOL. Returns TRUE if the object handle refers to a PowerBuilder object.
8
Usage Getting an object handle can be a difficult programming exercise. Programs

like Spy let you get object handles.
FOR INFO For information about getting object handles, see "Using the
PowerBuilder Test interfaces" on page 1.
ObjectClassName
Description Reports the class of the object.
Syntax string ObjectClassName (HWND Object )
Object An object handle
Return value String. Returns the name of the object’s class. If Object is not a PowerBuilder
object, ObjectClassName returns an empty string.
Usage An object’s class is the PowerBuilder object definition for that object. The
returned string is the name of the class definition as saved in the PBL.
ObjectFactory
Description Creates a PowerBuilder Test interface without relying on the interface being
installed in the system registry. This is useful for future custom interfaces,
which wouldn’t be installed automatically in the system registry.
Syntax BOOL ObjectFactory ( HWND WindowObject, string InterfaceID, REF

IDispatch Interface )
WindowObject The object handle for a window that you want to use with
the interface
9
ObjectIUnknown
InterfaceID A string whose value is either a Class ID or a
programmatic identifier for a PowerBuilder Test interface
Values for programmatic identifiers are:
♦ PowerBuilder.Test_DW
♦ PowerBuilder.Test_RTE
Values for COM class IDs are:
♦ TypeLibrary: LIBID_LIBPBTEST = {9537EB50-
52CC-11D0-9945-080009AC61A9}
♦ BaseTest: IID_IPBTEST = {9537EB51-52CC-11D0-
9945-080009AC61A9}
♦ DataWindow: IID_IPBTEST_DW = {9537EB52-
52CC-11D0-9945-080009AC61A9}
♦ RichTextEdit: IID_IPBTEST_RTE = {9537EB53-
52CC-11D0-9945-080009AC61A9}
Interface An IDispatch variable that will hold the handle to the
returned interface
Return value BOOL. Returns TRUE if the interface is successfully created.
Usage You can call ObjectFactory to get an interface for accessing a DataWindow or
a RichTextEdit control instead of calling your language’s method for
connecting to an object. Calling ObjectFactory is necessary when the
individual interfaces are not installed in the system registry.
To get an interface to an OLE object in a PowerBuilder window, call
ObjectIUnknown.
ObjectIUnknown
Description Gets the IUnknown interface for an OLE object in a PowerBuilder window.
Syntax IUNKNOWN *ObjectIUnknown ( HWND Object )
Object The object handle of the OLE object for which you want
an interface
Return value IUnknown. A reference to the interface.
10
Usage Use ObjectIUnknown when you want to call methods and set properties of an
OLE object. The caller must release this interface when done.
This method does not give you access to the methods and properties of
PowerBuilder objects.
VersionDetails
Description Reports version information about a PowerBuilder application, including
version number, internal build number, and the operating system for which it
was built.
Syntax BOOL VersionDetails ( REF long VersionMajor, REF long VersionMinor,

REF long MaintLevel, REF long BuildNumber, REF long MiscFlags )
VersionMajor A long variable to which PowerBuilder Test will assign
the major version number of the PowerBuilder application
server
For example, for PowerBuilder 5.0, VersionMajor is 5
VersionMinor A long variable to which PowerBuilder Test will assign
the minor version number of the PowerBuilder application
server
For example, for PowerBuilder 5.0.03, VersionMinor is 0
MaintLevel A long variable to which PowerBuilder Test will assign
the maintenance release number of the PowerBuilder
application server
For example, for PowerBuilder 5.0.03, MaintLevel is 3
BuildNumber A long variable to which PowerBuilder Test will assign
the build number of the PowerBuilder application server.
Applicable only to beta versions of PowerBuilder
MiscFlags A long variable in which PowerBuilder Test will set bits
to tell you more about the PowerBuilder version. See
Usage below
Return value BOOL. Returns TRUE if you are connected to a valid PowerBuilder
application server.
11
PowerBuilder.Test_DW
Usage To get the major and minor version numbers as a float value (for example,
PowerBuilder 5.0), use the Version property instead of the VersionDetails
method.
The meanings of the bit settings in the MiscFlags argument are:
Hex value Meaning of flag is SET
0000.0001 Debug build of PowerBuilder Virtual Machine
0000.0010 Win32 build (includes Win32 emulation builds)
0000.0020 Win16 build
0000.0040 Macintosh build
0000.0080 OS/2 build
0000.0100 UNIX build (of any flavor)
0001.0000 UNICODE build
0002.0000 Double Byte Character Set (DBCS) build
All other bits are reserved.
PowerBuilder.Test_DW
The PowerBuilder.Test_DW interface provides information about data and
focus in a DataWindow control in a PowerBuilder application. You can change
the current row and mark rows as selected. You can examine but can’t change
data. The Describe method gives access to the internal properties of the
DataWindow object.
PowerBuilder.Test_DW must be registered in the system registry unless you
connect via the ObjectFactory function of the PowerBuilder.Test interface.
When you install PowerBuilder or use the deployment kit, all the OLE
interfaces are registered automatically and each time you run PowerBuilder the
interfaces are reregistered.
12
Properties
BandAtPointer string (Read-only) The name of the band in
which the pointer is currently located
and the row number associated with
the band. The two values are separated
by a tab (~t). The value has the format:
bandname~trow
FOR INFO For a list of band names
and the row associated with a band, see
the GetBandAtPointer function in the
PowerScript Reference
Column long The number of the current column,

which is the column that has focus
ItemAsNumber double (Read-only) The value at the current

row and column as a number. If the
column’s data type is not numeric, the
value is 0.0
ItemAsString string (Read-only) The value at the current

row and column as a string.
ItemAsString has a value regardless of
the column’s data type as long as the
value can be represented as a string
Row long The number of the current row, which

is the row that has focus
RowCount long (Read-only) The number of rows in the

primary buffer. It does not include
rows that have been retrieved and then
deleted or filtered
Methods
Data type
Describe string Reports the values of properties of a
DataWindow object and objects within
the DataWindow object
13
Describe
Data type
GetChild BOOL Provides an object reference to a child
DataWindow or to a report in a
composite DataWindow
GetItemDateTime BOOL For a column whose data type is

DateTime, reports the date and time
values of the specified row and column
GetObjectAtPointer BOOL Reports the object and row number

under the pointer
Init BOOL Makes a DataWindow available for
inspection
IsSelected BOOL Reports whether a row is highlighted

in the DataWindow
SaveAs BOOL Saves the contents of the DataWindow

in the format you specify
SelectedRow BOOL Reports the selected row in the

DataWindow
SelectRow BOOL Highlights or unhighlights a row in a

DataWindow
SetAllEvents BOOL Enables all PowerScript events for the

current DataWindow
Describe
Description Reports the values of properties of a DataWindow object and objects within the
DataWindow object. You can also evaluate expressions using values in a
specific row in the DataWindow.
Syntax string Describe ( string Propertylist )
Propertylist A string whose value is a blank-separated list of the
properties whose values you want. A property takes the
format objectname.property
14
Return value string. Returns a string that includes a value for each property or Evaluate
function in Propertylist. A newline character (~n) separates each item.
Usage Although you can request several properties in a single call to Describe, doing
so can result in a very complex string with several levels of nested quotes. For
debugging purposes, it is easier to request one property at a time.
FOR INFO For more information about the format of Propertylist, the return
value, or evaluating an expression, see the Describe function in the
PowerScript Reference.
FOR INFO For information about the properties of objects within a
DataWindow object, see the DataWindow Reference.
GetChild
Description Provides a reference to a child DataWindow or to a report in a composite
DataWindow.
Syntax BOOL GetChild ( string ChildName, REF HWND ChildDW )
ChildName A string whose value is the name of the column
containing the child DataWindow or the name of the
report in the composite DataWindow
ChildDW A variable in which you want GetChild to put the
reference to the child DataWindow
Return value BOOL. Returns TRUE if it succeeds and FALSE if an error occurs.
Usage To specify the current DataWindow (the one that contains the child
DataWindow) before calling other methods, call Init.
To examine the child DataWindow, use the reference returned by GetChild as
the argument for the Init method. This resets the current DataWindow to be the
child DataWindow. Then call other Test_DW methods for the child
DataWindow.
FOR INFO For more information about child DataWindows, see the
GetChild function in the DataWindow Reference.
15
GetItemDateTime
GetItemDateTime
Description Gets data whose type is DateTime from the primary buffer of the DataWindow.
Syntax BOOL GetItemDateTime ( long Row, long Col, REF long Year, REF long
Month, REF long Day, REF long Hour, REF long Minute, REF long
Second, REF long MicroSeconds )
Row A long value specifying the row for which you want the
DateTime value
Col A long value specifying a column whose data type is
DateTime
Year A long variable in which to store the 4-digit year of the
DateTime value
Month A long variable in which to store the month of the
DateTime value. Month is a value from 1 to 12
Day A long variable in which to store the day of the DateTime
value. Day is a value from 1 to 31
Hour A long variable in which to store the hour of the
DateTime value. Hour is a value from 0 to 23
Minute A long variable in which to store the minutes of the
DateTime value. Minute is a value from 0 to 59
Second A long variable in which to store the seconds of the
DateTime value. Second is a value from 0 to 59
MicroSecond A long variable in which to store the year of the DateTime
value. MicroSecond is a value from 0 to 999,999
Return value BOOL. Returns TRUE for success and FALSE if an error occurs—for
example, if the column is the wrong data type.
Usage To specify the current DataWindow before calling other method, call Init.
FOR INFO For similar PowerBuilder functionality, see the GetItemDate,
GetItemDateTime, and GetItemTime functions in the PowerScript
Reference.
GetObjectAtPointer
16
Description Reports the object and row number under the pointer.
Syntax BOOL GetObjectAtPointer ( REF string DWObject )
DWObject A string variable in which to store the name of the object
under the pointer and its row number, separated by a tab
character (~t). The string has the format:
name~trow
Usage To specify the current DataWindow before calling other methods, call Init.
The PowerBuilder function GetObjectAtPointer has similar functionality to
this PowerBuilder Test method.
FOR INFO For information on the rows associated with bands (and therefore
with objects in those bands), see the GetBandAtPointer function in the
Init
Description Sets up the PBTEST_DW interface for the DataWindow you want to examine.
Syntax BOOL Init ( HWND DWObject )
DWObject An object reference to a DataWindow
Return value BOOL. Returns TRUE if DWOBject is a valid DataWindow and the
initialization was successful. Returns FALSE if an error occurs.
Usage To specify the current DataWindow before calling other methods, call Init. You
can call Init as often as needed to change the DataWindow being examined.
IsSelected
17
SaveAs
Description Reports whether a row is selected in a DataWindow. A selected row is

highlighted using reverse video.
Syntax BOOL IsSelected ( long Row )
Row A long value specifying the row that you want to test
Return value BOOL. Returns TRUE if Row is selected FALSE if it is not selected. If Row is
greater than the number of rows in the primary buffer or is 0 or negative,
IsSelected returns FALSE.
Usage Call Init to specify the current DataWindow before calling other methods.
More than one row can be highlighted. A selected row is not the same as the
current row, which is the row that has focus. To find out the current row, use
the Row property.
FOR INFO For similar PowerBuilder functionality, see the IsSelected
function in the PowerScript Reference.
SaveAs
Description Saves the contents of a DataWindow control in the format you specify.
Syntax BOOL SaveAs ( long SaveAsType, long IncludeHeadings, string FileName )
18
SaveAsType A long value specifying the format of the saved data. Use
values of the enum tagDW_SAVEAS:
♦ DW_SAVEAS_EXCEL
♦ DW_SAVEAS_TEXT
♦ DW_SAVEAS_CSV
♦ DW_SAVEAS_SYLK
♦ DW_SAVEAS_WKS
♦ DW_SAVEAS_WK1
♦ DW_SAVEAS_DIF
♦ DW_SAVEAS_DBF2
♦ DW_SAVEAS_DBF3
♦ DW_SAVEAS_SQL
♦ DW_SAVEAS_CLIPBOARD
♦ DW_SAVEAS_PS
♦ DW_SAVEAS_WMF
Values are similar to the PowerBuilder enumerated data
type SaveAsType. For more information about the values,
see the SaveAs function in the PowerScript Reference
IncludingHeadings A long value indicating whether to include the
DataWindow’s column headings at the beginning of the
file. Values are:
♦ 0 Do not include headings
♦ Nonzero Include headings
FileName A string whose valid is the name of the file in which to
save the contents
FOR INFO For similar PowerBuilder functionality, see the SaveAs function
SelectedRow
19
SelectRow
Description Reports the number of the next highlighted row after a specified row in a
DataWindow control.
Syntax BOOL SelectedRow ( REF long Row )
Row A long variable in which to store the location of the row
after which you want to search for the next selected row
SelectedRow begins its search after the specified row. It doesn’t matter whether
row itself is selected.
FOR INFO For similar PowerBuilder functionality, see the GetSelectedRow
SelectRow
Description Highlights or unhighlights rows in a DataWindow. You can select all rows or a
single row. SelectRow does not affect which row is current. It does not select
rows in the database.
Syntax BOOL SelectRow ( long RowNumber, long State )
RowNumber A long value specifying the number of the row you want
to select or deselect. Rows are numbered from 1 to the
total number of rows. To specify all rows, specify 0
State A long value specifying whether to select the row. Values
are:
♦ 0 Unhighlight the row
♦ Nonzero Highlight the row
FOR INFO For similar PowerBuilder functionality, see the SelectRow
20
SetAllEvents
Description Enables all PowerScript events for the current DataWindow.
Syntax BOOL SetAllEvents ( )
Return value BOOL. Returns TRUE if it is successful and FALSE if an error occurs.
PowerBuilder.Test_RTE
The PowerBuilder.Test_RTE interface provides information about the content
and insertion point in a RichTextEdit control or RichTextEdit DataWindow in
a PowerBuilder application. You can get and set the insertion point or mark a
text selection. You can get the text in the line containing the insertion point and
you can change the current band (header, body, or footer).
PowerBuilder.Test_RTE must be registered in the system registry—unless you
connect via the ObjectFactory function of the PowerBuilder.Test interface.
When you install PowerBuilder or use the deployment kit, all the OLE
interfaces are registered automatically and each time you run PowerBuilder the
interfaces are reregistered.
Properties
LineCount long (Read-only) The number of lines of
text in the RichTextEdit control
Methods
Data type
GetCharFormat BOOL Reports the text formatting in effect at
the insertion point
21
GetCharFormat
Data type
GetCurrentBand BOOL Finds out whether the current band is
detail, header, or footer
GetInsertionPoint BOOL Finds out the line and character

position of the insertion point
GetLine BOOL Gets the text of the line containing the

insertion point
GetSelection BOOL Gets the position of the beginning and

end of the selected text
Init BOOL Makes a RichTextEdit control

available for inspection
LineLength BOOL Reports the length of the line

containing the insertion point
SetCurrentBand BOOL Sets the current band to detail, header,

or footer. Subsequent function calls
will affect that band
SetInsertionPoint BOOL Sets the insertion point at the specified

line and character position
SetSelection BOOL Selects a range of text
GetCharFormat
Description Reports the character formatting in effect at the insertion point.
Syntax BOOL GetCharFormat ( REF long OldRetVal, REF long Mask, REF long
Effects, REF long Height, REF long Color, REF long CharSet, REF long
PitchAndFamily, REF string FaceNameAsString )
OldRetVal A long variable in which to store the return value from an
internal message
Mask A long variable. The mask value is always 0
Effects A long variable in which to store an effects value
22
Height A long variable in which to store the text height. The
value is as described for the Windows SDK LOGFONT
structure
Color A long variable in which to store the text color as an RGB
color value
CharSet A long variable in which to store the character set. The
structure
PitchAndFamily A long variable in which to store additional font
information. The value is as described for the Windows
SDK LOGFONT structure
FaceNameAsString A string variable in which to store the font name. The
structure
Usage FOR INFO For similar PowerBuilder functionality, see the GetTextColor and
GetTextStyle functions in the PowerScript Reference. (In PowerBuilder, you
can’t find out the font and font size programmatically.)
GetCurrentBand
Description Finds out what band in the RichTextEdit control or DataWindow contains the
insertion point.
Syntax BOOL GetCurrentBand ( REF long BandAttributes )
BandAttributes A long variable in which to store a number identifying the
current band. Compare the value to the values of the enum
tag RTE_BAND:
♦ RTEBAND_DETAIL
♦ RTEBAND_HEADER
♦ RTEBAND_FOOTER
23
GetInsertionPoint
GetInsertionPoint
Description Reports the line and character column of the insertion point.
Syntax BOOL GetInsertionPoint ( REF long Line, REF long CharCol )
Line A long variable in which to store the number of the line
containing the insertion point
CharCol A long variable in which to store the number of the
character just after the insertion point, where the first
character is 1. When the insertion point is at the beginning
of a line, CharCol is set to 1
Usage For similar PowerBuilder functionality, see the Position function in the
GetLine
Description Gets the text of a entire line in a RichTextEdit control or DataWindow.
Syntax BOOL GetLine ( long LineNumber, REF string TextOfLine )
LineNumber A long value specifying the number of a line
TextOfLine A string variable in which to store the text of the specified
line
Usage For similar PowerBuilder functionality, see the TextLine, SelectTextLine, and
SelectedText functions in the PowerScript Reference.
GetSelection
24
Description Gets the start and end position of selected text in a RichTextEdit control or
DataWindow.
Syntax BOOL GetSelection ( REF long FromLine, REF long FromColumn, REF
long ToLine, REF long ToColumn )
FromLine A long variable in which to store the number of the line in
which the selection starts
FromColumn A long variable in which to store the number in the line of
the first character in the selection
ToLine A long variable in which to store the number of the line
where the selection ends
ToColumn A long variable in which to store the number in the line of
the character before which the selection ends
Usage If text is selected, the insertion point can be at the beginning or the end of the
selection. For example, if the user dragged down to select text, the insertion
point is at the end.
Selection or insertion point To find out whether there is a selection or just
an insertion point, check the values of the last two arguments. If ToLine and
ToColumn are set to 0, then there is no selection but only an insertion point.
If there is a selection and you want the position of the insertion point, call
GetInsertionPoint instead.
Insertion point and end of selection discrepancy The position of an
insertion point at the end of the selection and the actual end of selection can
differ. When reporting the position of selected text, the positions are
inclusive. GetSelection reports the first line and character and the last line
and character that are selected. When reporting the position of the insertion
point, GetInsertionPoint identifies the character just after the insertion point.
FOR INFO For similar PowerBuilder functionality, see the Position function
Init
25
LineLength
Description Sets up the PBTEST_RTE interface for the control you want to examine. The
control must be a RichTextEdit control or a DataWindow control containing a
DataWindow object with the RichTextEdit presentation style.
Syntax BOOL Init ( HWND RTEObject )
RTEObject An object reference to a RichTextEdit control or
DataWindow
Return value BOOL. Returns TRUE if RTEOBject is a valid RichTextEdit control or

DataWindow and the initialization was successful. Returns FALSE if an error
occurs.
Usage To specify the current RichTextEdit control or DataWindow before calling

other methods, call Init. You can call Init as often as needed to change the
RichTextEdit control being examined.
LineLength
Description Reports the number of characters in the line containing the insertion point in a
RichTextEdit control or DataWindow.
Syntax BOOL LineLength ( long LineNumber, REF long LineLength )
LineNumber A long value specifying the number of the line for which
you want the length
LineLength A long variable in which to store the number of characters
in the line
Usage For similar PowerBuilder functionality, see the SelectLine and SelectedLength
functions in the PowerScript Reference.
SetCurrentBand
26
Description Sets the current band in a RichTextEdit control or DataWindow. The bands are
detail (the main text area), header, and footer.
Syntax BOOL SetCurrentBand ( long Band )
Band A long value specifying the band. Use values of the enum
tag RTE_BAND:
♦ RTEBAND_DETAIL
♦ RTEBAND_HEADER
♦ RTEBAND_FOOTER
Usage Call GetCurrentBand to find out the current band before you change it with
SetCurrentBand. When you change the current band, you should reset it after
your processing is complete. Otherwise, the user’s view of the RichTextEdit
content could be disrupted.
SetInsertionPoint
Description Puts the insertion point at a particular line and character column in a
RichTextEdit control or DataWindow.
Syntax BOOL SetInsertionPoint ( long Line, long CharCol )
Line A long value specifying the number of the line that will
contain the insertion point
CharCol A long value specifying the number of the character that
will follow the insertion point. The first character on a line
is 1
Usage To put the insertion point in a different band, call SetCurrentBand first.
FOR INFO For similar PowerBuilder functionality, see the SelectText
27
SetSelection
SetSelection
Description Selects a range of text in a RichTextEdit control or DataWindow.
Syntax BOOL SetInsertionPoint ( long FromLine, long FromCharCol, long ToLine,

long ToCharCol )
FromLine A long value specifying the number of the line in which
the selection starts
FromCharCol A long value specifying the number in the line of the first
character in the selection. The number of the first
character in a line is 1
ToLine A long value specifying the number of the line in which
the selection ends
ToCharCol A long value specifying the number in the line of the last
character in the selection
Usage To select text in a different band, call SetCurrentBand first.

SetSelection sets the position of the insertion point if the ToLine and
ToCharCol arguments are 0.
FOR INFO For similar PowerBuilder functionality, see the SelectText
28
CH A PTE R 2 PBSCC Interface Function
Reference
About the chapter This chapter documents functions that the PowerBuilder SCC interface
calls and the values that PowerBuilder passes to the source control
provider so that you can implement those functions in a source control
provider DLL.
Contents
Topic Page
About the PBSCC interface 29
How PBSCC works 30
Functions for the SCC interface 35
About the PBSCC interface

The PBSCC interface works with any external source control system that
implements the Microsoft SCC specification. PBSCC calls functions in
the specification and the source control provider DLL implements those
functions to respond to PowerBuilder’s source control requests.
PBSCC is available in PowerBuilder Versions 5.0.03 and 6.0.
Microsoft header file Source control in PowerBuilder implements the Microsoft Common
required Source Code Control Interface Specification, Version 0.00.0823.
Powersoft has conformed to this interface specification as closely as
possible. For this reason, vendors who wish to write SCC provider DLLs
for PowerBuilder need to license the SCC.H header file from Microsoft.
For future versions of PowerBuilder, Powersoft and its CODE partners
may decide to augment this specification to provide additional
functionality.
Calling convention The functions in the SCC provider DLL must use the _cdecl calling
convention.
29
How PBSCC works
SCC functions called The SCC functions that the PowerBuilder PBSCC interface calls in response
by PowerBuilder to the user’s source control commands are listed in "Source control commands
that trigger SCC function calls" on page 31.
The values that PBSCC passes to the functions are documented in "Functions
for the SCC interface" on page 35.
SCC functions not These functions specified in the SCC API are not currently implemented in the
implemented in PowerBuilder PBSCC interface:
PBSCC
SccGetVersion
SccRename
SccProperties
SccQueryInfo
SccGetEvents
SccAddFromScc
SccSetOption
These functions are called in the PowerBuilder 6.0 version of PBSCC only:
SccDiff
SccRunScc
How PBSCC works

Source control activities take place in the PowerBuilder Library painter via the
Source menu.
User options The user has several options for source control. The user can connect:
♦ To PowerBuilder native source control, which checks objects in to and
out of PBLs but does not maintain a source control archive
♦ Via a PowerBuilder interface to a small set of source control vendors
♦ Via SCC to any source control vendor that supports the SCC interface
The PowerBuilder SCC interface provides the most robust source control with
the best synchronization between the source control archive and PowerBuilder
PBLs.
How the user The user connects to an SCC source control system by selecting
connects via SCC to Source>Connect and choosing SCC API from the list of vendors. Then if more
source control
than one SCC provider is installed, the user chooses from a list of providers.
PowerBuilder gets the list of SCC providers from the system registry.
30
Chapter CHAPTER 2 PBSCC Interface Function Reference
PowerBuilder uses a data value associated with the provider (called the
ProviderRegKey) to look up the path for the provider DLL, stored in an entry
labeled SCCServerPath.
After the user has established a source control connection for an application
object, PowerBuilder saves that information and connects automatically
without prompting the user. The user can change the configuration by choosing
Source>Configuration.
Source control commands that trigger SCC function calls

PBSCC is an interface between PowerBuilder and a source control provider’s
SCC DLL. PBSCC calls functions specified in the Microsoft Common Source
Code Control Interface Specification that the provider implements in its SCC
DLL.
These are the SCC functions that PBSCC calls in response to the commands on
the Library painter’s Source menu and other user actions:
PowerBuilder menu choice or action SCC function(s) called
Start the Library painter SccInitialize
Choose another application object SccCloseProject

SccUninitialize
SccInitialize
SccGetProjectPath
SccOpenProject
Exit PowerBuilder SccCloseProject

SccUninitialize
Source>Connect SccGetProjectPath
SccOpenProject
SccGetCommandOptions
Source>Configuration SccCloseProject
SccUninitialize
SccInitialize
SccGetProjectPath
SccOpenProject
Source>Create New Release Not implemented in PBSCC
Source>SCC Administration SccRunScc (PowerBuilder 6.0 only)
Source>Check In SccCheckin
31
How PBSCC works
Choose another application object SccCloseProject

SccUninitialize
SccInitialize
SccGetProjectPath
SccOpenProject
Exit PowerBuilder SccCloseProject

SccUninitialize
Source>Connect SccGetProjectPath
SccOpenProject
Source>Configuration SccCloseProject
SccUninitialize
SccInitialize
SccGetProjectPath
SccOpenProject
Source>Create New Release Not implemented in PBSCC
Source>SCC Administration SccRunScc (PowerBuilder 6.0 only)
Source>Check In SccCheckin
32
Configuration information for SCC

Configuration information is stored in two files.
[Library] section of PowerBuilder stores information about the most recently used source control
PB.INI system in PB.INI:
[Library]
SourceVendor=vendorname
If an application object has been configured for source control, PowerBuilder

stores information about the source control system in a configuration file for
the application. PB.INI identifies the configuration file:
[Library]
$c:\myproj1\myproj.pbl(app1)=c:\myproj1\pamm.cfg
Configuration file for In the configuration file, the ProviderRegKey value names a subkey in the
the application object system registry that identifies where to locate the provider’s SCC DLL. A
section named for the provider identifies the parameters of the user’s last
connection for the application.
For example, the PBSCC configuration file might have values like these for the
user’s last connection to a project called scctest using Visual SourceSafe:
[PBSMS]
SMSInterface=SCC
ProviderRegKey=Software\Microsoft\SourceSafe
[SourceSafe]
UserID=pamm
ProjectName="$/scctest",JAAAAAAA
LocalPath=c:\pbls\srcctl
AuxProjPath=d:\vss,
Filenames passed as arguments to SCC functions

Each SCC function that deals with an archived object identifies the object in
the lpFileNames array. When the source control provider or PBSCC needs to
copy the object, an actual file exists in the local project directory. When the
source control provider just needs to know the name of the object and doesn’t
need a new copy of the object, there is no actual file. However, a string
identifying an object in the lpFileNames array is always a full path, whether or
not a file containing the object exists.
33
How PBSCC works
The string identifying the object consists of:

♦ The local project path
♦ A backslash
♦ The name of the object as it is stored in the PBL plus the extension that
PB uses for that object type when it exports the object
The source control provider is expected to use the object name plus file
extension as the name of the archived object.
Error message handling

PowerBuilder displays error messages to the user based on the return value of
an SCC function. If an error occurs while the provider’s SCC function is
running, the provider should return the appropriate value. PowerBuilder will
use that value to display an error message to the user at the appropriate time.
To present an integrated user interface, the provider should not display an error
message.
When the provider If during initialization the provider has told PBSCC that it supports textout
supports textout (SCC_CAP_TEXTOUT), the provider can also call the PBSCC message
handler when an error occurs. This callback function stores a message in the
PBSCC trace log. PowerBuilder does not display this message to the user. It
always displays error messages based on the return values of SCC functions.
The syntax for the message handler is:
typedef LONG (*LPTEXTOUTPROC) (LPSTR, LONG);
LPSTR A string whose value is the error message text. The
string should not contain carriage return or linefeed
characters and should be null-terminated
LONG A long identifying the type of message. Values are:
♦ SCC_MSG_INFO
♦ SCC_MSG_WARNING
♦ SCC_MSG_ERROR
♦ SCC_MSG_STATUS
♦ SCC_MSG_DOCANCEL
♦ SCC_MSG_STARTCANCEL
♦ SCC_MSG_STOPCANCEL
34
The value returned to the SCC provider is always SCC_MSG_RTN_OK.
Steps for error When the provider supports textout These are the steps for error message
message handling processing when the provider supports textout:
1 PowerBuilder calls an SCC function implemented by the provider.
2 An error occurs during the provider’s processing.
3 The provider may or may not display an error message. Because
PowerBuilder also displays a message, it is better for the provider not
to.
4 The provider calls the PBSCC textout callback function. The pointer to
the function was passed to the provider when PBSCC called
SccOpenProject.
5 PowerBuilder puts the message passed to it by the callback function
into its trace log and returns SCC_MSG_RTN_OK to the provider.
6 The provider returns an error code from the function called in step 1.
7 PowerBuilder performs error processing based on the error code, which
can include displaying a message to the user.
When the provider doesn’t support textout The steps for handling error
messages are the same except for the omission of steps 4 and 5 (because
there is no callback function).
Functions for the SCC interface

This section documents the functions that PBSCC calls and the argument
values that PBSCC passes to the provider.
To implement an SCC provider DLL, the source control provider needs to
license the SCC.H header from Microsoft. The header file defines constants
specified in this documentation. For information on the general source control
specification, see the documentation on the Common Source Code Control
Interface Specification from Microsoft.
The functions in this section are:
SccAdd
SccCheckin
SccCheckout
SccDiff
SccGet
35
SccAdd
SccGetProjPath
SccHistory
SccInitialize
SccOpenProject
SccPopulateList
SccRemove
SccRunScc
SccUncheckout
SccAdd
Description Called when the user highlights one or more objects and selects
Source>Register in the Library painter. PBSCC calls it once for each
highlighted object.
Syntax SCCRTN SccAdd (void *pvContext, HWND hWnd, LONG nFiles, LPSTR
*lpFileNames, LPSTR lpComment, LONG *pfOptions, void *pvOptions);
Argument passed
to provider Data Type Value
pvContext void * Provider’s context structure, allocated
during initialization
hWnd HWND Window handle of the Library painter’s

workspace
nFiles LONG Number of files to be added to the current

project. Always 1
lpFileNames LPSTR * Pointer to an array of pointers to

filenames. Array length is always 1.
lpFileNames[0] contains the name of a file
that is the object to be registered. PBSCC
puts a temporary file containing the object
in the local project directory
FOR INFO For information about the
string, see "Filenames passed as arguments
to SCC functions" on page 33
lpComment LPSTR The comment associated with this object

in the Library painter
36
Argument passed
to provider Data Type Value
pfOptions LONG * Array of LONGs. Array length is 1. The
value of pfOptions[0] is usually
SCC_FILETYPE_TEXT, meaning the file
to be registered is an ASCII text file
For DataWindow object, the value is
SCC_FILETYPE_AUTO
pvOptions void * Provider-specific options. Always NULL
Return value SCCRTN. The SCC provider should return one of the following values:
Value Meaning
SCC_OK Success
SCC_E_FILEALREADYEXISTS File is already registered
SCC_E_TYPENOTSUPPORTED File type (binary) is not supported
SCC_E_OPNOTSUPPORTED Source control system does not support

this operation
SCC_E_ACCESSFAILURE Could not access the source control system
SCC_E_NOTAUTHORIZED User not authorized for this operation
SCC_E_NONSPECIFICERROR Nonspecific failure
SCC_I_OPERATIONCANCELED Operation canceled before completion
SCC_E_FILENOTEXIST Local file to be registered was not found
Usage PowerBuilder behavior PowerBuilder does not display a dialog box when
registering an object, so there is no opportunity for the user to specify a
comment or advanced options. PBSCC passes the object comment stored in
the PBL.
Before calling SccAdd, PBSCC creates a temporary file containing the object
that the provider will register in the archive. The file is in the local project path
directory specified in the configuration. After SccAdd finishes and control
returns to PBSCC, PBSCC deletes the temporary file.
SccCheckin
37
SccCheckin
Description Called when the user highlights one or more objects in the Library painter and
selects Source>Checkin. It is called once for each highlighted object.
Syntax SCCRTN SccCheckin (void *pvContext, HWND hWnd, LONG nFiles,

LPSTR *lpFileNames, LPSTR lpComment, LONG fOptions, void
*pvOptions);
Argument
passed to
provider Data type Value
pvContext void * Provider’s context structure, allocated by
the provider during initialization
workspace
nFiles LONG Number of files to be checked in. Always 1
lpFileNames LPSTR * A pointer to an array of strings. The array

length is 1. lpFileNames[0] names the file
containing the object being checked in
FOR INFO For information about the string,
see "Filenames passed as arguments to SCC
functions" on page 33
lpComment LPSTR Comment from check-in dialog boxes
fOptions LONG Command flags.

SCC_KEEP_CHECKEDOUT may be set
pvOptions void * SCC provider-specific options from

Return value SCCRTN. The SCC provider returns one of the following values:
Value Meaning
SCC_OK Success
SCC_E_FILENOTCONTROLLED File not under source code control
SCC_E_ACCESSFAILURE Could not access the source control

system
SCC_E_NOTCHECKEDOUT File is not checked out by this user
SCC_E_CHECKINCONFLICT File could not be checked in
38
Value Meaning
SCC_E_FILENOTEXIST Local file could not be found
Usage PowerBuilder behavior When the user chooses Source>Checkin,

PowerBuilder displays the CheckIn Object(s) dialog box so that the user can
specify a comment and advanced options.
If the user clicks the Advanced button, PBSCC calls SccGetCommandOptions
with the ppvOptions argument pointing to a NULL value. The SCC provider
can display an advanced settings dialog box, store the user’s settings in a data
structure, and put the address of the data structure in the location specified by
the ppvOptions argument.
PBSCC calls SccCheckout for each object the user highlighted, passing the
address of the advanced options data structure in pvOptions.
If the user doesn’t check the Reuse Comments box, PowerBuilder displays the
dialog box for each selected object so that the user can supply another
comment. When the user checks Reuse Comments, the current comment is
used for the rest of the objects to be checked in.
SCC provider actions The provider copies the file specified in the
lpFileNames array into the archive.
The provider can take into account the advanced settings stored in its own data
structure passed in pvOptions.
Additional PowerBuilder behavior When SccCheckin returns SCC_OK,
PBSCC deletes the temporary file containing the object and copies the
object from the work PBL to the registration PBL and clears the check-out
status in both PBLs.
SccCheckout
selects Source>Checkout. It is called once for each highlighted object.
Syntax SCCRTN SccCheckout (void *pvContext, HWND hWnd, LONG nFiles,

*pvOptions);
39
SccCheckout
Argument
passed to

workspace
nFiles LONG Number of files to be checked out. Always

1

length is 1. lpFileNames[0] contains a
filename that the SCC provider uses to write
the file containing the object being checked
out of the archive
lpComment LPSTR Check out comment provided by the user
fOptions LONG Command flags. Always 0
pvOptions void * A pointer to the address of the SCC

provider’s data structure containing the
user’s advanced settings. If the user doesn’t
set advanced options, pvOptions points to a
null value
FOR INFO For more information, see
Value Meaning
SCC_OK Success

system
SCC_E_ALREADYCHECKEDOUT File already checked out by this user
40
Value Meaning
SCC_E_FILEISLOCKED File is locked
SCC_E_FILEOUTEXCLUSIVE File checked out by another user
Usage The same check-out comment applies to the all the objects the user checks out
at one time. To have different check-out comments, the user must highlight one
object and select Source>Checkout, repeating the sequence for all objects.
PowerBuilder behavior PowerBuilder detects whether the provider
supports check-out comments from the
SCC_CAP_COMMENTCHECKOUT flag set from SccInitialize. If the
provider doesn’t support checkout comments or advanced options, the
CheckOut Object(s) dialog box is not displayed.
When the user chooses Source>Checkout, PowerBuilder prompts for the name
of the work library into which it will copy the object. Then it displays the
CheckOut Object(s) dialog box so that the user can specify a comment and
advanced options.
If the user clicks the Advanced button, PBSCC calls SccGetCommandOptions
with the ppvOptions argument pointing to a NULL value. The SCC provider
can display an advanced settings dialog box, store the user’s settings in a data
structure, and put the address of the data structure in the location specified by
the ppvOptions argument.
Finally, PBSCC calls SccCheckout for each object the user highlighted,
passing the address of the advanced options data structure in pvOptions.
SCC provider actions The provider writes a file containing the object
stored in the archive using the path and filename specified in the
lpFileNames array.
The provider can take into account the advanced settings stored in its own data
structure passed in pvOptions.
Additional PowerBuilder behavior When SccCheckout returns SCC_OK,
PBSCC imports the temporary file written by the provider into the
registration PBL, then copies the object to the work PBL and sets the check-
out status in both PBLs. Then it deletes the temporary file.
If PBSCC cannot import the object into the registration PBL, it calls
SccUncheckout to clear the check-out status in the archive so that the archive
and the PBLs remain in sync.
41
SccDiff
SccDiff
Description Called when the user highlights an object in the Library painter and selects
Source>Compare Differences.
Available in PowerBuilder 6.0 or later.
Syntax SCCRTN SccDiff (void *pvContext, HWND hWnd, LPSTR lpFileName,

LONG fOptions, void *pvOptions);
Argument
passed to
pvContext void * Provider’s context structure, allocated by the
provider during initialization

workspace
lpFileName LPSTR A pointer to a string naming the object to be

compared
FOR INFO For information about the string, see
"Filenames passed as arguments to SCC
fOptions LONG Command flags. Always 0, meaning the SCC

provider should display a window showing the
differences between the current object and the
most recently checked-in version
pvOptions void * SCC provider-specific options. Always NULL

because there is no dialog box for the user to
specify advanced option.
Value Meaning
SCC_OK Success
SCC_I_FILESDIFFER Differences exist
SCC_E_FILENOTEXIST Local file not found
42
Usage PowerBuilder behavior Before calling SccDiff, PowerBuilder creates a

temporary file containing the object to be compared. The file is in the local
project path directory specified in the configuration. After the comparison is
complete and control returns to PBSCC, PBSCC deletes the temporary file.
PowerBuilder does not support advanced options for SccDiff.
SCC provider actions The SCC provider has control of the comparison.
The provider should display a window showing the differences between the
user’s copy of the object and the checked-in object.
SccGet
Description Called when PBSCC needs a copy of an object in the source control archive.
PBSCC calls SccGet in these situations:
♦ When the user selects Source>Synchronize
♦ When the user selects Take in the PBSCC Registration Directory dialog
box
Syntax SCCRTN SccGet (void *pvContext, HWND hWnd, LONG nFiles, LPSTR
*lpFileNames, LONG fOptions, void *pvOptions);
Argument
passed to

workspace
nFiles LONG Number of files to be retrieved. Always 1

filename that the SCC provider uses to write
a file containing the archived object
fOptions LONG Always 0
43
Argument
passed to
pvOptions void * SCC provider-specific options. Always
NULL
Value Meaning
SCC_OK Success
SCC_E_OPNOTSUPPORTED Operation not supported
SCC_E_FILEISCHECKEDOUT File is already checked out by this user

system
SCC_E_NOSPECIFIEDVERSION Specified an invalid revision

Usage PowerBuilder behavior When SccGet returns, PBSCC copies the file
written by the SCC provider into the work PBL or a PBL designated by the
user.
In PowerBuilder, the fOptions flags SCC_GET_ALL and
SCC_GET_RECURSIVE will not be used. lpFileNames will always be a list
of one file.
PowerBuilder will not create a temporary file in the local project path before
calling SccGet.
44
Description Called during initialization to find out what advanced options the SCC provider
supports. When a user invokes a command that supports advanced options,
PBSCC calls it again so that the SCC provider can display the dialog boxes for
those options.
Syntax SCCRTN SccGetCommandOptions (void *pvContext, HWND hWnd,

SCCCOMMAND iCommand, void **ppvOptions);
Argument passed
to provider Data type Value
pvContext void * Provider’s context structure,
allocated by the provider during
initialization
hWnd HWND PowerBuilder window handle.

Usually the client area of the Library
painter
iCommand SCCCOMMAND The command about which

PowerBuilder is querying or for
which the SCC provider should
display the advanced options dialogs
FOR INFO For a list of the
PowerBuilder commands that provide
access to advanced options, see Usage
below
ppvOptions void ** A NULL value or a pointer to a void

pointer
When PowerBuilder wants to query
the SCC provider about its advanced
option support, ppvOptions is set to
NULL
When PowerBuilder wants the SCC
provider to display its dialog boxes
for advanced options, ppvOptions
points to a NULL pointer
Value Meaning
SCC_OK Success
SCC_I_ADV_SUPPORT Provider supports advanced options
SCC_I_ADV_CANCEL The user canceled the advanced dialog
SCC_E_OPNOTSUPPORTED Provider does not support this function
45
Value Meaning
SCC_E_ISCHECKEDOUT Operation cannot be performed on a
checked-out file
SCC_E_ACCESSFAILURE Problem accessing the system

SCC_E_NONSPECIFICERROR Nonspecific error
Usage PowerBuilder behavior PowerBuilder calls SccGetCommandOptions

several times during initialization. Each time, the iCommand argument is set
to one of these command values:
♦ SCC_COMMAND_ADD for registering an object
♦ SCC_COMMAND_REMOVE for unregistering an object
♦ SCC_COMMAND_CHECKIN for checking in an object
♦ SCC_COMMAND_CHECKOUT for checking out an object
♦ SCC_COMMAND_OPTIONS for setting configuration options
♦ SCC_COMMAND_GET for getting a copy of an object
These constants are defined in the Microsoft header file SCC.H.
SCC provider actions During initialization, when PowerBuilder calls
SccGetCommandOptions with ppvOptions set to NULL, the SCC provider
should return SCC_I_ADV_SUPPORT if it supports advanced options for
the command specified in iCommand.
When the user invokes a command for which the SCC provider indicated
advanced support, PowerBuilder calls SccGetCommandOptions with
ppvOptions pointing to a NULL long value. The SCC provider should:
♦ Display one or more dialog boxes to let the user set advanced options
♦ Store the user’s settings in a data structure known to the provider
♦ Set *ppvOptions to the address of that data structure so that PBSCC can
pass the settings back to the provider when the user finishes with the
command
The SCC API does not provide a function call to tell the SCC provider to
deallocate the data structure. Therefore, it is assumed that the SCC provider
will retain the structure pointer and free this memory during SccUninitialize.
46
Additional PowerBuilder actions If the user clicks the Advanced button a

second time during the same command, PowerBuilder calls
SccGetCommandOptions again and passes the address of the data structure
back in *ppvOptions so that the SCC provider can retrieve the previous
settings.
Finally, when the user clicks OK in the PowerBuilder dialog box,
PowerBuilder calls the command’s API function. The function’s pvOptions
argument holds the address of the advanced options data structure.
Carryover of advanced option settings If the provider wants to apply
advanced settings to subsequent calls, it is up to the provider to save the
settings and apply them. PBSCC passes the data structure pointer to the
provider for one command only.
SccGetProjPath
Description Called when PBSCC connects and the current PowerBuilder application object
has not been configured for source control.
Syntax SCCRTN SccGetProjPath (void *pvContext, HWND hWnd, LPSTR lpUser,

LPSTR lpProjName, LPSTR lpLocalPath, LPSTR lpAuxProjPath, BOOL
bAllowChangePath, LPBOOL pbNew);
Argument passed
hWnd HWND PowerBuilder window handle. Usually

the client area of the Library painter
lpUser LPSTR The user ID specified by the user in the

PowerBuilder Configuration dialog box.
If the user ID changes during the SCC
provider’s SccGetProjPath processing,
the provider should put the current user
ID in this buffer
47
SccGetProjPath
Argument passed
lpProjName LPSTR The project name provided by the user in
the PowerBuilder Configuration dialog
box. If the value is blank, the provider
can prompt for a project name and return
the name in this buffer
PowerBuilder expects the provider to
create a new project if the named project
does not exist
lpLocalPath LPSTR The path specified by the user in the

PowerBuilder Configuration dialog box.
Both PBSCC and the provider write files
in this directory. If the user provides a
local path in the provider’s
SccGetProjPath dialog boxes, the
provider should return that path in this
buffer
After SccGetProjPath returns, the local
path must not be changed for the
duration of the source control session
lpAuxProjPath LPSTR Buffer where provider puts its own

project path or any other information
needed to open the project. PBSCC will
pass the string to SccOpenProject.
PBSCC does not use the information
bAllowChangePath BOOL Set to FALSE. The provider must not

change the local path during a source
control session
pbNew BOOL * Set to TRUE. PowerBuilder expects the

provider to create a new project if the
named project does not exist
Return value None.
Usage If the user connects and the application has not been configured for source
control, PowerBuilder prompts the user to provide project information.
PBSCC passes the information the user provides to SccGetProjPath. If the
information is incomplete, the provider can display its own dialog boxes to get
the information. If the specified project doesn’t exist, the provider should
create the project, displaying its own dialog boxes to get information from the
user as needed.
48
For each application object that has been configured for source control,
PowerBuilder stores information about the associated source control project.
When the user connects, PBSCC passes this information to SccOpenProject. It
doesn’t call SccGetProjPath.
SccHistory
Description Called when the user highlights one or more objects in a PBL and selects
Source>Registration Report.
Syntax SCCRTN SccHistory (void *pvContext, HWND hWnd, LONG nFiles, LPSTR
*lpFileNames, LONG fOptions, void *pvOptions);
Argument
passed to

workspace
nFiles LONG Number of files to be retrieved. Always 1

filename that the SCC provider uses to
determine what object to report history for
and to write a file containing a version of
the object, if the user requests it
pvOptions void * SCC provider-specific options. Always

NULL
Value Meaning
SCC_OK Success
49
SccInitialize
Value Meaning
SCC_I_RELOAD SCC provider modified the local version
of the file. IDE should reload the file.
Usage PowerBuilder behavior PowerBuilder calls SccHistory for each

highlighted object in the painter. It does not create a temporary file
containing the object.
SCC provider actions The SCC provider has control of the report facility
and displays all the dialog boxes for reporting the information to the user.
If the provider allows the user to get an object version based on the information
in the registration report, the SCC provider should write a temporary file
containing the object in the local project directory and return
SCC_I_RELOAD. PowerBuilder will prompt the user for a PBL name and
import the object.
The Microsoft SCC API does not provide a way to use SCC to request all the
revisions and comments for an object and does not support labels and filtering
by label. The dialog boxes the provider implements for SccHistory should
provide this functionality.
SccInitialize
Description Called when PowerBuilder connects to the source control system and when the
user changes projects—for example, by choosing another application object.
Syntax SCCRTN SccInitialize (void **ppvContext, HWND hWnd, LPSTR

lpCallerName, LPSTR lpSccName, LPLONG lpSccCaps, LPSTR
lpAuxPathLabel, LPDWORD pnCheckoutCommentLen, LPDWORD
pnCommentLen);
50
Argument passed to
ppvContext void ** The SCC provider can allocate a
context structure for a connection and
store the address of this work
memory at this location. All
subsequent SCC function calls will
pass back the Context pointer

painter
lpCallerName LPSTR The name of the SCC client, which is

PowerBuilder
lpSccName LPSTR Buffer where the SCC provider puts
its own name
lpSccCaps LPLONG A pointer to a long value whose value

is bit settings that the SCC provider
specifies to describe which API
functions it implements. Based on
this information, PowerBuilder can
hide or disable features. The provider
uses SCC_CAP_function bit settings
described in SCC.H
lpAuxPathLabel LPSTR Buffer where the SCC provider can

put a path. Not used by PBSCC
pnCheckoutCommentLen LPDWORD Pointer to a DWORD where the SCC

provider puts the maximum length it
allows for check-out comments
pnCommentLen LPDWORD Pointer to a DWORD where the SCC

provider puts the maximum length it
allows for comments other than
check-out comments
Return value SCCRTN. The provider returns one of the following values:
Value Meaning
SCC_OK Success
SCC_E_INITIALIZEFAILED Could not initialize
51
SccOpenProject
Value Meaning
If the provider returns any value other than SCC_OK, PowerBuilder displays
an error message to the user and tells the Library painter that connecting to
source control failed.
Usage PowerBuilder behavior PowerBuilder connects to the source control

system when the user chooses Source>Connect in the Library painter.
After the user has configured a source control system and has connected for the
first time, PowerBuilder connects automatically in the following situations:
♦ The user opens the first instance of the Library painter and PB.INI
contains a value for SourceVendor
♦ The user is connected to source control and double-clicks another
application object in the Library painter
♦ In the Application painter, the user creates a new application or opens a
different application when connected to source control
SCC provider actions PBSCC needs information from the SCC provider.
In the provider’s implementation of SccInitialize, the provider should fill in
the information at the locations passed by PBSCC. The information required
is:
♦ A pointer to the SCC provider’s context
♦ The name of the SCC provider
♦ Bit settings describing available functions in the source control system
♦ Maximum length of check-out comments allowed by the source control
system
♦ Maximum length of other comments allowed by the source control
system
SccOpenProject
Description Called after initialization to tell the provider to open a project.
52
Syntax SCCRTN SccOpenProject (void *pvContext, HWND hWnd, LPSTR

lpUser, LPSTR lpProjName, LPSTR lpLocalProjPath, LPSTR
lpAuxProjPath, LPSTR lpComment, LPTEXTOUTPROC
lpTextOutProc, LONG dwflags);
Argument
passed to
pvContext void * Provider’s context structure,
allocated by the provider during
initialization

painter
lpUser LPSTR The user ID passed by PBSCC. The

value comes from the application
object’s configuration information or
from SccGetProjPath
lpProjName LPSTR The project name passed by PBSCC.

The value comes from the application
from SccGetProjPath
lpLocalProjPath LPSTR The local path passed by PBSCC.

The value comes from the application
from SccGetProjPath. Both the
provider and PBSCC write files in
this directory
lpAuxProjPath LPSTR Additional information about the

project that PBSCC saved for the
provider. The value comes from the
application object’s configuration
information or from SccGetProjPath.
Not used by PBSCC
lpComment LPSTR Not used
53
SccOpenProject
Argument
passed to
lpTextOutProc LPTEXTOUTPROC If the provider reported support for
textout (SCC_CAP_TEXTOUT), a
pointer to the PBSCC callback
function for handling messages
If textout isn’t supported,
lpTextOutProc is NULL
FOR INFO For more about error
message handling and the callback
syntax, see "Error message handling"
on page 34
dwFlags LONG PBSCC passes the value

SCC_OP_CREATEIFNEW. If the
project named in lpProjName doesn’t
exist, the provider should create it
Return value SCCRTN. The provider returns one of the following values:
Value Meaning
SCC_OK Success
SCC_E_INITIALIZEFAILED Project could not be initialized
SCC_E_INVALIDUSER Invalid user name
SCC_E_PROJSYNTAXERR Invalid project syntax
SCC_E_UNKNOWNPROJECT Project unknown to SCC
SCC_E_INVALIDFILEPATH Invalid file path
SCC_E_NOTAUTHORIZED User not authorized
SCC_E_ACCESSFAILURE Unable to access SCC
Usage PowerBuilder actions If SccOpenProject returns successfully,

PowerBuilder saves the user ID in PB.INI and saves the project
specifications in the application’s configuration file. When the user connects
to source control again for the same application object, PBSCC uses that
information and does not prompt the user for it again.
FOR INFO For more about SCC configuration files, see "Configuration
information for SCC" on page 33.
54
Changing the configuration When the user chooses Source>Configuration

and changes any value (such as changing the user ID to log in as another
user), PBSCC reinitializes the source control connection. It calls
SccCloseProject and SccUninitialize to log out and calls SccInitialize and
SccOpenProject to sign on again. PowerBuilder saves the new information
in the configuration file and uses it for subsequent connections.
SccPopulateList
Description Called when the user selects Source>Registration Directory in the Library
painter. PBSCC prompts the provider to build the list of registered objects so
that PowerBuilder can display the list to the user.
Syntax SCCRTN SccPopulateList (void *pvContext, SCCCOMMAND nCommand,

LONG nFiles, LPSTR * lpFileNames, POPLISTFUNC pfnPopulate, void
* pvCallerData, LPLONG lpStatus, LONG fOptions);
Argument
passed to
pvContext void * Provider’s context structure, allocated
by the provider during initialization
nCommand SCCCOMMAND The command for which

PowerBuilder wants to populate a list,
which is SCC_COMMAND_GET
nFiles LONG Number of files in the lpFileNames

list. Always 0
lpFileNames LPSTR* The list of files that the IDE knows

about. Always NULL
pfnPopulate POPLISTFUNC Callback function for adding or

removing files from list. For its
prototype, see Usage below
pvCallerData void * Structure owned by IDE, which the

provider passes on to the callback
lpStatus LPLONG Array for the SCC provider to return

status flags. Not used by
PowerBuilder
55
SccPopulateList
Argument
passed to
fOptions LONG Set to 0, which means the value in
lpFileNames is a file, not a directory
Value Meaning
SCC_OK Success
SCC_E_NONSPECIFICERROR Nonspecific error
Usage PowerBuilder behavior When PBSCC calls SccPopulateList, it does not

pass a list of files. PBSCC adds an entry to its list each time the SCC
provider invokes the pfnPopulate callback function. When SccPopulateList
returns, PBSCC displays the list in the Registration Directory dialog.
SCC provider actions The SCC provider calls the function identified in the
pfnPopulate argument repeatedly, each time passing the name and status of
an object under source management. The callback function uses the _cdecl
calling convention.
The declaration for the callback function is:
typedef BOOL(*POPLISTFUNC) (LPVOID pvCallerData, BOOL
fAddRemove, LONG nStatus, LPSTR lpFileName);
Argument Data type Description

pvCallerData LPVOID Pointer to PowerBuilder data structure
that PBSCC passed to SccPopulateList
fAddRemove BOOL Indicates whether PowerBuilder should
add or remove the object. Values are:
♦ TRUE Add lpFileName to the list
♦ FALSE Remove lpFileName from
the list
nStatus LONG Flags showing the check-out status of
the file. The provider uses
SCC_STATUS bit settings to pass status
to PowerBuilder.
This information is not currently used
by PowerBuilder
56
Argument Data type Description

lpFileName LPSTR The name of an object under source
management. Some SCC providers
concatenate the local project path and
object name; others simply return the
object’s name. PowerBuilder accepts
either format
The callback function always returns TRUE.
SccRemove
selects Source>Clear Registration. It is called once for each highlighted object.
The provider should remove all registration information for the object from the
source control project.
Syntax SCCRTN SccRemove (void *pvContext, HWND hWnd, LONG nFiles,

*pvOptions);
Argument
passed to

workspace
nFiles LONG Number of files to be deleted from the
current project. Always 1
lpFileNames LPSTR * Pointer to an array of string pointers. Array

length is always 1. lpFileNames[0] names
the object to be deleted from the source
control archive. There is no actual file
lpComment LPSTR The string PowerBuilder Clear Registration

Function
57
SccRunScc
Argument
passed to
fOptions LONG Command flags. Set to
SCC_REMOVE_KEEP
pvOptions void * SCC provider-specific options. Set to

NULL (because PowerBuilder does not
support advanced options for this
command)
Value Meaning
SCC_OK Success
SCC_E_OPNOTSUPPORTED Operation not supported
SCC_E_ISCHECKEDOUT File is checked out and cannot be deleted

system
Usage PowerBuilder behavior For each selected item, PowerBuilder prompts the
user to confirm the clearing. Then if confirmed, PowerBuilder calls
SccRemove for that object.
There is no dialog box for clearing a registration, so there is no opportunity for
the user to specify advanced options.
SCC Provider actions The provider should remove all version information
from the source management system for the object identified in the
lpFileNames array.
SccRunScc
Description Called when the user selects Source>SCC Administration.
58
Available in PowerBuilder 6.0 or later.
Syntax SCCRTN SccRunScc (void *pvContext, HWND hWnd, LONG nFiles,

LPSTR *lpFileNames );
Argument
passed to
hWnd HWND Window handle of the Library painter’s workspace
nFiles LONG Number of elements in lpFileNames. Always 0
lpFileNames LPSTR * A pointer to an array of strings. The array is

always empty
Value Meaning
SCC_OK Success

system
Usage PowerBuilder does not support advanced options for SccRunScc.

SCC provider actions The SCC provider launches the source control
administration tool as a separate process. Changes by the user affect the
archive only and don’t need to be communicated to PowerBuilder.
SccUncheckout
selects Source>Clear Checkout Status. It is called for each highlighted object.
The provider should mark the object as checked in.
Also called when a check-out fails because the checked-out file cannot be
imported into the PBL.
59
SccUncheckout
Syntax SCCRTN SccUncheckout (void *pvContext, HWND hWnd, LONG nFiles,

LPSTR *lpFileNames, LONG fOptions, void *pvOptions);
Argument
passed to

workspace
nFiles LONG Number of files whose check-out status is to be

cleared. Always 1

length is 1. lpFileNames[0] contains a filename
that the SCC provider uses to identify the object
whose status is being cleared. There is no need
for the provider to write a file containing the
archived object
FOR INFO For information about the string, see
"Filenames passed as arguments to SCC
pvOptions void * SCC provider-specific options. Always NULL

(because there is no dialog box for the user to
specify advanced options)
Value Meaning
SCC_OK Success

system
SCC_E_NOTCHECKEDOUT File is not checked out by this user
60
Usage PowerBuilder does not display a dialog box for Clear Checkout Status.
Therefore, there is no opportunity for the user to specify advanced options.
61
SccUncheckout
62

Powerbuilder®: Powerbuilder Apis and Interfaces

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Powerbuilder®: Powerbuilder Apis and Interfaces

Transféré par

Droits d'auteur :

Formats disponibles

PowerBuilder APIs and Interfaces

Using the PowerBuilder Test interfaces

Global variable An object variable belongs in the global variable section:

To connect to the RichTextEdit or DataWindow interface, specify the name of

In other development environments, call the function that connects to an OLE

Set MainObj = CreateObject("PowerBuilder.Test")

Text1 would hold the value "Version 6.0".

Declare Function FindWindowEx Lib "USER32"

Const lpDWClassName = "pbdw60"

hwndFrameTop = FindWindow(lpFrameClassName, 0&)

efSource = "&H" + Hex(hwndDW) + "&"

MDI client area MDIClient

RichTextEdit control PBRTC60

DataWindow control PBDW60

Runtime SDI window FNWND360

Window class names will change

The first subroutine does all the initialization:

Const lpRTEClassName = "PBRTC60"

hwndFrameTop = FindWindow(lpFrameClassName, 0&)

Set RTEObj = Nothing

Another subroutine checks the insertion point:

MyBool = RTEObj.GetInsertionPoint(line, col)

The next subroutine sets the selection to some arbitrary values:

MyBool = RTEObj.SetSelection(fl, fc, tl, tc)

Dim hwndDW As Long

hwndFrameTop = FindWindow(lpFrameClassName, 0&)

Set DWObj = Nothing

PowerBuilder.Test must be registered in the system registry. When you install

ObjectClassName string Gets the class of an object

ObjectFactory BOOL Creates an interface (for future use)

ObjectIUnknown IUnknown Establishes a basic IUnknown

VersionDetails BOOL Provides full version information for

Syntax BOOL IsPowerBuilderObject ( HWND Object )

Usage Getting an object handle can be a difficult programming exercise. Programs

Syntax string ObjectClassName (HWND Object )

Syntax BOOL ObjectFactory ( HWND WindowObject, string InterfaceID, REF

Return value BOOL. Returns TRUE if the interface is successfully created.

Syntax IUNKNOWN *ObjectIUnknown ( HWND Object )

Return value IUnknown. A reference to the interface.

Syntax BOOL VersionDetails ( REF long VersionMajor, REF long VersionMinor,

0000.0010 Win32 build (includes Win32 emulation builds)

0000.0020 Win16 build

0000.0040 Macintosh build

0000.0080 OS/2 build

0000.0100 UNIX build (of any flavor)

0001.0000 UNICODE build

0002.0000 Double Byte Character Set (DBCS) build

All other bits are reserved.

Column long The number of the current column,

ItemAsNumber double (Read-only) The value at the current

ItemAsString string (Read-only) The value at the current

Row long The number of the current row, which

RowCount long (Read-only) The number of rows in the

GetItemDateTime BOOL For a column whose data type is

GetObjectAtPointer BOOL Reports the object and row number

IsSelected BOOL Reports whether a row is highlighted

SaveAs BOOL Saves the contents of the DataWindow

SelectedRow BOOL Reports the selected row in the

SelectRow BOOL Highlights or unhighlights a row in a

SetAllEvents BOOL Enables all PowerScript events for the

Syntax string Describe ( string Propertylist )

Syntax BOOL GetChild ( string ChildName, REF HWND ChildDW )