This technical information is for HATS V4, formerly known as Host Access Transformation Server
Deploying HATS applications on a zSeries server
You can deploy a Host Access Transformation Server (HATS) application to a WebSphere Application Server running on a zSeries server to transform 5250 or 3270 applications residing on that machine or on other server systems.
Running a HATS application on zSeries requires:
- HATS Fix Pack 4.0.2 (APAR IC35970)
- zSeries server platforms:
- OS/390 V2R10
- zOS v1.1 or higher
- WebSphere Application Server V4.0.1 for z/OS and OS/390 Service level W401404 (PTF UQ71461) or later Service level.
- To see the currently available PTFs, go to WebSphere Application Server for z/OS
- For the WebSphere for OS/390 and z/OS system requirements and other documentation, see WebSphere Application Server
- For installation and configuration steps required to provide session affinity support across multiple J2EE server instances or multiple server regions per server instance, refer to WebSphere Application Server Version 4.0.1 for z/OS and OS/390: WebSphere HTTP Plug-in for z/OS (APAR PQ68250, Service Level W401500) documentation at WebSphere Application Server for z/OS
This documentation is intended to describe anything that is unique about HATS on z/OS and OS/390. It is expected that you also use HATS Getting Started, and the HATS Developer's Guide as sources of information on HATS, and that you review the HATS Readme.
This document includes the following information:
Preparing your HATS project for use as a Web application on z/OS and OS/390
After you develop a HATS project, follow these steps to convert the project to a WebSphere application and make it ready for use on a server.
Note: The terms "HATS application", "WebSphere application", and "J2EE application" can be used interchangeably to refer to an application created from a HATS project. It is a HATS application because it was developed in the HATS Studio. It is a WebSphere application because it will be deployed and run on WebSphere Application Server. It is a J2EE application because it conforms to the J2EE standards.
Assembling the project into an application
You have created a HATS project and customized it to provide a usable representation of your host application. IBM recommends that you do "Run on Server" on the development platform to insure the application is working as you want. Now you're ready to put it into production on a Web server.
To assemble the project into a J2EE application, follow these steps:
- Highlight (single-click) the name of your project in the HATS Project View under the HATS Perspective.
- Click the Assemble HATS Project icon on the main tool bar, or click the project name and select Assemble HATS Project.
- In the Export window, choose an Enterprise Application project from the drop-down list or type the name of an Enterprise Application project in the What resources do you want to export? field.
- Type the name of a directory and file name in the Where do you want to export resources to? field (or click Browse and then select a directory and file name).
- If you want to export the project's source files along with the executable files, check the Export source files box. If you include the source files, another developer can extract them from your .ear file. This can make collaboration or service easier, but you must decide whether it creates a security risk.
- If you have exported this project to this location before, the export process asks whether you want to overwrite the existing files. This is intended to protect you from overwriting files that you might want to keep, perhaps to archive a previous version of your project. If you want to overwrite previous files without being asked for confirmation, check the Overwrite existing resources without warning box.
- Click Finish. The project is assembled into a J2EE application, represented by an Enterprise Archive file with extension .ear, with the directory and file name you specified.
Grouping your applications
You can group your HATS applications together in one .ear file, or store each in its own separate .ear file. These options are discussed in HATS Developer's Guide. Be sure your HATS applications are grouped in the way you want before you deploy them to WebSphere Application Server.
Deploying the application on a server
Assumptions for Installation and Recommendations
- You must have a correctly running and configured IBM WebSphere Application Server V4.0.1 (FMID H28W401) at minimum PTF UQ71461.
- The Installation Verification Program (IVP) for IBM WebSphere Application Server must have been configured, run, and working correctly including the web container.
- IBM recommends that you increase your DB2 User LOB Value Storage (LOBVALA) and System LOB Value Storage (LOBVALS) to values of at least 20000. You may experience SQL errors when loading the large HATS EAR files if you do not increase these two parameter values.
- IBM recommends that on your WebSphere Administration Application workstation you have at least 512M of memory. You may experience java language out of memory errors if you do not have at least 512M on your Windows machine if you are installing large HATS ear files.
- IBM also recommends that you configure at least 512M as your Systems Management Server Region Heap size.
IBM WebSphere Application Server for z/OS and OS/390 (Administration & Operations):
You must use the IBM WebSphere Application Server for z/OS and OS/390 Administration and Operations Utility (SM EUI) to deploy your HATS J2EE application EAR file. The SMEUI executable can be ftpped from the following directory on your z/OS system (assuming you have installed to the default /usr/lpp/WebSphere directory):
/usr/lpp/WebSphere/bin/bboninst.exe
Add Your HATS Applications using WebSphere Administration Application:
This step will add your HATS applications to the IBM WebSphere Application Server. Your HATS EAR can be deployed to the BBOASR2 Application Server defined for the IVP or to whatever server you defined for the IVP. Replace BBOASR2 with your server name in the following sections. Follow these steps carefully to add your applications.
If it is not started, start your IBM WebSphere for z/OS Administration Application (SM EUI). If necessary, log into your Bootstrap server using the correct server IP name, port, USERID, and password.
Modifying the BBOASR2 server:
- Add a new conversation called HATS Conversation.
- Drill down to BBOASR2 (Follow the tree to Sysplexes, your_sysplex, J2EEServers, BBOASR2).
- Change the following settings:
- Isolation policy - Multiple transactions per server region
- Allow server region recycling - Clear the check box
- Add the following environment variables:
- BBOO_WORKLOAD_PROFILE=LONGWAIT
- BBOO_SKIP_DESTROYJAVAENV=YES
- BBOO_ACCEPT_HTTP_WORK_AFTER_MIN_SRS=1 (1 means true, default is 0)
- MIN_SRS=x (set accordingly based on number of concurrent users)
- If you have configured the HTTP(S) Transport Handler, we have had the most success with the following values when running a large number of concurrent users (note that these values may need to be adjusted for your environment):
- BBOC_HTTP_INPUT_TIMEOUT=0
- BBOC_HTTP_OUTPUT_TIMEOUT=0
- BBOC_HTTP_MAX_PERSIST_REQUESTS=1
- BBOC_HTTP_PERSISTENT_SESSION_TIMEOUT=0
For information about these environment variables, see WebSphere Application Server Library Page
Adding HATS.ear as a BBOASR2 J2EEApplication
- Drill down to BBOASR2 (Follow the tree to Sysplexes, your_sysplex, J2EEServers, BBOASR2).
- Click on BBOASR2 and select Install J2EE application.
- Enter in the EAR Filename box, your workstation path and exported HATS EAR file name (i.e.,c:\XXX\export\HATS.ear) or use the 'Browse EAR File' button to browse for your exported EAR.
- Click OK to Load your EAR file. You may get message:
BBON0889I At least one....which is normal and can be ignored, click OK - When the Reference and Resource Resolution screen is displayed Click on the node to the left of HATS_WebApp.Jar to expand (the HATS_WebApp.jar 'bean' should now be expanded).
- Click on the HATS_WebApp bean and click the Set Default JNDI Path & Name box. This will set default JNDI Path & Names for the HATS_WebApp bean. Make sure that all beans now have green checks.
- Click OK to add to J2EEApplications on your host system. You will receive the following message:
BBON0470I Ear file HATS_resolved.ear has been successfully installed on server BBOASR2.
Validate, Commit, Complete and Activate Your HATS Conversation
The next step is to validate, commit, complete, and activate your newly created HATS conversation. These steps should be the same as with activating any new conversation.
- To validate, click on your HATS Conversation and select Validate. You will know the validation was successful when you receive the following message:
BBONO442I Conversation HATS Conversation is valid. - To commit, click on your HATS Conversation and select Commit. Answer Yes to the question:
BBON0534I You cannot undo Commit, Do you still want to commit?
The words "Committing... HATS Conversation" appear and you know you are done when the following message appears in the status area:
BBON0444I Conversation HATS Conversation was committed. - You must now complete all required tasks and mark as complete. To complete click on your HATS Conversation and select Complete, then All tasks. Answer Yes to the question:
BBON0550I Are you sure that all tasks have been completed?
You know you are done when the following message appears in the status area:
BBON0484I All tasks complete. - To Activate your HATS Conversation, click on your HATS Conversation and select Activate. Answer Yes to the question:
BBON0539I Active cannot be undone. Do you want to activate conversation HATS Conversation?
The words "Activating... HATS Conversation" appear and your conversation is successfully activated when you receive the following message:
BBON0449I Conversation HATS Conversation was activated.
Modify Your BBOASR2A Server Region Files:
When you deploy your HATS applications, if you have more than one HATS application in an .ear file, you must configure your application server to set its module visibility to Application. Please refer to HATS Developer's Guide for more information. You will need to add the following to the jvm.properties file:
com.ibm.ws390.server.classloadermode=2
Starting Your Application Servers
You will first need to start your Application server and server instance that you are using for your HATS applications, BBOASR2.
Note: IBM recommends that your BBOASR2S Server PROC uses default LE stack sizes of 1024K. Also, to avoid Conversation Activate errors if re-deploying a HATS ear after a /logs directory has been created (see HATS Logging and Tracing on z/OS and OS/390), add the ENVAR parm below with a umask value of 002 to your server region proc. This means that files created by applications running in the server region will have permission bits set to 775. This will allow the /logs directory to be deleted when re-deploying.
Follow the example below to code the LE stack size and ENVAR parm as part of your EXEC PGM=BBOSR statement in your PROC.
//BBOASR2SEXECPGM=BBOSR,REGION=0M,TIME=NOLIMIT,
// PARM='STACK(1024K,1024K,ANY) ENVAR("_EDC_UMASK_DFLT=002") X
// / &PARMS &IWMSSNM'
1. Start the BBOASR2A server instance. Enter at your console the following:
s bboasr2.bboasr2a
2. You will also see the following messages when your Application Server is ready:
+ Server "BBOASR2A" open for business
Starting your HATS application
To access the HATS application that you have deployed to WebSphere Application Server BBOASR2, enter in the URL area of your browser
http://<webserver name>/<appname>/entry
where webserver name is your webserver name or IP address and appname is the name of a HATS application in the .ear file.
Unique HATS functionality on z/OS and OS/390
Enabling graphics support for HATS on z/OS and OS/390
HATS enables you to transform host data such as tables into graphs on a Web page. APAR PQ69797 is required in order to support the complete graphing capabilities of HATS applications running on zSeries. These HATS applications require the Java Abstract Windowing Toolkit (AWT) and therefore need access to an Xwindows server. Refer to APAR PQ69795 for additional configuration information required; namely, setting the DISPLAY environment variable in the application server's current.env file to the address of your Xwindows server.
HATS Logging and Tracing on z/OS and OS/390
HATS logging and tracing are controlled by the runtime.properties file
The runtime.properties file is located in
CBCONFIG/apps/SRVNAME/<webapp>.ear
for example:
/u/WebSphere390/CB390/apps/BBOASR2/HATS.ear
The runtime.properties file is in ASCII initially after the ear file is deployed. After the first invocation of the application, the file is rewritten in EBCDIC as runtime_xxxx.properties, where xxxx is the address space identifier (ASID) of the application server region. There will be a runtime_xxxx.properties for each active application server region. To modify runtime.properties for the first time, you must edit one of the active runtime_xxxx.properties files and then copy it back as runtime.properties. Since the HATS runtime code only reads from runtime.properties, any additional changes must be made in runtime.properties, not runtime_xxxx.properties.
Message and trace files are located in
CBCONFIG/apps/SRVNAME/<webapp>.ear/logs
/u/WebSphere390/CB390/apps/BBOASR2/HATS.ear/logs
These file names are specified in the runtime.properties file, but will contain the ASID when written to the /logs directory. For example, if you specified logFile=myMessages.txt in runtime.properties, the file would be written as myMessages_xxxx_n.txt, where xxxx is the ASID of the active server region, and n will be an integer from 1 to the number of message files you specified for maxLogFiles.
HATS runtime does not remove inactive runtime_xxxx.properties or message and log files.
Accessing HATS Administration Console
The HATS Administration Console enables the system administrator to view sessions initiated for HATS applications. The panels in HATS administration display license usage informations and sessions information for applications included in an .ear file. Each application in an .ear file includes files to support HATS administration.
To start HATS Administration Console, enter in the URL area of your browser:
http://<webserver name>/<appname>/HATSAdmin/admin.jsp
where webserver name is your webserver name or IP address and appname is the name of a HATS application in the .ear file.
HATS Administration Console is bound to WebSphere security and uses form-based login. If WebSphere security is active on WAS, and the URL to start HATS Administration Console is entered in a browser, the page is redirected to a HATS Administration Console login authentication page. You must enter the user ID and password for the WAS security server before HATS Administration Console can be started. You can consult Chapter 5 on the WebSphere Installation and Customization manual for more information on setting up advanced security features. The HATS Administrator role is defined as "HATSAdministrator". This role can be used in the definition of EJBROLE or GEJBROLE profiles as described in Chapter 2 of the WebSphere Installation and Customization manual.
Please refer to HATS Developer's Guide for more information on HATS Administration.
