Upgrade Guide


Chapter 1 . Upgrading to Panther from JAM 7

This chapter lists features that are new and changed since JAM 7 for customers upgrading to Panther.

Additional upgrade information is available in the following chapters:

A major development change is that application files are now stored in libraries. Refer to "Libraries, not Files" for more information about this feature.


Installation

Start-up License

A start-up license is included in all Panther products. This temporary license allows you to start using Panther immediately. The license expires in 45 days, during which time you should have contacted the Prolifics License Desk to receive your permanent license, as arranged by your salesperson. The start-up license does not preclude or eliminate the need to obtain a permanent license.

When a temporary license is in use, a warning message is issued when you start the Panther editor. This warning is issued once a week until the last week, at which point it is issued daily.


Program Startup

By default, Java is initialized on program startup. You can change this initialization using the new behavior variable JAVA_USE.

Windows clients having an old version of the Java DLLs display an error message, "Java Not Supported". To update the Java DLLs, run the executable in %SMBASE%\jvm.


Editor

Menu Changes

File Menu

The New, Open and Save options have the following new options:

The Import Database Objects option is now on the Tools menu.

Edit Menu

Create Menu

View Menu

Options Menu

The Options menu is now a subset of the Tools menu and includes the following new options:

Tools Menu

This new menu bar item contains the Import Database Objects that was located on the File menu in previous releases, and gives editor access to the styles editor, menu bar editor, and JIF editor (in JetNet and Oracle Tuxedo). There are also the following new options in Panther:

Other Editor Changes

Other editor changes are:

Properties

For descriptions of new properties and information about changes in the Properties window, refer to "API Changes."

Library Member Access

Access to library members is provided by the Select Library Member dialog box. This dialog is available from the Properties window when properties requiring filenames are selected, and wherever else access to libraries is required. Both local and remote libraries can be accessed.

JPL Modules

JPL modules can be created in the editor. Access to the JPL window is provided from the File menu. JPL can be read into the window from a library or from a file on disk. The JPL can be saved to a library or to an external text file on disk. The JPL is automatically compiled when it is saved to a library, eliminating the need to do any file/library manipulation outside of the editor.

Non-modal Text Windows

The JPL Program Text window, JavaScript window, and VBScript window are no longer modal when writing screen- or report-level JPL procedures or JavaScript/ VBScript functions. This allows you to edit multiple files as well as move freely between script files and the editor workspace. The buttons have also changed for these windows.

Date/time Formats for Year 2000 Compliance

Date/time formats have two new Format Type property specifications in the Properties window for assigning date/time formats that display a four-digit year: MON/DATE/YR4 HR:MIN2 and MON/DATE/YR4. These are associated with the DEFAULT3 and DEFAULT4 mnemonics, respectively. In addition, DEFAULT3 is set as the default type in the Properties window.

Alternatively, you can use the behavior variable, DA_CENTBREAK, to set the behavior for applications using two-digit years. The default value of DA_CENTBREAK is 50. Therefore, if the year setting is equal to or greater than 50, the year is processed as 19xx; if the year is less than 50, the year is processed as 20xx. You can change the setting of DA_CENTBREAK by setting its value in the smvars file or at runtime by using sm_option.

Name Extensions

Screen names no longer have a default value is set for the application variable SMFEXTENSION. If you do not explicitly set this variable in a setup file or the environment, Panther no longer adds an extension to names during file searches; and all filenames must be fully qualified; for example, supplied a screen name of myscreen, Panther searches only for myscreen and not myscreen.ext also.

The recommended file extension for binary screen files is .scr. For binary report files, the recommended extension is .rpt. The file extension for temporary file names has been changed from .jam to .pro.

Editor Toolbars

A new menu option, OptionsConfigure Toolbars, determines which toolbars are available in the editor.

Screen Wizard

When constructing screens in the screen wizard, columns defined as being NOT NULL in the database are automatically selected to be part of the screen and are designated with the number symbol (#).

For JetNet and Oracle Tuxedo, refer to "Screen Wizard" for information about changes to the screen wizard in those executables.

Grids

There are new properties and functions pertaining to grids which control the amount of space between grid rows and which sort the data appearing in grids. For more information, refer to "New Properties for Grids."

Menu Bar Editor

The menu bar editor is now located on the Tools menu in the editor workspace.

For JetNet and Oracle Tuxedo, refer to "Menu Bar Editor" for information about changes to the menu bar editor in those executables.

Docking Toolbars

For Windows applications, toolbars can dock to the MDI frame or float within the MDI frame. A new menu pixmap property, Hot Pixmap, controls the appearance of the item when a mouse moves over an active toolbar item. In addition, pixmaps can be specified for the Inactive Pixmap property.

In previous releases, an Inactive Pixmap was a grayed version of the Active Pixmap in Windows applications. That capability is still there, but you can also specify a separate inactive pixmap. For each toolbar state that you want to indicate in your application–active, inactive and hot–you must supply a pixmap for each toolbar item. The size of the pixmaps for the entire toolbar is taken from the size of the first pixmap.

At runtime, application properties control the appearance and position of the toolbar; refer to "Dockable Toolbar Properties" in Application Development Guide.

Styles Editor

The styles editor is now located on the Tools menu in the editor workspace.

JIF Editor

For JetNet and Oracle Tuxedo applications, refer to page 1-55, "JIF Editor" for information about the JIF editor, a graphical utility used to create and edit a JIF file that contains information about your application's services.


Development and Deployment

New Executable Names

The development executable name has been changed from jamdev to prodev. The runtime executable name has been changed from jam to prorun.

Universal Makefile

A single, universal makefile is provided. In prior releases, different pieces of JAM required their own individual makefiles, and it was sometimes necessary to merge the individual makefiles for your specific needs. With the new makefile, you can build either two-tier or three-tier executables:

For more information, refer to the Installation Guide.

Libraries, not Files

To facilitate deployment, all application components (screens, JPL modules, bitmaps, and so on) are now required to reside in libraries. In the screen editor, the components are opened as library members by default, or as repository entries by request. The notion of an independent disk file no longer exists. Refer to Chapter 2, "Using the JAM Upgrade Utility," for information about a utility which groups your disk files into libraries.

Panther cannot write to libraries created by versions of JAM. To upgrade and make writable a preexisting library, use formlib with the -w flag. In the screen editor, if an attempt is made to access a library that has not been upgraded, a warning instructs you to upgrade the library. Note that Panther can still read preexisting libraries.

During development, libraries can exist anyplace on your network. If your development environment includes shared libraries on a server (remote libraries), your clients can have access to those libraries via a (provided) development server (devserv) configured to access remote libraries. With Panther, access is provided to both local and remote libraries from the screen editor, the menu bar editor, the styles editor, and the JIF editor.

For more information on opening libraries, refer to "Opening and Creating a Library" in Using the Editors.

Library Locking

Libraries now automatically reuse space as part of normal processing. Because of this, libraries now require read locks as well as write locks. Two methods of library file locking are used, internal and external, depending on the platform. By default, the internal (native OS) file locking system is used on UNIX and Windows. If an external file locking method is used, lock files must be created in the directory where the library exists; make sure the directory where the libraries reside is writable.

During deployment, it is advantageous to make all your libraries read-only, so that no file locking is required. However, if you decide to make an application library writable, make sure that if external locking is used, lock files can be created in the directory where the library resides.

For more information, refer to Chapter 10, "Accessing Libraries," in Application Development Guide.

Source Control

Source control is now available (SCCS, PVCS) for JPL, menus, and styles–in addition to screens—that are in libraries under source control.

Libraries Names

A Panther application can consist of a set of libraries, depending on the product and architecture.

All Panther applications are installed with a library named client.lib in the config directory. When you start Panther, this library will be opened unless different libraries are specified in the environment or initialization file using SMFLIBS. It contains:

JetNet and Oracle Tuxedo Applications

A Panther JetNet/Oracle Tuxedo application consists of a set of libraries:

client.lib, server.lib, and common.lib are three libraries distributed with Panther. You can use these libraries as a starting point to build your application. The contents of these libraries are:

The Library Table of Contents window gives you access to library members, and permits you to add external files, such as bitmaps, into open libraries.

References to Files Outside of Libraries

Although it is recommended and documented that all application files (for example, screens, JPL modules, graphics, and menus) be stored in libraries, this release of Panther will continue to support applications that reference files outside of Panther libraries. To ensure compatibility with future releases, it is recommended that newly developed applications store files in libraries.

JPL Programming

Declaring Variables

Use commas to delimit initial values in global and vars declarations.

Sending and Receiving Data

The send and receive commands have changed for word-wrapped fields. Word-wrapped fields are now sent as a single item; the receive command should specify a word-wrapped field which permits it to use sm_ww_write to place the text.

Another change is that the number of available bundles can be set with the max_bundles application property. It defaults to ten bundles (including the unnamed bundle) if unspecified.

Variable Assignments

In previous versions of the product, an expression which mixed numeric with string variable assignments yielded inconsistent results. It is illegal to mix these assignments within one expression. For example, the following assignment previously yielded either 0 or an empty string, depending on which version is being used:

%.0 a='' // Assigned '' to a

Now, this assignment generates a syntax error.

Application Properties

The @jam property shortcut for the application name has been replaced with @app(). @jam will continue to work for backward compatibility.

New Commands

COM and WebSphere applications can call the following JPL commands:

JetNet and Oracle Tuxedo applications also have additional commands (see "JPL Commands."

Java Interface

In addition to C and JPL, you can program your application behavior in Java. In the editor, Panther objects (screens, service components, widgets) can be assigned a Java tag, which defines a Java class to act as an event handler for that object.

At runtime, when a given object has an event handler associated with it, Panther will invoke the methods supported by the event handler in response to application events.

The event handler classes must provide methods that correspond to the various kinds of events supported by the object with which it is associated. To this end, predefined interfaces, that the event handler classes must implement, have been provided.

For more information on Java programming in Panther, refer to Chapter 21, "Java Event Handlers and Objects," in Application Development Guide.

Internal File Locking Available on Windows

Internal (native) file locking is now the default for Windows, and you will need to run formlib -e on a library in order to continue using external lock files. Once a library is set to external file locking with formlib -e, you must run formlib -i on that library in order to use internal file locking.

Opening Library Files in Windows

In Windows executables, double clicking on the name of any file in a library will open the file in the program associated with it according to the Windows File Type setting.

MSVC Project Files

MSVC project files are now available for rebuilding your Panther executables.

Team Development

In JetNet and Oracle Tuxedo executables, developers can have personal copies of screens in library files and services in the JIF in order to make and test changes during development.


Utilities

File Extension Option

A change has been made to the way the -e file extension option is implemented on UNIX in the utilities cmap2bin, jpl2bin, key2bin, msg2bin, msg2hdr, var2bin, and vid2bin. Formerly, in UNIX, file extensions were appended to existing extensions. In DOS, using -e replaced an existing file extension. Now, use of the -e option works the same on both platforms—any existing file extensions are replaced.

Changed Utilities

Changes were made to the following utilities:

binherit
In addition to updating screens with inherited values from the repository, binherit also updates reports.

The following changes were implemented for the -u option:

dd5upg
(JAM 5 updates only) The dd5to6 utility has been renamed as dd5upg.

f2asc
In addition to converting screens between binary and ASCII format, f2asc also converts reports and service components. ASCII files for screens and service components start with a S: output area containing screen/component properties; ASCII files for reports start with a R: output area. The output area for static labels has changed from S: to L:. The output area for the service component's interface starts with I:.

f5upg
(JAM 5 updates only) In addition to being renamed f5upg (previously f5to6), a new -p option includes the GUI interface values for the hmargin, vmargin, hbuffer, vbuffer properties in the converted screens.

formlib
Panther cannot write to libraries created by any version of JAM. To upgrade and make writable a preexisting library, use formlib with the -w flag. In the editor, if an attempt is made to access a library that has not been upgraded, a warning instructs you to upgrade the library. Note that Panther can still read preexisting libraries.

The -m flag now compacts the library by removing unused space. Using this option before making the library read-only will allow the read-only operation to be reversible. (This option is only available for Panther libraries.)

The -o option makes a library read-only. Be aware that once this is done, the library cannot be made writable again unless the library is first compacted with the -m flag.

The -s flag now synchronizes a library with the source code management directory. This used to be accomplished with the -m flag, along with library compacting.

monitor
In Panther, you must start the web application by using monitor or by installing the application as an Windows service which uses Services properties in the Control Panel to start the application.

monitor has new options: -restart which combines the clean, stop, and start options and -install for installing the application as an service.

r2asc
The r2asc utility has been superseded by f2asc; therefore, to convert a report between binary and ASCII output, use f2asc.

rinherit
The rinherit utility has been superseded by binherit; therefore, to batch update all reports with inherited values from your application's repository, use binherit.

rw6toprl
rw6to7 has been renamed as rw6toprl.

New Utilities

Jam to Panther
A utility to help you upgrade your JAM application to Panther by packaging the application files into libraries. (Refer to Chapter 2, "Using the JAM Upgrade Utility.")

AxView
In the Windows development environment, COM components, including ActiveX controls, are displayed by AxView, the ActiveX and COM Control Viewer. With this utility, you can view a component's methods, properties, CLSID number, and installation location.

Web Setup Manager
A Web-based utility is available for creating and updating the files needed on your Web application server: the requester executable and the Web initialization file.

For step-by-step instructions, refer to Appendix B, "Web Setup Manager," in Web Development Guide.

COM/MTS Utilities

MakeDLLs
In COM/MTS applications, a utility to generate the service components's DLLs for the specified libraries.

JetNet/Oracle Tuxedo Utilities

Refer to "Administration Utilities" for information on utilities to administer your JetNet or Oracle Tuxedo application.

WebSphere Utilities

makeejb
In Panther/WebSphere applications, a utility to generate the Java files for the service components in the specified libraries.

Configuration

Name extensions
Screen names no longer have a default value set for the application variable SMFEXTENSION which, in previous releases, specified the default file extension for screens.

Video files
Video files are no longer needed on GUI platforms. The SMVIDEO environment variable is only required for character-mode Panther users.

Opening multiple libraries
A single declaration of SMFLIBS can now point to multiple libraries. Separate directories with a vertical bar (|) or use the convention used by your operating system for listing multiple directories in path. (For UNIX, this is a colon, and for Windows, it is a semi-colon.) For the JetNet/Oracle Tuxedo middleware adapter, the default setting automatically opens client.lib, server.lib, and common.lib.

Java
The behavior variable JAVA_USE specifies whether Java is initialized. This variable can also be used to control the opening Java support message.If you are using Java event handlers, four optional environment variables are available. SMJAVAEDITOR specifies a different text editor than SMEDITOR. SMJAVALIBRARY specifies the location of Java libraries, if the default location needs to be changed. SMJAVAFACTORY specifies the location of the class factory if the default class factory is not used. SMJAVACOMPILE specifies the command used to compile Java using ToolsCompile Java.

Motif resources
A new Motif resource has been added to the Prolifics resource file, Prolifics*positionIsFrame. When placing a window at a specific position on the display, the requested position can be for the placement of the frame or for the placement of the client window inside the frame. If the position is for the frame, set this resource to true (the default setting).The window manager can have a resource of the same name. The value of the Prolifics resource should match the value of the window manager. The distributed resource files are in the config directory.

JetNet/Oracle Tuxedo Variables

The following variables were developed specifically for the JetNet/Oracle Tuxedo middleware adapters:

Connecting to the middleware
For the JetNet/Oracle Tuxedo executables, variables are used to connect to the middleware: SMRBCONFIG, SMRBHOST, and SMRBPORT. For more information on middleware connections, refer to Chapter 9, "Connecting to the Middleware," in Application Development Guide.

WebSphere Variables

The following variables were developed specifically for the Panther/WebSphere environment:

IBM WebSphere Administrative Console
For Panther/WebSphere applications, you can specify the command to launch IBM's WebSphere Administrative Console program with SMWSADMIN.

Oracle Tuxedo support in Panther/WebSphere
In Panther/WebSphere applications, the initialization file (Panther.ini) can set SMTPCLIENT to specify whether Oracle Tuxedo connectivity is enabled and what type of client is needed (native or workstation). Set SMTPINIT to specify the default arguments to the client_init command.

WebSphere Application Server
In Panther/WebSphere applications, specify URL of the machine running WebSphere Application Server in SMPROVIDERURL.

API Changes

The Panther API has been significantly expanded to accommodate the middleware API and to incorporate other product changes.

Specifying Application Properties

The @jam property shortcut for the application name has been replaced with @app(). @jam will continue to work for backward compatibility.

Additional Flags for Widget Functions

Two additional flags are now documented for widget functions:

K_EXTEND
The widget is an extended selection list box.

K_EXTEND_LAST
For extended selection list boxes, the widget is the last item in the list box.

Properties Window

Database property category
The properties listed under Database have been reorganized under new subheadings for text widgets:

Database, Transaction and Server View property categories
The properties listed under Database and Transaction for table views have been reorganized. In addition, a new category, Server View, contains all the properties having to do with select processing.

Service property category in JetNet and Oracle Tuxedo executables
Table view and link widgets have a Service property category. With the JetNet and Oracle Tuxedo middleware adapters, service names can be specified to implement database access operations. Table views can have the Insert, Update, Delete, and Select service properties set. Link widgets can have the Validation Service property set. If you create your client screens with the screen wizard, these properties are set automatically.

For more information, refer to "Creating Services with the Screen Wizard" on page 5-5 in JetNet/Oracle Tuxedo Guide.

Component API Changes

New Library Functions for Components

As of Panther 4.2, you can use the same programming interface for both COM components and Enterprise JavaBeans in a Panther application:

sm_log
Write a message to a server log.

sm_obj_call
Call a service component's method.

sm_obj_create
Instantiate a service component. Before calling this function, the application must specify the type of components currently in use with current_component_system.

sm_obj_delete_id
Remove a service component.

sm_obj_get_property
Get the value of a service component's property.

sm_obj_onerror
Install an error handler for a service component.

sm_obj_set_property
Set the value of a service component's property.

sm_raise_exception
Send an error code back to the client.

sm_receive_args
Receive the method's parameters from the client.

sm_return_args
Return a list of parameters back to the client.

New Properties for Components

There are new properties associated with service components:

Current Component System (current_component_system)
A runtime-only application property that specifies the type of component system currently in use: PV_SERVER_COM for COM components or PV_SERVER_EJB for Enterprise JavaBeans deployed under WebSphere Application Server.

In Server (in_server)
An application property which specifies which server is in use for a service component: PV_SERVER_COM, PV_SERVER_MTS or PV_SERVER_EJB.

Provider URL (provider_url)
For WebSphere applications, a runtime-only application property specifying the location of the WebSphere application server machine. If SMPROVIDERURL is set in the environment, the property is initially set to this value.

ActiveX Controls and COM Components

Web and Windows applications can create and deploy ActiveX controls in client screens. Windows 32-bit applications can create COM components and deploy them under COM, DCOM, and MTS.

New Library Functions for COM Components

There are new library functions associated only with use of ActiveX controls and other COM objects. Additional functions are documented in "Component API Changes."

sm_com_load_picture
Get the object ID for the specified picture.

sm_com_QueryInterface
Access the QueryInterface method for the specified COM component.

sm_com_result
Get the error code returned by the last call to a COM component.

sm_com_result_msg
Get the error message returned by the last call to a COM component.

sm_com_set_handler
Set an event handler for the specified event on a COM component.

New MTS Functions

For COM components running under MTS, there is a set of wrapper functions to the associated MTS methods.

sm_mts_CreateInstance 
sm_mts_CreateProperty
sm_mts_CreatePropertyGroup
sm_mts_DisableCommit
sm_mts_EnableCommit
sm_mts_GetPropertyValue 
sm_mts_IsCallerInRole
sm_mts_IsInTransaction
sm_mts_IsSecurityEnabled
sm_mts_PutPropertyValue
sm_mts_SetAbort
sm_mts_SetComplete

New Properties for COM Components

In addition to the properties for ActiveX controls listed here, refer to "New Properties for Components."

ActiveX Controls
For ActiveX Controls, there is a new property category with three Panther properties: Control Name (control_name), CLSID (clsid), and Runtime License (runtime_license). ActiveX controls are available in Web and Windows applications.

For more information about ActiveX controls, refer to Chapter 18, "ActiveX Controls," in Using the Editors.

Grid API Changes

New Library Functions for Grids

There are new library functions associated with sorting data in arrays and grids:

sm_obj_sort
Sort the object's occurrences according to the rules specified in the object's Sort Order property.

sm_obj_sort_auto
Sort the object's occurrences according to the conventions for grids in Windows.

New Properties for Grids

There are new properties associated with the use of grids:

Column Click Action (column_click_action)
For widgets in grids, under Format/Display, specify the action–sort or custom function–that occurs when a user clicks on the grid column header.

Column Click Function (column_click_func)
For widgets in grids, under Format/Display, specify the custom function to invoke when a user clicks on the grid column header. For this property to be available, Column Click Action must be set to Custom.

Default Row Margin (default_row_margin)
Use this application property to control the grid row height if the Row Margin property is not set for the grid widget.

Row Margin (row_margin)
For grid widgets, under Geometry, adjust the space between the text and row dividers to control the row height.

Sort Order (sort_order)
Under Format/Display, specify the sort order to be used when the widget is in an array or in a grid. If the widget is in a grid, the Column Click Action property must also be set to Sort.

Sort Order Function (sort_order_func)
Under Format/Display, specify the custom function to be invoked when Sort Order is set to Custom. The function can be either a JPL procedure or prototyped C function.

Tab Control API Changes

New Properties for Tab Controls

There are new properties associated with use of the tab controls in Windows applications:

Card (card)
For widgets on tab cards, a runtime, read-only property returning the object id of the tab card of which the widget is a member.

Card Entry Function (card_entry_func)
For tab cards, under Focus, the name of the function to be called when the tab card is entered.

Card Exit Function (card_exit_func)
For tab cards, under Focus, the name of the function to be called when the tab card is exited.

Card Expose Function (expose_function)
For tab cards, under Focus, the name of the function to be called when the tab card is made the topmost card in the deck.

Card Hide Function (hide_function)
For tab cards, under Focus, the name of the function to be called when the tab card ceases to be the topmost card in the deck.

Card Number (card_number)
For tab cards, under Identity, specify the number location of the card in the deck.

Conceal Tabs (conceal_tabs)
For tab decks, under Identity, determines whether the index tabs for the cards in the deck are visible.

Deck (deck)
For tab cards, a runtime-only, read-only property returning the object id of the tab deck of which the tab card is a member.

Number of Cards (number_of_cards)
For a tab deck, a runtime-only, read-only property specifying the number of cards in a tab deck, including hidden cards.

Tab Entry Function (tab_entry_func)
For the index tab field on tab cards, under Focus, the name of the function to be called when the tab card is topmost and its index tab gains focus.

Tab Exit Function (tab_exit_func)
For the index tab field on tab cards, under Focus, the name of the function to be called when the tab card is topmost and its index tab loses focus.

New Logical Keys for Tab Controls

New logical keys, NCARD and PCARD, move to the next card and previous card respectively.

Database Interface API Changes

New Functions for the Database Interfaces

The new library functions associated with the database interfaces are:

dm_convert_empty
Determine if empty numeric fields should be replaced with a 0. This setting is database-specific since some databases do not allow NULL values in numeric columns.

dm_cursor_connection
Return the database connection for the specified cursor.

dm_cursor_consistent
Determine if the specified cursor is on the default connection.

dm_cursor_engine
Return the database engine for the specified cursor.

dm_get_db_conn_handle
Return a handle to the database connection's structure.

dm_get_db_cursor_handle
Return a handle to the database cursor's structure.

dm_get_driver_option
Return the value of a database driver option.

dm_odb_preserves_cursor
Check to see whether the ODBC datasource preserves the cursor on a commit or a rollback.

dm_set_driver_option
Set the value of a database driver option.

dm_set_max_fetches
Set the maximum number of rows in a select set.

dm_set_max_rows_per_fetch
Set the maximum number of rows per fetch.

New Properites for the Database Interfaces

There is a new property associated with database connections:

Connection Pooling (conn_pool_size)
In Panther/WebSphere applications,d specify the number of concurrent database connections.

New Commands for Database Interfaces

The new database interface commands are:

DBMS QUERY

DBMS RUN

Database Interface Command Changes

The following commands used in conjunction with the database interface have changed:

DBMS CATQUERY

DBMS DECLARE CONNECTION

Transaction Manager API Changes

New Library Functions for the Transaction Manager

The new library functions associated with the transaction manager are:

dm_disable_styles
Suppress the enforcement of styles in the transaction manager.

dm_enable_styles
Enable enforcement of styles in the transaction manager.

dm_set_tm_clear_fast
Clear all fields in a server view.

sm_get_tv_bi_data
Get before-image data.

sm_tm_handling
Process the specified transaction manger functions for special insert, update, select and delete handling.

sm_tm_old_bi_context
Specify the method of before-image processing.

The following library functions used in conjunction with the transaction manager have changed:

dm_gen_change_select_list
For this function, do not use a local JPL variable as the target of a transaction manager fetch.

sm_tm_inquire
A new argument, TM_SV_SEL_COUNT determines if an initial query will be performed in order to determine the number of rows in the select set. Five new arguments are available: TM_CANCEL_ON_DISCARD, TM_CURRENT_COMMAND, TM_SAVE_COUNT, TM_SV_SEL_COUNT, TM_XA_TRANSACTION_BEGUN.

sm_tm_iset
Three new arguments are available: TM_CANCEL_ON_DISCARD, TM_SV_SEL_COUNT, TM_XA_TRANSACTION_BEGUN.

sm_tm_pinquire
A new argument, TM_COMMAND_ROOT, identifies the root table view of the current command.

New Properties for the Transaction Manager

There are several new properties associated with the transaction manager. Some are settable via the Properties window and others are readable and/or writable only at runtime. They are:

Before Image Rows (bi_string[iter])
A widget, runtime-only, property. Provides access to the before image values of rows in the transaction manager as strings. The iter specification lets you walk through the list of rows.

Continue Function Name (continue_func_name)
For table views in two-tier applications, specify the function for handling CONTINUE operations in the transaction manager for the specified server/table view. The Select Handling property must be set to Function Name.

Count Result (count_result)
A table view, runtime-only, property. This readable/writable property holds the value returned from a count query (from a TM_SELECT_COUNT event), that is, the total number of rows in the result set. The value is examined to determine whether to query the user about proceeding with the normal SELECT statement.

Count Select (count_select)
A table view property, located under Transaction, takes a value of Yes or No. Instructs the transaction manager whether or not to count the number of rows in a result set and compare it (stored in the server view's count_result property) to a specified threshold (Count Threshold property) value before actually fetching data. This property is readable and writable.

Default Transaction (default_tran)
A runtime-only, read-only screen property that provides the name of the default transaction manager transaction. This property always contains the name, even if the transaction is not currently open, and can be used to stop and then re-start the default transaction when making runtime property changes.

Delete Function Name (del_func_name)
For table views, specify the function for handling delete statements in the transaction manager for the specified table view. The Delete Handling property must be set to Function Name.

Delete Handling (delete_handling)
For table views, select the method for handling delete statements in the transaction manager for the specified table view: SQL Statement Generation (PV_HANDLING_SQL), Function Call (PV_HANDLING_FUNC), or Nothing (PV_HANDLING_NOTHING).

Deleted Rows (di_string[iter])
A widget, runtime-only, property. Provides access to the values of deleted rows in the transaction manager as strings. The iter specification lets you walk through the list of deleted rows. Use in conjunction with the num_del_images property.

Insert Function Name (ins_func_name)
For table views, specify the function for handling insert statements in the transaction manager for the specified table view. The Insert Handling property must be set to Function Name.

Insert Handling (insert_handling)
For table views, select the method for handling insert statements in the transaction manager for the specified table view: SQL Statement Generation (PV_HANDLING_SQL), Function Call (PV_HANDLING_FUNC), or Nothing (PV_HANDLING_NOTHING).

Join Type (join_type)
For link widgets, under Transaction, a subproperty of Type. When the link is identified as a server link, that is if the link's Type (type) property is set to Server (PV_LNK_SERVER), the Join Type property is available. It can be set to: Inner (PV_INNER) (default), Left Outer (PV_LEFT_OUTER), Right Outer (PV_RIGHT_OUTER), or Full Outer (PV_FULL_OUTER). This property lets you take advantage of SQL join facilities, whereby you can control the join operation of a SELECT statement that combines information from two database tables.

Number of Columns (num_columns)

A read-only and runtime-only property associated with table view widgets. This property returns the number of columns belonging to a specific table view, or more specifically, the number of occurrences defined in the Columns (columns) property.

Number of Deleted Rows (num_del_images)
A widget, read-only and runtime-only, property that returns the number of deleted rows in the transaction manager.

Primary Key Update (primary_key_update)
A runtime-only application property determining how primary key changes are processed in the transaction manager: whether the row is updated or whether it is deleted and then inserted.

Regenerate SQL (regenerate_ins_sql, regenerate_upd_sql)
If the transaction manager generates SQL statements, as determined by the Method property, specify if the SQL statement should be regenerated for each row in the table.

Save Function Name (save_func_name)
For table views, specify the function for handling SAVE operations in the transaction manager for the specified server/table view. The Delete Handling, Insert Handling, or Update Handling properties must be set to Function Name.

Select Function Name (sel_func_name)
For table views, specify the function for handling select statements in the transaction manager for the specified server/table view. The Select Handling property must be set to Function Name.

Select Handling (select_handling)
For table views, select the method for handling select statements in the transaction manager for the specified server/table view: SQL Statement Generation (PV_HANDLING_SQL), Function Call (PV_HANDLING_FUNC), or Nothing (PV_HANDLING_NOTHING).

Service Transaction (tm_transaction)
A runtime-only application property in JetNet and Oracle Tuxedo executables that determines whether a service is transaction-manager enabled and, if so, which transaction manager operation is to be performed.

Threshold (count_threshold)
For table view widgets, this property is a subproperty of the Count Warning property when Count Select and Count Warning are set to Yes. Use to specify the maximum number of rows to fetch in a result set. If a result set (stored in the server view's count_result property) exceeds this value, the user is prompted before the data is actually fetched.

Update Function Name (upd_func_name)
For table views, specify the function for handling update statements in the transaction manager for the specified table view. The Update Handling property must be set to Function Name.

Update Handling (update_handling)
For table views, select the method for handling update statements in the transaction manager for the specified table view: SQL Statement Generation (PV_HANDLING_SQL), Function Call (PV_HANDLING_FUNC), or Nothing (PV_HANDLING_NOTHING).

Warning (count_warning)
For table view widgets, this property is a subproperty of the Count Select property when Count Select is set to Yes. Use to specify whether the user is prompted, before the data is actually fetched, when the size of a result set (stored in the server view's count_result property) exceeds the value in the Count Threshold property.

Property Changes for the Transaction Manager

The property changes associated with the transaction manager are:

Fetch Directions/Directions (fetch_directions)
The table view Fetch Directions property has been renamed to Directions and is located in the new Server View category.

Both the table view Directions property and the screen Fetch Directions property have an additional value, none, which when set eliminates the possibility of doing CONTINUE command processing on a server view. CONTINUE functionality can consume system resources, therefore, using this property value can allow you to better control how a SELECT is issued against the table view.

Memo Text (memo1...memo9) properties for table views and links
Under Identity, both table view and link widgets can now have Memo Text properties assignments.

Relations (relations)
This property, which describes the relationship between two table views, has been refined into three sub-properties: rel_child (database column in child table view), rel_parent (database column in parent table view), and rel_op (type of relationship–join or lookup).

Other property changes for the transaction manager are:

Readable transaction properties
Prior to Panther, almost all transaction properties were readable at runtime; only five were not. All transaction properties are now readable via the property API. They include widget properties (under Column Edits): Length (column_length), Precision (column_precision), Scale (column_scale), and Type (column_type).

Writable transaction manager properties
If a transaction manager transaction is not in effect, all transaction manager properties are writable.

New Commands for the Transaction Manager

The new transaction manager commands are:

RELEASE
The transaction manager has a new command, RELEASE, which releases the database cursors when the transaction manager is active.

WALK commands
The WALK commands direct the transaction manager to traverse the transaction tree of an application screen. These commands have no processing attached to them in the transaction models so the traversal can be used to fire any transaction event functions.

WALK_DELETE

Traverses the tree in delete order.

WALK_INSERT

Traverses the tree in insert order.

WALK_SELECT

Traverses the tree in select order.

WALK_UPDATE

Traverses the tree in update order.

New Events in Transaction Manager Processing

If you write your own transaction manager event functions, three new slices were added to the TM_SELECT and TM_VIEW request events in order to check the size of the select set:

TM_SET_SEL_COUNT_FLAG

TM_SEL_COUNT_CHECK

TM_CLEAR_SEL_COUNT_FLAG

For database transactions, the following slices were added to the SAVE command:

TM_SAVE_BEGIN

TM_SAVE_COMMIT

TM_SAVE_ROLLBACK

TM_SAVE_SET_MODE

Web Application API Changes

Browser Events

In conjunction with VBScript support, the JavaScript Events category in the Properties window was renamed Browser Events. A new event is also available:

OnMouseOut event
For JavaScript and VBScript, the OnMouseOut event for widgets is now available. This property lets you specify a JavaScript or VBScript function to execute when the mouse pointer leaves an area (in client-side image maps) or a link.

New Library Functions for Web Applications

There is a new library function associated with Web applications:

sm_web_log_error
Write Web application errors to a log file.

New Properties for Web Applications

There are several new properties associated with Web applications:

Default Link (default_link)
For Web applications, specify the URL location for this hyperlink. (This replaces the link property in previous releases.) If the property is specified for an array, it is the hyperlink location for every occurrence in the array. (See Item Link.)

HTML Max Loop (html_max_loop)
For HTML templates using condition processing, specify the number of loop iterations to perform before terminating the process. The default setting is 1000.

HTML Max Nest (html_max_nest)
For HTML templates using condition processing, specify the number of nesting levels. Each if, while, or include constitutes one level. The default setting is 20.

HTML Name (html_name)
Read-only access to the converted HTML name, which is based on the Panther variable name, using the syntax {{variable->html_name}}.

Insert/Delete Buttons property (ins_del_buttons)
For grid widgets in Web applications, if set to Yes (default), Insert (Insert Above and Insert Below) and Delete buttons are generated in the HTML representation of the grid widget. If set to No, the buttons are not generated under any circumstances.

OnMouseOut (on_mouse_out)
For Web applications, under Browser Events, this property lets you specify a JavaScript or VBScript function to execute when the mouse pointer leaves an area (in client-side image maps) or a link.

Previous Form (previous_form)
For Web applications, get the screen name as stored in the current cache file. Typically, this would be the name of the last screen that was accessed.

Stylesheet Data (stylesheet_data)
Under Web Options, for inline style sheets, enter the style sheet specification.

Stylesheet Link (stylesheet_link)
Under Web Options, specify the URL location of the style sheet. On the HTTP server, the style sheet should be located in the public documents directory.

Stylesheet Source (stylesheet_source)
Under Web Options, specify whether the style sheet for the web application screen is included in the screen itself (Inline) or in a separate document (Link).

Stylesheet Type (stylesheet_type)
Under Web Options, specify the type of style sheet to be used for the web application screen: CSS (cascading style sheets) or JavaScript.

Submit (submit)
Under Web Options, setting this new push button property to No will keep the screen from being submitted back to the web application server when the button is pressed.

VBScript (vbscript)
Under Web Options, setting this new push button property to No will keep the screen from being submitted back to the web application server when the button is pressed.

Web ID (webid)
For Web applications, this application property obtains the name of the next cache file to be generated.

Property Changes for Web Applications

There are several property changes associated with Web applications:

Label (label) property
The Label property (label) is now available for grid widgets. The setting provides a caption for the HTML table in Web applications.

Link (default_link) property
The Link property (link) in previous releases has been changed to Default Link (default_link).

In addition, business graphs can be assigned a URL. If no value is set, the graph does not act as an HTML link.

Style property (style)
The screen subproperty of the Pixmap property now defaults to Tile instead of Center. This only affects newly created screens.

Dockable Toolbars

New Properties for Dockable Toolbars

There are new properties associated with the use of dockable toolbars in Windows applications:

Toolbar Allowed Sites (toolbar_allowed_sites)
For toolbars in Windows applications, a runtime application property sets the frame placement for the toolbar using one or more of the following bit flags: PV_TOOLBAR_FLOAT, PV_TOOLBAR_TOP, PV_TOOLBAR_BOTTOM, PV_TOOLBAR_LEFT or PV_TOOLBAR_RIGHT.

Toolbar Coordinates (toolbar_x_position, toolbar_y_position)
For toolbars in Windows applications, runtime application properties set the screen coordinates of the upper-left corner of the floating toolbar.

Toolbar Current Site (toolbar_current_site)
For toolbars in Windows applications, a runtime application property sets the current placement of the toolbar using one of the defined bit flags: PV_TOOLBAR_FLOAT, PV_TOOLBAR_TOP (default), PV_TOOLBAR_BOTTOM, PV_TOOLBAR_LEFT, or PV_TOOLBAR_RIGHT.

Toolbar Hidden (toolbar_hidden)
For toolbars in Windows applications, a runtime application property sets whether the toolbar is currently displayed using PV_YES and PV_NO. Users can hide the toolbar by clicking on the X in the upper-right corner of the menu.

Other API Changes

New Properties

These are the remaining new properties not covered in previous sections:

Endsession (endsession)
For Windows applications, an application property which specifies the function to call which closes down the application when Windows sends the WM_ENDSESSION message.

Java Tag (java_tag)
Under Identity, specify the Java class implementing the event handler for this object (screen, service component, widget).

Max Bundles (max_bundles)
A runtime-only application property specifying the number of JPL bundles available for send and receive commands. It defaults to ten bundles (including the unnamed bundle) if unspecified.

Queryendsession (queryendsession)
For Windows applications, an application property which specifies the function to call which prepares to close the application when Windows sends the WM_QUERYENDSESSION message.

Screen Type (screen_type)
For screens and service components in distributed applications, a property under Identity which displays whether the screen object is a client screen or service component.

Property Changes

The following properties have changed in Panther:

Font properties
Screen and widget font properties that identify, what was JAM-specific fonts, have been updated to be Panther-specific fonts both in the Properties window and in the configuration map file; the JAM modifier has been eliminated.

Help properties (help_screen)
The menu property, mni_jam_help (menu item Help property) is now mni_help.

The screen property (JAM Help property) and its corresponding mnemonic, jam_help_screen are now Help Screen and help_screen, respectively.

Style property (style)
The screen subproperty of the Pixmap property now defaults to Tile instead of Center. This only effects newly created screens.

Application Properties

The @jam property shortcut for the application name has been replaced with @app(). @jam will continue to work for backward compatibility.

Text Selection

A new series of logical keys have been added for selecting text:

EXTFB

extend selection to start of field or list box

EXTFE

extend selection to end of field or list box

EXTL

extend selection with left arrow in text field

EXTLB

extend selection to start of line in text field

EXTLE

extend selection to end of line in text field

EXTPD

extend selection down one page in text field or list box

EXTPU

extend selection up one page in text field or list box

EXTR

extend selection with right arrow in text field

EXTWL

extend selection one word left in text field

EXTWR

extend selection one word right in text field

SLALL

select entire text field

SLWRD

select current word

In addition, EXTD and EXTU now also apply to text fields as well as list boxes.

New Library Functions

There are several new library functions for use in application building:

sm_file_exists
Checks whether a file exists.

sm_file_move
Copies a file and deletes its source.

sm_file_remove
Deletes a file.

sm_ldb_fld_get
Copy data from LDBs to specific fields.

sm_ldb_fld_store
Copy data from specific fields to LDBs.

sm_l_open_syslib
Opens a library as a system library.

sm_list_objects_count
Counts the widgets contained by an application object.

sm_list_objects_end
Destroys an object contents list.

sm_list_objects_next
Traverses the widgets contained by an application object.

sm_list_objects_start
Constructs a list of widgets contained by a Panther object.

sm_load_screen
Preload a screen into memory.

sm_menu_change
Set a menu's properties.

sm_mnitem_create
Insert a new item into a menu.

sm_msg_del
Delete a message set from memory.

sm_msg_read
Read messages from a memory block.

sm_mw_PrintScreen
In Windows executables, print Panther screens, sending either the current Panther screen or all the screens in the MDI frame to the printer.

sm_unload_screen
Unload a screen from memory.

Changed or Discontinued Functions

The following library functions have been changed or discontinued:

sm_fi_open
Is no longer documented. sm_fi_open was used to find a file (along the Panther's search path) and open it in binary read-only mode. Use sm_fi_path instead to search along Panther's search path. Then call fopen (a standard C function) to open the file in any way you choose (it does not limit you to binary read-only mode).

sm_inquire
A new parameter, I_INERROR, is available to determine if a message box is being displayed.

sm_msgread
Has been replaced with the following new functions:

The message classes have also been updated; FM_MSGS, JM_MSGS and JX_MSGS messages are now located in SM_MSGS. The value for WB_MSGS has also been updated. Any instances of sm_msgread in a Panther application should be updated to the new message classes.


Database Interface

For additional information, refer to "Database Interface API Changes."

Improved SQL Processing

DBMS SQL statements that specify data modification and do not return data (INSERT, UPDATE, and DELETE statements) are executed by simply passing the SQL statement to the database immediately to process the statement quickly and efficiently. For SQL statements that return rows (SELECT), the process includes a prepare and execute cycle. This means that the database is first notified where to put the data (if any), and then tells the database to execute the SQL.

The method used to determine if a SQL statement returns rows is to execute the SQL statement and see if it returns rows. If it does, it goes through the prepare and execute cycle—essentially executing the SELECT statement twice. If the statement is a stored procedure which inserts a row and then selects back data, the stored procedure is executed twice and therefore causes two copies of the row to be inserted.

The new method of SQL statement processing includes two new DBMS statements which will improve SELECT-type processing and performance:

Performance is improved because:

Specifying Variables in DECLARE CONNECTION

The new recommended syntax for DBMS DECLARE CONNECTION allows the values for the connection options to contain spaces or punctuation characters. Use the WITH keyword in the statement (instead of FOR) and connect the option and value with an equal sign in comma-separated pairs. Variables no longer need to be colon-expanded; strings must still be in quotation marks. The following example contains two variables for the user and password and a quoted string for the database path:

DBMS DECLARE c1 CONNECTION WITH \
USER=user, PASSWORD=pword, \
DATABASE="C:\Program Files\Prolifics\videobiz"

Since the variables are not colon-expanded in this variant, the values will not appear in error messages and trace statements.

Support for Long Filenames

DBMS CATQUERY now supports writing to a filename containing spaces or punctuation. Create a variable for the filename and use the variable in the new command syntax:

vars query1 = "query results"
DBMS CATQUERY TO FILENAME query1

This syntax does not replace DBMS CATQUERY TO FILE, which is supported unchanged.


Transaction Manager

For information on API changes (functions, properties, commands, slice events), refer to "Transaction Manager API Changes."

Transaction Manager Common Model

The previous set of database-specific transaction models delivered with Panther have been replaced with smaller, more manageable models. In addition to the database-specific model, each engine also accesses a common transaction model, containing the functionality common to all of the database engines. The source code for the new database-specific transaction models is provided and can be modified to make global changes in transaction manager functionality. The common model should not be modified; however, the source code is available for reference.

Having a database-specific model expands the event processing in the transaction manager. As in previous versions, the transaction manager first checks to see if an event function has been specified for the event. If so, it is processed; otherwise, the transaction manager proceeds to the database-specific transaction model. If database-specific processing for the event is required, it must be contained in this model. Otherwise, the transaction manager proceeds to the common transaction model and performs the processing defined there.

To call the common model in addition to an event function and the database-specific model, have the event processing in the event function and the database-specific model return TM_PROCEED, which passes the processing to the next level. The common model is always called for TM_START and TM_FINISH events.

The common model provides plausible processing for every event known to the transaction manager. This includes default behavior for the database transaction events. While a majority of the database-specific transaction models set the mode to initial after a database transaction is committed, the common model does not, leaving this for the database-specific transaction models.

If you have revised an existing transaction model, the revised version can continue to serve as a database-specific transaction model. Since none of the previously distributed transaction models return TM_PROCEED, unless this return value has been explicitly coded, the transaction manager will only access the common model for the new transaction manager events.

If you have implemented a transaction manager event function and use one of the existing transaction models, there is no visible effect with the replacement of the old models with the new.


Web Application Development

For additional information, refer to "Web Application API Changes."

Initialization File Changes

Initialization File Settings

Web initialization files have the following new initialization variables:

One Initialization File

In previous releases, a Panther web application read the values from a global initialization file before reading the application's initialization file (appName.ini). This was done so that the proweb.ini or jamweb.ini could define any global values which are common among all web applications, but it caused problems for application maintenance. Therefore, the distributed proweb.ini file will no longer be read when you have an application initialization file. Only one initialization file is read for each Web application.

If you are using a global initialization file (proweb.ini or jamweb.ini) to set global parameters, merge all global values into your application-specific initialization file.

New Web Applications

A new Web-based utility, the Web Setup Manager, will help write and configure the files needed for your Web application.

For step-by-step instructions, refer to Appendix B, "Web Setup Manager," in Web Development Guide.

HTML Template Changes

HTML templates behave as Panther screens, allowing you to have the flexibility of how the HTML is created tied in with the power of the Panther backend. In the HTML Template property, you specify the name of the HTML document to use in conjunction with the Panther screen.

HTML Template Caching
The cache data for a Panther screen utilizing an HTML template can be maintained, and the template will be updated dynamically to associate the cache file with it. The HTML template must contain the {{form:info}} template tag.

HTML Template Tags
The syntax for HTML template tags has changed from <<variable>> to {{variable}}. In addition, there are new tags for HTML templates:

{{form:info}}

Interpolates hidden data needed to submit the form.

{{form:output}}

Outputs the entire form in the HTML format Panther would normally use.

{{form:script}}

Generates JavaScript procedures based on edits and validations of widgets on the form.

{{form:tag}}

Generates the start <FORM> tag with ACTION and JavaScript attributes.

{{value:variable}}

Generates the value corresponding to the specified variable.

{{emit:object}}

Generates the HTML that Panther would normally output for the specified object.

{{while:condition}}

{{if:condition}}

{{else:}}

{{elseif:condition}}

{{end:}}

Performs condition processing based on a JPL boolean expression.

{{include:filename}}

Include the specified file.

{{eval:statement}}

Evaluate a simple JPL statement.

Two application properties are associated with HTML loop processing: html_max_loop to limit the number of loop iterations and html_max_nest to limit the number of nesting levels.

New Syntax for Specifying Variables

The syntax for accessing Panther variables has changed from<<variable>> to {{variable}}. This new syntax can be used in JavaScript, VBScript, the Custom HTML properties (such as Prefix Markup and Suffix Markup), and HTML templates.

Web Entry Processing

When screens are submitted at runtime, Panther variables (@web_action, @web_action_widget and @web_action_occurrence) contain information about the push button that was pressed and the widget's object ID and occurrence number, if applicable. These variables can be accessed in web_enter processing. For more information, refer to "Web Entry Context Flags" in Web Development Guide.

Caching Application State

The state of the application can now be obtained when performing a GET for Panther files. In previous releases, invoking screens and reports via a GET caused the state information to be lost. The following can now be accomplished:

To implement this caching behavior, two new application properties are available:

Previous Form (previous_form)
Gets the screen name as stored in the current cache file. Typically, this would be the name of the last screen that was accessed.

WebID (webid)
Obtains the name of the next cache file to be generated.

To access the cache file, a new name=value pair can be encoded as part of the URL:

@webid=cacheFile

For more information, refer to "Getting Screens from the Server" in Web Development Guide.

Requester Executables

If you are using an ISAPI- or NSAPI-compliant HTTP server, use the new ISAPI and NSAPI versions of the requester executable, instead of the CGI version, for faster processing of your HTTP requests.

Windows Servers

If you are using Windows as your Web application server:

Running Java Servlets

A Panther web application can run as a Java servlet. For more information, refer to Appendix D, "Using Java Servlets," in Web Development Guide.

Determining Mouse Location

Two JPL globals, @web_image_click_x and @web_image_click_y, contain the X and Y coordinates of the user's mouse click for use in JPL procedures.

Widget Positioning in Web Applications

In order to control widget positioning in Web applications better, a COLS attribute has been added to the table definition in the generated HTML. This will affect the widget positioning for screens built in previous versions of Panther. For new screens, there is a higher correlation between the GUI position and the HTML position.

Additionally if you create multiple boxes or grids which are aligned on two sides in the screen editor, they will now appear to be aligned in the Browser.

Note that one browser may create its widgets using different font families and sizes than another browser, or than the Panther screen editor. This results in screens that can appear slightly different (more or less space between widgets) from browser to browser, or from browser to screen editor.

Some helpful tips are:

Errors in Web Applications

Additional error text has been added for the requester, dispatcher, and jserver programs. Errors for the Web application server have also been added to the Panther message file.

Web Gallery Samples

The following changes have been made to the gallery of Web application samples:

ActiveX and VBScript
You can embed ActiveX controls in your Panther screens and write VBScript to manipulate them on the browser. This example contains JPL procedures that dynamically generate VBScript to populate an ActiveX control. This example also demonstrates how to write VBScript to get values from an ActiveX control and copy them to hidden Panther fields in order to send them back to the server.

Templates
Demonstrates the use of the Panther Template property to present data from a Panther screen using the format of a custom HTML file. This HTML file can also be submitted back to Panther for normal processing.

By clicking on the scroll buttons of the grid, the custom representation of the data is also updated at the bottom of the screen.

Web Wizard Defaults

For wizard-generated Web screens, the default values have changed for some properties. The Border, Title Bar, and System Menu properties now default to No.

Naming Conventions

With the change in naming conventions, smrepost.jam becomes smrepost.scr.


Reports

Converting ReportWriter 6 Reports

If you need to modify a report created with JAM/ReportWriter 6, you must first convert it to a Panther report file using the rw6toprl utility. From the command line, type:

rw6toprl [-fgkm] rw6Report pantherReport

-f
Output file can overwrite existing file.

-g
Use GUI coordinates when converting the report. This option positions widgets using the GUI decimal coordinates, instead of integer coordinates. Used this option if PostScript and proportional fonts have been specified in the JAM ReportWriter 6 source file.

-k
Retain ReportWriter 6 widget types in the output file.

-m
Merge included files name in input file into output report file.

The utility converts GUI coordinates to column and row (whole-number grid units, as though in character mode) coordinates to position widgets. To ensure GUI coordinates, run rw6toprl with the -g option.

Modifying Reports from Previous Versions

As of Prolifics 2.5, several changes were made inside the report editor. To edit report files created in previous versions, you need to manually rescale the grid in the report editor using either of the following methods:

Setting Widget Size

To resize a widget in ReportWriter, do not drag the widget by its edges; set the widget size by setting the font size.

Printing PostScript

In Windows, if reports are generated using the driver=postscript option, those reports must be printed using a Windows print driver that supports PostScript. Some printer models have more than one printer driver; install the PostScript version for PostScript reports.

Report Utilities

The r2asc utility has been superceded by f2asc; therefore, to convert a report between binary and ASCII output, use f2asc. The rinherit utility has been superceded by binherit; therefore, to batch update all reports with inherited values from your application's repository, use binherit.


Upgrading to JetNet

JetNet, Panther's three-tier middleware product, is available for UNIX and Windows server. This section lists the additional features available in that product.

Editor

Screen Wizard

Menu Bar Editor

Styles Editor

JIF Editor

Debugger

For JetNet/Oracle Tuxedo applications in order to debug your server, you must configure a debuggable server. For more information, refer to "Server Details" on page 3-22 in JetNet/Oracle Tuxedo Guide.

The debugger will only access compiled JPL code saved in libraries. If compiled JPL is put in a library outside of the editor (with the jpl2bin and formlib utilities), the binary JPL file must include the JPL source code. This means that you must not use the -r flag with jpl2bin. For more information on compiling JPL source code, refer to jpl2bin in Application Development Guide.

Service Components

Service components reside on the server, and are used to map data between client screens and services. In a running application they are not visible to the user. During development, if you execute a debuggable server, service components can be viewed in Test mode, or you can test it like a client screen if you have a direct connection to the database. They can be created using the screen wizard at the same time you create client screens.

JIF

For JetNet/Oracle Tuxedo applications, the JIF is a file that contains service information required by both the clients and servers of your application. A JIF is created and edited using the JIF editor and can be set in the environment using SMTPJIF.

For more information on the JIF and the JIF editor, refer to Chapter 24, "JIF Editor," in Using the Editors.

Administration Utilities

Panther provides several utilities to configure and operate your three-tier application. For the Oracle Tuxedo middleware adapter, use utilities provided by Oracle Tuxedo that perform similar functions, such as tpadmin.

Environment Variables

Database Error Handling

Errors resulting from database access are handled differently when the server is connected to the database, as opposed to two-tier processing where the client is connected directly to the database. Default error handling on the server also depends on the environment: development or production.

There are new default database error handlers for servers. The DBMS ONENTRY default error handler logs each DBMS command in the development environment, but does nothing in a production environment. The DBMS ONERROR function default error handler logs all DBMS errors to the central user log file in both the development and production environments.

Team Development

In JetNet and Oracle Tuxedo executables, developers can have personal copies of screens in library files and services in the JIF in order to make and test changes during development.

A new menu option, OptionsService Alias allows you to specify a user identifier to use when testing services. For more information, refer to "Using Service Aliases to Test Services" on page 5-8 in JetNet/Oracle Tuxedo Guide.

To use this feature, the application server must have a service alias defined. Once defined, the library function sm_tp_get_svc_alias returns the value of the service alias for the application server.

Transaction Model

A JetNet-specific transaction model is provided for applications that use the transaction manager in the client side of your application: jetrb1. This database- and middleware-independent model is designed to process transaction manager events by requesting service calls, for example, when:

progserv

A conversion server, progserv, is provided to process service requests made by client screens that use the transaction manager but do not have Service property specifications, such as screens created from a clnt2svr conversion.

JetNet and Oracle Tuxedo Event Handling

For JetNet/Oracle Tuxedo applications, there is a middleware layer of event handling. Several event types are defined, and built-in handlers are provided for both development and production executables. Default handlers are installed and can be overridden by using new, runtime, application-specific property settings.

For information on middleware API events and event handling, refer to Chapter 6, "JetNet/Oracle Tuxedo Event Processing," in JetNet/Oracle Tuxedo Guide.

API Changes for JetNet and Oracle Tuxedo Applications

JPL Commands

There are several JPL commands associated with use of the JetNet and Oracle Tuxedo applications:

advertise

notify

unload_data

client_exit

service_call

wait

client_init

service_cancel

xa_begin

jif_check

service_forward

xa_end

jif_read

service_return

xa_commit

log

unadvertise

xa_rollback

Note that each new JPL command represents a potential name conflict with existing variable and field names in your application. All JPL commands are reserved keywords.

The receive command has been enhanced to provide middleware support. It is used to receive message data, for example by service routines to receive client data.

For more information on these commands, refer to Programming Guide.

Library Functions

There are several library functions associated with use of the JetNet and Oracle Tuxedo:

sm_tp_free_arg_buf

Frees up memory allocated by argument list generation functions.

sm_tp_gen_insert

Generates an argument list of fields for an INSERT operation.

sm_tp_gen_sel_return

Generates a list of fields for the returned select set of a SELECT or VIEW operation.

sm_tp_gen_sel_where

Generates a list of fields for the WHERE clause of a SELECT or VIEW operation.

sm_tp_gen_val_link

Generates a list of fields to be validated in a validation link operation.

sm_tp_gen_val_return

Generates a list of fields for the returned select set of a validation link operation.

sm_tp_get_svc_alias

Returns the value of the service alias for the application server.

sm_tp_get_tux_callid

Returns the Oracle Tuxedo-specific ID for a service request call.

Properties

There are several properties for JetNet and Oracle Tuxedo applications:

Table view service properties:

delete_service

insert_service

select_service

update_service

Runtime application properties:

agent_type

devserv_id

hdl_advertise

hdl_exception

hdl_jif_changed

hdl_message

hdl_post_request

hdl_post_service

hdl_pre_request

hdl_pre_service

hdl_request_received

hdl_server_exit

hdl_unadvertise

hdl_unload

tp_async_poll_interval

tp_block

tp_commit_return

tp_exc_code

tp_exc_msg

tp_exc_names

tp_mon_exc_code

tp_mon_exc_msg

tp_return

tp_severity

tp_severity_names

tp_signal_restart

tp_svc_cache_size

tp_svc_outcome

tp_svc_return

tp_this_call

tp_timeout

tp_tran_level

tp_tran_status

tp_unsol_poll_interval

Runtime service request properties:

call_client

call_in_transaction

call_initial_text

call_no_reply

call_origin

call_priority

call_security_key

call_svc_name

call_text

Link widget service property:

validation_service

Migrating a JAM Transaction Manager Application

If you are upgrading a two-tier application that uses the transaction manager to three-tier–either a pre-Enterprise application or a two-tier Panther application– you must use the clnt2svr (client-to-server) utility provided with the Panther distribution.

The clnt2svr utility creates three-tier client screens and service components from the two-tier client screens in the library you provide as input. Upon completion, the service components, and optionally any JPL procedures associated with the original client screens, are placed in a library which can be used as the server library in a three-tier application. Also, the client screens are updated to use the default three-tier transaction model jetrb1, and stored in a new client library. The input library is left unchanged.

Certain property values that existed on the client screens are removed from the service components created from them in order to avoid unnecessary entry processing on the server.

To convert your two-tier JAM application to a three-tier Panther application:

  1. If your two-tier screens are not in a library, run formlib and create a two-tier client library from all client screens and client JPL.
  2. From the command line, type:
    clnt2svr inputLib

    A new client library (cl.lib) and a server library (sv.lib) are created from the input client library, which is left intact.

  3. Create a JetNet configuration file using the JetNet manager. Include in the configuration a conversion server (progserv).
  4. Set SMFLIBS on the client and server to recognize and open the new libraries on application startup.

    clnt2svr is described in more detail in JetNet/Oracle Tuxedo Guide.

Upgrading an Existing Application

If you are not ready to convert your existing application to three-tier, you need to put all the screens, modules and bitmaps in a library in order to use it with Panther. Run formlib and create a client library from all client screens and client JPL, or add them to the distributed client library (client.lib).

Consideration needs to be made for existing JPL code. JPL modules must be compiled before they are put in libraries. JPL can be compiled in two ways:


Upgrading to Panther for IBM WebSphere

Refer to Panther for IBM WebSphere Developer's Studio for information about:


Documentation

Documentation Titles

The titles of some manuals have changed in this release:

JAM/Prolifics 2.5 Title Panther Title

Administration Guide

JetNet Guide

Oracle Tuxedo Guide

COM/MTS Guide

WebSphere Developer's Studio

Editors Guide

Using the Editors

Language Reference

Programming Guide

Tutorial

Getting Started

A new Quick Reference manual has been printed, containing a list of the property names, library functions, JPL commands, and transaction manager commands. The properties reference section of that manual is available online. For changes to the Quick Reference since its printing, refer to "Quick Reference Changes and Corrections."

The Application Development Guide has been totally re-organized in order to illustrate a typical development process.

Online Documentation

Panther documentation is now available in HTML and PDF formats. For more information about Panther online documentation, refer to Appendix A, "Panther Online Documentation," in Installation Guide.

Documentation Changes and Corrections

Other documentation changes not listed in previous sections are:

ASCII JPL modules
Even though it is recommended that all JPL modules be placed in libraries, JPL modules can be in ASCII format on disk. This has been added back to the Programming in JPL chapter.

CGI variables
In Web applications, the variables containing the HTTP header information, such as @cgi_request_method, are now referred to as HTTP server variables.

cgi-bin directory
With the addition of ISAPI and NSAPI requester executables, the cgi-bin directory is now referred to as the program directory or scripts directory.

Reports
The first release of Panther documentation incorrectly included descriptions of the Bar Height and Portable Placement properties. These properties are not in the Panther product.

sm_card_val
sm_tw_val
The first release of Panther documentation incorrectly included these functions. For tab card validation, use sm_validate.

sm_msg_del
sm_msg_read
Initial releases of the Panther documentation did not have an updated list of the message prefixes or message classes. FM_MSGS, JM_MSGS and JX_MSGS messages are now located in SM_MSGS. The value for WB_MSGS has also been updated.

sm_prop_get_str
The documentation has been updated to say that this function stores the returned data in a pool of buffers that it shares with other functions so you need to copy or process this data immediately.

Traversal properties for table views
Traversal properties for table views and server views in the transaction manager return the table view or server view name as a string, not as an object ID.

Quick Reference Changes and Corrections

The Panther Quick Reference which was printed in November 1999 does not have the following changes.

Configuration

Text Selection Keys - Windows
Refer to "Text Selection" for the list of new logical keys.

SMIBMVJAVA, SMPROVIDERURL, SMTPCLIENT, SMTPINIT, SMWSADMIN
Refer to "WebSphere Variables" for a description of the configuration variables in Panther for IBM WebSphere.

Functions

sm_com* Functions
The functions for components supersede the functions for COM components released in Panther 4.0 and 4.1.

COM Function Panther 4.2 Replacement

sm_com_call_method

sm_obj_call

sm_com_get_prop

sm_obj_get_property

sm_com_log

sm_log

sm_com_obj_create

sm_obj_create

sm_com_obj_destroy

sm_obj_delete_id

sm_com_onerror

sm_obj_onerror

sm_com_raise_exception

sm_raise_exception

sm_com_receive_args

sm_receive_args

sm_com_return_args

sm_return_args

sm_com_set_prop

sm_obj_set_property

sm_obj_sort, sm_obj_sort_auto
New functions for sorting data in arrays and grids.

Properties

Column Click Action (column_click_action)
For widgets in grids, under Format/Display, specify the action–sort or custom function–that occurs when a user clicks on the grid column column header.

Column Click Function (column_click_func)
For widgets in grids, under Format/Display, specify the custom function to invoke when a user clicks on the grid column column header. For this property to be available, Column Click Action must be set to Custom.

Connection Pooling (conn_pool_size)
In Panther/WebSphere applications, specify the number of concurrent database connections.

Current Component System (current_component_system)
A runtime-only property that instantiates the type of component system currently in use. Before creating any service components, set this property to PV_SERVER_COM for COM components or PV_SERVER_EJB for Enterprise JavaBeans deployed under WebSphere Application Server.

HTML Max Loop (html_max_loop)
For HTML templates using condition processing, specify the number of loop iterations to perform before terminating the process. The default setting is 1000.

HTML Max Nest (html_max_nest)
For HTML templates using condition processing, specify the number of nesting levels. Each if, while, or include constitutes one level. The default setting is 20.

In Server (in_server)
A new value for Panther/WebSphere applications, PV_SERVER_EJB.

Max Bundles (max_bundles)
A runtime-only application property specifying the number of JPL bundles available for send and receive commands. It defaults to ten bundles (including the unnamed bundle) if unspecified.

Provider URL (provider_url)
For Panther/WebSphere applications, a runtime-only application property specifying the location of the WebSphere application server machine. If SMPROVIDERURL is set in the environment, the property is initially set to this value.

Runtime License (runtime_license)
For ActiveX controls which support runtime licensing, if the Runtime License property exists, the control will be created using the license.

Sort Order (sort_order)
Under Format/Display, specify the sort order to be used when the widget is in an array or in a grid. If the widget is in a grid, the Column Click Action property must also be set to Sort.

Sort Order Function (sort_order_func)
Under Format/Display, specify the custom function to be invoked when Sort Order is set to Custom. The function can be either a JPL procedure or prototyped C function.

Utilities

formlib
New -m option for compacting the library.

makeejb
Panther/WebSphere utility for generating the Java files for EJBs from the service components in an application library.