PowerBuilder 110 NET Quick Reference Guide.pdf by yan198555

VIEWS: 521 PAGES: 10

									PowerBuilder® 11.0 .NET Quick Reference Guide                     Version:     <0.2>

          PowerBuilder® 11.0 .NET Quick Reference Guide
This guide provides a quick reference to topics that you need to know when you attempt to
deploy and run PowerBuilder applications as .NET applications. For complete information on
a .NET feature, refer to the Deploying Applications and Components to .NET book in the
PowerBuilder 11.0 online Help.

1     System Requirements
1.1    Development and deployment (with PowerBuilder 11.0 installed)

        Windows XP Professional SP2 or Windows 2003 SP1
        .NET Framework 2.0 GA (version 2.0.50727)
        .NET Framework 2.0 SDK (for .NET Smart Client deployment only)
        Internet Information Services (IIS) 5.0 or higher (for .NET Web Forms and .NET Web
        Services local host deployment only)
        SQL Anywhere 10 (for samples and tutorials)
        Adaptive Server Anywhere 9.0.2 or SQL Anywhere 10 with MobiLink Synchronization
        (for .NET Smart Client MobiLink Synchronization feature only)

1.2    Runtime

        .NET Framework 2.0 redistributable files
        IIS 5.0 or higher configured for hosting ASP.NET 2.0 applications (for .NET Web
        Forms and .NET Web Services Runtime only)
        PowerBuilder 11.0 .NET runtime libraries.
        IE Web Controls (for .NET Web Forms runtime only)
        GNU Ghostscript (for .NET Web Forms runtime printing only)

Special Note:
      If more than one .NET Framework version is installed, modify the system PATH so
      that the .NET Framework 2.0 appears first.
      If you install IIS after .NET Framework 2.0, you need to register ASP.NET 2.0 with
      IIS to enable hosting ASP.NET 2.0 (run aspnet_regiis.exe –i from the .NET
      Framework 2.0 installed folder).

2     Prerequisites
2.1    For existing PowerBuilder applications
Before attempting to deploy an existing PowerBuilder application as a .NET application, you
must determine the type of .NET target you want to use for your application. The following
criteria will help you to determine the appropriate .NET target type:
            Small- or medium-sized reporting, inquiry, and simple transactional applications
            are ideal candidates for .NET Web Forms deployment.
            Large applications or intensive data entry applications are suitable for .NET Smart
            Client or .NET Windows Forms deployment.

<01/11/2007 >                                                                     Page 1 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                      Version:      <0.2>

             If you want to integrate existing business logic in PowerBuilder custom class user
             objects (NVOs) with other systems, you can use the .NET Web Service or the
             .NET Assembly targets for your applications. For better performance, partition the
             NVOs and related objects into new PBLs and deploy them from a .NET Web
             Service or .NET Assembly project.
After you select the .NET target type that you want, create a new .NET application target
and base it on an existing PowerBuilder client-server application.

2.2     For new development
With PowerBuilder 11.0, you can design and develop new applications and deploy them as
.NET applications. For new development, create a new .NET target of your choice from
scratch. Before developing .NET applications, refer to the Deploying Applications and
Components to .NET book in the HTML Help for a list of unsupported PowerBuilder features
in .NET targets.

3     PowerBuilder to .NET deployment basics

3.1     Dashes in PowerScript identifiers
If a PowerBuilder application uses dashes in its identifiers (for example, int max-value or
the window name w-employee), then the “Allow Dashes in Identifiers” property must be set
to true before you attempt to deploy .NET projects.
This property is set to true by default. If it is not set to true, open the application in the
Application painter, select Design>Options from the menu bar, select the Allow Dashes in
Identifiers check box on the Scripts tab page, and click OK.

3.2     Refactoring unsupported features (common to .NET deployment)
This section provides some basic refactoring tips for common unsupported features. For a
list of unsupported PowerBuilder features in .NET targets, refer to the Deploying
Applications and Components to .NET book in the PowerBuilder 11.0 HTML Help.

3.2.1    GOTO statement
         In .NET targets, the GOTO statement is not allowed to jump to a label with a
         different scope. The following code snippet causes deployment failure.
                   if b = 0 then
                          label1: …
                   end if
                goto label1
         Refactor this code with an alternative approach.

3.2.2    Narrow casting not allowed
         Narrow casting (downcasting) is not allowed by the C# compiler.
         n_ds ds
         ds = create Datastore // avoid this

<01/11/2007 >                                                                       Page 2 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                       Version:      <0.2>

        This code can be refactored as follows:
        Datastore ds //declare the variable of the same type as the object created.

3.2.3   Calling the base method of an indirect ancestor class in an override method is not allowed
        Suppose that there are three classes W1, W2 and W3. W1 inherits from Window, W2
        inherits from W1, and W3 inherits from W2.
        Each of these classes handles the Open event. In the Open event of W3, it is
        perfectly legal to code W1::open() in PowerScript. The W1 Open event is triggered.
        However, in .NET targets, the w2::open() event is triggered. Therefore, you must
        refactor such code segments before .NET deployment.

3.2.4   The “finally” clause
        The finally clause should not have a Return statement. If the finally clause has a
        Return statement, it results in a .NET project deployment error due to a C# compiler

3.2.5   Do not use “this” pronoun in function objects
        A function object is essentially a static method of a class. Although the PowerBuilder
        compiler does not prevent you from using the “this” pronoun in a function object, the
        C# compiler does not allow this.

3.2.6   Use PowerScript system functions instead of external functions.
        External functions are allowed in .NET deployment of a PowerBuilder application, but
        if PowerScript offers the same functionality, use PowerScript functions instead of
        external functions (for example, GetCurrentDirectory).
3.2.7   Issues with External functions
                Enough space should be allocated for a string parameter (using the
                PowerScript Space function), before passing the string to an external function
                by reference.
                The datatype of a parameter passed to an external function should be the
                same as the one declared for it.
                All external DLLs that are referred by external function calls must be added to
                the Win32 DLL list in the .NET Project painter or a runtime error will occur.

3.2.8   IsNull function limitation
        The IsNull function works for primitive datatypes only in .NET deployment. It does
        not work for structure or class objects. You can use IsValid as an alternative to IsNull
        for structures and class objects before attempting .NET deployment.

3.2.9   Naming conflict
        In .NET targets, the same name is not allowed for multiple objects, even if they have
        different types.

3.2.10 Consuming .NET assemblies in PowerBuilder
        Refer to the “Referencing .NET Classes in PowerScript” chapter in the Deploying
        Applications and Components to .NET book in the PowerBuilder 11.0 HTML Help.

<01/11/2007 >                                                                        Page 3 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                        Version:      <0.2>

3.2.11 Clipboard and drag-and-drop functions and are not supported in Web Forms targets
         Clipboard functions, such as the Cut, Copy, and Paste functions, are not supported in
         Web Forms targets. Drag-and-drop functionality is not supported in the browser

3.3     Best coding practices for .NET deployment

3.3.1    Use of Yield function in .NET Web Forms targets
         The Yield function is executed at the server when used in .NET Web Forms
         applications and requires additional system resources as well as frequent postbacks
         to the server. Because this reduces the performance of the application, you should
         avoid using the Yield function if you intend to deploy it in a .NET Web Forms project.

3.3.2    Timer in .NET Web Forms targets
         The Timer functions and events generate periodic postbacks when used in Web
         Forms targets. As this could be a severe drawback in data entry applications, you
         should avoid using Timer functions and events if you deploy such applications in .NET
         Web Forms projects.

3.3.3    File operation in .NET Web Forms targets
         File operations can greatly impede performance. If you must use file operations in
         Web Forms targets, you should use them in the “Share” operation mode.
         See the “File process mode” topic in the “Using the Web Forms File Manager” section
         in the Deploying Applications and Components to .NET book in the PowerBuilder 11.0
         HTML Help.

4     Running PowerBuilder .NET Web Forms Applications

4.1     Configuring database resources
                Grant full access rights to the ASPNET user account (if IIS is running on
                Windows XP) or the IIS_WPG user group (if IIS is running on Windows 2003
                Server) to the database client installed folder and all its subfolders (for
                example, the Oracle\bin folder)
                ODBC data sources should be created as System DSNs, not User DSNs.

4.2     Initial access time for Web Forms applications is greater than subsequent access times
         When you access a .NET Web Forms application for the first time, it takes a few
         seconds to load the page in the Internet Explorer (IE) browser due to JIT
         compilation. On subsequent access, the page loads faster in the IE browser.

4.3     Application menu, toolbar, and TreeView control do not render correctly
                Make sure the IE Web Controls are installed and configured on the server

<01/11/2007 >                                                                         Page 4 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                         Version:      <0.2>

                To install and configure IE Web Controls, refer to the “Configuring ASP.NET for Web
                Forms projects” section in Chapter 1 of the Deploying Applications and Components to
                .NET book in the HTML Help.

4.4   DataWindow pagination
       If your PowerBuilder application retrieves large volumes of data in a DataWindow
       (row count exceeds 100 rows), rendering this data in a client browser takes a longer
       time to process.
       In this scenario, you can use DataWindow pagination to reduce the size of the HTML
       and increase application performance.
       Please refer to “DataWindow pagination” in the section “Best practices for C# and
       .NET coding” in the Deploying Applications and Components to .NET book in the
       PowerBuilder 11.0 HTML Help.

4.5   Web page causes too many postbacks
       If a Web page containing DataWindows refreshes frequently even for simple actions
       (generating too many postbacks to the server), then:
                Check if the following events are handled (contain a script) for a DataWindow
                   o   Clicked
                   o   RowFocusChanging
                   o   RowFocusChanged
                   o   ItemFocusChanged
                   o   ItemChanged
                If any of these events are handled, clicking on the DataWindow control can
                trigger postbacks.
                Try replacing the functionality in these event handlers with the following
                alternative approaches:
                   o   Clicked – avoid it entirely. If possible, use a control like a
                       CommandButton and put functionality there.
                   o   RowFocusChanging – use a row-level CommandButton and put the
                       event handler in ButtonClicking.
                   o   RowFocusChanged– use a row-level CommandButton and put the
                       event handler in ButtonClicked.
                   o   ItemFocusChanged –avoid it entirely. If possible, use a control like a
                       CommandButton and put functionality there.
                   o   ItemChanged – avoid it entirely. If possible, use a control like a
                       CommandButton and put functionality there.
       Alternatively, use the JavaScript injection techniques described in the

<01/11/2007 >                                                                          Page 5 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                          Version:   <0.2>

5     Troubleshooting

5.1     Most common .NET deployment issues

5.1.1    Error: “…\bin\pb2cs.exe is not recognized as an internal or external command, operable
         program or batch file”
         Root cause: PBNET_HOME environment variable is not set correctly.
                Set the PBNET_HOME environment variable to the location of the DotNET
                directory in the PowerBuilder 11 installation directory.
                Make sure Sybase\Shared\PowerBuilder and Sybase\PowerBuilder                  11.0
                directories are set in the system PATH environment variable.
                The deployment process uses the XCOPY command to copy the required
                resources.   Make     sure    the     system     directory    (typically
                C:\WINDOWS\SYSTEM32) is in the system PATH environment variable.
                If the problem still exists, completely uninstall and reinstall PowerBuilder

5.1.2    Error: “Syntax error: line xxx: x: unexpected token – “
         Root cause: Dashes in PowerScript identifiers are disabled.
         Solution: Enable “Allow dashes in PowerScript Identifiers”. To set this property,
         please refer to section 3.1.

5.1.3    Error: Current user does not have administrative privileges on server.
         Root cause: Current user or group does not administrative privileges on a remote
         server for .NET Web Form deployment.
         Solution: Please check if you (the current user) have administrator privileges or are
         in the Administrators group on the server. You will need to create folders, copy files,
         and create virtual directories on the server.

5.2     Web Form application run-time issues

5.2.1    Failure to launch the Web application in Internet Explorer (IE)
                If an error like “Could not load <Global.app>” is generated when accessing
                the application in IE, it could be caused by ASP.NET and IIS configuration
                issues. Possible solutions are:
                o    Install the .NET Framework 2.0 on the Web server, if it is not already
                o    Register ASP.NET 2.0 with IIS (run aspnet_regiis.exe –I from the .NET
                     Framework 2.0 installed folder).
                o    Make sure that ASP.NET 2.0 is the version set for the Web application.
                o    Restart IIS.

<01/11/2007 >                                                                        Page 6 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                       Version:     <0.2>

             If the error in IE is “Exception from HRESULT: 0x8007007E”
             The most likely cause is that different versions of the PowerBuilder 11.0 .NET
             assemblies are installed in the environment.
                 o   Check whether different versions of the PowerBuilder 11.0 .NET
                     assemblies exist in folders or in the GAC (Global Assembly Cache).
                 o   If present, remove older versions and leave only the latest version of the
                If the error is “the page cannot be displayed” or “404 file not found”

                 o   Check the folders under \wwwroot\ to see if related folders and files
                     have been generated.

                 o   Check if you are using a TCP port number other than the default 80.
                If you fail to open the page from a remote client
                 o   Try pinging the server to make sure it is accessible.
                 o   Check if the firewall is on on the server that you are accessing. If yes,
                     turn it off and open the page again.

5.2.2   Internet Explorer Menu, Toolbar, and Address are invisible after opening the Web Forms
           Check the Web site Properties>Documents tab page to see if Enable Default
           Document is selected and if default.aspx is at the top of list. If default.aspx is not
           there, add it manually and move it to the top of the list.

5.2.3   Database connection failure
           Make sure that you have configured the database resources correctly. To
           configure database resources please refer to section 4.1 in this document.
           Make sure the database configuration files (*.ini) are selected in the .NET Web
           Form project before deployment.

5.2.4   Application is not functioning as expected
           If some part of the application is not functioning as expected, check whether
           there is any unsupported feature in the application by reviewing the
           Deployment.txt file. If unsupported features are present refactor them and
           redeploy the application.
           Check the errors and exceptions raised at runtime in the log file PBTrace.log. The
           file is in the <drivename>:\Inetpub\wwwroot\<application name>_root\log\

5.2.5   DataWindow printing failure
           Make sure that Ghostscript is installed on the Web server.
           See the section “Web Forms Print Manager” in the Deploying Applications and
           Components to .NET book for detailed information about installation and configuration.

<01/11/2007 >                                                                       Page 7 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                          Version:      <0.2>

5.2.6    Drop-down DataWindow (DDDW) cannot display multiple columns
            A DDDW displays only one column in a Web form by default to avoid performance
            issues. To show all columns in the DDDW, set PBDataWindowEnableDDDW to
            true on the Configuration page in the Project painter.

5.3     Windows Forms application runtime issues

5.3.1    RichTextControl is not displayed properly
            Make sure that the files required by the control are installed on the client
            computer running the .NET Windows Forms application. These files are listed in
            the chapter on deployment in Application Techniques.

5.3.2    Font display differences between standard PowerBuilder and .NET Windows Forms
            Microsoft does not support bitmap (screen) fonts such as MS Sans Serif for .NET
            applications. It supports only true-type and open-type fonts.
            If your application uses a font that is not a true-type font and you selected a font
            size that is not supported, in a standard PowerBuilder application the font
            displays in the nearest font size. In a .NET Windows Forms application, the font is
            enhanced so that an unsupported font size can be displayed correctly. However,
            the display is different from the display in the PowerBuilder development
            environment or a standard PowerBuilder application. You will need to modify your
            application to adapt to the difference.

5.3.3    OLE control/out-of-thread OLE features do not work
            Currently, out-of-thread OLE features only support Microsoft Office Word and
            Excel. Other types such as BMP, AVI, and WAV are not supported.
            OLE OCX controls are supported but with limitations. See the section
            “Unsupported features in PowerBuilder Windows Forms” in the PowerBuilder 11.0
            HTML Help.

5.4     .NET Smart Client deployment issues

5.4.1    File generation failure When creating a local folder structure.
                Check whether the current user has sufficient access rights to create a folder. When generating the application manifest file.
                Make sure that the .NET Framework 2.0 %SDK%\bin directory is in the PATH
                system environment variable.
                If a certificate file is specified in the project’s properties, make sure it is valid
                and exists in the correct folder. When generating a setup.exe file.
                Make sure that the setup.exe exists in the %PBNET_HOME%\PBIU\
                BootStrapper directory.

<01/11/2007 >                                                                            Page 8 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                        Version:      <0.2>

5.4.2   File transfer error   When the publish location is a Web server: http://testmachine/testapp/
                Make sure that the Web server and the PowerBuilder 11.0 development
                computer are in the same network domain.
                Make sure the current user has administrative privileges on the Web server or
                has write access to the \\WebServer\wwwroot$ folder. When the publish location is a file share: \\testmachine\testapp\
                Make sure that the target computer and publish computer are in the same
                Make sure the current user has write access to the target computer’s publish
                folder. When the publish location is an FTP site: ftp://testmachine/testapp/
                Make sure the FTP site can be accessed by the given user name and
                Make sure the user logged into the development computer has write access to
                the FTP site.

5.4.3   Client installation failures
                Failure to open the publish site
                    o   Make sure the server’s firewall is turned off if you are accessing the
                        publish site through HTTP.
                Failure to open setup.exe or download files
                    o   Make sure that Script Source Access is selected on the Directory page
                        in the Properties dialog box for the virtual directory of the publish site
                        in InetMgr.
                    o   Make sure the files exist in the server’s specified folder (for example,
                    o   Make sure the installation link is the same as the publish location or
                        pointing to the same location.
                    o   Check whether the current user has sufficient rights to access the
                        publish server.
                    o   Check whether there is enough space on the client computer.
                    o   Check whether the network connection to the publish server works

5.4.4   Update errors
                Check the update mode and make sure the appropriate update mode is
                Check the update location and make sure files exist in the update location and
                that it is accessible.

<01/11/2007 >                                                                         Page 9 of 10
PowerBuilder® 11.0 .NET Quick Reference Guide                      Version:       <0.2>

5.5     .NET Smart Client application runtime issues

5.5.1    Cannot launch the application
             Check that the correct version of the .NET framework is installed.
             Make sure the following DLLs are deployed to the end user’s computer. These
             files can be packaged in the PowerBuilder Runtime Packager.
             o   PowerBuilder DLLs:
             o   MSVC runtime DLLs:

5.5.2    Cannot connect to the database
         Check whether the required ODBC DSN has been created on the client computer (for
         ODBC connections). The DSN can be created by an MSI setup file.
         Check whether required PowerBuilder DLLs, such as pbodb110.dll, are selected as
         Win32 DLLs in the Project painter when you publish the project.
         Check whether required database configuration files, such as myapp.ini or
         pbodb110.ini, are added as resource files in the Project painter when you publish the
         Check whether other prerequisite components are installed correctly.

5.5.3    Unable to determine path to dbmlsync.exe
         Make sure that the MobiLink Synchronization component is selected when installing
         Adaptive Server Anywhere 9 or SQL Anywhere 10.

5.5.4    Trouble configuring MobiLink consolidated database or remote database.
         Refer to the section “Using MobiLink synchronization” in the chapter on intelligent
         deployment and update in the Deploying Applications and Components to .NET book
         in the HTML Help.

<01/11/2007 >                                                                       Page 10 of 10

To top