Web transaction linkage properties

The linkage properties file tells the gateway servlet where to find the web transactions and how to communicate with the web transactions. The function provided by the file is similar to the function provided by the linkage table in VisualAge® Generator Client/Server programs. This file is specified by the hptLinkageProperties parameter in the gateway servlet parameters. By default, the linkage properties are stored in the csogw.properties file in the Java™ Resources folder.

The linkage properties file contains three types of entries: application, serverLinkage, and options. Each application entry identifies one or more web transactions and is related to serverLinkage entries that indicate how to connect to those web transactions.

Following is an example of a linkage properties file:

application.WEBUITRAN=CICS5 
application.WEBUI*=CICS5 
application.STF*=idaho
application.MATT*=IMSC 
application.BASIC*=rtpas400 
application.Z*=remoteC

serverLinkage.CICS5.commtype=CICSECI 
serverLinkage.CICS5.contable=CSOE037
serverLinkage.CICS5.location=nracics5 
serverLinkage.CICS5.serverid=CPMI 
serverLinkage.CICS5.javaProperty=my.pkg

serverLinkage.idaho.commtype=TCPIP 
serverLinkage.idaho.contable=CSOX437 
serverLinkage.idaho.location=machine01
serverLinkage.idaho.serverid=9877 
serverLinkage.idaho.javaProperty=my.pak

serverLinkage.IMSC.commtype=TCPIMS 
serverLinkage.IMSC.contable=CSOE037 
serverLinkage.IMSC.location=carimsc
serverLinkage.IMSC.tcpport=4000 
serverLinkage.IMSC.javaProperty=my.pak 
serverLinkage.IMSC.imsgroupid=mygroup
serverLinkage.IMSC.imsdestid=IMSC  
serverLinkage.IMSC.serverid=*  

serverLinkage.rtpas400.commtype=as400
serverLinkage.rtpas400.contable=CSOE037 
serverLinkage.rtpas400.location=rtpas400
serverLinkage.rtpas400.javaProperty=my.pag 
serverLinkage.rtpas400.library=sdearth

serverLinkage.remoteC.commtype=cicseci 
serverLinkage.remoteC.contable=CSOI1252
serverLinkage.remoteC.location=CSONT2 
serverLinkage.remoteC.serverid=CPMI
serverLinkage.remoteC.ctgLocation=ctghostname 
serverLinkage.remoteC.ctgPort=2006
serverLinkage.remoteC.javaProperty=my.cicspkg

Application entries

Each application entry has the following format:

application.webtran=servername

webtran

The name of the web transaction.

The final character can be the wildcard character (*). The entry application.webui*=CICS5, for example, is used for all web transactions that start with the characters webui.

If multiple application entries match a web transaction name, the most specific entry takes precedence. For example, a gateway servlet tries to access web transaction webuitran when the linkage properties file contains the following entries:

application.webui*=abc 
application.webuit*=def

In this case, the second statement is used

servername

An arbitrary name that you assign to an application entry and to a related set of serverLinkage entries for a particular web transaction. Consider the following application entry, for example:

application.SERVER1=CICS5

To access a web transaction called SERVER1, the gateway servlet refers to the serverLinkage entries that are identified by CICS5.

ServerLinkage entries

Each serverLinkage entry has the following format:

serverLinkage.servername.parameter=value

servername

An arbitrary name that you assign to a set of serverLinkage entries for a particular web transaction. The name must be present in an application entry.

parameter

One of the following:

commtype

Specifies the type of communications used to access the web transaction. The valid values are as follows

AS400: For use when the web transaction resides on OS/400®.
CICSECI: For use when the web transaction resides on CICS® (CICS® for AIX®, CICS® for MVS™, CICS® for Solaris, or CICS® for VSE).
JCICS: For use when the web transaction resides on CICS® for MVS™ and the gateway servlet is running under CICS® Liberty.
DIRECT: For use when the web transaction is a Java™ program, tier 2 and tier 3 are the same Windows™ 2000 or Windows NT™ machine, and you want the web transaction to run in a thread of the Java™ Virtual Machine in which the gateway servlet is running. Only in this case is the program property enableJ2EE valid.
TCPIMS: For use when the web transaction resides on an IMS™ system.
TCPIP: For use when the web transaction resides on a native Windows™ 2000, Windows NT™, OS/2®, AIX®, HP-UX or Solaris system. If the tier 2 and tier 3 environments are the same Windows™ 2000 or Windows NT™ machine, consider using commtype DIRECT instead of TCPIP.

contable

Specifies the conversion table used on the tier 2 platform. The format is as follows:

CSOzxxxx;

z

One of the following binary formats, which refers to the tier 3 platform:

I (for Intel™)
E (for EBCDIC)
J (for Java™ Unicode)
X (for UNIX™)

xxxx

The code page used for conversion.

The Java™ conversion routines convert the data in accordance with the data definitions in the UI record. For more information on conversion tables for different languages and platforms, see the VisualAge® Generator Client/Server Communications Guide.

ctgLocation

Optional. Specifies the machine where the CICS® Transaction Gateway resides. If you do not specify ctgLocation and ctgPort when commtype=CICSECI, the CICS® Transaction Gateway is assumed to be local.

ctgPort

Optional. Specifies the port on which where the remote CICS® Transaction Gateway listens. If you do not specify ctgLocation and ctgPort when commtype=CICSECI, the CICS® Transaction Gateway is assumed to be local.

Note:

The procedure for setting the port number of the CICS® Transaction Gateway listener depends on the version of that product:for version 3.01, use the ctgStart -port command; for version 3.03, use the JGate -port command; for other versions, see the CICS® Transaction Gateway configuration manual. The default port number is 2006.

debugcontable

Equivalent to contable, but used by the EGL debugger. Set this parameter if the generated code uses one table while the debugger uses a second.

The default is the value specified for contable.

location

For commtype=CICSECI or commtype=JCICS, specifies the CICS® system identifier that corresponds to the server name in the CICSCLI.INI file of the CICS® Client.

For commtype=TCPIMS, commtype=TCPIP, or commtype=AS400, specifies the TCP/IP host name of the machine where the web transaction resides.

This option is not required when using JCICS to call CICS® programs residing under the same CICS® region as the gateway servlet.

remoteapptype

If the web transaction is a Java™ program and commtype=TCPIP, specify the value VGJAVA; otherwise, do not include this parameter.

serverid

For commtype=CICSECI, specifies the CICS® trans-id for the catcher. In most cases, the following is true:

The value of serverid is CPMI, which causes invocation of program DFHMIRS.
If you specify a trans-id other than CPMI, CICS® starts CPMI, which switches control to the CICS® transaction you specify, which in turn switches control to program DFHMIRS.

To avoid starting CPMI when the trans-id is not CPMI, prepend tpn_ to the trans_id. If the trans-id is WEBT, for example, specify tpn_WEBT; but if the trans-id is CPMI, specify only CPMI. If you specify WEBT without tpn_, CICS® starts CPMI, which in turn switches control to WEBT.

Note:

In relation to OS/390®, serverid is ignored and the CICS® transaction always runs as CPMI unless the following is true:

CICS® TS V1.3 is installed with PTF UQ47399.
CICS® Transaction Gateway is at or aboveV3.1.2.

For commType=JCICS, specifies the CICS® trans-id for the catcher in the remote CICS® region (default is CPMI). The trans-id you specify must point to DFHMIRS. This option is ignored when using JCICS to call CICS® programs residing under the same CICS® region as the gateway servlet.

For commtype=TCPIP, serverid specifies the port number of the listening socket on the machine where the web transaction resides.

For commtype=TCPIMS, serverid specifies the IMS™ transaction code. If you set serverid=*, the value of servername is used as the transaction code.

For commtype=AS/400, serverid is not used.

tcpport

For commtype=TCPIMS, specifies the port number of the listening socket on the machine where the web transaction resides. The listening socket is configured in the IMS™ TCPIP Open Transaction Manager Access connection (ITOC).

javaProperty

Specifies the Java™ package where the UI record object and UI record bean for the web transaction are located. This entry is case sensitive.

imsgroupid

Specifies a RACF® group to which the user must be connected for authentication. This entry is valid only for TCPIMS connections.

imsdestid

Specifies the IMS™ system in which the web transaction runs, as that system is defined by the ITOC configuration. This entry is valid only for TCPIMS connections.

keyring

Optional. It is required when keyring Password is specified. For commtype=CICSECI, keyring is the name of the keystore generated with the Java™ tool keytool.exe or with the CICS® Transaction Gateway tool IKEYMAN, and the CICS® transaction gateway is assumed to use ssl. Do not include this parameter for other commtype.

keyringPassword

Optional. It is required when keyring is specified. For commtype=CICSECI, keyringPassword is the password used when generating the keystore, and the CICS® transaction gateway is assumed to use ssl. Do not include this parameter for other commtype.

library

Specifies the name of the library on the OS/400® system where the web transaction resides. If the tier 3 platform is OS/400® and you omit this entry or leave it blank, VisualAge® Generator searches for the web transaction in the QVGEN library, then in the library list specified by OS/400® variable QUSRLIBL.

value

The value to which the parameter is set.

Options entries

The following options entries are valid:

hptGateway.propertiesRefreshInterval=n

n

Specifies the number of minutes that pass between inspections of the linkage properties file by the gateway servlet.

This entry lets you dynamically put into effect any changes made to the linkage properties file, without your being required to stop and start the web application server. Web transactions initiated after the inspection are invoked with the new values. A value of 0 indicates that the gateway servlet reviews the linkage properties file only at startup.
application.webtran.traceFlag=n

webtran

The name of the web transaction, the same as the same-named parameter in application entries.

n

Indicates whether the gateway servlet is to provide internal, communications layer tracing, which is useful only if you are in contact with IBM® support. Alternatives are 1 (for tracing) or 0 (for none, as is the default). A communications layer trace requires the presence of the gateway servlet parameter hptErrorLog, which is usually in the gateway properties file.