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:

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.

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:

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.

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.

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.

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:

PowerBuilder

Orcascr125 /D refresh_flags="outofdate exclude_checkout"<br>/D build_type="incremental" MyExample.dat

1	Orcascr125 /D refresh_flags="outofdate exclude_checkout"<br>/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:

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.

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>

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:

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.

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.

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.

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.

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:

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.