|
By the web server point of view, XJWEB is simply a package performing the communication with XCICS. Therefore it must be used in the context of a so called "web-app".
It means that user will have to create one or more webapps to use XJWEB.
For example, on the same webserver, user could have an application to interface XCICS running on system A and another to interface XCICS on system B. Another scenario could be a web server with a webapp to interface only the warehouse transactions, and another to interface the billing transaction
The context
Once installed Tomcat and XFRAME, a dedicated context for the new webapp must be created. To do this simply add to your $CATALINA_HOME/webapps directory a file named <application_name>.xml containing:
<Context path="/application_name" docBase="/home/webapp" debug="0" reloadable="true">
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="localhost.application_name.log."
suffix=".txt"
timestamp="true"
/>
</Context>
bold text above is depending on configuration:
| • | /application_name is the name of the context |
| • | /home/webapp is the path to the web app root directory (JSP, HTML, etc.). Since now on this document will refer to to this pas as $DOCBASE |
Then the application directories must be create. Under the $DOCBASE the following driectory tree must be created:
$DOCBASE
|
+-WEB-INF
|
+- classes
+- lib
then copy the following files in the correspnding path:
| • | $XFRAMEHOME/xje/tools/xjweb/web.xml into $DOCBASE/WEB-INF |
| • | $XFRAMEHOME/xje/tools/xjweb/*.jsp into $DOCBASE |
| • | $XFRAMEHOME/xje/tools/xjweb/*.js into $DOCBASE |
| • | $XFRAMEHOME/lib/xjweb.jar into $DOCBASE/WEB-INF/lib/xjweb.jar |
I.e.
mkdir $DOCBASE
mkdir $DOCBASE/WEB-INF
mkdir $DOCBASE/WEB-INF/lib
mkdir $DOCBASE/WEB-INF/classes
cp $XFRAMEHOME/xje/tools/xjweb/web.xml $DOCBASE/WEB-INF
cp $XFRAMEHOME/xje/tools/xjweb/*.jsp $DOCBASE
cp $XFRAMEHOME/xje/tools/xjweb/*.js $DOCBASE
cp $XFRAMEHOME/lib/xjweb.jar $DOCBASE/WEB-INF/lib/xjweb.jar
How to create a session with login connection
If you want to add to your XCICS web application an initial login you can define to tomcat a user table containing all enabled users. You have to add this line to your context :
<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
driverName="oracle.jdbc.driver.OracleDriver"
connectionURL="jdbc:oracle:thin:@hostname:1521:htoradb"
connectionName="user"
connectionPassword="password"
userTable="web_users"
userNameCol="login_name"
userCredCol="user_pass"
userRoleTable="web_users"
roleNameCol="role_name"
/>
where driver name define RDBMS in this case is a Oracle DB,
connection URL a valid connection to DB instance,
connection name and password are valid user and password of defined instance.
All user* parameters are table and columns reference to resolve connection. This is a table describe example
SQL> desc web_users;
Name Null? Type
----------------------------------------- -------- ----------------------------
USER_NAME VARCHAR2(15)
USER_PASS VARCHAR2(15)
ROLE_NAME VARCHAR2(15)
LOGIN_NAME NOT NULL VARCHAR2(15)
TERM_NAME CHAR(4)
userNameCol setting has to match with user column, and userCredCol has to match with password columns.
See Tomcat documentations for more detailed information.
Configuring
To configure the application the file web.xml defined in $DOCBASE/WEB-INF must be edited.
Format of the configuration file:
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"
<web-app>
<display-name>Application Name</display-name>
<description>This is the description for the application</description>
<context-param>
<param-name>xjweb.license.file</param-name>
<param-value>license_file</param-value>
</context-param>
<context-param>
<param-name>xjweb.default.action</param-name>
<param-value>default_action</param-value>
</context-param>
<context-param>
<param-name>xjweb.default.transaction</param-name>
<param-value>default_transaction</param-value>
</context-param>
<context-param>
<param-name>xjweb.terminal.prefix</param-name>
<param-value>terminal_prefix</param-value>
</context-param>
<context-param>
<param-name>xjweb.template.jsp</param-name>
<param-value>template</param-value>
</context-param>
<context-param>
<param-name>xjweb.template.3270.jsp</param-name>
<param-value>template_3270</param-value>
</context-param>
<context-param>
<param-name>xjweb.wrapper.template.jsp</param-name>
<param-value>wrapper_template</param-value>
</context-param>
<context-param>
<param-name>xjweb.resources.path</param-name>
<param-value>resource_path</param-value>
</context-param>
<context-param>
<param-name>xjweb.timeout.handler.jsp</param-name>
<param-value>timeout_handler</param-value>
</context-param>
<context-param>
<param-name>xjweb.error.handler.jsp</param-name>
<param-value>error_handler</param-value>
</context-param>
<servlet>
<servlet-name>XJWebServlet</servlet-name>
<servlet-class>com.hite.x4j.jsp.XJWebServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>XJWebManager</servlet-name>
<servlet-class>com.hite.x4j.jsp.XJWebManager</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>XJWebServlet</servlet-name>
<url-pattern>/default_action</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>XJWebManager</servlet-name>
<url-pattern>/manager</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>session_timeout</session-timeout>
</session-config>
</web-app>
More than one application may be defined and more than one terminal per application may be defined.
The following items may be configured:
xjweb.license.file
|
path to the XJWEB license file (normally under $XFRAMEHOME/license)
|
xjweb.default.action
|
name of the XJWEB processing form
|
xjweb.default.transaction
|
default transaction (optional, XSSN by default)
|
xjweb.template.jsp
|
name of the template JSP for default HTML refacing for BMS maps
|
xjweb.template.3270.jsp
|
name of the template JSP for default HTML refacing for raw 3270 screens
|
xjweb.wrapper.template.jsp
|
name of the template JSP for the XJWEB/3270 wrapper (XJWEB wrapping mode)
|
xjweb.resource.path
|
path to resources (normally the same as the context name)
|
xjweb.session.timeout
|
the session timeout in minutes
|
xjweb.timeout.hander.jsp
|
JSP to handle the timeout event
|
xjweb.error.hander.jsp
|
JSP to handle errors
|
xjeb.terminal.prefix
|
the terminal identifier prefix as specified in xcics.conf
|
xjeb.terminal.sessions.number
|
the maximum terminal sessions available for connected users
|
An example
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"
<web-app>
<display-name>XJWEB Application</display-name>
<description>This is the xjweb development application</description>
<context-param>
<param-name>xjweb.default.action</param-name>
<param-value>reply</param-value>
</context-param>
<context-param>
<param-name>xjweb.default.transaction</param-name>
<param-value>MENU</param-value>
</context-param>
<context-param>
<param-name>xjweb.terminal.prefix</param-name>
<param-value>W</param-value>
</context-param>
<context-param>
<param-name>xjweb.template.jsp</param-name>
<param-value>xjweb.jsp</param-value>
</context-param>
<context-param>
<param-name>xjweb.template.3270.jsp</param-name>
<param-value>xjweb3270.jsp</param-value>
</context-param>
<context-param>
<param-name>xjweb.wrapper.template.jsp</param-name>
<param-value>wrapper3270.jsp</param-value>
</context-param>
<context-param>
<param-name>xjweb.timeout.handler.jsp</param-name>
<param-value>timeout.jsp</param-value>
</context-param>
<context-param>
<param-name>xjweb.error.handler.jsp</param-name>
<param-value>error.jsp</param-value>
</context-param>
<context-param>
<param-name>xjweb.resources.path</param-name>
<param-value>/xjweb</param-value>
</context-param>
<servlet>
<servlet-name>XJWebServlet</servlet-name>
<servlet-class>com.hite.x4j.jsp.XJWebServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>XJWeb3270Servlet</servlet-name>
<servlet-class>com.hite.x4j.jsp.XJWeb3270Servlet</servlet-class>
</servlet>
<servlet>
<servlet-name>XJWebManager</servlet-name>
<servlet-class>com.hite.x4j.jsp.XJWebManager</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>XJWebServlet</servlet-name>
<url-pattern>/reply</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>XJWeb3270Servlet</servlet-name> <url-pattern>/wrapper</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>XJWebManager</servlet-name>
<url-pattern>/manager</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>5</session-timeout>
</session-config>
</web-app>
Connecting XCICS
A connection page must be provided.
It must provide the following fields data to the XJWEB servlet pointed by the parameter xjweb.default.action:
xjweb_host
|
hostname of XCICS server
|
xjweb_port
|
port of XCICS application
|
xjweb_termname
|
terminal name (optional)
|
The connect.jsp provided with XFRAME is a sample of the connect. This is another sample (index.jsp):
<%@ page import="java.util.*" %>
<html>
<head><title>Connecting XCICS</title></head>
<body>
<p>Press the button to connect XCICS</p>
<form name=xjweb.form ACTION="<%= application.getInitParameter("xjweb.default.action")%>" method=post>
<input type="hidden" name="xjweb_host" value="hpux01.ht.net">
<input type="hidden" name="xjweb_port" value="40000">
<input type="hidden" name="xjweb_termname" value="">
<input type="submit" value="connect" >
</form>
<pre><%=request.getParameter("xjweb.message")%></pre>
</body>
</html>
Terminal connected through XJWEB, must be defined as "web" type
If you want to user the XJWEB/3270 wrapper, change the ACTION to the mapping of the servlet XJWeb3270Servlet (wrapper in the sample above) and define terminal as "standard" type.
Handling errors
Each time an error should occur (i.e. XCICS is not available, the terminal is not available, etc), the XJWEB servlet, will invoke the error defined JSP, providing the attribute xjwe.exception, to the user code, to let it handle the error condition. This is a sample error handling page
<html>
<p>XJWEB get an error:
<%
Exception e=(Exception)session.getAttribute("xjweb.exception");
if (e instanceof java.net.ConnectException) {
out.println("connection refused");
} else if (e instanceof com.hite.x4j.device.TerminalUndefException) {
out.println("terminal not defined");
} else if (e instanceof com.hite.x4j.device.TerminalBusyException) {
out.println("terminal already in use");
} else {
out.println("unhandled exception caught: "+e);
}
%>
</p>
</html>
| 
