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.
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.
The following section describes how to specify the input and output for MFS IMS/TM transactions. Examples are also provided.
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:
|
iwaySuppress | This attribute is reserved for future use (Optional). |
iwayFieldType | The following values are available:
|
attribute | Specifies whether 3270 attribute bytes are included (Required). The following values are available:
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:
|
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.
<MFLD name="SomeField" Length="10" iwaySuppress="no" iwayFieldType="alpha" attribute="no" fill=" " default="WHATEVER" />
<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.
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:
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:
|
iwayFieldType |
The following values are available:
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. |
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:
As a reference, it helps to use the Cobol description of the output message or the MFS message output descriptor area for the transaction to create the Cobol descriptions.
Note: For generic transactions where the format of the output is of no consequence, you are not required to supply Cobol descriptions.
For the PART transaction, you require three Cobol descriptions. A RECTYPE field in each description is used by the adapter to determine which of the three messages is being returned by the adapter.
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.
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.
The Transaction node appears under the connected target.
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.
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.
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:
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.
The new IMS/TM transaction is added under the Transactions node for the current target.
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.
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.
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>
To modify COBOL DD field definitions:
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.
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.
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 |