PWB516: Using Source Control Effectively with PowerBuilder

1. PWB516: Using Source Control Effectively with PowerBuilder Paul A. Horan[TeamSybase] Senior Architect - VCI paulh@vcisolutions.com Mike Cobb Software Engineer – Sybase mike.cobb@sybase.com August 15-19, 2004

2. Session Agenda • Audience Poll – Who’s 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 – Who’s 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 PowerBuilder’s 4GL stores its code inside PBLs… • Versioning the PBL itself is useless • SCC tools couldn’t “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. A C: \myWork.pbl SCC Repository w_main.srw \Main.pbl w_main T: \Main.pbl w_main B C: \myWork.pbl \Main.pbl w_main 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: • <drive>:\ \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 <workspace>.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. PROD (1.0) QA (1.1) QA (1.1) DEV (2.0) CR 1234 QA (1.1.1) EBF (1.0.1) 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 it’s 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, don’t live in the past (PB7 and earlier) • Local code - don’t try and share PBLs on the LAN.

14. QUESTIONS?? ? ? ? ? ? ? ?

15. PWB516 Using Source Control Effectively in PowerBuilder Part 2 – What’s New in PB10 Michael Cobb Staff Software Engineer – Sybase mikecobb@sybase.com August, 2004

16. What’s 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 HA$PBExportHeader$w_main.srw string title = "$$HEX2$$c189d063$$ENDHEX$$jianti $$HEX2$$417ed49a$$ENDHEX$$fanti $$HEX3$$dd d0ddd0ddd0$$ENDHEX$$Hanwen ~'" • 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.HA$PBExportHeader$w_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 } • SccDiffStrategy=nn • 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 > 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