Web Development

Application processing in Panther occurs by executing a series of events. Panther supports several event hooks that are specific to Web applications. This chapter describes the following event types:

• Web Event Hooks

• Web Application Events

• Screen Entry Context Flag—K_WEBPOST

• Web Entry Context Flags

Web Event Hooks

Panther has four Web application event hooks where you can attach JPL procedures. Four events are defined: web_startup, web_enter, web_exit, and web_shutdown. When one of these events occurs, Panther searches for a JPL procedure that has the corresponding event name.

web_startup

Called when the Panther Web application starts up. This event hook performs start up processing or specifies application-wide settings. You can use a web_startup procedure to create global variables, to establish database connections for two-tier applications, or to establish request broker connections for three-tier applications.

proc web_startup //2-tier
DBMS ENGINE jdb
DBMS DECLARE jdb_conn1 CONNECTION FOR DATABASE "videobiz"
return

proc web_startup //3-tier
client_init 
return

web_enter

Called after the Panther screen has been opened and the data from the browser has been mapped into the screen. This hook can be used to validate the contents of screens and to verify data before acting upon a request.

When a screen is submitted, values are written to Panther variables which can be used in web_enter processing. These variables tell why the screen was submitted, the object ID of the widget involved, and the occurrence number, if applicable. For more information, refer to "Web Entry Context Flags."

The following web_enter procedure from the Panther Gallery specifies a different graphic and hyperlink if the documents are displayed using frames.

proc web_enter
if frames=1
{
// If using frames, use jlogomin.gif.

    gallery->active_pixmap = "jlogomin.gif"
    gallery->default_link = ""
}
else
{
// If frames unavailable, use Gallicon.gif and set hyperlink.

    gallery->active_pixmap = "Gallicon.gif"
    gallery->default_link = "main"
}
return

web_exit

Called just before the HTML generation. This hook offers a last chance to change a screen before

Panther generates the HTML for presentation in the browser. Screen exit processing occurs after the HTML is generated; therefore, screen exit processing cannot affect the generated HTML.

The following web_exit procedure unhides the grid containing the address information if the JPL global variable show_details is set to PV_YES. This variable is created during screen entry and is set to PV_YES on POST events.

proc screen_entry (data, flags)
if !(flags & K_WEBPOST)

// If this is a GET, create variable
// and set to No
{
    global show_details = PV_NO
}
else  // If this is a POST, create variable and set to Yes
{
    global show_details = PV_YES
}
return

proc web_exit ()
if show_details = PV_YES // If show_details set to Yes for
                         // a POST, grid is unhidden
{
    address_grid->hidden = PV_NO
}
else // hide grid
{
     address_grid->hidden = PV_YES
}
return

web_shutdown

Called when a Panther Web application shuts down. Use this hook to close the database and request broker connections that are created in web_startup. You can also use it to perform any other necessary clean up.

Note that this procedure is only called if the application shuts down cleanly, such as with the monitor utility.

proc web_shutdown //2-tier
DBMS CLOSE CONNECTION jdb_conn1
return

proc web_shutdown //3-tier
client_exit
return

When a Web application event occurs, Panther searches for a JPL procedure with the event name and, if found, executes it.

Panther executes the first JPL procedure that it finds with this name, using this search algorithm:

1. If the call is issued from a JPL module, a named procedure in that module.
2. A named procedure in the current screen's module.
3. A named procedure in a public module. If the procedure name exists in more than one public module, Panther uses the procedure in the most recently loaded module.
4. A memory-resident module.
5. A named procedure in the JPL module named in the application variable, SMINITJPL. Because Panther automatically publics this module as part of its initialization, the default processing for each of the Web event hooks can be defined here.

Given this search order, a Web application can have multiple JPL procedures for the same event. For example, you can define the web_enter procedure and issue the public command on it at application startup; this procedure performs default processing for all screens. However, a specific screen can have its own web_enter procedure; when this screen is open, Panther finds its web_enter procedure first and executes it. The default web_enter procedure is executed when subsequent screens open that lack their own web_enter procedure.

Web Application Events

After Panther is installed and configured on your system, each Web application server performs the following steps when it is initialized:

1. Loads any JPL modules specified by SMINITJPL in smvars.bin or in the Web application's initialization file.
2. Calls the JPL procedure web_startup.

If the Web application server receives a request to terminate from the monitor utility, it performs the following steps:

1. Executes the JPL procedure web_shutdown.
2. Performs normal Panther shutdown processing and exits.

For each screen request or submission, Panther performs these steps:

1. Restores any open bundles (created by the send command) and global JPL variables that come back from the browser or have been cached on the server.
2. Opens the screen by calling sm_r_form. This causes the following screen entry processing:

   • Executes the unnamed JPL procedure.

   • Initializes the transaction manager which issues a START command.

   • Executes the default screen function.

   • Executes the screen entry function.

   • Merges with the LDB.

   • Executes the AUTO control string.

3. On a POST, restores the contents of fields as specified by data from the browser and from the server cache.
4. On a GET, processes variable assignments from the QUERY_STRING.
5. If a button was pushed, calls sm_gofield for that button.
6. Calls the JPL procedure web_enter.
7. If a button was pushed, calls sm_ungetkey for the NL logical key.
8. Invokes the Panther executive to perform normal processing until key input is required. This includes:

   • Execution of the default field function.

   • Execution of the field entry function for the first field.

   • Processing the NL key from Step 7.

   • Execution of the application processing defined in the screen.

     Error messages, instead of requiring a user response, are processed by automatically executing the processing assigned to the default push button.

9. Calls the JPL procedure web_exit.
10. Generates HTML for the screen and sends that data to the browser.
11. Closes all open windows, which executes normal screen exit processing. Note that this cannot affect the already generated HTML.
12. Deletes appropriately marked JPL variables.
13. If a C web event hook finction was installed by calling sm_web_set_onevent, this function is called.

---

Controlling Entry Processing

K_WEBPOST is a context bit flag that is set to true when Panther opens a screen because of a browser's POST command. When you press a push button on a browser screen, the data is sent back to the HTTP server with the POST method and the K_WEBPOST flag is set. If part of that screen's processing is to open another screen on the Panther server, K_WEBPOST flag is not set for the second screen. Only after you post the second screen back to the server does the K_WEBPOST flag get set.

For example, your application screen selects data from the database on screen entry and displays that data to the user so that the user can make a selection. At this point, Panther performs these actions:

1. Receives the URL request for the screen (using the GET method).
2. Opens the screen.
3. Executes screen entry processing which selects the data.
4. Generates HTML for the screen.
5. Sends the data to the browser making the request.

The user then makes a selection and submits the screen back to the server where Panther performs these actions:

1. Receives the screen data (using the POST method).
2. Reopens the screen.
3. Reexecutes screen entry processing which reselects the data, wiping out the user's selection.

You can test the K_WEBPOST flag so that the screen entry procedure selects data only when a user requests the screen, not when the user submits the screen back to the server on a POST. For example:

proc scr_entry(scr_name, flags)
if !(flags & K_WEBPOST)
{
	DBMS QUERY SELECT title_id, name, pricecat FROM titles
}
return

In the Panther Gallery, HTTP Request Method illustrates a screen using K_WEBPOST. The Panther Gallery is accessible from the Web application server:

http://server-name/cgi-bin/jwsamp/main

An option menu widget can have its Drop Down Source property set to External Screen so that it gets its data from a database. When a Panther screen has an option menu thus set, its screen entry event is processed twice—when the screen initially opens, and again after it returns from populating the option menu. When the Panther screen opens on a GET and then reopens on a POST, the additional screen entry event that is triggered by the option menu occurs on both the GET and POST events.

You can control screen entry processing so that it occurs only on the desired event:

• Set the application variable EXPHIDE_OPTION to OFF_EXPHIDE so that screen entry events only occur when the screen is explicitly opened.

• Test the K_EXPOSE flag. This flag is set to true only if the screen is exposed after another screen is closed. This is what occurs with the option menu initialization.

The following JPL procedure tests the K_EXPOSE and K_WEBPOST so that screen entry processing occurs only on GET and POST events; this processing is avoided when screen entry occurs after option menu initialization:

proc scr_entry (name, flags)
if ( !(flags & K_WEBPOST) && !(flags & K_EXPOSE) )
{
// Processing occurs only on a GET event.
}
if ( (flags & K_WEBPOST) && !(flags & K_EXPOSE) )
{
// Processing occurs only on a POST event.
}

When a screen is submitted, values are written to the following variables for use in web_enter procedures:

@web_action

This variable tells why the screen was submitted. The values are:

PV_SUBMIT

General submit (using JavaScript submit or by pressing Enter in a text field).

PV_BUTTON_PRESS

Push button was pressed. PV_INSERT, PV_APPEND, PV_DELETE,

PV_SCROLL_UP, PV_SCROLL_DOWN, PV_SCROLL_TOP, PV_SCROLL_BOTTOM

The corresponding grid push button was pressed.

@web_action_widget

For PV_BUTTON_PRESS, this will contain the object ID of the button that was pressed.

For the grid push buttons, this will contain the object ID of the grid being operated on.

Otherwise, this will contain PR_NULL_OBJID.

@web_action_occurrence

For PV_BUTTON_PRESS, this will contain the occurrence number of the button pressed.

For PV_INSERT, PV_APPEND and PV_DELETE, this will contain the occurrence being operated upon.

For PV_SCROLL_UP, PV_SCROLL_DOWN, PV_SCROLL_TOP and PV_SCROLL_BOTTOM, this will contain the occurrence number placed in the first onscreen element of the grid being scrolled.