The BMS re-facing

XJWEB allows the re-facing of the BMS maps into HTML. To do this it requires a JSP to control this function.

User have to provide a default re-facing JSP, which will control all the maps that have no dedicated JSP.

Dedicated JSPs  may be created simply defining a JSP named as <mapset>.<map>.jsp.

I.e., for a map named MENU01 in the mapset MPSXY user will provide a page named MENU01.MPSXY.jsp.

Programming the re-facing pages

These pages are standard JSP files, therefore they have to be coded respecting the JSP/J2EE standards.

Re-facing pages mandatory have to include the file named xjweb.include.jsp:

<%@ include file="/xjweb.include.jsp" %>

The following objects will be available for programmer after included the file above:

For detailed information concerning XJWEB API please refer to the document "XJE - Xframe Java Environment" in the XFRAME bookshelf.

Formatted and unformatted screens

XCICS/XJWEB distiguish between formatted screens coming from BMS maps (therefore the output of a SEND MAP command) and raw 3270 data. In the first case XCICS will convert for XJWEB the sent map into an XML stream describing the map. In the second case a raw 3270 stream will be sent to XJWEB.

The BMS fields

When a BMS map is sent to the screen, and therefore, to XJWEB, this one handles the XML provided by XCICS and generates a CXMap object to be used in the JSP to retrieve information about the map and its fields.

For each field a CXField object is created and through this, programmers may get information about the field. These information may only be use to display data in the HTML screen.

I.e.

<p><font color=red>
<%
   CXField f=xjMap.getField("MSG");
   if (f!=null) {
       if (f.hasInitial()) {
           out.println("the systems says: "+ f.getInitial());
       } else {
           out.println("no message from the system");
       }
   } else {
       out.println("The field MSG cannot be retrieved");
   }
%>
</font></p>

The input form

All the data involved in a map that have to be returned to XCICS must be included into an HTML form, and must be handled as HTML form fields.

This form must be defined using the methods provided by the class com.hite.x4j.jsp.XJWebHtmlBean:

I.e.

<p>an html paragraph</p>
<%=xjweb.createFormHead()%>
<!-- body of the map form -->
<%=xjweb.createFormTail()%>

The form fields

As describe above data returning to XCICS, must be handled as HTML field. These fields must be defined as specified as follows:

the name must be the same as BMS field

the field type may be text, hidden or password

Moreover, in order to grant input integrity, user edited fields should make use of the following Javascript functions on the onChange event:

I.e.

<p>an html paragraph</p>
 
<%=xjweb.createFormHead()%>
 
<!-- body of the map form -->
<input type="hidden" name="CODE" value="123">
 
Please enter your name:
<input type="text" name="NAME" onChange="_xjweb_on_change_(this)">
 
Please enter your age:
<input type="text" name="NAME" onChange="_xjweb_on_changenum_(this)">
 
<%=xjweb.createFormTail()%>

However, XJWebHtmlBean provides a set of method to easily wrap the data coming from XCICS into HTML fields.

I.e.

<%=xjweb.createFormHead()%>
 
<p>
Enter a function
<%=xjweb.createField("ITEM")%>
<%=xjweb.createButton("Proceed", XJWebHtmlBean.KEY_ENTER)%>
</p>
 
<p><font color=red><b><%=xjweb.createField("MSG")%></b></font></p>
<i>System date/time</i>:
<%=xjweb.createField("DATE")%>
<%=xjweb.createField("TIME")%>
</p>
 
<%=xjweb.createFormTail() %>

The AID keys

In order to simulate the AID keys, the form field _xjweb_eibaid_ is automatically defined by the createFormHead(). This field must be set according with the following to return the desired AID to XCICS:

The function _xjweb_setaid_(<value>) should be used to set the desired AID.

In any case, user should use XJWebHtmlBean methods to define buttons:

I.e.

<%=xjweb.createFormHead()%>
<p>
Enter a function <%=xjweb.createField("ITEM")%>
<%=xjweb.createButton("Proceed", XJWebHtmlBean.KEY_ENTER)%>
</p>
<p><font color=red>
<%
CXField f=xjMap.getField("MSG");
if (f!=null) {
   if (f.hasInitial()) {
       out.println("the systems says: "+ f.getInitial());
   } else {
       out.println("no message from the system");
   }
} else {
   out.println("The field MSG cannot be retrieved");
}
%>
</font></p>
<%=xjweb.createButton("Exit","images/Delete.gif", XJWebHtmlBean.KEY_PF3)%>
<%=xjweb.createHtml4Button("<table bgcolor=orange><tr><td >Proceed</table>", XJWebHtmlBean.KEY_CLEAR)%>
<hr>
<p>
<i>System date/time</i>:<%=xjweb.createField("DATE")%>
<%=xjweb.createField("TIME")%>
</p>
<%=xjweb.createFormTail() %>

Transaction processing

As well known by CICS programmers, data entered on the screen may determine the transaction run by CICS/XCICS. If the program is under the control of a RETURN TRANSID the TP monitor knows what to do and, when user enters data, starts the transaction previously requested by the application. Instead, when the program simply executes a RETURN command, the transaction started will be determinated depending on the first bytes coming from the 3270 screen.

Using XJWEB programmers must take care about this condition. While there is no problem with the RETURN TRANSID, when program terminates with a simple RETURN, XJWEB programmer must communicate to XCICS which transaction to start.

The may provide this information in two ways:

In the first case, programmers must use the method createTransactionField() to specify the transaction code to restart. I.e.

<%=xjweb.createFormHead()%>
 
<%=xjweb.createTransactionField("MENR")%>
 
<p>
Enter a function <%=xjweb.createField("ITEM")%>
<%=xjweb.createButton("Proceed", XJWebHtmlBean.KEY_ENTER)%>
</p>
<%=xjweb.createFormTail() %>

In the second one, programmers must use the method createTransactionFieldId() to specify the field from which XCICS will get the transaction code to restart. This field may be either a BMS field or another HTML form field (maybe hidden) containing the information.

I.e.

<%=xjweb.createFormHead()%>
 
<%=xjweb.createTransactionFieldId("ITEM")%>
 
<p>
Enter a function <%=xjweb.createField("ITEM")%>
<%=xjweb.createButton("Proceed", XJWebHtmlBean.KEY_ENTER)%>
</p>
<%=xjweb.createFormTail() %>

or another example:

<%=xjweb.createFormHead()%>
 
<%=xjweb.createTransactionFieldId("HIDDEN_TRANSACTION")%>
<input name="HIDDEN_TRANSACTION" value="MENR" type=hidden>
 
<p>
Enter a function <%=xjweb.createField("ITEM")%>
<%=xjweb.createButton("Proceed", XJWebHtmlBean.KEY_ENTER)%>
</p>
<%=xjweb.createFormTail() %>

Defining the default re-facer for BMS maps

The default wrapper for BMS maps is the JSP handling all the non customized maps. It have to make use of the createFormBody() method. This method provides a generic body for all.

This is the simplest default re-facer JSP:

<%@ include file="/xjweb.include.jsp" %>
<html>
<head><title>XJWEB default re-facer</title>
</head>
 
<%=xjweb.createFormHead()%>
 
<%=xjweb.createFormBody() %>
 
<%=xjweb.createButtonPanel() %>
 
<%=xjweb.createFormTail() %>
</html>

Starting from the JSP above, user may customize its default wrapper adding any kind of resource (logos, pictures, links, etc).

Defining the wrapper for 3270 unformatted screens

The wrapper for 3270 unformatted screens is the JSP handling all the data not included in a BMS definition coming from XCICS.

This is the simplest wrapper JSP for 3270 unformatted screens:

<%@ include file="/xjweb.include.jsp" %>
<html>
<head>
   <title>XJWEB JSP Session</title>
</head>
 
<%=xjweb.createFormHead()%>
 
<%=cxResponse.getTextHtml()%>
Enter transaction code
<input type="text" name="TRANSACTION_CODE"/>
<%=xjweb.createTransactionFieldId("TRANSACTION_CODE")%>
 
<%=xjweb.createButton("GO!", XJWebHtmlBean.KEY_ENTER)%>
 
<%=xjweb.createFormTail() %>
</html>

Starting from the JSP above, user may customize its default wrapper adding any kind of resource (logos, pictures, links, etc).