Performing CICS RPC Actions

About Actions

An action is similar to a programming statement in that it takes input in the form of parameters and performs specific tasks. Please see the chapters in the Composer User's Guide devoted to Actions.

Within the CICS RPC Component Editor, a set of instructions for processing XML documents or communicating with non-XML data sources is created as part of an Action Model. The Action Model performs all data mapping, data transformation, data transfer between mainframe and XML documents, and data transfer within components and services.

An Action Model is made up of a list of actions. All actions within an Action Model work together. As an example, one Action Model might read invoice data from a disk, retrieve data from a mainframe inventory database, map the result to a temporary XML document, make a conversion, and map the converted data to an output XML document.

The Action Model mentioned above would be composed of several actions. These actions would:

Open an invoice document and perform a CICS RPC command to retrieve invoice data from a mainframe database
Map the result to a temporary XML document
Convert a numeric code using a Code Table and map the result to an Output XML document.

About CICS RPC Specific Actions

There is an Action unique to CICS RPC called "Execute ECI." This action is used to make an external call by converting copybook data into a ByteArray and sending it to the mainframe, or by creating the ByteArray directly.

To access this action from the Menu Bar, click Action Menu/New Action/Execute ECI. The following dialog box appears:

executeeci27

The use of this dialog is as follows.

Procedure To define an Execute ECI Action:

Enter the Host Program Name. In the example SKUT02 is the program name
Click inside the checkbox to activate field entry for a CICS Transaction ID. This field is optional, and only needs to be filled in if the system and/or your CICS environment requires a Transaction ID as well as a Host Program name.

NOTE: A typical Transaction ID has been entered in the above screen. If you have clicked the checkbox to enter a Transaction ID but fail to enter that information in the field provided, you will not be able to Execute ECI.
In the Input/Output Data section, select Copybook or ByteArray. Choose Copybook if you wish to convert Copybook data into a ByteArray and send it to the mainframe, receiving a ByteArray back from the mainframe. Choose ByteArray if you wish to create the ByteArray directly using the Convert actions and absorb and emit it directly.
Select Source Copybook (or Source ByteArray) from the pull down list box. In the example INDATA is the Source Copybook. If you select a ByteArray, you will have access to the ECMAScript Expression Builder.
Select Target Copybook (or Target ByteArray) from the pull down list box. In the example OUTDATA is the Target Copybook. the pull down list box. In the example INDATA is the Source Copybook. If you select a ByteArray, you will have access to the ECMAScript Expression Builder.
Click OK. The component's Action Model now contains an Execute ECI action.

CICS RPC Specific Expression Builder Extensions

The purpose of the CICS RPC Expression Builder extensions is to provide an ECMAScript programmatic alternative to the functionality performed automatically when you drag and drop between a DOM and a Copybook and a Map action is created. If you click on the expression icon, the Source Expression dialog window appears.

These ECMAScript Extensions are available for you to use in customizing your own Auto Map. Each copybook utilized by the CICS RPC component is represented as an ECMAScript object. These copybook objects have one available method: getField (). The getField method returns a Copybook Field object which in turn has two methods as discussed below.

. source

copybookField getField(String cobolData Desc)

Novell exteNd extension method.

Returns a CopybookField object.

For example, to resolve duplicate named cobolDataDesc in a Copybook, reference the parent cobol Data Desc as follows:

getField("PARTID IN INDATA") given the following copybooks

01COMMAREA

05 INDATA

10PARTID

05 OUTDATA

10PARTID

The returned Copybook Field object has two methods:
String toString()

Novell exteNd extension method.

Returns the string value for CopybookField object.
void setValue(Object aValue)

Novell exteNd extension method.

Sets the value for a CopybookField object.

Using Other Actions in the RPC Component Editor

In addition to actions already discussed, you have all the standard Basic and Advanced Composer actions at your disposal as well. The complete listing of Basic Composer Actions can be found in Chapter 7 of the Composer User's Guide. Chapter 8 contains a listing of the more Advanced Actions available to you.

Handling Errors and Messages

This section describes common error messages you may see while using the animation tools.

ECI Connection Error Messages

Exception Messages:

dt002001: Error executing component: ECI Exception java.io.IOException:CCL6651E: Unable to connect to the Gateway.
```
  [address = tiger,port = 2006]
  [java.net.UnknownHostException: tiger]
```
Nested Message: rtCICSRPC000301:ECIException java.io.IOException: CCL6651E: Unable to connect to the Gateway.
```
  [address = tiger, por t= 2006]
  [java.net.UnknownHostException: tiger]
```

Nested Message: CCL6651E: Unable to connect to the Gateway.

  [address = tiger, port = 2006]
  [java.net.UnknownHostException: tiger]

NOTE: This error message indicates to the user that the Hostname used for the ECI Connection is incorrect and/or does not exist in the environment during execution. To correct the problem, verify the parameters in the Connection Dialog specifically check the host name IP address.

Data Type Translation Error Messages

Exception Messages:

dt002701: Error trying to map `TESTALL.getField("ESIGNED")'
Nested Message: rt001002:** Error evaluating

`TESTALL.getField("ESIGNED").setValue(Input.Xpath("COMMAREA/EXTERNAL

DECIMAL/ESIGNED"))'
Nested Message: Runtime error Error in Java method set Value

Caused by exception:

Error converting source data type to the selected copybook field.

NOTE: This error message is the most common, when a user enters a value that does not comply with the data type of the target field in a COBOL Copybook. An example would be if a user entered the value LOR8437 into a numeric data type field such as COMP, COMP-3, or 9999999.