Interaction

The Interaction activity represents a modern approach to run CICS programs: all the functionality available in the Adapter Mode Interaction is available here, in addition to the ability to use CICS Containers as input and output from the program, the ability to route the request between CICS regions for execution, and much more. The following tables describe the fields available on the Interaction.

General

In the General tab, you can establish a connection to a CICS region. The following table lists the configurations in the General tab of the Interaction activity:

Field Module Property Description
Name No Specify the name of the region resource.

Default: Interaction

Region Yes Specify a link to the CICS region to be used for this interaction.
Program Name Yes Specify the name of the CICS program that you want to invoke.
Interaction Timeout Yes Specify the number of seconds that the activity waits for the CICS system to return from the called program. Zero disables the timeout, which means that interactions wait forever for the CICS system to return. A blank value implements the 60 second default.

Default: 60

Range: 0 - 255

Logger Name Yes Enter the name of any logger you have reconfigured for this purpose, or leave it blank to use the default logger.
To configure loggers to display log messages in TIBCO Business Studio returned by the plug-in, add the following stanzas to the logback.xml file located in the TIBCO_HOME\bw\6.x\config\design\logback directory: 
<logger name="com.tibco.bw.palette.cics">
    <level value="DEBUG"/>
  </logger>

Note that if no logger is specified and the root logger for the run time is set to WARN or higher, the plug-in incurs overheads related to retrieving log records from the CICS system at run time. To ensure that performance is acceptable, it is best to use a dedicated logger, which is not set to DEBUG.

Create Timing Report No Select this check box to enable the plug-in to produce a timing report on the output schema.

This check box is provided to assist TIBCO Support to resolve a performance problem with the plug-in. It is good practice to clear this check box for production applications.

Description

In the Description tab, provide a short description for the Interaction activity.

Advanced

In the Advanced tab, you can configure response related information for the Interaction activity. The following table lists the configurations in the Advanced tab of the Interaction activity:

Field Module Property Description
Response Type No Select a response type.
The response type is as follows:
  • Data: returns the output of the program.

    This is the default response type.

  • Nothing: calls the program and does not wait for a result code. This is completely asynchronous.
  • Return Code Only: calls the program and returns the program call return code. This ensures that the activity finds out about abnormal events in the call, but does not return any data.
Return Area Size Yes

Provide the size, in bytes, of the commarea to be used by the program. This size must be sufficient to hold the input data as well as any data that the program writes.

This field is enabled only when you select Data as the response type.

Regardless of the input output type, this is the number of bytes returned from the programs output area.

If a program produces 20K of data but you are only interested in the first 100 bytes, you can select to receive only the first 100 bytes to conserve network resources.

If this parameter is used to limit the size of the data area returned from an activity, it must be done in such a way that any subsequent DCP parse activity has enough data so satisfy the requirements of its schema. Therefore, if you truncate the data, be sure to adjust the requirements of the schema to match.

Note: A size of zero effectively disables this parameter. Commarea interactions use the maximum commarea size (32500), and container interactions use actual sizes for containers.

Default: 32500

Range: commarea 0 - 32500; container 0 - 4m

Data Comm Type No Select a data communication type.
The data communication type can be as follows:
  • Commarea: this is the default type and means that the program is a commarea program and uses a commarea for input and output.
  • Variable Length Commarea: this option provides the ability to run a CICS program using a commarea of a specific size, and to transfer an arbitrary subsection of the resultant commarea back to the activity. If you click Variable Length Commarea, the Commarea Size and Commarea Offset fields become enabled.
  • Container: this means that the input and output to the program is provided by named containers. You must know what the program expects its containers to be named. If you click Container, the Channel Name, Input Container, and Output Container fields become enabled.
Commarea Size Yes Provide the size, in bytes, of the commarea to be used by the program. This size must be sufficient to hold the input data as well as any data that the program writes.

This field is only enabled when you select Variable Length Commarea as the data communication type.

Commarea Offset Yes Provide a zero-based offset into the commarea returned by the program.

This value is used as the starting position when copying the commarea data back to the activity. The number of bytes specified in the Return Area Size field is copied from this offset. An error is returned to the activity if any overrun is detected.

Provide a zero-based offset into the commarea returned by the program.

Channel Name Yes This field is only enabled when you select Container as the data communication type.

The optional name of the CICS Channel object which contains the input containers for this program execution. This is only required to support programs which explicitly open a named channel rather than use the default.

Input Container Yes Specify the input container name to be used for this transaction. It can be 1 to 16 characters long.

This field is only enabled when you select Container as the data communication type.

Output Container Yes Specify the output container name to be used for this transaction. It can be 1 to 16 characters long.

This field is only enabled when you select Container as the data communication type.

CICS Resource Commit Point No Select a CICS resource commit point.
Options are:
  • Auto: the CICS interaction interface program automatically commits CICS resources at the completion of the program call.

    This is the default.

  • User: it is expected that the called program explicitly commits CICS resource changes if it is necessary to do so.
  • Remote: the remote CICS system automatically commits all resources at transaction end.
DB2 Transaction Id Yes Optionally, provide a transaction identifier to be used by programs accessing DB2 by way of plans that have a specific transaction ID bound into them.
Enable CICS Remote No Select this check box to enable the CICS routing options.

After you select this check box, the Remote CICS Sys Id, Remote CICS Trans , and Sync On Return fields become enabled.

Remote CICS Sys Id Yes Specify a four-character system identifier for the CICS region where the program ultimately runs.

Use alphanumeric characters only.

Remote CICS Trans Yes Specify a four-character transaction identifier responsible for running the program on the remote CICS system.

Use alphanumeric characters only.

Sync On Return Yes Select this check box to automatically commit CICS resources on the remote CICS system when the program returns.

If this check box is not selected, the remote CICS program cannot issue a CICS SYNC or a CICS ROLLBACK.

Default: disabled

Input

In the Input tab, you can configure information for the interaction.

The Input tab contains an XML document node called InteractionInput. The present fields make it possible to programmatically override the activity defaults by mapping values from a previous activity output.

The following table lists the configurations in the Input tab of the Interaction activity:

Input Item Module Property Description
Userid Yes Override the user ID for this interaction. This field is only available for interactions using non-pooled connections.
Password Yes Override the password for this interaction. This field is only available for interactions using non-pooled connections.
TranId Yes (Optional) Hold or override a custom transaction identifier that is used to account for application resources for each transaction.

This identifier becomes the transaction on whose behalf the connection to CICS is made and under which all plug-in interactions on this CICS region or regions run.

To enable this transaction ID, copy the transaction SXNE CSD provided by TIBCO to the name of the custom transaction.

This field is only available for interactions using non-pooled connections.

MroTran Yes Override the four-character transaction identifier responsible for running the program on the remote CICS system.

Use alphanumeric characters only.

MroSys Yes Override the four-character system identifier for the CICS region where the program ultimately runs.

Use alphanumeric characters only.

MroSync Yes Override the Boolean. Indicates whether the CICS link is completed with or without the SYNCONRETURN parameter. The valid input is the words TRUE or FALSE.
bytes No The input to the activity, normally mapped from a previous Render Copybook activity provided by TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion.

Output

In the Output tab, you can find the results of the interaction for a commarea or a container. The following table lists the output elements in the Output tab of the Interaction activity:

Output Item Data Type Description
bytes Binary Displays the body of the commarea or container that is returned.
responsetimemillisec Integer Displays the number of milliseconds that the Interaction took for performance monitoring reasons.
timings String Displays a list of strings describing the execution times for plug-in functions.

If the Create Timing Report check box is selected in the General tab, this node is present. It is intended to be used by TIBCO Support when they are assisting you with a performance problem. It is good practice for this option to be normally turned off.

Fault

In the Fault tab, you can find the error code and error message of the Interaction activity. The following table lists error schema elements in the Fault tab of the Interaction activity:

Error Element Data Type Description
msg String Displays the error message.
msgCode String Displays the error code.
errorMessage String Displays the CICS specific error information such as the abend code when error occurred in CICS.