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 folder JavaResources\JavaSource.

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
The name of the Web transaction.

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).
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.
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 SUN 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.
location
For commtype=CICSECI, 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.
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=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.
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 gateway-servlet inspections of the linkage properties file.

    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.

Related tasks
Configuring a project to run Web transactions
Adding Web transaction support to an EGL Web project

Related reference
Gateway servlet parameters

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.