The application you design for use as a plug-in can be much the same as other PowerBuilder applications you develop, but there are some restrictions and considerations to keep in mind in the following areas:
Window management
Objects
Scripts and variables
Data access
External files
Initial child window Your initial window needs to be a child window that lives in the browser frame.
You can:
Include a title bar on the child window (but you should not use a control menu, maximize box, or minimize box on that window)
Open pop-up and response windows from the child window (but not main or MDI windows)
You cannot:
Have a menu for the child window
Open another child window from the initial window
Closing windows When the client browses to another Web page, the child window on the current Web page is closed, but other windows remain open unless your application closes them. You must close them in the child window’s Close or CloseQuery events.
Do not try to stop the child window from being closed in the CloseQuery event by setting a return value. You cannot prevent the browser from changing to another page and removing the window from view. If the user returns to the page, another instance of your application is started.
Objects in your PBDs Your plug-in application has access to all objects in the PBDs. This includes functions, structures, and user objects.
System objects Your plug-in application has access to system objects that PowerBuilder instantiates, such as the SQLCA Transaction object and the Message object.
Application object You can use the optional APPLICATION attribute of the Embed element to specify the name of your PBD’s Application object. This gives your plug-in application access to the Application object’s Open and Close events.
If you do not specify the APPLICATION attribute:
Your plug-in application does not have access to the Application object, and thus events like SystemError and Idle are not available. You cannot treat variables and functions defined in an Application object as global.
Any scripts in the Application object are used only during testing within PowerBuilder. You cannot do any application setup in the Application object’s scripts.
For information about specifying the APPLICATION attribute, see “Attributes of the Embed element”.
Global variables If you use the APPLICATION attribute of the Embed element to specify your PBD’s Application object, your plug-in application has access to global variables and global functions used in the application.
If you do not specify the APPLICATION attribute, the plug-in application cannot use global variables. You must define all variables as instance, shared, or local.
For information about specifying the APPLICATION attribute, see “Attributes of the Embed element”.
Referencing the initial window You cannot reference the initial child window by name in your scripts, because PowerBuilder does not create a variable to hold the instance of it. (By contrast, when you instantiate a window yourself by coding the Open function, you always place the instance in a variable that you can then reference.)
Thus, the following code produces an error at runtime (because the window variable w_mychild does not exist):
// This code produces a runtime error: w_mychild.title = "The initial window"
But you can code:
// In the child window itself: this.title = "The initial window" // or title = "The initial window" // In controls of the child window: parent.title = "The initial window"
Scripts for application setup All application setup must be done in the child window, including connecting to the DBMS. The first scriptable events to occur are the constructors for the controls in the window. Then the Open event for the window occurs.
The Activate event does not occur for a child window; do not put application setup code there.
If your application accesses a DBMS, each client must have a connection to the data source. The connection must be defined on the client’s machine, not the server. The data source might be a local or a network DBMS.
For information about how to connect to a DBMS from the client machine, see Connecting to Your Database.
The constructor events for controls occur before the Open event of the window. If you connect to the DBMS in the window’s Open event, the constructor events cannot get data. You can get data for controls in the window’s Open event, or you can post events from the constructor events or the window’s Open event.
Paths you specify for files must be valid on the client workstation.
If your application uses images as external files, the images must be available at the path specified in the PowerBuilder object. Instead of using external files, you can build image resources into PBDs, as described in “Building the dynamic libraries”.
If your application reads or writes local files, the path for those files must be valid on each client’s machine.
If a path refers to a network drive by mapped drive letter, all clients must use the same drive letter that the application uses. As an alternative, specify the server name in the path instead.
For example, both of these paths are valid when o: is mapped to \\marketing\drive, but the second path, which uses a server name, is more likely to remain valid.
O:\pbapps\connect.bmp \\marketing\drive\pbapps\connect.bmp
