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.
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"
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 liblist ".\qadbtest\qadbtest.pbl;.\shared_obj\shared_obj.pbl;.\datatypes\datatype.pbl;.\chgreqs\chgreqs.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" 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.
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.
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
Defining variables from the command line
Instead of defining variables in the OrcaScript session, you
can define them from the command line when you call your script.
If you saved the OrcaScript example in the previous script in a
file named MyExample.dat, you could set the
same variables by typing the following at a command line prompt:
Orcascr105 /D refresh_flags="outofdate exclude_checkout" /D build_type="incremental" MyExample.dat
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_machine\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
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.
Applicable scc connect properties for offline processing
When scc connect offline is used, only
the following connect properties apply:
scc set connect property localprojpath localProjectPath
scc set connect property logfile logFileName
scc set connect property logappend <true | false>
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.
Advantage of using OutOfDate with ImportOnly option
Combining the OutOfDate option with the ImportOnly option
is particularly useful if you perform nightly builds of a project
that has several promotion models defined. If the volume of changes
is low, it may be more efficient to use OutOfDate processing rather
than Refresh All. In one PowerBuilder workspace, you build the “development” view
of the project that includes all development work in progress. In
another workspace, you build the “maintenance” view
of the project, which includes bug fixes waiting for QA verification.
Elsewhere, you build a “production” view of the
project containing only verified bug fixes.
Each PowerBuilder workspace connects to the same SCC project, but uses a different local project path.You use your vendor-specific SCC administration tool to synchronize the local project path with the desired revision of each object belonging to each promotion model. Then you launch OrcaScript to refresh the PBLs in each workspace. This results in a nightly rebuild of all three promotion models, which development team members can download each morning from a shared network drive.
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 machine. 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.
How the current user is determined for Exclude_checkout
processing
For online SCC connections, Exclude_checkout calls scc
connect property userid userID or
the scc get connect properties workspaceName to
determine the current user. The runtime processing makes actual SccQueryInfo calls
to the SCC provider to determine check out status, so the information
in the PBC file (from the prior SCC connection) is ignored. Objects
checked out to the current user are not imported and replaced in
the target library list.
For scc connect offline, the scc connect property userid command is completely ignored. OrcaScript must rely on information from the prior SCC connection. Each PBC file entry contains a bit flag that indicates “checked out to current user”. This flag determines whether the object is imported or excluded. The current user at the time the PBC file was created is the user who last connected to this workspace through the PowerBuilder IDE on this workstation.
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.
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.
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.
