Working with an Application project -

Creating an Application project

To create an Application project:

Select File>New or click the New button in the PowerBar to open the New dialog box.
Select the Project tab.
Select the target in which you want to create the project from the Target drop-down list.
Select the Application Wizard or Application project type and click OK.

If you select Application Wizard, complete the wizard screens to create a new project with most of its properties specified. Use the context-sensitive Help if you are not sure what to enter. You can open the Project painter now or later to modify the properties if necessary and to build the project.

If you select Application, the Project painter for the client/server application opens so that you can specify properties of the project object.

Defining an Application project

The Project painter for client/server applications allows you to streamline the generation of executable files and dynamic libraries. When you build a project object, you specify the following components of your application:

Executable file name
Which of the libraries you want to distribute as dynamic libraries
Which PowerBuilder resource files (if any) should be used to build the executable file and the dynamic libraries
Which build options you want to use in your project
Which code generation options you want to use
Version information for your application

If you do not use the Template Application Target wizard to create a new application project, you need to define the project using a Project wizard or by setting project properties in the Project painter. After you have created a project, you might need to update it later because your library list has changed or you want to change your compilation options.

To define or modify a client/server application project

Select the Application project icon on the Project tab in the New dialog box to create a new application project, or select File>Open to open an existing application project.

The Project painter workspace displays.
Specify or modify options as needed.

If you opened an existing project or a project created using the wizard, the options already selected display in the workspace. For information about each option, see Application project options.

When you have finished defining the project object, save the object by selecting File>Save from the menu bar.

PowerBuilder saves the project as an independent object in the specified library. Like other objects, projects are displayed in the System Tree and the Library painter.

Application project options

The following table describes each of the options you can specify in the Project painter for client/server applications. You can also specify most of these options in the Application Project wizard.

Option	What you specify
Executable file name	Specify a name for the executable. The name must have the extension EXE. If you do not want the executable saved to your current directory, click the Browse (...) button next to the box to navigate to a different directory.
Resource file name	(Optional) Specify a PowerBuilder resource file (PBR) for your executable if you dynamically reference resources (such as bitmaps and icons) in your scripts and you want the resources included in the executable file instead of having to distribute the resources separately. You can type the name of a resource file in the box or click the button next to the box to browse your directories for the resource file you want to include. For more about PBRs, see Distributing resources.
Prompt for overwrite	Select this if you want PowerBuilder to prompt you before overwriting files. PowerBuilder overwrites any files it creates when building your application.
Windows classic style	Select this to add a manifest file to the application that specifies the appearance of the controls as an application resource. By default, this option is not selected, which means the Windows flat style is used and the 3D effect of some controls will be removed to have a "flat" look, for example, the 3D lowered border of Column and Computed Field in the DataWindow object, the background color of Button, the BackColor and TextColor of tooltip, and the TabBackColor of tab header will not take effect. If you still want the 3D effect, you should select the "Windows classic style" option when deploying the application. Note If you have applied a theme to the application, you should not check the "Enable Windows Classic Style in the IDE" option in the System Options or the "Windows classic style" option in the project painter and the PB.INI file (if any) should not contain such setting, otherwise, the application UI will be rendered in the Windows classic style instead of the selected theme.
Rebuild	Specify either Full or Incremental to indicate whether you want PowerBuilder to regenerate all objects in the application libraries before it creates the executable and dynamic libraries. If you choose Incremental, PowerBuilder regenerates only objects that have changed, and objects that reference any objects that have changed, since the last time you built your application. As a precaution, regenerate all objects before rebuilding your project.
Platform	Select if the executable can run on 32-bit or 64-bit machines.
Machine Code	Select this if you want to generate compiled code instead of Pcode. For more information about compiled code and Pcode, see the section called “Compiler basics” in Application Techniques. Selecting Machine Code enables the other code generation options in the Project painter. They cannot be set in the wizard.
Trace Information	Select this if you want to create a trace file when you run your compiled code executable. You can use the trace file to troubleshoot or profile your application. For more information on obtaining trace information, see Tracing execution.
Error Context Information	Select this if you want PowerBuilder to display context information (such as object, event, and script line number) for runtime errors.
Optimization	Select an optimization level. You can build your application with no optimizations, or you can optimize for speed or space.
Enable DEBUG symbol	Select to enable any code that you placed in DEBUG conditional code blocks. For more information, see Using the DEBUG preprocessor symbol.
PBC runtime parameters	Directly copy the runtime parameters which are automatically displayed here according to the options selected, and execute them with the PowerBuilder Compiler. For more information about PowerBuilder Compiler, see About OrcaScript or PBC.
Libraries page	The label for the PBD or DLL check box depends on whether you are building a Pcode or machine code executable. Select the check box to define a library as a dynamic library to be distributed with your application. If you are generating Pcode, you create PBD files. If you are generating machine code, you create DLL files. For more about dynamic libraries, see Using dynamic libraries. Specify a resource file for a dynamic library if it uses resources (such as bitmaps and icons) and you want the resources included in the dynamic library instead of having to distribute the resources separately. The file name cannot be specified in the wizard.
Version page	Specify your own values for the Product Name, Company Name, Description, Copyright, Product Version, and File Version fields associated with the executable file and with machine-code DLLs. These values become part of the Version resource associated with the executable file, and most of them display on the Version tab page of the Properties dialog box for the file in Windows Explorer. The Product and File version string fields can have any format. The Product and File version numeric fields in the "Executable version used by installer" group box are used by Microsoft Installer to determine whether a file needs to be updated when a product is installed. The Product Version final value will automatically include the runtime version to help users easily identify which runtime version is used by the executable file, for example, if you input "1.0.2" to the Product Version field, the Product Version displayed in the executable file properties will look like this "1.0.0.2 (Runtime: 22.0.0.1234)". The four numbers can be used to represent the major version, minor version, point release, and build number of your product. They must all be present. If your file versioning system does not use all these components, you can replace the unused numbers with zeros. The maximum value for any of the numbers is 65535.
Security page	Use the Security tab page to generate a manifest file (either external or embedded) and to set the execution level of the application. To meet the certification requirements of the Windows logo program the application executable must have an embedded manifest that defines the execution level and specifies whether access to the user interface of another window is required. For further information, see Attaching or embedding manifest files.
Run page	Specify command-line arguments, the application's working directory, and the runtime path (a relative or absolute path) that will be displayed in the application XML file. The Application field displays the name and location of the executable file and is not editable. You can change these properties on the General page.

Location of temporary files

The machine code generation process puts temporary files in a temporary directory, such as the TEMP directory. You can specify a different location in the [PB] section of your PowerBuilder initialization file with the CODEGENTEMP variable. You might want to do this if you have limited space on your local system.

For example:

CODEGENTEMP=e:\pbtempdir

Tracing execution

You can trace execution of an executable file built with PowerBuilder. By tracing execution, you can troubleshoot your application if it does not behave the same way when run as an executable file as it does when run in the PowerBuilder development environment. You can also use the trace output to profile your application: for example, you can see how many times particular scripts and functions are being executed.

Two kinds of trace files

You can generate two kinds of trace files:

With timing information

You collect trace information by adding code to the scripts in the application or adding a window that lets users turn tracing on and off. PowerBuilder generates a binary trace file that you analyze using a comprehensive set of objects and functions or the Profiling tools. For more information about tracing and profiling, see About tracing and profiling an application.
Without timing information

You collect information by running the application with the /pbdebug command-line switch. PowerBuilder generates a text file that logs the creation and destruction of objects and the execution of scripts and functions.

Tracing execution using /pbdebug

You generate PBDebug trace information for an executable file by invoking the executable with a command-line switch.

To generate PBDebug trace information:

Invoke the executable file using the /pbdebug command-line switch:
```
EXEFILE  /pbdebug
```
As the application executes, PowerBuilder records the trace output in a file called exefile.dbg, which is a text file that you can read in any editor. For information about PBDebug tracing in the development environment, see Generating a trace file without timing information.

Enabling tracing

If you are compiling machine code, you must enable tracing at compile time by selecting Trace Information in the Project painter Compile Options group. If you have not enabled tracing when you compile for machine code, no trace information is generated and the /pbdebug switch has no effect.

If you compile your project in Pcode, the compiler automatically adds the information needed to enable tracing.

Building a client/server application and dynamic libraries

How PowerBuilder builds the project
How PowerBuilder searches for objects
Listing the objects in a project

Once you have completed development and defined your Application project, you build the project to create the executable files and all specified dynamic libraries. You can build your project whenever you have made changes to the objects and want to test or deploy another version of your application.

This section describes building a single project in the Project painter. You can build all the targets in your workspace at any time using buttons on the PowerBar, pop-up menus in the System Tree, or a command line. For more information, see Building workspaces.

To build the application:

Open the project you built in the Project painter.
Click the Build button in the PainterBar, or select Design>Build Project.

If the target's library list has changed

When you click Build, PowerBuilder checks your target's library list. If it has changed since you defined your project, PowerBuilder updates the Project painter workspace with the new library list. Make whatever changes you need in the workspace, then click Build again.

PowerBuilder builds the executable and all specified dynamic libraries.

The next two sections describe in detail how PowerBuilder builds the project and finds the objects used in the target.

When PowerBuilder has built the target, you can check which objects are included in the target. See Listing the objects in a project.

How PowerBuilder builds the project

When PowerBuilder builds your application project:

If you selected Rebuild: Full, PowerBuilder regenerates all the objects in the libraries.
If you selected Prompt for Overwrite, PowerBuilder displays a message box asking for confirmation before overwriting the executable file and each dynamic library.

To create the executable file you specified, PowerBuilder searches through your target and copies into the executable file the compiled versions of referenced objects from the libraries in the target's library search path that are not specified as dynamic libraries. For more details, see How PowerBuilder searches for objects.

PowerBuilder creates a dynamic library for each of the libraries you specified for the target and maintains a list of these library files. PowerBuilder maintains the unqualified file names of the dynamic library files; it does not save the path name.

PowerBuilder does not copy objects that are not referenced in the application to the executable file, nor does it copy objects to the executable file from libraries you declared to be dynamic libraries. These objects are linked to the target at runtime and are not stored in the executable file.

What happens at runtime

When an object such as a window is referenced in the application, PowerBuilder first looks in the executable file for the object. If it does not find it there, it looks in the dynamic library files that are defined for the target. For example, if you specified that a dynamic library should be generated from test.pbl, PowerBuilder looks for test.pbd or test.dll at runtime. The dynamic library files must be in the search path. If PowerBuilder cannot find the object in any of the dynamic library files, it reports a runtime error.

How PowerBuilder searches for objects

Which objects are copied to the executable file
Which objects are not copied to the executable file
Which objects are not copied to the dynamic libraries
How to include the objects that were not found

When searching through the target, PowerBuilder does not find all the objects that are used in your target and copy them to the executable file. This section describes which objects it finds and copies and which it does not.

Which objects are copied to the executable file

PowerBuilder finds and copies the following objects to the executable file.

Objects that are directly referenced in scripts

PowerBuilder copies objects directly referenced in scripts to the executable file. For example:

If a window script contains the following statement, w_continue is copied to the executable file:
```
Open(w_continue)
```
If a menu item script refers to the global function f_calc, f_calc is copied to the executable file:
```
f_calc(EnteredValue)
```
If a window uses a pop-up menu using the following statements, m_new is copied to the executable file:
```
m_new mymenu
mymenu = create m_new
mymenu.m_file.PopMenu(PointerX(), PointerY())
```

Objects that are referenced in painters

PowerBuilder copies objects referenced in painters to the executable file. For example:

If a menu is associated with a window in the Window painter, the menu is copied to the executable file.
If a DataWindow object is associated with a DataWindow control in the Window painter, the DataWindow object is copied to the executable file.
If a window contains a custom user object that includes another user object, both user objects are copied.
If a resource is assigned in a painter, it is copied to the executable file. For example, when you place a Picture control in a window in the Window painter, the bitmap file you associate with it is copied.

Which objects are not copied to the executable file

When creating the executable file, PowerBuilder can identify the associations you made in the painter, because those references are saved with the object's definition in the library, and direct references in scripts, because the compiler saves this information.

However, it cannot identify objects that are referenced dynamically through string variables. To do so, it would have to read through all the scripts and process all assignment statements to uncover all the referenced objects. The following examples show objects that are not copied to the executable file:

If the DataWindow object d_emp is associated with a DataWindow control dynamically using the following statement, d_emp is not copied:
```
dw_info.DataObject = "d_emp"
```
The bitmap files assigned dynamically in the following script are not copied:
```
IF Balance < 0 THEN
   p_logo.PictureName = "frown.bmp"
ELSE
   p_logo.PictureName = "smile.bmp"
END IF
```
The reference to window w_go in a string variable in the following window script is not found by PowerBuilder when building the executable file, so w_go is not copied to the executable file:
```
window   mywin
string   winname = "w_go"
Open(mywin,winname)
```

Which objects are not copied to the dynamic libraries

When building a dynamic library, PowerBuilder does not inspect the objects; it simply copies the compiled form of the objects. Therefore, the DataWindow objects and resources (pictures, icons, and pointers) used by any of the objects in the library—either specified in a painter or assigned dynamically in a script—are not copied into the dynamic library.

For example, suppose test_dw.pbl contains DataWindow objects and test_w.pbl contains window objects that reference them, either statically or dynamically. If you build a dynamic library from test_w.pbl, you must either include the DataWindow objects in a PowerBuilder resource file that is referenced by test_w.pbl, or build a dynamic library from test_dw.pbl, as described in How to include the objects that were not found.

How to include the objects that were not found

If you did not use any of the types of references described in the preceding sections, you do not need to do anything else to ensure that all objects get distributed: they are all built into the executable file. Otherwise, you have the following choices for how to include the objects that were not found.

Distributing graphic objects

For graphic objects such as icons and bitmaps, you have two choices:

Distribute them separately
Include them in a PowerBuilder resource file (PBR), then build an executable file or dynamic PowerBuilder library that uses the resource file

Distributing DataWindow objects

For DataWindow objects, you have two choices:

Include them in a PBR, then build an executable file or dynamic PowerBuilder library that uses the resource file
Build and distribute a dynamic library from the PBL that contains the DataWindow objects

Distributing other objects

All other objects, such as windows referenced only in string variables, must be included directly in a dynamic library.

The following table summarizes resource distribution possibilities.

Distribution method	Graphic objects	DataWindow objects	Other objects
As a separate file	Yes	No	No
In an executable or dynamic library that references a PBR	Yes	Yes	No
Directly in a dynamic library	No	Yes	Yes

Listing the objects in a project

After you have built your project, you can display a list of objects in the project in a grid DataWindow object with three columns showing:

The source library that contains the object
The name of the object
The type of the object

The report lists the objects that PowerBuilder placed in the executable file and the dynamic libraries it created when it built the project.

Because the report is a grid DataWindow object, you can resize and reorder columns just as you can in other grid DataWindow objects. You can also sort the rows and print the report using the Sort and Print buttons.

To list the objects in a project

Build your project.
Select Design>List Objects from the menu bar.

Building a client/server application with commands

Instead of building the Application project from the PowerBuilder IDE, you can also build the project using the PBAutoBuild220.exe tool.

PBAutoBuild220.exe is a standalone tool that can compile and deploy Application projects using DOS commands on Windows. It can automate the entire build and deploy process without requiring PowerBuilder IDE installed or any PowerBuilder license running; it is free for use! But it requires PowerBuilder Runtime to run, so it must be installed to a machine where PowerBuilder Runtime will also be installed. To install PBAutoBuild220.exe, run the PowerBuilder Installer and select PowerBuilder Utilities in the Programs tab.

For step-by-step guidance, refer to Tutorial: Building your client/server application with commands. The PBAutoBuild220 command can also integrate with Jenkins to automate the build process for Application projects. Refer to the Jenkins user documentations for how to use Jenkins.

To build the Application project with commands:

Export the configurations of the Application project to the JSON file.
1. Click the Export Build File button () in the toolbar if the Application project painter opens, or right click the Application project object (or target or workspace) and then select Export Build File.
2. In the Export Build File dialog box, specify where to save the exported file and how to overwrite the settings if the file already exists. Click Export.
  
  If you right click the workspace and then select Export Build File, you can select one or more targets to export the build file for, and then select one or more project types to export if there are more than one type of project objects in the selected target(s). If you select more than one project type, the corresponding project objects will be exported to the build file > "Projects" > [project object name]. If the selected targets contain project objects with the same name, only the object listed last will be added to the build file.
  
  Select "Export the Git/SVN SourceControl settings (if exists) from the project" if you want to export the Git/SVN source control settings (such as login username, password, source code path etc.) to the build file. The password will be encrypted automatically.
  
  Specify how to overwrite the source code settings if the build file already contains such settings. Existing settings will be kept by default. If you want to export the current settings, such as login username, password (encrypted), source code path etc. to the build file, you should select "Clear existing settings". If you have selected "Clear existing settings", while have not selected "Export the Git/SVN SourceControl settings (if exists) from the project", then existing settings will be removed and no settings will be stored.
  
  Specify how to overwrite the build job settings and project settings if the build file already contains such settings. Such settings will be cleared by default.
3. Click Export.
The exported JSON file includes every single setting that is required for compiling, packaging and deploying the Application project. It also contains a "BuildPlan" block which provides additional configurations. For more, see About the build file.
Execute the PBAutoBuild220.exe file and the JSON file in a command line to automatically build the project. For example,
```
PBAutoBuild220.exe /f "D:\PB2022\SalesDemo\salesdemo_exe.json" /l Log_PBBuild.log /le Log_PBError.log
```
The PBAutoBuild220.exe file supports the following parameters:
- /f -- specify the configuration file. The configuration file (in JSON format) can be directly exported from the PowerBuilder IDE, as described in step 1.
```
PBAutoBuild220 /f D:\PB2022\SalesDemo\salesdemo_exe.json
```
- /l -- write the logging information to a file.
- /le -- write the error information to a file. For example,
```
PBAutoBuild220 /f D:\PB2022\SalesDemo\salesdemo_exe.json /l Log_PBBuild.log /le Log_PBError.log
```
  The relative path specified in the parameter is relative to the path of the configuration file. In the above example, the log files will be generated under the same path as the configuration file.
- /p -- specify the password for logging into SVN or Git. This will generate an encrypted value based on the password. If the password contains the double quotation mark ("), use the escape character \" to replace ".
```
PBAutoBuild220 /p abcd1234
```
- /v -- specify the product version (property displayed for executable).
  
  /fv -- specify the file version (property displayed for executable).
  
  /vn -- specify the product version (executable version used by installer).
  
  /fvn -- specify the file version (executable version used by installer).
  
  You can specify for multiple projects at the same time, in this format: "[projectname1]:1.0.0.1;[projectname2]:1.2.3.4". Projects are separated with semicolons (";"). For example,
```
PBAutoBuild220 /f c:\test.json /v "project1:1.0.0.1;project2:1.2.3.4" /vn "project1:1.0.0.1;project2:1.2.3.4" /fv "project1:1.0.0.1;project2:1.2.3.4" /fvn "project1:1.0.0.1;project2:1.2.3.4"
```
  If no project name is specified, the version number will be used by all projects. For example,
```
PBAutoBuild220 /f c:\test.json /v "1.0.0.1"
```
  The version numbers specified by parameters take precedence over those specified in the build file.
- /h or /? -- display the help information. For example,
```
PBAutoBuild220 /h
```
Check if PBAutoBuild220 command is successful via errorlevel. For more information, refer to Verifying if PBAutoBuild is successful.

Note

The handling of PB.INI is the same in PBAutoBuild and OrcaScript:

If the application relies on a property in PB.INI to run, for example, [RichText] PageSizeAsControlSize=1, the user needs to copy the PB.INI file to the directory where the application executable resides.

If the compilation of PBAutoBuild or OrcaScript relies on a property in PB.INI, for example, [PB] DashInIdentifiers=0, the user needs to copy the PB.INI file to the directory where PBAutoBuild220.exe or pbc220.exe resides.

Tutorial: Building your client/server application with commands

Task 1: Exporting the build file
Task 2: Building with commands

Besides building your client/server application project in the PowerBuilder IDE, you can also build your client/server application project using a command line tool (PBAutoBuild220.exe).

Task 1: Exporting the build file

Preparing the environment
Exporting the build file
Modifying the build file

Preparing the environment

For convenience, you can directly export the configuration of an existing client/server application project from the PowerBuilder IDE to a JSON build file. Therefore, you will need to prepare a proper environment first.

Step 1: Install the following software to set up the PowerBuilder development environment.

Windows 11 or 10
PowerBuilder IDE 2022 R2
PowerBuilder Runtime 2022 R2

Step 2: Created and build the Application project for the Example Sales Demo successfully in the PowerBuilder IDE.

Exporting the build file

Now let's export the Application project settings of the Example Sales Demo to a JSON file.

You can export the current project or all projects from the workspace (or target).

To export the current project:

Open the workspace for the Example Sales App in the PowerBuilder IDE, and then double-click the Application project object to open the Application project painter.
When the Application project painter is opened, click the Export Build File button () in the toolbar.
In the Export Build File dialog box, specify the settings, write down the path and filename to be exported, and then click Export.

For more information about the settings, refer to Building a client/server application with commands.

The current project will be exported to the build file.

To export all of the projects from the workspace (or target):

Open the workspace for the Example Sales App in the PowerBuilder IDE, and then right click the workspace (or target) in the System Tree and select Export Build File.
In the Export Build File dialog box, select which target(s) to be exported.

If the workspace contains multiple targets, then by default all targets will be exported to the same build file.
Select which project type(s) to be exported.

By default, all project types under the workspace (or target) will be exported to the build file.
Specify the settings, write down the path and filename to be exported, and then click Export.

Modifying the build file

About the build file

The exported build file contains all the settings required for building and deploying the PBL files of the Example Sales App and some additional settings:

Build file content	Description
"MetaInfo": { "IDEVersion": "220", "RuntimeVersion": "22.0.0.1311" },	This section contains the version number of the PowerBuilder IDE and PowerBuilder Runtime currently in use.
"BuildPlan": { "SourceControl": { "PreCommand": "", "ClearSrcBeforeDownload": false, "SVN": [ ... ], "Git": [ ... ], "VSS": [ ... ], "Merging": [ ... ], "PostCommand": "" }, "BuildJob": { "PreCommand": "", "Projects": [ ... ], "PostCommand": "" } },	This section contains settings for source control and build jobs. "SourceControl" -- Provides settings for downloading and merging source code from the source control server (including SVN, Git, and/or VSS). You can download source code from SVN, Git, or VSS. If the source code is the objects in ws_objects, you can merge the objects to the PBL file. Merging will not only merge the source code but also upgrade the source code to the current version. However, it will not check or upgrade the PBD files used in the library list (you will need to replace the PBD files with the corresponding version). You can download and merge source code for one or more targets at one time. See Getting source code from SVN, Git, or VSS for more details and examples. The "ClearSrcBeforeDownload" setting is for removing files from the source code folder (specified by the "DestPath" setting) before downloading the source code. The "Git" > "Branch" setting is for downloading source code from the specified branch. The "Merging" > "RefreshPbl" setting is for refreshing the PBL files by deleting and then generating the PBL files again. Tip If you use Git repositories to host and collaborate on your code using Team Foundation Server (TFS) or Azure DevOps Server, you can configure the "Git" section in the build file to connect to Team Foundation Server (TFS) or Azure DevOps Server. See the next section for more information. "BuildJob" -- Contains the location of the PowerBuilder application target(s) and the name of the project object(s). You can specify one or more targets and projects (of the same or different type) and build them at one time. Both the "SourceControl" and "BuildJob" blocks contain a "PreCommand" setting and a "PostCommand" setting which allow you to specify commands that can be executed before and/or after that particular block is executed. See Executing additional commands for more examples. The commands in "PreCommand" and "PostCommand" can be executed in synchronous (default) or asynchronous mode, and the command window can be visible or invisible (default). For example, "PostCommand": "postcmd.bat /show /async"
"Projects": { "project1": { ... }, "project2": { ... }, "project3": { ... }, ... }	This section lists the project(s) that has been exported. Every single setting that can be found in the project painter can also be found here. You can modify the settings here when necessary.

Build file content

Description

    "MetaInfo": {
        "IDEVersion": "220",
        "RuntimeVersion": "22.0.0.1311"
    },

This section contains the version number of the PowerBuilder IDE and PowerBuilder Runtime currently in use.

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "ClearSrcBeforeDownload": false,
            "SVN": [
                ...
            ],
            "Git": [
                ...
            ],
            "VSS": [
                ...
            ],
            "Merging": [
                ...
            ],
            "PostCommand": ""
        },
        "BuildJob": {
            "PreCommand": "",
            "Projects": [
                ...
       ],
            "PostCommand": ""
        }
    },

This section contains settings for source control and build jobs.

"SourceControl" -- Provides settings for downloading and merging source code from the source control server (including SVN, Git, and/or VSS).

You can download source code from SVN, Git, or VSS. If the source code is the objects in ws_objects, you can merge the objects to the PBL file. Merging will not only merge the source code but also upgrade the source code to the current version. However, it will not check or upgrade the PBD files used in the library list (you will need to replace the PBD files with the corresponding version).

You can download and merge source code for one or more targets at one time. See Getting source code from SVN, Git, or VSS for more details and examples.

The "ClearSrcBeforeDownload" setting is for removing files from the source code folder (specified by the "DestPath" setting) before downloading the source code.

The "Git" > "Branch" setting is for downloading source code from the specified branch.

The "Merging" > "RefreshPbl" setting is for refreshing the PBL files by deleting and then generating the PBL files again.

Tip

If you use Git repositories to host and collaborate on your code using Team Foundation Server (TFS) or Azure DevOps Server, you can configure the "Git" section in the build file to connect to Team Foundation Server (TFS) or Azure DevOps Server. See the next section for more information.
"BuildJob" -- Contains the location of the PowerBuilder application target(s) and the name of the project object(s).

You can specify one or more targets and projects (of the same or different type) and build them at one time.

Both the "SourceControl" and "BuildJob" blocks contain a "PreCommand" setting and a "PostCommand" setting which allow you to specify commands that can be executed before and/or after that particular block is executed. See Executing additional commands for more examples.

The commands in "PreCommand" and "PostCommand" can be executed in synchronous (default) or asynchronous mode, and the command window can be visible or invisible (default). For example,

"PostCommand": "postcmd.bat /show /async"

    "Projects": {
        "project1": {
            ...
        },
        "project2": {
            ...
        },
        "project3": {
            ...
        },
        ...
    }

This section lists the project(s) that has been exported. Every single setting that can be found in the project painter can also be found here. You can modify the settings here when necessary.

Settings in the build file are independent from each other; they run in sequence but do not rely on other settings or execution results, for example, if there is already source code in ws_objects, then you only need to set the Merging setting, and leave Git, SVN, and VSS empty as there is no need to download source code; or if there are PBLs in your Git server, then you only need to set the Git setting (to download PBLs) and leave the Merging setting empty. If you do not want a setting to run, just leave that setting with no values; or add "\\" in front of the setting name, for example, "\\Git" or "\\SourceControl", to skip the setting.

It is recommended that you make a copy of the exported build file and place it to the same location or a location near your PowerBuilder application target, so that you could manage the file path (especially the relative file path) easily.

Note: the relative path specified in the build file is relative to the build file.

Getting source code from SVN, Git, or VSS

You can configure the exported build file to download source code from SVN, Git, or VSS before the build process starts.

Step 1: Make a copy of the exported build file and place it to a location near your PowerBuilder application target, so that you could manage the file path (especially the relative file path) easily.

Note: the relative path will be relative to the build file.

Step 2: Open the build file in a text editor, locate the "BuildPlan" section and then configure the corresponding part.

If the computer connects to Git or SVN through a proxy server, make sure to configure the proxy server settings in the "Proxy" part.

The following example shows how to download source code from Git:

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "ClearSrcBeforeDownload": false,
            "SVN": [
                {"SrcPath": "","User": "","Password": "","DestPath": "","Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],
            "Git": [
                {"SrcPath": "https://github.com/Appeon/PowerBuilder-AutoBuild-Sales-SourceCode", "User": "tester@appeon.com", "Password": "YGRrYjc6OzU=", "DestPath": ".\\Build", "Branch": "", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],

You can also download source code from multiple targets at one time:

           "Git": [
                {"SrcPath": "https://github.com/Appeon/PowerBuilder-AutoBuild-Sales-SourceCode", "User": "tester@appeon.com", "Password": "YGRrYjc6OzU=", "DestPath": ".\\Build_Sales", "Branch": "", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}},
                {"SrcPath": "https://github.com/Appeon/PowerBuilder-AutoBuild-Examples-SourceCode", "User": "tester@appeon.com", "Password": "YGRrYjc6OzU=", "DestPath": ".\\Build_Examples", "Branch": "", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],

The following example shows how to download source code from Team Foundation Server (TFS) or Azure DevOps Server:

IMPORTANT: To download source code from Team Foundation Server (TFS) or Azure DevOps Server, you will need to configure the "Git" section, and input your Personal Access Token (PAT) as the user name and password for connection.

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "ClearSrcBeforeDownload": false,
            "SVN": [
                {"SrcPath": "","User": "","Password": "","DestPath": "","Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],
            "Git": [
                {"SrcPath": "https://402977329@dev.azure.com/402977329/kittytest/_git/kittytest","User": "402977329@qq.com","Password": "ZHFgcXVsZndtY2hicHJkZHxuMXlicXxufjF7OzVzOzB8ejpmcjthZz15eWB5aW0/bDV+eQ==","DestPath": "C:\\TFStest\\bug1853_1","Branch": "master","Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],

The following example shows how to download source code from VSS:

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "ClearSrcBeforeDownload": false,
            "SVN": [ 
                {"SrcPath": "","User": "","Password": "","DestPath": "","Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],
           "Git": [
                {"SrcPath": "","User": "","Password": "","DestPath": "","Branch": "","Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],
            "VSS": [
                {"SrcPath": "\\\\192.168.0.100\\Project_VSS\\\"$/Salesdemo/native_pb/appeon.salesdemo\", YYOAAAAA","User": "tester","Password": "","DestPath": ".\\Build"}
            ],

Notes:

1) Connecting to Git or SVN through a proxy server is supported; but connecting to VSS through a proxy server is not supported yet.

2) The password for VSS is not supported. The VSS login window will be displayed for you to input the password before downloading the source code. The password for SVN or Git must be an encrypted value which is generated from the original password by executing "PBAutoBuild220.exe /p", as shown below.

3) Getting an SVN/VSS branch is completely unsupported. Getting a Git branch can be supported by using the "Branch" setting.

Step 3: If the source code downloaded from SVN, Git, or VSS is not the PBL file but objects in ws_objects, then you will need to merge the objects to the PBL file. Locate the "Merging" section in the build file and then configure as below:

Setting "RefreshPbl" to true if you want to refresh the PBL files by deleting and then generating the PBL files again.

            "Merging": [
                {"Target": ".\\Build\\salesdemo.pbt", "LocalProjectPath": ".\\Build", "RefreshPbl": false}
            ],

You can also merge source code for multiple targets at one time:

            "Merging": [
                {"Target": ".\\Build_Sales\\salesdemo.pbt", "LocalProjectPath": ".\\Build_sales", "RefreshPbl": true},
                {"Target": ".\\Build_Examples\\examples.pbt", "LocalProjectPath": ".\\Build_Examples", "RefreshPbl": true}
            ],

Merging will not only merge the source code but also upgrade the source code to the current version. However, it will not check or upgrade the PBD files used in the library list (you will need to replace the PBD files with the corresponding version).

At the same time, make sure to double check the target location is set correctly in the "Projects" section, for example,

        "BuildJob": {
            "PreCommand": "",
            "Projects": [
                {"Target": ".\\Build_Sales\\salesdemo.pbt", "Name": "salesdemo_pbnative"}
                {"Target": ".\\Build_Examples\\examples.pbt", "Name": "examplesdemo_pbnative"}
            ],
            "PostCommand": ""
        }

When the PBAutoBuild220.exe command is executed later, it will first download the source code from the Git server and then merge the source code.

Executing additional commands

The entire build process is made up of several steps, and additional commands can be executed before and/or after some particular steps such as the "SourceControl" and "BuildJob" steps.

For example, to add commands to remove a folder before downloading the source code.

Step 1: Create a bat file which contains the following command, and save the bat file as Command_DeleteFolder.bat.

RMDIR /s /q "D:\PB2022\SalesDemo\test"

Step 2: In the build file, locate the "BuildPlan" section and then the "PreCommand" sub-section; and add the file path and name of Command_DeleteFolder.bat.

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "Command_DeleteFolder.bat",
            "ClearSrcBeforeDownload": false,
            "SVN": [
               ...
            ],

When the PBAutoBuild220.exe command is executed later, it will execute the commands in Command_DeleteFolder.bat before it downloads the source code.

Besides the "PreCommand" setting, there is also a "PostCommand" setting for the "SourceControl" and "BuildJob" steps, which allows you to execute commands after that particular step. See Example 2 and 3 for more details.

Note

The dotnet commands can also be integrated with Jenkins. See Task 2 for more details.

Task 2: Building with commands

Preparing the environment
Running the command line tool
Verifying if PBAutoBuild is successful
Integrating with Jenkins

Preparing the environment

To build and deploy the client/server application project using the command line tool (instead of within PowerBuilder IDE), install the following software.

Windows 11 or 10, or Windows Server 2022, 2019, or 2016
PowerBuilder Utilities 2022 R2

The command line tool (PBAutoBuild220.exe) is included in PowerBuilder Utilities.
PowerBuilder Runtime 2022 R2

The PBAutoBuild220.exe tool can automate the entire build and deploy process outside PowerBuilder (without needing any PowerBuilder license).

Running the command line tool

Step 1: Copy the exported JSON build file to the current machine and double check the file paths in the build file are appropriate to the current environment.

Step 2: Copy the application source code (including PBT, PBL, PBR, images, INI etc.) to the current machine, or configure the build file to download source code from the source control server.

Step 3: In the command line window, execute the PBAutoBuild220.exe file and the build file. For example,

PBAutoBuild220.exe /f "D:\PB2022\SalesDemo\salesdemo_pbnative.json" /l Log_PBBuild.log /le Log_PBError.log

The PBAutoBuild220.exe file can be running with several parameters. For a complete list, refer to Building a client/server application with commands.

Step 4: Carefully check the information in the command line window to make sure the build process is successful.

The build file and commands used in this tutorial can be downloaded from https://github.com/Appeon/PowerBuilder-AutoBuild-Sales-Example. After you download these files to D:\PB2022\SalesDemo\, you can follow instructions in the readme file.

Verifying if PBAutoBuild is successful

After executing the PBAutoBuild220.exe file and the build file, you can check if the execution is successful via the Windows command errorlevel:

errorlevel = 0 indicates the process was successful.
errorlevel = 1 indicates the process encountered an error.

For example, you can write scripts like below to check the execution result:

Echo off
PBAutoBuild220.exe /f "D:\PB2022\SalesDemo\salesdemo_pbnative.json" /l Log_PBBuild.log /le Log_PBError.log 
If %ERRORLEVEL% == 0 (
    echo Run PBAutoBuild successfully.
) Else (
   echo Failed to run PBAutoBuild, Errorlevel is %ERRORLEVEL%.
)

Integrating with Jenkins

The PBAutoBuild220 command can integrate with Jenkins to automate the build process for Application projects. Refer to the Jenkins user documentations for how to use Jenkins.

Following gives a few examples on how to integrate the PBAutoBuild220 command with Jenkins.

For example, to execute the PBAutoBuild220 command and the build file.

For example, to download source code from SVN, Git, or VSS, and then execute the PBAutoBuild220 command and the build file. (Double check that the PBT location is the same one in all required areas.)

Prev	Up	Next
Distributing resources	Home	Working with a PowerClient project

Users GuideCreating Executables and Components