INVOKE APPLICATION

Invoke an application entry point program. EXEC CICS INVOKE APPLICATION allows invocation of an application by naming an operation that corresponds to one of its program entry points, without having to know the name of the application entry point program and regardless of whether the program is public or private.

The application must be in an AVAILABLE state. If multiple versions of the application are in an AVAILABLE state, the entry point programs of the highest version of the application are the ones that are public, and so can be linked to by using an EXEC CICS LINK command. The INVOKE APPLICATION command allows lower versions of the application to be invoked, by specifying a version as well as an operation, and this corresponds to a private entry point program.

INVOKE APPLICATION

Conditions: APPNOTFOUND, CHANNELERR, INVREQ, LENGERR, NOTAUTH, PGMIDERR

This command is threadsafe.

Description

The INVOKE APPLICATION command links to a local program, which is the entry point to the specified application for the specified operation. It passes control from an application program at one logical level to an application program at the next lower logical level.

This command operates in the current platform context. If the command does not specify a platform name, the current platform name is used. If there is no current platform, then the command fails with a response of APPNOTFOUND.

For more information, and examples of how you can use the EXEC CICS INVOKE APPLICATION command, see Invoking a multi-versioned application.

Options

APPLICATION(name)

Specifies the name (1 - 64 characters) of the application. The acceptable characters are: a-z A-Z 0-9 . _ # @ -

CHANNEL(name)

Specifies the name (1 - 16 characters) of a channel that is to be made available to the called program. The acceptable characters are: A-Z a-z 0-9 $ @ # / % & ? ! : | " = ¬ , ; < > . - _. Leading and embedded blank characters are not permitted. If the name supplied is fewer than 16 characters, it is padded with trailing blanks up to 16 characters. If the channel does not exist, it is created. This new channel remains in scope until the link level changes. For more information about channel scope, see The scope of a channel.

Channel names are always in EBCDIC. The set of allowed characters for channel names, as listed earlier, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, if channels are to be transferred between regions, it is advisable to restrict the characters that are used to name them to A-Z a-z 0-9 & : = , ; < > . - and _.

You can specify the channel name DFHTRANSACTION to use a transaction channel. A transaction channel does not go out of scope when the link level changes: it is always accessible in the transaction. For more information, see Channels and containers.

The program that issues the INVOKE command can do one of the following:

Have already created the channel by using one or more PUT CONTAINER CHANNEL or PUT64 CONTAINER commands.
Specify its current channel, by name.
Name a channel that does not currently exist. A new empty channel is created.

COMMAREA(data-area)

Specifies a communication area that is to be made available to the called program. In this option, the data area is passed, and you must give it the name DFHCOMMAREA in the receiving program. See Passing data to other programs .

EXACTMATCH

Specifies that an exact match on the application major version number and minor version number is required. If not found then an APPNOTFOUND condition is returned.

Note: There is no match criteria for micro version. The highest micro version is always used.

LENGTH(data-value)

Specifies a halfword binary value that is the length in bytes of the COMMAREA (communication area). This value must not exceed 24 KB if the COMMAREA is to be passed between any two CICS® servers (for any combination of product, version, and release). This limit allows for the COMMAREA and space for headers.

Ensure that the value you specify matches the length of the data that is being passed in the COMMAREA. Do not specify 0 (zero) for LENGTH because the resulting behavior is unpredictable and the EXEC CICS LINK command might fail.

When you use a COMMAREA to pass data, the program that is linked to must verify that the EIBCALEN field in the EIB of the task matches what the program expects. Discrepancies might result in storage violations or system failures. For more information, see COMMAREA.

MAJORVERSION(data-value)

Specifies the major version number of the application as a fullword binary value.

If MAJORVERSION is specified, then MINORVERSION must also be specified. If no version is specified, then the highest major and minor version of the application is invoked.

MINIMUM

Specifies that the specified minor version number is the minimum that is required, but use a higher version if it is available. If multiple higher minor versions are available the highest is used. This applies to minor version numbers only. The major version number cannot be exceeded and must match exactly. If no higher minor version exists nor the minimum required minor version, then an APPNOTFOUND condition is returned.

Note: There is no match criteria for micro version. The highest micro version is always used.

MINORVERSION(data-value)

Specifies the minor version number of the application as a fullword binary value.

If MINORVERSION is specified, then MAJORVERSION must also be specified. If no version is specified, then the highest major and minor version of the application is invoked.

The EXACTMATCH or MINIMUM keywords specify the matching criteria for the major and minor versions.

OPERATION(name)

Specifies the name (1 - 64 characters) of the application operation which the application entry point program implements. The acceptable characters are: a-z A-Z 0-9 . _ # @ -

PLATFORM(name)

Specifies the name (1 - 64 characters) of the platform on which the application is installed. The acceptable characters are: a-z A-Z 0-9 . _ # @ -

If no platform name is specified, the current platform name is used. If there is no current platform, then the command fails with a response of APPNOTFOUND.