Appendix C. The OrcaScript Language

About this appendix

This appendix describes the OrcaScript scripting language. OrcaScript allows you to perform source control operations and build PowerBuilder workspaces and executables without operator intervention. The full ORCA tool kit is available to Appeon partners only, but OrcaScript can be used by any PowerBuilder customer.

About OrcaScript

OrcaScript allows you to write batch scripts to process PowerBuilder applications and files without using the PowerBuilder development environment. You can use OrcaScript to get the latest version of a target from source control, build the target PBLs, and compile PowerBuilder executable files—all without operator intervention.

Using OrcaScript with source control

Note

The OrcaScript command for getting the latest objects from the source control server is not supported by the SVN/Git solution. You can consider using the SVN/Git client tool (such as TortoiseSVN, TortoiseGit etc.) to get the latest objects via commands. For more information, see Usage notes for OrcaScript commands with SVN/Git.

The targets you obtain from source control using OrcaScript could be placed on a network build computer that is shared by PowerBuilder developers. This is especially advantageous for large shops with fixed working hours: the builds could be done nightly by running an OrcaScript batch file, and an up-to-date version of the targets and libraries would be available at the start of the next work day.

Developers could then use OrcaScript or operating system commands to copy the shared files directly to their local computers. Although developers would still connect directly to source control from their local workspaces, refreshing the targets in the workspaces would be much faster since compilation times for complex targets would be greatly minimized.

Batch file order

If you include OrcaScript commands in a batch file, the file is read line by line. Each OrcaScript batch file must begin with a start session command and end with an end session command. You can save the batch file with any extension. You run the batch file by calling the OrcaScript executable on a command line and passing the batch file name as an argument:

OrcaScr210 myOrcaBat.dat

If you use relative directories in the OrcaScript batch file, create the batch file in the directory that is the required root directory at runtime. This must be in the same directory or in the path above a directory containing the files referenced by the batch file.

When you use relative directories, the OrcaScript batch file is portable for all users. However, users must make the directory where they copy the batch file the current directory (the one displayed in the DOS prompt) before invoking OrcaScr210.exe. The command to start the OrcaScript executable can also take the following parameters:

Parameter

Description

Example

/D

Sets variables that are valid in the batch file

OrcaScr210 /D myVar1=value1 /D myVar2=value2 myOrca.dat

/H or /?

Prints syntax help to screen

OrcaScr210 /H


Caution

You should not run an OrcaScript batch file if PowerBuilder is currently running on the same computer. If the PowerBuilder development environment is not shut down while OrcaScript is running, your PowerBuilder libraries can become corrupted. For this reason, casual use of OrcaScript is not recommended.

Executing DOS commands and batch file

The OrcaScript commands can call DOS commands and arguments and the batch file. For example,

start session
cmd "delete c:\test.txt"
end session

Or

start session
cmd "c:\test.bat"
end session

OrcaScript batch file vs. pbc210.exe

The pbc210.exe tool can be used to automate the PowerBuilder application building process. See below to compare the scripts for building a project using the OrcaScript batch file and the pbc210.exe tool.

OrcaScript batch file

The OrcaScript batch file contains the following scripts:

start session
set liblist "D:\Test\PB\190cmdvss\test11.pbl;D:\Test\PB\190cmdvss\appeontry.pbl;"
set application "D:\Test\PB\190cmdvss\test11.pbl"  "test11"
build library "D:\Test\PB\190cmdvss\test11.pbl" "" pbd
build library "D:\Test\PB\190cmdvss\appeontry.pbl" "" pbd
build executable "D:\Test\PB\190cmdvss\test11.exe" "" "" "yy" newvstylecontrols
end session

pbc210.exe tool

Directly execute the pbc210.exe tool with the following commands:

pbc210 /d D:\Test\PB\190cmdvss\test11.pbt

Note

Please make sure the PBC tool is the same version as the PowerBuilder application source code.

If you use the 2017 PBC tool (pbc170.exe) to build the 2019 R3 application source code, the application will be downgraded from 2019 R3 to 2017, and the 2017 application cannot be built using the 2019 R3 PBC tool.

For more about how to use the pbc210.exe tool, refer to About PBC210.exe.

Error handling

Each line of an OrcaScript batch file either succeeds or fails. If a command fails, subsequent commands are not processed and the OrcaScript session is ended. An error message is printed to the command window.

Exception handling

User-defined exceptions such as Try...Catch is not supported by OrcaScript.

Comments

A semicolon (;) indicates that the rest of the line is treated as a comment.

The comment (including the semicolon) must start in a new line; it cannot be added to the end of a command. This is a correct example:

scc connect  
;test

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, brackets indicate a parameter is optional. A pipe character inside angle brackets ( < | > ) indicates that a selection must be made from one of the values inside the angle brackets. As elsewhere in the PowerBuilder 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 pbrName 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 target from source control, see Usage notes for OrcaScript commands and parameters.

Some OrcaScript commands are for source control management, such as connecting with the source control server, getting the latest files from the server etc. Only a few of these OrcaScript commands are supported by the SVN/Git solution, and their usage are explained in Usage notes for OrcaScript source control commands with SVN/Git.

OrcaScript commands

OrcaScript supports the following commands:

start session

end session

set name = value

set name += value

set liblist pbl_list [pbl_list ...]

set appendlib pblName pbdflag

set application pblName applicationName

set debug <true |false>

set exeinfo property <companyname | productname | copyright | description> propertyString

set exeinfo property <fileversion | fileversionnum | productversion | productversionnum> versionString

echo value [value ...]

file copy fromFile toFile [ clobberAttribute ]

file delete fileName [ clobberAttribute ]

regenerate pblName entryName entryType

copy entry pblName entryName entryType toPblName

build library pblName pbrName <pbd | 32>

build executable exeName iconName pbrName pbdflags [machinecode] [newvstylecontrols] [x64]

build application <full | migrate | incremental | 3pass>

build project pblName projectName [ serverName serverPort logID logPass]

create library pblName pblComments

deploy winform project pblName entryName [iconName]

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 connect [offline]

scc set target targetName [refreshType][refreshOption][refreshOption]

scc get latest version file_list [file_list ...]

scc exclude liblist pblName [ pblName ...]

scc refresh target <full | migrate | incremental | 3pass>

scc close

Argument description

Arguments for OrcaScript commands are described in the table below:

Argument

Description

name

String you define for an OrcaScript session.

value

Value of a string that you set for the OrcaScript session.

pbl_list

String containing the list of PBLs for the session application. PBL names can be separated by semicolons in a single string, or separated by a blank space in multiple strings.

pblName

Name of a PBL for an OrcaScript action or for the OrcaScript session application.

pbdflag

String of a Y or an N. "y" indicates that the library is a PBD. Objects from the PBL are copied into the executable; objects from the PBD are not copied.

Unlike pbdFlags which can be a string of more than one Y and/or N, pbdflag is used with the appendlib command to set only one Y or N for one PBL at a time, for example,

set appendlib "D:\Test\PB\190cmd\test11.pbl" "n"
set appendlib "D:\Test\PB\190cmd\appeontry.pbl" "y"

The appendlib command can be used independently, or used together with the liblist command, for example,

set liblist "D:\Test\PB\190cmd\test11.pbl"
set appendlib "D:\Test\PB\190cmd\appeontry.pbl" "y"

applicationName

Name of the application for an OrcaScript action.

true | false

Boolean value for enabling or disabling script in conditional compilation blocks set with the DEBUG condition. The set debug command applies to standard PowerBuilder targets only. It affects all objects used by subsequent regenerate and build application commands. It also affects all objects retrieved with scc refresh target and scc get latest version commands.

propertyString

String for setting the company or product name, copyright owner, or application description.

versionString

String for setting the product or file version numbers. The FileVersionNum and ProductVersionNum strings must consist of four integer values representing the major version number, minor version number, fix version number, and build number, with each value separated by a decimal point, for example "11.0.0.3012".

fromFile

File that you want to copy during an OrcaScript session.

toFile

File name for a file that you copy during an OrcaScript session.

fileName

File that you want to delete during an OrcaScript session.

clobberAttribute

Determines whether the file copy command overwrites an existing file. If the destination file does not already exist, the file copy command creates the file regardless of the clobberAttribute value you select. Possible values are:

Clobber (default)

File copy command overwrites an existing file marked read/write, but does not overwrite an existing file marked read-only

NoClobber

File copy command does not overwrite an existing file even if it is marked read/write

Clobber Always

File copy command overwrites an existing file even if it is marked read-only

entryName

Pointer to a string whose value is the name of the referenced object.

entryType

Value specifying the type of the referenced object. Values can be: application, datawindow, function, menu, query, struct, userobject, window, pipe, project, or proxy. Certain abbreviations (app, dw, fn, struct, uo, and win) are allowed as substitute values.

toPblName

Name of the PBL to which you copy an entry.

pbrName

Name of a resource file you want to include in a build.

pbd | 32

Select PBD to generate PowerBuilder dynamic libraries. Select 32 to generate platform-specific machine code. You must enter a full path for a PBL or PBR if you select 32 as the value of this argument in an OrcaScript build library command.

exeName

Name of the executable you want to build.

iconName

Name of an icon to use for an executable you build with OrcaScript.

pbdFlags

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 PBDs. Objects from PBLs are copied into the executable; objects from PBDs are not copied.

machinecode

Use to compile the project as machine code.

newvstylecontrols

Use Windows visual style or the UI theme for controls. If your application has applied the UI theme, and if you has specified this argument, the UI theme will take effect.

x64

Compile the project as a 64-bit executable.

full | migrate | incremental | 3pass

Build strategy for the session application.

3pass performs a full rebuild of the application. It should be used instead of full when there are complex inherited relationships.

projectName

Name of the project object you want to build and deploy.

serverName

Name of the server where you want to deploy a project.

serverPort

Port for the server where you want to deploy a project.

logID

Login ID for the server where you want to deploy a project.

logPass

Login password for the server where you want to deploy a project.

pbdName

Name of a PBD you append to an EXE.

pblComments

Comments for a PBL you create in an OrcaScript session.

runtime_version

The version of PowerBuilder Runtime that will be used to compile the application executable.

This argument cannot be set in the batch file using the set command; it can only be used with the /D parameter in the command line for OrcaScr210, for example, OrcaScr210 /D runtime_version="19.2.0.2558" myOrca.dat. If this argument is not set, then the runtime version configured in the PowerBuilder IDE will be used; and if no PowerBuilder IDE is installed on the current machine, then the latest runtime within the same major version as OrcaScript will be used.


Arguments for source control commands

In addition to some of the arguments listed in the preceding table, OrcaScript source control commands use the following arguments:

Argument

Description

workspaceName

Name of the workspace to connect to source control. You must include the path to the workspace, although you can use a relative path.

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

Gets latest version of all objects from the SCC provider and refreshes all target libraries. Does not perform comparisons.

outofdate

Performs comparisons and updates objects that are out of date. If no refreshType value is specified, the refreshType defaults to outofdate.

Combining values. You can combine compatible refreshType and refreshOption values (for example, outofdate and exclude_checkout) in the same string if the values are separated by a blank space.

refreshOption

Value can be:

importonly

Does not perform comparisons and does not refresh. Use to build targets if you refreshed the local path using the SCC provider's administration tool.

exclude_checkout

Prevents objects that are currently checked out by the current user from being overwritten. Can be used with outofdate parameter in the same OrcaScript command.

file_list

String containing one or more resource file names (such as GIFs, HLPs, or PBRs) using relative or absolute path specification. The string should not include file names for objects contained in application PBLs. 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.


Usage notes for OrcaScript commands and parameters

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

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:

Orcascr210 /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.

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:

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 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.

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.

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.

Usage notes for OrcaScript commands with SVN/Git

You can use "scc connect offline" to compile the source code managed by the SVN/Git source control system in PowerBuilder 2019 R3; while you cannot use "scc connect" to connect with the SVN/Git server or get the source code from the server. Therefore, the following OrcaScript source control commands do not work with the SVN/Git solution in 2019 R3:

scc connect
scc get connect properties workspaceName
scc get latest version file_list [file_list ...]

The commands related with connecting to the server such as "scc set connect property userid userID", "scc set connect property password password" etc. will be simply ignored.

The following example shows you how to use the OrcaScript source control command to compile the source code from the SVN/Git source control system in 2019 R3.

start session 
scc set connect property localprojpath "D:\temp_svn" 
;localprojpath must point to the parent directory of ws_objects folder
scc set connect property logfile  "D:\temp_svn\svnorca.log" 
scc set connect property logappend false
scc set connect property deletetempfiles "true"
scc connect offline
scc set target "D:\temp_svn\datawindow_json.pbt" "refresh_all importonly"
scc exclude liblist "D:\temp_svn\pbsoapclient.pbd"
scc refresh target incremental
scc refresh target "3pass" 
build library "D:\temp_svn\datawindow_json.pbl" "" pbd 
build library "D:\temp_svn\appeon_workarounds.pbl" "" pbd
build library "D:\temp_svn\qa_frame.pbl" "" pbd
build executable "D:\temp_svn\datawindow_json.exe" "" "" "yyy"
scc close
end session
  • scc set connect property localprojpath -- Specifies the parent directory of the ws_objects folder. This example supposes ws_objects is located in D:\temp_svn.

  • scc connect offline -- Copies the objects from ws_objects up one level, that is, to the path specified in localprojpath (and it establishes no connection with the server).

    Important

    When you first upload a project to SVN or Git, all objects are generated under ws_objects which is a flat folder containing no sub-directories, therefore objects with the same name from different PBL files will be overwritten. If you have objects with the same name in different PBL files, make sure to rename the object before uploading it to SVN or Git.

  • scc set target -- Refreshes the object list in the PBL file according to the objects copied from ws_objects. The PBG file is no longer used by the SVN/Git solution to map and refresh objects in the PBL file.

  • scc exclude liblist -- Excludes any PBD files that are included in the current PBT, otherwise, an error will occur indicating that the corresponding PBG file cannot be found.

  • scc close -- Closes the session and clears the objects copied to the localprojpath path. The objects will not be cleared, if the OrcaScript commands are terminated by the user or by errors.

The following pseudocode shows you how to use the SVN/Git client tool to get the latest source code from the source control server via commands.

//generate bat file
long ll_file
string is_file
string ls_write
is_file = is_dirc+"\SvnGit.bat"
filedelete(is_file)
ll_file = fileopen(is_file,linemode!,write!,shared!,append!,encodingANSI!)
IF condition1 THEN  //SVN
  if  condition2 T then  // Checkout
      ls_write= "svn checkout ~""+ repository_url +"~" ~""+ checkout_directory +"~""
      //replace the variable "repository_url" and "checkout_directory"
  else   //Update
      ls_write = "svn update ~""+ checkout_directory +"~""
  end if
else  //Git
  if  condition2 T then //Checkout and switch branch
      ls_write = "git clone ~""+URL.text+"~" ~""+download_localpath.text+"~"~r~n"
      ls_write += "cd /d ~""+ download_localpath.text+"~"~r~n"
      ls_write +="git checkout ~"origin/"+sle_BranchName.text+"~""
  else  //Update and switch branch
      ls_write = "cd /d ~""+ download_localpath.text+"~"~r~n"
      ls_write += "git fetch origin ~""+sle_BranchName.Text +"~"~r~n"
      ls_write +="git checkout ~"origin/"+sle_BranchName.text+"~""
  end if
end if
filewrite(ll_file,ls_write)
fileclose(ll_file)

//Download files from svn or git server
run("~""+is_file+"~"")