Customizing the CWI Analyzer Module

Because macro customization is an S/390 Assembly process, macro specifications adhere to the conventions of a standard S/390 Assembler specification:

Examples of macros with the following functions are included at the end of this topic:


XTR1S001

The Analyzer Controller template is customized using the XTR1S001 macro.

Syntax

XTR1S001 TYPE= < ANALYZER | IPPOOL | XMLDEF | FINAL >

Parameters

Name Description
ANALYZER Begin definition for the Attachmate Analyzer. An Analyzer is defined by a single TYPE=ANALYZER macro, followed by one or more TYPE=IPPOOL and TYPE=XMLDEF macros. The specification is completed with a single TYPE=FINAL macro. For details, see XTR1S001 TYPE=ANALYZER.
IPPOOL Optional definition of a set of IP addresses or ranges that will be defined once and referred to in the definitions of one or more XML messages using the TYPE=XMLDEF macro. This provides flexibility by allowing authorized IP addresses to be entered on each specific XMLDEF macro, or defined in a pool and referred to by the IPPOOL= parameter of the XMLDEF macro. For details, see XTR1S001 TYPE=IPPOOL.
XMLDEF Define an XML message that, when received over a CWI HTTP connection, will be directed to the specified CWI Converter and subsequently to the CWI-compliant server that will handle the request. For details, see XTR1S001 TYPE=XMLDEF.
FINAL Construct the Analyzer Controller Template (ACT). This template is linked into the CWI Analyzer provided by Attachmate. IP addresses and pools will be resolved and efficient IP filtering will be linked into the CWI analyzer along with the specifications for each defined XML message and an indication of a default HTTP handler (if any) for undefined messages. The Analyzer is assigned designated TCP/IP port using the standard CEDA TCPIPSERVICE customization. For details, see XTR1S001 TYPE=FINAL. (See the IBM CICS Resource Definition Guide for further information.)

XTR1S001 TYPE=ANALYZER

Define a CWI Analyzer and a default analyzer for undefined messages.

Syntax

XTR1S001 TYPE=ANALYZER,                           X
           DEFAULT=  < Name | NONE >

Parameters

Name Description
ANALYZER Begin definition for the Attachmate Analyzer. An Analyzer is defined by a single TYPE=ANALYZER macro.
DEFAULT Name Name of the CWI Analyzer program load module to be given control in the event that the HTTP message received does not match any of the XML messages defined for the Analyzer. An example might be HTML received which should be routed to the IBM default HTML handler (DFHWBADX) to be processed by the default Web service provided by IBM. This designation allows a single TCP/IP port to be shared between the HTML and XML requests not routed by the Attachmate Analyzer and those messages routed by the Attachmate Analyzer.
NONE Treats any HTTP messages not specifically defined in TYPE=XMLDEF macros as Invalid Requests.

XTR1S001 TYPE=IPPOOL

Define a Group of IP addresses for authorization to conduct XML message exchanges with the target CICS region.

Syntax

Name   TYPE=IPPOOL,                                X
       nnn.nnn.nnn.*,                              X
       nn.nnn.nnn.nnn,                             X
       nn.nn.nnn.*

Parameters

Name Description
POOLNAME Name An eight-character name given to this group of IP addresses. Subsequent definitions of XML messages (XMLDEF) will refer back to this name as the collection of IP addresses to be granted access via this XML message.
IP ADDRESSES nnn.nnn.nnn.nnn A list (up to 16,000 elements) of IP addresses. Each IP address must consist of four components, each of which is either an integer less than 255 or the wildcard character (*). DNS names cannot be used.

XTR1S001 TYPE=XMLDEF

Define an XML message, or family of XML messages, and the corresponding CWI Converter, server, and parameters to use to execute XML-based server programs.

Syntax

Name   TYPE=XMLDEF,                                X
       HLQTAG=1stXMLtag,                           X
       XMLTAGA=2ndXMLtag,                          X
       TAGAID=value                                X
       CWICONV=converter,                          X
       CWISERV=server,                             X
       XLAT=< name | NONE >,                      X
       IPPOOL=poolname
         |
       nn.nnn.nnn.nnn,                             X
       nn.nn.nnn.*

Parameters

Name Description
MESSAGENAME Name An optional eight-character name to be given this XML definition. By specifying a name, the group of IP addresses defined in this macro can be treated as an IPPOOL definition, and reference in subsequent XMLDEF macros may be made in the same way an IPPOOL macro is referenced.
HLQTAG 1stXMLtag The first XML tag to be expected from the HTTP conversation for this XML message type. This tag should be exactly as the first tag in the data stream after the <xml version=1.0> will appear, but without the angle brackets (< >). For example, if <ATTACHMATE> is the first expected XML tag for a supported message, this parameter should appear as:
 HLQTAG=ATTACHMATE,                       X
XMLTAGA 2ndXMLtag The second XML tag to be expected from the HTTP conversation for this XML message type. This tag should be exactly as the second tag in the data stream after the <xml version=1.0> will appear, but without the angle brackets. This tag may be identified with a wildcard character (*), indicating that all HTTP XML traffic bearing the HLQTAG should be passed to the Converter without further inspection.
TAGAID Value If XMLTAGA is not specified as a wildcard, this parameter allows for the matching of a specific value inside the XMLTAGA parameter in the actual XML data stream. For instance, the XML stream <ATTACHMATE><CONNECTORID>QACOM_BIN</CONNECTORID> would be defined as TAGAID=QACOM_BIN.
CWICONV converter The name of the CWI Converter program load module to be given control when this defined XML message is received in the CICS region. For non-Attachmate product XML messages, the converter name must be supplied.
CWISERV server The name of the Server program load module to be given control when this defined XML message is received in the CICS region. For XML messages that are not coming from an Attachmate product, the server name must be supplied.
XLAT name The name of the DFHCNV module to be used for code page translation. This parameter is optional and defaults to NONE. A name provided will identify which DFHCNV translation module to use. An example module given by IBM is DFHWBHH. Attachmate products will default the correct XLAT parameter where possible.
IPPOOL name The name of the previously defined pool of acceptable IP addresses from which XML exchanges will be allowed. This pool may have been defined by use of the TYPE=IPPOOL, or by putting the specified IPPOOL=name as the Name field on another TYPE=XMLDEF macro. If the name comes from the Name field of a previous XMLDEF macro, the set of specific IP addresses configured for that XMLDEF are the same set allowed to access the transaction defined by this XMLDEF message.
IP ADDRESSES nnn.nnn.nnn.nnn A list (up to 16,000 elements) of IP addresses. Each IP address must consist of four components, each of which is either an integer less than 255 or the wildcard character (*). DNS names cannot be used.

XTR1S001 TYPE=FINAL

Specify the conclusion of customization to the Attachmate CWI Analyzer.

Syntax

XTR1S001 TYPE=FINAL


Examples

Filtering Requestor IP Addresses

The following example illustrates the use of IP Filtering to limit the requestor addresses that will be serviced. In the following example, the specific requestor address 140.147.249.7 will be accepted, as will requestor IP addresses beginning with 63.71.228. The wild card character "*" can be used on any and all of the four-part IP address segments.

XML Stream

QACOM_BIN
...

Macro Encoding

* ********************************************************
* ********************************************************
* **             ANALYZER CUSTOMIZED FOR THE            **
* **               ATTACHMATE DATA ENGINE               **
* ********************************************************
* ********************************************************
       XTR1S001 TYPE=ANALYZER, DEFAULT=NONE
       XTR1S001 TYPE=IPPOOL, HLQTAG=ATTACHMATE,          X
            XMLTAGA=CONNECTORID,                         X
            TAGAID=QACOM_BIN,                            X
            140.147.249.7,                               X
            63.71.228.*
       XTR1S001 TYPE=FINAL

XML Messages Supporting the Same Client IP Addresses

The following example illustrates a customization in which two different categories of XML messages will be accepted from a single set of IP addresses. An IPPOOL is set up once at the beginning and then referenced by XMLDEF definitions for both XML message types.

XML Stream

QACOM_BIN
...

OR:

PART_INQUIRY
...

Macro Encoding

* *****************************************************
* *****************************************************
* **           ANALYZER CUSTOMIZED FOR THE           **
* **             ATTACHMATE DATA ENGINE              **
* ***           ATTACHMATE SERVER TOOLKIT            **
* *****************************************************
* *****************************************************
       XTR1S001 TYPE=ANALYZER, DEFAULT=DFHWBADX
       ADJUSTER  XTR1S001 TYPE=IPPOOL,               X
                      140.147.249.*,                 X
                      65.205.231.130,                X
                      63.71.228.*
                 XTR1S001 TYPE=XMLDEF,               X
                          HLQTAG=MYCO,               X
                          XMLTAGA=SUBSYSREQ,         X
                          TAGAID=PART_INQUIRY,       X
                          CWICONV=PARTINQC,          X
                          CWISERV=PARTINQS,          X
                          XLAT=DFHWBHH,              X
                          IPPOOL=ADJUSTER
                 XTR1S001 TYPE=XMLDEF,               X
                      HLQTAG=ATTACHMATE,             X
                          TAGAID=QACOM_BIN,          X
                          IPPOOL=ADJUSTER
                 XTR1S001 TYPE=FINAL

Any Client IP Address Permitted

Following is an example of an XML message that has been defined as unsecured. A wildcard IP address has been set up to facilitate traffic from any client that is capable of formatting the proper XML message.

XML Stream

QACOM_BIN
...

Macro Encoding

* ******************************************************
* **          ANALYZER CUSTOMIZED FOR THE             **
* **            ATTACHMATE DATA ENGINE                **
* ******************************************************
* ******************************************************
       XTR1S001 TYPE=ANALYZER, DEFAULT=DFHWBADX
       XTR1S001 TYPE=XMLDEF, HLQTAG=ATTACHMATE,       X
            XMLTAGA=CONNECTORID,                       X
            TAGAID=QACOM_BIN,                          X
            *.*.*.*
       XTR1S001 TYPE=FINAL
Related Topics
Bullet Installation, Overview
Bullet Upgrading, Overview
Bullet Installing in UNIX
Bullet Installation Prompts for Management Components in Windows
  Attachmate