OrcaScript Commands

OrcaScript commands are not case sensitive. The generic command parameters can include only strings delimited by quotation marks, or predefined variables and constants without quotation marks. White space is used to separate multiple parameters for a single command. Any place a string is expected, a name that has been previously defined (set) in an OrcaScript command can be used.

In the OrcaScript command prototype syntax that follows, square brackets indicate a parameter is optional, and angle brackets indicate a parameter is required. A pipe character ( | ) inside brackets indicates that a selection can be made from one of the values inside the brackets. As elsewhere in the PocketBuilder documentation, text in italic type indicates a variable.

For commands where a string variable is required by the command syntax but is not essential to the command function (such as pkrName for the build library command), you can use an empty string inside quotation marks for the string value. Most of the OrcaScript commands and parameters are self-explanatory. For usage notes and an example of an OrcaScript batch file for obtaining a PowerScript target from source control, see “Usage notes for OrcaScript commands and parameters”.

OrcaScript commands

OrcaScript supports the following commands:

start session
end session
set liblist pkl_list [pkl_list ...]
set application pklName applicationName
set name = value
set name += value
echo value [value ...]
file copy fromFile toFile [Clobber | NoClobber | Clobber Always]

file delete file_name [Clobber | NoClobber | Clobber Always]
regenerate pklName entryName entryType
copy entry pklName entryName entryType topklName
build library pklName pkrName <RTLib>
build executable exeName iconName pkrName pkdflags [newvstylecontrols] [Desktop | ARM | SPARM ]
build application <full | migrate | incremental >
create library pklName pklComments
scc get connect properties workspaceName
scc set connect property deletetempfiles <true|false>
scc set connect property provider sccProvider
scc set connect property userid userID
scc set connect property password password
scc set connect property logfile logFileName
scc set connect property project projectPath
scc set connect property localprojpath localProjectPath
scc set connect property auxproject auxProjectPath
scc set connect property logappend < true | false >
scc set connect
scc set target targetName [refreshType][refreshOption][refreshOption]
scc get latest version file_list [file_list ...]
scc exclude liblist pklName [ pklName ...]
scc refresh target targetName <full | migrate | incremental >
scc close

Argument description

Table C-2 lists and describes arguments you can use in OrcaScript commands.

**Table C-2: Arguments for OrcaScript commands**
Argument	Description
pkl_list	String containing the list of PKLs for the session application. PKL names can be separated by semicolons in a single string, or separated by a blank space in multiple strings.
pklName	Name of a PKL for an OrcaScript action or for the OrcaScript session application.
applicationName	Name of the application for an OrcaScript action.
name	Program variable that you define for an OrcaScript session.
value	Value of a program variable that you set for the OrcaScript session. The value is typically a string that you must place in quotation marks.
fromFile	File that you want to copy during an OrcaScript session.
toFile	Destination file name for a file that you copy during an OrcaScript session.
Clobber \| NoClobber \| Clobber Always (in file copy command)	Clobber replaces a destination file if it is marked read/write, but returns an error if a file does not exist or the destination file is read-only. NoClobber fails when the destination file already exists. Clobber Always replaces read-only destination files and does not return an error if the file does not exist. Clobber is the default behavior.
file_name	File name for a file that you want to delete.
Clobber \| NoClobber \| Clobber Always (in file delete command)	Clobber deletes read-only files and returns an error if a file does not exist. NoClobber deletes files marked read/write and returns an error if the file is read-only or if it does not exist. Clobber Always deletes read-only files but does not return an error if the file does not exist. Clobber is the default behavior.
entryName	The name of the referenced object.
entryType	Value specifying the type of the referenced object. Values can be: application, datawindow, function, menu, query, structure, userobject, or window. Certain abbreviations (app, dw, fn, struct, uo, and win) are allowed as substitute values.
topklName	Name of the PKL to which you copy an entry.
pkrName	Name of a resource file you want to include in a build.
RTLib	Enter RTLib to generate PocketBuilder dynamic libraries.
exeName	Name of the executable you want to build.
iconName	Name of an icon to use for an executable you build with OrcaScript.
pkdFlags	String composed of a series of Y and N values for each library in the library list. A value of "nnyy" indicates that there are four libraries in the library list, the last two being PKDs. Objects from PKLs are copied into the executable; objects from PKDs are not copied.
newvstylecontrols	Use Microsoft XP visual style controls.
Desktop \| ARM \| SPARM	Use to select the deployment platform where you want the executable to be built. If an executable from a previous build exists, it will be replaced by the new executable on the target platform.
full \| migrate \| incremental	Build strategy for the session application.
pklComments	Comments for a PKL you create in an OrcaScript session.

Arguments for source control commands

In addition to some of the arguments listed in the Table C-2, Table C-3 lists and describes arguments you can use with OrcaScript source control commands.

**Table C-3: Source control arguments for OrcaScript commands**
Argument	Description
workspaceName	Name of the workspace to connect to source control.
sccProvider	Name of the source control provider.
userID	Name of the user registered to source control.
password	Password for the user ID.
logFileName	Name of a log file used to record SCC transactions.
projectPath	Path to the source control project.
localProjectPath	Local root directory for the project.
auxProjectPath	Contains any string that the SCC provider wants to associate with the project. It has a different meaning for every SCC vendor.
targetName	Name of the target for source control operations.
true \| false	Boolean value for appending to the source control log file. If this command is not used but a log file is specified, the session value defaults to true.
offline	Keyword indicating that an actual SCC connection will not be required for this session. It is appropriate only when the ImportOnly refresh option is used on a subsequent `scc set target` command. When refreshing a target using ImportOnly, no communication with the SCC provider is required at runtime, so the job may be run offline.
refreshType	Value can be “refresh_all” or “outofdate”. For a description of when to use these values, see “Setting refreshType and refreshOption values”.
refreshOption	Value can be “importonly” or “exclude_checkout”. For a description of when to use these values, see “Setting refreshType and refreshOption values”.
file_list	String containing one or more resource file names (such as GIFs, HLPs, or PKRs) using relative or absolute path specification. The string should not include file names for objects contained in application PKLs. File names can be separated by semicolons in a single string, or separated by a blank space in multiple strings. The list of files must be on a single line even when file names are contained in multiple strings.

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.pkt" "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 PKT file specified in the scc set target command. From the PKT file, it obtains the library list for the target. It then calls SccGetLatestVersion to obtain the tip revision of the PKG file associated with each PKL.

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

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

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 PKT, PKG, and object source files must already exist on the local project path and they are used to import objects into the PKLs. 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 PKT and PKG files. It then compares each object in the target PKLs with the tip revision in the SCC repository and imports the SCC source files into the PKLs 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 PKL 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 PocketBuilder 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 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 PKLs 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 PKC 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 PKC file will not be imported into the PKLs during target processing.

How the current user is determined for Exclude_checkout processing For online SCC connections, Exclude_checkout calls scc connect property useriduserID 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 PKC 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 PKC 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 PKC file was created is the user who last connected to this workspace through the PocketBuilder IDE on this workstation.