E177 Best Practices for SCC Integration with PowerBuilder 8.0 and 9.0

1. E177Best Practices for SCC Integrationwith PowerBuilder 8.0 and 9.0 Paul HoranVideo Communications Michael CobbSybase, Inc.

2. Part 1 -SCC Integration in PB8 Paul HoranVideo Communications

3. PowerBuilder 8.0 SCC Integration • Brief Introduction to Source Code Control • Understanding the SCC API • PB 8.0 Architecture Changes for SCC • Best Practices • Future Enhancements • Questions

4. Introduction to Source Code Control Benefits of Using Source Code Control • Secure Repository for Digital Assets • Version Control over Object/File Revisions • Traceability of Changes • “Time Travel” • Preventing Concurrent Object/File Access • Integrated Change Management/Defect Tracking

5. Introduction to Source Code Control Inside the SCC Repository myApp • Projects • Folders and Subfolders • Archives • Each revision tracked with a specific Version Number • Outermost revision is the “tip” • Many SCC tools use “Delta” or “Reverse Delta” file formats. SRC d_ph.srd d_mc.src DOC setup.txt

6. Introduction to Source Code Control SCC Terminology • Server Configuration – Maps to a physical repository • Project – Relates to a “releasable” product • View – A subset of objects in the Project. • Folders – Helps to better organize Projects/Views • Archives – Actual versionable objects and files • Labels – Names that identify specific archive revisions • Working Folder – The location where files are edited.

7. Revision Labels, applied to specific sets of changed objects Revision Labels, applied to specific sets of changed objects View Labels, applied to ALL objects associated to the View View Labels, applied to ALL objects associated to the View Introduction to Source Code Control Examining the Source Code Lifecycle File A File B File C File D File E File F

8. Understanding the SCC API • SCC is an industry-standard API that most source code control vendors support • SCC API provides: • Accurate status information on repository archives • Subdirectory hierarchies to be maintained • Operations to be performed on multiple objects through one API request

9. Understanding the SCC API More SCC Terminology • Local Project Path: the location on your local machine where PB IDE sees the exported source files. • It MUST contain the current Workspace file (*.pbw) • Therefore, this location is the same for all Targets • SCC Working Folder: the folder where the SCC tool places the working copies of specific objects/files. • The SCC tool uses this folder when using ITS user interface to work with archives. • Each SCC View/Folder can use a different Working Folder. NOTE: These DO NOT have to be the same location!

10. Understanding the SCC API • PB must EXPORT the object source to files on the local project path prior to calling: • SccAdd() “Add to Source Control” • SccCheckin() “Check In” • SccDiff() “Compare Differences” • PB must IMPORT object source files from the local project path after calling: • SccCheckout() “Check Out” • SccGet() “Get Latest Version” • SccUncheckout() “Undo Check Out”

11. Understanding the SCC API Example – “Checkout” • PB exports backup copies of objects (for rollback) • PB calls SccCheckout(). SCC Provider writes latest revision to Local Project Path • PB calls SccQueryInfo() to verify that objects were successfully checked out • PB imports objects into target PBLs • PB updates status cache and refreshes IDE • PB commits transaction & deletes backups

12. Understanding the SCC API Example - “Check In” • PB exports syntax of objects to be checked in to Local Project Path • PB calls SccCheckIn(). Scc Provider updates revision history in its Archive Directories and unlocks the files • PB calls SccQueryInfo() to verify successful checkin • PB updates status cache and refreshes IDE

13. PB 8.0 Architecture Changes for SCC • SCC status information was removed from PBLs • Eliminated the need for shared PBLs on the network • Use SccQueryInfo() to obtain status information • New Icons in IDE • Can now see “out-of-sync” status • New “Offline Mode” • Perform Target-wide SCC operations • Support directory hierarchies and sub-projects • Eliminate the “work” PBL

14. PB 8.0 Architecture Changes for SCC • Make SCC connection a Workspace property • Support Web Targets under source control • Allow target-wide SCC operations • New “CheckView” dialog • New PBW, PBT, PBG, and PBC files • Replace “Old” PBNative with an SCC provider

15. PB 8.0 Architecture ChangesEliminate Shared PBLs on Network • Private workspace for each developer • No file locking problems when running or debugging an application • Working “Offline” now possible • Reduce Network File I/O • Status information for objects in a workspace is now stored in a hash table in memory

16. PB 8.0 Architecture ChangesRemove Status Information From PBLs • Status information in PBL was unreliable • Registration PBL had to reside on a network drive and had to be shared among team members • Caused file locking problems when running or debugging an application • Inefficient network file I/O to obtain status information • Working offline requires private workspace on local drive

17. PB 8.0 Architecture ChangesUse SccQueryInfo() for Status Info • Get reliable status information directly from SCC Provider • Status cache populated as needed • Performance impact to be addressed in future release • Status cache stored in hash table in memory • Instant access to information • Configurable refresh rate • Optional feature to detect local objects out of synch • Serialize status cache at workspace shutdown (.PBC file) • Offline mode uses .PBC file for most recent status info

18. PB 8.0 Architecture ChangesEliminate the Work PBL • “Obsolete” vestige of old PBNative paradigm • Status information no longer stored in PBLs • Each developer now has his own local workspace • Unnecessary for SCC operations • Simplify Checkin and Checkout processing • Eliminate 4 steps from successful checkout • Eliminate 8 steps from successful checkin • Vastly simplifies rollback processing

19. PB 8.0 Architecture ChangesNew Icons in PB 8.0 IDE

20. PB 8.0 Architecture ChangesNew “Offline” Mode • Great for developers with laptops • Extremely efficient • Status information obtained from serialized status cache (.PBC file) created during the last workspace shutdown • Allows offline editing of objects already checked out • Enforces read-only attributes of objects not checked out

21. PB 8.0 Architecture ChangesPerform SCC Operations on Multiple Objects • Add many objects with one SCC API call • Faster and more efficient • “Advanced” attributes apply to all objects • Checkout objects from multiple PBLs in a target • Impossible under PB 7.0 • Three-pass compile / import resolves mutual dependencies

22. PB 8.0 Architecture ChangesSupport Directory Hierarchies • Absolute Requirement for Web Targets • Allows PB developers to group objects in subdirectories on local workstation and in archive directories • Arrange objects logically • Allows objects with the same name to exist in different archive directories

23. PB 8.0 Architecture ChangesSCC Connection is a Workspace Property • In PB 7.0. SCC connection was an application property • In PB 8.0 applications are now considered targets. You can develop multiple targets at once under a workspace • Keep SCC connection when moving from one target to another within a workspace • Multiple targets can share a common PBL within a workspace • SCC connection info stored in Windows registry – no more .CFG files and PB.INI entries • HKCU\Software\Sybase\PowerBuilder\8.0\Workspace\workspace_name\SourceControl

24. Workspace Properties Source Control Tab New ConnectionProperties

25. PB 8.0 Architecture ChangesSupport Web Targets Under Source Control • PB 8.0 supports source control for Web Targets • PB Targets and Web Targets can both co-exist under one source-controlled workspace • All Web Target directories must exist under the local project path

26. PB 8.0 Architecture ChangesAllow Target-Wide SCC Operations • PB 8.0 lets you perform an SCC operation for an entire target • Right Mouse Click on Target Icon • “Get Latest Version” to synchronize local target with SCC Provider • Choose “Select Multiple Files Contained Within this Target” • New CheckView dialog automatically selects objects that either do not exist locally or are out of synch • Three-pass compile/import resolves mutual dependencies

27. PB 8.0 Architecture ChangesNew CheckView Dialog

28. PB 8.0 Architecture ChangesNew SCC-related Files • .PBW file Workspace file • .PBT file Target file • .PBG file Relates an object to a PBL • .PBC file Offline Status Cache • .PRP file Used by PBNative Only PBT and PBG files get registered to Source Control

29. PB 8.0 Architecture ChangesNew PBNative is an SCC Provider • Old PBNative had to be eliminated in order to re-architect PB 8.0 source control • New PBNative is just another SCC Provider • Uses a directory hierarchy on a network drive instead of a registration PBL • Uses .PRP files in archive directories to record checkout status • Only latest revision kept on archive directory • No revision history available • SccDiff() can be configured (new feature)

30. Configuring Visual Diff Utility for PBNative Some Visual Diff Tools Available - P4diff.exe from Perforce Windiff.exe from Microsoft (part of the Visual Studio Tools install)

31. Best PracticesDesigning Your Directory Hierarchy • In PB 8.0 all targets that are under source control within a workspace must reside on the same hard drive • Best practice is to put the .PBW (workspace) file in the local project path directory. All .PBT (target) files and objects associated with each target should reside in sub-directories under the local project path.

32. Best PracticesDesigning Your Directory Hierarchy

33. Best PracticesSetting Up SCC Integration in PB8 • In PB 8.0, all targets that are under source control within a workspace must reside on the same hard drive. • The .PBW (workspace) file must reside in the local project path directory. • All .PBT (target) files and objects associated with each target should reside in sub-directories under the local project path. • Register PB objects from a single workstation first, then XCOPY the entire folder structure to each new machine. • Web Targets – Use “File > New > Target > Source Controlled Web Target” wizard.

34. Best PracticesTips and Recommendations • Unless disk space is an issue, do NOT uncheck “Delete PowerBuilder-generated Object Files” • “Perform DIFF on status update” will execute faster; • SCC tool will not report object status as “Missing” • Do NOT use the “Select All” button in the “Get Latest Version” dialog (in PB8). • Some key 3rd-party utilities: • PowerGen www.ecrane.com • PBDelta www.pbdr.com

35. Sybase Developer Network (SDN) Additional Resources for Developers/DBAs • Single point of access to developer software, services, and up-to-date technical information: • White papers and documentation • Collaboration with other developers and Sybase engineers • Code samples and beta programs • Technical recordings • Free software • Join today: www.sybase.com/developer or visit SDN at TechWave’s Technology Boardwalk

36. Part 2 -SCC Integration in PB 9.0 Michael CobbSybase, Inc.

37. Goals for SCC features in PB 9 • Automated target refresh • Improve performance of status queries • Improve detection of out of sync objects • Closer integration with SCC providers • User enhancement requests

38. Automated target refresh • ORCA / SCC integration (new) • Batch build procedure with no operation intervention • Rebuild PBLs from scratch • Refresh PBLs • Do not overwrite checked out objects • Refresh from a previous version label or view • OrcaScript utility (new) • Scripting language for ORCA API

39. Automated target refresh ORCA vs Orcascript • ORCA is a “C”language programming interface that allows Sybase partners to develop new tools to simplify the building and deployment of PowerBuilder applications. Separate license required. • Orcascript is a command line utility that exposes ORCA functionality to PowerBuilder developers. It is included with PB 9 Enterprise and Professional Editions.

40. New ORCA APIs for SCC Integration • PBORCA_SccGetConnectProperties • PBORCA_ SccConnect • PBORCA_ SccSetTarget • PBORCA_ SccExcludeLibraryList • PBORCA_ SccRefreshTarget • PBORCA_SccGetLatestVersion • PBORCA_ SccClose

41. How Orcascript works • User programs a .DAT file containing Orcascript commands. One command per line. Most Orcascript commands correspond to a specific ORCA API call. • User executes Orcascr9.exe from DOS command line. Required argument is the name of the .DAT file containing Orcascript syntax to be interpreted and run. Example: ORCASCR9 c:\testbld\bldqadb.dat

42. OrcaScript Example #1Bootstrap a PB Application start session scc get connect properties “c:\testbld\testbld.pbw” scc connect scc set target “c:\testbld\qadbtest\qadbtest.pbt” “refresh_all” scc refresh target “full” scc close end session

43. Orcascript Example #1 Summary • Connects to SCC repository, creates the .\qadbtest directory and obtains latest version of \qadbtest\qadbtest.pbt • Sets the library list and current application. Creates directories and empty PBLs if they do not already exist • Uses PBG files in repository to obtain a list of all objects that belong to the libraries in the library list. Issues SccGetLatestVersion for each object. • Imports each object into the appropriate PBL and performs a full application rebuild

44. OrcaScript example #2Create PBDs and Executable Start session Set liblist “.\qadbtest\qadbtest.pbl” “.\shared_obj\shared_obj.pbl”“.\chgreqs\chgreqs.pbl”“.\datatypes\datatype.pbl” Set application “.\qadbtest\qadbtest.pbl” “qadbtest” build library “.\shared_obj\shared_obj.pbl” "" pbd build library “.\datatypes\datatype.pbl” "" pbd build library “.\chgreqs\chgreqs.pbl” "" pbd build executable “.\qadbtest\qadbtest.exe” ".\emp.ico" ".\qadbtest.pbr" "nyyy" End session

45. Orcascript Example #2 Summary • No SCC connection required. Set library list and current application via standard ORCA APIs • Builds PBDs for three support libraries in the application. No .PBR file associated with these PBDs. • Build Pcode executable qadbtest\qadbtest.exe. • Emp.ico will be icon associated with the exe • Qadbtest.pbr is the resource file for the exe • “nyyy” means that objects from the first PBL in the library list must be included in the exe. Objects from the last threelibraries in the library list are PBDs, so do not include theseobjects into the exe.

46. OrcaScript Example #3Nightly Refresh Operation start session scc get connect properties “c:\testbld\testbld.pbw” scc connect scc set target “.\qadbtest\qadbtest.pbt” “outofdate exclude_checkout” scc refresh target “incremental” build library “.\shared_obj\shared_obj.pbl” "" pbd build library “.\datatypes\datatype.pbl” "" pbd build library “.\chgreqs\chgreqs.pbl” "" pbd build executable “.\qadbtest\qadbtest.exe” ".\emp.ico" ".\qadbtest.pbr“ "nyyy" scc close end session

47. Orcascript Example #3Summary • Connects to SCC repository, creates the .\qadbtest directory and obtains latest version of \qadbtest\qadbtest.pbt • Sets the library list and current application. • Compares differences to determine which objects are out of sync in the library list PBLs. Only imports out of sync objects that are not currently checked out by the current user. • Performs incremental rebuild of the application • Builds 3 .PBD files and .EXE for the application. Note that build library and build executable may be executed from the same runtime environment established by scc set target. • Closes Scc connection and orcascript session

48. Orcascript Example #4Sharing common PBLs among multiple Targets • Target QADBTEST • Qadbtest.pbl Refresh PBL & Create .EXE • Shared_obj.pbl Refresh PBL & Create .PBD • Datatype.pbl Refresh PBL & Create .PBD • Chgreqs.pbl Refresh PBL & Create .PBD • Target DBAUTO • DBAuto.pbl Refresh PBL & Create .EXE • Shared_obj.pbl no work necessary • Datatype.pbl no work necessary • Chgreqs.pbl no work necessary • Target QAMGR • QAMgr.pbl Refresh PBL & Create .EXE • Shared_obj.pbl no work necessary

49. Orcascript Example #4Sharing common PBLs among multipletargets and using variables start session Set refresh_flags = “outofdate exclude_checkout” Set build_type = “incremental” scc get connect properties “c:\testbld\testbld.pbw” scc connect scc set target “.\dbauto\dbauto.pbt” refresh_flags Scc exclude liblist “.\shared_obj\shared_obj.pbl” “.\datatypes\datatype.pbl” “.\chgreqs\chgreqs.pbl” scc refresh target build_type build executable “.\dbauto\dbauto.exe” ".\emp.ico" “” "nyyy" scc close end session

50. Orcascript Example #4Summary • You can define variables within an orcascript session and use them wherever the parser expects a string token • Scc exclude liblist excludes the specified librariesfrom the upcoming Scc refresh target operation. Thisis useful when libraries are shared among multipletargets and a previous orcascript session has alreadyrefreshed the common libraries.