GAIN version 1.2 General Information, Planning and ... · 1 1 General Information This chapter provides information about GAIN, the GATES APPC IP Networking product. It describes:

GAIN version 1.2

General Information,Planning andTechnical Overview

Manual: A-GPT0102-1

UnicornNetworking

ii

Copyright2001 - 2003 Unicorn Networking Ltd.Published February 2003, First Edition

OpenEdition, OS/390, RACF, VTAM and z/OS are trademarks of IBM Corporation. ACF2 and TopSecret are trademarks of Computer Associates Inc. All other trademarks, service marks, registered trademarks or registered service marks mentioned in this document are the property of their respective owners.

Contact Information

Unicorn Networking Ltd.24 High StreetPetersfieldGU32 3JLEngland

Tel: +44 1730 237236e-mail: [email protected]

DisclaimerThe information in this publication is subject to change without notice. While every effort has been made to ensure the accuracy and timeliness of the information contained in this publication, neither Unicorn Networking nor the author shall have any liability with respect to loss or damage caused or alleged to be caused by reliance on any information contained herein.

Table of Contents

1 General Information 1

GAIN - GATES APPC-IP Networking . . . . . . . . . . . . . . . . . .2What is GAIN ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Why GAIN ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Which TCP applications are supported by GAIN ? . . . . . . . . . . 5Which APPC applications are supported by GAIN ?. . . . . . . . . 6

GAIN Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7Connecting Unsupported Equipment . . . . . . . . . . . . . . . . . . . . 7Making Business Applications Device Independent . . . . . . . . . 8Improving Business Application Security . . . . . . . . . . . . . . . . . 9Improving Business Application Availability . . . . . . . . . . . . . . 10Adding Value to Business Application Data . . . . . . . . . . . . . . 11Internal Monitoring and Automated or Assisted Operation . . . 12Business Application Testing. . . . . . . . . . . . . . . . . . . . . . . . . . 13

GAIN Components and Feature List . . . . . . . . . . . . . . . . . . 14GAIN Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14GAIN transaction and Message Support. . . . . . . . . . . . . . . . . 15TCP Client, Server and Peer Networking Support . . . . . . . . . 16APPC Client, Server and Peer Networking Support . . . . . . . . 18Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Flexibility (configuration and REXX) . . . . . . . . . . . . . . . . . . . . 19Manageability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

GATES Support for GAIN . . . . . . . . . . . . . . . . . . . . . . . . . .21What is GATES ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21What is GAIN in this context ? . . . . . . . . . . . . . . . . . . . . . . . . 21What are Custom Solutions ? . . . . . . . . . . . . . . . . . . . . . . . . . 22GATES Base Code Features . . . . . . . . . . . . . . . . . . . . . . . . . 22GATES Design Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Sample GAIN Configuration . . . . . . . . . . . . . . . . . . . . . . . . 26Essential configuration parameters for all systems . . . . . . . . . 26Access Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27User Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Management Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28An example APPC Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 28An example TCP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Sample GAIN Logs and Displays . . . . . . . . . . . . . . . . . . . .32Operating System Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Journal Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Error Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34REXX Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34SYSOUT log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34List and Show Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

iii

2 Planning 37

Deliverables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38The Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Pre-Requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Obtain the Product Materials and Access Key . . . . . . . . . . . . 41Reserving disk space for the GATES datasets . . . . . . . . . . . . 41Updating the system PROCLIB with the GATES procedure . . 42Updating the system PARMLIB . . . . . . . . . . . . . . . . . . . . . . . . 42Updating the system VTAMLST. . . . . . . . . . . . . . . . . . . . . . . . 43Updating the system VTAMLIB . . . . . . . . . . . . . . . . . . . . . . . . 43SMP/E install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43APF authorise the SUNLINK module library . . . . . . . . . . . . . . 43Define the started task to SAF . . . . . . . . . . . . . . . . . . . . . . . . . 44Run the IVP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3 Technical Overview 45

GATES Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Optional Access Method Interfaces . . . . . . . . . . . . . . . . . . . . . 47Base Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

GATES Operational Models . . . . . . . . . . . . . . . . . . . . . . . . .50Integrated Application Model . . . . . . . . . . . . . . . . . . . . . . . . . . 50Message Switching Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Internal Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52The Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55GAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Unix System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58The Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59Event Trace Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

iv

1 General Information

This chapter provides information about GAIN, the GATES APPC IP Networkingproduct. It describes:

• What GAIN is, what it can do and where it can be used

• The relationship between GAIN and the GATES architecture.

• Custom Solutions and how some features can be used to extend GAINsapplicability or provide alternative connectivity solutions.

• Sample GAIN configuration

• Sample GAIN log and display output

You can also find information about planning for a GAIN implementation, in thechapter “Planning” on page 37.

If you want to understand how GATES and GAIN are architected, see thechapter “Technical Overview” on page 45.

1

General Information

GAIN - GATES APPC-IP Networking

What is GAIN ?

GAIN (GATES APPC-IP Networking) is a program product for IBMmainframes running the OS/390 or z/OS operating systems. GAIN allowsTCP applications running on hosts in an IP network to inter-communicatewith APPC based transaction programs in an SNA network without modifi-cation.

For example: using GAIN, data from many different types of TCP applicationcan be placed directly on IMS queues or schedule CICS transactions withoutthe need for additional mainframe programming.

Figure 1, “Networking TCP and APPC applications using GAIN” illustrateshow a high availability sysplex based GAIN environment can be used toconnect TCP applications running on UNIX, MS Windows or any otherplatform in an IP network to IMS, CICS or other APPC based sub systems inan SNA network. This means that applications such as web browsers, telnetclients and many other applications can communicate through GAIN asthough they were connected to a TCP server, never knowing that an APPCapplication is actually responding.

GAIN allows critical business applications such as those associated with IMSand CICS subsystems to run unaware of the network protocol used tocommunicate with a remote device. Changes to the network or protocolsused by the remote application need have no effect on the business appli-cation, the business appliction is said to be ‘device independent’.

Fig. 1. Networking TCP and APPC applications using GAIN

Other

UNIX

SNA network

TCP/IP network

Operating System Services

GAINApplication Logic

Access Method Interfaces

GAIN address space

SNA network


CICS IMS

SNA network

TCP/IP network




GAIN address space

WindowsSNA network

OtherAPPC

Other

UNIX

SNA network

TCP/IP network




GAIN address space

SNA network

TCP/IP network




GAIN address space

SNA network


CICS IMS

SNA network

TCP/IP network




GAIN address space

SNA network

TCP/IP network




GAIN address space

WindowsSNA network

OtherAPPC

2


What is GATES

The GATES in ‘GATES APPC-IP Networking (GAIN)’ is a software designmethodology that is implemented as a working code base for applicationdevelopment, in this case GAIN is the application. A GAIN installation alwaysincludes all the features described in “GATES Support for GAIN” on page 21.

Why GAIN ?

Every customer is different, you might be reading this document because youare currently unable to connect new equipment to old applications or viceversa. You might have a security vulnerability that can be removed through asecure front end application such as GAIN or you might have a more complexproblem requiring integration of other systems into the GAIN environment.

GAIN and GATES have been designed to tackle many unusual situations.These are the principal features that make GAIN the solution of choice:

DeviceIndependence:

The holy grail of business applications, device independence means neverhaving to change a business application (a transaction processor) because:

• The network evolves, perhaps it is a move to IPv6 on the mainframe.This would normally require changes to all existing sockets applica-tions.

• The remote application needs to modify its protocols, this time it couldbe a move from a telnet client protocol to web services that causesother socket applications to be re-written.

• A new local application (transaction) forces additions to an existingprotocol. GAIN can protect transactions developed earlier allowingevolutionary development of business applications.

Connectivity: By using GAIN, APPC based transaction programs are able to acceptconnections and exchange data with TCP applications in a structured mannernot available through off-board gateways and without a requirement for, oftenexpensive, SNA services in each of the IP hosts. Many flavours of TCP appli-cation exist, with GAIN business applications get immediate support to all ofthe major protocols. See “Which TCP applications are supported by GAIN ?”on page 5 for more information about what GAIN does to support TCPconnections. Connection to old or new equipment, complicated or simpleprotocols are all available through a single instance of GAIN.

Security: GAIN provides both connection and user level security.

Connection level security is included for both the SNA and the TCPIP inter-faces. This is an ideal method for preventing unwanted intrusion from theoutside world or from within an intranet, GAIN’s protection means that IPaddress ranges or sub-networks can be allowed or denied access to one ormore of the remote transaction systems. SNA protection can do the same apractical use of this is in the prevention of accidental cross connectionn ofSNA based test and production systems with potentially disastrious conse-quences for on-line databases.

User level security may require authentication prior to GAIN logon or passthrough to a transaction processing system. Where possible this is performedon a parameter driven basis. If the user details needs to be extracted from theinput message in some complex manner then GAIN exit code and callable

3

General Information

security interfaces mean that user authentication processing can becompleted with the minimum of programming knowledge.

Transaction Management:

When working with transaction oriented systems, the GAIN transactionmanagement system provides workload management and queuing structureswithout the need for distributed client code. Competing processes take workfrom the queues and present this to the business applications. This structureprovides not only for great efficiency and scalability but also for resilienceshould any single process fail.

Transaction management also includes the monitoring of workloads so thatslow/overworked business applications that cause queue build-ups in theGAIN address space result in the generation of server busy responses to newtransactions and the potential timing out of active or queued transactions.

Manageability: GAINs manageability is such that it can add a new level of clarity to your viewof business application performance. GAIN provides both real time statusdisplays and statistics about any and all connections and/or remote services.Customers can write their own management routines in REXX and therebybuild completely tailored reports on their business applications.

Reliability The GAIN philosophy is one of resilience through duplication and redun-dancy. Multiple dispatchable instances (tasks and/or processes) are clusteredto a common function. Connections are then grouped across the cluster. Thismeans that a failure in any one process need not impact access to a remotesystem or the transaction processing capabilities of any defined service.

To minimise the chances of process failure the GATES base code on whichGAIN runs provides FRRs and ESTAE routines that allow diagnostics to becaptured and where possible recovery to be effected without loss of theprocess.

The effect of total system failures can be minimised through the use ofdynamic VIPA support. GAIN’s ability to listen on a specific port and optionallya specific IP address provides sites with greater flexibility in planning theirfallback/recovery scenarios.

Flexibility GAIN’s flexibility and ease of customisation means that existing customerapplications or purpose written REXX extensions can be easily included intothe GAIN environment. Customisation of the GAIN service allows increasedvalue to be added to the business data passing through the GAIN addressspace. If GAIN’s flexibility still does not meet your needs then perhaps aGATES based custom solution is what you need.

Scalability Scalability within an address space is provided through the clustering oftasks and processes and the competitive processing of workload queues.This structure allows the standard multi-processing environment of an OS/390 z/OS system to be exploited to the full.

Scalability within a sysplex is provided through the use of advanced operatingsystem facilities. Optional registration with the WorkLoad Manager whenused in conjunction with WLM/DNS or Sysplex Distributor (with or withoutCisco’s Multi-Node Load Balancing, MNLB) can be used to distributeworkload across multiple GAIN images within a sysplex. When APPC is theclient VTAM’s Generic Name support can be used to distibute APPC transac-tions across multiple GAIN images within a sysplex.

4


Which TCP applications are supported by GAIN ?

This question is best first answered via another question: Why do we need toconsider this at all? The answer is, because the TCP standard, not only doesnot define how applications need to inter-operate but also fails to define struc-tures essential to IBM mainframe computing e.g. the concept of a record.GAIN makes great efforts to hide this fact by taking the random sequences ofbytes received over the net (translating them to EBCDIC) and making theminto whole records for later processing by business applications. This sectiondescribes the different remote TCP systems supported.

All the common TCP/IP suite of interactive applications for end-users(humans and application programs) are supported as well as programmedvariable length record datastreams and OSI’s BER encoding for ASN.1datastreams. GAIN also supports user defined datastreams, such as recorddependent variable offset length fields, through the use of exit routines

GAIN supports these applications in both the client and server model (whereapplicable) and through customisation allows peer communications betweenTCP and APPC applications. Figure 2, “GAIN’s TCP support” illustrates thesupported network protocols and possible users of each. “TCP Client, Serverand Peer Networking Support” on page 16 for additional details on GAINSTCP support...

Fig. 2. GAIN’s TCP support

TCP/IP network

Op System Services



GAIN address space

Telnet client HTTP

Character delimited

Lengthdelimited

BER encoded

Customprotocol

MS WindowsUNIX etc

MS Internet Explorer,

Netscape –Navigator,Opera etc.

WebServices based on

SOAP and XML

Telnet Servere.g. Cisco

Router

Programmed Communications

TCP/IP network

Op System Services



GAIN address space

Telnet client HTTP

Character delimited

Lengthdelimited

BER encoded

Customprotocol

MS WindowsUNIX etc

MS Internet Explorer,

Netscape –Navigator,Opera etc.

WebServices based on

SOAP and XML

Telnet Servere.g. Cisco

Router

Programmed Communications

5

General Information

Which APPC applications are supported by GAIN ?

This time the question of supported applications is included because of theclose relationship between GAIN and transaction processing systems. TheGATES core code already provides strong support for APPC transactionbased programming. GAIN extends this support through three modes ofoperation, these are:

Figure 3, “GAIN’s APPC support” illustrates the transaction and messagemodes supported with examples of the applications using them. All modescan support either client or server models, however message mode can alsobe used for peer communications between APPC and TCP partner appli-cation. “APPC Client, Server and Peer Networking Support” on page 18 forfurther details of APPC support.

Transaction Mode In this mode GAIN provides transaction oriented syn-chronous (message-in, message-out) or asynchronous (message-in-only) services to applications such as CICS, IMS and the many other applications with similar transaction characteristics.

Message Mode In this mode GAIN simply forwards received data according to its configured routing while honouring the protocol requirements for data transfer. GAIN is una-ware of any structure to the APPC conversation. The connection can be considered a data pipe between the two applications.

Custom Mode This mode is more usually applied to GATES custom solutions and allows the application to fully specify the characteristics of the APPC conversation. It can be used with GAIN when the TCP and transaction management support are desired.

Fig. 3. GAIN’s APPC support

SNA network

Op System Services



GAIN address space

Synchronous Transactions

Asynchronous Transactions

Message Transfer

CICS, IMS and others Programmed Communications

IMS async queuing etc

SNA network

Op System Services



GAIN address space

Synchronous Transactions

Asynchronous Transactions

Message Transfer

CICS, IMS and others Programmed Communications

IMS async queuing etc

6

GAIN Usage Scenarios


Due to its flexibility there are many possible scenarios for GAIN usage, mostof which will be covered by one or more of the following scenarios:

Connecting Unsupported Equipment

This is the most obvious of GAINs many potential roles. It may form part of a3745 replacement strategy or a general move to IP networking within theenterprise. In most cases it will mean providing a solution for legacymainframe applications which are otherwise unable to communicate withnetwork attached equipment for reasons such as:

• One or more business applications are coded to a single API whichcannot communicate with the intended device e.g. VTAM APPC appli-cations may wish to communicate with a TCP/IP attached device.

• A remote device or application uses a datastream not supported by thetarget applications.

• Received data requires some manipulation or routing decision to bemade prior to delivery to the target application.

By supporting multiple protocols, GAIN can give any application a new leaseof life.

In Figure 4, “Using GAIN to provide IP access to APPC based transactions”we see GAIN providing CICS and/or IMS transaction access to UNIX andWindows based applications in an IP network. (note: in an SNA LU6.2environment IMS actually uses APPC/MVS to communicate with GAIN).I

In this scenario the GAIN system establishes SNA sessions with partnersystems and initiates listens on the IP network as part of initialisation. After aTCP connection is accepted the AMI receives data from the IP network as astream (some undefined length of bytes). Multiple streams of data may beaccumulated into a single record or message or if necessary a single streamof data broken into multiple records or messages by the AMI segmentation

Fig. 4. Using GAIN to provide IP access to APPC based transactions

SNAnetwork

SNAnetwork

TCP/IPnetwork

Operating System ServicesOperating System Services

UNIX

Win NT

CICS GAINApplication Logic


GAIN / GATES address space

IMS

7

General Information

routines. These records can then be converted from ascii to ebcdic and anyunwanted characters, such as CRLF characters can be removed. The GAINexits can add further value to the data received possibly changing it’s layout,removing headers etc.

GAIN will then determine unique routing requirements for the messagedependent upon information in the data and/or configuration parameters,queuing the message on a transaction or message queue as appropriate.

As SNA processes become free they inspect the queues for more work. Anew transaction request initiates a conversation with the target application(using one of the LU6.2 sessions established during initialisation). The UNIX/Windows request is then processed as a CICS or IMS transaction.

If and when a transaction response is returned then this data is converted toascii and sent across the IP network to the UNIX or Windows system origi-nating the request. Optionally a response exit may interpret the programmedresponse and provide alternative feedback to the initiating TCP application.

Making Business Applications Device Independent

A strategic decision to provide device and protocol independence to businessapplications makes sense. This is particularly so because TCP applicationsare much more dependent upon application to application protocols thansimilar SNA connections. TCP applications are also more complex to write,they may involve record segment collating before processing and evencharacter set translation. Using GAIN allows a set of business applications tomaintain a consistent interface to the outside world. Using GAIN allowscomplex TCP protocols to be shielded from the business application suite

Business applications maintain a consistent interface with GAIN whilenetwork and application protocols change as new equipment and new appli-cations evolve within the networked infra-structure. This means: no change isrequired to the business application when a new TCP application is added.No change is required when an application protocol is modified. A useful side

Fig. 5. Moving a service to a TCP host

TCP/IP network

SNA network


UNIX based server application


GATESAccess Method Interfaces

GAIN address spaceAPPC application

TCP/IP network

SNA network


UNIX based server application



GAIN address spaceAPPC application

8


effect of this is that applications can also be moved transparently from oneplatform (SNA or IP based) to another.

Device independence also applies at any time in the future as well as atpresent. It is not only whether there is an absolute need for GAIN today butalso whether GAIN’s terminal support will be required tomorrow. Using GAINremoves the need to be aware of changing and/or developing device andnetwork protocols providing transaction processing systems instead with truedevice independence.

Improving Business Application SecurityGAIN exploits a number of connection and user oriented security featuresimplemented in the GATES base code. These features define whetherremote network resources are to be allowed or denied access to the GAINenvironment and its upstream business applications. GAIN and GATEStogether, in conjunction with your operating systems SAF product or usingstand-alone parameter files, can also restrict access on a per user basis.

In Figure 6, “Protecting downstream applications from “hackers”” we see that

both the GATES access method interfaces and the GAIN application logiccan make calls to the GATES security callable services. These services useeither internal tables or call the SAF interface to process an authorisation/access validation request.

At the connection level the AMIs of the GAIN address space restrict accessto:

• A range of IP addresses

• An IP network or sub-network

• An SNA LU and network mask

Where a protocol is well defined e.g. telnet, the applicable port can beconfigured for AMI based user authentication and access control. In thissituation the GAIN application code only becomes aware of a connection

Fig. 6. Protecting downstream applications from “hackers”

SNA network

SNA network

TCP/IP network

Operating System ServicesOS Services

UNIX

Win NT

GAIN GATES application

Logic


GAIN address spaceSNAappl

SAFinterface

logon security

Connection security

SNA network

SNA network

TCP/IP network

Operating System ServicesOS Services

UNIX

Win NT

GAIN GATES application

Logic


GAIN address spaceSNAappl

SAFinterface

logon security

Connection security

9

General Information

X

T

after both access control and user authentication have been completed.Where user ids are embedded in undetermined datastreams, the GAIN logonexit can be used to interface with SAF services for the purposes of userauthentication.

Improving Business Application Availability

The end-user perceived availability of mainframe applications can beimproved through the use of GAIN or GATES solutions. While GAIN/GATESavailability is maximised through the replication of key processes. Multiplecopies of GAIN/GATES can be run in the same sysplex or on unrelatedsystems so as to improve the networked availability of the remote application.

In Figure 7, “Using GAIN to establish a high availability environment” IPconnections are replicated across multiple systems, which is achieved bybinding to the same port on each system, possibly even to a specificmainframe TCP/IP network address. The local DNS (domain name system) isthen used to distribute connections evenly across the systems.

In a similar manner, if a single host is multi-homed i.e. has more than one IPaddress, then GAIN/GATES can bind separately to each IP address providingalternate access paths for access from different IP networks. With carefulplanning this approach can provide upstream applications with resilience torouter failures in the IP network.

In the case of an APPC client, each APPC process is defined to acceptconnections on the same generic name. When correctly configured VTAMthen distributes connections across each of these processes.

When a GATES solution is used to provide network support for a standaloneapplication, then these techniques assist in providing a high availabilityplatform for that applications use.

Fig. 7. Using GAIN to establish a high availability environment

UNI

Win NSNAnetwork

TCP/IPnetwork





SNAnetwork


CICS IMS

SNAnetwork

TCP/IPnetwork





10


Adding Value to Business Application Data

In this scenario, distributed systems using multiple protocols need to inter-operate in order to provide end-users with transparent access to consolidatedinformation from multiple remote systems.

To achieve this we build upon the earlier examples. In this case however, asingle inbound transaction request results in a variable number of requests toone or more local and remote transaction processing systems. Data isextracted from the associated responses, re-formatted and returned to therequest originator. GAIN (through GATES) provides access to IBM’sREstructured eXtended eXecutor (REXX) in order to allow this customscripting of the necessary requests and consolidation of the responses.

The REXX language is generally acknowledged to be amongst the best forparsing unspecified data streams. The powerful REXX data manipulationcapabilities are available to custom GATES/GAIN applications and can beused to add value to received data. Through REXX’s flexibility, GAIN appli-cation scripts can be rapidly developed to process transactions and extractinformation from the remote system’s responses. Further more a package ofGAIN oriented REXX functions provides an efficient interface between REXXand the GAIN assembler based routines. This means that procedures writtenin REXX can have almost identical functionality to those written in assembler.

In Figure 8, “REXX scripted transactions for Web browser presentation” we

see a REXX application acting as a simple web server by converting HTMLFORMs input to one or more transaction requests. The transaction data iscollected over an APPC interface and the response is returned to the webbrowser in HTML format. This provides web oriented CGI processing in atraditional MVS and REXX environment

In this scenario, The TCP/IP AMI converts received streams data from the IPnetwork into HTTP GET requests. The first HTTP GET will download anHTML page containing a form which then defines the transaction to beexecuted.

Fig. 8. REXX scripted transactions for Web browser presentation

SNA network

SNA network

TCP/IP network


UNIX web client

Win NT web client

Business application providing information via

APPC conversationAccess Method Interfaces

REXX based scriptingApplication Logic

GAIN address space

SNA network

SNA network

TCP/IP network


UNIX web client

Win NT web client

Business application providing information via

APPC conversationAccess Method Interfaces

REXX based scriptingApplication Logic

GAIN address space

11

General Information

The REXX application which in this case is a simple web server extracts infor-mation from the HTML form and constructs an LU6.2 transaction request.Additional information in the HTML form may allow the application todetermine unique routing requirements for the request or these may beestablished through GAIN configuration.

The SNA APPC AMI will then if necessary negotiate LU6.2 sessions betweenitself and the target server system (more normally this will have beencompleted as part of GATES initialisation). Once a session is available anAPPC conversation will be initiated and the transaction request will beprocessed as a CICS or IMS transaction.

When a transaction response is returned then this data is HTML formattedand enveloped in an HTTP header before being converted to ascii and sentacross the IP network to the web browser originating the request.

Internal Monitoring and Automated or Assisted Operation

Having added value to business application data through the use of REXXscripts we can find further use for REXX in the management of the GAINaddress space. GAIN based REXX procedures can be scheduled at regularintervals for the purpose of monitoring the GAIN environment. REXX proce-dures, through the provided REXX function package, have access to nearlyall of the GAIN control block storage. Access is via field name and istherefore release independent.

Access to control block storage means that custom commands can bedeveloped to display information applicable to the active environment. It alsomeans that connections can be monitored from within the address space.Alert type messages can be written to the system operator or via othercustom processes delivered to other operating systems as illustrated inFigure 9, “GAIN custom management” .

Fig. 9. GAIN custom management

TCP/IP network

TCP/IP network


Application under test

System ManagementProduct

REXX alertApplication Logic

GAIN address space

Access Method Interface

REXX monitorApplication Logic

TCP/IP network

TCP/IP network



System ManagementProduct

REXX alertApplication Logic

GAIN address space


REXX monitorApplication Logic

12


Business Application Testing

The simplicity of REXX based scripting coupled with GAINs flexibility fornetwork connectivity makes it an ideal application tester. Therefore onceGAIN has been installed you also have a business application testenvironment as well. When errors are detected during testing the standardtrace facilities can provide invaluable information with regard to the problem.

Storing scripts means that regression testing can be assigned to less skilledpersonnel that can then work from a testing ‘run book’. The ability to supportmultiple protocols means that the application under test can be locatedalmost anywhere.

In Figure 10, “Application testing using REXX scripts” the REXX script can

make one or more connections, send multiple datastreams or transactionsover each of these connections and then validate orderly disconnection. Anyerrors or deviations from expected responses can be detected and logged.

Fig. 10. Application testing using REXX scripts

SNAnetwork

SNAnetwork

TCP/IPnetwork

TCP/IPnetwork




Your choice of networkprotocol


REXX testing scriptsApplication Logic

GATES address space


13

General Information

GAIN Components and Feature ListAs a member of the GATES family of program products and customerspecific solutions GAIN includes GATES base code along with APPC andTCP/IP support. The GATES code provides general application support andnetwork access, GAIN provides the unique logic for intelligently linking APPCand TCP applications. In architecture terms, GAIN is considered an appli-cation of GATES. When this manual makes references to GAIN it automati-cally includes GATES. The advantage of building GAIN on top of the GATESfoundation code is that GATES features for high performance and systemmanagement are all immediately inherited by GAIN. See the section “GATESSupport for GAIN” on page 21 for a description of the common GATESfeatures inherited by GAIN.

GAIN Components

Another way of viewing the GAIN GATES relationship is by reviewing thecomponents that make up the GAIN product, these are:

• GATES base code

• GATES TCP/IP support

• GATES APPC support

• GAIN application logic

• GAIN configuration builder

• GAIN Management

The following sections provide more detail on the individual GAIN compo-nents.

GAIN Configuration Builder

The GATES base code provides a rich set of general purpose configurationcommands. To simplify the construction of complex GAIN environmentsadditional GAIN specific configuration commands have been developed.These commands supplement those of GATES and better describe the GAINenvironment. Special purpose TCP and APPC commands define thenetwork, services available on partner systems and the inter-connection ofdifferent systems. These commands are used by the GAIN configurator toissue GATES CLUSTER, PAB and GROUP commands and to initialise thegenerated control blocks with GAIN specific parameter information.

More information about the GAIN configuration builder is available in “SampleGAIN Configuration” on page 26.

GAIN Management

GAIN introduces a number of additional resource display commands sepcifi-cally oriented to the display of resources related by the needs of the GAINconfiguration. These are the LIST SERVICES and LIST REMOTEScommands.

14

GAIN Components and Feature List

GAIN Application Logic

The GAIN application provides the glue between the two GATES providedAMIs (the GATES APPC and TCP support code). GAIN ensures data fromTCP connections on the one side are routed to APPC connections on theother and vice versa. When the data being processed is identified as a trans-

action then GAIN provides additional value by removing any fixed linkbetween the network components and thereby allows parallel processes tocompete for transaction processing.

In Figure 11, “Example GAIN data flow” we see that data arriving on a TCPconnection is passed by the TCP AMI to the GAIN logic. This logic deter-mines whether sufficient data has been collected to form a complete trans-action and then routes and queues the transaction request for processing bythe partner APPC AMI. The APPC transaction manager ensures that allAPPC processes are kept active and the queued transaction is processed asa unit of work associated with a configuration or exit defined connection.When a transaction response is received the GAIN logic ensures that thedata is returned to the originating system.

In a similar manner transactions received on the APPC AMI can be routed tothe TCP AMI and a configuration defined connection.

GAIN transaction and Message SupportGAIN supports both asynchronous and synchronous transactions. Figure 12,“Transaction Support” illustrates this and how an outbound asynchronoustransaction is supported through the use of an acknowledgement exit. Notethat the TCP and SNA networks can be inter-changed in the diagram.

Messaging involves the sending of data to the remote destination withoutregard to transaction state, as data arrives it is sent on to the appropriatedestination. In this situation full duplex TCP data flows are mapped to halfduplex APPC flows in one of two ways. The simplest method involves estab-

Fig. 11. Example GAIN data flow

TCP/IPnetwork

SNAnetwork


GATES address space

GAIN application logic

SNAAMI

TCPAMI

15

General Information

lishing two uni-directional (simplex) data pipes between GAIN and the remoteapplication. Data is sent on one pipe and received on the other, as such nohalf duplex change direction protocol is required. The other option is to builda custom GAIN application segment using either REXX or assembler. Thisapplication then takes responsibility for supporting APPC half duplex directionchanges in a custom defined manner.

TCP Client, Server and Peer Networking Support

Any basic connectivity support to TCP based applications requires consider-ation of the following points:

• Access Controls

• The application datastream and how to determine a record

• The application role and expected data flows

• Acknowledgement processing

The following sections provide more information on these points.

TCP Access Controls

The TCP AMI uses the standard Access Lists to define who may or who maynot access the system. Access lists are defined on a per listener/port basisand can be established as one or more ranges of IP addresses and/or IP sub-networks.

While the AMI must accept a socket connection in order to determine theoriginators IP address, the application logic is unaware of the connection

Fig. 12. Transaction Support

TCP/IP network

TCP/IP network

GAIN address space

SNA network

Inbound synchronous transaction

outbound synchronous transaction

SNA network

outbound asynchronous transaction

Inbound asynchronous transaction

Acknowledgementexit

TCP/IP network

TCP/IP network

GAIN address space

SNA network

Inbound synchronous transaction

outbound synchronous transaction

SNA network

outbound asynchronous transaction

Inbound asynchronous transaction

Acknowledgementexit

16


attempt if the address is excluded via the access list. The AMI simply closesthe connection without ever notifying the application.

TCP Application datastreams

TCP applications self-define the protocol they use for communication, whichmeans that the data flowing between any two TCP applications can beunique to that application pair. For programmers working in the IBM SNAarena the idea of a datastream containing a length field in character decimalat offset 19 into the message is quite strange but this approach is notuncommon in ad-hoc programs between unix systems. This absence of afixed structure means that the TCP protocol is unable to recognise the recordstructure common to IBM mainframes. TCP is said to stream the data. TheTCP application, the TCP API implementation and the IP network deliveringthe data can all change the size of a particular data stream. This means thatreceived data may contain a fraction of a record or multiple records plus afinal fraction. Again, each TCP application must code for these eventualities.

GAIN approaches this problem of limited conformity by supplying multiplesegmentation routines, each of which specialise in building a record orientedstructure into the data received from a remote TCP application. Theseroutines are defined by the datastream they support and are as follows:

Character delimited

Here a received datastream contains a pre-defined character sequence delimiting logical records. Support is for any sequence of up to five characters, the most common however being the carriage return and line feed combination CRLF.

This datastream is in use by many TCP applications including some of those defined by rfc’s such as telnet and HTTP these particular examples can also be han-dled through more specialised routines, see below.

Lengthdelimited

This is where the received data contains a length field. The length field may be at any fixed offset into the datastream and may be in binary or character ascii or ebcdic format.

This datastream is most commonly used in program to program communications. These datastreams are proc-essed from configuration options and without the need for user written exits.

Telnet encoded This is a specialised version of the character delimited protocol described above and allows GAIN to handle interactions with human end-users. The additional sup-port for telnet includes network virtual terminal negotia-tion and optional data editing for the removal of back spaces etc.

HTTP encoded This again is a specialised version of the character delimited protocol. The HTTP support analyses HTTP headers so that an entire HTML page or XML document can be provided to the application as a single message rather than each line, as would be the case with stand-ard character delimited CRLF support.

This datastream is used for transporting HTML for web browsers and servers as well as XML and SOAP struc-tures for web services.

17

General Information

Protocols not fitting into any of the above categories such as variable offsetlength delimiting fields can be supported through the use of a user codedsegmentation routine.

In addition to performing streams to record mode conversion GATES canprovide for automatic ascii - ebcdic translation via customisable translatetables. The above routines can also translate partial streams inbound andoutbound. Some routines support SAF or user defined authentication as partof automated logon processing.

TCP Application Role and Data Flows

The full duplex TCP protocols do not require specific management. The TCPapplication can be a client connection, a server connection or a peerconnection. Peer connections may requires some additional customisation orscripting to determine the purpose of received data and to forward this to thepartner application. TCP hosts defined as remote servers can take advantageof GAIN’s transaction management services with incomplete transactionsbeing cleared after a user defined timeout interval.

TCP Acknowledgement processing

On receipt of data from a TCP host, custom TCP application acknowledge-ments can be made from the GAIN data receipt exit for local “spoofing” ofacknowledgements or from the GAIN acknowledgement exit for end to endacknowledgement.

APPC Client, Server and Peer Networking Support

Any basic connectivity support to APPC based applications requires consid-eration of the following points:

• Access Controls

• The application role and expected data flows

• Acknowledgement processing

The following sections provide more information on these points.

APPC Access Controls

The APPC AMI uses the standard Access Lists to define who may or whomay not access the system. Access lists are defined on a per listener basisand can be established as one or more LU name and/or network namemasks.

The AMI is unable to prevent VTAM managing the ISTSVMGR sessionbetween a GAIN LU and a remote SNA application but rejects all the conver-sation capable session requests. The application logic is unaware of theconnection attempt if the LU is excluded via the access list. The AMI simplyrejects the connection without ever notifying the application.

BER encoded Supports incoming data coded to the Basic Encoding Rules defined for Abstract Syntax Notation 1.

This datastream is used for program to program commu-nications.

18


APPC Application Role and Data Flows

APPC transaction program protocols are well defined. GAIN uses the termsynchronous if a response is expected and asynchronous if not (This is thesame terminology as used by IMS). Data flows for most situations in this caseare already parameterised within GAIN.

When APPC pipes are used for transferring data between two applications,no protocols are required except for potential acknowledgement processingwhich is parameterised within GAIN.

When an existing APPC application with a unique half duplex flow controlalgorithm is to connect to GAIN then a custom script is required to managethe data flows.

APPC Acknowledgement Processing

APPC protocols define a CONFIRM level of acknowledgement for confirmingdata receipt. GAIN permits these acknowledgements to be returned immedi-ately in order to maximise throughput or to be returned after successful trans-mission to a partner application for higher data integrity when this is notsupported at the application level.

SyncPoint protocol is only possible through a custom solution, this is becausethe TCP protocols do not define SyncPoints in the datastream so GAIN hasno way of determining the required protocol.

SecurityAccess lists define the APPC and IP addresses able to connect to a GAINsystem. These lists are defined are defined globally and then applied (viacross reference) to specific access points such as a TCP listen port.

In cases where a given protocol allows a user-id to be readily determined,then GAIN is able to interface to internal or SAF based logon security. If theuser-id can be programmatically extracted then the GAIN logon interface exitallows for simplified user validation.

Flexibility (configuration and REXX)The GAIN environment is defined via configuration parameters. This meansany use of flexibility and throughput

ManageabilityGAIN takes advantage of the extensive management facilities available in aGATES environment. This includes:

• Specialised journal and error logging

• Resource listing and status display commands

• Detailed tracing capabilities

Access to these management facilities is through the sysplex compliant MVSoperator interface or through terminal access to the console facility. Theconsole facility will support linemode telnet or web browser access.

19

General Information

See “Sample GAIN Logs and Displays” on page 32 for examples of GAIN’smanagement output.

AvailabilityGAIN uses usr defined redundant processes and duplication within a sysplexenvironment to maintain the highest availability possible. Advanced sysplexand access method facilities such as VTAM generic name support andTCPIPs dynamic VIPA allow redundancy across images of an MVS sysplex.

ScalabilityScalability is provided through cloning of processes within a cluster or byreplicating entire GAIN environments across multiple MVS images within thesysplex. VTAM’s generic name support can be used to distribute APPC loadacross multiple MVS images and TCPIPs connection optimisation can beused to distribute the TCP workload in a similar manner.

Performance

GAIN uses the highest performing assembler interfaces to the operatingsystem and its access methods. MVS’s SRB mode is used wherever possibleand a user defined multi-processing mix can be used to ensure that allGAIN’s MVS tasks and processes can run simultaneously (on a multi-enginedCPU) when throughput and response time are a premium.

20

GATES Support for GAIN


This section is a general topic disrobing the GATES structure and how theGAIN product is implemented on top of the GATES base code.

What is GATES ?

GATES is a versatile application architecture for the IBM OS/390 and z/OSmainframe environments. The architecture is implemented as a base codeset with extensions for interfacing to TCP/IP and SNA network protocols.Interfaces to logic component code allows for the implementation of variousapplications.

Typically GATES is used to build or support applications with a high commu-nications content and the GATES acronym loosely stands for its objective toprovide Generalised (device independent) Access for Transaction basedEnterprise Systems. GATES is of course bi-directional and can equally wellprovide client services for access to external servers.

GATES has a base code set associated with it, however it is not a product byitself. Instead GATES is used to build products and to assist in the devel-opment of bespoke software, known as a ‘custom solution’ and which solvesindividual customer problems.

What is GAIN in this context ?GATES APPC IP Networking or GAIN is a program product implemented ontop of the GATES architecture base code. As a program product GAIN isready for use as soon as it is unloaded from the distribution tape.

GAIN provides access between TCP applications on an IP network and SNAAPPC based transaction processing systems on the IBM mainframe or othersystem located in the SNA network.

GAIN adds product specific code to the base code set provided by GATES.This code adds the logic required to link the IP and APPC networks in astandardised manner. GAIN also exploits many of the other features providedby the GATES environment. In GATES architecture terms, GAIN is known asa GATES application.

The self defining product environment means that GAIN is also able tosimplify configuration requirements when compared with more generalGATES applications.

21

General Information

What are Custom Solutions ?A custom solution is a unique extension to the GATES base code to resolve aspecific problem for one of our customers. The base code will normally besupplemented by one or more of the supported network protocols, asrequired.

The custom solution may represent only a minor change to an existingproduct or may be a completely new GATES development. Whatever thesituation the tried and tested GATES base code provides an immediateadvantage in the resolution of a networking problem.

After on site consultations development of the solution may be completed onthe customer site or at our own location with final acceptance at the customersite.

If GAIN cannot meet your requirements out of the box then it can be modifiedas part of a custom solution. This could mean coding of GAIN user exits onyour behalf or re-use of some of the GAIN code when developing a newsolution tailored to your environment.

GATES Base Code Features

A GATES system, that is to say GAIN or a GATES custom solution, isimmediately provided with services common to the needs of all applications,these include an efficient, scalable multi-tasking environment which handles:

• Common Initialisation and Termination processing.

Initialisation uses the GATES command set in the form of a configura-tion file that allows the many different GATES environments to be cre-ated without user programming. GATES products such as GAINextend this command set to further simply configuration.

• Command processing

Commands enter a GATES system from multiple sources, includingtelnet and web browser clients as well as a sysplex compliant operatorinterface. Responses are returned to the requester whether they be ata console or connected through a supported network.

• Security.

A simple fixed connection establishment protocol ensures that busi-ness logic can define/refine who has access to the GATES system.Operators can be assigned a command authority through user ids orterminal/console ids and a callable SAF interface allows for integrationinto the enterprise security environment.

• Logging.

Multi-output and duplicated logging allows important messages to behighlighted in separate logs, or even written to the system operator.These messages are also written to the journal logs along with infor-mation about connections and communications errors. Business appli-cations use the logs and callable log services as required.

• Tracing.

Multi-stage tracing, on a per process or per connection basis, allowsfor key diagnostic information to be captured while minimising theimpact to the total GATES system.

22


• Timer services.

Housekeeping activities can be easily managed through the use ofdirect calls to these routines at configuration defined intervals. Thesesame routines can then drive additional automated procedures forinformation gathering or resource recovery.

• Integrated REXX support.

IBM’s REstructured eXtended eXecutor (REXX) is tightly integratedwith the GATES system to provide truly flexible application processingcapabilities. At a small performance impact, the built-in REXX functionsof GATES when combined with REXX’s excellent parsing capabilitiescan dramatically affect application development time.

• Integrated recovery.

GATES recovery logic is implemented through operating systemESTAE and FRR routines. GATES recovery logic can also collect diag-nostic information and minimise the impact of a failure while attemptingrecovery of a failing resource.

• Optional high performance Unix system services TCP/IP support.

A part of the GAIN product or installed as required for custom solu-tions, GATES extended TCP/IP support provides immediate accessacross a variety of network protocols.

• Optional high performance APPC support.

Like TCP/IP support, APPC is part of the GAIN product or installed asrequired for custom solutions. GATES APPC support provides immedi-ate access to a variety of SNA transaction programs with extendedAPPC support providing simplified access to transaction processingsystems such as CICS and IMS.

• Transaction management.

Is used by APPC support and internal command processes but can beused anywhere through the available callable interface. Transactionmanagement provides flow control and capacity management facilitiesto any GATES application.

• Performance and Statistics gathering.

Statistics on connections, transactions and I/O volumes are maintainedby the GATES system. Displays on buffer pools other resources can bemanaged through automated procedures.

• Miscellaneous callable service and macro routines.

Many common routines used by any application have been included aseither macros or callable services to further reduce development work-load on custom solutions.

The above structures typically consume a major proportion of a project’sdevelopment budget, however by using GATES, applications have access tothis tried and tested re-usable code without the associated cost of devel-opment. This means that GATES custom solutions can be constructed in afraction of the time taken for a normal application project.

In the case of our own GATES based products, our customers benefit fromgreater product resilience through the re-use of base component code usedby other products and custom solutions.

23

General Information

GATES Design Objectives

The GATES base code and the selectable AMIs provide a scalable, secure,manageable and reliable infrastructure for application development whilemaintaining the flexibility required to meet today’s and tomorrow’s demandingapplication and communications requirements.

Any GATES based application has the immediate advantage of the featuresinherent in any GATES system e.g.

• External communications support through selectable mainframeaccess methods. This support includes additional functionality orientedtoward (but not restricted to) transaction type protocols.

• Simple consistent interfaces for business logic written in Assembler,REXX or soon to be available High-Level language callable interfaces.The application code can with no or only minor modification communi-cate over any of the available access methods supported.

• Before one line of business logic code has been written each GATESbased application starts with full initialisation and termination routines,optional simplified access to TCPIP or VTAM, logging, tracing andmany other callable services.

These features have a common underlying theme. That theme is the GATESdesign objectives based on the classic values of reliability, scalability andmanageability. These objectives and the approaches to meeting them aredescribed below:

Rapid and Flexible Solution Development

• Solves customer problems quickly

• Low cost compared to other solutions

• GATES use of selectable access method interface modules givesimmediate access to a wide range of network and device protocols.

• Low volume applications can be written in REXX and use the REXXAPP to AMI interface for all communications.

Productivity:

• AMI removes need to understand API complexities. Gives immediateaccess to supported APIs.

• AMI is 100% re-used code reducing cost of development and potentialfor bug content.

• APP works with small procedures to handle a specific GATES event.

• APP uses a common interface for all AMIs.

Application Value Adds:

• Transaction management system controls transaction scheduling, pro-vides reports and can notify on busy conditions.

• SAF interfaces for additional connection security.

• REXX function packages integrate REXX and assembler.

Management:

• Double logging of serious system errors to a separate error logensures these errors are not overlooked.

24


• Standard logging of all communications activity allows for auditing andmore detailed problem analysis.

• Multiple level tracing on a process or connection basis allows for sim-ple problem diagnosis of errors in the network or business logic appli-cation.

• Displays of all clusters, processes, connections and storage pools arestandard.

• Customisable displays. GATES REXX automation has access to everyassembler field used by processes and connections.

Security:

• Application and configuration can jointly apply connection restrictions.

• Callable SAF interfaces for integration with enterprise security man-agement.

• Additional security by MCS console id (SDSF and NetView use the cur-rently logged on user's id when allocating an MCS console).

Efficiency:

• Selectable API/AMI, pick the best API for the job.

• All core routines written in assembler.

• SRB mode used whenever desirable/possible.

• Efficient program linkage and work area allocations including dynamicsupport for SRB routines and other task based system exits.

• Reduced calls to dispatcher (branch entries used for AMI to APP andAPP to APP communications, subject only to constraints of the APIused).

• Storage management, predictive storage use allows allocation frommain task. Careful use of subpools takes advantage of VSM efficiencyof operating system.

Reliability:

• FRRs clean up connections should errors occur.

• ESTAEs clean up processes/tasks should errors occur. Allow for retriesup to a user defined limit.

• Diagnostics are always captured to ensure permanent problems canbe resolved rapidly.

25

General Information

Sample GAIN Configuration

The GAIN configuration file or files are a series of GAIN and GATEScommands held in member(s) of the UNPARM dataset. To illustrate thesimplicity of system definition and the huge flexibility of GAIN systems somesample configurations have been included below. These configurations arebased upon the transfer of data between a telnet client and IMS as illustratedbelow:

Essential configuration parameters for all systems

Configuration items common to multiple systems can be placed in a separatemember of the UNPARM parameter dataset. Initialisation supports multiplecommand files allowing members to be grouped as required. The systemcommand is normally the first configuration command and since it contains areference to the cpu dependent authorisation key one option is to hold this ina short configuration member acting as a prefix to other configurationmembers. The alternative is to specify multiple SYSTEM commands, eachwith the CPU_ID parameter on the system parameter. Only the SYSTEMcommand with the active CPU id matching the CPU_ID parameter is used, allother SYSTEM commands with the CPU_ID parameter are then ignored.

A typical first member to be read is as follows:

SNA network

SNA network

TCP/IP network

Operating System ServicesOperating System

Services

UNIX

Win NT




IMSPAPPC/MVS

GAIN defines listens on ports 2043 and 2044

APPC/MVS uses LU

SVRLU001

GAIN defines CLNLU001 and 2 to connect with

SVRLU001

GATES base code interfaces between

GAIN and the SNA and TCPIP access methods

Program using BER/ ASN.1 datastream

TELNET client

SNA network

SNA network

TCP/IP network

Operating System ServicesOperating System

Services

UNIX

Win NT




IMSPAPPC/MVS

GAIN defines listens on ports 2043 and 2044

APPC/MVS uses LU

SVRLU001

GAIN defines CLNLU001 and 2 to connect with

SVRLU001

GATES base code interfaces between

GAIN and the SNA and TCPIP access methods

Program using BER/ ASN.1 datastream

TELNET client

26


*********************************************** * Initialisation parameters * *********************************************** SYSTEM ID(TEST),MODE(TEST), KEY('4E4A4848210416DA66BD9920'), SYSACB(GAIN), PRODUCT(GAIN) POOL ID(IBUF), MAXDATA(4K) POOL ID(VBUF), MAXDATA(32K) SYSLOG DDNAME(SYSPRINT), AMI(QSAM),RECLEN(84)

The early initialisation process establishes a common GATES environment,hence one of the first requirements is to identify the GAIN product and this isspecified on the SYSTEM command’s PRODUCT parameter.

In the above example the SYSTEM command also specifies:

One or more POOL commands are used to define characteristics of theGATES/GAIN storage pools. In this example, we see an override to thestandard I/O and Variable Length buffer pool definitions.

The SYSLOG command defines where GATES journal logging is to beperformed and characteristics of the log dataset.

Access Controls

The first GAIN specific configuration action is normally to define the IP andSNA connections permitted with the local system.

ACCESS ID(UNICORN),ALLOW, IPADDR_RANGE(127.0.0.1,127.0.0.1), IPADDR_MASK(213.121.240.32,255.255.255.224) ACCESS ID(SNA_TEST),ALLOW, SNA_LU_MASK(*.CLNLU*)

The above examples illustrate the IP address range and IP address maskoptions for defining connections to be allowed or denied. The SNA LU maskallows both a network id and an LU name to be specified using the traditionalwildcard format available for names.

ID identifies the name of the GATES/GAIN system being started.

KEY The authorisation key for use of the software on the current CPU.

SYSACB Identifies a system ACB used by GATES/GAIN to determine the VTAM operating level prior to initialisation of other VTAM AMIs.

27

General Information

User Controls

Users are defined globally in a similar manner to the access controls definedabove. Applications such as custom GAIN controls can then use these userdefinitions as required. For example the general GATES systemmanagement access, described below, uses the user definitions as a list ofauthorised users.

************************************************** Define users and their authority levels ************************************************** USR NAME('OPER1,OPER2'), AUTH_LVL(200)

In the example shown, users OPER1 and OPER2 are given an authority levelof 200. When logged on to the management access interface, this means thatthese operators will be permitted to execute commands with an executionauthorisation level at or below 200.

Management Access

Management access to a system is provided through a system consoleinterface process. This process and the ports on which it is to listen is definedthrough the specialised SYSCNSL command illustrated below.

************************************************** Define system management access ************************************************** SYSCNSL HTTP(2180), TELNET(2123)

In the example above, web browser access is provided through port 2180and linemode telnet access through port 2123.

An example APPC Service

A GAIN service is a definition of a service provided on a remote system. Thisservice will then form the target of GAIN client connections.

The configuration structure is always cluster, remote system and transaction.Where multiple transactions can be run on a single remote and multipleremotes can be accessed across a single cluster.

These extracts from a configuration file illustrate the definitions used forplacing data onto an IMS queue using IMS asynchronous transaction logic.That is to say no response is expected to the input transaction.

Defining the APPC Cluster

The APPC cluster is defined by the APPC.CLU command, a typical exampleof which follows:

********************************************************* The following APPC.CLU (CLUSTER) command defines a ** two process (PAB) environment. Each process will ** open its own ACB named CLNLU001 and CLNLU002 respec- ** tively. VTAM will distribute inbound connections for *

28


* the generic resource GAIN across these two ACBs. ********************************************************* APPC.CLU ID(APPC),NUMPABS(2), ACB_NAME('CLNLU*,1'), GNAME(GAIN)

Note that only a single cluster definition is required to support multipleinbound and outbound connections. Additional clusters might be used tosupport multiple ACBs, provide a degree of queuing independence and/or toallow more complex routing options to be selected.

Defining the Remote APPC System

The remote APPC system is defined through the use of the APPC.RMTcommand, an example of which follows:

********************************************************* The following APPC.RMT (REMOTE LU) command defines a ** remote LU (SVRLU001). Each process in APPC cluster ** IMSP will establish four parallel sessions with the ** remote LU. ********************************************************* APPC.RMT ID(IMSP), RMT_TYPE(IMS), LU(SVRLU001), MAX_SESS(4), CLU_ID(APPC)

This example combined with the cluster definition illustrates two processeseach supporting four parallel sessions with the IMS system accessed viaremote LU SVRLU001. The GAIN Installation Guide provides additional infor-mation about the VTAM definitions that should be used for client and serverso as to allow GAIN to correctly negotiate the selected number of sessions.

Defining the Remote Transaction

Transactions available for execution on the remote system are defined usingthe APPC.SVC command as illustrated below:

********************************************************* The following APPC.SVC command defines the APPC ** transaction program that can be run at the remote ** location defined above. Since the target is IMS ** we use a QNAME parameter rather than the more ** general TPN parameter. ********************************************************* APPC.SVC ID(IMS1),QNAME(TEST01), SVC_TYPE(ASY),MAX_TRAN(100), RMT_ID(IMSP)

Using the examples above, up to 100 transactions for IMS queue TEST01can be queued. After this value is exceeded a service busy response isreturned to all requesters. The 100 transactions will be processed asindividual APPC conversations over any one of the 8 sessions defined to theremote system.

Transaction program names can be supplied through a GAIN exit allowing asingle APPC.SVC command to be used for all transactions. A single

29

General Information

APPC.SVC command can also be used when the transaction name isignored by the receiving system.

An example TCP Client

A GAIN client is a definition of an access point to be routed to a remoteservice. In the case of TCP clients protocol definitions are also required toallow streams to record mapping and to take advantage of system providedservices.

The configuration structure is always cluster and access point. As withservices many access points can be associated with a single cluster.

These extracts from a configuration file illustrate the definitions used to allowtelnet clients and a programmed BER encoded datastream client to accessGAIN and be routed to the APPC service for IMS defined earlier.

Defining the TCP cluster

The TCP cluster is defined similarly to the APPC cluster, through the use (thistime) of a TCP.CLU command.

********************************************************* The following TCP.CLU (CLUSTER) command defines a 2 ** process (PAB) environment. Inbound connections are ** split across the two processes. ********************************************************* TCP.CLU ID(TCP),NUMPABS(2)

Inbound and outbound connections will be split across the availableprocesses within the cluster. The TCP.CLN commands that follow will ifnecessary cause the activation of a separate listening process. This processwill ‘give’ connecting sockets alternately to each process in the cluster.

Defining TCP clients

Individual client access points are defined through use of the TCP.CLNcommand, examples of which follow:

********************************************************* The following TCP.CLN command defines a TELNET ** client that connects via port 2043. Logon processing ** will be handled by GAIN along with NVT negotiation, ** the writing of an input prompt and detection of a ** logoff string. Input data are treated as transactions** and routed to the APPC.SVR with ID(IMS2). ********************************************************* TCP.CLN ID(TLN),PORT(2043),CLU_ID(TCP), PROTOCOL(TELNET), PROMPT(AMI),NVTNEG(AMI),LOGOFF(AMI), LOGON(AMI,SAF), ROUTE(IMS2), ACC_ID(LOCAL)

This first example is for a line mode telnet connection available through port2043. The available options select whether the target application or GAIN isto provide various key facilities for the connection. This first command willcause activation of a separate listening process and then generate a listen on

30


port 2043. All connections established via this port will inherit the connectionattributes of the client definition.

********************************************************* The following TCP.CLN command defines a connection ** using a BER encoded datastream. Logon processing is ** handled through a user provided exit routine. ********************************************************* TCP.CLN ID(UNB),PORT(2042),CLU_ID(TCP), PROTOCOL(BER),RDLM(60), LOGON('APP,UNBTLGN'), ROUTE(IMS2)

Subsequent TCP.CLN commands define alternative ports to be listened onand the datastream associated with sockets connected over these ports. Allconnections can share common clusters irrespective of connection attributes.

31

General Information

Sample GAIN Logs and Displays

To illustrate the management capability of the GATES system various samplelog and display outputs have been provided. The purpose of these is to illus-trate the care taken to present the needed information while keeping logsboth clear and concise.

These illustrations are based on combining each of the earlier configurationfiles through the INITMEM() parameter of the job or started task, i.e. GATESmight have been started as follows:

//*******************************************//* Standard job to run GATES *//*******************************************//GATES PROC INIT=,DSPFX='UN.V1R2' //GATES EXEC PGM=UNA,PARM=('INITMEM(&INIT)') //STEPLIB DD DISP=SHR,DSN=&DSPFX..SUNLINK //SYSPARM DD DISP=SHR,DSN=&DSPFX..UNPARM //SYSEXEC DD DISP=SHR,DSN=&DSPFX..SUNEXEC // DD DISP=SHR,DSN=&DSPFX..APPEXEC //SYSPRINT DD SYSOUT=* //SYSERROR DD SYSOUT=* //SYSTRACE DD SYSOUT=*,BLKSIZE=5280 //SYSREXX DD SYSOUT=* // PEND //TEST EXEC GATES,INIT='SYSTEM,TEST1,TEST2'

Operating System Output

On running the above JCL as a job or started task, the system operator wouldsee the following messages on the system console:

The point to note is that system level messages are kept to a minimum. Amessage to inform the operator that the GATES start command has beenaccepted or the job has been submitted. A message to indicate that the basicproduct is active and in which mode and normally a final message showingthat GAIN has activated everything that was successfully defined.

In the example above we see message AIN404E was also issued. Defaultrouting for E messages is to display them on all available logs and to theoperator. In this case operations are being advised to check the GAIN logs forinitialisation errors which may have prevented resources being defined andactivated.

Journal Logging

This is the largest of the GATES logs, it is designed to hold all system leveland connection level information. Note that in the following extracts the times-tamps have been removed, GATES records time to an accuracy of 1/1000thof a second on all log entries.

Initialisation, Journal Log Extract

The following messages are typical of those first appearing in the journal log:

UNB025I GATES is initialising AIN403I GAIN is enabled in a GATES EVALUATION mode environment AIN404E GAIN configuration errors were detected during initialisUNB029I GAIN all defined PABs now active/connected

32


The journal log sequence shown above illustrates initial processing of a firstconfiguration file, which must contain the SYSTEM command and KEYparameter. First the operating system environment is validated and listed,then each GAIN component ensures that the supplied authorisation key isvalid indicating this with an enabled message.

Initialisation continues with the processing of configuration files. Commandssuch as SYSTEM, POOL and SYSLOG must by their nature be processedprior to logging activation. This is done as a first pass of the configurationfiles. Any errors with these commands are reported on the second passwhich is also used to process all other commands. The journal log thereforetypically contains entries like the following:

To aid log analysis, the text of solicited response messages are indented. Inthe example above the messages are the result of an internally issued EXECcommand for each of the initialisation members. The EXEC command simplyschedules each command entered within the selected file, it does not wait fortheir invocation.

TCP Cluster Activation, Journal Log Extract

This edited journal log extract shows a minimal cluster, consisting of a singleprocess (PAB), being activated, after which a TCP.CLN command is issuedwhich causes the listener process to be activated and a listen issued.:

UNB020I Journal log active on Sun, 07 July 2002 UNB027I GAIN system TEST is starting on MVS system SYS1 UNB070I HW configuration, CPU xx6666 model id 7490 UNB071I SW configuration, MVS OS/390 version 2.10.0 UNB072I CVTOSLVL: X'FFFFFF80A00000000000000000000000' AIN403I GAIN is enabled in a GATES EVALUATION mode environment UNT481I TCP AMI is enabled on host UNCN0001, IPaddr 219.12.140.144UNA481I APPC AMI is enabled on SSCP UNCN0001, SNA network UNCNSNA1UNA482I VTAM is at version 5.1.0, Function List X'FFFFFFF7DDFF0000'

UNB036I Starting second pass of initialisation commands UNB390I Reading initialisation commands from UNPARM member SYSTEMUNB396I Cmd: SYSTEM processed successfully on first pass UNB396I Cmd: POOL processed successfully on first pass UNB396I Cmd: POOL processed successfully on first pass UNB396I Cmd: SYSLOG processed successfully on first pass UNB398I 0 commands scheduled from SYSTEM UNB390I Reading initialisation commands from UNPARM member AINTESTUNB398I 21 commands scheduled from AINTEST UNB301I Cmd: EXEC completed successfully

SYSINIT > TCP.CLU ID(TCP),NUMPABS(1)

UNB328I DEFINE of process TCP00001 completed successfully UNB330I START command accepted for process TCP00001 UNB328I START of process TCP00001 completed successfully UNB301I Cmd: TCP.CLU completed successfully UNB017I PAB TCP00001 activation scheduled UNB018I PAB TCP00001 initialisation in progress UNT410I PAB TCP00001 is active on Unix process Id 0001001C

SYSINIT > TCP.CLN ID(TLN),PORT(2043),CLU_ID(TCP),PROTOCOL(TELNET), PROMPT(AMI),NVTNEG(AMI),LOGOFF(AMI),LOGON(AMI,SAF), ROUTE(IMS2),ACC_ID(LOCAL)

UNB017I PAB +TCPLSTN activation scheduled UNB018I PAB +TCPLSTN initialisation in progress UNT410I PAB +TCPLSTN is active on Unix process Id 0001001D UNT413I CAB TLN(10) now listening on port 2043

33

General Information

Because these commands were issued as part of initialisation the log showsthe command has having been issued by SYSINIT. Each command is initiallyfollowed by a series of solicited message responses. Activation of theassociated new processes however causes the generation of unsolicitedmessages to indicate activation progress, these messages are therefore notindented.

Note: The editing that took place was simply to remove non-relatedmessages that were interspersed between these TCP messages in thejournal log.

Error Logging

The error log is deliberately small and is always held on the JES2 spool. Onlymessages directly affecting program operation are normally issued to theerror log. The error log prefixes each message with the name of the moduleissuing the error message, the process under which it was issued and thetimestamp as shown below:

The timestamp can be used to cross reference these error messages with themore complete journal log. The example above illustrates the reporting of aconfiguration error, however, often there will be no messages in the error log.During development of custom solutions entries for logic errors can often beseen, as follows:

these error messages were generated while developing a REXX application,they are all logic errors not expected to be found in a running system.

Messages with a W or E suffix are automatically duplicated to the error log,however normal I suffixed messages can be routed to the error log throughcustomisation overrides. Note that E suffixed messages are also written tothe system operator.

REXX LogAny GAIN process can run as a REXX environment, the entire process or justthe application/logic component being a REXX procedure. When defining theprocess the SAY_DD parameter specifies the DDname to be used for theoutput from REXX say commands. The default DDname is SYSREXX.

SYSOUT log

The sysout log is a GAIN specific REXX log. It is used by the commandprocess and is also the default log for the console process. The dataset isopened as part of initialisation and can be written to by any customised REXXbased GAIN command.

UNABELOG *SYSERR* 08:59:17.564 UNB020I Error log active on Mon, 08 J..AINBCAS *SYSCMD* 08:59:23.855 AIN484W Cmd: APPC.SVC param RMT_ID inv.AINBCAS *SYSCMD* 08:59:23.855 AIN481W APPC.SVC command terminated due

UNAB590W ERROR StemVar.0 not initialised. Exec UNATLSTN, fn(CMDRSP..UNAB010W AMI_SIGNAL event to +TCPLSTN at UNABRFEG+0222 failed: EVEN..UNAB591W ERROR Event could not be generated. Exec UNABLSTN, fn(EVTG..

UNB020I SYSOUT log active on Thu, 11 July 2002

34


The above message simply indicates successful opening of the SYSOUT log.

List and Show Commands

The LIST and SHOW commands are used to display the status of GAINresources. The list command formats and displays lists of resources, whilethe show command displays a specific resource. List and Show commandshave been added for GAIN specific displays while more generic displays arepart of the GATES base code. Some examples follow, refer to the ”GAINInstallation, Configuration and Operations Manual” for more details on all theavailable list and display commands.

List Services

This command lists the status of all the defined GAIN services. It providesbasic configuration information and indicates whether a service has beenused as well as how heavily. An examle of the list services command follows:

Using the list services command an operator is able to determine whether atransaction path has been correctly defined and if so the degree of activityand whether current resources allow transactions to be processed withoutundue delay.

List Remotes

This command lists the status of all the defined GAIN remote systems. Itprovides configuration and conection status information. An examle of the listremotes command follows:

Using the list remotes command an operator is able to determine whether acommunications path to a remote destination has been correctly defined andfully activated. This might be required as part of a slow transactionprocessing analysis.

List CABs

CABs are used to define a connection (or potential connection). Orientation isassigned based on whether GATES establishes the connection or not andthis, along with some refinements defines the role of the CAB. The LIST

Svc_Id State Rmt AMI Total Qud MaxQud AMI specific data -------- ----- ----- ---- ------ --- ------- ------------------------IMS1 ADRMT IMSP APPC 0 0 0/ 0 TEST01 IMS2 ACONN IMSP APPC 10 0 1/ 40 TEST02 CICS1 ACONN CICSA APPC 0 0 0/100 CICS_test_tran TCP1 ACONN HOST1 TCP 0 0 0/100 UNB300I End

RmtId State Clus AMI Act Tot Destination ----- ----- ----- ---- --- --- ---------------------IMSP ACONN APPC APPC 4 4 UNCNSNA1.SVRLU001 CICSA ACONN APPC APPC 4 4 UNCNSNA1.SVRLU002 HOST1 INACT TCP TCP 0 1 127.0.0.1:2044 UNB300I End

35

General Information

CABS command displays the connection names, state, role and I/O activityas shown in the example below:

Show System

The show system command displays information about the GAIN addressspace. When the GAIN address space was activated and storage poolusage.

UNB351I Show SYSTEM System STDY is running in TEST mode started at 09:19:11 on Mon, 12 August 2002 running as a job under userid TS access key valid for another 142 days Pool InUse Total Xpn MaxIU Size Init Incr Thr---- ----- ----- --- ----- ----- ----- ---- ---IBUF 12 64 0 18 4096 64 32 8SBUF 14 64 0 27 352 64 32 8SPA 0 16 0 2 15360 16 8 6CAB 21 64 0 21 448 64 32 8USER 7 16 0 8 128 16 64 8PAB 10 10 8 10 2008 2 1 0VCA 1 1 0 1 255K 1 1 0App 0 0 0 0 0 0 0 0Total pool storage: 823K VCA storage in use = 448 bytes, 0% of available UNB300I End

CAB name Index State AMI R RemoteEntity Name Sent bytes Rcvd bytes-------- ----- ----- ---- - --------------------- ---- ----- ---- -----*OP_SYS* 1 ACONN 00 I 0 0 0 0SYSERROR 2 ACONN QSAM C DD: SYSERROR 4 368 0 0SYSPRINT 4 ACONN QSAM C DD: SYSPRINT 145 9K 0 0SYSTRACE 5 ACONN BSAM C DD: SYSTRACE 23 118K 0 0IMSASY 6 ALSTN APPC M UNCNSNA1.CLNLU001 0 0 0 0CICSS 7 ALSTN APPC M UNCNSNA1.CLNLU001 0 0 0 0IMSP-01 8 ACONN APPC M UNCNSNA1.SVRLU001 0 0 0 0CICSA-01 9 ACONN APPC M UNCNSNA1.SVRLU002 0 0 0 0TN1 10 ALSTN TCP L waiting connection 0 0 0 0TN2 11 ALSTN TCP L waiting connection 0 0 0 0HOST1-01 12 ACONN TCP C 127.0.0.1:2044 0 0 1 50CICSS001 13 ACONN APPC M UNCNSNA1.CLNLU001 0 0 0 0IMSASY01 14 ACONN APPC M UNCNSNA1.CLNLU001 0 0 0 0CNST 15 ALSTN TCP L IN_ADDR_ANY:2081 0 0 0 0TN1* 16 RESET TCP I waiting connection 0 0 0 0TN200001 17 ACONN TCP S 127.0.0.1:2044 1 50 0 0TN2* 18 RESET TCP I waiting connection 0 0 0 0CNST* 19 RESET TCP I waiting connection 0 0 0 0CNSH 20 ALSTN TCP L IN_ADDR_ANY:2080 0 0 0 0CNSH* 21 RESET TCP I waiting connection 0 0 0 0TS 22 ACONN OSYS S SYSOP 0 0 1 9UNB300I End

36

2 Planning

This chapter provides information to assist in planning for a GAIN installation. Itidentifies pre-requisite product requirements and provides an installation checklist so that the required resources can be made available for a successful instal-lation. Detailed information is available in the publication ”GAIN Installation,Configuration and Operations” .

37

Planning

Deliverables

The GAIN software is in SMP/E format and delivered on 3480/3490/3490Eand 9mm DAT media. An INSTALL dataset, delivered in non-SMP/E formatas the first file on the tape provides an ISPF dialogue based installationprocedure which will:

• Allocate SMP/E and product datasets.

• Receive, Apply and Accept the product code.

• Allocate and prime a parameters dataset

Documentation is delivered in PDF format and can be downloaded from yourdistributor’s website.

The Code

Product code and the GATES architecture implementing base code issupplied as object code only modules and REXX procedures.

An operational system will typically use all of the following target librarydatasets:

Output datasets are normally allocated to JES but can equally well be writtento sequential datasets.

In addition many sites will make use of one or more of the following datasets.

Custom Solutions

The first step of a custom solution is to install the GATES base code. If thecustom solution includes in-house development, then the base install will alsoinclude a small ISPF development environment.

Additional source, maclib, object, listing and link datasets will then beallocated as required for the development process. At the production level thetwo link datasets can be merged to reduce the number of APF authorisdlibraries required.

SUNLINK Contains the executable code. Datasets in the SUNLINK con-catenation must be APF authorised.

SUNEXEC Contains the interpreted (REXX) code

SUNHTML Contains the HTML used by the console interface when sup-porting web browser access.

UNPARM Contains the initialisation command file. This dataset is con-structed as part of the GATES installation process.

SUNSAMP Is a samples dataset providing configuration, exit and REXX coding examples.

SUNMAC Is the standard GATES macro library that will be required for customisation of message tables and creation of exits.

38

Deliverables

Access Key

The product code is key protected. Your distributor will supply you with anaccess key to enable your use of the product. Without an access key you willonly be able to run in evaluation mode.

Initially, you will be supplied with an access key that will allow you to runGAIN in TEST mode only. TEST mode is limited in the number of connectionspermitted and will terminate on error conditions rather than attemptingrecovery i.e. re-instatement of failed tasks is inhibited, certain error conditionscause abends to force capture of diagnostic information. Once you haveaccepted the product a permanent key is provided that will allow you to run inan unlimited PROD (production) mode.

To summarise the available modes:

Documentation

Documentation is always delivered in PDF format and the latest version canbe downloaded from your distributors website.

EVAL Evaluation mode does not require an access key, however the following limitations apply:

Execution is permitted only on Tue, Wed and Thu days

Other limitations as exist for TEST mode

TEST Test mode requires an access key which is freely available to customers performing registered trials or who also have a pro-duction key. Test mode is limited to a maximum number of con-nections, automated recovery on errors is also disabled and diagnostic data capture forced.

PROD Production mode requires an access key which is provided in accordance with your license agreement. Production mode is unlimited in functionality and operation.

39

Planning

Pre-Requisites

GAIN has been developed and tested on releases of OS/390 from version 2.7onwards.

Most features used by GATES have been around for some time. If theoperating system requirements have been met then the following pre-requi-sites should not be of much concern:.

Web Browser Console Support

Client web browsers accessing the console facility must support HTTP 1.1protocols, specifically user authentication. This is not a stringent requirementand is met by Microsoft’s Internet Explorer version 4 and Netscape’sNavigator version 4.

VTAM Generic Name Support

Generic name support allows multiple copies of GAIN located within asysplex to be perceived by SNA APPC clients as a single transactionprocessing image. VTAM distributes non-parallel sessions across each of theactive GAIN applications. This technique removes any routing requirementsfrom the client and provides a fault tolerant environment.

In order to use this feature VTAM must be at version 4.1 or higher and anXES based coupling facility structure must be established in accordance withthe instructions laid out in the CS SNA Network Implementation Guide.

TCPIP Dynamic VIPA Support

Dynamic VIPA support is implemented by the TCP/IP stack and allowsmultiple GAIN instances located within a sysplex to provide mutual backup.Each GAIN instance is associated with it’s TCP/IP stack and a specificdynamic VIPA address, each stack further defines itself as a backup for theother systems (a ranking order determines which stack actually performs thebackup in a failure scenario). TCP clients will be able to connect to thebackup system immediately after the primary system fails.

In order to use this feature the operating system must be at the OS/390version 2.8 level or higher.

SMP/E

RACF Version 2.1 or later

TSO/REXX REXX support is required for command processing, console support and for optional custom REXX applications.

TCPIP Communications Server for OS/390 2.7 or one of its succes-sor products is required.

VTAM Communications Server for OS/390 2.7 or one of its succes-sor products is required.

40

Installation Checklist


Once you are satisfied that all GATES pre-requisite products are installed andavailable on your system, you are ready to start planning for the GATESinstallation itself. Here is a checklist of some of the actions you may need totake as part of your GATES install process:

• Obtain the product materials and Access Key

• Reserve disk space for GATES SMP/E and product datasets

• Update the system PROCLIB with the GATES procedure

• Update the system PARMLIB

• Update the system VTAMLST

• Update the system VTAMLIB

• SMP/E install the GATES components

• APF authorise the SUNLINK module library

• Define the started task to SAF, protect the SUNLINK dataset

• Run the IVP

The planning actions required are identified in more detail in the sectionsbelow and should enable you to plan for interactions with other departmentswhere necessary. The ”GATES Installation, Configuration and Operationsmanual G-ICO0102-1” provides full details of the actual installation process.

Obtain the Product Materials and Access Key

To install any GATES based product or custom soltion you will need an instal-lation tape and an access key. Let your distributor know the media on whichyou want the product delivered, product delivery is normally a matter of days.

In order to provide you with an access key your distributor will need to knowthe CPU model and serial number on which you intend to run the GATEScode. You can obtain this information by issuing a D M (display systemconfiguration) command at a system console. The information you need is inthe first part of the response to this command and will be similar to that shownbelow:

D M IEE174I 16.09.19 DISPLAY M 262 PROCESSOR STATUS ID CPU SERIAL 0 + 0011112222

Where the SERIAL is made of the following groups of numbers: 00 is variableinformation and ignored. 1111 is the CPU serial number and 2222 is the CPUmodel.

NB: Ensure that your distributor gives you a GATES access key. You will not be able to run a GATES product or custom solu-tion without this key.

Reserving disk space for the GATES datasetsThe space required for GATES datasets is minimal, the actual details follow.

41

Planning

The system on which GATES is to be installed will need to reserve space forall the GATES datasets as follows:

Note that allowing GATES to share an existing SMP/E CSI is not recom-mended as the risk of naming conflicts cannot be excluded.

In the case of on-site developed custom solutions you should estimate thatan additional 20 M-bytes of storage should be reserved for developmentdatasets.

The run-time environment is smaller yet with space allocations for theindividual datasets required being as follows:

Updating the system PROCLIB with the GATES procedureGATES can run as a job or started task. As part of the migration to a liveenvironment you should plan to start GATES products as a started task. Thiswill require that you have access to one of your system PROCLIB datasets.

Updating the system PARMLIBDepending upon your configuration the use of the BPX sockets API for TCPcommunications may require you to update the BPXPRMxx member of yoursystem parmlib dataset.

NB: Updating system datasets without following your sites standard procedures can have disastrous consequences. Also, be aware that this update will require an IPL and may therefore need to be scheduled well in advance.

In a test environment it may be satisfactory to make the required updatesdynamically via the SETOMVS command (for most parameters). In yourproduction environment you will probably require the updated BPXPRMxxmember to be in place and active as part of the GATES migration to live.

SMP/E datasets 14 cyl 3390

Target library datasets 10 M-bytes

Distribution library datasets 10 M-bytes

SUNLINK dataset 2 M-bytes

SUNEXEC dataset 2 M-bytes

UNPARM dataset 1 M-byte

42


Possible BPXPRMxx parameter changes

You should scan the entire BPXPRMxx member to ensure that the param-eters specified meet your requirements. You should pay especial attention tothe following:

See also ‘APF authorise the SUNLINK module library’ below for details ofanother PARMLIB dataset update.

Updating the system VTAMLSTYou will need to define a VTAM application major node containing APPLdefinitions for use by GAIN. The exact definitions will depend upon yourchosen configuration and the capabilities of the remote systems with whichyou will communicate.

Updating the system VTAMLIBAs well as updating VTAMLST you will almost certainly need to updateVTAMLIB with the supplied default mode table.

SMP/E installYou will need to allocate resource for the actual installation of the productmaterials. The SMP/E install is guided and straight forward, provided all pre-requisite actions have been completed you should estimate install andrunning of a simple test to be no more than one to two day’s work.

Note that development of a final product configuration will take longerdependent upon the complexity of the environment being created.

APF authorise the SUNLINK module libraryGAIN must be run from an authorised library. This will require that you updatethe PROGxx member of your system parmlib dataset.

NB: Updating system datasets without following your sites standard procedures can have disastrous consequences. Also, be aware that this update may require an IPL and may therefore need to be scheduled well in advance.

MAXFILEPROC This parameter specifies the maximum number of active sockets per Unix process. That is the maximum sockets per GATES PAB definition (MVS TCB). The default value is 64, which is often too low.

MAXPROCUSER This parameter specifies the maximum number of con-current processes per user (GATES address space). Each GATES PAB definition is a single UNIX process. The default value is 25, which may be low for very large GATES configurations.

MAXSOCKETS This is a parameter on the NETWORK statement. GATES uses the AF_INET network for TCP sockets. Ensure that the MAXSOCKETS value for this network is sufficient for all the AF_INET connections to this system.

43

Planning

In a test environment it may be satisfactory to make the required updatesdynamically via the SETPROG command. In your production environmentyou will probably require the updated PROGxx member to be in place andactive as part of the migration to live.

As with all APF datasets you should restrict all write access and limit readaccess to ensure system integrity. Consult with your system security adminis-trator for your site’s conventions for APF datasets.

Define the started task to SAFIf started tasks are protected remeber that you will need the help of yoursecurity administrator before you can run your GATES system. In any casethe system user id under which the started task runs will need to have beenassigned a SAF optional UNIX System Services (OMVS) user id.

If access to the SUNLINK dataset has been restricted you will need to permityour started task access.

Run the IVP

Running the IVP ensures that basic installation has been completed success-fully. For simplicity it is normally run as a job but do not forget that the jobowner will need to have been assigned SAF optional UNIX System Services(OMVS) user and group ids.

44

3 Technical Overview

This chapter provides a technical overview of the GATES architecture andimplementation examples for custom soltions and/or products.

Pre-requisite reading: You should have read the General Information chapterbefore beginning with this material.

45

Technical Overview

GATES Components

GATES, is an OS/390 and z/OS compliant, multi-tasking structure makingextensive use of Unix System Services processes and operating system SRBbased processing. GATES is split into inter-operating components so that thenecessary complexities of one component do not affect another.

Until now, when describing GATES product or custom solution logic we haveonly taken into account the application logic and possibly the access methodinterface. Figure 13, “GATES components,” provides a better illustration of aGATES address space. The components themselves are described in moredetail in the following sections.

Applications

The code forming the central logic for the GATES product or custom solutionis known as the GATES application. Normally multiple applications will runwithin the GATES address space, each forming a part of the single product orcustom solution and running under an independent MVS task. Applicationsare event based, that is to say, GATES applications define small proceduresfor handling various network and/or house-keeping events, these individualprocedures are therefore known as event processors.

For maximum run-time performance event processors may be written inassembler taking advantage of the operating system’s efficient SRBprocessing, the complexities of which are hidden by the GATES infra-structure code. However, for maximum flexibility event processors may also

This diagram adds callable services to the APPs and AMIs defined in previous GATES address space representations. The supplied processes are simply GATES system supplied APPs required for general use.

Fig. 13. GATES components

GATES address space

Productor Custom SolutionApplication Logic

Optional Access Method Interfaces

Supplied processes•Command Processing•Logging•Tracing•REXX stub support

Callable Services

Limited AMIs

GATES address space

Productor Custom SolutionApplication Logic


Supplied processes•Command Processing•Logging•Tracing•REXX stub support

Callable Services

Limited AMIs

46

GATES Components

be written in IBM’s REstructured eXtended eXecutor (REXX) language.While, by default, REXX is interpreted (rather than compiled) it does providea truly simple and flexible interface for application programming.


While optional for custom solutions the AMIs are integrated into GATESbased products such as GAIN. The AMI provides the application componentswith a simplified common interface to operating system services and networkprotocols. The AMI’s use GATES event oriented processing for interfacingwith the application components while absorbing any of the complexitiesassociated with the application programming interface (API) as defined by theaccess method.

AMIs act like building blocks which aid in the development of almost anyapplication model. The use of these building blocks means that there is noneed to develop device or network protocol oriented code within an appli-cation component.

Base Code

This is the code common to every GATES system and provides the infra-structure to support the application within the multi-tasking environment. Thefeatures common to complex communications applications are integrated intothis base code. Some key facilities are summarised below:

• A set of standard processes (MVS tasks) for command processing,logging and tracing. As well as support for integrating REXX into theGATES environment.

• A set of callable services available to any of the GATES components.These services standardise and simplify interfaces to major GATEScomponents and other operating system services..

• Limited functionality QSAM, BSAM and BPAM access method inter-faces primarily supplied to support the GATES base logging and trac-ing funtionality.

These sub-components are reviewed in more detail below:

GATES Callable Services

The GATES callable services can be invoked by any code and provideaccess to commonly used routines to ensure code efficiency and the highestlevels of code re-use. Examples of callable services are for:

Storage Management: GATES provides it’s own storage/cell pool structureswhich optimise use of frequently obtained and released storage areas. Poolsare pre-emtively expanded as required under user defined criteria.

Message Logging: messages are generated through a callable service.Variables are inserted into a pre-defined and customisable skeletal messagewith routing characteristics defined by the caller or defaulted from the staticdefinition.

Transaction Management Services: this service provides for transactionqueuing and scheduling to one or more threads of a GATES process,

47

Technical Overview

including operator warnings when thresholds for maximum queued requestsare exceeded. These services also manage statistics counters which aremade available to operations through the standard GATES displaycommands or for logging through REXX automation.

Data Translation Services: where AMI presentation support is unable toprovide automatic data translation (due to structured data fields etc.) customlogic can invoke the translation services directly. Using these servicesensures compatibility with parametised and potentially customisd translationservices requested through configuration.

REXX Function Package: to ensure the tight integration of assembler andREXX code within the GATES address space a specialised REXX functionpackage is provided. This package provides all of the essential servicesrequired by a REXX routine which is acting either as a GATES commandprocessor or as a business logic application.

GATES Standard Processes

The following processes are part of the GATES base code set. They must bepresent in any GATES system:

GATES Optional Base Processes

The following processes are also part of the base code set but need not bepresent in an operational GATES environment:

Process Name Description

*MASTER* This is the GATES process associated with the job step TCB of the operating system. It is responsible for:

initialisation/terminationstorage managementoperator interfaces

*SYSERR* This process is for the GATES system error log which is QSAM based and normally associated with JES2 output. With a few exceptions (notably during initialisation) when the standard system log is not active all mesages are writ-tent to this log. When a standard system log is available W and E suffixed messages are duplicated to this log unless overriding actions have been coded in the message skele-ton or by the message generator.

*SYSCMD* This process is for the processing of GATES commands entered either by the operator or via initialisation and other command files. This process supports a REXX environ-ment to allow the use of REXX based command proces-sors.

48

GATES Components

Process Name Description

*SYSLOG* Activated by the SYSLOG command, this process is for the GATES system log which is typically QSAM based. All GATES generated messages are by default written to this log. Should there be an error writing to this log or the proc-ess not be available then the messages are written to the system error log.

*SYSTRC* This process is activated automatically whenever a trace command starts tracing. It is BSAM based and supports branch entry for tracing events allowing tracing to be per-formed with minimum of impact.

49

Technical Overview

GATES Operational Models

The GATES layered structure and modularised support allows for great flexi-bility in product or custom solution design. Every GATES installation will,however, follow a similar design which can be seen as a variant on one oftwo models described below:

Integrated Application ModelIn this model the product or custom solution (the GATES application) is fully contained within the GATES address space, incoming requests are proc-

essed via direct access to data and not by the forwarding of the requests to another transaction processing system.

The application uses GATES to provide basic servercies permitting it to act as a stand-alone application. The application code, however, still consists entirely of small procedures known as event proc-essors.

This model is best used when the prod-uct or custom solution development can be tightly integrated with the GATES base code. It is also suitable for existing applications that have modularised net-work access and now wish to take advantage of GATES access to multiple network protocols.

The integrated application model is also a common configuration for relatively simple REXX based network utilities such as an SMTP based e-mail posting application, a simple web server or a REXX based remote application tester.

The GATES base code, the AccessMethod Interface and the Applicationcode make up the entire GATES system.

Here the role of GATES is to provide an efficient working environmentallowing the application code to remain small, confining itself only to therequired business logic.

Message Switching Model

The message switching model acts as a value added switch typicallybetween an external network resource and a local transaction processingsystem. In this scenario, the GATES address space can be vertically split intotwo similar components governed by common application code. Typically oneAMI will be a network feed supplying the GATES address space with data.The other AMI will then be a transaction oriented structure acting as a clientand obtaining data from the local transaction processing system which actsas the server.

GATES AMI’s are designed to work as both a transaction scheduler and anetwork feed. Transactions can be scheduled in either direction so that the

SNAnetwork

TCP/IPnetwork


GATES address space


Data

Application Logic

Access MethodInterfaces

50

GATES Operational Models

mainframe can beeither the client or theserver or even both. Ifthe transaction modeldoes not meet therequirements of thelocal transactionsystem then the APPcan apply the uniquelogic required foraccess to the requireddata.

The diagram opposite illustrates data enter-ing the GATES system through one network interface (say a TCP/IP feeder) and exiting through another inter-face perhaps as an APPC client transac-tion. The GATES AMI and application code will typically add value to the data for exam-ple by converting incoming data from ascii to ebcdic and/or by converting input TCP/IP streams to mainframe based records.

This message switch model is frequently used to provide legacy SNA appli-cations with snap-in TCP/IP support. The ability to customise or even writethe GATES application code means that this model can provide a legacytransaction processing system with immediate transparent access to multiplenetwork protocols

SNAnetwork

Operating SystemServices

TCP/IPnetwork

Operating SystemServices

GATES address space

Application Logic

AccessMethod

Interface

AccessMethod

Interface

NetworkFeed

TransactionScheduler

51

Technical Overview

Internal Structure

GATES maintains information for all key components within individual controlblocks/storage areas. A central System Anchor Block, SAB maintains thelinks to all of the other control blocks which are principally allocated on eithera process, connection or user basis.

The ClustersThe CLUSTER is the principal building block of a GATES environment. Thecluster, represented in storage by a QAB, is made up of one or moreprocesses performing identical functions. Clusters can be managed as asingle entity simplifying operation of the GATES environment. The clusterstructure also allows for increased throughput in a multi-processingenvironment, load distribution across the cluster is normally a standard partof the GATES structure and when more than one process is used theCLUSTER gains a degree of fault tolerance through process redundancy.

In Figure 14, “Cluster configuration,” we see a typical structure for a GATESmessage switching model implementation, in this case based upon the GAINproduct. Two clusters are defined one TCP the other APPC, each repre-sented by a QAB. The linkage between the QABs can be predefined throughconfiguration or dynamic through the use of exits.

Under each QAB are the PABs representing processes implicitly defined bythe cluster. The TCP cluster includes a stand-alone PAB which representsthe TCP based listener. TCP connections received by the listener are passedin turn to each of the processes defined in the associated cluster. Once aconnection has been passed the listener plays no further role and all I/O isthrough the process owning the connection.

The clusters define the linkage between the TCP and APPC components andthis is fine when communication consists of transactions. In user defined or

Fig. 14. Cluster configuration

QAB

GATES address space

QAB

PAB

PAB

PAB

PAB

PAB

PAB

PAB

TCP APPC

QAB

GATES address space

QAB

PAB

PAB

PAB

PAB

PAB

PAB

PAB

TCP APPC

52

Internal Structure

message oriented communications an affinity between individual processesand connections has to be established if the data flow is to be maintained inan orderly manner.

Processes

Individual proceses drive the GATES APP logic. Apps, as in Figure 14,“Cluster configuration,” normally have a direct assocaition with an AMI. TheApp and the AMI run under the operating system as a single task (repre-sented by an operating system TCB and may also be dubbed as a Unixprocess). This combination of APP and AMI is termed a process and theprocess’s status information is held in a Process Anchor Block, PAB. ThePAB interfaces between the operating system and the GATES orienteddispatcher for the scheduling of serialised event procedures. Space isreserved in the PAB for use by the AMI and APP, each PAB supports onlyone APP and one AMI.

Where permitted by the undelying access method, network I/O orientedprocesses tend to be grouped into clusters with a centralised listeningprocess passing connections to processes within the cluster on a loadbalancing basis.

While the PAB provides an anchor for serialised processing of queued eventsvia the operating system’s TCB dispatching mechanism, many events oncescheduled will branch enter other events owned by other processes. SRBroutines scheduled from system exits may also scheule events that must thenbe capable of being run re-entrantly. The event processor is defined to theGATES system as serial or re-entrant as part of initialisation processing.

Connections

Connection Anchor Blocks CABs represent individual connections with theGATES system. A CAB is obtained and initialised as connections are estab-

Fig. 15. Cluster and Process control blocks

QAB (CLUSTER)GATES address space

PABAccessMethodInterface

ApplicationLogic


ApplicationLogic


ApplicationLogic

53

Technical Overview

lished, either when requested by an APP or received from the network by theAMI. The AMI and APP manage the connection state through shared use ofthe CAB, each connection oriented event handling procedure is passed theaddress of the CAB and any data buffer when it is invoked.

The CAB maintains dedicated work areas for both the AMI and the APP.

Where a local entity must be defined in order to accept connections e.g.VTAM’s OPEN ACB and TCPIP’s listen, the CAB is once again used. Theexact use of the CAB in these circumstances being defined by the AMI. Newinbound connections are always mapped to a new CAB as they connect tothe local system.

The LIST CABS command will display all of the active CABs and the CABrole field will allow determination of which CABs are preforming a listening,client or server role.

GroupsConnection groups are represented by GAB control blocks. The GAB isqueued from a QAB (representing a cluster). A group automatically maps therequested connection across each of the processes in the cluster. A CABbeing implicitly generated for each process. Processing of the individualCABs in order to construct the connection is then as defined by the AMI andunder control of the owning process. Thus connections are arranged intogroups in a similar manner to which processes are arranged into clusters.

Group oriented work is normally competed for by the individual groupmembers, actually the processes owning the individual connections. Thequeue of work (transactions) to be completed is presented to the AMI trans-action handling routines by the APP.

Fig. 16. Connection control blocks

QAB (CLUSTER)GATESaddress space

AccessMethodInterface

CAB

CAB

CAB

CAB

CAB

AccessMethodAddressSpace

VTAM

TCPIP

Application

PAB

54

Internal Structure

Note that multiple connections are established, this is especially important toremember when considering the APPC AMI. Each of the connectionsdiscussed will have its own ISTSVMGR connection for CNOS control, eachconnection will also have multiple parallel sessions based on the suppliedvalue of MAX_SESS (and VTAM negotiated parameters). A group APPCconnection in a cluster with two processes and a MAX_SESS of eight willactually have eighteen SNA sessions to the target LU. On each process therewill be one ISTSVMGR session and eight parallel sessions.

Note also that the APPC AMI does not build CAB control blocks for theparallel sessions. CABs for the ISTSVMGR session have a CAB role of ‘M’for master. Additional CABs are obtained to manage conversations as theseare established, these will have a role of client or server dependent upon thedirection of connection establishment.

Users

Users are defined by the application logic i.e they may be users of theGATES system or users passing through the GATES system. A USR blockmaintains the status of an individual user. Multiple USR blocks can beassociated with a single connection (CAB) or the same user may be concur-rently active over multiple connections once again dependent only uponapplication logic.

The GATES console process is an example of an application using USRblocks.

Fig. 17. Connection groups


PABAccess Method Interface

ApplicationLogic CAB



GAB (GROUP)



ApplicationLogic CABPAB




ApplicationLogic CABPAB



GAB (GROUP)

55

Technical Overview

GAIN

GAIN adds fixed application logic to the GATES function so far described.The GATES based TRN block shown in Figure 18, “GAIN transactionprocessing,” is used to represent a GAIN service (see APPC.SVC orTCP.SVC configuration commands). Included with the service definition is aservice or transaction queue held in the GATES TAB (transaction anchorblock). This service structure acts as a link between a GAIN TCP client andan APPC server (or vica versa). A simplified view of typical GAIN transactionprocessing is as follows:

The CAB on the left hand side of the diagram runs under its on process (notshown) and has been built by an AMI to represent an inbound clientconnection. Data received on this connection forms a transaction, the trans-action is constructed according to the rules coded during GAIN configuration.A fixed configuration defined relationship with a remote service results in alink between the CAB and the TRN block (this link can also be createddynamically through a user supplied exit).

On receipt of a transaction the GAIN logic places the request onto the TRNblock. If no connection to the remote system exists then the request isrejected with a ‘no access’ condition. If the transaction queue (TAB) is fullthen the request is rejected with a ‘server busy’ condition. The first availableCAB with a connection to the remote system is then selected to transport thenew transaction. If no CAB is available then the request remains queued untila CAB becomes available or the request times out.

Each GATES AMI supports synchronous and asynchronous transactions.Once the AMI has received and accepted the request GAIN logic takes nofurther action until a response is returned or the request must be timed out.When a response is returned this is routed back to the originating CAB fordelivery to the client issuing the original transaction request.

On completion of transaction processing the CAB attempts to find more workon the TRN blocks associated with its destinaion in a prioroty order. If nofurther work exists the process waits by returning to the operating system.

Fig. 18. GAIN transaction processing

GAIN address space

ApplicationLogic

GAB (GROUP)


PAB

CAB

TRN (SVC)

TAB (queue)

CAB

GAIN address space

ApplicationLogic

GAB (GROUP)


PAB

CAB

TRN (SVC)

TAB (queue)

TRN (SVC)

TAB (queue)

CAB

56

Processing

Processing

The GATES process is a relatively simple concept which maps essentially toan operating system task primarily running under it’s own TCB. After taskinitialisation, each task shares a common GATES dispatcher that is able torun a single unit of work known as an event. The event can be run by the APPor the AMI dependent only upon the event type.

Events

Processing for both the APP and the AMI is broken into small procedures forhandling specific events. These events might be:

From the application logic

• A request to establish a connection with a remote entity

• A request to send data to a remote entity

• A request to disconnect from a remote entity

• A request of another application component

From the Access Method Interface

• An indication (notification) that a remote entity has requested a con-nection with this application.

• An indication that data has arrived on a connection

• An indication that a remote connection has been terminated.

A small number of events are generated by the GATES base code, these are:

• Application is being started

• Application is being stopped

• HouseKeeping timer

These event handling routines are invoked as required and on eachinvocation supporting information such as the connection being processedand any data associated with the event is supplied.

The event processing routines are defined at application start time. Includedalong with the identification of the the routine for a specific event are theroutines capabilities. Whether the routine can accept branch entry, runningunder a non-local MVS TCB or running in SRB mode. The event issuer andthe event processor will negotiate requirements and capabilities and a branchentry event is queued for dispatching under the local TCB only when eventprocessing routines demand this.

Exits

In addition to processing events issued by the application, the AMI must alsosupport exits defined by the access method API. These are again smallprocedures but in this case are not invoked through the GATES dispatchingenvironment. These exits do however generate events for either the AMI orAPP to process.

57

Technical Overview

Event procedures with no serialisation requirements may be branch enteredwhen undelying operating system constraints permit this. In this case eventsmay run in TCB or SRB mode dependent only on the mode of the invoker.

When procedures must be serialised then this is achieved on a per processper connection basis. The executing procedure is unaware of the serialisationapart from having requested it.

Unix System Services

One final complexity is in the use of the TCPIP AMI as the API used is theUnix System Services BPX callable services API. This requires that each ofthe GATES processes (TCBs) be dubbed as Unix processes. The operatingsystem further segregates USS SRB based processing from otherprocessing so care must be taken when dispatching different types of SRBson different processes.

The Process

It is only now that the true definition of the process can be understood. Whilethere is a strong affinity to the local TCB i.e. the TCB used to initiate theprocess, event branch entry means that code associated with the processcan be run under any operating system thread. The process ties together thecode and therefore the functionality, dispatchability and code execution isdefined by restrictions set by the event or the calls it makes and the dynamicsof the run time environment.

58

Traces

Traces

A better understanding of the GATES logic can be obtained through analysisof the standard traces, a review of these now also illustrates the power ofGATES tracing for diagnosing any network problem. Full deatils of GATEStracing can be found in ”GATES Installation, Configuration and Operationsmanual G-ICO0102-1”.

A single tracing mechanism exists, allowing for tracing of various activitieswithin the system. These being:

• Scheduling, queuing or dispatching of an event.

• Buffer gets and frees

• Transaction management services enques and dequeues

• System messages

• REXX function calls

• AMI to API interface requests

Each trace record begins with:

• A timestamp

• A record identifier

• A general status/completion code for the traced item

• The name of the PAB under which the request is being processed

The rest of the trace record is dependent upon the type of trace record.

Event Trace Analysis

As an example of the types of information made available to the user and tofurther discuss GATES internals we consider the event trace in more detail.There are three different record types for event traces, these are:

The return code has significance on the BEQ and occaisionally on the BECtrace records, for example:

BEQ Identifies an event queuing action. The active PAB is queu-ing an event to itself or another PAB. PABs queue events to themselves when the APP and AMI are cross scheduling events.

BES Identifies an event being scheduled from the queue. This could well be some time after the event was originally queued.

BEC Identifies a call or branch entry to an event processor

00 Event was successfully queued to the target PAB

01 A request to call an event processor has been converted to a queue request, as the caller does not meet the con-straints set by the event processor.

59

Technical Overview

The information that follows the status/completion code for an event record isthen:

• The originating PAB name

• The CAB name and index (if applicable)

• The target PAB name

02 The target PAB has requested that this event be ignored, the event will not be scheduled. This is not an error, the logic of the target system is simply not interested in the event being traced.

04 Event not supported by the target PAB.

08 Target PAB invalid or not specified, CAB not supplied for a connection oriented event, buffer not supplied when required.

12 Target PAB inactive

60

Traces

• The buffer address (if applicable)

61

Technical Overview

GA

TE

S S

ampl

e T

race

Out

put

12:19:02.501 BES 00 TCP10001 APP_START TCP10001 UNABRAPP +0000 ....................

12:19:02.501 MSG 00 TCP10002 UNAB018I PAB TCP10002 initialisation in progress

12:19:02.501 BES 00 TCP10002 APP_START TCP10002 UNABRAPP +0000 ....................

12:19:02.501 BRF 00 TEST02 ex: TEST02 fn: EVTQ( NAME)

12:19:02.501 BRX 00 TEST02 ex: TEST02 fn: EVTQ() AMI_DATA_CFM

12:19:02.501 BES 00 TEST02 NTWKSVR 00005 AMI_RECEIVE TEST02 UNATBAMI +0000 ....................

12:19:02.501 TRQ 00 TEST02 NTWKSVR(00005) AIO(RECEIVE) 000000 000000 X'00000000' 00000000 UNATBAMI+071A

12:19:02.501 TRC 00 TEST02 NTWKSVR(00005) RECEIVE 006401 000000 X'00000000' 065F02A0

0000 + C9C10000 00000000 00004020 00000000 00000000 00000B0C 00001901 000023ED + IA........ ..................... +

0B00 + 6C6F723D 22233830 30303030 220D0A20 20202020 + %?.................. +

0B20 + 20666163 653D2241 7269616C 22207369 7A653D22 33223E3C 7374726F 6E673E3C + ../......./%....:..........?>... +

0B40 + 7370616E 20737479 6C653D22 666F6E74 2D66616D 696C793A 20417269 616C3B20 + ../>...`%....?>.../_.%`...../%.. +

0B60 + 666F6E74 2D73697A 653A2031 31707422 3E4F7572 0D0A2020 20202020 50726F64 + .?>....:.........|..........&.?. +

0B80 + 75637473 2026616D 703B2050 72696365 733C2F73 70616E3E 3C2F7374 726F6E67 + ....../_...&........./>......?>. +

0BA0 + 3E3C2F66 6F6E743E 3C2F7464 3E0D0A20 20202020 203C7464 20776964 74683D22 + ....?>.......................... +

0BC0 + 36352220 7374796C 653D2270 61646469 6E672D6C 6566743A 20357078 223E3C66 + ......`%..../...>..%............ +

62

Traces

• The name and offset into the module issuing the event

If a buffer is present then the active contents of the buffer are dumped to thetrace file as well.

Other trace entries exist for:

• Messages (as duplicated from the journal log)

• REXX functions

• Access Method to API interfaces

63

Documents

GAIN version 1.2 General Information, Planning and ... · 1 1 General Information This chapter provides information about GAIN, the GATES APPC IP Networking product. It describes: