The best software development project can come to a dead end if you can't build an executable that your end users can run. Luckily, PowerBuilder provides several different ways to generate an executable with a variety of options. Most of these employ the use of the project painter and differ only by how we deploy the project (i.e., development IDE or command line). However, if you want to build your executable with relative pathing like Workspace has or passing-in parameters that change, then Orca-Script is the way to go. If you combine it with a command or batch file, you can automate your build and deploy steps into an unattended and/or scheduled process.

Using the OrcaScript language, you can automate both the building of the application into the exe and pbd/dlls as well as the deployment of the needed files to a single directory where they can be tested before being promoted to production.

The Background of OrcaScript
OrcaScript is a scripting language that was first released with PowerBuilder 9 and is built off of the Orca API. The Orca API has existed for a number of years and third-party products such as PowerGen have used it as their backbone into the PowerBuilder environment. The scripting language makes it possible for the average developer to perform a variety of library functions from a command file, like performing an unattended full build at a target level to ensure all of your objects are in sync or, if you have source control, getting the latest version of all of the objects in your application, not checked out by you, before you get to work in the morning. There are many other tasks that can be done using OrcaScript with just a little thought. The full documentation is in the appendix of the Users Guide (yes, the documentation).

Application Setup
For our purposes here, we'll be using a small application consisting of three pbl files each in its own directory as recommended when using source control. These three directories will be located under the .\Source directory. The target (pbt) file will be stored in the .\Source directory. The .\Executable directory will hold the exe and pbd files as well as any other files needed to run the application for testing before being promoted to production (the ini's, ocx's, dll's, etc.). The .\Resources directory will hold all of the additional resources (bmps or icons) used by the application and referenced by the PBR file. The directory structure can be seen in Figure 1.

To make the call to the OrcaScript file easier, we can build a command file that does some simple housecleaning both before and after the build. This includes removing the last build from the .\Executable directory and, once the build is done and successful, removing the exe and pbd files from the .\Source subdirectories. You can see that if the first attempt fails you'd try a second pass with a slightly different build script. This second script is an identical copy of the original except for the Build Application command. Instead of using the "FULL" parameter, you'd use the "INCREMENTAL" parameter. The reason for this is that OrcaScript may fail on the first pass with an application that has a deep inheritance structure for menus (four or more), but will succeed on the second. If you succeed on the first pass, checking the error level ensures that the second OrcaScript call doesn't get executed.

You can design your cmd file to accept a parameter to be passed into the OrcaScript for variables that may change build to build. For example, if you wanted to set the version number of the executable so it would show on the version tab under properties on the right-mouse click of the executable, that could be a parameter passed through the command file into the OrcaScript and included in the build. For this example we'll keep it simple and keep everything static. A sample command file can be seen in Listing 1.

Without Source Control
The first thing to remember when using OrcaScript is that everything happens in a session. If any single command fails, then the remaining commands are ignored, the session is ended, and an error level of 1 is returned to the calling program. Following the script in Listing 2 you'll see that we begin and end with a start session and end session, respectively.

Next we need to designate the library search path. This can be done either by using the full path, as a project would do, or a relative path starting at the location of the .cmd file. The problem with using the full path is that every person running the script file must have the same directory structure. The Set LibList command takes a single string of libraries names with paths separated by semicolons. The string should be enclosed in quotes. This is followed by identifying the application object that we're going to use with the Set Application command. This command has two string parameters both enclosed in quotes. The first is the name and path to the application pbl filename and the second is the name of the application object.

Once you've identified all of the objects used in the application, you should then regenerate them to make sure they're all synchronized. This is done with the Build Application command. This command has three options: full, incremental, and migrate. Since we're building this executable for a production environment, we need to do a full rebuild of all of the objects, not just the ones that have changed.

The next section of the script actually builds the executable and either the pbls or the dlls. It uses the Build Executable command and the Build Library command to do this. We feed the Build Executable command five parameters that represent the following:

• exe Name
• exe icon name and path
• pbr file to use for the exe
• A set of flags to indicate which pbls from the library list should not be compiled into the exe
• A flag saying to use the XP look and feel

The Build Library command only takes three parameters as shown in Listing 2. They are the name and path of the pbl file, the name and path of the Resource file to be used when compiling this library, and a flag to designate whether we should create a pbd or dll file.

Once the exe and pbd or dll files have been created, there's just one more step - putting a copy of them in the .\Executable directory ready for testing. This is done by using the File Copy command with its two parameters of to and from. Remember that in our case the pbd files will be removed from the source directories by the cmd file if everything compiles and deploys cleanly.

With Source Control
When using OrcaScript with a source control provider you have to add commands to connect to the source code repository and get the latest version. To do this, there are a series of commands that will have to be added to the script file that we used earlier.

In our example, we'll connect to source control but not just point to the Workspace to get the parameters. We'll be using PBNative but this works for any source control system supported by PowerBuilder. Pointing to the Workspace would force everyone who ran this script to have the Workspace file in the same location on the hard drive and named the same. First we will need to set the connection parameters. Using the scc set connection property command we can set the properties for provider, user, logfile, logappend, local project path, project, and the deletion of temporary files. These are the same elements required from the source control tab of the Workspace properties to be able to connect in PowerBuilder. Different source control systems need different parameters so yours may not need all of these but may need a few others.

Once all of the parameters are set, we can connect to the source code control provider by issuing the scc connect command. If you are using ClearCase with static views, the latest revision export files already exist locally so there's no need to go to the central repository to retrieve them. You'd simply connect using the offline option: however, most other SCC providers, including PBNative, don't use this option. When using other source code control providers you may just have to issue the scc connect command. After connecting, you point to the target using the refresh all and import only option. This gets the latest version of every object from the source code repository and imports them into the local pbls. You then do a full rebuild just as you did in the script without source control. This is followed by the scc close command before the files are copied to the Executable directory.

One other main difference that you'll see in the script (see Listing 3) is that since the target file for the application is registered in the source control, you don't have to specify the application or library search path in the script. Instead, you can specify the target file and derive them from there. This makes it easier when things change.

Conclusion
Now that we have both the .cmd and the OrcaScript files built it's just a matter of starting them to automate the build process. This can easily be done through the Windows Task Scheduler or a number of other products available on the market to schedule tasks. It can also be as easy as putting an icon on the desktop so anyone can start the build when they're told the development team is ready. They don't have to know anything about PowerBuilder.

This is just one small part of what OrcaScript can do for a development team. From bootstrapping a new set of pbls from the source code repository, performing a full "Get Latest Version" before the developers sit down in the morning, to doing a full application rebuild to keep your objects in sync before you get to work.

The examples have been very simple. By passing in parameters or using parameter files, OrcaScript and the .cmd files used to call them can get very complicated. I've even written a PowerBuilder program that writes an OrcaScript file based on the user's selections from a window and then schedules the task in Windows.