Lesson 10: Exception Handling

Add a new sheet window to the existing application

In this lesson you add a third sheet window to the main tutorial application. You create and call a function to perform a routine operation (calculate a percentage) on values returned from embedded SQL commands and a value selected by the application user from a drop-down list box control.

The prototype for the function you create throws user-defined exceptions. You call the function in a TRY-CATCH block inside the Clicked event on a command button control. The CATCH clauses in the Clicked event catch user-defined exceptions thrown by the new function as well as a system exception thrown up the application call stack.

You use the new sheet window to calculate the percentage of customers that resides in a selected state. The controls you add to the new sheet window are:

Two static text boxes that you change programmatically to display read-only results

A command button to call a function that calculates percentages

A drop-down list box for a list of states where customers reside

A text box that displays the percentage of customers residing in the state that application users select from the drop-down list box

To add a sheet window to the existing application, you must:

Create the sheet window

You inherit the sheet window from the w_pbtutor_basesheet window. This is the base class for sheet windows that you generated with the Template Application wizard. You do not use the w_master_detail_ancestor extension layer window, since the modifications you made to it are not useful in the new sheet window.

Select File>Inherit from the PowerBuilder menu.

Make sure the Objects of Type box displays Windows.

Select w_pbtutor_basesheet from the available windows in the pbtutor.pbl library and click OK.

Make sure the Layout view displays in the Window painter.

Select Insert>Control>StaticText and click near the top left corner of the Layout view.

In the Properties view, highlight the default text in the Text text box and type the following:

1. Select or type a state code in drop-down list:

Lengthen the control width and the width of the sheet window to display the entire text and allow room for a drop-down list control at the top right of the window.

A length of 2250 should be sufficient for the sheet window width. You can set this on the Other tab of the Properties view for the window, or you can drag the window edge in the Layout view to make room for an additional control.

Right-click the static text control in the Layout view and click Duplicate from the pop-up menu.

In the Properties view, highlight the default text in the Text text box of the new static text control and type the following:

2. Click Percentage button

Select Insert>Control>DropDownListBox and click to the right of the static text boxes near the top right corner of the Layout view.

Shown is a grid of dots in Layout view. At top left is the text for the two static ext boxes you entered in the preceding steps of this lesson. At top right is the drop down list box you entered in this step.

In the Properties view for the drop-down list box, type ddlb_state for the control name.

Select the AllowEdit and the VScrollBar check boxes.

Click the command button in the painter bar and click below the two static text boxes.

In the Properties view, type cb_percent for the button name and type Percentage for the button text.

Select Insert>Control>SingleLineEdit and click below the command button in the Layout view.

In the Properties view, type sle_result for the control name and type the following for the control text:

Text box for percent of customers in the selected state

Lengthen the control width to display the entire text.

Shown is a grid of dots in Layout view. At top left is the text for the two static text boxes you entered earlier in the lesson, and at top right is the drop down list box. At center left is a rectangle labeled Percentage. Across the bottom is a rectangle with the text: Text box for percent of customers in the selected state.

Make sure no control is selected and the sheet window properties are displayed in the Properties view.

Type Customer Location for the Tag property.

The text you typed will be visible in the sheet window title at runtime. Code in the basesheet ue_postopen event assigns the Tag text to the sheet window title.

Select File>Save from the PowerBuilder menu.

Select pbtutor.pbl for the application library, type w_cust_pct for the new sheet window name, and click OK.

This saves the new sheet window with all its controls to the main tutorial library.

Provide access to the sheet window from the main application frame

You must register the new sheet with the sheet manager.

Double-click w_pbtutor_frame in the System Tree.

If the ue_postopen event is not visible in the Script view, click the Event List tab and double-click ue_postopen.

The ue_postopen event script displays in the Script view.

Type the following line in the list of registered sheet windows:

ls_sheets[3] = "w_cust_pct"

Type the following line below the list of sheet window titles to display:

ls_display[3] = "Customer Location"

Shown is the u e _ post open event script in the Script view. At the top is a list of three registered sheet windows including the entry l s _ sheets [ 3 ] equals " w _ cust _ p c t " and next is a list of sheet window titles to be displayed, including the entry s _ display [ 3 ] = "Customer Location".

Better coding practice You could reduce the six lines of code for defining sheet windows and their display names by replacing them with the following lines of code:

// Define sheet windows and their display names

string ls_sheets[]={"w_customers", "w_products",	&
		"w_cust_pct"}

string ls_display[]={"Maintain Customers", &
		"Maintain Products", "Customer Location" }

Select File>Save and close the w_pbtutor_frame window.

The next time you run the pbtutor application, you should be able to open the new sheet window from the File menu of the main frame window. Although you can now run the new sheet window from the development environment, you must make sure that you can run it from a compiled application as well.

For this purpose, you reference the sheet windows as window objects in the sheet manager of_registersheet script. The reference is necessary for the compiler to know that this object is used in the application so that it will include it in the executable.

You create a compiled application in Lesson 11, “Preparing the Application for Deployment.”

Double-click n_pbtutor_sheetmanager in the System Tree.

Click the Function List tab and double-click of_registersheet.

The script for the of_registersheet function displays in the Script view.

Type the following after the lines declaring sheet window variables for the w_customers and w_products windows:

w_cust_pct  lw_sheet3

Shown is the script for the of _ register sheet function in the Script view. It includes lines declaring sheet window variables for w _ customer and w _ products, and then the line s _ cust _ p c t l w _ sheet 3.

Save and close the n_pbtutor_sheetmanager user object.