Linkage properties file

A linkage properties file file is a text file that is used at Java™ run time to give details on how to call a remote program.

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 genProperties build descriptor option set to GLOBAL or PROGRAM.

How the linkage properties file is identified at run time

If the callLink element remoteBind property for a called program was set to runtime in the linkage options part, EGL looks for the linkage properties file at run time; the source of the file name is determined in the following ways:
  • A Java program checks the cso.linkageOptions.LO Java runtime property, where LO is the name of the linkage options part used for generation. If the property is not present, the EGL runtime 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 runtime 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.

Deploying a linkage properties file

The linkage properties file must be in the same project as the Java program that uses the file. If the file is in the top-level directory of the application, set the cso.linkageOptions.LO Java runtime property to the file name, without path information. If the file is under the top-level directory of the application, use a path that starts at the top-level directory and includes a forward slash (/) for each level, even if the application is running on a Windows® platform.

When you are developing a J2EE project, the top-level directory corresponds to the appClientModule, ejbModule, or Web Content directory of the project in which the module resides. When you are developing a Java project, the top-level directory is the project directory.

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:
  • The remoteBind property is necessarily runtime and is ignored.
  • The type property cannot belocalCall, 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. Use externalName for the alias property, not alias.
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=remoteCall
  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.

You can find more information in the topics "Naming conventions" and "Exception handling" in the EGL Language Reference.


Feedback