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).
- 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, 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.
- 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.