Linkage properties file (details)

When you generate a calling Java program or wrapper, you can specify that linkage information is required at run time. You make that specification by setting the linkage-option values for the called program as follows:

A linkage properties file may be handwritten, but EGL generates a file if (in addition to the settings described earlier) you generate a Java program or wrapper with the build descriptor option genProperties set to GLOBAL or PROGRAM.

How the linkage properties file is identified at run time

If the callLink element property remoteBind for a called program was set to RUNTIME in the linkage options part, the linkage properties file is sought at run time; but the source of the file name is different for Java programs and Java wrappers:

A Java program checks the Java run-time property cso.linkageOptions.LO, where LO is the name of the linkage options part used for generation. If the property is not present, the EGL run-time code seeks a linkage properties file named LO.properties. Again, LO is the name of the linkage options part used for generation.
In this case, if the EGL run-time code seeks a linkage properties file but is unable to find that file, an error occurs on the first call statement that requires use of that file. For details on the result, see Exception handling.
The Java wrapper stores the name of the linkage properties file in the program object variable callOptions, which is of type CSOCallOptions. The generated name of the file is LO.properties, where LO is the name of the linkage options part used for generation.
In this case, if the Java Virtual Machine seeks a linkage properties file but is unable to find that file, the program object throws an exception of type CSOException.

Format of the linkage properties file

As used during run time, the linkage properties file includes a series of entries to handle each call from the generated Java program or wrapper that you are deploying.

The primary entry is of type cso.serverLinkage and can include any property-and-value pair that you can set in a callLink element of the linkage options part, with the following exceptions:

Property remoteBind is necessarily RUNTIME and should not appear
Property type cannot be localCall, because linkage for local calls must be established at generation time

cso.serverLinkage entries

In the most elementary case, each entry in the linkage properties file is of type cso.serverLinkage. The format of the entry is as follows:

  cso.serverLinkage.programName.property=value

programName: The name of the called program. If the called program is generated by EGL, the name you specify is that of a program part.
property: Any of the properties appropriate for a Java program, except for properties remoteBind and pgmName. For details, see callLink element.
value: A value that is valid for the specified property.

An example for called program Xyz is as follows, where xxx refers to a case-sensitive string:

  cso.serverLinkage.Xyz.type=ejbCall
  cso.serverLinkage.Xyz.remoteComType=TCPIP
  cso.serverLinkage.Xyz.remotePgmType=EGL
  cso.serverLinkage.Xyz.externalName=xxx
  cso.serverLinkage.Xyz.package=xxx
  cso.serverLinkage.Xyz.conversionTable=xxx
  cso.serverLinkage.Xyz.location=xxx
  cso.serverLinkage.Xyz.serverID=xxx
  cso.serverLinkage.Xyz.parmForm=COMMDATA
  cso.serverLinkage.Xyz.providerURL=xxx
  cso.serverLinkage.Xyz.luwControl=CLIENT

The literal values TCPIP, EGL, and so on are not case sensitive and are examples of valid data.

cso.application entries

If you wish to create a series of cso.serverLinkage entries that refer to any of several called programs, precede those entries with one or more entries of type cso.application. Your purpose in this case is to equate a single application name to multiple program names. In the subsequent cso.serverLinkage entries, you use the application name instead of programName; then, at Java run time, those cso.serverLinkage entries handle calls to any of several programs.

The format of a cso.application entry is as follows:

  cso.application.wildProgramName.appName

wildProgramName: A valid program name, an asterisk, or the beginning of a valid program name followed by an asterisk. The asterisk is the wild-card equivalent of one or more characters and provides a way to identify a set of names.
If wildProgramName refers to a program that is generated by EGL, any program name included in wildProgramName is the name of a program part.
appName: A series of characters that conforms to the EGL naming conventions. The value of appName is used in subsequent cso.serverLinkage entries.

The following example show use of an asterisk as a wild-card character. The cso.serverLinkage entries in this example handle any call to a program whose name begins with Xyz:

  cso.application.Xyz*=myApp
  cso.serverLinkage.myApp.type=remoteCall
  cso.serverLinkage.myApp.remoteComType=TCPIP
  cso.serverLinkage.myApp.remotePgmType=EGL
  cso.serverLinkage.myApp.externalName=xxx
  cso.serverLinkage.myApp.package=xxx
  cso.serverLinkage.myApp.conversionTable=xxx
  cso.serverLinkage.myApp.location=xxx
  cso.serverLinkage.myApp.serverID=xxx
  cso.serverLinkage.myApp.parmForm=COMMDATA
  cso.serverLinkage.myApp.luwControl=CLIENT

The following example shows use of the same cso.serverLinkage entries to handle calls to any of several programs, even though the names of those programs do not begin with the same characters:

  cso.application.Abc=myApp
  cso.application.Def=myApp
  cso.application.Xyz=myApp
  cso.serverLinkage.myApp.type=remoteCall
  cso.serverLinkage.myApp.remoteComType=TCPIP
  cso.serverLinkage.myApp.remotePgmType=EGL
  cso.serverLinkage.myApp.externalName=xxx
  cso.serverLinkage.myApp.package=xxx
  cso.serverLinkage.myApp.conversionTable=xxx
  cso.serverLinkage.myApp.location=xxx
  cso.serverLinkage.myApp.serverID=xxx
  cso.serverLinkage.myApp.parmForm=COMMDATA
  cso.serverLinkage.myApp.luwControl=CLIENT

If multiple cso.application entries are valid for a program, EGL uses the first entry that applies.