About this chapter
This chapter provides the information required to deploy applications and components to users' computers and servers. It describes a tool you can use to package PowerBuilder runtime files, and lists the files you need to deploy with various kinds of targets.
These lists of files sometimes need to be updated, as, for example, when new database interfaces become available. For information about such changes, see the Release Bulletin for the version of PowerBuilder you are using.
Regardless of the type of application you are deploying, you must include any supporting files such as dynamic libraries, resources like BMP and ICO files, online Help files, and initialization files. Each application type requires a different set of supporting files. The PowerBuilder runtime files, such as pbvm.dll and pbdwe.dll, and PowerBuilder database interfaces such as pbin9 and pbo10.dll, can be freely distributed with your application with no licensing fee.
Planning for deployment
Packaging an Application for Deployment helps you make decisions about deploying a PowerBuilder executable application, such as whether to use dynamic libraries, Pcode or machine code, and resource files. It also provides a checklist to make sure you install all the required pieces.
If you are deploying a Web application or a transaction server component, you will find the information about PowerBuilder dynamic libraries (PBDs) and PowerBuilder resource files (PBRs) in that chapter helpful. You should also read the documentation for specific types of applications, components, or plug-ins.
Finding information in this chapter
This chapter is intended to help you write installation programs using a third-party software package that creates installation configurations. It tells you which files each computer needs, where you can find the files, where they should be installed, and what registry settings need to be made. PowerBuilder also provides a tool, described in PowerBuilder Runtime Packager, to help you package the files your application needs.
Use the following table to locate information about the specific files you need to deploy with your application.
|
Scenario |
See these sections |
|---|---|
|
All PowerBuilder client applications |
|
|
PowerBuilder client application accessing data on a database server |
|
|
PowerBuilder clients for EJBs (obsolete), SOAP Web services (obsolete), and XML services |
|
|
PowerBuilder clients that save data in PDF or XSL-FO format |
Installed and deployment paths
The Installed path listed after some of the tables in this chapter is the location where files are installed when you install PowerBuilder and select the default installation location. When you build an installation program for your application, you can copy files from this location to your staging area.
The Deployment path tells you where these files can be installed on the computer on which you install your application or component.
Some tables are followed by a list of the Registry entries your installation program needs to make so that your application or component can find the files it needs. When an application runs on Windows, it looks for supporting files in these locations and in this order:
-
The directory where the executable file is installed.
-
The Windows system and Windows directories (for example, in C:\WINDOWS\system32, C:\WINDOWS\system, and C:\WINDOWS).
-
In an application path that can be specified in the registry.
-
In the system path.
You do not need to specify an application path, but it is recommended.
Specifying an application path
To specify the path the application uses to locate supporting files, your installation program should create an App Path key for your application in this registry location:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\App Paths
Set the data value of the (Default) string value to the directory where the application is installed and create a new string value called Path that specifies the location of shared files. The following example shows a typical registry entry for an application called myapp.exe that uses SQL Anywhere. The registry key is enclosed in square brackets and is followed by string values for the key in the format "Name"="Value":
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\myapp.exe] "Default"="C:\Program Files\myapps\myapp.exe" "Path"="C:\Program Files\myapps;C:\Program Files\Appeon\Common\PowerBuilder\Runtime 19.2.0.2382;C:\Program Files\SQL Anywhere 16\Bin32\;"
About REG files
Registry update files that have a .REG extension can be used to import information into the registry. The format used in registry key examples in this chapter is similar to the format used in registry update files, but these examples are not intended to be used as update files. The path names in data value strings in registry update files typically use a pair of backslashes instead of a single backslash, and the "Default" string value is represented by the at sign (@).
Use the examples to help determine which registry keys your installation program should add or update.
If your application uses ActiveX controls, OLE controls, or OCX controls, you must:
-
Deploy the control files with your application
-
Make sure each control is registered
-
Make sure required files are in the target computer's system directory
If your application uses a control that is not self registering, your setup program needs to register it manually on each user's computer. To find out whether a control is self registering, see the documentation provided with the control. Depending on the development and deployment platforms and the controls you are deploying, you might need to copy additional DLLs or license files to the Windows system directories on the target computer.
The PowerBuilder Runtime Packager is a tool that packages the PowerBuilder files an application needs at runtime into a Microsoft Windows Installer (MSI) package file or a Microsoft merge module (MSM). Windows Installer is an installation and configuration service that is installed with recent Microsoft Windows operating systems. The MSM file must be incorporated into an application MSI file using a merge tool before the components it contains can be installed on a client computer.
You can use the MSM or MSI file generated by the Runtime Packager as part of an installation package that includes the other files that your application needs.
You must have Microsoft Windows Installer on your system in order to run the Runtime Packager successfully.
To get more information about Windows Installer, see the Microsoft documentation at http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx.
Note
You must have Microsoft Visual C++ 2010 Redistributable Package (32-bit or 64-bit) installed, if you use the EXE file generated by the Runtime Packager. You must also have Microsoft .NET Framework 4.0 installed, if the Runtime Packager will install components such as ADO.NET, MS Excel12 Support, and OData which rely on .NET Framework to install and run.
The Runtime Packager can be used with client applications installed on Windows systems and applications deployed to the .NET Framework. It does not install most third-party components. See Third-party components and deployment for more information.
Make sure that you read the sections referenced in Table: PowerBuilder files required for deployment that apply to your application for more information about where files that are not installed by the Runtime Packager should be installed.
To use the PowerBuilder Runtime Packager:
-
Select Programs>Appeon PowerBuilder [version]>PowerBuilder Runtime Packager [version] from the Windows Start menu or launch the pbpack210.exe file in your %AppeonInstallPath%\PowerBuilder [version]\IDE directory.
-
Select the PowerBuilder Base Components.
-
Select the PowerBuilder Runtime Version.
-
Select whether to generate the PowerBuilder runtime files in a standalone MSI file or in an MSM merge module.
-
Select a location for the generated MSI or MSM file.
-
Select the database interfaces your application requires.
The DLLs for the database interfaces you select are added to the package. For ODBC and OLE DB, the pbodb.ini file is also added. For JDBC, the pbjdbc12.jar and pbjvm.dll files are also added. The Java Runtime Environment (JRE) is not added. See Third-party components and deployment.
Other ODBC or OLE DB files your application may require are not added. For information about deploying these files, see ODBC database drivers and supporting files and OLE DB database providers.
-
If your application uses the the following Web integration features, such as HTTPClient object, RESTClient object, OAuth 2.0, and WebBrowser control, select the corresponding check box.
The Runtime Packager adds the files listed for HTTPClient object, RESTClient object, OAuth 2.0, and WebBrowser control in Table: Additional PowerBuilder runtime files.
-
If your application uses the rich text control for the RichTextEdit control or RichText DataWindow, select the corresponding check box.
For 32-bit, you can select from
-
TX TextControl ActiveX 15.0
-
TX TextControl ActiveX 28.0
-
Rich Edit Control (TE Edit Control) (in the Obsolete Features section)
For 64-bit, you can select from
-
TX TextControl ActiveX 28.0
-
Microsoft RichEdit Control (in the Obsolete Features section)
The Runtime Packager adds the files listed for the rich text support in Table: Additional PowerBuilder runtime files.
Rich Edit Control and Microsoft RichEdit Control are obsolete
Rich Edit Control and Microsoft RichEdit Control are obsolete features. Obsolete features are still available to use, but are no longer eligible for technical support and will no longer be enhanced.
If your application uses the old editor (TX Text Control ActiveX 24.0 Professional/Enterprise) for a RichTextEdit control or RichText DataWindow, you should follow the vendor's documentation to package the files required for running this editor.
To know more about the built-in editor and the old editor, see Rich text editors.
-
-
If your application uses the following features such as data compression, encryption and decryption, JSON support, NativePDF, RibbonBar control, UI theme, XML support, and .NET assembly calls, select the corresponding check boxes.
The Runtime Packager adds the files listed for these feature supports in Table: Additional PowerBuilder runtime files.
-
If your application saves DataWindow or graph data in Microsoft Excel format, select the MS Excel12 Support check box.
The Runtime Packager adds the PBDWExcel12Interop.dll and Sybase.PowerBuilder.DataWindow.Excel12.dll files to the MSM or MSI package that you generate. It does not add the .NET Framework that is also required for Microsoft Excel support.
The Sybase.PowerBuilder.DataWindow.Excel12.dll file will be automatically installed to the Windows GAC folder, for example, C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Sybase.PowerBuilder.DataWindow.Excel12, if you run the MSM or MSI package. However, if you manually copy runtime DLLs to the client (instead of using the MSM or MSI package), make sure to copy the Sybase.PowerBuilder.DataWindow.Excel12.dll file to the same directory as the application executable, as this file is a C# assembly DLL and cannot be loaded through the environment variable.
-
If your application uses the XML services provided by the PowerBuilder Document Object Model or if it is an EJB client (obsolete), select the EJB client or PB DOM check boxes.
The Runtime Packager adds the DLLs, PBXs, and JAR files required by the selected component.
EJB client is obsolete
EJB client is obsolete features. Obsolete features are still available to use, but are no longer eligible for technical support and will no longer be enhanced.
-
If your application is a SOAP Web services client or if your application uses Web service DataWindows, select the SOAP Client for Web Service or Web Service DataWindow Support check boxes.
The Runtime Packager adds required files for both the EasySoap and .NET Web service engines when you select the SOAP Client for Web Service check box. For more information about required files for these services, see PowerBuilder extensions.
Web service DataWindows and SOAP client are obsolete
Web service DataWindows (OData and SOAP) and SOAP client are obsolete features. Obsolete features are still available to use, but are no longer eligible for technical support and will no longer be enhanced.
-
Click Create.
The Runtime Packager creates an MSI or MSM file that includes the files required by the components you selected, as well as the runtime DLLs for standard PowerBuilder applications listed in the following table.
Base components selected
Files
PowerBuilder components (Default file name for runtime package is PBCLTRT.msi)
libjcc.dll
libjutils.dll
libjtml.dll
libsybunic.dll
nlwnsck.dll
pbacc.dll
pbAccessibility.dll
pbcomrt.dll
pbdpl.dll
pbdwe.dll
pbdwr.pbd
pbjag.dll
pbjvm.dll
pbresource.dll
pbshr.dll
pbsysfunc.dll
pbtra.dll
pbtrs.dll
pbuis.dll
pbvm.dll
The MSI file is a compressed file that can be executed directly on any Windows platform. It registers any self-registering DLLs, adds the installation destination path to the Windows Registry, sets the system PATH environment variable, and adds information to the Registry for the Install/Uninstall page in the Windows Control Panel. It can also be used in some third-party installation software packages.
The MSI file generated by the PowerBuilder Runtime Packager tool has been enhanced, so that runtime files of different builds at the same major version (starting from 2019 R3 GA) can be installed and coexisting on the same computer, for example, 2019 R3 and 2019 R2 can coexist, multiple 2019 R3 MRs can coexist. And the MSI file no longer sets the runtime file path in the system PATH environment variable; therefore, the user will need to decide which build of runtime files will be loaded by the application executable file and place the application executable and the runtime files in the same folder.
The MSM file is similar to an MSI file, but the MSM file must first be merged into an installation package before its components can be installed on a client computer. A merge tool is required to merge the MSM file into an MSI installation package.
PowerBuilder applications have some dependencies on third-party components that are installed with PowerBuilder. Most of these components are not installed with the PowerBuilder Runtime Packager. You may redistribute some of these components with your application, but others must be obtained from the vendor.
For information about components that can be freely downloaded, see the free download terms document. A copy of this document is located on the Appeon website at https://docs.appeon.com/policies/PowerBuilder_Installer_2021_FreeDownloadTerms.pdf.
You may redistribute Apache files included with PowerBuilder to your users. Any use or distribution of the Apache code included with PowerBuilder 2017 and later must comply with the terms of the Apache License which is located in the free download terms document for PowerBuilder 2017 and later.
Version 0.20.5 of the Apache Formatting Objects Processor (FOP) is required if your application uses XSL-FO to save files as PDF. For more information about FOP, see the Apache FOP website at http://xmlgraphics.apache.org/fop/.
The Apache Xerces files xerces-c_2_8.dll and xerces-depdom_2_8.dll are required for XML Web DataWindow support, XML support for DataWindows and DataStores, PBDOM, and SOAP clients for Web services (obsolete). For more information about Xerces, see the Xerces C++ Parser website at http://xerces.apache.org/xerces-c/.
Visual C++ runtime, Active Template, and GDI+ libraries
When you deploy the core PowerBuilder runtime files, you must ensure that the msvcr100.dll and msvcp100.dll Microsoft Visual C++ runtime libraries and the Microsoft .NET Active Template Library (ATL) module atl100.dll, are present on the user's computer or server. The PowerBuilder runtime files have a runtime dependency on these files and they are required for all applications and components that require the PowerBuilder runtime. You can obtain these DLL files from the %systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version]\ (for 32-bit) or %systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version]\x64 (for 64-bit) folder, or from the DLL archive website. Make sure you obtain the same version (32-bit or 64-bit) of the these DLL files as the version (32-bit or 64-bit) of the PowerBuilder application executable.
The PowerBuilder runtime files also have a runtime dependency on Microsoft Windows GDI+ (gdiplus.dll). The GDI+ graphics design interface is included by default in the system paths of all Windows platforms currently supported by PowerBuilder.
Files must be installed before running MSI or MSM file
Some files installed by the MSI or MSM file generated by the PowerBuilder Runtime Packager have dependencies on these files. For example, atl100.dll and gdiplus.dll must be installed on the user's computer before the pbjvm.dll file can be registered. Make sure these files are on the target computer before you run the installation module generated by the Runtime Packager.
Ink picture libraries
Microsoft.Ink, Microsoft.Ink.dll, and Microsoft.Ink.Resources.dll are required if your application uses InkEdit and InkPicture controls. These files are part of the Microsoft .NET Framework 3.5 and later, and are available at C:\Windows\winsxs and its sub-folders after .NET framework is installed.
DirectX runtime
PowerBuilder applications can use DirectX 3D rendering to display 3D graphs (Pie3D, Bar3D, Column3D, Line3D, and Area3D) with a more sophisticated look. You can use data item or series transparency with the DirectX graph styles to improve the presentation of data.
The DirectX 3D rendering depends on the DirectX runtime. The first time you select the Render3D check box on the General tab of the Properties view for a 3D graph, PowerBuilder launches the DirectX installer. If you opt out of the installation, the Render3D property is ignored. End users of PowerBuilder applications must also have the DirectX runtime installed on their computers to view the DirectX graph styles. You can download a redistributable package containing the DirectX runtime from the Microsoft website at https://www.microsoft.com/en-us/download/details.aspx?id=9894.
For computers with older graphics drivers, you can check whether DirectX is supported by running dxdiag.exe. This file is typically installed in the Windows\System32 directory. The Display tab of the DirectX Diagnostic Tool that opens when you run dxdiag.exe indicates whether Direct3D is enabled.
The Java Runtime Environment (JRE) is required for EJB clients (obsolete), JDBC connections, and saving as PDF using XSL-FO. For a copy of third-party terms and conditions for the JRE, see the free download terms document.The JRE can be downloaded from the Oracle Technology Network at http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Note
SOAP clients (including .NET Web service engine and EasySoap Web service engine) for Web services are obsolete. Obsolete features are still available to use, but are no longer eligible for technical support and will no longer be enhanced.
PowerBuilder includes the EasySoap++ library in executable form in EasySoap.dll, which is dynamically linked to pbsoapclient.pbx. The EasySoap++ library and its use are covered by the GNU Lesser General Public License (LGPL). For a copy of this license, see the free download terms document.
You may distribute the EasySoap++ library to third parties subject to the terms and conditions of the LGPL. Please read the LGPL prior to any such distribution.
The complete machine-readable source code for the EasySoap++ library is provided in the EasySoap.zip file in the Support\WSExtn folder on the DVD. In addition, the object code and Microsoft Visual C++ project file for the pbsoapclient.pbx are provided in the soapclient.zip file in the same directory.
These files are provided under the terms of the LGPL so that you can modify the EasySoap++ library and then relink to produce a modified EasySoap.dll. You can also relink pbsoapclient.pbx with the modified EasySoap++ import library. According to the terms of the LPGL, it is understood that you will not necessarily be able to recompile pbsoapclient.pbx to use the definitions you have modified in the EasySoap++ library.
Follow the instructions in the Readme.txt file in the soapclient.zip file to build pbsoapclient.pbx.
All PowerBuilder runtime DLL files are digitally signed (starting from PowerBuilder 2019 R2).
Database connectivity
Files required for database connectivity are listed separately in Database connections.
Core runtime files
The following table lists the core PowerBuilder runtime files.
|
Name |
Required for |
|---|---|
|
pbvm.dll |
All. |
|
pbshr.dll |
All. pbvm.dll has dependencies on this file. |
|
libjcc.dll |
All. pbvm.dll has dependencies on this file. |
|
libsybunic.dll |
All. pbvm.dll has dependencies on this file. Required in 32-bit only. |
|
libjutils.dll |
All. libjcc.dll has dependencies on this file. Required in 32-bit only. |
|
libjtml.dll |
All. libjcc.dll has dependencies on this file. Required in 32-bit only. |
|
nlwnsck.dll |
All. libjcc.dll has dependencies on this file. Required in 32-bit only. |
|
pbuis.dll |
All. pbvm.dll has dependencies on this file. |
|
pbdwe.dll, pbdwr.pbd |
DataWindows and DataStores. |
|
pbsysfunc.dll |
System functions. |
|
pbresource.dll |
PowerBuilder resource file. |
|
pbacc.dll, PBAccessibility.dll * |
UI accessibility and automation support (Section 508) |
|
pbjvm.dll, pbjag.dll |
Java support |
|
pbtra.dll, pbtrs.dll |
Database connection tracing |
|
pbdpl.dll |
Data pipeline support |
|
pbcomrt.dll |
COM/COM+ support |
|
pbcrypt.dll |
Encryption and decryption support |
The UI accessibility and automation support (Section 508) is turned on by default through the PowerBuilder initialization file. For more, see here.
Microsoft files
When you deploy the core PowerBuilder runtime files, you must also deploy the msvcr100.dll and msvcp100.dll Microsoft Visual C++ runtime libraries and the Microsoft .NET Active Template Library (ATL) module atl100.dll, if they are not present on the user's computer. The PowerBuilder runtime files have a runtime dependency on these files. See Third-party components and deployment for more information.
Additional runtime files
The following table lists additional runtime files that your application might not require. For example, pbvm.dll is required for all deployed applications, but pbrtc.dll and its associated runtime files are required only if your application uses Rich Text controls or RichText DataWindow objects.
For more information about deploying applications that use the pbjvm.dll for Java support, see Java support.
|
Name |
Required for |
|---|---|
|
pbhttpclient.dll |
HTTPClient support |
|
pboauth.dll |
OAuth 2.0 support |
|
pbrestclient.dll, pbhttpclient.dll, pboauth.dll, pbcompression.dll, pbjson.dll |
RESTClient support |
|
pbwebbrowser.dll (and its dependent DLLs: chrome_elf.dll, d3dcompiler_43.dll, d3dcompiler_47.dll, libEGL.dll, libGLESv2.dll, libcef.dll, swiftshader/libEGL.dll, swiftshader/libGLESv2.dll) and "pbcef" folder |
WebBrowser support |
|
pbrtc.dll, PBTXTEXT.dll, podofo.dll, tp4ole15.ocx, tp15.dll, tp15_bmp.flt, tp15_css.dll, tp15_doc.dll, tp15_dox.dll, tp15_gif.flt, tp15_htm.dll, tp15_ic.dll, tp15_ic.ini, tp15_jpg.flt, tp15_obj.dll, tp15_pdf.dll, tp15_png.flt, tp15_rtf.dll, tp15_tif.flt, tp15_tls.dll, tp15_wmf.flt, tp15_wnd.dll |
TX Text Control ActiveX 15.0 (32-bit) |
|
pbrtc.dll, PBTXTEXT.dll, podofo.dll, tx4ole28.ocx, tx28.dll, tx28_tls.dll, tx28_wnd.dll, tx28_obj.dll, tx28_ic.dll, tx28_rtf.dll, tx28_htm.dll, tx28_doc.dll, tx28_xml.dll, tx28_css.dll, tx28_pdf.dll, tx28_dox.dll, tx28_xlx.dll, mfc90u.dll, msvcr90.dll, msvcr120.dll, Microsoft.VC90.CRT.manifest, Microsoft.VC90.MFC.manifest |
TX Text Control ActiveX 28.0 (32-bit) |
|
pbrtc.dll, PBTXTEXT.dll, podofo.dll, tx4ole28.ocx, tx28.dll, tx28_css.dll, tx28_doc.dll, tx28_dox.dll, tx28_htm.dll, tx28_ic.dll, tx28_obj.dll, tx28_pdf.dll, tx28_rtf.dll, tx28_tls.dll, tx28_wnd.dll, tx28_xlx.dll, tx28_xml.dll, mfc90u.dll, msvcr90.dll, msvcr120.dll, Microsoft.VC90.CRT.manifest, Microsoft.VC90.MFC.manifest |
TX Text Control ActiveX 28.0 (64-bit) |
|
pbcompression.dll |
Compression and extraction support (used by CompressorObject and ExtractorObject) |
|
pbjson.dll |
JSON support |
|
PBDWExcel12Interop.dll, Sybase.PowerBuilder.DataWindow.Excel12.dll |
MS Excel12 support |
|
pbpdf.dll |
NativePDF support (Saving DataWindows as PDF files using the NativePDF! method) |
|
PBDOM.pbx |
PB DOM |
|
PBRibbonBar.dll (and its dependent DLLs: PBXerces.dll, xerces-c_2_8.dll, xerces-depdom_2_8.dll, pbjson.dll) |
RibbonBar support |
|
pbtheme.dll, pbjson.dll, and "theme" folder ("theme" folder must be manually copied from the "%AppeonInstallPath%\PowerBuilder [version]\IDE" directory) |
UI theme support |
|
PBXerces.dll, xerces-c_2_8.dll, xerces-depdom_2_8.dll |
XML support (for DataWindows\DataStores and Web DataWindow) |
|
PBDotNet.dll, PBDotNetFrameworkInvoker.dll, PBDotNetCoreInvoker.dll |
.NET assembly calls |
|
pblab.ini |
Label DataWindow presentation-style predefined formats |
|
pbejbclient.pbx, pbejbclient.jar |
EJB Client (Obsolete) |
|
pbrtc.dll, PBMSText.dll |
Microsoft RichEdit Control (64-bit) (Obsolete) |
|
pbrtc.dll, PBTCTEXT.dll, TER25.dll, WRS9.dll, spell32.dll, PDC32.dll, WRW9.dll, HTS20.DLL, ssts.dll, SSGP.dll, TXML2.dll |
Rich Edit Control (TE Edit Control) (32-bit) (Obsolete) |
|
Gnu--LGPL.txt, EasySoap.dll, Thai Open License.txt, ExPat.dll, LICENSE, libeay32.dll, ssleay32.dll, pbsoapclient.pbx, pbwsclient.pbx, pbNetWSRuntime.dll |
SOAP Client for Web Service (Obsolete) |
|
Sybase.PowerBuilder.WebService.Runtime.dll, Sybase.PowerBuilder.WebService.RuntimeRemoteLoader.dll, Sybase.PowerBuilder.WebService.WSDL.dll, Sybase.PowerBuilder.WebService.WSDLRemoteLoader.dll |
Web service DataWindows (Obsolete) |
Installed path
%systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version].
The Sybase DLLs are installed to %AppeonInstallPath%\PowerBuilder 21.0\DotNET\bin.
The Sybase.PowerBuilder.DataWindow.Excel12.dll file will be automatically installed to the Windows GAC folder, for example, C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Sybase.PowerBuilder.DataWindow.Excel12, if you run the MSM or MSI package. However, if you manually copy runtime DLLs to the client (instead of using the MSM or MSI package), make sure to copy the Sybase.PowerBuilder.DataWindow.Excel12.dll file to the same directory as the application executable, as this file is a C# assembly DLL and cannot be loaded through the environment variable.
Deployment path
Same directory as the application, in a directory on the system path, or in the App Path registry key.
Registry entries
Localized runtime files
Localized runtime files are provided for French, German, Italian, Spanish, Dutch, Danish, Norwegian, and Swedish. These files are usually available shortly after the general release of a new version of PowerBuilder. The localized runtime files let you deploy PowerBuilder applications with standard runtime dialog boxes in the local language. They handle language-specific data when the application runs.
For more information, see Localizing the product.
Starting from version 2019 R3, the PowerBuilder runtime files are provided as an installable independent component in the PowerBuilder Installer. When you run the PowerBuilder Installer, the latest Runtime and IDE can be selected and installed respectively; and you will need to install Runtime before IDE if no runtime has been installed on the machine, because IDE requires a runtime to start.
To install PowerBuilder Runtime:
-
Run the PowerBuilder Installer.
-
Click Install/Modify or Update and then select PowerBuilder Runtime in the Components tab and then click Install or Update.
Multiple versions of "PowerBuilder Runtime" can be installed on the same machine.
"PowerBuilder Runtime" is always installed to %systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version], for example, C:\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime 19.2.0.2388 ("19.2" indicates 2019 R3); and its version number and installation directory are recorded in the system registry path:
The 32-bit apps in 32-bit OS search for this registry: HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerBuilder Runtime
The 32-bit apps in 64-bit OS search for this registry: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Sybase\PowerBuilder Runtime
The 64-bit apps in 64-bit OS search for this registry: HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerBuilder Runtime
If there are multiple versions of "PowerBuilder Runtime" installed, there will be multiple "Runtime [version]" installation folders and multiple registry entries.
Note
Pay attention to the following major changes caused by the separation of Runtime from IDE:
-
All runtime DLLs that used to be installed to the "Shared" folder are now separately installed to the "Runtime [version]" folder and the "IDE" folder instead, in order to physically separate Runtime files from IDE files.
"Runtime [version]" folder contains the files required at runtime. Example location: C:\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime 19.2.0.2556.
"IDE" folder contains the support files required by IDE. Example location: C:\Program Files (x86)\Appeon\PowerBuilder 21.0\IDE.
-
The runtime file location is no longer recorded in the PATH environment variable; it is recorded in the system registry instead.
-
The runtime files (including .dll, .ini, .pbx, .pbd etc.) are renamed so that the version number indicator (such as "170", "190") that used to be appended to the file name is removed, for example, pbvm190.dll is renamed as pbvm.dll.
If any external program has called the runtime file, you may need to change the code accordingly.
Download runtime files for 2017 R3, 2019, and 2019 R2
To help developers conveniently get the runtime files for versions earlier than 2019 R3, Appeon provides the runtime files as zip packages on the site: https://www.appeon.com/developers/get-help/knowledgebase-for-pb. You can download from here the runtime files for 2017 R3, 2019, and 2019 R2.
If you want to uninstall a runtime version which is currently used by the IDE, you will be prompted to confirm the uninstall; and if you continue to uninstall, the IDE will automatically find the best matching version (normally the latest) available on the machine, or will fail to work if no compatible runtime version is found.
PowerBuilder IDE can work with multiple PowerBuilder Runtime of different versions.
When there are more than one version of PowerBuilder Runtime installed, you can determine which version of PowerBuilder Runtime will be loaded by the PowerBuilder IDE. By default, the latest PowerBuilder Runtime that is installed will be used by the PowerBuilder IDE. If a newer version of PowerBuilder Runtime is installed, you will be prompted to switch to the newer version and compile the PowerScripts with the newer version when you open PowerBuilder IDE. Or you can manually change to use a different PowerBuilder Runtime for the IDE. The PowerBuilder Runtime will be used by the IDE to run, debug, compile, and build the application.
To manually change a PowerBuilder Runtime for the PowerBuilder IDE:
-
Select Tools>System Options.
-
On the General tab, select a version from the Switch PowerBuilder Runtime Version list.
-
Restart PowerBuilder IDE for the change to take effect.
If more than one instances of IDE are running, make sure to restart all instances.
The PowerBuilder IDE will load the runtime files according to the specified version. If the specified version of runtime failed to load, IDE will load the latest version of runtime that is installed and compatible with the IDE.
PowerBuilder IDE can work with PowerBuilder Runtime at the same or earlier versions, for example:
|
IDE (including MRs) |
Supported Runtime (including MRs) |
Unsupported Runtime |
|---|---|---|
|
2019 R3 |
2019 R3 |
2021 or later |
|
2021 |
2019 R3, 2021 |
2022 or later |
|
2022 |
2019 R3, 2021, 2022 |
2022 R2 or later |
|
2022 R2 |
2019 R3, 2021, 2022, 2022 R2 |
2022 R3 or later |
|
2022 R3 |
2019 R3, 2021, 2022, 2022 R2, 2022 R3 |
2023 or later |
The application executable can only run with PowerBuilder Runtime at the exact same version. If there are more than one builds of PowerBuilder Runtime installed, you can determine which build of PowerBuilder Runtime will be loaded by the application executable.
The application executable in this section refers to the native C/S application compiled using Pcode only, excluding the application compiled using machine code and the application deployed by PowerClient.
If the application is compiled using machine code, follow instructions in Compiler basics to configure the runtime files.
If the application is deployed using PowerClient, it will not be able to select PowerBuilder Runtime (the runtime version used by the IDE will be used by the application by default).
Note
Applications deployed using PowerClient cannot switch the runtime version like the native C/S application. But developers can deploy the same application with different application names and with different runtime versions (the runtime version used by the IDE will be used for deployment, so developers can manually change the runtime version in the IDE before deployment), and then run the application using different names against the corresponding runtime version.
To configure which version of PowerBuilder Runtime will be used by the application executable,
-
Specify the version of PowerBuilder Runtime in the configuration file (executable-name.xml).
The configuration file is automatically created by default using the same name under the same directory as the application executable, for example, if the application executable is app1.exe, then the configuration file is app1.xml. (However, this file will not be generated if the application is compiled using machine code.)
By default, the configuration file contains the runtime path and version which is specified on the Run tab of the application project painter. You can open the configuration file in an editor and change the runtime path and version that will be loaded by the application executable.
If the PowerBuilder Runtime files are placed in the same directory as the application executable, you could specify a relative path.
For example, if the "Runtime" folder is in the same folder as the executable file:
<RuntimePath>\Runtime\Runtime 21.0.0.1234</RuntimePath>
or if the "Runtime" folder is placed next to the folder which contains the executable file:
<RuntimePath>..\Runtime\Runtime 21.0.0.1234</RuntimePath>
Note
In the configuration file (executable-name.xml), you can only input one path and that path should point to the location of the runtime files; you cannot specify any other files or paths such as pb.ini (they should be deployed and distributed like before).
Runtime files here refer to the files that are installed by the PowerBuilder Runtime component and required by the application at runtime.
-
Make sure to keep the configuration file in the same folder as the application executable when you distribute the application package.
Note
If you want to use the configuration file to determine the runtime files, make sure no runtime files exist under the same directory as the executable file, otherwise, these runtime files will be loaded before the ones specified in the configuration file.
Make sure you have correctly specified the runtime path in the configuration file, otherwise, the application will throw an error if it failed to load the runtime file. If you do not want to use the configuration file, make sure to remove it, then the application will search for the runtime DLLs in the following sequence:
-
the runtime version used during the application compilation
-
the best matching version recorded in the system registry (normally the latest compatible version; and the application will not look for a version older than the one used for compilation)
-
the runtime path listed in the PATH environment variable
Environment variable
The location of PowerBuilder Runtime is no longer listed in the environment variable starting from version 2019 R3; instead it is recorded in the system registry by default. But you can add the location to the PATH environment variable by yourself.
The application executable can only run with PowerBuilder Runtime at the exact same version, for example:
|
Application executable compiled with Runtime |
Can run with Runtime |
Cannot run with Runtime |
|---|---|---|
|
2019 R3 |
2019 R3 |
2019 R2 or earlier, 2021 or later |
|
2021 |
2021 |
2019 R3 or earlier, 2022 or later |
|
2022 |
2022 |
2021 or earlier, 2023 or later |
If you are deploying an executable or component that accesses a database, your users need access to the DBMS and to the database your application uses.
Where to install database connectivity files
You do not need to deploy database connectivity files with a client application that relies on a middle-tier component on another computer to perform database transactions. Database connectivity files must be deployed on the computer that interacts with the database server.
You need to:
-
If necessary, install the DBMS runtime (client) files in the application directory or in a directory on the system path
If your application uses a standalone SQL Anywhere database, you can install the SQL Anywhere Runtime Edition files on the user's computer. For more information, see SQL Anywhere files. Otherwise follow the instructions and licensing rules specified by the vendor.
-
Make sure each user has access to the database the application uses
If your application uses a local database, install the database and any associated files, such as a log file, on the user's computer.
If your application uses a server database, make sure the user's computer is set up to access the database. This may be the task of a database administrator.
-
Install any database interfaces your application uses on the user's computer
-
If your application uses the ODBC interface, configure the ODBC database drivers and data sources, as described in Configuring ODBC data sources and drivers
For more information about database drivers and interfaces, see:
The following table lists the native database drivers supplied with PowerBuilder. If an application or component uses the database specified, the file is required on the computer. The first two characters of the native database file name are PB, the next three characters identify the database, and the last two identify the version of PowerBuilder.
|
Name |
Required for |
|---|---|
|
pbin9.dll |
Informix v9.x Interface (IN9) |
|
pbi10.dll |
Informix v10.x & v12.x Interface (I10) |
|
pbo90.dll |
Oracle 9i (O90) |
|
pbo10.dll |
Oracle 10g (O10) |
|
pbora.dll |
Oracle 11g and later (ORA) |
|
pbmsoledbsql.dll |
Microsoft OLE DB Driver for SQL Server |
|
pbsnc.dll |
SQL Native Client for Microsoft SQL Server (SNC) |
|
pbdir.dll |
DirectConnect (DB) |
|
pbase.dll |
Adaptive Server Enterprise CT-LIB for Adaptive Server 15.x & 16.x (ASE) |
|
pbsyc.dll |
Adaptive Server Enterprise CT-LIB (SYC) |
|
pbodw.dll, pbodt.dll, pbCSI.dll, Sybase.PowerBuilder.DataSource.OData.dll, Sybase.PowerBuilder.ODataClient.dll, Sybase.PowerBuilder.ODataWrapper.dll |
OData database interface (ODT) |
Installed path
%systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version]\
Deployment path
Same directory as the application, in a directory on the system path, or in the App Path registry key.
Registry entries
This section lists files that are required for all ODBC database connections from PowerBuilder or InfoMaker applications, as well as files required for a specific database interface or DBMS.
PowerBuilder ODBC interface files
The following PowerBuilder ODBC interface files are required if your application uses ODBC:
|
Name |
Description |
|---|---|
|
pbodb.dll |
PowerBuilder ODBC interface |
|
pbodb.ini |
PowerBuilder ODBC initialization file |
Installed path
%systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version]\
Deployment path
Same directory as the application, in a directory on the system path, or in the App Path registry key.
Registry entries
Notes
The PBODB.ini file must be in a directory defined by the HKEY_CURRENT_USER\Software\sybase\PowerBuilder\21.0\InitPath registry setting or, in the absence of that key, in the same directory as the DLL file. In most cases, the target deployment machine will not have the registry setting and, therefore, the INI file should be in the same directory as the DLL.
Microsoft ODBC files
The following table lists the Microsoft ODBC files that are required if your application uses ODBC.
|
Name |
Description |
|---|---|
|
DS16GT.dll DS32GT.dll ODBC32.dll ODBC32GT.dll ODBCAD32.exe ODBCCP32.cpl ODBCCP32.dll ODBCCR32.dll ODBCINST.cnt ODBCINST.hlp ODBCINT.dll ODBCTRAC.dll |
Microsoft ODBC driver manager, DLLs, and Help files |
Installed path
Windows system directory.
Deployment path
Windows system directory.
Registry entries
None.
Notes
The Microsoft ODBC Driver Manager (ODBC32.dll) and supporting files are usually already installed in the user's Windows system directory.
If your PowerBuilder application uses a SQL Anywhere database, you need to deploy the SQL Anywhere DBMS as well as SQL Anywhere's ODBC database drivers.
Restrictions
PowerBuilder includes SQL Anywhere for use during the development process. However, this product cannot be deployed royalty-free to your users.
If your application requires the data definition language (DDL), a transaction log, stored procedures, or triggers, see your sales representative.
If your application uses a standalone database, you can deploy the SQL Anywhere Desktop Runtime System to users' computers without incurring additional license fees. The runtime system allows the user to retrieve and modify data in the database, but does not allow modifications to the database schema. It does not support transaction logs, stored procedures, or triggers.
A full installation for the SQL Anywhere driver, runtime engine, and supporting files is available in the PowerBuilder setup program.
The following table lists some of the files that are installed. For more information see the RuntimeEdition.html file in the installed SQL Anywhere directory. It contains a list of all the SQL Anywhere files that can be freely deployed with PowerBuilder applications to end users' computers.
|
Name |
Description |
|---|---|
|
dbodbc11.dll |
SQL Anywhere ODBC driver |
|
dbbackup.exe |
SQL Anywhere backup utility |
|
dbcon11.dll |
Connection dialog box, required if you do not provide your own dialog box and your end users are to create their own data sources, if they need to enter user IDs and passwords when connecting to the database, or if they need to display the Connection dialog box for any other purpose |
|
dbisqlc.exe |
Interactive SQL utility |
|
dblgen11.dll |
Language-specific string library (EN indicates the English version) |
|
dblib11.dll |
Interface library |
|
dbtool11.dll |
SQL Anywhere database tools |
|
dbunlspt.exe |
SQL Anywhere unload utility |
|
dbvalid.exe |
SQL Anywhere validation utility |
|
rteng11.exe |
Restricted runtime engine |
|
rteng11.lic |
License file for restricted runtime engine |
|
dbctrs11.dll |
Performance utility |
|
dbserv11.dll |
Server utility |
Installed path
\Program Files\SQL Anywhere 16\bin32 or \bin64
Deployment path
Same directory as the application, in a directory on the system path, or in the App Path registry key.
Registry entries
See App Path registry key and Configuring ODBC data sources and drivers.
Privilege requirements on Windows
When running under User Account Control, the SQL Anywhere restricted runtime engine (rteng11.exe) and other SQL Anywhere executables require elevated privileges. For Windows 8.1 and later versions of Windows, you can use the SQL Anywhere elevated operations agent (dbelevate11.exe) to elevate the privileges of users running these executables and allow non-elevated client processes to autostart elevated servers or database engines. The following DLLs also require elevated privileges when they are registered and unregistered: dbcon11.dll, dbctrs11.dll, dbodbc11.dll, dboledb11.dll, and dboledba11.dll.
Notes
Supporting files should be installed in the same directory as dbodbc11.dll. If you are not using the English string library, make sure you deploy the appropriate version of the language-specific string library.
Configuring ODBC data sources and drivers
ODBC.INI
To allow the user to connect to a particular data source, your installation program must provide a definition for that data source in the ODBC.INI key in the registry on the computer that accesses the data source, in HKEY_CURRENT_USER for a user DSN or in HKEY_LOCAL_MACHINE for a system DSN. The data source definition specifies the name and location of the database driver as well as the command required to start the database engine. The data source in the ODBC Data Sources key must also be listed in ODBC.INI.
The following shows typical registry entries for a data source called MyApp DB that uses SQL Anywhere. Registry keys are enclosed in square brackets and are followed by string values for that key in the format "Name"="Value":
[HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\MyApp DB] "Driver"="C:\Program Files\SQL Anywhere 16\bin32\dbodbc16.dll" "Start"="c:\program files\SQL Anywhere 16\bin32\dbeng16.exe -c9m" "UID"="dba" "PWD"="sql" "Description"="Database for my application" "DatabaseFile"="C:\Program Files\myapps\myapp.db" "AutoStop"="Yes" [HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources] "MyApp DB"="SQL Anywhere 16.0"
ODBCINST.INI
Your installation program needs to make two types of entry in the ODBCINST.INI key in HKEY_LOCAL_MACHINE\SOFTWARE\ODBC for each driver that your deployed application uses:
-
Add a string value with the name of the driver and the data value "Installed" to the ODBC DRIVERS key in ODBCINST.INI
-
Add a new key for each driver to the ODBCINST.INI key with string values for Driver and Setup
Some drivers require additional string values in ODBCINST.INI.
If the ODBC database driver files are not located in a directory on the system path, you also need to add their location to the App Paths key for the executable file.
If you are using ODBC drivers obtained from a vendor, you can use the driver's setup program to install the driver and create registry entries.
The following shows a typical registry entry for SQL Anywhere. A registry key is enclosed in square brackets and is followed by string values for the key in the format "Name"="Value":
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\SQL Anywhere 16.0] "Driver"="c:\program files\SQL Anywhere 16\bin32\dbodbc16.dll" "Setup"="c:\program files\SQL Anywhere 16\bin32\dbodbc16.dll"
For more information about the contents of the registry entries for ODBC drivers and data sources, see the section called “How PowerBuilder accesses the data source” in Connecting to Your Database.
If your application uses OLE DB to access data, you must install Microsoft's Data Access Components software on each user's computer if it is not installed already.
The PowerBuilder OLE DB interface requires the functionality of the Microsoft Data Access Components (MDAC) version 2.8 or later software.
To check the version of MDAC on a computer, users can download and run the MDAC Component Checker utility from the MDAC Downloads page at https://msdn.microsoft.com/en-us/data/aa937730.aspx.
On the Windows 8.1/10 operating systems, the Windows Data Access Components (DAC) version 6.0 replaces MDAC, and implements the functionality requirements of the PowerBuilder OLE DB interface.
OLE DB data providers
Several Microsoft OLE DB data providers are automatically installed with MDAC and DAC, including the OLE DB Provider for SQL Server (SQLOLEDB) and OLE DB Provider for ODBC (MSDASQL).
OLE DB Provider for SQL Server (SQLOLEDB) is not maintained any more and it is not recommended to use it for new development work. Instead, use the new OLE DB Driver for SQL Server (MSOLEDBSQL) which will be updated with the most recent server features. The new OLE DB Driver for SQL Server (MSOLEDBSQL) must be used with the "MSOLEDBSQL SQL Server" interface (instead of the "OLE Microsoft OLE DB" interface) installed with PowerBuilder.
PowerBuilder OLE DB interface files
The PowerBuilder OLE DB interface file is required if your application uses OLE DB. The ODBC initialization file is required if you have used it to customize OLE DB settings:
|
Name |
Description |
|---|---|
|
pbole.dll |
PowerBuilder OLE DB interface |
|
pbodb.ini |
PowerBuilder ODBC initialization file |
Installed path
%systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version]\
Deployment path
Same directory as the application, in a directory on the system path, or in the App Path registry key.
Registry entries
Notes
The INI and DLL files must be in the same directory. If you have modified the pbodb.ini file, make sure you deploy the modified version.
The PowerBuilder ADO.NET interface supports the OLE DB, Microsoft SQL Server .NET, Oracle ODP.NET, and SAP ASE data providers. If you use ADO.NET, you must deploy pbado.dll, pbrth.dll, sybase.PowerBuilder.Db.dll, sybase.PowerBuilder.DbExt.dll, and, for OLE DB, the OLE DB data provider.
|
Name |
Description |
|---|---|
|
pbado.dll pbrth.dll sybase.PowerBuilder.Db.dll sybase.PowerBuilder.DbExt.dll sybase.PowerBuilder.DataSource.Sharing.dll OLE DB data provider (for OLE DB) |
PowerBuilder ADO.NET interface |
The files pbado.dll and pbrth.dll are standard DLL files, and you can deploy them in the same way as other PowerBuilder DLLs. However, sybase.PowerBuilder.Db.dll, sybase.PowerBuilder.DbExt.dll, and sybase.PowerBuilder.DataSource.Sharing.dll are .NET assemblies. You can use one of three techniques to deploy the files:
-
Deploy sybase.PowerBuilder.Db.dll, sybase.PowerBuilder.DbExt.dll, and sybase.PowerBuilder.DataSource.Sharing.dll in the same directory as the executable file that calls the ADO.NET driver.
-
Use a .NET application configuration file to assign the path of sybase.PowerBuilder.Db.dll, sybase.PowerBuilder.DbExt.dll, and sybase.PowerBuilder.DataSource.Sharing.dll. The file contains configuration settings that the common language runtime (CLR) reads as well as settings that the application reads. For an executable file, the configuration file has the same name as the executable file with the extension .config. The pb210.exe.config file in your PowerBuilder 2021 directory is an example.
For more information about configuration files, see the Microsoft Visual Studio SDK documentation.
-
Add the sybase.PowerBuilder.Db.dll, sybase.PowerBuilder.DbExt.dll, and sybase.PowerBuilder.DataSource.Sharing.dll assemblies to the Global Assembly Cache (GAC). For more information about the GAC, see the section on the Global Assembly Cache in the Microsoft Visual Studio SDK documentation. If you use the Runtime Packager, the assemblies are installed in the GAC.
The PowerBuilder JDB interface supports the Java Runtime Environment (JRE) versions 1.6 and later.
If your application or component uses JDBC connections, you must deploy the JDB driver as well as the appropriate Java package for the Java VM you are using. The Java virtual machine and a vendor-supplied JDBC-compliant driver, such as SAP Sybase jConnect for JDBC, must also be installed and configured on the computer that accesses the data source.
For more information about the Java VM, see Java support.
|
Name |
Description |
|---|---|
|
pbjdb.dll |
PowerBuilder JDBC Driver (JDB) for JRE 1.6 or later |
|
pbjdbc12.jar |
Java package for PowerBuilder JDB driver and JRE 1.6 or later |
Installed path
%systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version]\
Deployment path
Same directory as the application, in a directory on the system path, or in the App Path registry key.
Registry entries
Make sure the CLASSPATH environment variable includes the PowerBuilder pbjdbc12.jar file. For example:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment] "CLASSPATH"="C:\Program Files\Appeon\Common\PowerBuilder\Runtime 19.2.0.2382\pbjdbc12.jar;...
You must deploy the PowerBuilder pbjvm.dll file with any applications or components that use the Java Runtime Environment (JRE), and there must be a JRE installed on the target computer. The JRE is required for EJB clients (obsolete), JDBC connections, and saving as PDF using XSL-FO. You can copy the JRE installed with PowerBuilder to the same directory as the PowerBuilder runtime files on the target computer, or use an existing JRE whose location is defined in the user's system PATH environment variable.
Locating the Java VM
When a PowerBuilder application requires a Java VM, the PowerBuilder runtime searches for the jvm.dll file in a subdirectory of the directory where pbjvm.dll is installed on the user's computer. The jvm.dll file is installed in the JRE\bin\client directory of JDK 1.6 and later installations.
PowerBuilder adds the location of jvm.dll to the beginning of the path currently being used by the PowerBuilder application. This path is a copy of the path defined in the user's PATH system environment variable. PowerBuilder does not modify the environment variable maintained in the Windows registry.
To locate the jvm.dll, PowerBuilder first determines where pbjvm.dll is installed. Suppose pbjvm.dll is installed in C:\Program Files\Appeon\Common\PowerBuilder\Runtime 19.2.0.2382. Then PowerBuilder uses this search procedure to add the location of the jvm.dll to the path currently in use:
-
Search for the directory structure JRE\bin\client in %AppeonInstallPath%\PowerBuilder [version]\IDE\ and, if found, add it to the beginning of the path.
-
If not found, search for a JDK directory structure that contains JRE\bin\client in %AppeonInstallPath%\PowerBuilder [version]\IDE\ and, if found, add it to the beginning of the path.
If none of these directory structures is found, PowerBuilder uses the first jvm.dll whose location is defined in the user's PATH environment variable. If no jvm.dll is found, the Java VM does not start.
The runtime Java VM classpath
When PowerBuilder starts a Java VM, the Java VM uses internal path and class path information to ensure that required Java classes are always available. At runtime, the Java VM uses a class path constructed by concatenating these paths:
-
The system JAVA_HOME environment variable.
-
A class path added programmatically when the Java VM is started. For example, EJB client applications can pass a class path to the CreateJavaVM method.
-
The PowerBuilder runtime static registry class path. This is a path built into the pbjvm.dll file that corresponds to the path in the Windows Registry that is used when you are developing an application in PowerBuilder. It contains classes required at runtime for features that use a Java VM.
-
The system CLASSPATH environment variable.
-
The current directory.
Overriding the runtime static registry classpath
If necessary, you can override the JVM settings and properties defined for runtime use in the static registry. PowerBuilder uses the following algorithm to locate configuration information:
-
When the first request is made for a JVM, PowerBuilder looks for registry entries for the configuration information and properties to be passed to the function that creates the JVM.
-
If PowerBuilder finds a registry entry for the configuration information, it uses it instead of the static registry. If it does not find a registry entry, it uses the static registry.
-
If PowerBuilder finds a registry entry for custom properties to be passed to the JVM, it uses those instead of the static registry. If it does not find a registry entry, it uses the static registry entries.
To override the default settings, create a new key named PBRTConfig in the HKEY_LOCAL_MACHINE\Software\Sybase\PowerBuilder\2019\Java key, then add either or both of the following subkeys: PBJVMconfig and PBJVMprops.
To duplicate the static registry entries, add the same string values to these subkeys that you see in the PBIDEConfig key, that is:
|
Subkey |
String value name |
String value data |
|---|---|---|
|
PBJVMconfig |
Count |
1 |
|
|
0 |
-verbose:jni,class |
|
PBJVMprops |
java.compiler |
NONE |
You can override either the configuration or properties entries or both. If you make incorrect entries, PowerBuilder attempts to recover by defaulting to the static registry. However, you should be cautious about making any changes since you can cause incorrect behavior in the JVM if you do not configure it correctly.
Several PowerBuilder extension files are provided with PowerBuilder. If your application uses one of these extensions, you must deploy the files listed in the following table.
|
Extension |
Files |
|---|---|
|
PowerBuilder Document Object Model |
pbdom.pbx, PBXerces.dll, xerces-c_2_8.dll, xerces-depdom_2_8.dll |
|
EJB client (Obsolete) |
pbejbclient.pbx, pbejbclient.jar |
|
SOAP client for Web services (Obsolete) |
ExPat.dll, libeay32.dll, ssleay32.dll, xerces-c_2_8.dll, xerces-depdom_2_8.dll, EasySoap.dll, pbnetwsruntime.dll, pbsoapclient.pbx, pbwsclient.pbx, Sybase.PowerBuilder.WebService.Runtime.dll, Sybase.PowerBuilder.WebService.RuntimeRemoteLoader.dll |
In addition to the files listed in the table for EJB client, a Java Runtime Environment (JRE) compatible with the JDK on the EJB server must be available on the client and listed in the CLASSPATH.
For more information, see Java support.
PowerBuilder can save the DataWindow's data and presentation as a Portable Document Format (PDF) file using three techniques. By default, PowerBuilder saves as PDF using a distiller. PowerBuilder can also save to native PDF using PDFlib, or save to PDF or XSL Formatting Objects (XSL-FO) format using the Apache XML Formatting Objects processor.
In order for users to use the SaveAs method to save data as PDF with the distiller, they must first download and install Ghostscript on their computers as described in the procedure that follows.
The use of GPL Ghostscript is subject to the terms and conditions of the GNU General Public License (GPL). Users should be asked to read the GPL before installing GPL Ghostscript on their computers. A copy of the GPL is available on the GNU Project Web server at http://www.gnu.org/licenses/gpl.html.
The use of AFPL Ghostscript is subject to the terms and conditions of the Aladdin Free Public License (AFPL). Commercial distribution of AFPL Ghostscript generally requires a written commercial license. For more information, see the Ghostscript website at https://www.ghostscript.com.
To install Ghostscript:
-
Into a temporary directory on your computer, download the self-extracting executable file for the version of Ghostscript you want from one of the sites listed on the Ghostscript website at https://www.ghostscript.com/download/.
See the Release Bulletin for the version of Ghostscript that was used for testing.
-
Run the executable file to install Ghostscript on your system.
The default installation directory is C:\Program Files\gs. You can select a different directory and/or choose to install shortcuts to the Ghostscript console and readme file.
After installing Ghostscript, you should read the readme.htm file in the doc subdirectory in the Ghostscript installation directory to find out more about using Ghostscript and distributing it with your application.
Save Rows As fails
To save as PDF in the DataWindow painter, select File>Save Rows As and select PDF as the Save As type. If you do not install Ghostscript and use the default export properties, PowerBuilder displays a pop-up window notifying you that Save Rows As failed. If you install Ghostscript and then change the name of the directory where Ghostscript is installed, Save Rows As PDF fails silently.
Location of files
When you save a DataWindow object as PDF using the Distill! method, PowerBuilder searches in the following locations for an installation of GPL or AFPL Ghostscript:
-
The Windows registry
-
The relative path of the pbdwe.dll file (typically %systemdrive%\Program Files (x86)\Appeon\Common\PowerBuilder\Runtime [version])
-
The system PATH environment variable
If GPL or AFPL Ghostscript is installed using the Ghostscript executable file, the path is added to the Windows registry.
If the Ghostscript files are in the relative path of the pbdwe.dll file, they must be installed in this directory structure:
dirname\pbdwe.dll dirname\gs\gsN.NN dirname\gs\fonts
where dirname is the directory that contains the runtime DLLs and N.NN represents the release version number for Ghostscript.
You might not need to distribute all the fonts provided in the distribution. For information about fonts, see Fonts and font facilities supplied with Ghostscript at https://www.ghostscript.com/doc/current/Fonts.htm.
PostScript printer drivers
If your users have installed a PostScript printer on their computers, the PostScript driver files required to create PDF files, PSCRIPT5.DLL, PS5UI.DLL, and pscript.ntf, are already installed, typically in C:\Windows\System32\DriverStore\FileRepository\ntprint.inf_1a216484\Amd64 on a 64-bit Windows system. Your users must use the version of these files that is appropriate to the operating system where the PDF file is created. They should copy the files to the dirname\drivers directory.
You must also deploy the related files that are installed in %AppeonInstallPath%\PowerBuilder [version]\IDE\drivers. These files can be copied to or installed on users' computers. They must be located in this directory structure:
dirname\pbdwe.dll dirname\drivers
PostScript printer profile
Each user's computer must have a PostScript printer profile called Sybase DataWindow PS. Users can add the profile manually using the Windows Add Printer wizard in one of the following ways:
-
By selecting a printer with PS in its name (such as "Apple Color LW 12/660 PS") from the list of printers on the Install Printer Software page of the wizard, and changing the printer name to "Sybase DataWindow PS" on the Name Your Printer page.
-
(For 32-bit Windows only) By clicking the Have Disk button on the Install Printer Software page of the wizard, browsing to the Adist5.inf file (installed with PowerBuilder in the %AppeonInstallPath%\PowerBuilder [version]\IDE\drivers directory) or to another PostScript driver file, and on the Name Your Printer page, changing the printer name to "Sybase DataWindow PS".
For how to set properties for the Distill! method, see the section called “Saving as PDF using the Distill! method with Ghostscript” in Users Guide.
No drivers need to be installed in order to use the PDFlib generator to save DataWindow data as a native PDF file.
The DLL file for PDFlib (PBPDF.dll) is automatically packaged into the PowerBuilder application executable without requiring the developer to make any configuration or selection during the building process.
By using the PDFlib generator, the DataWindow is first saved to EMF. Depending on the size of the DataWindow and also the specified page size, there may be multiple EMFs. For example, if a DataWindow has 8 columns that cannot fit in a page, maybe the first 3 columns are in page #1, and the other 5 columns in page #2; if the DataWindow has more data, and the data will go to page #3 (and page #4), page #5 (and page #6), and so on. The EMF files will then be converted and combined into one PDF. The EMF files are memory-based and will be deleted from memory after the successful generation of the PDF file.
During the PDF generation process, an "Appeon" folder (containing a "NativePDF" sub-folder which contains a "Log" and a "Temp" sub-folders) will be generated in the temporary directory; the temporary files in these folders will be deleted after the PDF file is created but the folders will be kept for future use.
For how to set PDFLib as the default PDF method and the other properties, see the section called “Saving as PDF using NativePDF! method with PDFlib” in Users Guide.
If your application uses the Apache processor to save as PDF or XSL-FO, you must deploy the fop-0.20.4 directory and the Java Runtime Environment (JRE) with your application.
They must be deployed in the same directory as the PowerBuilder runtime files. For example, if you deploy your application and pbvm.dll and the other PowerBuilder runtime files in a directory called MyApplication, the Apache processor must be deployed in MyApplication/fop-0.20.4, and the JRE in MyApplication/jre. However, you do not need to place a copy of the JRE in this location if the full JDK is installed on the target computer and is in the classpath.
The following JAR files must be in the user's classpath:
| fop-0.20.4\build\fop.jar |
| fop-0.20.4\lib\batik.jar |
| fop-0.20.4\lib\xalan-2.3.1.jar |
| fop-0.20.4\lib\xercesImpl-2.1.0.jar |
| fop-0.20.4\lib\xml-apis.jar |
| fop-0.20.4\lib\avalon-framework-cvs-20020315.jar |
For more information about the JRE, see Java support.
On Windows DBCS platforms, you also need to deploy a file that supports DBCS characters to the Windows font directory on the target computer, for example, C:\WINDOWS\fonts. For more information about configuring fonts, see the Apache website at http://xmlgraphics.apache.org/fop/1.1/fonts.html.
For how to set properties for the XSL-FO method, see the section called “Saving as PDF using XSL-FO” in Users Guide.
