Usage notes for OrcaScript commands and parameters – PB Docs 2019

Before calling any other ORCA functions, you need to open a
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:

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.

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.

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:

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,

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.