Iwave Integrator Users Guide PDF

iWave Integrator User Guide
Revision 5.7.20 Updated 03/01/07
www.iwavesoftware.com
Confidential
th iWave Integrator Users Guide 10 Edition, March 2007 P01-664-09
Publication Copyright Notice

This document is published by the iWave Software Technical Publications Department and applies to iWave Integrator Version 5.7.20. Copyright 2007 iWave Software, LLC. All rights reserved. This software/documentation contains proprietary information of iWave Software; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. Licensee is granted permission to make a limited number of copies of the documentation for its internal business purposes only. All such copies shall bear all copyright, trade secret, trademark and any other intellectual property notices on the original copies. This limited right to reproduce for internal purposes only is not transferable. Furthermore, this limited right DOES NOT include any license to distribute, modify, display or make derivative works from the Copyrighted materials.
Trademarks
iWave Software, iWave Integrator, and the iWave Software logo, are trademarks of iWave Software, LLC in the USA and in other select countries. The symbols and denote USA trademark rights. All other trademarks referenced are the property of their respective owners.
Disclaimer
iWave Software does not warrant that this document is error-free. The information in this document is subject to change without notice and does not represent a commitment on the part of iWave Software. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of an authorized representative of iWave Software, LLC.
Address inquiries to: iWave Software

3000 Internet Blvd, Suite 200 Frisco, Texas 75034 tel: + 1 866.924.9283 fax: + 1 214.618.6754 World Wide Web: http://www.iwavesoftware.com Email: ContactUs@iwavesoftware.com
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 2 of 276
Contents
FIGURES......................................................................................................................................... 8 TABLES .......................................................................................................................................... 9 ABOUT THIS GUIDE .................................................................................................................... 10 Notational Conventions .......................................................................................................... 10 iWave Integrator Library Information Map.............................................................................. 11 Common Books...................................................................................................................... 11 iWave Integrator Guides......................................................................................................... 12 Manual History ....................................................................................................................... 14 PART I ........................................................................................................................................... 15 CONCEPTS................................................................................................................................... 15 CHAPTER 1 .................................................................................................................................. 16 INTRODUCTION TO IWAVE INTEGRATOR ............................................................................................ 16 iWave Components ................................................................................................................ 17 Administering iWave............................................................................................................... 18 Enterprise Data Model............................................................................................................ 19 Transactions Between iWave Integrators .............................................................................. 20 Defining Mapping and Processing ......................................................................................... 22 Mapping File ........................................................................................................................... 22 Processing File ....................................................................................................................... 23 Securing Transactions............................................................................................................ 24 Specialized Processing with iWave Exits............................................................................... 25 Automatic Creation of Problem Reports................................................................................. 26 CHAPTER 2 .................................................................................................................................. 28 BASIC IWAVE INTEGRATOR CONCEPTS ............................................................................................. 28 What Data is Sent from Client to Server? .............................................................................. 29 Client Object ID ...................................................................................................................... 29 Server Object ID ..................................................................................................................... 31 Server Name .......................................................................................................................... 31 What Data is Returned from Server to Client?....................................................................... 31 Server Object ID ..................................................................................................................... 32 Transaction Return Value....................................................................................................... 32 Error Text................................................................................................................................ 32 What is Verb CREATE-UNIQUE? .......................................................................................... 33 What Causes a Client to Begin Processing a Transaction? .................................................. 33 Event Detection Mode ............................................................................................................ 34 Poll Detection Mode ............................................................................................................... 34 How Does the Client Respond to Transaction Success or Failure? ...................................... 35 What is Freeform Text?.......................................................................................................... 36 Example of Freeform Text Processing................................................................................... 36 Writing Freeform Text to a Database ..................................................................................... 39 CHAPTER 3 .................................................................................................................................. 40 UNDERSTANDING TABLES AND VERBS .............................................................................................. 40 Primary Tables and Subtables ............................................................................................... 40 Verbs ...................................................................................................................................... 41 Create-Unique ............................................................................................................... 42 Create............................................................................................................................ 44
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 3 of 276
Update ........................................................................................................................... 45 Lock ............................................................................................................................... 45 Unlock............................................................................................................................ 46 Retrieve ......................................................................................................................... 46 Search ........................................................................................................................... 46 Verb Qualifiers........................................................................................................................ 47 CHAPTER 4 .................................................................................................................................. 48 SELECTING A DETECTION MODE ....................................................................................................... 48 Event Mode ............................................................................................................................ 49 Guaranteed Delivery .............................................................................................................. 50 Responding to Transaction Delays ............................................................................... 52 Priority of Agent Requests............................................................................................. 52 Poll Mode................................................................................................................................ 53 CHAPTER 5 .................................................................................................................................. 55 UNDERSTANDING POST-PROCESSING UPDATE ................................................................................. 55 Success Codes ...................................................................................................................... 56 Failure..................................................................................................................................... 56 Responding to the Transaction Outcome............................................................................... 57 CHAPTER 6 .................................................................................................................................. 59 MAPPING AND TRANSFORMING DATA ............................................................................................... 59 iWave Integrator Data Types.................................................................................................. 59 Timestamp Fields .......................................................................................................... 61 Personal-Name Fields............................................................................................................ 62 Translate Field........................................................................................................................ 63 Planning for Data Conversion ................................................................................................ 64 NoClear Field.......................................................................................................................... 65 CHAPTER 7 .................................................................................................................................. 66 SYSTEM VARIABLES ........................................................................................................................ 66 #APP-RC# .............................................................................................................................. 66 #CLIENT-OBJECT-ID# .......................................................................................................... 67 #DATE# .................................................................................................................................. 67 #DIP-RC# ............................................................................................................................... 68 #DIP-RS# ............................................................................................................................... 68 #ERROR-TEXT# .................................................................................................................... 69 #EXIT#.................................................................................................................................... 69 #FIXED-NOW# ....................................................................................................................... 71 #NOW#................................................................................................................................... 72 #NULL# .................................................................................................................................. 72 #SERVER-OBJECT-ID# ........................................................................................................ 72 #TIME# ................................................................................................................................... 73 CHAPTER 8 .................................................................................................................................. 74 EXITS .............................................................................................................................................. 74 Exits Supplied with iWave Integrator...................................................................................... 75 UNIX and Windows Exits .............................................................................................. 75 z/OS Exits...................................................................................................................... 77 lpad......................................................................................................................................... 79 ltrim......................................................................................................................................... 79 pntexec ................................................................................................................................... 80 pntexif ..................................................................................................................................... 81 pntfrag .................................................................................................................................... 81 pntindex .................................................................................................................................. 84
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 4 of 276
pntinteger................................................................................................................................ 85 pntmath................................................................................................................................... 86 pntmcs (z/OS Extended MCS Console Assignment Exit)...................................................... 86 Example 1: Unrestricted System Commands ........................................................................ 89 Example 2: Restricted System Commands............................................................................ 92 pntsqlcmd ............................................................................................................................... 95 pntsqlif, PNTSQLIF ................................................................................................................ 99 pntsubst ................................................................................................................................ 100 pntwto ................................................................................................................................... 100 randint................................................................................................................................... 101 right....................................................................................................................................... 102 rpad ...................................................................................................................................... 102 rtrim ...................................................................................................................................... 103 strlwr ..................................................................................................................................... 104 strupr .................................................................................................................................... 105 timeconv ............................................................................................................................... 105 timediff .................................................................................................................................. 106 timestr................................................................................................................................... 108 tokenize ................................................................................................................................ 109 tranchr .................................................................................................................................. 110 Writing Functions for Use in Exits ........................................................................................ 111
PART II ........................................................................................................................................ 113 SECURING TRANSACTIONS .................................................................................................... 113 CHAPTER 9 ................................................................................................................................ 114 AUTHENTICATION AND ENCRYPTION USING SECURE SOCKETS (SSL).............................................. 114 SSL Overview....................................................................................................................... 114 Secure Sockets Certificates ................................................................................................. 115 Commercial Certificates .............................................................................................. 115 Self-Signed Certificates............................................................................................... 117 Secure Sockets Entropy....................................................................................................... 118
PART III ....................................................................................................................................... 119 ADMINISTERING IWAVE INTEGRATOR .................................................................................. 119 CHAPTER 10 .............................................................................................................................. 120 ADMINISTERING IWAVE INTEGRATOR FROM THE COMMAND LINE OR CONSOLE ................................. 120 Running iWave Administrator CLI (SDDC) .......................................................................... 121 Verbs Supported by the iWave Administrator CLI ...................................................... 123 Using UNIX Scripts to Administer iWave Integrator ............................................................. 126 Administering iWave Integrator from the z/OS Console ...................................................... 128 Stopping iWave Director.............................................................................................. 129 Generating a Status Report ........................................................................................ 129 Changing iWave Director Log Options........................................................................ 130 Starting Components................................................................................................... 130 Stopping Components................................................................................................. 130 Cycling Components ................................................................................................... 131 Forcing Components to Stop ...................................................................................... 131 Securing Userids and Passwords with the iwpasswd Utility............................................... 131
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 5 of 276
PART IV....................................................................................................................................... 134 A P P E N D I X E S , G L O S S A R Y A N D I N D E X ................................................................... 134 APPENDIX A............................................................................................................................... 135 PROCESSING AND MAPPING FILES .................................................................................................. 135 Sections in the Processing and Mapping Files .................................................................... 135 Purpose of the Sections in a Processing File....................................................................... 137 Purpose of the Sections in a Mapping File........................................................................... 138 Verb Processing and Active Sections .................................................................................. 138 Create-Unique ............................................................................................................. 139 Search ......................................................................................................................... 139 Statements in Processingand Mapping Files ....................................................................... 140 Assignment Statements .............................................................................................. 140 Mapping Statements ................................................................................................... 141 Inheritance............................................................................................................................ 142 Keyword INCLUDE...................................................................................................... 144 Keyword EXCLUDE .................................................................................................... 145 Value Assignments across Data Types ............................................................................... 145 Assigning to Field with Different Syntax...................................................................... 146 Assigning Character Data to a Freeform Text Field.................................................... 146 Assigning Freeform Text Data to a Character Field.................................................... 147 Assigning an Additional Entry to a Freeform Text Field.............................................. 147 APPENDIX B............................................................................................................................... 150 SYNTAX RULES.............................................................................................................................. 150 Syntax Rules ........................................................................................................................ 150 iWave Integrator Constants.................................................................................................. 150 Referencing Data Values ..................................................................................................... 152 Keywords whose Settings can be Referenced..................................................................... 153 Relational Expressions......................................................................................................... 154 Timestamp Masks ................................................................................................................ 155 Conversion Specifiers in Timestamp Masks ............................................................... 155 Settings for SQL Interfaces ......................................................................................... 158 Settings for Other Interfaces ....................................................................................... 159 Personal-Name Masks ......................................................................................................... 160 APPENDIX C............................................................................................................................... 163 TRANSACTION PROCESSING ........................................................................................................... 163 Stage 1: Data Access by the Local Client ............................................................................ 164 Search Phase on the Client ........................................................................................ 164 Read Phase on the Client ........................................................................................... 164 Stage 2: Processing by the Remote Server ......................................................................... 166 Search Phase on the Server ....................................................................................... 167 Read Phase on the Server.......................................................................................... 167 Write Phase on the Server .......................................................................................... 169 Stage 3: Post-Processing Update ........................................................................................ 170 Understanding the Details of Search Phase ........................................................................ 173 Understanding the Last Steps of Write Phase ..................................................................... 174 APPENDIX D............................................................................................................................... 176
IWAVE UNIVERSAL AGENT ............................................................................................................. 176
Running the Universal Agent................................................................................................ 176 Format .................................................................................................................................. 177 UNIX and Windows NT/2000 Example of Notification Mode ............................................... 184 UNIX Example of Event Mode.............................................................................................. 185
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 6 of 276
z/OS Examples..................................................................................................................... 186 Preparing to Run the Agents ....................................................................................... 186 Invoking the Agent in Normal Mode ............................................................................ 187 Running the Agent in Automated Mode ............................................................................... 188 Purpose of a Second Agent ........................................................................................ 188 Configuration Steps..................................................................................................... 189 Return Codes ....................................................................................................................... 190 APPENDIX E ............................................................................................................................... 192
IWAVE DIRECTOR CONFIGURATION FILE ......................................................................................... 192
Syntax of Statements in Configuration Files ........................................................................ 192 Base Section (z/OS)............................................................................................................. 193 Base Section (UNIX) ............................................................................................................ 197 Base Section (Windows) ...................................................................................................... 201 InternetParameters Section (z/OS) ...................................................................................... 205 ReceiveFrom Section (z/OS)................................................................................................ 206 ReceiveFrom Section (UNIX and Windows) ........................................................................ 206 Secure Sockets (UNIX and Windows) ................................................................................. 207 ReceiveFromSSL Section (UNIX and Windows) ................................................................. 207 ssl_recv_name Section (UNIX) ............................................................................................ 207 ssl_recv_name Section (Windows) ...................................................................................... 209 SendTo Section.................................................................................................................... 210 iwave_director_name Section (z/OS)................................................................................... 211 iwave_director_name Section (UNIX and Windows) ........................................................... 212 SendToSSL Section (UNIX and Windows) .......................................................................... 216 ssl_send_name Section (UNIX and Windows) .................................................................... 216 Services Section................................................................................................................... 220 service_name Section (z/OS)............................................................................................... 221 service_name Section (UNIX and Windows) ....................................................................... 225 ClientApplications Section.................................................................................................... 229 application_name Section (z/OS)......................................................................................... 230 application_name Section (UNIX and Windows) ................................................................. 232 Agents Section ..................................................................................................................... 236 agent_name Section (z/OS) ................................................................................................. 236 agent_name Section (UNIX and Windows).......................................................................... 238 APPENDIX F ............................................................................................................................... 242 PRODUCT IDENTIFIERS ................................................................................................................... 242 APPENDIX G............................................................................................................................... 244 TERMINATION STATUS ................................................................................................................... 244
GLOSSARY................................................................................................................................. 246 INDEX.......................................................................................................................................... 254
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 7 of 276
Figures
FIGURE 1 CONNECTION .................................................................................................................... 16 FIGURE 2 IWAVE INTEGRATOR COMPONENTS .................................................................................... 17 FIGURE 3 IWAVE DIRECTORS CONTROL ONE OR MORE IWAVE INTEGRATORS .................................... 18 FIGURE 4 SINGLE POINT OF CONTROL FROM A WINDOWS MACHINE ................................................... 19 FIGURE 5 VENDOR APPLICATION DATA MAPS TO THE ENTERPRISE DATA MODEL ................................ 19 FIGURE 6 TRANSLATION IS NEEDED WHEN VALUES ARE DIFFERENT................................................... 20 FIGURE 7 DATA FLOW ...................................................................................................................... 21 FIGURE 8 MAPPING AND PROCESSING FILES ..................................................................................... 22 FIGURE 9 SEVERITY AND PRIORITY MAP TO SEVPRI .......................................................................... 23 FIGURE 10 ENCRYPT TRAFFIC THAT CROSSES THE INTERNET ............................................................ 25 FIGURE 11 CONNECTING ENTERPRISE MANAGEMENT TO HELP-DESK APPLICATIONS .......................... 26 FIGURE 12 IWAVE INTEGRATOR CONNECTION ................................................................................... 28 FIGURE 13 EVENT DETECTION MODE................................................................................................ 49 FIGURE 14 DETECTION PORT NEEDED FOR EVENT MODE .................................................................. 50 FIGURE 15 POLL MODE .................................................................................................................... 53 FIGURE 16 ISSUING AN Z/OS COMMAND IN THE EXTENDED MCS CONSOLE ........................................ 87 FIGURE 17 SAMPLE RESPONSE FROM CONSOLE COMMAND ............................................................... 88 FIGURE 18 SETTINGS FOR THE EXTENDED MCS CONSOLE ................................................................ 89 FIGURE 19 COMMAND TO LAUNCH AGENT: UNRESTRICTED COMMANDS ............................................. 90 FIGURE 20 CLIENT MAPPING FILE: UNRESTRICTED COMMANDS ......................................................... 91 FIGURE 21 CLIENT PROCESSING FILE: UNRESTRICTED COMMANDS.................................................... 91 FIGURE 22 SERVER MAPPING FILE: UNRESTRICTED COMMANDS ........................................................ 92 FIGURE 23 SERVER PROCESSING FILE: UNRESTRICTED COMMANDS .................................................. 92 FIGURE 24 COMMAND TO LAUNCH AGENT: RESTRICTED COMMANDS ................................................. 93 FIGURE 25 CLIENT MAPPING FILE: RESTRICTED COMMANDS ............................................................. 93 FIGURE 26 CLIENT PROCESSING FILE: RESTRICTED COMMANDS ........................................................ 94 FIGURE 27 SERVER MAPPING FILE: RESTRICTED COMMANDS ............................................................ 94 FIGURE 28 SERVER PROCESSING FILE: RESTRICTED COMMANDS ...................................................... 95 FIGURE 29 IWAVE INTEGRATOR CONNECTION ................................................................................. 135 FIGURE 30 STRUCTURE OF FILES ................................................................................................... 136 FIGURE 31 STRUCTURE OF PROCESSING AND MAPPING FILES ......................................................... 143 FIGURE 32 CONVERSION SPECIFIERS IN TIMESTAMP MASKS ............................................................ 157 FIGURE 33 CONVERSION SPECIFIERS IN PERSONAL NAME MASKS ................................................... 161 FIGURE 34 ORIGIN PORT IN UNIVERSAL AGENT ............................................................................... 183 FIGURE 35 EXAMPLE SCRIPT TO START THE UNIVERSAL AGENT ....................................................... 185 FIGURE 36 TSXAGENT REXX EXEC ........................................................................................... 188 FIGURE 37 TSOAUTAG JCL......................................................................................................... 189 FIGURE 38 AUTOAGT REXX EXEC ............................................................................................. 190
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 8 of 276
Tables
TABLE 1 EXIT FUNCTIONS PROVIDED ON UNIX OR WINDOWS ............................................................ 76 TABLE 2 EXIT FUNCTIONS PROVIDED ON Z/OS .................................................................................. 78 TABLE 4 KEYS OF BASE SECTION (UNIX)........................................................................................ 197 TABLE 5 KEYS OF BASE SECTION (WINDOWS)................................................................................. 201 TABLE 6 KEYS OF INTERNETPARAMETERS SECTION (Z/OS) ............................................................. 205 TABLE 7 KEYS OF RECEIVEFROM SECTION (Z/OS) .......................................................................... 206 TABLE 8 KEYS OF RECEIVEFROM SECTION (UNIX AND WINDOWS) .................................................. 206 TABLE 9 KEYS OF RECEIVEFROMSSL SECTION (UNIX AND WINDOWS)............................................ 207 TABLE 10 KEYS OF SSL_RECV_NAME SECTION (UNIX).................................................................... 208 TABLE 11 KEYS OF SSL_RECV_NAME SECTION (WINDOWS) ............................................................. 209 TABLE 12 KEYS OF SENDTO SECTION ............................................................................................. 210 TABLE 13 KEYS OF IWAVE_DIRECTOR_NAME SECTION (Z/OS).......................................................... 211 TABLE 14 KEYS OF IWAVE_DIRECTOR_NAME SECTION (UNIX AND WINDOWS).................................. 213 TABLE 15 KEYS OF SENDTOSSL SECTION ...................................................................................... 216 TABLE 16 KEYS OF SSL_SEND_NAME SECTION (UNIX AND WINDOWS)............................................. 217 TABLE 17 KEYS OF SERVICES SECTION .......................................................................................... 220 TABLE 18 KEYS OF SERVICE_NAME SECTION (Z/OS) ....................................................................... 221 TABLE 19 KEYS OF SERVICE_NAME SECTION (UNIX AND WINDOWS)................................................ 225 TABLE 20 KEYS OF CLIENTAPPLICATIONS SECTION ......................................................................... 229 TABLE 21 KEYS OF APPLICATION_NAME SECTION (Z/OS)................................................................. 230 TABLE 22 KEYS OF APPLICATION_NAME SECTION (UNIX AND WINDOWS) ......................................... 232 TABLE 23 KEYS OF AGENTS SECTION ............................................................................................. 236 TABLE 24 KEYS OF AGENT_NAME SECTION (Z/OS) .......................................................................... 236 TABLE 25 KEYS OF AGENT_NAME SECTION (UNIX AND WINDOWS) .................................................. 238 TABLE 26 VENDOR APPLICATION IDENTIFIERS IN IWAVE INTEGRATOR LOGS ..................................... 242 TABLE 27 CLIENT ADAPTER EXIT STATUSES ................................................................................... 244 TABLE 28 SERVER ADAPTER EXIT STATUSES .................................................................................. 245 TABLE 29 MANAGED AGENT EXIT STATUSES ................................................................................... 245
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 9 of 276
About This Guide
This document does the following: Explains the iWave Integrator product concepts Describes how to administer iWave Integrator Details how to use the product to transfer data
Refer to the iWave Integrator Guide for any additional modifications required by your iWave Integrators.
Notational Conventions
This section explains the conventions used in this book: Examples that you type are in bold Courier. Menu selections are shown with arrows. For example, the command to select the Print choice from the File menu looks as follows: Select FilePrint. File names and path names are shown in bold. New or emphasized terms are shown in italics.
Descriptions of keyword syntax and system-variable syntax use the following conventions: Substitution variables are in italics.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 10 of 276
A pair of brackets ([ ]) means that the enclosed characters or variables are optional. An ellipsis (...) means that the preceding characters and variablesfrom the character after the preceding left bracket ([)may be repeated multiple times.
iWave Integrator Library Information Map

The iWave Integrator product includes books that apply to all iWave Integrator Adapters and iWave Integrator Guides for the specific iWave Integrator Adapter you are connecting. Searchable versions of the books are available in Adobe Acrobat Portable Document Format (PDF) in the Docs folder on the iWave Integrator product CD-ROM.
Common Books
The following iWave Integrator manuals contain information that applies to any iWave Integrator implementation, regardless of which iWave Integrator Adapter you are connecting: Readme File -- Although not a book, the Readme file, located on the distribution CD, should be consulted. Information about changes made to the product may not be documented in the regular manuals due to time constraints, but will always be listed in the Readme file. iWave Integrator Planning and Installation Guide -- Guides you through the steps you must complete before you implement iWave Integrator data synchronization. This book contains two parts. Part I describes planning issues and explains how to complete the planning worksheets. Part II provides instructions for loading the iWave Integrator files on UNIX, Windows, and z/OS. The appendices for this book include instructions for using the TCP/IP Test Program to test network connectivity, troubleshooting information, and more. iWave Integrator User's Guide -- Explains iWave Integrator concepts, guides you through the process of creating mapping and processing files, and explains how to administer the iWave Integrator product. (Refer to the associated iWave Integrator Guide for any additional changes required for a specific iWave Integrator Adapter.) iWave Integrator Keyword Reference -- Lists all of the keywords you can use in the mapping and processing files to customize iWave Integrator data exchanges. Each keyword entry includes a description, keyword syntax, application-specific usage, and lists of related keywords. iWave Integrator Messages and Codes -- Explains the log messages and the return codes and reason codes that iWave Integrator generates.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 11 of 276
iWave Integrator Guides

Each iWave Integrator Guide contains technical notes for specific iWave Integrator Adapters and complements the other iWave Integrator books. These documents provide supplemental instructions that apply only to a specific iWave Integrator Adapter for creating processing and mapping files, launching Agents, and modifying example files. Information that is common across all iWave Integrator Adapters is typically not included. The iWave Integrator Guides include the following: Customer Management Systems and Help Desk Products iWave Guide for Unicenter Service Desk Implementation -- Provides information regarding the implementation of the iWave Integrator Adapter for Unicenter Service Desk (CA) iWave Integrator Guide for Remedy -- Provides supplemental information for the iWave Integrator Adapter for Remedy (BMC Software) iWave Integrator Guide for Clarify -- Provides supplemental information for the iWave Integrator Adapter for Clarify. (Amdocs) iWave Integrator Guide for Microsoft Operations Manager 2005 -- Provides supplemental information for the iWave Integrator Adapter for Microsoft Operations Manager 2005 (Microsoft) iWave Integrator Guide for Peregrine -- Provides supplemental information for the iWave Integrator Adapter for Peregrine (Hewlett Packard) iWave Integrator Guide for SOLVE:Central -- Provides supplemental information for the iWave Integrator Adapter for CA SOLVE:Central (CA) iWave Integrator Guide for Tivoli InfoMan -- Provides supplemental information for the iWave Integrator Adapter for Tivoli InfoMan (IBM)
Enterprise-Management Applications iWave Integrator Guide for Enterprise Management -- Provides supplemental information for the iWave Integrator Adapter for a variety of enterprisemanagement applications that capture network information, including any version of the following:
OpenView NNM (Hewlett Packard) OpenView Operations (Hewlett Packard) Tivoli Enterprise Console (IBM) Tivoli NetView (IBM) Tivoli NetView for z/OS (IBM) Unicenter NSM (CA)
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 12 of 276
Other event-management applications (UNIX, Windows, or z/OS) that capture network events and are able to initiate system commands from those incoming events
Databases iWave Integrator Guide for SQL -- Provides supplemental information for the iWave Integrator Adapters that support the following databases: DB2 Universal Database (IBM) ODBC databases such as MS-SQL Oracle databases
This book also contains specific examples of how to integrate with the following products by integrating with one of the supported SQL databases: Tivoli Service Desk, including Tivoli Problem Management, Tivoli Asset, and Tivoli Change Management (IBM)
General Purpose iWave Integrator Guide For Web Services -- Explains how to transfer data received by iWave Integrator in XML to any other iWave Integrator Adapter. You can also convert data from other iWave Integrator Adapters to XML which can then be posted to a Web Service. iWave Integrator Guide for Flat Files -- Provides supplemental information for using the iWave Integrator Adapter for Flat Files, which connects to a text file (rather than to a specific vendor application or database). iWave Integrator Universal Interface -- Provides information about this generic iWave Integrator Adapter, which is useful for launching other programs that simulate an iWave Integrator Server or perform other actions.
NOTE purposes only and are no longer applicable.
iWave Integrator no longer supports SNA. Any references to SNA are for historical
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 13 of 276
Manual History
New editions incorporate any updates issued since the previous edition. Edition 1st Edition 2 Edition 3rd Edition 4th Edition 5th Edition 6th Edition 7th Edition 8th Edition 9th Edition
nd
Publication Number P01-664-01 P01-664-02 P01-664-03 P01-664-04 P01-664-05 P01-664-06 P01-664-07 P01-664-08 P01-664-09
Product Version Version 5 Version 5.02 Version 5.1 Version 5.2 Version 5.2.2 Version 5.5 Version 5.6 Version 5.7 Version 5.7.20
Publication Date April 2000 May 2000 December 2000 July 2001 December 2001 July 2002 August 2002 August 2005 March 2007
Minimum Product Level iWave Integrator Version 5 iWave Integrator Version 5.0.2 iWave Integrator Version 5.1 iWave Integrator Version 5.2 iWave Integrator Version 5.2 iWave Integrator Version 5.5 iWave Integrator Version 5.6 iWave Integrator Version 5.7 iWave Integrator Version 5.7.20
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 14 of 276
Part I Concepts
1
Introduction to iWave Integrator
The iWave Integrator product is a software system that shares information within an organization and between businesses. iWave Integrator exchanges data among a variety of vendor applications, which are third-party products such as help-desk tools and database-management systems. The exchange is accomplished by means of a connection --a data link--between one vendor application and the next. More than one connection can be implemented to enable multi-system data sharing. iWave Integrator connections can link vendor applications that reside either on the same machine or on different machines and can cross platforms. Supported platforms include z/OS, Windows NT/2000/XP, and UNIX (AIX, HP-UX, Linux, Solaris). Figure 1 shows an iWave Integrator connection between two vendor applications. Each vendor application has its own set of iWave components.
Figure 1 Connection iWave Integrator can synchronize data in both directions. You can also use iWave Integrator to transfer data in only one direction; for example, from vendor application A to vendor application B, depending on your business needs.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 16 of 276
iWave Components
An iWave Integrator is the iWave Integrator component that accesses a given vendor application's data. For example, one iWave Integrator supports the vendor application Remedy, one iWave Integrator supports the vendor application Clarify, and so on. Each connection requires two iWave Integrators, one for each vendor application. You can add additional connections as needed. iWave Integrators include one or more of the following: A Client uses data received from the vendor application, requests a service (such as a record update) from the remote iWave Integrator, and processes a response received from the remote iWave Integrator. A Server fulfills the requests sent from a remote Client and responds to the Client.
Figure 2 shows the iWave Integrators and their Client and Server components.
Figure 2 iWave Integrator Components The software that controls the iWave Integrators on a given machine is iWave Director. To start iWave Integrator, you invoke the iWave Director on each machine, which in turn starts one or more iWave Integrators (Figure 3).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 17 of 276
Figure 3 iWave Directors Control One or More iWave Integrators
Administering iWave
iWave Administrator CLI lets you manage iWave components from a single workstation running UNIX, Windows NT, Windows 2000, or Windows XP. You start each iWave Director from its own machine, and then you can use iWave Administrator CLI to do the following: Stop iWave Directors. iWave Directors start and stop the iWave Integrator Adapters, so stopping the iWave Directors is how you stop the iWave Integrator product. Start and stop the iWave components controlled by iWave Directors. View the status of those components.
Anyone using iWave Administrator CLI can view component status, but only users defined as iWave Integrator Authorized Users can stop and start components. iWave Administrator CLI communicates with each iWave Director through a reserved port called the Management Port (Figure 4).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 18 of 276
Figure 4 Single Point of Control from a Windows Machine
Enterprise Data Model

Vendor applications store and manipulate data using their own data structures and data formats. To enable vendor applications to share data, iWave Integrator interprets the data and resolves the inconsistencies. iWave Integrator accomplishes this by converting the data into the common data format that iWave components use to communicate with one another--the Enterprise Data Model format. The individual fields in this common format are called data model fields. On each side of a transfer, you map a relationship between a vendor field and a data model field. For example, in Vendor Application Data Maps to the Enterprise Data Model, Vendor Application A has the vendor field Company and Vendor Application B has the equivalent vendor field Customer. Both fields map to the data model field called CompCust. (You choose the names for the data model fields.)
Figure 5 Vendor Application Data Maps to the Enterprise Data Model

iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 19 of 276
The vendor fields, Company and Customer, have different names in the vendor application, but both vendor fields contain the same values--company names. Frequently, however, there are inconsistencies between the two vendor fields that must be resolved. iWave Integrator provides facilities for resolving common data inconsistencies. For example, one of the most common inconsistencies occurs when the vendor fields do not contain the same exact values (Figure 6).
Figure 6 Translation Is Needed When Values are Different In Vendor Application A, the values for Severity are Low, Medium, and High, but the valid values for the equivalent field in Vendor Application B are 1, 2, 3, 4, and 5. iWave Integrator lets you specify how you want to translate these values when transferring data.
Transactions Between iWave Integrators

Under the control of iWave Integrator, a series of events called a transaction occurs, beginning when the local Client starts to receive the data to be transmitted to the remote Server and ending when the local Client completes processing of the response received from the Server. Before the actual transaction begins, the Client must know when there is work to be done. All iWave Integrator transactions are initiated by the vendor application to which iWave Integrator is interfaced. The vendor application identifies the record that needs processing and then performs the actions needed to invoke the iWave Integrator Client. A transaction has these stages: Stage 1 --The local Client accesses the data from its vendor application, translates the data into the Enterprise Data Model format, and sends the data to the Server. Stage 2 --The remote Server receives the data, translates it into the vendor application's format, writes the data into the vendor application's database, and sends a response back to the requesting Client with reason codes and record numbers. Stage 3 --The local Client processes the response it receives from the Server.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 20 of 276
Figure 7 illustrates the flow of data for a sample transaction between two vendor applications.
Figure 7 Data Flow 1. The Client retrieves the data from Vendor Application A. You can set up a Client in event mode, which means that the Client processes records when specific events occur (such as an end user saving a record), or in poll mode, which means the Client processes records at regular intervals. For many vendor applications, only one of these detection modes is available.
NOTE
2. The Client tags each data item with the name of a data model field, transforms the data to Enterprise Data Model format, and sends the data to the remote Server. 3. The Server transforms the data into the format that Vendor Application B requires and writes the data into Vendor Application B's database. 4. The Server may retrieve processed data from Vendor Application B that may, in turn, be included in the response that the Server sends the Client. 5. The Server sends a response to the Client. The response contains a return value and may contain other data; for example, the Server may return a confirmation code to be written into the record that the Client retrieved initially. 6. The Client writes the response into Vendor Application A's database.
If data also travels in the other direction--starting at Vendor Application B and traveling to Vendor Application A--the flow begins with iWave Integrator B's Client, continues to iWave Integrator A's Server, and returns to iWave Integrator B's Client.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 21 of 276
Defining Mapping and Processing

During the planning phase of implementing iWave Integrator, you identify the fields in each vendor application that will be integrated and any inconsistencies between the data. Based on this planning information, you define the processing files and mapping files that guide the runtime behavior of a given iWave Integrator. The rules that control which vendor application fields are transferred and how iWave Integrator translates data from a vendor application's format into the Enterprise Data Model format are defined through the mapping and processing files. Each iWave Integrator has its own set of mapping and processing files (Figure 8).
Figure 8 Mapping and Processing Files For example, when a record in Vendor Application A is created or updated, the iWave Integrator Client uses the Client processing file and mapping file on that side of the connection to retrieve data from Vendor Application A's database and to convert the data to the Enterprise Data Model format. The data travels from Client to Server in this standardized format. Then Vendor Application B's Server uses the Server processing file and mapping file on its side of the connection to convert the data to Vendor Application B's format. When Vendor Application B's Server returns a response to Vendor Application A's Client, the data travels in the standardized format again. Vendor Application A's Client receives the response and uses the same Client processing file and mapping file to handle the response as were used when retrieving the data originally.
Mapping File
The mapping file associates vendor application fields with data model fields. For a connection between Vendor Application A and Vendor Application B, there are two mapping files: one that maps Vendor Application A's fields to data model fields and another that maps Vendor Application B's fields to data model fields.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 22 of 276
Processing File
The processing file defines the communication environment, including information about when and how to process records. Examples of information found in the processing file are as follows: Configuration information necessary for iWave Integrator to connect to the vendor application. Location of the mapping file. Defaults for certain operations and data transformations (for example, fields that allow you to append text to existing text--called freeform text fields --must be handled differently from simple character fields or timestamp fields). Required parameters for data transactions from Client to Server and Server to Client.
When building a processing file, you do the following: Assign settings to a series of keywords, or rules, which are reserved symbols for changing the run-time behavior of iWave Integrator. Build assignment statements, which place values in data model fields to allow complex processing.
The processing file also includes rules for translating data values between vendor applications. For example, suppose that Vendor Application A's field Severity and Application B's field Priority are both mapped to the same data model field (Figure 9). Although it is possible to include this translation in the mapping file, it is recommended the translation rule be defined in the processing file.
Figure 9 Severity and Priority Map to SevPri
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 23 of 276
Securing Transactions
iWave Integrator provides several levels of security for your customer data. The following security is always enabled: Each iWave Director must be configured to allow sending transactions to a specific iWave Director address and the receiving iWave Director must be configured to allow incoming transactions from the sending iWave Director. Only Authorized Users can start iWave Integrator. iWave Integrator must be authorized to read and write from the vendor application.
The following optional security is available: When transaction authentication is enabled, iWave Director must verify a user ID and password sent from iWave Client before a connection to the iWave Server is allowed. Connections between Directors may be authenticated, and transactions between Directors may be encrypted, with Secure Sockets Layer (SSL) authentication and encryption. The iWave Integrator Adapter for Web Services has Secure Sockets Layer (SSL) capabilities that you can use if necessary for your specific implementation. An origin port in the transaction allows firewalls to verify that iWave Integrator is the source of the message when determining whether to allow the transaction to cross.
You can choose which security options are appropriate for your site. For example, you may not need to encrypt transactions within your local network, but you would want to encrypt any transactions sent across the Internet (Figure 10).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 24 of 276
Figure 10 Encrypt Traffic That Crosses the Internet
Specialized Processing with iWave Exits

If the basic iWave Integrator functions do not meet a requirement you have, you can create an exit to perform this processing. Exits are powerful. When correctly created, you can define an exit to be loaded and kept in memory with iWave Integrator. The exit then becomes a user-defined extension. iWave Integrator provides the following types of exits, which allow you to integrate a customized program into iWave Integrator: An assignment exit, which places a value in a data model field. For example, you can use an assignment exit in the Client processing file of the local iWave Integrator to convert all letters except the first to lowercase in names sent to the remote iWave Integrator. You also can use assignment exits to place data into an unmapped data model field, which is a data model field that has no corresponding field in the vendor application. This option is available to handle moderately complex data transformations that require a temporary placeholder.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 25 of 276
A transaction exit, which changes processing behavior at a specified point before, during, or after a transaction. For example, you could use a transaction exit to send e-mail to several managers whenever a new problem report is available in vendor applications A and B.
iWave Integrator provides several programs for use in exits, and you can code your own.
Automatic Creation of Problem Reports

An enterprise-management application is a vendor application that filters network events and displays the significant events to the console. iWave Integrator can transfer these filtered network events to create problem reports in a remote help-desk application automatically, without operator intervention. When creating problem reports, iWave Integrator also does the following: Supplements the network events with meaningful data Recognizes duplicate problems and updates the problem report to show the number of times the event has occurred within a given interval (optional)
Figure 11 shows how iWave Integrator creates problem reports based on network events.
Figure 11 Connecting Enterprise Management to Help-Desk Applications Through use of a transaction exit, iWave Integrator can update the enterprisemanagement consoles to inform the operators that a problem report has been created in the remote help-desk application.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 26 of 276
iWave Integrator supports the following enterprise-management applications: HP OpenView NNM (Hewlett Packard) HP OpenView Operations (Hewlett Packard) Tivoli Enterprise Console (IBM) Tivoli Enterprise NetView (IBM) Tivoli NetView for z/OS (IBM) Unicenter NSM (Computer Associates, International) Unicenter Advanced Network Operations (Computer Associates, International) Microsoft Operations Manager (Microsoft)
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 27 of 276
2
Basic iWave Integrator Concepts
To understand the details of what iWave Integrator does requires answering the following questions: See What Data is Sent from Client to Server? See What Data is Returned from Server to Client? See What is Verb CREATE-UNIQUE? See What Causes a Client to Begin Processing a Transaction? See How Does the Client Respond to Transaction Success or Failure? See What is Freeform Text?
The answers in some cases refer to Figure 12, which shows the relationship between iWave Integrators A and B.
Figure 12 iWave Integrator Connection
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 28 of 276
What Data is Sent from Client to Server?

iWave sends the following kinds of data from a local Client to a remote Server: iWave Integrator sends data-model-field names and values. The collection of those data model fields --without values--is a named entity called an object class. An object class identifies the kind of information you are transferring. Examples are as follows: A problem report from a help-desk application, including problem date, description, and level of severity. A sales call, including call date, sales rep number, and result. An inventory update, including product number and number of items.
The data-model-field values are specific to a transaction. A particular problem report, for example, includes the following: Report date: 01-APR-2005 17:30:00 Report description: The printer in office 5 is out of order Problem severity: Medium
iWave Integrator also sends processing instructions, which are directives for use on the receiving iWave Integrator. Each processing instruction provides an internal value or the setting of a keyword, which is a rule in the processing file that changes the runtime behavior of iWave Integrator. All data model fields--both those that are mapped to vendor-application fields on the Client and those that are not mapped to vendor fields--are sent to the Server unless you explicitly exclude them from the transmission. To exclude fields from the transmission, you identify data model fields as local fields.
Following are processing instructions that are part of most transmissions from Client to Server: See Client Object ID See Server Object ID See Server Name
Client Object ID
When the Client at iWave Integrator A, for example, retrieves data from a database and transmits that data to the Server at iWave Integrator B, the transmission includes a Client object ID. The Client object ID is a key, a value that uniquely identifies a record in the database of vendor application A.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 29 of 276
For a given transaction, you identify the Client-side local object ID fields, which are fields that are in the database of vendor application A and are the source of the Client object ID. In most transactions, the Server at iWave Integrator B writes the received data-modelfield values into the database of vendor application B. You can also configure the Server to automatically write the Client object ID into that database. On the Server, the Client object ID received from iWave Integrator A is called the external object ID. To cause the Server at iWave Integrator B to store the Client object ID, do the following: Add a field for the external object ID to the database of vendor-application B. Specify that the Client Object ID is to be written to the added database field. It is recommended that you store the Client object ID on the Server side of a transaction because doing so helps to synchronize the data in the two vendor applications. Specifically, you store the Client object ID for one or both of the following reasons: To make easier a transaction that sends the stored and subsequently revised data in the opposite direction, from the Client at iWave Integrator B to the Server at iWave Integrator A. That transaction would use the external object ID in the database of vendor application B to identify what record to update in the database of vendor application A. To help end-users of vendor application B to identify the related record in the database of vendor application A. An end user of vendor application B, for example, could identify the Client object ID when asking an end user of vendor application A to review the record in its original format.
Two sets of vendor applications deserve special mention: On an iWave Integrator that supports one of the following vendor applications, the Client object ID is stored in a preset database field, and you do not identify the field: Action Request System SOLVE:Central Tivoli Information Management
On a Client that supports one of the following vendor applications, the Client object ID may be built from multiple database fields: Clarify SQL: DB2, ODBC, or Oracle
If the Client object ID is built from multiple database fields, a specified character--called a field separator --separates the data that was received from one field from the data received from another. If, for example, the Client object ID contains a last name and first name, and if the field separator is a forward slash, the following is a valid Client object ID: George/Washington
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 30 of 276
Server Object ID
When the Client at iWave Integrator A retrieves data from a database and transmits that data to the Server at iWave Integrator B, the transmission also may include the Server object ID. The Server object ID is a key, a value that uniquely identifies a record in the database of vendor application B. The Client at iWave Integrator A received that ID from the Server at iWave Integrator B at the end of a previous transaction, during postprocessing update. On the Client, the Server object ID received from iWave Integrator B is also called the external object ID. To cause the Client to store the ID during post-processing update and to retrieve the ID at the beginning of a later transaction, do the following: Add a field for the external object ID to the database of vendor application A. Specify that the Server object ID is to be written to and read from the added database field.
If the Server object ID is built from multiple database fields, a specified character--called a field separator --separates the data that was received from one field from the data received from another. The field separator of interest is the one defined for the remote iWave Integrator--in this case, for iWave Integrator B.
Server Name
Each iWave Integrator Server in your enterprise must have a unique name, which you specify in iWave Administrator CLI. During a transaction, the data sent from the Client always includes the name of the Server that is to receive the data.
What Data is Returned from Server to Client?

After the Server at iWave Integrator B processes data sent from the Client at iWave Integrator A, the Server returns the following: Data-model-field names and values.
For a given transaction, each data model field on the Client at iWave Integrator A is sent to the Server at iWave Integrator B unless you exclude the field from transfer by identifying it as a local field. For the transmission from Server to Client in the same transaction, however, the opposite is true: the only data model fields returned from the Server are those that you explicitly identify as return fields. The one exception to the latter rule is for verb RETRIEVE.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 31 of 276
The following processing instructions are part of most data flows from the Server at iWave Integrator B to the Client at iWave Integrator A: See Server Object ID See Transaction Return Value See Error Text
Server Object ID
When the Server at iWave Integrator B accesses data from a database and returns that data to the Client at iWave Integrator A, the transmission includes the Server object ID. It is recommended that you store the Server object ID on the Client side of a transaction for one or both of the following reasons: To make easier a later transaction that sends revised data from the Client at iWave Integrator A to the Server at iWave Integrator B. That transaction would use the Server object ID to identify what record to update in vendor application B. To help end-users of vendor application A to identify the related record in the database of vendor application B. An end user of vendor application A, for example, could supply the Server object ID when asking an end user of vendor application B to review the record in vendor application B.
Transaction Return Value

The transmission returned from the Server includes three error codes, which are available on the Client as iWave Integrator system variables: #DIP-RC#: the iWave Integrator return code #DIP-RS#: the iWave Integrator reason code #APP-RC#: the vendor-application return code
The combination of error codes is called the transaction return value, and the Client uses that value to determine what vendor-application database fields to update.
Error Text
The transmission returned from the Server also includes error text or, in the absence of such text, a null. The Client can store the returned value in the local database.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 32 of 276
What is Verb CREATE-UNIQUE?

A verb is a predefined transaction subtype such as UPDATE, which describes an action to be performed on the Server. Although several verbs are available, nearly all iWave Integrator customers run transactions based on verb CREATE-UNIQUE, and at most sites CREATE-UNIQUE is the only verb in use in an iWave Integrator client. During CREATE-UNIQUE processing, iWave Integrator determines whether a record exists that corresponds to the data being sent. If so, the existing record is updated, and if not, a new record is created. CREATE-UNIQUE makes development easier and helps ensure that data is synchronized across vendor applications. Features include the following: You set up only one type of transaction to handle both record creation and update. You can identify that certain data is to be written only when a record is being updated or only when a record is being is created. You can specify, for example, that only when a record is being created is the current time to be written into a database field called CreateTime. The Server can search for a record based on a search argument you specify. As a result, the transaction can prevent the Server from doing an unnecessary create if the data being transferred already exists in the remote vendor application, but an earlier network failure prevented the Client from receiving the Server object ID for that data. The transaction creates a replacement record if data on the Server is inadvertently deleted and equivalent data arrives from the Client.
What Causes a Client to Begin Processing a Transaction?

The circumstance that causes a Client to begin processing a transaction depends on whether you configured the Client for poll detection mode or event detection mode. On some iWave Integrators you must use a particular detection mode; on others, you have a choice. iWave Integrators that support enterprise-management applications like HP OpenView NNM, for example, only use event mode. For details on a specific iWave Integrator, see the iWave Integrator Guide for the vendor application.
Most iWave Integrators can use the Universal Agent for event mode.
NOTE Some iWave Integrators use specialized agents. See the iWave Integrator Guide for
your vendor application to determine which Agent to use.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 33 of 276
Event Detection Mode

If detection mode is event, you set up the vendor application so that an end-user action-for example, a record update--causes that vendor application to invoke a software program called an Agent. When invoking an Agent, the vendor application indicates what data is to be processed and what is to be done with that data. The Agent transfers the information to the Client, which listens for transmissions on a port. On an iWave Integrator that supports a database-based vendor application such as a help-desk tool, the Agent is called an Agent and provides transmission data indirectly, supplying a Client object ID that identifies a database record for the Client to retrieve. In this case, a transaction begins when the Client starts to retrieve a record. The Client object ID is in the data sent from Agent to Client. If the Client is running in event mode, Agents usually send only the information that the Client needs to retrieve the record from the database (local object ID, object class, verb, and verb qualifier, if used). However, Agents can send vendor fields and values in addition to the local object ID. When initiating a transaction, some Clients check to determine if the Agent supplied such vendor fields and values. If so, the Client retrieves the vendor fields directly from the data supplied from the Agent instead of from the database. iWave Integrator Clients that process data-item lists this way include the following: Remedy Amdcos CRM (formerly Clarify) SQL Tivoli Information Management iWave Universal Integrator
To use event mode, set the detection mode to event in the processing file.
Poll Detection Mode

If detection mode is poll, you set up the vendor application so that an end-user action--for example, a record update--places specified values in specified database fields. On the Client, you map data model fields to those database fields, then identify poll criteria --a search argument that includes the data model fields and values. The Client uses the poll criteria to search the database periodically for records in which the specified fields contain the specified values. You cannot specify ranges, such as a date range, as part of the search criteria. Nor can you define a logical OR condition. All data model fields defined in poll criteria are treated as a logical AND. After mapping data model field UPDATE_FLAG to a field in the vendor-application database, for example, you specify a poll criteria like the following: UPDATE_FLAG="Y"
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 34 of 276
In this example, the Client initiates a transaction on finding a record in which Y is the value of the database field that corresponds to UPDATE_FLAG. On finding a record that fulfills the poll criteria, the Client retrieves either the record itself or a record directly linked by foreign key to that record, depending on how you set up the transaction. You also specify a poll interval --the number of seconds between the end of one search and the beginning of the next.
How Does the Client Respond to Transaction Success or Failure?

In the poll-mode example from the previous section, the Client initiates a transaction on finding the value Y in a database field. If nothing is done to overwrite that string when the transaction ends, the Client selects the same record during the next poll and during every subsequent poll. This section describes how to prevent that kind of repetition and how to use data returned from the Server. In the Client processing files, you categorize each transaction return value as one of the following: A success code, which indicates that the transaction completed successfully. A failure code, which indicates that the transaction failed. A recover code, which indicates that the transaction failed but may succeed if run again. Reserve this category for transactions that end because of network failure.
During post-processing update (the final stage of a transaction), the Client uses your categorization to determine what to do with the data returned from the Server. In the pollmode example, you might null the database field that contained Y. Making that change prevents the Client from processing a record twice. To specify what value to assign to a database field after the transaction ends in a particular way, identify the data model field as one or more of the following: A success field, which receives a specified value only if the transaction succeeds. A failure field, which receives a specified value only if the transaction fails. A recover field, which receives a specified value only if the transaction ends with a recoverable error.
After a successful transaction and in no other case, iWave Integrator writes all data model fields returned from the Server. At the end of a successful transaction, if a data model field is both specified as a
NOTE success field and returned from the Server, the value assigned to the success field
takes precedence over the value returned from the Server.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 35 of 276
What is Freeform Text?

Many transactions include a freeform text field, which is a data model field that contains information in a format like that of a diary. The freeform text field is composed of a series of entries, each of which contains the following: Entry text The ID of the user who wrote the entry text A timestamp that indicates when the entry was created
Some vendor applications provide a data type that is structured like a freeform text field. Remedy, for example, provides data type DIARY. If no such data type is available, iWave Integrator can be made to access the vendor-application database in a way that simulates access of a DIARY field. When sending a freeform text field, iWave Integrator does not include every entry, but only the most recent ones; specifically, only entries that were added since iWave Integrator last accessed the database fields to which the freeform text field is mapped. iWave Integrator avoids transferring all entries because a full transfer could result in duplicate information being appended to database fields in the remote vendor application. The transfer of partial information is part of a design that lets you integrate the following: Vendor applications that provide a data type for storing freeform text Vendor applications that lack such a data type
After reading into a freeform text field, iWave Integrator selects the entries to be sent by comparing the timestamp in each entry with the value in a text-indicator field, which is a date/time database field that iWave Integrator keeps updated but does not include in the data transmitted between Client and Server.
Example of Freeform Text Processing

To understand how iWave Integrator processes freeform text, assume the following: The main office of the iWave Bank has a computerized system for tracking reports of hardware problems at branch offices. When a problem arises, branch employees dial a help-desk number that connects them randomly with an old help-desk site or a new one. The help-desk operators at the old site enter problem reports in vendor application A, while those at the new site enter reports in vendor application B. You set up a connection so that, when a help-desk operator at one site creates or updates a problem report, iWave Integrator transfers a subset of the data to the remote vendor application; in this way, the personnel who use one vendor application can access data from problem reports entered into the other.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 36 of 276
You add a text-indicator field to each vendor-application database. The initial value in each text-indicator field is 01 January 2007.
The series of events is as follows: 1. In response to a call from a branch office, a help-desk operator working in vendor application A enters a problem report, which includes the following data: Problem-report number: 1006 Branch ID: 05 User ID: USER01 Timestamp: 01 April 2008 09:30:00 Entry Text: The branch printer is out of order.
The data is stored in the local problem-report table, along with the branch ID and problem-report number. 2. The local Client does the following: a Reads the problem-report number into one data model field; reads the branch ID into a second; and reads the user ID, timestamp, and entry text into a third, which is a freeform text field that contains one entry. Compares the timestamp in the freeform text entry (year 2008) with the value in the text-indicator field (year 2007) and accepts the entry. Sends the transaction data to the remote Server at time 09:30:55.
b c
3. On receiving the data, the remote Server does the following: a b c Writes the current time (09:31:00) to the text-indicator field that you added to the database of vendor application B. Writes the data to the database in vendor application B. Sends a response to the Client.
4. On receiving the response, the local Client does the following: a

Writes the time when the transaction was sent (09:30:55) into the text-indicator field that you added to vendor application A; this step occurs only if the transaction succeeded. Updates other database fields, as you specify.
5. A help-desk representative working in vendor application A receives a status report and adds the following data to the same problem report: User ID: USER02 Timestamp: 01 April 2008 09:45:00 Entry Text: Technician 8 is investigating.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 37 of 276
The new data is stored in the local problem-report table, along with branch ID and problem-report number. 6. Before the Client accesses the record, a help-desk representative working in vendor application A adds the following data to the same problem report: User ID: USER03 Timestamp: 01 April 2008 09:46:00 Entry Text: Estimated down time is 2 hours.
The new data is stored in the local problem-report table, along with branch ID and problem-report number. 7. The local Client does the following: a Reads the problem-report number into one data model field; reads the branch ID into a second; and reads the user ID, timestamp, and entry text into a third, which is a freeform text field that contains three entries. Compares the timestamp in each freeform text entry with the updated value in the text-indicator field (09:30:55), discards the first entry, and accepts the second two. Sends the transaction data to the remote Server at 09:47:56.
8. On receiving the data, the remote Server does the following: a Writes the current time (09:48:00) to the text-indicator field that you added to the database of vendor application B. Writes the data to the database in vendor application B. Sends a response to the Client.
b c
9. On receiving the response, the local Client does the following: a Writes the time the transaction was sent (09:47:56) into the text-indicator field that you added to vendor application A; this step occurs only if the transaction succeeded. Updates other database fields, as per your specification.
As demonstrated in the previous steps, iWave Integrator uses the local text-indicator field to avoid resending freeform text entries to the remote Server. If your connection sends freeform text only in one direction, from the local Client to the remote Server, you need to identify a text-indicator field only in the local iWave Integrator. In this example, some transactions flow from the local Client to the remote Server, and some flow in the opposite direction. The local text-indicator field keeps the Client from sending freeform text entries that the local Server received from the remote Client. A similar situation is in effect for the remote iWave Integrator. The remote text-indicator field has the following purposes:
iWave Software
Revised [03/01/07] P01-664-09
To prevent the remote Client from resending freeform text entries it already sent.
Confidential Page 38 of 276
To prevent the remote Client from sending data received during an earlier transaction.
Writing Freeform Text to a Database

When writing freeform text to the vendor-application database, a single database field receives a concatenated string, which contains every text entry sent in the freeform text field. In most cases, iWave Integrator precedes the text for a given entry with the user ID and timestamp for that entry. In the last example of the previous section, a database field in vendor application B receives the following: USER02 01 April 2008 09:45:00
Technician 8 is investigating. USER03 01 April 2008 09:46:00
Estimated down time is 2 hours.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 39 of 276
3
Understanding Tables and Verbs
This chapter includes the following sections: Primary Tables and Subtables on page 40 Verbs on page 41 Verb Qualifiers on page 47
Primary Tables and Subtables

Most iWave Integrators access a vendor-application database. During a typical transaction, the local Client reads data to be processed; the remote Server writes the data received from the Client; and the Client writes the transaction-status information returned from the Server. For each iWave Integrator in a given transaction, you identify a primary table, which is the main database table being accessed. The primary table contains a record whose ID uniquely identifies the data being accessed. The ID from the Client-side primary table is called the Client object ID, and the ID from the Server-side primary table is called the Server object ID. Each ID is passed to the opposite iWave Integrator and is referred to there as the external object ID. For each iWave Integrator in a given transaction, you usually may specify one or more subtables, each of which is a database table that is either related to the primary table or is processed on its own, with no relationship to another table. The operation you perform on a subtable is independent of the operation you perform on the primary table. For example, you may do any of the following: Create or update a subtable record when creating a record in the primary table Create or update a subtable record when updating a record in the primary table
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 40 of 276
Read subtable data for use in the primary-table record being created or updated
For further details on subtables, see the iWave Integrator Keyword Reference entry for keyword SUB-TABLE.
Verbs
When planning a transaction, you decide on one of several predefined verbs, each of which is a type of transaction. The verbs used most often are Create-Unique, Create, and Update: Create-Unique updates an existing record on the remote iWave Integrator, if possible, or creates a new record in most cases when an update is not possible. Using verb Create-Unique is the best way to synchronize the local and remote iWave Integrators and to protect against data loss. Create inserts a new primary-table record on the remote iWave Integrator. Update updates a primary-table record on the remote iWave Integrator.
The Lock, Unlock, Search, and Retrieve verbs are also available, but the vendor application must provide special support for their use: Lock locks a primary-table record on the remote iWave Integrator and in some cases locks the equivalent primary-table record on the local iWave Integrator. Unlock unlocks a primary-table record on the remote iWave Integrator and in some cases unlocks the equivalent primary-table record on the local iWave Integrator Search searches for primary-table records on the remote iWave Integrator and returns IDs of the records found and, if only one record is found, Search in some cases returns that record. Retrieve returns a primary-table record from the remote iWave Integrator.
NOTE verbs Create, Create-Unique, and Update only.
An iWave Integrator that supports an enterprise-management application processes
The following sections describe each verb in relation to the three stages of processing. The commonly used verbsCreate-Unique, Create, and Updateare described first. For a detailed description of the three stages, see Transaction Processing on page 163.
Keyword LOCK-SPEC guides record locking and unlocking for all verbs except
NOTE Search, which involves no locking or unlocking. For further details, see the iWave
Integrator Keyword Reference entry for keyword LOCKSPEC.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 41 of 276
Create-Unique This section describes the benefits of Create-Unique processing and gives details on how the verb works.
Benefits of Create-Unique Processing Create-Unique handles the following, commonplace circumstance: The Client sends data from record A to the remote iWave Integrator, which creates a new record and returns the Server object ID to the local iWave Integrator. During post-processing update, the Client writes the Server object ID to a field in the local database. After the local vendor application changes record A, the Client resends the data from record A to the remote iWave Integrator, along with the previously stored Server object ID. The remote iWave Integrator uses that ID to identify the record to be updated.
Create-Unique also protects against data loss on the Server, as described in the following example: The local iWave Integrator sends data from record B to the remote iWave Integrator, which creates a new record and returns the Server object ID to the local iWave Integrator. During post-processing update, the local iWave Integrator writes the Server object ID to a field in the local database. Some time later, however, an end-user of the remote vendor application mistakenly deletes the record. After the local vendor application changes record B, the local iWave Integrator resends the data from record B to the remote iWave Integrator, along with the previously stored Server object ID. The remote iWave Integrator identifies no record that matches the ID, but creates a new record and returns the new ID to the local iWave Integrator. During post-processing update, the local iWave Integrator writes the new Server object ID to a field in the local database, ensuring that in future the remote iWave Integrator will update the correct record, as if the deletion had not occurred.
Finally, Create-Unique protects against the creation of an extra record on the Server in the following circumstance: The local iWave Integrator sends data from record C to the remote iWave Integrator, which creates a new record and tries to return the record ID to the local iWave Integrator. A network failure prevents the local iWave Integrator from receiving that response. After the local vendor application changes record C, the local iWave Integrator resends the data from record C to the remote iWave Integrator. The remote ID is not available to the local iWave Integrator, which provides the ID of the local record instead. The remote iWave Integrator uses the available ID to find the record created during the previous transaction. In this way, iWave Integrator maintains the same data on the two iWave Integrators despite the earlier network failure.
iWave Software
Revised [03/01/07] P01-664-09
Details of Create-Unique Processing During the initial stage of Create-Unique processing, the local Client reads data from a primary table and optionally from one or more subtables and sends the data to the Server. Events on the Server depend on whether the Client transmitted a Server object ID, as happens if the Client stored that ID during a previous Create-Unique transaction. To cause the Client to store and transmit the Server object ID, set keyword EXTOBJECTID, as described in the iWave Integrator Keyword Reference. On an iWave Integrator that supports an enterprise-management application like HP OpenView NNM, the external object ID setting is not available, because iWave Integrator does not access a Client-side database. Including a Server Object ID in the invocation of an Event Agent, however, causes the Client to transfer the Server Object ID to the Server. For details, see the iWave Integrator Guide for Enterprise Management.
If the Server Receives a Server Object ID If a Server object ID is present in the data sent from Client to Server, no search occurs, and the Server tries to update the record. If the update is unsuccessful, the Server creates a record if both of the following are true: The update fails specifically because a record on the Server is not found. The setting for keyword CREATE-ALWAYS is Yes.
Set keyword CREATE-ALWAYS to Yes to protect against data loss from an inadvertent deletion of the record. Set the keyword to Never to force a transaction failure if the Server object ID is provided but does not match a record.
If the Server Does Not Receive a Server Object ID If a Server object ID is not present in the data sent from Client to Server, the Server searches for the record if you provide search criteria in either of two ways: If keyword UNIQUE-FIELDS identifies one or more data model fields sent from the Client as being unique fields, the Server searches for a primary-table record having the following characteristics: Contains values equal to the values in the unique fields that are mapped to the primary table. Is directly related to a subtable record that has values equal to the values in the unique fields that are mapped to the subtable; you specify a direct relationship of primary table to subtable when defining the subtable.
The search rules may be supplemented by search criteria specified on the Server. You may specify search criteria only on the Server, but the search occurs only if you also set keyword SEARCH-ALWAYS to Yes.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 43 of 276
If a search is successful, the Server tries to update the first primary-table record found; but if the update fails, the Server creates a record only if you set keyword CREATEALWAYS field to Yes or Err. If no search argument is provided or if a search fails, the Server tries to create a record in all cases. Subsequent Processing on the Server Next, the remote Server does the following: Writes mapped data model fields to vendor fields in the new or updated primarytable record Optionally, writes mapped data model fields to vendor fields in a new or existing record in one or more subtables Returns the following: The ID of the new or updated primary-table record. A transaction return value. Error text, if any. Data model fields identified as return fields. If the Server created a record, the return fields are those identified as create return fields; if the Server updated a record, the return fields are those identified as update return fields.
Post-processing Update on the Client On receiving the returned data, the Client does a post-processing update, as described in Chapter 5, Understanding Post-Processing Update.
Create During the initial stage of Create processing, the local Client reads data from a primary table and optionally from one or more subtables and sends the data to the Server. Next, the Server does the following: Writes mapped data model fields to vendor fields in the new primary-table record Optionally, writes mapped data model fields to vendor fields in a new or existing record in one or more subtables Returns the following: iWave Software
Revised [03/01/07] P01-664-09
The ID of the new primary-table record A transaction return value Error text, if any Data model fields identified as create return fields
On receiving the returned data, the Client does a post-processing update, as described in Chapter 5, Understanding Post-Processing Update.
Update During the initial stage of Update processing, the local Client reads data from a primary table and optionally from one or more subtables and sends the data to the Server, including a Server object ID. Next, the Server does the following: Writes mapped data model fields to vendor fields in the remote primary-table record Optionally, writes mapped data model fields to vendor fields in a new or existing record in one or more subtables Returns the following: The ID of the updated primary-table record. A transaction return value. Error text, if any. Data model fields identified as update return fields.
On receiving the returned data, the Client does a post-processing update, as described in Chapter 5, Understanding Post-Processing Update.
Lock During the initial stage of Lock processing, the local Client does the following: Reads data from a primary table and optionally from one or more subtables. Locks the primary-table record on the local iWave Integrator, but only if settings of keyword LOCK-SPEC cause that effect. Sends the data to the Server, including a Server object ID.
Next, the Server locks the primary-table record identified by the Client and returns the following: The ID of the locked record. A transaction return value. Error text, if any.
The Server processes no subtables. On receiving the returned data, the Client does a post-processing update, as described in Chapter 5, Understanding Post-Processing Update.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 45 of 276
Unlock During the initial stage of Unlock processing, the local Client reads data from a primary table and optionally from one or more subtables, then sends the data to the Server, including a Server object ID. Next, the Server unlocks the primary-table record identified by the Server and returns the following: The ID of the locked record A transaction return value Error text, if any
The Server processes no subtables. On receiving the returned data, the Client does a post-processing update, as described in Chapter 5, Understanding Post-Processing Update. The Client then unlocks the primarytable record on the local iWave Integrator, but only if the Lock Spec settings cause that effect.
Retrieve During the initial stage of Retrieve processing, the local Client reads a Server object ID from a record in either the primary table or a subtable and sends the ID to the Server. Next, the Server does the following: Reads vendor fields from the identified primary-table record Optionally, reads vendor fields from existing records in one or more subtables Returns the data model fields that correspond to those vendor fields, as well as a transaction return value and any error text.
The Client writes the received data model fields to the database; usually, to a primarytable record that contained the Server object ID. (If requested by the Agent, the Client sends data-model-field values to the Agent, which the Agent then writes to the Agent log.) The Client also does a post-processing update, as described in Chapter 5, Understanding Post-Processing Update.
Search During the initial stage of Search processing, the local Client reads data from a primary table and optionally from one or more subtables and sends the data to the Server. The Server searches for a record that has the following characteristics: Matches the values of the data model fields transmitted from the local Client. Fulfills the search criteria, if any, sent from the local Client. Fulfills the search criteria, if any, present on the Server.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 46 of 276
If the remote Server finds one and only one record, and if you set keyword RETRIEVEONE-HIT to YES on the local Client, the Server reads values from the found record into mapped data model fields, then returns to the Client both the data model fields and the ID of the found record. If the Server finds multiple records, or if you set keyword RETRIEVE-ONE-HIT to NO on the local iWave Integrator and a single record is found, the Server returns the following for each record found: The ID of the found record. A transaction return value. Error text, if any. Data model fields identified as search return fields.
The Client writes the received data model fields to the database; usually, to a primarytable record that contained the Server object ID. The Client also does a post-processing update, as described in Chapter 5, Understanding Post- Processing Update. If the remote Server returns data from multiple records, the local Client processes repeated updates to the database. If the local vendor application does not process each record in some way, only the last set of data-model-field values remains.
Verb Qualifiers
A verb qualifier is a verb subtype that causes a transaction to be processed in a way that is specific to a characteristic of the data that initiated the transaction. You may be working with a pair of help-desk applications, for example, and want the Server to nullify a database field called DATE_CLOSED when receiving data on a problem report that was opened or reopened, but to set DATE_CLOSED to the current date when receiving data on a problem report that was closed. One way to fulfill the task is unrelated to verb qualifiers. In the data to be sent from Client to Server, include a data model field that reflects the status of the problem report opened or closed. You then configure the Server to conditionally place a value in the data model field mapped to DATE_CLOSED, where the condition that determines the value of that data model field is the status value sent from the Client. See the entry for keyword USE-KEYWORD-IF in the iWave Integrator Keyword Reference for more details. Alternatively, you can define separate transactions, one of which is initiated when the problem report is opened or reopened, the other when the problem report is closed. The Server nulls DATE_CLOSED in the first transaction and assigns the current date to the database field in the second. The separate transactions are identified with the same object class and verb, but are distinguished by an additional name of your choosing, the verb qualifier. Verb qualifiers are used infrequently, but are necessary when the data-model-field values sent from Client to Server cannot cause a required difference in processing.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 47 of 276
4
Selecting a Detection Mode
Detection mode specifies how a Client determines that the local vendor application has data to be processed by iWave Integrator. The available options are event mode and poll mode. Event mode In event mode, the Client listens on a port for a communication by an iWave Integrator Agent. The Agent in most cases is a small program launched from a vendor application in response to an end-user action such as a record update. On an iWave Integrator that supports a database-based vendor application such as a help-desk tool, the Agent is called a Notification Agent and it usually provides transmission data indirectly by identifying a primary-table record for the Client to retrieve. In this case, a transaction begins when the Client starts to retrieve the record from the database. However, if the Agent is configured to send additional data to the Client, the Client retrieves the data from the Agent (and not from the database). In this case, a transaction begins when the Client starts to retrieve the record from the Agent. On an iWave Integrator that supports an enterprise-management application, the Agent is called an Event Agent and directly provides data that the Client transmits to the remote iWave Integrator. In this case, a transaction begins when the Client starts accessing the data. Notification Agents (but not Event Agents) include logic for sending the local object ID for a record to the Client, which allows the Client to retrieve the record from the database. Event Agents (but not Notification Agents) include logic for filtering, so you can configure the Agent to process or ignore incoming records or events based on criteria you choose. For further details, see Event Mode on page 49.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 48 of 276
Poll mode In poll mode, you define database-search rules that the Client uses to find records for subsequent processing, and you specify the interval between the end of one search period and the start of the next. For further details, see Poll Mode on page 53.
On some iWave Integrators you must use a particular detection mode; on others, you have a choice. iWave Integrators that support enterprise-management applications, for example, only use event mode. For details on a specific iWave Integrator, see the iWave Integrator Guide.
Event Mode
To prepare for event mode, customize the vendor application to communicate with an Agent in response to a real-time event such as a record update. The Agent in turn communicates with the local Client (Figure 13).
Figure 13 Event Detection Mode Different iWave Integrators include different Agents: Most UNIX- and Windows-based iWave Integrators that support event mode receive data from a Universal Agent, which is launched as necessary; for details, see the appropriate iWave Integrator Guide. Similarly, iWave Integrators that support an enterprise-management application receive data from an Event Agent (sometimes called a Universal Agent), which is also launched as necessary; for details, see the iWave Integrator Guide for Enterprise Management. In the following cases, the Notification Agent is defined in the iWave Administrator CLI product and runs continuously under the control of the iWave Director product rather than in response to a vendor-application message: iWave Software
Revised [03/01/07] P01-664-09
For ECI, see the iWave Integrator Guide for ECI.

For Peregrine Service Center, see the iWave Integrator Guide for Peregrine Service Center.
Any Agents that must (or can) run under the control of iWave Director are available in iWave Administrator CLI. If you do not see your Agent listed, it never runs as a managed Agent. The Notification Agent runs continuously, but not under the control of iWave Director for the following: For CA SOLVE:Central, see the iWave Integrator Guide for SOLVE:Central.
Finally, in the following cases, the Notification Agent is launched as necessary, but takes different parameters than does the Universal Agent: For Tivoli Information Management, see the iWave Integrator Guide for Tivoli Information Management.
If the Client runs in event mode, identify the port where the Client listens for messages from an Agent (Figure 14).
Figure 14 Detection Port Needed for Event Mode
Guaranteed Delivery
iWave Integrator supports store-and-forward capability, known as guaranteed delivery, for Clients and, beginning with Version 5.1, for most Agents. Although you can implement guaranteed delivery for only the Agent or the Client, you should configure guaranteed delivery for both for the best results. (If guaranteed delivery is not available for the Agent, configure a second Client running in poll mode to check for unsent records and forward them to the remote Server.) Implementing guaranteed delivery for the Agent guarantees that records are delivered to the local Client. Implementing guaranteed delivery for the Client ensures that records are delivered to the remote Server.
Agent If the Client is down when the Agent sends to the Client, the transaction can be lost. To ensure that all transactions are sent, you can set up a second Client running in poll mode
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 50 of 276
that sends any records that could not be sent by the Client running in event mode. Another method is to implement guaranteed delivery by setting up a store locale for the Agent. The following Agents can have a store locale: Universal Agent Universal Agent
When one of these Agents receives information to be transmitted to the Client, the data is guaranteed to be delivered to the remote Server if you do the following: Step 1. Establish a store-locale directory or z/OS VSAM key-sequenced data set (KSDS) specific to that Agent, with space sufficient to store information on all transactions received but not completed. Depending on the type of Agent and your configuration, the objects stored in the store locale may contain only the information that the Client needs to retrieve the records from the database or may contain all the data that the Client will transfer. The Agent cannot share this store locale with a Client, because iWave Integrator prevents this. Step 2. Identify the location of the store locale with an Agent parameter. For the Universal Agent and Universal Agent, this is the -g parameter. For the Agent Logging Facility used with the iWave Integrator for IMS Event Capture and the iWave Integrator for DB2 Event Capture, this is the STORE_LOCALE parameter. See the documentation for the Agent you are using for more information about specifying Agent parameters.
Client After an Agent transmits information to the Client in event mode, the data is guaranteed to be delivered to the remote Server if you do the following: Step 1. Establish a directory (Windows or UNIX) or VSAM KSDS (z/OS) specific to that Client, with space sufficient to store information on all transactions received but not completed. The Client cannot share this store locale with an Agent, because iWave Integrator prevents this. You must be sure that the Client does not share the store locale with another Client. Step 2. Identify that directory or ddname for the VSAM KSDS in keyword STORELOCALE. When guaranteed delivery is in effect, the Client restarts any transaction that ended with a recoverable error. You indicate which transaction return values are categorized as recoverable errors by specifying recover or failure codes. You specify the retry interval the period between a failure and a retrywith keyword RETRY-INTERVAL. After a Notification Agent transfers data for a transaction to a Client, the Client reads a record from the database and tries to transfer the retrieved data to the Server. After an Event Agent transfers data to a Client, on the other hand, the Client tries to transfer the data itself to the Server. In either case, if the transmission fails because of a network problem and the Client interprets the iWave Integrator transaction value as indicating a recoverable error, the Client places the original data received from the Agent into the store-locale directory. Until an attempt to process the transaction either succeeds or fails (with no recoverable error), the Client places in the store locale any Agent-provided data that identifies a
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 51 of 276
transaction destined for the same Server. After the retry interval has elapsed, the Client retries the transactions, starting with the first that failed with a recoverable error. When you stop iWave Integrator, the Client writes into the store locale the information on any pending transactions. When you restart iWave Integrator, the Client resends the stored transactions. Unless the Client is supporting an enterprise-management application, the Client rebuilds the transaction data from a database and in this way ensures that the transmission reflects the current data. Guaranteed delivery affects all verbs, but is especially useful during Create, CreateUnique, or Update processing, so long as the transaction being processed is not part of a real-time dialogue. The reason for the exception is that during a real-time dialogue, the vendor application presents confirmation messages and lets the end-user control whether to restart a transaction. You can prevent guaranteed delivery from being used in a given transaction by specifying that no transaction return values indicate a recoverable error. It is particularly recommended that you prevent guaranteed delivery from being used for a Lock or Unlock verb. For details on transaction return values, see Chapter 5, Understanding PostProcessing Update.
Responding to Transaction Delays Keyword ESCALE specifies how the Client manages child processescalled subtasks on z/OSin response to changes in the number of requests made by an Agent. You identify the following: The minimum number of child processes to execute at one time. The maximum number of child processes to execute at one time. The number of waiting requests which, if exceeded, causes the Client to start another child process. The number of minutes that must elapse, once all requests have been handled, before iWave Integrator stops all but the minimum number of child processes.
If your vendor application is initiating more transactions than iWave Integrator can handle quickly, improve throughput by changing the setting of keyword ESCALE. In most cases, the default setting is appropriate.
Priority of Agent Requests In event mode, when the Client receives requests from an Agent and cannot process the requests immediately, the Client keeps the transactions in a waiting list that is organized in priority order and in chronological order within priority. You can set priority in two ways: By setting a priority in the request sent from the vendor application to the Agent. By setting keyword PRIORITY.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 52 of 276
The priority set when invoking the Agent takes priority over the setting of keyword PRIORITY, which by default gives a high priority to verbs Retrieve, Lock, and Unlock. The default setting ensures better response when the vendor application is invoking iWave Integrator as part of a real-time dialogue with an end-user. In most cases, the default setting is appropriate.
Poll Mode
During poll mode, the Client periodically reviews the poll criteria you specify and does so in the order in which POLL-CRITERIA keywords appear in the Client processing file. For each keyword, the Client does the following before reviewing the next: Searches the database for records that match the criteria in the keyword. Runs a transaction for each record found.
The purpose of the search is to find the IDs of primary-table records. Once the search is completed, the Client does the following for each Client object ID found: Retrieves a primary-table record that contains the Client object ID. Optionally, retrieves data from subtables that are defined in the transaction.
A poll cycle comprises the events that begin with the Clients review of the first POLLCRITERIA keyword and end with the completion of the last transaction. The value you specify as a poll interval defines how many seconds pass between the end of one poll cycle and the start of the next (Figure 15).
Figure 15 Poll Mode If a transaction ends with a recoverable error, the poll cycle continues normally. As a result of a recoverable error, however, the following occurs: The number of seconds between the end of that poll cycle and the beginning of the next is determined by the value you set for retry interval. The retry-interval value takes precedence over the poll-interval value for subsequent poll cycles until all transactions in a cycle endwhether successfully or in failurewithout a recoverable error.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 53 of 276
If you do not specify a retry interval, the poll-interval value always defines the time between the end of one poll cycle and the beginning of the next. If the poll-interval value is low, you can increase the retry interval to avoid filling up system logs during a network interruption. Alternatively, if the poll-interval value is high (24 hours, for example) you can decrease the retry interval to quickly process transactions that failed during the last poll cycle.
Setting the poll interval to a small number may degrade response time for all
WARNING applications running on the execution platform. A value between 120 and 240
gives good results in most cases.
To use poll mode, specify DETECTION:MODE:POLL in the Client processing file. Also specify the number of seconds for the poll interval and retry interval, using keywords POLL-INTERVAL and RETRY-INTERVAL. For information on tables, see Primary Tables and Subtables on page 40.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 54 of 276
5
Understanding Post-Processing Update
Post-processing update is the last stage of a transaction. This period begins when the Client starts to receive a response from the Server and continues until the Client completes writing to the local database. On an iWave Integrator that supports an enterprise-management application, iWave Integrator does not access a vendor-application database, and post-processing update is meaningful only if you have a transaction exit. For details on transaction exits, see Exits on page 74.
NOTE
During post-processing update, the Client writes the Server object ID, if any, to a database field that you identified as receiving the external object ID. Also, if freeform text fields are in the transaction data, the Client stores the date and time at which transaction data was sent to the Server; the timestamp information is written to the database field or fields that you identified as text indicator fields. The Client also takes additional steps, depending on how the Client interprets the transaction return value, which is a three-part string: #DIP-RC# #DIP-RS# #APP-RC# where each part is the value of an iWave Integrator system variable: #DIP-RC# is the iWave Integrator return code #DIP-RS# is the iWave Integrator reason code #APP-RC# is the vendor-application return code
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 55 of 276
Success Codes
If the transaction returns a value that you categorize as a success code, iWave Integrator interprets the transaction as having ended successfully. In the following example, a transaction return value is categorized as a success code if the values of #DIP-RC#, #DIP-RS#, and #APP-RC# are each 0: Success codes: 0 0 0 If you do not set success codes, the Client uses the default value: 0 0 0. You may substitute an asterisk (*) for any of the three numbers. Doing so indicates that the Client defines any value in the corresponding system variable to be consistent with success. In the following example, a transaction return value is categorized as a success if the value of #DIP-RC# is 0, regardless of the value of the other two system variables: Success codes: 0 * * You may use multiple triplets to define success codes. In the following example, a transaction return value is categorized as a success if the value of #DIP-RC# is 0 and the value of #DIP-RS# is 4 or 0, regardless of the value of #APP-RC#: Success codes: 0 0 *, 0 4 *
Failure and Recover Codes

Only if a transaction ends without success does iWave Integrator compare the transaction return value against one of two other, similar code categorizationsfailure codes or recover codes. You may specify either of the two, or neitherbut not both. After a transaction has completed unsuccessfully, the following is true: If you specify failure codes, the Client interprets the transaction as an unrecoverable failure when the transaction returns any code you identified as a failure code. The Client does not attempt to resend the transaction when the failure is unrecoverable. A typical example of an unrecoverable error is a configuration error in the processing files; until the error is corrected, the transaction will continue to fail, and so the Client does not resend the transaction. If the transaction returns any code that is not identified as a success code or a failure code, the Client interprets the transaction failure as a recoverable failure. If you specify failure codes, do not specify recover codes. In the following example, a transaction that returns with the value 4 8 1 is interpreted to be recoverable: Success codes: 0 * * Failure codes: 8 * *, 4 0 *, 4 4 * If you specify recover codes, the Client interprets the transaction as a recoverable failure when the transaction returns any code you have identified as a recover code. The Client continues to retry to the transaction when the failure is
iWave Software
Revised [03/01/07] P01-664-09
recoverable; a typical example of a recoverable failure is a temporary network outage. If the Client receives a code that is not defined as a recover code or a success code, the Client interprets the code to mean that an unrecoverable failure has occurred. If you specify recover codes, do not specify failure codes. In the following example, a transaction that returns with the value 4 8 1 is interpreted to have failed: Success codes: 0 * * Recover codes: 8 * *, 4 0 *, 4 4 * If you specify neither failure nor recover codes, iWave Integrator interprets the transaction as an unrecoverable failure if the transaction is not a success.
For details on the circumstances under which iWave Integrator reruns a recoverable transaction, see Chapter 5, Selecting a Detection Mode.
Responding to the Transaction Outcome

During the post-processing update, the Client can set the value assigned to data model fields you specify. You can instruct the Client to set the values for different data model fields (or provide different settings for the data model fields) depending on whether the transaction was successful, a recoverable failure, or an unrecoverable failure. The Client writes the new values into the local database (or uses the values for other processing). One use of this capability to set the value of data model fields would be to capture information about the success or failure of the transaction and place it into your database. When the destination Server responds to the local Client, the Server always sends a series of three error codes (the transaction return value) and error message text associated with those error codes. This information is written into the Client log. If you choose, you can capture some or all of these error codes and error message text in your database. It is recommended that you do this, because it allows you to see whether records have been transmitted successfully without looking at the logs. To capture the error codes in your database, you add one or more fields in the database to contain error numbers and one or more fields to contain the associated error message text. If the field will contain error codes, you identify the field in the Client processing file as an error num field. If the field will contain error message text, you define the field as an error text field. If you choose, you can add multiple error num fields and error text fields and then instruct the Client write to different fields depending on whether the transaction was successful, a recoverable failure, or an unrecoverable failure. The usual configuration is to add a single field to hold all error codes and a single field to hold all error messages. After you define the error num fields and error text fields, you define which data model fields are set during the post-processing update by identifying the success fields, failure fields, and recover fields. A success field is a database field or data model field to which the Client writes after a transaction succeeds. Similarly, a failure field is a database field or data model field to which the Client writes after a transaction fails with an unrecoverable error; and a recover field is a database field or data model field to which the Client writes after a transaction ends with a
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 57 of 276
recoverable error. A given success, failure, or recover field may receive a value that you specify or may be either an error num field or an error text field. You identify the data model fields that are error num fields or error text fields, then you select whether the Client writes to those fields after a success (success fields), a recoverable error (recover fields), or an unrecoverable failure (failure fields). If the transaction is successful, the Client also does the following: Assigns the transaction return value to an error num field that is also a success field (that is, the error codes are written to the error num field after a success). Assigns error text (probably a null) to an error text field that is also a success field. Assigns specified values to other success fields.
After a successful transaction, the Client always writes to the database any mapped data model fields that were returned from the Server, regardless of whether those data model fields are success fields. If the transaction fails, the Client does the following: Assigns the transaction return value to an error num field that is also a failure field (that is, the error codes are written to the error num field after an unrecoverable failure) Assigns error text to an error text field that is also a failure field. Assigns specified values to other failure fields.
Similarly, if the transaction ends with a recoverable error, the Client does the following: Assigns the transaction return value to an error num field that is also a recover field (that is, the error codes are written to the error num field after a recoverable failure). Assigns error text to an error text field that is also a recover field. Assigns specified values to other recover fields.
NOTE
If you specify recover fields or failure fields, the Client writes information to the database when a transaction ends as recoverable or as a failure. It is recommended that in this case you also specify success fields because doing so causes the Client to overwrite out-of-date information when a transaction succeeds.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 58 of 276
6
Mapping and Transforming Data
This chapter includes the following sections: iWave Integrator Data Types below Translate Field on page 63 NoClear Field on page 65
iWave Integrator Data Types

When reading data from a vendor field, iWave Integrator converts the data to iWave Integrator formata data representation independent of the format used in the vendor application. The data is contained in a data model field and is transferred to a second iWave Integrator, which reformats the data before writing to the vendor application supported by that iWave Integrator. Data model fields are of four types: Character Each field of type character contains a single string. Most vendor fields are mapped to character fields, and unmapped data model fieldsthose that have no corresponding vendor fieldsare always of type character. It is valid to map a data model field of type character to a numeric vendor field. When reading from a vendor field that contains the number 10, for example, iWave Integrator places the string 10 in the data model field; and when writing that data-model-field value to a numeric vendor field, iWave Integrator writes the number 10.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 59 of 276
Freeform Text A freeform text field contains information in a format like that of a diary. The data is composed of a series of entries, each of which contains three strings: Entry text The ID of the user who wrote the entry text A timestamp that indicates when the entry was created
Timestamp A timestamp field contains a single string that represents date and time information. A timestamp field is mapped to a vendor application date field, time field, or both. Defining a timestamp field requires that you specify a timestamp mask, which specifies how to copy date and time information between the vendor application and the data model field.
Personal-Name A personal-name field contains a series of three strings composed of a first name, middle name, and a last name and suffix. Any of the strings may be null. A personal-name field is mapped to one, two, or three vendor fields. The purpose of this data type is to handle differences in how vendor applications store names. Among the differences: Case, as in Chris versus CHRIS Order, as in Chris Jones versus Jones, Chris Abbreviation, as in Chris Terry Jones versus Chris T. Jones Distribution across vendor fields, as when Chris and Jones are stored in a single field versus when they are stored in separate fields
Defining a personal-name field requires that you specify a personal-name mask, which indicates how to copy personal-name information between the vendor application and the data model field. iWave Integrator can place a value in a data model field in either of two ways. First, if the data model field is mapped to a vendor field when data is being retrieved, iWave Integrator places the retrieved value into the data model field. Second, iWave Integrator can assign a value to a data model field before writing data to the vendor application or after reading data from the vendor application. If the target of an assignment is a character field, the assigned value can be any of the following: The system variable #EXIT#, as described in Chapter 8, Exits. An iWave Integrator constant, as described in iWave Integrator Constants on page 150. A reference to another data model field, as described in Referencing Data Values on page 152.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 60 of 276
The target field in almost all assignments is a character field. If the target of an assignment is a timestamp, personal-name, or freeform text field, the assigned value can be a reference to a data model field of the same type. For details on assigning a value from a data model field of one type to a data model field of another, see Value Assignments across Data Types on page 145. Assigning a quoted literal is equivalent to assigning a character field. A value assignment can be conditionaldependent on another data-model-field value or can be unconditional. The following subsections give details on the data types that require a mask specification: Timestamp Fields below. Personal-Name Fields on page 62.
For an overview of freeform text, see What is Freeform Text? page 36. For freeform text-related details that are specific to an iWave Integrator, see the iWave Integrator Guides.
Timestamp Fields For date and time information, iWave Integrator must copy information between two formats: A format that is specific to a vendor application The iWave Integrator timestamp format, which allows for data transfer between iWave Integrators
iWave Integrator Timestamp Format When reviewing a log file, you may see data from a timestamp field. The iWave Integrator timestamp format is as follows: YYYYMMDDHH24MISS/gmt_offset where the characters preceding the forward slash represent local time: YYYY is the 4-digit year MM is the 2-digit month DD is the 2-digit day HH24 is the 2-digit hour, in military time MI is the 2-digit minute SS is the 2-digit second
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 61 of 276
gmt_offset can be any of the following: any of three equivalent literals0, Z, or z; such a literal is used only if your machine is in the same time zone as Greenwich, England, in a locality that supports daylight savings time ohhmm, which is the amount of time you add to or subtract from the local time to obtain Universal Coordinated Time, which is the time equivalent to Greenwich Mean Time if Greenwich, England did not observe daylight savings time. The meaning of the characters: is either plus (+) or minus (-). hh is the number of hours ranging from 00 to 12. mm is the number of minutes ranging from 00 to 59.
All time zones west of Greenwich have a positive offset, up to the international dateline; all time zones east of Greenwich have a negative offset. The offset for Eastern Standard Time is +0500; the offset for Sydney, Australia is -1100.
Timestamp Masks To determine how to copy date and time information between a vendor field and a timestamp field, iWave Integrator uses a timestamp mask.
CAUTION iWave Integrator requires a specific mask value and you use a different mask
value, then application results will be unpredictable. For details on timestamp fields, see Timestamp Masks on page 155.
The timestamp mask may have application-specific requirements. If the particular
Personal-Name Fields
iWave Integrator provides a syntax for transferring personal-name data, which includes a first name, middle name, and a combination of last name and suffix, and any of those three elements may be null. You can use this syntax to transfer and in some ways to modify a series of up to three strings. In relation to personal-name data, iWave Integrator must copy information between two formats: A format used by a vendor application The iWave Integrator personal-name format, which allows for data transfer between iWave Integrators
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 62 of 276
iWave Integrator Personal-Name Format When reviewing a log file, you may see data in iWave Integrator personal-name format. The data is composed of three capitalized, null-terminated strings arranged in the following order: first name or initial followed by middle name or initial followed by last name and suffix. The log would show up to three separate strings; for example: value: CHRIS value: B value: JONES ESQ
Personal-Name Masks To determine how to copy personal-name data between a vendor field and a data model field, iWave Integrator uses a personal-name mask. For details, see Personal-Name Masks on page 160.
Translate Field
A mechanism called translate field performs a data conversion both before a data model field is sent from an iWave Integrator and after a data model field is received on an iWave Integrator. The purpose of the conversion is to be sure that information is meaningful on both Client and Server. You also use Translate Field for the following reasons: To specify a default value to write into a required vendor field. To make possible a scenario in which a local Client sends a valuefor example, a model numberto the remote Server, which does the following: Derives a second valuefor example, a producer namefrom the received value. Stores both values in the database.
You often use keyword TRANSLATE-FIELD to change the case of data; for example, OPEN to Open. You specify a pairing of vendor-field values (like OPEN and CLOSED) with data modelfield values (like DMF_OPEN and DMF_CLOSED), and that pairing identifies the necessary data conversion on a given iWave Integrator. In most cases, the pairing accomplishes a pairing of a Client-side value (like OPEN) with a Server-side value (like Open). The value sent between the iWave Integratorsthe data-model-field valueis meaningful only as an intermediate value; you need not be concerned about what the value is. Translate Field takes three actions: Before a Client or Server writes a value from a data model field, Translate Field converts the value and ensures that the converted value is placed in the related database field.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 63 of 276
After an iWave Integrator reads from a vendor field, translate field converts the value and places the converted value into the related data model field. The third action of Translate Field is related to iWave Integrator search phase and is best described by example. Assume that you have set a search argument to be MY_DMF=A and that the Translate-Field for MY_DMF indicates that the database-field value related to A is a. As a result of Translate Field, the search argument used during the search is MY_DMF=a.
In general terms, the third action is as follows: Before a Client or Server searches for a record, the data-model-field value you specified is converted to a value that Translate Field identifies as the related database-field value. Search phase occurs on the Client during poll mode (the search argument is specified in one or more poll criteria); and occurs on the Server during Search processing or during the search that occurs in some circumstances during Create-Unique processing. For details on poll mode, see Poll Mode on page 53. For details on the verbs whose processing includes a search phase, see Search on page 46 and Create-Unique on page 42.
Planning for Data Conversion

Before transferring data between two iWave Integrators, analyze the requirements of your organization. If some or all values of a data model field on the source iWave Integrator are not appropriate on the destination, determine whether the field should be transferred at all and, if so, decide on an appropriate conversion. As part of your analysis, consider the meaning of the data-model-field values as understood by users of the vendor application at each iWave Integrator. In addition, consider the value restrictions that are enforced by the vendor application at the destination iWave Integrator; for example, a database field called PROBLEM_STATUS might require use of no values other than 1, 2, or 3. You can specify keyword TRANSLATE-FIELD on both iWave Integrators to make possible the transfer of a value that is independent of the value on either. If you are transferring data about a problem report, for example, and more values are valid for data model field STATUS on the Client than on the Server, your options include the following: You can refrain from moving STATUS altogether; this option is available, for example, if you decide that the values for STATUS on the Client are authoritative, while the values on the Server are useful only as part of an audit trail. You can decide that several values on the Client (for example, 1, 2, and 3) are equivalent to a single value on the Server (for example, Open); if you are transferring data in two directions, however, this option may result in lost meaning, as described later in this section. You can store any STATUS value transferred from the Client; but that storage may be possible, if at all, only after you change the rules of field validation in the vendor applicationor perhaps in the vendor-application databaseat the Server.
iWave Software
Revised [03/01/07] P01-664-09
You can write the transferred STATUS value to a database field other than the one in which the Server-side vendor application stores status information. The purpose of that database field might be to provide information on record status on the Client. Again, this option may require changes to the configuration of your vendor application.
When planning for data conversion, you must be especially thorough when data transferred in one direction may be transferred later in the other direction. For example, suppose that STATUS value 1, 2, or 3 on machine A is converted to Open on machine B, while a transfer in the opposite direction converts value Open to 1. You must analyze how best to handle the problem of lost meaning, as happens in the following case: A record with STATUS value 3 is transferred from machine A to B, where the value of STATUS is converted to OPEN The record is transferred back to machine A, where the value is converted, not to the original value 3, but to 1
If that loss of meaning is unacceptable, the best solution is to add to the number of valid database values in the vendor application that has fewer valid values.
Relation of Translate Field to Assignments The effect of Translate Field is at data access. Implications are as follows: After the Client accesses a record to begin a transaction, the effect of Translate Field precedes the effect of any assignment statement. After the Server receives a transaction, the effect of any assignment statement precedes the effect of Translate Field. After the Server reads a record during Retrieve or Search processing, the effect of Translate Field precedes the effect of any assignment statement. When post-processing update occurs on the Client, the effect of any assignment statement precedes the effect of Translate Field.
NoClear Field
You can specify that a given data model field is a no-clear fieldif null, the data model field is not written to the vendor-application database. You identify such a data model field using keyword NOCLEAR-FIELDS to avoid overwriting a database field that contains a value that you do not want to erase. You can use a no-clear field even if it contain nulls and is therefore not written. For example, you can include a NoClear Field in a relational expression, as is used to determine a conditional value. For details on relational expressions, see Relational Expressions on page 154. It is recommended that you identify all incoming freeform text fields as noclear fields. You must do this for any iWave Integrator that supports Remedy because writing a null to a field of type DIARY in that vendor application corrupts the Remedy database.
WARNING
iWave Software
Revised [03/01/07] P01-664-09
7
System Variables
This chapter describes the iWave Integrator system variables. In the following descriptions, true may be any of the following: TRUE and any of its abbreviations, not case-sensitive YES and any of its abbreviations, not case sensitive 1 (digit)
and false is anything else.
#APP-RC#
When the Client receives a response from the Server during post-processing update, system variable #APP-RC# is one part of the transaction return value, which is a series of three numbers, one separated from the next by a blank: #DIP-RC# #DIP-RS# #APP-RC# where: #DIP-RC#: is the iWave Integrator return code #DIP-RS#: is the iWave Integrator reason code #APP-RC#: is the vendor-application return code
During post-processing update, system variable #APP-RC# usually contains the return code from the vendor application supported by the remote Server; but if you define transaction exits on the remote Server with subkeyword OBSERVE-FAIL set to true and if one or more of those exits fail, #APP-RC# contains the return code from the first such exit to fail.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 66 of 276
System variable #APP-RC# is equal to 0 during the initial stage of transaction processing, when data is accessed by the Client. On the Server, the variable is used primarily as input to transaction exits of the following types: POST-VERB POST-TRAN-SUCCESS POST-TRAN-FAILURE
For details on post-processing update, see Chapter 5, Understanding Post-Processing Update.
#CLIENT-OBJECT-ID#
Before the Client sends transaction data, the following is true: System variable #CLIENT-OBJECT-ID# contains the Client object ID, which in most cases is the value of the data model fields to which keyword LOCALOBJECT-ID-FIELDS refers. If the Client supports an enterprise-management application, #CLIENT-OBJECT-ID# is null. If keyword LOCAL-OBJECT-ID-FIELDS refers to more than one data model field, the character specified by keyword FIELD-SEPARATOR separates one data model field value from the next.
On the Server, the following is true: Before the Server receives transaction data, #CLIENT-OBJECT-ID# is null. Once the Server receives transaction data, #CLIENT-OBJECT-ID# contains the Client object ID if one was sent. If the Client supports an enterprise management application, #CLIENT-OBJECT-ID# is null.
During post-processing update, #CLIENT-OBJECT-ID# contains the same value that it did before the Client sent the transaction data.
#DATE#
System variable #DATE# contains todays date in the format you specified in keyword DATE-MASK. Any differences in value among system variables #NOW#, #DATE#, and #TIME# are the result of different specifications for keywords NOW-MASK, DATEMASK, and TIMEMASK fields, respectively. In most cases, #NOW# contains both date and time, while #DATE# contains date and #TIME# contains time. On the Client, the following is true of #FIXED-NOW#, #NOW#, #DATE#, and #TIME#:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 67 of 276
At the beginning of a transaction, the variables indicate when the Client began to collect data to be transmitted. On the Server, the variables indicate when the Server received the transmission. During post-processing update, the variables indicate when the Client received data from the Server.
#DIP-RC#
When the Client receives a response from the Server during post-processing update, system variable #DIP-RC# is one part of the transaction return value, which is a series of three numbers, one separated from the next by a blank: #DIP-RC# #DIP-RS# #APP-RC# where: #DIP-RC#: is the iWave Integrator return code #DIP-RS#: is the iWave Integrator reason code #APP-RC#: is the vendor-application return code
System variable #DIP-RC# is equal to 0 during the initial stage of transaction processing, when data is accessed by the Client. On the Server, the variable is used primarily as input to transaction exits of the following types: POST-VERB POST-TRAN-SUCCESS POST-TRAN-FAILURE
For details on post-processing update, see Chapter 5, Understanding Post-Processing Update. For details on the specific values of #DIP-RC#, see the iWave Integrator Messages and Codes book.
#DIP-RS#
When the Client receives a response from the Server during post-processing update, system variable #DIP-RS# is one part of the transaction return value, which is a series of three numbers, one separated from the next by a blank: #DIP-RC# #DIP-RS# #APP-RC# where: #DIP-RC#: is the iWave Integrator return code #DIP-RS#: is the iWave Integrator reason code
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 68 of 276
#APP-RC#: is the vendor-application return code
System variable #DIP-RS# is equal to 0 during the initial stage of transaction processing, when data is accessed by the Client. On the Server, the variable is used primarily as input to transaction exits of the following types: POST-VERB POST-TRAN-SUCCESS POST-TRAN-FAILURE
For details on post-processing update, see Chapter 5, Understanding Post-Processing Update. For details on the specific values of #DIP-RS#, see the iWave Integrator Messages and Codes book.
#ERROR-TEXT#
You can use system variable #ERROR-TEXT# to reference the optional error text created by the Server and returned to the Client in the transaction response. During the Client's post-processing update phase, you can use system variable #ERROR_TEXT# during the update (database write) for any of the following: Subtable statement. When defining a subtable statement, you can use system variable #ERROR-TEXT# for defining a search criterion during the write phase (KEY and VALUE subkeyword pair) or to set the initial value for a field in a subtable (INIT and VALUE subkeyword pair), as described in keyword SUBTABLE keyword in the iWave Integrator Keyword Reference. Value for translate field. When there are discrepancies between the valid data in the vendor applications, you define the valid values for each vendor field so that iWave Integrator can translate the data. You can use the #ERRORTEXT# system variable as a valid vendor-field value. Data-model assignment. Transaction exit. You can use the #ERROR_TEXT# system variable in any Client transaction exit that can run after the transaction response is received from the Server. This does not include POST-TRAN-ABORT.
For details on post-processing update, see Chapter 5, Understanding Post-Processing Update.
#EXIT#
System variable #EXIT# invokes a customized program that assigns a value to a mapped or unmapped data model field. You specify an assignment exit when assigning a value to a data model field.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 69 of 276
Format #EXIT#, LIBRARY=library_name, PROGRAM=program_name [,MAXVLEN=maximum_value_length] [,CONTEXT=RW|R|W] [,LOG=false|true] [,PARMS=(constant[,constant...])]; where: The LIBRARY clause is required on UNIX and Windows, but is invalid on MVS. On UNIX, library_name identifies the shared objectfor example, my_lib.so that contains the function to run. An environment variable specifies the path: for HP-UX, variable SHLIB_PATH; for AIX, variable LIBPATH; for Solaris and MPRAS, variable LD_LIBRARY_PATH. On Windows NT, library_name identifies the dynamic link libraryfor example, my_lib.dllthat contains the function to run. The Windows NT system variable Path specifies the path. The PROGRAM clause is required on all operating systems. On UNIX and Windows, program_name is the function to invoke; on MVS, program_name is the program. The MAXVLEN clause indicates the maximum number of bytes in the string assigned to the data model field, including the terminating null that is characteristic of C-language strings. The default is 4096. The CONTEXT clause specifies the processing phase in which iWave Integrator invokes the exit. Setting this clause is useful only on the Client, where read and write phase occur in the same transaction. R refers to read phase. On the Client, read phase is the time between starting to retrieve data from the vendor application and transmitting data to the Server. W refers to write phase. On a Client, write phase is post-processing update: the time between receiving a response from the Server and ending all processing except for an optional transaction exit. The LOG clause specifies whether to allow the invoked program to write to the iWave Integrator log file: The PARMS clause is a list of one or more iWave Integrator constants that are evaluated and passed to library_name or program_name. As described in iWave Integrator Constants on page 150, each constant is in double quotes and may include system variables and literals, as well as references to data model fields, database fields, and keywords.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 70 of 276
Each of the clauses in variable #EXIT# must be separated from the next by a comma. Comments For details on exits and on programs provided with iWave Integrator, see Chapter 8, Exits. For details on transaction exits, see TRANSACTION-EXIT in the iWave Integrator Keyword Reference.
#FIXED-NOW#
System variable #FIXED-NOW# contains todays date in the following fixed format: YYYYMMDDHHmmSSFFFyyyUUUUUUUUohhnn where: YYYY MM DD HH mm SS FFF yyy UUUUUUUU o hh nn is the current year is the current month is the current day is the current hour using a 24 hour clock is the current minute is the current second is the current millisecond is the day of the year is the equivalent UNIX time_t in display hexadecimal format is the GMT offset modifier of LOCAL-UTC is the GMT offset hours of LOCAL-UTC is the GMT offset minutes of LOCAL-UTC
On the Client, the following is true of #FIXED-NOW#, #NOW#, #DATE#, and #TIME#: At the beginning of a transaction, the variables indicate when the Client began to collect data to be transmitted. On the Server, the variables indicate when the Server received the transmission. During post-processing update, the variables indicate when the Client received data from the Server.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 71 of 276
#NOW#
System variable #NOW# contains todays date in the format you specified in the Now Mask field. Any differences in value among system variables #NOW#, #DATE#, and #TIME# are the result of different specifications for keywords NOW-MASK, DATEMASK, and TIMEMASK, respectively. In most cases, #NOW# contains both date and time, while #DATE# contains date and #TIME# contains time. On the Client, the following is true of #FIXED-NOW#, #NOW#, #DATE#, and #TIME#: At the beginning of a transaction, the variables indicate when the Client began to collect data to be transmitted. On the Server, the variables indicate when the Server received the transmission. During post-processing update, the variables indicate when the Client received data from the Server.
#NULL#
System variable #NULL# contains a null string and can be used in iWave Integrator constants. For details on iWave Integrator constants, see iWave Integrator Constants on page 150.
#SERVER-OBJECT-ID#
Before the Client sends transaction data, system variable #SERVER-OBJECT-ID# contains the value of the database field that you identify as the external object ID field. If you do not identify a database field in this way or if the Client supports an enterprisemanagement application, #SERVER-OBJECT-ID# is null. For details on identifying a database field as the external object ID field, see keyword EXT-OBJECT-ID in the iWave Integrator Keyword Reference. When the Server receives transaction data, the value of #SERVER-OBJECT-ID# is set to the value sent from the Client. If the Server creates a new record during processing of verb Create or Create-Unique, the new value of that system variable is first available for your use during transaction exit POST-TRAN-SUCCESS or POST-TRAN-FAILURE. During post-processing update, #SERVER-OBJECT-ID# contains the value returned from the Server.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 72 of 276
#TIME#
System variable #TIME# contains the current time in the format you specified in the Time Mask field. Any differences in value among system variables #NOW#, #DATE#, and #TIME# are the result of different specifications for keywords NOW-MASK, DATEMASK, and TIMEMASK, respectively. In most cases, #NOW# contains both date and time, while #DATE# contains date and #TIME# contains time. On the Client, the following is true of #FIXED-NOW#, #NOW#, #DATE#, and #TIME#: At the beginning of a transaction, the variables indicate when the Client began to collect data to be transmitted. On the Server, the variables indicate when the Server received the transmission. During post-processing update, the variables indicate when the Client received data from the Server.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 73 of 276
8
Exits
iWave Integrator provides the following types of exits, which allow you to integrate a customized program into iWave Integrator: An assignment exit places a value in a data model field. For example, you can use an assignment exit at the beginning of a transaction to calculate a value based on a value read from the Client-side database. The calculated value is sent to the remote iWave Integrator. You also can use assignment exits to place data into an unmapped data model field, which is a data model field that has no corresponding field in the vendor application. This option is available to handle moderately complex data transformations that require a temporary placeholder. For all assignment exits, the maximum length of the assigned text is determined by the MAXVLEN parameter of the assignment statement; the command response text is truncated if it exceeds this length. When processing an assignment exit, iWave Integrator does the following: Provides a buffer into which the function writes a string that is assigned to a data model field. Ignores the functions return code.
You specify an assignment exit when assigning a value to a data model field; for details, see #ERROR-TEXT# on page 69. A transaction exit changes processing behavior at a specified point before, during, or after a transaction. For example, you could use a transaction exit to send e-mail to several managers whenever a new problem report is available in a given vendor application. When iWave Integrator processes a transaction exit, iWave Integrator provides no buffer to store an assignment string. Also, if you set up Server-side
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 74 of 276
transaction exits with subkeyword OBSERVE-FAIL set to true and if one or more of the exits fail, system variable #APP-RC# contains the return code from the first such exit to fail. For details on transaction exits, see TRANSACTION-EXIT in the iWave Integrator Keyword Reference. iWave Integrator provides several functions for use in exits, and you can code your own. The custom functions used in assignment exits and transaction exits are built the same way, and a given function can be written to be used for either type of exit. Test your exits carefully before using them in your production environment: if a custom function fails during either type of exit, the iWave Integrator also fails. For details on how to write an exit function, see Writing Functions for Use in Exits on page 111.
Exits Supplied with iWave Integrator

This section provides an overview of the exit functions provided with iWave Integrator.
UNIX and Windows Exits On UNIX and Windows NT, exit functions are in a library, and the function you invoke is said to be exported by that library. On UNIX, the library is a shared objectfor example, libPNTpexa.sothat contains the function to run. An environment variable specifies the path: for HPUX, variable SHLIB_PATH; for AIX, variable LIBPATH; for Solaris and MP-RAS, variable LD_LIBRARY_PATH. On Windows, the library is the dynamic link libraryfor example, libPNTpexa.dllthat contains the function to run. Windows NT system variable Path specifies the path.
On UNIX and Windows, the exported function is called the program name. Table 1 lists the exit functions provided on UNIX or Windows. In each case, you invoke the function with a parameter that specifies one of several exit functions to execute. Exit functions in the following libraries generate detailed messages in the adapter log when the following adapter log option is in effect: EXIT libPNTpexa.so (UNIX), libPNTpexa.dll (Windows) timeexit.so (UNIX), timeexit.dll (Windows)
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 75 of 276
Table 1 Exit Functions Provided on UNIX or Windows Exit Function pntpexif (lpad) Library On UNIX, libPNTpexa.so;on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so;on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so;on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll See Library on page 98 Purpose Returns a string with leftmost padding added Returns a string with leftmost whitespace removed Runs an operating system command How Used Assignment Exit Only Page 79
pntpexif (ltrim)
Assignment Exit Only
79
pntpexif (pntexec)
Assignment or Transaction Exit
80
pntpexif (pntfrag)
Returns a word or phrase from a string Returns the offset of a substring in a string Returns the integer at the beginning of a string Returns the result of a calculation
81
pntpexif (pntindex)
84
pntpexif (pntinteger)
85
pntpexif (pntmath)
86
pntsqlif (pntsqlcmd)
Returns the value of a column in a SQL database; specifically, the first column of the last row of the last result set that the function receives Returns a substring from a string
95
pntpexif (pntsubst)
On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll
100
pntpexif (randint)
Returns a random number.
101
pntpexif (right)
Returns the rightmost n characters of a string.
102
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 76 of 276
Exit Function pntpexif (rpad)
Library On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, timeexit.so; on Windows NT, timeexit.dll On UNIX, timeexit.so; on Windows NT, timeexit.dll On UNIX, timeexit.so; on Windows NT, timeexit.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll On UNIX, libPNTpexa.so; on Windows NT, libPNTpexa.dll
Purpose Returns a string with rightmost padding added Returns characters with rightmost whitespace removed Converts characters to all lower-case letters. Converts characters to all upper-case letters. Converts a formatted timestamp to a different format Returns the difference between two timestamps in number of seconds Returns a formatted timestamp Returns the nth substring from a string Converts selected characters in a string
How Used Assignment Exit Only
Page 102
pntpexif (rtrim)
103
pntpexif (strlwr)
104
pntpexif (strupr)
105
timeexif (timeconv)
Assigment Exit Only
105
timeexif (timediff)
106
timeexif (timestr) pntpexif (tokenize)
108
109
pntpexif (tranchr)
110
z/OS Exits On z/OS, when you specify system variable #EXIT# or a transaction exit, the following is true: A PROGRAM clause contains the name of the load module in which is found the exit function to be executed. The first entry in the PARMS clause is the name of the exit function, and each subsequent entry in the PARMS clause is a parameter of that exit function.
The exit function pntinteger, for example, accepts a string and returns an integer, if any, which appears at the beginning of the string. If the value of data model field MY_VALUE is 25.30, the following expression assigns 25 to the data model field that you are defining:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 77 of 276
#EXIT#,PROGRAM=PNTPEXA, PARMS=("pntinteger","@A_VALUE@") Table 2 lists the exit functions provided on z/OS. Table 2 Exit Functions Provided on z/OS Exit Function lpad ltrim pntfrag pntindex Library PNTPEXA PNTPEXA PNTPEXA PNTPEXA Purpose Returns a string with leftmost padding added Returns a string with leftmost whitespace removed Returns a word or phrase from a string Returns the numeric, zero based position of a substring in a string. Returns the integer at the beginning of a string Returns the result of a calculation Returns the response from an z/OS system command Executes one or more SQL statements in an available database management system. In an assignment exit, pntsqlcmd returns the value of a column in a DB2 database; specifically, the first column of the last row of the last result set that the exit function receives. Returns a substring from a string Writes a string to the z/OS system console Returns the right-most n characters of a string. Returns a string with rightmost padding added Returns a string with rightmost whitespace removed Returns the nth substring from a string How Used Assignment Exit Only Assignment Exit Only Assignment Exit Only Assignment Exit Only Page 79 79 81 84
pntinteger pntmath pntmcs
PNTPEXA PNTPEXA PNTPEXA
Assignment Exit Only Assignment Exit Only Assignment Exit Only
85 86 86
pntsqlcmd
PNTSQLIF
95
pntsubst
PNTPEXA
100
pntwto right rpad rtrim
PNTPEXA PNTPEXA PNTPEXA PNTPEXA
Transaction Exit Only Assignment Exit Only Assignment Exit Only Assignment Exit Only
100 102 102 103
tokenize
PNTPEXA
109
The following sections describe the supplied exit functions in alphabetical order.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 78 of 276
lpad
The exit function lpad is used solely in an assignment exit and returns a superstring of a string to which a pad character has been prefixed to the leftmost end. To use lpad, provide the following parameters to function pntpexif: ".pad", "the_string",pad_character,new_length where: the_string is the string to which padding is to be prepended at the lefttmost end. pad_character is the single character to be prepended to the leftmost end of the_string new_length is the length of the resulting assigned value
The function returns an empty string if an error occursfor example, if the length of resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns ----four to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("lpad",four,"-",8) On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("lpad",four,"-",8) On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("lpad",four,"-",8)
ltrim
The exit function ltrim is used solely in an assignment exit and returns a substring of a string from which the leftmost contiguous whitespace (space, tab, carriage return, newline) is removed. To use ltrim, provide the following parameters to function pntpexif: "ltrim", "the_string"
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 79 of 276
where: the_string is the string from which the leftmost contiguous whitespace (space, tab, carriage return, newline) is to be removed.
The function returns an empty string if an error occursfor example, if the length of resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns four to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("ltrim"," four") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("ltrim"," four") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("ltrim"," four")
pntexec
The exit function pntexec runs a command or script in the operating system. When run in an assignment exit, pntexec returns the first line directed to the standard output; when run in a transaction exit, pntexec returns the return or exit value of the command or script. To use pntexec, provide the following parameters to exit function pntpexif: "pntexec", "os_command"[, "command_parameter"...] where: os_command on UNIX is a script, an executable, or an operating-system command; and on Windows NT is a command file, an executable, or an operating-system command. os_command may include path information, as appropriate to the operating system; otherwise, the operating system searches the directories specified by PATH (on UNIX) or path (on Windows). command_parameter is provided to the command or script, and you may specify multiple parameters or none.
The following returns the first line that my_exec directs to the standard output: On UNIX: #EXIT#,LIBRARY=libPNTpexa.so,
iWave Software
Revised [03/01/07] P01-664-09
PROGRAM=pntpexif, PARMS=("pntexec","my_exec","my_command_parameter") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntexec","my_exec","my_command_parameter")
pntexif
pntexif is a function on UNIX and Windows NT; for details, review the entry for each of its exit functionspntexec, pntfrag, pntindex, pntinteger, pntmath, pntsubst, and right.
pntfrag
The exit function pntfrag is used solely in an assignment exit and returns a substring of the string you provide, as shown in a series of examples in this section. To use pntfrag, provide the following parameters to function pntpexif: "pntfrag", "the_string", "max_segment_length", "seg_no" where: the_string is the string from which to derive a substring. max_segment_length is the maximum number of characters in a given segment (subpart) of the string. max_segment_length may be a list of lengths, one separated from the next by a forward slash (/). In this case, each item identifies the maximum number of characters in the associated segmentthe first item is the maximum in the first segment, the second item is the maximum in the second segment, and so on. If the parameters are such that additional characters are present in the_string beyond the number of items in the list, the last item identifies the maximum number of characters in each additional segment. seg_no is the number of the segment at which the substring begins.
pntfrag is used in a situation like the following: Fields in a mainframe vendor application like Tivoli Information Management are limited by screen-width limitations A vendor-application developer emulates a multi-line field by defining several fields on the screen like the following, each associated with a different database field:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 81 of 276
Description:
______________ ______________ ______________
iWave Integrator prepares the data from the three database fields for storage in a remote vendor application by combining the three mapped data model fields into a single unmapped data model field as follows: DESCRIPTION="@LINE_ONE@ @LINE_TWO@ @LINE_THREE@" To process a transaction that copies data in the opposite direction, from the remote iWave Integrator to the local iWave Integrator, iWave Integrator uses the function pntfrag to divide description data into substrings.
Leading blanks in a segment are ignored, and the character count begins at the first nonblank character. A segment never includes a trailing blank. If a substring cannot be identified, the function returns an empty string. If the parameters values are such that segment segment_no would include whole words and a fraction of a subsequent word, the segment includes only the whole words, and the subsequent segment begins at the start of the word not associated with segment segment_no. The following, for example, assigns 456 to a data model field: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag"," 456 pickup stix","8","1") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","8","1") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","8","1")
The following assigns pickup to the data model field: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag"," 456 pickup stix","8","2") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","8","2") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","8","2")
As noted earlier, max_segment_length may be a list. The following, for example, assigns 456 pickup to the data model field:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 82 of 276
On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","1") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","1") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","1")
The following assigns stix on to the data model field: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","2") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","2") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","2")
The following assigns one day to the data model field: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","3") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","3") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag", "456 pickup stix on one day only","12/8","3")
iWave Software
Revised [03/01/07] P01-664-09
If the parameters values are such that segment segment_no includes only part of a word, the segment is that part, and the subsequent segment begins with the next character. The following assigns 45 to the data model field: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag"," 456 pickup stix","2","1") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","2","1")
On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","2","1") The following assigns 6 to the data model field: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntfrag"," 456 pickup stix","2","2") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","2","2") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntfrag"," 456 pickup stix","2","2")
pntindex
The exit function pntindex is used solely in an assignment exit and returns the numeric position of a substring in a string. The position of the first character in the string is zero. To use pntindex, provide the following parameters to function pntpexif: "pntindex", "the_string", "the_substring" where: the_string is the string that contains the substring the_substring is the substring whose position is of interest
If the_substring is not in the_string, the function returns an empty string. The following assigns 4 to the data model field:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 84 of 276
On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntindex","0123four","four") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntindex","0123four","four") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntindex","0123four","four")
pntinteger
The exit function pntinteger is used solely in an assignment exit and returns the long integer, if any, at the start of a string, or returns a null. To use pntinteger, provide the following parameters to function pntpexif: "pntinteger", "the_string" where: the_string is the string that contains the long integer and may include a leading plus or minus sign. The range of long integers is -2,147,483,647 to 2,147,483,647. When the string contains a value less than the minimum, the minimum value is returned; when the string contains a value greater than the maximum, the maximum value is returned.
iWave Integrator retains a leading minus sign when returning a value, but ignores a leading plus sign. The following assigns 25, for example:
On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntinteger","+25.30") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntinteger","+25.30") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntinteger","+25.30")
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 85 of 276
pntmath
The exit function pntmath is used solely in an assignment exit and returns the result of adding, subtracting, or multiplying two long integers. To use pntmath, provide the following parameters to function pntpexif: "pntmath", "1st_long", "the_operator", "2nd_long" where: 1st_long is a long integer the_operator is + (for addition), - (for subtraction), or * (for multiplication) 2nd_long is a long integer
The range of long integers (including the result) is -2,147,483,647 to 2,147,483,647. The result of overflow is either -2,147,483,647 or 2,147,483,647. If either 1st_long or 2nd_long contains a non-integer character other than a leading plus or minus sign, the function returns a null string; otherwise, the function returns a string that contains an integer and may begin with a minus sign. The following assigns -100, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntmath","20","*","-5") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntmath","20","*","-5") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntmath","20","*","-5")
pntmcs (z/OS Extended MCS Console Assignment Exit)

The exit function pntmcs is an assignment exit that issues a system command in an Extended MCS Console and places the commands response text into a data model field. This exit lets you issue z/OS system commands from a UNIX machine and display the command responses on the UNIX machines screen.
NOTE most likely scenario.
You are not limited to issuing the z/OS system commands from UNIX, but that is the
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 86 of 276
Exit function pntmcs is used only in a Server processing file on z/OS. To run system commands with pntmcs, you must configure an Extended MCS Console in the iWave Director configuration file (ddname SDMCONFG in the iWave Director JCL).
CAUTION Ensure that all libraries listed in the STEPLIB statement of the JCL that starts
iWave Director are APF-authorized. See the iWave Integrator Planning and Installation Guide for more information. Provide the following parameters for pntmcs to function PNTPEXA: "pntmcs", "system_command" where system_command is the text of a supported command on z/OS. All z/OS, JES, VTAM, IMS, and DB2 commands are supported. If the command response spans multiple lines, lines are terminated with an EBCDIC line feed (0x25). The maximum length is determined by the MAXVLEN parameter of the assignment statement; the command response text is truncated if it exceeds this length.
Sample Scenario Suppose that you want to use an HP OpenView IT/Operations command window to issue an z/OS system command and then view the command response text in the HP OpenView IT/Operations command window. You can issue the system command using the Universal Notification or Universal Agent (Figure 16).
Figure 16 Issuing an z/OS Command in the Extended MCS Console Before you can issue any system commands from the Universal Agent or Universal Agent, you must configure 1) the iWave Director on z/OS, 2) the local Client, and 3) the remote Server. After you set up the configuration, the procedure works as follows: 1. The HP OpenView IT/Operations command window invokes the Universal Agent. The following sample Universal Agent command sends the system command d a,l in the -a parameter: notfagt -r HOST1,21928 -p OS390-CONSOLE/CREATE -c coid -a "command=d a,l" -b response_text
iWave Software
Revised [03/01/07] P01-664-09
-O /dev/null 2. The Agent request travels to the Client, which in turn sends the request to the Server. 3. On the Server side, exit function pntmcs sends the system command to iWave Director, which issues the command in the Extended MCS Console and pntmcs receives the command response from iWave Director. 4. Exit function pntmcs assigns the command response text to a data model field that is returned by the Server (as specified by keyword CREATE-RETURN-FIELDS). 5. The Client sends all data model fields named by CREATE-RETURN-FIELDS to the originating Agent. 6. The originating Agent displays the command response text in the HP OpenView IT/Operations command window. The Agent displays the name of the vendor field that contains the response followed by the text returned from the system command (Figure 17). response_text: IEE114I 15.06.23 2001.052 ACTIVITY 974 JOBS M/S TS USERS SYSAS INITS 00013 00059 00031 00028 00036 VTAM VTAM VTAM NSW S DLF RACF RACF RACF NSW S INETD5 AOPD STEP1 BPXOINIT NSW AO VLF RRS RRS RRS NSW S APPC ASCH ASCH ASCH NSW S CSF IRLMPROC IRLMPROC NSW S IMS0IRLM IMS1IRLM IMS1IRLM EXECIRLM NSW S IMS2IRLM LLA LLA LLA NSW S TSO SDSF SDSF SDSF NSW S TCPIP XDCCDF XDCCDF XDCCDF OWT S PORTMAP FTPD1 STEP1 FTPD OWT AO IMWEBSRV CICSD CICSD CICS NSW S SWSS RMF RMF IEFPROC NSW S INFOSYS . . . AI38BM1 OWT AI38CCF OWT AI38SJT OWT Figure 17 Sample Response from Console Command The following sections provide details for configuring the Extended MCS Console in iWave Director, setting up an unrestricted configuration that allows the Agent to send any system command, and setting up a restricted configuration that allows the Agent to send to send only the commands you explicitly allow in the Server processing file.
ACTIVE/MAX VTAM 00031/00060 DLF DLF STEP1 BPXOINIT VLF VLF APPC APPC CSF IMS0IRLM EXECIRLM IMS2IRLM EXECIRLM TSO STEP1 TCPIP TCPIP PORTMAP PMAP IMWEBSRV WEBSRV SWSS SWSS INFOSYS BLXSPCAS
OAS 00029 NSW S OWT AO NSW S NSW S NSW S NSW S NSW S OWT S NSW SO OWT SO IN SO NSW SO NSW S
iWave Director Configuration Exit function pntmcs issues system commands within a single Extended MCS Console. Based on settings in the configuration file (ddname SDMCONFG), iWave Director creates the console on startup and deactivates the console during shutdown. iWave Director also issues all system commands and receives all command responses.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 88 of 276
The iWave Director configuration file has three console keys in the Base section: ExtendedMCSConsoleName, ExtendedMCSConsoleKey, and ExtendedMCSConsoleMaxWait (Figure 18). [Base] : ExtendedMCSConsoleName=IWIEMCS1 ExtendedMCSConsoleKey=MCSGRP15 ExtendedMCSConsoleMaxWait=2 : Figure 18 Settings for the Extended MCS Console You must specify a setting for ExtendedMCSConsoleName if you want iWave Director to start an Extended MCS Console. ExtendedMCSConsoleKey and ExtendedMCSConsoleMaxWait have default settings, so you can omit them if you choose. See Appendix F, iWave Director Configuration File for more information about these settings. iWave Director processes one system command at a time and all incoming transactions wait until the current commands processing ends. This wait is typically very shortless than a second. You can set the maximum wait time with the ExtendedMCSConsoleMaxWait key.
CAUTION Avoid system commands that require human intervention. Failure to do so can
delay transaction processing.
Set the scaling for the Server to 1. All command processing occurs sequentially, so increasing the scaling for the Server uses additional system resources without increasing throughput.
Example 1: Unrestricted System Commands

This section shows sample settings for the Agent, Client, and Server that allow the Universal Agent to send any system command. For this unrestricted configuration, the system command to be issued is included in the command that launches the Agent. Be sure to configure the Extended MCS Console as shown in iWave Director
NOTE Configuration on page 88.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 89 of 276
Agent Settings for Unrestricted Commands The following sample Universal Agent command sends the z/OS command d a,l in the command vendor field and displays the contents of the response_text vendor field at stdout (Figure 19). notfagt r p c a b O
HOST1,21928 OS390-CONSOLE/CREATE coid "command=d a,l" response_text /dev/null
Figure 19 Command to Launch Agent: Unrestricted Commands In this example, the parameters to the Universal Agent (notfagt) are as follows: -r HOST1, 21298This parameter identifies the host name and port number where the Client is listening for communications from the Agent. -p OS390-CONSOLE/CREATEThis parameter identifies the name of the section to process. In this example, the Object Class is OS390-CONSOLE and the Verb is Create. There is no Verb Qualifier. -c coidThis parameter identifies the Client object ID, which is required for the Universal Agent (notfagt). Typically, the Client uses the Client object ID to retrieve records, but in this example, the only purpose of the Client object ID is to allow the transaction to be accepted by the Client. As a result, the object ID is arbitrary: the example setting shown here matches the Client object ID setting used in many of the iWave Integrator samples. If you are using the Universal Agent (uniagt), omit the -c parameter. -a 'command=d a,l'This parameter sends a vendor field and its value to the Client. In this example, the value d a,l is the system command that exit function pntmcs will execute. -b response_textWhen the Client responds to the Agent, the Client can send data (vendor fields and their values) as part of the response. In the examples shown here, the Client sends data in the response (because AGENTRESPONSE-IMMEDIATE is set to NO in the Client processing file). The b parameter identifies vendor fields whose values the Agent sends to stdout (which is typically the screen) or to the Agent log, depending on the setting of the -O parameter. -O /dev/nullThis is the Agent log setting. The setting /dev/null means that there is no Agent log specified, so the vendor fields identified by the b parameter will be written to stdout.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 90 of 276
Client Settings for Unrestricted Commands The Client can reside on any platform; in these examples, the iWave Integrator Universal Interface Client and Server both reside on z/OS. The Client mapping file has one Object Class section, OS390-CONSOLE, and one Verb section, CREATE. There are no Verb Qualifier sections for this unrestricted configuration. The two data model fields are COMMAND and RESPONSE (Figure 20). Begin Base; Client mapping file Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/; COMMAND=%command%; RESPONSE=%response_text%; End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base; Figure 20 Client Mapping File: Unrestricted Commands The Client processing file contains the same Object Class and Verb sections as the Client mapping file. The setting AGENT-RESPONSE-IMMEDIATE:NO is required so that the Client will send the command response to the Agent (Figure 21). Begin Base; Client processing file : Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/;
This required setting in the Verb section causes the Client to send the command response back to the Agent.
AGENT-RESPONSE-IMMEDIATE:NO; End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base;
Figure 21 Client Processing File: Unrestricted Commands The COMMAND and RESPONSE data model fields cannot be timestamp, personal name, or freeform text fields.
Server Settings for Unrestricted Commands The Server must reside on z/OS. The Server mapping file is identical to the Client mapping file (Figure 22).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 91 of 276
Begin Base; Client mapping file Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/; COMMAND=%command%; RESPONSE=%response_text%; End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base; Figure 22 Server Mapping File: Unrestricted Commands In the Server processing file, the assignment exit pntmcs creates the value for the RESPONSE data model field. Notice that the value of the COMMAND data model field which is the system command from the Agent, in this unrestricted exampleis the parameter for pntmcs (Figure 23).
Begin Base; Server processing file : Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/;
The Server returns the RESPONSE data model field, which contains the command response, to the Client.
CREATE-RETURN-FIELDS:(RESPONSE);
The command response from pntmcs is mapped to the RESPONSE data model field.
RESPONSE=#EXIT# PROGRAM=PNTPEXA MAXVLEN=24576 CONTEXT=W LOG=1 PARMS=("pntmcs","@COMMMAND@");
End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base; Figure 23 Server Processing File: Unrestricted Commands After pntmcs assigns the command response to the RESPONSE data model field, the Server returns the RESPONSE data model field to the Client as a result of the CREATERETURN-FIELDS setting.
Example 2: Restricted System Commands

The sample settings for the Agent, Client, and Server shown in this section restrict the system commands that can be requested by the Universal Agent. Most of the settings are the same as those for an unrestricted configuration. To restrict the commands that can be issued, you set up a Verb Qualifier section for each command you want to allow. The following configuration allows two commands: d a and d a,l, which are defined in the Server processing file.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 92 of 276
NOTE Configuration on page 88.
Be sure to configure the Extended MCS Console as shown in iWave Director
Agent Settings for Restricted Commands If you want to restrict the commands sent from the Agent, explicitly identify the commands you want to allow in the Server processing file. The command that launches the Agent contains the name of the Verb Qualifier section that contains the system command to be issued (Figure 24). notfagt r HOST1,21928
Instead of sending the text of the system command, send the Verb Qualifier section.
p OS390-CONSOLE/CREATE/D-A-L c a b O coid "command=d a,l" response_text /dev/null
Figure 24 Command to Launch Agent: Restricted Commands Notice that the actual text of the command is not part of the Agent transaction when you use this configuration that restricts the commands that can be issued. The Verb Qualifier section D-A-L in the Server processing file contains the command, d a,l.
Client Settings for Restricted Commands The Client mapping file for a restricted configuration is similar to the Client mapping file for an unrestricted configuration except that there are Verb Qualifier sections for each command allowed (Figure 25). Begin Base; mapping file Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/; COMMAND=%command%; RESPONSE=%response_text%; Begin Verb Qualifier /D-A/; End Verb Qualifier; /D-A/ Begin Verb Qualifier /D-A-L/; End Verb Qualifier; /D-A-L/ End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base;
In a restrictedcommand configuration, each command that the Agent can issue has its own Verb Qualifier section.
Figure 25 Client Mapping File: Restricted Commands
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 93 of 276
The Client processing file contains the same Verb Qualifier sections and the AGENTRESPONSE-IMMEDIATE setting in each Verb Qualifier section (Figure 26).
Begin Base; processing file : Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/; Begin Verb Qualifier /D-A/; AGENT-RESPONSE-IMMEDIATE:NO; End Verb Qualifier; /D-A/ Begin Verb Qualifier /D-A-L/; AGENT-RESPONSE-IMMEDIATE:NO; End Verb Qualifier; /D-A-L/ End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base; Figure 26 Client Processing File: Restricted Commands
Server Settings for Restricted Commands The Server mapping file is identical to the Client mapping file (Figure 27). Begin Base; mapping file, identical to client mapping file Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/; COMMAND=%command%; RESPONSE=%response_text%; Begin Verb Qualifier /D-A/; End Verb Qualifier; /D-A/ Begin Verb Qualifier /D-A-L/; End Verb Qualifier; /D-A-L/ End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base; Figure 27 Server Mapping File: Restricted Commands
In the Server processing file, each Verb Qualifier section contains the settings for each allowed system command (Figure 28).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 94 of 276
Begin Base; processing file : Begin Object Class /OS390-CONSOLE/; Begin Verb /CREATE/; Begin Verb Qualifier /D-A/; CREATE-RETURN-FIELDS:(RESPONSE); RESPONSE=#EXIT# PROGRAM=PNTPEXA MAXVLEN=8192 CONTEXT=W LOG=1 PARMS=("pntmcs","d a); End Verb Qualifier; /D-A/ Begin Verb Qualifier /D-A-L/; CREATE-RETURN-FIELDS:(RESPONSE); RESPONSE=#EXIT# PROGRAM=PNTPEXA MAXVLEN=24576 CONTEXT=W LOG=1 PARMS=("pntmcs","d a,l); End Verb Qualifier; /D-A-L/ End Verb; /CREATE/ End Object Class; /OS390-CONSOLE/ End Base; Figure 28 Server Processing File: Restricted Commands Notice that the text of the system command is explicitly defined in the parameter for exit function pntmcs. As a result, the Agent sends the Verb Qualifier section but not the actual command text.
One system command (d a) is in Verb Qualifier section D-A in the Server processing file.
Another system command (d a,l) is in Verb Qualifier section D-A-L in the Server processing file.
pntsqlcmd
The exit function pntsqlcmd executes one or more SQL statements in an available database management system (DBMS), even if the iWave Integrator does not interact directly with that DBMS. When run in an assignment exit, pntsqlcmd returns the value of a column in a SQL database; specifically, the first column of the last row of the last result set that the function receives. When used in a transaction exit, pntsqlcmd returns 0 for success, and one of the following for failure: -1: unable to initialize the environment, probably as a result of missing resourcesa memory problem, perhapsor a flawed installation of ODBC or (in the case of DB2) the Call Level Interface -2: unable to log into the database -3: unable to change to a database

iWave Software
Revised [03/01/07] P01-664-09
-4: interaction with the database management system failed, perhaps because of a SQL syntax error, a record in use, or some other cause for a SQL error -5: either an internal iWave Integrator error or MAXVLEN in system variable #EXIT# is incorrectly set to 0 -6: MAXVLEN in system variable #EXIT# is set too low -7: Internal iWave Integrator error -8: Internal iWave Integrator error -9: A failure interacting with the database for any of several reasons, including a disconnection, a network failure, a machine failure, a faulty database, or an internal iWave Integrator error -10: out of memory -65536: not enough arguments supplied in the exit call -65537: the first argumentthe function nameis incorrect
To use pntsqlcmd, provide the following parameters to function pntsqlif: "pntsqlcmd", "user_id", "password", "database", "sql_command", "reserved", "connection", [database_server] where: user_ID is the user ID that the function uses to log into the local database management system. Type the following if you wish to assign the local user ID that you specified with keyword LOCAL-USERID: #LOCAL-USERID# password is the password that the function uses when logging in to the local database management system. Type the following if you wish to assign the password that you specified with keyword LOCAL-PASSWORD: #LOCAL-PASSWORD# database is the name of the database to access. Type the following if you wish to assign the database name that you specified with keyword DB-NAME: #DB-NAME# sql_command is the SQL statement to process. To process multiple SQL statements, separate one from the next with a semicolon (;). Place the parameter in double quotes (") regardless of the number of included statements. reserved was formerly a numeric string that defined the level of tracing information available in a log file, and is now reserved for future use. Use Adapter LogOptions of ADET and ADETF to control tracing. connection is a numeric string that identifies how the exit connects to the database. connection can be any of the following:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 96 of 276
0 means to use the existing connection that iWave Integrator has with the vendor-application database. This option is available only when the iWave Integrator is directly supporting ODBC, Oracle, or (on UNIX) DB2. 1 means to use a separate connection that is initialized and terminated by pntsqlcmd. This option is required if the iWave Integrator is directly supporting DB2 on z/OS.
database_server is the database server that the function accesses. Type the following if you wish to assign the database server name that you specified with keyword DB-SERVER-NAME: #DB-SERVER-NAME# database_server is optional. Valid values depend on the database management system being accessed: For DB2, the parameter represents the name of the ODBC data source to which iWave Integrator connects. The data source is the location name defined in table SYSIBM.LOCATIONS. The default value is the default ODBC data source. For ODBC, the parameter represents the name of the ODBC data source to which iWave Integrator connects. The default value is the default ODBC data source. For Oracle, the parameter must match an entry from TNSNAMES.ORA (on UNIX) or SQLNET.INI (on Windows NT). The default value is the content of the Oracle environment variable ORACLE_SID (on UNIX) or LOCAL (on Windows NT).
Commit and Rollback A unit of work is a period in which database changes are tentative, pending a commit orwhere supporteda rollback. During write phase on the Server, the iWave Integrator unit of work begins after the Server receives data model fields and ends just before execution of any POST-TRAN transaction exits; those exits are of type POST-TRANABORT, POST-TRAN-FAILURE, POST-TRANRECOVER, or POST-TRAN-SUCCESS. During write phase on the Client, the iWave Integrator unit of work begins immediately after the Client receives data model fields and ends after execution of any POSTUPDATE transaction exits. On an iWave Integrator that supports ODBC or (in the case of DB2) the Call Level Interface, you may use any of the following statements, but only when invoking a transaction exit of type PRE-TRAN or POST-TRAN: ODBC_AUTOCOMMIT_ON; ODBC_AUTOCOMMIT_ON means that each SQL command is immediately committed. When iWave Integrator is not within its own unit of work, ODBC_AUTOCOMMIT_ON is the default. Therefore, when iWave Integrator is
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 97 of 276
running a PRE-TRAN or POST-TRAN exit, each SQL command that ends successfully is immediately committed. ODBC_AUTOCOMMIT_OFF; ODBC_AUTOCOMMIT_OFF means a programs changes to the database are rolled back if they are not committed explicitly. When ODBC_AUTOCOMMIT_ON is in effect, execution of ODBC_AUTOCOMMIT_OFF begins a unit of work. When iWave Integrator is within its own unit of work, ODBC_AUTOCOMMIT_OFF is in effect and iWave Integrator commits changes only after writing the records in your transaction. During a pntsqlcmd exit of type PRE-TRAN, if you specify ODBC_AUTOCOMMIT_OFF before changing the database and do nothing to end the unit of work, those changes are committed by iWave Integrator after iWave Integrator writes the records in your transaction. You can specify ODBC_AUTOCOMMIT_OFF in a pntsqlcmd exit of type POSTTRAN (for example, POST-TRAN-SUCCESS), and then commit changes in the last such exit. In this case, however, it is especially important that the last database write be followed by a commit or rollback, because if you specify ODBC_AUTOCOMMIT_OFF and fail to end the unit of work, iWave Integrator ends the unit of work during a subsequent transaction or when the iWave Integrator stops. Also, it is recommended that you specify ODBC_TRANSACTION_ROLLBACK early in a pntsqlcmd exit of type PRETRAN to prevent the iWave Integrator from committing changes made by a POST-TRAN exit that failed during an earlier transaction.
WARNING
If the underlying database management system does not support rollbacks, each SQL command is immediately committed even if you specify ODBC_AUTOCOMMIT_OFF, and this command has no effect. ODBC_TRANSACTION_COMMIT; ODBC_TRANSACTION_COMMIT commits user changes to the database. ODBC_TRANSACTION_ROLLBACK; ODBC_TRANSATION_ROLLBACK rolls back user changes to the database, if rollback is supported. Library On z/OS, function pntsqlcmd is in program PNTSQLIF and can access DB2. On other platforms, the library for function pntsqlif (which contains exit function pntsqlcmd) is as follows:
iWave Software
Revised [03/01/07] P01-664-09
For DB2 on UNIX: libPNTdb2.so For ODBC, which is available only on Windows NT: libPNTodbc.dll
For Oracle: On UNIX: libPNTora.so On Windows: libPNTora.dll
Examples Following is an example use of pntsqlcmd in a transaction exit on UNIX: TRANSACTION-EXIT:LIBRARY=libPNTsyb.so,PROGRAM=pntsqlif, CONTEXT=PRE-POLL,PARMS=("pntsqlcmd","#LOCAL-USERID#", "#LOCAL-PASSWORD#","#DB-NAME#","update lock_table set " "poll_flag=X where getdate() > dateadd(ss,15, lock_ts) " "AND (update_status != Y OR update_status=NULL)", "1", "1", "#DB-SERVER-NAME#"); Following is an example use of pntsqlcmd in an assignment exit on UNIX: #EXIT#,LIBRARY=libPNTsyb.so,PROGRAM=pntsqlif, PARMS=("pntsqlcmd","diplomat","diplomat","ADVISOR", "select datediff(ss, convert(datetime," "Jan 01 2007 00:00:00:00AM,109),getdate())", "0", "2", "easerver"); Following is an example use of pntsqlcmd in a transaction exit on z/OS: TRANSACTION-EXIT: PROGRAM=PNTSQLIF, CONTEXT=PRE-POLL, PARMS=("pntsqlcmd","#LOCAL-USERID#", "#LOCAL-PASSWORD#","#DB-NAME#", "update lock_table set poll_flag=X " "where current_timestamp > lock_ts + 15 seconds " "AND (update_status <> Y OR update_status='')", "1", "1", ""#DB-SERVER-NAME#"); Following is an example use of pntsqlcmd in an assignment exit on z/OS: #EXIT#,PROGRAM=PNTSQLIF, PARMS=("pntsqlcmd","iwave","iwave","ADVISOR", "select second(current_time) from " "sysibm.systables", "0", "1", "easerver");
pntsqlif, PNTSQLIF
pntsqlif is a function on UNIX and Windows NT, and PNTSQLIF is a program on z/OS. For details, review the entry for exit function pntsqlcmd.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 99 of 276
pntsubst
The exit function pntsubst is used solely in an assignment exit and returns a substring of a string, starting at a specified, zero-based position in the string and continuing for a specified number of characters. To use pntsubst, provide the following parameters to function pntpexif: "pntsubst", "the_string", "position", "number_of_chars" where: the_string is the string from which to derive a substring. position is the string position at which the substring starts. The first character of the string is at position zero. number_of_chars is the number of characters to include in the substring. If the combination of position and number_of_chars extends beyond the end of the string, the substring begins at position and extends to the end of the_string.
The function returns an empty string if an error occursfor example, if number_of_chars is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns four to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntsubst","0123four","4","3") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("pntsubst","0123four","4","3") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("pntsubst","0123four","4","3")
pntwto
The exit function pntwto is used solely in a transaction exit on z/OS and writes a string to the z/OS system console. To use pntwto, provide the following parameters to program PNTPEXA: "pntwto",iwave_integrator_constant
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 100 of 276
where: iwave_integrator_constant is evaluated, and the string is written to the z/OS system console; for details on the syntax of an iWave Integrator constant, see iWave Integrator Constants on page 150.
After evaluating the iWave Integrator constant, the iWave Integrator truncates the value to 124 characters, if necessary. The program pntwto ends with a status value of 0, even if the number characters is 0. The following writes Error on Remote iWave Integrator to the z/OS system console: #EXIT#,PROGRAM=PNTPEXA, PARMS=("pntwto","Error on Remote iWave Integrator")
randint
The exit function randint is used solely in an assignment exit and returns a random number. To use randint, provide the following parameters to function pntpexif: "randint", "low", "high" where: low is an unsigned whole number; the resulting random number is greater than this. high is an unsigned whole number; the resulting random number is less than this.
The function returns an empty string if an error occursfor example, if length of the resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns a random number greater than 0 and less than 10 to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("randint","0","10") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("randint","0","10") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("randint","0","10")
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 101 of 276
right
The exit function right is used solely in an assignment exit and returns a substring that is the right-most n characters of a string. To use right, provide the following parameters to function pntpexif: "right", "the_string", "number_of_chars" where: the_string is the string from which to derive a substring. number_of_chars is the number of right-most characters to include in the substring. If number_of_chars is greater than the length of the_string, the substring is all of the_string.
The function returns an empty string if an error occursfor example, if number_of_chars is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns four to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("right","0123four","4") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("right","0123four","4") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("right","0123four","4")
rpad
The exit function rpad is used solely in an assignment exit and returns a superstring of a string to which a pad character has been appended to the rightmost end. To use rpad, provide the following parameters to function pntpexif: "rpad", "the_string",pad_character,new_length where:
iWave Software
Revised [03/01/07] P01-664-09
the_string is the string to which padding is to be appended at the rightmost end.

pad_character is the single character to be appended to the rightmost end of the_string new_length is the length of the resulting assigned value
The function returns an empty string if an error occursfor example, if the length of resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns four---- to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("rpad",four,"-",8) On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("rpad",four,"-",8) On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("rpad",four,"-",8)
rtrim
The exit function rtrim is used solely in an assignment exit and returns a substring of a string from which the rightmost contiguous whitespace (space, tab, carriage return, newline) is removed. To use rtrim, provide the following parameters to function pntpexif: "rtrim", "the_string" where: the_string is the string from which the rightmost contiguous whitespace (space, tab, carriage return, newline) is to be removed.
The function returns an empty string if an error occursfor example, if the length of resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns four to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA,
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 103 of 276
PARMS=("rtrim","four On UNIX:
")
#EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("rtrim","four ") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("rtrim","four ")
strlwr
The exit function strswr is used solely in an assignment exit and returns a string converted to all lower-case letters. To use strlwr, provide the following parameters to function pntpexif: "strlwr", "THE_STRING" where: THE_STRING is the string to be converted to all lower-case letters.
The function returns an empty string if an error occursfor example, if the length of resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns four to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("strlwr","FOUR") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("strlwr","FOUR") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("strlwr","FOUR")
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 104 of 276
strupr
The exit function strupr is used solely in an assignment exit and returns a string converted to all upper-case letters. To use strupr, provide the following parameters to function pntpexif: "strupr", "the_string" where: the_string is the string to be converted to all upper-case letters.
The function returns an empty string if an error occursfor example, if the length of resulting string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns FOUR to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("strupr","four") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("strupr","four") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("strupr","four")
timeconv
The exit function timeconv is used solely in an assignment exit and returns a formatted timestamp based on an input timestamp and mask, an output timestamp mask, and the current processing file sections settings for AM-INDICATOR, PM-INDICATOR, MONTHNAMES, and LOCAL-UTC.
CAUTION requirements. If the particular iWave Integrator requires a specific mask value
and you use a different mask value, then application results will be unpredictable. For details on timestamp fields, see Timestamp Masks on page 155.
The input and output timestamp masks may have application-specific
To use timeconv, provide the following parameters to function timeexif:

iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 105 of 276
"timeconv", "input_timestamp", "input_timestamp_mask", "output_timestamp_mask" where: input_timestamp is the timestamp whose format is to be converted. input_timestamp_mask identifies how input_timestamp is formatted. output_timestamp_mask identifies how the assigned value is formatted. For further details on timestamp masks, see Timestamp Masks on page 155. For example: On UNIX: #EXIT#,LIBRARY=timeexit.so, PROGRAM=timeexif, PARMS=("timeconv", "@INPUT_TIMESTAMP@", %T, "%Y-%m-%d %H:%M:%S); On Windows: #EXIT#,LIBRARY=timeexit.dll, PROGRAM=timeexif, PARMS=("timeconv", "@INPUT_TIMESTAMP@", %T, "%Y-%m-%d %H:%M:%S");
timediff
The exit function timediff is used solely in an assignment exit and returns the difference between two timestamps in number of seconds; the calculation subtracts the second timestamp from the first and can return a negative or positive number.
value, then application results will be unpredictable. For details on timestamp fields, see Timestamp Masks on page 155.
To use timediff, provide the following parameters to function timeexif: "timediff", "first_timestamp", "second_timestamp", "timestamp_mask", "month_names", "am_indicator", "pm_indicator" where:
iWave Software
Revised [03/01/07] P01-664-09
first_timestamp is the timestamp from which to subtract.

second_timestamp is the timestamp to subtract from first_timestamp. timestamp_mask identifies how each timestamp is formatted. Both timestamps must be formatted in accordance with the same mask. Type the following if you wish to assign the mask you specified in keywords NOWMASK, DATE-MASK, or TIME-MASK, respectively: #NOW-MASK# #DATE-MASK# #TIME-MASK#
month_names identifies what month names are valid in a database date or time field. This parameter is meaningful only when the timestamp mask includes conversion specifier %b, which refers to a month name to be transformed into an equivalent integer. Type the following if you wish to assign the value you specified with keyword MONTH-NAMES: #MONTH-NAMES#
am_indicator tells what characters in a database date or time field indicate that the hour value in the field is less than 12 noon. This parameter is meaningful only when the timestamp mask includes conversion specifier %p. Type the following if you wish to assign the value you specified with keyword AM-INDICATOR: #AM-INDICATOR#
pm_indicator tells what characters in a database date or time field indicate that the hour value in the field is greater than or equal to noon. This parameter is meaningful only when the timestamp mask includes conversion specifier %p. iWave Integrator adds 12 to the number of hours in the timestamp if the following are true: The hour in the timestamp is less than 12 The conversion specifier %p appears in the timestamp mask, and the database-field value to which %p refers matches the setting of pm_indicator
Type the following if you wish to assign the value you specified with keyword PMINDICATOR: #PM-INDICATOR# For further details on timestamp masks, see Timestamp Masks on page 155. You may assign a null string ("") to any of the last three parameters, as is appropriate if the parameter is not meaningful for the timestamps you are comparing. The following assigns 20, for example: On UNIX: #EXIT#,LIBRARY=timeexit.so, PROGRAM=timeexif, PARMS=("timediff", "2000-01-01 00:00:20", "2000-01-01 00:00:00", "%Y-%m-%d %H:%M:%S","", "", "")
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 107 of 276
On Windows: #EXIT#,LIBRARY=timeexit.dll, PROGRAM=timeexif, PARMS=("timediff", "2000-01-01 00:00:20", "2000-01-01 00:00:00", "%Y-%m-%d %H:%M:%S","", "", "")
timestr
The exit function timestr is used solely in an assignment exit and returns a formatted timestamp based on the current date and time and a timestamp mask.
value, then application results will be unpredictable. For details on timestamp fields, see Timestamp Masks on page 155. To use timestr, provide the following parameters to function timeexif: "timestr", "timestamp_mask", "#FIXED-NOW#", "month_names", "am_indicator", "pm_indicator" where:
timestamp_mask identifies how the resulting timestamp is formatted. Type the following if you wish to assign the mask you specified in keywords NOWMASK, DATE-MASK, or TIME-MASK, respectively: #NOW-MASK# #DATE-MASK# #TIME-MASK#
#FIXED-NOW# is a system variable month_names identifies what month names are valid in the resulting timestamp. This parameter is meaningful only when the timestamp mask includes conversion specifier %b, which refers to a month name to be included in the timestamp. am_indicator tells what characters in the resulting timestamp indicate that the hour value is less than 12 noon. This parameter is meaningful only when the timestamp mask includes conversion specifier %p. pm_indicator tells what characters in the resulting timestamp indicate that the hour value is greater than or equal to noon. This parameter is meaningful only when the timestamp mask includes conversion specifier %p. For further details on timestamp masks, see Timestamp Masks on page 155. You may assign a null string ("") to any of the last three parameters, as is appropriate if the parameter is not meaningful for the timestamp mask. The following assigns 20, for example:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 108 of 276
On UNIX: #EXIT#,LIBRARY=timeexit.so, PROGRAM=timeexif, PARMS=("timestr", "%Y-%m-%d %H:%M:%S.%f","#FIXED-NOW#", "", "", ) On Windows: #EXIT#,LIBRARY=timeexit.dll, PROGRAM=timeexif, PARMS=("timestr", "%Y-%m-%d %H:%M:%S.%f","#FIXED-NOW#", "", "", )
tokenize
The exit function tokenize is used solely in an assignment exit and returns a substring that is the nth substring of a string. To use tokenize, provide the following parameters to function pntpexif: "tokenize", "the_string", substring_separator, "substring_instance" where: the_string is the string from which to derive a substring. substring_separator is a single character that separates substrings in the_string substring_instance is the ordinal of the substring to be found, starting at 1 (the first substring)
The function parses the_string from left to right, using substring_separator to delimit substrings within the_string. The substring_separator character is not recognized as such if it is encountered in a substring that is contained within single quotes or double quotes. The function returns an empty string if an error occursfor example, if substring_instance is 0 or is not numeric or is greater than the number of substrings, or if the length of the substring is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns second substring to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("tokenize","first substring|second substring|third substring",|,"2") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("tokenize","first substring|second substring|third substring",|,"2")
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 109 of 276
On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("tokenize","first substring|second substring|third substring",|,"2")
tranchr
The exit function tranchr is used solely in an assignment exit and returns a string with selected characters changed. To use tranchr, provide the following parameters to function pntpexif: "tranchr", "the_string", from_ars, "to_chars" where: the_string is the string in which selected characterts are to be changed. from_chars is character string containing the characters to be changed when found in the_string to_chars is a character string with the same number of characters as from_chars, containing the characters to which characters in the_string are to be changed
The function changes characters in the_string, found in from_chars, to the character in the same position in to_chars. The function returns an empty string if an error occursfor example, if the length of the string is greater than the maximum value length (MAXVLEN) specified in system variable #EXIT#; the default of MAXVLEN is 4096. The following assigns Hurting to MY_FIELD, for example: On z/OS: #EXIT#,PROGRAM=PNTPEXA, PARMS=("tranchr","Testing",Tse,"Hru") On UNIX: #EXIT#,LIBRARY=libPNTpexa.so, PROGRAM=pntpexif, PARMS=("tranchr","Testing",Tse,"Hru") On Windows: #EXIT#,LIBRARY=libPNTpexa.dll, PROGRAM=pntpexif, PARMS=("tranchr","Testing",Tse,"Hru")
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 110 of 276
Writing Functions for Use in Exits
This section describes conventions for writing custom functions for use in assignment exits, transaction exits, or both. z/OS On z/OS, the following is true: Exits use custom programs, and the program name is identified in the PROGRAM clause of system variable #EXIT#for assignment exitsor the Program field of the Transaction Exit dialog box. SAS/C exit programs must contain main( ) and must be link edited with the entry point set to $MAINC. All exit programs must be either reentrant or reusable.
For example code on z/OS, see the following directory for your iWave Integrator: <high-level-qualifier>.SAMPLES.xx where xx identifies the iWave Integrator.
UNIX and Windows On UNIX and Windows NT, exits use functions contained within a shared object (UNIX) or a DLL (Windows NT), and the library is identified in the LIBRARY clause of the system variable #EXIT#for assignment exits or the Library field of the Transaction Exit dialog box. The PROGRAM clause is the name of the function. For example make files and code, see the following subdirectory: exitsamp
Pointer List iWave Integrator invokes the custom code with a pointer to a pointer list; in C, the argument passed is in the form char**. Your code must handle the pointer list, which is as follows: Pointer 1 points to an unsigned 32-bit integer containing the number of pointers in the list. The value of that integer is at least 5. Pointer 2 points to the result buffer, which a transaction uses only when the code is invoked as an assignment exit. The number of bytes in this buffer is equal to the maximum-value length, which is the default 4096 or is the number you specify in the MAXVLEN clause when you use system variable #EXIT#.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 111 of 276
If the code is invoked as a transaction exit, pointer 2 is NULL. This convention lets your code determine whether the invocation is for an assignment exit or a transaction exit. iWave Integrator initializes the buffer, if any, to binary zeros. To return a string to be assigned to a data model field, build a null-terminated string in that buffer. To return an empty string, keep a binary zero in the first byte. If the code is invoked as an assignment exit, pointer 3 points to an unsigned 32bit integer that contains the maximum-value length of the buffer to which pointer 2 refers; results are indeterminate if the program fails to observe this maximum. If the code is invoked as a transaction exit, pointer 3 points to a location in which to place a return code. A zero indicates success, a non-zero indicates failure. Pointer 4 points to a 256-byte message buffer, which iWave Integrator initializes to binary zeros. To return a string to be written to the system log, build a nullterminated string in that buffer and be sure that the statement used to invoke the function indicates that writing to the log is valid. (The statement used to invoke the function is either system variable #EXIT# or the transaction exit specification.) Pointer 5 is reserved. Results are indeterminate if the program changes this pointer or the area to which it points. Pointers 6 and above point to the fully evaluated iWave Integrator constants that you specified as exit parameters, in parameter-list order. Each pointer points to a null-terminated string, which should not be modified. On z/OS, in accordance with standard linkage conventions, identify the end of the list by setting the high-order bit of the last pointer.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 112 of 276
Part II Securing Transactions
iWave Integrator transactions flowing across a non-secure networkespecially the public Internetmust be secured to protect your business data. To secure these iWave Integrator transactions, iWave offers several different solutions. When both connection authentication and transaction encryption are required, iWave supports Secure Sockets Layer (SSL) communications on UNIX and Windows. SSL provides both connection authentication and transaction encryption. When connection authentication is not required but transaction encryption is needed, iWave transactions can be encrypted using the Blowfish encryption algorithm.
9
Authentication and Encryption Using Secure Sockets Layer (SSL)
For transactions that do not require the use of XML, use the Secure Sockets Layer (SSL) support of iWave Director for UNIX and Windows. For transactions that require the use of XML to communicate with non-iWave components such as Web Services, install and configure the iWave Integrator for XML Web Services and configure its Secure Sockets Layer (SSL) support. This chapter describes which connections can be authenticated and which data flows can be encrypted with SSL, and how to configure SSL.
SSL Overview
SSL secures network connections and data by providing authentication and encryption. Authentication is the process of establishing the identity of both parties to a network connection. SSL uses the public key infrastructure (PKI) for authentication. Each party to a connection uses certificates issues by a trusted Certificate Authority (CA) to authenticate the identity of the other party. SSL uses encryption to secure the information exchanged between connected partners. During the authentication process, the SSL partners negotiate an encryption algorithm and encryption keys that are subsequently used for all data transferred on the connection. This chapter describes which iWave connections can be authenticated and encrypted with SSL.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 114 of 276
You can configure Secure Sockets for any of the following iWave Integrator connections and message flows: iWave Client/iWave Director Transaction requests sent by an iWave Client to a specific iWave Servers iWave Director, and transaction responses sent by an iWave Director to an iWave Client. The Client and Director must be running on either Windows or UNIX. iWave Adapter for Web Services Server/XML Web Server The connection between the Server Adapter for Web Services and a web server, and the data flowing on that connection. iWave Adapter for Web Services Client/Microsoft Operations Manager MCF The connection between the Client Adapter for Web Services and MOM MCF, and the data flowing on that connection. iWave Agent for Web Services/XML Web Client The connection between an XML web client and the Agent for Web Services, and the data flowing on that connection.
Secure Sockets Certificates

iWave now supports Secure Sockets (SSL) on Windows. In topics following, configuration parameters are described for Director and the Web Services agent and adapter. This topic describes how to obtain the certificates required by SSL. Commercial Certificates iWave customers may obtain both client and server certificates from GeoTrust (www.geotrust.com) or any certificate authority that generates certificates in the required format (either PEM format or PKCS#12 format). The procedure for obtaining certificates from any certificate authority is as follows. 1. Create a certificate signing request (CSR) with the openssl utility. This utility may already be available on your system as part of the OpenSSL package. It is also included in the iWave distribution bin directory. The openssl utility requires a configuration file. iWave is distributed with a sample of this configuration file, suitable for creating CSRs. This file is named iwavecsr.cfg and is located in the SAMPLES directory in iWave distribution CD 2. Following are sample commands. These commands apply to certificates from any certificate authority. a. Create a private key. You will be prompted for a pass phrase. Be sure to keep a record of this pass phrase, since this is the passphrase described in the following topics. openssl genrsa -out drive:\directory\domainname.key des3 1024 -
We recommend using the domain name in the key file name. We also recommend that you make a copy of the key file and keep it in a safe place. If you lose your key you will need to purchase another certificate.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 115 of 276
There are two other ways that you can supply the pass phrase. You may want to use one of these to be sure that the pass phrase is spelled correctly. The first method uses the following command line. The pass phrase is entered directly on the command line. openssl genrsa -out drive:\directory\domainname.key passout pass:pass-phrase -des3 1024 The second method uses the following command line. The pass phrase is contained in the first line of the pass phrase file, as plain text. openssl genrsa -out drive:\directory\domainname.key passout file:pathname -des3 1024 b. Create a CSR using the private key. You will be prompted for various items. Following the sample command is an explanation of each item. openssl req -new key drive:\directory\domainname.key out drive:\directory\domainname.csr config drive:\iwavesample-directory\iwavecsr.cfg
Character Set The following characters cannot be used: < > ~ ! @ # $ % ^ / \ ( ) ? . , Common Name The Common Name is the Host + Domain Name. It looks like "www.company.com" or "company.com". Certificates can only be used on iWave using the Common Name specified during enrollment. For example, a certificate for the domain "domain.com" will fail if accessing a site named "www.domain.com" or "secure.domain.com", because "www.domain.com" and "secure.domain.com" are different from "domain.com". When you subsequently configure iWave to use SSL, this is the fully qualified domain name. Organization Information The Organizational Unit Name is the name of the department or organization unit making the request. The Locality Name is the city or town name, for example: Frisco. Do not abbreviate the state or province name, for example: Texas. Use the two-letter code without punctuation for country, for example: US or CA.
Contact Information During the verification process, the certificate authority may need to contact your organization. Be sure to provide an email address, telephone number, and fax
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 116 of 276
number that will be checked and responded to quickly. The email address, telephone number and fax number are not part of the certificate. 2. Go to www.geotrust.com (or any other certificate authority) and follow instructions for obtaining a server certificate. This certificate can be used in either a client context or a server context. Be sure to request the certificate in PEM format; if this format is not available, request PKCS#12 format. If neither format is available, certificates from this authority cannot be used by iWave. Also, be sure to request a root CA certificate in addition to your server certificate. 3. If your certificate is in PKCS#12 format, use the following command to convert it to PEM format: openssl pkcs12 in pkcs12-certificate-file -out pemcertificate-file
Self-Signed Certificates iWave customers may create and use self-signed certificates instead of commercial certificates. To create a self-signed certificate, you use OpenSSL tools to create your own Certificate Authority, then create your self-signed certificate based on your Certificate Authority. You will use the following tools: 1. The openssl utility. This utility may already be available on your system as part of the OpenSSL package. It is also included in the iWave distribution bin directory. 2. The CA.pl Perl script, in the SAMPLES directory of iWave distribution CD #2. 3. The openssl.cnf configuration file, in the SAMPLES directory of iWave distribution CD #2. You may need to customize this file. For example, the $DAYS variable defaults the life of the application certificate to 365 days; you may want to increase this. 4. The createCA Korn shell script, in the SAMPLES directory of iWave distribution CD #2. This script uses CA.pl and openssl.cnf to create the Certificate Authority and the application certificate. When you execute this script, you will be prompted for information needed to create the CA certificate and the application certificate. See the instructions above for Commercial Certificates for the types of information required. This script creates the CA certificate, named cacert.pem in a child directory named demoCA, and creates the application certificate and CSR in the current directory. The application certificate is named newcert.pem and the CSR is named newreq.pem. You can use the CSR as the private key file in the iWave Director configuration file (sdserver.ini). The CA certificate can be used for the TrustedCACertificateFile in both the ReceiveFromSSL section and the SendToSSL section. The application certificate can be used for the CertificateChainFile in both the ReceiveFromSSL section and the SendToSSL section. The CSR can be used for the PrivateKeyFile in both the ReceiveFromSSL section and the SendToSSL section.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 117 of 276
Secure Sockets Entropy

SSL uses random numbers to implement cryptographic security. Conventional random number sources are useless for cryptographic purposes because they are too predictable. For truly random numbers a source of entropy is required. SSL is able to acquire sufficient entropy from Windows without requiring user involvement. On UNIX and Linux, user involvement may be required. SSL attempts to acquire entropy from /dev/random and /dev/urandom. If these sources exist, they are provided automatically by the operating system. If these sources do not exist or supply insufficient entropy, SSL attempts to acquire entropy from an entropy gathering daemon, at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool, and /etc/entropy. If none of these sources exist or supply insufficient entropy, iWave writes a message to its log indicating that a cryptographically weak random number is in use, and proceeds with SSL operations. Entropy gathering daemons are not part of the operating system and must be installed and started by the user. One such is the Entropy Gathering Daemon (EGD), available at http://egd.sourceforge.net. If you use this product, follow the installation instructions in the EGD readme. To start the daemon, follow the instructions for OpenSSH.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 118 of 276
Part III Administering iWave Integrator
10
Administering iWave Integrator from the Command Line or Console
To start iWave Integrator components, you start iWave Director. The method you use to start iWave Director depends on the platform where iWave Director resides. The most common methods for starting iWave Directors are as follows: On Windows NT, you start iWave Director using iWave Integrator Service Interface. On UNIX, you start iWave Director using the startall script. On z/OS, you start iWave Director by submitting JCL named xxSERVER (IMSERVER for Tivoli Information Management, SLSERVER for CA SOLVE:Central.
This chapter describes the following tools that you can use to control iWave Integrator components: iWave Administrator Command Level Interface (iWave Administrator CLI, also called SDDC), runs on UNIX and Windows NT machines. Using SDDC, you can administer iWave Directors, iWave Integrators, Clients, Servers, and Agents running on UNIX and Windows NT and, if TCP/IP is available, on z/OS. Scripts are provided that run on UNIX platforms. You can use these scripts to control iWave Directors, Clients, Servers, and Agents running on UNIX and Windows NT and, if TCP/IP is available, on z/OS. MVS console commands let you control iWave Directors, Clients, Servers, and Agents from the z/OS console. These commands control components running on z/OS only.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 120 of 276
Running iWave Administrator CLI (SDDC)

Using iWave Administrator CLI (also known by the name of its executable, SDDC), you can administer iWave Integrator from the UNIX or Windows NT command line. You can include iWave Administrator CLI commands in batch programs or scripts.
NOTE iWave Administrator CLI (SDDC) replaces the sdstatus utility.
SDDC uses the following syntax: sddc a address -v verb [-u userid/password] [-k] [-c unicode-file] [-l local-address] [-t object-type [-o object]] [-p option ...] where: sddc is the name of the program. address is the IP address of iWave Directors management access point. The format of address is either ip-address,port (if iWave Director is located at a foreign system) or port (if iWave Director is located on the same system). The value of port must match the value of the ManagementPort key used to configure iWave Director. verb is any of the following: cycleStart and restart a Client, Server, or iWave Integrator, or an Agent that is managed by iWave Director. killForce an immediate termination of a Client, Server, or iWave Integrator, or of an Agent that is managed by iWave Director. Executing a kill may lose some information that otherwise would be logged. reportReport information such as the date, the version of iWave Director, and the operational status of all Clients, Servers, iWave Integrators, and Agents that are managed by iWave Director. setSet the level of detail presented in the iWave Director output log. shutdownStop iWave Director in a way that retains logging information. startStart a Client, Server, or iWave Integrator, or an Agent that is managed by iWave Director; or to start a new log.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 121 of 276
stopStops a Client, Server, or iWave Integrator, or an Agent that is managed by iWave Director.
For details, see Verbs Supported by the iWave Administrator CLI on page 123.
userid is a user ID that is valid on the machine where iWave Director runs.
NOTE
You must supply a valid user ID and password when issuing the cycle, kill, set, start, stop, or shutdown actions. If the user ID and password are omitted or if they are invalid on the machine where iWave Director runs, iWave Director reports the following message: User ID and Password not authorized by iWave Director
The following conditions apply for actions that require that you supply a valid user ID: If no Authorized Users are defined for iWave Director, any user with a valid user ID on the machine where iWave Director runs can issue cycle, kill, set, start, stop, or shutdown actions. If any Authorized User is defined for iWave Director in the configuration file, only Authorized Users can issue cycle, kill, set, start, stop, or shutdown actions.
password is the configured password for userid on iWave Director system. Notice that a forward slash separates the user ID and password. This is true on all platforms. An alternative to u is k, which causes sddc to prompt for userid and password. The password reply is not displayed on the screen. unicode-file is the full path name of the Unicode translation file. Optional. If not provided, SDDC uses the Unicode translation file named 8859-1.TXT in the directory containing the sddc executable. local-address is the IP address of the local machine. Supply this value if the local machine is multi-homed and iWave Directors system uses a firewall. object-type is one of several values, and the verb-specific choices are described in Verbs Supported by the iWave Administrator CLI in the next section. object is one of several values, and the verb-specific choices are described in Verbs Supported by the iWave Administrator CLI in the next section. option is one of several values, and the verb-specific choices are described in Verbs Supported by the iWave Administrator CLI in the next section.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 122 of 276
Verbs Supported by the iWave Administrator CLI The verbs supported by the iWave Administrator CLI are as follows: cycleStop and restart a managed resource (object) that is currently defined in the configuration file. option is not used. If the resource is not running already, start it. The valid values for object-type are as follows: agentAn Agent named object. clientA Client named object. interfaceAn iWave Integrator named object. serverA Server named object.
The following command stops and restarts the Client named PNTRYDCA, where floyd is the user ID and haircut is the password: sddc -a server2,9300 -v cycle -t client -o PNTRDYCA u floyd/haircut killForce the immediate termination of a managed resource (object) of type object-type. option is not used. The valid values for object-type are as follows: agentAn Agent named object. clientA managed application named object. interfaceAn iWave Integrator named object. serverA Server named object.
The following command forces the Server named PNTRYDSA to stop, where floyd is the user ID and haircut is the password: sddc -a server2,9300 -c /usr/skywiresoftware/iwave/integrator/config/8859-1.TXT -v kill -t server -o PNTRDYSA u floyd/haircut reportReport information of type object-type. option is not used. The valid values for object-type are as follows: - dateSystem date and time. object is not used. - eventsReport on iWave Director error events as they occur. If you select events, the session between SDDC and iWave Director is devoted to open ended reporting of all log messages whose action type is either U (user error) or P (product error). Messages written to all log files managed by iWave Director are monitored. object is not used. identityThe version, release, and modification level of the Service Manager, the name of iWave Directors configuration file, and the generic operating system type. object is not used. statusOperational status and statistics for all managed resources. Object is not used.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 123 of 276
Examples of the report verb are as follows: sddc sddc sddc sddc -a -a -a -a server3,9000 -v report -t status server3,9000 -v report -t identity server3,9000 -v report -t events 208.99.12.12,9000 -v report -t events
If you omit the host name or IP address, the command is issued for the machine from which you are issuing the command: sddc -a 9000 -v report -t status setSet or reset an operational parameter of type object-type to option. Object is not used. The only valid value for object-type is as follows: logiWave Directors log. option may be either normal, for normal log messages, or verbose, for problem determination.
Examples of the set verb are as follows, where floyd is the user ID and haircut is the password: sddc -a server2,9300 -v set -t log -p verbose -u floyd/haircut shutdownStop iWave Director and all of its managed resources. objecttype, object, and option are not used. The following is an example of the shutdown verb (where floyd is the user ID and haircut is the password): sddc -a server2,9300 -v shutdown -u floyd/haircut startStarts a managed resource (object) that is currently defined in the configuration file. option is not used. The valid values for object-type are as follows: agentAn Agent named object. If object is not provided, all Agents are started. clientA Client named object. If object is not provided, all Clients are started. interfaceAn iWave Integrator named object. If object is not provided, all iWave Integrators are started. logA log file. This verb causes the current log file to be closed and a new log file to be opened. If object is provided, the log file for a Server or Client or Agent named object is affected. If object is not provided, iWave Directors log is affected. When a new iWave Director log file is opened, its name is manager.log.n, where n is 0 the first time this command is issued, and increments for each subsequent use of this command. When a new Server or Client or Agent log file is opened, the new name is created according to the rules for naming Server and Client and Agent logs (for example, server-name.log.n and client-name.log.n and agentname.log.n).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 124 of 276
NOTE The log object type is not valid for z/OS.
serverA Server named object. If object is not provided, all Servers are started.
Examples of the start verb are as follows, where floyd is the user ID and haircut is the password: sddc -a server2,9300 -v start -t interface -o "RemedyARS" -u floyd/haircut The following command starts a new iWave Director log: sddc -a server2,9300 -v start -t log -u floyd/haircut The following command starts a new log for the Client named PNTRYDCA: sddc -a server2,9300 -v start -t log -o PNTRDYCA u floyd/haircut The iWave Integrator name must be enclosed in quotation marks ( ) when the name
NOTE includes blanks.
stopStart a managed resource (object) that is currently defined in the configuration file. option is not used. If object-type is not specified, all currently active iWave Integrators, Servers, Clients, and Agents are stopped. The valid values for object-type are as follows: agentAn Agent named object. If object is not provided, all Agents are stopped. clientA Client named object. If object is not provided, all Clients are stopped. interfaceAn iWave Integrator named object. If object is not provided, all iWave Integrators are stopped. serverA Server named object. If object is not provided, all Servers are stopped.
The following command stops the Server named PNTRYDSA, where floyd is the user ID and haircut is the password: sddc -a server2,9300 -c /usr/skywiresoftware/iwave/integrator/config/8859-1.TXT -v stop -t server -o PNTRDYSA u floyd/haircut The previous is a UNIX example. Note that the user ID and password are always separated by a forward slash. On Windows, the paths use backslashes, but the user ID and password are still separated by a forward slash.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 125 of 276
Using UNIX Scripts to Administer iWave Integrator

Several useful scripts are included with iWave Integrator for running the iWave Administrator CLI (SDDC). If you do not want to use the scripts, skip this section. The following scripts are available: setenv startall stopall checkall start_agent
To use the scripts, do the following: Only an Authorized User who is defined in the configuration file (sdserver.ini) that is currently in use by iWave Director can use the stopall script. Before you try to use these scripts to start or stop iWave Director, you should be sure you are defined as an Authorized User in the configuration file.
NOTE
Step 1. Copy the scripts into a directory that is not in the operating systems path. (If you have more than one iWave Director on the machine, placing the directory in the path would prevent your being able to control more than one iWave Director.) Step 2. Edit the setenv script. The setenv script sets the environment variables that the other scripts require. Refer to the comments within the file for instructions.
NOTE Be sure that setenv is in the same directory as the other scripts.
If you installed iWave Integrator into the default installation directory, you may be able to use the scripts with no changes. To enable the scripts, open the file scripts/setenv in a text editor and modify it as follows: 1. If iWave Integrator is installed in a directory other than /usr/skywire software/iwave/integrator, change the value of SDHOME to the directory in the following line: export SDHOME=/usr/skywiresoftware/iwave/integrator 2. The SDPATH setting is the name of the directory where the iWave Integrator binary files are installed, $SDHOME/bin. Do not change this setting. 3. To use a port other than 9000 to send commands to iWave Director, change the value of SDSTATUSPORT in the following line: export SDSTATUSPORT=9000 4. Three environment variables (SHLIB_PATH, LD_LIBRARY_PATH, and LIBPATH) contain the search path for UNIX to use to locate shared libraries. By default these environment variables are set to $SDHOME/lib, which is the location of the iWave Integrator shared libraries. You may need to specify additional shared libraries for your application. For Oracle see the following instructions.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 126 of 276
If you are using Oracle, do the following: a. Define the ORACLE_HOME environment variable. See your Oracle product installation instructions. b. Refer to the Oracle product installation instructions. If you are running UNIX, define the ORACLE_SID environment variable. For Windows, define the LOCAL environment variable. c. Modify the SHLIB_PATH, LD_LIBRARY_PATH, and LIBPATH environment variables (in the setenv script) to include $ORACLE_HOME/lib as shown in the following example:
export SHLIB_PATH=$SDHOME/lib:$ORACLE_HOME/lib export LD_LIBRARY_PATH=$SDHOME/lib:$ORACLE_HOME/lib export LIBPATH=$SDHOME/lib:$ORACLE_HOME/lib Step 3. Run the scripts using the following syntax: startall The startall script starts the iWave Director defined in setenv; iWave Director then starts the other iWave Integrator components. The startall script has no parameters; the script finds the name of the iWave Director to start in setenv. stopall userid password The stopall script stops all iWave Integrator components; iWave Director stops last. Only users who are defined as Authorized Users in the iWave Director configuration file (sdserver.ini) can use the stopall script. The stopall script requires two parametersthe user ID and password of an Authorized User. checkall The checkall script runs the SDDC status report, which reports whether iWave Integrator is running and which components are running. The checkall script has no parameters. start_agent The start_agent script starts the Universal Notification Agent, if the iWave Integrator is running in event detection mode and if the iWave Integrator uses the Universal Agent. Refer to the iWave Integrator Guide for your iWave Integrator to determine which Agent your iWave Integrator uses, if any. The start_agent script has no parameters. (The Peregrine Service Center iWave Integrator uses the start_agentaxc and stop_agentaxc scripts instead. See the iWave Integrator Guide for Peregrine Service Center.)
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 127 of 276
Within the start_agent script, change the variables (which all begin with $) to match your environment: $SD_BINPATHChange $SD_BINPATH to the iWave Integrator bin directory, for example: /usr/skywiresoftware/iwave/integrator/bin $SD_MGMTIPADDRChange $SD_MGMTIPADDR to the TCP/IP address where the Client resides. The TCP/IP address can be either a host name or an IP address. $SD_NOTFPORTChange $SD_NOTFPORT to the TCP/IP port where the Client listens for notifications from the Agent. This port is defined by keyword DETECTION-PORT in the Client processing file. $SD_LOGPATHChange $SD_LOGPATH to the iWave Integrator log directory, for example: /usr/skywiresoftware/iwave/integrator/log After you replace the variables, you can change other settings in the start_agent script if you choose: Section name (the combination of Object Class, Verb, and optional Verb Qualifier)In most of the samples supplied with iWave Integrator, transactions are processed as Object Class PROBLEM, Verb CreateUnique. If you have named your Object Class differently, or if you want to use a different Verb or a Verb Qualifier, change those section name settings. Log nameYou can specify any name for the log. Log detailThe -v setting, which is either -v 1 or -v 0, determines how much detail the log contains: 0 is minimal logging; 1 is maximum logging. Unless you are troubleshooting a problem with the Agent, you should use the -v 0 setting in your production environment.
Administering iWave Integrator from the z/OS Console

On z/OS, you administer iWave Director by issuing console commands. You do not need to be an Authorized User to issue these commands if you have access to the system console. The console commands allow you to do the following: Stop iWave Director
NOTE your z/OS iWave Integrator.
You start iWave Directors that run on z/OS by running the start-up JCL provided with
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 128 of 276
Generate status reports for iWave Director and the components it controls Change iWave Director log options Start, stop, cycle, or force stop the components iWave Director controls typically Clients and Servers
The status of the iWave Director is reported to the system console. You can also control iWave Directors running on z/OS by using either SDDC (which
NOTE runs on Windows NT and UNIX).
You can run iWave Director as either a batch job or a started task. In either case, when iWave Director starts successfully, it issues the following message with reply outstanding: @nn PNT2001I IWAVE DIRECTOR READY FOR WORK You enter all iWave Director commands as replies to this message. After you enter an iWave Director command, this message is reissued to the system console.
Stopping iWave Director The TERM console command stops iWave Director. The format of the command is as follows: R nn, TERM
Generating a Status Report iWave Director reports the status of various iWave Director components in response to the REPORT command. The format of the command is as follows: R nn, REPORT The following is an example of the report: +PNT2105I RECEIVE-FROM TRANSPORT 199.0.80.25,22764 STATUS: CONNECTED +PNT2102I RECEIVE-FROM IWAVE DIRECTOR 199.0.80.25 STATUS: CONNECTED REQUESTS=0 RESPONSES=0 +PNT2106I SEND-TO IWAVE DIRECTOR 199.0.80.25,22764 STATUS: CONNECTED +PNT2101I SERVER INFOSA REQUESTS=0 RESPONSES=0 ACTIVE TASKS=2 MAX TASKS=2 +PNT2103I CLIENT APP infoca STATUS: ACTIVE @10 PNT2001I IWAVE DIRECTOR READY FOR WORK, reply TERM to terminate
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 129 of 276
This report is different from the reports generated by SDDC.
Changing iWave Director Log Options The SET command modifies iWave Directors log options. The format of the command is as follows: R nn, SET LOG log_option where log_option is NORMAL or VERBOSE.
Starting Components The START command causes iWave Director to start componentsClients, Servers, and Agentsthat are defined in the configuration file (ddname SDMCONFG). The format of the command is as follows: R nn, START component_type component_name where: component_type is one of the following: - CLIENT (or CLIAPP or C) - SERVER (or SERVICE or S) - AGENT (or A) component_name is the name of the Client, Server, or Agent as defined in the configuration file
Stopping Components The STOP command causes iWave Director to stop componentsClients, Servers, and Agentsthat are defined in the configuration file (ddname SDMCONFG). The format of the command is as follows: R nn, STOP component_type component_name where: component_type is one of the following: - CLIENT (or CLIAPP or C) - SERVER (or SERVICE or S) - AGENT (or A) component_name is the name of the Client, Server, or Agent as defined in the configuration file
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 130 of 276
Cycling Components The CYCLE command causes iWave Director to stop and then restart running componentsClients, Servers, and Agentsthat are defined in the configuration file (ddname SDMCONFG). If the component is defined in the configuration file but not running, iWave Director starts the component. When you modify mapping or processing files, stop and restart only the affected components; leave iWave Director running. The format of the CYCLE command is as follows: R nn, CYCLE component_type component_name where: component_type is one of the following: - CLIENT (or CLIAPP or C) - SERVER (or SERVICE or S) - AGENT (or A) component_name is the name of the Client, Server, or Agent as defined in the configuration file
Forcing Components to Stop The KILL command causes iWave Director to terminate active components immediately. Always issue the STOP command first; if the component remains active, issue the KILL command. The format of the command is as follows: R nn, KILL component_type component_name where: component_type is one of the following: - CLIENT (or CLIAPP or C) - SERVER (or SERVICE or S) - AGENT (or A) component_name is the name of the Client, Server, or Agent as defined in the configuration file
Securing Userids and Passwords with the iwpasswd Utility

Several iWave Adapters require the use of userids and passwords to log into the local vendor application. You can encrypt such userids and passwords so that only iWave and authorized users have access to their plaintext values. The iWave encryption tool is the iwpasswd command line utility, available on Linux, UNIX, and Windows. The syntax of this utility is as follows: iwpasswd action entry_address
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 131 of 276
where: action is one of the following: - a (adds an entry) - m (modifies an entry) - d (deletes an entry) - l (lists all entries) - t (tests an entry) entry_address is the address of the entry, with format filepath.entryname, where filepath is the absolute pathname of the file containing encrypted values, and entryname is the name assigned to the specific value to be added, modified, deleted, or listed.
A maintenance password is created automatically when a new file is specified in the filepath portion of the entry_address with iwpasswd. The entryname for the maintenance password is root and the value associated with this entryname must be supplied before anything in the file can be added, modified, deleted, or listed. When a new file is used with iwpasswd the user is prompted to enter a value for the root entryname. After the first time, anytime anyone attempts to add, modify, delete, or list entries from the file they must supply the value set when the file was first created. The value associated with root can be changed after the first time by running iwpasswd m and specifying the entry_address with the filepath for the intended file, and the entryname of root. For example, a typical session to create two iWave Encrypted Data Values named MOMUID and MOMPWD in a file named iwpasswd in the directory /PROGRA~1/SKYWIR~1/IWAVEI~1/config might look like the following. $ iwpasswd a /PROGRA~1/SKYWIR~1/IWAVEI~1/config/iwpasswd.MOMUID Enter access code: enter the value associated with root Enter value for MOMUID: ****** Reenter value for MOMUID: ***** $ iwpasswd a /PROGRA~1/SKYWIR~1/IWAVEI~1/config/iwpasswd.MOMPWD Enter access code: enter the value associated with root Enter value for MOMPWD: ****** Reenter value for MOMPWD: ***** To now inform the iWave adapter for XML Web Services that it should refer to this iWave Encrypted Data Values file to get values, you can modify the sdserver.ini file agent section as follows. [XMLAG] ... IWAVEXMLURL=http://IWAVEMOMSRV:1271/ConnectorServicev2.asmx USERID=@/PROGRA~1/SKYWIR~1/IWAVEI~1/config/iwpasswd.MOMUID PASSWORD=@/PROGRA~1/SKYWIR~1/IWAVEI~1/config/iwpasswd.MOMPWD ... Furthermore, MOMUID and MOMPWD (in this case) could also be used in LOCALUSERID and LOCAL-PASSWORD in the client and server processing files. [Base] ...
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 132 of 276
LOCAL-USERID:@/PROGRA~1/SKYWIR~1/IWAVEI~1/config/iwpasswd.MOMUID LOCALPASSWORD:@/PROGRA~1/SKYWIR~1/IWAVEI~1/config/iwpasswd.MOMPWD ... The @ (at symbol) at the beginning of the entry_address is used by the iWave Adapters and iWave EXITs to recognize that the value for these keywords is not a user ID or password, but is instead a reference to an entry in an iWave Encrypted Data Values file.
This tool is only intended to help the user to hide user and password information that
NOTE would otherwise exist in plain text in the iWave configuration, processing, or mapping
file. It is not intended to be a replacement for normal security measures.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 133 of 276
Part IV Appendixes, Glossary and Index
A
Processing and Mapping Files
This appendix describes the processing and mapping files. Use this information for reference to edit processing and mapping files manually. Descriptions in this appendix refer to Figure 29, which shows the relationship between iWave Integrators A and B.
Figure 29 iWave Integrator Connection
Sections in the Processing and Mapping Files

A processing or mapping file is composed of a series of sections: A single Base section defines the file as a whole Embedded within the Base section are one or more Object Class sections
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 135 of 276
Embedded within each Object Class section are one or more Verb sections Embedded within each Verb section are zero or more Verb Qualifier sections
The processing and mapping files have the same basic structure (Figure 30).
Figure 30 Structure of Files An outline of a file is as follows: Begin Base; Begin Object Class /PROBLEM/; Begin Verb /CREATE/; End Verb; /CREATE/ Begin Verb /UPDATE/; Begin Verb_Qualifier /CLOSED/; End Verb_Qualifier; /CLOSED/ Begin Verb_Qualifier /REOPENED/; End Verb_Qualifier; /REOPENED/ End Verb; /UPDATE/ End Object Class; /PROBLEM/ Begin Object Class /CALL/; Begin Verb /CREATE/; End Verb; /CREATE/ Begin Verb /UPDATE/; End Verb; /UPDATE/ End Object Class; /CALL/ End Base; Begin and End statements bracket each section. The following statements bracket the file: Begin Base; End Base; Each Begin statement (other than Begin Base;) contains a section name delimited by a forward slash (/). Each End statement (other than End Base;) may show a section name, but only after the ending semicolon. In the case of an Object Class or Verb Qualifier section, you define the section name.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 136 of 276
Examples are as follows: Begin Object Class /PROBLEM/; End Object Class; /PROBLEM/ In the case of a Verb section, you assign one of the following predefined names: Create Create-Unique Lock Retrieve Search Unlock Update
On a given iWave Integrator, each section in the Client processing file must have a matching section in the Client mapping file. Similarly, each section in the Server processing file must have a matching section in the Server mapping file. No error occurs if you include extra sections in a mapping file, but it is recommended that you avoid doing so. Information that appears in an embedding section is said to propagate if the scope of that information extends to the embedded sections. The embedded sections are said to inherit the propagated information. An embedding section is said to be superior to the embedded sections, and the embedded sections are said to be subordinate. At any given point in transaction processing, an iWave Integrator uses the following: One and only one processing-file section, called the active section One and only one mapping-file section, also called the active section
The active section is always a Verb or Verb Qualifier section. During a transaction, the following occurs: On the local iWave Integrator, the active section of the Client processing file accesses the active section of the Client mapping file On the remote iWave Integrator, the active section of the Server processing file accesses the active section of the Server mapping file
Purpose of the Sections in a Processing File

The purposes of the processing-file sections are as follows: The Base section includes keywords that are meaningful for any transaction data; keyword MAPFILE, for example, tells where the mapping file resides.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 137 of 276
On the Client, the Base section often includes keyword SERVER-APP, which identifies the Server to which you are sending transaction data. In a manually edited processing file, each Object Class section includes keywords that affect the data belonging to a particular object class, which is a collection of data fields. The data belonging to one object class might define a problem report; the data belonging to another object class might define a sales call. An Object Class section often includes the following: Keyword TABLE-NAME, which identifies the primary tablethe main database table being accessed in a given transaction on a given iWave Integrator One or more SUB-TABLE keywords, each of which identifies a subtablea database table other than the primary table, but usually related directly to the primary table
Each Verb section includes keywords and assignment statements that are in use only when the iWave Integrator is processing a specified verb, which is a predefined transaction type such as UPDATE. For further details, see Verbs on page 41. Each Verb Qualifier section includes keywords and assignment statements that are in use only when the iWave Integrator is processing a specified verb qualifier, which is a transaction subtype that you define for processing data in a special way. For further details, see Verb Qualifiers on page 47.
Purpose of the Sections in a Mapping File
The purposes of the mapping-file sections are as follows: The Base section defines the file as a whole; this section should include no information. Each Object Class section contains mapping statements that are meaningful for processing a given object class; in manually edited mapping files, this section is the only one with any information. Each Verb or Verb Qualifier section contains mapping statements that are not in the Object Class section and are used by the equivalent Verb or Verb Qualifier section in a processing file.
Verb Processing and Active Sections

When editing mapping and processing files manually, you need to know what file sections are active during the processing of each of the verbs described in Verbs on page 41.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 138 of 276
In relation to verbs Create, Update, Lock, Unlock, and Retrieve, the active section in the Client processing and mapping files on Client A (see Figure 29 on page 135) is the same as the active section in the Server processing and mapping files on the Server B. The section is either (a) the Verb section named for the verb being processed or (b) a Verb Qualifier section subordinate to that Verb section. If you use a Verb Qualifier section for Create, Update, Lock, Unlock, or Retrieve, the same-named Verb Qualifier section must be in the Client processing and mapping files on Client A and on the Server processing and mapping files on Server B. Identifying the active section is more complex in relation to the other two verbsCreateUnique and Search.
Create-Unique In relation to verb Create-Unique, the active section in the Client processing and mapping files on Client A is Verb section Create-Unique or a subordinate Verb Qualifier section. The same active section is in use when the transaction begins and during postprocessing update. On the remote iWave Integrator, the active section during a database search is also Verb section Create-Unique or a subordinate Verb Qualifier section. When the iWave Integrator begins to update or create a record, however, the active section on Server B not on Client Ais Verb section Create or Update, as appropriate, or a subordinate Verb Qualifier section. If you are using a verb qualifier, Verb Qualifier sections must exist and have the same name in all of the following: Subordinate to the Verb section Create-Unique in the Client processing and mapping files on Client A. Subordinate to the Verb section Create-Unique in the Server processing and mapping files on Server B. Subordinate to the Verb section Create in the Server processing and mapping files on Server B. Subordinate to the Verb section Update in the Server processing and mapping files on Server B.
Search In relation to verb Search, the active section in the Client processing and mapping files on Client A is Verb section Search or a subordinate Verb Qualifier section, regardless of whether a record is retrieved during Search processing. Between the time when the Server receives a Search transaction and when the search is complete, the active section in the Server processing and mapping files on Server B is Verb section Search or a subordinate Verb Qualifier section. When the Server begins to execute a Retrieve of a single found record, the active section in the Server processing and mapping files on Server B is Verb section Retrieve or a
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 139 of 276
subordinate Verb Qualifier section. That section specifies what data model fields are sent back to the Client. If you are using a verb qualifier, Verb Qualifier sections must exist and have the same name in all of the following: Subordinate to the Verb section Search in the Client processing and mapping files on Client A. Subordinate to the Verb section Search in the Server processing and mapping files on Server B. Subordinate to the Verb section Retrieve in the Server processing and mapping files on Server B; but only if the Client-side keyword RETRIEVE-ONE-HIT is set to YES in Verb section Search in the Client processing file on Client A.
Statements in Processingand Mapping Files

A statement is a series of characters beginning with a reserved word and ending with a semicolon (;). Spaces at the beginning of a statement are ignored, and a statement may span multiple lines. Types of statements are as follows: Begin and End statements, as described on page 135. They appear in both mapping and processing files. Keyword statements, which are described in detail in the iWave Integrator Keyword Reference. They appear in processing files, with keyword TRANSLATE-FIELD appearing in some manually written mapping files. Each keyword statement has the following syntax: keyword:value; Assignment statements, as described in the next section. They appear only in processing files. Mapping statements, as described on the next page. They appear only in mapping files.
Every line in a processing or mapping file is part of a statement, with one exceptiona comment is a line in which the first column contains an asterisk (*). If a space precedes the asterisk, the line is not a comment. A comment can appear in either a mapping or processing file and is not meaningful at runtime.
Assignment Statements An assignment statement has the following syntax:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 140 of 276
data_model_field=value; where: data_model_field may be mapped or unmapped. value can be any of the following: An iWave Integrator constant, as described in iWave Integrator Constants on page 150. System variable #EXIT#, which executes a program that returns a value; or details, see #ERROR-TEXT# on page 69. A reference to another system variable, data model field, database field, or keyword, as described in Referencing Data Values on page 152.
To specify an assignment statement that executes only if an expression evaluates to TRUE, use keyword SET-VALUE-IF. Assignment and SET-VALUE-IF keyword statements appear only in a Verb or Verb Qualifier section of a processing file. An unmapped data model field can be declared only by assigning a value to it in an assignment statement or in keyword SET-VALUE-IF. Assignment statements, SET-VALUE-IF keyword statements, and unmapped data model fields never propagate to subordinate sections.
Mapping Statements A mapping statement has the following syntax: data_model_field=%vendor_field%; where: data_model_field is the name of the data model field being mapped. vendor_field is the name of the vendor field that corresponds to the data model field. If vendor_field is the name of a database field, vendor_field may refer to a field in the primary table or in a subtable. To refer to a field in a subtable, do the following: - Prefix the field name with the subtable name and a subtable delimiter, which separates the subtable name from a field name. The following mapping statement, for example, maps data model field X_CITY to field CITY in subtable ZIP_CODE_TABLE: X_CITY=%ZIP_CODE_TABLE.CITY%; To set a subtable delimiter different from a period (.), set keyword SUBTABLE_DELIMITER.
Depending on the vendor application, the vendor field may contain special characters such as vertical bars, question marks, and others. Some vendors may have field names that contain many special characters. These special characters
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 141 of 276
are part of the vendor field name that you map and have no special significance to iWave Integrator. Special considerations are in effect for timestamp and personal-name fields: The simplest mapping-file entry for a timestamp field has the following format, where the timestamp mask is delimited by two vertical bars: dmf_name=|timestamp_mask|%vendor_field%; The data model field may be mapped to two vendor fields, in which case each combination of mask and vendor field is separated from the next by a comma, as in the following example: a_datetime=|%m/%d/%y|%the_date%,|%H:%M:%S|%the_time%; When building mapping statements for timestamp fields, follow the examples provided to you in the example mapping files. For details on timestamp masks, see Timestamp Fields on page 61. In your processing files, use keyword TIMESTAMP-FIELDS to identify data model fields that contain timestamp data. The simplest mapping-file entry for a personal-name field has the following format, where the personal-name mask is delimited by two vertical bars: dmf_name=|personal_name_mask|%vendor_field%; The data model field is often mapped to two or (at most) three vendor fields, in which case each combination of mask and vendor field is separated from the next by a comma, as in the following example: a_name=|%l|%last_name%,|%f|%first_name%,|%m|%mid_init%; When building mapping statements for personal-name fields, follow the examples provided to you in the example mapping files. For details on personal-name masks, see Personal-Name Fields on page 62. In your processing files, use keyword PERSONAL-NAME-FIELDS to identify data model fields that contain personal-name data. Finally, special considerations are in effect when processing freeform text fields for SQL iWave Integrators or for iWave Integrators that support Clarify. For details, see the entries for the following keywords in the iWave Integrator Keyword Reference: CFY-TEXT, and SQL-TEXT.
Inheritance
Some of the information that is available in the active section does not appear in that section, but is inherited when the iWave Integrator starts. In general (but not always), the settings in any section are inherited by its subordinate sections. When the iWave
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 142 of 276
Integrator starts, the settings in the mapping and processing files are combined (Figure 31).
Figure 31 Structure of Processing and Mapping Files In particular, items of the following type are inherited by default: Most keywords All mapped data model fields
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 143 of 276
Assignment statements can appear only in a processing file and are not inherited. The keywords INCLUDE and EXCLUDE are not inherited, but each allows you to control which mapped data model fields are present in the section in which the keyword appears. A section cannot include both keyword INCLUDE and EXCLUDE, and neither keyword affects unmapped data model fields because those fields are never inherited. In some cases, ordering is important. The position of inherited items in the active section precedes the position of items inherited from a superior section, and the position of items within a section is in item order. In the following subset of a mapping file, for example, if the active section is Verb Qualifier section ONE, the order of data model fields is dmf_1, dmf_2, dmf_3, dmf_4, dmf_5, dmf_6: Begin Object Class /PROBLEM/; mapped_dmf_5=%vendor_field_5%; mapped_dmf_6=%vendor_field_6%; Begin Verb /CREATE/; mapped_dmf_3=%vendor_field_3%; mapped_dmf_4=%vendor_field_4%; Begin Verb Qualifier /ONE/; mapped_dmf_1=%vendor_field_1%; mapped_dmf_2=%vendor_field_2%; End Verb Qualifier; /ONE/ End Verb; /CREATE/ End Object Class; /PROBLEM/
Keyword INCLUDE The keyword INCLUDE identifies mapped data model fields that are inherited from superior sections. The default setting is the system variable #ALL#, which means that all mapped data model fields are inherited. Data model fields that are missing from the setting of keyword INCLUDE are not inherited. Consider the following subset of a processing file: Begin Object Class /PROBLEM/; : Begin Verb /CREATE/; : INCLUDE:(STATUS,PRIORITY); End Verb; /CREATE/ End Object Class; /PROBLEM/ The Verb section Create has only the following mapped data model fields: Data model fields that are defined in Verb section Create STATUS and PRIORITY, which if not present in Verb section Create are inherited from superior sections
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 144 of 276
Keyword EXCLUDE The names of mapped data model fields listed explicitly in the setting of keyword EXCLUDE are no longer part of the section in which the keyword appears, whether those names are inherited from a superior section or are specified in the section itself. If you specify the system variable #ALL# as part of the setting of keyword EXCLUDE, the keyword does the following: Prevents the inheritance of all mapped data model fields from a superior section Has no effect on mapped data model fields that are specified in the section itself
You may mix data model names and the system variable #ALL#. Consider the following subset of a processing file: Begin Base; Begin Object Class /PROBLEM/; : Begin Verb /CREATE/; : EXCLUDE:(#ALL#,STATUS); End Verb; /CREATE/ End Object Class; /PROBLEM/ End Base; The following are unavailable in Verb section Create: Mapped data model fields defined in superior sections, except those redefined in Verb section Create Mapped data model field STATUS
Value Assignments Across Data Types

This section details the effects of assigning the value of a data model field of one type to a data model field of another type. A distinction is necessary between the following: Assignments that occur after a database readfor example, on the Client at the beginning of a Create-Unique transaction. Assignments that occur before a database writefor example, on the Server during a Create-Unique transaction or on the Client during the post-processing update of any transaction.
In relation to assignments that occur after a database read, the value in the source data model field is in a database-specific format. If the source data model field is a timestamp or personal-name field, a mask helped to structure the value of that field (a date, for example, could be 1/1/2008 or 1 January 2008). The steps for an assignment are as follows:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 145 of 276
When all assignments occur on the iWave Integrator, the value in the source data model field is transferred to the target data model field. When all conversions to a data model format occur on the iWave Integrator, the value in the target is converted to a data-type-specific iWave Integrator format, as described in iWave Integrator Data Types on page 59.
In relation to assignments that occur before a database write, the value in the source data model field is in a data-type-specific iWave Integrator format, as described in iWave Integrator Data Types on page 59. The steps for an assignment are as follows: When all assignments occur on the iWave Integrator, the value in the source data model field is transferred to the target data model field. When all conversions to a database format occur on the iWave Integrator, the value in the target is converted in memory to a database format. If the target data model field is a timestamp or personal-name field, a mask guides the conversion.
NOTE character field.
Using a quoted literal as the source of an assignment is equivalent to using a
Topics are as follows: Assigning to Field with Different Syntax on page 146. Assigning Character Data to a Freeform Text Field on page 146. Assigning Freeform Text Data to a Character Field on page 147. Assigning an Additional Entry to a Freeform Text Field on page 147.
Assigning to Field with Different Syntax Any data model field may be assigned to a character field. Only a character field may be assigned to a freeform text field. No other assignments are allowed between fields with unlike syntax.
Assigning Character Data to a Freeform Text Field The rules for assigning character data to a freeform text field are the same whether the assignment occurs after a database read or before a database write. In the following assignment statement, the value of character field COMMENT is assigned to a freeform text field PROBLEM_INFO (the @ notation references the data model value): PROBLEM_INFO=@COMMENT@
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 146 of 276
iWave Integrator does the following: Eliminates any data already in freeform text field PROBLEM_INFO. Creates a single entry in the freeform text field. Assigns the value of system variable #NOW# to the timestamp component of that entry. Assigns the setting of keyword TEXT-USERID into the user ID portion of the entry. If keyword TEXT-USERID is not defined, iWave Integrator uses the setting of keyword LOCAL-USERID. If neither keyword is defined, iWave Integrator uses the value iWave_Integrator. Assigns the value of the character field to the text of that entry.
Assigning Freeform Text Data to a Character Field The rules for assigning freeform text data to a character field are the same whether the assignment occurs after a database read or before a database write. In the following assignment statement, the value of freeform text field PROBLEM_INFO is assigned to a character field COMMENT: COMMENT=@PROBLEM_INFO@ The character fields retain a concatenation of the comment data with added spaces, but does not retain the user ID or timestamp. For example, assume that each of the entries in freeform text field PROBLEM_INFO consists of a 6-character user ID (A_USER, B_USER, or C_USER); a timestamp that ends with +500; and a text entry: A_USER2005010100000/+500HELLO B_USER2005010200000/+500AND C_USER2005010100000/+500GOODBYE iWave Integrator adds a space between each entry and causes the character field COMMENT to contain the following: HELLO AND GOODBYE
Assigning an Additional Entry to a Freeform Text Field Freeform text fields contain a series of entries, each of which is composed of a user ID, a timestamp, and text lines. In previous assignment examples in this chapter, the assigned data replaced any entries contained in the freeform text field. Sometimes, you may want to keep the existing entries and use an assignment statement to append an additional entry to the entries already in the freeform text field. To append an entry to a freeform text field, you first reference that same freeform text field in the assignment. For example, in the following assignment statement, the value of freeform text field PROBLEM_INFO is assigned to the freeform text field PROBLEM_INFO: PROBLEM_INFO=@PROBLEM_INFO@ comment;
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 147 of 276
Following the data-model reference @PROBLEM_INFO@ in this example, comment includes whatever data you want to include in the text lines of the appended freeform text entry. iWave Integrator does the following: Preserves any data already in freeform text field PROBLEM_INFO. All existing freeform text entriestheir user IDs, timestamps, and text linesare preserved unchanged, as is their ordering. Appends the new freeform text entry at the end of all other entries in the freeform text field PROBLEM_INFO. iWave Integrator creates the entry as follows: User IDAssigns the setting of keyword TEXT-USERID into the user ID portion of the appended entry. If keyword TEXT-USERID is not defined, iWave Integrator uses the setting of keyword LOCAL-USERID. If neither keyword is defined, iWave Integrator uses the value iWave_Integrator. TimestampAssigns the value of system variable #NOW# (the current time) to the timestamp component of the appended entry. Text linesAssigns any data specified after @PROBLEM_INFO@ to the text lines portion of the new entry.
iWave Integrator can place different kinds of character data into the text lines of the new entry: one or more character strings; references to character, timestamp, personal-name, or freeform text fields; references to keywords or system variables; or any combination of these. iWave Integrator follows rules for formatting the spacing and line breaks in the text lines; these rules are described later in this section. To improve the formatting of the text lines, you can use the new line sequence \n between the items you want included in the new entry, but read the sections that follow describing how iWave Integrator handles formatting first. If you are unfamiliar with these rules, adding the new line sequence \n can produce an unwanted blank line, because iWave Integrator may already insert line feeds where you want them. iWave Integrator converts data model field (@) references depending on the context in which the assignment is performed: after database read (post-Retrieve in a Client) or before database write (post-process Update in a Client; Create and Update in a Server). References to system variables are consistent for both contexts.
@ Reference to Freeform Text Data Model Field When you create a new freeform text entry through an assignment statement, you can include entries from other freeform text fields in the text lines of the new entry. For example, after the first data-model-field reference, @PROBLEM_INFO@, the following assignment statement includes a reference to another freeform text data model field, @COMMENT_HISTORY@: PROBLEM_INFO=@PROBLEM_INFO@ @COMMENT_HISTORY@; iWave Integrator copies each text line from each entry in freeform text field @COMMENT_HISTORY@ into a separate text line in the new entry. Text lines from @COMMENT_HISTORY@ are preserved unchanged. iWave Integrator does not copy user IDs and timestamps.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 148 of 276
If there are any strings or other referenced fields before or after the freeform text field reference (@COMMENT_HISTORY@), iWave Integrator places them on separate lines from the referenced data model field. As a result, you do not need to add the line feed sequence \n before freeform text field (@) references to separate the freeform text lines from the other data in the assignment statement. This action is identical in both after database read and before database write contexts. In summary, the first entry and all other entries from a referenced freeform text field
NOTE each start on a new line. The data immediately following these entries (if any) starts
on a new line.
@ Reference to Non-Freeform Text Data Model Field After database read, the values iWave Integrator copies from non-freeform text fields are vendor field values, not data model values. Thus, vendor field values are used for personal-name fields and timestamp fields, not the data model equivalents. For vendor fields referenced by keyword TRANSLATE-FIELD, the vendor field values are used; translations occur after all assignments are made. If the referenced data model field has character syntax and has multiple vendor field values, iWave Integrator copies the first value to the current text line and copies each succeeding value to a new text line. When an @ reference is to a character field and the referenced field has multiple values, iWave Integrator copies each value except the first to a new text line. To copy the first value into a new text line, precede the @ reference with the line feed sequence \n. Before database write, the values iWave Integrator copies from non-freeform text fields are data model values. For vendor fields referenced by keyword TRANSLATE-FIELD, the data model values are used; translations occur after all assignments are made. If the referenced field has multiple data model values, iWave Integrator copies the first value to the current text line and copies each succeeding value to a new text line.
Reference to #ERROR-TEXT# Keyword If the error text has multiple values, iWave Integrator copies the first value to the current text line and copies each succeeding value to a new text line. To copy the first value into a new text line, precede the #ERROR-TEXT# reference with the line feed sequence \n. The action is identical for both after database read and before database write contexts.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 149 of 276
B
Syntax Rules
Syntax Rules
The following pages describe syntax used when defining transactions. Topics are as follows: iWave Integrator Constants on page 150 Referencing Data Values on page 152 Keywords whose Settings can be Referenced on page 153 Relational Expressions on page 154 Timestamp Masks on page 155 Personal-Name Masks on page 160 For details on additional syntax used when manually editing the processing and mapping files, see the iWave Integrator Users Guide.
iWave Integrator Constants

In some cases a value in a keyword statement or assignment statement includes an iWave Integrator constant, which is enclosed in double quotes (") and may contain any printable character. To accommodate a double-quote character as part of a constant, immediately precede the double-quote character with a backslash character (\"). For example, the value of "constant" is as follows:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 150 of 276
Constant But the value of "\"constant" is as follows: "constant Within a constant, a string delimited by # or @ is interpreted as having a substitution value rather than being a literal, and iWave Integrator substitutes the value into the constant before using the constant in a transaction. A character preceded by backslash (\), however, is itself part of the constant and no substitution occurs. For example, if the value of data model field STATUS is A, the following statements are true: The value of "status: @STATUS@" is this: status: A The value of "status: \@STATUS\@" is this: status: @STATUS@
The following statements are always true: The value of "\@" is this: @ The value of "\\@" is this: \@
The character \ in a constant has no special meaning except when the character immediately precedes one of these: ", #, and @. The character # in a constant may appear as part of any system variable other than #ALL#, #EXIT#,# or #NULL#,# and may delimit any of the following: One of the keywords listed in Referencing Data Values on page 152 A keyword that resolves to one of these: A literal A reference to a data model field
To split a constant across several lines in a processing file, enclose each substring in quotes. Consider this assignment statement, for example: DMFIELD="This is a long and cumbersome constant"; The following is equivalent: DMFIELD="This is a " "long and cumbersome " "constant"; Include only spaces or tabs between constants that form a larger constant. Using an
NOTE intervening character other than a space or tab causes an error.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 151 of 276
You can define line feeds in assignment statements by including the characters \n in the assignment, for example: DMFIELD1="Text sub carriage return \nNext Line"; The following keyword statement shows a constant syntax: NOW-MASK:"%I:%M:%S%p %d/%m/%Y";
Referencing Data Values

In some cases, keywords or data model assignments refer to data-model-field values, vendor-field values, system variables, or the settings of other keywords: To reference the value of a data model field, delimit the name of that field within at signs (@). If, for example, the string John Martin is in the data model field MY_FIELD, the following also has the value John Martin: @MY_FIELD@ To reference the value of a system variable other than #EXIT#, use the system variable name. For a list, see the iWave Integrator Users Guide chapter System Variables. To reference the setting of a keyword, delimit the keyword itself within pound signs (#). You can do so only if the keyword appears in the list shown in Keywords whose Settings can be Referenced on page 153. Assume, for example, that keyword LOCAL_USERID is set to SOLVE_01, as shown: LOCAL-USERID:SOLVE_01; You can use the setting of keyword LOCAL_USERID in this way: TRANSLATE-FIELD:PROBLEM_STATUS, VALUES(Active:#NULL#, #LOCAL-USERID#:"USER_01"); Here, on reading the database, iWave Integrator translates a null vendor value to the data model value Active and translates a vendor value USER_01 to the data model value SOLVE_01. If the setting of a referenced keyword is itself a reference, the value obtained is the setting referenced by the referenced keyword; that is, multiple levels of indirection are allowed. Circular references are not allowed.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 152 of 276
Keywords whose Settings can be Referenced

Following are the keywords whose settings can be referenced by use of pound sign (#) delimiters:
iWave Software
Revised [03/01/07] P01-664-09
API-ELAPSED-TIME API-MODULE APPLICATION-NAME AUTO-ACCEPT CFY-LOG-FILENAME DATA-MODEL-RECORDS DB-SERVER-NAME DB-SERVER-PORT DB-SESSION-ID DELETE-EVENT-REC DUMMY-OBJID ECI-CUST-ID EVPSWD EVUSER FFT-CVTFMT FFT-XLATE FIELD-SEPARATOR FIELD-VALIDATION HISTORY-TEXT-END-TIMESTAMP HISTORY-TEXT-TOP-TIMESTAMP LANGUAGE LOCAL-OBJECT-ID-SEPARATOR MAX-TEXT-LENGTH OBJECT-ID-RETRIEVE-MODE PERSONAL-NAME-CVTFMT PPI-DEST-ADDRESS PPI-QUEUE-SIZE PPI-SOURCE-ADDRESS PRIVILEGE-INIT RETRIEVE-OBJECT-ID SEQNUM-FILENAME SEQNUM-ROLL-AT SEQNUM-ROLL-TO SESSION SQL-PREFIX SQL-SUFFIX TABLE-ID TABLE-OWNER TEXT-RECORD-COUNT
TEXT-RECORD-LENGTH TEXT-REPLACE TIMEOUT-INTERVAL TIMESTAMP-CVTFMT TRAN-FIELD-COUNT
Relational Expressions
Some keyword statements contain an embedded relational expression: a statement that evaluates to TRUE or FALSE. The building blocks of a relational expression are as follows: One or more relationships: expressions that themselves evaluate to TRUE or FALSE and use this syntax: @data-model-field@ relational-operator comparison-value The Boolean operators AND and OR Parentheses that force an order of evaluation Some characteristics of a relationship are as follows: The value of the data model field must either be a string or be able to be converted into a string. The string equivalent of a number is valid; for example, "4.5" is the string equivalent of 4.5. iWave Integrator converts data model fields as follows: To convert the value in a freeform field to a string, iWave Integrator uses only the text portion of the freeform text field, with individual text lines concatenated; the user ID and timestamp are ignored. To convert the value in a timestamp field or personal-name field to a string, iWave Integrator uses the mask specified for the field as a guide to formatting the value, but the mask itself is not part of the string.
The relational operator must be one of the following. EQ (equal to) NE (not equal to) GT (greater than) LT (less than) GE (greater than or equal to) LE (less than or equal to) CONTAINS BEGINS-WITH
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 154 of 276
The comparison value must be a constant or the system variable #NULL#; constants are described in iWave Integrator Constants on page 150.
If different Boolean operators are necessary in a relational expression, use parentheses to create subexpressions in which only one Boolean operator type appears. Consider what is required to form an expression that reflects this logic: field A not equal to xyz, and either field B equals 3 or field B equals 4 or field B greater than 17. The following relational expression is valid: @A@ NE "xyz" AND (@B@ EQ "3" OR @B@ EQ "4" OR @B@ GT "17") The following relational expression is invalid because Boolean operators may not be mixed in a subexpression: @A@ NE "xyz" AND @B@ EQ "3" OR @B@ EQ "4" OR @B@ GT "17" Relationships are evaluated from left to right in a relational expression or subexpression.
Timestamp Masks
iWave Integrator uses a timestamp mask to determine how to copy date and time information between a vendor field and a timestamp field. When reading a vendor field that contains date or time data, iWave Integrator uses the timestamp mask as follows: iWave Integrator interprets the vendor-field value in accordance with the mask. iWave Integrator excludes vendor-field characters that are not mapped.
When writing a timestamp field to a database, iWave Integrator uses the timestamp mask to format the value in a way that is specific to the vendor application.
WARNING
If you are interacting with vendor fields that your vendor application treats as character data, follow the conventions that are in use at your location. If, however, you are interacting with fields that have special data types like DATE and TIME, you must follow the examples provided to you in the sample mapping files. In your processing files, use keyword TIMESTAMP-FIELDS to identify data model fields that contain timestamps.
Conversion Specifiers in Timestamp Masks A timestamp mask consists of the following: Ordinary characters.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 155 of 276
Conversion specifiers, which are symbols that refer to a value in the vendor field (during read) or in the data model field (during write). Those symbols transform the value to a format appropriate for the field receiving the data.
As shown in the following table, a conversion specifier consists of the character % followed by a letter. Conversion Specifier %b Description When iWave Integrator is reading from a database, the conversion specifier %b refers to a month name to be transformed into an equivalent integer. The setting of keyword MONTH-NAMES identifies which names are valid. When iWave Integrator is writing to a database, the conversion specifier %b refers to an integer to be transformed into an equivalent month name. The valid range is 1-12. %d The conversion specifier %d refers to a one- or two-digit day of the month. The valid range is 1 to 31. The conversion specifier %D refers to a three-digit day of the year. The valid range is 001-366. The conversion specifier %H refers to a one- or two-digit hour in a 24-hour clock. The valid range is 0-23. The conversion specifier %I refers to a one- or two-digit hour in a 12-hour clock. The valid range is 1-12. The conversion specifier %m refers to a one- or two-digit month. The valid range is 1-12. The conversion specifier %M refers to a one- or two-digit minute. The valid range is 0-59. When iWave Integrator is reading from a database, the conversion specifier %p refers to an AM or PM indicator characters that tell whether the hour in the field is a day or night hour. If %p refers to characters that are different from the setting of either the AM and PM indicator, iWave Integrator ignores the conversion specifier, as well as the unmapped characters. When assigning the vendor-field value to a data model field, iWave Integrator adds 12 to the number of hours if the following is true: The hour in the vendor field is less than 12. The conversion specifier %p appears in the timestamp mask, and the vendor-field value to which %p refers matches the value of the PM indicator.
%D %H %I %m %M %p
On writing to a database when the conversion specifier %p is in use, iWave Integrator uses the value of the AM or PM indicator to assign the appropriate indicator to the vendor field. Use the conversion specifier %p only when %I is specified; that is, only when the valid range of hours is 1 to 12.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 156 of 276
%S %C %U %y
%Y %f %T
The conversion specifier %S refers to a one- or two-digit second. The valid range is 0-59. %C refers to the standard UNIX internal timestamp (time_t), expressed as a variable-length string. %U refers to the standard UNIX internal timestamp (time_t), expressed as an 8-character string in hexadecimal format. The conversion specifier %y refers to a one- or two-digit year. When using the conversion specifier %y to read a two-digit year from a vendor field, iWave Integrator determines what century to include in the data model field by referring to the pivot year, which you with keyword PIVOT-YEAR. Two-digit years equal to or greater than the pivot year are assumed to be in the twentieth century; lower two-digit years are assumed to be in the twenty-first. The conversion specifier %Y refers to a four-digit year. The conversion specifier %f refers to 3-digit milliseconds and is available only with the timestr exit. The conversion specifier %T refers the the iWave version 5 transaction format: YYYYMMDDhhmmss/TZD where: YYYY is 4-digit year. MM is 2-digit month (January = 01, etc.) DD is 2-digit day of month (01 through 31) hh is 2-digit hour (00 through 23, a.m. and p.m. not allowed) mm is 2-digit minute (00 through 59) ss is 2-digit second (00 through 59) TZD is time zone designator (Z0000 or +hhmm or hhmm), sign indicates the amount by which local time must be adjusted to arrive at UTC The conversion specifier %1 refers to a subset of ISO 8601 format: YYYY-MM-DDThh:mm:ss.fTZD where: YYYY is 4-digit year. MM is 2-digit month (January = 01, etc.) DD is 2-digit day of month (01 through 31) hh is 2-digit hour (00 through 23, a.m. and p.m. not allowed) mm is 2-digit minute (00 through 59) ss is 2-digit second (00 through 59) f is one or more digits representing a decimal fraction of a second TZD is time zone designator (Z or +hh:mm or hh:mm), sign indicates the amount by which UTC must be adjusted to arrive at local time
%1
Figure 32 Conversion Specifiers in Timestamp Masks Consider the following when specifying masks for timestamp fields: If you are interacting with vendor fields that your vendor application treats as character data, follow the conventions that are in use at your location.
iWave Software
Revised [03/01/07] P01-664-09
If you are interacting with fields that have special data types like DATE and TIME, use the masks specified the processing-file samples provided with iWave Integrator.
If the vendor field first_date contains the string 1/1/2008 AD, the following timestamp mask tells iWave Integrator how to assign the equivalent value to a timestamp field: %m/%d/%Y In this example, iWave Integrator ignores AD.
Settings for SQL Interfaces There are some required formats for the SQL interfaces when interacting with DATE, TIME, and TIMESTAMP fields: Oracle A vendor field of TIMESTAMP type must be mapped using the mask: %m/%d/%Y %H:%M:%S A vendor field of DATE type must be mapped using the mask: %m/%d/%Y A vendor field of TIME type must be mapped using the mask: %H:%M:%S
ODBC A vendor field of TIMESTAMP type must be mapped using the mask: %Y-%m-%d %H:%M:%S A vendor field of DATE type must be mapped using the mask: %Y-%m-%d A vendor field of TIME type must be mapped using the mask: %H:%M:%S
Furthermore, these formats are not modifiable at the users discretion. Finally, if a freeform text field will be used and only one field is identified in the SQL-TEXT keyword for use in the TIMESTAMP portion of the freeform text, the timestamp in the data will be formed according to the NOW-MASK. If that field is a TIMESTAMP field, then you must define NOW-MASK with the mask identified above for a TIMESTAMP field. If that field is a DATE, then you must define NOW-MASK with the mask identified above for a DATE field. If that field is a TIME field, then you must define NOW-MASK with the mask identified above for a TIME field.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 158 of 276
If a freeform text field will be used and two fields are identified in the SQL-TEXT keyword for use in the TIMESTAMP portion of the freeform text, the date portion of the data will be formed according to the DATE-MASK and time portion according to the TIME-MASK. If that field is a TIMESTAMP field, then you must define NOW-MASK with the mask identified above for a TIMESTAMP field. If that field is a DATE, then you must define NOW-MASK with the mask identified above for a DATE field. If that field is a TIME field, then you must define NOW-MASK with the mask identified above for a TIME field.
You must ensure that the mapped field masks and the masks for NOW-MASK, DATEMASK, and TIME-MASK conform to these requirements. Suppose you have a TIMESTAMP field you are populating, but you only wish to populate either the DATE portion or the TIME portion. In this case, you must still provide both the date and the time portion of the timestamp in the mask, but you may fix the date or the time portion to a specific date or time (for example, masks of 01/01/2005 %H:%M:%S or %m/%d/%Y 00:00:00).
Settings for Other Interfaces The following are the required formats for other interfaces when interacting with DATE, TIME, and TIMESTAMP fields. Clarify A vendor field of TIMESTAMP type must be mapped using the mask: %m/%d/%y %H:%M:%S A vendor field of DATE type must be mapped using the mask: %m/%d/%y A vendor field of TIME type must be mapped using the mask: %H:%M:%S
ECI for MQ Series A vendor field of TIMESTAMP type must be mapped using the mask: %Y/%m/%d %H:%M:%S A vendor field of DATE type must be mapped using the mask: %Y/%m/%d A vendor field of TIME type must be mapped using the mask: %H:%M:%S
HP OpenView NNM A vendor field of TIMESTAMP type must be mapped using the mask: %m/%d/%y %H:%M:%S A vendor field of DATE type must be mapped using the mask: %m/%d/%y
iWave Software
Revised [03/01/07] P01-664-09
A vendor field of TIME type must be mapped using the mask: %H:%M:%S
Peregrine Service Center A vendor field of TIMESTAMP type must be mapped using the mask: %m/%d/%Y %H:%M:%S A vendor field of DATE type must be mapped using the mask: %m/%d/%Y A vendor field of TIME type must be mapped using the mask: %H:%M:%S
Remedy A vendor field of TIMESTAMP type must be mapped using the mask: %U
The following are SQL Interfaces and the permitted masks depend on their underlying database: McAfee HelpDesk (ODBC) Tivoli Service Desk (Oracle, ODBC)
Personal-Name Masks
iWave Integrator uses a personal-name mask to determine how to copy personal name data between a vendor field and a data model field. When reading a personal-name field from a vendor field, iWave Integrator uses the personal-name mask as follows: Interprets the value in accordance with the mask Excludes vendor-field characters that are not mapped
When writing a personal-name field to a database, iWave Integrator uses the personalname mask to format the value in a way that is specific to the vendor application. A personal-name mask consists of the following: Ordinary characters. Conversion specifiers,, which are symbols that do either of the following: Reposition and capitalize the strings during a database read so that the data model field value is in the iWave Integrator personal-name format. Reposition and translate the strings during a database write so that the vendor field values are as required in the vendor-application database.
iWave Software
Revised [03/01/07] P01-664-09
As shown in the following table, a conversion specifier consists of the character % followed by a letter. Conversion Specifier %a Description The conversion specifier %a refers to an additional name such as Jr. When the data is written to a vendor field, the first letter is uppercase and the rest are lowercase. The conversion specifier %A refers to an additional name such as III. When the data is written to a vendor field, all letters are capitalized. The conversion specifier %f refers to a first name. When the data is written to a vendor field, the first letter is uppercase and the rest are lowercase. The conversion specifier %F refers to a first name. When the data is written to a vendor field, all letters are capitalized. The conversion specifier %g refers to the initial of the first name. During a database read, if the vendor field contains more than one letter, only the first letter is placed in the data model field. During a database write, only the lowercase first letter of the first name or initial is placed in the vendor field. The conversion specifier %G refers to the initial of the first name. During a database read, if the vendor field contains more than one letter, only the first letter is placed in the data model field. During a database write, only the capitalized first letter of the first name or initial is placed in the vendor field. The conversion specifier %m refers to a middle name. When the data is written to a vendor field, the first letter is uppercase and the rest are lowercase. The conversion specifier %M refers to a middle name. When the data is written to a vendor field, all letters are capitalized. The conversion specifier %n refers to the initial of the middle name. During a database read, if the vendor field contains more than one letter, only the first letter is placed in the data model field. During a database write, only the lowercase first letter of the middle name or initial is placed in the vendor field. The conversion specifier %N refers to the initial of the middle name. During a database read, if the vendor field contains more than one letter, only the first letter is placed in the data model field. During a database write, only the capitalized first letter of the middle name or initial is placed in the vendor field. The conversion specifier %l (lowercase L) refers to a last name. When the data is written to a vendor field, the first letter is uppercase and the rest are lowercase. The conversion specifier %L refers to a last name. When the data is written to a vendor field, all letters are capitalized.
%A
%f
%F %g
%G
%m
%M %n
%N
%l
%L
Figure 33 Conversion Specifiers in Personal Name Masks
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 161 of 276
If several name elements (first, middle, last) are in a single vendor field, they must be separated by at least one ordinary character (not a conversion specifier), and that character or set of characters must always be present in exactly the same way in the vendor field for all records. The maximum length allowed for each name element is 255 characters. If a vendor field doctor_name contains J S Bach, II MD, the following personal name mask tells iWave Integrator how to assign the equivalent value to a data model field: %G %N %L,%A In this example, %G refers to J, the initial of the first name; %N refers to S, the initial of the middle name; %L refers to Bach, the last name; and %A refers to the additional name, II. iWave Integrator ignores MD.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 162 of 276
C
Transaction Processing
This appendix gives details on transaction processing, including aspects of inheritance, although inheritance is meaningful only if you are editing processing and mapping files manually. Reference is also made to keywords, subkeywords, and assignment statements as they appear in processing files. For details on processing and mapping files, see Appendix A, Processing and Mapping Files. For details on transaction exits and on how failure of a transaction exit affects subsequent processing, see keyword TRANSACTION-EXIT in the iWave Integrator Keyword Reference. That document is also the primary source of information on other processing-file keywords. The three stages of a transaction are as follows: 1. Data access by the local Client 2. Processing by the remote Server 3. Post-processing update by the local Client
Each stage includes one or more of the following phases: Search phase, during which the iWave Integrator searches for records that fulfill specified criteria. Read phase, during which the iWave Integrator reads from the primary table and, optionally, from one or more subtables. Write phase, during which the iWave Integrator writes to the primary table and, optionally, to one or more subtables.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 163 of 276
Stage 1: Data Access by the Local Client

The following phases occur before the Client sends data to the Server: Search phase, but only if the Client is in poll mode Read phase
Search Phase on the Client If keyword DETECTION-MODE is set to POLL, processing begins as follows, for each keyword POLL-CRITERIA in turn: Run the PRE-POLL transaction exits, if any. Run the search phase. Run the POST-POLL transaction exits, if any.
For the Client, the following is true of search phase: Occurs only if keyword DETECTION-MODE is set to POLL. Is the time between starting a poll and starting to retrieve data from the Is not part of a specific transaction: the Client may find several records during search phase, and each record is the basis of a transaction.
Keyword POLL-CRITERIA may include reference to a primary table and, at most, one subtable. If a subtable is referenced, a parameter in keyword SUB-TABLE indicates whether to search the subtable before or after the primary table. Before an iWave Integrator searches for a record, keyword TRANSLATE-FIELD converts a data-model-field value into the related vendor-field value if the data-modelfield value is used as a search criterion. For more information on search phase, see Understanding the Details of Search Phase on page 173.
Read Phase on the Client After search phase, if any, the Client does the following: Runs the PRE-TRAN transaction exits, if any. Runs the PRE-RETRIEVE transaction exits, if any.
At this point, iWave Integrator runs the read phase, which is the time between when the Client starts to access data from the vendor application and when the Client transmits data to the remote Server. On iWave Integrators that access a vendor-application database, the local Client does the following:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 164 of 276
Step 1. Reads the primary table and (except in the case of verb Lock or Unlock) places values in the data model fields that are mapped to the fields in the primary table. Step 2. Reads the values from the vendor fields identified in keyword EXT-OBJECT-ID, if any. Step 3. Except in the case of verb Lock or Unlock, reads the values from the vendor field identified in keyword TEXT-INDICATOR, if any. Step 4. Does the following for each keyword SUB-TABLE that is in or inherited by the active section of the Client processing file and that has a CONTEXT value that includes R (for read phase): 1. Searches the subtable for records that match the KEY and VALUE search criteria in keyword SUB-TABLE. 2. Reads the matching subtable records and places values into the data model fields that are mapped to that subtable and are listed in subkeyword FIELDS. Processing of keywords in the active section precedes processing of keywords inherited from a superior section, and processing within a section is in keyword order. Step 5. Except when processing verbs Lock and Unlock, the Client does the following regardless of whether the iWave Integrator accesses a database: 1. The Client evaluates TRANSLATE-FIELD keywords in the order in which the data model fields referenced in those keywords are defined in the mapping file. 2. The Client processes the following for unmapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to R (for read phase).
The order of processing of assignment and SET-VALUE-IF statements for unmapped data model fields is the order in which the data model fields were declared in the active section of the Client processing file. Unmapped data model fields are not inherited. 3. The Client processes the following for mapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to R (for read phase).
The order of processing of the assignment and SET-VALUE-IF statements for mapped data model fields is the order in which the fields appear in the active section of the Client mapping file, such that processing of statements for locally defined data model fields precedes processing of statements for inherited data model fields. Specifically, processing of statements for data model fields mapped in the Verb Qualifier section precedes processing of statements for data model fields mapped in the Verb section, and processing of statements from either
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 165 of 276
source precedes processing of statements for data model fields mapped in the Object Class section. 4. Next, the Client evaluates USE-KEYWORD-IF keywords for which subkeyword CONTEXT is set to R (for read); runs the POST-RETRIEVE transaction exits, if any; and converts timestamp fields, personal-name fields, and freeform text fields to the format in which they are sent to the Server. Step 6. If the iWave Integrator accesses a database and is not processing verb Lock or Unlock, the Client also removes from the transaction any freeform text entries that are associated with a time greater than the time stored in the local textindicator fields, which are the vendor fields to which the local keyword TEXTINDICATOR refers.
Stage 2: Processing by the Remote Server

The remote Server does the following: Step 1. Checks for a mismatch between the data type of a received, mapped data model field and the data type expected for that field. Step 2. Runs the PRE-TRAN transaction exits, if any. Step 3. Does the following if processing verb Create-Unique or Search: 1. Runs the PRE-VERB transaction exits, if any, for the search phase. 2. Runs the search phase. 3. Runs the POST-VERB transaction exits, if any, for the search phase. Step 4. Runs the read phase if verb Lock, Unlock, or Retrieve is being processed or if a retrieve occurs for verb Search; the read phase includes the PRE-VERB and POST-VERB transaction exits, if any. Step 5. Does the following if verb Create or Update is being processed or for the create or update phase of Create-Unique processing: 1. Runs the write phase, which includes the PRE-VERB transaction exits, if any. 2. Runs the POST-VERB transaction Exits, if any. Step 6. Runs one of the following, depending on whether the iWave Integrator return code is zero or non-zero: POST-TRAN-SUCCESS, POST-TRAN-FAILURE.
NOTE
An unusual characteristic of verbs Create-Unique and Search is the use of multiple active sections in the Server processing and mapping files, as described in Verb Processing and Active Sections on page 138.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 166 of 276
NOTE
When the Server runs two phases for a single verb, a different active section controls each phase, and the same type of TRANSACTION-EXITin particular, PRE-VERB and POST-VERBmay be present in a given active section for use only during the phase that the active section controls.
Search Phase on the Server On an iWave Integrator Server, search phase refers to either of the following: The period between receiving a Create-Unique transaction and beginning the write phase, whether for update or create. The period between receiving a Search transaction and completing the search.
In relation to verb Create-Unique, the search is for records that match the criteria specified by keywords UNIQUE-FIELDS, SEARCH-CRITERIA, and SEARCH-ALWAYS, as described in the entry for UNIQUE-FIELDS in the iWave Integrator Keyword Reference. In relation to verb Search, the search is for records that have the following characteristics: Match the data-model-field values of the record transmitted from the Client. Fulfills the setting of keyword SEARCH-CRITERIA on the Client, if that keyword is present. Fulfills the setting of keyword SEARCH-CRITERIA on the Server, if that keyword is present.
For more information on search phase, see Understanding the Details of Search Phase on page 173.
Read Phase on the Server For the Server, read phase is the time between retrieving data from the vendor application and transmitting a response to the Client. This phase is either of the following: The period between receiving a Lock, Unlock, or Retrieve transaction and responding to the Client. The period between completing the search phase of Search processing and responding to the Client, but only in the following case: The iWave Integrator Client sends a Search transaction with keyword RETRIEVE-ONE-HIT set to YES. Exactly one record is found during the search phase.
During read phase, the following occurs:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 167 of 276
Step 1. The Server runs the PRE-VERB transaction exits, if any Step 2. The Server reads the primary table and (except in the case of verb Lock or Unlock) places values in the data model fields that are mapped to those vendor fields; reads the values from the vendor fields identified in keyword EXTOBJECT-ID, if any; and, except in the case of verb Lock or Unlock, reads the values from the vendor field identified in keyword TEXT-INDICATOR, if any. Step 3. Does the following for each keyword SUB-TABLE that is in or inherited by the active section of the Server processing file and that has a CONTEXT value that includes R (for read phase): 1. Searches the subtable for records that match the KEY and VALUE search criteria in keyword SUB-TABLE. 2. Reads the matching subtable records and places values in the data model fields listed in subkeyword FIELDS. Processing of keywords in the active section precedes processing of keywords inherited from a superior section, and processing within a section is in keyword order. Step 4. The Server evaluates TRANSLATE-FIELD keywords in the order in which the data model fields referenced in those keywords are defined in the mapping file. Step 5. The Server processes the following for unmapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to W (for write phase) .
The order of processing of assignment and SET-VALUE-IF statements for unmapped data model fields is the order in which the data model fields were declared in the active section of the Client processing file. Unmapped data model fields are not inherited. Step 6. The Client processes the following for mapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to W (for write phase).
The order of processing of the assignment and SET-VALUE-IF statements for mapped data model fields is the order in which the fields appear in the active section of the Server mapping file, such that processing of statements for locally defined data model fields precedes processing of statements for inherited data model fields. Specifically, processing of statements for data model fields mapped in the Verb Qualifier section precedes processing of statements for data model fields mapped in the Verb section, and processing of statements from either source precedes processing of statements for data model fields mapped in the Object Class section. Step 7. The Server runs the POST-VERB transaction exits, if any; converts timestamp fields, personal-name fields, and freeform text fields to the format in which they are sent to the Client; and, except in the case of verb Lock or Unlock, removes (from the data being returned to the Client) any freeform text entries that are
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 168 of 276
associated with a time greater than the time stored in the local text-indicator fields, which are the vendor fields to which the local keyword TEXT-INDICATOR refers. Write Phase on the Server For the Server, writephase refers to either of the following: The period of Create-Unique processing between ending the search phase and sending a response to the iWave Integrator Client. The period between receiving a Create or Update transaction and sending a response to the iWave Integrator Client.
During write phase, the following occurs: Step 1. The Server receives data model fields from the iWave Integrator Client. Step 2. The Server begins a unit of worka period in which database changes are tentative, pending a commit orwhere supporteda rollback. Step 3. The Server processes the following for unmapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to W (for write phase).
The order of processing of assignment and SET-VALUE-IF statements for unmapped data model fields is the order in which the data model fields were declared in the active section of the Client processing file. Unmapped data model fields are not inherited. Step 4. The Server processes the following for mapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to W (for write phase).
The order of processing of the assignment and SET-VALUE-IF statements for mapped data model fields is the order in which the fields appear in the active section of the Server mapping file, such that processing of statements for locally defined data model fields precedes processing of statements for inherited data model fields. Specifically, processing of statements for data model fields mapped in the Verb Qualifier section precedes processing of statements for data model fields mapped in the Verb section, and processing of statements from either source precedes processing of statements for data model fields mapped in the Object Class section. Step 5. The Server evaluates TRANSLATE-FIELD keywords in the order in which the data model fields referenced in those keywords are defined in the mapping file. Step 6. The Server converts timestamp fields, personal-name fields, and freeform text fields to the format in which they are written to the vendor-application database.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 169 of 276
Step 7. The Server evaluates USE-KEYWORD-IF keywords for which subkeyword CONTEXT is set to W (for write). Step 8. The Server runs the PRE-VERB transaction exits, if any. Step 9. The Server eliminates data model fields that are null and specified in keyword NOCLEAR-FIELDS. Step 10. The Server processes each keyword SUB-TABLE for which the following is true: Subkeyword PFLAGS includes the setting PBEFORE either explicitly or by default. Subkeyword CONTEXT is set to W (for write phase).
Step 11. The Server creates or updates the primary-table record. Step 12. The Server processes each keyword SUB-TABLE for which the following is true: Subkeyword PFLAGS includes the setting PAFTER. Subkeyword CONTEXT is set to W (for write phase).
For further details, see Understanding the Last Steps of Write Phase on page 174. The unit of work ends at the end of write phase, after which the Server can run one or more transaction exits of one of the following types: POST-TRAN-FAILURE POST-TRAN-SUCCESS
Stage 3: Post-Processing Update

Post-processing update is equivalent to write phase on the Client and is the time between receiving a response from the Server and ending all processing except for the first optional transaction exit of the following type: POST-TRAN-ABORT POST-TRAN-FAILURE POST-TRAN-RECOVER POST-TRAN-SUCCESS
During write phase, the following occurs: Step 1. The Client retains access to mapped data model fields, which initially have the same values as were sent to the Server Step 2. The Client receives data model fields from the Server, possibly including fields whose values override values sent to the Server Step 3. The Client begins a unit of worka period in which database changes are tentative, pending a commit orwhere supporteda rollback.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 170 of 276
Step 4. The Client receives transaction return values and error text, which are available in system variables. Step 5. The Client ignores unmapped data model fields; those fields are processed before the Client sends data to the Server and are invisible during postprocessing update. Step 6. The Client processes the following for mapped data model fields: Assignment statements, optionally including system variable #EXIT#. SET-VALUE-IF keywords with CONTEXT set to W (for write phase).
The order of processing of the assignment and SET-VALUE-IF statements for mapped data model fields is the order in which the fields appear in the active section of the Client mapping file, such that processing of statements for locally defined data model fields precedes processing of statements for inherited data model fields. Specifically, processing of statements for data model fields mapped in the Verb Qualifier section precedes processing of statements for data model fields mapped in the Verb section, and processing of statements from either source precedes processing of statements for data model fields mapped in the Object Class section. If the Client receives multiple records during Search processing, no assignments
NOTE occur.
Step 7. The Client evaluates TRANSLATE-FIELD keywords in the order in which the data model fields referenced in those keywords are defined in the mapping file. Step 8. The Client determines the values to be written to the vendor fields identified in keywords ERROR-NUM-FIELD, ERROR-TEXT-FIELD, EXT-OBJECT-ID, and TEXT-INDICATOR. Step 9. The Client replaces values in data model fields as per the settings of keywords SUCCESS-CODES, FAILURE-CODES, RECOVER-CODES, SUCCESSFIELDS, FAILURE-FIELDS, and RECOVER-FIELDS. Step 10. The Client converts timestamp fields, personal-name fields, and freeform text fields to the format in which they are written to the vendor-application database. Step 11. The Client evaluates USE-KEYWORD-IF keywords for which subkeyword CONTEXT is set to W (for write phase). Step 12. The Client runs the PRE-UPDATE transaction exit. Step 13. The Client eliminates data model fields that are null and specified in keyword NOCLEAR-FIELDS. Step 14. The Client processes each keyword SUB-TABLE for which the following is true: Subkeyword PFLAGS includes the setting PBEFORE either explicitly or by default.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 171 of 276
Subkeyword CONTEXT is set to W (for write phase).
Processing of keywords in the active section precedes processing of keywords inherited from a superior section, and processing within a section is in keyword order. Step 15. The Client creates or updates the primary-table record. Step 16. The Client processes each keyword SUB-TABLE for which the following is true: Subkeyword PFLAGS includes the setting PAFTER. Subkeyword CONTEXT is set to W (for write phase).
Processing of keywords in the active section precedes processing of keywords inherited from a superior section, and processing within a section is in keyword order. Step 17. The Client runs the POST-UPDATE transaction exits. Step 18. The unit of work ends. If the Client receives multiple records during Search processing, the following steps
NOTE occur once for each recordStep 2 through Step 5, and Step 7 through Step 18.
After write phase, the Client can run one or more transaction exits of one of the following types: POST-TRAN-ABORT POST-TRAN-FAILURE POST-TRAN-RECOVER POST-TRAN-SUCCESS
If a transaction is successful, data model fields that are mapped on the Client and are returned from the Server are written to the database. That writing occurs automatically only if the transaction is successful. A data model field that is mapped on the Client but is not returned from the Server is written to the database only if the appropriate -FIELDS keyword (like SUCCESSFIELDS) assigns a value to the data model field. You might want to write the data model field to the database if, for example, you had changed the value in a local transaction exit. To write a data model field that would not be written automatically, include an expression like the following in the appropriate -FIELDS keyword: MY_DATA_MODEL_FIELD = @MY_DATA_MODEL_FIELD@
NOTE
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 172 of 276
Understanding the Details of Search Phase

During search phase on either Client or Server, the following rules apply: The active section may include no more than one keyword SUB-TABLE The Server ignores assignment statements and SET-VALUE-IF keywords Before an iWave Integrator searches for a record, keyword TRANSLATE-FIELD converts a data-model-field value, if used as a search criterion, into the related vendor-field value If a subtable is referenced, a parameter in keyword SUB-TABLE indicates whether to search the subtable before or after the primary table; specifically: The order of searching is determined by whether subkeyword PFLAGS includes SBEFORE (search the subtable before searching the primary table) or SAFTER (search the primary table first). The criteria used for finding a record in the second-searched tablewhether primary table or subtableis further restricted. In one case the further restriction is based on the values of paired subkeywords PSET and SFIELD, and another case on the values of paired subkeywords SSET and PFIELD. If subkeyword PFLAGS includes PBEFORE, explicitly or by default, the further restriction is based on the values of subkeywords PSET and SFIELD; specifically: If the subtable search precedes the primary table search (PFLAGS value SBEFORE), the search of the primary table seeks a record that has PSET fields having values that match the values of the subtables corresponding SFIELD fields. If the subtable search follows the primary-table search (PFLAGS value SAFTER), the search of the subtable seeks a record that has SFIELD fields having values that match the values of the primary tables corresponding PSET fields.
If subkeyword PFLAGS includes PAFTER, the further restriction is based on the values of subkeywords SSET and PFIELD; specifically: If the subtable search precedes the primary table search (PFLAGS value SBEFORE), the search of the primary table seeks a record that has PFIELD fields having values that match the values of the subtables corresponding SSET fields. If the subtable search follows the primary-table search (PFLAGS value SAFTER), the search of the subtable seeks a record that has SSET fields having values that match the values of the primary tables corresponding PFIELD fields.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 173 of 276
Understanding the Last Steps of Write Phase

This section gives additional details on the final steps of write phase, which includes the following: Writing to PBEFORE subtables, if any. Writing to the primary table. Writing to PAFTER subtables, if any.
Processing of SUB-TABLE keywords in the active section precedes processing of SUBTABLE keywords inherited from a superior section, and processing within a section is in keyword order. The following is true for each keyword SUB-TABLE that the iWave Integrator processes before writing to the primary table: The iWave Integrator processes the subtable in accordance with the setting of subkeyword WMODE. If WMODE is set to Create, or if an attempt to find a subtable record fails with no record found when WMODE is set to UNIQUE, the iWave Integrator creates a new subtable record and sets the subtable fields as required by the paired subkeywords INIT and VALUE. When creating or updating the subtable record, the iWave Integrator uses the values in the data model fields that are mapped to the subtable. For a subtable record being created, the values in the data model fields take precedence over the settings of the paired keywords INIT and VALUE. The iWave Integrator uses the settings of paired subkeywords PSET and SFIELD to copy data from the subtable record to an internal variable that is ultimately written to the primary table. The value assigned to that variable takes precedence over both the following: The value contained in any data model field mapped to the same primary-table field as the field identified in subkeyword PSE The value assigned from a previously processed SUB-TABLE keyword
The following is true for each keyword SUB-TABLE that the iWave Integrator processes after writing to the primary table: The iWave Integrator processes the subtable in accordance with the setting of subkeyword WMODE. If WMODE is set to Create, or if an attempt to find a subtable record fails with no record found when WMODE is set to UNIQUE, the iWave Integrator creates a new subtable record and sets the subtable fields as required by the paired subkeywords INIT and VALUE. When creating or updating the subtable record, the following is true: The iWave Integrator uses the values in the data model fields that are mapped to the subtable. For a subtable record being created, the values
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 174 of 276
in the data model fields take precedence over the settings of the paired keywords INIT and VALUE. The iWave Integrator uses the settings of paired subkeywords SSET and PFIELD to assign data from the primary table to the subtable; those values take precedence over both the values in the data model fields that are mapped to the subtable and (for newly created subtable records) the settings of the paired keywords INIT and VALUE.
On a given iWave Integrator for a given transaction, if a successful database write is followed by transaction failure (iWave Integrator return code 8), iWave Integrator rolls back changes to the record if the iWave Integrator is supporting one of the following vendor applications:
NOTE
Clarify SQL: DB2, Oracle, andif the underlying database management system supports rollbackODBC
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 175 of 276
D
iWave Universal Agent
This section describes the iWave Integrator Universal Agent. This Agent is used for most iWave Integrators when event mode is chosen. The Universal Agent is launched by the vendor application when a real-time event occurs (such as saving a record) that indicates that there is data for the Client to process. You customize your vendor application as appropriate to launch the Agent when the real-time event occurs (see your vendor applications documentation to learn how to execute an external program). The iWave Integrator Universal Agent is installed when you install your iWave Integrator. The program is used to initiate an iWave Integrator Client transaction.
Running the Universal Agent

The Agent connects to a Client, sends an agent message, and then disconnects from the Client. Arguments for the Agent are supplied on the command line for UNIX and Windows NT. For z/OS, you must invoke the Universal Agent using standard linkage conventions; typically, you launch the Agent from a REXX EXEC. The Agent can be started on demand by either another application or a user. Usually, the iWave Integrator Universal Agent is started automatically in response to a event. This can be a database event causing iWave Integrator to initiate the process by which a record in that database is conveyed to the remote Server; in this case, the agent runs in notification mode. This can also be an event in which the agent receives all data to be sent from an enterprise-management vendor application to some other vendor application (such as a help desk product) via the remote Server; in this case, the agent runs in event mode.
NOTE send data directly to a remote Server.
Like other types of Agents, the Universal Agent sends data to a Client. Agents never
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 176 of 276
Format
Brackets [ ] indicate an optional command line argument; all others are required. The command-line syntax for the Universal Agent is as follows: uniagt -r client-location [-l local_address] [-s server_name] [-p section_name] [-c client_object_id] [-o server_object_id] [-t priority] [-O log_file] [-v log_detail] [-g store_locale] [-u unicode_file] [-b returned_vendor_field] [-b returned_vendor_field] [-a vendor_field=value [-a vendor_field=value]] [-n orgin_port] [-e count,interval] [-E] [-d delay] where: uniagtis the name of the Universal Agent executable. The agent can also be invoked by either of its aliases: uniagt, and notfagt. -r client_locationclient_location is the network location of the Client. This argument is required. Any argument containing spaces must be enclosed in double quotation marks. The network location is always a TCP/IP address (as of iWave Integrator Version 5.1). The network location may be specified as either of the following: client_address,port or port where client_address is the IP address or host name of the Client machine, and port is the port number specified by the DETECTION-PORT keyword in the Clients processing file. Use the client_address,port format when the Agent and Client run on different machines, or when they both run on one machine with multiple IP addresses. Use the port format when the Agent and Client run on the same machine and the machine has a single IP address. The client_address portion of the client_address,port format must match the IPAddress key in the Base section of the configuration file of iWave Director that owns the Client.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 177 of 276
-l local_addresslocal_address is the TCP/IP address of the Universal Agents machine, orfor z/OSmay have a different meaning, as explained below. Use this argument when you use the client_address,port format of the -r client_location argument, and the Agent and Client run on different machines. For UNIX and Windows NT, if this argument is omitted, the Agent derives its local_address from client_location. If client_location is in the client_address,port format, the Agent uses client_address as its local_address; otherwise, the Agent uses the default TCP/IP address of its machine. For z/OS, this is the ASID of the TCP/IP protocol stack. If omitted, the default IBM TCP/IP protocol stack is used.
-s server_nameserver_name is the name of the remote Server to which the Client is to send the resulting transaction request. If the Agent work request contains a Server name, the Agents setting overrides the setting in the Client processing file. (In the Client processing file, the Server name is specified by keyword SERVER-APP in section_name or in the section where keyword EVENT-FILTER has been defined.) -p section_namesection_name is the fully-qualified name of a Verb or Verb Qualifier section in the Clients processing file. This operand is optional; if present, it must be object_class/verb or object_class/verb/verb_qualifier. -c client_object_idclient_object_id is the name of an object instance in the database managed by the Client to which the agent message applies. When the -c client_object_id argument is specified, the agent runs in notification mode, and a vendor_field arguments are optional. When the -c client_object_id argument is not specified, the agent runs in event mode, and at least one a vendor_field argument is required. -o server_object_idserver_object_id is the name of an object instance in the database managed by the Server to which the Client will send a transaction. This argument is optional. -t prioritypriority is the priority number assigned to the event message by the Client. The priority is a number from 1 to 10, where 1 is the highest priority and 10 is the lowest. If you specify this argument, keyword PRIORITY in the Client processing file is not meaningful. -O logfileis the location of the Agent log. This parameter is optional. For UNIX and Windows NT, logfile is either the full path name for the Universal Agents log (enclosed in quotes if the path contains spaces), or one of the following: /dev/nullTurns off logging stdoutSends the log to the screen stderrSends the log to the screen
Both stdout and stderr direct logs to the screen; however, by directing stderr to a file,
NOTE and then defining -O stderr, you can automatically redirect all Agents to the new
file. On UNIX and Windows NT, the log is sent to the screen if the -O argument is omitted.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 178 of 276
For z/OS, this is the ddname for the Universal Agents log or DUMMY, which turns off logging. If omitted, the log is sent to ddname SYSPRINT. To turn off logging, you must specify -O DUMMY as the first Agent parameter. -v log_detaillog_detail is the number that indicates the amount of detail in the log. A value of 0 indicates that minimal logging is to be performed. Any other numeric value indicates that detailed logging is to be performed. This argument is optional and is ignored when logging is suppressed. -g store_localestore_locale is one of the following: For UNIX and Windows NT/2000, store_locale is the fully-qualified pathname of the directory where the Agent stores a copy of every request sent to a Client. If the path includes spaces, enclose the path in quotes. For z/OS, store_locale is the ddname (1 to 8 characters) or the data set name (9 to 44 characters) of the VSAM key-sequenced data set (KSDS) where the Agent stores a copy of every request sent to a Client.
NOTE
For the Agent, the value for the store-locale argument (-g) can be either a ddname or a data set name; the Agent determines which is being specified by the number of characters in the value. The Client has its own store-locale setting (keyword STORELOCALE) in the Client processing file; the value of that setting must be a ddname. On z/OS, the store-locale data set must be a VSAM KSDS with the correct key size (8,0). To create the store-locale data set, you modify and run the VSAMINIT JCL located in the hlq.TOOLS data set, where hlq is the high-level qualifier of the data set where iWave Integrator is installed. Only one Agent can use any given store-locale data set, so be sure to specify a unique data set name in the VSAMINIT JCL.
CAUTION You can use the VSAMINIT JCL to create either Agent or Client storelocale data
sets on z/OS. However, only one Agent or one Client can use any given storelocale data set, so be sure to specify a different name each time you modify VSAMINIT to create a store-locale data set.
The -g store_locale parameter is optional. Specifying a store locale activates store-and-forward capability: if the Client is not running when the Agent sends its request, specifying a store locale ensures that the request is retained until the Client is available. The next time the Agent is launched and the Client is running, the Agent sends all the stored requests (in the correct order) to the Client. On UNIX and Windows NT/2000, the Agent creates a long-running child process that, at one-minute intervals, attempts to send all stored requests to the Client. On Windows NT/2000, the long-running process is a detached process; on UNIX, it is a daemon.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 179 of 276
The next time the Client starts, this child process sends the stored requests, with a maximum delay of one minute. The child process then terminates. The child process does not interfere in any way with the normal operation of the Agent. When the Agent is restarted, the Agent does not attempt to start another child process if a child process is already running. On z/OS, the Agent does not start an equivalent child process to send stored requests. Instead, you can run a second Agent in a long-running environment such as a batch job to achieve the same goal. Unlike the UNIX and Windows NT/2000 process, this job continues to run after having sent the stored requests to the Client. You must run the second Agent using standard linkage conventions (for example, from a REXX EXEC) and you must specify the -r (Client location) and -g (store locale) flags and their valuesrunning an Agent with only these two arguments runs the Agent in automated mode. The -l (local address) flag and its value are optional. No other arguments are allowed. Do not allocate the Agent store-and-forward VSAM KSDS in JCL. Instead, specify the complete data set name in the -g (store locale) value. See Running the Agent in Automated Mode on page 188 for more information. Both the Client and the Agent can have a store locale, but they do not share store locales. For information about specifying a store locale for the Client, see keyword STORE-
NOTE LOCALE in the iWave Integrator Keyword Reference.
An iWave Integrator store locale cannot be shared by simultaneously active processes. You must use the same store locale for successive invocations of an Agent that sends to the same Client. Two or more simultaneous invocations of the Agent cause the second and subsequent invocations to suspend operation until the first invocation of the Agent completes. If all invocations of the Agent are for the same Client, this behavior is correct. Be sure that all invocations of the Agent for the same Client use the same store locale, and do not attempt to share store locales between invocations for different Clients. Store-and-forward capability in the Agent works like this: When the Universal Agent starts, it builds a work request for the Client from its command line arguments and attempts to send the work request to the Client. If the Agent cannot connect to the Client, the Agent stores the work request in its store locale. The Agent attempts to send every request in its store locale to the Client, in the order in which they were created. If a send attempt fails, the Agent terminates without attempting to send any succeeding work requests. If a send attempt succeeds, the Agent deletes the work request from its store locale and proceeds to the next work request.
If the Agent starts and there are work requests waiting in the store locale, the Agent sends those requests before the current work request.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 180 of 276
Typically, the Client is running and the work request represented by the Agent's command line arguments is sent to the Client. If the Client is not running, the work request is stored in the Agents store locale. Every time the Agent is invoked and the Client is unavailable, another work request is stored in the Agent's store locale. At some point, the Client becomes available. The work requests remain (unsent) in the Agent store locale until the Agent is invoked again. (There is no means for automatically sending the work requests immediately upon the Client becoming available.) When the Agent is invoked to send a new work request, the Agent sends all requests in its store locale to the Client and then sends the new work request. -u unicode_fileunicode_file is one of the following: For UNIX and Windows NT/2000 unicode_file is the full pathname of the Unicode table file. For z/OS, unicode_file is the ddname (1 to 8 characters) or the data set name (9 to 54 characters including PDS member name) of the Unicode table file.
If you omit the -u parameter, a default Unicode table file that is included in the Agent is used for Unicode translations. This table is equivalent to ISO 8859-1. -b returned_vendor_fieldreturned_vendor_field identifies a vendor field that might be sent from the Client in its response to the Agent when the Client processing file contains the setting AGENT-RESPONSE-IMMEDIATE:NO. If the Client response includes the vendor field identified by the -b parameter, the vendor fields data appears in the Agent log or stdout (typically, the screen), depending on the setting of the -O parameter.
NOTE is set to YES.
The -b parameter is meaningless when keyword AGENT-RESPONSE-IMMEDIATE
Multiple -b arguments may be supplied to the Agent. You can use the -b parameter to display the contents of any returned vendor field, including the results of system commands issued using the z/OS Extended MCS Console Assignment Exit (exit function pntmcs). See the iWave Integrator Users Guide for details. -a vendor_field=valuevendor_field is the name of the vendor field; the mapping file maps a data model field to that vendor field. The second part of the argument, value, is the data to be transmitted from Client to Server.
NOTE the iWave Integrator you are using explicitly requires its use.
Typically, you should avoid using the -a parameter with the Universal Agent unless
This optional parameter describes the data to send to the Client. For most implementations that use the Universal Agent, you should provide the Agent the section name (-p) and the local object ID (-c) but no vendor field values (-a), so that the Client retrieves the data from the vendor application.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 181 of 276
If you want the data included in the Agent transaction (instead of having the Client retrieve the data), use the -a parameter. For Enterprise Management vendor applications, at least one a parameter is required and the c parameter is omitted.
CAUTION Sending data to the Client using the -a parameter typically requires different
mapping and processing file settings from the settings used when the Agent does not send data. Failure to understand these differences can cause unpredictable results. When sending data from the Agent, the Client still executes some processing file statements that affect which data the Client sends in the transaction, including the following: Data model assignments SET-VALUE-IF statements SET-VALUE-IF-GROUP statements SUB-TABLE statements TRANSLATE-FIELD statements
SUB-TABLE statements are incompatible with the -a parameter. You must not use the -a parameter to include vendor field values in the Agent transaction when there are SUB-TABLE statements in the Client mapping or processing files. If you include SUB-TABLE statements, the Client retrieves the data from the subtables, which may replace data sent in the Agent transaction. Multiple -a arguments may be supplied to the Universal Agent, each describing a separate data value provided by the enterprise-management application. In most environments, if the name of the vendor field or the value includes a blank, surround the data by double quotes, as follows: -a "my_field=value that contains blanks" If the Agent transaction includes vendor-field values in the -a parameter, then the Client does not attempt to retrieve additional mapped fields from the vendor application. The Client behaves differently depending on whether the -a parameter is specified: -a parameter not specifiedThe Client uses the Client object ID (-c parameter) from the Agent transaction to retrieve the mapped vendor fields from the vendor application (the most common implementation). -a parameter specified one or more timesThe Client retrieves all vendor-field values (-a parameters) from the Agent.
Some Clients do not recognize the -a parameterincluding the iWave Client for
NOTE SOLVE:Central. Do not attempt to use the Universal Agent with the SOLVE:Central
Client; use the SOLVE:Central Agent.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 182 of 276
Mapped fields for which you did not supply data are sent as NULL unless the Client performs data model assignments, SET-VALUE-IF translations, or other types of translations. -n origin_portDefines an origin IP port number when connecting to a TCP server. The purpose of the origin port is to allow the Agent to send messages through firewalls that allow traffic to pass only when the traffic originates from particular ports (Figure 34).
Figure 34 Origin Port in Universal Agent The -n parameter (like -r and -g) causes the Agent to run in automated mode when no other parameters are specified. Testing has shown that all supported operating systems ignore any attempt by an application program to reuse an origin IP port number when the following are true: The port number has been recently used. TCPs timeout period for port number reuse has not yet elapsed. This period is always 2 x MSL, where MSL is the TCP maximum segment lifetime.
The origin port must not be in use when an iWave Agent (or iWave Client or iWave Director) attempts to use it. Be sure to assign a unique port number. -e count,intervalWhen the c client_object_id parameter is supplied and the a vendor_field parameter is not supplied, thus causing the agent to run in notification mode, the Client that receives the agent message may experience a failure when it attempts to retrieve the object from the local vendor database. The Universal Agent can anticipate this error and include retry instructions in the agent message. The agent message can instruct the client to retry the retrieve at a later time with the e count,interval parameter. The count value is the number
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 183 of 276
of times to retry the failed retrieve, and the interval value is the number of seconds to wait between retries. -E Instructs the agent to put each environment variable in a a parameter. This feature is not available on z/OS. -d delayCauses the agent to delay this number of seconds before exiting.
UNIX and Windows NT/2000 Example of Notification Mode

The following is an example of the syntax for the Universal Agent when the Agent runs on a UNIX or Windows NT/2000 platform, and runs in notification mode: uniagt -r hp,9011 -O /usr/skywiresoftware/iwave/integrator/log/ uniagt.log -p PROBLEM/CREATE-UNIQUE -c 123456 -g /user/skywiresoftware/iwave/integrator/agentstore The following describes the parts of the preceding Universal Agent example:
uniagtThe name of the iWave Integrator Universal Agent application
-O /usr/skywiresoftware/iwave/integrator/log/uniagt.log (UNIX) \C:\Program Files\ SkywireSoftware\uniagt.log (Windows NT/2000) The name of the log file. As long as you use a unique name, you can share this folder with other iWave components such as iWave Director. -r hp,9011Identifies the system where the Client is running (hp) and the port number (specified by the DETECTION-PORT keyword) on which that application is expecting Universal Agent messages (9011) -p PROBLEM/CREATE-UNIQUETells the Client the OBJECT-CLASS and VERB for which this transaction must be processed -c 123456Tells the Client that record in its database must be transferred -g /user/skywiresoftware/iwave/integrator/agentstoreIdentifies
the Agents store locale where work requests traveling from the Agent to the Client are stored. Frequently, only a single object class and verb are triggered through the Universal Agent. In this case, it may be easier to initiate the iWave Integrator Universal Agent through a command script. The command script can contain all the fixed parameters used by the Universal Agent reducing the number of parameters that must be specified by the database application when starting the agent. Such a script is provided for iWave Integrators running under UNIX. The start_agent script accepts the following parameters: start_agent 123456 where:
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 184 of 276
start_agentis the name of the script 123456is the record ID to be supplied as the parameter value for the COID (client object ID) parameter
UNIX Example of Event Mode

Often, the enterprise-management application is configured to start a script when a specified event occurs. The script then calls the Universal Agent. You might type a string into an onscreen field to ensure that under a specified circumstance, the enterprise-management application runs a script with specified parameters. When working with HP OpenView NNM, for example, you might type the following in the Command for Automatic Action field, which is accessed from the Event Configuration window: /usr/skywiresoftware/iwave/integrator/scripts/nnm_exec "x=$x" "X=$X" "@=$@" "O=$O" "o=$o" "V=$V" "r=$r" "R=$R" "c=$c" "s=$s" "N=$N" "F=$F" "C=$C" "E=$E" "e=$e" "A=$A" "G=$G" "S=$S" "T=$T" In this case, $x, $X, and so on are environment variables exported by OpenView Network Node Manager, and those variables contain information about the event. Figure 35 shows the nnm_exec script started from HP OpenView NNM. The script does the following: Creates the command that invokes the Universal Agent Includes a loop to concatenate all network-event fields to that command Executes that command
#!/bin/ksh # nnm_exec # CMD="/usr/skywiresoftware/iwave/integrator/bin/uniagt -r 9092 -p PROBLEM/CREATE-UNIQUE -O /usr/skywire software/iwave/integrator/log/uniagt.log" while [ $# -gt 0 ] do CMD=`echo $CMD -a '"'$1'"'` shift done eval $CMD Figure 35 Example Script to Start the Universal Agent The following mapping file maps data model fields to network-event fields. No problems arise if some of the arguments passed from the enterprise-management application are ignored, as is the case in this example.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 185 of 276
Begin Base; Begin Object Class /PROBLEM/; SUBMITTED_BY=%r%; LOCATION=%C%; SOURCE=%A%; CLASS=%N%; EVENT_DATE=%x%; EVENT_TIME=%X%; TRAPGEN=%G%; TRAPSPC=%S%; IMPACT=%s%; PROBLEM_TYPE=%c%; Begin Verb /CREATE-UNIQUE/; End Verb; /CREATE-UNIQUE/ Begin Verb /CREATE/; End Verb; /CREATE/ Begin Verb /UPDATE/; End Verb; /UPDATE/ Begin Verb /RETRIEVE/; End Verb; /RETRIEVE/; Begin Verb /SEARCH/; End Verb; /SEARCH/ End Object Class; /PROBLEM/ End Base;
z/OS Examples
You must launch the Agent on z/OS using standard linkage conventions. The steps and explanations in this section assume that you will launch the Agent from a REXX EXEC. On z/OS, you can run the Agent in either of the following two modes: Normal modeThe Agent is invoked when the vendor application runs a REXX EXEC (TSXAGENT, in the following examples) that starts the Agent. The Agent is short-running: the Agent processes the work request from the vendor application and then ends. Automated modeThe Agent is invoked from a TSO batch job that runs a REXX EXEC (AUTOAGT, in these examples). The Agent is long-running: it runs continuously and, once a minute, sends any work requests stored in the store locale to the Client.
The recommended configuration is to run two Agents, one in normal mode and one in automated mode. This section shows how to set up this configuration.
Preparing to Run the Agents Whether you run the Universal Agent in normal mode or automated mode, you must do the following: Step 1. Allocate the data set where the Agent resideshlq.LOADin the logon procedure for all users who need to launch the Agent from the vendor
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 186 of 276
application. In this step, hlq is the high-level qualifier of the data set where you installed iWave Integrator. When you upgrade to a later version of iWave Integrator, be sure to modify the logon
NOTE procedure so that the correct version of the Agent is used.
Step 2. Modify and run the VSAMINIT JCL (located in hlq.TOOLS) to create a store locale for the Agent. In this example, the store locale is hlq.ASTORE, where hlq is the high-level qualifier of the data set where you installed iWave Integrator. Make sure the store locale you specify does not interfere with other Agents or Clients.
Invoking the Agent in Normal Mode In normal mode, the Agent is launched by the vendor application. The Agent processes the work request from the vendor application, then the Agent terminates. When there is more work to be done, the vendor application invokes the Agent again. To invoke the Agent in normal mode, do the following: Step 1. Modify your vendor application to run the REXX EXEC that launches the Agent in normal mode. For Tivoli Service Desk for z/OS, you modify panels to run the REXX EXEC TSXAGENT. Step 2. For Tivoli Service Desk for z/OS, copy TSXAGENT from hlq.SAMPLES.IM to hlq.CONFIG. (This sample works only with the sample configuration shipped with the iWave Integrator for Tivoli Service Desk for z/OS). Step 3. Change the settings in REXX EXEC that runs the Agent in normal mode, as needed for your environment. The following sample is TSXAGENT, which is located in hlq.SAMPLES.IM (Figure 36).
/*********************************************************************/ /*(C) */ /* Copyright (c) 1994-2005 Skywire Software,LLC., as an unpublished */ /* work. All rights reserved. This work contains trade secret */ /* information of Skywire Software, LLC. The copying, distribution and */ /* use of this work is restricted to licensees, in accordance with */ /* the terms and conditions of the applicable license. */ /*(C) */ /*********************************************************************/ /* This TSX invokes the iWave Universal Agent included */ /* with iWave Integrator V5.1 for use with Tivoli Service Desk for */ /* z/OS (Information/Management). */ /*********************************************************************/ signal on syntax name synrtn /* Call synrtn if any syntax or TSX */ /* control line parameter errors */ parse source . . execname . /* Get exec name */ if blgtrace=1 then /* TSP/TSX tracing requested? */ say '**** Entering' left(execname,8) '****' /* A separate IF statement is used to turn on tracing so that the */ /* first traced statement won't be "end", which could be confusing */ if blgtrace=1 then /* TSP/TSX tracing requested? */ trace results /* yes - trace results */
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 187 of 276
Specify the Client location. You specify this same address in the AUTOAGT REXX EXEC.
arg1='-r' arg2='9003' arg3='-s' arg4='INFOSA' arg5='-p' arg6='PROBLEM/CREATE-UNIQUE' arg7='-c' arg8=TSCALFID arg9='-v' arg10='1' arg11='-g' arg12='hlq.ASTORE' arg11='-o'
/* address of client
*/
/* name of service /* section/verb/qualifier /* client object ID /* 1 = logging enabled
*/ */ */ */
Specify a storelocale data set. You specify this same store locale in the AUTOAGT REXX EXEC.
/* Store Locale data set name
*/
/* Search for iWave external object ID. If found, use the value /* as an additional parameter to the agent, UNIAGT
*/ */
call BLGTSX 'FINDSDATA','IMDIPEXID','SWORD','LAST'; if TSCAFRET = 0 then do; arg12 = TSCASDF; /* external object ID */ ADDRESS LINKPGM "UNIAGT arg1 arg2 arg3 arg4 arg5 arg6 arg7 arg8 arg9 arg10 arg11 arg12" end; else ADDRESS LINKPGM "UNIAGT arg1 arg2 arg3 arg4 arg5 arg6 arg7 arg8 arg9 arg10" say '=>' rc '<= returned by UNIAGT' exit; synrtn: say 'Syntax error at line' sigl exit
Figure 36 TSXAGENT REXX EXEC
Running the Agent in Automated Mode

It is recommended that you use a second Agent running in automated mode to process work requests saved in the store locale. This second Agent guarantees that any stored work requests are forwarded to the Client promptly.
Purpose of a Second Agent On z/OS, suppose that you are running a single Agent (in normal mode) and the Agent has a store locale specified. The Agent attempts to send the requests to the Client. If the Client is unavailable, the work requests remain in the store locale and the Agent ends. When the Client starts again, the work requests are not automatically forwarded to the Client; they remain unsent in the store locale until the next time the vendor application invokes the Agent. This can result in an unacceptable lag between the time when the Client restarts and the time when the Agent is launched and forwards the work requests to the Client.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 188 of 276
To avoid this delay, run a second Agent in automated mode. At one-minute intervals, the Agent running in automated mode attempts to send any work requests in the store locale to the Client. The Agent running in automated mode does not interfere with other Agents invoked at the same time. The Agent running in normal mode and the Agent running in automated mode are
NOTE both instances of the same Universal Agent executable, UNIAGT.
Configuration Steps In this section, you will modify two members: TSOAUTAGAn Agent running in automated mode must be invoked from a long-running environment. This sample JCL runs the Agent from within batch TSO. AUTOAGTThis sample REXX EXEC runs the Agent in automated mode.
To run a second Agent in automated mode, do the following: Step 1. Copy the AUTOAGT REXX EXEC from hlq.TOOLS to hlq.CONFIG. (You will customize this member in a later step.) Step 2. You must invoke the second Agent running in automated mode from within a batch job. See the TSOAUTAG JCL in hlq.TOOLS for a sample. In TSOAUTAG, batch TSO runs the REXX EXEC that invokes the Agent (Figure 37). To invoke the Agent from within a batch job, copy the TSOAUTAG JCL from hlq.TOOLS to a data set you select, then modify the JCL for your environment.
//BATCHTSO EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K Identify the data set where the Agent executable (UNIAGT) resides. //STEPLIB DD DSN=hlq.LOAD,DISP=SHR /* //SYSEXEC DD DSN=hlq.CONFIG,DISP=SHR /* //SYSTSPRT DD SYSOUT=A //SYSTSIN DD * %AUTOAGT /* //
Identify the data set where the REXX EXEC that invokes the Agent (AUTOAGT) resides.
Identify the REXX EXEC that invokes the Agent in automated mode.
Figure 37 TSOAUTAG JCL Step 3. An Agent runs in automated mode when the only arguments passed to it are (1) the Client location and (2) the Agent store locale, and, optionally, (3) the Agent location.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 189 of 276
NOTE locale. Be sure you specify the Agent store locale.
The Client can have a store locale, too, but it must be different from the Agent store
Edit the AUTOAGT REXX EXEC (Figure 38) as follows: Change the Client location to the same Client location used in the REXX EXEC that invokes the Agent running in normal mode (TSXAGENT). Change the store locale to the same store locale used in TSXAGENT (hlq.ASTORE, in this example).
NOTE If the store locale you specify does not exist, the Agent fails.
/* REXX */ /* AUTOAGT: example of automated Agent guaranteed delivery */ /* set the network address of the iWave Client */ AddressFlag = '-r' Specify the Client location you identified in TSXAGENT. Specify the store locale you identified in TSXAGENT. ClientAddress = '9003' /* set the iWave Agent store locale */ StoreFlag = '-g' StoreLocale='hlq.ASTORE' ADDRESS LINKPGM "UNIAGT AddressFlag ClientAddress StoreFlag StoreLocale"
Figure 38 AUTOAGT REXX EXEC Step 4. Submit the TSOAUTAG JCL. The Agent job will run until you stop it or until the next IPL. You must resubmit TSOAUTAG after each IPL.
Return Codes
The following are the return codes for the Universal Agent: 0Success. 1Memory allocation error. 2 Parameter error. Corresponding messages are generated for each parameter error. These and other messages are listed in order by message number in iWave Integrator Messages and Codes.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 190 of 276
3Communication failure. Corresponding messages are generated for each parameter error. These and other messages are listed in order by message number in iWave Integrator Messages and Codes.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 191 of 276
E
iWave Director Configuration File
This appendix describes the iWave Director configuration file, sdserver.ini or ddname SDMCONFG, which is specified in the JCL that starts iWave Director. You can change the settings in the configuration file using iWave Administrator CLI, or you can open the file in a text editor and change the settings manually. The iWave Integrator distribution media includes example configuration files for each iWave Integrator.
Syntax of Statements in Configuration Files

The statements in the iWave Director configuration files have the following syntax: key=value The tables in this appendix list the keys that are available for UNIX, Windows, and z/OS platforms and describe the possible values. Spaces are significant within the configuration file statements, so you should avoid using spaces in either the key or its value. Any spaces you include in the key name (except leading spaces) become part of the key, which can be confusing. More importantly, spaces that are part of the value following the equals sign in the statement may cause unexpected results. Any space you type in the value is recognized, so make sure that you type spaces only where intended. There is no reason to use quotes to enclose the spaces, because quotes have no special significance in the configuration file. Both double and single quotes are simply characters like any others. In several instances, value may be either true or false, where true is any of the following, and false is anything else: TRUE and any of its abbreviations, case-insensitive
iWave Software
Revised [03/01/07] P01-664-09
YES and any of its abbreviations, case-insensitive 1 (digit)
When you open the configuration file in a text editor, you can add comments if you choose. When the first character in the line of text is a semicolon, the entire line is a comment. (In earlier versions of iWave Integrator, any text following a semicolon was a comment, regardless of where the semicolon appeared in the line of text. That is no longer true.) Unless the semicolon appears in the first position in a line, it has no special significance.
Base Section (z/OS)

Each record in the Base section of the iWave Director configuration file identifies a single configuration parameter. The following keys are recognized. Error! Reference source not found. Keys of Base Section (z/OS). Key ServiceManagerName ServiceManagerDescription FileVersion Description and Value The name of the iWave Director. This key is required. The description of the iWave Director. This key is optional. The version, release, and modification level of this file. This is a dotted decimal number, as version.release.modlevel. Optional. Default is 5.0.0. The IP port number of the management access point. This key is required. The IP port number or service name through which this iWave Director will receive transactions from remote iWave Directors, for any Servers managed by this iWave Director. This key is required. The IP port number of the iWave Directors Router Port. Optional. This key is required if iWave Director is an intermediate iWave Director (the SendTo section is present, and neither the Services section nor the ClientApplications section is present). LogDetail The amount of information to be written to iWave Directors log file. This key is optional. normal Only error messages and standard informational messages are to be written to the log. Default. Detailed messages about iWave Director operation are to be written to the log.
ManagementPort ServiceReceiveFromPort
ProxyReceiveFromPort
verbose
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 193 of 276
CreatedBy
Documents the name of the application that created the configuration file and its version. Optional. iWave Director ignores this key. Documents the date when the configuration file was created or last changed. Optional. iWave Director ignores this key. Documents the operating system type. Correct value is MVS. Required. The value of this key is a suffix phrase to be appended to system console message PNT2001I. Optional. iWave Director always leaves system console message PNT2001I outstanding, indicating that iWave Director is operational. The operator can give various replies to this message that affect iWave Director operation.
CreatedOn ValidOS ConsoleSuffix
StopWaitInterval
The time interval in seconds after the TERM system console command is entered when iWave Director is to force the termination of all subtasks. This parameter can be used to automatically force termination of applications when tiWave Director is terminated by an automation process. Optional. Default is 15 seconds. Transport interface subtasks and router subtasks are automatically forced to terminate if they do not terminate normally within 10 seconds after the termination of the last service.
AuthorizedUseridn
A user ID that is authorized to request the Adminstrator action commands set log options, start, stop, cycle, kill, and shutdown. If this key is not present, any user ID is authorized. This key may occur multiple times. The local time zone in the format zzzdddnnn, where zzz is the name or abbreviation of the standard time time zone, ddd is the difference in hours from Universal Coordinated Time (UTC), and nnn is the name or abbreviation of the daylight savings time zone. For example, the value for the Eastern Time Zone in the United States is EST5EDT. This key is optional. If not present, Clients and Servers interpret all timestamp values retrieved from a database as occurring during standard time. Although TimeZone is not required, you should always use it unless the host is in a time zone that does not support daylight savings time. If TimeZone is set correctly, you do not need to change it when the time changes from standard to daylight savings, but you do need to restart iWave.
TimeZone
IPAddress ExtendedMCSConsoleName
The Internet address of this system. This key is optional. The Extended MCS Console to be activated by iWave Director and used by the assignment exit. The console name is one to eight characters in length. Do not use a name that might match the name of a device number (for example, BAD).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 194 of 276
Error! Reference source not found. Keys of Base Section (z/OS) Cont. Key ExtendedMCSConsoleKey Description and Value The name used on the DISPLAY C command to identify Extended MCS Consoles (DISPLAY C,KEY=key); for example:
ExtendedMCSConsoleKey=console_key
where console_key is one to eight characters in length. The default value is IWAVEINT. This parameter is ignored when ExtendedMCSConsoleName is not configured. When ExtendedMCSConsoleName is configured, the value of ExtendedMCSConsoleKey must be different from the value of Extended MCSConsoleName. ExtendedMCSConsoleMaxWait The maximum time in seconds that iWave Director is to wait for any command response; for example:
ExtendedMCSConsoleMaxWait=seconds
where seconds is an integer greater than 0. The default value is 5 seconds. This parameter is ignored when ExtendedMCSConsoleName is not configured. SerializeInterfaceInitialization This setting causes iWave Integrators to initialize serially (true) or to initialize concurrently (false); for example:
SerializeInterfaceInitialization=1
The default setting is to initialize the iWave Integrators concurrently (false). On a heavily loaded system, however, concurrent initialization activity by multiple Clients and Servers can place a heavy load on memory and other system resources, resulting in failures during startup. You should set this key to true only if you experience such problems, because the time required to initialize iWave Integrator can be significantly longer. ClientIdleTimeout The number of seconds that must elapse during which Director receives no transactions at its ProxyReceiveFromPort from a specific client before Director disconnects from the client. Use this keyword to detect and recover from a firewall disconnect. Optional. The number of seconds that must elapse during which Director receives no transactions at its ServiceReceiveFromPort from a specific ReceiveFrom Director before Director disconnects from the remote Director. Use this keyword to detect and recover from a firewall disconnect. Optional. Indicates whether (true) or not (false) multiple SendTo Directors may simultaneously own the same server. The default is false. Indicates whether (true) or not (false) Director is to send a transaction for a server owned by multiple SendTo Directors to the Director that has the least number of outstanding transaction responses for all servers owned by the SendTo Director. Meaningful only when MultipleServerOwners=true. false is the default.
ReceiveFromIdleTimeout
MultipleServerOwners
LoadBalance
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 195 of 276
Error! Reference source not found. Keys of Base Section (z/OS) Cont. Key ApplicationStartState Description and Value Director normally starts all managed applications (agents, clients, servers) in an active state. To start Director but cause it to not start its managed applications, set the value of this keyword to inactive. The default value is active. If inactive is used, managed applications can be subsequently start with Administrator or the sddc CLI.
Example The following is an example of a Base section of an iWave Director configuration file: [Base] ServiceManagerName=MVS iWave Director FileVersion=5.7.0 ManagementPort=3451 ServiceReceiveFromPort=3452 LogDetail=normal ConsoleSuffix=, REPLY TERM TO TERMINATE StopWaitInterval=15 TimeZone=PST8PDT AuthorizedUserid1=TREPHO5R ValidOS=MVS
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 196 of 276
Base Section (UNIX)

Each record in the Base section of the iWave Director configuration file identifies a single configuration parameter. The following keys are recognized. Table 3 Keys of Base Section (UNIX) Key ServiceManagerName ServiceManagerDescription FileVersion Description and Value The name of iWave Director. Embedded spaces are not allowed. This key is required. The description of iWave Director. This key is optional. The version, release, and modification level of this file. This is a dotteddecimal number, as version.release.modlevel. Optional for 3.5.2; required for 4.0.0 and later. Default is 5.0.0. The IP port number of the management access point. This key is required. The IP port number or service name through which this iWave Director will receive transactions from remote iWave Director, for any Servers managed by this iWave Director. This key is required if the ReceiveFrom section is present; otherwise it is ignored. The IP port number of iWave Directors Router Port. Optional. This key is required if iWave Director is an intermediate iWave Director (the SendTo section is present, and neither the Services section nor the ClientApplications section is present). The full pathname of the iWave Integrator license-key file. This key is required. The full pathname of the Unicode conversion table file. This key is optional. If omitted, a built-in conversion table based on ISO 8859-1 is used. Fully-qualified name of the directory for the log file used by iWave Director. In this directory, iWave Director creates a log file named manager.log.n, where n is a generation number and is always 0 for the current generation. This key is required. The amount of information to be written to the iWave Director log file. A plus-delimited list of tokens. Tokens may be abbreviated. This key is optional. normal Only error messages and standard informational messages are to be written to the log. Default. Summary of actions requested by Administrator are to be written to the log. Details of managed applications are log. Connections made by remote clients are to be written to the log.
LicenseKeyFile UnicodeTableFile
LogPath
LogDetail
administrator applications client
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 197 of 276
Table 3 Keys of Base Section (UNIX) Cont. Key LogDetail - continued connect library license recvfrom Details of remote connections are to be written to the log. Internal library details are to be written to the log. Licensing details are to be written to the log. Messages exchanged with ReceiveFrom and ReceiveFromSSL Directors are to be written to the log. Messages exchanged with SendTo and SendToSSL Directors are to be written to the log. Details of the Unicode conversion tables are to be written to the log. All of the above. Use this value only when performing problem determination. Description and Value
sendto
Unicode verbose
CreatedBy
Documents the name of the application that created the configuration file and its version. Optional. iWave Director ignores this key. Documents the date when the configuration file was created or last changed. Optional. iWave Director ignores this key. Documents the operating system type. Correct value is UNIX. Required. A user ID that is authorized to request the Administrator action commands set log option, start, stop, cycle, kill, and shutdown. If this key is not present, any user ID is authorized. This key may occur multiple times. The Internet address of this system. This keyword must be supplied on multi-homed systems; otherwise, it is optional. The local time zone in the format zzzdddnnn, where zzz is the name or abbreviation of the standard time time zone, ddd is the difference in hours from Universal Coordinated Time (UTC), and nnn is the name or abbreviation of the daylight savings time zone. For example, the value for the Eastern Time Zone in the United States is EST5EDT. This key is optional. If not present, Clients and Servers interpret all timestamp values retrieved from a database as occurring during standard time. Although TimeZone is not required, you should always use it unless the host is in a time zone that does not support daylight savings time. If TimeZone is set correctly, you do not need to change it when the time changes from standard to daylight savings, but you do need to restart iWave.
CreatedOn ValidOS AuthorizedUseridn
IPAddress TimeZone
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 198 of 276
Table 3 Keys of Base Section (UNIX) Cont. Key DiplomatUser Description and Value Identifies the UNIX user ID to be associated with all components that iWave Director starts (including Clients, Agents, Servers, and internal components not visible to end users). Not required for iWave Integrator to run. If provided, all started components will inherit the user and group permissions associated with the user ID. If not provided, all started components inherit the user and group permissions associated with the user ID of iWave Director. Because iWave Director runs with root authorities, it is a security risk to omit this setting. The maximum number of generations for Directors log file. Before Director starts a new log file, it looks for the number of generations then in existence. If the number is not less than MaxLogFiles, it deletes generations, starting with the oldest, until the number of generations is one less than MaxLogFiles. Log files are named with a generation number suffix. The current log file always has suffix ".0". Successively older generations have suffix ".1", ".2", etc. When Director deletes a generation in preparation for opening a new log file with generation suffix ".0", it also renames the remaining generations. If MaxLogSize is configured but MaxLogFiles is not configured, the default for MaxLogFiles is 1. MaxLogSize The maximum byte count for Directors log file. When MaxLogSize is exceeded for a log, Director will start a new log. If MaxLogSize is not configured or is zero, no attempt is made to manage maximum log size or log generations (MaxLogFiles is ignored). ClientIdleTimeout The number of seconds that must elapse during which Director receives no transactions at its ProxyReceiveFromPort from a specific client before Director disconnects from the client. Use this keyword to detect and recover from a firewall disconnect. Optional. The number of seconds that must elapse during which Director receives no transactions at its ServiceReceiveFromPort from a specific ReceiveFrom Director, or at a connection to a ReceiveFromSSL Director, before Director disconnects from the remote Director. Use this keyword to detect and recover from a firewall disconnect. Optional. Indicates whether (true) or not (false) multiple SendTo Directors may simultaneously own the same server. The default is false. Indicates whether (true) or not (false) Director is to send a transaction for a server owned by multiple SendTo Directors to the Director that has the least number of outstanding transaction responses for all servers owned by the SendTo Director. Meaningful only when MultipleServerOwners=true. false is the default.
MaxLogFiles
MultipleServerOwners
LoadBalance
iWave Software
Revised [03/01/07] P01-664-09
Key ApplicationStartState
Description and Value Director normally starts all managed applications (agents, clients, servers) in an active state. To start Director but cause it to not start its managed applications, set the value of this keyword to inactive. The default value is active. If inactive is used, managed applications can be subsequently start with Administrator or the sddc CLI. A comma-delimited list of iWave Director log message numbers. Every log message with this number is to be omitted from the Director log. The IP port number or service name through which this iWave Director will receive transactions from remote iWave Director, using Secure Sockets Layer (SSL), for any Servers managed by this iWave Director. This key is required if the ReceiveFromSSL section is present; otherwise it is ignored.
LogMsgNumSuppress
SSLServiceReceiveFromPort
Example The following is an example of a Base section of an iWave Director configuration file. [Base] ServiceManagerName=iWaveDirector ServiceManagerDescription=iWave Director FileVersion=5.7.0 ManagementPort=5912 ServiceReceiveFromPort=5913 LogPath=/usr/skywiresoftware/iwave/integrator/logs LogDetail=normal LicenseKeyFile=/usr/skywiresoftware/iwave/integrator/config/ license.txt ValidOS=UNIX AuthorizedUserid1=a76chng AuthorizedUserid2=pp87xfor MaxLogFiles=3 MaxLogSize=100000
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 200 of 276
Base Section (Windows)

Each record in the Base section of the iWave Director configuration file identifies a single configuration parameter. The following keys are recognized. Table 4 Keys of Base Section (Windows) Key ServiceManagerName Description and Value The iWave Director name. Embedded spaces are not allowed. This is also the name of iWave Director as it is known to the Windows service control program. This key is required. The description of iWave Director. This key is optional. The version, release, and modification level of this file. This is a dotteddecimal number, as version.release.modlevel. Optional; required for 4.0.0 and later. Default is 5.0.0. The IP port number of the management access point. This key is required. The IP port number or service name through which this iWave Director will receive transactions from remote iWave Directors, for any Servers managed by iWave Director. This key is required if the ReceiveFrom section is present; otherwise it is ignored. The IP port number of the iWave Directors Router Port. Optional. This key is required if iWave Directoris an intermediate iWave Director (the SendTo section is present, and neither the Services section nor the ClientApplications section is present). The full pathname of the iWave Integrator license-key file. This key is required. The full pathname of the Unicode conversion table file. This key is optional. If omitted, built-in conversion table based on ISO 8859-1 is used. Fully-qualified name of the directory for the log file used by iWave Director. iWave Director creates a log file in this directory named manager.log.n, where n is a generation number and is always 0 for the current generation. This key is required. The amount of information to be written to the iWave Director log file. This key is optional. normal Only error messages and standard informational messages are to be written to the log. Default. Summary of actions requested by Administrator are to be written to the log. Details of managed applications are log. Connections made by remote clients are to be written to the log.
ServiceManagerDescription FileVersion
LicenseKeyFile UnicodeTableFile
LogPath
LogDetail
administrator applications client
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 201 of 276
Table 4 Keys of Base Section (Windows) Key LogDetail Continued connect library license recvfrom Details of remote connections are to be written to the log. Internal library details are to be written to the log. Licensing details are to be written to the log. Messages exchanged with ReceiveFrom and ReceiveFromSSL Directors are to be written to the log. Messages exchanged with SendTo and SendToSSL Directors are to be written to the log. Details of the Unicode conversion tables are to be written to the log. All of the above. Use this value only when performing problem determination. Description and Value
sendto
Unicode verbose
CreatedBy CreatedOn ValidOS AuthorizedUseridn
Documents the name of the application that created the configuration file and its version. Optional. iWave Director ignores this key. Documents the date when the configuration file was created or last changed. Optional. iWave Director ignores this key. Documents the operating system type. Correct value is NT. Required. A user ID that is authorized to request the Administrator action commands set log option, start, stop, cycle, kill, and shutdown. If this key is not present, any user ID is authorized. This key may occur multiple times. The Internet address of this system. This keyword must be supplied on multi-homed systems; otherwise, it is optional. The maximum number of generations for Directors log file. Before Director starts a new log file, it looks for the number of generations then in existence. If the number is not less than MaxLogFiles, it deletes generations, starting with the oldest, until the number of generations is one less than MaxLogFiles. Log files are named with a generation number suffix. The current log file always has suffix ".0". Successively older generations have suffix ".1", ".2", etc. When Director deletes a generation in preparation for opening a new log file with generation suffix ".0", it also renames the remaining generations. If MaxLogSize is configured but MaxLogFiles is not configured, the default for MaxLogFiles is 1.
IPAddress MaxLogFiles
MaxLogSize
The maximum byte count for Directors log file. When MaxLogSize is exceeded for a log, Director will start a new log. If MaxLogSize is not configured or is zero, no attempt is made to manage maximum log size or log generations (MaxLogFiles is ignored).
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 202 of 276
Table 4 Keys of Base Section (Windows) Key TimeZone Description and Value The local time zone in the format zzzdddnnn, where zzz is the name or abbreviation of the standard time time zone, ddd is the difference in hours from Universal Coordinated Time (UTC), and nnn is the name or abbreviation of the daylight savings time zone. For example, the value for the Eastern Time Zone in the United States is EST5EDT. This key is optional. If not present, Clients and Servers interpret all timestamp values retrieved from a database as occurring during standard time. Although TimeZone is not required, you should always use it unless the host is in a time zone that does not support daylight savings time. If TimeZone is set correctly, you do not need to change it when the time changes from standard to daylight savings, but you do need to restart iWave. ClientIdleTimeout The number of seconds that must elapse during which Director receives no transactions at its ProxyReceiveFromPort from a specific client before Director disconnects from the client. Use this keyword to detect and recover from a firewall disconnect. Optional. The number of seconds that must elapse during which Director receives no transactions at its ServiceReceiveFromPort from a specific ReceiveFrom Director, or at a connection to a ReceiveFromSSL Director, before Director disconnects from the remote Director. Use this keyword to detect and recover from a firewall disconnect. Optional. Indicates whether (true) or not (false) multiple SendTo Directors may simultaneously own the same server. The default is false. Indicates whether (true) or not (false) Director is to send a transaction for a server owned by multiple SendTo Directors to the Director that has the least number of outstanding transaction responses for all servers owned by the SendTo Director. Meaningful only when MultipleServerOwners=true. false is the default. Director normally starts all managed applications (agents, clients, servers) in an active state. To start Director but cause it to not start its managed applications, set the value of this keyword to inactive. The default value is active. If inactive is used, managed applications can be subsequently start with Administrator or the sddc CLI. A comma-delimited list of iWave Director log message numbers. Every log message with this number is to be omitted from the Director log. The IP port number or service name through which this iWave Director will receive transactions from remote iWave Director, using Secure Sockets Layer (SSL), for any Servers managed by this iWave Director. This key is required if the ReceiveFromSSL section is present; otherwise it is ignored.
MultipleServerOwners LoadBalance
ApplicationStartState
LogMsgNumSuppress
SSLServiceReceiveFrom Port
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 203 of 276
Example The following is an example of a Base section of an iWave Director configuration file for Windows NT. [Base] ServiceManagerName=iWaveDirector ServiceManagerDescription=iWave Director FileVersion=5.7.0 ManagementPort=5912 ServiceReceiveFromPort=5913 LogPath=c:\Program Files\skywiresoftware\iWave\Integrator\ logs LogDetail=normal LicenseKeyFile=c:\Program Files\skywiresoftware\iWave\ Integrator\config\license.txt ValidOS=NT AuthorizedUserid1=a76chng AuthorizedUserid2=pp87xfor MaxLogFiles=3 MaxLogSize=100000
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 204 of 276
InternetParameters Section (z/OS)

When this section is present, the keys describe parameters used by iWave Director to communicate with other iWave Directors using TCP/IP. Each record in the InternetParameters section describes an optional attribute to be applied to TCP/IP communications. The following keys are recognized in the InternetParameters section. Table 5 Keys of InternetParameters Section (z/OS) Key ASID Description and Value Identifier of the TCP/IP address space (protocol stack) to be used. If you do not supply this value, iWave Director uses the default address space. You supply this value only if you need to use a protocol stack other than the default. The default address space identifier depends on the protocol stack vender. Following is a partial list of vendors and their default address space identifiers. IBM Interlink EtcServices TCPIP ACSS
iWave Director looks for the following data set names while searching for the data set that is equivalent to /etc/services: Value of EtcServices key, if any; value must be in format DSN:data set_name ETC.SERVICES prefix.ETC.SERVICES, where prefix is the value of the EtcPrefix key
EtcHosts
iWave Director looks for the following data set names while searching for the data set that is equivalent to /etc/hosts: Value of EtcHosts key, if any; value must be in format DSN:data set_name ETC.HOSTS prefix.ETC.HOSTS, where prefix is the value of the EtcPrefix key
EtcPrefix
This is the high-level data set name qualifier that is used in finding the TCP/IP configuration data sets: /etc/hosts and /etc/services. The default value is TCPIP.
Example The following is an example of the InternetParameters section of an iWave Director configuration file [InternetParameters] ASID=TCPIP32
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 205 of 276
ReceiveFrom Section (z/OS)

Each record in the ReceiveFrom section of the iWave Director configuration file contains the network host address of a remote iWave Director that is authorized to send transactions to services managed by the local iWave Director. The following keys are recognized in the ReceiveFrom section. Table 6 Keys of ReceiveFrom Section (z/OS) Key IPAddressn Description and Value The host name or IP address of a remote iWave Director. This key may occur multiple times.
Example The following is an example of a ReceiveFrom section of an iWave Director configuration file, containing definitions of two iWave Directors. [ReceiveFrom] IPAddress1=204.75.139.102 IPAddress2=178.11.231.5
ReceiveFrom Section (UNIX and Windows)

Each record in the ReceiveFrom section of the iWave Director configuration file contains the network host address of a remote iWave Director that is authorized to send transactions to services managed by the iWave Director. The following keys are recognized in the ReceiveFrom section. Table 7 Keys of ReceiveFrom Section (UNIX and Windows) Key IPAddressn Description and Value The host name or IP address of a remote iWave Director. This key may occur multiple times.
Example The following is an example of a ReceiveFrom section of an iWave Director configuration file, containing definitions of two iWave Directors. The first iWave Director is identified by its host address, and the second is identified by its host name. [ReceiveFrom] IPAddress1=204.75.139.102 IPAddress2=falcon
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 206 of 276
Secure Sockets (UNIX and Windows)

Secure Sockets (SSL) is used to authenticate Directors and encrypt customer data flowing between Directors when one Director has a ReceiveFromSSL section and another has a SendToSSL section. The ReceiveFromSSL section of the iWave Director configuration file identifies all remote iWave Directors from which this Director is accept inbound connections using Secure Sockets. The SendToSSL section of the iWave Director configuration file identifies all remote iWave Directors to which this Director is to connect using Secure Sockets.
ReceiveFromSSL Section (UNIX and Windows)

The ReceiveFromSSL section of the iWave Director configuration file identifies all iWave Directors from which this Director will accept inbound connections using Secure Sockets. The following keys are recognized in the ReceiveFromSSL section. Table 8 Keys of ReceiveFromSSL Section (UNIX and Windows) Key ServiceManagern Description and Value A remote iWave Director from which this iWave Director is to accept connections using Secure Sockets for the purpose of receiving transactions. This is the name of a section in the configuration file (ssl_recv_name) containing keys applicable to this iWave Director. At least 1 instance of this key is required.
Example The following is an example of a ReceiveFromSSL section of an iWave Director configuration file. [ReceiveFromSSL] ServiceManager1=recvssl
ssl_recv_name Section (UNIX)

The ssl_recv_name section section defines attributes of an iWave Director from which this iWave Director will receive transactions using Secure Sockets. This section exists to provide parameters. The value specified as the section key must be named in the ReceiveFromSSL section as a ServiceManager key. Within each ssl_recv_name section the following keys are recognized.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 207 of 276
Table 9 Keys of ssl_recv_name Section (UNIX) Key IPAddress Description and Value The host name or IP address of a remote iWave Director from which this iWave Director is to accept connections using Secure Sockets for the purpose of receiving transactions. Required. The fully qualified domain name (Common Name) in the CA client certificate presented by the remote Director. Required. The certificate chain file containing the CA server certificate for this Director. Required. Must be in PEM format. The file containing the private key that corresponds to the public key in the CA server certificate. Required. Must be in PEM format. The file containing the passphrase used to encrypt the private key in the PrivateKeyFile. Required. This file is created with the iwpasswd utility. The key of the entry in the PassphraseFile. Required The file containing one or more CA certificates of trusted CAs. Either this keyword or TrustedCACertificateDirectory must be present, and both may be present. Must be in PEM format. The full pathname of a directory containing one or more CA certificates of trusted CAs. Either this keyword or TrustedCACertificateFile must be present, and both may be present. Certificates must be in PEM format. Each file must be named by the subject names hash and an extension of .0. To get the subject names hash, enter the following openssl command: openssl x509 -in certificate-file-name noout hash Example The following is an example of a ssl_recv_name section of an iWave Director configuration file: [recvssl] IPAddress=77.3.39.101 FullyQualifiedDomainName=www.remote-domain.com CertficiateChainFile=/usr/iwave/certs/server.pem PrivateKeyFile=/usr/iwave/certs/privatekey.pem PassphraseFile=/usr/iwave/config/passphrase PassphraseFileKey=sslkey TrustedCACertificateDirectory=/usr/iwave/cacerts
FullyQualifiedDomainName CertificateChainFile PrivateKeyFile
PassphraseFile
PassphraseFileKey TrustedCACertificateFile
TrustedCACertificateDirectory
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 208 of 276
ssl_recv_name Section (Windows)

The ssl_recv_name section section defines attributes of an iWave Director from which this iWave Director will receive transactions using Secure Sockets. This section exists to provide parameters. The value specified as the section key must be named in the ReceiveFromSSL section as a ServiceManager key. Within each ssl_recv_name section the following keys are recognized.
Table 10 Keys of ssl_recv_name Section (Windows) Key IPAddress Description and Value The host name or IP address of a remote iWave Director from which this iWave Director is to accept connections using Secure Sockets for the purpose of receiving transactions. Required. The fully qualified domain name (Common Name) in the CA client certificate presented by the remote Director. Required. The certificate chain file containing the CA server certificate for this Director. Required. Must be in PEM format. The file containing the private key that corresponds to the public key in the CA server certificate. Required. Must be in PEM format. The file containing the passphrase used to encrypt the private key in the PrivateKeyFile. Required. This file is created with the iwpasswd utility. The key of the entry in the PassphraseFile. Required. The file containing one or more CA certificates of trusted CAs. Required. Must be in PEM format.
PassphraseFile
Example The following is an example of a ssl_recv_name section of a iWave Director configuration file: [recvssl] IPAddress=77.3.39.101 FullyQualifiedDomainName=www.remote-domain.com CertficiateChainFile=c:\iwave\certs\server.pem PrivateKeyFile=c:\iwave\certs\privatekey.pem PassphraseFile=c:\iwave\config\passphrase PassphraseFileKey=sslkey TrustedCACertificateFile=c:\iwave\certs\root.pem
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 209 of 276
SendTo Section
The SendTo section of the iWave Director configuration file identifies all iWave Directors that own services to which this iWave Director is to send transactions. The following keys are recognized in records in the SendTo section. Table 11 Keys of SendTo Section Key ServiceManagern Description and Value A remote iWave Director to which this iWave Director is to connect for the purpose of sending transactions to Servers. This is the name of a section in the configuration file (iwave_director_name) containing keys applicable to this iWave Director. At least 1 instance of this key is required.
Examples The following is an example of a SendTo section of an iWave Director configuration file. [SendTo] ServiceManager1=RemoteManager
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 210 of 276
iwave_director_name Section (z/OS)

The iwave_director_name section defines attributes of an iWave Director to which this iWave Director will send transactions. This section exists to provide parameters for use with an iWave Director named in the SendTo section. The value specified as the section key must be named in the SendTo Section as a ServiceManagerx key. Within each iwave_director_name section the following keys are recognized. Table 12 Keys of iwave_director_name Section (z/OS) Key IPAddress Description and Value The Internet address of the SendTo iWave Directors Transaction Port. Required. The value is a comma-delimited list of 2 items: 1) the host name or IP address of the SendTo iWave Director, 2) the ServiceReceiveFromPort of the SendTo iWave Director. The IP port number to be used on the local system when connecting to the address specified by the IPAddress key. Optional. If not defined, iWave Director uses a port number assigned by the operating system. Configure this option if the system at the address specified by the IPAddress key requires that incoming connections originate at specific IP port numbers; this is typically the case when the system at the address specified by the IPAddress key is behind a firewall. The time interval, in seconds, that the local iWave Director should wait for a remote Server to process a transaction request. Required. This keyword is used to prevent firewall timeouts. When this keyword is used, Director sends a ping message to the remote Director and waits for an echo message in response. The syntax is: ping-interval[,echo-interval] where ping-interval is the number of seconds between ping messages, and echo-interval is the number of seconds to wait for the echo message response. If the echo message does not return within echo-interval seconds, Director breaks its connection with the remote Director, and then attempts to reconnect to the remote Director at one minute intervals thereafter.
OriginPort
Timeout
PingInterval
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 211 of 276
PingInterval Continued
If echo-interval is not specified, then the Timeout value is used as the echo message wait interval. Since ping-interval is used to determine the availability of a remote Director, it may be a large value, perhaps 30 to 60 minutes. However, once a ping has been sent the remote Director should respond immediately, so the echo-interval should be a very small value, perhaps 5 to 15 seconds. As a consequence, if the Timeout for the remote machine is large, it is not typically recommended to supply only one value for this keyword. This keyword is meaningful only when MultipleServerOwners=true (in the Base section). This keyword tells Director whether (true) or not (false) this SendTo Director is the primary owner of all of its servers. All transactions for servers owned by this Director are to be sent only to this Director. However, if the connection to this Director is lost, all transactions for this Director's servers are to be sent to any other SendTo Director that has ownership of these servers. When a SendTo Director is the primary owner of its servers, the local Director does not perform load balancing for these servers.
Primary
Examples The following is an example of a iwave_director_name section of an iWave Director configuration file, containing definitions of one SendTo iWave Director. [SendTo] ServiceManager1=RemoteManager1 [RemoteManager1] This is an iwave_director_name section IPAddress=falcon,3975 OriginPort=17777 Timeout=20 PingInterval=1800,5
iwave_director_name Section (UNIX and Windows)

The iwave_director_name section defines attributes of an iWave Director to which this iWave Director will send transactions. This section exists to provide parameters for use with an iWave Director named in the SendTo section. The value specified as the section key must be named in the SendTo Section as a ServiceManager key. Within each iwave_director_name section the following keys are recognized.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 212 of 276
Table 13 Keys of iwave_director_name Section (UNIX and Windows) Key IPAddress Description and Value The Internet address of the SendTo iWave Directors Transaction Port. Required. Three formats are supported: 1. dotted-decimal dotted-decimal-ip-address,port or dotted-decimal-ip-address:port The only difference between these formats is the choice of delimiter. Either comma (,) or colon (:) may be used. 2. domain name domain-or-host-name,port or domain-or-host-name:port The only difference between these formats is the choice of delimiter. Either comma (,) or colon (:) may be used. 3. URL [scheme:]//domain-name[:port][/path] The IP port number to be used on the local system when connecting to the address specified by the IPAddress key. Optional. If not defined, iWave Director uses a port number assigned by the operating system. Configure this option if the system at the address specified by the IPAddress key requires that incoming connections originate at specific IP port numbers; this is typically the case when the system at the address specified by the IPAddress key is behind a firewall. The IP address to be used on the local system when connecting to the address specified by the IPAddress key. Optional. If not defined, iWave Driector uses the IPAddress associated with the host name returned by gethostname(). Configure this option if the system at the address specified by the IPAddress key requires that incoming connections originate at specific IP addresses, and the local system is multi-homed; this is typically the case when the system at the address specified by the IPAddress key is behind a firewall. The time interval, in seconds, that the local iWave Director should wait for a remote Server to process a transaction request. Required. The text of a command to be executed before the local iWave Director attempts to connect to the SendTo iWave Director, enclosed in parentheses. Optional. If not provided, a command is not executed before the local iWave Director connects to the SendTo iWave Director. The syntax of this keyword is: PreCommand=executable-path [token-list] where: executable-path is the full pathname of the command processor and may not contain spaces. token-list is a list of optional tokens, separated by whitespace, to be passed to the command processor.
OriginPort
LocalIPAddress
Timeout
PreCommand
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 213 of 276
Table 13 Keys of iwave_director_name Section (UNIX and Windows) Cont Key PostCommand Description and Value The text of a command to be executed after the local iWave Director disconnects from the SendTo iWave Director, enclosed in parentheses. Optional. If not provided, a command is not executed after the local iWave Director disconnects from the SendTo iWave Director. The syntax of this keyword is: PostCommand=executable-path [token-list] where: executable-path is the full pathname of the command processor and may not contain spaces token-list is a list of optional tokens, separated by whitespace, to be passed to the command processor. PingInterval This keyword is used to prevent firewall timeouts. When this keyword is used, Director sends a ping message to the remote Director and waits for an echo message in response. The syntax is: ping-interval[,echo-interval] where ping-interval is the number of seconds between ping messages, and echo-interval is the number of seconds to wait for the echo message response. If the echo message does not return within echo-interval seconds, Director breaks its connection with the remote Director, and then attempts to reconnect to the remote Director at one minute intervals thereafter. If echo-interval is not specified, then the Timeout value is used as the echo message wait interval. Since pinginterval is used to determine the availability of a remote Director, it may be a large value, perhaps 30 to 60 minutes. However, once a ping has been sent the remote Director should respond immediately, so the echo-interval should be a very small value, perhaps 5 to 15 seconds. As a consequence, if the Timeout for the remote machine is large, it is not typically recommended to supply only one value for this keyword. This keyword is meaningful only when MultipleServerOwners=true (in the Base section). This keyword tells Director whether (true) or not (false) this SendTo Director is the primary owner of all of its servers. All transactions for servers owned by this Director are to be sent only to this Director. However, if the connection to this Director is lost, all transactions for this Director's servers are to be sent to any other SendTo Director or SendToSSL Director that has ownership of these servers. When a SendTo Director is the primary owner of its servers, the local Director does not perform load balancing for these servers.
Primary
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 214 of 276
Table 13 Keys of iwave_director_name Section (UNIX and Windows) Cont Key ProxyMode Description and Value The SOCKS proxy protocol to be used when connecting to the remote Director. The protocol may be either SOCKS4 or SOCKS5. The Internet address of the SOCKS proxy host is specified by the ProxyIPAddress keyword. The Internet address of the SOCKS proxy host through which the remote Director is to be connected. The specific SOCKS protocol to be used is specified by the ProxyMode keyword. Any of the address formats of the IPAddress keyword may be used. The number of seconds to wait for a SOCKS protocol response from the proxy host identified by the ProxyIPAddress keyword. Default is 15 seconds. 0 indicates no time limit. The optional userid to be included in the SOCKS4 protocol handshake with the SOCKS proxy host identified by the ProxyIPAddress keyword. Consult your proxy host documentation or administrator to determine if the userid is required. Indicates whether (1) or not (0) the connection to the remote Director is to be persisent. If not persistent, the connection is made only when there is a transaction to be sent to the remote Director, and is broken after the transaction response is received.
ProxyIPAddress
ProxyWait
SOCKS4Userid
Persist
Example The following is an example of a iwave_director_name section of an iWave Director configuration file. [SendTo] ServiceManager1=RemoteManager1 [RemoteManager1] This is an iwave_director_name section IPAddress1=77.15.28.195,7350 OriginPort=17777 Timeout=20
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 215 of 276
SendToSSL Section (UNIX and Windows)

The SendToSSL section of the iWave Director configuration file identifies all iWave Directors that own services to which this iWave Director is to send transactions using Secure Sockets (SSL). The following keys are recognized in records in the SendToSSL section. Table 14 Keys of SendToSSL Section Key ServiceManagern Description and Value A remote iWave Director to which this iWave Director is to connect for the purpose of sending transactions to Servers using Secure Sockets (SSL). This is the name of a section in the configuration file (ssl_send_name) containing keys applicable to this iWave Director. At least 1 instance of this key is required.
Examples The following is an example of a SendToSSL section of an iWave Director configuration file [SendToSSL] ServiceManager1=SSLDirector
ssl_send_name Section (UNIX and Windows)

The ssl_send_name section defines attributes of an iWave Director to which this iWave Director will send transactions using Secure Sockets (SSL). This section exists to provide parameters for use with an iWave Director named in the SendToSSL section. The value specified as the section key must be named in the SendToSSL Section as a ServiceManager key. Within each ssl_send_name section the following keys are recognized.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 216 of 276
Table 15 Keys of ssl_send_name Section (UNIX and Windows) Key IPAddress Description and Value The Internet address of the SendToSSL iWave Directors and the port number defined in an ssl_recv_name section of that Director. Required. Three formats are supported: 1. dotted-decimal dotted-decimal-ip-address,port or dotted-decimal-ip-address:port The only difference between these formats is the choice of delimiter. Either comma (,) or colon (:) may be used. 2. domain name domain-or-host-name,port or domain-or-host-name:port The only difference between these formats is the choice of delimiter. Either comma (,) or colon (:) may be used. 3. URL [scheme:]//domain-name[:port][/path] The IP port number to be used on the local system when connecting to the address specified by the IPAddress key. Optional. If not defined, iWave Director uses a port number assigned by the operating system. Configure this option if the system at the address specified by the IPAddress key requires that incoming connections originate at specific IP port numbers; this is typically the case when the system at the address specified by the IPAddress key is behind a firewall. The time interval, in seconds, that the local iWave Director should wait for a remote Server to process a transaction request. Required. This keyword is used to prevent firewall timeouts. When this keyword is used, Director sends a ping message to the remote Director and waits for an echo message in response. The syntax is: ping-interval[,echo-interval] where ping-interval is the number of seconds between ping messages, and echo-interval is the number of seconds to wait for the echo message response. If the echo message does not return within echo-interval seconds, Director breaks its connection with the remote Director, and then attempts to reconnect to the remote Director at one minute intervals thereafter. If echo-interval is not specified, then the Timeout value is used as the echo message wait interval. Since pinginterval is used to determine the availability of a remote Director, it may be a large value, perhaps 30 to 60 minutes. However, once a ping has been sent the remote Director should respond immediately, so the echo-interval should be a very small value, perhaps 5 to 15 seconds. As a consequence, if the Timeout for the remote machine is large, it is not typically recommended to supply only one value for this keyword.
OriginPort
Timeout
PingInterval
iWave Software
Revised [03/01/07] P01-664-09
Table 15 Keys of ssl_send_name Section (UNIXand Windows) Cont Key Primary Description and Value This keyword is meaningful only when MultipleServerOwners=true (in the Base section). This keyword tells Director whether (true) or not (false) this SendToSSL Director is the primary owner of all of its servers. All transactions for servers owned by this Director are to be sent only to this Director. However, if the connection to this Director is lost, all transactions for this Director's servers are to be sent to any other SendTo Director or SendToSSL Director that has ownership of these servers. When a SendToSSL Director is the primary owner of its servers, the local Director does not perform load balancing for these servers. PreCommand The text of a command to be executed before the local iWave Director attempts to connect to the SendToSSL iWave Director, enclosed in parentheses. Optional. If not provided, a command is not executed before the local iWave Director connects to the SendToSSL iWave Director. The text of a command to be executed after the local iWave Director disconnects from the SendToSSL iWave Director, enclosed in parentheses. Optional. If not provided, a command is not executed after the local iWave Director disconnects from the SendToSSL iWave Director. The fully qualified domain name (Common Name) in the CA server certificate presented by the remote Director. Required. The certificate chain file containing the CA client certificate for this Director. Required. Must be in PEM format. The file containing the private key that corresponds to the public key in the CA client certificate. Required. Must be in PEM format. The file containing the passphrase used to encrypt the private key in the PrivateKeyFile. Required. This file is created with the iwpasswd utility. The key of the entry in the PassphraseFile. Required The file containing one or more CA certificates of trusted CAs. This keyword is required for Windows. For UNIX, either this keyword or TrustedCACertificateDirectory must be present, and both may be present. Must be in PEM format. The full pathname of a directory containing one or more CA certificates of trusted CAs. This keyword is ignored for Windows. For UNIX, either this keyword or TrustedCACertificateFile must be present, and both may be present. Certificates must be in PEM format. Each file must be named by the subject names hash and an extension of .0. To get the subject names hash, enter the following openssl command: openssl x509 -in certificate-file-name noout hash
PostCommand
PassphraseFile
TrustedCACertificateDirectory
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 218 of 276
Table 15 Keys of ssl_send_name Section (UNIXand Windows) Cont Key ProxyMode Description and Value The SOCKS proxy protocol to be used when connecting to the remote Director. The protocol may be either SOCKS4 or SOCKS5. The Internet address of the SOCKS proxy host is specified by the ProxyIPAddress keyword. The Internet address of the SOCKS proxy host through which the remote Director is to be connected. The specific SOCKS protocol to be used is specified by the ProxyMode keyword. Any of the address formats of the IPAddress keyword may be used. The number of seconds to wait for a SOCKS protocol response from the proxy host identified by the ProxyIPAddress keyword. Default is 15 seconds. 0 indicates no time limit. The optional userid to be included in the SOCKS4 protocol handshake with the SOCKS proxy host identified by the ProxyIPAddress keyword. Consult your proxy host documentation or administrator to determine if the userid is required.
ProxyIPAddress
ProxyWait
SOCKS4Userid
Examples The following is a UNIX example of an ssl_send_name section of an iWave Director configuration file. [SendToSSL] ServiceManager1=SSLDirector [SSLDirector] This is an ssl_send_name section IPAddress1=77.15.28.195,7350 OriginPort=17777 Timeout=20 PingInterval=1800,4 FullyQualifiedDomainName=www.remote-domain.com CertificateChainFile=/usr/iwave/certs/client.pem PrivateKeyFile=/usr/iwave/certs/privatekey.pem PassphraseFile=/usr/iwave/config/passphrase PassphraseFileKey=mypass TrustedCACertificateFile=/usr/iwave/certs/root.pem The following is a Windows example of an ssl_send_name section of an iWave Director configuration file. [SendToSSL] ServiceManager1=SSLDirector [SSLDirector] This is an ssl_send_name section IPAddress1=77.15.28.195,7350 OriginPort=17777 Timeout=20 PingInterval=1800,4 FullyQualifiedDomainName=www.remote-domain.com CertificateChainFile=c:\iwave\certs\client.pem PrivateKeyFile=c:\iwave\certs\privatekey.pem PassphraseFile=c:\iwave\config\passphrase PassphraseFileKey=mypass TrustedCACertificateFile=c:\iwave\certs\root.pem
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 219 of 276
Services Section
Each record in the Services section of the iWave Director configuration fileidentifies the Server that is to be managed by iWave Director. Each record contains one key, with the following format. Table 16 Keys of Services Section Key Servicen Description and Value Name of a section in the configuration file (service_name) containing keys applicable to this Server. This is also the name of the Server as it is known to the Client. This is a 18 character string. The service_name must be unique among all keys in the Services section.
Notes There are a number of reasons that you might define additional iWave Servers for an iWave Integrator:
The most common reason is performance. You can use scaled iWave Servers, but not all iWave Integrators support scaling. Also, iWave Clients running in poll mode do not support scaling. If you are using an iWave Client running in poll mode and need to increase throughput, you must use multiple iWave Clients. If the target iWave Server does not support scaling, you must also use multiple iWave Servers. When using poll mode with multiple object classes, you run the risk of a highpriority problem record waiting while hundreds of low-priority inventory or contact records are processed. In this case, you might have one iWave Client processing only problem records, and one or more additional iWave Clients processing the other record types. Again, if the target iWave Server does not support scaling, you must use separate iWave Servers.
Example The following is an example of a Services section of an iWave Director configuration file. [Services] Service1=sdrdysa
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 220 of 276
service_name Section (z/OS)

A service_name section entry is required for each Service key within the Services section of the configuration file. Within each service_name section the following keys are recognized. Table 17 Keys of service_name Section (z/OS) Key EndpointName ApplicationName BasicScaling Description and Value Name of the iWave Integrator of which this Server is a component. Optional. Default name is Anonymous. Name of this component within its iWave Integrator. Optional. Default is service_ name. Basic Server scalability specification. A decimal number specifying the number of processes in which this Server will execute concurrently. This is the number of Server child processes that iWave Director starts when iWave Director starts. A value of 0 is equivalent to a value of 1. This key is mutually exclusive with the EnhancedScaling key. Enhanced Server scalability specification. A comma-delimited list of 4 decimal values. This key is mutually exclusive with the BasicScaling key. The meanings of the values are as follows: Value Ordinal 1 2 Description MAXPROCESS value. Specifies the maximum number of child processes for the Server. MINPROCESS value. Specifies the minimum number of child processes for the Server. iWave Director starts this number of child processes when iWave Directorstarts. When MINPROCESS equals MAXPROCESS, iWave Director uses basic scalability for the Server. MAXDEPTH value. Specifies the number of unprocessed transaction requests that, if exceeded, causes iWave Director to start another child process, subject to the upper limit specified by the MAXPROCESS value. If iWave Director receives a transaction request and this limit has already been reached, iWave Director starts a new child process. iWave Director ignores this value when MAXPROCESS and MINPROCESS are equal. QUIESCE value. The time duration in minutes, during which there are no transactions queued for processing and no transactions being processed, that must elapse before all child processes with no transactions being processed are stopped, subject to the lower limit specified by the MINPROCESS value.
EnhancedScaling
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 221 of 276
Table 17 Keys of service_name Section (z/OS) Cont Key EnhancedScaling Continued Description and Value This value determines how rapidly a buildup of child processes is dissipated after a burst of transactions has been completed. iWave Director ignores this value when MAXPROCESS and MINPROCESS are equal. A value of zero (0) is equivalent to a value of one (1) minute. The ddname of the applications processing file. Required. A plus-delimited list of log options. Optional. If this key is omitted, the default is no logging other than the copyright notice and the termination notice. The log options for the iWave Client and Server are as follows: FILESInclude processing and mapping file contents in the Client or Server log. INITHow processing and mapping files were used during initialization. MEMORYDynamic memory allocation and deallocation. PDETMessages about parsing the processing and mapping files. REQRequest transactions generated by the Client. RESPResponse transactions generated by the Server. TFIELDSData model fields and vendor fields used in a transaction. UOWProcessing file section names and identifiers for each object processed. WARNWarnings, typically generated by the underlying database system. ADETApplication information. ADETFApplication information details. APIDatabase API. EVENTInformation about Client and Agent operation and the related transaction data. FAPIFFramework API details. FDETFramework information. FDETFFramework information details. IAPIDatabase API details. FAPIFramework API. EXITExits. DETAILSSpecifying DETAILS in LogOptions is the same as specifying ADET+ADETF+FDET+FDETF+EXIT. Example: LogOptions=API+IAPI+WARN Note that LogOptions are also valid for any managed Agents; however, Agents have a more restricted set of logging options and what is logged is entirely determined by the Agent.
ProcessingFile LogOptions
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 222 of 276
Table 17 Keys of service_name Section (z/OS) Cont Key LogOptions Continued Description and Value This is important for a log option such as UOW. For Clients and Servers, UOW is picked up by the framework and always logs some basic information about each transaction. In the Agents, UOW only causes something to be recorded if the Agent is coded to do something with that option. The following are the log options for managed Agents: ADET ADETF API IAPI INIT UOW
The descriptions of the logging options for the Agent should be essentially the same as for Clients and Servers, except that it is entirely dependent on the coding of the Agent what options are used and what they do. RestartDelayInterval When a Server instance terminates, it may notify the iWave Director that another instance of the same Server may be started only after a delay. The value of this key is the time duration in seconds of the delay. If a Server instance terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If a Server instance terminates with this condition, then there may or may not be any remaining server instances available to process transactions. If there are no remaining instances, any transactions waiting for this Server are returned to the originating Clients with an iWave reason code of 106. If any transactions for the Server subsequently arrive, each transaction is return with iWave reason code of 106, until the delay interval expires and the iWave Director starts a Server instance. If instances remain, the Server scaling algorithm related to MINPROCESS, MAXPROCESS, and MAXDEPTH is suspended until the delay interval expires. If the iWave Director is waiting for the expiration of this delay interval, and an iWave Authorized User sends either a Start command, a Stop command, a Cycle command, or a Kill command for the Server, then the iWave Director immediately cancels its iWave Integrator Restart logic and commences normal command processing.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 223 of 276
Key AutoRestartMax
Description and Value The maximum number of times that Director will attempt to start the server when iWave is initially started. The delay between restart attempts is controlled by the RestartDelayInterval keyword. The date and time at which the server is to be automatically cycled. The value uses the syntax of UNIX crontab, which is a list of 5 numbers: minute (0-59) hour (0-23) day of month (1-31) month (1-12) day of week (0-6, 0 is Sunday) Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a hyphen (meaning an inclusive range). Note that the specification of days may be made by two fields (day of month and day of week). Both are adhered to if specified as a list of elements. If minute is *, it is changed to 0. Multiple instances of this keyword are supported.
AutoCycleClock
AutoStartClock AutoStopClock
The date and time at which the server is to be automatically started. Uses the same syntax as AutoCycleClock. The date and time at which the server is to be automatically stopped. Uses the same syntax as AutoCycleClock.
Notes iWave Director always manages a separate log for each Server, and always adds the I:T prefix to each log message, where I represents each instance (0 is the original, 1 is the first copy, 2 is the second copy, and so on) and T is the transaction number (1 is the first transaction processed by I, 2 is the second transaction processed by I, and so on). The ddname of the log file is service_name. When iWave Director writes a log message concerning a Server to its log (not to be confused with the log for the Server), it refers to the Server by its ApplicationName.
Example The following is an example of a service_name section of an iWave Director configuration file. [Services] Service1=infosa [infosa]
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 224 of 276
EndpointName=Information/Management ApplicationName=Info/Man Server EnhancedScaling=3,1,0,10 ProcessingFile=INFOSPRC LogOptions=TFIELDS LoadModule=PBMXMAPP AutoStopClock=59 3 * * 5 AutoStartClock=03 5 * * 5
service_name Section (UNIX and Windows)

A service_name section entry is required for each Service key within the Services section of the configuration file. Within each service_name section the following keys are recognized. Table 18 Keys of service_name Section (UNIX and Windows) Key EndpointName ApplicationName ApplPath Description and Value Name of the iWave Integrator of which this Server is a component. Optional. Default name is Anonymous. Name of this component within its iWave Integrator. Optional. Default is service_ name. The full pathname of the application executable. Required when ApplLoader is not used. Mutually exclusive with ApplLoader. Any DLLs required by this application may be located in the same directory. This keyword is used in place of the ApplPath keyword. Required when ApplPath is not used. Mutually exclusive with ApplPath. The purpose of this keyword is to allow an intermediary application, e.g. a Java Virtual Machine, to start a managed application. The syntax of this keyword is: ApplLoader=executable-path token-list where: executable-path is the full pathname of the intermediary application and may not contain spaces token-list is a list of tokens, separated by whitespace, to be passed to the intermediary application. Quoted strings () are supported for inclusion of whitespace in tokens. If a double-quote is to be included in a token, escape it with backslash (\). The full pathname of the managed application executable may be among these tokens, depending on how the intermediary works.
ApplLoader
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 225 of 276
Table 18 Keys of service_name Section (UNIX and Windows) Cont Key Description and Value Director always passes a standard list of command line arguments to managed applications. When ApplLoader is used in place of ApplPath, Director creates an argument list consisting of the token-list tokens, followed by the standard arguments. BasicScaling Basic Server scalability specification. A decimal number specifying the number of processes in which this Server will execute concurrently. This is the number of Server child processes that iWave Director will start when the iWave Director starts. A value of 0 is equivalent to a value of 1. This key is mutually exclusive with the EnhancedScaling key. Enhanced Server scalability specification. A comma-delimited list of 4 decimal values. This key is mutually exclusive with the BasicScaling key. The meanings of the values are as follows: Value Description Ordinal MAXPROCESS value. Specifies the maximum 1 number of child processes for the Server. 2 MINPROCESS value. Specifies the minimum number of child processes for the Server. iWave Director starts this number of child processes when iWave Director starts. When MINPROCESS equals MAXPROCESS, iWave Director uses basic scalability for the Server. MAXDEPTH value. Specifies the number of unprocessed transaction requests that, if exceeded, causes iWave Director to start another child process, subject to the upper limit specified by the MAXPROCESS value. If iWave Director receives a transaction request and this limit has already been reached, iWave Director starts a new child process. iWave Director ignores this value when MAXPROCESS and MINPROCESS are equal. QUIESCE value. The time duration in minutes, during which there are no transactions queued for processing and no transactions being processed, that must elapse before all child processes with no transactions being processed are stopped, subject to the lower limit specified by the MINPROCESS value. This value determines how rapidly a buildup of child processes is dissipated after a burst of transactions has been completed. iWave Director ignores this value when MAXPROCESS and MINPROCESS are equal. A value of zero (0) is equivalent to a value of one (1) minute.
EnhancedScaling
ProcessingFile LogOptions
The full pathname of the processing file. Required. A plus-delimited list of log options. Optional.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 226 of 276
Table 18 Keys of service_name Section (UNIX and Windows) Cont Key RestartDelayInterval Description and Value When a Server instance terminates, it may notify the iWave Director that another instance of the same Server may be started only after a delay. The value of this key is the time duration in seconds of the delay. If a Server instance terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If a Server instance terminates with this condition, then there may or may not be any remaining server instances available to process transactions. If there are no remaining instances, any transactions waiting for this Server are returned to the originating Clients with an iWave reason code of 106. If any transactions for the Server subsequently arrive, each transaction is return with iWave reason code of 106, until the delay interval expires and the iWave Director starts a Server instance. If instances remain, the Server scaling algorithm related to MINPROCESS, MAXPROCESS, and MAXDEPTH is suspended until the delay interval expires. If the iWave Director is waiting for the expiration of this delay interval, and an iWave Authorized User sends either a Start command, a Stop command, a Cycle command, or a Kill command for the Server, then the iWave Director immediately cancels its iWave Integrator Restart logic and commences normal command processing. AutoRestartMax The maximum number of times that Director will attempt to start the server when iWave is initially started. The delay between restart attempts is controlled by the RestartDelayInterval keyword. The maximum number of generations for the servers log file. Before Director starts a new log file, it looks for the number of generations then in existence. If the number is not less than MaxLogFiles, it deletes generations, starting with the oldest, until the number of generations is one less than MaxLogFiles. Log files are named with a generation number suffix. The current log file always has suffix ".0". Successively older generations have suffix ".1", ".2", etc. When Director deletes a generation in preparation for opening a new log file with generation suffix ".0", it also renames the remaining generations. If MaxLogSize is configured but MaxLogFiles is not configured, the default for MaxLogFiles is 1.
MaxLogFiles
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 227 of 276
Table 18 Keys of service_name Section (UNIX and Windows) Cont Key MaxLogSize Description and Value The maximum byte count for the servers log file. When MaxLogSize is exceeded for a log, Director will start a new log. If MaxLogSize is not configured or is zero, no attempt is made to manage maximum log size or log generations (MaxLogFiles is ignored). AutoCycleClock The date and time at which the server is to be automatically cycled. The value uses the syntax of UNIX crontab, which is a list of 5 numbers: minute (0-59) hour (0-23) day of month (1-31) month (1-12) day of week (0-6, 0 is Sunday) Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a hyphen (meaning an inclusive range). Note that the specification of days may be made by two fields (day of month and day of week). Both are adhered to if specified as a list of elements. If minute is *, it is changed to 0. Multiple instances of this keyword are supported. AutoStartClock AutoStopClock The date and time at which the server is to be automatically started. Uses the same syntax as AutoCycleClock. The date and time at which the server is to be automatically stopped. Uses the same syntax as AutoCycleClock.
Other Differences iWave Director always manages a separate log for each Server. It is located in the directory named by the LogPath key in the Base section. When iWave Director writes a log message concerning a Server to its log (not to be confused with the log for the Server), it refers to the Server by its ApplicationName.
Example The following is an example of a service_name section of an iWave Director configuration file. [Services] Service=1sdrdysa [sdrdysa] EndpointName=Remedy Action Request System
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 228 of 276
ApplicationName=Remedy Server ApplPath=c:\skywiresoftware\iwave\integrator\bin\sdrdysa.exe EnhancedScaling=1,3,0,10 ProcessingFile=c:\skywiresoftware\iwave\integrator\config\rdysapro c LogOptions=TFIELDS+FILES MaxLogFiles=6 MaxLogSize=500000 AutoCycleClock=59 3 * * 5
ClientApplications Section
Each record in the ClientApplications section of the iWave Director configuration file identifies a Client component of an iWave Integrator that is to be managed by iWave Director.
NOTE been removed to the ClientApplications section. It now references Clients only.
Each record contains one key, with the following format: Table 19 Keys of ClientApplications Section Key Applicationn Description and Value
The OtherApplications section from previous versions of the configuration file has
Name of a section in the configuration file (application_name) containing keys applicable to this Client. The application_name must be unique among all keys in the ClientApplications section. For z/OS, this name cannot exceed 8 characters in length, may include only alphanumeric or national ($,#,@) characters, and must start with an alphabetic or national character.
Notes There are a number of reasons that you might define additional iWave Clients for an iWave Integrator: The most common reason is performance. You can use scaled iWave Clients, but not all iWave Integrators support scaling. Also, iWave Clients running in poll mode do not support scaling. If you are using an iWave Client running in poll mode and need to increase throughput, you must use multiple iWave Clients. If the target iWave Server does not support scaling, you must also use multiple iWave Servers. When using poll mode with multiple object classes, you run the risk of a highpriority problem record waiting while hundreds of low-priority inventory or contact records are processed. In this case, you might have one iWave Client processing only problem
iWave Software
Revised [03/01/07] P01-664-09
records, and one or more additional iWave Clients processing the other record types. Again, if the target iWave Server does not support scaling, you must use separate iWave Servers. Some customers use a special iWave Client running in poll mode to send a record at regular intervals to prevent a firewall or other software from forcing a disconnect if the connection is idle for some predefined period of time. Sending the record periodically prevents the time-out condition.
Example The following is an example of a ClientApplications section of an iWave Director configuration file. [ClientApplications] Application1=sdrdyca
application_name Section (z/OS)

An application_name section entry is required for each Application key within the ClientApplications section of the configuration file. Within each application_name section the following keys are recognized: Table 20 Keys of application_name Section (z/OS) Key EndpointName ApplicationName ProcessingFile LogOptions LoadModule RestartDelayInterval Description and Value Name of the iWave Integrator of which this Server is a component. Optional. Default name is Anonymous. Name of this component within its iWave Integrator. Optional. Default is application_name. The ddname of the processing file. Required. A plus-delimited list of log options. Optional. The name of the load module for this application. Optional. The default is application_name if this is a valid load module name. When a Client running in poll mode terminates, it may notify the iWave Director duration in seconds of the delay. If a Client terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If the iWave Director is waiting for the expiration of this delay interval, and an iWave Authorized User sends either a Start command, a Stop command, a Cycle command, or a Kill
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 230 of 276
Table 20 Keys of application_name Section (z/OS) Cont Key RestartDelayInterval Continued Description and Value command for the Client, then the iWave Director immediately cancels its iWave Integrator Restart logic and commences normal command processing. When a child process of a Client running in event mode terminates, it may notify the Client parent process that it may be started again only after a delay. The value of this key is the time duration in seconds of the delay. If an event-mode child process terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If an event-mode child process terminates with this condition, then there may or may not be any remaining child processes available to process Agent requests. If there are no remaining event-mode child processes, any Agent requests that subsequently arrive are held by the parent process until the delay interval expires and the parent process starts a child process. If event mode child processes remain, the Client scaling algorithm related to MINPROCESS, MAXPROCESS, and MAXDEPTH is suspended until the delay interval expires. AutoRestartMax The maximum number of times that Director will attempt to start the client when iWave is initially started. The delay between restart attempts is controlled by the RestartDelayInterval keyword. The date and time at which the client is to be automatically cycled. The value uses the syntax of UNIX crontab, which is a list of 5 numbers: minute (0-59) hour (0-23) day of month (1-31) month (1-12) day of week (0-6, 0 is Sunday) Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a hyphen (meaning an inclusive range). Note that the specification of days may be made by two fields (day of month and day of week). Both are adhered to if specified as a list of elements. If minute is *, it is changed to 0. Multiple instances of this keyword are supported. AutoStartClock The date and time at which the client is to be automatically started. Uses the same syntax as AutoCycleClock.
AutoCycleClock
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 231 of 276
Table 20 Keys of application_name Section (z/OS) Cont Key AutoStopClock Description and Value The date and time at which the client is to be automatically stopped. Uses the same syntax as AutoCycleClock.
Notes iWave Director always manages a separate log for each Client. The ddname of the log file is application_name. When iWave Director writes a log message concerning a Client to its log (not to be confused with the log for the Client), it refers to the Client by its ApplicationName.
Example The following is an example of an application_name section of an iWave Director configuration file. [ClientApplications] Application1=infoca [infoca] EndpointName=Information/Management ApplicationName=Info/Man Client ProcessingFile=INFOCPRC LoadModule=PBMXMAPP LogOptions=UOW
application_name Section (UNIX and Windows)

An application_name section entry is required for each Application key within the ClientApplications section of the configuration file. Within each application_name section the following keys are recognized. Table 21 Keys of application_name Section (UNIX and Windows) Key EndpointName ApplicationName ApplPath Description and Value Name of the iWave Integrator of which this Server is a component. Optional. Default name is Anonymous. Name of this component within its iWave Integrator. Optional. Default is application_name. The full pathname of the application executable. Required when ApplLoader is not used. Mutually exclusive with ApplLoader. Any DLLs required by this application should be located in the same directory.
iWave Software
Revised [03/01/07] P01-664-09
Table 21 Keys of application_name Section (UNIX and Windows) Cont Key ApplLoader Description and Value This keyword is used in place of the ApplPath keyword. Required when ApplPath is not used. Mutually exclusive with ApplPath. The purpose of this keyword is to allow an intermediary application, e.g. a Java Virtual Machine, to start a managed application. The syntax of this keyword is: ApplLoader=executable-path token-list where: executable-path is the full pathname of the intermediary application and may not contain spaces token-list is a list of tokens, separated by whitespace, to be passed to the intermediary application. Quoted strings () are supported for inclusion of whitespace in tokens. If a double-quote is to be included in a token, escape it with backslash (\). The full pathname of the managed application executable may be among these tokens, depending on how the intermediary works. Director always passes a standard list of command line arguments to managed applications. When ApplLoader is used in place of ApplPath, Director creates an argument list consisting of the token-list tokens, followed by the standard arguments. ProcessingFile LogOptions RestartDelayInterval The full pathname of the processing file. Required. A plus-delimited list of log options. Optional. When a Client running in poll mode terminates, it may notify the iWave Director that it may be started again only after a delay. The value of this key is the time duration in seconds of the delay. If a Client terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If the iWave Director is waiting for the expiration of this delay interval, and an iWave Authorized User sends either a Start command, a Stop command, a Cycle command, or a Kill command for the Client, then the iWave Director immediately cancels its iWave Integrator Restart logic and commences normal command processing. When a child process of a Client running in event mode terminates, it may notify the Client parent process that it may be started again only after a delay. The value of this key is the time duration in seconds of the delay. If an event-mode child process terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If an eventmode child process terminates with this condition, then there may or may not be any remaining child processes available to process Agent requests.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 233 of 276
Table 21 Keys of application_name Section (UNIX and Windows) Cont Key RestartDelayInterval Continued Description and Value If there are no remaining event-mode child processes, any Agent requests that subsequently arrive are held by the parent process until the delay interval expires and the parent process starts a child process. If event mode child processes remain, the Client scaling algorithm related to MINPROCESS, MAXPROCESS, and MAXDEPTH is suspended until the delay interval expires. AutoRestartMax The maximum number of times that Director will attempt to start the client when iWave is initially started. The delay between restart attempts is controlled by the RestartDelayInterval keyword. The maximum number of generations for the clients log file. Before Director starts a new log file, it looks for the number of generations then in existence. If the number is not less than MaxLogFiles, it deletes generations, starting with the oldest, until the number of generations is one less than MaxLogFiles. Log files are named with a generation number suffix. The current log file always has suffix ".0". Successively older generations have suffix ".1", ".2", etc. When Director deletes a generation in preparation for opening a new log file with generation suffix ".0", it also renames the remaining generations. If MaxLogSize is configured but MaxLogFiles is not configured, the default for MaxLogFiles is 1. MaxLogSize The maximum byte count for the clients log file. When MaxLogSize is exceeded for a log, Director will start a new log. If MaxLogSize is not configured or is zero, no attempt is made to manage maximum log size or log generations (MaxLogFiles is ignored). AutoCycleClock The date and time at which the client is to be automatically cycled. The value uses the syntax of UNIX crontab, which is a list of 5 numbers: minute (0-59) hour (0-23) day of month (1-31) month (1-12) day of week (0-6, 0 is Sunday) Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a hyphen (meaning an inclusive range). Note that the specification of days may be made by two fields (day of month
iWave Software
Revised [03/01/07] P01-664-09
MaxLogFiles
Confidential
Page 234 of 276
Table 21 Keys of application_name Section (UNIX and Windows) Cont Key AutoCycleClock Continued Description and Value and day of week). Both are adhered to if specified as a list of elements. If minute is *, it is changed to 0. Multiple instances of this keyword are supported. AutoStartClock AutoStopClock The date and time at which the client is to be automatically started. Uses the same syntax as AutoCycleClock. The date and time at which the client is to be automatically stopped. Uses the same syntax as AutoCycleClock.
Notes iWave Director always manages a separate log for each Client. It is located in the directory named by the LogPath key in the Base section. When iWave Director writes a log message concerning a Client to its log (not to be confused with the log for the Client), it refers to the Client by its ApplicationName.
Example The following is an example of an application_name section of an iWave Director configuration file. [ClientApplications] Application1=sdrdyca [sdrdyca] EndpointName=Remedy Action Request System ApplicationName=Remedy Client ApplPath=c:\Program Files\skywiresoftware\iWave\Integrator\ bin\sdrdyca.exe ProcessingFile=c:\Program Files\skywiresoftware\iWave\ Integrator\config\rdycaproc LogOptions=TFIELDS+UOW MaxLogFiles=6 MaxLogSize=500000
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 235 of 276
Agents Section
Each record in the new Agents section of the iWave Director configuration file identifies an event agent or notification agent component of an iWave Integrator that is to be managed by iWave Director. Each record contains 1 key, with the following format. Table 22 Keys of Agents Section Key Agentn Description and Value Name of a section in the configuration file (agent_name) containing keys applicable to this agent. The agent_name must be unique among all keys in the Agents section. For z/OS, this name cannot exceed 8 characters in length, may include only alphanumeric or national ($,#,@) characters, and must start with an alphabetic or national character.
Example The following is an example of an Agents section of an iWave Director configuration file. [Agents] Agent1=notfagent
agent_name Section (z/OS)

An agent_name section entry is required for each Agent key within the Agents section of the configuration file. Within each agent_name section the following keys are recognized. Table 23 Keys of agent_name Section (z/OS) Key EndpointName ApplicationName LoadModule RestartDelayInterval Description and Value Name of the iWave Integrator of which this Agent is a component. Optional. Default name is Anonymous. Name of this component within its iWave Integrator. Optional. Default is agent_name. The name of the load module for this agent. Optional. The default is agent_name if this is a valid load module name. When a managed agent terminates it may notify the iWave Director that it may be started again only after a delay. The value of this key is the time duration in seconds of the delay. If an Agent terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds.
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 236 of 276
Table 23 Keys of agent_name Section (z/OS) Cont Key RestartDelayInterval Continued Description and Value If the iWave Director is waiting for the expiration of this delay interval, and an iWave Authorized User sends either a Start command, a Stop command, a Cycle command, or a Kill command for the Agent, then the iWave Director immediately cancels its iWave Integrator Restart logic and commences normal command processing. The maximum number of times that Director will attempt to start the agent when iWave is initially started. The delay between restart attempts is controlled by the RestartDelayInterval keyword. The date and time at which the agent is to be automatically cycled. The value uses the syntax of UNIX crontab, which is a list of 5 numbers: minute (0-59) hour (0-23) day of month (1-31) month (1-12) day of week (0-6, 0 is Sunday) Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a hyphen (meaning an inclusive range). Note that the specification of days may be made by two fields (day of month and day of week). Both are adhered to if specified as a list of elements. If minute is *, it is changed to 0. Multiple instances of this keyword are supported. AutoStartClock AutoStopClock (user key) Notes iWave Director always manages a separate log for each agent. The ddname of the log file is agent_name. When iWave Director writes a log message concerning an agent to its log (not to be confused with the log for the agent), it refers to the agent by its ApplicationName. The keys for any Agent that iWave Director manages are included in the agent_name section in the configuration file. There are currently no managed Agents that run on z/OS. The date and time at which the agent is to be automatically started. Uses the same syntax as AutoCycleClock. The date and time at which the agent is to be automatically stopped. Uses the same syntax as AutoCycleClock. An optional user-defined key. Multiple are supported.
AutoRestartMax
AutoCycleClock
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 237 of 276
Example The following is an example of an agent_name section of an iWave Director configuration file. [Agents] Agent1=SOLVEAGT [SOLVAGT] EndpointName=SOLVE_Central ApplicationName=SOLVE:Central Agent LoadModule=PBMCSLNO
agent_name Section (UNIX and Windows)

An agent_name section entry is required for each Agent key within the Agents section of the configuration file. Within each agent_name section the following keys are recognized. Table 24 Keys of agent_name Section (UNIX and Windows) Key EndpointName ApplicationName ApplPath Description and Value Name of the iWave Integrator of which this Agent is a component. Optional. Default name is Anonymous. Name of this component within its iWave Integrator. Optional. Default is agent_name. The full pathname of the agent executable. Required when ApplLoader is not used. Mutually exclusive with ApplLoader. Any DLLs required by this agent should be located in the same directory. This keyword is used in place of the ApplPath keyword. Required when ApplPath is not used. Mutually exclusive with ApplPath. The purpose of this keyword is to allow an intermediary application, e.g. a Java Virtual Machine, to start a managed application. The syntax of this keyword is: ApplLoader=executable-path token-list where: executable-path is the full pathname of the intermediary application and may not contain spaces token-list is a list of tokens, separated by whitespace, to be passed to the intermediary application. Quoted strings () are supported for inclusion of whitespace in tokens. If a double-quote is to be included in a token, escape it with backslash (\). The full pathname of the managed application executable may be among these tokens,
ApplLoader
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 238 of 276
Table 24 Keys of agent_name Section (UNIX and Windows) Cont Key ApplLoader Continued Description and Value depending on how the intermediary works. Director always passes a standard list of command line arguments to managed applications. When ApplLoader is used in place of ApplPath, Director creates an argument list consisting of the token-list tokens, followed by the standard arguments. MaxLogFiles The maximum number of generations for the agents log file. Before Director starts a new log file, it looks for the number of generations then in existence. If the number is not less than MaxLogFiles, it deletes generations, starting with the oldest, until the number of generations is one less than MaxLogFiles. Log files are named with a generation number suffix. The current log file always has suffix ".0". Successively older generations have suffix ".1", ".2", etc. When Director deletes a generation in preparation for opening a new log file with generation suffix ".0", it also renames the remaining generations. If MaxLogSize is configured but MaxLogFiles is not configured, the default for MaxLogFiles is 1. MaxLogSize The maximum byte count for the agents log file. When MaxLogSize is exceeded for a log, Director will start a new log. If MaxLogSize is not configured or is zero, no attempt is made to manage maximum log size or log generations (MaxLogFiles is ignored). When a managed agent terminates it may notify the iWave Director that it may be started again only after a delay. The value of this key is the time duration in seconds of the delay. If an Agent terminates with this condition, and this keyword is not defined, the default time duration is 20 seconds. If the iWave Director is waiting for the expiration of this delay interval, and an iWave Authorized User sends either a Start command, a Stop command, a Cycle command, or a Kill command for the Agent, then the iWave Director immediately cancels its iWave Integrator Restart logic and commences normal command processing. AutoRestartMax The maximum number of times that Director will attempt to start the agent when iWave is initially started. The delay between restart attempts is controlled by the RestartDelayInterval keyword.
RestartDelayInterval
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 239 of 276
Table 24 Keys of agent_name Section (UNIX and Windows) Cont Key AutoCycleClock Description and Value The date and time at which the agent is to be automatically cycled. The value uses the syntax of UNIX crontab, which is a list of 5 numbers: minute (0-59) hour (0-23) day of month (1-31) month (1-12) day of week (0-6, 0 is Sunday) Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a hyphen (meaning an inclusive range). Note that the specification of days may be made by two fields (day of month and day of week). Both are adhered to if specified as a list of elements. If minute is *, it is changed to 0. Multiple instances of this keyword are supported. AutoStartClock AutoStopClock StopCmd The date and time at which the agent is to be automatically started. Uses the same syntax as AutoCycleClock. The date and time at which the agent is to be automatically stopped. Uses the same syntax as AutoCycleClock. A command to be sent to the agent when it is to stop. This command is sent only if the agent has not performed the normal connect protocol handshake with Director. The syntax of this keyword is: StopCmd=executable-path [token-list] where: executable-path is the full pathname of the command processor and may not contain spaces token-list is a list of optional tokens, separated by whitespace, to be passed to the command processor. Quoted strings () are supported for inclusion of whitespace in tokens. If a double-quote is to be included in a token, escape it with backslash (\). If this keyword is not present and the agent has not performed the normal connect protocol handshake with Director at the time when the agent is to stop, Director will force the agent to stop immediately using an OS-specific method. An Agent will only need this keyword when ApplLoader is also used and the agent does not perform the connect protocol handshake with Director. This keyword should never be needed when ApplPath is used. An optional user-defined key. Multiple are supported.
(user key)
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 240 of 276
Notes iWave Director always manages a separate log for each agent. It is located in the directory named by the LogPath key in the Base section. When iWave Director writes a log message concerning an agent to its log (not to be confused with the log for the agent), it refers to the agent by its ApplicationName. The keys for any Agent that iWave Director manages (starts and stops) are included in the agent_name section in the configuration file. Managed Agents include the iWave Agents for XML Web Services and Peregrine Service Center.
NOTE managed Agents.
The iWave Integrator Guide for each product describes the Agent settings for any
Example The following is an example of an agent_name section for the iWave Agent for XML Web Services, which is an Agent that iWave Director manages. Notice that the keys for the managed Agent are included in the agent_name section.
[Agents] Agent1=XMLAGT [XMLAGT] EndpointName=Web Services Interface ApplPath=/Program Files/skywiresoftware/iWave Integrator/bin/ PNTxmlag.EXE ;LogOptions=WARN+UOW+TFIELDS LogOptions=WARN AGENTADDR=8011 CLIENTADDR=9039 TYPEMAPFILE=/Program Files/skywiresoftware/iWave Integrator/config/type_map.txt MaxLogFiles=3 MaxLogSize=100000
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 241 of 276
F
Product Identifiers
Each iWave Integrator has a unique product number. IWave Integrators are licensed by product number. The following table relates each product number with an external product identifier which is published to customers. The external product identifier appears in log messages that describe the content of license keys. Table 25 Vendor Application Identifiers in iWave Integrator Logs Product Identifier in Logs 1 1 1 3 4 5 5 5 6 6 6 7 Product Name in Logs Service Center/MVS Service Center/NT Service Center/UNIX Info/Management/MVS SOLVE:Central/MVS Enterprise Management/MVS Enterprise Management/NT Enterprise Management/UNIX Universal/MVS Universal/NT Universal/UNIX ClearHelpDesk (MS-SQL)/NT Associated iWave Integrator iWave Integrator Adapter for Peregrine Service Center iWave Integrator Adapter for Peregrine Service Center iWave Integrator Adapter for Peregrine Service Center iWave Integrator Adapter for Tivoli Information Management iWave Integrator Adapter for CA SOLVE:Central iWave Integrator Adapter for Enterprise Management iWave Integrator Adapter for Enterprise Management iWave Integrator Adapter for Enterprise Management iWave Integrator Universal Interface iWave Integrator Universal Interface iWave Integrator Universal Interface iWave Integrator Adapter for Clarify
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 242 of 276
8 8
ClearHelpDesk (Oracle)/NT ClearHelpDesk (Oracle)/UNIX
iWave Integrator Adapter for Clarify iWave Integrator Adapter for Clarify
Table 25 Vendor Application Identifiers in iWave Integrator Logs Cont Product Identifier in Logs 10 10 11 11 11 12 13 13 16 16 19 22 22 22 23 25
Product Name in Logs Action Request System/NT Action Request System/UNIX DB2/MVS DB2/NT DB2/UNIX ODBC/NT Oracle/NT Oracle/UNIX ECI/NT ECI/UNIX Web Services/NT Flat File/MVS Flat File/NT Flat File/UNIX MOM/NT GSEM/NT
Associated iWave Integrator iWave Integrator Adapter for Remedy iWave Integrator Adapter for Remedy iWave Integrator Adapter for SQL iWave Integrator Adapter for SQL iWave Integrator Adapter for SQL iWave Integrator Adapter for SQL iWave Integrator Adapter for SQL iWave Integrator Adapter for SQL iWave Integrator Adapter for ECI iWave Integrator Adapter for ECI iWave Integrator Adapter for Web Services iWave Integrator Adapter for Flat Files iWave Integrator Adapter for Flat Files iWave Integrator Adapter for Flat Files iWave Integrator Adapter for Microsoft Operations Manager iWave Integrator Adapter for GSEM
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 243 of 276
G
Termination Status
When a Client, Server, or Managed Agent terminates, Director reports its exit status in the log for that Client, Server, or Managed Agent. Following are the exit statuses and their meanings. Table 26 Client Adapter Exit Statuses Status 0 1 3 4 5 6 7 8 9 10 16 17 20 21 22 23 24 26 27 28 29 30 100 128 199 1999
iWave Software
Revised [03/01/07] P01-664-09
Description normal exit cannot create ICP environment processing file not defined error registering for configuration parser error in processing file error in mapping file application initialization failed error in local object identifier serialization rule error in keywords defined in application keyword header error opening listen port (DETECTION-PORT) internal parameter error error opening application callback log error creating child process error creating socket pair error in program exit shared library AGENT-MANAGES-LOCAL-LOCK conflicts with LOCK-SPEC unable to connect to parent process unable to send to parent process socket environment initialization failure error reading stored work unit Director is back-leveled not licensed memory allocation error Windows DLL is missing incorrect number of command line arguments termination forced by Windows Director
Table 27 Server Adapter Exit Statuses Status 0 2 3 4 5 6 7 8 10 12 13 14 17 30 32 40 100 128 1999 Description normal exit log open failure processing file not defined error registering for configuration parser error in processing file error in mapping file application initialization failed error in SYNCH-FLAG-FIELD SEARCH or CREATE-UNIQUE has more than 1 table error in program exit shared library CREATE or UPDATE missing when CREATE-UNIQUE is defined and CREATE-UNIQUE-ASIS:YES is not specified CREATE-UNIQUE-ASIS in verb other than CREATE-UNIQUE error opening application callback log socket environment initialization failure cannot connect to Director incorrect number of command line arguments memory allocation error Windows DLL is missing termination forced by Windows Director
Table 28 Managed Agent Exit Statuses Status 0 128 194 195 196 199 Description normal exit Windows DLL is missing cannot send to Director cannot connect to Director socket environment initialization failure memory allocation failure
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 245 of 276
Glossary
This glossary defines the terms and abbreviations commonly used with iWave Integrator.
Term
Adapter Agent Assignment exit
Definition
See iWave Integrator Adapter. The iWave Integrator executable that provides data to a Client when the Client is in event mode. A facility that allows you to integrate a customized function into iWave Integrator so as to place a value in a data model field. System variable #EXIT# makes this integration possible. A series of characters that place a value in a data model field. The syntax is as follows, where value may be either an iWave Integrator constant or the system variable #EXIT#: data_model_field = value; A person who can run any of the actions supported by the iWave Administrator CLI that require authorization, including stopping, starting, and cycling components, and shutdown iWave. To define an Authorized User you must (1) define the Authorized User's user ID and password on the machine where the iWave Director runs, then (2) define the Authorized User's user ID in an AuthorizedUseridn keyword in the Base section of the Director's configuration file. The first section in a mapping file or a processing file. This section defines the file as a whole and includes all subordinate sections. A public-domain algorithm providing strong encryption that is used by a large number of commercial and open source products, including iWave Integrator. The iWave Integrator component where a transaction originates. The ID of a primary-table record on the Client. The file that guides the first and last stages of transaction processing, which occur on the Client. The iWave Integrator file that contains settings that iWave Director requires to set up the run-time environment. On Windows NT/2000 and UNIX platforms, the configuration file is named sdserver.ini. On z/OS, the configuration file is the member named by ddname SDMCONFG; typically, this member is SDSERVER. Integration between two iWave Integrators. Each end of a connection is known as a connection point. Also, a data link between one vendor application and the next.
Assignment statement
Authorized User
Base section
Blowfish
Client Client object ID Client processing file Configuration file
Connection
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 246 of 276
Term
Connection point
Definition
Either end of a connection between two iWave Integrator Adapters. A connection point includes one inbound transaction path for an iWave Server and one outbound transaction path for an iWave Client. An iWave Integrator constant is a string that may include references to data model fields, database fields, system variables, and keyword settings. Values stored in iWave control fields. Field added to the vendor application's database for use by iWave Integrator. Typically, control fields are not transferred to the remote iWave Integrator. In some vendor applications (such as Microsoft Operations Manager), the control fields are stored in a delimited area of a single database field, rather than in separate fields. A separate table that holds the iWave control fields. For most vendor applications, the use of a control table is optional. When the control fields are placed in a control table rather than in the primary table, the control table must be related to the primary table. The relationship is identified in the mapping and processing files by use of the SUB-TABLE keyword. Part of a mask. A conversion specifier is a symbol that refers to a value in the field being copied--whether a data model field or a vendor field--and that transforms that value to a format appropriate for the field receiving the data. Verb that creates a new record in the remote vendor-application database. Verb that updates an existing primary-table record on the remote iWave Integrator, if possible, or creates a new record in most cases when an update is not possible. A field that contains data being transferred from one iWave Integrator to another. The format is independent of vendor application and is common across iWave Integrators. A planning spreadsheet used to map database fields to iWave Integrator data model fields and to specify the processing needed. A character or string used either to separate one entry in a list from the next (as a forward slash separates integers in 1/2/3) or to bracket characters with an identical prefix and suffix (as a forward slash brackets an integer in /3/). The destination of the data transfer between vendor applications connected by iWave Integrator.
Constant
Control data Control field
Control table
Conversion specifier
CREATE CREATE-UNIQUE
Data model field
Data Model Matrix
Delimiter
Destination
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 247 of 276
Term
Detection mode
Definition
A Client characteristic that specifies how the Client determines that work is available. Two options are possible, as follows: In event mode, the Client listens on a port for a communication by an Agent. In poll mode, the Client searches at regular intervals for records that require processing
Endpoint Enterprise-management application Event mode Exit
Obsolete term; see iWave Integrator. A vendor application that captures network events and displays information about them to a console. The detection mode in which a Client listens on a port for a communication by an Agent. A facility that allows you to integrate a customized function into iWave Integrator . Two types of exits are available: 1. An assignment exit places a value in a data model field 2. A transaction exit changes processing behavior at a specified point before, during, or after a transaction The ID of a primary-table record on the remote iWave Integrator; for a local Client, an ID on the remote Server; for a local Server, an ID on the remote Client. Transaction return value that is defined as failure by virtue of the settings of keyword SUCCESS-CODES, FAILURE-CODES, and RECOVER-CODES. Failure also refers to a non-zero return code from a transaction exit or a Agent. A dedicated gateway machine with special security precautions on it, used to service an outside network, especially Internet connections and dial-in lines. A mapped data model field composed of a series of entries, each composed of a user ID, a timestamp, and a variable length text string. To access a value in a section of a processing or mapping file, when the value was specified in a superior section. A command line interface that runs on UNIX and Windows machines that lets you administer iWave Directors (and the iWave Integrator Adapters they control). For Version 4, iWave Administrator CLI was known as the Dynamic Control Utility or by the name of the executable, SDDC. On a given machine, the software that controls iWave Integrator Adapter. iWave Director starts first, then iWave Director starts the iWave Integrator router component and one or more iWave Integrator Adapters. To connect two vendor applications running on different machines requires two iWave Directors. To connect two vendor applications that are both running on the same machine requires one iWave Director. For Version 4, iWave Director was known as the Service Manager.
External object ID
Failure
Firewall
Freeform text
Inherit iWave Administrator CLI
iWave Director
iWave Software
Revised [03/01/07] P01-664-09
Term
iWave Integrator Adapter Keyword
Definition
The component that accesses a given vendor application's data. A reserved symbol that appears in processing, mapping, or configuration files and changes the runtime behavior of iWave Integrator. A symbol that evaluates to the setting of a keyword and is characterized by a keyword name delimited by pound signs (#). Only a subset of keywords can be referenced in this way. A series of characters that begins with a keyword and has the following syntax: keyword:value; Permission for using iWave Integrator connection points that is enforced by iWave Director. The actual alphanumeric string issued by Skywire Software that you type into the license key file. A single key might contain licensing information for one or more connection points to a product. A text file where the licenses are stored. You type the license keys into this file. iWave Director checks the licenses during startup and at regular intervals afterwards. Each iWave Director has a license key file, and no two iWave Directors can share a license key file or its contents. A license key file can contain one or more license keys, which in turn contain the license for one or more connection points to a product. The iWave Integrator Adapter from which transaction data flows from the remote iWave Integrator Adapter. Verb that locks a primary-table record on the remote iWave Integrator Adapter and in some cases locks the equivalent primary-table record on the local iWave Integrator Adapter. The TCP/IP address for the computer. The TCP/IP address can be either an IP address or a host name. An Agent that is started by iWave Director. Managed Agents (such as the iWave Agents for ECI and Peregrine Service Center) run continuously. Unlike these managed Agents, most Agents are not started by iWave Director and run only when specific events occur in the vendor application. iWave Integrator Adapter, Server, Client, or Agent that iWave Director starts and stops. A file that maps a series of data model fields to their corresponding vendor fields and that gives an iWave Integrator's processing files access to those data model fields. A series of characters that maps a data model field to a database field.
Keyword reference (#)
Keyword statement
License License key
License key file
Local iWave Integrator LOCK
Machine address Managed Agent
Managed component Mapping file
Mapping statement
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 249 of 276
Term
Mask
Definition
A string of characters that specifies how to copy special data-for example, a timestamp--between a data model field and a vendor field. A mask consists of ordinary characters and conversion specifiers, which are symbols that refer to a value in the field being copied--whether a data model field or a vendor field--and that transform that value to a format appropriate for the field receiving the data. A computer that has more than one IP address. Fields that an Agent provides to a Client when the supported vendor application is an enterprise-management application. An iWave Integrator executable that notifies the Client when there is data to be transmitted. An Agent can either send the Client all of the data to be transmitted, or it can send only enough information for the Client itself to retrieve the data. The appropriate behavior to configure varies by iWave Integrator. A collection of data fields. The data belonging to one object class might define a problem report; the data belonging to another object class might define a sales call. A processing-file or mapping-file section that includes keywords and assignment statements affecting the data belonging to a particular object class. The ID of a primary-table record on an iWave Integrator Adapter. On the Client, the Client object ID; on the Server, the Server object ID. A port address carried in the iWave transaction to identify the sender for the purpose of passing through firewalls. A license key that is tied to a specific IP address or CPU serial number. A mapped data model field that comprises a first name, middle name, last name, and suffix, any one of which may be null. The events that begin with the Client's review of the first POLLCRITERIA keyword in a processing file and end with the completion of the final transaction caused by the last POLLCRITERIA keyword. The detection mode in which keyword POLL-CRITERIA defines database search rules that the Client uses to find records for subsequent processing. The last stage of transaction processing. This period begins when the Client starts to receive a response from the Server and continues until the Client completes writing to the local vendor-application database. The main database table being accessed in a given transaction on a given iWave Integrator Adapter.
Multi-hosted machine Network event field Notification Agent
Object class
Object class section
Object ID
Origin port Permanent license key Personal-name field Poll cycle
Poll mode
Post-processing update
Primary table
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 250 of 276
Term
Processing file
Definition
A file that guides transaction processing. During a given transaction, the local Client uses a client processing file, and the remote Server uses a server processing file. Each file contains keywords and assignment statements. A number visible in the logs that identifies a particular iWave Integrator Adapter. The value of system variable #DIP-RS#, one of three variables in the transaction return value. A transaction return value that is defined as a recoverable error by virtue of the settings of keywords SUCCESS-CODES, FAILURE-CODES, and RECOVER-CODES. The transaction failed because of a temporary condition; the transaction may succeed if run again. A network failure is often defined as a recoverable error. A portion of a statement that evaluates to TRUE or FALSE. Applies to keywords such as FILTER-DUPLICATE-EVENTS, SET-VALUE-IF, and USE-KEYWORD-IF. The iWave Integrator Adapter to which transaction data flows from the local iWave Integrator Adapter. Verb that returns a primary-table record from the remote iWave Integrator Adapter. Collection of sample mapping, processing, and other files for a given iWave Integrator Adapter. Use these files as the starting point when configuring your connection. On z/OS, the ddname of the iWave Director configuration file, which is typically member SDSERVER. The configuration file for iWave Director on UNIX platforms and Windows NT/2000. Verb that seeks primary-table records on the remote iWave Integrator Adapter and returns IDs of the records found. If only one record is found, SEARCH in some cases returns that record. Each operating system has methods to allow processes to own a resource; for example, to prevent multiple processes from writing to the same file. For licensing, the resource that is owned is the text in the license key file. The iWave Integrator component that provides a service when it receives a request from a Client at a different iWave Integrator. The ID of a primary-table record on the Server. Obsolete term; see iWave Director. A series of characters that begins with a reserved word and ends with a semicolon (;). One of the following: keyword statement, mapping statement, assignment statement.
Product ID Reason code, iWave Integrator Recoverable error
Relational expression
Remote iWave Integrator RETRIEVE Sample files
SDMCONFG sdserver.ini SEARCH
Serialization
Server Server object ID Service Manager Statement
iWave Software
Revised [03/01/07] P01-664-09
Term
Store locale
Definition
A UNIX directory or Windows NT/2000 directory or z/OS VSAM key-sequenced data set (KSDS) where requests are stored before sending. Either one Agent or one Client can use a given store locale. Specifying a store locale activates store-andforward capability. An Agent store locale ensures that no data is lost if the Agent attempts to send data to a Client that is not running. A Client store locale ensures that no data is lost when a Client running in event mode attempts to send data to a Server that is not running. A database table related to the primary table. Transaction return value that is defined as successful by virtue of the settings of keyword SUCCESS-CODES. Success also refers to a zero return code from a transaction exit or a Agent. A placeholder that contains data available in processing files; for example, in most installations of iWave Integrator, system variable #NOW# contains the current date and time. A mapped data model field that includes date and time information. A series of events, beginning when the local Client starts to receive the data to be transmitted to the remote Server and ending when the local Client completes processing of the response received from the Server. The process of checking a password submitted from Client to Server; if the password does not match the password expected, the Server does not attempt the service requested by the Client. A facility that allows you to integrate a customized function into iWave Integrator so as to change processing behavior before, during, or after a transaction. Keyword TRANSACTION-EXIT makes this integration possible. A route from one iWave Client to one iWave Server. A series of three numbers, one separated from the next by a blank, as follows: #DIP-RC# #DIP-RS# #APP-RC# where: #DIP-RC# is the iWave Integrator return code #DIP-RS# is the iWave Integrator reason code #APP-RC# is the vendor-application return code An iWave Client with a unique combination of product ID and iWave Director address. An iWave Server with a unique name and address as defined in an iWave Director configuration file. Verb that unlocks a primary-table record on the remote iWave Integrator Adapter and in some cases unlocks the equivalent primary-table record on the local iWave Integrator Adapter.
Subtable Success
System variable
Timestamp Transaction
Transaction authentication Transaction exit
Transaction path Transaction return value
Unique iWave Client Unique iWave Server UNLOCK
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 252 of 276
Term
UPDATE Vendor application Vendor field
Definition
Verb that updates a primary-table record on the remote iWave Integrator Adapter. One of the third-party products supported by iWave Integrator. Refers generically to a network-event field or a database field. Data in a vendor field is in a format specific to a vendor application. The value of system variable #APP-RC#. When the Client receives a response from the Server during post-processing update, keyword #APP-RC# usually contains the return code from the vendor application supported by the remote Server; but if TRANSACTION-EXIT keywords on the remote Server have subkeyword OBSERVE-FAIL set to true and if one or more of the related exits fail, #APP-RC# contains the return code from the first such exit to fail. A pre-defined transaction type. One of the following: CREATE, CREATE-UNIQUE, UPDATE, LOCK, UNLOCK, SEARCH, and RETRIEVE. A transaction subtype that you define for processing data in a special way. A processing-file or mapping-file section that includes keywords and assignment statements that is in use only when the iWave Integrator Adapter is processing a specified verb qualifier. A processing-file or mapping-file section that includes keywords and assignment statements that is in use only the iWave Integrator Adapter is processing a specified verb.
Vendor-application return code
Verb
Verb qualifier Verb Qualifier section
Verb section
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 253 of 276
Index
# #ALL# ......................................................154 Specifying with EXCLUDE Keyword....148 Specifying with INCLUDE Keyword .....147 #APP-RC# ........................ 32, 55, 66, 68, 69 #CLIENT-OBJECT-ID#..............................67 #DATE# .....................................................67 #DIP-RC# ................................32, 55, 66, 68 #DIP-RS#.................................32, 55, 66, 68 #ERROR-TEXT# ...............................69, 152 #EXIT#...............................................69, 154 Specifying in Assignment Statement ..144, 168, 171, 174 #FIXED-NOW# ..........................................71 #NOW# ..............................................72, 151 #NULL#......................................72, 154, 158 #SERVER-OBJECT-ID#............................72 #TIME# ......................................................73 $ $MAINC ...................................................114 $ORACLE_HOME .......................................130 $SD_BINPATH ........................................131 $SD_LOGPATH.......................................131 $SD_MGMTIPADDR ...............................131 $SD_NOTFPORT....................................131 $SDHOME ...............................................129 % %1 (ISO 8601 format)..............................160 %a (lower case) .......................................164 %A (upper case) ......................................164 %b (lower case) .......................................159 %C (upper case)......................................160 %D (upper case)......................................159 %f (lower case) ................................160, 164 %F (upper case) ......................................164 %g (lower case) .......................................164 %G (upper case)......................................164 %H (upper case)......................................159 %I (upper case) .......................................159 %l (lower case) ........................................164 %L (upper case) ......................................164 %m (lower case) ..............................159, 164 %M (upper case) .............................159, 164 %n (lower case) .......................................164
iWave Software
Revised [03/01/07] P01-664-09
%N (upper case) ..................................... 164 %p (lower case) ...................................... 159 %S (upper case) ..................................... 160 %T (iWave Version 5 transaction format)160 %U (upper case) ..................................... 160 %y (lower case) ...................................... 160 %Y (upper case) ..................................... 160 * * Default Value for Success Code ........... 56 / /dev/null................................................... 181 @ @ Notation References .......................... 149 @ Reference........................................... 151 To Freeform Text Data Model Fields .. 151 To Non-FreeformText Data Model Fields ......................................................... 152 A -a arguments Multiple ................................................ 185 -a parameter Usages ................................................ 184 Action Request System Storing Client Object ID......................... 30 Action Type ............................................. 126 Actions Issuing ................................................. 125 Translate Field....................................... 63 Active Section ......................................... 141 Search Verbs....................................... 169 Transaction Processing....................... 140 Adding Comments to the Configuration File.... 196 Line Feeds in Assignment Statements 150 Prefixes to Messages.......................... 227 Shared Libraries to Application ........... 130 Address iWave Administrator CLI ..................... 124 Administering
Confidential
Page 254 of 276
iWave Integrator from the Command Line ..........................................................123 iWave Integrator Overview.....................18 Administrator Action Commands ....197, 201, 205 Agent .................................................34, 240 Agent Object Types for Cycle Verb .....126 Agent Object Types for Kill Verbs ........126 Agent Object Types for Start Verbs .....127 Agent Object Types for Stop Verbs .....128 Allocating Data Set ..............................190 Automated Mode (z/OS) ......................189 Child Process Sending Stored Requests ..........................................................182 Communicating with Clients...................49 Configuration File Section....................240 Event Agent............................................48 Guaranteed Delivery ..............................50 Log Files...............................................127 Named Objects for Cycle Verb ............126 Named Objects for Kill Verb.................126 Named Objects for Log Verbs..............127 Named Objects for Start Verb..............127 Named Objects for Stop Verb ..............128 Normal Mode........................................190 Normal Mode (z/OS) ............................189 Notification Agent...................................48 Operational Status ...............................124 Running as Batch Job or Started Task on z/OS..................................................183 Running in Automated Mode ...............192 Second .................................................192 Section of Configuration File................240 Settings for Managed Agents...............245 Settings for Restricted Commands ........94 Settings for Unrestricted Commands.....91 Specifying Agent Name Sections.240, 242 Starting.........................................130, 202 Stopping ...............................................128 Store and Forward Capabilities............183 store_locale..........................................182 Store-and-Forward...............................182 Terminating ..................................240, 243 Universal ..............................................179 Universal Notification Starting..............130 Universal Notification UNIX User IDs ..202 UNIX Example......................................188 Agent Key agent_name Section ............................242 Agent Requests Priority ....................................................52 agent_name Section................................245 Configuration File UNIX and Windows 242 Configuration File z/OS........................240 AGENT-RESPONSE-IMMEDIATE..........184
Appending Additional Entry to Freeform Text Field..................................................... 150 Application Managed ............................................. 126 Application Key application_name section.................... 233 application_name.................................... 239 application_name Section....................... 235 Configuration File z/OS ....................... 233 Configuration Files UNIX and Windows ......................................................... 235 Applications Forcing Terminiation ........................... 197 Rolling Back Data................................ 178 Specifying Additional Shared Libraries 130 Writing Data......................................... 172 Applicationx............................................. 232 Assigning Character Data to Freeform Text Fields ................................................. 149, 150 Data Model Fields Values Declaring Unmapped Fields ............................ 144 Data Model Values from One Type to Another ............................................ 148 Freeform Text Data to Character Fields ......................................................... 150 Personal Name Data to Character Fields ......................................................... 150 Timestamp Data to Character Fields .. 150 To Field with Different Syntax ............. 149 Values to Unmapped Data Model Fields ......................................................... 144 Assignment Exit .................................. 25, 74 Exit Function pntfrag ............................. 81 lpad........................................................ 79 ltrim........................................................ 79 pntindex................................................. 84 pntinteger .............................................. 85 pntmath ................................................. 87 pntmcs................................................... 87 pntsubst............................................... 102 Processing............................................. 74 randit ................................................... 103 right ..................................................... 104 rpad ..................................................... 104 rtrim ..................................................... 105 strlwr.................................................... 106 strupr ................................................... 108 timeconv .............................................. 108 timediff................................................. 109 timestr.................................................. 111 tokenize ............................................... 112 tranchr ................................................. 113 Assignment Statements.................... 23, 143 Appending Entry to Freeform Text ...... 150 Client Processing ........................ 168, 171
iWave Software
Revised [03/01/07] P01-664-09
Creating New Freeform Text Entries ...151 Description/Purpose.....................144, 147 In Verb Qualifier Sections ....................141 Including Constants .............................153 Line Feeds ...........................................155 Processing Rules .................................176 Server Processing................................171 Specifying.............................................144 Assignments After Database Read ...........................148 Before Database Write.........................148 Relation to Translate Field .....................65 Asterisk (*) Using in Comments..............................143 Authorized User Defining ........................................129, 130 Failure to Define...................................125 Issuing Commands .... 125, 131, 226, 230, 233, 237, 241, 243 Specifying in stopall Scripts .................130 Specifying Stopall Scripts ....................129 Authorized Users in Configuration File Failure to Define...................................125 Specifying stopall Scripts .....................129 AuthorizedUserid .....................197, 201, 205 AUTOAGT JCL ........................................192 Automated Mode z/OS .....................................................183 z/OS Agent...........................................189 B Backslash (\) Using ....................................................154 Base Section............................................138 Description/Purpose.............................141 UNIX.....................................................200 Base Section Keys UNIX.....................................................200 Windows...............................................204 z/OS .....................................................196 Batch Programs Issuing iWave Administrator CLI Commands .......................................124 Running iWave Director .......................132 Begin and End Statement.............................................143 Begin Statements ....................................139 Books in iWave Library..............................11 Boolean Operators ..................................157 Brackets [ ]...............................................180 Buffers Maximum Value Length .......................115
C CFY-TEXT Special Considerations ....................... 145 Character Causing Errors .................................... 154 Data Model Fields ................................. 59 Character Data Assigning Freeform text Fields............ 149 Assigning to Freeform Text Fields ...... 150 Character Fields Assigning Freeform Text Data ............ 150 Specifying Quoted Literals .................. 149 Checkall Scripts Defining/Purpose................................. 130 Running iWave Administrator CLI ....... 129 Running SDDC Status Reports........... 130 UNIX.................................................... 130 Child Processes for Sending Stored Requests .............. 182 Managing..................................... 224, 229 Starting ........................................ 224, 229 Stopping ...................................... 225, 229 Terminates .................................. 234, 238 Circular References Keywords............................................. 155 Clarify Required Settings for Other Interfaces 162 Storing Client Object ID......................... 30 Clauses #EXIT# .................................................. 71 Client #CLIENT-OBJECT-ID# ......................... 67 #DATE#................................................. 67 Categorizing Transaction Returns......... 35 Create-Unique Processing .................. 142 Description/Purpose.............................. 17 Event Mode ..................................... 48, 49 Guaranteed Delivery ............................. 50 Identifying Components ...................... 232 Logs..................................................... 235 Mapping and Processing Files, Matching Sections ........................................... 140 Mapping File........................................ 168 Mapping/Processing Files Base Section ......................................................... 141 Operational Status .............................. 124 Post Processing Update................ 44, 173 Processing Assignment Statements .. 168, 171 Processing Error Messages .................. 57 Processing File.................................... 168 Processing Records .............................. 21 Read Phases....................................... 167 Receiving Multiple Records......... 174, 175 Responding to Transactions ................. 35
iWave Software
Revised [03/01/07] P01-664-09
Running Event Mode .............................34 Running in Poll Mode.............................34 Search Phase...............................167, 176 Search Processing...............................142 Search Verbs .......................................142 Settings for Restricted Commands ........94 Settings for Unrestricted Commands.....92 SET-VALUE-IF Keywords............168, 171 Starting.................................................202 Terminating ..................................233, 237 Transactions.........................................166 Using -a parameter ......................184, 185 Verb Processing...................................142 Writing Server Object ID ........................42 Client Application Section Specifying Time Zone Keys .197, 201, 206 Client Application Section (Configuration File) Specifying ApplicationName Sections .235 Specifying DiplomatUser Keys.............202 Specifying ProxyReceiveFromPort .....196, 200, 204 Specifying Servicex Keys.....................223 Client Object ID..........................................40 Storing on Server Side...........................30 Client Object ID (COID) .............................29 client_address..........................................180 client_address,port ..................................180 client_location ..........................................180 client_object_id ........................................181 ClientApplications Application Key ....................................235 ClientApplications Section Application............................................232 Description/Purpose.............................232 Examples .............................................233 ClientApplications Section (Configuration File) RestartDelayInterval Keys ...................233 Codes Failure ..............................................35, 56 Reason.......................................55, 66, 68 Recover............................................35, 56 Return ..................................55, 66, 68, 69 Return Universal Agent........................194 Success............................................35, 56 Vendor Application Return .....................55 Command Level Interface Administering iWave From...................123 Command Line Format..................................................180 UNIX and Windows NT ........................179 Commands Administrator Action, User ID Password Requirements ...................197, 201, 205
Canceling iWave Integrator Restart Logic ................. 226, 230, 234, 237, 241, 243 Cycle ... 124, 226, 230, 233, 237, 241, 243 CYCLE Description/Purpose............... 134 Executed Before Connecting to SendTo iWave Director ................................. 216 Executed Before Connecting to SendToSSL iWave Director............. 221 Formatting CYCLE .............................. 134 Formatting KILL................................... 134 Formatting REPORT ........................... 132 Formatting SET ................................... 133 Formatting START .............................. 133 Formatting STOP ................................ 133 Formatting TERM ................................ 132 Issuing in Batch or Script .................... 124 Kill........ 124, 226, 230, 234, 237, 241, 243 KILL Description/Purpose ................... 134 Kill, User ID Password Requirements 197, 201, 205 Report.................................................. 124 REPORT Description/Purpose............ 132 SDDC .................................................. 124 Sending to iWave Director .................. 129 Set ....................................................... 124 SET Description/Purpose.................... 133 Shutdown ............................................ 124 Start..... 124, 226, 230, 233, 237, 241, 243 START Description/Purpose ............... 133 Starting Client Logs............................. 127 Starting iWave Director Logs .............. 127 Stop ..... 125, 226, 230, 233, 237, 241, 243 STOP Description/Purpose ................. 133 Stopping Clients .................................. 126 Stopping iWave Components.............. 133 Stopping iWave Director ..................... 131 Stopping Servers................................. 126 TERM Description/Purpose................. 132 TERM, Specifying Time Intervals with StopWaitInterval Keys ..................... 197 User ID Password Requirements197, 201, 205 User ID/Password Requirements........ 125 z/OS System Console ......................... 123 z/OS System Console Changing Log Options ............................................ 131 z/OS System Console Controlling iWave Director Components....................... 131 z/OS System Console Description/Purpose ........................ 131 Comments Adding ................................................. 196 Editing setenv Scripts.......................... 129 Using Asterisk ..................................... 143 Commit and Rollback................................ 98 Communication Failure........................... 194
iWave Software
Revised [03/01/07] P01-664-09
Components Starting by iWave Director ...................202 Terminiating .........................................134 Configuration File Adding Comments ...............................196 agent_name Section ....................240, 242 Agents Section .....................................240 application_name Section............233, 235 Base Section ................................200, 204 Base Section Example.........................199 Changing Files .....................................195 ClientApplications Section ...................232 ClientApplications Section Examples ..233 Configuring Keys for UNIX...................200 Configuring Keys for Windows.............204 Configuring Keys for z/OS ...................196 Defining Authorized Users ...................130 Examples .............................................195 Examples Base Section .......................203 Examples, agent_name Section z/OS .242 Examples, Agents Section ...................240 Examples, application_name Section Windows/UNIX .................................239 Examples, application_name Section z/OS..................................................235 Examples, ClientApplications Section .233 Examples, InternetParameters Section208 Examples, iwave_director_name Section UNIX and Windows ..................218, 222 Examples, iwave_director_name Section Windows ...........................................222 Examples, iwave_director_name Section z/OS..................................................215 Examples, ReceiveFrom Section Windows/UNIX .................................209 Examples, ReceiveFrom Section z/OS209 Examples, SendTo Section..................213 Examples, SendToSSL Section...........219 Examples, service_name Section Windows/UNIX .................................231 Examples, service_name Section z/OS ..........................................................227 Examples, Services Section ................223 Exits .....................................................199 InternetParameters Section .................208 iWave Director agent_name Section ..240, 242 iWave Director Agents Section ............240 iWave Director application_name Section ..................................................233, 235 iWave Director Base Section ......196, 200, 204 iWave Director ClientApplications Section ..........................................................232 iWave Director Compatability with Windows Service Functions .............196
iWave Software
Revised [03/01/07] P01-664-09
iWave Director Names Sections, Modifying ......................................... 196 iWave Director ReceiveFrom Section . 209 iWave Director SendToSection Section ......................................................... 213 iWave Director SendToSSL Section ... 219 iWave Director service_name Section 224, 228 iWave Director Services Section......... 223 iwave_director_name Section UNIX and Windows .......................................... 215 iwave_director_name Section z/OS.... 214 ReceiveFrom Section.......................... 209 sdserver.ini .................................. 129, 130 SendTo Sections................................. 213 SendToSSL Section............................ 219 Services Section.................................. 223 ssl_send_name Section UNIX and Windows .......................................... 219 Using Quotes....................................... 195 Configuration Parameters....... 196, 200, 204 Console Appending Suffixes to Messages........ 197 Commands .......................................... 123 Commands Description/Purpose ........ 131 Commands, TERM.............................. 197 Extended MCS .................................... 197 Messages ............................................ 197 Specifying Names ............................... 197 Console Keys iWave Director....................................... 90 CONTEXT............................................... 173 Clause ................................................... 70 Options with Write Phase.................... 171 Subkeyword......................................... 169 Conversion Specifiers Personal-Name ................................... 163 Purpose ....................................... 159, 163 Timestamp........................................... 159 Timestamp Masks ............................... 158 Converting Data..................................................... 157 Data Model Field Values ............. 167, 175 Data Model Formats............................ 148 Freeform Text Fields ........... 169, 171, 174 Personal-Name Fields......... 169, 171, 174 Timestamp Fields ................ 169, 171, 174 Create ....................................................... 41 Description ............................................ 44 Create Phases For Create Unique Processing............ 169 Create Return Fields................................. 44 CREATE-ALWAYS ............................. 43, 44 CREATE-RETURN-FIELDS ..................... 89 CreateTime ............................................... 33 Create-Unique........................................... 41
Description .............................................42 CREATE-UNIQUE Description/Purpose...............................33 Create-Unique Processing Description .............................................43 Create-Unique Verbs...............................142 Cycle Commands.. 226, 230, 233, 237, 241, 243 Verbs....................................................126 CYCLE Commands Description/Purpose .........134 component_name ................................134 component_type ..................................134 Cycle Actions Issuing..................................................125 Cycle Verbs Supported by iWave Administrator CLI126 Cycling Clients ..................................................132 iWave Director Components ................134 Servers.................................................132 D Data Returned from Server to Client ..............31 Sent from Client to Server......................29 Storing and Manipulating .......................19 Data Conversion Data Model Field Values..............167, 175 Data Model Format ..............................149 Freeform Text Fields....................171, 174 On Data Model Fields ............................63 Personal-Name Fields .................171, 174 Planning for ............................................64 Timestamp Fields.........................171, 174 Unicode Conversion Table Pathname 200, 204 Data Model ................................................19 Data Model Fields......................................59 Assigning Value #EXIT# ........................69 Assignment Exit .....................................74 Client Processing for Mapped..............168 Client Processing for Unmapped .........168 Converting Values........................167, 175 Data Conversion ....................................63 Declaring Unmapped ...........................144 Determining Transferability ....................64 No-Clear Field ........................................65 Overview ................................................19 Processing ...........................................171 References...........................................155 Referencing..................................144, 168 Values ............................................60, 157 Data Sent From Client to Server
iWave Software
Revised [03/01/07] P01-664-09
Client Object ID Description/Purpose ... 29 Server Object ID Description/Purpose .. 31 Data Sent From Server to Client Server Object ID Description/Purpose .. 32 data set_name EtcHosts .............................................. 208 EtcServices ......................................... 208 Data Type Personal-Name Field .................. 157, 163 Timestamp Field.......................... 157, 160 Data Types................................................ 59 Data Values Refences ............................ 155 data_model_field..................................... 144 Database Changes Tentative................................................ 98 Database Conversion ............................. 155 Database Fields CreateTime............................................ 33 Reference............................................ 155 Referencing ......................................... 144 Database Table Main....................................................... 40 Database-Based Vendor Application Agent ..................................................... 48 Databases Adding Fields for Error Messages......... 57 Converting Format .............................. 149 Freeform Entries After Read ............... 152 Freeform Entries Before Write ............ 152 Interpretting Timestamp Values . 197, 201, 206 Searching ............................................ 142 Specifying............................................ 144 Specifying Primary Tables .................. 141 Specifying Subtables........................... 141 Data-Model Assignment #ERROR-TEXT# ................................... 69 DATE SQL Interfaces .................................... 161 DATE-MASK ............................................. 67 SQL Interfaces .................................... 162 Dates Created On Keys................. 197, 201, 205 Daylight Savings Time Not Supported ..................... 197, 201, 206 DB2 Library for Exit Function ...................... 100 Storing Client Object ID......................... 30 DBMS Executing Statements pntsqlcmd .............................................. 96 DB-NAME ................................................. 97 Defaults ApplicationName Keys224, 228, 233, 235, 240, 242 ASID Keys ........................................... 208
Confidential
Page 259 of 276
EndpointName Keys .. 224, 228, 233, 235, 240, 242 Environment Variable Library...............130 EtcPrefix Keys......................................208 ExtendedMCSConsoleKey Keys .........198 ExtendedMCSConsoleMaxWait Keys .198 File Version Keys .................196, 200, 204 INCLUDE Keywords ............................147 Inherited Items .....................................147 iWave Installation Directory .................129 LogDetail Keys .... 196, 200, 201, 204, 205 RestartDelayInterval .. 226, 230, 233, 237, 240, 243 StopWaitInterval Key ...........................197 Defining Authorized Users .................................129 Mapping and Processing Files Section Names ..............................................140 Delimiters Semicolon ( ..........................................143 Backslash Character (") .......................153 Commas(,) ...........................214, 224, 229 Double Quotes (") ................................153 Double Vertical Bars (|) ........................145 Forward Slash (/) .................................139 Plus Signs (+).............. 225, 229, 233, 237 Pound Sign (#) .....................................156 SUBTABLE_DELIMITER Keyword ......144 Timestamp Masks................................145 Delimiting Decimal Values ....................................229 Log Options................. 225, 229, 233, 237 Optional Command Line Arguments....180 Section Names.....................................139 Statements ...........................................143 Subtable Names ..................................144 Detection Mode..........................................48 Event ................................................33, 34 Poll ...................................................33, 34 Specifying start_agent Scripts .............130 DETECTION-MODE................................167 DETECTION-PORT.........................131, 180 Directories Bin ........................................................131 Configuration File .........................200, 204 Containing sddc Executables...............125 Default Installation ...............................129 Log .......................................131, 200, 204 Double Quotes (") Using ....................................................153 E ECI Required Settings for Other Interfaces 162
iWave Software
Revised [03/01/07] P01-664-09
Editing Configuration Files .............................. 196 Processing and Mapping Files ............ 152 setenv Scripts...................................... 129 Embedded Sections................................ 140 Enabled Security....................................... 24 End Statements ...................................... 139 Enhanced Scaling Servers ........................................ 224, 229 EnhancedScaling Keys................... 224, 229 Enterprise Data Model .............................. 19 Format ................................................... 19 Enterprise-Management Application Agent ..................................................... 48 As a Source of Problem Reports........... 26 Configured to Start a Script................. 188 Description/Purpose.............................. 26 Supported.............................................. 27 Entries Appended to Freeform Text Fields...... 150 Freeform Text Fields ........................... 150 Environment Variables Default Location .................................. 130 Defining LOCAL .................................. 130 Defining ORACLE_HOME .................. 130 Defining ORACLE_SID ....................... 130 setenv Script........................................ 129 Error Codes Transaction Return Value ..................... 32 Error Events Reporting ........................... 126 Error Messages Adding Fields to Database .................... 57 Writing to the Log ........................ 196, 204 Error Num Field......................................... 57 Error Text .................................................. 32 Field....................................................... 57 Optional ................................................. 69 ERROR-NUM-FIELD .............................. 174 ERROR-TEXT-FIELD ............................. 174 ESCALE.................................................... 52 EtcHosts Formats ............................................... 208 Syntax ................................................. 208 EtcServices Format ................................................. 208 Syntax ................................................. 208 Event Agent .............................................. 48 Event Detection Mode .............................. 34 Event Mode................................... 21, 48, 49 Examples Adding Entries to Freeform Text ......... 151 Assignment Exit..................................... 74 Client in Poll Mode ................................ 35 Configuration Files Base Section ........ 199 Configuration Files, agent_name Section ......................................................... 242
Configuration Files, Agents Section.....240 Configuration Files, application_name Section......................................235, 239 Configuration Files, Base Section........203 Configuration Files, ClientApplications Section..............................................233 Configuration Files, InternetParameters Section..............................................208 Configuration Files, iwave_director_name Section......................................215, 218 Configuration Files, ReceiveFrom Section Windows/UNIX .................................209 Configuration Files, ReceiveFrom Section z/OS..................................................209 Configuration Files, SendTo Section ...213 Configuration Files, SendToSSL Section ..........................................................219 Configuration Files, service_name Section ..................................................227, 231 Configuration Files, Services Section ..223 Configuration Files, ssl_send_name Section..............................................222 Cycle Verbs..........................................126 Data Conversion Planning .....................64 Data-Model Field Values........................29 Enterprise Data Model ...........................19 Event Mode ..........................................188 Field Separators.....................................30 iWave Integrator Connection .................17 Kill Verb................................................126 Linking Section Names ........................140 Mapping and Processing Files...............22 Mapping File Subsets ..........................147 Mapping Statements ............................145 Mask and Vendor Fields ......................145 Modifying setenv Scripts ......................129 Notification Mode .................................187 Object Classes .......................................29 pntfrag ....................................................81 pntmcs....................................................88 pntsqlcmd.............................................100 Processing File Subsets ......................148 Processing Freeform Text......................36 Referencing Value of Data Model Field ..........................................................155 Report Verbs ........................................127 Restricted System Commands, pntmcs.93 Security ..................................................24 Set Verb ...............................................127 Shutdown Verbs...................................127 SQL Interface .......................................162 Start Verbs ...........................................128 Status Reports .....................................132 Stop Verbs ...........................................128 Transaction Exit .....................................74 Translating Data Values.........................23
iWave Software
Revised [03/01/07] P01-664-09
Universal Agent ........................... 187, 188 UNIX for Universal Agent .................... 188 Unrestricted System Commands, pntmcs ........................................................... 90 EXCLUDE Keywords............................................. 148 Executing Assignment Statements ...................... 144 Commands .................................. 216, 221 Cycle Commands ................................ 124 Kill Commands .................................... 124 Processes Concurrently .............. 224, 229 Report Commands .............................. 124 Retrieve Verbs..................................... 143 Set Commands.................................... 124 Shutdown Commands......................... 124 Start Commands ................................. 124 Stop Commands ................................. 125 Exit Function lpad........................................................ 79 ltrim........................................................ 79 pntexec.................................................. 80 pntexif.................................................... 81 pntfrag ................................................... 81 pntindex................................................. 84 pntinteger .............................................. 85 pntmath ................................................. 87 pntmcs................................................... 87 pntsqlcmd ...................................... 96, 100 pntsqlif ................................................. 101 pntsubst............................................... 102 pntwto.................................................. 102 randint ................................................. 103 right ..................................................... 104 rpad ..................................................... 104 rtrim ..................................................... 105 strswr................................................... 106 strupr ................................................... 108 timediff......................................... 108, 109 timestr.................................................. 111 tokenize ............................................... 112 tranchr ................................................. 113 UNIX & Windows................................... 75 z/OS ...................................................... 78 Exits Assignment............................................ 25 Description/Purpose.............................. 25 Transaction............................................ 26 UNIX...................................................... 75 Windows................................................ 75 Writing Functions ................................ 114 z/OS ...................................................... 77 Extended MCS Console ......................... 198 Identifying ............................................ 198 Specifying Names ............................... 197 ExtendedMCSConsoleKey ..................... 198
External Object ID .........................30, 31, 40 External Product Identifier .......................246 EXT-OBJECT-ID............... 72, 168, 171, 174 F Failure Codes ......................................35, 56 Failure Fields .......................................35, 57 FAILURE-CODES....................................174 FAILURE-FIELDS....................................174 Field Separator ....................................30, 31 Fields Data Model Declaring Unmapped........144 Failure ....................................................35 Freeform Text...................................23, 36 Personal Name ....................................145 Recover..................................................35 Required for SQL Interfaces ................161 Success..................................................35 Text-Indicator .........................................36 Timestamp ...........................................145 FIELDS Subkeywords................................168, 171 FIELD-SEPARATOR .................................67 Files Mapping Structure................................139 Processing ...........................................154 Processing Structure............................139 Firewall ClientIdleTimeout ....................198, 202, 206 OriginPort .............................214, 216, 220 PingInterval ..........................214, 217, 220 ReceiveFromIdleTimeout.....198, 202, 206 Sending Messages ..............................186 Forced Returns in Assignment Statements .............................................................154 Forced Stop .............................................125 Components.........................................134 Forcing Application Termination .......................197 Formats CYCLE Commands..............................134 Data Model Fields ..................................19 Enterprise Data Model ...........................19 EtcHosts...............................................208 EtcServices ..........................................208 IP Address............................................124 KILL Commands ..................................134 Personal-Name ....................................145 REPORT Commands...........................132 Required...............................................162 SET Commands...................................133 SQL Interfaces .....................................161 START Commands..............................133 STOP Commands................................133
iWave Software
Revised [03/01/07] P01-664-09
TERM Commands............................... 132 Timestamp........................................... 145 Formatting Personal-Name Data............................. 63 Text Lines, Freeform Text Entry Additions ......................................................... 151 Timestamp............................................. 61 Freeform Text Data Model Fields ................................. 60 Writing to Database............................... 39 Freeform Text Fields........................... 23, 36 Assigning Additional Freeform Text Entries.............................................. 150 Converting ........................... 169, 171, 174 First and Subsequent Entries.............. 152 Identifying as No-Clear Fields ............... 65 SQL Interfaces .................................... 161 G Generating Status Reports..................................... 132 Glossary.................................................. 250 Guaranteed Delivery................................. 50 Agent ..................................................... 50 Client ..................................................... 51 H hlq.LOAD ................................................ 190 Host Names Omitting ............................................... 127 Specifying Remote iWave Director ..... 209 Specifying Send To iWave Director ... 213, 214, 215, 219 Specifying SendToSSL iWave Director219 I Identifying Active Sections.................................... 142 Agents ................................................. 240 Client Components.............................. 232 Configuration Parameters ... 196, 200, 204 Data Model Fields Inherited from Superior Sections ........................................... 147 Data Model Fileds for Personal-Name Fields ............................................... 145 Data Model Fileds for Timestamp Fields ......................................................... 145 iWave Directors ........................... 213, 219 Primary Table ........................................ 40 Primary Tables .................................... 141 Servers ........................................ 141, 223
Subtables .............................................141 TCP/IP Address Space ........................208 UNIX User IDs......................................202 INCLUDE Keyword ...............................................147 Inherit Embedded Scetions.............................140 Inheritance .......................................145, 202 Inherited Items Position ................................................147 INIT ..................................................177, 178 Interfaces Client ......................................................17 iWave Administrator Command Level .123 Named Objects ............................125, 127 Operational Status ...............................124 Server.....................................................17 Service, Starting iWave Director ..........123 Intermediate iWave Director ProxyReceiveFromPort........196, 200, 204 InternetParameters ..................................208 Invoking An Agent ................................................34 IP Addresses For Remote iWave Director .................209 For SendTo iWave Director .................214 Formatting ............................................124 iWave Director Management Access Point ..........................................................124 Local Machine ......................................125 Omitting................................................127 Syntax ..................................................124 Issuing Actions .................................................125 KILL Commands ..................................134 SDDC Commands ...............................124 STOP ...................................................133 z/OS System Console Commands ......131 iWave Administrator Administering from Command Level....123 iWave Administrator CLI Communications ....................................18 Description/Purpose.............................123 Executing SDDC Commands...............124 Including Commands in Batch/Scripts .124 iWave Director Error Events ................126 Overview ................................................18 Replacing sdstatus Utility 13-2.............124 Running........................................124, 129 Running Status Reports.......................130 Syntax ..................................................124 Tasks......................................................18 Unicode File .........................................125 Verbs....................................................124 iWave Agent for XML Web Services agent_name Section ............................245
iWave Software
Revised [03/01/07] P01-664-09
iWave Clients Additional............................................. 232 iWave Components................................... 17 iWave Director agent_name.log................................... 245 application_name.log .......................... 239 Base Section ....................... 196, 200, 204 Common Methods ............................... 123 Configuration File Agents.................... 240 Configuration File Examples ...... 203, 207, 208, 209, 213, 215, 218, 219, 222, 223, 227, 231, 233, 235, 239, 240, 242 Configuration File service_name Section z/OS................................................. 224 Configuration File service_name Section, UNIX and Windows ......................... 228 Configuration File, Examples .............. 199 Configuration File, iwave_director_name Section, UNIX and Windows ........... 215 Configuration File, SendTo Section .... 213 Configuration File, SendToSSL Section ......................................................... 219 Configuration File, ssl_recv_name Section, UNIX .................................. 210 Configuration File, ssl_recv_name Section, Windows ............................ 212 Configuration File, ssl_send_name Section, UNIX .................................. 219 Configuration Files Syntax .................. 195 Configuration Files, InternetParamenters Section............................................. 208 Configuration pntmcs ............................ 89 ConfigurationFile, iwave_director_name Section, z/OS................................... 214 Configuring Security.............................. 24 Console Keys ........................................ 90 Defining Authorized Users .................. 125 Description/Purpose.............................. 17 Identifying .................................... 213, 219 Intermediate, ProxyReceiveFromPort 196, 200, 204 Modifying ............................................. 196 Relation to iWave Integrator.................. 17 Remote IP Addresses ................. 209, 214 Running as a Started Task.................. 132 Running Batch..................................... 132 SendTo Host Names................... 214, 216 SendTo IP Addresses ................. 214, 216 SendToSSL Host Names .................... 220 SendToSSL IP Addresses .................. 220 server_name.log.n .............................. 231 Services Section.................................. 223 Starting ................................................ 130 Starting on UNIX ................................. 123 Starting on Windows ........................... 123 Starting on z/OS .................................. 123
Stopping ...............................................127 Using Management Port ........................18 z/OS System Console Commands ......131 iWave Director Configuration File....213, 219 application_name.................................239 application_name section ....................235 Base Section ................................200, 204 ClientApplications section ....................232 ReceiveFrom Section...........................209 SendTo Section ...................................213 SendToSSL Section.............................219 service_name section ..................227, 231 Services Section ..................................223 iWave Integrator Administering from Command Line .....123 Basic Concepts ......................................28 Components...........................................17 Constant...............................................153 Constants .............................................153 Definition ................................................17 Exits .......................................................25 Exits Supplied ........................................75 For Web Services, SSL..........................24 Handling Freeform Text .........................36 Identifying Fields ....................................22 Operational Status ...............................124 Overview ................................................16 Processing Subtables ..........................177 Processing Transaction Exit ..................74 Relation to iWave Director .....................17 Return Codes .........................................32 Sending Data .........................................29 Sending Processing Instructions............29 Serial Intialization Setting.....................198 Server Names ........................................31 Service Interface ..................................123 Stopping ...............................................130 System Variable #ALL# .......................147 System Variable #EXIT#......................144 Transactions Between ...........................20 Using iWave Administrator...................123 iWave Servers Additional .............................................223 iwpasswd Utility .......................................134 J JCL AUTOAGT............................................192 Creating store_locale Data Set ............182 TSOAUTAG .........................................192
K Keys Base Section UNIX ............................. 200 Base Section Windows ....................... 204 Base Section z/OS .............................. 196 Describing iWave Director Paramenters ......................................................... 208 ExtendedMCSConsoleKey.................. 198 ExtendedMCSConsoleMaxWait.......... 198 Internet Paramenters Section z/OS .... 208 Time Zone ........................... 197, 201, 206 Keywords AGENT-RESPONSE-IMMEDIATE ..... 184 CFY-TEXT........................................... 145 CREATE-ALWAYS ......................... 43, 44 CREATE-RETURN-FIELDS.................. 89 DATE-MASK ......................................... 67 DB-NAME.............................................. 97 Definition ......................................... 23, 29 DETECTION-MODE ........................... 167 DETECTION-PORT .................... 131, 180 ERROR-NUM-FIELD .......................... 174 ERROR-TEXT-FIELD ......................... 174 ESCALE ................................................ 52 EXCLUDE ........................................... 148 EXT-OBJECT-ID ........... 72, 168, 171, 174 FAILURE-CODES ............................... 174 FIELD-SEPARATOR............................. 67 INCLUDE............................................. 147 INIT...................................................... 178 LOCAL_USERID ................................. 155 LOCAL-OBJECT-ID-FIELDS ................ 67 LOCAL-USERID............................ 97, 151 LOCK-SPEC.................................... 41, 45 MONTH-NAMES ................................. 159 NOCLEAR-FIELDS ..................... 173, 174 NOW-MASK ........................................ 155 PERSONAL-NAME-FIELDS ............... 145 PIVOT-YEAR....................................... 160 POLL-CRITERIA ........................... 53, 167 PRIORITY ............................................. 52 Processing........................................... 168 Processing Data Model Fields .... 171, 174 RECOVER-CODES ............................ 174 RECOVER-FIELDS............................. 174 RETRIEVE-ONE-HIT .................... 47, 170 RETRY-INTERVAL ............................... 51 SEARCH-ALWAYS ....................... 43, 170 SEARCH-CRITERIA ........................... 170 Settings Referenced............................ 156 SET-VALUE-IF .... 168, 171, 172, 174, 176 SET-VALUE-IF Assignment ................ 144 SQL-TEXT........................................... 145 Statement Syntax ................................ 143 Statements .................................. 153, 154
iWave Software
Revised [03/01/07] P01-664-09
STORE-LOCALE .................................183 SUB-TABLE . 69, 141, 168, 171, 173, 175, 176, 177 SUBTABLE_DELIMITER .....................144 SUCCESS-CODES..............................174 SUCCESS-FIELDS..............................174 TABLE-NAME ......................................141 TEXT-INDICATOR...... 168, 169, 171, 174 TEXT-USERID .....................................151 TIMESTAMP-FIELDS ..................145, 158 TRANSACTION-EXIT ..........................166 TRANSLATE-FIELD63, 64, 152, 155, 167, 168, 171, 172, 174, 176 UNIQUE-FIELDS ...........................43, 170 USE-KEYWORD-IF .............169, 173, 174 VALUE .................................................178 Kill Actions, Issuing ....................................125 Commands.. 226, 230, 233, 237, 241, 243 Example ...............................................126 For CLI .................................................124 KILL Commands Description/Purpose .........134 component_name ................................134 Kill Commands User ID Password Requirements197, 201, 205 Kill Verbs Supported by iWave Administrator CLI126 L Library Exits .......................................................75 PNTSQLIF..............................................99 LIBRARY Clause .......................................70 License Key File Pathnames ...................................200, 204 Line Feeds in Assignment Statements....155 LoadModule Keys ............................233, 240 Local Fields................................................29 Local Object ID Fields ...............................30 local_address...........................................181 LOCAL_USERID Keywords .............................................155 Local-Address Values ..................................................125 Verbs Supported by iWave Administrator CLI ....................................................125 LOCAL-OBJECT-ID-FIELDS.....................67 LOCAL-PASSWORD.................................97 LOCAL-USERID ................................97, 151 Locating Shared Libraries...................................130 Lock ...........................................................41
iWave Software
Revised [03/01/07] P01-664-09
Description ............................................ 45 LOCK-SPEC ....................................... 41, 45 LOG Clause .............................................. 70 Log Messages Prefix ................................................... 227 log_detail................................................. 182 logfile....................................................... 181 Logging Detail Specifying............ 196, 200, 201, 204, 205 Logging Options Changing ............................................. 133 LogOptions Parameters for Managed..... 225 Logs Action Types........................................ 126 Normal................................................. 127 Problem Determination ....................... 127 Starting New........................................ 124 stdout and stderr ................................. 181 Verbose ............................................... 127 lpad ........................................................... 79 ltrim ........................................................... 79 M Machines Administering iWave ........................... 123 Identifying Host Name/IP Address ...... 125 Managed Agents Log Options ......................................... 225 Managed Resources Operational Status .............................. 126 Starting ................................................ 126 Statistics .............................................. 126 Stopping .............................................. 126 Terminating ......................................... 126 Management Port ..................................... 18 Mapping Data Model Fields ...................... 60 Mapping Files.................................... 22, 138 Active Sections.................................... 142 Basic Structure .................................... 139 Editing ................................................. 142 Examples Subsets .............................. 147 Overview ............................................... 22 Sections, Description/Purpose ............ 141 Mapping Statements............................... 143 Examples............................................. 145 Location............................................... 141 Personal-Name Fields......................... 145 Syntax ................................................. 144 Timestamp Fields ................................ 145 Mapping/Processing Files Parsing ................................................ 225 Masks Mapped Field for SQL Interfaces ........ 162 Personal-Name ................................... 163
Personal-Name Data .............................63 Personal-Name Field ...........................157 Timestamp .....................................62, 160 Timestamp Field...................................157 MAXDEPTH Values.........................224, 229 MAXPROCESS Values ...................224, 229 MAXVLEN Clause .....................................70 Messages Error, Unauthorized User ID/Password125 Error, Writing to the Log......196, 200, 201, 204, 205 Monitoring ............................................127 Parsing Mapping/Processing Files ......225 Prefixes ................................................227 Replying to ...........................................132 Success................................................132 MINPROCESS Values ....................224, 229 Modes z/OS Agent...........................................189 Modifying Configuration Files ...............................196 Environment Variables.........................130 Processing and Mapping Files.............138 scripts/setenv Files ..............................129 Monitoring Messages.............................................127 System Console ...................................197 MONTH-NAMES......................................159 MVS ............................................... See z/OS MVS Console Commands .......................123 N National Characters.........................232, 240 New Line Forcing Returns in Assignment Statements .......................................154 New Line Sequence \n Freeform Text Entry Additions .............151 nnm_exec Script Example .....................................188 NoClear Fields ...........................................65 Freeform Text Fields..............................65 NOCLEAR-FIELDS..........................173, 174 Normal Mode z/OS Agent...........................................189 Notational Conventions .............................10 notfagt......................................................180 Notification Agent.......................................48 Now Mask Field .........................................72 NOW-MASK.............................................155 SQL Interfaces .....................................161
O Object Verbs Supported by iWave Administrator CLI ................................................... 125 Object Class.............................................. 29 Section, Description/Purpose.............. 141 Sections............................................... 138 Object Values.......................................... 125 Object-Type Values ................................................. 125 Verbs Supported by iWave Administrator CLI ................................................... 125 OBSERVE-FAIL.................................. 66, 75 ODBC Client Object ID ..................................... 30 Library for Exit Function ...................... 100 Required SQL Interfaces..................... 161 ODBC_AUTOCOMMIT_OFF.................... 99 ODBC_AUTOCOMMIT_ON ..................... 98 ODBC_TRANSACTION_COMMIT ........... 99 ODBC_TRANSACTION_ROLLBACK ...... 99 Operational Parameter Setting/Resetting ................................. 127 Operational Status Agents ................................................. 124 Clients ................................................. 124 iWave Integrators ................................ 124 Servers ................................................ 124 Operators Boolean ............................................... 157 Relational ............................................ 157 Option Verbs Supported by iWave Administrator CLI ................................................... 125 Option Values ......................................... 125 Oracle Client Object ID ..................................... 30 Library for Exit Function ...................... 100 Required SQL Interfaces..................... 161 ORACLE_HOME .................................... 130 ORACLE_SID ......................................... 130 Origin Port................................................. 24 origin_port ............................................... 186 OriginPort Key......................... 214, 216, 220 Other Interfaces Settings ............................................... 162 P PAFTER .................................. 173, 176, 177 Pairing Vendor Field Values.............................. 63 Parameter Error ...................................... 194 Parameters
iWave Software
Revised [03/01/07] P01-664-09
Base Section UNIX ..............................200 Base Section Windows ........................204 Base Section z/OS...............................196 Configuration........................196, 200, 204 Forcing Application Termination ..........197 Keys Describing .......... 208, 214, 215, 219 Operational, Setting/Resetting .............127 Providing for iWave Diectors208, 214, 215 Providing for iWave Directors ..............219 stopall Scripts.......................................130 User ID .................................................125 PARMS Clause....................................70, 77 Parsing Mapping/Processing Files....................225 Password Values .....................................125 Passwords stopall Scripts.......................................130 Syntax Example ...................................124 Verbs Supported by iWave Administrator CLI ....................................................125 PBEFORE................................173, 174, 177 Peregrine Required Settings for Other Interfaces 163 Personal-Name Data Model Fields ..................................60 Fields............................. 62, 145, 157, 163 Format....................................................63 Masks.....................................63, 149, 163 Maximum Length .................................165 Personal-Name Fields Converting............................169, 171, 174 PERSONAL-NAME-FIELDS Keywords .............................................145 PFIELD ............................................176, 178 PFLAGS.......................... 173, 174, 175, 176 Phases Controlling ............................................170 Create-Unique Processing...................169 Read, Description/Purpose ..................166 Read, Server ........................................170 Read,Running PRE/POST-VERB Transaction Exits ..............................169 Search, Description/Purpose ...............166 Search, Server .....................................170 Search,Running PRE-VERB transaction Exits..................................................169 Update, Create Unique Processing .....169 Write, Description/Purpose ..................166 Write, Server ........................................172 Pivot Year ................................................160 PIVOT-YEAR Keyword ...............................................160 Placing Data Into Unmapped Data Field ............................74 Planning Data Conversion ....................................64
iWave Software
Revised [03/01/07] P01-664-09
Platforms Supported.............................................. 16 pntexec ..................................................... 80 pntexif ....................................................... 81 pntfrag....................................................... 81 pntindex .................................................... 84 pntinteger .................................................. 85 pntmath ..................................................... 87 pntmcs ...................................................... 87 Example Restricted System Commands93 Example Unrestricted System Commands ........................................................... 90 iWave Director Configuration ................ 89 Sample .................................................. 88 pntsqlcmd............................................ 96, 99 Examples............................................. 100 pntsqlif..................................................... 101 PNTSQLIF Library ................................................... 99 pntsubst .................................................. 102 pntwto ..................................................... 102 Pointer List Handling .............................................. 114 Pointer Values......................................... 115 Poll Criteria ............................................... 34 Poll Cycle .................................................. 53 Poll Detection Mode.................................. 34 Poll Interval ......................................... 35, 53 Setting Too Low .................................... 54 Poll Mode ...................................... 21, 49, 53 Client Terminates ........................ 233, 237 Search Phase...................................... 167 POLL-CRITERIA............................... 53, 167 Port DETECTION-PORT Keyword ............. 131 Format ................................................. 180 Management ......................................... 18 Origin..................................................... 24 Specifying SDSTATUSPORT ............. 129 TCP/IP................................................. 131 Values ................................................. 124 POST-POLL Transaction Exits ............... 167 Post-Processing Update ................... 35, 173 #CLIENT-OBJECT-ID# ......................... 67 POST-TRAN-ABORT Transaction Exits 173, 175 POST-TRAN-FAILURE........................... 169 Transaction Exits....... 67, 68, 69, 173, 175 POST-TRAN-RECOVER Transaction Exits .................................................... 173, 175 POST-TRAN-SUCCESS ........................ 169 Transaction Exits....... 67, 68, 69, 173, 175 POST-VERB Transaction Exits............... 67, 68, 69, 169 Pound Signs (#) ...................................... 155 Prefix
Adding to Log Messages .....................227 Prefixing Field Names .............................144 PRE-POLL Transaction Exits ..................167 PRE-RETRIEVE Transaction Exits .........167 PRE-TRAN Transaction Exits .........................167, 169 PRE-UPDATE..........................................174 PRE-VERB ..............................................173 Transaction Exits .........................169, 171 Primary Table ............................................40 Identifying TABLE-NAME Keywords....141 priority ......................................................181 Priority Setting for Requests ..............................52 PRIORITY..................................................52 Problem Reporting.....................................26 Processing Assignment Exit .....................................74 Client, SET-VALUE-IF .................168, 171 Processing Files ........................22, 138, 154 Active Sections.....................................142 Basic Structure.....................................139 Editing ..................................................142 Examples Subsets ...............................148 Overview ................................................23 Purpose................................................140 Processing Instructions .............................29 PROGRAM Clause ....................................77 Programs Batch ....................................................124 Executing .............................................144 Specifying SDDC .................................124 Propagate Embedded Section...............................140 PSE..........................................................177 PSET .......................................................177 Q Qualified Directory Names ..........................200, 204 High Level DSN ...................................208 Qualifiers Create-Unique......................................142 Enbedded in Verb Sections .................139 In Mapping/Processing Files................142 Specify Assignment SET-VALUE-IF Keyword............................................144 Verb, Data Model Fields ......................174 Verb, Defining Section Names.............140 Verb, Search ........................................142 Verb, Section Content..........................141 Verbs, Mapping Data Model Fields......172 Queues Transaction ..........................................225
iWave Software
Revised [03/01/07] P01-664-09
QUIESCE Values............................ 224, 229 Quoted Literal Equivalent to Character Fields ............ 149 Quotes Configuration File ................................ 195 Double, Specifying iWave Integrator Names ............................................. 128 R randint ..................................................... 103 Read Phase .............................................. 70 Client ................................................... 167 Description/Purpose............................ 166 Running PRE/POST-VERB Transaction Exits ................................................. 169 Server.................................................. 170 Reason Code ................................ 55, 66, 68 #DIP-RS# .................................... 226, 230 ReceiveFrom Section UNIX and Windows ............................. 209 z/OS .................................................... 209 ReceiveFromSSL Section UNIX and Windows ............................. 210 Records Preventing Extra.................................... 42 Recover Codes ................................... 35, 56 Recover Fields .................................... 35, 57 RECOVER-CODES ................................ 174 RECOVER-FIELDS ................................ 174 Referencing Circular ................................................ 155 Data Model Fields 144, 154, 168, 171, 172 Data Values......................................... 155 Database ............................................. 155 Database Fields .................................. 144 Primary Tables .................................... 167 Subtables .................................... 167, 176 System Variables ................................ 144 Relational Expression ..................... 157, 158 Relational Operator................................. 157 Relationship Characteristics..................................... 157 Remedy Required Settings for Other Interfaces 163 Remote iWave Director Network Host Addresses ......................................................... 209 iWave Director, Network Host Address ................................................. 209, 214 iWave Directors Receiving Transactions ......................... 196, 200, 203, 204, 206 Server, Transaction Request Processing Interval ............................. 214, 216, 220 Remote Server
Processing ...........................................169 REPORT Commands Description/Purpose .........132 Report Verbs Description/Purpose.............................124 Examples .............................................127 Supported by iWave Administrator CLI126 Syntax ..................................................126 Valid Object Type Values.....................126 Reports Generating iWave Director Status .......132 Generating SDDC Status.....................130 Generating Status Reports ..................132 Required Parameters...........................................130 Password .............................................130 Responses Command.............................................198 From the Server ...........................172, 225 To Client...............................................170 To the Client.........................................172 Transactions.........................................225 Restart Logic... 226, 230, 234, 237, 241, 243 RestartDelayInterval Keys ......226, 230, 233, 237, 240, 243 Restarting Agents ..................................................124 Clients ..........................................124, 126 Components.........................................134 Cycle Verbs..................................124, 126 iWave Integrators.................................124 Managed Resources............................126 Servers.................................................124 Retrieve .....................................................41 Description .............................................46 Executing Verbs...................................143 RETRIEVE Verb........................................................31 RETRIEVE-ONE-HIT.........................47, 170 Retrieving Timestamps..........................197, 201, 206 Vendor Application Data ......................167 Retry Interval .............................................53 Guaranteed Delivery ..............................51 RETRY-INTERVAL....................................51 Return Codes.................................55, 66, 68 #APP-RC#..............................................32 #DIP-RC#...............................................32 #DIP-RS# ...............................................32 From Vendor Application, System Variable ..............................................66 Universal Agent....................................194 Return Fields .......................................31, 44 Return Values Transaction ............................................35 returned_vendor_field..............................184
iWave Software
Revised [03/01/07] P01-664-09
REXX EXEC ........................................... 179 AUTOAGT ........................................... 192 TSOAUTAG......................................... 192 Right Assignment Exit................................... 104 Rollback .................................................. 172 Database Changes ............................... 98 rpad......................................................... 104 rtrim......................................................... 105 Running Agent in Automated Mode................... 192 iWave Director as a Batch Job............ 132 iWave Director as a Started Task ....... 132 Universal Agent ........................... 179, 190 Universal Agent in Normal Mode ........ 190 S SAFTER.................................................. 176 Savings Time Daylight ............................... 197, 201, 206 SBEFORE............................................... 176 Scalability Basic Server ................................ 224, 229 Enhanced Server Windows................. 229 Enhanced Server z/OS ....................... 224 Specifications .............................. 224, 229 Scripts Changing Variables............................. 131 checkall ............................................... 129 checkall, Description/Purpose............. 130 controlling iWave Components ........... 123 Controlling iWave Director .................. 123 Description/Purpose............................ 129 Including Commands In ...................... 123 iWave Director Starting/Stopping 129, 130 nnm_exec Example............................. 188 Required Parameters .......................... 130 Required Passwords ........................... 130 Running iWave Administrator CLI ....... 129 Running SDDC Status Reports........... 130 setenv.................................................. 129 start_agent .......................................... 129 start_agent Description/Purpose......... 130 start_agent Starting Universal Agent .. 130 start_agentaxc..................................... 131 startall.................................................. 129 startall Description/Purpose ................ 130 Starting iWave Director ....................... 123 stopall .................................................. 129 stopall Description/Purpose ................ 130 UNIX............................................ 123, 129 Using ................................................... 129 scripts/setenv Files Modifying ............................................. 129
SDDC Description/Purpose.....................123, 124 Issuing Commands ..............................124 iWave Director Error Events ................126 Replacing sdstatus Utility.....................124 Running................................................129 Running Status Reports.......................130 Status Reports .....................................133 Syntax ..................................................124 Unicode Files .......................................125 SDHOME Values .....................................129 SDMCONFG............................................195 pntmcs....................................................89 sdserver.ini agent_name Section Windows/UNIX...242 agent_name Section z/OS ...................240 Agents Section .....................................240 application_name Section Windows/UNIX ..........................................................235 application_name Section z/OS...........233 Base Sections UNIX ............................200 Base Sections Windows ......................204 Changing Settings................................195 ClientApplications Section ...................232 Configuring Keys UNIX ........................200 Configuring Keys Windows ..................204 Defining Authorized Users ...........129, 130 Examples .............................................195 InternetParameters Section z/OS ........208 iwave_director_name Section UNIX and Windows ...........................................215 iwave_director_name Section z/OS.....214 ReceiveFrom Section Window/UNIX ...209 ReceiveFrom Section z/OS..................209 ReceiveFromSSL Section Windows/UNIX ..........................................................210 SendTo Section ...................................213 SendToSSL Section.............................219 service_name Section Windows/UNIX 228 service_name Section z/OS.................224 Services Section ..................................223 ssl_recv_name Section UNIX ..............210 ssl_recv_name Section Windows ........212 ssl_send_name Section UNIX and Windows ...........................................219 sdstatus Utility Replacement ...................124 SDSTATUSPORT Values .......................129 Search .......................................................41 Description .............................................46 Records................................................170 Rules ....................................................176 Server...................................................170 Shared Libraries...................................130 Specifying Criteria..................................43 Verbs, Processing................................174 Search Argument
iWave Software
Revised [03/01/07] P01-664-09
Poll Criteria............................................ 34 Search Phases Client ................................................... 167 Description/Purpose............................ 166 Details ................................................. 176 Exits..................................................... 169 Rules ................................................... 176 Running PRE-VERB transaction Exits 169 Search Processing .............................. 170 Server.................................................. 170 Search Transactions ....................... 142, 170 Search Verbs .......................................... 142 Multiple Active Sections ...................... 169 Processing........................................... 169 Searching Client Processing/Mapping Files ................................................. 142 Searching for Records ........................ 170 SEARCH-ALWAYS........................... 43, 170 SEARCH-CRITERIA ............................... 170 Section Names Defining ............................................... 140 Delimiting............................................. 139 Processing Files .................................. 225 UOW.................................................... 225 section_name.......................................... 181 Sections Active................................................... 142 Base .................................................... 138 Embedded ........................................... 140 Inheritance........................................... 146 Mapping/Processing Files ........... 138, 143 Object Class ................................ 138, 140 Verb............................................. 139, 143 Verb Qualifier ...................... 139, 140, 143 Verb, Mapped Data Model Fields........ 148 Secure Sockets UNIX and Windows ............................. 210 Secure Sockets Layer....................... 24, 117 Securing Transactions .............................. 24 Security For Transactions ................................... 24 Optional ................................................. 24 SendTo Section ...................................... 213 SendToSSL Section ............................... 219 Serial Initialization iWave Integrators ................................ 198 Server #CLIENT-OBJECT-ID# ......................... 67 Data Model Fields Sent......................... 29 Description/Purpose.............................. 17 Identifying ............................................ 141 Names ................................................... 31 Optional Error Text................................ 69 Processing By ..................................... 169 Protecting Data Loss............................. 42 Received Server Object ID.................... 43
Remote.................................................169 Search Phase.......................................176 Settings for Restricted Commands ........95 Settings for Unrestricted Commands.....92 Subsequent Processing .........................44 Verbs......................................................33 Server Instances Terminating ..................................226, 230 Server Name..............................................31 Server Object ID ........................................40 Server Does Not Receive ......................43 Server Object ID(SOID).............................31 server_name............................................181 server_object_id ......................................181 Servers Identifying.............................................223 Starting.................................................202 Service.....................................................223 Service Interface......................................123 Service Key service_name section ..........................224 service_name Section .....................227, 231 Configuration Files, Windows/UNIX.....228 Configuration Files, z/OS .....................224 ServiceManager...............................213, 219 Services Section ......................................223 Sessions SDDC/iWave Director Reporting Log Messages .........................................126 SET Commands Description/Purpose .........133 Set Actions Issuing..................................................124 Set Verbs Supported by iWave Administrator CLI127 Setenv Scripts Running iWave Administrator CLI........129 Settings For Other Interfaces.............................162 For SQL Interfaces...............................161 PAFTER ...............................................173 PBEFORE ....................................173, 174 Settings for Restricted Commands Agent......................................................94 Client ......................................................94 Server.....................................................95 Settings for Unrestricted Commands Agent......................................................91 Client ......................................................92 Server.....................................................92 SET-VALUE-IF ...... 144, 168, 171, 172, 174, 176, 185, 186 Processing Data Model Fields .............168 Search Phase Rules ............................176 SET-VALUE-IF-GROUP..........................185 SFIELD ....................................................177
iWave Software
Revised [03/01/07] P01-664-09
Shared Libraries............................................... 130 Shutdown Actions Issuing ................................................. 124 Shutdown Verbs Supported by iWave Administrator CLI127 SNA........................................................... 13 Software Controlling iWave Integrator.................. 17 SOLVE:Central ....................................... 123 Storing Client Object ID......................... 30 Spaces in Syntax .................................... 195 Specifying Failure and Recover Codes .................. 56 Failure Codes ........................................ 56 Recover Code ....................................... 56 Scalability .................................... 224, 229 SQL Storing Client Object ID......................... 30 SQL Interfaces Permitted Masks.................................. 163 Required Fields ................................... 161 SQL-TEXT .............................................. 145 SSET............................................... 176, 178 SSL ......................................................... 117 Authentication...................................... 117 Encryption ........................................... 117 UNIX and Windows ............................. 210 Stages Transactions................................ 166, 167 Transactions, Description/Purpose ..... 169 Transactions, Remote Server Processing ......................................................... 169 Transactions, Stage 1 ......................... 167 Transactions, Stage 2 ......................... 169 Transactions, Stage 3 ......................... 173 Start Commands .. 226, 230, 233, 237, 241, 243 START Commands Description/Purpose ........ 133 component_name ............................... 133 component_type.................................. 133 Start Actions Issuing ................................................. 124 Start Agent Scripts Running iWave Administrator CLI ....... 129 Start Verbs Supported by iWave Administrator CLI127 start_agent Changing Variables............................. 131 Scripts ................................................. 131 UNIX Scripts........................................ 130 Startall UNIX Scripts........................................ 130 Startall Scripts Defining/Purpose................................. 130
Running iWave Administrator CLI........129 Starting iWave Director ........................123 Started Task Running iWave Director .......................132 Starting Agents ................. 124, 127, 130, 133, 202 Clients ......................... 124, 127, 133, 202 Components Managed by iWave Directors ..........................................................202 Cycle Verbs..........................................124 iWave Director............. 229, 237, 241, 243 iWave Director Components ........133, 202 iWave Director on UNIX.......................129 iWave Director, Child Processes 229, 237, 241, 243 iWave Directors On z/OS.....................132 iWave Integrator...........................124, 127 Managed Resources............................127 New Logs .............................................127 Objects .................................................127 Processes, Child . 224, 229, 237, 241, 243 Servers........ 124, 128, 133, 202, 226, 230 Universal Agent....................................130 Statements...............................................143 Assignment ............................23, 149, 153 Assignment Syntax ..............................144 Begin ....................................................139 End.......................................................139 In Mapping Files...................................143 In Processing Files...............................143 Keyword ...............................................153 Keyword Syntax ...................................143 Mapping ...............................................144 Mapping Syntax ...................................144 SET-VALUE-IF.....................................185 SET-VALUE-IF-GROUP ......................185 SUB-TABLE .........................................185 TRANSLATE-FIELD ............................185 Statistics Managed Resources............................126 Status Generating Reports for iWave Director132 iWave Director......................................132 Operational for Managed Resources...126 REPORT Commands...........................132 STATUS Data Model Fields ................................148 stderr........................................................181 stdout .......................................................181 Stop Commands.. 226, 230, 233, 237, 241, 243 STOP Commands Description/Purpose .........133 component_name ................................133 component_type ..................................133 Stop Actions
iWave Software
Revised [03/01/07] P01-664-09
Issuing ................................................. 125 Stop Verbs Supported by iWave Administrator CLI128 stopall Requirements ...................................... 130 Stopall Scripts Defining/Purpose................................. 130 Running iWave Administrator CLI ....... 129 Stopping Agents ................................. 125, 128, 133 Clients ......................... 125, 128, 132, 133 Components Managed by iWave Director ......................................................... 128 CYCLE Command............................... 134 Forced Stops ....................................... 134 iWave Director..................... 127, 131, 132 iWave Director Components ............... 133 iWave Integrators ................ 125, 128, 130 Managed Resources ................... 126, 127 Objects ................................................ 126 Processes.................................... 224, 229 Servers ........................ 125, 128, 132, 133 Shutdown Verbs .................................. 124 TERM Commands............................... 132 StopWaitInterval Keys .................................................... 197 Store Locale Client Different from Agent.................. 193 Successive Invocations....................... 183 store_locale............................................. 182 Agent -g Argument .............................. 182 Creating with VSAMINIT ..................... 182 Store-and-Forward Agent store_locale .............................. 182 Capability............................................... 50 Sending Requests when Agent Not Running ........................................... 182 Workings ............................................. 183 STORE-LOCALE .................................... 183 strlwr ....................................................... 106 strupr....................................................... 108 Subexpression Boolean Operators Errors ................... 158 Subkeywords CONTEXT ................................... 169, 173 FIELDS........................................ 168, 171 INIT...................................................... 177 OBSERVE-FAIL .............................. 66, 75 PFIELD........................................ 176, 178 PFLAGS ...................... 173, 174, 175, 176 PSE ..................................................... 177 SFIELD................................................ 177 SSET ........................................... 176, 178 VALUE................................................. 177 WMODE .............................................. 177 Subordinate
Embedded Scetions.............................140 SUB-TABLE41, 69, 141, 167, 168, 171, 173, 174, 175, 176, 177, 185 Subtable Statement #ERROR-TEXT#....................................69 SUB-TABLE Statements .........................185 SUBTABLE_DELIMITER.........................144 Subtables...................................................40 Identifying.............................................141 PAFTER ...............................................177 PBEFORE ............................................177 Records, Creating/Updating.................177 Referencing..................................167, 176 Subtasks Terminating ..........................................197 Success Codes....................................35, 56 Default Value..........................................56 Success Fields.....................................35, 57 Specifying...............................................58 Value Over Returned From Server ..57, 58 SUCCESS-CODES .................................174 SUCCESS-FIELDS..................................174 Superior Embedded Scetions.............................140 Supported Platforms..................................16 Synchronizing Local and Remote iWave Integrators ....41 Syntax Assignment Statements .......................144 Command Line For Universal Agent....180 CYCLE Commands..............................134 Errors ...................................................154 EtcHosts...............................................208 EtcServices ..........................................208 For Scripts............................................130 IP Addresses........................................124 iWave Director Configuration Files ......195 Keywords .............................................143 KILL Commands ..................................134 Mapping Statements ............................144 Personal-Name ....................................145 Relational Expression ..........................157 REPORT Commands...........................132 SDDC ...................................................124 SET Commands...................................133 Spaces Within Configuration File Files 195 START Commands..............................133 STOP Commands................................133 TERM Commands ...............................132 Timestamp ...........................................145 Transferring Personal Name Data .........62 Syntax Rules............................................153 System Console Commands CYCLE..............................134 Commands KILL ..................................134 Commands REPORT...........................132
iWave Software
Revised [03/01/07] P01-664-09
Commands SET .................................. 133 Commands START ............................. 133 Commands STOP ............................... 133 Commands TERM............................... 132 Messages ............................................ 197 System Variable #ALL# .................................................. 154 #ALL# Specifying EXCLUDE Keyword 148 #ALL# Specifying INCLUDE Keyword 147 #APP-RC#............................................. 66 #CLIENT-OBJECT-ID# ......................... 67 #DATE#................................................. 67 #DIP-RC# .............................................. 68 #DIP-RS# .............................................. 68 #ERROR-TEXT# ................................... 69 #EXIT# .......... 69, 144, 154, 168, 171, 174 #EXIT# Specifying in Assignment Statements....................................... 174 #EXIT#, Specifying in Assignment Statements....................................... 168 #FIXED-NOW#...................................... 71 #NOW#.................................................. 72 #NULL# ................................. 72, 154, 158 #SERVER-OBJECT-ID# ....................... 72 #TIME#.................................................. 73 Differences ................................ 67, 72, 73 T TABLE-NAME ......................................... 141 Target Fields ..................................... 61, 149 TCP/IP Address for Client................................ 131 Address Space, Identifying ................. 208 ASID Key............................................. 208 EtcPrefix Keys ..................................... 208 Ports .................................................... 131 TERM Commands Description/Purpose............................ 132 Specifying Time Intervals with StopWaitInterval Keys ..................... 197 Terminating Subtasks ......................... 197 Terminate Active Components ............................. 134 Clients ................................................. 124 iWave Integrators ................................ 124 Servers ................................................ 124 Terminating Agent ........................................... 240, 243 Client ........................................... 233, 237 Managed Resources ........................... 126 Server Instances ......................... 226, 230 Subtasks.............................................. 197 Termination Forcing Application.............................. 197
Text Indicator Fields ....................36, 55, 169 Text Lines Freeform Text Entry Additions .............151 TEXT-INDICATOR.......... 168, 169, 171, 174 TEXT-USERID.........................................151 Time Universal Coordinated Time 197, 201, 206 time_t .......................................................160 timeconv ..................................................108 timediff .....................................................109 Timestamp Fields ......................61, 157, 158 Converting............................169, 171, 174 Data Model Fields ..................................60 Examples .............................................145 Freeform Text Entry Additions .............151 Text Indicator Fields...............................55 TIMESTAMP Fields SQL Interfaces .....................................161 Timestamp Format.....................................61 Timestamp Masks......................62, 158, 160 Description/Purpose.............................158 TIMESTAMP-FIELDS..............................158 Keywords .............................................145 timestr ......................................................111 TimeZone Keys........................197, 201, 206 Tivoli Information Management Storing Client Object ID .........................30 Tivoli Service Desk for z/OS....................123 tokenize ...................................................112 tranchr......................................................113 Transaction Agents, -a parameter ...........................185 Authentication ........................................24 Changing Processing Behavior..............74 Content...................................................29 Data Flow ...............................................20 Ends in Recoverable Error.....................58 Fails........................................................58 Identifying Primary Table .......................40 Outcome.................................................57 Phases .................................................166 Post Processing Update ........................55 Processing ...........................................166 Return Values ..................................35, 56 Specifying Subtables .............................40 Stages ....................................................20 Starting...................................................33 Subtypes ................................................33 Successful......................................58, 175 Transaction Delays Responding ............................................52 Transaction Exits .........................26, 74, 173 #ERROR-TEXT#....................................69 pntwto...................................................102 POST-TRAN-ABORT...................173, 175 POST-TRAN-FAILURE................173, 175
iWave Software
Revised [03/01/07] P01-664-09
POST-TRAN-RECOVER ............ 173, 175 POST-TRAN-SUCCESS............. 173, 175 POST-VERB........................................ 169 PRE-TRAN .......................................... 169 PRE-UPDATE ..................................... 174 PRE-VERB .................................. 169, 173 Read Phase......................................... 167 Search Phases .................................... 167 Transaction Return Value ......................... 32 System Variables .................................. 66 TRANSACTION-EXIT ..................... 166, 169 Translate Field .......................................... 63 Data Accessing ..................................... 65 TRANSLATE-FIELD .. 63, 64, 152, 167, 168, 171, 172, 174, 176, 185 Keywords............................................. 155 Transmission Error Text .............................................. 32 TSOAUTAG ............................................ 192 TSOAUTAG JCL..................................... 192 U uniagt .............................................. 180, 187 Unicode Conversion Table Pathname ... 200, 204 unicode_file............................................. 184 Unicode-File Values ................................................. 125 Verbs Supported by iWave Administrator CLI ................................................... 125 UNIQUE WMODE Setting .................................. 177 Unique Fields ............................................ 43 UNIQUE-FIELDS .............................. 43, 170 Unit of Work ...................................... 98, 173 Description/Purpose............................ 172 Universal Agent................................. 49, 179 Avoid Using -a parameter ................... 184 Example .............................................. 187 Executable........................................... 180 Return Codes ...................................... 194 Running ............................................... 190 Running Normal Mode ........................ 190 Sample Restricted Commands ............. 93 Sample Settings for Unrestricted Commands ........................................ 90 Starting ................................................ 130 Syntax ................................................. 180 Universal Coordinated Time (UTC) Specifying TimeZone Keys . 197, 201, 206 UNIX Agent Example .................................... 188 Configuration Files, agent_name Sections ......................................................... 242
Configuration Files, application_name Sections............................................235 Configuration Files, iwave_director_name Section..............................................215 Configuration Files, service_name Sections............................................228 Configuration Files, ssl_send_name Section..............................................219 Exit Functions.........................................75 Exits .......................................................75 ReceiveFrom Section...........................209 Scripts ..........................................123, 129 Scripts to Administer iWave .................129 Starting iWave Director ........................123 store_locale..........................................182 unicode_file ..........................................184 Universal Agent Example.....................187 Writing Functions .................................114 Unlock........................................................41 Description .............................................46 Unmapped Data Model Placing Data...........................................74 Update .......................................................41 Description .............................................45 Phase Create-Unique Processing .......169 UPDATE ....................................................33 Update Return Fields...........................44, 45 USE-KEYWORD-IF .................169, 173, 174 User ID Freeform Text Entry Additions .............151 SDDC Syntax .......................................125 Userid Verbs Supported by iWave Administrator CLI ....................................................125 Users Authorized ....................................125, 129 Inherting Permissions ..........................202 User Defined Key.........................241, 244 V VALUE .............................................177, 178 Value Assignments Across Data Types...............................148 Value For Translate Field #ERROR-TEXT#....................................69 Values Local-Address ......................................125 MAXDEPTH .................................224, 229 MAXPROCESS............................224, 229 MINPROCESS .............................224, 229 Object...................................................125 Object-Type..........................................125 Option...................................................125 Password .............................................125
iWave Software
Revised [03/01/07] P01-664-09
Port...................................................... 124 QUIESCE .................................... 224, 229 SDHOME............................................. 129 SDSTATUSPORT ............................... 129 Unicode ............................................... 125 Variables #ALL# .......................................... 147, 148 #EXIT# ................................................ 144 $SD_BINPATH.................................... 131 $SD_LOGPATH .................................. 131 $SD_MGMTIPADDR........................... 131 $SD_NOTFPORT ............................... 131 Changing Scripts ................................. 131 Environment, Default........................... 130 Environment, LD_LIBRARY_PATH .... 130 Environment, LIBPATH ....................... 130 Environment, Specifying with setenv Scripts.............................................. 129 Vendor Application.................................... 16 Assigning a Data Model Field Value ..... 60 Client Object ID ..................................... 30 Fields Containing Special Characters. 145 Freeform Text........................................ 36 Invoking an Agent ................................. 34 Modifying for Universal Agent ............. 190 Oracle Environment Variables ............ 130 Return Code .......................................... 55 Rolling Back Data................................ 178 Sharing Data ......................................... 19 SOLVE:Central.................................... 123 Supported.............................................. 27 Tivoli Service Desk.............................. 123 Treating Vendor Fields as Character Data ................................................. 158, 160 Writing Data......................................... 172 Writing Data to..................................... 174 Vendor Fields SQL Interfaces .................................... 161 vendor_field .................................... 144, 184 Vendor-Application Return Code .. 66, 68, 69 Vendor-Field Values Pairing ................................................... 63 Verb Processing...................................... 141 Verb Qualifier ............................................ 47 Sections............................................... 139 Sections, Description/Purpose ............ 141 Verb Sections.......................................... 139 Description/Purpose............................ 141 Mapped Data Model Fields ................. 148 Verbs......................................................... 41 Create.................................................... 41 Create-Unique ............................... 41, 142 CREATE-UNIQUE ................................ 33 Cycle ................................................... 126 Description/Purpose.............................. 33 Guaranteed Delivery ............................. 52
iWave Administrator CLI ......................124 Kill ........................................................126 Lock........................................................41 Lock/Unlock..........................................168 Processing ...........................................142 Report ..................................................126 Retrieve..........................................41, 143 RETRIEVE .............................................31 Search............................................41, 142 Set........................................................127 Setting Operational Parameters...........127 Shutdown .............................................127 Specifying Pre Defined Names ............140 Start......................................................127 Stop......................................................128 Unlock ....................................................41 Update....................................................41 UPDATE.................................................33 VSAMINIT Modifying..............................................190 VSAMINIT JCL ........................................182 Create storelocale Data Sets ...............182 W Windows Configuration Files, agent_name Sections ..........................................................242 Configuration Files, application_name Sections............................................235 Configuration Files, iwave_director_name ..........................................................215 Configuration Files, service_name Sections............................................228 Configuration Files, ssl_send_name Section..............................................219 Configuration Keys...............................204 Enhanced Server Scalability ................229 Exit Functions.........................................75 Exits .......................................................75 Starting iWave Director ........................123 Universal Agent Example.....................187 Writing Functions .................................114 Windows NT/2000 store_locale..........................................182 unicode_file ..........................................184 WMODE...................................................177 Write Phase ...............................................70 Client ....................................................171 CONTEXT Options ..............................171 Description/Purpose.............................166 Last Steps ............................................177
Processing Subtables ......................... 177 Server.......................................... 171, 172 Writing Client Object ID ..................................... 30 Freeform Text to Database ................... 39 Functions for Use in Exits ................... 114 To Data Base, Data Model Fields ....... 175 To iWave Director Logs...... 127, 196, 200, 204, 227, 231, 235, 239, 241, 245 To Mapping/Processing Files.............. 143 To Primary Table................................. 177 To Subtables ....................................... 177 To Vendor Applications ....................... 172 Z z/OS Administering iWave Integrator ........... 131 Changing iWave Director Log Options 133 Commands .................................. 123, 131 Configuration Files, agent_name Sections ......................................................... 240 Configuration Files, application_name Sections ........................................... 233 Configuration Files, iwave_director_name Sections ........................................... 214 Configuration Files, service_name Sections ........................................... 224 Configuring Keys ................................. 196 Controlling iWave Director .................. 131 Cycling Components ........................... 134 Enhanced Server Scalability ............... 224 Exit Functions........................................ 78 Exits....................................................... 77 Forcing Components to Stop .............. 134 Internet Paramenters Section ............. 208 Launching the Agent ........................... 189 Log Object Type .................................. 128 Long Running Agent ........................... 183 Standard Linkage Conventions ........... 179 Starting Components .......................... 133 Starting iWave Director ....................... 123 Stopping Components......................... 133 Stopping iWave Director ..................... 131 store_locale ......................................... 182 Subtasks................................................ 52 System Commands from UNIX ............. 87 Tivoli Service Desk.............................. 123 unicode_file ......................................... 184 Using VSAMINIT JCL.......................... 182 Writing Functions ................................ 114
iWave Software
Revised [03/01/07] P01-664-09
Confidential
Page 276 of 276

Iwave Integrator Users Guide PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Iwave Integrator Users Guide PDF

Hochgeladen von

Copyright:

Verfügbare Formate

iWave Integrator User Guide

Revision 5.7.20 Updated 03/01/07

iWave Integrator User Guide

th iWave Integrator Users Guide 10 Edition, March 2007 P01-664-09

Publication Copyright Notice

Address inquiries to: iWave Software

iWave Integrator User Guide

iWave Integrator User Guide

iWave Integrator User Guide

iWave Integrator User Guide

iWave Integrator User Guide

GLOSSARY................................................................................................................................. 246 INDEX.......................................................................................................................................... 254

iWave Integrator User Guide

iWave Integrator User Guide

iWave Integrator User Guide

About This Guide

iWave Integrator User Guide

iWave Integrator Library Information Map

iWave Integrator User Guide

iWave Integrator Guides

iWave Integrator User Guide

NOTE purposes only and are no longer applicable.

iWave Integrator User Guide

iWave Integrator User Guide

iWave Integrator User Guide

iWave Integrator User Guide

Figure 3 iWave Directors Control One or More iWave Integrators

iWave Integrator User Guide

Figure 4 Single Point of Control from a Windows Machine

Enterprise Data Model

Figure 5 Vendor Application Data Maps to the Enterprise Data Model

iWave Integrator User Guide

Transactions Between iWave Integrators

iWave Integrator User Guide

iWave Integrator User Guide

Defining Mapping and Processing

iWave Integrator User Guide

Figure 9 Severity and Priority Map to SevPri

iWave Integrator User Guide

iWave Integrator User Guide

Figure 10 Encrypt Traffic That Crosses the Internet

Specialized Processing with iWave Exits

iWave Integrator User Guide

Automatic Creation of Problem Reports

iWave Integrator User Guide

iWave Integrator User Guide

Figure 12 iWave Integrator Connection

iWave Integrator User Guide

What Data is Sent from Client to Server?

iWave Integrator User Guide

iWave Integrator User Guide

What Data is Returned from Server to Client?

iWave Integrator User Guide

Transaction Return Value

iWave Integrator User Guide

What is Verb CREATE-UNIQUE?

What Causes a Client to Begin Processing a Transaction?

iWave Integrator User Guide

Event Detection Mode

Poll Detection Mode

iWave Integrator User Guide

How Does the Client Respond to Transaction Success or Failure?

iWave Integrator User Guide