Title: Arial 28pt.

1
PWB516 Using Source Control Effectively with
PowerBuilder
Paul A. HoranTeamSybase Senior Architect -
VCI paulh_at_vcisolutions.com Mike Cobb Software
Engineer Sybase mike.cobb_at_sybase.com August
15-19, 2004
2
Session Agenda

• Audience Poll Whos Using PB/SCC Today?
• Which version of PowerBuilder?
• Which SCC Providers?
• Architectural Changes introduced in PB8
• Discussion and Demo of Basic Functionality
• Add to/Remove from Source Control
• Adding New Users and Workstations
• Check Out/Refresh Status/Check In
• Adding New Objects and PBLs to Targets
• Get Latest Version vs. Bootstrap
  Import/Import_Only
• Discussion on Best Practices
• Mike Cobb PB10 Enhancements and Changes
• Questions?

3
Audience Polling Whos Using What?

• Version Build of PowerBuilder?
• PB7.x and earlier?
• PB8?
• PB9?
• Source Control Provider?
• PBNative
• Microsoft Visual Source Safe
• Merant PVCS/VM (Serena ChangeMan??)
• Rational ClearCase
• Borland StarTeam
• Perforce
• CVS w/ Jalindi Igloo or PushOK interface?
• Others?

4
SCC Challenges for PowerBuilder Developers

• SCC Tools are designed for 3GL environments
• C/C, VB, Java, Pascal, COBOL, Fortran
• Code stored on the file system as ASCII text
  files
• But PowerBuilders 4GL stores its code inside
  PBLs
• Versioning the PBL itself is useless
• SCC tools couldnt peek inside the PBL to see
  the individual objects
• Every SCC vendor had their own proprietary
  interface API
• The Solution?
• Microsoft to the rescue (!) with their SCC API
  (circa PB5)
• More Challenges?
• SCC metadata was stored right in the PBL itself
• PBNative was a separate codeline within the IDE
• No facility to rebuild PBLs directly from Source
  Code archives

5
Architectural Differences introduced in PB8

• PB7 and earlier
• Registered set of PBLs out on the LAN
• SCC provider-managed repository
• SCC metadata stored in the PBL
• Objects were checked out from the registered
  PBLs to a work PBL
• Write locks on PBLs could result in file I/O
  errors during check in/out
• Sync process required on each machine

• Typical SCC Operation
• w_main registered from the T\ drive
• User A checks out w_main to C\ drive
• User B sees checkout status change
• User A checks w_main back into T\
• w_main deleted from local work PBL
• Users A and B must both sync from T\

6
Architectural Differences introduced in PB8

• PB8 and current
• No need for registered PBLs on the LAN
• SCC info stored in the SCC repository
• Local Root Folder on each machine
• No work or checkout PBLs
• No chance of File Locks when running or debugging
  from within the IDE.
• Sync process is called Get Latest Version

A
C
\Main.pbl w_main
SCC Repository w_main.srw
C
\Main.pbl w_main

• Typical SCC Operation
• User A registers w_main from his machine
• User B does a GLV to retrieve w_main
• User A checks out w_main. User B sees icon
  change upon the next Refresh Status
• User A checks in revised w_main. User B sees
  icon change upon Refresh Status
• User B does a GLV and retrieves w_main
• GLV on build machine prior to a Compile

B
C
\Main.pbl w_main
7
Basic SCC Operations

• Setup and Initial Registration
• Step 1 Get the PBLs off the LAN! No more
  shared PBLs
• Step 2 Agree on a common Folder structure for
  ALL developers to adopt. This includes the
  placement of PBW and PBT files, as well as PBLs
• Sample folder structure
• ltdrivegt\ \ProjectName \Version
  PROD, DEV, QA, Rel3.2 \Source
  Local Root Folder containing all PBW files
  \Target1 Contains .PBT file
  for Target1
• \Tgt1_PBLs PBLs specific to
  target 1 \Target2 Contains
  .PBT file for Target2 \Tgt2_PBLs
  PBLs specific to target 2
• \Shared Parent folder for all
  shared libraries
  \PFC Foundation Class PBLs
• Step 3 Register objects into the SCC
  repository from a single workstation
• DEMO PBNative example using PFC-based sample
  application

8
Basic SCC Operations

• Setup of Additional Workstations and Developers
• No need to re-register the code from another
  workstation
• Step 1 Copy entire Local Root Folder from
  workstation A to workstation B
• Step 2 Open the workspace on workstation B, and
  set the SCC properties
• DEMO Continued example with PBNative

9
Basic SCC Operations

• Check Out
• PB gets the tip revision from SCC repository
  into LRF
• PB locks the object in the SCC repository
• PB imports the object into the PBL, overwriting
  the current object
• PB sets the object status icon to checked out to
  ME
• If Delete .. Files is ON, PB deletes the
  exported source file
• Undo Checkout
• PB gets the tip revision from SCC repository
  into LRF
• PB imports the object into the PBL, overwriting
  the current object
• PB releases the lock on the object in the SCC
  repository
• PB sets the object status icon back to
  available
• If Delete .. Files is ON, PB deletes the
  exported source file
• DEMO Continued example with PBNative

10
Basic SCC Operations

• Refresh Status
• PB maintains an internal table of object names
  with status timestamps
• When a PBL is expanded in System Tree or Library
  Painter, PB looks for any objects that it
  considers stale.
• The status of all stale objects are refreshed
  with SccQueryInfo() calls
• Status flags are written to the ltworkspacegt.PBC
  file upon close of workspace
• Check In
• PB exports the source of the object into the LRF
• PB calls SCC provider to check in the exported
  source file
• PB releases the lock on the object in the SCC
  repository
• PB sets the object status icon back to
  available
• If Delete .. Files is ON, PB deletes the
  exported source file
• DEMO Continued example with PBNative

11
Basic SCC Operations

• Get Latest Version
• Used to synchronize a local workstation with the
  latest version of all objects
• PB will determine which objects it considers to
  be out of sync
• Overriding that list by clicking the Select All
  button is NOT ADVISED.
• PB will grab the tip revisions from the SCC
  provider and import them locally
• This can easily be scripted with either PowerGen
  or OrcaScript
• DEMO Get Latest Version with OrcaScript batch
  file

12
Basic SCC Operations

• Get SPECIFIC Version
• There may be times you need to reconstruct a
  working environment from a previously released
  configuration.
• Example
• DEV is working on a big project that involves
  several critical objects
• QA is testing the next release candidate, and
  its not yet ready for GA
• Someone finds a critical bug in the PROD release

• DEMO Bootstrap Import of PROD label using
  PowerGen

13
Tips and Techniques

• Virus Scanning software
• Disable completely if possible
• Filter out .SR and .PB file extensions
• Get Latest Version operations
• Perform a target-wide Refresh Status first, then
  the GLV
• Experiment with the SccMaxArraySize setting in
  PB.INI (default is 25)
• Do NOT use GLV to implement a Bootstrap Import
  (Select All button)
• Low Bandwidth environments (WANs, VPNs)
• Set Refresh Status rate to its MAX value (600
  minutes)
• Perform a target-wide Refresh Status upon startup
  
• Perform all subsequent Refresh Status operations
  manually
• Pressure your SCC provider to implement Diff by
  Version Number!!
• Above all, dont live in the past (PB7 and
  earlier)
• Local code - dont try and share PBLs on the LAN.

14
QUESTIONS??
?
?
?
?
?
?
?
15
PWB516 Using Source Control Effectively in
PowerBuilder Part 2 Whats New in PB10
Michael Cobb Staff Software Engineer Sybase
mikecobb_at_sybase.com August, 2004
16
Whats New in PowerBuilder 10

• New source encoding formats for unicode
  PowerBuilder
• Unicode
• UTF8
• ANSI/DBCS
• HEXASCII
• Import / Export PB objects
• New ORCA and Orcascript Features
• SCC Vendor Integration
• PB.INI settings
• Bug fixes
• SCC, ORCA, and Orcascript available for Pocket
  PowerBuilder 1.5.2

17
Source Encoding Formats - Unicode

• Export Header Prefix 0xFFFE
• Unicode is the default encoding when you export
• Remember HEXASCII is the encoding that is
  always used for SCC operations

18
Source Encoding Formats UTF8

• Export Header Prefix 0xbbefbf
• Half the size of unicode for most PB objects

19
Source Encoding Formats ANSI/DBCS

• Export Header Prefix None

• ANSI/DBCS is the only encoding that PowerBuilder
  9
• can import successfully

20
Source Encoding Formats - HEXASCII

• Export Header Prefix HA
• Encoding format used with all SCC export
  operations
• HAPBExportHeaderw_main.srw
• string title "HEX2c189d063ENDHEXjianti
  HEX2417ed49aENDHEXfanti
  HEX3dd d0ddd0ddd0ENDHEXHanwen '"
• Chosen so that all visual diff utilities will
  process PB10 source

21
Import / Export PB Objects - Tips

• If the object source contains all ANSI
  characters, the only difference between HEXASCII,
  UTF8, and ANSI/DBCS format will be the export
  header prefix. Delete the prefix in a text
  editor, and you can import that source into
  PB9. HAPBExportHeaderw_main.srw
• You can share the same SCC repository between PB9
  and PB10 as long as you perform all checkins
  using PB9 IDE. Repository will contain objects
  in ANSI/DBCS encoding.
• Import processing detects the encoding format
  automatically

22
New ORCA Features

• ANSI or Unicode client API
• PBORCA_ConfigureSession
• PBORCA_SccSetPassword
• PBORCA_SccSetTarget enhancements for IMPORTONLY
• PBORCA_SccConnectOffline
• IMPORTONLY OUTOFDATE
• IMPORTONLY EXCLUDE_CHECKOUT

23
ORCA - ANSI / Unicode API

• Existing ANSI client applications may be
  recompiled with few if any code changes required
• Unicode clients use compiler directives
• /D UNICODE /D _UNICODE
• Orcascript command files remain ANSI

24
PBORCA_ConfigureSession()

• Allows the client to configure the behavior of
  subsequent requests. Settings stay in effect for
  the duration of the session or until the client
  calls PBORCA_ConfigureSession again. Be sure to
  specify all of the settings each time you call
  PBORCA_ConfigureSession.
• When to overwrite files on the file system
• Export encoding format
• Include export header or not
• Export with or without binary component
• Export to a file or to a memory buffer
• Import encoding format
• ORCA only - not implemented in Orcascript

25
PBORCA_SccSetPassword()

• Specific enhancement for integration with Borland
  StarTeam. Prevents a modal dialog from appearing
  during SCC connection.
• Scc Set Connect Property Password password

26
PBORCA_SccConnectOffline()

• Only applicable with IMPORTONLY refresh option
• Typical scenario
• Synchronize your SCC client view at the office
• Take your laptop home
• Refresh and rebuild application overnight while
  disconnected
• Orcascript example
• start session
• Scc set connect property localprojpath ""
• Scc set connect property logfile ".\orcascr.log"
• Scc connect offline
• Scc set target ".\dbpaint.pkt" "refresh_all
  importonly"
• Scc refresh target "full"
• Scc close
• end session

27
IMPORTONLY OUTOFDATE

• OUTOFDATE now allowed with IMPORTONLY refresh
  option
• Usual diff strategy does not apply with
  IMPORTONLY. Instead, compare source in PBL with
  source on local project path .
• A better way to perform target-wide
  GetLatestVersion
• Synchronize your SCC client view
• Refresh and rebuild application with a batch job
• Orcascript example
• start session
• Scc set connect property localprojpath ""
• Scc set connect property logfile ".\orcascr.log"
• Scc connect offline
• Scc set target ".\dbpaint.pkt" "importonly
  outofdate"
• Scc refresh target "full"
• Scc close
• end session

28
IMPORTONLY EXCLUDE_CHECKOUT

• Do not refresh objects checked out to current Scc
  user
• Radically different behavior if Scc Connect
  Offline is chosen
• When connected to SCC, obtain checkout status of
  each object via SccQueryInfo
• When offline, obtain checkout status from the PBC
  file
• When offline, Scc Get Connect Properties
  workspace is required in order to obtain PBC
  file
• Usage Note
• Use IMPORTONLY OUTOFDATE EXCLUDE_CHECKOUT
  instead of a target-wide GetLatestVersion request
  from the IDE. Same objects will be imported, but
  Orcascript will rebuild the target fully and can
  be done off-hours.

29
SCC Vendor Integration

• Merant Version Manager 8 SccQueryInfoEx
• Merant Dimensions 8 SccQueryInfoEx
• Merant TrackerLink 8 SccQueryInfoEx
• Borland StarTeam SccQueryInfoEx
• Rational ClearCase SccQueryInfoEx
• QVCS 3.6 SccQueryInfoEx
• Telelogic Synergy Case Sensitivity
• Perforce Diff PBL vs LPP
• Ecrane PowerGen ORCA import/export

30
PB.INI Settings

• SccMaxArraySize 25 nnn
• SccLogLevel 1 2 3
• SccMultiThread 1 0
• SccDiffStrategynn
• SccExtensions 1 0
• SccCaseSensitive 0 1
• SccCOImport full inc outofdate
• SccRBImport full inc
• SccGLImport full inc
• SccUCImport full inc

31
CR 345547 Refresh Lib Painter Listview
Click on PBL in Library Painter treeview launches
secondary thread to refresh the listview.
32
CR 233718 Get Latest PBT file

• When you get the latest version of a PBT file, PB
  checks to see if the library list for the target
  has changed. If so, new PBLs are created on your
  local project path and the new library list takes
  effect immediately.
• NOTE If a new PBL is created, it will be EMPTY.
  You should perform an additional get latest
  version to populate the new PBL with objects from
  the SCC repository.

33
Changing SCC Providers
Changing SCC providers makes the PBC file, local
PBG files, and version information stored in
PBLs obsolete
34
Miscellaneous Bug Fixes

• CR 345593 fix problems with object names gt 37
  characters
• CR 344775 fix multi-file checkin involving PB
  objects and Web Target objects
• CR 341715 fix GPF if PB10 tries reading a PBC
  file created by PB9
• CR 357148 fix diff not done icon for PBT file
  and web target files under Perforce
• CR 294038 Silent Orcascript connection to
  StarTeam
• CR 341029 Extra backslashes generated in PBT
  project entries
• CR 340458 Improve SccAdd error messages
• CR 336807 fix GPF in SccAdd if File already
  exists error encountered