PowerBuilder Native Interface Programmers Guide and Reference Appeon PowerBuilder® 2019 R2 FOR WINDOWS DOCUMENT ID: DC37794-01-1900-01 LAST REVISED: March 24, 2020 Copyright © 2019 Appeon. All rights reserved. This publication pertains to Appeon software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Appeon Inc. Appeon and other Appeon products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Appeon Inc. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP and SAP affiliate company. Java and all Java-based marks are trademarks or registered trademarks of Oracle and/or its affiliates in the U.S. and other countries. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. All other company and product names mentioned may be trademarks of the respective companies with which they are associated. Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies. Appeon Inc., 1/F, Shell Industrial Building, 12 Lee Chung Street, Chai Wan District, Hong Kong Contents I Programmers Guide ................................................................................................ 1 1 Introduction to PBNI ....................................................................................... 2 1.1 About PBNI ........................................................................................... 2 1.1.1 Understanding PowerBuilder extensions .................................... 2 1.1.2 Embedding the PBVM in a C++ application ............................... 4 1.2 The elements of PBNI .......................................................................... 4 1.3 The PBNI SDK ..................................................................................... 6 1.4 Comparing PBNI and JNI ..................................................................... 7 2 Building PowerBuilder Extensions .................................................................. 8 2.1 Nonvisual extension example ............................................................... 8 2.1.1 Building the pbadd PowerBuilder extension ............................... 8 2.1.2 Using the extension in PowerBuilder ........................................ 11 2.2 Creating a PowerBuilder extension .................................................... 12 2.2.1 Step 1: Decide on a feature to implement ................................ 13 2.2.2 Step 2: Define the classes and functions in the extension ........ 13 2.2.3 Step 3: Declare native classes and global functions ................ 15 2.2.4 Step 4: Implement native classes and global functions ............ 16 2.2.5 Step 5: Export methods to create class instances .................... 17 2.2.6 Step 6: Build a PBX ................................................................. 18 2.3 Adding an extension to a PowerBuilder target ................................... 18 2.4 Using the extension ............................................................................ 19 2.5 Creating and using a visual extension ............................................... 20 2.5.1 Step 1: Decide on a feature to implement ................................ 20 2.5.2 Step 2: Define the classes and functions in the extension ........ 20 2.5.3 Step 3: Declare visual classes and global functions ................. 21 2.5.4 Step 4: Implement native classes ............................................ 21 2.5.5 Step 5: Export methods to create class instances .................... 21 2.5.6 Step 6: Build and use a PBX ................................................... 21 2.5.7 Step 7: Use the visual extension in an application ................... 21 2.6 Creating visual class instances .......................................................... 22 2.7 Event processing in visual extensions ................................................ 24 2.7.1 Using an event name with return type and arguments ............. 24 2.7.2 Using an event name with a PowerBuilder event ID ................ 26 2.7.3 Processing events sent to the parent of the window ................ 26 2.8 Calling PowerScript from an extension .............................................. 28 2.8.1 Example: Calling PowerBuilder functions ................................. 30 2.9 Exception handling and debugging .................................................... 30 3 Creating Marshaler Extensions ..................................................................... 32 3.1 About marshaler extensions ............................................................... 32 3.2 Developing the PowerBuilder extension ............................................. 32 3.2.1 Step 1: Describe the extension ................................................ 33 3.2.2 Step 2: Implement the creator class ......................................... 34 3.2.3 Step 3: Implement the marshaler class .................................... 36 3.3 Generating proxies for Java classes .................................................. 37 3.4 Calling the Java class from PowerBuilder .......................................... 38 4 Exchanging Data with PowerBuilder ............................................................ 39 4.1 About exchanging data with PowerBuilder ......................................... 39 4.2 Passing values between extensions and the PBVM .......................... 39 4.2.1 PBCallInfo structure .................................................................. 39 4.2.2 IPB_Arguments interface .......................................................... 39 4.2.3 IPB_Value interface .................................................................. 40 4.3 Using the IPB_Session interface ........................................................ 41 4.4 Saving data from IPB_Value to a local variable ................................. 43 4.5 Using variables throughout a session ................................................ 45 4.6 Handling enumerated types ................................................................ 45 5 Calling PowerBuilder from C++ .................................................................... 47 5.1 About calling PowerScript from C++ applications ............................... 47 5.2 Calling PowerBuilder objects from C++ .............................................. 47 5.2.1 Creating a PowerBuilder object to be called from C++ ............. 48 5.2.2 Getting the signature of a function ........................................... 48 5.2.3 Creating the C++ application .................................................... 49 5.2.3.1 Load the PowerBuilder VM ............................................ 50 5.2.3.2 Call PB_GetVM to get a pointer to the IPB_VM interface ...................................................................................... 50 5.2.3.3 Create an IPB_Session object within IPB_VM ............... 50 5.2.3.4 Create an instance of the PowerBuilder object .............. 50 5.2.3.5 Initialize the PBCallInfo structure ................................... 51 5.2.3.6 Call the PowerBuilder function ....................................... 51 5.2.3.7 Write cleanup code ........................................................ 52 5.2.4 Running the C++ application .................................................... 52 5.3 Accessing result sets .......................................................................... 52 5.4 Processing PowerBuilder messages in C++ ...................................... 52 5.4.1 Examples .................................................................................. 53 5.5 More PBNI possibilities ...................................................................... 56 II Reference ............................................................................................................. 58 6 PBNI Types and Return Values ................................................................... 59 6.1 PowerBuilder to PBNI datatype mappings ......................................... 59 6.2 Types for access to PowerBuilder data .............................................. 59 6.3 PBNI enumerated types ..................................................................... 60 6.4 Error return values .............................................................................. 61 7 PBNI Interfaces, Structures, and Methods ................................................... 63 7.1 Header file contents ........................................................................... 63 7.2 Class and interface summary ............................................................. 63 7.3 IPB_Arguments interface .................................................................... 66 7.3.1 GetAt ......................................................................................... 66 7.3.2 GetCount .................................................................................