Basic Example

This is an example of how to use WebSphere Host Publisher to connect, collect data, and disconnect from a University site.  Using Host Access, we will connect to the University of Michigan's Library database.  From this database we can search for books by authors, titles, subjects, and so on.  We will search for books by the author's name.  After we obtain a list of books, we will disconnect from the database.  This example will be used as a basis for the following examples:  Looping, Chaining, and Conditional.

Creating and Understanding the Connection Macro

When you define a Host Integration Object, you must define a Connect Macro, and additionally, a Disconnect Macro.  You can configure a default connection pool that does not use pooling and has the same name you chose for your Integration Object.  Alternatively, you can create and use a new pool, or use an existing connection pool.  You have three choices:

Configure a default connection pool
Select this option if you want this Integration Object to use a default connection (single connection).  If you use a single connection, the connection must be established each time the Integration Object runs.  You can use this as a quick way to develop your application.  When you are ready to support multiple users, you can modify the connection information to include pooling and to have additional user IDs.

Create a new pool
Select this option if you want this Integration Object to use one of several user accounts.  Ensure that each of the IDs you specify behave the same way as the ID you use to record the macros; otherwise your Connect Macro might not run correctly when other user IDs from the pool are used.

You can use a pool to keep one or more connections initialized, thereby reducing the response time between when a client with a browser requests information and when the information displays on the page.  Use the Connection Pool Configuration panel to specify how many connections you want, as well as configure other pool properties.

Share an existing pool
Select this option to specify which existing pool to use.  When you select Share an existing pool, Host Access uses the host server information associated with that pool.

When you create a connection pool, the Connect and Disconnect Macros are associated with that pool.  When you create an Integration Object, you use a pool created as part of that Object.  Although it may look as if you are recording the Connect and Disconnect macros as part of the object, they are really kept separate.  When you record subsequent Integration Objects, you can create a new connection that requires you to record Connect/Disconnect Macros, or you can use an existing connection pool that associates the Object with existing Connect and Disconnect Macros.

Creating the Connect Macro

When the Host Access application is initially brought up, the Welcome Screen appears.  Click Next.

The Integration Object screen appears.  Select Create a new Integration Object, then click Next.

The Host Configuration screen appears.  You now have the option to Configure a default connection pool, Create a new pool, or Share an existing connection pool.  We will Configure a default connection pool.  Fill in the Server name and Terminal type of the University of Michigan's host in the Host Server Information box.  After you complete the Host Configuration page, click Next.

You are ready to begin recording the Connect Macro.  Click Next.

The Define Screen appears.  You must define the first screen in each macro.  The screen name defaults to Screen1, Screen2, and so forth.  To make the macro easier to read, change the name to something meaningful.

In this example, we rename the screen to Database Selection Menu Screen which makes the screen easier to identify on the left-hand side.  Then click Next.

The Text Area Recognition appears.  We will recognize this logon screen by the Database Selection Menu unique text.  Use the cursor to draw a box around the unique text, indicate that we will recognize the text At the specified position, and click Next.

We will navigate to the point where we are connected to the system.  Enter the database selection "MCAT" in capital letters then press the Enter key.

The Unrecognized Screen appears.  Click Yes to create a definition for this screen.

The Define Screen appears.  To help identify the screens on the left-hand side, rename the screen from Screen2 to Introduction Screen, then click Next.

The Text Area Recognition appears.  Draw a box around the specified text on the terminal.  In this case, it is the word Introduction in the upper right-hand corner of the screen.  Select At the specified position and click Next.

You have now completed the Connect Macro.  The wizard states that when you are ready to capture data, click Next.  We are going to begin recording our Data Macro and gather data.  Click Next.

Creating the Data Macro

The Data Macro is where the system starts recording the steps you take to obtain the desired data.

The Gather Data Screen appears.  In this example, we will extract the names of books by a particular author.  By selecting to use a variable for the author, you can fill in different names during invocations of the Data Macro.  Type a=, then click Insert Input Variable.  (You may use the Menu item pull downs, or use the Insert Input Variable item on the tool bar.)

The Insert Input Variable box appears.  Type an input variable name, and provide a value for the variable, which will be used only to record the interaction with this system.  The value itself will not be remembered.

In this example, the variable will be author.  For recording purposes, we fill in a temporary value for the author.  Since this value is variable, the value is not stored in the Integration Object.  It is merely used to continue recording.  After typing this information, click OK.

Note that the value used for the variable is inserted in the command line.  Press Enter to continue recording this data.

The Unrecognized Screen appears.  Create a definition for this screen by selecting Yes.

We will rename this screen from DataScreen1 to Search Results Screen.  Then, click Next.

The Text Area Recognition appears.  Draw a box around the words Search Results and select At the specified position, then click Next.

The Gather Data Screen appears.  You are now ready to capture data associated with this page.  Click Next.

The Select Data page appears.  Select Select data on the terminal and draw a box around the data you want to capture.  When you finish, click Next.

The Data Format page appears.  We can choose to display the information in the selected area as text, or provide to the user in a table format.   In this example, the data will appear as a table.  Select Extract data as a table, then click Next.

The Extract Data page appears.  Type a name for this extraction, then click Next.

The Select Column Names page appears.  You can either use values on the screen as table headers by selecting text on the screen, or use default values by selecting Next.  You can change these names when you use the Studio.  Therefore, let the table header names default and click Next.

The Data Table appears.  Select the column name and provide an identifiable value.  In this example, the header was allowed to default column0, which we changed to book_titles.  After values are provided for all of the column headers, click Next.

The Finish Data Extraction page appears.  Select Finish capturing data, then click Next.

The Finish Data Macro screen appears.  Navigate back to the Database Selection Menu Screen by typing STA to disconnect from the session.

The Unrecognized Screen appears.  Click Yes to create a definition for this screen.

The Define Screen appears.  Rename the screen from DataScreen2 to Database Selection Menu Screen.  Click Next.

The Text Area Recognition appears.  Draw a box around the words Database Selection Menu, then click Next.

The Finish Data Macro screen appears.  You are now ready to begin recording the Disconnect Macro.  Click Next.

Creating the Disconnect Macro

The Disconnect Your Session screen appears.  Disconnect from the session by typing "exit".  Look at the left-hand side.  The key strokes you entered to disconnect from the session are recorded in the Disconnect Macro.  Since you are disconnected from the system, click Next.

The Save Integration Object screen appears.  Click Next to save this Integration Object (or use the File->Save menu).

You are asked to name this Integration object.  Enter the name (leaving off the file extension) and click Save.

The Integration Object is being generated.  When complete, click OK.  You have now created a Connect, Data, and Disconnect Macro.  You are finished!  You are ready to use the Host Publisher Studio to build an application to deploy to Host Publisher servers.  For details on how to build the Web Application go to  Host Publisher Studio: Basic Example .

In this example, Pooling would not work because the Macros do not start and end at the same place.  Therefore, if you were to use additional IDs, your Macros might not run correctly.  To fix this, you must start and end all of your Macros in the same place, so that each of your IDs will behave in the same way that the ID you recorded the macros with behaved.