tibcoactivematrix adapterfor ibm i

Copyright © 1999-2021. TIBCO Software Inc. All Rights Reserved.

TIBCO ActiveMatrix® Adapter forIBM i

Configuration and Deployment Version 6.2.2

September 2021

2 | Contents

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Chapter 1 Preparing IBM System i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Loading a Library on an IBM System i Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Adding the Library to a Library List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Starting Host Server Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Configuring the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Starting the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21Starting the Adapter with the Adapter Tester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21Starting the Adapter from the Command Line with a Repository File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22Starting the Adapter from the Command Line with a Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Chapter 3 Adapter Instance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Design-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Run-time Connection Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Multithreading Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Startup Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Monitoring Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Chapter 4 Adapter Service Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Transport Specific Service Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Transport Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39Wire Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Connection Factory Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

TIBCO ActiveMatrix® Adapter for IBM i Configuration and Deployment

3 | Contents

Delivery Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Publication Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Queue Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Message Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

Subscription Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Service Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50Message Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Program Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Message Monitor Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

Request-Response Service Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Service Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Message Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Program Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Message Monitor Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Request-Response Invocation Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68Queue Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69Message Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73

Adapter Service Options Supplement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Defining Message Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Chapter 5 Deploying the Adapter with TIBCO Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Creating an EAR File in TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Deploying the Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78

Starting or Stopping the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Monitoring the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82Properties File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82Predefined Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83Obfuscating or Encrypting a Password in the Properties File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85


4 | Contents

Chapter 6 Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

Using the Adapter with a Revision Control System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Defining a TIBCO Hawk Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90

Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92Variable Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92Changing Global Variable Values at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Setting Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Connection Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Chapter 7 Monitoring the Adapter Using TIBCO Hawk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Starting TIBCO Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

The Auto-Discovery Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Invoking MicroAgent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Available Micro agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106activateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109deactivateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110getActivityStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111getActivityStatisticsByOperation(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112getActivityStatisticsByService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113getAdapterServiceInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114getComponents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115getConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116getConfigProperties() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117getConnectionStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118getHostInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119getQueueStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120getRvConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122getThreadStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123getTraceSinks(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124getVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125_onUnsolictedMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126preRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127resetActivityStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128resetConnectionStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129resetThreadStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131setTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133stopApplicationInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134unRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135


5 | Contents

Appendix A Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Overview of Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141

TIBCO Product Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150How to Access TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150How to Join TIBCO Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Legal and Third-Party Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152



6 | Figures

Figures

Figure 1 Save Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Figure 2 Creating an Adapter Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Figure 3 Adapter Tester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Figure 4 Message Schema Tab of Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Figure 5 Message Schema Tab of Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

Figure 6 Program Schema Tab of Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Figure 7 Message Schema Tab of Request-Response Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Figure 8 Program Schema Tab of Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64

Figure 9 Message Schema Tab of Request-Response Invocation Service . . . . . . . . . . . . . . . . . . . . . . . . . .71

Figure 10 Add Data Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Figure 11 Import Data Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Figure 12 Edit Data Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Figure 13 Monitoring Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90

Figure 14 HawkSession Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91

Figure 15 Global Variables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Figure 16 TIBCO Hawk Enterprise Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Figure 17 Micro agents, Methods and Arguments Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Figure 18 Select Micro agent and Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Figure 19 Invocation Result Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Figure 20 Trace Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

7 | Tables

Tables

Table 1 Fields of Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Table 2 Fields of Design-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Table 3 Fields of Run-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Table 4 Fields of Multithreading Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Table 5 Fields of Logging Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Table 6 Fields of Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Table 7 Fields of Monitoring Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Table 8 Configuration Tab of Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 9 Queue Configuration Tab of Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Table 10 Transport Tab of Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Table 11 Schema Tab of Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Table 12 Configuration Tab of Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Table 13 Service Options Tab of Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Table 14 Message Monitor Tab of Subscription Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Table 15 Transport Tab of Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Table 16 Schema Tab of Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Table 17 Configuration Tab of Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Table 18 Service Options Tab of Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Table 19 Message Monitor Tab of Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Table 20 Transport Tab of Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Table 21 Schema Tab of Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Table 22 Configuration Tab of Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Table 23 Queue Configuration Tab of Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . 69

Table 24 Transport Tab of Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Table 25 Schema Tab of Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Table 26 Predefined Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Table 27 Predefined Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Table 28 Commands on IBM i Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98


8 | Tables

Table 29 Micro agent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Table 30 Input parameters of activateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Table 31 Input parameters of deactivateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Table 32 Input parameter of getActivityStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Table 33 Returns of getActivityStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Table 34 Input parameter of getActivityStatisticsByOperation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Table 35 Returns of getActivityStatisticsByOperation(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Table 36 Input parameter of getActivityStatisticsByService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Table 37 Returns of getActivityStatisticsByService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Table 38 Input parameter of getAdapterServiceInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Table 39 Returns of getAdapterServiceInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Table 40 Input parameters of getComponents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Table 41 Returns of getComponents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Table 42 Returns of getConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Table 43 Input parameter of getConfigProperties(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Table 44 Returns of getConfigProperties() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Table 45 Returns of getConnectionStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Table 46 Returns of getHostInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Table 47 Returns of getQueueStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Table 48 Input parameter of getRvConfig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Table 49 Returns of getRvConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Table 50 Returns of getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Table 51 Returns of getThreadStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Table 52 Input parameters of getTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Table 53 Returns of getTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Table 54 Returns of getVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Table 55 Input parameters of preRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Table 56 Input parameters of reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Table 57 Returns of reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Table 58 Input parameters of setTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Table 59 Input parameters of unRegisterListener(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Table 60 Tracing Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139


9 | Tables

Table 61 Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141


10 | Preparing IBM System i

Chapter 1 Preparing IBM System i

This chapter explains how to prepare an IBM System i machine for use with theadapter.

Topics

• Loading a Library on an IBM System i Machine, page 11

• Adding the Library to a Library List, page 12

• Starting Host Server Daemons, page 13


11 | Loading a Library on an IBM System i Machine

Loading a Library on an IBM System i Machine

For the adapter to interact with an IBM System i machine, you have to load asaved file that contains pre-defined libraries to the IBM System i machine.

1. On the machine where the adapter is installed, start a command session.Change the directory of the command session to ADAS400_HOME\examples.

2. Start an FTP session in the command session to the IBM System i machine.

ftp your_IBMi

3. Enter the user ID and password when requested.

4. In the FTP session, change the transfer mode to binary using the commandbin.

5. Transfer the saved file named ADAS400.SAVF from theADAS400_HOME\examples directory to the IBM System i machine by enteringthe following command:

put ADAS400.SAVF library_name/ADAS400

where library_name is the name of the library where the saved file ADAS400exists.

6. After the transfer is completed, sign on to the IBM System i machine andrestore the example library ADAS400 by entering the following command:

RSTLIB SAVLIB(ADAS400) DEV(*SAVF) SAVF(library_name/ADAS400)

where library_name is the name of the library where the saved file ADAS400exists.

The example library is compatible with IBM i operating system version V6R1 orlater.


12 | Adding the Library to a Library List

Adding the Library to a Library List

After restoring the ADAS400 library on the IBM System i machine, you have toadd the library to library list every time you sign on.

Enter the following command from the IBM System i machine command menu:

ADDLIBLE ADAS400


13 | Starting Host Server Daemons

Starting Host Server Daemons

To use the adapter’s Request-Response Service or Request-Response InvocationService, the remote command and distributed program call server daemon andthe data queue server daemon must be started on the IBM System i machine.

Enter the following command from the IBM System i machine command menu:

STRHOSTSVR SERVER(*RMTCMD)STRHOSTSVR SERVER(*DTAQ)


14 |

Chapter 2 Getting Started

This chapter describes the basic steps to configure and run the adapter. Details foreach step are provided later in the manual.

Topics

• Prerequisites, page 15

• Configuring the Adapter, page 16

• Starting the Adapter, page 21


15 | Prerequisites

Prerequisites

Before starting the configuration, ensure that all required software has beeninstalled and is operating correctly. For a list of required software, see TIBCOActiveMatrix Adapter for IBM i Installation.

This manual assumes that you know how to drag icons in TIBCO Designer andsave projects. If you are not familiar with these topics, read the TIBCO Designerdocumentation, which can be accessed from the Help > Designer Help menuoption in TIBCO Designer.


16 | Configuring the Adapter

Configuring the Adapter

ActiveMatrix Adapter for IBM i is configured with TIBCO Designer. To configurethe adapter, complete the following tasks:

• Task A, Creating a Project, page 16

• Task B, Creating and Configuring an Adapter Instance, page 17

• Task C, Creating and Configuring a Service, page 19

Task A Creating a Project

The TIBCO Designer GUI is used to configure adapter instances. When startingDesigner, you must create or select a project. A project contains the configurationfiles that define options used by a runtime adapter.

To create a project, complete the following steps:

1. Start TIBCO Designer by executing one of the following platform-specificcommands:

— On Microsoft Windows

Click Start > All Programs > TIBCO > TIBCO Designer versionNumber >Designer versionNumber.

— On UNIX

From a command window, change the directory toinstall-path/TIBCO/designer/version/bin and then enter ./designer.

2. Click the New Empty Project button in the TIBCO Designer startup panel.

3. Click the Multi-File Project tab in the Save Project dialog. Click the Select afile from the file system button next to the Project Directory field to save theproject, and then click the OK button to open the TIBCO Designer Window.

The name of the project will be the same as the last file name of the projectdirectory. For example, if you want to save the project in theD:\Work\AS400\example\IBMiDemo directory, the name of the project will beIBM i Demo, as shown in Figure 1.



Figure 1 Save Project

Task B Creating and Configuring an Adapter Instance

After creating a project, you have to create an adapter instance and configure it toaccess the IBM System i machine.

To create and configure an adapter instance, complete the following steps:

1. Select the project created in the preceding task in the Project Explorer.

2. Drag the IBM i Adapter Configuration icon from the IBM i Adapter Palettespanel to the Design panel on the right.

3. Specify the instance name in the Configuration tab. The default name isIBMiAdapterConfiguration. Check the Show All Tabs check box to showthe advanced options configuration.



4. Click the Design-time Connection tab to set the server connection for theproject (see Figure 2):

— Enter the name of the IBM System i machine for the connection in theServer Name field. It can be either an IP address or a machine name.

— Enter a valid user name and the corresponding password that will be usedto access the server in the User field and the Password field. Check theRemember Password check box.

— Click the Browse Resources button next to the Work Library field to selecta library. The popup window displays all the available libraries on the IBMSystem i machine, to which the design-time user profile is authorized.

— Click the Browse Resources button next to the Library List field to select alist of libraries. A library list on the IBM System i machine is equivalent toPATH on Microsoft Windows platforms or LD_LIBRARY_PATH on UNIXplatforms.

— Check the Use Design-time Connection For Run-time check box if it is notchecked.

— Click the Test Connection button to verify the connection information.

— Click the Apply button to save your configuration.

You can also use SSL for connection by checking the Use SSL For Connectioncheck box.



Figure 2 Creating an Adapter Instance

5. Save your project.

Task C Creating and Configuring a Service

After configuring the adapter instance, you have to add and configure adapterservices that perform the data passing operations for the adapter. See AdapterInstance Options on page 24 for instructions on each service. You can add morethan one service to an adapter instance.

Take the Publication Service for example. To add and configure a PublicationService, complete the following steps:

1. Expand the adapter instance folder in the Project Panel, for example,IBMiAdapterConfiguration. Select the Adapter Services folder.

2. Drag a Publication Service icon from the IBM i Adapter Palettes to the DesignPanel.



3. Specify the service name and transport type in the Configuration tab. Clickthe Apply button to save your configuration. See Configuration Tab onpage 43 for more information.

4. Specify the data queue for publish, data queue for error, source type, sourcefile, and member name in the Queue Configuration tab. Click the Applybutton to save your configuration. See Queue Configuration Tab on page 44for more information.

5. Define the message schema for the service in the Message Schema tab. Clickthe Apply button to save your configuration. See Message Schema Tab onpage 46 for more information.

6. Save your project.

After completing the previous tasks, you have to create a process linking with theactivities in the ActiveEnterprise Adapter Palettes to deal with certain workflow.For detailed information about creating and configuring a process, see TIBCODesigner User’s Guide. For detailed information about configuring the activities,see TIBCO ActiveMatrix BusinessWorks Palette Reference.


21 | Starting the Adapter

Starting the Adapter

This section describes three ways to start the adapter:

• Starting the Adapter with the Adapter Tester, page 21

• Starting the Adapter from the Command Line with a Repository File, page 22

• Starting the Adapter from the Command Line with a Properties File, page 22

You can also deploy the adapter with TIBCO Administrator. For moreinformation, see Deploying the Adapter with TIBCO Administrator on page 76.

Starting the Adapter with the Adapter TesterThe Adapter Tester allows you to verify an adapter instance while working in thedesign-time mode in TIBCO Designer. To start the adapter with the AdapterTester, the adapter and TIBCO Designer must be installed on the same machine.

1. Start TIBCO Designer.

2. From the Tools menu, select Show Adapter Tester.

3. In the left pane, select the adapter instance that you want to start.

4. Click the Run Settings tab. In the Working Directory field, enter a directoryto place running files.

5. In the Adapter Executable field, select the executable. For example, TIBCOActiveMatrix Adapter for IBM i 6.2 (adas400.exe).

Figure 3 Adapter Tester



6. Click the Apply button.

7. Click the Start button. To view the output messages, click the Console tab.

Starting the Adapter from the Command Line with a Repository FileTo start the adapter from the command line with a repository file, the project mustbe run as a local repository and saved in DAT (repository) format.

Task A Converting the Project to a Repository File

To export the project to a local repository, complete the following steps:


2. From the Project menu, select Export Full Project.

3. In the Export Project dialog, click the Local Repository tab, enter the projectname and the output directory. Click the OK button.

4. In the Create Project dialog, select File Type and TIBCO MessagingEncoding. Click the Yes button.

Task B Starting the Adapter

The adapter can be run by specifying the path of the DAT file in the repo URL, inthe properties file or TIBCO Runtime Agent.

1. At the command prompt, go to the ADAS400_HOME\bin directory, which hoststhe adapter executable.

2. Enter the following command to start the adapter:

adas400.exe -system:repourl repository_file_url -system:configurlconfiguration_url

For example,

adsd400.exe -system:repourl D:\example\sample.dat-system:configurl IBMiAdapterConfiguration

Starting the Adapter from the Command Line with a Properties FileTo start the adapter from the command line with a properties file, the project mustfirst be converted to a repository file.

Task A Converting the Project to a Repository File

To export the project to a local repository, complete the following steps:




2. From the Project menu, select Export Full Project.

3. In the Export Project dialog, click the Local Repository tab, enter the projectname and the output directory. Click the OK button.

4. In the Create Project? dialog, select File Type and TIBCO MessagingEncoding. Click the Yes button.

Task B Creating a Properties File

To create a properties file for the adapter instance, complete the following steps:

1. Open a command window.

2. Change the directory to the adapter bin directory, that is,ADAS400_HOME\bin.

3. Copy adas400.tra to a new text file. For example, test01.tra.

4. Open the test01.tra file in a text editor and change the file as follows:

— Change #tibco.repourl <repourl> to tibco.repourl repository_file_url.For example, tibco.repourl ADAS400_HOME/examples/samples.dat

— Change #tibco.configurl <configurl> to tibco.configurl

IBMiAdapterInstanceName. For example, tibco.configurlIBMiAdapterConfiguration

— Change application.args -system\:perfMon -system:propfile

ADAS400_HOME/bin/adas400.tra to application.args-system\:perfMon -system:propFile

ADAS400_HOME/bin/test01.tra

— Change application.start.dir ADAS400_HOME toapplication.start.dir repository_file_path. For example,application.start.dir ADAS400_HOME/examples.

5. Save the file.

Task C Starting the Adapter

To start the adapter, complete the following steps:

1. At the command prompt, go to the directory that hosts the adapter executable.

2. Enter the following command to start the adapter:

adas400.exe -run -propFile test01.tra


24 |

Chapter 3 Adapter Instance Options

This chapter explains how to create and design an adapter instance using theadapter instance tabs in TIBCO Designer. Adding services to an adapter isdescribed in Adapter Service Options on page 37.

Topics

• Configuration Tab, page 25

• Design-time Connection Tab, page 27

• Run-time Connection Tab, page 29

• General Tab, page 31

• Multithreading Tab, page 32

• Logging Tab, page 33

• Startup Tab, page 35

• Monitoring Tab, page 36


25 | Configuration Tab

Configuration Tab

Define the options on the Configuration tab before configuring the other options.

Guidelines for Choosing an Instance Name

• An instance name must use alphanumeric characters. An underscore (_)character can be used. The entire instance name must be less than 80characters. The space character cannot be used in an instance name.

• An instance name cannot use global variables.

• An instance name must be unique with respect to other adapter instances forthe same adapter in the project. The same instance name can be used to namean adapter instance for a different adapter in the same project. For example,an IBM i adapter instance named TEST and a Siebel adapter instance namedTEST can coexist in the same project.

• Each instance name must be unique per adapter within a project even if eachinstance is defined in a different folder. That is, configuring same-namedadapter instances in different folders will not make their names unique.

Table 1 Fields of Configuration Tab

Field Description

Instance Name Use the default name or replace it with a name of your choice. See Guidelines for Choosingan Instance Name on page 25.

Version The version string indicates the ActiveEnterprise (AE) format in which the adapterinstance is saved.

Description Provide information about the adapter instance that you want to store in the project. Thisfield is optional.

Message Filter If you have configured a message filter resource for use with the adapter, specify amessage filter. The message filter allows you to manipulate incoming and outgoing databefore sending it on the network or handing it to the target application.

Message filters can be written using the TIBCO Adapter SDK. See TIBCO Adapter SDKProgrammer’s Guide for instructions on how to write a message filter.

Show All Tabs Check this check box to display the General tab and Multithreading tab for advancedoptions configuration.


26 | Configuration Tab

When you create an adapter instance, several resources are automatically createdfor it. The names of these resources derive from the name of the instance to whichthey belong. Changing the adapter instance name results in an automaticregeneration of the resources names. If you manually modify any resource name,that particular name will not be automatically regenerated the next time yourename the adapter instance.


27 | Design-time Connection Tab

Design-time Connection Tab

Many of the following fields make use of global variables. Click the GlobalVariables tab in the project panel to edit or browse the value for a global variable.

Table 2 Fields of Design-time Connection Tab

Field Description

Server Name The IP address or machine name of the IBM System i machine for this connection.

User The IBM i user profile name.

A user profile is used to connect to the IBM System i machine when configuring theadapter at design time. The user profile must have enough authority to access objectsthat will be used in service configurations. Also, the user profile must have full authorityfor the library specified in the Work Library field.

Password Password for the user profile.

RememberPassword

If not checked, the password must be entered each time the project is opened.

If checked, the password will be stored in the project repository.

Use SSL forConnection

Specify whether you want to use SSL for the connection to the IBM i system. Check thischeck box to enable SSL connection for the adapter.

Note: Before you use SSL for connection, make sure that the following code has beenadded in the designer.tra file and adas400.tra file:java.property.com.tibco.security.EntrustLast=true

You can enable the SSL log by setting As400.debug=4 in the adas400.tra file. Youcan review the log by selecting Windows > Show Console from the menu bar in TIBCODesigner.

The designer.tra file is in the TIBCO_HOME\designer\version\bin directory, and theadas400.tra file is in the TIBCO_HOME\adapter\adas400\version\bin directory.

File for CA Specify the location of the certificate used to verify the identities of clients.

Click the button to locate the certificate.

This field is displayed only when the Use SSL for Connection check box is checked.

Password for CA Password for connecting to the IBM i system.


Work Library Name of the library that will be used to generate temporary object lists and as a defaultlibrary when generating any adapter services configuration related objects.

Type the name of the library manually in this field or click the Browse Resources buttonnext to this field to open the Select A Library dialog. All libraries are listed in the dialog.


28 | Design-time Connection Tab

Library List A library list on the IBM System i machine is equivalent to PATH on Microsoft Windowsplatform or LD_LIBRARY_PATH on UNIX platforms.

Type a library name or type multiple library names separated by a comma manually inthis field, or click the Browse Resources button next to this field to select library in theSelect Libraries In Library List dialog. You can hold the Ctrl key and click on the itemsyou want, in order to select multiple items. Select libraries in the popup window in theorder that the libraries are displayed in the library list.

Use Design-timeConnection forRuntime

Check this check box to use this connection at runtime. If not checked, you have tospecify runtime connection parameters in the Run-time Connection tab.

Generate UtilityPrograms

Check this check box to generate utility programs (PUBLISHER, RPCCLIENT,RPCSERVER, and SUBSCRIBER) on the IBM System i machine.

If not checked, the utility programs won’t be generated.

Test Connection Click this button to test the validity of the connection information that you specified forthe adapter instance in the design phase.

Table 2 Fields of Design-time Connection Tab (Cont’d)

Field Description


29 | Run-time Connection Tab

Run-time Connection Tab

If you have checked the Use Design-time Connection for Runtime check box inthe Design-time Connection tab, some options in the Run-time Connection tabwill inherit design-time configuration and cannot be changed.

Table 3 Fields of Run-time Connection Tab

Field Description

Server Name The IP address or machine name of the IBM System i machine for this connection.

User The IBM i user profile name.

A user profile is used to connect to the IBM System i machine at run time. The userprofile must have enough authority to access objects that will be used in serviceconfigurations.

Password Password for the user profile.

Library List Clicking the Browse Resources button next to this field will bring up a popup windowwith the list of libraries. You can select multiple libraries from the list by pressing theCtrl key.

You must select libraries in this popup window in the order that the libraries have to bedisplayed in the library list.

Initial Program ToRun

Initial program is a command that will be called each time a new connection isestablished with the IBM System i machine.

For example, you can enter ADDLIBLE ADAS400 in this field to add the ADAS400library to a library list when a new connection is established.

This option is also useful if you want to run additional commands for newly createdconnections after reconnection.

The initial program cannot contain any runtime parameters.

File for CA Specify the location of the certificate used to verify the identities of clients.

Click the button to locate the certificate.


Password for CA Password for connecting to the IBM i system.


Initial No ofConnections

The number of connections that have to be made to the adapter when the adapter startsup.

Maximum No ofConnections

The maximum number of connections that can be made to the adapter.


30 | Run-time Connection Tab

Retry Total The total number of reconnection attempts to make before the runtime adapter oradapter service is stopped. A value of -1 means reconnection attempts will continueindefinitely.

AdapterTerminationCriteria (after maxnumber ofreconnect attempts)

This option is not applicable for ActiveMatrix Adapter for IBM i.

TIBCO ActiveMatrix Adapter for IBM i continues running after the maximum numberof reconnect attempts, but stops attempting to reconnect. After this point, the adapterthrows a connection exception when it receives a new request.

Test Connection Click this button to test the validity of the connection information that you specified forthe adapter instance.

Table 3 Fields of Run-time Connection Tab (Cont’d)

Field Description


31 | General Tab

General Tab

This tab has no fields.

Encoding for the adapter can be set by specifying an IBM System i user profilewith the appropriate coded character set identifier (CCSID) in the Run-timeConnection tab.


32 | Multithreading Tab

Multithreading Tab

Request-Response Service and Subscription Service process inbound requests tothe adapter. The thread count can be used to control the number of inboundrequests to be processed by the adapter concurrently.

Table 4 Fields of Multithreading Tab

Field Description

Inbound Thread Count Number of threads to process requests inbound to the adapter.


33 | Logging Tab

Logging Tab

The following table lists the configurations in the Logging tab.

Guidelines for Creating and Configuring the Sinks

To create and configure the sinks, complete the following steps:

1. Check the Use Advanced Logging check box.

2. In the Design panel, double-click the Advanced folder.

3. Double-click the Log Sinks folder.

Table 5 Fields of Logging Tab

Field Description

Use AdvancedLogging

If selected, you have full control of selecting the destinations and associating roles witheach of the destinations.

If not selected, you can set two standard output destinations (sinks) for trace messages andset the tracing level for the roles selected.

By default, this check box is not checked.

Log to StandardI/O

(STDIO Sink) When the Log to Standard I/O check box is checked, trace messages aredisplayed in the command prompt window where the adapter is started.

When not selected, trace messages are not displayed in the window.

By default, this check box is checked.

Log File The name of the log file (log sink) to which trace messages are written. Global variables canbe used to specify the location of the log file. See Global Variables on page 92 for moreinformation.

When configuring the adapter to run as a service, ensure that the absolute path is used forthe log file name. For more information about tracing and logged messages, see TIBCOActiveMatrix Adapter for IBM i Concepts.

LogInfo/Debug/Warning/ErrorMessages

Trace messages of the selected levels will be collected in the named log sink. You canspecify which levels of trace messages are logged, and where trace messages are sent.

There are three types of logs (log sinks) that you can configure to hold trace messages,corresponding to three levels (roles) of trace messages, Information, Warning, and Error. Afourth level of trace messages, Debug, is reserved and must not be enabled unlessrequested by the TIBCO Product Support Group. To hold Debug trace messages will writea lot of information to the log file and significantly degrades the performance of theadapter.

Turning on the levels can affect the performance of the adapter. Therefore, it isrecommended to turn on the required levels only.


34 | Logging Tab

4. You can customize the predefined sinks or create new sinks.

— To customize the predefined sinks, fileSink and stdioSink, select themin the Design panel, then modify settings in the Configuration tab.

— To create a new sink, drag the Generic Log Sink icon from the Palettespanel to the Design panel. Then, in the Configuration tab, select the sinktype. Click the Apply button, and then configure the sink.

There are four sink types available: File, Hawk, Network, and STDIO. Each hascertain configuration options.

• For the File sink, the file name, file limit, file count, and the option to appendor overwrite can be specified. When created by default, the file limit, filecount, and append mode are set to 30000 bytes, 3, and append respectively.

• For the STDIO sink, the option to write to stdout or stderr can be selected.When created by default, stdout is selected.

• The Hawk sink uses the Hawk session, created and used by the adapter formonitoring purposes, to send tracing messages to the TIBCO Hawk monitoror Display.

For details on Hawk sessions, see Global Variables on page 92. Theconfiguration for the Hawk sink involves specifying the MicroAgent Namethat must be specified in the Configuration tab.

• The Network sink is used to publish tracing message on TIBCO Rendezvous.

The configuration of a network sink involves specifying the session and thesubject on which the trace messages have to be published.

For all the sinks, optionally the name and description for the sinks can beprovided.


35 | Startup Tab

Startup Tab

The following table lists the configurations in the Startup tab.

Table 6 Fields of Startup Tab

Field Description

Show StartupBanner

The startup banner displays the runtime adapter version, the infrastructure version onwhich the adapter is built, and the copyright information in the console window when theadapter is started.

MetadataSearch URL

The location where the adapter searches for base schemas. The adapter searches for anyschema that has been defined and saved at this location, and that must be loaded atstartup.


36 | Monitoring Tab

Monitoring Tab

Many of the following fields make use of global variables. See Global Variables onpage 92 for more information.

Table 7 Fields of Monitoring Tab

Field Description

Enable StandardMicroAgent

Turn on or turn off the standard TIBCO Hawk MicroAgent.

Clicking the globe button, you can switch the method of configuration between astandard check box and text value (true or false).

StandardMicroAgent Name

The name for the standard micro agent that will be registered with the TIBCO Hawksystem.

In most cases, the default value is used. The InstanceId variable need not be set becauseit is automatically set at runtime by the runtime adapter.

StandardMicroAgentTimeout(ms)

The timeout value for the standard micro agent in milliseconds.

Enable ClassMicroAgent

Turn on or turn off the instance or class-specific standard TIBCO Hawk MicroAgent.

Clicking the globe button, you can switch the method of configuration between astandard check box and text value (true or false).

Class MicroAgentName

The name for the class micro agent that will be registered with the TIBCO Hawksystem.

In most cases, the default value is used.

Class MicroAgentTimeout(ms)

The timeout value for the class micro agent in milliseconds.

DefaultMicroAgentSession

The name of the TIBCO Rendezvous session that will be used by the standard, class,and custom micro agents.

Do not change the session name and the corresponding session, which areautomatically generated by TIBCO Designer. However, you can navigate to theSessions folder under the Advanced folder to modify the session parameters ifrequired.

Ensure that you have set the correct parameter value for the global variables thatcorrespond to the TIBCO Hawk configuration. Otherwise, the micro agents are notdisplayed in the TIBCO Hawk Display.

For a list of all supported micro agents, see Available Micro agents on page 106.


37 |

Chapter 4 Adapter Service Options

After configuring an adapter instance, assign one or more adapter services to theinstance. All configuration tasks are performed in TIBCO Designer.

Topics

• Transport Specific Service Options, page 38

• Publication Service Tabs, page 43

• Subscription Service Tabs, page 49

• Request-Response Service Tabs, page 56

• Request-Response Invocation Service Tabs, page 68

• Adapter Service Options Supplement, page 74


38 | Transport Specific Service Options

Transport Specific Service Options

The transport type (Rendezvous or JMS) you select for the runtime adapterdetermines transport specific service options such as Quality of Service, deliverymode, wire format, and so on. Only options that are compatible with the transporttype of a service are available.

This section explains transport type and some of the transport specific serviceconfiguration options, as follows:

• Transport Type, page 38

• Quality of Service, page 39

• Wire Format, page 40

• Connection Factory Types, page 41

• Delivery Modes, page 41

Transport TypeThere are two transport types available for the runtime adapter, namely JMS andRendezvous. After selecting the transport type, you can configure the transportspecific options.

• TIBCO Rendezvous Transport — This transport uses subject-basedaddressing to support both multicast or broadcast and point-to-pointcommunications.

• JMS Transport — TIBCO Enterprise Message Service must be installed touse the JMS transport. The JMS administration interfaces allow you to createand manage administered objects such as Connection Factories.

JMS clients can retrieve references to these objects by using Java Naming andDirectory Interface (JNDI). Creating static administered objects allows clientsto use these objects without having to implement the object within the client.

When a JMS client starts, it performs a JNDI lookup for the connectionfactories that it needs. For details on JNDI, see the TIBCO Enterprise MessageService User’s Guide.

The transport can be configured to use a trusted store and identity resource foruse in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessionsand JMS topics have an SSL configuration field that uses a dialog to perform SSLconfiguration.



To enable and configure SSL, complete the following steps:

1. In the Project panel, select the adapter instance.

2. Expand Advanced > Sessions, and then select the TIBCO Rendezvous sessionor JMS topic.

3. Check the Use SSL? check box.

4. Click the Configure SSL button to do further configuration.

The SSL configuration options are explained in the online help associated with thesession dialog.

Quality of ServiceIf Rendezvous is selected as the transport type, select Quality of Service.

Certified (RVCM)

Guarantees that every certified message reaches its intended recipient in the ordersent. The message can be sent across network boundaries and, if a network fails,delivery attempts continue until it succeeds or the message times out. This iscalled certified message delivery.

If certified message delivery is used, data is stored in a ledger file. The size of theledger depends on several factors, the most important one is the retention rate ofstored data. That is, the ledger grows fastest in response to the cumulative lengthof undeliverable messages. Ensure that sufficient disk space is available for theexpected size of the ledger.

Reliable (RV)

Ensures that each multicast or broadcast message is received as long as thephysical network and packet recipients are working. It also ensures that the lossof a message is detected.

This option can compensate for brief network failures because it can retransmit amessage on request if the first attempt failed. This choice is appropriate whenmessage delivery is expected but some loss can be tolerated.

Distributed Queue (RVDQ)

Distributed queue includes a group of cooperating transport objects, each in aseparate process. Each transport object is called a member. To balance thetransmission load among servers, the adapter can use distributed queues forone-of-n delivery of messages to a group of servers. Each member of a distributed



queue listens for the same subject using the TIBCO Rendezvous DistributedQueue listener objects. Even though many members listen for each inboundmessage (or task), only one member processes the message. For details ondistributed queues, see TIBCO Rendezvous Concepts.

In the queue mode within TIBCO Enterprise Message Service, each listener is asingle receiver of a point-to-point message. However, the listeners can beconfigured as a set of receivers, each of which receives a fraction of the messages.For details on TIBCO Enterprise Message Service distributed queues, see theTIBCO Enterprise Message Service User’s Guide.

Load balancing for the processing of TIBCO Rendezvous or JMS messages issupported using distributed queuing. The messages from TIBCO Rendezvous orTIBCO Enterprise Message Service are distributed equally among all instancesthat belong to the same group. This distributes the data load over several adapterinstances. However, the order in which the data is sent to the application server isnot guaranteed.

Wire Format

Rendezvous Message

The Rendezvous Message is available only for the Rendezvous transport.

Control information for validation is not sent in the message. If you use thisformat, the adapter is compatible with adapters not developed with TIBCOAdapter SDK.

XML Message

The XML Message wire format conforms to specifically constructed and fullycompliant XML Schema (XSD) based on the existing definition of theActiveEnterprise schema.

ActiveEnterprise Message

The ActiveEnterprise Message is available only for the Rendezvous transport.

For the XML Message wire format, when carriage returns are passed through theadapter, they are converted to line feeds. This behavior is as per the W3Cspecifications.



Control information for validation is sent in the message. If no controlinformation is included, an exception is returned to the subscriber.ActiveEnterprise standard wire format provides class information and packingrules for the TIBCO Adapter SDK set of data types. This format allowsActiveEnterprise components to perform extra validation on messages sent orreceived.

See TIBCO Adapter SDK Programmer’s Guide for details about the controlinformation generated and sent with ActiveEnterprise messages.

Connection Factory TypesFor JMS transport, two types of connection factories are available.

Topic

A message published to a topic is broadcast to one or more subscribers. Allmessages published to the topic are received by all services that have subscribedto the topic. This messaging model is known as publish-subscribe.

Queue

A message sent to a queue is consumed by one and only one receiver. Eachmessage has only one receiver though multiple receivers may connect to thequeue. The first receiver to access the queue gets the message. The other receiversdo not. This messaging model is known as point-to-point.

Delivery ModesFor JMS transport, two groups of delivery modes are available.

Publication Service, Request-Response Invocation Service

• Persistent—In general, a message marked as persistent will be available to aJMS client even if the EMS server goes down.

Messages sent with the persistent delivery mode are always written topersistent storage, except when they are published to a topic that has nodurable subscribers. When a topic has no durable subscribers, there are nosubscribers that need messages resent in the event of a server failure.Therefore, messages do not have to be saved, and performance is improvedbecause disk I/O is not required.

• Non-Persistent—A message marked as non-persistent will not be available toa JMS client if the EMS server goes down.



Subscription Service, Request-Response Service

• Durable—In general, a message marked as durable will be available to a JMSclient even if the EMS server goes down.

• Non-Durable—A message marked as non-durable will not be available to aJMS client if the EMS server goes down.

See TIBCO Enterprise Message Service User’s Guide for more information about thesemantics for this field.


43 | Publication Service Tabs

Publication Service Tabs

The following tabs are available:


• Queue Configuration Tab, page 44

• Message Schema Tab, page 46

• Transport Tab, page 47

• Schema Tab, page 48

Configuration TabThe Configuration tab contains the following fields, as shown in Table 8.

Table 8 Configuration Tab of Publication Service

Field Description

Name Name of the service. You can use the default name or replace it with a name of your choice.

A service name must use alphanumeric characters. An underscore (_) character can beused. The entire instance name must be less than 80 characters. The space character cannotbe used in an instance name. A service name cannot use global variables.

Description Additional information about the Publication Service being configured. This field isoptional.

Transport Type The transport to be used by the runtime adapter, JMS or Rendezvous. See Transport Typeon page 38 for details.



Queue Configuration TabThe Queue Configuration tab contains the following fields, as shown in Table 9.

Table 9 Queue Configuration Tab of Publication Service

Field Description

Data Queue ForPublish

The name of the data queue (*DTAQ object) that will be used for publishing the messagefrom an application running on the IBM System i machine.

You can assign a global variable to this field. The format of the data queue name islibrary_name/data_queue_name.

By default, the name of the data queue is ADAS400PUB in the work library of the adapterinstance. If the data queue specified does not exist, it will be created with an entry length of10000 characters.

Type the data queue name manually in this field, assign a pre-defined global variable, orclick the Browse Resources button next to this field to open the Select A Data Queue ForPublishing Message dialog. All libraries are listed in the dialog. You can expand eachlibrary to view a list of available data queue (*DTAQ) objects. You can also select a libraryand create a new data queue in it.

Is Data QueueShared?

Whether a data queue specified for a service is shared among multiple services. SeeGuidelines for Using Shared Data Queue on page 46 for details.

Is Peek/ReadUsed?

If selected, you can customize the polling interval of the Publication Service to poll an IBMSystem i machine for messages in the data queue. This can be done using the propertynamed adas400.pollingInterval in the properties file, or by typing the interval inthe Polling Interval fields. See Predefined Properties on page 83.

If not selected, the Publication Service will be blocked when there are no messages in thedata queue.

Is PublisherKey Used?

If selected, Publication Service uses a specified key value to query a keyed data queue.Only those messages that have a matching key will be published.

If not selected, messages are published regardless of the key.

Publisher Key Value of the key used to query the keyed data queue. Available only if the Is PublisherKey Used check box is checked.



Data Queue ForError

The name of the error data queue (*DTAQ object). When the adapter fails to retrieve amessage from a data queue for publishing due to an incorrect message format, the messagewill be removed from the data queue for publishing and put in an error data queue.

Type the error data queue name manually in this field or click the Browse Resourcesbutton next to this field to open the Select A Data Queue When There Is An Error dialog.All libraries are listed in the dialog. You can expand each library to view a list of availabledata queue (*DTAQ) objects. You can also select a library and create a new data queue in it.

Note: The name of the data queue for publishing and error data queue must be different.The type of the data queue for publishing and the type of the error data queue must be thesame, for example, both of them are keyed data queue (the length of the keys must be thesame, or an error occurs).

Polling Interval(milliseconds)

The time interval in milliseconds that the adapter retrieves messages from the data queuefor publishing. The default value is 0 milliseconds. If you use the default value, the adapteruses the polling interval defined in the property named adas400.pollingInterval inthe properties file.

Type the time interval manually or use a predefined global variableadas400.publisher.polling.interval. See Global Variables on page 92 for details.

Note: If you want to change the polling interval after deploying the project on TIBCOAdministrator, you have to set the polling interval in TIBCO Designer using thepredefined global variable.

GenerateSource Type

When message schema is defined for the publisher, a copy source member containing themessage schema will be generated in a library on the IBM System i machine. This fieldspecifies the type of generated source member.

The generated source type can only be ILE RPG in the current release.

Generate inSource File

The source file in which the source member for message schema will be generated. Thesource file name must be specified as library_name/source_file_name.

By default, the source file name is ADAS400SRC in the work library of the adapter instance.If the source file specified does not exist, it will be created with an entry length of 112characters.

Type the name of the source file manually in this field or click the Browse Resourcesbutton next to this field to open the Select A Source File dialog. All libraries are listed in thedialog. You can expand each library to view the list of available file (*FILE) objects. Youcan also select a library and create a new source file in it.

GenerateMember ofName

Name of the source member that will be generated.

Table 9 Queue Configuration Tab of Publication Service (Cont’d)

Field Description



Guidelines for Using Shared Data Queue

• If a data queue is marked as shared, the data queue can be shared with otherPublication Service and Request-Response Invocation Service.

Each message entry in a shared data queue must contain a routing header. If amessage is published to the shared data queue using the PUBLISHERprogram, which is generated by the adapter at design-time, the routing headerinformation is automatically added to the message.

• If a data queue is marked as non-shared, it cannot be shared with otherservices.

• The application program running on IBM System i machine publishesmessages to a non-shared data queue through system APIs.

Message Schema TabThis tab allows you to browse and define the message schema for PublicationService.

• The schema for the message must be defined under the Entry schema elementin the main schema for the service.

• If the Data Queue for Publish specified is a keyed data queue, key elementscan also be defined in this tab. The key elements must be defined under theKey schema element in the main schema.

Figure 4 Message Schema Tab of Publication Service

See Defining Message Schema on page 74 for instructions on how to define themessage schema.

Click the Upload button to upload the message schema to the IBM System imachine and generate the ILE RPG source for the schema.



Transport TabThe Transport tab contains the following fields, as shown in Table 10.

Table 10 Transport Tab of Publication Service

Field Description

MessageSubject

Available only for the Rendezvous transport.

By default, a service uses a message subject that is generated using the Domain andDeployment global variables, the adapter acronym, the adapter instance name, and theservice name. To use this default subject, ensure that the values for Domain andDeployment are not empty.

You can type a TIBCO Rendezvous subject name that is different from the default in thisfield. See TIBCO Rendezvous Concepts for instructions on how to specify subject names.

Reply MessageSubject


The TIBCO Rendezvous subject name that the adapter uses to respond, if no responsesubject is specified in the request message.

Destination Available only for the JMS transport.

By default, a service uses a dynamic destination that is generated using the Domain andDeployment global variables, the adapter acronym, the adapter instance name, and theservice name. To use this default dynamic destination, ensure that the values for Domainand Deployment are not empty.

You can override the default dynamic destination by specifying the static destination inthis field. The static destination must be defined on the EMS server before it can be used bythe runtime adapter. See the TIBCO Enterprise Message Service User’s Guide for informationabout destinations.

ReplyDestination

Available only for the JMS transport.

The subject to receive a response from TIBCO Enterprise Message Service.

Quality ofService

Available only for the Rendezvous transport. It can be Certified or Reliable. See Quality ofService on page 39 for details.

Wire Format Services must use the same wire format to exchange data. It can be Rendezvous Message(Rendezvous only), XML Message (JMS or Rendezvous), or ActiveEnterprise Message(Rendezvous only). See Wire Format on page 40 for details.

ConnectionFactory Type

Available only for the JMS transport. It can be Topic or Queue. See Connection FactoryTypes on page 41 for details.

Delivery Mode Available only for the JMS transport. It can be Persistent or Non-Persistent. See DeliveryModes on page 41 for details.



Schema TabThe Schema tab contains the following fields, as shown in Table 11.

SessionReference

Every adapter instance can have one or more sessions configured for it. Sessionsencapsulate stateful connections to TIBCO Rendezvous and other messaging sources. Thesession object shown in this field is initially supplied by the adapter, depending on theQuality of Service selected. You can change the session by browsing for it in the projectpanel.

EndpointReference

The location in TIBCO Repository where the endpoint information is stored (default).

You can go to the referenced endpoint to edit its properties. Endpoint reference objects areexplained in TIBCO Designer Palette Reference.

Table 10 Transport Tab of Publication Service (Cont’d)

Field Description

Table 11 Schema Tab of Publication Service

Field Description

Class Reference The class reference for a service is set automatically.


49 | Subscription Service Tabs

Subscription Service Tabs



• Service Options Tab, page 50


• Program Schema Tab, page 52

• Message Monitor Tab, page 53




Table 12 Configuration Tab of Subscription Service

Field Description



Description Additional information about the adapter service being configured. This field is optional.




Service Options TabThe Service Options tab contains the following fields, as shown in Table 13.

Table 13 Service Options Tab of Subscription Service

Field Description

Service Type There are two types of Subscription Service:

Data Queue Write Writes messages to data queues on IBM System i machine eitherasynchronously or synchronously.

Program Call Invokes application programs running on the IBM System i machine.

Options Available for the Data Queue Write Service Type

Data QueueName

Name of the data queue (*DTAQ object) that sends the request message to the IBM Systemi machine. The format of the data queue name is library_name/data_queue_name.

Type the data queue name manually in this field, assign a pre-defined global variable, orclick the Browse Resources button next to this field to open the Select A Data Queue ForWrite Operation dialog. All libraries are listed in the dialog. You can expand each library toview a list of available data queue (*DTAQ) objects. You can also select a library and createa new data queue in it.

GenerateSource Type

When the message schema is defined for the service, a copy source member containing themessage schema is generated in a library on the IBM System i machine. This field acceptsthe type of generated source member. The generated source type can only be ILE RPG inthe current release.


The name of the source file where the message schema will be generated. The format of thesource file name is library_name/source_file_name.

Clicking the Browse Resources button next to this field will bring up a popup window witha list of libraries. You can expand each library to view a list of file (*FILE) objects availablein that library.

Type the name of the source file manually in this field or click the Browse Resources buttonnext to this field to open the Select A Source File dialog. All libraries are listed in the dialog.You can expand each library to view a list of file (*FILE) objects available in that library.


Name of the source member to be generated. The source member is created based on themessage schema.



Options Available for the Program Call Service Type

When the service type is Program Call, you can add the programcallTimeout attribute to the .trafile to set a timeout value expressed in seconds.

Program Object Name of the program object (*PGM object). The format of the program object name islibrary_name/program_name.

Type the name of the program object manually in this field, assign a pre-defined globalvariable, or click the Browse Resources button next to this field to open the Select AProgram dialog. All libraries are listed in the dialog. You can expand each library to viewthe list of available program (*PGM) objects.

Source File (Optional) Name of the source file that contains the program source member. The format ofthe source file name is library_name/source_file_name. This field is optional, you can create aschema for the program object manually.

Type the name of the source file in this field or click the Browse Resources button next tothis field to open the Select A Source File dialog. All libraries are listed in the dialog. Youcan expand each library to view a list of available file (*FILE) objects.

Source Member Name of the program source member.

PCML File Name of the PCML file that contains programs.

Type the name of the PCML file in this field or click the Browse Resources button next tothis field to navigate to the location of the PCML file. You can load parameters from thePCML file to invoke PGM objects.

Note: Ensure that the pcml file extension is in lowercase. To enter program schema usingthe PCML file, use the JT400 jar version 9.1 that supports character datatypes with size over1MB.

PCML ProgramName

Name of a specific program contained in the PCML file.

Note: The program name is case sensitive and must exactly match the name in the PCMLfile.

LoadParameters

When this button is clicked, the source for the program is parsed to retrieve programparameters. Then the retrieved program parameters are populated as a schema in theProgram Schema tab.

Note: The maximum data transmission size that can be supported by ActiveMatrixAdapter for IBM i is 16,000 bytes. This is the total size of all the parameters passed to theremote program in a single call. The value must be equal to or less than the maximum size.

Table 13 Service Options Tab of Subscription Service (Cont’d)

Field Description



Message Schema TabThis tab is available only for the Data Queue Write service type. You can browseand define the message schema in this tab.

• The schema for the message must be defined under the Entry schema elementof the main schema for the service.

• If the specified data queue is a keyed data queue, key elements can also bedefined in this tab. The key elements must be defined under the Key schemaelement of the main schema.

Figure 5 Message Schema Tab of Subscription Service



Program Schema TabThis tab is available only for the Program Call service type.

In this tab, you can browse or define the schema for program parameters. If theprogram source is parsed successfully, the parameters are displayed as a schemaunder this tab. If the program source is not parsed successfully, the programparameters can be defined manually.

You can define program parameter attributes in the program schema by using theAdd and Delete buttons.

• Clicking the Add button will display a popup window where you can defineattributes in the program schema.

• To delete an attribute, select the attribute and press the Delete button.

• To edit the definition of an attribute, select that element and click the Editbutton.



The attributes can be moved up or down by clicking the Move Parameter buttons.

Figure 6 Program Schema Tab of Subscription Service

Message Monitor TabThis tab is available only for the Program Call service type.

If the invocation of the program configured in this service is likely to generatemessages (error or otherwise) to a message queue, you can define aRequest-Response Invocation Service for the monitoring messages in this tab.

Table 14 Message Monitor Tab of Subscription Service

Field Description

Message MonitorService Name

Name of the selected message monitoring Request-Response Invocation Service. Thisis a display only field.

Browse for MessageMonitor Service

Select a message monitoring Request-Response Invocation Service.

Create MessageMonitor Service

If there is no existing message monitoring Request-Response Invocation Service, clickthis button to create a new one.




Table 15 Transport Tab of Subscription Service

Field Description

MessageSubject







Quality ofService

Available only for the Rendezvous transport. It can be Certified, Reliable, or DistributedQueue. See Quality of Service on page 39 for details.

Wire Format Services must use the same wire format to exchange data. It can be Rendezvous Message(Rendezvous only), XML Message (JMS or Rendezvous), or ActiveEnterprise Message(Rendezvous only). See Wire Format on page 40 for details.



Delivery Mode Available only for the JMS transport. It can be Durable or Non-Durable. See DeliveryModes on page 41 for details.

SessionReference


EndpointReference

The location in TIBCO Repository where the endpoint information is stored.





Table 16 Schema Tab of Subscription Service

Field Description



56 | Request-Response Service Tabs

Request-Response Service Tabs



• Service Options Tab, page 57


• Program Schema Tab, page 63

• Message Monitor Tab, page 65




Table 17 Configuration Tab of Request-Response Service

Field Description







Service Options TabThe Service Options tab contains the following fields, as shown in Table 18.

Table 18 Service Options Tab of Request-Response Service (Sheet 1 of 5)

Field Description

Service Type There are four types of Request-Response Service, as follows:

Data Queue Write Writes messages to data queues on IBM System i machine eitherasynchronously or synchronously.

Program Call Invokes application programs running on the IBM System i machine.

Spooled File List Retrieves list of spooled files from the IBM System i machine.

Spooled File to PDF Retrieves a spooled file from the IBM System i machine andconverts it to PDF format. The current release supports conversion of only *SCS typespooled files to PDF format.

Service Program Call Invokes service programs running on the IBM System i machine.

Options Available for the Data Queue Write Service Type

Request DataQueue

Name of the data queue (*DTAQ object) that sends the request message to the IBM Systemi machine. A global variable can be assigned to this field. The format of the data queuename is library_name/data_queue_name.

The request queue can be either a keyed data queue or a none-keyed data queue. You candefine your own key and put it in the request message. By default, the request data queueis ADAS400SRQ in the work library of the adapter instance. If the specified data queuedoes not exist, it is created with entry length of 10000 characters and a key length of 112characters.

You can manually type the library and data queue with the formatlibrary_name/data_queue_name in this field, assign a pre-defined global variable, or click theBrowse Resources button next to this field to open the Select A Data Queue For WriteOperation dialog. All libraries are listed in the dialog. You can expand each library to viewa list of available data queue (*DTAQ) objects. You can also select a library and create anew data queue in it.

Note: You can dynamically set the request data queue library and data queue when theadapter is running. See Dynamically Setting the Program Object and Data Queue onpage 61 for details.



Reply DataQueue(optional)

Name of the data queue (*DTAQ object) that reads the reply message from the IBM Systemi machine. A global variable can be assigned to this field. The format of the data queuename is library_name/data_queue_name.

The reply data queue must be a keyed data queue. The reply data queue must be differentfrom the request data queue.

By default, the reply data queue is ADAS400SRY in the work library of the adapterinstance. If the specified data queue does not exist, it is created with an entry length of10000 characters and a key length of 112 characters.

You can manually type the library and data queue with the formatlibrary_name/data_queue_name in this field, assign a pre-defined global variable, or click theBrowse Resources button next to this field to open the Select A Data Queue For WriteOperation dialog. All libraries are listed in the dialog. You can expand each library to viewa list of available data queue (*DTAQ) objects. You can also select a library and create anew data queue in it.

Note: You can dynamically set the reply data queue library and data queue when theadapter is running. See Dynamically Setting the Program Object and Data Queue onpage 61 for details.

Timeout(milliseconds)(optional)

The timeout value in milliseconds for Request-Response Service.

By default, the timeout value is 30000 milliseconds (30 seconds).

Are DataQueues Shared?

Whether data queues specified for a Request-Response Service are shared among multipleservices.

If selected, the adapter will generate a unique 112 character key for the request-responseoperation at runtime.

If not selected, the key for the request-response operation is user specified.

GenerateSource Type

When the message schema is defined for the Request-Response Service, a copy sourcemember containing the message schema is generated in a library on the IBM System imachine. This field specifies the type of generated source member. The generated sourcetype can only be ILE RPG in the current release.


The source file where the message schema will be generated. The format of the source filename is library_name/source_file_name.

You can manually type the library and source file with the formatlibrary_name/source_file_name in this field or click the Browse Resources button next to thisfield to open the Select A Source File dialog. All libraries are listed in the dialog. You canexpand each library to view a list of available file (*FILE) objects.


Name of the source member that will be generated. The source member will contain themessage schema.


Field Description



Options Available for the Program Call Service Type

When the service type is Program Call, you can add the programcallTimeout attribute to the .trafile to set a timeout value expressed in seconds.

Program Object Name of the program object (*PGM object). The format of the program object name islibrary_name/program_name.

You can manually type the program library and program object with the formatlibrary_name/program_name in this field, assign a pre-defined global variable, or click theBrowse Resources button next to this field to open the Select A Program dialog. Alllibraries are listed in the dialog. You can expand each library to view the list of availableprogram (*PGM) objects.

Note: You can dynamically set the program library and program object when the adapteris running. See Dynamically Setting the Program Object and Data Queue on page 61 fordetails.

Source File

(Optional)

Name of the source file that contains the program source member. The format of the sourcefile name is library_name/source_file_name. This field is optional, you can create a schemafor the program object manually.

You can manually type the library and source file with the formatlibrary_name/source_file_name in this field or click the Browse Resources button next to thisfield to open the Select A Source File dialog. All libraries are listed in the dialog. You canexpand each library to view a list of available file (*FILE) objects.

Source Member Name of the program source member.

PCML File Name of the PCML file that contains programs.

Type the name of the PCML file in this field or click the Browse Resources button next tothis field to navigate to the location of the PCML file. You can load parameters from thePCML file to invoke PGM objects.

Note: Ensure that the pcml file extension is in lowercase. To enter program schema usingthe PCML file, use the JT400 jar version 9.1 that supports character datatypes with sizeover 1MB.

PCML ProgramName

Name of a specific program contained in the PCML file.

Note: The program name is case sensitive and must exactly match the name in the PCMLfile.


Field Description



LoadParameters

When this button is clicked, the source for the program is parsed to retrieve programparameters. The retrieved program parameters are populated as a schema in the ProgramSchema tab.

Note: Before loading parameters, make sure the source file has been provided in theSource File field.


Options Available for the Spooled File to PDF Service Type

Paper Size The PDF paper size.

PaperOrientation

The PDF paper orientation.

Unit forMargins

The unit of measure for page margins of the PDF.

Top Margin/Bottom Margin/Left Margin/Right Margin

The page margins of the PDF.

Options Available for the Service Program Call Service Type

ServiceProgramObject

Name of the service program object (*SRVPGM object). The format of the service programobject name is library_name/service_program_name.

You can type the service program library and the service program object with the formatlibrary_name/service_program_name in this field, assign a global variable to this field, or clickthe Browse Resources button next to this field to open the Select a Program dialog. Alllibraries are listed in the dialog. You can expand each library to view a list of serviceprogram (*SRVPGM) objects available in that library.

ProcedureName

Name of the procedure in the service program.

You can type the procedure name in this field or assign a global variable to this field.

Note: If no value is provided in this field, an error occurs when running the adapter.

Return ValueType

The type of value that is returned from a service program call. There are two types:

• numeric — The programs return a 4-byte signed integer.

• void — The program does not return a value. If you select the void type, the value 0will be returned by the adapter.


Field Description



Dynamically Setting the Program Object and Data Queue

The adapter allows you to dynamically set the following items when the adapteris running:

• Program library and program object

• Request or reply data queue library and request or reply data queue

To dynamically set the program library and program object, complete thefollowing steps:

1. Select the Call CUSTMR_UPD activity in the Call Program to UpdateCustomer process, and then click the Input tab to do the configuration.

2. Select the __caretuserClosure_caret_ element in the__caret_request_caret_Customer__Add__Server_caret_CUSTMR__ADDcomplex type.

Source File (Optional) Name of the source file that contains the service program source member. Theformat of the source file name is library_name/source_file_name.

You can type the library and source file with the format library_name/source_file_name inthis field or click the Browse Resources button next to this field to open the Select A SourceFile dialog. All libraries are listed in the dialog. You can expand each library to view a listof available file (*FILE) objects. This field is optional, you can create a schema for theservice program object manually.

Source Member Name of program source member.

LoadParameters

When this button is clicked, the source for the service program is parsed to retrieve serviceprogram parameters. The retrieved service program parameters are populated as a schemain the Program Schema tab.

Note: Before loading parameters, make sure the source file has been provided in theSource File field.



Field Description

The following illustration is based on the Request-Response Service (ProgramCall) example, which is shipped with the installation package. See TIBCOActiveMatrix Adapter for IBM i Examples for details.



3. Click the Edit Statement button in the Toolbar of the Activity Input panel tomodify the Extensible Stylesheet Language Transformation (XSLT) statementfor the element. The Edit Statement dialog is displayed.

See TIBCO ActiveMatrix BusinessWorks Palette Reference for more informationand examples of using XSLT to perform mapping.

4. In the Edit Statement dialog, complete the following steps:

a. Click the Type button

b. Check the Type Substitution check box.

c. Click the Browse Resources button next to the Schema field to select theschema resource. The Select A Resources dialog is displayed.

d. Expand AESchemas > ae > as400 > MetaData folder, and select theDynamicProgramCall schema, and then click the OK button in the SelectA Resources dialog.

e. Click the OK button to save the changes.

5. Expand the __caretuserClosure_caret_ element in the Activity Input area, theProgramLibrary field and the ProgramObject field are displayed.

6. Type values in the ProgramLibrary field and the ProgramObject field toupdate the program library and the program object.

Message Schema TabThis tab is available only for the Data Queue Write service type. Users can definethe message schema for service in this tab.

• The request schema must be defined under the Request schema element ofthe main schema.

• The response schema must be defined under the Response schema element ofthe main schema.

• The key elements for request and response data queues must be definedunder the Key schema element in the main schema.

To dynamically set the data queue library and data queue, you can follow similarinstructions. Replace the DynamicProgramCall schema with theDyamicDataQueueWrite schema, the RequestLibrary, RequestQueue,ReplyLibrary, and ReplyQueue fields are displayed.



Figure 7 Message Schema Tab of Request-Response Service



Program Schema TabThis tab is available for the Program Call and the Service Program Call servicetypes.

In this tab, you can browse or define the schema for program or service programparameters. If the program or service program source has been parsedsuccessfully, the parameters are displayed as a schema under this tab. Otherwise,the program or service program parameters can be defined manually.

You can define program or service program parameter attributes in the programschema by using the Add and Delete buttons.

• To add an attribute, click the Add button.

The Add data attributes dialog is displayed where you can define attributesin the program or service program schema.

• To delete an attribute, select the attribute and press the Delete button.

• To edit definition of an attribute, select that element and click the Edit button.

When the service type is Program Call or Service Program Call, you can selectan item from the Direction field in the Add data attributes dialog to configurewhether to return request parameter data in response messages forRequest-Response Service.



The attributes can be moved up or down by clicking the Move Parameter buttons.

Figure 8 shows the Program Schema tab of Request-Response Service.

Figure 8 Program Schema Tab of Request-Response Service



Message Monitor TabThis tab is available only for the Program Call service type.

If the invocation of program configured in this service is likely to generatemessages (error or otherwise) to a message queue, a Request-Response InvocationService for monitoring messages can be specified in this tab.


Table 19 Message Monitor Tab of Request-Response Service

Field Description

Message MonitorService Name

If a message monitoring Request-Response Invocation Service is selected, the name ofthat service is displayed in this field. This is a display only field.

Browse for MessageMonitor Service

Select a message monitoring Request-Response Invocation Service.

Create MessageMonitor Service

If there is no existing message monitoring Request-Response Invocation Service, clickthis button to create a new one.

Table 20 Transport Tab of Request-Response Service

Field Description

MessageSubject









Quality ofService

Available only for the Rendezvous transport. It can be Certified, Reliable, or DistributedQueue. See Quality of Service on page 39 for details.

Wire Format Services must use the same wire format to exchange data. It can be XML Message (JMSonly) and ActiveEnterprise Message (Rendezvous only). See Wire Format on page 40 fordetails.



Delivery Mode Available only for the JMS transport. It can be Durable or Non-Durable. See DeliveryModes on page 41 for details.

SessionReference


EndpointReference

The location in TIBCO Repository where the endpoint information is stored.


Table 20 Transport Tab of Request-Response Service (Cont’d)

Field Description




Table 21 Schema Tab of Request-Response Service

Field Description



68 | Request-Response Invocation Service Tabs

Request-Response Invocation Service Tabs



• Queue Configuration Tab, page 69





Table 22 Configuration Tab of Request-Response Invocation Service

Field Description







Queue Configuration TabThe Queue Configuration tab contains the following fields, as shown in Table 23.

Table 23 Queue Configuration Tab of Request-Response Invocation Service

Field Description

Service Type Type of the Request-Response Invocation Service.

Monitor Message The service is used as a message monitoring service. If you plan to callan application program which is likely to generate messages which require a reply (erroror otherwise) on a message queue, you can configure a Monitor Message type ofRequest-Response Invocation Service and associate this service with program call service.See Message Monitor Tab on page 53 and Message Monitor Tab on page 65 for reference.

Outbound Message The service is used to process the outbound request-responseoperation initiated by applications running on an IBM System i machine.

Timeout(milliseconds)

The timeout value in milliseconds for Request-Response Invocation Service.

By default, the value for timeout is 30000 milliseconds (30 seconds).

Options Available for the Monitor Message Service Type

Message Queue The name of a message queue (*MSGQ object). The format of the message queue name islibrary_name/message_queue_name.

You can manually type the library and the message queue with the formatlibrary_name/message_queue_name in this field or click the Browse Resources button next tothis field to open the Select A Message Queue dialog. All libraries are listed in the dialog.You can expand each library to view the list of available message queue (*MSGQ) objects.

Options Available for the Outbound Message Service Type

Request DataQueue

Name of the data queue (*DTAQ object) that sends the request message from an applicationrunning on the IBM System i machine. The request data queue must be a keyed data queue.

The format of the data queue name is library_name/data_queue_name. By default, the nameof the request data queue is ADAS400RQS in the work library of the adapter instance. If thespecified data queue does not exist, it is created with an entry length of 10000 charactersand a key length of 112 characters.

You can manually type the library and the data queue with the formatlibrary_name/data_queue_name in this field, assign a pre-defined global variable, or click theBrowse Resources button next to this field to open the Select A Data Queue For OutboundRequest dialog. All libraries are listed in the dialog. You can expand each library to viewthe list of available data queue (*DTAQ) objects. You can also select a library and create anew data queue in it.



Reply DataQueue

Name of the data queue (*DTAQ object) that sends the reply message to an applicationrunning on the IBM System i machine. The reply data queue must be a keyed data queueand be different from the request data queue.

The format of the data queue is library_name/data_queue_name.

By default, the name of the reply data queue is ADAS400RPY in the work library of theadapter instance. If the specified data queue does not exist, it is created with an entrylength of 10000 characters and a key length of 112 characters.

You can manually type the library and the data queue with the formatlibrary_name/data_queue_name in this field, assign a pre-defined global variable, or click theBrowse Resources button next to this field to open the Select A Data Queue For InboundReply dialog. All libraries are listed in the dialog. You can expand each library to view thelist of available data queue (*DTAQ) objects. You can also select a library and create a newdata queue in it.

Are DataQueues Shared?

Whether the data queues specified for the service are shared among multiple services.

If this check box is checked, data queues can be shared with other Publication Service andRequest-Response Invocation Service. The length of the key for data queues must be 112characters. For shared data queues, each message entry in the request data queue mustcontain a routing header. A message must be published to the request data queue usingRPCCLIENT program generated by the adapter at design-time. If a message is publishedto the shared data queue using the RPCCLIENT program, the routing header informationis automatically added to the message.

If this check box is not checked, the data queues cannot be shared with other services. Thelength of the key for data queues can be any key length and the message entry can be inany format. The application program running on the IBM System i machine send messagesto a non-shared data queue through system APIs.

GenerateSource Type

The type of generated source member.

When the message schema is defined for the publisher, a copy source member containingthe message schema is generated in a library on the IBM System i machine. The generatedsource type can only be ILE RPG in the current release of the adapter.


Name of the source file in which a source member for the message schema is generated.The format of the source file name is library_name/source_file_name.

By default, the name of the source file for generating the message schema source on theIBM System i machine is ADAS400SRC in the work library of the adapter instance. If thespecified source file does not exist, it is created with a length of 112 characters.

You can manually type the library and the source file with the formatlibrary_name/source_file_name in this field or click the Browse Resources button next to thisfield to open the Select A Source File dialog. All libraries are listed in the dialog. You canexpand each library to view the list of available file (*FILE) objects. You can also select alibrary and create a new source file in it.

Table 23 Queue Configuration Tab of Request-Response Invocation Service (Cont’d)

Field Description



Message Schema TabThis tab is available only for the Outbound Message service type. Users candefine the message schema for Request-Response Invocation Service in this tab.

• The schema for the message must be defined under the Entry schema elementof the main schema for the service.

• If the data queue specified for the service is a keyed data queue, key elementscan be defined in this tab too. The key elements must be defined under theKey schema element of the main schema.

• The request schema and response schema must be defined separately:

— The request schema must be defined under the Request schema element ofthe main schema for the service.

— The response schema must be defined under the Response schema elementof the main schema for the service.

• The key elements for the request and response data queues must be definedunder the Key schema element of the main schema.

Figure 9 Message Schema Tab of Request-Response Invocation Service


Name of the source member that will be generated.

Table 23 Queue Configuration Tab of Request-Response Invocation Service (Cont’d)

Field Description






Table 24 Transport Tab of Request-Response Invocation Service

Field Description

MessageSubject







Quality ofService

Available only for the Rendezvous transport. It can be Certified or Reliable. See Quality ofService on page 39 for details.

Wire Format Services must use the same wire format to exchange data. It can be XML Message (JMSonly) and ActiveEnterprise Message (Rendezvous only). See Wire Format on page 40 fordetails.



Delivery Mode Available only for the JMS transport. It can be Persistent or Non-Persistent. See DeliveryModes on page 41 for details.




SessionReference


EndpointReference

The location in TIBCO Repository where the endpoint information is stored (default).


Table 24 Transport Tab of Request-Response Invocation Service (Cont’d)

Field Description

Table 25 Schema Tab of Request-Response Invocation Service

Field Description



74 | Adapter Service Options Supplement

Adapter Service Options Supplement

This section consists of some common operations.

Defining Message SchemaYou can define the message schema structure in the Message Schema tab.

Adding Data Attributes

To add a data attribute, complete the following steps:

1. Click the Add button.

2. Enter the definition in the Add data attributes dialog.

3. Click the Add button, and then click the Finish button.

Figure 10 Add Data Attributes

If you want to define child attributes, note the following rules:

• Child attributes are defined by selecting the parent attribute before clickingthe Add button.

• The data type of the parent attribute must be set to Data Structure.

You can also import data definitions from a file object, a source file, or a XMLschema by clicking the Import button.


75 | Adapter Service Options Supplement

Figure 11 Import Data Definition

Deleting Data Attributes

To delete a data attribute, select the attribute and click the Delete button.

Editing Data Attributes

To edit the definition of a data attribute, complete the following steps:

1. Select the attribute and click the Edit button.

2. Modify the definition in the Add data attributes dialog.

3. Click the Update button, and then click the Finish button.

Figure 12 Edit Data Attributes

The data attributes can be moved up or down by clicking the Move Parameterbuttons.


76 |

Chapter 5 Deploying the Adapter with TIBCOAdministrator

This chapter provides an overview about deploying, starting, stopping, andmonitoring adapter services using the TIBCO Administrator web interface. Seethe TIBCO Administrator documentation set for details.

Topics

• Creating an EAR File in TIBCO Designer, page 77

• Deploying the Project, page 78

• Starting or Stopping the Adapter, page 80

• Monitoring the Adapter, page 81

• Adapter Properties File, page 82


77 | Creating an EAR File in TIBCO Designer

Creating an EAR File in TIBCO Designer

The EAR file contains information about the adapter services that you want todeploy. This can be one or more adapter services, one or more TIBCOBusinessWorks process engines, or both.

To create an EAR in TIBCO Designer, complete the following steps:

1. Configure the adapter services.

2. In the Project panel, select the project.

3. Drag the Enterprise Archive icon from the Palettes panel to the Design panel.

4. In the Project panel, select the Enterprise Archive you have just created.

If there are any configured adapter services in your project, an AdapterArchive resource becomes available in the Palettes panel.

5. Drag the Adapter Archive icon from the Palettes panel to the Editor View.

6. In the Configuration tab, click the Browse Resources button to select theadapter instance in the Adapter field. Click the Apply button.

7. In the Project panel, select the Enterprise Archive, and then click the BuildArchive button in the Configuration tab to create the archive file.

See Also

See TIBCO Designer User’s Guide for more information about this procedure. Theguide is available from the TIBCO Designer Help menu.

Building an archive creates the EAR file, which you can then deploy from TIBCOAdministrator. If you change the business processes or adapter services includedin the archive, you have to rebuild the archive. Saving the project does not affectthe archive.


78 | Deploying the Project

Deploying the Project

Before deploying a project, the machine on which the adapter is installed must bepart of a TIBCO administration domain. After you have installed the TIBCOAdministration Server, any machine on which you install TIBCO Runtime Agentcan be added to the administration domain. The TIBCO software installed on themachine is then visible and accessible via the TIBCO Administrator GUI.

When you deploy a project, startup scripts and other information about thedifferent components are sent to the machines to which the components wereassigned. The project data store and TIBCO Administration Server are updatedwith the deployed components.

To deploy a project, complete the following steps:

1. Import the EAR file into TIBCO Administrator.

a. Start TIBCO Administrator. Log into the domain.

b. In the left panel, select Application Management.

c. Click New Application.

d. In the Upload EAR File dialog, browse to select the EAR file. Click OK.

2. Assign adapter archives in the EAR file to adapters installed in theadministration domain and likewise assign process archives to processengines.

3. In the New Application Configuration dialog, uncheck the Quick Configurecheck box, and then click the Save button.

4. Specify startup options for each adapter service.

If required, set up your deployment for fault tolerance by specifying morethan one adapter service to run on different machines. The secondary serviceswill run in standby mode until they are needed.

5. In the Configuration Builder, click the top level application name, and thenperform following tasks:

a. Change the values in the Advanced tab if necessary.

b. Click the Save button.

c. In the Configuration Builder, select the adapter archive, and then clickAdd to Additional Machines.

d. Select the machine and click the OK button. Click the Save button.

6. In the Configuration tab, click the Deploy button. Click the OK button.


79 | Deploying the Project

7. Once the deployment is complete, click Application Processes under theapplication. Select the adapter and the TIBCO ActiveMatrix BusinessWorksengine and click Start Selected.

See Also

See the TIBCO Administrator User’s Guide for an introduction to the TIBCOadministration domain and detailed information about the above steps.

See the TIBCO Administrator Server Configuration Guide for fault toleranceinformation.


80 | Starting or Stopping the Adapter

Starting or Stopping the Adapter

The TIBCO Administrator Application Management module allows you to startor stop deployed applications.

Starting the Adapter

To start an adapter service from the module, complete the following steps:

1. In the Administrator GUI left-hand pane, expand Application Management >ApplicationName > Service Instances.

2. In the Service Instance panel, check the check box next to the adapter service.

3. Click the Start Selected button.

The status changes from Stopped to Starting up to Started.

Stopping the Adapter

To stop the adapter service, click the Stop Selected button.

See Also

See the TIBCO Administrator User’s Guide for more information.


81 | Monitoring the Adapter

Monitoring the Adapter

TIBCO Administrator offers a number of monitoring options:

• Specify alerts and TIBCO Hawk rulebases for each machine in the domain.

• Specify alerts and Hawk rulebases for each adapter service.

• View the log for each adapter service.

See Also

See TIBCO Administrator User’s Guide for information about configuring the abovemonitoring options.


82 | Adapter Properties File

Adapter Properties File

The runtime adapter parses a properties file at startup. The default runtimeadapter properties file is named adas400.tra, which is located in the binsubdirectory of the adapter installation directory:ADAS400_HOME/bin

Each line in a properties file is a single property. Each property consists of a keyand a value. The key starts with the first non-whitespace character and ends at thefirst "=", ":", or whitespace character. The value starts at the first character afterthe equal sign (=) and cannot have trailing whitespace. For example:

tibco.configurl AS400AdapterConfigurationtibco.repourl C:/tibco/adapter/adas400/6.2/examples/Samples.dattibco.username=admintibco.password=samplePassword

Properties defined in the properties file override the same properties defined inthe project.

Properties File FormatThe following restrictions apply to properties:

• The "!" character may not be used as a comment line indicator. Only the "#"character is recognized.

• The line continuation character is ignored (a value must fit in a line).

• The key may not contain any of the termination characters. Java allowstermination characters by escaping the value with a preceding "\" character.The adapter does not support this syntax.

Tagging Values for Obfuscation

The presence of a "#" character as the first character in a value (not the key)indicates that the value has been obfuscated or is to be obfuscated. Theobfuscation command-line tool prompts for values to be obfuscated when itencounters a value with "#" as the first character in the properties file.

When the obfuscate tool is run, it rewrites the properties file with the obfuscatedvalue in place. See Obfuscating or Encrypting a Password in the Properties File onpage 85 for more information.



Predefined PropertiesTable 26 lists the predefined properties. Properties that start with ntservice areavailable only on Microsoft Windows platforms.

All paths inside a properties file, including Windows directory names, must useforward slashes.

Table 26 Predefined Properties

Property Description

tibco.repour The absolute path name to the Designer project where the adapterconfiguration is defined.

tibco.configurl The location of the adapter configuration inside the project file.

If a relative path is specified, the adapter service is assumed to be under thedefault area in the project: /tibco/private/adapter/

If an absolute path is specified, the adapter configuration is looked up in theproject as defined by the argument.

tibco.username The user name and password used by the repository server to access theproject.

tibco.password

tibco.clientVar.varname Runtime values to substitute for global variables defined in the project. Thisvalue takes precedence over the named global value set in the project.Substitution takes place only at start up.

Append the global variable to tibco.clientVar, then give its value. Forexample:tibco.clientVar.DirLedger=C:/tibco/adapter/adas400/6.2/ledger/myledger

adas400.perfMon<on/off>

Turns the performance statistics micro agent on or off.

adas400.addCustomHawkMethodstoClassMAgent<on/off>

If set to on, custom methods are added to the class micro agent. If set to off,custom methods are not available from the standard micro agent. Default ison.

adas400.PollingInterval <Integer>

The interval (in milliseconds) at which the adapter poll the data queue.Default value is 250(milliseconds).



ntservice.name Name for this Windows Service.

This property is useful if you want to have multiple Windows Services forthe same executable. That is, you may want to have two adapters running onthe same machine. By specifying different service names and display namesfor the adapters, you can accomplish this.

ntservice.displayname Name to display in the Services control for this Windows Service.

This property is useful if you want to have multiple Windows Services forthe same executable. That is, you may want to have two adapters running onthe same machine. By specifying different service names and display namesfor the adapters, you can accomplish this.

ntservice.starttype Start type for this Windows Service. Either manual or automatic. Forexample:

ntservice.starttype automatic

You can use this property to initially set the start type for the service, butonce the service is installed, use the Windows Services control to change thestart type of services.

ntservice.binary.path.absolute

Absolute path to the executable that is run when the service is started. Forexample:ntservice.binary.path.absoluteC:/tibco/adapter/adas400/6.2/Fbin/adas400

ntservice.interactive Whether the Windows Service is interactive. Either true or false.

ntservice.interactive=true

ntservice.dependencies Dependencies of this Windows Service.

ntservice.account User name under which to run the Windows Service.

You can use this property to initially set the account for the service, but oncethe service is installed, use the Services control to change the user accountof services.

ntservice.password Password for the user name in the ntservice.account property.

You can use this property to initially set the password for the user account,but once the service is installed, use the Services control to change thepassword.

Table 26 Predefined Properties (Cont’d)

Property Description



Obfuscating or Encrypting a Password in the Properties File

Password Handling

At design-time, the adapter uses a password to connect to the back endapplication and fetch metadata. At runtime, the adapter uses a password toconnect to the back-end application and inter-operate with it.

When deploying the adapter, check the Service property of the global variable inthe global variables section then go to the Advanced tab of the adapter archiveand set the password value under the Run-Time Variables section.

If you want to run the adapter locally, define the runtime password value to be aglobal variable. Before starting the adapter, include the runtime password asclient variable in the adapter's .tra file and obfuscate it using obfuscate tool. Forexample, if the password value is defined as %%myPassword%%, create a globalvariable named myPassword in the global variables section with no value andinclude the following entry in the .tra file:

tibco.clientVar.myPassword

Obfuscating a Password

If the runtime adapter uses a password to access the vendor application, thepassword is stored in readable form as a value to thetibco.clientVar.adas400.connection.password=# <password> property in the runtimeadapter properties file. You can use the obfuscate tool to hide the password in theproperties file so the password cannot be viewed by unauthorized users.

To obfuscate the password, complete the following steps:

1. In TIBCO Designer, open the adapter instance and navigate to the panelwhere the password used by the runtime adapter to connect to the LotusNotes is defined. In the password field, provide a user defined global variable,such as %%MyPassword%%. The global variable must also be added to the globalvariable list. See Global Variables on page 92 for information about creatingglobal variables.

2. In the runtime adapter properties file, verify that thetibco.clientVar.<variable>=#! <password> property is defined in the file.

3. Run the obfuscation tool supplied with adapter software against theproperties file. This tool is named obfuscate.exe and resides in theTIBCO_HOME\tra\5.10\bin directory.

Do not set the password to type Password in the global variables section foradapter configurations that are set to AE Version 4.0 or AE Version 5.0 (in theConfiguration tab Version field) or any intermediate version.



The command syntax on Microsoft Windows for a default installation is:

C:\tibco\tra\5.10\bin\obfuscate tra-file-path-name

where tra-file-path-name is the absolute path name of the adapter properties filethat contains the tibco.clientVar.<variable>=#! <password> property.

For example, on Windows:

TIBCO_HOME\tra\5.10\bin\obfuscateADAS400_HOME\bin\adas400.tra

The password is now obfuscated and you can start the adapter with thechanged properties file.

Encrypting a Password

Encryption is only supported for version 5 adapters and later. To encrypt aproperty in a properties file, complete the following steps:

1. In the property file, add the #! characters in front of the value you want toencrypt. For example:

Repo.serverPassword = #!mysecret

2. Invoke the obfuscate utility from the command line:

TIBCO_HOME/tra/5.10/bin/obfuscate.exe--propertyfile=property-file-name

The next time you open the property file, mysecret will have been replaced witha random sequence of characters.

If you do not want to obfuscate a password, remove the # at the beginning of theobfuscated password and replace it with the password in plain text.


87 |

Chapter 6 Advanced Topics

This chapter describes advanced features such as using global variables,configuring a remote adapter and language support.

Topics

• Using the Adapter with a Revision Control System, page 88

• Defining a TIBCO Hawk Session, page 90

• Global Variables, page 92

• Setting Encoding Options, page 97

• Connection Settings, page 98


88 | Using the Adapter with a Revision Control System

Using the Adapter with a Revision Control System

TIBCO Designer supports revision control systems such as Microsoft VisualSourceSafe and Perforce. If you are using a revision control system, you mustmanually add some configured resources to the revision control system and checkin the resources when completing the instance configuration.

As part of service configuration, the adapter creates schema files inroot/AESchemas/ae/as400. For example, if you configure a service in an adapterconfiguration Instance1, the following file is created:

Project_root/AESchemas/ae/as400/Instance1.adas400

When the project is saved and a revision control system has been specified, theadapter displays a warning that additional files were created and must be addedto the revision control system. This warning is displayed only when the files arecreated for the first time.

The warning displays a Go To Resource button that helps in navigating to theresource. To add these files to the revision control system, select Add Resource toRCS from the Multi-User menu.

For instructions on how to use the Multi-User feature in TIBCO Designer, see theTIBCO Designer User’s Guide.

Copy, Cut, Paste, and Move Operations

• To copy and paste a service from adapter Instance1 to Instance2, the adapterconfiguration and schema files for the Instance2 must be checked out.

• To cut and paste a service from adapter Instance1 to Instance2, the adapterconfiguration and schema files for both Instance1 and Instance2 must bechecked out.

• To move a service from adapter Instance1 to Instance2 along with theassociated schemas, select Extended Copy and Paste from the Edit menu inTIBCO Designer and then delete the resource.

Regeneration When Moving, Copying, and Pasting

• Default subjects are not regenerated to reflect the new instance name when aservice is moved.

• Manually changed certified messaging and certified messaging queue ledgerfile names are regenerated to defaults when a service is moved, or copied andpasted to a new instance.


89 | Using the Adapter with a Revision Control System

• If a service associated with a custom session is moved, or copied and pasted,the custom session is not moved, or copied and pasted. The session isregenerated as a default session.


90 | Defining a TIBCO Hawk Session

Defining a TIBCO Hawk Session

To use TIBCO Hawk to monitor the adapter, you must first define a TIBCORendezvous session:


2. In the Project panel, select your adapter instance configuration.

3. Check the Show All Tabs check box, then click the Monitoring tab. TheDefault MicroAgent Session field contains the name of the Hawk session:HawkSession. Use default setting for the other fields.

Figure 13 Monitoring Tab

4. In the Project panel, expand Advanced > Sessions, and then select theHawkSession to configure it.


91 | Defining a TIBCO Hawk Session

Figure 14 HawkSession Configuration

5. After changing the defaults, click the Apply button and save the project.


92 | Global Variables

Global Variables

The variable substitution mechanism can override global variables predefined inthe project in a restricted manner. Predefined variables can be viewed and set inTIBCO Designer. Variables are specified as %%VARNAME%% and cannot contain anywhite space.

Variable substitution allows you to accomplish the following:

• Substitute string variables specified in the project at startup time.

• Locally define the value for a variable for a specific project. The local valuetakes precedence over the global value.

• Specify the value for a variable in a properties file. This overrides the projectrepository and values set in code, but not variables set on the command line.

• Enforce the pre-defined variables listed in Predefined Global Variables onpage 94.

Variables can be used anywhere in the configuration and will be replaced bythe locally defined adapter instance.

Variable SpecificationVariables can be specified in the following ways:

• In the project during configuration using TIBCO Designer.

• In a properties file.

• In TIBCO Administrator Enterprise Edition when deploying the project.

The values in the properties file or Enterprise Edition take precedence over thevalues set in the project through TIBCO Designer.

Specifying Variables Using TIBCO Designer

Global variables provide an easy way to set defaults for use throughout yourproject. There are several ways in which they can be used:

• Define a variable using TIBCO Designer, then override the value forindividual applications at deployment time using TIBCO Administrator. Youcan also override values for predefined variables, unless the GUI does notallow you to change them later.

• Predefine a variable using TIBCO Designer, then override the value forindividual services (for example, Publication Service or TIBCO ActiveMatrixBusinessWorks process) at deployment time using TIBCO Administrator. The



values you specify are then used at runtime. You can also override values forpredefined variables, unless the GUI does not allow you to make themsettable later.

For example, you can assign the value 7474 to the predefined global variableRvDaemon. And then use the variable in different sessions in the adapter. Tochange the TIBCO Rendezvous daemon for the adapter, globally set it to adifferent value or override it from the command line.

To specify global variables in TIBCO Designer, complete the following steps:

1. In the Project panel, click the Global Variables tab. All currently definedglobal variables are displayed.

Figure 15 Global Variables Tab

2. To edit the global variables, click the Open Advanced Editor button .

In the Global Variables dialog, you can do the following:

— To assign or change a variable value, click the field in the Value column andthen enter the new value. Press Enter when done.

— To add a global variable group, click the Add A Variable Group button .Specify the name of the group, then press Enter.

— To add a global variable, click the Add A Variable button . A newglobal variable item is added to the bottom of the list. With a variable group



selected, you can click this button to add variables to the group. Enter thevariable name and, optionally, the value. Press Enter when done.

— To add a global variable to a group, select the desired group icon and clickthe Add A Variable button.

3. To use the global variable in the fields of a resource, enter the variable nameenclosed with %% on both sides. For example, %%DirTrace%%.

When the project is deployed and the configured components are run, alloccurrences of the global variable name are replaced with the global variablevalue (unless it was overridden in a way that had higher precedence).

A number of global variables are predefined. See Predefined Global Variables onpage 94 for details. You can add definitions of any variables you have to thepredefined variables.

Changing Global Variable Values at RuntimeYou can change the value of a global variable when you deploy your project inTIBCO Administrator. See the section on modifying runtime variables in theTIBCO Administrator User’s Guide for more information.

You can also specify values for global variables when starting a process engine onthe command line. To do this, specify the following as a command line argumentwhen starting the process engine:

-tibco.clientVar.variablePathAndName value

where variablePathAndName is the name of the variable you want to set, includingthe path to the variable if it is contained in a folder. value is the value you want toset the variable to. For example, if you have a global variable named item1

contained in a folder named myGroup and you want to set its value to 500, add thefollowing argument to the command line when starting the process engine:

-tibco.clientVar.myGroup/item1 500

Predefined Global VariablesTable 27 lists and explains the predefined global variables.

Some global variables are automatically used within the system when an adapterinstance is configured.



Table 27 Predefined Global Variables

Variable Description

Deployment Defaults to the TIBCO Designer project name. This global variable is used by the systemto partially define the subject name defined for a service.

DirLedger The path name of the TIBCO Rendezvous certified messaging ledger file. The default isthe root installation directory.

DirTrace The path name for the log file used by the adapter. The default is the root installationdirectory.

Domain The default value for file-based local projects is MyDomain. The value for server-basedprojects is the domain to which the project is saved.

HawkEnabled Indicates whether TIBCO Hawk is used to monitor the adapter. True indicates that aHawk micro agent is defined for the adapter. False indicates the micro agent is not to beused.

JmsProviderUrl The location of the JMS server. Setting this value mostly makes sense in early stages of aproject, when only one JMS server is used.

JmsSslProviderUrl The location of the JMS SSL daemon.

RemoteRvDaemon TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO Administrator ServerConfiguration Guide for details about setting up a domain using rvrd.

RvDaemon TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. Thedefault value is 7500.

RvNetwork TIBCO Rendezvous network. This variable needs only be set on computers with morethan one network interface. If specified, the TIBCO Rendezvous daemon uses thatnetwork for all outbound messages.

In most cases, you can leave the default.

RvService TIBCO Rendezvous service. The Rendezvous daemon divides the network into logicalpartitions. Each transport communicates on a single service. A transport cancommunicate only on the same service with other transports.

Unless you are using a non-default TIBCO Rendezvous configuration, you must leavethe default (7500).

RvaHost Computer on which the TIBCO Rendezvous agent runs. This variable is only relevant ifyou are using the TIBCO Rendezvous Agent (rva) instead of the TIBCO Rendezvousdaemon, and if you have configured a non-default setup. See TIBCO RendezvousAdministration for details about specifying the rva parameters.



RvaPort TCP port where the TIBCO Rendezvous agent (rva) listens for client connectionrequests. See TIBCO Rendezvous Administration for details about specifying the rvaparameters.

TIBHawkDaemon TIBCO Rendezvous daemon used in the TIBCO Hawk session. See the TIBCO HawkInstallation and Configuration manual for details about this parameter.

TIBHawkNetwork TIBCO Rendezvous network used by the TIBCO Hawk session. See the TIBCO HawkInstallation and Configuration manual for details about this parameter.

TIBHawkService TIBCO Rendezvous service used by the TIBCO Hawk session. See the TIBCO HawkInstallation and Configuration manual for details about this parameter.

adas400.connection.environment

Identifies the connection options to the IBM System i machine. See Design-timeConnection Tab on page 27 for more information.

adas400.connection.password

adas400.connection.securityLib

adas400.connection.server

adas400.connection.userName

adas400.connection.worklib

adas400.publisher.polling.interval

The time interval in milliseconds that takes the adapter to retrieve messages from thedata queue for publishing.

Table 27 Predefined Global Variables (Cont’d)

Variable Description


97 | Setting Encoding Options

Setting Encoding Options

See TIBCO ActiveMatrix Adapter for IBM i Concepts for an introduction toInternationalization topics such as Unicode and how adapters handle it.

To set encoding options, in TIBCO Designer, select the root project and click theProject Settings tab. Click the menu next to the TIBCO Message Encoding field toview encoding choices.


98 | Connection Settings

Connection Settings

You can save the connection settings to the IBM System i machine, then reusethem when creating another adapter configuration. The connection settings aresaved through the IBM i menu.

Table 28 lists the available commands in the IBM i menu.

The IBM i menu is available only at the adapter instance level.

Table 28 Commands on IBM i Menu

Command Description

SaveConnectionSettings

After applying the information in the Connection tab, use this command to save theinformation in a file.

DeleteConnectionSetting

Delete a specified connection setting file.

UserConnections

Choose a stored setting to fill in the fields in the Design-time Connection tab orRun-time Connection tab.


99 |

Chapter 7 Monitoring the Adapter Using TIBCO Hawk

Read this chapter if you have installed TIBCO Hawk and want to use TIBCOHawk micro agents through the Monitoring tab of an adapter instance. TIBCOHawk can be used in addition to the standard trace message logging methodsdescribed in Logging Tab on page 33.

Topics

• Overview, page 100

• Starting TIBCO Hawk Software, page 101

• The Auto-Discovery Process, page 102

• Invoking MicroAgent Methods, page 103

• Available Micro agents, page 106

In the TIBCO ActiveMatrix BusinessWorks environment, the adapter is monitoredusing TIBCO Administrator. See TIBCO ActiveMatrix BusinessWorksdocumentation for more information.


100 | Overview

Overview

TIBCO Hawk is a tool for enterprise-wide monitoring and managing of alldistributed applications and systems. System administrators can use it to monitoradapters in a wide area network of any size.

TIBCO Hawk can be configured to monitor system and adapter parameters andto take actions when predefined conditions occur. These actions include:

• Sending alarms that are graphically displayed in the TIBCO Hawk display

• Sending e-mail

• Paging

• Running executable

• Modifying the behavior of a managed adapter

Unlike other monitoring applications, TIBCO Hawk relies on a purely distributedintelligent agent architecture using publish or subscribe to distribute alerts.

TIBCO Hawk uses TIBCO Rendezvous for all messaging and thus gains thebenefits and scalability from the TIBCO Rendezvous features of publish orsubscribe, subject name addressing, interest-based routing, and reliable multicast.

TIBCO Hawk is a purely event-based system that uses alerts. The agents areconfigured with rules that instruct them on everything from what and how tomonitor to what actions to take when problems are discovered. Thus, theworkload is fully distributed throughout the enterprise. Every agent isautonomous in that it does not depend on other components to perform itsfunctions.

The TIBCO Hawk Enterprise Monitor consists of the following components:

Display GUI front end that displays alarms and provides editors to create rulebases, create tests, view messages, and invoke micro agents to requestinformation or initiate an action.

Agents Intelligent processes that perform monitoring and take actions as definedin rules.

Rulebases Rules that are loaded by agents to determine agent behavior.

Application Management Interface (AMI) Manages network applications via TIBCORendezvous and supports communication between a network application andmonitoring TIBCO Hawk agents, including the ability to examine applicationvariables, invoke methods, and monitor system performance.

Micro agents Feed information back to TIBCO Hawk and expose action methodsto rulebases.


101 | Starting TIBCO Hawk Software

Starting TIBCO Hawk Software

The TIBCO Hawk agent can be configured to start automatically during thesystem boot cycle. See the TIBCO Hawk Installation and Configuration forinstructions on how to start TIBCO Hawk.

TIBCO Hawk Administrator’s Guide explains how to start the TIBCO HawkDisplay.

The guides are included in the TIBCO Hawk software installation area.


102 | The Auto-Discovery Process

The Auto-Discovery Process

Start an instance of TIBCO Hawk Display, which continually discovers machinesrunning TIBCO Hawk Agents on your network. Container icons are created foreach agent, and arranged hierarchically in clusters. By default, agent icons areclustered according to subnets.

At first, the Agents container is empty. Its counter displays a value of zero and theDiscovered counter is also at zero. Both icons are initially green to show that noalerts or warning messages are in effect. As agents are discovered, the countersincrease to reflect the current number.

Figure 16 TIBCO Hawk Enterprise Monitor

Monitored network nodes are arranged in a hierarchical tree of containers.Clicking a container in the left-hand panel displays nested items on theright-hand panel.

Icon colors change to reflect the highest level of alert found on discovered agents.See TIBCO Hawk Administrator’s Guide for more information about icon elementsand characteristics.


103 | Invoking MicroAgent Methods

Invoking MicroAgent Methods

A set of default micro agents is loaded when a TIBCO Hawk Agent is started.When you install and start the adapter, its micro agents are dynamically added tothe local agent. To invoke a micro agent method on a TIBCO Hawk Agent:

1. In TIBCO Hawk Display, right-click the Agent icon and select GetMicroagents.

If TIBCO Hawk security is implemented on your system and you do not haveaccess to micro agents on this agent, an error dialog is displayed. Selectanother agent, or contact your system administrator to obtain access.

The Micro agents, Methods and Arguments dialog is displayed. The panel onthe upper left lists micro agents you can access on the current agent.

Figure 17 Micro agents, Methods and Arguments Dialog

This dialog has two modes that are controlled by the radio buttons at thebottom:

— Invoke: Invoking a method immediately returns a single set of currentresults.

— Subscribe: Subscribing provides updates of current results at regularintervals.



2. Click a micro agent name, such as Self, to display a list of associated methodsand text descriptions in the panels below.

3. Click the name of the method to invoke, such as getMicroAgentInfo.

Figure 18 Select Micro agent and Method

If the method accepts arguments, fields for each argument are displayed in theupper right panel. Detailed help text is displayed in the lower panel.

4. Specify any arguments for the method invocation.

5. Ensure that the Invoke option button is selected.

6. Click the Invoke button to invoke the selected method.

The Invocation Results dialog displays the results returned by the method.



Figure 19 Invocation Result Dialog

7. Click the Done button to close the dialog.

These steps describe how to interactively invoke a micro agent method andreceive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automaticallyreceive method results, apply tests to evaluate them, then take action if necessary.For more information on building TIBCO Hawk rules and rule bases, see TIBCOHawk Administrator’s Guide.


106 | Available Micro agents

Available Micro agents

Each adapter has three micro agents, a standard TIBCO Hawk micro agent namedCOM.TIBCO.ADAPTER.xyz where xyz is the adapter configuration name, a custommicro agent, and a class micro agent (for PAM compliance).

The micro agents provide:

• Business level statistics that report the progress of the adapter as it interactswith the vendor application.

For example, in a database adapter such statistics might indicate whetherobjects were successfully or unsuccessfully inserted, updated, or deleted inthe database.

• Queries that return information about the state of the adapter.

This can be an important tool for seeing the internal of an adapter anddebugging it if something is displayed wrong. For example, methods canreturn information about threads, internal queues, or connections to the targetsystem. Using these methods, one might be able to identify certain bottlenecksor gauge how successfully an adapter is scaling with respect to the currentenvironment.

• Updates of the adapter runtime parameters.

This includes retrieving the current runtime parameters and setting newruntime parameters without restarting the adapter. An example of this isgetting and setting the polling interval. Updating a runtime parameterthrough the Hawk micro agent only affects the setting of the instance that isrunning. It does not make a permanent change of the setting in either therepository or the .tra file.

By default, only standard and class micro agents are available at runtime. You candisallow adding custom methods to the class micro agent when deploying theadapter by changing the addCustomHawkMethodsToClassMAgent property valuein the adapter’s property file.

Table 29 lists all the standard methods available for the adapter.

Table 29 Micro agent Methods

Method Description

activateTraceRole() Activates a mapping of a role to a sink at runtime.

deactivateTraceRole() Deactivates a mapping of a roles to sinks at runtime.



getActivityStatistics() Returns the total number of objects processed for all theschemas.

getActivityStatisticsByOperation() Returns the total number of objects processed for all theschemas by each service that is associated with a specifiedoperation.

getActivityStatisticsByService() Returns information about the services implemented by thisadapter.

getAdapterServiceInformation() Returns information about the services implemented by thisadapter.

getComponents() Returns information about the publisher, subscriber andIODescriptor.

getConfig() Returns basic configuration information. More specificinformation is accessed by the more specific methods.

getConfigProperties() Returns all attributes and elements for the given repositoryobject.

getConnectionStatistics() Returns the state and statistics for all the current connectionsused by the adapter.

getHostInformation() Returns standard and extended application information.

getQueueStatistics() Returns the current count of elements in any internal queueused by the adapter.

getRvConfig() Returns information about all TIBCO Rendezvous sessionsdefined.

getStatus() Returns general status information, such as the number ofTIBCO Rendezvous messages received and published, thenumber of errors since the last call, the PID of theapplication, and more.

getThreadStatistics() Returns the operation counts of the current threads.

getTraceSinks() Returns information about sinks to which traces currentlygo.

getVersion() Returns the configuration ID, application name, version, anddate for this adapter instance.

Table 29 Micro agent Methods (Cont’d)

Method Description



_onUnsolictedMsg() Displays alert messages sent to the current adapter.

preRegisterListener() Preregisters an anticipated listener.

resetActivityStatistics() Resets all the counts for the activity statistics.

resetConnectionStatistics() Resets all the counts for the connection statistics.

resetThreadStatistics() Resets all the counts for the thread statistics.

reviewLedger() Returns information retrieved from the ledger file of acertified messaging session for a publisher adapter.

setTraceSinks() Adds a role or changes the file limit of a previously specifiedsink.

stopApplicationInstance() Stops the running adapter instance.

unRegisterListener() Unregisters a currently preregistered listener.

Table 29 Micro agent Methods (Cont’d)

Method Description


109 | activateTraceRole()

activateTraceRole()

Purpose Activates a mapping of a role to a sink at runtime. This replaces thenow-deprecated setTraceSink() TIBCO Hawk method.

Parameters

Table 30 Input parameters of activateTraceRole()

Input Parameters Type Description

roleName String Name of the role to activate.

sinkName String Name of the sink for which to activate the role.


110 | deactivateTraceRole()

deactivateTraceRole()

Purpose Deactivates a mapping of roles to sinks at runtime.

Parameters

Table 31 Input parameters of deactivateTraceRole()


roleName String Name of the role to deactivate.

sinkName String Name of the sink for which to deactivate the role.


111 | getActivityStatistics()

getActivityStatistics()

Purpose Returns the total number of objects processed for all the schemas, based on therequest type. Also, returns the number of success and error objects.

Parameters

Returns

Table 32 Input parameter of getActivityStatistics()

Input Parameter Type Description

GetSubTotalBy String Indicates how to group the subtotals, byService or Operation.

Table 33 Returns of getActivityStatistics()

Returns Type Description

Name String Service name or All Services whichrepresents the final tally of all the services.

Total Integer Total number of objects processed includingboth success and failures.

Success Integer Total number of objects successfullyprocessed.

Failure Integer Total number of objects that caused an errorduring processing.

MeasurementInterval Integer Displays the time (in seconds) since last timethe adapter was reset, or if never reset, sincethe adapter started.


112 | getActivityStatisticsByOperation()

getActivityStatisticsByOperation()

Purpose Returns statistics about one operation.

Parameters

Returns

Table 34 Input parameter of getActivityStatisticsByOperation()


Operation String Name of the operation.

Table 35 Returns of getActivityStatisticsByOperation()


Operation String Name of the operation.

Service Name String Name of the service.

Total Integer Total number of objects processed, bothsuccess and failures.

Success Integer Total number of objects successfullyprocessed.



LineIndex String Concatenated string of Service Name andOperation separated by a comma.


113 | getActivityStatisticsByService()

getActivityStatisticsByService()

Purpose Returns statistics about the data handled by a given adapter service or all adapterservices since the time the adapter was started.

Parameters

Returns

Table 36 Input parameter of getActivityStatisticsByService()

Input parameter Type Description

Service Name String Name of service to get the statistics for. If noservice name is given, performance statistics for allservices is returned.

Table 37 Returns of getActivityStatisticsByService()


Service Name String Service name.

Schema Name String Name of top level schema processed by thisservice.

Operation String Type of operation this service provides.

Total Integer Total number of objects processed, both successand failures.

Success Integer Total number of objects successfully processed.


MeasurementInterval Integer Displays the time (in seconds) since last time theadapter was reset, or if never reset, since theadapter started.

LineIndex String Concatenated string of Service Name andOperation separated by a comma.


114 | getAdapterServiceInformation()

getAdapterServiceInformation()

Purpose Returns information about the services implemented by this adapter. Theinformation is a summary of available adapter services.

Parameters

Returns

Table 38 Input parameter of getAdapterServiceInformation()


ServiceName String Name of the service from which to getinformation. Default is ALL.

Table 39 Returns of getAdapterServiceInformation()


Line Integer Sequential row number.

ServiceName String Name of the service as defined at design-time.

EndpointName String Name of the endpoint used for this service.

Type String Type of the endpoint, for example, publisher orsubscriber.

Quality of Service String Quality of service for the endpoint. Forexample, RVCM or JMS Persistent.

Subject String Subject defined for this endpoint.

Class String Class associated with the endpoint.

Number of Messages Integer Number of messages processed for thisendpoint.


115 | getComponents()

getComponents()

Purpose Returns information about the currently active TIBCO Hawk components such aspublishers, subscribers, or timers.

Parameters

Returns

Table 40 Input parameters of getComponents()


Component Name String Name of the component. If no value is provided,all components are displayed.

Component Type String Any of Publisher, Subscriber, Timer, orIODescriptor. The default value is All.

Table 41 Returns of getComponents()


Instance ID String Name of this adapter instance as defined atdesign time.

Adapter Name String Name of the adapter.

Component Name String Name of the component.

Component Type String The name of the TIBCO Adapter SDK class forthis component, such as MPublisher,MSubscriber, or MIODescriptorSource. Formore information about the class, see your TIBCOAdapter SDK documentation.

Session Name String Name of the session.

Description String Information about this component, for example,time interval, signal type, validating thepublisher or subscriber.


116 | getConfig()

getConfig()

Purpose Retrieves generic configuration information. More specific configurationinformation is accessed through separate methods.

Returns

Table 42 Returns of getConfig()


Instance ID String Configuration ID of this adapter.


RepositoryConnection

String URL of the repository used for adapter instance.

Configuration URL String Location of the adapter project; either a file nameor configuration URL.

Command String Command line arguments used to start theadapter.


117 | getConfigProperties()

getConfigProperties()

Purpose Returns all attributes and elements for the given repository object.

Parameters

Returns

Table 43 Input parameter of getConfigProperties()


Property String Name of the property for which elements (tags)and attributes are desired. For example,agentone/startup.

If no value is given, all properties are returned.

Table 44 Returns of getConfigProperties()


Element Name String Repository directory for the property.

Attribute Name String Name of the repository object attribute.

Attribute Value String Value of the repository object attribute.

Line Integer Line number in which this property is defined inthe project file.


118 | getConnectionStatistics()

getConnectionStatistics()

Purpose Returns the state and statistics for all the current connections used by the adapter.

Returns

Table 45 Returns of getConnectionStatistics()


Connection ID String Unique identification of a particularconnection.

Connection Type String Type or key that will match this connection to athread or queue.

State String Current state: CONNECTED orDISCONNECTED.

NumRetries Integer Total number of times this connection had to bereestablished.

TotalNumOperations Integer Total number of operations processed by thisconnection since the adapter started.

CurrentNumOperations Integer Total number of operations processed by thisconnection since the last reconnection.

NumLostConnections Integer Total amount of time that this connection hasbeen lost.



119 | getHostInformation()

getHostInformation()

Purpose Returns standard and extended application information set.

Returns

Table 46 Returns of getHostInformation()


Name String Name of the property.

Value String Value of the property.


120 | getQueueStatistics()

getQueueStatistics()

Purpose Returns the current count of elements in any internal queue used by the adapter.This includes the TIBCO Rendezvous event queues automatically spawned byRendezvous for each adapter.

Returns

Table 47 Returns of getQueueStatistics()


QueueID String Unique identification of a particular queue.

QueueType String Type or key that will match this queue to athread or connection.

QueueCount Integer Current number of elements in the queue.

MaxQueueSize Integer Maximum number of elements in the queue.



121 | getRvConfig()

getRvConfig()

Purpose Returns information about the TIBCO Rendezvous session defined by thisadapter.

Parameters

Returns

Table 48 Input parameter of getRvConfig()


Session Name String Name of the TIBCO Rendezvous session for whichconfiguration is required. If not given, informationabout all currently defined sessions is returned.The default is all.

Table 49 Returns of getRvConfig()


Instance ID String The configuration ID of this adapter.


Session Name String Name of the session.

Service String Service parameter for this session.

Daemon String Daemon parameter for this session.

Network String Network parameter for this session.

Synchronous Boolean Returns 1 if this is a synchronous session, 0 otherwise.

Session Type String Type of session; one of M_RV, M_RVCM, or M_RVCMQ.

Certified Name String Name of this certified session.

Ledger File String Ledger file for this certified messaging session.Returns the empty string for sessions that are notcertified messaging sessions.

CM Timeout String Timeout for this certified messaging session. Returnsthe empty string for sessions that are not certifiedmessaging sessions.


122 | getStatus()

getStatus()

Purpose Retrieves basic status information about the adapter.

This information is fairly limited. Additional methods are provided in getConfig()on page 116 and getRvConfig() on page 121.

Returns

Table 50 Returns of getStatus()


Instance ID String Configuration ID for this adapter instance.


Uptime Integer Number of seconds since startup.

Messages Received Integer Number of TIBCO Rendezvous messagesreceived.

Messages Sent Integer Number of TIBCO Rendezvous messagespublished.

New Errors Integer Number of errors since the last call to thismethod.

Total Errors Integer Total number of errors since startup.

Process ID Integer Process ID of the application.

Host String Name of host machine on which this adapter isrunning.


123 | getThreadStatistics()

getThreadStatistics()

Purpose Returns the operation counts of the current threads.

Returns

Table 51 Returns of getThreadStatistics()


ThreadID String Unique identification of a particular thread.

ThreadType String Type that tells what part of the adapter thisthread belongs to. Valid types include"Publisher", "Subscriber", "RPC", or"Connection".

TaskType String One-word description of the tasks this threadprocesses.

TaskCount Integer Number of tasks processed by this thread.



124 | getTraceSinks()

getTraceSinks()

Purpose Returns information about sinks to which traces currently go.

Parameters

Returns

Table 52 Input parameters of getTraceSinks()


Sink Name String Name of the sink for which you needinformation. If no name is specified, informationabout all sinks is returned. Default is all.

Role Name String Name of the role for which you need informationfor the specified sink or sinks. Default is all.

Table 53 Returns of getTraceSinks()


Instance ID String Name of this adapter instance as a string.

Adapter Name String Name of the application for this sink.

Sink Name String Name of the sink.

Sink Type String Type of this sink. One of fileSink, rvSink,hawkSink, stderrSink.

Roles String Roles this sink supports, as a string. For example“warning, error, debug”.


125 | getVersion()

getVersion()

Purpose Retrieves version information for the current application. Two lines may bereturned, one for the TIBCO Adapter SDK, one for the adapter.

Returns

Table 54 Returns of getVersion()


Instance ID String The configuration ID as a string, for example,SDK.

Adapter Name String Name of the adapter as a string, for example,agentone.

Version String Version number as a string, for example, 1.1.


126 | _onUnsolictedMsg()

_onUnsolictedMsg()

Purpose Displays all alert messages sent from the adapter or an error if not successful.


127 | preRegisterListener()

preRegisterListener()

Purpose Preregisters an anticipated listener. Some sending applications can anticipaterequests for certified delivery even before the listening applications start running.In such situations, the sender can preregister listeners, so TIBCO Rendezvoussoftware begins storing outbound messages in the sender’s ledger. If the listeningcorrespondent requires old messages, it receives the backlogged messages when itrequests certified delivery.

Parameters

Returns OK if the listener was preregistered successfully, false otherwise.

Table 55 Input parameters of preRegisterListener()


Session Name String Name of the session that anticipates thelistener.

Publisher Name String Name of the component for which thelistener has to be preregistered.

Listener SessionName

String Name of the listener to preregister.


128 | resetActivityStatistics()

resetActivityStatistics()

Purpose Resets all the counts for the activity statistics.


129 | resetConnectionStatistics()

resetConnectionStatistics()

Purpose Resets all the counts for the connection statistics.


130 | resetThreadStatistics()

resetThreadStatistics()

Purpose Resets all the counts for the thread statistics.


131 | reviewLedger()

reviewLedger()

Purpose Returns information retrieved from the ledger file of a TIBCO Rendezvouscertified messaging session.

Before invoking this method, ensure that the certified messaging publisheradapter has established a certified delivery agreement with its subscriber agents.

Parameters

Returns

Table 56 Input parameters of reviewLedger()


Session Name String Name of the TIBCO Rendezvous session forwhich ledger information is desired (default isall).

Subject String Name of the subject for which ledger informationis desired.

Table 57 Returns of reviewLedger()

Return Type Description

Session Name String Name of the TIBCO Rendezvous CM session towhich this information applies.

Subject String Subject name for this session.

Last Sent Message Integer Sequence number of the most recently sentmessage with this subject name.

Total Messages String Total number of pending messages with thissubject name.

Total Size Integer Total storage (in bytes) occupied by all pendingmessages with this subject name.

If the ledger contains ten messages with thissubject name, then this field sums the storagespace over all of them.


String Within each listener submessage, the ListenerSession Name field contains the name of thedelivery-tracking listener session.


132 | reviewLedger()

Last Confirmed String Within each listener submessage, the LastConfirmed field contains the sequence number ofthe last message for which this listener sessionconfirmed delivery.

Line Integer Row number in ledger file.

UnacknowledgedMessages

Integer Number of RVCM messages pending for thislistener. The value is computed by subtractingthe last sent sequence number from the lastacknowledged sequence number.

Table 57 Returns of reviewLedger() (Cont’d)

Return Type Description


133 | setTraceSinks()

setTraceSinks()

Purpose Adds a role or changes the file limit of a previously specified sink.

Parameters

Returns OK if successful or an error if not successful.

Table 58 Input parameters of setTraceSinks()


Sink Name String Name of the sink for which you want to add a roleor change the file limit.

Role Name String Name of the role you want to add to this sink(warning, error, debug, or user defined). Defaultis all.

File Size Integer Maximum file size for this sink.

This parameter is ignored if the sink specified bysinkName is not a file sink.


134 | stopApplicationInstance()

stopApplicationInstance()

Purpose Stops the specified adapter by calling the internal stop() method.

Returns OK if successful or an error if not successful.


135 | unRegisterListener()

unRegisterListener()

Purpose Unregisters a currently preregistered listener.

Parameters

Returns True if the listener was unregistered successfully, false otherwise.

Table 59 Input parameters of unRegisterListener()


Session Name String Name of the session that anticipates the listener.

Publisher Name String Name of the component to which the listener ispreregistered.


String Name of the listener to be unregistered.


136 |

Appendix A Status Messages

This appendix explains the trace messages that are logged to a location specifiedat configuration time.

Topics

• Overview of Trace Messages, page 137

• Trace Message Fields, page 139

• Status Messages, page 141


137 | Overview of Trace Messages

Overview of Trace Messages

Trace messages provide information about adapter activities. The messages arelogged to the console where the runtime adapter is started and to a log file. Tracemessages can also be redirected to the TIBCO Hawk Display application, or sentto other applications using the TIBCO Rendezvous transport.

Each trace message can include the following fields:

<Timestamp> <Adapter Identifier> <Role> <Category> <Status Code><Tracking Identifier>

The above fields are explained in Trace Message Fields on page 139. Figure 20shows an example trace message and calls out the fields.

Figure 20 Trace Message

Example Trace Messages

The following trace messages are written during a session in which thePublication Service monitors an outbound data queue and publishes messagesplaced in the queue.

The first message indicates that ActiveMatrix Adapter for IBM i has started. Thetimestamp indicates when the adapter started, and the role indicates that the tracemessage is informational, which means the activity is normal for the adapter. Thecategory is identified, and the corresponding status code is displayed. The statuscode indicates that the adapter started successfully.

2010 Jan 07 14:06:20:415 GMT +8 IBMiAdapterConfiguration Info[Adapter] TIS-00001 "Adapter AS400Adapter started successfully"

The next set of trace messages indicates that the adapter obtained connectionfrom the pool and read output values successfully. The tracking identifierincluded in the trace message uniquely identifies the message.


138 | Overview of Trace Messages

2010 Jan 07 14:11:54:831 GMT +8 IBMiAdapterConfiguration Info[OutMsg] TAS400-0351 Received message from data queue ADAS400PUB inlibrary ADAS400.

2010 Jan 07 14:11:54:924 GMT +8 IBMiAdapterConfiguration Info[Publish] TAS400-0451 Publisher CustomerMessage_Publisher receivedmessage. tracking=#2Oy/bedI/qYTf-VagIQcc7L-b3o#

2010 Jan 07 14:11:56:895 GMT +8 IBMiAdapterConfiguration Info[Adapter] TIS-30028 "Obtained connection from pool "

2010 Jan 07 14:11:56:926 GMT +8 IBMiAdapterConfiguration Info[Publish] TAS400-0452 Output values read successfully.tracking=#2Oy/bedI/qYTf-VagIQcc7L-b3o#

2010 Jan 07 14:11:56:973 GMT +8 IBMiAdapterConfiguration Info[Publish] TAS400-0453 Publisher CustomerMessage_Publisherpublished message successfully.tracking=#2Oy/bedI/qYTf-VagIQcc7L-b3o#

The final trace message indicates that the Publication Service published themessage successfully.


139 | Trace Message Fields

Trace Message Fields

Table 60 lists the fields in trace messages.

Table 60 Tracing Fields

Field Name Description

Timestamp Timestamp of occurrence. For example, 2003 Feb 22 20:14:51:718 GMT -8.

Adapter Identifier Name of the adapter that wrote the trace message. This is a combination of the adapteracronym and adapter configuration name. For example, the application identifier,ADB.publisher1 identifies a TIBCO Adapter for ActiveDatabase service namedpublisher1.

Role A role can be:

Info Indicates normal adapter operation. No action is necessary. A tracing messagetagged with Info indicates that a significant processing step was reached and has beenlogged for tracking or auditing purposes. Only info messages preceding a trackingidentifier are considered significant steps.

Warn Indicates an abnormal condition. Processing will continue, but special attentionfrom an administrator is recommended.

Error An unrecoverable error occurred. Depending on the error severity, the adaptermay continue with the next operation or stop altogether.

Debug A developer-defined tracing message. In normal operating conditions, debugmessages must not display.

When configuring the adapter you define what roles must or must not be logged. Forexample, you may decide not to log Info roles to improve performance.


140 | Trace Message Fields

Category One of the following:

Adapter The adapter is processing an event.

Application The adapter is interacting with the IBM AS/400.

Configuration The adapter is reading configuration information.

Database The adapter is interacting with a database.

DTA (Design-time adapter) The trace message is from the DTA.

Metadata The adapter is retrieving metadata from the IBM AS/400.

Palette The adapter is interacting with the palette.

Publisher Service Publication Service reports the trace message.

Request-Response Client Service Request-Response Invocation Service reports thetrace message.

Request-Response Server Request-Response Service reports the trace message.

Shutdown The adapter is shutting down.

Startup The adapter is starting.

Subscription Service Subscription Service reports the trace message.

System This category is not linked to a specific event process. The trace message maybe related to a Windows service related messages, memory allocation, file system error,and so on.

TibRvComm The adapter is communicating with TIBCO Rendezvous.

XML The adapter is parsing XML documents.

Status Code Unique code for the message and description. Status codes are identified by a uniquenumber and description. If a trace message includes an error or warn role, the statuscode documentation includes a resolution. See Status Messages on page 141 for details.

Tracking Identifier A unique identifier that is stamped on each message by the originating adapter. Thetracking identifier remains in effect from a message’s beginning to its completion as it isexchanged by TIBCO applications. If the adapter is the termination point of themessage, the tracking identifier is not displayed in the trace message.

You cannot modify the tracking identifier format or configure what information isdisplayed.

Table 60 Tracing Fields (Cont’d)

Field Name Description


141 | Status Messages

Status Messages

In environments where multiple applications are used simultaneously, thepossible status of messages increases as well. This appendix lists the variousmessages in numerical order.

Table 61 Status Messages (Sheet 1 of 9)

Status Code Message Role Category Solution

TAS400-0001 Incorrect value is specified forserver, security library orenvironment parameter.

errorRole Connection Specify correct valuesfor server, security orenvironmentparameter.

TAS400-0002 Error(s) occurred when settinglibrary list for connection.Error(s): error_details

errorRole Connection Check error(s) listed inthe error message andtake appropriate action.

TAS400-0003 An exception occurred whentrying to connect to server:error_details

errorRole Connection Check error(s) listed inthe error message andtake appropriate action.

TAS400-0008 An exception occurred whentrying to run the initialprogram.

errorRole Connection Check the initialprogram.

TAS400-0101 Service service_name programcall for program program_namein library library_name endedin error. Error(s): error_details

errorRole PgmCall Check error(s) listed inthe error message andtake appropriate action.

TAS400-0102 Service service_nameencountered an exceptionwhile dispatching programcall error for programprogram_name in librarylibrary_name. Error:error_details

errorRole PgmCall Check error(s) listed inthe error message andtake appropriate action.

TAS400-0151 Service service_name receivedprogram call request forprogram program_name inlibrary library_name.

infoRole PgmCall Indicates normaladapter operation. Noaction necessary.



TAS400-0152 Input program parametersread successfully in serviceservice_name for programprogram_name in librarylibrary_name.


TAS400-0153 Output program parameterswritten successfully in serviceservice_name for programprogram_name in librarylibrary_name.


TAS400-0154 Service service_namesuccessfully completedprogram call for programprogram_name in librarylibrary_name.


TAS400-0191 Error occurred when callingprogram.

debugRole PgmCall

TAS400-0201 Error occurred when listeningto message queue. Error:error_details.

errorRole MonMsg Check error(s) listed inthe error message andtake appropriate action.

TAS400-0202 Error occurred whendispatching message. Error:error_details.

errorRole MonMsg Check error(s) listed inthe error message andtake appropriate action.

TAS400-0203 Program context for programprogram_name in librarylibrary_name is already in use.Context details:JobName=job_name,JobUser=job_user,JobNumber=job_number

errorRole MonMsg Make sure thatdispatcher formonitoring messagequeue for program callis running in singlethread mode.

TAS400-0204 Monitor message serviceservice_name for programprogram_name in librarylibrary_name not found.

errorRole MonMsg Specify a validrequest-responseinvocation servicename of type 'MonitorMessage' in programcall service.





TAS400-0252 Received message frommessage queuemessage_queue_name in librarylibrary_name. Message details:JobName=job_name,JobUser=job_user,JobNumber=job_number,MsgId=message_id,MsgText=message_text

infoRole MonMsg Indicates normaladapter operation. Noaction necessary.

TAS400-0253 Received monitorablemessage for programprogram_name in librarylibrary_name with noassociated monitor messageservice. Ignoring message.


TAS400-0254 Request-response invocationservice service_name receivedmessage.


TAS400-0255 Request-response invocationservice service_name processedmessage successfully.


TAS400-0291 Error occurred whendispatching message.

debugRole MonMsg

TAS400-0292 Error occurred when listeningto message queue.

debugRole MonMsg

TAS400-0293 The adapter processed numbermessages from data queuedata_queue_name in librarylibrary_name.

debugRole MonMsg





TAS400-0301 Outbound message serviceservice_name for message fromdata queue data_queue_name inlibrary library_name not found.

errorRole OutMsg Outbound messagedispatcher received amessage for which arequest-responseinvocation service doesnot exist in this adapterinstance. Please checkthe IBM AS/400application that sentthis message to recoverfrom this error.

TAS400-0302 Error during OutboundMessage operation.

errorRole OutMsg Check error(s) listed inthe error message andtake appropriate action.

TAS400-0303 Request-response invocationservice service_name receivedmessage of unhandled datatype data_type. Message notprocessed.

errorRole OutMsg The data type specifiedin the error message isnot handled by theadapter. Please changethe data type of thevariable in error andtry request again.

TAS400-0304 Request-response invocationservice service_name did notfind reply data queuedata_queue_name in librarylibrary_name.

errorRole OutMsg Specify a valid dataqueue name as replydata queue inrequest-responseinvocation service.

TAS400-0351 Received message from dataqueue data_queue_name inlibrary library_name. Messagedetails:Version=adapter_version,Service=service_name,JobName=job_name,JobUser=job_user,JobNumber=job_number,Time=time_stamp

infoRole OutMsg Indicates normaladapter operation. Noaction necessary.

TAS400-0352 Request-response invocationservice service_name receivedmessage.






TAS400-0353 Request-response invocationservice service_name processedmessage successfully.


TAS400-0354 Write the message to the dataqueue data_queue_name inlibrary library_name.

infoRole OutMsg

TAS400-0395 The Publication Service hasbeen stopped. Error:error_details.

errorRole OutMsg

TAS400-0396 The data queuedata_queue_name in librarylibrary_name has no message.

debugRole OutMsg

TAS400-0391 Error during request-responseinvocation operation.

debugRole OutMsg

TAS400-0394 The Publication Service startsunsuccessfully.

errorRole Publish

TAS400-0401 Publisher service_namereceived message ofunhandled data typedata_type. Message notprocessed.

errorRole Publish The data type specifiedin the error message isnot handled by theadapter. Please changethe data type of thevariable in error andtry request again.

TAS400-0451 Publisher service_namereceived message.

infoRole Publish Indicates normaladapter operation. Noaction necessary.

TAS400-0452 Output values readsuccessfully.


TAS400-0453 Publisher service_namepublished messagesuccessfully.


TAS400-0491 Error when publishingmessage.

debugRole Publish





TAS400-0901 Could not map AS/400 datatype of 'data_type'.

errorRole Marshall The data type specifiedin the error message isnot handled by theadapter. Please changethe data type of thevariable in error andtry request again.

TAS400-0902 Error occurred when settingsequence value for AS/400parameter parameter_name atindex index_number. Error:error_details

errorRole Marshall Check error(s) listed inthe error message andtake appropriate action.

TAS400-0903 Error occurred when settingdata structure value forAS/400 parameterparameter_name at elementelement_name. Error:error_details


TAS400-0904 Error occurred when settingsequence value from AS/400parameter parameter_name atindex index_number. Error:error_details


TAS400-0905 Error occurred when settingdata structure value fromAS/400 parameterparameter_name at elementelement_name. Error:error_details


TAS400-0907 Variable variable_name was setto default value due to errorerror_details.

infoRole Marshall Indicates normaladapter operation. Noaction necessary.

TAS400-9003 Default library for objectobject_name of type object_typemember member_name notfound! Error: error_details

errorRole MetaData Check that the librariesin library list for theadapter instancecontains the objectmentioned in the errormessage.





TAS400-9051 Error occurred when deletingtemporary list table table_namein library library_name. Error:error_details

infoRole MetaData Indicates normaladapter operation. Noaction necessary.

TAS400-0501 Service service_name of typedata queue write for dataqueue data_queue_name inlibrary library_name ended inerror. Error(s): error_details

errorRole DQWrite Check error(s) listed inthe error message andtake appropriate action.

TAS400-0502 Service service_name did notreceive reply in data queuedata_queue_name in librarylibrary_name within timeoutseconds

errorRole DQWrite Make sure that dataqueue requestprocessing jobs isrunning on IBM Systemi machine.

TAS400-0551 Service service_name receiveddata queue write request fordata queue data_queue_name inlibrary library_name.

infoRole DQWrite

TAS400-0552 Request message writtensuccessfully in serviceservice_name to data queuedata_queue_name in librarylibrary_name.

infoRole DQWrite

TAS400-0553 Reply message readsuccessfully in serviceservice_name from data queuedata_queue_name in librarylibrary_name.

infoRole DQWrite

TAS400-0554 Service service_namesuccessfully completed dataqueue write request.

infoRole DQWrite

TAS400-0591 Error occurred when writingto data queue.

debugRole DQWrite

TAS400-0601 Service service_name forspooled files list ended inerror. Error(s): error_details

errorRole SpooledFileList Check error(s) listed inthe error message andtake appropriate action.





TAS400-0602 Date-time range filter value isincorrect. Start DateTime:start_date-time, End DateTime:end_date-time

errorRole SpooledFileList The date/time rangespecified for spooledfiles list operation isincorrect. Pleasechange the date/timerange and try requestagain.

TAS400-0603 Status filter value is incorrect.Status: status

errorRole SpooledFileList The status valuespecified for spooledfiles list operation isincorrect. Pleasechange the status valueand try request again.

TAS400-0651 Service service_name receivedspooled files list request.

infoRole SpooledFileList

TAS400-0652 Spooled files list filters readand set successfully in serviceservice_name.


TAS400-0653 Service service_namesuccessfully completedspooled files list request.


TAS400-0691 Error occurred in spooled fileslist operation

debugRole SpooledFileList

TAS400-0701 Service service_name forspooled file to PDF ended inerror. Error(s): error_details

errorRole SpooledFilePDF Check error(s) listed inthe error message andtake appropriate action.

TAS400-0702 Required parameterparameter_name has incorrectvalue.

errorRole SpooledFilePDF The value of parametername specified in errorhas incorrect value.Please change the valuefor parameter and tryrequest again.

TAS400-0703 Parameter parameter_name hasnegative value.

errorRole SpooledFilePDF The value of parametername specified in errorhas negative value.Please change the valuefor parameter and tryrequest again.





TAS400-0704 Spooled file printer devicetype is not *SCS.

errorRole SpooledFilePDF The spooled file is not a*SCS spooled file.Please specify a *SCStype spooled file andtry request again.

TAS400-0705 Spooled file name'spooled_file_name', numberspooled_file_number for jobjob_name/job_user/job_numbernot found.

errorRole SpooledFilePDF The spooled filespecified for thisoperation was notfound. Please specifyan existing spooled fileand try request again.

TAS400-0751 Service service_name receivedspooled file to PDF request.

infoRole SpooledFilePDF

TAS400-0752 Service service_namesuccessfully completedspooled file to PDF request.

infoRole SpooledFilePDF

TAS400-0791 Error occurred in spooled fileto PDF operation

debugRole SpooledFilePDF




18 | TIBCO Product Documentation and Support Services

TIBCO Product Documentation and Support Services

For information about this product, you can read the documentation, contactTIBCO Support, and join the TIBCO Community.

How to Access TIBCO DocumentationDocumentation for TIBCO products is available on the TIBCO ProductDocumentation website, mainly in HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is morecurrent than any other documentation included with the product.

Product-Specific Documentation

The following documentation for this product is available on the TIBCOActiveMatrix® Adapter for IBM i page.

• TIBCO ActiveMatrix® Adapter for IBM i Release Notes

• TIBCO ActiveMatrix® Adapter for IBM i Installation

• TIBCO ActiveMatrix® Adapter for IBM i Concepts

• TIBCO ActiveMatrix® Adapter for IBM i Configuration and Deployment

• TIBCO ActiveMatrix® Adapter for IBM i Examples

How to Contact TIBCO SupportGet an overview of TIBCO Support. You can contact TIBCO Support in thefollowing ways:

• For accessing the Support Knowledge Base and getting personalized contentabout products you are interested in, visit the TIBCO Support website.

• For creating a Support case, you must have a valid maintenance or supportcontract with TIBCO. You also need a user name and password to log in toTIBCO Support website. If you do not have a user name, you can request oneby clicking Register on the website.

TIBCO ActiveMatrix® Adapter for IBM i Release Notes

https://docs.tibco.com/


https://www.tibco.com/services/support


https://support.tibco.com

https://docs.tibco.com/products/tibco-activematrix-adapter-for-ibm-i

https://docs.tibco.com/products/tibco-activematrix-adapter-for-ibm-i


https://docs.tibco.com/products/tibco-activematrix-businessworks-plug-in-for-ibm-mq


19 | TIBCO Product Documentation and Support Services

How to Join TIBCO CommunityTIBCO Community is the official channel for TIBCO customers, partners, andemployee subject matter experts to share and access their collective experience.TIBCO Community offers access to Q&A forums, product wikis, and bestpractices. It also offers access to extensions, adapters, solution accelerators, andtools that extend and enable customers to gain full value from TIBCO products. Inaddition, users can submit and vote on feature requests from within the TIBCOIdeas Portal. For a free registration, visit TIBCO Community.


https://ideas.tibco.com/portal_session/new

https://ideas.tibco.com/portal_session/new

https://community.tibco.com


20 | Legal and Third-Party Notices

Legal and Third-Party NoticesSOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY(OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE.THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BYANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyrightlaws and treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.TIBCO, the TIBCO logo, the TIBCO O logo, Hawk, Rendezvous, TIBCO Runtime Agent, ActiveMatrixBusinessWorks, TIBCO Administrator, TIBCO Designer, TIBCO BusinessEvents, andBusinessConnect are either registered trademarks or trademarks of TIBCO Software Inc. in the UnitedStates and/or other countries.Java and all Java based trademarks and logos are trademarks or registered trademarks of Oracleand/or its affiliates.All other product and company names and marks mentioned in this document are the property oftheir respective owners and are mentioned for identification purposes only.This software may be available on multiple operating systems. However, not all operating systemplatforms for a specific software version are released at the same time. See the readme file for theavailability of this software version on a specific operating system platform.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLYOR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer toTIBCO's Virtual Patent Marking document (https://www.tibco.com/patents) for details.Copyright © 1999-2021. TIBCO Software Inc. All Rights Reserved.

https://www.tibco.com/patents

tibcoactivematrix adapterfor ibm i

Documents