IBM^(R) WebSphere^(R) Host Publisher; Programmer's Guide and Reference

Host Publisher File formats

Host Publisher produces applications using standard open formats--such as HTML pages, Java files, JSPs, and XML files. This makes it simple to make changes to a Host Publisher application after it has been published to a Host Publisher Server. You don't have to keep returning to the Host Publisher Studio to make small changes to your application.

Warning: If you make changes to applications on the server without updating the files in the Host Publisher Studio, you could lose the changes in the server version when you next publish your application. Be sure to update the version you keep in the Host Publisher Studio before you publish those files. There is no automatic way to synchronize the two versions.

A Host Publisher application is made up of several types of files. Other files are only used in the Host Publisher Studio. The sections below describe each file, explain how it is used, and provide the file format.

Integration Object project (.hpi) file

Host Access and Database Access store project information into .hpi files. These files describe the details you defined while creating an Integration Object.

Note:: The format of the Integration Object project (.hpi) file is shown for information only. If you manually edit this file, you might receive unexpected results.

The following is a sample .hpi project file generated by Host Access.

<?xml version="1.0" standalone="yes"?> 
<!DOCTYPE com.ibm.HostPublisher.IntegrationObject SYSTEM "io.dtd" []> 
<com.ibm.HostPublisher.IntegrationObject name = "callup"   type="hod">	
  <Package name = "IntegrationObject"/>
  <Session>
    <PoolName>callup</PoolName>
  </Session>  	
 
  <EJB PropertiesSuffix = "Properties" HelperSuffix = "Helper" 
              EJB10AccessBeanSuffix = "Access0"/> 
 
  <OutputVariable name="callupResults" type ="simple">
    <ScreenCoordinates x="2" y="14" dx="71" dy="6"/>
      <SubVariable name="column1" type ="array">
        <RelativeCoordinates x="0" y="0" dx="26" dy="5"/>
      </SubVariable>
      <SubVariable name="column2" type ="array">
        <RelativeCoordinates x="26" y="0" dx="4" dy="5"/>
      </SubVariable>
      <SubVariable name="column3" type ="array">
        <RelativeCoordinates x="30" y="0" dx="9" dy="5"/>
      </SubVariable>
      <SubVariable name="column4" type ="array">
        <RelativeCoordinates x="39" y="0" dx="9" dy="5"/>
      </SubVariable>
      <SubVariable name="column5" type ="array">
        <RelativeCoordinates x="48" y="0" dx="9" dy="5"/>
      <SubVariable name="column6" type ="array">
        <RelativeCoordinates x="57" y="0" dx="15" dy="5"/>
      </SubVariable> 
  </OutputVariable>
 
  <HODMacro filename = "callup.macro"/>
  <SessionChain>
    <StartState name = "Start Label"/>
    <EndState name = "The End Label"/>
    <Position>middle</Position>
  </SessionChain>
<com.ibm.HostPublisher.IntegrationObject>

The following is a sample .hpi project file generated by Database Access.

<?xml version="1.0" standalone="yes"?> 
<!DOCTYPE com.ibm.HostPublisher.IntegrationObject SYSTEM "io.dtd" []> 
<com.ibm.HostPublisher.IntegrationObject name = "QuerySample"   type="db">	
  <Package name = "IntegrationObject"/>
  <Session>
    <PoolName>callup</PoolName>
  </Session>  	
 
  <RIO RIOPrefix = "Remote"/>
 
  <SQL>SELECT "SHERRI"."DEPARTMENT"."DEPTNO", "SHERRI"."DEPARTMENT"."DEPTNAME", 
                       "SHERRI"."DEPARTMENT"."MGRNO" FROM "SHERRI"."DEPARTMENT"
                       WHERE ( ( "SHERRI"."DEPARTMENT"."DEPTNO" <> 'CHY' ) 
                       AND ( "SHERRI"."DEPARTMENT"."DEPTNAME" <> @+)deptname@-)''@+) ) )
  </SQL>
 
  <JDBCUrl name="jdbc:db2:Sample"/>
  <JDBCDriver name="COM.ibm.db2.jdbc.app.DB2Driver"/>
<com.ibm.HostPublisher.IntegrationObject>

Tag descriptions:

com.ibm.HostPublisher.IntegrationObject

name: Specifies the name of this Integration Object. This name must match the name of the file.
type: The type of Integration Object described in this file. Valid values are hod or db.

EJB

Specifies the suffixes appended to the name of the Integration Object for naming EJB Access Beans and object files. You specify the values for the attributes using the EJB Integration Object Properties selection of the Options menu in the Host Publisher Studio when creating the Integration Object. The attributes are:

EJB10AccessBeanSuffix: Specifies the suffix appended to the name of the Integration Object for naming the EJB 1.0 Access Bean files. The default value is Access0, unless you modify the value in the Studio.ini file.
HelperSuffix: Specifies the suffix appended to the name of the Integration Object for naming the EJB helper object files. The default value is Helper, unless you modify the value in the Studio.ini file.
PropertiesSuffix: Specifies the suffix appended to the name of the Integration Object for naming the EJB properties object files. The default value is Properties, unless you modify the value in the Studio.ini file.

HODMacro

filename: Identifies the filename containing the Host On-Demand macro recorded by the user for this Host Access Integration Object.

JDBCDriver

name: The JDBC driver name to use for the specified URL for Database Access Integration Objects.

JDBCUrl

name: The JDBC URL to connect to when executing this Database Access Integration Object.

OutputVariable

Output variables define data that will be extracted during the macro execution in Host Access Integration Objects.

name

Specifies the variable name provided by the user during macro recording.

type

Specifies the type of variable described by the tag. Valid values are simple and array. Simple variables are stored and displayed as single blocks of text. Array variables are stored as individual lines that can be displayed individually on a JSP.

ScreenCoordinates

Identifies a rectangular region on the application screen that defines the data to extract.

x: Identifies the starting column number. The first column begins at 1.
y: Identifies the starting row number. The first row begins at 1.
dx: Identifies the total number of columns to include in this variable.
dy: Identifies the total number of rows to include in this variable.

Package

name: Specifies the Java package name used when generating the Java source code for this object.

RIO

RIOPrefix: Specifies the prefix prepended to the name of the Integration Object for naming the Remote Integration Object files. You specify the value for the RIOPrefix attribute using the Remote Integration Object Properties selection of the Options menu in the Host Publisher Studio when creating the Integration Object. The default value is Remote, unless you modify the value in the Studio.ini file.

Session

PoolName: Specifies the connection pool name used by this Integration Object.

SessionChain

StartState name: The connection start state label given by the user for the Host Access Integration Object.
EndState name: The connection end state label given by the user for the Host Access Integration Object.
Position: The position of this Host Access Integration Object in the object chain. Valid values are first, middle, or last.

SQL

Identifies the SQL statement to execute for Database Access Integration Objects.

SubVariable

Subvariables define further detail of the format of data defined by an output variable. Subvariables are generated when the user specifies data to be extracted as a table in Host Access. Each column identified by the user is defined using the SubVariable tag.

name

Specifies the variable name provided by the user during macro recording.

type

RelativeCoordinates

Identifies a rectangular region on the application screen that defines the data to extract.

x: Identifies the starting column number. The first column begins at 1.
y: Identifies the starting row number. The first row begins at 1.
dx: Identifies the total number of columns to include in this variable.
dy: Identifies the total number of rows to include in this variable.

Host Publisher application (.hpa) file

This XML file organizes all of the parts that make up a Host Publisher application, including Java objects and the Web pages that refer to them. Host Publisher applications are published to Host Publisher Servers for access by your customers. When Host Publisher Studio is used to load an existing application, it is this file that you actually open.

Note:: The format of the Host Publisher application (.hpa) file is shown for information only. If you manually edit this file, you might receive unexpected results.

Here is a sample of a typical application file:

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE application SYSTEM 'WebBridge.dtd'> 
<application>         
<appl_name>testdb</appl_name>        
<integration_object>         
  <obj_name>D:\HostPublisher\Studio\IntegrationObjects\EmployeeQuery.jar
  </obj_name>         
  <input_properties>             
    <input>setLastName</input>         
  </input_properties>         
  <output_properties>             
    <output>getEmployeesEmployeeIDResult</output>             
    <output>getEmployeesFirstNameResult</output>             
    <output>getEmployeesExtensionResult</output>             
    <output>getEmployeesLastNameResult</output>             
    <output>getLastName</output>         
  </output_properties>         
  <execution_method>doHPTransaction</execution_method>     
</integration_object>     
<page>d:\hostpublisher2\Studio\testdb\output.jsp</page>     
<page>d:\hostpublisher2\Studio\testdb\input.jsp</page> 
</application>

Tag descriptions:

appl_name: Names the Host Publisher application. This name must match the name of the file. It is also the name Host Publisher Server uses to track this application.
execution_method: Specifies the Java method for invoking the Java object once the inputs are satisfied with data. After the execution method completes, the Java object's resulting data can be accessed using its output methods, if there are any.
input: Specifies the Java method used to set an input value. For a Java bean, this is typically the setter method for a Java bean property.
input_properties: Specifies the beginning of the list of inputs for this Java object. Inputs generally must be satisfied with data before the Java object can be executed. Each input is specified by a separate input tag under this tag.
integration_object: Specifies beginning of a definition of an Integration Object or other Java object that was imported into Host Publisher Studio.
obj_name: Specifies the full path to the Integration Object or other Java object within the file system. If the object is an Integration Object created using one of the Host Publisher Access applications, this file refers to a .jar file containing the Integration Object Java bean and its related files. If this object is another Java object, this file refers to the file containing that Java object.
output: Specifies the Java method used to get data values from a Java object. For a Java bean, this is typically the getter method for a Java bean property.
output_properties: Specifies the beginning of the list of outputs for this Java object. Outputs are used to render Java object data within a Web page. Each output is specified by a separate output tag under this tag.
page: Specifies a Web page that is used, either directly or indirectly, to access Java objects.

Integration Object source (.java) file

Integration Objects created by Host Publisher Studio are Java beans. The Java bean files are contained within a .jar file and are generally made up of two files, the Java bean class and the Java bean BeanInfo class. These class files are generated based on a template maintained by the Host Publisher Studio and information provided by you through one of the Host Publisher Access applications.

The template for Database Access Integration Obects is not available to you for customization, and since any time the Integration Object is modified using the Database Access application it is regenerated and compiled, do not customize the source files for the Integration Objects in any way. Instead, if you require custom logic to make use of Integration Object data, use JSP tags and additional Java code to include the logic in the Web pages, or develop another Java class that extends your Integration Object to customize Integration Object results.

The template for Host Access Integration Objects can be modified at the Java code level. For more information, see Customizing Host Access Integration Object Java code.

JavaServer Pages (JSP) Web page files

Host Publisher Studio generates JSP 1.0 pages to manipulate Java objects and their output. JSP tags are similar to HTML tags, but their purpose is to instantiate Java objects, execute methods, and access the object's properties (inputs and outputs). JSP tags enable you to interact with Java objects using standard Web pages.

With Host Publisher Version 2, JSPs were created using the JSP 0.91 specification. Host Publisher Version 3.5 creates JSPs using the JSP 1.0 specification. Host Publisher provides a migration utility to convert .91 JSPs to 1.0 JSPs. This utility can be invoked at server installation time, in the Host Publisher Studio, and as a command line utility. See the IBM WebSphere Host Publisher Administrator's and User's Guide for more information about the migration utility.

If you want to customize JSP migration, Host Publisher provides sample JSP migration code. For more information about customizing the sample JSP migration code, see Customizing JavaServer Page (JSP) migration.

The following are sample JSPs, followed by a description of how the tags are being used.

JSP for the EmployeeQuery Integration Object

<HTML>
<%@ page contentType="text/html;charset=ISO-8859-1" %>
<BODY>
<jsp:useBean id="EmployeeQuery" type="IntegrationObject.EmployeeQuery" 
                class="IntegrationObject.EmployeeQuery" scope="request">
</jsp:useBean>
<jsp:setProperty name="EmployeeQuery" property="*" />
<% EmployeeQuery.setHPubStartPoolName("NorthwindLocal"); %>
<% EmployeeQuery.doHPTransaction(request, response); %>
<%
if (EmployeeQuery.getHPubErrorOccurred() != 0) {
    // Error page redirection already done by IO
    return;
}
%>
<P>Table:
<TABLE BORDER>
<TBODY>
<tr>
<th>EmployeesEmployeeID<th>
<th>EmployeesFirstName<th>
<th>EmployeesExtension<th>
</tr>
<%
for (int idx1 = 0;idx1 <= 2147483647; idx1 ++){
try {
%>
<tr>
<td><%= EmployeeQuery.getDB2ADMINEMPLOYEEEMPNO_(idx1) %>
<td><%= EmployeeQuery.getDB2ADMINEMPLOYEEFIRSTNME_(idx1) %>
<td><%= EmployeeQuery.getDB2ADMINEMPLOYEEPHONENO_(idx1) %>
</tr>
<%
}
catch (java.lang.ArrayIndexOutOfBoundsException e){
break;
}
catch (java.lang.NullPointerException e){
break;
}
}
%>
</TBODY>
</TABLE>
</BODY>
</HTML>

JSP for the QuerySample Integration Object

<%
// Establish a session object which can be used by chained applications.
 
HttpSession hp_session =  request.getSession(false);
if (hp_session == null) {
    hp_session = request.getSession(true);
}
%>
<HTML>
<%@ page contentType="text/html;charset=ISO-8859-1" %>
<BODY>
<jsp:useBean id="QuerySample" type="IntegrationObject.QuerySample" 
                class="IntegrationObject.QuerySample" scope="request">
</jsp:useBean>
<jsp:setProperty name="QuerySample" property="*" />
<% QuerySample.setHPubStartPoolName("samplePool"); %>
<% QuerySample.doHPTransaction(request, response); %>
<%
if (QuerySample.getHPubErrorOccurred() != 0) {
    // Error page redirection already done by IO
    return;
}
%>
<FORM NAME="QuerySample" METHOD="POST" ACTION="<%= response.encodeUrl("QuerySample.jsp") %>">
<P>Department Number
<SELECT NAME ="DB2ADMINEMPLOYEEWORKDEPT_" MULTIPLE SIZE=3>
<%
for (int idx1 = 0 ; idx1 <= 2147483647; idx1 ++){
 try{
%>
<% String str = "<OPTION VALUE=\"" +QuerySample.getDB2ADMINEMPLOYEEWORKDEPT_(idx1) + 
     "\">\n"; out.println(str); %>
<%= QuerySample.getDB2ADMINEMPLOYEEWORKDEPT_(idx1) %>
<%
}
catch (java.lang.ArrayIndexOutOfBoundsException e){
break;
}
}
%>
</SELECT>
<P>
<INPUT TYPE="submit" VALUE="Submit">
</FORM>
</BODY>
</HTML>

The first page references an Integration Object called EmployeeQuery. After invoking the object, it renders the object's output in an HTML table with three columns. The second page references an Integration Object called QuerySample. After invoking the object, it renders the object's output in an HTML form that enables the user to select a department. The following tags are used on these pages:

FORM

The FORM tag encompasses the content of an HTML fill-in form. Use this tag to create fill-in forms with checkboxes, radio buttons, and text input windows. It contains the following parameters:

ACTION

The ACTION parameter specifies the URL to which the FORM tag content is sent. This parameter is required.

METHOD

When the ACTION parameter indicates an HTTP URL, the METHOD parameter identifies the HTTP method for sending information to the server. This parameter is optional. Values for this parameter are:

GET: The form content is appended to the URL.
POST: The form content is sent to the server as a message body, and not as part of the URL.

NAME

The NAME parameter specifies the URL to which the FORM tag content is sent. This parameter is required.

Inline Java tag (<% %>)

Inline Java tags specify the beginning and end of Java code segments that are to be invoked as they are written. These segments may reference variables specified within other inline Java tags before these on the same page. As shown in the examples, these tags can be used to access or execute Java objects explicitly.

INPUT

The INPUT tag specifies a variety of editable fields inside a form. It contains the following parameters:

NAME

The NAME parameter specifies the variable name for the VALUE parameter.

TYPE

The TYPE parameter specifies the type for the INPUT tag. This parameter is required. Values for this parameter are:

checkbox: INPUT tag elements are boolean quantities. The default value is off.
file: The INPUT tag element is a file selection tool, with which the user can select a file to be sent with the FORM tag.
hidden: The INPUT tag element is not displayed to the user.
image: The INPUT tag element is an active inline image.
password: The INPUT tag element is a single-line text field, but the text typed in the field is obscured by asterists or some other method. This is used for password entry.
radio: The INPUT tag element is a radio button. Radio buttons are linked together by the same NAME parameter.
reset: The INPUT tag element is a reset button. When pressed, all the fields in the FORM tag are reset to the values given by their VALUE parameter, erasing all user input.
submit: The INPUT tag element is a Submit button. Pressing the Submit button sends the FORM tag data to the specified URL.
text: The INPUT tag element is a single-line text entry field. The physically displayed size of the input field is set by the SIZE attribute.

VALUE

The VALUE parameter specifies the initial value of the INPUT tag.

jsp:setProperty

The jsp:setProperty tag sets the value of one or more properties in a Java bean component, using the Java bean's set methods. You must use a jsp:useBean tag to declare the Java bean before you use the jsp:setProperty tag. The jsp:setProperty tag contains the following parameters:

name

The name parameter names an instance of a Java bean that has already been created or located with a jsp:useBean tag. The value of the name parameter must match the value of the id parameter on a jsp:useBean tag. The jsp:useBean tag must appear before the jsp:setProperty tag in the same JSP file.

property

The property parameter sets the property values in a Java bean component. You can set property values in several ways:

By passing all of the values in the user's request (stored as parameters in the request object) to matching properties in the Java bean
By passing a specific value in the request object to a matching property or a property of a different name in the Java bean
By explicitly setting a Java bean property to a value specified as a String or the result of an expression.

Each method of setting property values is determined by the values you specify on the property tag. The values are:

property="*"

Stores all of the values in the request object parameters (called request parameters) in matching Java bean properties. The property names in the Java bean must match the request parameters. The parameter names usually come from the elements of an HTML form, and the values come from the data the user enters.

The values of the request parameters are always of type String. The String values are converted to other data types so they can be stored in Java bean properties. The allowed Java bean property types and their conversion methods are shown in the following table:

Table 2. String conversions

Property Type	String Is Converted Using
boolean or Boolean	java.lang.Boolean.valueOf(String)
byte or Byte	java.lang.Byte.valueOf(String)
char or Character	java.lang.Character.valueOf(String)
double or Double	java.lang.Double.valueOf(String)
integer or Integer	java.lang.Integer.valueOf(String)
float or Float	java.lang.Float.valueOf(String)
long or Long	java.lang.Long.valueOf(String)

You can also use jsp:setProperty tag to set the value of an indexed property in a Java bean. The indexed property must have one of the types shown in Table 2, and the request value assigned to it must be an array of the same type. The array elements are converted using the conversion methods shown in Table 2.

If a request parameter has an empty or null value, the corresponding Java bean property is not set. If the Java bean has a property that does not have a matching request parameter, the property value is not set.

property="propertyName" [ param="parameterName" ]

Sets one Java bean property to the value of one request parameter. The request parameter can have a different name than the Java bean property, and if so, you must specify the param attribute. If the Java bean property and request parameter have the same name, you can omit the param attribute.

If the parameter has an empty or null value, the corresponding Java bean property is not set.

You cannot use both the param and value attributes in a jsp:setProperty tag.

property="propertyName" value="{ string | <%= expression %> }"

Sets one Java bean property to a specific value. The value can be a string or an expression. If you use a string, it is converted to the Java bean property's data type, according to the conversion rules shown in Table 2. If you use an expression, the data type of the value of the expression must match the data type of the Java bean property.

If the parameter has an empty or null value, the corresponding Java bean property is not set.

You cannot use both the param and value attributes in a jsp:setProperty tag.

jsp:useBean

The jsp:useBean tag locates or instantiates a Java bean with a specific name and scope. The body of a jsp:useBean tag often contains a jsp:setProperty tag that defines property values in the object.

The jsp:useBean tag works with JavaBeans^(TM) components, but not with enterprise beans. If you want to use enterprise beans, you can write a JSP file that constructs a JavaBean component, and have the JavaBean component call the EJB.

Note:: In Host Publisher, Integration Objects and EJB Access Beans are both Java beans.

The jsp:useBean tag contains the following parameters:

class=package.class

The class parameter instantiates a Java bean from a class, using the new keyword and the class constructor. The class must not be abstract and must have a public, no-argument constructor. The package and class names are case sensitive.

id

The id parameter names a variable that identifies the Java bean in the scope you specify. You can use the variable name in expressions or scriptlets in the same JSP file. The name is case sensitive and must conform to the naming conventions of the page scripting language.

scope

The scope parameter defines a scope in which the Java bean exists and the variable named on the id parameter is available. Values for this parameter are:

application: The Java bean is set as a context in the application by a servlet that invokes the JSP file. If the Java bean is not part of the request context, the Java bean is created and stored in the request context.
page: If the Java bean is present in the current JSP, the Java bean is reused. If the Java bean is not present, it is created and stored until the request in the current page is completed.
request: The life of the Java object lasts as long as the request for this page is being processed. It is discarded when a new page is requested.
session: The instance of this class is maintained past the current request, allowing other JSPs, for example, to access this object again.

The default value for the scope parameter is page.

type=package.class

If the Java bean already exists in the specified scope, the type parameter gives the Java bean the type you specify. If you use the type parameter without the class parameter, no Java bean is instantiated. The package and class names are case sensitive.

OPTION

The OPTION tag sets the different character-string options for a SELECT tag. The OPTION tag can contain characters, character references, or entity references. The VALUE attribute specifies the value assigned to the OPTION tag.

SELECT

The SELECT tag enables the user to select from a set of values presented as a selectable list of text strings, specified by the OPTION tag. The SELECT tag contains the following parameters:

MULTIPLE: The MULTIPLE parameter specifies that the user can select multiple items from a single SELECT tag. If MULTIPLE is not specified, the user can select only a single item from the SELECT tag. This parameter is optional.
NAME: This parameter specifies the variable name associated with the SELECT tag. This parameter is required.
SIZE: This parameter specifies the number of displayed text lines. The default is 1, and the list is often presented as a pull-down menu.

Connection and configuration files

This section describes the format of configuration files used by Host Publisher Server Administration to configure Host Publisher. The files use XML tags to structure their content. Host Publisher generates these files along with Integration Objects and publishes them to the server as part of an application. The configuration files are the following:

Connection specification (.connspec): This file specifies the parameters necessary for establishing a connection to a data source, such as a 3270 application or a database.
Connection pool specification (.poolspec): This file defines how to create a pool of connections to a host or database. It specifies parameters for pools of connections to data sources, such as 3270 applications or databases. It also serves as the main coordinating file for a complete connection pool definition (including connection, users, and connect and disconnect macros, if appropriate).
Logon specification (.logonspec): This file specifies the names of the connect and disconnect macros for Host Access Integration Objects. If connection pooling is enabled, this file also specifies the name of the checkin screen.
User pool specification (.userpool): This file lists the users and any associated user-specific information necessary for accessing a data source. It is this list of users and the connection definition that define a pool of connections.
Checkin screen description (.screen): This Host On-Demand screen description identifies the host screen that should be active for a connection to be considered ready to be returned to the connection pool. If a connection is not in that state, it is discarded or recycled in an attempt to return the connection to that state. If connection pooling is not enabled, the checkin screen is ignored.
Application manifest (.application): This file describes all Web pages, Integration Objects and other Java objects, and configuration files that an application requires.
This file is generated by Host Publisher Studio when transferring an application to Host Publisher Server. When the application is deployed into production by the server, this file ensures that all parts of an application are moved into the production area.
Macro files (.macro): For Host Access Integration Objects only, these files specify IBM Host On-Demand keyboard and screen recognition macros. They are used for replaying sequences of keystrokes for performing certain tasks for the Integration Object, such as logging on to a system or accessing a data screen on an application. See Macro script syntax for more information on the format of these XML files.

Notes:

Configuration descriptions might refer to other files that can be referenced using relative path names. The forward slash (/) is used as a file name separator, and it is replaced by the platform-specific filename separator character when Host Publisher Server Administration processes file names.
If you edit any of the following files in a non-English environment, you must use a UTF-8 capable editor:
- Connection specification
- Connection pool specification
- Logon specification
- User pool specification
- Application manifest.

Format of connection pool specification files

XML tag conventions

The following sections describe the XML syntax used to define Host Publisher connection pools, using examples. The following conventions have been used:

Each file contains a set of tags that correspond to a single instance of the connection or connection pool that the file describes.
A single top level tag identifies the type of connection being described, such as <poolconfig> or <connconfig>.
A tag that describes an instance always has a name attribute.
Different object-specific tags are used to distinguish the connections that they are instances of. For example, a connection pool specification configuration file can have a <hodpoolspec> or a <dbpoolspec> tag.
Within the tag describing the object of interest are nested tags defining that object's properties. Each nested tag within a connection-specific tag is an empty XML tag, and the value of the property that it represents is specified by an attribute.
- If the property is a "simple" type (integer or string), the value is specified using a value attribute.
- If the property is a reference to a DbConnSpec, HodConnspec, HodLogonSpec, or LocalUserPool specification, a refname attribute is used to reference that specification's definition. Another file with that name and a fixed extension (in the production/poolspecs directory) contains that specification.
- If the property is a reference to another Java object such as java.util.Properties, whose string representation can be quite big, the value is represented using a nonempty nested tag. An example of this is the sessionprops attribute of the <hodconnspec> tag.
- If the property is a reference to an object that also has an XML representation (such as an HOD macro), then the object is stored in a separate file, and an empty tag with a filename attribute is used to reference that file.
  Note:
  The file can be in a subdirectory relative to the c:/HostPublisher/Server/production/poolspecs directory, where c:/HostPublisher is the directory where Host Publisher is installed. As in all other cases, relative pathnames are specified using the separator character '/'.
If a property value is not specified in the XML tag, the default value is used during execution.
Notes:
1. All timeout values are integers (32 bit), and the unit of time is seconds.
2. A timeout value of 0 indicates no waiting. A timeout value of -1 indicates an infinite wait. For counters, the upper limit is always the maximum value of the primitive integer type in Java (2,147,483,647).
3. While all attribute values in XML are strings, type information is provided for each property that the attribute represents since that will limit the string values that can appear (for example, if boolean, valid values are true and false).

XML Tags for connection specifications

Note:: This file uses UTF-8 encoding.

A file defines each instance of the ConnSpec record. A connection specification defines how to connect to a data source. Whether connection pooling is used for this definition is defined by the pool specifications. A connection specification is nested within a single <connconfig> tag. The <hodconnspec> tag is used to describe an HodConnSpec record, and the <dbconnspec> tag is used to describe a DbConnSpec record. These records have different sets of properties, and the nested tags used to set their values are described in separate sections.

Host On-Demand connections

The following XML tags correspond to properties of an HodConnSpec record.

connecttimeout

The time, in seconds, that Host Publisher Server will wait while creating a host connection using Host On-Demand APIs, and priming it by running a connect macro.

The value is an integer, either -1 or 1 or greater. The default is 120.

disconnecttimeout

The time, in seconds, that Host Publisher Server will wait while running a disconnect macro and disconnecting a host connection using Host On-Demand APIs.

The value is an integer, either -1 or 1 or greater. The default is 120.

expresslogon

Contains tags that specify whether the connection uses express logon. The nested tags specify connection information for the Digital Certificate Access Server (DCAS) server. The nested tags are:

elfenabled
dcasservername
dcasserverport

sessionprops

Contains Host On-Demand connection properties.

singlelogon

Set this value to true if this connection does not allow a user ID and password to be used for multiple simultaneous sessions. If this value is set to true and a user list is defined for this connection, the user ID/password pairs in that user list are locked when in use to prevent their being used by simultaneous connections. If this value is set to true and a user ID is not available for the user list, the requester for the connection waits the amount of time specified by the connecttimeout property.

Set this value to false if this connection allows a user ID and password to be used for multiple simultaneous connections. If this value is set to false and a user list is defined for this connection, the first user ID/password pair in the user list will be reused for each requested connection.

The value is boolean. The default is false.

JDBC connections

The following XML tags correspond to properties of a DbConnSpec record.

connecttimeout: The time, in seconds, that Host Publisher Server will wait to create a database connection using JDBC APIs.
The value is an integer, either -1 or 1 or greater. The default is 120.
drivername: The name of a JDBC driver (class) that can be used by Host Publisher Server to load the driver.
This string value is mandatory.
urlname: This URL must identify the database to which a connection is created.
This string value is mandatory.

Examples

vm3.connspec

<?xml version="1.0"?>
<!DOCTYPE connconfig SYSTEM "connconfig.dtd">
  <connconfig>
    <hodconnspec name="vm3">
    <singlelogon value="false"/>
    <sessionprops>
             SSL=false
             fontSize=10
             autoReconnect=false
             OIAVisible=true
             port=23
             autoConnect=false
             TNEnhanced=false
             fontSizeBounded=true
             autoFontSize=false
             codePage=037
             host=ralvm3
             screensize=2
             sessionType=1
             SSLServerAuthentication=false
             LUName=
             codePageKey=KEY_US
    </sessionprops>
    <expresslogon>
             <elfenabled value="true"/>
             <dcasservername value="9.37.52.31"/>
             <dcasserverport value="809">
    </expresslogon/>
    <disconnecttimeout value="120"/>
    </hodconnspec>
  </connconfig>

empdb.connspec

<?xml version="1.0"?>
<!DOCTYPE connconfig SYSTEM "connconfig.dtd">
  <connconfig>
    <dbconnspec name="empdb">
        <drivername value="com.ibm.db2.jdbcdvr"/>
        <urlname value="jdbc://myserver.ibm.com/employeedb"/>
        <connecttimeout value="60"/>
    </dbconnspec>
  </connconfig>

XML tags for pool specifications

Note:: This file uses UTF-8 encoding.

A file defines each instance of a PoolSpec record. A pool specification defines whether a connection pool supports connection pooling and defines properties required to support connection pooling. The pool specification is nested within a single <poolconfig> tag. Pool specification values are only used if connection pooling is enabled. See the description of the <poolingenabled> tag for more information.

The <hodpoolspec> tag is used to describe an HodPoolSpec record, and the <dbpoolspec> tag is used to describe an DbPoolSpec record. Both objects have the same set of properties with values defined using the set of nested tags described below:

connecttimeout

The time, in seconds, for which a requester of a connection waits to acquire a connection from the pool if no connections are available.

The value is an integer, either -1 or 0 or greater. The default is 120.

If connecttimeout is set to -1, the requester will wait forever.

dbconnspec

A reference to a DbConnSpec specification in another file. This tag (with different attributes) is used in .connspec files to define DbConnSpec records.

hodconnspec

A reference to a HodConnSpec specification in another file. This tag (with different attributes) is also used in .connspec files to define HodConnSpec records.

hodlogonspec

A reference to a HodLogonSpec specification in another file. This tag (with different attributes) is also used in .logonspec files to define HodLogonSpec records.

localuserpool

A reference to a LocalUserPool specification in another file. This tag (with different attributes) is used in .userpool files to define LocalUserPool records.

maxbusytime

The time in seconds, since a connection was last accessed, after which it is reclaimed. A connection is considered to be accessed when it is acquired or when it is released to the Host Publisher Server to save until the next Integration Object in a chained application acquires it. The connection is reclaimed and terminated if maxbusytime is not set to -1 and either of the following occurs:

An Integration Object acquires a connection, but does not release it to the pool in the time specified by maxbusytime
An Integration Object releases a connection to the Host Publisher Server to save for the next Integration Object in a chain, but the next Integration Object does not acquire it in the time specified by maxbusytime

The value is an integer, either -1 or 60 or greater. The default is -1.

If maxbusytime is set to -1, a busy connection is never reclaimed.

Note:: The maxbusytime parameter is in effect even when pooling is not enabled. If an Integration Object acquires a connection that is not pooled, the connection is reclaimed if the connection is not active and maxbusytime is not set to -1.

maxconnections

This is the maximum size of the pool. Once this many connections have been created and all connections have been acquired, the next requester will wait unless overflowallowed is set to true. In that case, a new non-pooled connection is created.

The value is an integer. The default is 1.

maxidletime

The time, in seconds, after which a connection that is idle is removed from the pool, if the number of connections in the pool exceeds minconnections.

The value is an integer, either -1 or 60 or greater. The default is -1.

If maxidletime is set to -1, an idle connection is never removed from the pool.

minconnections

The number of active connections in the pool below which idle connections are not disconnected, regardless of the value of maxidletime. This does not imply that Host Publisher Server Administration will create that many connections during initialization. The pool is populated on demand.

The value is an integer. The default is 0.

overflowallowed

If set to true, when a request is received for a connection and none is available (because the maxconnections limit has been reached), a new connection outside the pool is created. When this connection is released, it is ended and discarded.

The value is boolean. The default is false.

poolingenabled

If set to true, connection pooling is enabled and a request to acquire a connection from the pool results in an already-initialized connection being returned to the requester, if one is available. When the requester releases this connection, it is returned to the pool for later use.

If set to false, connection pooling is disabled and a request to acquire a connection from the pool results in a new connection being initialized and returned to the requester. When the requester releases this connection, it is terminated and discarded.

Note:

If connection pooling is disabled, the values of the following properties are ignored:

maxidletime
connecttimeout
minconnections
maxconnections
overflowallowed

The value is boolean. The default is true.

Examples

callup.poolspec

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE poolconfig SYSTEM "poolconfig.dtd">
<poolconfig>
  <hodpoolspec name="callup">
      <hodconnspec refname="vm6conn"/>
      <hodlogonspec refname="vm6"/>
      <localuserpool refname="vm6users"/>
      <maxidletime value="600"/>
      <minconnections value="10"/>
      <maxconnections value="20"/>
      <connecttimeout value="30"/>
      <overflowallowed value="true"/>
  </hodpoolspec>
</poolconfig>

puborder.poolspec

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE poolconfig SYSTEM "poolconfig.dtd">
<poolconfig>
  <hodpoolspec name="puborder">
      <hodconnspec  refname="vm6conn"/>
      <hodlogonspec  refname="vm6"/>
      <localuserpool  refname="vm6users"/>
      <connecttimeout value="30">
      <minconnections value="30"/>
      <maxconnections value="40"/>
  </hodpoolspec>
</poolconfig>

empdb.poolspec

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE poolconfig SYSTEM "poolconfig.dtd">
<poolconfig>
  <dbpoolspec name="empdb">
    <dbconnspec refname="empdb"/>
    <localuserpool refname="empdbusers"/>
    <connecttimeout value="20">
    <minconnections value="5"/>
    <maxconnections value="10"/>
  </dbpoolspec>
</poolconfig>

XML Tags for logon and logoff specifications

Note:: This file uses UTF-8 encoding.

A file defines each HodLogonSpec record.The logon specification defines information required by Host On-Demand for logging on and off a connection to a host. This file is only pertinent to Integration Objects created by the Host Access application. The <hodlogonspec> tag is used to describe an HodLogonSpec record, and is nested within a single <logonconfig> tag. The following XML tags correspond to properties of an HodLogonSpec record.

checkinscreendesc: References a file containing a string representation of a com.ibm.eNetwork.ECL.ECLScreenDesc object that is constructed in the Host Publisher Studio. This value is only used when connection pooling is enabled. When a connection is returned to Host Publisher Server, the Server checks the current screen against this screen description. If the current screen and this screen description match, the connection is returned to the pool. If the current screen and this screen description do not match, connection recovery might be initiated.
This string value is mandatory.
logoffmacro: References a file containing the Host On-Demand disconnect macro (in Host On-Demand-defined XML format). A disconnect macro may not be needed if the Integration Object's data macro includes disconnect actions or if certain public domain hosts do not need a disconnect step.
This file reference value is optional.
logonmacro: References a file containing the Host On-Demand connect macro (in Host On-Demand-defined XML format). A connect macro may not be needed if the Host Access Integration Object's data macro includes connect actions or if certain public domain hosts do not need a connect step.
This file reference value is optional.

IBM(R) WebSphere(R) Host Publisher; Programmer's Guide and Reference

IBM^(R) WebSphere^(R) Host Publisher; Programmer's Guide and Reference