EGL Reference Guide for iSeries

callLink element

The callLink element of a linkage options part specifies the type of linkage used in a call. Each element includes these properties:

The value of the type property determines what additional properties are available, as shown in the next sections:

If callLink type is localCall (the default)

Set property type to localCall when you are generating a Java program that calls a generated Java program that resides in the same thread. In this case, EGL middleware is not in use, and the following properties are meaningful for a callLink element in which pgmName identifies the called program--

You do not need to specify a callLink element for the call if the called program is in the same package as the caller and if either of these conditions is in effect:

The value of type cannot be localCall when you are generating a Java wrapper.

If callLink type is remoteCall

Set property type to remoteCall when you are generating a Java program or wrapper, and the Java code calls a program that runs in a different thread. The call is not by way of a generated EJB session bean. In this case, EGL middleware is in use, and the following properties are meaningful for a callLink element in which pgmName identifies the called program--

If callLink type is ejbCall

Set property type to ejbCall when a callLink element is required to handle either of the following situations:

In this case, EGL middleware is in use, and the following properties are meaningful for a callLink element in which pgmName identifies the called program:


Related concepts
Linkage options part
Run-time configurations


Related tasks
Editing the callLink element of a linkage options part


Related reference
alias in callLink element
conversionTable in callLink element


linkType in callLink element
location in callLink element


package in callLink element


pgmName in callLink element
providerURL in callLink element
remoteBind in callLink element
remoteComType in callLink element
remotePgmType in callLink element
serverID in callLink element
type in callLink element

alias in callLink element

The linkage options part, callLink element, property alias specifies the run-time name of the program identified in property pgmName. The property is meaningful only when pgmName refers to a program that is called by the program being generated.

The value of this property must match the alias (if any) you specified when declaring the program. If you did not specify an alias when declaring the program, either set the callLink element property alias to the name of the program part or do not set the property at all.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element
pgmName in callLink element

conversionTable in callLink element

The linkage options part, callLink element, property conversionTable specifies the name of the conversion table that is used to convert data on a call. The property is meaningful only when pgmName identifies a program that is called by the generated program or wrapper.

When you generate a COBOL program, these details are in effect:

When you generate a Java program or wrapper, the following details are in effect:

Select one of the following values:

conversion table name
The caller uses the conversion table specified. For a list of tables, see Data conversion.
*
Uses the default conversion table. For a COBOL client, the name of that table is ELAxxx, where the value of xxx is the value of build descriptor option targetNLS. For a Java client, the selected table is based either on the locale of the client machine or (if the client is running on a Web application server) on the locale of that server. If an unrecognized locale is found, English is assumed.

For a list of tables, see Data conversion.

programControlled
The caller uses the conversion table name that is in the system item sysVar.callConversionTable at run time. If sysVar.callConversionTable contains blanks, no conversion occurs.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
Bidirectional language text
callLink element
Data conversion
pgmName in callLink element
sysLib.convert
targetNLS
type in callLink element

ctgKeyStore in callLink element

The linkage options part, callLink element, property ctgKeyStore is the name of the key store generated with the Java tool keytool.exe or with the CICS Transaction Gateway tool IKEYMAN. This property is required when the value of property remoteComType is set to CICSSSL.


Related concepts
Linkage options part


Related reference
callLink element
ctgKeyStorePassword in callLink element
remoteComType in callLink element

ctgKeyStorePassword in callLink element

The linkage options part, callLink element, property ctgKeyStorePassword is the password used when generating the key store.


Related concepts
Linkage options part


Related reference
callLink element
ctgKeyStore in callLink element
remoteComType in callLink element

ctgLocation in callLink element

The linkage options part, callLink element, property ctgLocation is the URL for accessing a CICS Transaction Gateway (CTG) server, as is used if the value of property remoteComType is CICSECI or CICSSSL. Specify the related port by setting the property ctgPort.


Related concepts
Linkage options part


Related reference
callLink element
remoteComType in callLink element

ctgPort in callLink element

The linkage options part, callLink element, property ctgPort is the port for accessing a CICS Transaction Gateway (CTG) server, as is used if the value of property remoteComType is CICSECI or CICSSSL. Specify the related URL by setting the property ctgLocation.

If the case of CICSSSL, the value of ctgPort is the TCP/IP port on which a CTG JSSE listener is listening for requests; and if ctgPort is not specified, the CTG default port of 8050 is used.


Related concepts
Linkage options part


Related reference
callLink element
ctgLocation in callLink element
remoteComType in callLink element

JavaWrapper in callLink element

The linkage options part, callLink element, property javaWrapper indicates whether to allow generation of Java wrapper classes that can invoke the program being generated.

Valid values are as follows:

No (the default)
Do not allow generation of Java wrapper classes.
Yes
Allow that generation to occur. The generation occurs only if the build descriptor option enableJavaWrapperGen is set to yes or only.

Your choice for javaWrapper property has an effect only when you are setting up a remote call, as occurs when the value of the callLink property type is remoteCall. In contrast, if you are setting up a call to the program by way of an EJB, the value of javaWrapper is always yes; and if you are setting up a local call, the value of javaWrapper is always no.

If you are generating in the workbench or from the workbench batch interface, the build descriptor option genProject identifies the project that receives the classes. If genProject is not specified (or if you are generating in the EGL SDK), the wrapper classes are placed in the directory specified by the build descriptor option genDirectory.


Related concepts
Linkage options part


Related reference
callLink element
genDirectory
genProject

linkType in callLink element

The linkage options part, callLink element, property linkType specifies the type of linkage when the value of property type is localCall.

If you are generating a COBOL or Java program, linkType is meaningful when property pgmName refers to a program that is called by the program being generated. If you are generating a Java wrapper, property type must be remoteCall or ejbCall, and linkType is not available.

Select a value from this list:

DYNAMIC
If you are generating a COBOL program, specifies that the call is a dynamic COBOL call.

If you are generating a Java program, specifies that the call is to a Java program in the same thread. DYNAMIC is the default value when you are generating a Java program.

STATIC
If you are generating a COBOL program, specifies that a static COBOL call occurs, which means that you must link-edit the called program with the calling program.

If you are generating a Java program, STATIC is equivalent to DYNAMIC.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element
pgmName in callLink element
type in callLink element

library in callLink element

The linkage options part, callLink element, property library specifies the DLL or library that contains the called program when the value of the type property is ejbCall or remoteCall:


Related concepts
Linkage options part


Related reference
callLink element

location in callLink element

The linkage options part, callLink element, property location specifies how the location of a called program is determined at run time. The property location is applicable in the following situation:

Select a value from this list:

programControlled
Specifies that the location of the called program is obtained from the system function sysVar.remoteSystemID when the call occurs.
system name
Specifies the location where the called program resides.

If you are generating a Java program or wrapper, the meaning of this property depends on property remoteComType:


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part
Setting up the J2EE server for CICSJ2C calls


Related reference
callLink element
sysVar.remoteSystemID
pgmName in callLink element
remoteComType in callLink element
type in callLink element

luwControl in callLink element

The linkage options part, callLink element, property luwControl specifies whether the caller or called program controls the unit of work. This property is applicable only in the following situation:

Select one of the following values:

CLIENT
Specifies that the unit of work is under the caller's control. Updates by the called program are not committed or rolled back until the caller requests commit or rollback. If the called program issues a commit or rollback, a run-time error occurs.

CLIENT is the default value, unless a caller-controlled unit of work is not supported on the platform where the called program resides.

SERVER
Specifies that a unit of work started by the called program is independent of any unit of work controlled by the calling program. In the called program, these rules apply:

On a call from EGL-generated Java code to a VisualAge Generator COBOL program, a commit (or rollback on abnormal termination) is issued automatically when the called program returns. That command affects only the changes that were made by the called program.

When the property type is ejbCall, the run-time behavior is as described for SERVER.


Related concepts
Linkage options part
Logical unit of work


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element
sysLib.commit
sysLib.rollback
pgmName in callLink element
type in callLink element

package in callLink element

The linkage options part, callLink element, property package identifies the Java package in which a called Java program resides. The property is useful whether property type is ejbcall, localCall, or remoteCall.

If you are generating a Java program, package is meaningful when property pgmName refers to a program that is called by the program being generated. If you are generating a Java wrapper, package is meaningful when property pgmName refers to the program that is called by way of the Java wrapper.

If the package property is not specified, the called program is assumed to be in the same package as the caller.

The package name that is used in generated Java programs is the package name of the EGL program, but in lower case; and when EGL generates output from the callLink element, the value of package is changed (if necessary) to lower case.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part
Setting up the J2EE run-time environment for EGL-generated code


Related reference
callLink element
pgmName in callLink element
type in callLink element

parmForm in callLink element

The linkage options part, callLink element, property parmForm specifies the format of call parameters.

If you are generating a COBOL program, parmForm is applicable in this situation:

If you are generating a Java program, parmForm is applicable in this situation:

If you are generating a Java wrapper, parmForm is applicable in this case:

Select a value from this list:

COMMDATA
Specifies that the caller places business data (rather than pointers to data) in the COMMAREA.

Each argument value is moved to the buffer adjoining the previous value without regard for boundary alignment.

COMMDATA is the default value if the property type is ejbCall or remoteCall.

COMMPTR
Specifies that the caller acts as follows:

COMMPTR is the default value if the value of property type is localCall.

OSLINK
Specifies that the standard COBOL parameter-passing conventions are in effect, with the called program expecting pointers to data, but without the CICS EIB or COMMAREA.

OSLINK is available only when type is localCall, linkType is DYNAMIC or STATIC, and you are generating a COBOL program.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element
linkType in callLink element
parmForm in callLink element
pgmName in callLink element
type in callLink element

pgmName in callLink element

The linkage options part, callLink element, property pgmName specifies the name of the program part to which the callLink element refers.

You can use an asterisk (*) as a global substitution character in the program name; however, that character is valid only as the last character. For details, see Linkage options part.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element

providerURL in callLink element

The linkage options part, callLink element, property providerURL specifies the host name and port number of the name server used by an EGL-generated Java program or wrapper to locate an EJB session bean that in turn calls an EGL-generated Java program. The property must have the following format:

  iiop://hostName:portNumber
hostName
The IP address or host name of the machine on which the name server runs
portNumber
The port number on which the name server listens

The property providerURL is applicable only in the following situation:

Enclose the URL in double quote marks to avoid a problem either with periods or with the colon that precedes the port number.

A default is used if you do not specify a value for providerURL. The default directs an EJB client to look for the name server that is on the local host and that listens on port 900. The default is equivalent to the following URL:

  "iiop:///"

The following providerURL value directs an EJB client to look for a remote name server that is called bankserver.mybank.com and that listens on port 9019:

  "iiop://bankserver.mybank.com:9019"

The following property value directs an EJB client to look for a remote name server that is called bankserver.mybank.com and that listens on port 900:

  "iiop://bankserver.mybank.com"


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part
Setting up the J2EE run-time environment for EGL-generated code


Related reference
callLink element
pgmName in callLink element
type in callLink element

refreshScreen in callLink element

The linkage options part, callLink element, property refreshScreen indicates whether an automatic screen refresh is to occur when the called program returns control. Valid values are yes (the default) and no.

Set refreshScreen to no if the caller is in a run unit that presents text forms to a screen and either of these situations applies:

The property refreshScreen applies only in these cases:

The property is ignored if you include the noRefresh indicator on the call statement.


Related reference
call

remoteBind in callLink element

The linkage options part, callLink element, property remoteBind specifies whether linkage options are determined at generation time or at run time. This property is applicable only in the following situation:

Select one of these values:

GENERATION
The linkage options specified at generation time are necessarily in use at run time. GENERATION is the default value.
RUNTIME
The linkage options specified at generation time can be revised at deployment time. In this case, you must include a linkage properties file in the run-time environment.

EGL generates a linkage properties file in the following situation:


Related concepts
Linkage options part
Linkage properties file


Related tasks
Deploying a linkage properties file
Editing the callLink element of a linkage options part


Related reference
callLink element
genProperties
Linkage properties file (details)
pgmName in callLink element
type in callLink element

remoteComType in callLink element

The linkage options part, callLink element, property remoteComType specifies the communication protocol used in the following case:

Select one of the following values.

DEBUG
Causes the called program to run in the EGL debugger, even when the calling program is running in a Java run-time or Java debug environment. You might use this setting in the following cases:

The preceding situations can occur outside the WebSphere Test Environment, but can also occur within that environment, as when a JSP invokes a program written with EGL. In any case, the effect is to invoke the EGL source, not an EGL-generated program.

If you are using the WebSphere Test Environment, the caller and called programs must both be running there; the call cannot be from a remote machine.

When you use DEBUG, you set the following properties in the same callLink element--

If the caller is not running in the EGL debugger and is not running in the WebSphere Test Environment, you must set these properties of the callLink element:

DIRECT
Specifies that the calling program or wrapper uses a direct local call, which means that the calling and called code run in the same thread. No TCP/IP listener is involved, and the value of property location is ignored. DIRECT is the default.

A calling Java program does not use the EGL middleware, but a calling wrapper uses that middleware to handle data conversion between EGL and Java primitive types.

DISTINCT
Specifies that a new run unit is started when calling a program locally. The call is still considered to be remote because EGL middleware is involved.

You can use this value for an EGL-generated Java program that calls a C or C++ program.

CICSECI
Specifies use of the CICS Transaction Gateway (CTG) ECI interface, as is needed when you are debugging or running non-J2EE code that accesses CICS.

CTG Java classes are used to implement this protocol. To specify the URL and port for a CTG server, assign values to the callLink element, properties ctgLocation and ctgPort. To identify the CICS region where the called program resides, specify the location property.

CICSJ2C
Specifies use of a J2C connector for the CICS Transaction Gateway.
CICSSSL
Specifies use of the Secure Socket Layer (SSL) features of CICS Transaction Gateway (CTG). The JSSE implementation of SSL is supported.

CTG Java classes are used to implement this protocol. To specify additional information for a CTG server, assign values to the following callLink element properties:

To identify the CICS region where the called program resides, specify the location property.

JAVA400
Specifies use of the IBM Toolbox for Java to communicate between a Java wrapper or program and a COBOL program that was generated (by EGL or VisualAge Generator) for iSeries.
TCPIP
Specifies that the EGL middleware uses TCP/IP.


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
ctgKeyStore in callLink element
ctgKeyStorePassword in callLink element
ctgLocation in callLink element
ctgPort in callLink element
Editing the callLink element of a linkage options part
Setting up the J2EE server for CICSJ2C calls
Setting up the TCP/IP listener

remotePgmType in callLink element

The linkage options part, callLink element, property remotePgmType specifies the kind of program being called. The property is applicable in the following situation:

EGL
The called program is a COBOL or Java program that was generated by EGL or by VisualAge Generator; in this case, the caller is a COBOL program, Java program, or Java wrapper. This value is the default.


Related concepts
Linkage options part
Run-time configurations


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element
pgmName in callLink element
type in callLink element

serverID in callLink element

The linkage options part, callLink element, property serverID specifies one of the following values:

The property is used only in the following situation:


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part
Setting up the TCP/IP listener


Related reference
callLink element
pgmName in callLink element
remoteComType in callLink element
type in callLink element

type in callLink element

The linkage options part, callLink element, property type specifies the kind of call. Select one of the following values:

ejbCall
Indicates that the generated Java program or wrapper will implement the program call by using an EJB session bean and that the EJB session bean will access the COBOL or Java program identified in the property pgmName. The value ejbCall is applicable in either of two cases:

In either case, if you are using an EJB session bean, you must generate a Java wrapper, if only to generate the EJB session bean.

The generated session bean must be deployed on an enterprise Java server, and one of the following statements must be true:

If you wish to use an EJB session bean, you must generate the calling program or wrapper with a linkage options part in which the value of property type for the called program is ejbCall. You cannot make the decision to use a session bean at deployment time. If you set the property remoteBind to RUNTIME, however, you can decide at deployment time how the EJB session bean accesses the generated program, although making this decision at generation time is more efficient.

localCall
Specifies that the call does not use EGL middleware. The called program in this case is in the same process as the caller.

If the caller is a COBOL program, the situation is further defined by other properties. Most important are linkType and (for CICS COBOL programs) parmForm. Those properties have default values that you can accept or override.

localCall is the default value

remoteCall
Specifies that the call uses EGL middleware, which adds 12 bytes to the end of the data passed. Those bytes allow the caller to receive a return value from the called program.

If the caller is Java code, communication is handled by the protocol specified in property remoteComType; the protocol choice indicates whether the called program is in the same or a different thread.

If variable length records are passed on a call, these statements apply:


Related concepts
Linkage options part


Related tasks
Editing the callLink element of a linkage options part


Related reference
callLink element
linkType in callLink element
location in callLink element
parmForm in callLink element
pgmName in callLink element
providerURL in callLink element
remoteComType in callLink element


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]