Users Guide
Appendixes

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

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:

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

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

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

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

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

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

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:

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

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.

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.

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,

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.

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

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+"~"")