Creating an Adapter Transaction

In this section:

After you create a connection to IMS/TM, you can add adapter transactions using iWay Explorer. A single IMS/TM connection may be associated with multiple transactions. Each transaction represents one service offered by IMS/TM and consists of a program and its metadata.

A generic transaction is automatically added and represents IMS/TM services whose data will not be mapped to XML. You can use a generic transaction for transactions that accept no input and for transactions that return no output or when it is acceptable to return a non-formatted answer set.

For example, the IMS transaction PART connects to IMS/TM and returns PART information on successful adapter installation and configuration. One request and response schema is applicable for this generic transaction. The request schema for the generic transaction is in Sample Requests, Schemas, and Cobol File Descriptions.

Using the generic transaction, the XML request document that is received must include the name of the program to be called in the <Transaction> element. The payload to be sent as the IMS segment must be in the <message> tag, which can be a maximum of 32,500 bytes.

The generic response schema is constructed from the data received from IMS/TM. If the <message> element has more than 80 bytes, the received IMS segment is split into 80-byte messages. Illegal XML characters ('<', '/', and '&') are converted to XML entities. For example:

<?xml version="1.0" encoding="UTF-8" ?>
<IMS>
<Transaction tpname="PART" noreply="NO">
<message>
<message>*</message>
</message>
</Transaction>
</IMS>

For transactions that require input and output and a formatted response, which is usually the case, you must add your own adapter transactions, as described in How to Create an Adapter Transaction. XML request messages must specify the transaction to use in the location attribute of the <Transaction> tag. For example, if you create an IMS/TM transaction called PART, the location is "IMS/Transactions/PART".

To view a sample generic request or response schema or for information about specifying a transaction to use in the location attribute of the <Transaction> tag, see Sample Requests, Schemas, and Cobol File Descriptions.


Top of page

x
Specifying IMS/TM Transaction Input and Output

The iWay Transaction Adapter for IMS can execute regular IMS/TM transactions and transactions that use Message Format Services (MFS). Therefore, the input to, and output from, IMS/TM transactions can be specified by using COBOL copybooks or MFS XML descriptors. Any combination of the two can be used, provided that only one method is used to specify the input and only one method is used to specify the output.

Input

Output

Cobol copybook

Cobol copybook

Cobol copybook

MFS XML descriptor

MFS XML descriptor

Cobol copybook

MFS XML descriptor

MFS XML descriptor

Note: Only field format 1 (OPT=1 on the MSG macro definition) is supported. Short records, allowed under OPT 1, are not currently supported. In addition, only one segment can be sent when using MFS.



x
Specifying the Input and Output For MFS IMS/TM Transactions

The following section describes how to specify the input and output for MFS IMS/TM transactions. Examples are also provided.



x
Using an MFS XML Descriptor to Define IMS/TM Transaction Input

The iWay Transaction Adapter for IMS uses an MFS XML input descriptor to create the proper IMS/TM transaction input record from the input XML document. All segments that are sent to IMS are full length; there are no short fields or short segments. The input MFS XML specifies how to format each element in the input XML document before adding it to the IMS/TM input record by specifying the attributes of the MFLD element.

When using an input XML document, the adapter does not use the value that is specified in the Program Name field of the Add Service dialog box in iWay Explorer. The IMS/TM transaction code must be specified in some other manner.

The first MFLD element in the MFS XML input descriptor must describe the IMS/TM transaction code used to invoke the IMS/TM program. The transaction code itself must either appear in the input XML document, as the value of the element whose name is equal to the value of the name attribute of the first MFLD element in the MFS XML input descriptor, or it must appear as the value of the default attribute of the first MFLD element in the MFS XML descriptor.



The following is a sample input MFS XML descriptor.

<?xml version="1.0" encoding="UTF-8" ?>
<MSG name="IW01MI" opt="1" type="INPUT" next="IW01MO">
  <SEG>
     <MFLD name="TCODE" 
         Length="9"
         iwaySuppress="no"
         iwayFieldType="alpha"
         justification="left"
         attribute="no"
         fill=" "
         InputMFSDocumentUsage="Required"
     />
     <MFLD name="CSRPOS"
         Length="4"
         iwayFieldType="cursor"
         default="7,2"
         InputMFSDocumentUsage="Forbidden"
     />
     <MFLD name="BCODE"
         Length="12"
         iwaySuppress="no"
         iwayFieldType="alpha"
         justification="right"
         attribute="yes"
         fill="0"
         InputMFSDocumentUsage="Optional"
     />
   </SEG>
</MSG>

The following table lists and describes the attribute types in the input MFS XML descriptor.

Attribute

Description

name

Specifies the name of the field (Required).

Length

Specifies the length of the field (Required).

It includes 2 for attributes if attribute="yes". For the cursor type, it must always be set to 4.

InputMFSDocumentUsage

Specifies the input disposition (Optional). This attribute specifies the disposition of the field from the input XML document. If absent, the field is always included in the data that is returned to IMS. The following values are available:

  • Required - The field must be included in the inbound document.
  • Forbidden - The field must not be included in the inbound document. The data that is sent to IMS is supplied from the default attribute.
  • Optional - The field can be included in the inbound document. If it is not, the data sent to IMS is supplied from the default attribute.

iwaySuppress

This attribute is reserved for future use (Optional).

iwayFieldType

The following values are available:

  • alpha (default)
  • cursor

attribute

Specifies whether 3270 attribute bytes are included (Required). The following values are available:

  • yes
  • no (default)

If yes is selected, the length specified by the Length attribute includes these 2 bytes.

justification

Specifies left or right justification. The following values are available:

  • left (default) - Indicates left justify and right truncate.
  • right - Indicates right justify and left truncate.

fill

Specifies the pad byte. The default is " ". For example, if the attribute is missing or specified as "" (empty string).

default

Specifies the default value of the field when the field is omitted from the document. The default must be in a format that is acceptable for the type specified by the iwayFieldType attribute.

For alpha type fields, the default, if specified, is populated with the fill byte, and justified according to the justification attribute.

Note: For alpha type fields, conceptually, the fill byte is set first. Then the value of the field is set. The field is then padded, justified, and truncated. If the value specified for the field in the input document is null (<field/>), the default is not used; the field is populated with the pad byte.

The default attribute is required if the InputMFSDocumentUsage attribute is set to Forbidden.

If the MFLD element describes the IMS/TM transaction code, and the CRM gateway is used as the communication method, only the following attributes are used:

If TCP/IP communication method is used, the other attributes are used in the expected manner.

Notes Regarding iwayFieldType="cursor"

The expected format of type cursor elements in the input MFS XML document is "row,column". The row and the column must be integers. Only the following attributes, if present, are used from the MFLD element:

The other attributes may be present, but are not used.

If the cursor element is not in the input document, or if its value is null (for example, <csr/>), the default is used instead, unless there is no default, in which case the IMS "1,2" default cursor position is used. Whichever values are used, they are converted to 2 byte integers before being inserted in the record that is sent to IMS.



Example: Input MFS XML Descriptor I
<MFLD name="SomeField"
      Length="10"
      iwaySuppress="no"
      iwayFieldType="alpha"
      attribute="no"
      fill=" "
      default="WHATEVER"
/>

Input XML: <SomeField>nothing</SomeField>
Sent to IMS: 'nothing '

Input XML: <SomeField></SomeField> (or < SomeField/>)
Sent to IMS: ' ' (10 blanks)

Input XML: <SomeField>nothingofimportance</SomeField>
Sent to IMS: 'nothingofi' (10 chars)

Input XML: Field not in the input XML
Sent to IMS: 'WHATEVER ' (10 chars)



Example: Input MFS XML Descriptor II
<MFLD name="csr"
      Length="4"
      iwayFieldType="cursor"
      default="10,23"
/>

Note: Only the type, and the default attributes are used. The cursor values sent to IMS are 2 byte integers, not strings.

Input XML: <csr>3,17</csr> Sent to IMS: the 2 half integers 3, and 17.

Input MFS: <csr/> Sent to IMS: the 2 half integers 10, 23.



x
Using an MFS XML Descriptor to Define IMS/TM Transaction Output

The iWay Transaction Adapter for IMS uses an MFS XML input descriptor to convert the records received from IMS/TM to an XML message properly. Currently, it is assumed that IMS sends full length segments every time. If a short segment is sent from IMS, it will result in a length mismatch error.

Attribute

Description

name

Specifies the name of the XML element that will be generated.

Length

Specifies the length of the field in the IMS output.

attribute

Specifies whether 3270 attribute bytes are included (Optional). The following values are available:

  • yes
  • no (default)

If yes is selected, the length specified by the Length attribute includes these 2 bytes.

OutputMFSDocumentUsage

Specifies the output disposition. This attribute specifies the disposition of the field. If absent, the field is always included in the output. The following values are available:

  • Always - The field is always included in the output.
  • Never - The field is omitted from the output.
  • IfNotDefault - The field is included in the output if it is different from the value of the default attribute, or if there is no default attribute.

iwayFieldType

The following values are available:

  • alpha
  • cursor

If cursor is used, two 2-byte integers are read and converted in a string of the form "row,column".

default

Used in conjunction with the OutputMFSDocumentUsage attribute.



x
Cobol Descriptions for Defining IMS/TM Transaction Output

The adapter uses Cobol descriptions to properly create an XML structure of the message that is returned from the IMS/TM transaction. For transactions that return one or more messages (for example, a message that has its own message layout), the adapter transforms the message into the proper structure based on Cobol descriptions.

If the application that executes the adapter requires proper formatting of each returned message from the transaction:


Top of page

x
Sample Transaction PART

IBM supplies the PART transaction with an IMS system. This document uses the PART transaction for illustration purposes and as a reference for the adapter. The PART transaction accepts an input part number with a length of 17 characters or less. Based on what is passed to the PART transaction, an answer set is returned from the DP21PART database.

The PART transaction is an example of a transaction that returns multiple answer sets. Three different answer sets are returned based on what is passed in the request. The adapter enables you to create a response schema that contains different possible return messages.

Sample request documents, including sample response schemas for the PART transaction, are in Sample Requests, Schemas, and Cobol File Descriptions. You specify the output as explained in Creating an Adapter Transaction. You must know the field in the Cobol description that can be used as a record type and the value of that field. You specify the value of the field to create the appropriate response schema.

The previous is also true for events to determine the layout returned from IMS when you configure an IMS event. For more information on configuring IMS events, see Event Processing With the IMS Adapter.



x
Procedure: How to Create an Adapter Transaction

Perform the following steps to create an adapter transaction.

Note: For demonstration purposes only, this procedure uses the version of iWay Explorer that is embedded within iWay Designer. For more information about configuring and using this version of iWay Explorer, see the iWay Designer User’s Guide.

  1. Expand the Services node.

  2. Expand the IMS adapter node and connect to an available IMS target (for example, IMSTarget).

    The Transaction node appears under the connected target.

  3. Right-click the Transactions node and select Add Service from the context menu.

    The Add Service dialog box opens and displays two tabs (General and Cobol DD for Output). The following image shows the parameters in the General tab that will enable you to map the Cobol descriptions for the IMS/TM transaction.

  4. To map the Cobol descriptions for the IMS/TM transaction, type values for the parameters in the General tab, as defined in the following table.

    Parameter

    Description

    Node Name

    Name to describe the adapter transaction you create. This name, for example, Part, appears under the Transactions node for the current connection. The name to use in the <Transaction location="..."> attribute.

    Program Name

    Name of the program to be called in IMS/TM, for example, PART. The PART input DD is shown in Sample Requests, Schemas, and Cobol File Descriptions.

    Cobol MFS/XML for input

    Specifies the MFS XML input descriptor. For more information, see Specifying IMS/TM Transaction Input and Output.

    Cobol MFS/XML for output

    Specifies the MFS XML output descriptor. For more information, see Specifying IMS/TM Transaction Input and Output.

    Cobol DD for Input

    Location of the Cobol description that describes the input parameters of the IMS transaction to execute.

    Converted by the adapter to an XML schema that the adapter uses to map from XML to the format required by IMS/TM at run time.

    Convert Binary Zeros to

    Character to convert binary zeros to in output.

    Transaction has no reply

    Set this parameter to true when you do not want to wait for a response from the program.

    No Reply Wait time (TCP/IP only)

    Specify a wait time, in milliseconds, for IMS to send an error message during service interactions defined for IMS/TCPIP targets that use TCPIP connections when the Transaction has no reply check box is selected.

    Timeout (For default use 0)

    Specifies, in hundredths of a second, how long the adapter waits for a response before assuming IMS will not respond. The minimum is two seconds.

    To get the default value, enter 0. For TCP/IP connections, the default is in the IMS Connect configuration file. For CRM Gateway connections, the default is one minute.

    Note: The implementation of the Timeout parameter depends on whether the adapter connects to IMS using a TCP/IP connection, or using the CRM Gateway.

    If using a TCP/IP connection, the adapter uses the IMS Connect timeout service. It indicates the length of the timeout by setting the IRM_TIMER field in the IRM header to an appropriate value. The IRM_TIMER field is only one byte long, and the actual mapping from the IRM_TIMER value to the actual wait time is best explained in the IMS Connect Guide and Reference manual. The adapter maps the user-specified timeout to the IRM_TIMER value that would result in the wait time closest to the value entered.

    If using a CRM Gateway, the adapter sets the socket timeout, and the user-specified value is the value used for the timeout, without any modifications.

    Suppress blank delimiter on transaction name

    When this parameter is set to true, and the target uses Cobol copybooks, the adapter sends all eight character transaction codes to IMS Connect without appending a trailing blank.

    This parameter only applies to TCP/IP targets, and it only affects transactions with eight character names. Shorter transactions keep their trailing blank regardless of this setting. It has no effect on CRM Gateway targets. By default this parameter is set to false.

    LTERM

    Logical terminal. Blank is the default unless specified by the user.

    Use data structure information from Cobol

    When this parameter is set to true, the adapter creates request and response schemas that reflect Cobol group levels (for example, 05, 10, 20, and so on). The Cobol grouping will be reflected in the XML request and response schemas.

    You must enable this parameter when Cobol input or output descriptions contain the Cobol OCCURS statement.

    When this parameter is enabled and the program COMMAREA contains an OCCURS statement, the output Cobol definition must also contain an OCCURS statement. Do not "flatten out" the Cobol output description, since the adapter relies on the number of OCCURS when formulating the program output.

    Accept multiple records per TRANSACTION

    When this parameter is set to true, multiple COMMAREA records are read by the PreParser. Otherwise, any data in excess of the Cobol definition is truncated.

    Note: You must transfer the Cobol descriptions to a location accessible to iWay Explorer. For the correct Cobol descriptions to use for the program, contact your IMS/TM Administrator or application developer.

  5. Click the Cobol DD for Output tab.

    The Cobol DD for Output tab allows you to specify the path that corresponds to the message you want returned from the IMS/TM transaction. This tab contains the following columns:

    • COBOL Data Description
    • DD Field
    • Value

    If the transaction can return multiple types of messages for each output Cobol description, enter the Cobol description field and value to determine the schema that is created and used for a particular message.

    iWay Explorer creates the schema to use for a particular message based on the contents of a field that is returned. For example, a program called PART populates the field called RECTYPE. Depending on program logic, iWay Explorer creates the correct response schema.

    Value in RECTYPE Field

    Cobol Description

    space ' '

    PART_Detail_Out

    't'

    PART_Error_Out

    parenthesis ')'

    PART_All_Out

    The PART_Detail_Out, PART_Error_Out, and PART_All_Out Cobol descriptions appear in Sample Requests, Schemas, and Cobol File Descriptions.

  6. Click Update when you have finished configuring all the parameters.

    The new IMS/TM transaction is added under the Transactions node for the current target.


Top of page

x
Cobol Descriptions for Input and Output Communications

IMS Connect Considerations: Every time IMS Connect returns data (that is, an IMS Segment) it prefixes the data with LL, which represents the length of the returned data, and ZZ, which is a reserved field of binary zeros. The LL is called the IRM_LEN and is the length of the IRM structure, while ZZ is called IRM_RSV and is a reserved field. The format of the IRM structure is LLZZDATA, where LL is the total length of this segment, ZZ are binary zeros, and DATA is the IMS trancode followed by transaction data.

Important: The adapter does not require these prefixes in the Cobol input and output definitions. Only describe the data portion in the Cobol input and output definitions.



Example: Cobol Descriptions

You must use the following syntax for binary and packed fields for the Cobol descriptions for the adapter transaction input and output formats.

For a binary field:

05  BINARY-FIELD         PIC S9(n) COMP.

For a packed-decimal field:

05  PACKED-FIELD         PIC S9(n) COMP-3.

Note: Underscores are not supported in Cobol descriptions.


Top of page

x
Modifying COBOL DD Field Definitions

Using iWay Explorer, you can indicate that alpha type fields derived from COBOL DD input will be represented in XML by hex character strings. Specifically, this feature allows you to change the mapping for PIC X fields from XML type "string" to type "hexBinary". As a result, arbitrary binary data can be transmitted in an XML supported format to IMS applications. This feature is useful when sending flag bits.

The following is an input example:

FLAG1 PIC X
<FLAG>02</FLAG> to transmit byte X'02'

The following is an output example:

CHARS PIC X 4
AAAA is returned as <CHARS>C1C1C1C1</CHARS>


x
Procedure: How to Modify COBOL DD Field Definitions

To modify COBOL DD field definitions:

  1. Open iWay Explorer and connect to your IMS target.
  2. Expand the Transactions node and select a defined transaction.

  3. Right-click the transaction and select Modify DD from the menu.

    A sequence of Modify DD dialog boxes open representing the input and output record layouts for the transaction. Each layout includes the Use as Binary column, which allows you to modify an Alpha field.

  4. Select the Alpha field in the table that you want to use as Binary.
  5. Click the Use as Binary column and select yes or no from the drop-down list.
  6. Click Next to browse through the remaining input and output record layouts for the transaction.
  7. Click Done when you are finished to save the Alpha field modifications you made.

    HexBinary support is available for input and output transaction records. In particular, input RecType fields can also be defined with binary 'Value' arguments. In this case, the 'Value' data must be specified as the hexadecimal representation of the expected field.

  8. Right-click the transaction in the left pane and select Edit from the menu.

    The Edit dialog box opens.

    Note: Hexadecimal values must be specified before any modifications to Alpha fields are performed. This is required because the Edit dialog box only saves dialog input when you click Update. As a result, the internal COBOL DD representation to be recreated and any prior Alpha field modifications would be lost.


iWay Software