Elastic Transaction Platform (ETP) Deployment Wizard – Heirloom Computing

Introduction

The ETP Deployment Wizard is used to set up an Elastic COBOL project (configured for operation with the Elastic Transaction Platform Project Template project compatibility setting) for use within a JEE server. The output, an Enterprise Application Archive, or EAR file, is deployed to a JEE application server with EJB support. The Wizard is an optional step in that the EAR file can be created with other tools such as make, ant or maven following the EAR standards and conventions. But, the ETP Deployment Wizard is a simplified approach for creating what amounts to be CICS Regions.

The ETP Deployment Project doesn't contain application code ... that's the role of the Elastic COBOL Project in Eclipse. Instead, it holds configuration settings and references the Elastic COBOL Project that contains the ETP transactions. The ETP Deployment Project contains one file, the ETP Settings File.

Creating the ETP Deployment Project

As discussed in the Getting Started Guide, create a new ETP Deployment Project from within the Eclipse IDE by selecting File > New > Other > Elastic Transaction Platform > ETP Project.

Fig. 1. Create an ETP Project

The project creates a new ETP Deploy Settings File and opens the project. Fig 2. shows the settings wizard pane and an overview of the settings categories.

Fig. 2. ETP Deployment Settings (Property View)

In Fig. 2, theJava EE folder created by the new project operation has been expanded. These are the various configuration settings that make an EAR work under various conditions and with a variety of servers.

ETP Deployment Settings

ETP settings are divided into 3 areas:

CICS settings - ETP settings that map to CICS options
Tracing and Logging - Tracing of CICS API calls and ETP operations
JEE Server Settings - Interfacing ETP environment with the Java EE Server

The settings are shown through a series of categories or tabs shown on the main Property tab, shown in Fig. 2. You can also switch to the text XML view of the settings at any time named project.etp_deploy_settings, shown in Fig 3. Any changes made in the Property view will be reflected by the wizard into the text view. Although the text view doesn't allow the items to be changed the file project.etp_deploy_settings file can be opened withe Eclipse's standard Text Editor to make changes. Those manual edits may not be represented by the wizard the next time you open it up.

Fig. 3. ETP Deployment Settings (Text View).

Many of the tabs are divided into an overview and a detail view. Selecting the item from the table in an overview window and clicking Edit button will display the detail view of that one item. Clicking the Add button will add a new item to the list and selecting and then clicking remove will delete the item. In the sections that follow the overview and detail views from the Properties tab will be presented along with the text equivalent from the project.etp_deploy_settings view.

General

The General tab names the ETP system, the equivalent to a CICS Region on the mainframe. It serves a place to define the participating Elastic COBOL (and Java) projects that are part of the same Eclipse workspace.

Fig. 4. General tab.

General tab settings:

SYSID - the ETP system ID, or "region name," that will also serve as part of the EJB name used to distinguish this region from others deployed to the same JEE server
APPLID - the (optional) ETP application ID that will may used by transactions running in one SYSID to refer to other transactions by application ID in a different region
Participating Projects - Click the Elastic COBOL or Java applications that are to participate in this ETP region. When the wizard deploys the EAR file it will collect executable and other resources from each project

The ETP settings view:

# Elastic Transaction Platform deploy settings
_projects=etpprograms
applid=etai
sysid=etsy

Programs

The Programs tab describes the programs names that are used when other regions link to programs in this region. These program names are mapped to a Java class (i.e., COBOL program ID).

Fig. 5. Programs tab.

Overall Program settings:

Programs - The list of all programs known in this CICS region. The list is initially populated by the main programs from the Participating Projects in the Fig. 4. As more programs are added to those projects you must add them to this list manually. See the detail view on Add, Edit and Remove of individual program IDs
Strict condition PGMIDERR enabled - (default off) When checked a PGMIDERR condition arises for missing programs.
Reinitialize programs on LINK - (default on) When checked, local program storage is reinitialized when programs or transactions transfer control to this program. It may help in debugging a transaction when this is on and it may speed execution if this is off.

Fig. 6. Program detail views (Local and Distributed).

Detail Program settings:

Program ID - the program name by which external programs can refer to this program, 8 characters max.
Location - (default local) Local programs are contained in this EAR file, distributed programs are a synonym for distributed program link (DPL) transactions that are actually resident on a remote ETP. Usually this is used when programs are moved from one ETP to another but other (local) programs still link to it thinking it is local.
Class - Select the Java class backing up this ETP program ID from the class hierarchy that indicates the COBOL or Java application for it
Initial parameters - (optional) indicates the list of parameters if not passed to the program
URI - the URL of the EJB directory or Java naming protocol daemon handling lookup requests for this JEE server. For example, "ejbd://remotehost:4201/" indicates that EJB Directory protocol will be used to lookup the names on the host "remotehost" and the EJBD process is listening on port 4201.
DPL SYSID - The remote SYSID of the region containing the program. The ETP region running on the remote server ("remotehost') must have been configured with this SYSID.
DPL TRANSID - The 4-character transaction ID that maps to the remote program on the remote server.

The ETP settings view:

# Elastic Transaction Platform deploy settings
program.etpeasn=etpeasn
program.etpedpl=ejbd://localhost:4201
program.etpedpl.sysid=west
program.etpedpl.transid=etrn

Transaction

The transactions tab maps the 4-character transaction IDs used in EXEC CICS LINK calls to the program IDs that, through the Programs tab. indicate which application should be run. Whether your system uses program IDs or trans IDs on its EXEC CICS LINK API statements is up to you. You may not need to define trans IDs if you only refer to program IDs.

Fig. 7. Transaction tab

Overall Transaction Settings:

Transactions - The mapping from transaction ID to program ID
Principal Facility - Facilities are used to make the connection between the transaction and the end-user. When running under JEE application servers and containers the ETP HTMLServlet facility is the default setting and allows the transaction to be accessed through the HTTP Servlet interface, delivering up HTML representations of the Basic Mapping Support (BMS) screens used by the transaction.
Uppercase Translation - Perform upper case translation on all input from the "terminals" (Web browsers, RESTful Web services, JCA connectors, EJB invocations) before that input is seen by the transactions (CICS UCTRAN equivalent).

Note: Always define the INIT (init) transaction to indicate the initial program, perhaps a transaction that invokes EXEC CICS LOGIN (e.g., CESN) or your menu transaction. This will be the default transaction that is invoked if the transaction ID is not specified on the request.

Fig. 8. Transaction Detail

Detail Transaction Settings:

Transaction ID - Enter the 4-character transaction ID that is to be defined
Program ID - Select from the list of Program IDs that were entered on figure 5.

The ETP Settings View:

# Elastic Transaction Platform deploy settings
transaction.etdq=etpetdq

transaction.etrn=etpetrn
transaction.init=etpemnu
uctran=true

SQL

The SQL tab defines the automatic database connections that occur when programs issue EXEC SQL API calls. unlike standard COBOL applications, CICS transactions generally do not issue CONNECT statements (although they may issue SET CONNECTION statements). ETP handles the connection pooling of database handles when multiple concurrent transactions are running under the server. This SQL tab defines the JDBC connection criteria that should be used when a new connection must be made. They map a connection name to JDBC connection settings.

For each SQL connection provide the following information:

Connection Name - the name by which the connection information is referenced. Names may provide a "high level qualifier" of the dataset name for VDB protocol files. For example, a VDB dataset A.B.C.IDX may have connection names A or B for the VDB table C.
Datasource - (optional) when connections are controlled by the JEE Application Server this corresponds to the datasource name referenced within that system's configuration. If provided, the datasource name will define all the remaining SQL connection attributes.
URL - (optional) the JDBC universal resource locater for the the database management system (e.g., jdbc:mysql://localhost/mydb).
Username - (optional) the relational database management system authorized user name to access this database
Password - (optional) the password for the authorized user name
Driver - (optional) the JDBC driver class name designated for this driver, which must be on the classpath or deployed with the .war or .ear file making up the ETP region. Associate the ETP's corresponding COBOL project(s) with specific drivers in the Java Build Path (Libraries tab) within the Eclipse project settings.
Autocommit - (optional) indicate whether the database autocommit feature is "on" or "off." Normally, for ETP transactions under control of the JEE Server this should be set to "off" such that ETP explicit or implicit SYNCPOINT operations will control when transactions are committed.
Isolation Level - (optional) indicates the transactional isolation level to use for this connection.

When datasources are configured in the JEE Application Server (e.g., IBM Websphere, Red Hat JBOSS/Wildfly, Oracle Weblogic) or Servlet Container (e.g., Eclipse Jetty, Apache Tomcat) only the Connection Name and Datasource properties need to be specified. The connection attributes are JEE AS or Container-specific. For example, in Apache Tomcat you modify the Java EE/war/META-INF/context.xml file to contain these attributes. For example, setting ETP Deploy Settings SQL tab Connection Name to default and Datasource to jdbc/LocalPG allows you to define

<context> ...  <Resource name="jdbc/LocalPG" auth="Container" type="javax.sql.DataSource" maxTotal="100" maxIdle="30" maxWaitMillis="10000" defaultAutoCommit="false" defaultReadOnly="false" defaultTransactionIsolation="REPEATABLE_READ" username="postgres" password="abc000" driverClassName="org.postgresql.Driver" url="jdbc:postgresql://localhost/mydb" /> </context>

There are two special connection names that may be present in this tab:

default - the default connection that is used should the transaction not use EXEC SQL SET CONNECTION ... END-SQL statement.
file - the connection name that is used when you are using the ETP data transparency layer that maps CICS file I/O to relational databases. Used for VDB (record-oriented VSAM transparency mode) and VSQL (column-oriented VSAM transparency mode).

There are a few global SQL configuration parameters that govern all SQL connections and are set with checkboxes on the SQL tab:

Strict XA/2PC checking - when checked indicates that two-phase commit-capable JDBC drivers are required and will participate under control of the JEE Server to provide 2PC across multiple servers. When unchecked (default), ETP will commit transactions by serially going through all the resource managers (database connections)
Disconnect / Reconnect SQL - disconnect from the database after each ETP SYNCPOINT operation and reconnect to the database when necessary (default). When unchecked, leave the connection open for the life of the ETP session. The unchecked setting may be required on certain JEE Servers such as RedHat Wildfly (JBOSS) because of the way the server spreads transactions from a session across multiple processes.

Fig. 9. SQL tab

The overview SQL settings are:

SQL Connection Names/Values - Consists of a number of attributes for each connection name. The table can be scrolled left-to-right to see an attribute of all the connection names but it is easier to view the attributes by selecting and editing a particular connection name. See the detailed view below
String XA/2PC checking - Only JDBC drivers that support the two-phase commit protocol will be used and ETP, in conjunction with the encompassing JEE application server, will prepare all resources then commit all resources participating in a transaction when a EXEC CICS SYNCPOINT END-EXEC API call is used.

Fig 10. SQL detail

Detail SQL Settings:

Connection name - the name associated with this group of settings. It is also the name by which the application can switch SQL contexts using the EXEC SQL SET CONNECTION name END-SQL statement.
Datasource - (optional) If left empty datasource names are not being used for this set of attributes. If a JEE datasource name is specified it must be specified as "dsname:uri" indicating the naming context lookup that should be used to find the definition of this datasource. For example, "ds:ejbd://remotehost:4201" will use EJBD protocol to lookup the datasource named "ds." The datasource should be configured under that naming protocol with the remainder of attributes specified below.
Username - the principal name under which the JDBC SQL connection should be made.
Password - the credentials that should be included in the connection to the database
Connection URL - the JDBC connection URI that specifies information needed to make the connection to a specific database, database server, and driver type. This is database and driver specific. For example, the following indicates that JDBC protocol should be used to connect to the postgresql driver to the remote host name dbhost.intranet. The driver will determine the default port number or it may also be specified. Finally, the customerdb database is connected.

jdbc:postgresql://dbhost.intranet/customerdb

Driver classname - the classname for the JDBC driver to use. Since JDBC 3 and later, this has been optional since the JDBC driver manager asks all loaded classes to respond to the driver name, "postgresql" in this case. But, in EAR files a large number of JAR files are included in the affiliated projects' resources directories. In order to help the class name lookup process in Java it is recommended that the Driver classname be specified. Otherwise, it may be necessary to "unpackage" the driver jars and include them with your programs in the application jar files.
Auto Commit - By default for most databases used with ETP set this to false indicating that an EXEC CICS SYNCPOINT END-EXEC statement or a EXEC SQL COMMIT WORK END-EXEC statement should be issued by the application when the transactions should be committed to disk. If set to true then each database statement is a transaction.
Isolation Level - The isolation level determines the way in which transactions are isolated from one another in the way in which cursors, for example, are re-read and re-used within a transaction. The database-specific default is changed to the mainframe DB2 default of "cursor stability", which is closest to "repeatable read" in JDBC database terminology.

Repeatable Read - Indicating that dirty reads and non-repeatable reads are prevented; phantom reads can occur. This level prohibits a transaction from reading a row with uncommitted changes in it, and it also prohibits the situation where one transaction reads a row, a second transaction alters the row, and the first transaction rereads the row, getting different values the second time (a "non-repeatable read"). Text setting is repeatable.
Read Uncommitted - Indicating that dirty reads, non-repeatable reads and phantom reads can occur. This level allows a row changed by one transaction to be read by another transaction before any changes in that row have been committed (a "dirty read"). If any of the changes are rolled back, the second transaction will have retrieved an invalid row. Text setting is uncommitted.
Read Committed - Indicating that dirty reads are prevented; non-repeatable reads and phantom reads can occur. This level only prohibits a transaction from reading a row with uncommitted changes in it. Text setting is committed.
Serializable - Indicating that dirty reads, non-repeatable reads and phantom reads are prevented. This level includes the prohibitions in Repeatable Read and further prohibits the situation where one transaction reads all rows that satisfy a WHERE condition, a second transaction inserts a row that satisfies that WHERE condition, and the first transaction rereads for the same condition, retrieving the additional "phantom" row in the second read. Text setting is serializable.

Catalog - (optional) This sets the default catalog (DB2 terminology) or "schema" name that should be used when high-level table qualifiers are missing on EXEC SQL statements and the default is not implied by principal ownership settings within the database. There may be other database-specific ways in which this is set.
Read Only - This sets the database connection to a read-only condition, when true, which will prevent updates even if the transaction issues INSERT or DELETE statements, for example. The default is false for normal database operations.

The ETP Settings text view:

# Elastic Transaction Platform deploy settings
sql.customers.autocommit=false
sql.customers.driver=org.postgresql.Driver
sql.customers.isolation=repeatable
sql.customers.password=abc000
sql.customers.readonly=false
sql.customers.catalog=
sql.customers.url=jdbc:postgresql://localhost/gary
sql.customers.user=postgres

HTML Templates

Journals

ETP Journals map to a number of external entities:

Text files
Java Log4J journal files
JMS Queues
Server stdout file
Server stderr file

Use the "Add..." button in the ETP deployment settings wizard under the Journals category to name the journal referenced in the "EXEC CICS WRITE JOURNALNAME(name)" statement.

Provide the JNDI Queue name for JMS queues, a text file name for text files or target name for Log4J journals.

Queues

ETP Queues map to JMS queues, which themselves may be backed by transactional AQ Series or IBM MQ Series queue managers. Use the "Add..." button in the ETP deployment settings wizard under the Queues category to name and define the external representation of the temp storage or transient data queue:

Provide the following information:

SYSID - the sysid of the system holding the queue
Queue Local Name - the queue name referenced in the "EXEC CICS WRITEQ TS QUEUE (queuename)" statement
Queue Type - one of

Session - an internal session-specific queue that is private to a particular ETP session
JMS - an external Java Messaging Service queue type, provide the JMS connection to a queue manager that maintains persistence
JMS (Temporary/Task Scope) - Task scope temporary queue
JMS (Temporary/Session Scoep) - Session scope tempoary queue
EBP Internal Reader - A queue that serves as a conduit to submit JCL jobs to the Elastic Batch Platform internal reader, provide the URL to the EBP installation
NULL - a null queue that reads as empty and throws away any WRITEQ messages

JMS Connection - provided for JMS protocol queues
Connection Name - the name for private Session protocol queues
Queue JNDI Name - the JNDI name associated with this JMS protocol spool

Spools

EBP spools map to the same external entities that Queues map map to. Information is provided with the "Add..." button on the Spools category within the ETP Deployment Settings wizard:

Provide the following information:

User ID - user ID of the spool
Protocol - one of

Session - an internal session-specific queue that is private to a particular ETP session
JMS - an external Java Messaging Service queue type, provide the JMS connection to a queue manager that maintains persistence
JMS (Temporary/Task Scope) - Task scope temporary queue
JMS (Temporary/Session Scoep) - Session scope tempoary queue
EBP Internal Reader - A spool that serves as a conduit to submit JCL jobs to the Elastic Batch Platform internal reader, provide the URL to the EBP installation
NULL - a null spool that throws away any messages written to it

Symbolic Name - provided for Session protocol spools
EBP Submit - the submit Web service URL for the targeted EBP system for EBP protocol spools
JNDI Name - the JNDI name associated with this JMS protocol spool
Spool Class (optional) - the spool class A..Z
Spool Node (optional) - the spool node if not local

JMS

The JMS category of the ETP deployment wizard provides more information for JMS queues used in the Queues and Spools tab. When mapping JMS to IBM MQ Series, for example, you must provide the JNDI factor names, class names, resource adapters and/or MDB definition and activation specifications. See Java Messaging Service configuration for more information.

Program Control

The Program control category of the ETP deployment wizard provides more information for other servers used when cross-connecting Java application servers with Distributed Program Link inter-system communication. You provide the resource symbolc name mapping that is necessary to connect to other systems. For example, provide,

Source Name = ETPSYSL_etp2_INITIAL_CONTEXT_FACTORY

OpenEJB

Destination Name = org.apache.openejb.client.RemoteInitialContextFactory

Oracle WebLogic

Destination Name = weblogic.jndi.WLInitialContextFactory

IBM WebSphere 8.5 (Full Profile)

Destination Name = com.ibm.websphere.naming.WsnInitialContextFactory

and

Source Name = ETPSYSL_etp2_PROVIDER_URL

OpenEJB

Destination Name = ejbd://10.20.30.40:4201

Oracle WebLogic

Destination Name = t3://10.20.30.40:7001

IBM WebSphere 8.5 (Full Profile)

Destination Name = iiop://10.20.30.40:2809

in order to define a linkage between this system and ETP region name "etp2" that is running on a JEE server at location 10.20.30.40. The Apache OpenEJB library provides the EJB connection package and the remote JEE server is listening on EJBD directory context lookup port 4201. By default, Oracle's WebLogic uses it's own implementation of the RMI specification and favors it's own proprietary protocol known as T3 with the context lookup port 7001. Similarly, IBM's WebSphere 8.5 (full profile) utilizes the Internet Intra-ORB Protocol (IIOP) with the context lookup port 2809.

File Control

Date/Time

Operator

Trace

We currently support 4 types of tracing in an ETP project. They can all be configured by editing deploy.properties or if you are using Heirloom Eclipse plugin by choosing Category 'Trace' when opening deploy.properties.

Here are the level of tracing that can be configured:

System tracing - follows tracing activity in a CICS system
User tracing - follows tracing activity from users
Master tracing - requires to be turned on in order for any of the other tracing to be performed

A journal destination for trace (that was added earlier) can be configured here in the menu.

An example of deploy.properties configuration:

journal.=<journal_protocol>\:<journal_destination>
trace=<journal_name>
trace.master=true
trace.user=true

JEE Application

JEE Servlet

JEE Security Roles