e*Way Intelligent Adapter for SNA User’s Guide · Configuring the SNA Server and Client 18 All...

e*Way Intelligent Adapter for SNAUser’s Guide

Release 4.5.2

SeeBeyond Proprietary and Confidential

The information contained in this document is subject to change and is updated periodically to reflect changes to the applicable software. Although every effort has been made to ensure the accuracy of this document, SeeBeyond Technology Corporation (SeeBeyond) assumes no responsibility for any errors that may appear herein. The software described in this document is furnished under a License Agreement and may be used or copied only in accordance with the terms of such License Agreement. Printing, copying, or reproducing this document in any fashion is prohibited except in accordance with the License Agreement. The contents of this document are designated as being confidential and proprietary; are considered to be trade secrets of SeeBeyond; and may be used only in accordance with the License Agreement, as protected and enforceable by law. SeeBeyond assumes no responsibility for the use or reliability of its software on platforms that are not supported by SeeBeyond.

e*Gate, e*Insight, e*Way, e*Xchange, e*Xpressway, iBridge, Intelligent Bridge, IQ, SeeBeyond, and the SeeBeyond logo are trademarks and service marks of SeeBeyond Technology Corporation. All other brands or product names are trademarks of their respective companies.

© 1999–2002 by SeeBeyond Technology Corporation. All Rights Reserved. This work is protected as an unpublished work under the copyright laws.

This work is confidential and proprietary information of SeeBeyond and must be maintained in strict confidence.

Version 20020307220257.

e*Way Intelligent Adapter for SNAUser’s Guide 2 SeeBeyond Proprietary and Confidential

Contents

Contents

Preface 7Intended Reader 7

Organization 7

Nomenclature 8

Online Use 8

Writing Conventions 8

Additional Documentation 9

Chapter 1

Introduction 10SNA Architectural Overview 10

Supported Logical Unit Types 13SNA LU6.2 13SNA LUA 14SNA LU0 14

SNA e*Way Overview 15e*Way Components 15

Chapter 2

Installation 16System Requirements 16

Supported Operating Systems 16

External System Requirements 17SNA LU6.2 17SNA LU0, LU1, LU2, LU3 17Solaris Patch Requirements 17

External Configuration Requirements 18Configuring the SNA Server and Client 18

All Platforms 18Additional Procedures for Solaris 18


Contents

Installing the e*Way 19Windows Systems 19

Installation Procedure 19Subdirectories and Files 21Environment Configuration 21

UNIX Systems 22Installation Procedure 22Subdirectories and Files 23Environment Configuration 23

Chapter 3

Implementation 24Overview 24

Implementation Sequence 25

The e*Gate Enterprise Manager 26

Creating a Schema 27

Creating Event Types 28

Creating Event Type Definitions 28Assigning ETDs to Event Types 28

Defining Collaborations 30

Creating Intelligent Queues 31

Exception Handling 32

Enabling TP Trace 33

Known Issues and Limitations 33

Chapter 4

Setup Procedures 34Overview 34

Setting Up the e*Way 35Creating the e*Way 35Modifying e*Way Properties 36Configuring the e*Way 37

Using the e*Way Editor 38Changing the User Name 41Setting Startup Options or Schedules 41Activating or Modifying Logging Options 43Activating or Modifying Monitoring Thresholds 44

Troubleshooting the e*Way 45Configuration Problems 45System-related Problems 46


Contents

Chapter 5

Operational Overview 47e*Way Architecture 47

Basic e*Way Processes 49Initialization Process 50Connect to External Process 51Data Exchange Process 52Disconnect from External Process 55Shutdown Process 55

Chapter 6

Configuration Parameters (LU6.2) 56Overview 56

General Settings 57

Communication Setup 59

Monk Configuration 62Specifying Function or File Names 62Specifying Multiple Directories 62Load Path 62

SNA Client Configuration 71

Chapter 7

Configuration Parameters (LUA) 74Overview 74

General Settings 75

Communication Setup 77

Monk Configuration 80Specifying Function or File Names 80Specifying Multiple Directories 80Load Path 80

SNA LUA Client Configuration 89

Chapter 8

API Functions 90Overview 90

Native e*Way Functions 91


Contents

LU6.2 91LUA 100

Standard e*Way Functions 105LU6.2 105LUA 112

Generic e*Way Functions 118

Index 126


Preface

This Preface contains information regarding the User’s Guide itself.

P.1 Intended ReaderThe reader of this guide is presumed to be a developer or system administrator with responsibility for maintaining the SeeBeyond™ e*Gate™ Integrator system, and have a working knowledge of:

� Windows NT/2000 and/or UNIX operations and administration

� Windows-style GUI operations

� SNA Server, LU6.2 and/or LU0, and CPIC APIs

P.2 OrganizationThis User’s Guide is organized into two parts. The first part, consisting of Chapters 1-4, introduces the e*Way and describes the procedures for installing the e*Way and implementing a working system incorporating the e*Way. Chapter 3 also contains descriptions of the sample schemas provided with the product. These can be used to test your system following installation and, if appropriate, as templates you can modify to produce your own custom schemas. This part should be of particular interest to a System Administrator or other user charged with the task of getting the system up and running.

The second part, consisting of Chapters 5-8, describes the architecture and internal functionality of the e*Way. This part should be of particular interest to a Developer involved in customizing the e*Way for a specific purpose. Information contained in this part that is necessary for the initial setup of the e*Way is cross-referenced in the first part of the guide, at the appropriate points in the procedures.

e*Way Intelligent Adapter for SNAUser’s Guide 7


Section P.3Preface Nomenclature

P.3 NomenclatureNote that for purposes of brevity, the e*Way Intelligent Adapter for SNA is frequently referred to as the SNA e*Way, or simply the e*Way.

P.4 Online UseThis User’s Guide is provided in Adobe Acrobat’s Portable Document Format (PDF). As such, it can be printed out on any printer or viewed online. When viewing online, you can take advantage of the extensive hyperlinking imbedded in the document to navigate quickly throughout the Guide.

Hyperlinking is available in:

� The Table of Contents

� The Index

� Within the chapter text, indicated by blue print

Existence of a hyperlink hotspot is indicated when the hand cursor points to the text. Note that the hotspots in the Index are the page numbers, not the topics themselves. Returning to the spot you hyperlinked from is accomplished by right-clicking the mouse and selecting Go To Previous View on the resulting menu.

P.5 Writing ConventionsThe writing conventions listed in this section are observed throughout this document.

Monospaced (Courier) Font

Computer code and text to be typed at the command line are set in Courier as shown below.

Configuration for BOB_Promotion

java -jar ValidationBuilder.jar

Variables within a command line, or attributes within a function signature, are set in italics as shown below:

stcregutil -rh host-name -un user-name -up password -sf

Bold Sans-serif Font

� User Input: Click Apply to save, or OK to save and close.

� File Names and Paths: In the Open field, type D:\setup\setup.exe.

� Parameter, Function, and Command Names: The default parameter localhost is normally only used for testing; the Monk function iq-put places an Event into an IQ.



Section P.6Preface Additional Documentation

P.6 Additional Documentation� Many of the procedures included in this User’s Guide are described in greater detail

in the e*Gate Integrator User’s Guide.



Chapter 1

Introduction

This chapter provides a brief overview on SNA fundamentals and an introduction to the e*Way Intelligent Adapter for SNA.

1.1 SNA Architectural OverviewSNA (System Network Architecture) is a data communications architecture developed by IBM to specify common conventions for communication between various IBM hardware and software products. It is specifically designed to address issues of the reliability and flexibility of sharing data between components and their peripherals. Many vendors other than IBM also support SNA, allowing their products to interact with SNA networks.

An addressable unit on an SNA network is called a node, and is made up of four functional components forming a hierarchy as shown in Figure 1.

Figure 1 SNA Node Architecture

To establish a communications session, SNA uses Logical Units (LUs) as entry points into the network. There are several types of LUs: the e*Way Intelligent Adapter for SNA supports LU0, LU1, LU2, LU3, and LU6.2 on all supported operating systems (see Supported Operating Systems on page 16.

Like the OSI model, SNA functions are divided into seven hierarchical layers, but the layers are not identical. Their relationships to each other, and to the SNA node functionality, are shown in Figure 2. The Transport Network handles the lower three layers, while the Network Accessible Units (NAU) implement the upper four layers by using the services of the Transport Network to establish communication between nodes.

SNA Node

End User Logical Unit(LU)

Pysical Unit(PU) Data Link SNA

Network


Chapter 1 Section 1.1Introduction SNA Architectural Overview

Figure 2 SNA Functional Layers

SNA defines formats and protocols between these layers that allow equivalent layers in different nodes to communicate with each other. Also, each layer provides services to the layer above, and requests services from the layer below. As an example, the communication path between two Transmission Control layers would appear as shown in Figure 3.

User Process

Logical Unit

Physical Unit

Data Link

SNA Functions

Transaction Services

Presentation Services

Data Flow Control

Transmission Control

Path Control

Data Link Control

Physical Control

SNA Layers

Application

Presentation

Session

Transport

Network

Data Link

Physical

OSI Layers



Figure 3 Equivalent-Layer Communications Path

SNA uses a standard method for the exchange of data within a network. This standard method defines how to establish a route between components, how to send and receive data reliably, how to recover errors, and how to prevent flow problems.

Originally designed for networks in which a mainframe computer controls the communications relationships, SNA has since evolved to incorporate protocols and implementations to allow two user processes to communicate with each other directly. These two different networking models, or roles, are referred to as hierarchical and peer-oriented, respectively. The peer-oriented model is designed to allow distributed control of the communications process independent of the mainframe.

The peer-to-peer connection between two user processes is known as a conversation, while the peer-to-peer connection between two LUs is known as a session. A session is



Data Flow Control


Path Control

Data Link Control

Physical Control

SNA Node A



Data Flow Control


Path Control

Data Link Control

Physical Control

SNA Node B



generally a long-term connection between two LUs, while a conversation is generally of shorter duration.

Figure 4 Sessions and Conversations

What is shown in Figure 2 and Figure 4 as a User Process is also known as a Transaction Program (TP). Also, the interface between a User Process and an LU is known as Presentation Services.

1.1.1 Supported Logical Unit Types

SNA LU6.2

LU 6.2, also known as APPC (Advanced Program-to-Program Communication), is used for Transaction Programs communicating with each other in a distributed data processing environment. In a CPIC (Common Programming Interface for Communications) implementation, CPIC provides the API that contains the commands, known as verbs, that are used by LU 6.2 to establish communication sessions.

Two types of Presentation Service interfaces are possible with LU6.2: mapped conversations and unmapped, or basic, conversations. Table 1 summarizes the set of LU6.2 commands for basic conversations. Equivalent commands for mapped conversations have the prefix <MC_> added to the command name. Note that “control operator verbs” are not listed.

User Process

Logical Unit

Physical Unit

Data Link

SNA Node X

User Process

Logical Unit

Physical Unit

Data Link

SNA Node Y

Conversation

Session



SNA LUA

The e*Way Intelligent Adapter for SNA uses the Conventional Logical Unit Application (LUA) interface from Data Connection Limited to communicate with LU0, LU1, LU2, and LU3 hosts, using their SNAP-IX SNA function library.. The LUA interface acts at the request/response unit (RU) level, and supports an extensive set of functions.

SNA LU0

The e*Way Intelligent Adapter for SNA also supports the LU0 interface from Data Connection Limited to communicate with LU0 hosts. This provides a less complex interface, supporting a subset of the functions contained in the LUA interface.

Table 1 LU6.2 Commands

Name Description

ALLOCATE Allocates a conversation with another program.

CONFIRM Sends a confirmation request to the remote process and waits for a reply.

CONFIRMED Sends a confirmation reply to the remote process.

DEALLOCATE De-allocates a conversation.

FLUSH Forces the transmission of the local SEND buffer to the other LU.

GET_ATTRIBUTES Obtains information about a conversation.

PREPARE_TO_RECEIVE Changes the conversation state from SEND to RECEIVE.

RECEIVE_AND_WAIT Waits for information (either data or confirmation request) to be received from the partner process.

RECEIVE_IMMEDIATE Receives any information that is available in the local LU’s buffer, but does not wait for information to arrive.

REQUEST_TO_SEND Notifies the partner process that the local process wants to send data. When a “send” indication is received from the partner process, the conversation state changes.

SEND_DATA Sends one data record to the partner process.

SEND_ERROR Informs the partner process that the local process has detected an application error.


Chapter 1 Section 1.2Introduction SNA e*Way Overview

1.2 SNA e*Way OverviewThe SNA e*Way is an interface that makes uni-directional calls to an SNA Server. The SNA Server acts as a high-speed gateway between distributed SNA Clients and the SNA network having a mainframe host system (see Figure 5).

The SNA e*Way enables the SeeBeyond e*Gate Integrator system to access an SNA network environment to drive entire transactions, including conversational transactions. The connection requires a TCP/IP connection with, and the appropriate link service to, the SNA server in use. The SNA Client and the e*Gate Participating Host reside on the same platform.

In a typical data exchange using the SNA e*Way, the e*Way invokes either the LU6.2 or LU0 protocol to enable the SNA client to send requests to the SNA server.

Figure 5 SNA Data Exchange

Note: The SNA e*Way does not support bi-directional transaction calls. Two e*Ways must be configured to handle inbound and outbound data transfer.

1.2.1 e*Way ComponentsThe SNA e*Way incorporates the following components:

� stcewgenericmonk.exe, the executable component (installed with e*Gate)

� Configuration files, which the e*Way Editor uses to define configuration parameters

� Monk function scripts, discussed in Chapter 8.

For a list of installed files, see Chapter 2.

IDC

SNAProtocol

ClientMainframe

SNAProtocolServer

SNA Network

TP 1 TP 2

LAN


Chapter 2

Installation

This chapter describes the requirements and procedures for installing the e*Way Intelligent Adapter for SNA. Following installation, you must configure it for your system and incorporate it into a schema (see Chapter 3).

2.1 System RequirementsTo use the e*Way Intelligent Adapter for SNA, you need the following:

1 An e*Gate Participating Host, version 4.5.1 or later.

2 A TCP/IP network connection.

3 Sufficient free disk space to accommodate e*Way files:

� Approximately 200 KB on Windows systems

� Approximately 400 KB on Solaris systems

� Approximately 200 KB on AIX systems

Note: Additional disk space is required to process and queue the data that this e*Way processes; the amount necessary varies, based on the type and size of the data being processed.

2.1.1 Supported Operating Systems

Note: The e*Gate Enterprise Manager GUI runs only on the Windows operating system.

The e*Way Intelligent Adapter for SNA is available for the following operating systems:

� Windows 2000, Windows 2000 SP1, or Windows 2000 SP2

� Windows NT 4.0 SP 6a

� Solaris 2.6, Solaris 7, and Solaris 8

� AIX 4.3.3


Chapter 2 Section 2.2Installation External System Requirements

2.2 External System Requirements

2.2.1 SNA LU6.2To enable the e*Way to communicate properly with the SNA Server system, the following are required:

� Microsoft SNA Server 4.0 client

� Administrative access to the SNA server

� Sunlink SNA Server 9.1 (Solaris)

� IBM Communication Server 6.0 (AIX)

� CPI-C version 1.2

� Appropriate link service for the SNA Server in use

2.2.2 SNA LU0, LU1, LU2, LU3To enable the e*Way to communicate properly with an SNA LU0, LU1, LU2, or LU3 Server system, the following is required:

� Data Connection Limited’s SNAP-IX library

2.2.3 Solaris Patch Requirements Solaris operating systems require the following SNA version 9.1 patches before the SNA e*Way can be installed. If the patch is not installed, the setup program detects it.

These patches are available from Sun (see Table below), from downloaded from:

http://sunsolve.sun.com

Table 2 Sun-Solaris Patches

Once these patches have been installed, the configuration file shows two pu2s. Use vi to edit out one of the pu2s. Each time the configuration is changed, you must start up the sunsetup script:

<fullpath>/opt/SUNWpu21/.sunsetup

The sunsetup menu provides a list of options.

1 Select Option 6 (stop pu21).

Package SNA component Patch

SUNWpu21 pu21server 106162-29

SUNWgman gateway mngr 106164-15

SUNWgmi configuration gui 106165-09

SUNWlu62 lu62 configs 105860-23


Chapter 2 Section 2.3Installation External Configuration Requirements

2 Select Option 7 (stop gman).

3 Select Option 4 (start gman).

Note: When bringing down the SNA server, you must invoke option 6 and 7, but in bringing up the SNA server, you must invoke option 4. The gman automatically brings up your active SNA configuration.

2.3 External Configuration Requirements

Note: The configuration steps mentioned below are presented as a general guideline for configuring the SNA system, and are not to be considered complete. Please refer to your SNA Administration guide for detailed information on SNA System Configuration. Each platform requires different parameters and information.

2.3.1 Configuring the SNA Server and Client

All Platforms

You must configure both the partner and the remote SNA systems to have an active connection. Use the following procedure as a guide.

1 Configure a link station or service for the remote and partner system. This can be an Ethernet or Token ring link for the LAN connection. Links vary for SDLC, QLLC and channel connections.

2 Configure a local LU and a remote LU definition on each system. You need the physical machine address, the control point name, or full computer name, and the network name.

3 Define a mode on the remote and local SNA system. This mode name must be the same on both systems in order to have an active connection and for the data to be transferred.

4 Define a Symbolic Destination Name and Transaction Program (TP) name on both systems. The names must match in order for the TPs to communicate with each other. You must select the correct mode name for each TP name.

5 The status flag for DEALLOCATE must be a 4. You must set your external system to send or receive this flag for the e*Way to process a shutdown.

Additional Procedures for Solaris

1 Create an information file that the e*Way can access. This file should have the same name as entered for the e*Way’s SYMDESTNAME parameter.

2 Set the appropriate environmental variables for APPC_GATEWAY and APPC_LOCA_LU.


Chapter 2 Section 2.4Installation Installing the e*Way

2.4 Installing the e*Way

2.4.1 Windows Systems

Installation Procedure

Note: The installation utility detects and suggests the appropriate installation directory. Use this directory unless advised otherwise by SeeBeyond. You must have Administrator privileges to install this e*Way.

To install the e*Way on a Windows NT or Windows 2000 system

1 Log in as an Administrator on the workstation on which you want to install the e*Way.

2 Exit all Windows programs and disable any anti-virus applications before running the setup program.

3 Insert the e*Way installation CD-ROM into the CD-ROM drive.

4 If the CD-ROM drive’s Autorun feature is enabled, the setup application should launch automatically. Otherwise, use the Windows Explorer or the Control Panel’s Add/Remove Applications feature to launch the file setup.exe on the CD-ROM drive.

5 The InstallShield setup application launches. Follow the on-screen instructions until you come to the Choose Product screen.

Figure 6 Choose Product Dialog

6 Check Add-ons, then click Next. Again follow the on-screen instructions.



7 When the Select Components dialog box appears, highlight—but do not check—eWays and then click Change.

Figure 7 Select Components Dialog

8 When the Select Sub-components dialog box appears, check the SNA e*Way.

Figure 8 Select e*Way Dialog

9 Click Continue, and the Select Components dialog box reappears.

10 Click Next and continue with the installation.



Subdirectories and Files

By default, the InstallShield installer creates the following subdirectories and installs the following files within the \eGate\client tree on the Participating Host, and the \eGate\Server\registry\repository\default tree on the Registry Host.

By default, the InstallShield installer also installs the following file within the \eGate\Server\registry\repository\default tree on the Registry Host.

Environment Configuration

No changes are required to the Participating Host’s operating environment to support this e*Way.

Table 3 Participating Host & Registry Host

Subdirectories Files

\bin\ stc_monksna.dll

\configs\stcewgenericmonk\ stcewsna.defstcewsnalu0.def

\monk_library\ ewsna.gui

\monk_library\ewsna\ sna-conn-establish.monksna-conn-shutdown.monksna-conn-verify.monksna-incoming.monksna-init.monksna-neg-ack.monksna-outgoing.monksna-pos-ack.monksan-shutdown.monksna-startup.monk

Table 4 Registry Host Only


\ stcewsna.ctl



2.4.2 UNIX Systems

Installation Procedure

Note: You are not required to have root privileges to install this e*Way. Log on under the user name that you wish to own the e*Way files. Be sure that this user has sufficient privilege to create files in the e*Gate directory tree.

To install the e*Way on a UNIX system

1 Log onto the workstation containing the CD-ROM drive and, if necessary, mount the drive.

2 Insert the e*Way installation CD-ROM into the CD-ROM drive.

3 At the shell prompt, type

cd /cdrom

4 Start the installation script by typing:

setup.sh

5 A menu appears, containing several options. Select the Install e*Way option, and follow any additional on-screen directions.

Note: The installation utility detects and suggests the appropriate installation directory. Use this directory unless advised otherwise by SeeBeyond. Note also that no spaces should appear in the installation path name.



Subdirectories and Files

The preceding installation procedure creates the following subdirectories and installs the following files within the /eGate/client tree on the Participating Host, and the /eGate/Server/registry/repository/default tree on the Registry Host.

The preceding installation procedure also installs the following file only within the /eGate/Server/registry/repository/default tree on the Registry Host.

Environment Configuration

No changes are required to the Participating Host’s operating environment to support this e*Way.

Table 5 Participating Host & Registry Host


/bin/ stc_monksna.dll

/configs/stcewgenericmonk/ stcewsna.defstcewsnalu0.def

/monk_library/ ewsna.gui

/monk_library/ewsna/ sna-conn-establish.monksna-conn-shutdown.monksna-conn-verify.monksna-incoming.monksna-init.monksna-neg-ack.monksna-outgoing.monksna-pos-ack.monksan-shutdown.monksna-startup.monk

Table 6 Registry Host Only


/ stcewsna.ctl


Chapter 3

Implementation

In this chapter we summarize the procedures required for implementing a working system incorporating the Java-enabled e*Way Intelligent Adapter for SNA. Please refer to the e*Gate Integrator User’s Guide for additional information.

3.1 OverviewThis e*Way provides a specialized transport component for incorporation into an operational Schema. The schema also contains Collaborations, linking different data or Event types, and Intelligent Queues. Typically, other e*Way types also are used as components of the Schema.

Note: The SNA e*Way does not support bi-directional transactions. Two e*Ways must be configured to handle inbound and outbound data transfer.


Chapter 3 Section 3.1Implementation Overview

3.1.1 Implementation Sequence

1 The first step is to create a new Schema—the subsequent steps apply only to this Schema (see Creating a Schema on page 27).

2 The second step is to define the Event Types you are transporting and processing within the Schema (see Creating Event Types on page 28).

3 Third, you need to associate the Event Types created in the previous step with Event Type Definitions (ETDs) derived from the applicable Business Rules (see Creating Event Type Definitions on page 28).

4 The fourth step is to create and configure the required e*Ways (see Chapter 4).

5 Next is to define and configure the Collaborations linking the Event Types from step 2 (see Defining Collaborations on page 30).

6 Now you need to create Intelligent Queues to hold published Events (see Creating Intelligent Queues on page 31

7 Finally, you must test your Schema. Once you have verified that it is working correctly, you may deploy it to your production environment.

Define & ConfigureCollaborations

Create & Configuree*Ways

Create Schema

Generate Event TypeDefinitions

Test & Deploy

Define Event Types

CreateIntelligent Queues


Chapter 3 Section 3.2Implementation The e*Gate Enterprise Manager

3.2 The e*Gate Enterprise Manager First, here is a brief look at the e*Gate Enterprise Manager. The general features of the e*Gate Enterprise Manager window are shown in Figure 9. See the e*Gate Integrator User’s Guide for a detailed description of the features and use of the Enterprise Manager.

Figure 9 e*Gate Enterprise Manager Window (Components View)

Use the Navigator and Editor panes to view the e*Gate components. Note that you may only view components of a single schema at one time, and that all operations apply only to the current schema. All procedures in this chapter should be performed while displaying the Components Navigator pane.

Editor Pane

Navigator Pane

Palette


Chapter 3 Section 3.3Implementation Creating a Schema

3.3 Creating a SchemaA schema is the structure that defines e*Gate system parameters and the relationships between components within the e*Gate system. Schemas can span multiple hosts.

Because all setup and configuration operations take place within an e*Gate schema, a new schema must be created, or an existing one must be started before using the system. Schemas store all their configuration parameters in the e*Gate Registry.

To select or create a schema

1 Invoke the Open Schema dialog box and Open an existing schema or click New to create a new schema.

Figure 10 Open Schema Dialog

2 Enter a new schema name and click Open.

3 The e*Gate Enterprise Manager then opens under your new schema name.

4 From the Options menu, click on Default Editor and select Monk.

5 Select the Components tab, found at the bottom of the Navigator pane of the e*Gate Enterprise Manager window.

6 You are now ready to begin creating the necessary components for this new schema.


Chapter 3 Section 3.4Implementation Creating Event Types

3.4 Creating Event TypesWithin e*Gate, messages and/or packages of data are defined as Events. Each Event must be categorized into a specific Event Type within the schema.

To define the Event Types

1 In the e*Gate Enterprise Manager’s Navigator pane, select the Event Types folder.

2 On the Palette, click the New Event Type button .

3 In the New Event Type Component box, enter the name for the input Event Type and click Apply. Use this method to create all required Event Types, for example:

� InboundEvent

� ValidEvent

� InvalidEvent

4 After you have created the final Event Type, click OK.

3.5 Creating Event Type Definitions Each Event Type now must be associated with an Event Type Definition within the schema. In general, you select an existing ETD or create a new one based on an existing template. See the e*Gate Integrator User’s Guide for additional information.

To create an Event Type Definition

1 In the e*Gate Event Type Editor, select Build.

2 In the Build an Event Type Definition dialog box, locate and select an ETD to use as a template.

3 Edit the ETD properties as needed.

4 Rename and save as a new ETD (.ssc file).

3.5.1 Assigning ETDs to Event Types After you have created the e*Gate system’s ETD files, you can assign them to existing Event Types.

To assign ETDs to Event Types

1 In the Enterprise Manager window, select the Event Types folder in the Navigator/Components pane.

2 In the Editor pane, select one of the Event Types you created.

3 Right-click on the Event Type and select Properties (or click in the toolbar).

The Event Type Properties dialog box appears. See Figure 11.


Chapter 3 Section 3.5Implementation Creating Event Type Definitions

Figure 11 Event Type Properties Dialog Box

4 Under Event Type Definition, click Find, and the Event Type Definition Selection dialog box appears (it is similar to the Windows Open dialog box).

5 Open the monk_scripts\common folder, then select the desired file name (*.ssc).

6 Click Select. The file populates the Event Type Definition field.

7 To save any work in the properties dialog box, click Apply to enter it into the system.

8 When finished assigning ETDs to Event Types, click OK to close the properties dialog box and apply all the properties.

Each Event Type is now associated with the specified Event Type Definition.


Chapter 3 Section 3.6Implementation Defining Collaborations

3.6 Defining Collaborations After you have created the required Event Type Definitions, you must define a Collaboration to transform the incoming Event into the desired outgoing Event.

Collaborations are e*Way components that receive and process Event Types, then forward the output to other e*Gate components. Collaborations consist of the Subscriber, which “listens” for Events of a known type or from a given source, and the Publisher, which distributes the transformed Event to a specified recipient. The same Collaboration cannot be assigned to more than one e*Gate component.

Figure 12 Collaborations

The Collaboration is driven by a Collaboration Rule script, which defines the relationship between the incoming and outgoing ETDs. You can use an existing Collaboration Rule script, or use the Monk programming language to write a new Collaboration Rule script. Once you have written and successfully tested a script, you can then add it to the system’s run-time operation.

Collaborations are defined using the e*Gate Monk Collaboration Rules Editor. See the e*Gate Integrator User’s Guide for instructions on using this Editor. The file extension for Monk Collaboration Rules is .tsc.

SNA e*Way

CollaborationEventA

EventB

Collaboration Rule

ETDA

ETDB


Chapter 3 Section 3.7Implementation Creating Intelligent Queues

3.7 Creating Intelligent Queues IQs are components that provide nonvolatile storage for Events within the e*Gate system as they pass from one component to another. IQs are intelligent in that they are more than just a “holding tank” for Events. They actively record information about the current state of Events.

Each schema must have an IQ Manager before you can add any IQs to it. You must create at least one IQ per schema for published Events within the e*Gate system. Note that e*Ways that publish Events externally do not need IQs.

For more information on how to add and configure IQs and IQ Managers, see the e*Gate Integrator System Administration and Operations Guide. See the e*Gate Integrator Intelligent Queue Services Reference Guide and the SeeBeyond JMS Intelligent Queue User’s Guide for complete information on working with IQs.


Chapter 3 Section 3.8Implementation Exception Handling

3.8 Exception HandlingThe SNA e*Way handles an external (remote) shutdown request by confirming the request and throwing an application-specific exception. Specifically, if the remote application issues a deallocate, the e*Way then throws the exception $Sna-Exception-Fatal back to the calling Monk function. Please refer to the Exception Functionality chapter of the Monk Developers Reference for details on catching exceptions.

Example Code

The following code sample, from the monk script sna_incoming.monk, demonstrates how to catch this exception and issue a shutdown request to shut the e*Way down.

(if (string=? SNA_CONFIGURATION_SYNCHRONIZATION_LEVEL "NONE") (begin (try (set! pszData (sna-client-recv-no-synch hCon SNA_CONFIGURATION_PACKETSIZE SNA_CONFIGURATION_TIMEOUT)) (catch (($Sna-Exception-Fatal) (display (string-append "Exception string: " (exception-string) ".")) (newline) (display "Caught Fatal Exception - calling shutdown\n") (shutdown-request) ) (otherwise (display (string-append "Exception category: " (number->string (exception-category)) ".")) (newline) (display (string-append "Exception symbol: " (symbol->string (exception-symbol)) ".")) (newline) (display (string-append "Exception string: " (exception-string) ".")) (newline) ) ); catch ); try ); begin


Chapter 3 Section 3.9Implementation Enabling TP Trace

3.9 Enabling TP TraceOn Solaris only, SNA LU6.2 TP trace can be turned on by setting the following environment variable (if in C shell) prior to starting the e*Way:

setenv SUNLINK_CNT_API_TRACE 1 export SUNLINK_CNT_API_TRACE

A TP trace is written to the current directory.

3.10 Known Issues and Limitations1 SNA e*Ways that send initialization must be started after the accepting program is

ready to accept.

2 The status flag for deallocate must be a 4. You must set your external system to send or receive this flag for the e*Way to process a shutdown.

3 Issuing a shutdown while running in Non-Confirmed mode shuts down only the e*Way to which you issued the command. Issuing a shutdown while running in Confirmed mode shuts down the e*Way to which you issued the command and the associated e*Way.




Chapter 4

Setup Procedures

This chapter describes the procedures required to customize the SeeBeyond e*Way Intelligent Adapter for SNA to operate within your production system.

4.1 OverviewAfter installing the SNA e*Way, you must instantiate and configure it to work with your system. A wide range of setup options allow the e*Way to conform to your system’s operational characteristics and your facility’s operating procedures.

The topics discussed in this chapter include the following:

Setting Up the e*Way

Creating the e*Way on page 35

Modifying e*Way Properties on page 36

Configuring the e*Way on page 37

Changing the User Name on page 41

Setting Startup Options or Schedules on page 41

Activating or Modifying Logging Options on page 43

Activating or Modifying Monitoring Thresholds on page 44

Troubleshooting the e*Way

Configuration Problems on page 45

System-related Problems on page 46

Chapter 4 Section 4.2Setup Procedures Setting Up the e*Way



4.2 Setting Up the e*Way

Note: The SNA e*Way does not support bidirectional transactions. Two e*Ways must be configured to handle inbound and outbound data transfer.

4.2.1 Creating the e*Way The first step in implementing an e*Way is to define the e*Way component using the e*Gate Enterprise Manager.

To create an e*Way

1 Open the schema in which the e*Way is to operate.

2 Select the e*Gate Enterprise Manager Navigator's Components tab.

3 Open the host on which you want to create the e*Way.

4 Select the Control Broker you want to manage the new e*Way.

Figure 13 e*Gate Enterprise Manager Window (Components View)

5 On the Palette, click Create a New e*Way.

6 Enter the name of the new e*Way, then click OK.

7 All further actions are performed in the e*Gate Enterprise Manager Navigator's Components tab.




4.2.2 Modifying e*Way Properties To modify any e*Way properties

1 Right-click on the desired e*Way and select Properties to edit the e*Way’s properties. The properties dialog opens to the General tab (shown in Figure 14).

Note: The executable and default configuration files used by this e*Way are listed in e*Way Components on page 15.

Figure 14 e*Way Properties (General Tab)

2 Make the desired modifications, then click OK.




4.2.3 Configuring the e*Way The e*Way’s default configuration parameters are stored in an ASCII text file with a .def extension. The e*Way Editor provides a simple graphical interface for viewing and changing those parameters to create a working configuration (.cfg) file.

To change e*Way configuration parameters

1 In the e*Gate Enterprise Manager’s Component editor, select the e*Way you want to configure and display its properties.

Note: The executable and default configuration files used by this e*Way are listed in e*Way Components on page 15.

Figure 15 e*Way Properties - General Tab

2 Under Configuration File, click New to create a new file or Find to select an existing configuration file. If you select an existing file, an Edit button appears. Click this button to edit the currently selected file.

3 You are now in the e*Way Configuration Editor.




Using the e*Way Editor

Note: The e*Gate Enterprise Manager GUI runs only on the Windows operating system.

Figure 16 The e*Way Configuration Editor

The e*Way Editor controls fall into one of six categories:

� The Menu bar allows access to basic operations (e.g., saving the configuration file, viewing a summary of all parameter settings, and launching the Help system)

� The Section selector at the top of the Editor window enables you to select the category of the parameters you wish to edit

� Section controls enable you to restore the default settings, restore the last saved settings, display tips, or enter comments for the currently selected section

� The Parameter selector allows you to jump to a specific parameter within the section, rather than scrolling

� Parameter controls enable you to restore the default settings, restore the last saved settings, display tips, or enter comments for the currently selected parameter

� Parameter configuration controls enable you to set the e*Way’s various operating parameters

Section controls

Parameter selector

Parametercontrols

Section selector

Menu Bar

Parameter configuration area




Section and Parameter Controls

The section and parameter controls are shown in Table 7 below.

Table 7 Parameter and Section Controls

Note: The section controls affect all parameters in the selected section, whereas the parameter controls affect only the selected parameter.

Parameter Configuration Controls

Parameter configuration controls fall into one of two categories:

� Option buttons

� Selection lists, which have controls as described in Table 8

Table 8 Selection List Controls

Button Name Function

Restore Default Restores default values

Restore Value Restores saved values

Tips Displays tips

User Notes Enters user notes

Button Name Function

Add to List Adds the value in the text box to the list of available values.

Delete Items Displays a “delete items” dialog box, used to delete items from the list.




Command-line Configuration

In the Additional Command Line Arguments box, type any additional command line arguments that the e*Way may require, taking care to insert them at the end of the existing command-line string. Be careful not to change any of the default arguments unless you have a specific need to do so.

Getting Help

To launch the e*Way Editor’s Help system

From the Help menu, select Help topics.

To display tips regarding the general operation of the e*Way

From the File menu, select Tips.

To display tips regarding the selected Configuration Section

In the Section Control group, click .

To display tips regarding the selected Configuration Parameter

In the Parameter Control group, click .

Note: “Tips” are displayed and managed separately from the Help system that launches from the Toolbar’s Help menu. You cannot search for Tips within the Help system, or view Help system topics by requesting Tips.

For detailed descriptions and procedures for using the e*Way Configuration Editor, see the e*Gate Integrator User’s Guide.




4.2.4 Changing the User Name Like all e*Gate executable components, e*Ways run under an e*Gate user name. By default, all e*Ways run under the Administrator user name. You can change this if your site’s security procedures so require.

To change the user name

1 Display the e*Way’s properties dialog.

2 On the General tab, use the Run as user list to select the e*Gate user under whose name this component is to run.

See the e*Gate Integrator System Administration and Operations Guide for more information on the e*Gate security system.

4.2.5 Setting Startup Options or SchedulesSeeBeyond e*Ways can be started or stopped by any of the following methods:

� The Control Broker can start the e*Way automatically whenever the Control Broker starts.

� The Control Broker can start the e*Way automatically whenever it detects that the e*Way terminated execution abnormally.

� The Control Broker can start or stop the e*Way on a schedule that you specify.

� Users can start or stop the e*Way manually using an interactive monitor.

You determine how the Control Broker starts or shuts down an e*Way using options on the e*Way properties Start Up tab (see Figure 17). See the e*Gate Integrator System Administration and Operations Guide for more information about how interactive monitors can start or shut down components.




Figure 17 e*Way Properties (Start-Up Tab)

To set the e*Way’s startup properties


2 Select the Start Up tab.

3 To have the e*Way start automatically when the Control Broker starts, select the Start automatically check box.

4 To have the e*Way start manually, clear the Start automatically check box.

5 To have the e*Way restart automatically after an abnormal termination:

A Select Restart after abnormal termination.

B Set the desired number of retries and retry interval.

6 To prevent the e*Way from restarting automatically after an abnormal termination, clear the Restart after abnormal termination check box.

7 Click OK.




4.2.6 Activating or Modifying Logging OptionsLogging options enable you to troubleshoot problems with the e*Way and other e*Gate components.

To set the e*Way debug level and flag

1 Display the e*Way’s Properties dialog.

2 Select the Advanced tab.

3 Click Log. The dialog window appears (see Figure 18).

Figure 18 e*Way Properties (Advanced Tab - Log Option)

4 Select DEBUG for the Logging level.

5 Select either e*Way (EWY) or e*Way Verbose (EWYV) for the Debugging flag. Note that the latter has a significant negative impact on system performance.

6 Click OK.

The other options apply to other e*Gate components and are activated in the same manner. See the e*Gate Integrator Alert and Log File Reference for additional information concerning log files, logging options, logging levels, and debug flags.




4.2.7 Activating or Modifying Monitoring ThresholdsMonitoring thresholds enable you to monitor the throughput of the e*Way. When the monitoring thresholds are exceeded, the e*Way sends a Monitoring Event to the Control Broker, which routes it to the e*Gate Monitor and any other configured destinations.


2 Select the Advanced tab.

3 Click Thresholds.

4 Select the desired threshold options and click OK.

See the e*Gate Integrator Alert and Log File Reference for more information concerning threshold monitoring, routing specific notifications to specific recipients, or for general information about e*Gate’s monitoring and notification system.

Chapter 4 Section 4.3Setup Procedures Troubleshooting the e*Way



4.3 Troubleshooting the e*WayIn the initial stages of developing your e*Gate Integrator system administration system, most problems with e*Ways can be traced to configuration.

4.3.1 Configuration ProblemsIn the Enterprise Manager

� Does the e*Way have the correct Collaborations assigned?

� Do those Collaborations use the correct Collaboration Services?

� Is the logic correct within any Collaboration Rules script employed by this e*Way’s Collaborations?

� Do those Collaborations subscribe to and publish Events appropriately?

� Are all the components that “feed” this e*Way properly configured, and are they sending the appropriate Events correctly?

� Are all the components that this e*Way “feeds” properly configured, and are they subscribing to the appropriate Events correctly?

In the e*Way Editor

� Check that all configuration options are set appropriately.

� Check that all settings you changed are set correctly.

� Check all required changes to ensure they have not been overlooked.

� Check the defaults to ensure they are acceptable for your installation.

On the e*Way’s Participating Host

� Check that the Participating Host is operating properly, and that it has sufficient disk space to hold the IQ data that this e*Way’s Collaborations publish.

� Check that the PATH (on Windows) or LD_LIBRARY_PATH (on UNIX) environmental variable includes a path to the PeopleSoft dynamically-loaded libraries.

In the External Application

� Check that the application is configured correctly, is operating properly, and is sending or receiving the correct data appropriately.

Chapter 4 Section 4.3Setup Procedures Troubleshooting the e*Way



4.3.2 System-related Problems� Check that the connection between the external application and the e*Way is

functioning appropriately.

� Once the e*Way is up and running properly, operational problems can be due to:

� External influences (network or other connectivity problems).

� Problems in the operating environment (low disk space or system errors)

� Problems or changes in the data the e*Way is processing.

� Corrections required to Collaboration Rules scripts that become evident in the course of normal operations.

One of the most important tools in the troubleshooter’s arsenal is the e*Way log file. See the e*Gate Integrator Alert and Log File Reference Guide for an extensive explanation of log files, debugging options, and using the e*Gate monitoring system to monitor operations and performance.

Chapter 5

Operational Overview

This chapter contains an overview of the architecture and basic internal processes of the SNA e*Way.

5.1 e*Way ArchitectureConceptually, an e*Way can be viewed as a multi-layered structure, consisting of one or more layers (see Figure 19). Each layer contains Monk scripts and/or functions, and makes use of lower-level Monk functions residing in the layer beneath. You, as user, primarily use the highest-level functions, which reside in the upper layer(s).

Figure 19 Typical e*Way Architecture

The upper layers of the e*Way use Monk functions to perform Business Process modeling and ETD mapping, package data as e*Gate Events, send those Events to Collaborations, and manage interaction with the external system. These layers are built upon an e*Way Kernel layer that manages the basic operations of the e*Way, data processing, and communication with other e*Gate components.

Additional Layer(e.g., API Model)

Communications Layer(e.g., RFC Transport)

e*Way Kernel Layer

e*GateExternalApplication

PUB/SUB

RFC

Typical e*Way



Chapter 5 Section 5.1Operational Overview e*Way Architecture

The communication layers of the e*Way are single-threaded. Functions run serially, and only one function can be executed at a time. Processing layers are multi-threaded, with one executable thread for each Collaboration. Each thread maintains its own Monk environment; therefore, information such as variables, functions, path information, and so on cannot be shared between threads.

Collaborations execute the business logic that enable the e*Way to do its intended work. In turn, each Collaboration executes a Collaboration Rule, containing the actual instructions to execute the business logic. Each Collaboration that publishes its processed Events internally (within e*Gate Integrator) requires one or more IQs to receive the Events, as shown in Figure 20. Any Collaboration that publishes its processed Events only to an external system does not require any IQs.

Figure 20 Collaborations and IQs

Configuration options that control the Monk environment and define the Monk functions used to perform various e*Way operations are discussed in Chapter 6 and Chapter 7. You can create and modify these functions using the SeeBeyond Collaboration Rules Editor or a text editor (such as Microsoft Word or Notepad, or UNIX vi). The available set of e*Way API functions is described in Chapter 8. Generally, e*Way Kernel Monk functions should be called directly only when there is a specific need not addressed by higher-level Monk functions, and should be used only by experienced developers.

For more information on defining Collaborations, defining IQs, assigning Collaborations to e*Ways, or configuring Collaborations to publish Events, see the e*Gate Integrator User’s Guide.

e*Gate Integrator

SNAServer

SNA e*Way(Inbound)

CollaborationEventA

EventB

Collaboration Rule

IntelligentQueue

ETDA

ETDB



Chapter 5 Section 5.2Operational Overview Basic e*Way Processes

5.2 Basic e*Way Processes

Note: This section describes the basic operation of a typical e*Way based on the Generic e*Way Kernel. Not all functionality described in this section is used routinely by this e*Way.

The most basic processes carried out by an e*Way are listed in Figure 21. In e*Ways based on the Generic Monk e*Way Kernel (using stcewgenericmonk.exe), these processes are controlled by the listed Monk functions. Configuration of these functions is described in the referenced sections of this User’s Guide.

Figure 21 Basic e*Way Processes

A series of diagrams on the next several pages illustrate the interaction and operation of these functions during the specified processes. Configuring the parameters associated with these functions is covered in Chapter 6 and Chapter 7, while the functions themselves are described in Chapter 8.

Process Monk Configuration Sections

Startup Function on page 64 and on page 82 (also see Monk Environment Initialization File on page 63 and on page 81).

External Connection Establishment Function on page 66 and on page 84, andExternal Connection Verification Function on page 67 and on page 85.

Event-driven Data ExchangeProcess Outgoing Message Function on page 64 and on page 82.

Schedule-driven Data ExchangeExchange Data with External Function on page 65 and on page 83;Positive Acknowledgment Function on page 68 and on page 86;Negative Acknowledgment Function on page 68 and on page 86.

External Connection Shutdown Function on page 67 and on page 85.

Shutdown Command Notification Function on page 69 and on page 87.

Connection toExternal System

Data Exchange

Disconnection fromExternal System

e*Way Shutdown

e*Way Initialization




Initialization Process

Figure 22 illustrates the e*Way’s initialization process, using the Monk Environment Initialization File and Startup Function.

Figure 22 Initialization Process

Start e*Way

LoadMonk Initialization

file

Execute any Monk functionhaving the same name as

the initialization file

Load Startup file

Execute any Monk functionhaving the same name as

the startup file




Connect to External Process

Figure 23 illustrates how the e*Way connects to the external system, using the External Connection Establishment Function and External Connection Verification Function.

Figure 23 Connection Process

Note: The e*Way selects the connection function based on an internal up/down flag rather than a poll to the external system. See Figure 25 on page 53 and Figure 24 on page 52 for examples of how different functions use this flag.

User functions can manually set this flag using Monk functions. See send-external-up on page 122 and send-external-down on page 122 for more information.

Connect e*Way toexternal system

Is connection active?

Wait for Up Timeoutschedule

Call External ConnectionVerification function

Wait for Down Timeoutschedule

Call External ConnectionEstablishment function

Yes

No




Data Exchange Process

Event-driven

Figure 24 illustrates how the e*Way’s event-driven data exchange process works, using the Process Outgoing Message Function.

The e*Way periodically checks the Failed Message counter against the value specified by the Max Failed Messages parameter. When the Failed Message counter exceeds the specified maximum value, the e*Way logs an error and shuts down.

After the function exits, the e*Way waits for the next outgoing Event.

Figure 24 Event-Driven Data Exchange Process

Collaboration publishesto External system

Call Process OutgoingMessage function

Set internal flagConnection Down

MaximumResends per Message

exceeded?

Yes

Return

CONNERR DATAERR

Increment FailedMessage counter

Create journalentry

Nullstring

NoJournal

enabled?

No

Function exits

Wait for ResendTimeout period

Roll back Event toits publishing IQ

Yes

Wait for ResendTimeout period

IncrementResend counter

RESEND




Schedule-driven

Figure 25 illustrates how the e*Way’s schedule-driven data exchange process works for incoming data, using the Exchange Data with External Function, Positive Acknowledgment Function, and Negative Acknowledgment Function.

Figure 25 Schedule-Driven Data Exchange Process


DATAERR plusadditional data

Nullstring

Data(other than

error strings)

Forwardexternalerrors?

No

Yes

Set interval flagConnection Down

CONNERR


DATAERR only

Journalenabled?

Create journalentry

Yes

No

Start

Function exits

Send Event toe*Gate

Allsubscribing

Collaborations returnTRUE

?

Call PositiveAcknowledgment

function

Zerowait after successful

exchange?

Call NegativeAcknowledgment

function

Yes

No

YesNo

CallExchange Data with External

function

Return




Start can occur in any of the following ways:

� Start Data Exchange time occurs

� Periodically during data-exchange schedule (after Start Data Exchange time, but before Stop Data Exchange time), as set by Exchange Data Interval

� The start-schedule Monk function is called

Send Events to e*Gate can be implemented using any of the following Monk functions:

� event-send-to-egate

� event-send-to-egate-ignore-shutdown

� event-send-to-egate-no-commit

The last of these is used when confirmation of correct transmission is required from the external system. In this case, the e*Way sends information back to the external system after receiving data. Depending upon whether the acknowledgment is positive or negative, you subsequently use one of the following functions to complete the process (see Figure 26):

� event-commit-to-egate

� event-rollback-to-egate

Figure 26 Send Event to e*Gate with Confirmation

After the function exits, the e*Way waits for the next Start time or command.

ExternalSystem

e*Way

REPLY FUNCTION

(event-commit-to-egate)

(event-rollback-to-egate)

e*Gate IQManager

Results

NegativeConfirmation

PositiveConfirmation

CommitPreviously-Sent Event

Roll BackPreviously-Sent Event

(event-send-to-egate-no-commit)DATA

Send EventWithout

Committing




Disconnect from External Process

Figure 27 illustrates how the e*Way disconnects from the external system, using the External Connection Shutdown Function.

Figure 27 Disconnect Process

Shutdown Process

Figure 28 illustrates how the e*Way shuts itself down, using the Shutdown Command Notification Function.

Figure 28 Shutdown Process

Control Broker issuesSuspend command

Call External Connection Shutdown functionwith SUSPEND_NOTIFICATION parameter

e*Way closes connection

Return any value

Control Broker issuesShutdown command

Call Shutdown Notification functionwith SHUTDOWN_NOTIFICATION parameter

e*Way shuts down

Wait forshutdown-request

function

Return

Null string or"SUCCESS"

any other value

Call waiting-to-shutdownfunction

Inform External systemthat Shutdown command

has been issued

(Optional)



Chapter 6

Configuration Parameters (LU6.2)

This chapter describes the LU6.2 configuration parameters for the e*Way Intelligent Adapter for SNA.

6.1 Overview The e*Way’s configuration parameters are set using the e*Way Editor; see Configuring the e*Way on page 37 for procedural information. The SNA e*Way’s configuration parameters are organized into the following sections. The default configurations are provided in stcewsna.def.

General Settings on page 57

Communication Setup on page 59

Monk Configuration on page 62

SNA Client Configuration on page 71


Chapter 6 Section 6.2Configuration Parameters (LU6.2) General Settings

6.2 General Settings The General Settings control basic operational parameters.

Journal File Name

Description

Specifies the name of the journal file.

Required Values

A valid filename, optionally including an absolute path (for example, c:\temp\filename.txt). If an absolute path is not specified, the file is stored in the e*Gate SystemData directory. There is no default value for this parameter.

Additional Information

An Event is journaled for the following conditions:

� When the number of resends is exceeded (see Max Resends Per Message below)

� When its receipt is due to an external error, but Forward External Errors is set to No

See the e*Gate Integrator System Administration and Operations Guide for more information about file locations.

Max Resends Per Message

Description

Specifies the number of times the e*Way attempts to resend a message (Event) to the external system after receiving an error. When this maximum is reached, the e*Way waits for the number of seconds specified by the Resend Timeout parameter, and then rolls back the Event to its publishing IQ.

Required Values

An integer from 1 to 1,024 (omit the comma). The default value is 5.

Max Failed Messages

Description

Specifies the maximum number of failed Events that the e*Way allows. When the specified number of failed Events is reached, the e*Way shuts down and exits.

Required Values



Chapter 6 Section 6.2Configuration Parameters (LU6.2) General Settings

Forward External Errors

Description

Description

Selects whether or not error messages received from the external system that begin with the string “DATAERR” are queued to the e*Way’s configured queue. See Exchange Data with External Function on page 65 for more information.

Required Values

Yes or No. The default value, No, specifies that error messages are not to be forwarded.


Chapter 6 Section 6.3Configuration Parameters (LU6.2) Communication Setup

6.3 Communication Setup The Communication Setup parameters control the schedule by which the e*Way obtains data from the external system.

Note: The schedule you set using the e*Way’s properties in the Enterprise Manager controls when the e*Way executable runs. The schedule you set within the parameters discussed in this section (using the e*Way Editor) determines when data are exchanged. Be sure you set the "exchange data" schedule to fall within the "run the executable" schedule.

Exchange Data Interval

Description

Specifies the number of seconds the e*Way waits between calls to the Exchange Data with External Function during scheduled data exchanges.

Required Values



� If Zero Wait Between Successful Exchanges is set to Yes and the Exchange Data with External Function returns data, the setting of this parameter is ignored and the e*Way invokes the Exchange Data with External Function immediately

� If it is desired to invoke the Exchange Data with External Function again as soon as possible when data is not queued to e*Gate via the return mechanism, the e*Way Kernel Monk function insert-exchange-data-event can be called directly (prior to leaving the exchange function) to accomplish this

� If this parameter is set to zero, no exchange data schedule is set and the Exchange Data with External Function is never called

See also

Start Exchange Data Schedule on page 60

Stop Exchange Data Schedule on page 61

Zero Wait Between Successful Exchanges

Description

Selects whether to initiate data exchange after the Exchange Data Interval or immediately after a successful previous exchange.

Required Values

Yes or No. The default value is No.




� If this parameter is set to Yes, and the previous exchange function returned data, the e*Way invokes the Exchange Data with External Function immediately


� If this parameter is set to No, the e*Way always waits the number of seconds specified by Exchange Data Interval between invocations of the Exchange Data with External Function

Start Exchange Data Schedule

Description

Establishes the schedule to invoke the e*Way’s Exchange Data with External Function.

Required Values

One of the following:

� One or more specific dates/times

� A single repeating, regular, interval (such as weekly, daily, or every n seconds)

Other Requirements

If you set a schedule using this parameter, you must also define all of the following parameters. If you do not, the e*Way terminates execution when the schedule attempts to start.

� Exchange Data with External Function

� Positive Acknowledgment Function

� Negative Acknowledgment Function


When the schedule starts, the e*Way determines whether or not:

� it is waiting to send an ACK or NAK to the external system (using the Positive Acknowledgment Function or Negative Acknowledgment Function)

� the connection to the external system is active

If no ACK/NAK is pending and the connection is active, the e*Way immediately executes the Exchange Data with External Function. Thereafter, the Exchange Data with External Function is called according to the Exchange Data Interval parameter until the Stop Exchange Data Schedule time is reached.



Stop Exchange Data Schedule

Description

Establishes the schedule to stop data exchange.

Required Values

One of the following:

� One or more specific dates/times

� A single repeating, regular, interval (such as weekly, daily, or every n seconds)

Down Timeout

Description

Specifies the number of seconds that the e*Way waits between calls to the External Connection Establishment Function.

Required Values


Up Timeout

Description

Specifies the number of seconds the e*Way waits between calls to the External Connection Verification Function.

Required Values

An integer from 1 to 86,400 (omit the comma). The default is 15.

Resend Timeout

Description

Specifies the number of seconds the e*Way waits between attempts to resend an Event to the external system, after receiving an error message.

Required Values



Chapter 6 Section 6.4Configuration Parameters (LU6.2) Monk Configuration

6.4 Monk Configuration The parameters in this section help you set up the information required by the e*Way to utilize Monk for communication with the external system. The functions that you specify within this section are Monk functions that the e*Way calls automatically as part of its normal operations. The functions are not called under user control.

All the configuration options in this section—the functions or variables defined, and the additional path information—are loaded into a separate Monk environment than is used by the e*Way’s Collaborations and its Collaboration Rules scripts. You cannot access any of these functions, variables, or path information from Collaboration Rules scripts.

Specifying Function or File Names

For those parameters that accept a file or the name of a Monk function, the e*Way presumes that the name of the file is the same as the name of the function to be executed, plus a .monk extension. For example, the file startup.monk should contain the definition for the function startup. If path information is specified, that path is appended to the Load Path.

If you specify a file name, be sure that the file has one of the following extensions:

� .monk

� .tsc

� .dsc

Specifying Multiple Directories

To specify multiple directories, manually enter the directory names rather than selecting them with the File Selection button. Directory names must be separated with semicolons, and you can mix absolute paths with relative e*Gate paths. For example:

monk_scripts\my_dir;c:\my_directory

The internal e*Way function that loads this path information is called only once, when the e*Way first starts up.

Load Path

The Monk load path is the path Monk uses to locate files and data (set internally within Monk). The default load paths are determined by the SharedExe and SystemData settings in the .egate.store file. See the e*Gate Integrator System Administration and Operations Guide for more information about this file.



Additional Path

Description

Specifies a path to be appended to the Load Path. A directory specified here is searched after searching the default load path.

Required Values

A pathname, or a series of paths separated by semicolons. There is no default value for this parameter.

Note: This parameter is optional and may be left blank.

Additional information


Auxiliary Library Directories

Description

Specifies a path to auxiliary library directories. Any .monk files found within those directories is automatically loaded into the e*Way’s Monk environment.

Required Values

A pathname, or a series of paths separated by semicolons. The default value is monk_library/ewsna.


Monk Environment Initialization File

Description

Specifies a file that contains environment initialization functions, which is loaded after the Auxiliary Library Directories are loaded.

Required Values

A filename within the Load Path, or filename plus path information (relative or absolute). If path information is specified, that path is appended to the load path. The default value is sna-init.


Returns

The string “FAILURE” indicates that the function failed, and the e*Way exits; any other string, including a null string, indicates success.




� Use this feature to initialize the e*Way’s Monk environment (for example, to define Monk variables that are used by the e*Way’s function scripts); it is good practice to initialize any global Monk variables that may be used by any other Monk Extension scripts

� The internal function that loads this file is called once when the e*Way first starts up

� The e*Way loads this file and try to invoke a function of the same base name as the file name

Startup Function

Description

Specifies a Monk function that the e*Way loads and invokes upon startup or whenever the e*Way’s configuration is reloaded. It is called after the e*Way loads the specified Monk Environment Initialization File and any files within the specified Auxiliary Library Directories. This function accepts no input, and must return a string.

This function should be used to initialize the external system before data exchange starts.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-startup.


Returns

The string “FAILURE” indicates that the function failed, and the e*Way exits; any other string (including a null string) indicates success.

Process Outgoing Message Function

Description

Specifies the Monk function responsible for sending outgoing messages (Events) from the e*Way to the external system. This function is event-driven, rather than schedule-driven). The function requires a non-null string as input (i.e., the outgoing Event to be sent), and must return a string.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-outgoing.

Note: This parameter is required, and must not be left blank.



Returns

� A null string (““) indicates that the Event was published successfully to the external system

� A string beginning with RESEND indicates that the Event should be resent

� A string beginning with CONNERR indicates that there is a problem with the connection to the external system, and causes a rollback of the Event

� A string beginning with DATAERR indicates that there is a problem with the message (Event) data itself, and causes a rollback of the Event

� A string beginning with SHUTDOWN indicates that the e*Way must exit immediately

� If any string other than one of the preceding is returned, the e*Way creates an entry in the log file indicating that an attempt has been made to access an unsupported function


� The e*Way invokes this function when one of its Collaborations publishes an Event to an external destination (as specified within the e*Gate Enterprise Manager).

� Once this function has been called with a non-null string, the e*Way does not process another Event until the current Event has been completely processed.

Note: If you wish to use event-send-to-egate to enqueue failed Events in a separate IQ, the e*Way must have an inbound Collaboration (with appropriate IQs) configured to process those Events.

Exchange Data with External Function

Description

Specifies a Monk function that initiates the transmission of data from the external system to the e*Gate system and forwards that data as an inbound Event to one or more e*Gate Collaborations. This function is invoked automatically by the Down Timeout or manually by the start-schedule Monk function, and is responsible for either sending data to or receiving data from the external system. If this function returns data, it is queued to e*Gate in an inbound Collaboration. The e*Way must have at least one Collaboration configured suitably to process the inbound Event, as well as any required IQs.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-incoming.

Note: This parameter is conditional and must be supplied only if the Exchange Data Interval is set to a non-zero value.



Returns

� A null string (““) indicates that the data exchange was completed successfully, but with no resultant data sent back to the e e*Gate system

� A string beginning with CONNERR indicates that there is a problem with the connection to the external system

� A string beginning with DATAERR indicates that there is a problem with the message (Event) data itself. If the error string contains data beyond the keyword, the entire string is queued to e*Gate if an inbound Collaboration is so configured and Forward External Errors is set to Yes. Queueing, however, is performed without the subsequent sending of a ACK or NAK to the external system.

� Any other string indicates that the contents of the string are packaged as an inbound Event


� Data can be queued directly to e*Gate by using the event-send-to-egate Monk function or, if a two-phase approach is required, by using event-send-to-egate-no-commit and then event-commit-to-egate or event-rollback-to-egate to commit or rollback the enqueued events, as appropriate

Note: Until an Event is committed, it is not revealed to subscribers of that Event.

External Connection Establishment Function

Description

Specifies a Monk function that the e*Way calls (repeatedly) when it has determined that the connection to the external system is down. The function accepts no input and must return a string.

This function is executed according to the interval specified within the Down Timeout parameter, and is called only according to this schedule. Once the e*Way has determined that its connection to the external system is up, it calls the External Connection Verification Function (see next).

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-conn-establish.


Returns

� A string beginning with SUCCESS or UP indicates that the connection was established successfully

� A string beginning with DOWN indicates that the connection was not established successfully

� Any other string, including a null string, indicates that the attempt to establish the connection failed and the external state is unknown



External Connection Verification Function

Description

Specifies a Monk function that the e*Way calls when its internal variables show that the connection to the external system is up. It is executed according to the interval specified within the Up Timeout parameter, and is called only according to this schedule.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-conn-verify.


Returns

� “SUCCESS” or “UP” indicates that the connection was established successfully

� Any other string (including the null string) indicates that the attempt to establish the connection failed


If this function is not specified, the e*Way executes the External Connection Establishment Function in its place. This latter function also is called when the e*Way has determined that its connection to the external system is down.

External Connection Shutdown Function

Description

Specifies a Monk function that the e*Way calls to shut down the connection to the external system. This function is invoked only when the e*Way receives a suspend command from a Control Broker.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-conn-shutdown.


Input

A string indicating the purpose for shutting down the connection.

� “SUSPEND_NOTIFICATION” - the e*Way is being suspended or shut down

� “RELOAD_NOTIFICATION” - the e*Way is being reconfigured

Returns

A string, the value of which is ignored. Any return value indicates that the suspend command can proceed and that the connection to the external system can be broken immediately.



Note: Include in this function any required “clean up” operations that must be performed as part of the shutdown procedure, but before the e*Way exits.

Positive Acknowledgment Function

Description

This function is loaded during the initialization process and is called when all data received from the external system has been processed and enqueued successfully.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-pos-ack.

Note: This parameter is conditional and must be supplied only if the Exchange Data with External Function is set to a non-zero value.

Required Input

A string, the inbound Event to e*Gate.

Returns

� The string beginning with CONNERR indicates a problem with the connection to the external system; when the connection is re-established, the function is called again, with the same input data

� Any other string, including a null string, indicates that the acknowledgement has been sent to the external system successfully


� After the Exchange Data with External Function returns a string that is transformed into an inbound Event, the Event is handed off to one or more Collaborations for further processing. The e*Way executes this function only if the Event’s processing is completed successfully by all the Collaborations to which it was sent; otherwise, the e*Way executes the Negative Acknowledgment Function.

� This function can return data to be queued, but the e*Way will not acknowledge the data with an ACK or NAK.

Note: If you configure the acknowledgment function to return a non-null string, you must configure a Collaboration (with appropriate IQs) to process the returned Event.

Negative Acknowledgment Function

Description

This function is loaded during the initialization process and is called when the e*Way fails to process or enqueue data received from the external system successfully.



Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-neg-ack.


Required Input


Returns

� The string beginning with CONNERR indicates a problem with the connection to the external system; when the connection is re-established, the function is called again, using the same input data



� This function is called only during the processing of inbound Events. After the Exchange Data with External Function returns a string that is transformed into an inbound Event, the Event is handed off to one or more Collaborations for further processing. The e*Way executes this function if the Event’s processing is not completed successfully by all the Collaborations to which it was sent; otherwise, the e*Way executes the Positive Acknowledgment Function.



Shutdown Command Notification Function

Description

The e*Way calls this Monk function automatically to notify the external system that it is about to shut down. This function also can be used to shut down the connection with the external. The function accepts a string as input and must return a string.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is sna-conn-shutdown.


Input

When the Control Broker issues a shutdown command to the e*Way, the e*Way calls this function with the string “SHUTDOWN_NOTIFICATION” passed as a parameter.



Returns

� A null string or “SUCCESS” indicates that the shutdown can occur immediately

� Any other string indicates that shutdown must be postponed; once postponed, shutdown does not proceed until the Monk function shutdown-request is executed


If you postpone a shutdown using this function, be sure to use the shutdown-request function to complete the process in a timely manner.


Chapter 6 Section 6.5Configuration Parameters (LU6.2) SNA Client Configuration

6.5 SNA Client Configuration The parameters in this section provide the information required by the Generic Monk e*Way to support SNA LU6.2.

SYMDESTNAME

Description

Specifies the symbolic destination name on which the SNA client is running.

Required Values

A string; this field is case sensitive and can contain up to 64 ASCII characters.

Note: This parameter is required; you must not leave this field blank.

LOCALTPNAME

Description

Specifies the name of the local TP that is running on the local LU.

Required Values

A string; this field is case sensitive and should be 8 characters in length.


LOCALLUNAME

Description

Specifies the name of the local LU as defined for the SunLink 6.2 server.

Required Values

A string; this field is case sensitive.

Note: This parameter is required for Sunlink P2P LU6.2 version 9.1, and is ignored on other platforms.

PacketSize

Description

Specifies the number of bytes per packet of data.

Required Values




Timeout

Description

Specifies the number of milli-seconds to wait for a response, when making requests to the server.

Required Values


Use Ack Nak

Description

Specifies whether or not to use ACK and NAK for Request Reply.

Required Values

Yes or No. The default value is Yes.

Ack String

Description

Specifies the Positive acknowledgment value.

Required Values

A string. The default value is ACK.

Nak String

Description

Specifies the Negative acknowledgment value.

Required Values

A string. The default value is NAK.

Request Reply

Description

Specifies whether or not the Process Outgoing Function waits for a reply and posts that reply to e*Gate.

Required Values




Initialize Conversation

Description

Specifies whether to initialize a conversation with the remote LU, or to accept conversation from the remote LU.

Required Values

Yes or No. The default value is Yes.

� Set the value to Yes to initialize a conversation with the remote LU.

� Set the value to No to accept a conversation from a remote LU.

Data Flow

Description

Specifies the direction of data flow.

Required Values

Inbound or Outbound. The default value is Outbound.

� Set the value to Outbound to allow the local LU to send data to the partner LU.

� Set the value to Inbound to allow the local LU to receive data from the partner LU.

Synchronization Level

Description

Specifies the synchronization level of the conversation.

Required Values

Confirm or None. The default value is Confirm.

� Select Confirm to set the synchronization level parameter, CM_SYNC_LEVEL, to CM_CONFIRM.

� Select None to set the synchronization level parameter, CM_SYNC_LEVEL, to CM_NONE.


Chapter 7

Configuration Parameters (LUA)

This chapter describes the LUA configuration parameters for the e*Way Intelligent Adapter for SNA.

7.1 Overview The e*Way’s configuration parameters are set using the e*Way Editor; see Configuring the e*Way on page 37 for procedural information. The SNA e*Way’s configuration parameters are organized into the following sections. The default configurations are provided in stcewsnalu0.def.

General Settings on page 75

Communication Setup on page 77

Monk Configuration on page 80

SNA LUA Client Configuration on page 89


Chapter 7 Section 7.2Configuration Parameters (LUA) General Settings

7.2 General Settings The General Settings control basic operational parameters.

Journal File Name

Description

Specifies the name of the journal file.

Required Values

A valid filename, optionally including an absolute path (for example, c:\temp\filename.txt). If an absolute path is not specified, the file is stored in the e*Gate SystemData directory.. There is no default value for this parameter.


An Event is Journaled for the following conditions:

� When the number of resends is exceeded (see Max Resends Per Message below)

� When its receipt is due to an external error, but Forward External Errors is set to No

See the e*Gate Integrator System Administration and Operations Guide for more information about file locations.

Max Resends Per Message

Description

Specifies the number of times the e*Way attempts to resend a message (Event) to the external system after receiving an error. When this maximum is reached, the e*Way waits for the number of seconds specified by the Resend Timeout parameter, and then rolls back the Event to its publishing IQ.

Required Values


Max Failed Messages

Description

Specifies the maximum number of failed Events that the e*Way allows. When the specified number of failed Events is reached, the e*Way shuts down and exits.

Required Values



Chapter 7 Section 7.2Configuration Parameters (LUA) General Settings

Forward External Errors

Description

Description

Selects whether or not error messages received from the external system that begin with the string “DATAERR” are queued to the e*Way’s configured queue. See Exchange Data with External Function on page 83 for more information.

Required Values

Yes or No. The default value, No, specifies that error messages are not to be forwarded.


Chapter 7 Section 7.3Configuration Parameters (LUA) Communication Setup

7.3 Communication Setup The Communication Setup parameters control the schedule by which the e*Way obtains data from the external system.

Note: The schedule you set using the e*Way’s properties in the Enterprise Manager controls when the e*Way executable runs. The schedule you set within the parameters discussed in this section (using the e*Way Editor) determines when data are exchanged. Be sure you set the "exchange data" schedule to fall within the "run the executable" schedule.

Exchange Data Interval

Description

Specifies the number of seconds the e*Way waits between calls to the Exchange Data with External Function during scheduled data exchanges.

Required Values



� If Zero Wait Between Successful Exchanges is set to Yes and the Exchange Data with External Function returns data, the setting of this parameter is ignored and the e*Way invokes the Exchange Data with External Function immediately


� If this parameter is set to zero, no exchange data schedule is set and the Exchange Data with External Function is never called

See also

Down Timeout on page 79

Stop Exchange Data Schedule on page 78

Zero Wait Between Successful Exchanges

Description

Selects whether to initiate data exchange after the Exchange Data Interval or immediately after a successful previous exchange.

Required Values





� If this parameter is set to Yes, and the previous exchange function returned data, the e*Way invokes the Exchange Data with External Function immediately


� If this parameter is set to No, the e*Way always waits the number of seconds specified by Exchange Data Interval between invocations of the Exchange Data with External Function

Start Exchange Data Schedule

Description

Establishes the schedule to invoke the e*Way’s Exchange Data with External Function.

Required Values

One or more schedules. The schedule can specify a date, time, or frequency (such as yearly, weekly, monthly, daily, or every n seconds). There is no default value for this parameter.

Also required

If you set a schedule using this parameter, you must also define all three of the following:

� Exchange Data with External Function

� Positive Acknowledgment Function

� Negative Acknowledgment Function

If you do not do so, the e*Way terminates execution when the schedule attempts to start.

Stop Exchange Data Schedule

Description

Establishes the schedule to stop data exchange.

Required Values

One or more schedules. The schedule can specify a date, time, or frequency (such as yearly, weekly, monthly, daily, or every n seconds).



Down Timeout

Description

Specifies the number of seconds that the e*Way waits between calls to the External Connection Establishment Function.

Required Values


Up Timeout

Description

Specifies the number of seconds the e*Way waits between calls to the External Connection Verification Function.

Required Values


Resend Timeout

Description

Specifies the number of seconds the e*Way waits between attempts to resend an Event to the external system, after receiving an error message.

Required Values



Chapter 7 Section 7.4Configuration Parameters (LUA) Monk Configuration

7.4 Monk Configuration The parameters in this section help you set up the information required by the e*Way to utilize Monk for communication with the external system. The functions that you specify within this section are Monk functions that the e*Way calls automatically as part of its normal operations. The functions are not called under user control.

All the configuration options in this section—the functions or variables defined, and the additional path information—are loaded into a separate Monk environment than is used by the e*Way’s Collaborations and its Collaboration Rules scripts. You cannot access any of these functions, variables, or path information from Collaboration Rules scripts.

Specifying Function or File Names

For those parameters that accept a file or the name of a Monk function, the e*Way presumes that the name of the file is the same as the name of the function to be executed, plus a .monk extension. For example, the file startup.monk should contain the definition for the function startup. If path information is specified, that path is appended to the Load Path.

If you specify a file name, be sure that the file has one of the following extensions:

� .monk

� .tsc

� .dsc

Specifying Multiple Directories

To specify multiple directories, manually enter the directory names rather than selecting them with the File Selection button. Directory names must be separated with semicolons, and you can mix absolute paths with relative e*Gate paths. For example:

monk_scripts\my_dir;c:\my_directory


Load Path

The Monk load path is the path Monk uses to locate files and data (set internally within Monk). The default load paths are determined by the SharedExe and SystemData settings in the .egate.store file. See the e*Gate Integrator System Administration and Operations Guide for more information about this file.



Additional Path

Description

Specifies a path to be appended to the Load Path. A directory specified here is searched after searching the default load path.

Required Values

A pathname, or a series of paths separated by semicolons. There is no default value for this parameter.




Auxiliary Library Directories

Description

Specifies a path to auxiliary library directories. Any .monk files found within those directories is automatically loaded into the e*Way’s Monk environment.

Required Values

A pathname, or a series of paths separated by semicolons. The default value is monk_library/ewsnalu0.


Monk Environment Initialization File

Description

Specifies a file that contains environment initialization functions, which is loaded after the Auxiliary Library Directories are loaded.

Required Values

A filename within the Load Path, or filename plus path information (relative or absolute). If path information is specified, that path is appended to the load path. The default value is snalu0-init.


Returns

The string “FAILURE” indicates that the function failed, and the e*Way exits; any other string, including a null string, indicates success.




� Use this feature to initialize the e*Way’s Monk environment (for example, to define Monk variables that are used by the e*Way’s function scripts); it is good practice to initialize any global Monk variables that may be used by any other Monk Extension scripts

� The internal function that loads this file is called once when the e*Way first starts up

� The e*Way loads this file and try to invoke a function of the same base name as the file name

Startup Function

Description

Specifies a Monk function that the e*Way loads and invokes upon startup or whenever the e*Way’s configuration is reloaded. It is called after the e*Way loads the specified Monk Environment Initialization File and any files within the specified Auxiliary Library Directories. This function accepts no input, and must return a string.

This function should be used to initialize the external system before data exchange starts.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-startup.


Returns

The string “FAILURE” indicates that the function failed, and the e*Way exits; any other string (including a null string) indicates success.

Process Outgoing Message Function

Description

Specifies the Monk function responsible for sending outgoing messages (Events) from the e*Way to the external system. This function is event-driven, rather than schedule-driven). The function requires a non-null string as input (i.e., the outgoing Event to be sent), and must return a string.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-outgoing.




Returns

� A null string (““) indicates that the Event was published successfully to the external system

� A string beginning with RESEND indicates that the Event should be resent

� A string beginning with CONNERR indicates that there is a problem with the connection to the external system, and causes a rollback of the Event

� A string beginning with DATAERR indicates that there is a problem with the message (Event) data itself, and causes a rollback of the Event

� A string beginning with SHUTDOWN indicates that the e*Way must exit immediately

� If any string other than one of the preceding is returned, the e*Way creates an entry in the log file indicating that an attempt has been made to access an unsupported function


� The e*Way invokes this function when one of its Collaborations publishes an Event to an external destination (as specified within the e*Gate Enterprise Manager).

� Once this function has been called with a non-null string, the e*Way does not process another Event until the current Event has been completely processed.

Note: If you wish to use event-send-to-egate to enqueue failed Events in a separate IQ, the e*Way must have an inbound Collaboration (with appropriate IQs) configured to process those Events.

Exchange Data with External Function

Description

Specifies a Monk function that initiates the transmission of data from the external system to the e*Gate system and forwards that data as an inbound Event to one or more e*Gate Collaborations. This function is invoked automatically by the Down Timeout or manually by the start-schedule Monk function, and is responsible for either sending data to or receiving data from the external system. If this function returns data, it is queued to e*Gate in an inbound Collaboration. The e*Way must have at least one Collaboration configured suitably to process the inbound Event, as well as any required IQs.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-incoming.

Note: This parameter is conditional and must be supplied only if the Exchange Data Interval is set to a non-zero value.



Returns

� A null string (““) indicates that the data exchange was completed successfully, but with no resultant data sent back to the e e*Gate system

� A string beginning with CONNERR indicates that there is a problem with the connection to the external system

� A string beginning with DATAERR indicates that there is a problem with the message (Event) data itself. If the error string contains data beyond the keyword, the entire string is queued to e*Gate if an inbound Collaboration is so configured and Forward External Errors is set to Yes. Queueing, however, is performed without the subsequent sending of a ACK or NAK to the external system.

� Any other string indicates that the contents of the string are packaged as an inbound Event


� Data can be queued directly to e*Gate by using the event-send-to-egate Monk function or, if a two-phase approach is required, by using event-send-to-egate-no-commit and then event-commit-to-egate or event-rollback-to-egate to commit or rollback the enqueued events, as appropriate

Note: Until an Event is committed, it is not revealed to subscribers of that Event.

External Connection Establishment Function

Description

Specifies a Monk function that the e*Way calls (repeatedly) when it has determined that the connection to the external system is down. The function accepts no input and must return a string.

This function is executed according to the interval specified within the Down Timeout parameter, and is called only according to this schedule. Once the e*Way has determined that its connection to the external system is up, it calls the External Connection Verification Function (see next).

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-conn-establish.


Returns

� A string beginning with SUCCESS or UP indicates that the connection was established successfully

� A string beginning with DOWN indicates that the connection was not established successfully

� Any other string, including a null string, indicates that the attempt to establish the connection failed and the external state is unknown



External Connection Verification Function

Description

Specifies a Monk function that the e*Way calls when its internal variables show that the connection to the external system is up. It is executed according to the interval specified within the Up Timeout parameter, and is called only according to this schedule.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-conn-verify.


Returns

� “SUCCESS” or “UP” indicates that the connection was established successfully

� Any other string (including the null string) indicates that the attempt to establish the connection failed


If this function is not specified, the e*Way executes the External Connection Establishment Function in its place. This latter function also is called when the e*Way has determined that its connection to the external system is down.

External Connection Shutdown Function

Description

Specifies a Monk function that the e*Way calls to shut down the connection to the external system. This function is invoked only when the e*Way receives a suspend command from a Control Broker.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-shutdown.


Input

A string indicating the purpose for shutting down the connection.

� “SUSPEND_NOTIFICATION” - the e*Way is being suspended or shut down

� “RELOAD_NOTIFICATION” - the e*Way is being reconfigured

Returns

A string, the value of which is ignored. Any return value indicates that the suspend command can proceed and that the connection to the external system can be broken immediately.



Note: Include in this function any required “clean up” operations that must be performed as part of the shutdown procedure, but before the e*Way exits.

Positive Acknowledgment Function

Description

This function is loaded during the initialization process and is called when all data received from the external system has been processed and enqueued successfully.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-pos-ack.


Required Input


Returns

� The string beginning with CONNERR indicates a problem with the connection to the external system; when the connection is re-established, the function is called again, with the same input data



� After the Exchange Data with External Function returns a string that is transformed into an inbound Event, the Event is handed off to one or more Collaborations for further processing. The e*Way executes this function only if the Event’s processing is completed successfully by all the Collaborations to which it was sent; otherwise, the e*Way executes the Negative Acknowledgment Function.



Negative Acknowledgment Function

Description

This function is loaded during the initialization process and is called when the e*Way fails to process or enqueue data received from the external system successfully.



Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-neg-ack.


Required Input


Returns

� The string beginning with CONNERR indicates a problem with the connection to the external system; when the connection is re-established, the function is called again, using the same input data



� This function is called only during the processing of inbound Events. After the Exchange Data with External Function returns a string that is transformed into an inbound Event, the Event is handed off to one or more Collaborations for further processing. The e*Way executes this function if the Event’s processing is not completed successfully by all the Collaborations to which it was sent; otherwise, the e*Way executes the Positive Acknowledgment Function.



Shutdown Command Notification Function

Description

The e*Way calls this Monk function automatically to notify the external system that it is about to shut down. This function also can be used to shut down the connection with the external. The function accepts a string as input and must return a string.

Required Values

The name of a Monk function or the name of a file containing a Monk function. The default value is snalu0-conn-shutdown.


Input

When the Control Broker issues a shutdown command to the e*Way, the e*Way calls this function with the string “SHUTDOWN_NOTIFICATION” passed as a parameter.



Returns

� A null string or “SUCCESS” indicates that the shutdown can occur immediately

� Any other string indicates that shutdown must be postponed; once postponed, shutdown does not proceed until the Monk function shutdown-request is executed


If you postpone a shutdown using this function, be sure to use the shutdown-request function to complete the process in a timely manner.


Chapter 7 Section 7.5Configuration Parameters (LUA) SNA LUA Client Configuration

7.5 SNA LUA Client Configuration The parameters in this section provide the information required by the Generic Monk e*Way to support SNA LUA (including LU0).

Local LU Name

Description

Specifies the Local LU defined on VTAM for local host.

Required Values

A string; this field is case sensitive. There is no default value for this parameter.


Max Message Size

Description

Specifies the maximum number of bytes per packet of data. This number also determines the size of the buffers.

Required Values

An integer from 1 to 864,000 (omit the comma). The default value is 1024


Receive Timeout

Description

Specifies the number of milli-seconds to wait when reading from the SNA server.

Required Values


Control Bytes

Description

Specifies the number bytes to preserve at the beginning of the data. These are generally used for information such as the MUX header.

Required Values



Chapter 8

API Functions

This chapter describes the various API functions used by the SNA e*Way.

8.1 OverviewThe SNA e*Way’s functions fall into the following categories:

Native e*Way Functions

LU6.2 on page 91

LUA on page 100

Standard e*Way Functions

LU6.2 on page 105

LUA on page 112

Generic e*Way Functions on page 118


Chapter 8 Section 8.2API Functions Native e*Way Functions

8.2 Native e*Way Functions The functions described in this section control the SNA e*Way’s interaction with SNA, and can only be called from within a Collaboration Rules script.

8.2.1 LU6.2The SNA e*Way’s native Monk functions for LU6.2 are:

sna-accept-conversation on page 91

sna-change-state on page 92

sna-change-state-no-synch on page 92

sna-confirmed on page 93

sna-client-connect on page 94

sna-client-connect-no-synch on page 94

sna-client-disconnect on page 95

sna-client-isconnected on page 95

sna-client-recv on page 96

sna-client-recv-no-synch on page 97

sna-client-send on page 97

sna-client-send-no-synch on page 98

sna-accept-conversation

Description

Allows the client to accept conversation by means of the following sequence.

1 Calls CMSLTP to specify the local TP name.

2 Calls CMACCP to accept the conversation.

3 Calls CMWAIT to wait for the local LU to attach the conversation.

Signature

(sna-accept-conversation LocalTPName)

Parameters

Returns

Returns Boolean #t (true) if successful; otherwise, returns #f (false).

Name Type Description

LocalTPName string The Local TP Name associated with the SNA Server.



Throws

None.

Location

stc_monksna.dll

sna-change-state

Description

Changes the state of the SNA conversation as follows:

� If the parameter State = SEND, calls CMPTR to change the state to RECEIVE

� If the parameter State = RECEIVE, calls CMRTS to change the state to SEND

� After calling CMRTS, calls CMCFMED to get confirmation that the request to send was received

Signature

(sna-change-state ServerHandle State)

Parameters

Returns


Throws

None.


� Before a send or receive can be called, the conversation must be in the correct state. For the client to send an Event to the server, the state must be send. In order to receive an Event from the server, the state must be receive. This must be synchronized with the server. Neither a send nor a receive occurs unless both TPs are synchronized.

� If the conversation is already in the state being requested, an error is returned.

Location

stc_monksna.dll

sna-change-state-no-synch

Description

Changes the state of the SNA conversation with no synchronization calls.


ServerHandle opaque handle The handle to the SNA Server.

State string The Server State (send or receive).



Signature

(sna-change-state ServerHandle State)

Parameters

Returns


Throws

None.


� Before a send or receive can be called, the conversation must be in the correct state. For the client to send an Event to the server, the state must be send. In order to receive an Event from the server, the state must be receive. This must be synchronized with the server. Neither a send nor a receive occurs unless both TPs are synchronized.

� If the conversation is already in the state being requested, an error is returned.

sna-confirmed

Description

Calls CMCFMD to reply to a confirmation request from the partner program to verify that there was no error detected by the local program within the data received.

Signature

(sna-confirmed ServerHandle)

Parameters

Returns


Throws

None.



State string The Server State (send or receive).


ServerHandle opaque handle The handle to the SNA Server




SNA requires that the local and the partner program issue a ‘confirmed’ call after each instance of data received. The conversation is blocked until such confirmation is received. The ‘confirmed’ call synchronizes the processing of the two TPs.

Location

stc_monksna.dll

sna-client-connect

Description

Opens a connection to the specified server by means of the following sequence.

1 Calls CMINIT, to initialize the conversation with the partner LU.

2 Calls CMSPM, to set the processing mode to CM_BLOCKING.

3 Calls CMSSL, to set the synchronization level to CM_CONFIRM.

4 Calls CMALLC, to allocate the conversation with the partner LU.

Signature

(sna-client-connect SymDestName)

Parameters

Returns

Returns the handle to the SNA Server.

Throws

None.

Location

stc_monksna.dll

sna-client-connect-no-synch

Description

Opens a connection to the specified server and defaults the synchronization level to CM_NONE.

Signature

(sna-client-connect SymDestName)


SymDestName string The Symbolic Destination Name associated with the SNA Server (see SYMDESTNAME on page 71).



Parameters

Returns

Returns the handle to the SNA Server.

Throws

None.

Location

stc_monksna.dll

sna-client-disconnect

Description

Closes the connection to the SNA server.

Signature

(sna-client-disconnect ServerHandle)

Parameters

Returns


Throws

None.


Generally, the TP that is sending data should deallocate the conversation; however, if you are receiving data and want to disconnect, first call sna-change-state “SEND”.

Location

stc_monksna.dll

sna-client-isconnected

Description

Verifies that the connection to the SNA server is open.


SymDestName string The Symbolic Destination Name associated with the SNA Server (see SYMDESTNAME on page 71).





Signature

(sna-client-isconnected ServerHandle)

Parameters

Returns


Throws

None.

Location

stc_monksna.dll

sna-client-recv

Description

Contacts the specified SNA server to advise that it is ready to receive any data (Event) that is available from the server.

1 Calls CMRCV to receive data from partner LU.

2 Calls CMCFMD to send confirmation to the partner that the data was received successfully.

Signature

(sna-client-recv ServerHandle PacketSize Timeout)

Parameters

Returns

Returns a string representing the Event.

Throws

None.





PacketSize integer The size of the packet in bytes (see PacketSize on page 71)

Timeout integer The amount of milli-seconds to wait for a response from the Server before a Timeout is issued (see Timeout on page 72).




The states must be synchronized prior to making this call. The local program state must be in the ‘receive’ mode.

Location

stc_monksna.dll

sna-client-recv-no-synch

Description

Contacts the specified SNA server to advise that it is ready to receive any data (Event) that is available from the server. There are no synchronization calls with this function.

Signature

(sna-client-recv ServerHandle PacketSize Timeout)

Parameters

Returns

Returns a string representing the Event.

Throws

None.


The states must be synchronized prior to making this call. The local program state must be in the ‘receive’ mode.

Location

stc_monksna.dll

sna-client-send

Description

Sends an Event to the specified SNA server.

Signature

(sna-client-send ServerHandle Event)



PacketSize integer The size of the packet in bytes (see PacketSize on page 71).

Timeout integer The amount of milli-seconds to wait for a response from the Server before a Timeout is issued (see Timeout on page 72).



Parameters

Returns


Throws

None.


The states must be synchronized prior to making this call. The local program state must be in the ‘send’ mode.

Location

stc_monksna.dll

sna-client-send-no-synch

Description

Sends an Event to the specified SNA server.

1 Calls CMSEND to send data to the partner LU, and then

2 Issues CMCFM to request a confirmation from the partner LU that the data sent was received successfully.

Signature

(sna-client-send ServerHandle Event)

Parameters

Returns


Throws

None.


No synchronization is required prior to making this call. The local program state must be in the ‘send’ mode.



Event string The Event to be sent.



Event string The Event to be sent.



Location

stc_monksna.dll



8.2.2 LUAThe SNA e*Way’s native Monk functions for LUA (and LU0) are:

snalu0-connect on page 100

snalu0-disconnect on page 100

snalu0-isconnected on page 101

snalu0-send on page 102

snalu0-recv on page 102

snalu0-get-property on page 103

snalu0-set-property on page 103

snalu0-connect

Description

Calls RUI_INIT, which notifies VTAM that a connection is desired.

Signature

(snalu0-connect luName timeout)

Parameters

Returns

Returns a handle for subsequent SNA calls.

Throws

None.

Examples

(define hSNA (snalu0-connect “T1860C01”)

Location

monksnalua.monk

snalu0-disconnect

Description

Calls RUI_INIT, which notifies VTAM that the connection no longer desired.


luName string A zero-delimited string specifying the local LU name (see Local LU Name on page 89).

timeout int Timeout in milliseconds to wait for a response from the server before timing out (see Receive Timeout on page 89).



Signature

(snalu0-disconnect snaHandle)

Parameters

Returns


Throws

None.

Examples

(snalu0-disconnect hSNA)

Location

monksnalua.monk

snalu0-isconnected

Description

Sends a status to SNA Server to verify that the connection handle is still valid.

Signature

(snalu0-isconnected snaHandle)

Parameters

Returns


Throws

None.

Examples

(if (snalu0-isconnected hSNA)(display “handle still good\n”)(display “handle bad\n”)

)

Location

monksnalua.monk


snaHandle Opaque handle The handle to the SNA Server.





snalu0-send

Description

Sends an Event to the specified SNA Server.

Signature

(snalu0-send snaHandle event)

Parameters

Returns


Throws

None.

Examples

(snalu0-send hSNA “Hello There”)

Location

monksnalua.monk

snalu0-recv

Description

Receives an Event from the specified SNA Server.

Signature

(snalu0-recv snaHandle packetSize timeout)

Parameters

Returns

Returns the data string received from SNA.



event String Data to send to the SNA Server.



packetSize Integer The size of the packet in bytes to read.

timeout Integer Timeout in milliseconds to wait for a response from the server before timing out (see Receive Timeout on page 89).



Throws

None.

Examples

(set! data(snalu0-recv hSNA 200 2000))

Location

monksnalua.monk

snalu0-get-property

Description

Obtains the property from the previous send or receive call.

Signature

(snalu0-get-property snaHandle propertyName)

Parameters

Returns


Throws

None.

Examples


Location

monksnalua.monk

snalu0-set-property

Description

Sets the specified property in SNA, generally precedes the receive or send call.



propertyName String SNA Property types:� lua_th� lua_rh� lua_flag1� lua_flag2� lua_message_type� lua_inc_th_snf (returns current snf + 1)� lua_th_snf (returns current sequence number)



Signature

(snalu0-set-property snaHandle propertyName propertyValue)

Parameters

Returns


Throws

None.

Examples


Location

monksnalua.monk



propertyName String SNA Property types:� lua_th� lua_rh� lua_flag1� lua_flag2� lua_message_type� lua_inc_th_snf (returns current snf + 1)� lua_th_snf (returns current sequence number)

propertyValue String Property value to set.


Chapter 8 Section 8.3API Functions Standard e*Way Functions

8.3 Standard e*Way Functions The functions described in this section control the SNA e*Way’s communications center and are defined within the configuration file. None of these functions is available to Collaboration Rules scripts executed by the e*Way.

8.3.1 LU6.2The SNA e*Way’s standard Monk functions for LU6.2 are:

sna-init on page 105

sna-conn-establish on page 106

sna-conn-verify on page 106

sna-conn-shutdown on page 107

sna-incoming on page 107

sna-outgoing on page 108

sna-pos-ack on page 109

sna-neg-ack on page 109

sna-shutdown on page 110

sna-startup on page 111

sna-init

Description

Begins the initialization process for the e*Way. This function loads the stc_monksna.dll file and the initialization file, thereby making the function scripts available for future use.

Signature

(sna-init)

Parameters

None.

Returns

The string “FAILURE” causes the e*Way to shut down. Any other return indicates success.

Throws

None.




Within this function, any necessary global variables to be used by the function scripts could be defined. The internal function that loads this file is called once when the e*Way first starts up.

See Monk Environment Initialization File on page 63 for more information.

Location

sna-init.monk

sna-conn-establish

Description

Establishes a connection to the external system.

Signature

(sna-conn-establish)

Parameters

None.

Returns

The string “UP” indicates the connection was established successfully. Anything else indicates no connection.

Throws

None.


See External Connection Establishment Function on page 66 for more information.

Location

sna-conn-establish.monk

sna-conn-verify

Description

Used to verify whether or not the connection to the external system is established.

Signature

(sna-conn-verify)

Parameters

None.

Returns

The string “UP” indicates the connection is currently established. Anything else indicates no connection.



Throws

None.


See External Connection Verification Function on page 67 and on page 85 for more information.

Location

sna-conn-verify.monk

sna-conn-shutdown

Description

Requests that the external connection shut down.

Signature

(sna-conn-shutdown shutdown)

Parameters

Returns

The string “SUCCESS” indicates that the shutdown can occur immediately. Any other return value indicates that the shutdown Event must be delayed until a shutdown-request call is executed successfully.

Throws

None.


If a return value of “SUCCESS” is not returned, then you must execute a shutdown-request call from within a Monk function to allow the requested shutdown to process to continue.

See External Connection Shutdown Function on page 67 for more information.

Location

sna-conn-shutdown.monk

sna-incoming

Description

Sends a received Event from the external system to e*Gate. The function expects no input.


shutdown string The function that passes the string "SUSPEND_NOTIFICATION" to the external system before the e*Way shuts down.



Signature

(sna-incoming)

Parameters

None.

Returns

� An empty string indicates a successful operation, but nothing is sent to e*Gate.

� A string containing Event data indicates successful operation, and the returned Event is sent to e*Gate.

� The string “CONNERR” indicates a problem with the connection to the external system. When the connection is re-established this function is re-executed with the same input Event.

Throws

None.


See Exchange Data with External Function on page 65 for more information.

Location

sna-incoming.monk

sna-outgoing

Description

Sends a received Event from e*Gate to the external system.

Signature

(sna-outgoing event-string)

Parameters

Returns

� An empty string indicates a successful operation.

� The string “RESEND” causes the Event to be immediately resent.


� The string “DATAERR” indicates the function had a problem processing data. If the e*Gate journal is enabled, the Event is journaled and the failed Event count is increased. (The input Event is essentially skipped in this process.) Use the event-send-to-egate function to place bad Events in a bad Event queue.


event-string string The Event to be processed.



Throws

None.


See Process Outgoing Message Function on page 64 for more information.

Location

sna-outgoing.monk

sna-pos-ack

Description

Sends a positive acknowledgment to the external system after all Collaborations to which the e*Way sent data have processed and enqueued that data successfully.

Signature

(sna-pos-ack arg)

Parameters

Returns

� An empty string indicates a successful operation. The e*Way is then be able to proceed with the next request.

� The string “CONNERR” indicates a problem with the connection to the external system. When the connection is re-established, the function is called again.


See Positive Acknowledgment Function on page 68 for more information.

Location

sna-pos-ack.monk

sna-neg-ack

Description

Sends a negative acknowledgment to the external system when the e*Way fails to process and queue Events from the external system.

Signature

(sna-neg-ack arg)


arg string The Event for which an acknowledgment is sent.



Parameters

Returns



Throws

None.


See Negative Acknowledgment Function on page 68 for more information.

Location

sna-neg-ack.monk

sna-shutdown

Description

Notifies the external system that the e*Way is shutting down.

Signature

(sna-shutdown command)

Parameters

Returns

Returns a null string.

Throws

None.


See Shutdown Command Notification Function on page 69 for more information.

Location

sna-shutdown.monk


arg string The Event for which a negative acknowledgment is sent.


command string The function that passes the string "SHUTDOWN_NOTIFICATION" to the external system before the e*Way shuts down.



sna-startup

Description

Invokes startup and is used for function loads that are specific to this e*Way.

Signature

(sna-startup)

Parameters

None.

Returns


Throws

None.


This function should be used to initialize the external system before data exchange starts. Any additional variables may be defined here.

See Startup Function on page 64 for more information.

Location

sna-startup.monk



8.3.2 LUAThe SNA e*Way’s standard Monk functions for LUA (and LU0) are:

snalu0-init on page 112

snalu0-conn-establish on page 113

snalu0-conn-verify on page 113

snalu0-conn-shutdown on page 113

snalu0-incoming on page 114

snalu0-outgoing on page 115

snalu0-pos-ack on page 115

snalu0-neg-ack on page 116

snalu0-shutdown on page 116

snalu0-startup on page 117

snalu0-init

Description

Begins the initialization process for the e*Way. This function loads the stc_monksnalu0.dll file and the initialization file, thereby making the function scripts available for future use.

Signature

(snalu0-init)

Parameters

None.

Returns


Throws

None.


Within this function, any necessary global variables to be used by the function scripts could be defined. The internal function that loads this file is called once when the e*Way first starts up.

See Monk Environment Initialization File on page 81 for more information.



snalu0-conn-establish

Description

Establishes a connection to the external system.

Signature

(snalu0-conn-establish)

Parameters

None.

Returns

The string “UP” indicates the connection was established successfully. Anything else indicates failure to connect.

Throws

None.


See External Connection Establishment Function on page 84 for more information.

snalu0-conn-verify

Description

Used to verify whether or not the connection to the external system is established.

Signature

(snalu0-conn-verify)

Parameters

None.

Returns

The string “UP” if connection established. Any other value indicates the connection is not established.

Throws

None.


See External Connection Verification Function on page 85 for more information.

snalu0-conn-shutdown

Description

Requests that the external connection shut down. A return value of “SUCCESS” indicates that the shutdown can occur immediately. Any other return value indicates



that the shutdown Event must be delayed. The user is then required to execute a (shutdown-request on page 123) call from within a Monk function to allow the requested shutdown to process to continue.

Signature

(snalu0-conn-shutdown shutdown)

Parameters

Returns

The string “SUCCESS” allows an immediate shutdown to occur. Anything else delays shutdown until the shutdown-request is executed successfully.

Throws

None.


See External Connection Shutdown Function on page 85 for more information.

snalu0-incoming

Description

Sends a received Event from the external system to e*Gate. The function expects no input.

Signature

(snalu0-incoming)

Parameters

None.

Returns

� An empty string indicates a successful operation, but nothing is sent to e*Gate.

� A string containing Event data indicates successful operation, and the returned Event is sent to e*Gate.


Throws

None.


shutdown string The function that passes the string "SUSPEND_NOTIFICATION" to the external system before the e*Way shuts down.




See Exchange Data with External Function on page 83 for more information.

snalu0-outgoing

Description

Sends a received Event from e*Gate to the external system.

Signature

(snalu0-outgoing event-string)

Parameters

Returns


� The string “RESEND” causes the Event to be immediately resent.


� The string “DATAERR” indicates the function had a problem processing data. If the e*Gate journal is enabled, the Event is journaled and the failed Event count is increased. (The input Event is essentially skipped in this process.) Use the event-send-to-egate function to place bad events in a bad event queue.

Throws

None.


See Process Outgoing Message Function on page 82 for more information.

snalu0-pos-ack

Description

Sends a positive acknowledgment to the external system after all Collaborations to which the e*Way sent data have processed and enqueued that data successfully.

Signature

(snalu0-pos-ack arg)


event-string string The Event to be processed.



Parameters

Returns

� An empty string indicates a successful operation. The e*Way is then be able to proceed with the next request.



See Positive Acknowledgment Function on page 86 for more information.

snalu0-neg-ack

Description

Sends a negative acknowledgment to the external system when the e*Way fails to process and queue Events from the external system.

Signature

(snalu0-neg-ack arg)

Parameters

Returns

An empty string indicates a successful operation.

The string “CONNERR” indicates a problem with the connection to the external system. When the connection is re-established, the function is called again.

Throws

None.


See Negative Acknowledgment Function on page 86 for more information.

snalu0-shutdown

Description

Notifies the external system that the e*Way is shutting down.


arg string The Event for which an acknowledgment is sent.


arg string The Event for which a negative acknowledgment is sent.



Signature

(snalu0-shutdown command)

Parameters

Returns

Returns a null string.

Throws

None.


See Shutdown Command Notification Function on page 87 for more information.

snalu0-startup

Description

Invokes startup and is used for function loads that are specific to this e*Way.

Signature

(snalu0-startup)

Parameters

None.

Returns


Throws

None.


This function should be used to initialize the external system before data exchange starts. Any additional variables may be defined here.

See Startup Function on page 82 for more information.


command string The function that passes the string "SHUTDOWN_NOTIFICATION" to the external system before the e*Way shuts down.


Chapter 8 Section 8.4API Functions Generic e*Way Functions

8.4 Generic e*Way Functions The functions described in this section are implemented in the e*Way Kernel layer and control the e*Way’s most basic operations. They can be used only by the functions defined within the e*Way’s configuration file. None of these functions is available to Collaboration Rules scripts executed by the e*Way. These functions are located in stcewgenericmonk.exe.

The current set of basic Monk functions is:

event-commit-to-egate on page 118

event-rollback-to-egate on page 119

event-send-to-egate on page 119

event-send-to-egate-ignore-shutdown on page 120

event-send-to-egate-no-commit on page 120

get-logical-name on page 121

insert-exchange-data-event on page 121

send-external-up on page 122

send-external-down on page 122

shutdown-request on page 123

start-schedule on page 123

stop-schedule on page 124

waiting-to-shutdown on page 124

event-commit-to-egate

Description

Commits the Event sent previously to the e*Gate system using event-send-to-egate-no-commit.

Signature

(event-commit-to-egate string)

Parameters

Returns

Boolean true (#t) if the data is committed successfully; otherwise, false (#f).


string string The data to be sent to the e*Gate system.



Throws

None.

event-rollback-to-egate

Description

Rolls back the Event sent previously to the e*Gate system using event-send-to-egate-no-commit, following receipt of a rollback command from the external system.

Signature

(event-rollback-to-egate string)

Parameters

Returns

Boolean true (#t) if the data is rolled back successfully; otherwise, false (#f).

Throws

None.

event-send-to-egate

Description

Sends data that the e*Way has already received from the external system into the e*Gate system as an Event.

Signature

(event-send-to-egate string)

Parameters

Returns

A Boolean true (#t) if the data is sent successfully; otherwise, a Boolean false (#f).

Throws

None.


string string The data to be rolled back to the e*Gate system.


string string The data to be sent to the e*Gate system




This function can be called by any e*Way function when it is necessary to send data to the e*Gate system in a blocking fashion.

See also



event-send-to-egate-ignore-shutdown

Description

Sends data that the e*Way has already received from the external system into the e*Gate system as an Event—but ignores any pending shutdown issues.

Signature

(event-send-to-egate-ignore-shutdown string)

Parameters

Returns

Boolean true (#t) if the data is sent successfully; otherwise, false (#f).

Throws

None.

See also



event-send-to-egate-no-commit

Description

Sends data that the e*Way has received from the external system to the e*Gate system as an Event—but without Committing, pending confirmation from the external system of correct transmission of the data.

Signature

(event-send-to-egate-no-commit string)





Parameters

Returns

Boolean true (#t) if the data is sent successfully; otherwise, false (#f).

Throws

None.

See also

event-commit-to-egate on page 118

event-rollback-to-egate on page 119



get-logical-name

Description

Returns the logical name of the e*Way.

Signature

(get-logical-name)

Parameters

None.

Returns

The name of the e*Way (as defined by the e*Gate Enterprise Manager).

Throws

None.

insert-exchange-data-event

Description

While the Exchange Data with External Function is still active, this function can be called to initiate a repeat call to it—whether or not data was queued to e*Gate via the function’s return mechanism following the initial call.

Signature

(insert-exchange-data-event)





Parameters

None.

Returns

None.

Throws

None.

See also

Exchange Data with External Function on page 65 (LU6.2) or Exchange Data with External Function on page 83 (LUA/LU0).

Exchange Data Interval on page 59 (LU6.2) or Exchange Data Interval on page 77 (LUA/LU0).

Zero Wait Between Successful Exchanges on page 59 (LU6.2) or Zero Wait Between Successful Exchanges on page 77 (LUA/LU0).

send-external-up

Description

Informs the e*Way that the connection to the external system is up.

Signature

(send-external-up)

Parameters

None.

Returns

None.

Throws

None.

send-external-down

Description

Informs the e*Way that the connection to the external system is down.

Signature

(send-external-down)

Parameters

None.



Returns

None.

Throws

None.

shutdown-request

Description

Completes the e*Gate shutdown procedure that was initiated by the Control Broker but was interrupted by returning a non-null value within the Shutdown Command Notification Function. Once this function is called, shutdown proceeds immediately.

Signature

(shutdown-request)

Parameters

None.

Returns

None.

Throws

None.


Once interrupted, the e*Way’s shutdown cannot proceed until this Monk function is called. If you do interrupt an e*Way shutdown, we recommend that you complete the process in a timely fashion.

See also

Shutdown Command Notification Function on page 69 (LU6.2) or Shutdown Command Notification Function on page 87 (LUA/LU0).

start-schedule

Description

Requests that the e*Way execute the Exchange Data with External Function specified within the e*Way’s configuration file. Does not affect any defined schedules.

Signature

(start-schedule)

Parameters

None.



Returns

None.

Throws

None.

See also


stop-schedule

Description

Requests that the e*Way halt execution of the Exchange Data with External Function specified within the e*Way’s configuration file. Execution is stopped when the e*Way concludes any open transaction. Does not effect any defined schedules, and does not halt the e*Way process itself.

Signature

(stop-schedule)

Parameters

None.

Returns

None.

Throws

None.

See also


waiting-to-shutdown

Description

Informs the external application that a shutdown command has been issued.

Signature

(waiting-to-shutdown)

Parameters

None.

Returns

Boolean true (#t) if successful; otherwise, false (#f).



Throws

None.


Index

Index

AAck String parameter 72Additional Path parameter 63, 81APIs - see functions, MonkAssigning ETDs to Event Types 28Autorun 19Auxiliary Library Directories parameter 63, 81

CChanging the User Name 41Collaboration 30, 45, 48

Rules 48Service 45

Communication Setup - see configurationconfiguration

Communication Setup (LU0) 77–79Communication Setup (LUA) 59–61General Settings (LU0) 75–76General Settings (LUA) 57–58Monk Configuration (LU0) 80–88Monk Configuration (LUA) 62–70SNA Client Configuration (LU0) 89SNA Client Configuration (LUA) 71–73

configuration parametersAck String 72Additional Path 63, 81Auxiliary Library Directories 63, 81Control Bytes 89Data Flow 73Down Timeout 61, 79Exchange Data Interval 59, 77Exchange Data With External Function 65, 83External Connection Establishment Function 66,

84External Connection Shutdown Function 67, 85External Connection Verification Function 67, 85Forward External Errors 76Forward External Errors (LUA) 58Initialize Conversation 73Journal File Name 75Journal File Name (LUA) 57Local LU Name 71, 89Max Failed Messages 75

Max Failed Messages (LUA) 57Max Message Name 89Max Resends Per Message 75Max Resends Per Message (LUA) 57Monk Environment Initialization File 63, 81Nak String 72Negative Acknowledgment Function 68, 86PacketSize 71Positive Acknowledgement Function 68, 86Process Outgoing Message Function 64, 82Receive Timeout 89Request Reply 72Resend Timeout 61, 79Shutdown Command Notification Function 69,

87Start Exchange Data Schedule 60, 61, 78, 79Startup Function 64, 82Stop Exchange Data Schedule 61, 78SYMDESTNAME 71Synchronization Level 73Timeout 72Up Timeout 61, 79Use Ack Nak 72Zero Wait Between Successful Exchanges 59, 77

configuration procedures 37Control Bytes parameter 89conventions, writing in document 8

DData Flow parameter 73Down Timeout parameter 61, 79

Ee*Way

configuration 37creating 35Installation 19Properties 36Schedules 41Startup Options 41troubleshooting 45

EditorCollaboration Rules 48

Enterprise Manager 26Event Type 28Event Type Definition (ETD) 28event-commit-to-egate function 118event-rollback-to-egate function 119Events 47event-send-to-egate function 119event-send-to-egate-ignore-shutdown function 120event-send-to-egate-no-commit function 120


Index

Exchange Data Interval parameter 59, 77Exchange Data with External Function parameter 65, 83External Connection Establishment Function parameter 66, 84External Connection Shutdown Function parameter 67, 85External Connection Verification Function parameter 67, 85

FForward External Errors (LUA) parameter 58Forward External Errors parameter 76functions (see also functions, Monk)

Generic 118–125Native 91–104Standard 105–117

functions, Monkevent-commit-to-egate 118event-rollback-to-egate 119event-send-to-egate 119event-send-to-egate-ignore-shutdown 120event-send-to-egate-no-commit 120get-logical-name 121insert-exchange-data-event 121send-external down 122send-external-up 122shutdown-request 123sna-accept-conversation 91sna-change-state 92sna-change-state-no-synch 92sna-client-connect 94sna-client-connect-no-synch 94sna-client-disconnect 95sna-client-isconnected 95sna-client-recv 96sna-client-recv-no-synch 97sna-client-send 97sna-client-send-no-synch 98sna-confirmed 93sna-conn-establish 106sna-conn-shutdown 107sna-conn-verify 106sna-incoming 107sna-init 105snalu0-connect 100snalu0-conn-establish 113snalu0-conn-shutdown 113snalu0-conn-verify 113snalu0-disconnect 100snalu0-get-property 103snalu0-incoming 114snalu0-init 112

snalu0-isconnected 101snalu0-neg-ack 116snalu0-outgoing 115snalu0-pos-ack 115snalu0-recv 102snalu0-send 102snalu0-set-property 103snalu0-shutdown 116sna-neg-ack 109sna-outgoing 108sna-pos-ack 109sna-shutdown 110sna-startup 111, 117start-schedule 123stop-schedule 124waiting-to-shutdown 124

GGeneral Settings - see configurationGeneric e*Way Functions 118–125get-logical-name function 121

IInitialize Conversation parameter 73insert-exchange-data-event function 121Installation procedures

e*Way (UNIX) 22e*Way (Windows) 19

InstallShield 19Intelligent Queue (IQ) 31, 45

JJournal File Name (LUA) parameter 57Journal File Name parameter 75

LLoad Path, Monk 62, 80Local LU Name parameter 71, 89logging options 43

MMax Failed Messages (LUA) parameter 57Max Failed Messages parameter 75Max Message Name parameter 89Max Resends Per Message (LUA) parameter 57Max Resends Per Message parameter 75monitoring thresholds 44Monk Configuration


Index

Load Path 62, 80Specifying File Names 62, 80Specifying Function Names 62, 80Specifying Multiple Directories 62, 80

Monk Configuration - see configurationMonk Environment Initialization File parameter 63, 81Monk functions - see functions, Monk

NNak String parameter 72Native e*Way Functions - see functionsNegative Acknowledgment Function parameter 68, 86

PPacketSize parameter 71parameters - see configuration parametersParticipating Host 45Patch Requirements, Solaris 17Positive Acknowledgment Function parameter 68, 86procedures

configuration 37installation 19

Process Outgoing Message Function parameter 64, 82Properties, e*Way 36publish 45

QQueue - see Intelligent Queue (IQ)

RReceive Timeout parameter 89Request Reply parameter 72Resend Timeout parameter 61, 79

SSchedules 41send-external down function 122send-external-up function 122Setting Startup Options or Schedules 41Shutdown Command Notification Function parameter 69, 87shutdown-request function 123SNA Client Configuration 71SNA Client Configuration - see configuration

sna-accept-conversation function 91sna-change-state function 92sna-change-state-no-synch function 92sna-client-connect function 94sna-client-connect-no-synch function 94sna-client-disconnect function 95sna-client-isconnected function 95sna-client-recv function 96sna-client-recv-no-synch function 97sna-client-send function 97sna-client-send-no-synch function 98sna-confirmed function 93sna-conn-establish function 106sna-conn-shutdown function 107sna-conn-verify function 106sna-incoming function 107sna-init function 105snalu0-connect function 100snalu0-conn-establish function 113snalu0-conn-shutdown function 113snalu0-conn-verify function 113snalu0-disconnect function 100snalu0-get-property function 103snalu0-incoming function 114snalu0-init function 112snalu0-isconnected function 101snalu0-neg-ack function 116snalu0-outgoing function 115snalu0-pos-ack function 115snalu0-recv function 102snalu0-send function 102snalu0-set-property function 103snalu0-shutdown function 116sna-neg-ack function 109sna-outgoing function 108sna-pos-ack function 109sna-shutdown function 110sna-startup function 111, 117Solaris Patch Requirements 17Standard e*Way Functions - see functionsStart Exchange Data Schedule parameter 60, 61, 78, 79start-schedule function 123Startup Function parameter 64, 82Startup Options 41Stop Exchange Data Schedule parameter 61, 78stop-schedule function 124subscribe 45SYMDESTNAME parameter 71Synchronization Level parameter 73

TTimeout parameter 72


Index

troubleshooting the e*Way 45

UUNIX installation procedures 22Up Timeout parameter 61, 79Use Ack Nak parameter 72User name 41

Wwaiting-to-shutdown function 124Windows installation procedures 19

ZZero Wait Between Successful Exchanges parameter 59, 77


Date post:	05-Nov-2019
Category:	Documents
Upload:	others
View:	10 times
Download:	0 times

e*Way Intelligent Adapter for SNA User’s Guide · Configuring the SNA Server and Client 18 All...

Documents