Getting Started-JetNet

Lesson 11. Enhancing the Screen

An additional client screen and its corresponding service component are provided in tutorial.lib. They use a grid format to display a list of distributors. In this lesson, you enhance the screen and service component so users can query the database for a specific distributor record through two different search criteria: either a distributor ID number or a partial or full name string. The transaction manager uses user input to generate automatically the appropriate SQL query statement. If a query field is empty, the transaction manager excludes its data from the SQL generation.

In this lesson you learn how to:

In this lesson, you open a wizard-built client screen and service component from the local tutorial library. You then save them to their appropriate libraries on your remote application server, and enhance the user interface by including query fields.

  1. If necessary, reactivate the application, invoke the editor, and open a middleware session.
  2. Choose ViewLibrary TOC.

    The Library TOC opens.

  3. If tutorial.lib is not among the list of open libraries:
  4. Select tutorial.lib from the list of open libraries and lesson10.clt from the list of library members. Choose Open.

    The lesson10.clt screen opens in the editor workspace.

    This screen is a master-only screen for the distributors table and uses a grid format. The grid contains three of the table's columns: distrib_id, distrib_name, and distrib_phone.

  5. Choose FileSave AsLibrary Member. The Save Screen dialog opens.
  6. Save the screen as dstslect.scr in client.lib on the application server.
  7. From the Library Table of Contents dialog, select lesson10.svr from the list of library members.

    The service component, lesson10.svr, opens in the editor workspace.

    This screen contains the same grid as the client screen.

  8. Choose FileSave AsLibrary Member and save lesson10.svr as dstslect.scr in server.lib on the application server.

Access table view properties

Since the client screen and service component were created using the screen wizard, the services that will be requested by the client screen were also generated. These values are properties of the client screen's table view. Select the screen's invisible table view widget and determine the names of its Service properties so that you can define those services in the JIF.

More About Table Views

A table view widget is automatically created on a repository screen when you import database objects. Table views store the following types of database information:

Panther's transaction manager uses the information stored in table views (and links which specify the join relationships between multiple table views) to determine what SQL statements should be generated for each transaction command.

The JetNet transaction model uses the service information to determine how to respond to service calls.

In addition, table views provide you with a quick entry point for modifying the default transaction manager behavior.

You can select the table view widget by using either the Widget List or the DB Interactions window in order to gain access to its properties.

  1. Bring focus to the dstslect.scr client screen and choose ViewWidget List.

    The Widget List opens and lists all the widgets on the current screen: the widget's name, field number or contents is in the middle column and its type in the right column.

More About the Widget List

You can use the Widget List as an alternative way to select widgets. All widgets on the current screen are listed in the Widget List, including invisible widgets, such as selection groups, synchronization groups and table views.

When you select an item from the list, the widget on the screen is also selected. The Properties window displays the properties common to the widgets that are currently selected, or of the screen if no widgets are selected.

You can select multiple contiguous widgets in the list with a click+drag or Shift+click; Ctrl+click to toggle membership in the selection set or to select non-contiguous items.

  1. Select distributors from the list of names. It is identified as the distributors table view widget.

    The table view properties are displayed in the Properties window (Table View displays in the Type field).

  2. Expand the Service heading in the Properties window.

    The Delete Service, Insert Service, Select Service, and Update Service properties use the dstslect prefix for the names of the services used by this screen.

More About Wizard-Generated Service Names

When the screen wizard generates screens for a three-tier model, you will recall that it also creates services that the screen will use. It uses the master table on the client screen to determine the name of the services. Since the client screen, in this case, uses the distributors table as its master table, the services, by default, would have distributor as the prefix. Service names must be unique within the JIF, and since services with this prefix were already defined for a screen you created earlier, different services needed to be specified.

The services used by a screen are specified in the Service properties associated with the client screen's root table view. The screen wizard automatically sets these property values based on input you provide on the screen wizard Service Definition dialog box.

Refer to Chapter 31, "Building a Transaction Manager Screen." of the Developer's Guide for more information on root table views and table view processing.

Update the JIF

When you add or change services in the JIF, Panther rereads the JIF, which in turn, causes the application server to readvertise services (assuming the server was configured to do so).

In the case of the tutorial, you did configure the standard server to advertise all services in the JIF. Therefore, when you add services to the JIF, they are made immediately available to your application.

  1. Invoke the JIF editor and connect to the middleware (refer to Lesson 8 for details on using the JIF editor).

    The services in jif.bin, located in the remote common.lib, are displayed in the View Services dialog box.

  2. Define the four services needed for the dstslect client screen: dstslect_d, dstslect_i, dstslect_s, and dstslect_u (refer to Lesson 8 for details on creating services). In each case, name the service component dstslect.
  3. Choose FileSave.
  4. Choose FileExit to close the JIF editor and return to the editor workspace.

Resize the screen

Increase the screen's vertical dimension so you can add other widgets to it.

  1. In the editor workspace, resize the dstslect.scr client screen in one of the following ways:

Move widgets

Make room for more widgets above the grid widget by moving the grid widget and push buttons down to the screen's lower portion.

  1. Choose EditSelect All and drag the widgets to the bottom of the screen, leaving space at the top for more widgets.

Open a repository entry

You want to populate the screen with widgets that are associated with a particular database table. You can access these widgets in the repository, just as the screen wizard does.

  1. If the repository is not open, choose FileOpenRepository, and select data.dic in the proltut directory.
  2. Choose FileOpenRepository Entry.

    The Open Repository Entry dialog opens and displays the contents of the data.dic repository.

  3. Select the distributors repository entry and choose OK.

    The distributors@[Repository] window opens.

Copy widgets

You can use widgets from the repository to serve as query fields on the dstslect.scr screen. When you create a copy of a repository widget, the copy has an inheritance link to its parent in the repository. You can use inheritance to propagate changes from the repository to application screens and service components, as shown in the next lesson.

In the following steps, you copy distrib_id and distrib_name from the repository to the client screen dstslect.scr. The copies inherit their property values from the repository.

  1. With focus on the distributors repository screen, Shift+click to select the Distrib_id label and its corresponding text widget (distrib_id), and the Distrib_name label and its corresponding text widget (distrib_name).

    Selecting multiple widgets creates a selection set, which is useful for defining common property values. The first widget you select is the dominant widget. You can Ctrl+click on another widget in the selection set to make it dominant.

More About Selecting More than One Widget

When more than one widget is selected, the first one you select is considered the dominant selection and is indicated by little solid black squares around its border (square brackets in character mode); all other widgets in the selection set are indicated with hollow boxes (curly braces ({}) in character mode). The position and size of the dominant widget determines how the other widgets in your selection set will align or resize when you use Edit menu or toolbar options.

There are a variety of ways to select multiple widgets:

  1. Drag the widgets from the repository screen distributors to the top of the screen dstslect.scr.

  2. (Optional) Bring focus to the distributors repository entry and choose FileClosedistributors. The repository window closes.
  3. Arrange the widgets so they are horizontally aligned at the top of the screen, as shown below. Use alignment options from the Edit menu or toolbar.

Name the widgets

It is good practice to name all data entry widgets, especially if you need to access them programmatically. Names of all widgets on a screen must be unique. Because the dstslect.scr screen already contains widgets named distrib_id and distrib_name, the copies from the repository are left unnamed. You need to assign different names to the copies via their Name property.

  1. Select the copied text widgets on the client screen dstslect.scr and set each one's Name property (under Identity) as follows:

Define the query fields

Use database properties to provide the transaction manager with information it needs: identify the query fields, define the data to retrieve, and ensure that query field data is not used to update the database.

  1. Select the distid_qbe and distname_qbe widgets.

  2. Under Database, select CHANGE DATA. Under CHANGE DATA, set the following property for both widgets:
  3. Under Database, select NEW DATA. Under NEW DATA, set the following property for both widgets:
  4. Under Database, select FETCH DATA. Under FETCH DATA, set these properties for both widgets:
  5. Select the distname_qbe widget.
  6. Under the Use In Where property, set the Operator property to %like%.

    The percent sign (%) sign is a wildcard matching any sequence of zero or more characters. This pattern matching operator tells Panther to search the database for all records that contain the string in the distname_qbe field.

Synchronize the service component

Because this is a three-tier model, the service component associated with the dstslect.scr client screen must include the new query-by-example widgets that you just copied and modified. Simply copy them from the client screen to the service component; the properties you defined are copied with the widgets. Users never see the service component, so you don't have to worry about how it looks.

  1. Select text widgets distid_qbe and distname_qbe on client screen dstslect.scr.
  2. Drag the widgets to any area of the dstslect.scr service component.

  3. Save both the screen and the service component (press F6).

Query the database

You can try it out!

  1. Bring focus to the dstslect.scr client screen.
  2. Choose FileTest Mode or .
  3. Type Vid in the Distrib_name field.
  4. Choose .

    All distributors that have Vid in their name are listed in the grid.

  5. Choose .
  6. Type 6 in the Distrib_id field and choose .

    Panther looks for a record with an exact match—a distrib_id with a value of 6. The record corresponding to ID 6 is displayed in the grid.

  7. Now return to the editor.

What did you do?

You enhanced a screen so users can search for distributors by name or ID. You did this by performing these actions:

What did you learn?

You learned: