The HATS administrative interface can be used to manage connections and perform problem determination for HATS Web applications. This chapter describes how you can use these management functions. For information related to HATS rich client applications, see Administering HATS rich client applications.
You can include the HATS administrative console support files with the set of HATS applications contained within an Enterprise Archive (.ear) file deployed to WebSphere® Application Server. The deployed .ear file provides a runtime environment, in which the HATS administrative console enables you to manage HATS applications. If you include the HATS administrative console files in multiple projects, more than one administrative console can be started using different application names; however, each administrative console provides the same views and functions.
Instead of including the HATS administrative console support files in each .ear file, you can create an .ear file that contains only HATS administrative console files. When you deploy this .ear file, you can start the HATS administrative console and change the management scope to remotely manage HATS applications in multiple .ear files with one instance of the administrative console. The deployed HATS administrative console application gives you a single point of administration for all HATS applications. When you create a new HATS project, you specify whether to include HATS administrative console files in the project. If you create a HATS administrative console project, you no longer need to add the administration support files to other projects you create.
To create a HATS administrative console project in HATS Toolkit, follow the path File > New > Project > HATS > HATS Administration Project. You should specify an Enterprise Application project name that uniquely identifies this project as the HATS administrative console project. The HATS administrative console project only appears in HATS Toolkit on the Navigator tab. Deploy the .ear file you created to WebSphere Application Server and start it (see Starting HATS administrative console). To change the scope of management for the HATS administrative console project, refer to Selecting management scope.
Other administration topics are described in Display terminal functions.
The HATS administrative console uses a Java™ Management Extensions (JMX) bean to perform remote administration. When WebSphere Application Server global security is enabled, these JMX calls are authenticated by WebSphere security and must have a valid level of authorization in WebSphere. Consequently, remote administration from the HATS administrative console does not work properly unless the user ID is defined as a WebSphere Application Server administrative console user with either Administrator or Operator authority.
The HATS administrative console allows you to view and change problem determination settings. It also allows you to view connection status or disconnect host connections. When you deploy a HATS application with HATS administrative capabilities, you can map each of three HATS roles to particular system user IDs for security. The three defined HATS roles (HATSAdministrator, HATSOperator, and HATSMonitor) each have different capabilities within the HATS administrative console. For more information see HATS administrative console roles.
Similarly, the WebSphere Application Server administrative console allows you to view and change the configuration of the WebSphere Application Server environment. It enables you to install, start, stop, and uninstall Web applications such as HATS applications. There are WebSphere console user roles (Administrator, Configurator, Operator, or Monitor) that provide different capabilities within the WebSphere Application Server administrative console. The following links from the WebSphere Application Server Knowledge Center provide additional detail on these security roles and policies:
If WebSphere global security is enabled, the users IDs that have a HATS role can connect to the HATS administrative console in a HATS application, and can perform administration tasks within that specific HATS application only. If the user tries to change the management scope to remotely administer another HATS application, WebSphere security will check the authority of the user ID. If the user ID is not a valid WebSphere Application Server administrative console user with Administrator or Operator authority, the JMX calls will be blocked and HATS remote administration will not function properly.
For example, if the user ID is either not defined as a WebSphere Application Server administrative console user at all, or defined with only Monitor authority, the Select Application list under Management Scope in the HATS administrative console will not display any other HATS applications. It will not be possible to change the management scope because no other applications are listed.
As another example, if the user ID is defined as a WebSphere Application Server administrative console user with Configurator authority, the list will show other HATS applications, and the user can change scope from one application to another. However, the information shown in the HATS administrative console may be incorrect, and any changes attempted through remote administration will not take effect.
Therefore, if WebSphere global security is enabled two options exist for using the HATS administrative console.
For either option, if WebSphere global security is enabled, ensure the Enable application security option is selected. For WebSphere Application Server V6.x, from the WebSphere administrative console, select Security > Secure administration, applications, and infrastructure > Application security > Enable application security. For WebSphere Application Server V7.x and v8.x, from the WebSphere administrative console, select Security > Global security > Application security > Enable application security.
In summary, if WebSphere global security is enabled, the user IDs that are mapped to any HATS roles must also be mapped to WebSphere Application Server Administrator or Operator roles in order for HATS remote administration to function properly.
HATS administrative console is bound to WebSphere security. This means that when WebSphere Application Server security is enabled, your system administrators must have proper authentication to perform HATS administrative tasks. The security functions used by HATS are based on the Java EE form-based authentication process. When WebSphere Application Server security is enabled, HATS administrative console operations are restricted based on the role defined for a user ID. There are three roles defined for use of the HATS administrative console. Each role has different capabilities.
The mapping of roles to users or groups of users is performed using the WebSphere administrative console.
For WebSphere Application Server V6.x, ensure the All Authenticated option on the Map security roles to users/groups panel is checked for the appropriate HATS role. For WebSphere Application Server V7.x and V8.x, ensure the All Authenticated in Application Realm option is selected using the Map Special Subjects drop-down on the Map security roles to users/groups panel for the appropriate HATS role.
The HATS administrative console is Web-based. You perform administration tasks using a Web browser, through a user interface provided by the HATS administrative console servlet, HATSAdminServlet.
To start the HATS administrative console, load this URL in your browser: http://host:port/appname/hatsadmin/admin, where host is your host name, port is the port number of HTTP transport of the application server on which the HATS application is running and appname is the name of a HATS application that includes administration support.
When you start the HATS administrative console, it uses the default language of the server. You can, however, change the language by selecting Preferences in the navigation frame, choosing the language you want, and restarting the browser. The new language choice remains in effect for that browser until you select another language in Preferences.
The HATS administrative console can be started in HATS Toolkit, using either Debug on Server or Run on Server mode.
To launch the HATS administrative console for a particular project, right-click the project in the HATS Projects view, and click Open Administrative Console.
If the project is not already running in a local test environment, then it is launched using Debug on Server mode and a Web browser page is opened to the administrative console URL.
If the project is already running using Run on Server mode, then a prompt is displayed that informs you that the server is not running in Debug mode. If you select the option, Continue in the current mode, the administrative console will open in Run on Server mode.
For more information about running in different test modes see Testing modes for Web projects in HATS Getting Started.
The runtime settings you change when running the administrative console in the HATS Toolkit depends on which mode you are using. For more information, see Administering problem determination components.
This section guides you through the various functions in the HATS administrative console.
You can select the scope of management. HATS administrative console maintains a list of the management scopes for the life of the HttpSession. The initial scope of management is selected by default as the HATS enterprise application (.ear) of the HATS application used to access the HATS administrative console. You can change the scope of management to manage other HATS enterprise applications deployed within the same WebSphere cell.
The key to changing management scope is providing the host and port information for HATS administrative console to locate installed HATS enterprise applications. The port value specified must be an active WebSphere BOOTSTRAP_ADDRESS port. WebSphere application servers, nodes, and cells each have a BOOTSTRAP_ADDRESS port. Specifying the port value for one of these WebSphere resources enables administration for the HATS enterprise applications deployed to that resource. Specifying a host and port of a WebSphere node enables administration of all HATS enterprise applications installed on that node. Refer to WebSphere Application Server documentation for more information about the BOOTSTRAP_ADDRESS port.
In a secured environment, an administrator may see the following message in the HATS administrative console while trying to change the scope of administration:
There was a problem in trying to manage the scope you selected. There are no HATS applications found. Your management scope has not been changed.
This may occur because in a WebSphere secured environment, the user is not authorized to carry out the communication required to populate the list of available applications to be administered.
If WebSphere is using the local operating system as the user registry, the username used to access the HATS administrative console must have Administrator rights in the local operating system registry. If WebSphere is using LDAP as the user registry, the username used to access the HATS administrative console must be the server ID used by WebSphere for accessing LDAP.
There are two panels under the License Management heading in the left navigation frame for managing license information:
There are separate panels under the Connection Management heading in the left navigation frame with which you can monitor the different types of connections:
Each connection shown in these displays represents a communication link to a back-end data source, such as a 3270 application or a database. The displays enable you to see details about which users are connecting to which data sources, and which connection identifiers they are using. If an LU or Pool name exists for a 3270 connection, it is also displayed. You can also shut down sessions.
The Connection Pools panel under the Connection Management heading in the left navigation frame displays information about defined connection pools. A connection pool is not listed until at least one connection is allocated from the pool.
Connection pools are collections of communication links to back-end data sources, such as 3270 applications or databases. When an Integration Object or an application is run on behalf of a client request, it obtains an available connection from a pool, uses it for access to the data source, then returns the connection to the pool. When connection pooling is enabled, the processor usage of establishing a connection is absorbed in its first use. Each reuse of this connection benefits from the prior establishment of the connection and can run faster.
The Connection Pool Definitions panel under the Connection Management heading in the left navigation frame displays pool definition information for host and database connections. A pool definition is not listed until at least one connection is allocated from the defined pool.
A pool definition provides information about a collection of data source connections. Some related definitions are associated with a pool definition; for example, connection and macro definitions and user list name. In addition to creating associations between several other definitions, the pool definition provides configuration parameters for all connections in the pool, such as minimum and maximum pool size (in terms of number of active connections) and connection timers.
The User Lists panel under the User Management heading in the left navigation frame displays information about user lists.
User lists identify the user IDs and other connection-specific parameters associated with a particular connection pool definition. For systems that allow only a single connection per user ID, the number of user IDs determines the number of connections that can be active in a single pool.
The HATS administrative console enables you to monitor logging and tracing to help you resolve problems. You can view the messages in the log, and change log and trace settings by selecting the links under the Troubleshooting heading in the left navigation frame. Properties files maintain settings for these problem determination aids.
When you change settings while accessing the HATS administrative console running in a runtime environment, the changes are saved in the runtime.properties file. Although not recommended, you can also edit the file directly to change settings. The file is located in the was_dir/installedApps/ear_name directory for a HATS enterprise application.
When you change settings while accessing the HATS administrative console running in a local test environment in the HATS Toolkit, the changes are saved in one of two different files. Changes are saved in the runtime.properties file, when running in Run on Server mode, and in the runtime-debug.properties file, when running in Debug on Server mode. For more information, see Starting the administrative console while in HATS Toolkit. You can also edit the files directly to change settings. The files are located in the root of the .ear project in the HATS Toolkit. Be aware that any changes made to the runtime.properties file in the HATS Toolkit are retained and become effective when you deploy the HATS application to a runtime environment. The runtime-debug.properties file is ignored in the runtime environment.
For more information about log and trace settings in these files, see Appendix A. Runtime properties files.
The base log and trace file names in runtime.properties are used as templates to generate unique sets of log and trace files for each application server. The default base trace file name is trace.txt; the default base log file name is messages.txt. The application server name is appended to the base file name to generate the template for the log and trace files for an application server. The application server name is the same as the fully qualified name of the application server, as defined by WebSphere. This name is cell_node_server, where:
The application server running HATS is the concatenation of the underscore (_) character, followed by the application server name, followed by another underscore (_) character.
Using the trace file as an example, the name becomes trace _cell_node_server_.txt. Finally, an index (1, 2, 3, and so on) is added to this name to distinguish multiple files. With multiple trace files configured, the trace file names for this application server are trace_cell_node_server_1.txt, trace_cell_node_server_2.txt, and so on.
Using the View Log panel, you can view the HATS log file, download the entire file, or clear the file. The log file records information about two kinds of events:
The log file is intended for you to read and use as a reference when troubleshooting problems. Most of the messages that appear in the log are documented in HATS Messages. That publication contains suggestions for actions you can take to correct problems, when necessary.
Using the Log Settings panel, you can control whether information and warning events are written to the log file, and define the file to which the log events are written. See Log and trace file names for information about how log files are named. If the file already exists, new events are appended to it. Error events are always written to the log file. You can also define how many log files to keep and the maximum size of each log file.
Using the Trace Settings panel, you can select one or more of the following types of trace options:
In order to trace multiple host sessions concurrently, host simulation uses multiple TCP/IP ports. Use the TCP/IP Port Range for Recording fields to set the range of port numbers for server runtime usage. The default starting port in the range is 7021, and the default ending port is 7050.
When debugging applications on a test system, you can control whether a terminal window that displays host screens is created on the server display. You can use host screens displayed in the terminal window to observe interactions between the HATS applications and the host application at runtime. You can also interact with the host application using the host screen in the terminal window. Terminal screens are created only for connections established while this option is turned on. They are not created for existing connections or for connections that are idle. However, the Host Connections panel in HATS administrative console includes a Toggle Display Status button that turns display terminal on and off for selected connections.
You can turn display terminal on for any new host connections by selecting the Enable Display Terminal box on the Trace Settings panel under the Troubleshooting heading in the left navigation frame; however, you can use Toggle Display Terminal on the Host Connections panel to turn display terminal on and off for a particular connection at any time, regardless of whether you have selected the Enable Display Terminal box on the Trace Settings panel.