Creating Executables and Components -

Creating Executables and Components

About building PowerBuilder targets
Using the Project painter
Using dynamic libraries
Attaching or embedding manifest files
Distributing resources
Working with an Application project
Working with a PowerClient project
Working with a PowerServer project
Building proxies and .NET targets

About this chapter

This chapter describes how to create an executable version of your target. It also provides an overview of how you use the PowerBuilder Project painter to build other kinds of components.

About building PowerBuilder targets

You can build many types of targets with PowerBuilder. For traditional client/server applications, you need to create an executable version of your target that you can deploy to users' computers. If you are building a distributed application with PowerBuilder, you typically build a client executable file and a server component that you can deploy to a transaction server. For some types of distributed applications, you need to build proxy objects.

Building executable files

If you are building an executable file, there are two basic ways to package the application:

As one standalone executable file that contains all the objects in the application
As an executable file and one or more dynamic libraries that contain objects that are linked at runtime

Read the section called “Packaging an Application for Deployment” in Application Techniques to get an understanding of the best way for you to package the application. Then follow the procedures in Defining an executable application project to implement your strategy.

Building other types of targets

For an overview of how you use the Project painter to build different types of components, see Building proxies and .NET targets.

Providing other resources

You might need to provide additional resources that your target uses, such as bitmaps and icons. There are two ways to provide resources:

Distribute them separately
Include them in a PowerBuilder resource file (PBR) and build an executable, a dynamic library, or a component using the resource file

For more information, see Distributing resources.

Building the workspace

You can build and deploy all the targets in your workspace using buttons on the PowerBar, pop-up menus in the System Tree, or a command line. For more information, see Building workspaces.

Using the Project painter

Creating a project

You use the Project painter to create and maintain PowerBuilder projects that build all these different objects. The Project painter allows you to streamline the generation of the files your target needs and to rebuild easily when you make changes. There is a wizard to help you set up each project type.

The following table lists the types of projects you can create and what you can build using the project.

Project	What it builds
Application	An executable file and optional dynamic libraries that need to be installed/updated to the client manually.
PowerClient	An executable file and optional dynamic libraries that can be installed/updated automatically from a server.
PowerServer	An executable file and optional dynamic libraries that can be installed/updated automatically from a server and DataWindow objects and embedded SQLs that run as RESTFul Web APIs in a cloud-based n-tier architecture.
EJB Client Proxy (obsolete)	Enterprise JavaBeans components are obsolete technology, and will be removed in a future release. One or more proxy objects (stubs) that can be used by a PowerBuilder client to access functions in an EJB component on an application server.
.NET Assembly (obsolete)	A .NET assembly containing one or more custom class user objects.
.NET Web Service (obsolete)	A .NET Web service containing one or more custom class user objects.
Web Service Proxy (obsolete)	A proxy object that can be used by a PowerBuilder client to invoke a Web service defined in a WSDL (Web Services Description Language) file.

For how to create a new project, see Creating a project.

Creating a project

You can create a new project when you create a new target using most Target wizards. You can also create a project at any time from the Project page in the New dialog box if you have already created a target of the appropriate type.

The Project page has two kinds of icons: icons that open wizards that help you set up a project, and icons that open the Project painter. Wizard icons display next to the icon for the same project type. The following procedure describes how to create a new project from the Project page.

To create a new project object from the Project page:

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 wizard or project type you need and click OK.

If you select a 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 do not select a wizard, the Project painter for the type of object you selected opens so that you can specify properties of the project object.

Once you have created a project, you can open it from the System Tree.

Projects can be modified only in the painter

Unlike most other PowerBuilder objects, a project object cannot be edited in the Source editor.

Target-relative paths and shared projects

All paths used in projects are stored as target-relative paths, if possible. If you later move the application to a different location in the file system, or another user copies or checks out the application, the paths are adjusted relative to the new target location.

For example, suppose user A has an application target stored in the following directory structure, where pbl_1.pbl contains the application object:

C:\target1\target1.pbt
C:\target1\pbls\pbl_1.pbl
C:\target1\pbls\pbl_2.pbl
C:\target1\res\target1.pbr
C:\target1\out\target1.exe

When user B copies the application to the following directory structure, no changes need to be made in the Project painter, because the paths reflect the new directory structure:

D:\PB\My Targets\Target 1\target1.pbt
D:\PB\My Targets\Target 1\pbls\pbl_1.pbl
D:\PB\My Targets\Target 1\pbls\pbl_2.pbl
D:\PB\My Targets\Target 1\res\target1.pbr
D:\PB\My Targets\Target 1\out\target1.exe

A projects that was created in an earlier version of PowerBuilder using hard-coded paths must be opened and resaved before the files it references are modified with target-relative paths.

If a path is not on the drive where the target is stored, then the path is stored as an absolute path. For example, the path to image files stored on a shared network directory such as J:\res\images\common is stored as an absolute path in the project file.

References to files outside the target path

If a project references a PBL or another file on a local drive that is outside the path of the target, make sure that the PBL or file is copied to the new target location and that it is referenced correctly in the project.

Using dynamic libraries

You can store the objects used in your PowerBuilder application in more than one library and, when you run the application, dynamically load any objects that are not contained in the application's executable file. This allows you to break the application into smaller units that are easier to manage and makes the executable file smaller. You do this by using dynamic libraries. If you compile using Pcode, PowerBuilder builds PowerBuilder dynamic libraries (PBD files). If you use machine code, PowerBuilder builds Dynamic Link Libraries (DLL files).

When you distribute your application to users, you distribute the executable, the dynamic libraries, and PowerBuilder runtime DLLs. For more information about deployment and a list of PowerBuilder runtime DLLs, see the section called “Deploying Applications and Components” in Application Techniques.

Dynamic library names

PowerBuilder dynamic libraries are given the name of the PBL with the extension .pbd. For example, the Pcode library built from test.pbl is named test.pbd.

Machine-code dynamic libraries are given the extension .dll. For example, the machine-code library built from test.pbl is named test.dll.

Reducing the size of dynamic libraries

When PowerBuilder builds a dynamic library, it copies the compiled versions of all objects from the source library (PBL file) into the dynamic library.

The easiest way to specify source libraries is simply to use your standard PowerBuilder libraries as source libraries. However, using this technique can make your dynamic libraries larger than they need to be, because they include all objects from the source library, not just the ones used in your application. You can create a PowerBuilder library that contains only the objects that you want in a dynamic library.

To create a source library to be used as a dynamic library:

In the Library painter, place in one standard PowerBuilder library (a PBL file) all the objects that you want in the dynamic library.
If you need to create a new library, select Entry>Library>Create from the menu bar, then drag or move the objects into the new library.
Make sure the application's library search path includes the new library.

Multiple dynamic libraries

You can use as many dynamic libraries as you want in an application. To do so, create a source library (PBL file) for each of them.

Specifying the dynamic libraries in your project

When you define your project, you tell PowerBuilder which of the libraries in the application's library search path will be dynamic by checking the PBD or DLL check box next to the library name in the Project painter.

Including additional resources for a dynamic library

When building a dynamic library, PowerBuilder does not inspect the objects; it simply copies the compiled form of the objects into the dynamic library. Therefore, if any of the objects in the library use resources (pictures, icons, and pointers)—either specified in a painter or assigned dynamically in a script—and you do not want to provide these resources separately, you must list the resources in a PowerBuilder resource (PBR) file. Doing so enables PowerBuilder to include the resources in the dynamic library when it builds it.

To reference additional resources:

List the resources in a PBR file, as described in Using PowerBuilder resource files.
Use the Resource File Name box in the Project painter workspace to reference the PBR file in the dynamic library.

Attaching or embedding manifest files

If you want to deploy an application to the Windows operating system that meets the certification requirements of the Windows logo program, you must follow User Account Control (UAC) guidelines. The executable file must have an embedded manifest that defines the execution level and specifies whether access to the user interface of another window is required. The Application Information Service (AIS) checks the manifest file to determine the privileges with which to launch the process. Use the Security tab page in the Project painter to specify these properties.

Generate options

Select Embedded manifest if your application needs to be certified for Windows. A manifest file with the execution level you select is embedded in the application's executable file.

You can also select External manifest to generate a standalone manifest file in XML format that you ship with your application's executable file, or No manifest if you do not need to distribute a manifest file.

Execution level

Select As Invoker if the application does not need elevated or administrative privileges. Selecting a different execution level will probably require that you modify your application to isolate administrative features in a separate process to receive Windows certification.

Select Require Administrator if the application process must be created by a member of the Administrators group. If the application user does not start the process as an administrator, a message box displays so that the user can enter the appropriate credentials.

Select Highest Available to have the AIS retrieve the highest available access privileges for the user who starts the process.

UI access

If the application needs to drive input to higher privilege windows on the desktop, such as an on-screen keyboard, select the "Allow access to protected system UI" check box. For most applications you should not select this check box. Microsoft provides this setting for user interface Assistive Technology (Section 508) applications.

Authenticode signing required

If you check this box, the application must be Authenticode signed and must reside in a protected location, such as Program Files or Windows\system32.

Distributing resources

Distributing resources separately
Using PowerBuilder resource files
What happens at runtime

You can choose to distribute your resources (pictures, pointers, and icons) separately or include them in your executable file or dynamic library.

Distributing resources separately

When a resource is referenced at runtime, if the resource has not been included in the executable file or in a dynamic library, PowerBuilder looks for it in the search path. You need to distribute resources with your application and make sure they get installed in the user's search path.

For example, assume you use two bitmap files as in the following script:

IF Balance < 0 THEN
   p_logo.PictureName = "frown.bmp"
ELSE
   p_logo.PictureName = "smile.bmp"
END IF

You can distribute the files frown.bmp and smile.bmp with your application. If the files are on the search path at runtime, the application can load them when they are needed.

The Windows search path is as follows:

The current directory
The Windows directory
The Windows system directory
All directories in the PATH environment variable

Using PowerBuilder resource files

Instead of distributing resources separately, you can create a PowerBuilder resource file (a PBR file) that lists all dynamically assigned resources.

A PBR file is an ASCII text file in which you list resource names (such as BMP, CUR, GIF, ICO, JPEG, RLE, WMF, and PNG files) and DataWindow objects. To create a PBR file, use a text editor. List the name of each resource, one resource on each line, then save the list as a file with the extension PBR.

Here is a sample PBR file:

ct_graph.ico
document.ico
codes.ico
button.bmp
next1.bmp
prior1.bmp
background.png

PowerBuilder compiles the listed resources into the executable file or a dynamic library file, so the resources are available directly at runtime.

Using DataWindow objects

If the objects in one PBL reference DataWindow objects, either statically or dynamically, that are in a different PBL, you must either specify a PowerBuilder resource file that includes the DataWindow objects, or define the library that includes them as a PBD or DLL that you distribute with your application. You cannot distribute them separately as you can image files.

For more information about creating and using PBR files, see the section called “Packaging an Application for Deployment” in Application Techniques.

What happens at runtime

When a resource such as a bitmap is referenced at runtime, PowerBuilder first looks in the executable file for it. Failing that, it looks in the PBDs that are defined for the application. Failing that, it looks in directories in the search path for the file.

Working with an Application project

Creating an Application project
Defining an Application project
Tracing execution
Building a client/server application and dynamic libraries
Building a client/server application with commands
Tutorial: Building your client/server application with commands

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 Complier. For more information about PowerBuilder Complier, see About OrcaScript or the standalone PBC user guide (pbc.pdf) in the PBC folder after installation.
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: 19.2.0.2670)". 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 PBAutoBuild210 command. For step-by-step guidance, refer to Tutorial: Building your client/server application with commands. The PBAutoBuild210 command can 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.
The exported JSON file includes every single setting that is required for building the Application project, just to name a few, for example,
- Project settings such as project type, platform (32-bit or 64-bit), build options, code type (Pcode or Machine code) etc.
- Library list
- Version information
- Run options
- ...
You can find a complete list of settings under the "Projects" block in the exported file.

The exported file also contains a "BuildPlan" block which provides additional configurations:
- Settings for downloading and merging source code from the source control server (including SVN, Git, and/or VSS).
  
  Locate the "SourceControl" section to configure the settings.
  
  For example,
```
    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "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", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],
```
  Note: The password must be an encrypted value which is generated from the original password by executing "PBAutoBuild210.exe /p".
  
  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 exported build file and then configure as below:
```
            "Merging": [
                {"Target": ".\\Build\\salesdemo.pbt", "LocalProjectPath": ".\\Build", "RefreshPbl": false}
            ],
```
  Setting "RefreshPbl" to true if you want to refresh the PBL files by deleting and then generating the PBL files again.
  
  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\\salesdemo.pbt", "Name": "salesdemo_pbnative"}
            ],
            "PostCommand1": ""
        }
```
- In the "SourceControl" and "BuildJob" sections, you could also specify commands that can be executed before and/or after that particular section is executed.
  
  Locate the "PreCommand" and "PostCommand" keywords to specify the commands or command file, for example,
```
    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "Command_DeleteFolder.bat",
            "SVN": [
                ...
            ],
```
  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"
```
Note: The relative path specified in the file is relative to the path of the JSON file.
Execute the PBAutoBuild210.exe file and the JSON file in a command line to automatically build the project. For example,
```
PBAutoBuild210.exe /f "D:\PB2021\SalesDemo\salesdemo_exe.json" /l Log_PBBuild.log /le Log_PBError.log
```
The PBAutoBuild210.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.
```
PBAutoBuild210 /f D:\PB2021\SalesDemo\salesdemo_exe.json
```
- /l -- write the logging information to a file.
- /le -- write the error information to a file. For example,
```
PBAutoBuild210 /f D:\PB2021\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, Git, or VSS. This will generate an encrypted value based on the password. If the password contains the double quotation mark ("), use the escape character \" to replace ".
```
PBAutoBuild210 /p abcd1234
```
- /h or /? -- display the help information. For example,
```
PBAutoBuild210 /h
```

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 PBAutoBuild210.exe or pbc210.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 (PBAutoBuild210.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 10 or 8.1
PowerBuilder IDE 2021
PowerBuilder Runtime 2021

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:

Step 1: 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.

Step 2: When the Application project painter is opened, click the Export Build File button () in the toolbar.

Step 3: In the Export Build File dialog box, write down the path and filename to be exported, and then click Export.

Modifying the build file

Getting source code from SVN, Git, or VSS
Executing additional commands

The exported build file contains all the settings required for building the PBL files of the Example Sales App. It also contains some advanced settings that allow you to:

Get and merge source code from SVN, Git, or VSS;
Execute additional commands during the build process.

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, for example, "Git" as shown below.

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

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "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", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],

Note: The password must be an encrypted value which is generated from the original password by executing "PBAutoBuild210.exe /p", as shown below.

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}
            ],

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\\salesdemo.pbt", "Name": "salesdemo_pbnative"}
            ],
            "PostCommand1": ""
        }

When the PBAutoBuild210.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 the "build" 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:\PB2021\SalesDemo\Build"

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",
            "SVN": [
               ...
            ],

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

Besides the "PreCommand" sub-section, there is also a "PostCommand" sub-section for the "SourceControl" and "BuildJob" steps, which allows you to execute commands after that particular step.

Task 2: Building with commands

Preparing the environment
Running the command line tool
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 10 or 8.1, or Windows Server 2019, 2016, or 2012 R2
PowerBuilder Compiler 2021

The command line tool (PBAutoBuild210.exe) is included in PowerBuilder Compiler.
PowerBuilder Runtime 2021

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 PBAutoBuild210.exe file and the build file. For example,

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

The PBAutoBuild210.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:\PB2021\SalesDemo\, you can follow instructions in the readme file.

Integrating with Jenkins

The PBAutoBuild210 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 PBAutoBuild210 command with Jenkins.

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

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

Working with a PowerClient project

Configuring a deployment server
Uploading the app launcher and runtime files
Creating a PowerClient project
Defining a PowerClient project
Building and deploying a PowerClient project
Building and deploying the PowerClient project with commands
Running the PowerClient project
Packaging the PowerClient project
Undeploying the PowerClient project
Uninstalling the PowerClient project
Changing external files using commands
Supporting cookie validation
Rolling back to an earlier version of app
Tutorial 1: Deploying your first PowerClient project
Tutorial 2: Building your PowerClient project with commands

Configuring a deployment server

The applications deployed with PowerClient will be installed and updated through a Web server. Therefore, you will need to configure a Web server for deployment.

To configure a deployment server:

Set up a Web server according to the documents provided by the vendor.

Any type of Web server (such as IIS, Apache, Nginx etc.) is supported. You can set up FTP on the server, so that you can remotely deploy the app to the server. For how to configure FTP on a server running against IIS, refer to Configure an FTP server. For how to configure SSL on a server running against IIS, refer to Configure an SSL-based FTP server.
Select Tools>Web Server Profile from the menu bar to open the Server Configuration window.
In the Server Configuration window, configure a local or remote Web server where the application will be deployed.
- To configure a local Web server, select the Local Server tab and specify the Web root of the Web server (for example %systemdrive%\inetpub\wwwroot for IIS) or a subdirectory under the Web root. Click Test File Path to make sure the specified path is valid for deployment.
  
  Note
  
  If you intend to deploy to a local Web server, make sure you run PowerBuilder as administrator or have write permissions to the specified directory (administrator rights are required when transferring files to a local Web server).
- To configure a remote Web server, select the Remote Server tab, click Add to create a server profile. You will need to specify the profile name and the following FTP settings: host name, port number, user name, password, and encryption settings. Click Test FTP Connection to make sure the specified settings are correct for deployment.
The server configuration will be used by all PowerClient projects; therefore if you have changed the server settings, you will need to upload the app launcher if no launcher has been uploaded to that server or directory.

Note

If you intend to deploy to the Web server through a proxy server, make sure the proxy server and the FTP server have the same encoding, otherwise, the multi-byte characters in the file/folder name will become unrecognizable after deployed to the server.

Note

As PowerBuilder is designed to be case-insensitive, therefore, in a case-sensitive system like Linux, some app files (such as images) may not be found or loaded. To avoid any issue caused by the case of file name, make sure to configure the Linux server to ignore case-sensitive.

Uploading the app launcher and runtime files

About cloud app launcher

The app launcher and the runtime files must be uploaded to the server, and then installed to the client when the application is run for the first time. The app launcher and the runtime files will be used by all apps that are deployed to the same server and directory.

Note that there will be only one app launcher in the specified server and directory, although there can be multiple versions of runtime files. The app launcher will be overwritten without notice by the one uploaded later to the same server and directory.

To upload the app launcher and runtime files:

Select Tools>Upload Cloud App Launcher from the menu bar. The Upload Cloud App Launcher and Runtime window appears.
In the Upload Cloud App Launcher and Runtime window, select whether to directly upload the app launcher and runtime files to the server or only create a zip package and manually upload it to the server later.
- To directly upload the app launcher and runtime files to the server, select a local server or a remote server where the app launcher and the runtime files will be uploaded.
- To create a zip package which will be manually uploaded later, specify where the zip package will be created.
IMPORTANT: the app launcher and runtime files must be uploaded to the same server and directory where the application will be deployed. If you have not configured the server yet, follow instructions in Configuring a deployment server to configure the server first.
Select the runtime files (32-bit and/or 64-bit) to upload.

The version of runtime files is determined by the runtime version selected in the IDE > System Options. Multiple versions of runtime files can co-exist on the same server and directory.
Select or create an app launcher to upload.

You can select an existing app launcher from the Launcher profile list:
- Default_WithoutService -- This profile specifies the launcher without the background service. It contains the following default settings:
  - Launcher without background service is selected.
- Default_WithServiceSingle -- This profile specifies the launcher with the background service which supports single Windows user by default. It contains the following default settings:
  - Launcher with background service is selected.
  - Single user is selected.
- Default_WithServiceMulti -- This profile specifies the launcher with the background service which supports multiple Windows users by default. It contains the following default settings:
  - Launcher with background service is selected.
  - Multiple users is selected.
- Default_Both_WithServiceSingle -- This profile specifies the launcher with the background service and the launcher without the background service; and the launcher with the background service supports single Windows user by default. This profile contains the following default settings:
  - Launcher without background service is selected.
  - Launcher with background service is selected.
  - Single user is selected.
- Default_Both_WithServiceMulti -- This profile specifies the launcher with the background service and the launcher without the background service; and the launcher with the background service supports multiple Windows users by default. This profile contains the following default settings:
  - Launcher without background service is selected.
  - Launcher with background service is selected.
  - Multiple users is selected.
Or you can create your own launcher by clicking the Create button, if you want to customize the launcher settings.
- Specify a profile name for your new launcher.
- Specify where to save your new launcher on the local machine.
- On the General tab, specify the title and the logo (ICO format) that will be shown in the launcher.
- On the Advanced Options tab, specify where to install the application on the client. The path in the App path field will be used as the default installation path. If you want to allow the user to select where to install the application during the installation process, you can select "Allow the user to change the path".
  
  IMPORTANT: If you want to set a different path as the default path instead of %AppData%\PBApps, you should NOT include the system variable (such as %windir%, %temp% etc.) other than %AppData%, because currently only the %AppData% variable is supported.
- On the Advanced Options tab, specify which app launcher will be uploaded and installed: launcher without background service, or launcher with background service, or both. When Launcher with background service is selected, you can specify the launcher with background service supports single Windows user by default or supports multiple Windows users by default, and/or if you want to allow the user to select which user option to support during the installation process, you can select "Allow the user to change the option".
- On the Signing tab, select whether to digitally sign the launcher executable file (CloudAppLauncher_Installer.exe).
  
  If you want to digitally sign the launcher executable file, you can specify the settings required for signing under the "Use the SignTool utility from the Windows SDK" option, for example, SignTool location, signing certificate, certificate password, signature algorithm, and URL of the time stamp server. And make sure Microsoft’s SignTool has been installed on the current machine.
  
  Or you can place the signing scripts in a file (with file extension as .cmd) and then select the file for the "Use your own signing script" option. For example, to sign the executable file (CloudAppLauncher_Installer.exe) using Microsoft’s SignTool, you may create a cmd file that includes the following scripts:
```
signtool.exe sign /f mycert.pfx /p password /d "My app launcher" /du http://www.mytest.com /fd sha256 /tr "http://timestamp.digicert.com" /td sha256 CloudAppLauncher_Installer.exe
```
  After the executable file is generated and before it is uploaded to the server, PowerBuilder will sign the executable file using your own signing scripts or using the SignTool settings you specified.
Tip

To remove a launcher profile, go to the path where the launcher is saved (by default, C:\Users\appeon\AppData\Roaming\CloudAppLauncher), go into the folder which corresponds to the launcher version and then delete the sub-folder that is named after the profile.

About cloud app launcher

The Cloud App Launcher is a launcher program that must be first installed to the user’s machine. It facilitates the initial installation and subsequent updates of your PowerBuilder applications over HTTP/HTTPS.

There are two launcher types. You can determine which type of cloud app launcher you want to upload to the server:

Launcher without background service: This launcher program does NOT use a background service. As such, it should be easier to install and use and does not require administration rights. However, it has certain dependency on the browser, which may result in different installation experience depending on the browser used and its configuration. If there are multiple users on the client machine, the launcher will need to be installed for each user.
Launcher with background service: The launcher program uses a background service. If there are multiple users on the client machine, the launcher will need to be installed for each user, and only the first installation requires administrator rights to install and start the service. If the launcher is installed on the machine for the first time by a user without administrator rights, a window will pop up for inputting the administrator user name and password; after that, the other users also need to install the launcher but they do not need to have administrator rights, and all users will use the service started by the first installation. This launcher type does NOT have dependency on the browser.

Why cloud app launcher is needed

The cloud app launcher works as a "helper" application that installs, starts, and updates the PowerBuilder application over HTTP/HTTPS, besides that the cloud app launcher can be opened by the Web browser, therefore it enables the PowerBuilder application to be started through a Web browser (the Web browser launches the cloud app launcher; and then the cloud app launcher launches the PowerBuilder application).

How cloud app launcher is installed

The cloud app launcher will be automatically downloaded from the Web server and installed to the client when the user runs the application for the first time. However, some users are not able to install software on their computers without the assistance of an IT administrator. In such case, their IT administrator can get the installation package of the cloud app launcher from the PowerBuilder Runtime installation directory (for example, C:\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime 21.0.0.1311\CloudAppInstall\default) and install the cloud app launcher to the machine before the user runs the application.

The IT administrator can also run the following command to silently install the cloud app launcher.

CloudAppLauncher_Installer.msi /qn

When and why administrator rights are required?

When the cloud app launcher is first installed on the client, it needs to write to the registry for the purpose of

Registering a protocol to handle the app
Creating an entry for starting the launcher
Storing information that will be used by uninstall

Writing to the registry does not need administrator rights, unless the launcher with the background service which supports multiple Windows users (that is, the Default_WithServiceMulti or Default_Both_WithServiceMulti launcher) is installed, in such case, the launcher must be registered using administrator rights, so that the launcher can be started as a system service and used by all Windows users.

How multiple versions coexist

Currently, the two versions of cloud app launcher: 2019 R3 and 2021 will not coexist on the Web server and the client; only one of them will exist (either 2019 R3 or 2021). And the application deployed in 2019 R3 or 2021 can work with either of them.

If the client already has the 2019 R3 launcher, when running an app from a Web server that contains the 2021 launcher, the 2019 R3 launcher at the client will be upgraded to 2021.
If the client already has the 2021 launcher, when running an app from a Web server that contains the 2019 R3 launcher, because the launcher at the server is of lower version, the client will still use the 2021 launcher.
No matter the client has the 2019 R3 or 2021 launcher, the launcher can support the running of applications deployed from either 2019 R3 or 2021.

The IDE version used to deploy PowerClient or PowerServer projects	The Launcher that must exist at the web server	The Launcher that shall run at the client
2019 R3 (PowerClient only)	Either 2019 R3 or 2021 (only one version will exist)	Either 2019 R3 or 2021 (only one version will exist)
2021	Either 2019 R3 or 2021 (only one version will exist)	Either 2019 R3 or 2021 (only one version will exist)

Note: the launcher for version 2022 will be refactored, so the 2022 launcher will not work for 2019 R3 and 2021 apps, and vice versa. Therefore: (1) The 2022 launcher can co-exist with 2019 R3 or 2021 launcher at the Web server and also at the client side; (2) The 2022 launcher will work for 2022 apps only.

Creating a PowerClient project

You can create a PowerClient project by selecting the PowerClient project type.

To create a PowerClient 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 PowerClient project type and click OK.

The Project painter for PowerClient opens so that you can specify the various properties of your application.
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.

Defining a PowerClient project

Once you have created a PowerClient project, you can open it from the System Tree and modify the properties if necessary. The Project painter for the PowerClient project looks like this.

Note

If you want to view an example of the PowerClient project, you can open the demo app, for example, from Windows Start | Appeon PowerBuilder [version] | Example Sales App, and view the PowerClient project included in the demo.

The following table describes each of the options you can specify in the Project painter for PowerClient.

Page or Option		What you specify
General page	App name	Specify a name for the application.
	PBR file name	(Optional) Specify a PowerBuilder resource file (PBR) for your application if you dynamically reference resources (such as bitmaps and icons) in your scripts and you want the resources included in the application instead of having to distribute the resources separately. You can type the name of a PBR file in the box or click the button next to the box to browse your directories for the PBR file you want to include. The PBR file as well as the resources it references must reside in the application directory or subdirectory; and only relative paths of the PBR file and the resources will be accepted. For more about PBRs, see the section called “Distributing resources”.
	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 PowerClient to regenerate and redeploy all object files to the Web server. If you choose Incremental, PowerClient regenerates and redeploys only objects that have changed, and objects that reference any objects that have changed, since the last time you built the application. As a precaution, regenerate all objects before rebuilding your project.
	Enable DEBUG symbol	Select to enable any code that you placed in DEBUG conditional code blocks. For more information, see the section called “Using the DEBUG preprocessor symbol”.
	Encrypt all the compiled p-code files	Select whether to encrypt the object files when compiled from the PowerBuilder dynamic libraries.
	Platform	Select if the application can run on 32-bit or 64-bit machines.
	Manifest Information	Select whether to generate a manifest file (either external or embedded) and to set the execution level of the application. For further information, see the section called “Attaching or embedding manifest files”.
	Properties displayed for executable	Specify your own values for the Product name, Company name, Description, Copyright, Product version, and File version fields associated with the application file and with machine-code DLLs. These values become part of the Version resource associated with the application 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.
	Executable version used by installer	Specify the product version and file version (in numeric values) that will be used by Microsoft Installer to determine whether a file needs to be updated. 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.
Libraries page		Specify a PBR 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. You can type the name of a PBR file in the box or click the button next to the box to browse your directories for the PBR file you want to include. The PBR file as well as the resources it references must reside in the application directory or subdirectory; and only relative paths of the PBR file and the resources will be accepted.
External Files page		Specify the custom user external files and/or the resource files that are referenced in the PowerScript. Make sure all these files are placed in the same folder or sub-folder of the application target (.pbt) file. Files preloaded as compressed packages and Files preloaded in uncompressed format The custom user external files will be downloaded from the server before the application starts. It is recommended that you deploy the files which stay unchanged most of the time (such as UI theme files) as one compressed package, so that it can be transferred faster; and deploy the files which may be modified frequently (such as INI files) as individual files, or deploy them as a separate package. To deploy files as one compressed package, select Files preloaded as compressed packages from the list box, then click Create Package to create a package, and then click Add Folder or Add Files to add the folder or files under this package. To deploy files as individual files, select Files preloaded in uncompressed format from the list box, and then click Add Folder or Add Files to add the folder or files under it. The custom user external files may include the following: INI files (including pb.ini, pblab.ini, pbodb.ini etc.) DLL/OCX files (requiring no administrator rights to register) XML files or image files used by the UI theme or external functions text files, PDF files or any other files used by the external function Images/videos dynamically loaded The resource files (such as images, videos etc.) are downloaded from the server at the moment when they are used by the application. You can select Images/videos dynamically loaded and then click Add Folder or Add Files to add the folder or files under it. Note The read-only files added under Files preloaded in uncompressed format or Images/videos dynamically loaded will lose its read-only attribute after transferred to the server via FTP. This seems to be a common issue with FTP transfer. DLL & OCX Registration If the DLL/OCX files need to be registered and can be registered by Regsvr32 or Regasm without requiring the administrator rights, you can click DLL & OCX Registration to select the DLL/OCX files so that they can be registered by Regsvr32 or Regasm automatically before the application starts; if the DLL/OCX files need to be registered but cannot be registered by Regsvr32 or Regasm or they need to be registered using administrator rights, you can specify the registration commands in Preload Event in the Run Options tab. INI Configuration When the application is updated, the INI file can be updated with the specified strategy. Click the INI Configuration button and then select one or more INI file and configure the strategy for them at one time; or select and configure for the INI file one by one. Overwrite update -- The INI file on the client will be updated if the INI file downloaded from the server has been updated, and changes made to the local INI file will be lost. Merge update -- The INI file on the client will be merged with the INI file downloaded from the server, so changes made to the local INI file will be preserved and merged into the INI file downloaded from the server. But notice that any setting that exists in the local INI file while does not exist in the downloaded INI file will be removed. Do not update -- Once the INI file is downloaded to the client, it shall never be updated with the INI file downloaded from the server. Note The external files cannot contain any file that has the same name as the application, or the PBD or p-code file to be generated, otherwise duplicate name error occurs. For example, [appname].exe, [appname].xml, [appname].manifest file etc. cannot be added to External Files. For another example, test.pbl will be deployed as test.pbd, therefore, test.pbd cannot be added to External Files.
Runtime page		Select the runtime files according to the features used in the application. The files will be downloaded from the server to the client, for the application to run. The deployment tool does not actually deploy the files, instead it notifies the application to download such files (corresponding to the runtime version displayed) from the server directly. The runtime version displayed on this page can be configured in the IDE > System Options dialog. And you will need to make sure the corresponding version of PowerBuilder Runtime is uploaded to the server when you upload the Cloud App Launcher to the server.
Signing page		Select whether to digitally sign the application executable file (appname.exe). If you want to digitally sign the application executable file, you can specify the settings required for signing under the "Use the SignTool utility from the Windows SDK" option, for example, SignTool location, signing certificate, certificate password, signature algorithm, and URL of the time stamp server. And make sure Microsoft’s SignTool has been installed on the current machine. Or you can place the signing scripts in a file (with file extension as .cmd) and then select the file for the "Use your own signing script" option. For example, to sign the application executable file (appname.exe) using Microsoft’s SignTool, you may create a cmd file that includes the following scripts: signtool.exe sign /f mycert.pfx /p password /d "My application" /du http://www.mytest.com /fd sha256 /tr "http://timestamp.digicert.com" /td sha256 mytest.exe After the executable file is generated and before it is deployed to the server, PowerBuilder will sign the executable file using your own signing scripts or using the SignTool settings you specified. Make sure the PowerBuilder user has the appropriate rights to access the time stamp server and sign files.
Deployment page	Deployment Server	Select to deploy the application to a local server or a remote server. If you have not configured the server yet, click the Server Configuration button and follow instructions in Configuring a deployment server to configure the server. If the option "Check the availability of Cloud App Launcher on the server during the deployment process" is selected, the deployment process will be terminated if no Cloud App Launcher is detected on the target server. Click the Upload Cloud App Launcher button to upload the app launcher and runtime files to the same server or directory where app files will be deployed. For detailed instructions, refer to Uploading the app launcher and runtime files.
	Deployment version	The deployment version number is used by the server to determine whether to perform an install or update for the application. It is recommended to increment the deployment version number every time when the application is updated and re-deployed.
	Available time and Expiration time	Schedule the time for the deployment version to be accessible or inaccessible to end users. However, if the available time or expiration time is reached and the app is still open, the app will not get updated, until the app is closed or the session times out. Therefore, it is recommended that the session timeout feature should be enabled (for apps deployed via PowerServer) or implemented manually (for apps deployed via PowerClient).
	Minimum compatible version	Specify the lowest compatible version for the application. If the current version installed is older than it, a forced update will be performed, or the application will stop running.
	Update strategy	Specify the update strategy for the application. Always update: always performs updates before application startup. If checks for updates fail, then the application will not start. Update when connected: performs updates before application startup. If checks for updates fail, then the current version installed on the client will be running. Never update: never checks or performs updates once after the application is installed on the client. However, if the "Prompt to upgrade when the application deployment version is invalid" option is selected, and if the application installed on the client is older than the minimum compatible version, or is detected as expired according to the expiration time, the user will get prompts to update the application. And make sure appropriate session timeout is implemented otherwise the update strategy will not take effect if the app is open.
	Download options	Specify when to download the application files (other than those specified in the External Files page) -- before the application starts or at the moment when they are called by the application at runtime.
	App entry page settings	Specify which mode (with or without background service) will be run by default when the user accesses the application by inputting http://IPAddress/AppName. IMPORTANT: This setting must be consistent with the app launcher which is uploaded to the server, otherwise the application will fail to run. If you have changed the mode and uploaded the launcher again, make sure you also change the mode here accordingly, and ask the end user to clear the browser cache if the app launcher fail to run on the client. If you have uploaded the app launcher with background service, then you should select "Startup with background service" (and keep "Deploy auto.html..." selected and "Deploy manual.html..." unselected). In such case, the user can input http://IPAddress/AppName or http://IPAddress/AppName/auto.html to access the application. The user should not input http://IPAddress/AppName/manual.html, otherwise it will lead to a "page not found" error or an infinite searching for files. If you have uploaded the app launcher without background service, then you should select "Startup without background service" (and keep "Deploy manual.html..." selected and "Deploy auto.html..." unselected). In such case, the user can input http://IPAddress/AppName or http://IPAddress/AppName/manual.html to access the application. The user should not input http://IPAddress/AppName/auto.html, otherwise it will lead to a "page not found" error or an infinite searching for files. If you have uploaded the app launcher with and without background service, then you can choose the default startup mode between "Startup with background service" and "Startup without background service" and then select both the "Deploy manual.html..." and "Deploy auto.html..." options. In such case, the user can input http://IPAddress/AppName/manual.html to run the application without background service, and input http://IPAddress/AppName/auto.html to run the application with background service; or input http://IPAddress/AppName to run the application in the default startup mode.
Run Options page	Commandline arguments	Specify the command line arguments for the application. The arguments will be directly passed to the application when the application is run. And the arguments will be automatically saved and updated to the app startup icon on the desktop and the app shortcut menu in Windows start. The arguments specified here cannot be modified at runtime. If you want to modify the argument at runtime, you can specify the argument in the application URL (for example, http://localhost/salesdemo/?arg=1). You can also pass arguments to the EXE directly. If there are multiple arguments, please include them in quotation marks or separate them with a delimiter (instead of a space), for example, C:\Users\<username>\AppData\Roaming\PBApps\Applications\localhost_<appname>\<appname>.exe "parm1 parm2 parm3" C:\Users\<username>\AppData\Roaming\PBApps\Applications\localhost_<appname>\<appname>.exe parm1/parm2/parm3
	Create shortcut(s)	Specify whether to create an application shortcut icon on the client desktop and/or create an application shortcut menu in the Windows start menu.
	Show the loading animation before the app runs	Specify whether to show an animation (as shown below) when the application prepares for startup. The animation will disappear when the application's first window displays. This option should not be selected if the application starts with no user interface; otherwise the animation will not disappear. You can deploy your own animation to replace the default animation (as shown above). To deploy your own animation, Prepare a GIF format of your animation and name the file as "loading_ica.gif". Only GIF format is supported currently. Place "loading_ica.gif" under the same directory as the application target (.pbt) file. Add "loading_ica.gif" under Files preloaded as compressed packages or Files preloaded in uncompressed format in the External Files page.
	Validate the application integrity before the app runs	Specify whether to validate the hash of every object file before they are loaded, so that files changed illegally will not be run.
	Preload Event	(Optional) Specify the commands that will be executed immediately after files are downloaded and before the application starts. For example, you can specify commands to register DLL/OCX files that cannot be registered by Regsrv32 or Regasm or require administrator rights to register; or any other commands that need to be executed with administrator rights. If the commands need to be executed with the administrator rights, you should select the Run as administrator option. You can specify how often the commands should be executed: for only one time when the application is launched for the first time or when the application is updated, or every time when the application runs. The commands can be any Windows commands or user-defined commands. For example, suppose there is a DLL file from the application that needs to be registered on the client, you can enter the following commands: cd /d "C:\Windows\Microsoft.NET\Framework\v4.0.30319" regasm "%AppData%\Appeon\PBCloud\demo.appeon.com_app1\EncryptDecryptClass.dll" /tlb:testappeon.tlb /codebase /nologo Note that as the commands are executed silently, any commands that will pause the execution and wait for user input will cause the application to wait endlessly.
	Running app from IDE	Specify how the application can be launched from the PowerBuilder IDE (when you select the Run PowerClient Project button in the toolbar or from right-clicking the PowerClient project in the System Tree). You can specify the host name, port number, connection type (HTTP or HTTPS), and/or arguments. You can also specify to start the application from the Cloud App Launcher if the Cloud App Launcher is installed, or from a Web browser if the Cloud App Launcher is not already installed. If the Cloud App Launcher is not installed on the current machine, even if you have specified to start the application from the Cloud App Launcher, the Web browser will start to install the Cloud App Launcher and run the application. The arguments specified here will be appended to the application URL and then passed to the application via the URL, for example, http://localhost/salesdemo/?arg1&arg2. Note that the arguments appended to the application URL cannot contain special characters such as "?", "#", as they have special meanings in HTML URL; if you want to use these characters in the argument name or value, you can specify them in the Commandline arguments as static arguments on this same page, so that they can be passed to the application directly instead of being sent as part of the URL.

Tip

Advanced usage of External Files and Preload Event

The combination of External Files and Preload Event can streamline the process of deploying a setup package to the server, installing the package and registering the file on the client machine. In the External Files page, you add the folders and/or files that make up of the setup package, and in the Preload Event field, you add commands to run the setup file and register any component if necessary.

Take Microsoft OLE DB Driver for SQL Server (MSOLEDBSQL) as an example. Suppose the MSOLEDBSQL setup package includes the following folders and files: msoledbsql folder, sqlncli folder, CheckDBDriver.bat file, and Install.bat file.

Step 1: Copy the msoledbsql folder, sqlncli folder, CheckDBDriver.bat file, and Install.bat file to the same folder as the application target file.

Step 2: In the External Files page, select Files (Download at startup) in the list, and then click Add Folder to add the folders: msoledbsql and sqlncli and click Add Files to add the files: CheckDBDriver.bat and Install.bat.

The selected folders and files will be first deployed to the server and then downloaded to the application directory on the client machine.

Step 3: In the Run Options page, add the following command in the Preload Event field: .\CheckDBDriver.bat.

The command will be executed automatically when the application is first installed or upgraded. The CheckDBDriver.bat file checks whether MSOLEDBSQL is installed on the client machine. If MSOLEDBSQL is not installed, then Install.bat is automatically run to install MSOLEDBSQL. Administrator rights are required to run the Install.bat file, so the end user will be prompted for that if Install.bat is run.

Building and deploying a PowerClient project

To build and deploy a PowerClient project:

Before building and deploying the application, make sure to close any anti-virus tool on the development machine.
Click the Build & Deploy PowerClient Project button in the toolbar, or right-click the PowerClient project in the System Tree and then select Build & Deploy PowerClient Project to compile and deploy the application to the server. Or select Deploy PowerClient Project if you have already built the application before.

The application executable file (as well as an XML file with the same name and the object files) is generated under %PBAPPSCACHEDIR%\[appname] (%PBAPPSCACHEDIR% points to %TEMP%\pbappscache\temp\) on the development machine, then digitally signed, and deployed to the server.

Note

After the application is deployed to the server, do not manually change the application folder name on the server, otherwise the application uninstall program will fail to run.

Building and deploying the PowerClient project with commands

Instead of building and deploying the PowerClient project from the PowerBuilder IDE, you can also build and deploy the project using the PBAutoBuild210 command. For step-by-step guidance, refer to Tutorial 2: Building your PowerClient project with commands. The PBAutoBuild210 command can integrate with Jenkins to automate the build and deployment process for PowerClient projects. Refer to the Jenkins user documentations for how to use Jenkins.

To build and deploy the PowerClient project with commands:

Export the configurations of the PowerClient project to the JSON file.
1. Click the Export PowerClient Build File button () in the toolbar if the PowerClient project painter opens, or right click the PowerClient 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.
The exported JSON file includes every single setting that is required for compiling, packaging and deploying the PowerClient project, just to name a few, for example,
- Project settings such as project type, platform (32-bit or 64-bit), build options etc.
- Library list
- Version information
- Run options
- ...
You can find a complete list of settings under the "Projects" block in the exported file.

The exported file also contains a "BuildPlan" block which provides additional configurations:
- Settings for downloading and merging source code from the source control server (including SVN, Git, and/or VSS).
  
  Locate the "SourceControl" section to configure the settings.
  
  For example,
```
    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "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", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],
```
  Note: The password must be an encrypted value which is generated from the original password by executing "PBAutoBuild210.exe /p".
  
  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 exported build file and then configure as below:
```
            "Merging": [
                {"Target": ".\\Build\\salesdemo.pbt", "LocalProjectPath": ".\\Build", "RefreshPbl": false}
            ],
```
  Setting "RefreshPbl" to true if you want to refresh the PBL files by deleting and then generating the PBL files again.
  
  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\\salesdemo.pbt", "Name": "salesdemo_local"}
            ],
            "PostCommand1": ""
        }
```
- In the "SourceControl" and "BuildJob" sections, you could also specify commands that can be executed before and/or after that particular section is executed.
  
  Locate the "PreCommand" and "PostCommand" keywords to specify the commands or command file, for example,
```
"PreCommand": "SourcePre.bat"
```
  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"
```
Note: The relative path specified in the file is relative to the path of the JSON file.
Execute the PBAutoBuild210.exe file and the JSON file in a command line to automatically build and deploy the project. For example,
```
PBAutoBuild210 /f c:\salesdemo_local.json /l Log_PCBuild.log /le Log_PCError.log
```
The PBAutoBuild210.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.
```
PBAutoBuild210 /f c:\salesdemo_local.json
```
- /l -- write the logging information to a file.
- /le -- write the error information to a file. For example,
```
PBAutoBuild210 /f c:\salesdemo_local.json /l Log_PCBuild.log /le Log_PCError.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, Git, or VSS. This will generate an encrypted value based on the password. If the password contains the double quotation mark ("), use the escape character \" to replace ".
```
PBAutoBuild210 /p 123456
```
- /h or /? -- display the help information. For example,
```
PBAutoBuild210 /h
```

Note

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

Running the PowerClient project

To run the PowerClient project:

Note: IE and Edge Legacy (EdgeHTML-based) browsers should not be used to run the app deployed with PowerClient, as Microsoft will end support for IE and Edge Legacy soon. You can use one of the following supported browsers: Chrome, Firefox, and the new Edge browser (Chromium-based).

(For developers) Run the application by right-clicking the PowerClient project in the System Tree and then select Run PowerClient Project.

Or click the Run PowerClient Project button in the toolbar. The Run PowerClient Project button will be available in the toolbar when the Project painter for PowerClient is opened; if more than one Project painter for PowerClient is opened, then the settings in the currently active painter will be used to run the application. And the application will be run in the Web browser or in the Cloud App Launcher according to the configurations in the Run Options tab in the painter. However, if Cloud App Launcher is not installed, then the default Web Browser will be run to install the Cloud App Launcher and run the application.
(For developers and end users) Run the application in a Web browser for the first time.

The user can input http://IPAddress/AppName in a Web browser to access the application. This URL can run the application with or without background process, depending on which startup mode the developer has selected as the default. The end user may also be able to input http://IPAddress/AppName/manual.html to run the application without background service, and input http://IPAddress/AppName/auto.html to run the application with background service, depending on whether the developer has selected to deploy the app entry page. For more details, refer to "App entry page settings" in Defining a PowerClient project.

The cloud app launcher and the application must be installed through the Web browser for the first time. After that, users can directly double click the application icon on the desktop or the application shortcut on the Windows Start menu to run the application (the shortcut icon and menu are created by default unless the developer has changed the default settings in the Project painter for PowerClient).

If the application is started without the background service, the user will be asked by the Web browser whether to run the app launcher. This is a browser behavior. Select Allow. Then the following app entry page displays. If the download does not start automatically, click Download the Launcher to download and install the cloud app launcher first, and then click Start the Application to download, install, and start the application.

If the application is started with the background service, the following app entry displays. If the download does not start automatically, click to download and install the cloud app launcher.

If you want to customize the license agreement and the visual displays (such as color, icon, text etc.) in the above app entry page, you can make changes to the files under the %AppeonInstallPath%\PowerBuilder [version]\HTML folder, and then deploy the application again. The changes will apply to all deployed applications. Or you can directly make changes to the files under the application folder on the server, if you want to change that particular application only.

license.html is the template for license agreement.
auto.html, autoconnect.html, autodownload.html, autoinit.html, and index.html are templates for applications started with background service.
manual.html, manualconnect.html, manualdownload.html, and index.html are templates for applications started without background service.

Note

The virus-detection software McAfee WebAdvisor may block the CloudAppLauncher.exe file during the installation process. You can try adding the domain as a trusted site. To add the domain as a trusted site in McAfee WebAdvisor:

1. Right click the WebAdvisor add-on and select Options.

2. Under Manage your trusted sites, add the domain and click the + symbol.

3. Close and re-open the browser and run the installation again.

Note

If there is no response or progress when running the application, the CloudAppLauncher.exe file might be blocked by the Windows SmartScreen. You can try to turn off Windows SmartScreen in Control Panel > System and Security > Security and Maintenance > Change SmartScreen settings.

Note

Every time when the application launches, it needs to connect with the Web server to check updates, therefore, please make sure Web server is running and can be connected all the time.

Packaging the PowerClient project

To package the PowerClient project:

Right-click the PowerClient project in the System Tree and then select Package PowerClient Project from the popup menu.
Specify the location where the package will be generated.
Specify to generate the package as an executable installer or a compressed zip file.

If you select Zipped file, an appname_Installer.zip file is generated in the specified path. You can copy the zip file to the server and then decompress it to the Web root.

If you select Executable installer file, an appname_Installer.exe file is generated in the specified path. You can copy the executable file to the server and then run it to install the application to the Web root.

Note

Do not manually change the name of the installed or de-compressed application folder on the server, otherwise the application uninstall program will fail to run.

Undeploying the PowerClient project

To undeploy the PowerClient project from the server:

Right-click the PowerClient project in the System Tree and then select Undeploy PowerClient Project from the popup menu.
Select whether to remove the entire project (all deployed versions) or only the selected deployment version from the server.

Uninstalling the PowerClient project

To uninstall the PowerClient project from the client machine:

Uninstall the application by selecting the Uninstall shortcut menu from the Windows Start | [appname].

The Uninstall menu and the [appname] menu are available only when the developer selected to create the start menu shortcut in the Run Options page of the Project painter for PowerClient. If the Uninstall menu is not available, you can run the Uninstall.exe file in the application folder, for example, %AppData%\PBApps\Applications\localhost_app1\Uninstall.exe (%AppData%\PBApps is configurable when uploading the Cloud App Launcher and runtime files).

Note: If the application folder name (which is named after [appname]) on the server has been changed manually, the application uninstall program will fail to run.

The uninstall program will automatically remove the following:
- The application shortcuts on the desktop and the Windows start menu.
- The application folder under %AppData%\PBApps\Applications, for example, %AppData%\PBApps\Applications\localhost_app1.
  
  The application folder contains all of the application files and any external files (such as UI theme files, DLLs/OCXs, images/videos, INIs etc.) that are deployed with PowerClient. This folder will be automatically deleted during the uninstall process.
However, the uninstall program will NOT automatically remove the following:
- The registration information of DLL/OCX files in the Windows registry.
  
  If you have selected to register the DLL/OCX files (using Regsvr32 by default), you will need to remove the registry information manually. Follow instructions in step 4 below.
- The runtime files under %AppData%\PBApps\Applications\Runtime.
  
  The PowerBuilder Runtime files are used by all deployed apps on the client machine. You can manually delete the runtime files if they are no longer used.
- The download folder under %AppData%\PBApps, for example, %AppData%\PBApps\Download.
  
  This folder stores the download statistics of the app and runtime files. It can be manually deleted.
Uninstall the cloud app launcher by uninstalling Cloud App Launcher from Control Panel\Programs\Programs and Features.

If the cloud app launcher without background service is uninstalled, the %LocalAppData%\Launcher folder will be removed.

If the cloud app launcher with background service is uninstalled, the %LocalAppData%\LauncherWithService folder will be removed.
Uninstall the cloud app service by uninstalling Cloud App Launcher Service from Control Panel\Programs\Programs and Features.

The cloud app launcher service is installed only when the launcher with background service which supports multiple Windows users is installed.
Remove the registry information of DLL/OCX files.

The registry information of DLL/OCX files (or any other files that are installed and registered by your own) will not be automatically removed during the application uninstall process.

To clean up the registry information of the DLL/OCX files, you can write scripts (a sample shown below) and place them in a file named ManualUninstall.cmd, place the ManualUninstall.cmd file under the same directory as the application target (.pbt) file, add ManualUninstall.cmd under Files preloaded as compressed packages or Files preloaded in uncompressed format in the External Files page, and then deploy the application.

The scripts in ManualUninstall.cmd will be automatically run when the application uninstall program is run. (If the file requires administrator rights to unregister, you should run the application uninstall program with administrator rights.)

You can also add scripts in ManualUninstall.cmd to clean up any other files that are installed and registered by your own.

The following is a sample script for unregistering DLL/OCX files that are registered by Regsvr32:
```
set Driver=%~d0
set HOMEDIR=%~dp0
%Driver%
cd %HOMEDIR%
regsvr32 /u .\dllname
regasm   /unregister .\AssemblyName
```

Changing external files using commands

When the application is deployed (from the PowerBuilder IDE) or installed (from the packaged executable installer or zipped file) to the Web server, the app files are generated with hash codes, to prevent files changed illegally from running. Therefore, you cannot directly change the deployed files on the Web server, instead you will have to make changes in the project painter and then deploy the application again, or modify the files using the CustomizeDeploy.dll tool.

The CustomizeDeploy.dll tool allows you to modify the external files in the Web server. The "external files" refers to the packages, folders, and files (such as INI files, DLL/OCX etc.) that are deployed from the External Files tab of the PowerClient project painter.

You can find the CustomizeDeploy.dll tool under the "1.01" sub-folder of the application folder after the application is deployed or installed to the Web server (either from the PowerBuilder IDE or from the packaged executable installer or zipped file).

The CustomizeDeploy.dll tool supports the following syntax:

dotnet CustomizeDeploy.dll -src=<source file> -dest=<destination file>

The "src" argument should point to the new file that you want to use to replace the old file.

The "dest" argument should point to the old file that you want to replace with the new file.

When external files are deployed to the server, they are appended with the file extension ".zip", but they are not compressed files (the only exception is package). For example, if apisetup.ini is selected in the External Files tab, it will be deployed as apisetup.ini.zip to the server, however, apisetup.ini.zip is not a compressed file and it can be directly opened in a text editor just like apisetup.ini.

And to replace the file, you should prepare the source file without .zip extension.

For example,

dotnet CustomizeDeploy.dll -src=/new/apisetup.ini -dest=apisetup.ini.zip

dotnet CustomizeDeploy.dll -src=/new/new.ini -dest=apisetup.ini.zip

The only exception is the package which is indeed compressed as the zip format (with file extension ".zip.zip") during deployment. Therefore, you should prepare the source file for the package in the compressed zip format.

For example,

dotnet CustomizeDeploy.dll -src=/new/theme.zip -dest=theme.zip.zip

dotnet CustomizeDeploy.dll -src=/new/aaa.zip -dest=theme.zip.zip

The tool will replace the package as a whole (and refresh the hash code of the package) and it will not validate the individual files included in the package. Therefore you need to make sure the files included in the package are correct and complete.

Important

Prerequisites

To execute the CustomizeDeploy.dll file using the dotnet command, you will need to install the ASP.NET Core Runtime 3.1 or later in the server.

To run CustomizeDeploy.dll in Windows Web server:

Install the ASP.NET Core Runtime 3.1 or later.
Open the command prompt. (You'd better run the command prompt using an administrator by right-clicking it and then selecting "Run as administrator").
Navigate to the Web server root folder > [application] folder > "1.01" (for example, C:\inetpub\wwwroot\sales\1.01).
Execute the CustomizeDeploy.dll file using the dotnet command.

To run CustomizeDeploy.dll in Linux Web server:

Install the ASP.NET Core Runtime 3.1 or later.
```
dnf install aspnetcore-runtime-5.0
```
Go to the Web server root folder > [application] folder > "1.01" (for example, /var/www/html/sales/1.01, or /usr/share/nginx/html/sales/1.01).
Right click the blank area within the folder and then select Open in Terminal.
Execute the CustomizeDeploy.dll file using the dotnet command. Notice that the command and file name are all case-sensitive in the Linux OS.

Supporting cookie validation

You can now set a cookie to the cloud app launcher and the application; and the cookie will be automatically carried in the HTTP request header of every client request.

Once a cookie is set to the cloud app launcher and the application, the cookie can be validated against the validation scripts or the SSO server etc. And based on the validation results, the launcher and/or the application can be determined whether to allow to download the requested files.

Notice that

Currently you can only set the name and value for a cookie, and cannot set the other cookie attributes (including Domain, Expires, Path etc.); and you must set the cookie in the key-value pairs, for example, "key1=value1; key2=value2".
The cookie must be passed into the launcher and the application by the index.html file, therefore, you will have to start the application from the index.html (by accessing the app URL in the Web browser); you cannot start the application from the app shortcut on the desktop or start menu.
Make sure the cookie will stay valid if you select "Download the app files as necessary" because files will be downloaded only when requested. Set an appropriate expiration period for the cookie.

To set a cookie to the cloud app launcher and the application,

You can modify the JavaScript file (launcher.js) on the Web server to set a cookie to the cloud app launcher.

launcher.js is located in the application folder > "js" sub-folder on the Web server, for example, C:\inetpub\wwwroot\salesdemo_local\js\launcher.js.

For example, the following JavaScript will set the cookie by obtaining the cookie from document.cookie. However, if the cookie is set to HttpOnly, it cannot be accessed from document.cookie by JavaScript.

function getCookie(){
 var strCookie = "";
 strCookie = document.cookie;
 return strCookie;
}

function getCmdline(Url){
 var strCookie = getCookie();
 var strUrl = Url;
 if(strCookie.length > 0)
 {
  strUrl += " -cookie ";
  strUrl += strCookie;
 }
 return strUrl;
}

For example, the following JavaScript will set the cookie by obtaining the cookie from the application URL, for example, http://localhost/test?name=admin;pw=123.

function getCookie(){
 var strCookie = "";
 strCookie = window.parent.parent.location.search.split("?")[1];
 return strCookie;
}

function getCmdline(Url){
 var strCookie = getCookie();
 var strUrl = Url;
 if(strCookie.length > 0)
 {
  strUrl += " -cookie ";
  strUrl += strCookie;
 }
 return strUrl;
}

Rolling back to an earlier version of app

Suppose you have deployed four versions: 1.01, 1.02, 1.03, & 1.04, and now want to roll back to 1.02.

Step 1: Go to the Web server Web root and make a backup of the versions that you are going to roll back to or undeploy in the subsequent steps.

In this example, back up 1.02, 1.03, & 1.04 folders.

Step 2: Go to the Client Deployment tab of the PowerClient project painter and make sure Minimum compatible version is equal to or earlier than the version that you want to roll back to.

In this example, 1.02 or 1.01 must be selected.

Step 3: If you have made changes to Minimum compatible version, then click the Deploy PowerClient Project button () in the toolbar.

This will refresh the minimum compatible version on the server (and deploy files to the current Deployment version; the current deployment version should be 1.04 in this example).

Step 4: Undeploy any version that is newer than the version you want to roll back to, because the latest available version will be downloaded by default.

In this example, you will have to undeploy 1.03 & 1.04, otherwise the client side will not download 1.02 but download 1.03 or 1.04.

For how to undeploy from the server, see Undeploying the PowerClient project.

Step 5: Uninstall the current version from the client machine.

Although you can deploy multiple versions on the server, there will be only one version (the latest available version) installed on the client machine.

For how to uninstall from the client machine, see Uninstalling the PowerClient project.

Step 6: Run the application.

The latest available version (in this example 1.02) will be downloaded and installed from the server.

Tutorial 1: Deploying your first PowerClient project

By completing this tutorial, you will have a basic understanding of the key tasks for creating and deploying a PowerClient project. You will use the Example Sales Demo to complete this tutorial.

Step 1: Open the Example Sales Demo from Windows Start | Appeon PowerBuilder [version] | Example Sales App.

Step 2: In the PowerBuilder System Tree, expand the salesdemo target | salesdemo.pbl, double click the salesdemo_local object to open the PowerClient project in the painter.

Step 3: View the settings in each tab of the project painter; keep the default values, but pay special attentions to the following:

the app name in the General tab
the selected folders and files in the External Files tab
the selected runtime modules in the Runtime tab

Step 4: Select the Deployment tab in the project painter.

Step 5: Make sure Local server is selected, and then click the Server Configuration button.

In the Server Configuration window that appears, make sure the Web root full path is set to C:\inetpub\wwwroot.

Click Test File Path to ensure the path is valid.

Step 6: Click the Upload Cloud App Launcher button.

In the Upload Cloud App Launcher and Runtime window, make sure the following are selected: Local server, Default_WithoutService, Upload the runtime files for the apps, 32-bit, and 64-bit.

Click Upload and make sure the upload is successful.

Step 7: Scroll down the Deployment tab, and select Startup without background service.

Step 8: Save the project (by clicking the Save button in the toolbar).

Step 9: Build and deploy the project (by clicking the Build & Deploy PowerClient Project button in the toolbar). Or right click the salesdemo_local object and then select Build & Deploy PowerClient Project.

Make sure the project is built and deployed successfully.

Step 10: Run the project (by clicking the Run PowerClient Project button in the toolbar). Or directly access http://localhost/salesdemo_local in the Web browser.

In the app entry page that appears, click Download the Launcher to download and install the launcher. After the launcher is installed, the application should automatically start, if not, click Start the Application in the entry page to start the application.

Tutorial 2: Building your PowerClient project with commands

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

Besides building and deploying your PowerClient project in the PowerBuilder IDE, you can also build and deploy your PowerClient project using the command line tool (PBAutoBuild210.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 PowerClient 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 10 or 8.1
PowerBuilder IDE 2021
PowerBuilder Runtime 2021

Step 2: Follow Tutorial 1 to

create a PowerClient project for the Example Sales Demo;
build and deploy the PowerClient project (using the Build & Deploy PowerClient Project option in the PowerBuilder IDE) successfully; and
run the app successfully.

Exporting the build file

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

Step 1: Open the workspace for the Example Sales App in the PowerBuilder IDE, and then double-click the PowerClient project object to open the PowerClient project painter.

Step 2: When the PowerClient project painter is opened, click the Export PowerClient Build File button () in the toolbar.

Step 3: In the Export Build File dialog box, write down the path and filename to be exported, and then click Export.

Modifying the build file

Getting source code from SVN, Git, or VSS
Executing additional commands

The exported build file contains all the settings required for building and deploying the PBL files of the Example Sales App. It also contains some advanced settings that allow you to perform the following:

Getting and merging source code from SVN, Git, or VSS;
Executing additional commands during the build process.

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 easily, for example, when you use relative paths in the build file, 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, for example, "Git" as shown below.

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

    "BuildPlan": {
        "SourceControl": {
            "PreCommand": "",
            "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", "Proxy": {"Ip": "","Port": 0,"Username": "","Password": ""}}
            ],

Note: The password must be an encrypted value which is generated from the original password by executing "PBAutoBuild210.exe /p", as shown 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}
            ],

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\\salesdemo.pbt", "Name": "salesdemo_local"}
            ],
            "PostCommand1": ""
        }

When the PBAutoBuild210.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 & deploy 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 the "build" 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:\PB2021\SalesDemo\Build"

Step 2: In the exported 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",
            "SVN": [
               ...
            ],

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

Besides the "PreCommand" sub-section, there is also a "PostCommand" sub-section for the "SourceControl" and "BuildJob" steps, which allows you to execute commands after that particular step.

Task 2: Building with commands

Preparing the environment
Running the command line tool
Integrating with Jenkins

Preparing the environment

Step 1: To build and deploy the PowerClient project using the command line tool (instead of within PowerBuilder IDE), install the following software.

Windows 10 or 8.1, or Windows Server 2019, 2016, or 2012 R2
PowerBuilder Compiler 2021

The command line tool (PBAutoBuild210.exe) is included in PowerBuilder Compiler.
PowerBuilder Runtime 2021

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 PBAutoBuild210.exe file and the build file. For example,

PBAutoBuild210.exe /f "D:\PB2021\SalesDemo\salesdemo_local.json" /l Log_PCBuild.log /le Log_PCError.log

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

Integrating with Jenkins

The PBAutoBuild210 command can integrate with Jenkins to automate the build and deployment process for PowerClient projects. Refer to the Jenkins user documentations for how to use Jenkins.

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

For example, to execute the PBAutoBuild210 command and the exported build file.

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

Working with a PowerServer project

Please refer to PowerServer 2021 Help > How-to for more details.

Building proxies and .NET targets

The Project painter workspace for executable applications is shown in Defining an executable application project. It contains a tab control, and on each tab page there are text boxes and radio buttons you use to specify the characteristics of your executable file and dynamic libraries.

The workspace for all other types of project objects is similar. If you used a wizard to create the project, it shows the options you selected in the wizard. If you did not use a wizard, you select the objects the project will use and specify project properties on tab pages in the workspace.

When you build the project, the Output window shows whether the build was successful and lists any errors encountered.

Building and deploying a workspace

You can build and deploy a single project or all the projects in your workspace. You can also build and deploy from a command-line. For more information, see Building workspaces.

For more information

Web service proxies and EJB client proxies are obsolete features in PowerBuilder. An obsolete feature is no longer eligible for technical support and will no longer be enhanced, although it is still available.

If you are still interested to know more about building Web service proxies and EJB client proxies, see Building a Web Services Client (Obsolete) and Building an EJB client (obsolete).

Prev	Up	Next
Tracing and Profiling Applications	Home	Appendixes

Users GuideRunning Your Application