Using ZIETrans administrative console

The ZIETrans administrative interface can be used to manage connections and perform problem determination for ZIETrans Web applications. This chapter describes how you can use these management functions.

You can include the ZIETrans administrative console support files with the set of ZIETrans applications contained within an Enterprise Archive (.ear) file deployed to WebSphere® Application Server. The deployed .ear file provides a runtime environment, in which the ZIETrans administrative console enables you to manage ZIETrans applications. If you include the ZIETrans 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 ZIETrans administrative console support files in each .ear file, you can create an .ear file that contains only ZIETrans administrative console files. When you deploy this .ear file, you can start the ZIETrans administrative console and change the management scope to remotely manage ZIETrans applications in multiple .ear files with one instance of the administrative console. The deployed ZIETrans administrative console application gives you a single point of administration for all ZIETrans applications. When you create a new ZIETrans project, you specify whether to include ZIETrans administrative console files in the project. If you create a ZIETrans administrative console project, you no longer need to add the administration support files to other projects you create.

To create a ZIETrans administrative console project in ZIETrans Toolkit, follow the path File > New > Project > ZIETrans > ZIETrans Administration Project. You should specify an Enterprise Application project name that uniquely identifies this project as the ZIETrans administrative console project. The ZIETrans administrative console project only appears in ZIETrans Toolkit on the Navigator tab. Deploy the .ear file you created to WebSphere Application Server and start it (see Starting ZIETrans administrative console). To change the scope of management for the ZIETrans administrative console project, refer to Selecting management scope.

Other administration topics are described in Display terminal functions.

ZIETrans administrative console and WebSphere security

The ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans application with ZIETrans administrative capabilities, you can map each of three ZIETrans roles to particular system user IDs for security. The three defined ZIETrans roles (ZIETransAdministrator, ZIETransOperator, and ZIETransMonitor) each have different capabilities within the ZIETrans administrative console. For more information see ZIETrans 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 ZIETrans 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 ZIETrans role can connect to the ZIETrans administrative console in a ZIETrans application, and can perform administration tasks within that specific ZIETrans application only. If the user tries to change the management scope to remotely administer another ZIETrans 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 ZIETrans 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 ZIETrans administrative console will not display any other ZIETrans 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 ZIETrans applications, and the user can change scope from one application to another. However, the information shown in the ZIETrans 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 ZIETrans administrative console.

Option 1: Keep ZIETrans and WebSphere Application Server user roles separate
If you do not want to give any WebSphere Application Server administration authority to any of the user IDs that are mapped to ZIETrans roles, then you must include the ZIETrans administrative console in every ZIETrans application, and you will need to administer each ZIETrans application separately using the ZIETrans administrative console for that specific application. You will not be able to use remote administration.
Option 2: Combine ZIETrans and WebSphere Application Server user roles
If you want to use the ZIETrans administrative console in a single ZIETrans application to remotely administer other ZIETrans applications by changing the management scope, then the user IDs that are mapped to ZIETrans roles must also be defined in WebSphere Application Server as WebSphere administrative console users with either Administrator role or Operator role. These users will be able to change the management scope in the ZIETrans administrative console, and they will be able to perform the other ZIETrans administrative tasks that are allowed for the specific ZIETrans role to which they are mapped. In addition, the users will also be able to log into the WebSphere Application Server administrative console and perform WebSphere administrative tasks that are allowed for the WebSphere Application Server administrative console user role to which they are mapped.

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 ZIETrans roles must also be mapped to WebSphere Application Server Administrator or Operator roles in order for ZIETrans remote administration to function properly.

ZIETrans administrative console roles

ZIETrans 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 ZIETrans administrative tasks. The security functions used by ZIETrans are based on the Java EE form-based authentication process. When WebSphere Application Server security is enabled, ZIETrans administrative console operations are restricted based on the role defined for a user ID. There are three roles defined for use of the ZIETrans administrative console. Each role has different capabilities.

ZIETransAdministrator
This role has full administration capability, able to do all of the following tasks: By default, the ZIETransAdministrator role is mapped to "All Authenticated" users.
ZIETransOperator
This role is equivalent to the ZIETransAdministrator role, but cannot access potentially sensitive data. A user with this role cannot enable display terminal tracing, nor download trace files.
ZIETransMonitor
This role only allows the user to view non-sensitive data, such as active connections, connection pools, user lists, and logs. A user with this role cannot change any settings, such as license management settings, log and trace file options, display terminal settings, nor download trace files.

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 ZIETrans 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 ZIETrans role.

Starting ZIETrans administrative console

The ZIETrans administrative console is Web-based. You perform administration tasks using a Web browser, through a user interface provided by the ZIETrans administrative console servlet, ZIETransAdminServlet.

To start the ZIETrans administrative console, load this URL in your browser: http://host:port/appname/ZIETransadmin/admin, where host is your host name, port is the port number of HTTP transport of the application server on which the ZIETrans application is running and appname is the name of a ZIETrans application that includes administration support.

Note:
The port specification is not needed if URL requests are directed to a Web server configured for WebSphere.

When you start the ZIETrans 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.

Notes:
  1. If cookies are disabled for the browser accessing the ZIETrans administrative console, the following changes occur:
    • The ZIETrans administrative console does not keep track of the user's language preference.
    • The language of the browser is determined by the browser's preferred language, based on the Accept-Language header.
    • The language selection choice does not appear in the ZIETrans administrative console preferences.

Starting the administrative console while in ZIETrans Toolkit

The ZIETrans administrative console can be started in ZIETrans Toolkit, using either Debug on Server or Run on Server mode.

To launch the ZIETrans administrative console for a particular project, right-click the project in the ZIETrans 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 ZIETrans Getting Started.

The runtime settings you change when running the administrative console in the ZIETrans Toolkit depends on which mode you are using. For more information, see Administering problem determination components.

Using the functions in ZIETrans administrative console

This section guides you through the various functions in the ZIETrans administrative console.

Selecting management scope

You can select the scope of management. ZIETrans 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 ZIETrans enterprise application (.ear) of the ZIETrans application used to access the ZIETrans administrative console. You can change the scope of management to manage other ZIETrans enterprise applications deployed within the same WebSphere cell.

The key to changing management scope is providing the host and port information for ZIETrans administrative console to locate installed ZIETrans 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 ZIETrans enterprise applications deployed to that resource. Specifying a host and port of a WebSphere node enables administration of all ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans administrative console must be the server ID used by WebSphere for accessing LDAP.

Managing licenses

There are two panels under the License Management heading in the left navigation frame for managing license information:

Monitoring connections

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.

Monitoring connection pools

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.

Monitoring pool definitions

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.

Monitoring user lists and user list members

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.

Administering problem determination components

The ZIETrans 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 ZIETrans 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 ZIETrans enterprise application.

When you change settings while accessing the ZIETrans administrative console running in a local test environment in the ZIETrans 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 ZIETrans Toolkit. You can also edit the files directly to change settings. The files are located in the root of the .ear project in the ZIETrans Toolkit. Be aware that any changes made to the runtime.properties file in the ZIETrans Toolkit are retained and become effective when you deploy the ZIETrans application to a runtime environment. The runtime-debug.properties file is ignored in the runtime environment.

Note:
When running on WebSphere Application Server for z/OS®, the runtime.properties file must be edited with an ASCII editor. This can be done by transferring the file to a workstation, for example using FTP, editing the file and transferring it back. Also, there is a copy of runtime.properties for every active Servant within an application server (distinguished with the Address Space ID of the Servant). The base runtime.properties file should be changed for changes to persist across application server restarts.

For more information about log and trace settings in these files, see Appendix A. Runtime properties files.

Log and trace file names

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 ZIETrans 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.

Note:
When running on WebSphere Application Server for z/OS, an application server can have more than one Servant running, with each Servant generating unique log and trace files. To distinguish these, the server component of the name is prefixed with the Address Space ID (ASID) of the Servant (example: trace_asid_1.txt).

View Log

Using the View Log panel, you can view the ZIETrans log file, download the entire file, or clear the file. The log file records information about two kinds of events:

Error events
Problems that prevent an operation from completing. Error events typically require that you take some action to correct the problem.
Warning events
Unexpected occurrences that might require action to correct the problem. Warning events are not as serious as error 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 ZIETrans Messages. That publication contains suggestions for actions you can take to correct problems, when necessary.

Note:
In Windows, you cannot rename or delete the standard output and standard error logs while ZIETrans applications are running. If you want to rename or delete these logs as part of troubleshooting procedures, to reclaim disk space, or to minimize the size of an information bundle file, you must stop the application server representing ZIETrans. However, the WebSphere node can remain running.

Set Log Options

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.

Set Trace Options

Using the Trace Settings panel, you can select one or more of the following types of trace options:

Enable Runtime Tracing
Enables tracing in ZIETrans runtime for connections in your project. To trace these runtime connections at a different level, see Appendix A. Runtime properties files for information about the trace settings.
Enable Widget Tracing
Enables tracing in ZIETrans runtime for widgets in your project. To trace widgets at a different level, see Appendix A. Runtime properties files for information about the trace settings.
Enable Action Tracing
Enables tracing in ZIETrans runtime for event actions in your project. To trace events at a different level, see Appendix A. Runtime properties files for information about the trace settings.
Enable Component Tracing
Enables tracing in ZIETrans runtime for components in your project. To trace components at a different level, see Appendix A. Runtime properties files for information about the trace settings.
Enable Util Tracing
Enables tracing in ZIETrans runtime for runtime utilities in your project. To trace these runtime utilities at a different level, see Appendix A. Runtime properties files for information about the trace settings.
Integration Object Tracing
Enables tracing in specific Integration Objects in your project. Use the Class Name specification field to specify which Integration Objects to trace, using one or more patterns. Each pattern can contain one or more wildcard (*) character. For example, IntegrationObject.Callup* specifies that tracing is enabled for all Integration Objects that start with the letters Callup. To trace all Integration Objects, specify IntegrationObject.*. If multiple patterns are specified, they should be delimited with commas. ZIETrans administrative console sets the Integration Object setting to the maximum trace level. To trace Integration Objects at a different level, see Appendix A. Runtime properties files for information about the trace settings.
Applet Tracing
Enables tracing of the applet. The higher level of trace will produce more tracing information. When applet tracing is turned on, it will output server side messages for troubleshooting. For more information about applet trace settings, see Appendix A. Runtime properties files.
User Macro Tracing
Traces the playing of macros. Because it affects system performance, we recommend that you use this trace only for debugging macros.
Display Terminal
Enables you to view the host terminal screen of any connection as it runs in real time on the server. After you enable the display terminal, the terminal settings are shown only for newly created connections. For more information about the Display Terminal, see Using display terminal for testing and debugging.
Note:
You can decide whether ZIETrans should display a dialog asking you if you want to turn on the display terminal when you Run on Server. For more information, see Using ZIETrans preferences.
Record Host Simulation Trace
Select the Enable Host Simulation Recording box to enable host simulation recording during runtime. Recording starts the next time a host session starts and ends when the host session is closed, for example when the user clicks the disconnect button on the application keypad. If the user closes the Web browser while tracing is active, the trace will continue until the HTTP session times out. The trace file is saved in the host simulations folder on the server, for example, <WebSphere install root>\AppServer\profiles\AppSrv01\installedApps\<Node ID>\<ear file name>\<ApplicationName>.war\WEB-INF\profiles\hostsimulations. Trace files are named using the following template, ApplicationName_ConnectionName_Date(yyyymmdd)_Time(hhmmss)_Number, for example, MyApplication_main_20060101_134543_1.

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.

Trace Output
Enables you to control whether trace information is written to the trace file, and define the file to which the log events are written. See Log and trace file names for information about how trace files are named. If the file already exists, new trace information is appended to it. You can also define how many trace files to keep and the maximum size of each trace file.

Display terminal functions

Using display terminal for testing and debugging

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 ZIETrans 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 ZIETrans administrative console includes a Toggle Display Status button that turns display terminal on and off for selected connections.

CAUTION:
Turning on the display terminal option can seriously affect performance or overload the server. Do not use this on servers with many connections. Display terminal is intended for use in debugging during application development on a test system; it is not intended for use on a heavily loaded production server.

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.

Notes:
  1. For the display terminal to work properly when WebSphere Application Server is started as a service on the Windows platform, you must select Allow service to interact with desktop in the service settings for WebSphere Application Server.
  2. For the display terminal to work properly with WebSphere Portal V7 on the Windows platform, the portal server must be started as a normal Windows process and not as a Windows service.
  3. For information about displaying graphics, required for the display terminal function, using the Native Abstract Windowing Toolkit (NAWT) on the IBM i platform, see the section, Running your Java application on a host that does not have a graphical user interface, in one of the following documents as appropriate,
  4. For information about configuring the display terminal functions on other platforms, see the section, IBM i, z Systems, and Unix platform-specific information, in the ZIETrans Infocenter at https://zietrans.hcldoc.com/help/index.jsp.