Customizing the CWI Analyzer Module

Macro customization is an S/390 Assembly process. Macro specifications adhere to the standard S/390 Assember specification. These include:

Names that start in column one and have up to eight characters.
XTR5S001 starts in column 10.
Lines that continue must end in a comma and contain an "X" in column 72. The line will continue starting on the next line in column 16.
The last line of the macro cannot end with a comma

XTR55001

The Analyzer Control template is customized using the XTR5S001 macro.

Syntax
XTR5S001 TYPE= < ANALYZER | IPPOOL | URIDEF | 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.

IPPOOL Optional definition of a set of IP addresses or ranges that will be defined once and referenced in the definitions of one or more HTTP message handlers as defined using the URIDEF macro. This provides flexibility by allowing authorized IP addresses to be entered on each specific URIDEF macro, or defined once in a pool and referenced by use of the IPPOOL= parameter of the URIDEF macro.

URIDEF Define a handler for a given HTTP based 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.

FINAL Construct the Analyzer Control Template (ACT). This template is linked to 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 HTTP message and an indication of the default handler (if any) for undefined messages received. The Analyzer is assigned the designated TCP/IP port using the standard CEDA TCPIPSERVICE customization. (See the IBM CICS Resource Definition Guide for further information.)

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.
IPPOOL	Optional definition of a set of IP addresses or ranges that will be defined once and referenced in the definitions of one or more HTTP message handlers as defined using the URIDEF macro. This provides flexibility by allowing authorized IP addresses to be entered on each specific URIDEF macro, or defined once in a pool and referenced by use of the IPPOOL= parameter of the URIDEF macro.
URIDEF	Define a handler for a given HTTP based 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.
FINAL	Construct the Analyzer Control Template (ACT). This template is linked to 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 HTTP message and an indication of the default handler (if any) for undefined messages received. The Analyzer is assigned the designated TCP/IP port using the standard CEDA TCPIPSERVICE customization. (See the IBM CICS Resource Definition Guide for further information.)

XTR55001 TYPE=ANALYZER

Define a CWI Analyzer and an optional default analyzer to which unrecognized HTTP messages will be routed.

Syntax
XTR5S001   TYPE=ANALYZER,                             X
           DEFAULT=  < Name | NONE >
           TIMEOUT=  <Seconds>                       X
           CTRAN=    <NAME>
Parameters

Name Description

ANALYZER Begin definition for the Attachmate Analyzer. An Analyzer is defined by a single TYPE=ANALYZER macro.

DEFAULT
Name
The CWI Analyzer program load module to be given control in the event that an HTTP message received does not contain a URI that is recognized as being controlled by this Analyzer. An example might be HTML received that should be routed to the IBM default HTML handler (DFHWBADX) to be processed by the default Web service provided by IBM. This designation allows HTML, XML, and undefined HTTP messages received over a given TCP/IP port to be shared between Attachmate-provided CWI components and CWI components provided by another vendor or customer.

NONE Treats any HTTP message not specifically defined in TYPE=URIDEF macros as Invalid Requests.

TIMEOUT Time in seconds that a Connect will be allowed to persist before its host resources are released. Once traffic beyond the Connect request is received, the timeout value configured for the Server will assume control for the session.

CTRAN The transaction ID to be dispatched once the inactivity TIMEOUT for the session is reached. Services Builder for CICS TCP/IP Connectivity Feature is shipped with a template value for CTRAN of AQCC.

Name	Description
ANALYZER	Begin definition for the Attachmate Analyzer. An Analyzer is defined by a single TYPE=ANALYZER macro.
DEFAULT Name	The CWI Analyzer program load module to be given control in the event that an HTTP message received does not contain a URI that is recognized as being controlled by this Analyzer. An example might be HTML received that should be routed to the IBM default HTML handler (DFHWBADX) to be processed by the default Web service provided by IBM. This designation allows HTML, XML, and undefined HTTP messages received over a given TCP/IP port to be shared between Attachmate-provided CWI components and CWI components provided by another vendor or customer.
NONE	Treats any HTTP message not specifically defined in TYPE=URIDEF macros as Invalid Requests.
TIMEOUT	Time in seconds that a Connect will be allowed to persist before its host resources are released. Once traffic beyond the Connect request is received, the timeout value configured for the Server will assume control for the session.
CTRAN	The transaction ID to be dispatched once the inactivity TIMEOUT for the session is reached. Services Builder for CICS TCP/IP Connectivity Feature is shipped with a template value for CTRAN of AQCC.

XTR5S001 TYPE = IPPOOL

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

Syntax
Name   XTR5S001 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 HTTP messages (URIDEF) will refer back to this name as the collection of IP addresses to be granted access via the defined HTTP 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.

Name	Description
POOLNAME Name	An eight-character name given to this group of IP addresses. Subsequent definitions of HTTP messages (URIDEF) will refer back to this name as the collection of IP addresses to be granted access via the defined HTTP 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.

XTR5S001 TYPE = URIDEF

Define an URI that designates a unique HTTP message handler, and the corresponding CWI Converter and server designated to process messages targeted for this URI.

Syntax
Name     XTR5S001 Type=URIDEF,                        X
         URI=/MYURI/MYCOMPONENT,                      X
         CWICONV=MYPROG,                              X
         CWISERV=MYSERV,                              X
         IPPOOL=poolname,                             X
           |
         nn.nnn.nnn.nnn,                              X
         nn.nn.nnn.*
Parameters

Name Description

URI NAME
Name The eight-character name given to this HTTP message definition. By naming this URIDEF an implied IPPOOL is instantiated and can be referenced on subsequent URIDEF macros thereby simplifying definitions for IP filtering.

URI
URI-Specification A Universal Resource Indicator defining the CWI Converter and Server designated to handle the associated HTTP message. Note: The URI for Services Builder for CICS is /ATTACHMATE/HAPICICS for a global DPL definition and/or /ATTACHMATE/HAPICICS/<progname> for each specific <program> to which IP access is to be controlled.

CWICONV
converter The eight-character name of the CWI Converter program load module to be given control when this defined HTTP message is received in the CICS region. For non-Attachmate product HTTP messages the converter name must be supplied.

CWISERV
server The eight-character name of the CWI Server program load module to be given control when this defined HTTP message is received in the CICS region. For non-Attachmate product HTTP messages the server name must be supplied.

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 at least an integer less than 255 or the wildcard character (*). DNS names cannot be used.

Name	Description
URI NAME Name	The eight-character name given to this HTTP message definition. By naming this URIDEF an implied IPPOOL is instantiated and can be referenced on subsequent URIDEF macros thereby simplifying definitions for IP filtering.
URI URI-Specification	A Universal Resource Indicator defining the CWI Converter and Server designated to handle the associated HTTP message. Note: The URI for Services Builder for CICS is /ATTACHMATE/HAPICICS for a global DPL definition and/or /ATTACHMATE/HAPICICS/<progname> for each specific <program> to which IP access is to be controlled.
CWICONV converter	The eight-character name of the CWI Converter program load module to be given control when this defined HTTP message is received in the CICS region. For non-Attachmate product HTTP messages the converter name must be supplied.
CWISERV server	The eight-character name of the CWI Server program load module to be given control when this defined HTTP message is received in the CICS region. For non-Attachmate product HTTP messages the server name must be supplied.
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 at least an integer less than 255 or the wildcard character (*). DNS names cannot be used.

XTR5S001 TYPE = FINAL

Specify the conclusion of customization to the Attachmate CWI Analyzer.

Syntax
Name     XTR5S001   TYPE=FINAL

Services Builder for CICS Shared Analyzer Example

The following example illustrates access to /ATTACHMATE/HAPICICS/PROGNAMA from any workstation, and /ATTACHMATE/HAPICICS/PROGNAMB being accessed by 140.147.249.6 or 140.147.249.7, as well as any workstation starting with 63.71.228.

The group of IP addresses defined as accessible to /ATTACHMATE/HAPICICS/PROGNAMC is allowed access to /cgi-bin/ATTMHPS. The reference /cgi-bin/ATTMHPS routes requests to the Attachmate Services Builder for CICS, illustrating the ability to share a given TCP/IP port with more than one product via the routing functionality provided by the Attachmate CWI Analyzer.

*-----------------------------------------------------------------
*          IN THE FOLLOWING CONFIGURATION EXAMPLE
*          140.147.249.7 = AUTHORIZED SPECIFIC CLIENT EXAMPLE
*          63.71.228.*   = AUTHORIZED IP SEGMENT EXAMPLE
*-----------------------------------------------------------------
        XTR5S001 TYPE=ANALYZER,                                  X
           DEFAULT=DFHWBADX,   Next in chain default analyzer    X
           TIMEOUT=60, Connect will reserve a session for 1 min  X
           CTRAN=AQCC  Clean up transaction ID for our server
MYPOOL  XTR5S001 TYPE=IPPOOL,                                    X
           140.147.249.7,                                        X
           63.71.228.* 
        XTR5S001 TYPE=URIDEF,URI=/ATTACHMATE/HAPICICS,           X
           63.71.228.* 
        XTR5S001 TYPE=URIDEF,URI=/ATTACHMATE/HAPICICS/PROGNAMA,  X
           *.*.*.*
ADJUSTR XTR5S001 TYPE=URIDEF,URI=/ATTACHMATE/HAPICICS/PROGNAMB,  X
           140.147.249.7,                                        X
           140.147.249.6,                                        X
           63.71.228.*
        XTR5S001 TYPE=URIDEF,URI=/ATTACHMATE/HAPICICS/PROGNAMC,  X
           140.147.249.7 
S3270   XTR5S001 TYPE=URIDEF,URI=/cgi-bin/ATTMHPS,               X
           IPPOOL=ADJUSTR
        XTR5S001 TYPE=URIDEF,URI=/MYURI/MYCOMPONENT,             X
           CWICONV=MYCONV,                                       X
           CWISERV=MYSERV,                                       X
           IPPOOL=MYPOOL
        XTR5S001 TYPE=FINAL
        END


	Using the TCP/IP Connectivity Feature
	Installing from the CD on an OS/390 Server
	Installing from Tape or Disk
	Customizing the CWI Server Module