Users Guide
Appendix C. The OrcaScript Language

Before calling any other ORCA functions, you need to open a session:

start session

You can start and end multiple OrcaScript sessions in the same batch file.

Copying files, objects, and properties

If you want to use OrcaScript simply to move objects among libraries, you do not need to set a library list or application. You can use the copy commands to copy files, objects, and properties. This example copies the d_labels DataWindow from the source.pbl library to the destin.pbl library:

copy entry "c:\\app\\source.pbl" "d_labels" dw "c:\\app\\destin.pbl"

Setting a library list and an application

If you want to use OrcaScript to build targets or deploy components (or set product and version information using the set exeinfo command) you must first set the library list and the current application. You can set the library list and current application only once in an OrcaScript session. To use another library list and application, end the OrcaScript session and start a new session. The following OrcaScript commands build target libraries and compile an executable file.

start session
set appendlib ".\qadbtest\qadbtest.pbl" "n"
set appendlib ".\shared_obj\shared_obj.pbl" "y"
set appendlib ".\datatypes\datatype.pbl" "y"
set appendlib ".\chgreqs\chgreqs.pbl" "y"
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" ""
file copy ".\qadbtest\qadbtest.exe" ".\bin\qadbtest.exe"
file copy ".\chgreqs\chgreqs.pbd" ".\bin\chgreqs.pbd"
file copy ".\datatypes\datatype.pbd" ".\bin\datatype.pbd"
file copy ".\shared_obj\shared_obj.pbd" ".\bin\shared_obj.pbd"
end session

You can use relative paths when you generate PBDs with the "PBD" option, but the PBD always gets generated in the same directory as the PBL. To actually run the executable, you might have to move the PBDs to a "BIN" directory. The above example calls several file copy commands to accomplish this.

If you select 32 as the last argument in a build library command, you must use the full path for the PBL or PBR name included in that call.

Source control example

You can use OrcaScript source control commands instead of the commands to set the library list and application. The following is an example of an OrcaScript session that builds the same libraries as the previous example, but uses the target properties to set a library list and application:

start session
scc get connect properties "testbld\testbld.pbw"
scc connect 
scc set target "c:\testbld\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

You can call the scc connect command only after getting connection properties, and you must call it before you set or refresh the source-controlled targets. You must call the scc close command before you end your OrcaScript session.

Set DEBUG example

The build application full command in the following example recompiles all of the objects in the application PBL with the DEBUG condition disabled, and the buildapp_p.exe application created by the build executable command behaves exactly like the production application.

start session
set debug false
set liblist "testdebug\buildapp.pbl"
set application "testdebug\buildapp.pbl" "testdebug"
build application full
build executable "destination_1\buildapp_p.exe" "icon\icon9.ico" "" "N"
end session

Setting the debug value only affects objects that are compiled or regenerated after the set debug command is issued. The following example copies the PBL generated from the previous example after it was compiled with the debug condition disabled. In this example, even though set debug true is called before it builds the debug_copy.exe executable, the code in DEBUG conditional compilation blocks is not enabled because none of the commands that follow the set debug call invoke the PowerScript compiler.

start session
set debug TRUE
file copy "testdebug\buildapp.pbl" "testdebug\copy.pbl" clobber alwaysset 
liblist "testdebug\copy.pbl"
set application "testdebug\copy.pbl" "testdebug"
build executable "destination_1\debug_copy.exe" "icon\icon9.ico" "" "N"
end session

If you add a build application command or a regenerate command after the set debug command, the script inside DEBUG conditional compilation blocks will be enabled.

Shared library example

If you have another target that shares libraries with a target that you already refreshed, you can use the OrcaScript exclude command to quickly reconstitute your target. The following example excludes the shared libraries shared_obj.pbl, datatype.pbl, and chgreqs.pbl that were refreshed in the previous example. It also demonstrates the use of variables for refresh options and build type. Set statements define variables that can be used throughout an OrcaScript session wherever the parser expects a string token.

start session
set refresh_flags = "outofdate"
set refresh_flags += "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

Orcascr220 /D refresh_flags="outofdate exclude_checkout" /D build_type="incremental" MyExample.dat

SCC connection properties

The SCC get connect properties command is an easy way to populate the Orca SCC connection structure with the source control properties of a local workspace. However, to create OrcaScript batch files that are portable from one workstation to another, the recommended technique is to set each property explicitly. Many of these properties are vendor specific. The best way to obtain correct values is to copy them directly from the SCC log file for your PowerBuilder workspace.

After you have obtained the values you need from the SCC log file, you can create portable batch files by setting the required connection properties and using relative directories and URLs for path information. The following example shows portable OrcaScript batch file commands for a workspace that connects to PBNative:

start session
scc set connect property provider "PB Native" 
scc set connect property userid "Jane"
scc set connect property localprojpath ".\"
scc set connect property project "\\network_computer\PBNative_Archive\qadb"
scc set connect property logfile ".\MyPortableExample.log"
scc set connect property logappend "FALSE"
scc set connect property deletetempfiles "FALSE"
scc connect
; Perform refresh and build operations
scc close
end session

Using OrcaScript with source control targets offline

You can call scc connect offline to build source control targets offline. When you use this command, you must specify ImportOnly as a refresh option. If you also specify the Refresh_all option or the OutOfDate or Exclude_checkout refresh types, no connection is made to source control.

For the OutOfDate refresh type, the object source residing in the PBL is compared with the object source on the local project path. If these object sources are different, the object source on the local project path is imported and compiled.

For the Exclude_checkout refresh type, the workspace PBC file is used to determine current status. In order for the offline exclude_checkout processing to locate the PBC file, you must use the scc get connect properties workspaceName command at the beginning of the script. Objects marked as checked out to the current user in the PBC file will not be imported into the PBLs during target processing.

Setting refreshType and refreshOption values

When you set up a target with a source control connection, you can use refreshType and refreshOption options in various combinations. You can even combine these values in the same string if the values are separated by a blank space. For example:

scc set target ".\dbauto\dbauto.pbt" "refresh_all importonly"

Refresh_all option. Refresh_all performs no comparisons and imports all applicable objects. Refresh_all behavior varies depending on whether ImportOnly is set. If ImportOnly is off, Refresh All issues an SccGetLatestVersion call to obtain the tip revision of the PBT file specified in the scc set target command. From the PBT file, it obtains the library list for the target. It then calls SccGetLatestVersion to obtain the tip revision of the PBG file associated with each PBL.

Each PBG file contains a list of objects registered under source control that reside in the associated PBL. Refresh All then issues SccGetLatestVersion to obtain the tip revision of each object and imports these objects into the PBL.

In offline processing, ImportOnly must be set to on. If you also set the Refresh_all option, the PBT file that already exists on the local project path is used to obtain the library list for the target. The PBG file that also exists on the local project path is then read to obtain a list of objects associated with each PBL. Refresh_all then processes the PBG lists, importing source entries residing on the local project path into the appropriate PBL.

ImportOnly option. When ImportOnly is on, the expectation is that the user has already populated the local project path with the desired revision of each object. ImportOnly is used to build a target from a previous milestone, such as a version label or a promotion model that does not represent the tip revision of each object. Therefore, no SccGetLatestVersion calls are issued. The desired revisions of the PBT, PBG, and object source files must already exist on the local project path and they are used to import objects into the PBLs. You must use this option if you are building a source controlled target while you are offline.

OutOfDate option. OutOfDate processing behaves differently depending on whether ImportOnly is set. When ImportOnly is off, OutOfDate issues an SccGetLatestVersion call to obtain the tip revision of the PBT and PBG files. It then compares each object in the target PBLs with the tip revision in the SCC repository and imports the SCC source files into the PBLs for the objects that are out of sync.

With ImportOnly turned on, OrcaScript never performs GetLatestVersion since the desired revision of all objects already exists on the local project path. In this case, OutOfDate processing compares source code in the PBL against object source on the local project path to decide which objects, if any, need to be reimported. Using ImportOnly with OutOfDate processing works the same whether you are online or offline.

Exclude_checkout option. The Exclude_checkout option excludes from the import list all objects that are currently checked out by the current user, no matter what other refresh options are used. When connected to SCC, this option requires an additional call to SccQueryInfo for each object in the target. Therefore, it is not recommended on a nightly build computer. However, it is highly recommended when a developer uses OrcaScript on his or her own workstation.

If you use Exclude_checkout processing while offline, the workspace PBC file is used to determine current status, so you must specify the set get connect properties workspaceName command. Objects marked as checked out to the current user in the PBC file will not be imported into the PBLs during target processing.

Build command failures

OrcaScript build commands for an executable or a library fail if the executable or library already exists in the build directory. To prevent an OrcaScript batch file containing these commands from failing, move or delete existing executables and libraries from the build directory before running the batch script.

The building process may fail because of using "scc refresh target 3pass". In such case, you can add "scc refresh target incremental" before "scc refresh target 3pass", for example,

start session
set debug true
scc set connect property logfile "c:\ test\log.log"
scc connect offline
scc set target "c:\test\work.pbt" importonly
scc refresh target incremental
scc refresh target 3pass
scc close
end session

Escape characters for string variables

OrcaScript, like PowerScript, uses the tilde ( ~ ) as an escape character. If you need to include a special character, such as a quotation mark, inside a string, you must place a tilde in front of it. A character in an OrcaScript batch file with a tilde in front of it is processed as a literal character.

Ending an OrcaScript session

You must close an OrcaScript session after you finish calling other OrcaScript commands. You close an OrcaScript session by calling:

end session

Property values are deleted during end-session processing. If an OrcaScript program starts numerous sessions, each individual session must contain statements to specify property values, such as those assigned in set exeinfo or scc set connect commands. However, variables that you set on a batch script command line using the /D parameter, or inside a batch file using the set variable_name="value" syntax, remain valid for the entire multisession program.