tibco ems client for ibm i installation and reference · ibm websphere development studio – ile...

Two-Second Adv

TIBCO® EMS Clientfor IBM i

Installation and ReferenceSoftware Release 8.2November 2014

antage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDEDOR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITEDADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLEDSOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FORANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF ALICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSEAGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USERLICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THESOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARELICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATEDIN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMSAND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND ANAGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws andtreaties. No part of this document may be reproduced in any form without the written authorization of TIBCOSoftware Inc.TIBCO, Two-Second Advantage, TIB, Information Bus , TIBCO Enterprise Message Service, TIBCO Rendezvous,TIBCO Enterprise, TIBCO SmartSockets, TIBCO ActiveMatrix BusinessWorks, and TIBCO Hawk are eitherregistered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition(J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporationin the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALLOPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAMETIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFICOPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BEINCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKEIMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED INTHIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDINGBUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1995-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viTIBCO EMS Client for IBM i Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viTIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viThird Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiHow to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2IBM System i Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4Application Development Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4QSHELL Command Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5IBM Tools for Developers for IBM i PRPQ (5799PTL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5SSL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Distribution Media and Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10Obtaining the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10Installation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Uploading the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Previous Releases of the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13Identifying Previous Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13Deleting Previous Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15Dynamic Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Compiling the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

TIBCO EMS Client for IBM i Installation and Reference

iv | Contents

ILE RPG Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Verifying SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Importing Sample Certificates using the Digital Certificate Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Configuring the EMS Server for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Sample Invocations from the QSHELL to Verify SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Running and Developing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Running Applications and C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Running Applications From the Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Running Applications From the QSHELL Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Running Applications and RPG Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Data Conversion Plug-in Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Running Applications and COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Executing the EMS COBOL Sample Programs from QSHELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Submitting to Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Binding Your Application to the Correct Version of the EMS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Programmer's Checklist for C Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Compile and Bind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Programmer's Checklist for RPG Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Compile and Bind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Programmer's Checklist for COBOL Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Compile and Bind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Appendix A Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

TIBCO EMS Messaging Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42C Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Appendix B EMS Client Programming in RPG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Appendix C Installed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49


| v

Preface

This manual provides information about the TIBCO EMS Client for IBM iproduct. It is intended primarily for programmers who are responsible forinstalling and maintaining the software. Some of the information contained heremay also be useful for application programmers involved in creating ormodifying programs that work in conjunction with this product.

This release is the latest in a long history of TIBCO products that leverage thepower of the Information Bus® to enable truly event-driven IT environments. Tofind out more about how TIBCO EMS Client for IBM i and other TIBCO productsare powered by TIB® technology, please visit us at www.tibco.com.

Topics

• Related Documentation, page vi

• Typographical Conventions, page viii

• Connecting with TIBCO Resources, page xi

This software may be available on multiple operating systems. However, notall operating system platforms for a specific software version are released at thesame time. Please see the readme file for the availability of this softwareversion on a specific operating system platform.


www.tibco.com

vi | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO EMS Client for IBM i Documentation• TIBCO EMS Client for IBM i Installation and Reference This manual describes

the installation and use of the EMS Client.

• TIBCO EMS Client for IBM i Release Notes Read the release notes for a list ofnew and changed features. This document also contains lists of known issuesand closed issues for this release. This document is available only in PDFformat.

TIBCO Enterprise Message Service DocumentationThe following documents form the TIBCO Enterprise Message Servicedocumentation set:

• TIBCO Enterprise Message Service User’s Guide Read this manual to gain anoverall understanding of the product, its features, and configuration.

• TIBCO Enterprise Message Service Central Administration Read this manual forinformation on the central administration interface.

• TIBCO Enterprise Message Service Installation Read the relevant sections of thismanual before installing this product.

• TIBCO Enterprise Message Service C & COBOL Reference The C API reference isavailable in HTML and PDF formats.

• TIBCO Enterprise Message Service Java API Reference The Java API reference canbe accessed only through the HTML documentation interface.

• TIBCO Enterprise Message Service .NET API Reference The .NET API referencecan be accessed only through the HTML documentation interface.

• TIBCO Enterprise Message Service Release Notes Read the release notes for a listof new and changed features. This document also contains lists of knownissues and closed issues for this release. This document is available only inPDF format.


Preface | vii

Third Party DocumentationIBM publications you may find useful are listed below.

Publication Title

IBM iSeries – ILE Concepts

IBM iSeries – TCP/IP Configuration and Reference

IBM AS/400 – ILE Application Development Example

IBM WebSphere Development Studio – ILE C/C++ Language Reference

IBM WebSphere Development Studio – ILE C/C++ Compiler Reference

IBM WebSphere Development Studio – ILE C/C++ Programmer's Guide

IBM WebSphere Development Studio – ILE COBOL Programmer's Guide

IBM WebSphere Development Studio – ILE COBOL Reference

IBM WebSphere Development Studio – ILE RPG Language Reference

IBM WebSphere Development Studio – ILE RPG Programmer's Guide

IBM System i Programming – Socket Programing

IBM System i Security – Digital Certificate Manager


viii | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

ENV_NAME

TIBCO_HOME

EMI_HOME

TIBCO products are installed into an installation environment. A productinstalled into an installation environment does not access components in otherinstallation environments. Incompatible products and multiple instances of thesame product must be installed into different installation environments.

An installation environment consists of the following properties:

• Name Identifies the installation environment. This name is referenced indocumentation as ENV_NAME. If you specify a custom environment name,on Microsoft Windows the name becomes a component of the path to theproduct shortcut in the Windows Start > All Programs menu.

• Path The folder into which the product is installed. This folder is referencedin documentation as TIBCO_HOME. The value of TIBCO_HOME depends onthe operating system. For example, on Windows systems, the default value isC:\tibco.

TIBCO EMS Client for IBM i installs into a directory within TIBCO_HOME. Thisdirectory is referenced in documentation as EMI_HOME. The value of EMI_HOMEdepends on the release version. For example, the value for software release 8.2.0is /usr/tibco/tibems/8.2.0.

code font Code font identifies commands, code examples, filenames, pathnames, andoutput displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font

Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are ofparticular interest.

• In command syntax, to indicate the default parameter for a command. Forexample, if no parameter is specified, MyCommand is enabled:MyCommand [enable | disable]


Preface | ix

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrixBusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain severalportlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace.For example: MyCommand PathName

Keycombinations

Key name separated by a plus sign indicate keys pressed simultaneously. Forexample: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after theother. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, forexample, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to applythe information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example,data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3


x | Typographical Conventions

{ } A logical group of items in a command. Other syntax notations may appearwithin each logical group.

For example, the following command requires two parameters, which can beeither the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parametercan be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters.The first parameter must be param1. You can optionally include param2 as thesecond parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}

Table 2 Syntax Typographical Conventions

Convention Use


Preface | xi

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destination for TIBCO customers, partners, andresident experts. It is a place to share and access the collective experience of theTIBCO community. TIBCOmmunity offers forums, blogs, and access to a varietyof resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO DocumentationYou can access TIBCO documentation here:

https://docs.tibco.com

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, contactTIBCO Support as follows:

• For an overview of TIBCO Support, and information about getting startedwith TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a username, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

https://docs.tibco.com

http://www.tibcommunity.com

xii | Connecting with TIBCO Resources


| 1

Chapter 1 Introduction

This manual provides information about the TIBCO EMS Client for IBM iproduct. It is intended primarily for programmers who are responsible forinstalling and maintaining the software. Some of the information contained heremay also be useful for application programmers involved in creating ormodifying programs that work in conjunction with this product. We recommendthat you read through this manual before attempting to install the product, andkeep a copy handy for future reference.

Topics

• Overview, page 2

• System Requirements, page 4


2 | Chapter 1 Introduction

Overview

The TIBCO EMS Client for IBM i software allows applications running on IBM i toproduce and consume messages that are transported via TIBCO EMS servers.

Messages are structured data that one application sends to another. TIBCO EMSservers, running on platforms outside the traditional System i environment, act asintermediaries for messages and route them to recipients. This message flow isillustrated in the diagram below:

An IBM i application participates in this messaging environment as follows:

1. The IBM i application embeds TIBCO EMS API function calls to facilitatemessage communication.

2. The TIBCO EMS Client for IBM i establishes a connection with a TIBCO EMSserver using standard TCP/IP.

3. The IBM i application sends messages to or receives messages from the TIBCOEMS server using destinations for message routing.

4. Other TIBCO EMS clients communicate with the IBM i application via theTIBCO EMS server.

TIBCO EMS API function calls are coded by programmers and included in theSystem i application at compilation time. Please refer to TIBCO Enterprise MessageService User’s Guide for a complete description of TIBCO EMS operations.


Overview | 3

Limitations

This version of the TIBCO EMS Client for IBM i does not support the following:

• LDAP (Lightweight Directory Access Protocol)

IBM System i PlatformThe IBM i platform is a midrange server offering that uses IBM's proprietary ioperating system and includes an integrated database engine. The database iscalled DB2 UDB for IBM i. The file system, called Integrated File System (IFS), iscomprised of and provides an umbrella for several different sub-file systems.

The native file system used by System i is QSYS.LIB. Each entity in this file systemis called an object. Each object has an object type which is signified by a characterstring starting with the asterisk (*) character. For example, an executable programobject is signified by the character string *PGM; a data queue object is signified bythe character string *DTAQ.

A library is a special type of object signified by the character string *LIB. Libraryobjects are similar to directories in Windows and UNIX systems. A library is usedto group objects of different types together. However, unlike a directory, a librarycannot have another library as a child. Objects such as files (tables), programs andother native System i type objects can exist only inside a library. An object in alibrary is addressed as <library name>/<object name>.

Each unit of work processed by the IBM i system is called a job. Each job isuniquely identified by a job number assigned by the system when the job isstarted. Each job also has a library list associated with it. This is similar to thePATH variable on Windows or LD_LIBRARY_PATH variable on UNIX. When anobject is not explicitly qualified using a library name, the object is searched in thelibrary list for the job. The first occurrence of the object in the library list is used. Alibrary list is signified by string *LIBL.



System Requirements

An application that uses the TIBCO EMS Client for IBM i software runs as an IBMi job with multiple user threads enabled (ALWMLTTHD(*YES)). Product supportfor platform and versions can be located in the readme documentation.

Before installing the product in an IBM i environment, you must ensure that thefollowing are installed and properly configured:

Storage RequirementsThe TIBCO EMS Client for IBM i requires approximately 50 MB of auxiliarystorage to install.

TCP/IPThe TIBCO EMS Client for IBM i is expected to be installed and operated within apreviously existing, fully functional and integrated network. At a minimum, thisincludes the following:

• The TCP/IP protocol stack.

• A DNS server that provides the hostname and host address of the TIBCO EMSClient for IBM i and the TIBCO EMS server.

• Unrestricted network connectivity between the DNS, the TIBCO EMS Clientfor IBM i, and the TIBCO EMS server.

Customers should review their TCP/IP configuration with the CFGTCPcommand to ensure that it meets the installation’s needs. If customers want tocontrol TCP buffering to limit storage usage or to support large bandwidthdevices, they can modify the TCPRCVBUF and TCPSNDBUF values with theCHGTCPA command.

Application Development LanguagesThe TIBCO EMS Client for IBM i is implemented using the ILE C compiler. AnyILE compiler on System i can be used for application development. Sampleprograms are provided in C, RPG, and COBOL with your installation.


System Requirements | 5

QSHELL Command InterpreterAlthough not required, TIBCO Software recommends that you install theQSHELL Command Interpreter (option 30 of the OS). This provides the followingbenefits:

• Run your samples and applications in interactive mode.

• Compile all the C sample programs using a makefile.

• Utilize long names for the C sample programs and application invocation.

IBM Tools for Developers for IBM i PRPQ (5799PTL)If you compile the C sample programs using a makefile, as indicated in theprevious section, you must also have the icc and gmake utilities:

• gmake – the GNU make utility

• icc – the C compiler (invokes the ILE C compiler)

Locating the Utilities

The icc and gmake programs may already be installed on your system. Theseutilities are commonly located in one of two locations, and you can verify theirpresence by:

1. Enter the commandWRKLNK OBJ('/qibm/proddata/developertools/qsh/bin')

2. If the OBJ is found

a. Chose Option 5.

b. Scroll through to see if you see icc and gmake under Object link.

3. If icc and gmake are not there, repeat step 2 with the command:WRKLNK OBJ('/usr/bin')

If you locate the two programs under either of these two paths you can continueto compile the samples.

Installing the Utilities

If the programs are not already installed on your system, you can obtain them byfollowing the following steps provided by IBM in technical document 340490501,IBM Tools for Developers for IBM i (5799PTL) and Qshell Utilities PRPQ(5799-XEH).



Once 5799PTL is installed, icc and gmake can be located in directory/qibm/proddata/developertools/qsh/bin. To execute these programs fromthat location, you must make sure that you have that directory path included inenvironment variable PATH before you start your qshell environment.

To add the directory to your PATH environment variable, execute the followingcommand from your Command Entry screen:

ADDENVVAR ENVVAR(PATH)VALUE('./:/usr/bin:/qibm/proddata/developertools/qsh/bin')

SSL RequirementsThe TIBCO EMS Client for IBM i uses the IBM System SSL facility to create secureconnections to the EMS server. To use System SSL, you may need to configure:

• Digital Certificate Manager (Option 34)

• IBM HTTP Server (5761DG1)

Digital Certificate Manger

The Digital Certificate Manager (DCM) centralizes the management and use ofcertificates within certificate stores on an IBM i system. It provides the ability tocreate a local Certificate Authority (CA) that may be used to issue clientcertificates. The DCM may also be used to import certificates obtained from othersources, such as the sample certificates shipped with the TIBCO EMS Client forIBM i.

For details on how to obtain a copy of the private CA certificate from the DCM,see the Digital Certificate Manager section in the IBM iSeries Information Center.

IBM HTTP Server

The HTTP *ADMIN instance may be used to administer the DCM using a webbrowser. To administer the DCM, a user profile with *ALLOBJ and *SECADMspecial authority is required.

For more information on how to start the HTTP *ADMIN instance and administerthe DCM, please consult the IBM documentation for the Digital CertificateManager.

Special Authority

Applications that use the TIBCO EMS Client for IBM i and SSL need read access toa certificate store. The application either needs to be run with a user profile thathas *ALLOBJ special authority, or the user profile needs to be given *RX dataauthority to the certificate store using the CHGAUT command.


System Requirements | 7

The path and filename for the object to be used with the CHGAUT command maybe seen by using the web browser interface to the DCM and selecting thecertificate store to open.


| 9

Chapter 2 Installation

This chapter describes how to install the TIBCO EMS Client for IBM i software.

Topics

• Distribution Media and Contents, page 10

• Uploading the Software, page 11

• Installing the Software, page 15

• Compiling the Sample Programs, page 18

• Verifying the Installation, page 21

• Verifying SSL, page 24


10 | Chapter 2 Installation

Distribution Media and Contents

This section describes how to obtain the software, and the installation filesincluded in the distribution media. The software is distributed as a *SAVF inside azip file.

Obtaining the SoftwareTo obtain the TIBCO EMS Client for IBM i software, you can download it from theTIBCO Software web site, or you can request a CD.

Downloading from the Web Site

To download the software from the TIBCO web site, follow these steps:

• Contact TIBCO Software for a password, directory information, and so forth.

• Connect to the TIBCO web site with the required information.

• Download the appropriate ZIP file.

Requesting a CD

If you do not want to download the software over the network, you can obtain aCD that contains the same ZIP file as that obtained from the web. Contact TIBCOSoftware via email at:

[email protected]

Request a CD for your System i product installation.

Installation FilesThe following ZIP file is included in the distribution media:

TIB_ems_version_ibmi_power.zip

where version is the TIBCO EMS Client for IBM i software release version. Forexample, for software release 8.2.0, the file name is:

TIB_ems_8.2.0_ibmi_power.zip


Uploading the Software | 11

Uploading the Software

Once you have obtained the ZIP file, you need to upload the software to theSystem i host system using the FTP file transfer utility. Perform the following:

1. Download or copy the installation zip file to a PC that can connect to IBM i.

2. Unzip this file to a temporary location on the PC. The file contains thefollowing:

— TIB_emsi5os_version_readme.txt – The readme for the current softwarerelease, where version is the TIBCO EMS Client for IBM i software releaseversion. For example, for software release 8.2.0, the file name isTIB_emsi5os_8.2.0_readme.txt.

— TIB_emsi5os_version_license.pdf – The license file, in PDF format, forthe current software release.

— TIB_emsi5os_version_license.txt – The license file, in text format, for thecurrent software release.

— TIB_emsi5os_version_relnotes.pdf – The Release Notes for the currentsoftware release.

— TIBEMSvrm.SAV – TIBCO EMS Client for IBM i product, where vrm refers tothe version, release and modification that make up the current release ofthe product. For example, for software release 8.2.0, the file name isTIBEMS820.SAV.

3. From the temporary location on the PC, open a FTP session with IBM i:ftp <YOUR_IBMi>

4. Enter the user ID and password when requested.

5. Select the File Naming Format for ftp commands:quote site namefmt 1

6. Change the default working directory (library) on IBM i that will receive thetransfer:

cd <TARGET_LIBRARY>.LIB

7. Change the local directory on the PC to where the TIBEMS820.SAV file resides:lcd <WINDOWS_DIRECTORY>

8. Specify a binary transfer:bin

9. Transfer the SAV file as a *SAVF. For example:put TIBEMS820.SAV TIBEMS820.SAVF



10. Verify that the FTP was successful by signing on to IBM i and displaying thecontents of the *SAVF. For example:

DSPSAVF <TARGET_LIBRARY>/TIBEMS820

This should display a number of objects on the bottom half of the screen.


Previous Releases of the Software | 13

Previous Releases of the Software

If previous versions of TIBCO EMS Client for IBM i have been installed on thesystem, you may either delete the previous releases of the product, or install thenew release in its own library.

Identifying Previous InstallationsIf TIBCO EMS Client for IBM i has been previously installed on the system, youcan obtain information about the existing installations by executing commandDSPSFWRSC.

For example:

ResourceID Option Feature Description

2TIBEMS *BASE 5001 TIBCO EMS Client V5R1M02TIBEM1 *BASE 5001 TIBCO EMS Client for i5/OS V5R1M5 GA2TIBEM1 *BASE 5001 TIBCO EMS Client for IBM i V6R1M0 GA

If you Press F11, you can also see the product library name and release:

Resource FeatureID Option Feature Type Library Release

2TIBEMS *BASE 5001 *CODE TIBEMS V5R1M02TIBEM1 *BASE 5001 *CODE TIBEMS515 V5R1M52TIBEM1 *BASE 5001 *CODE TIBEMS610 V6R1M0

You may now elect to either delete the previous releases of the product, or installthe new release along side the existing releases. To install the new release alongside any existing release, see Multiple Installations on page 16.

Deleting Previous InstallationsTo delete a previous installation of TIBCO EMS Client for IBM i, execute theDLTLICPGM command specifying the resource ID for the installation to beremoved. Note that you can obtain the resource ID using the DSPSFWRSCcommand, as described above.

Before software release 5.1.5, TIBCO EMS Client for IBM i could not be installedmultiple times on the same system. It is now possible to install the currentsoftware release alongside previous releases.

If you have already installed the current release and want to delete a previousrelease, make sure that you release-qualify the operation. For example, to deleteTIBCO EMS Client for IBM i release 6.1.0 only, run:

DLTLICPGM LICPGM(2TIBEM1) RLS(V6R1M0)



If the current release has not yet been installed and only one other release isinstalled on the sytem, you can delete the previous installation withoutrelease-qualifying DLTLICPGM. For example:

• To delete Software Release 5.1.0, execute the following:

DLTLICPGM LICPGM(2TIBEMS)

Note the Resource ID specified is 2TIBEMS.

• To delete Software Release 5.1.5, execute the following:

DLTLICPGM LICPGM(2TIBEM1)

Note that the Resource ID specified here is different, 2TIBEM1.

These operations are optional and can be performed in any order.


Installing the Software | 15

Installing the Software

Single Installation

Perform the following steps to install the TIBCO EMS Client for IBM i software.All objects reside within *SAVF TIBEMSvrm.

1. Sign-on as QSECOFR, or a different user profile with similar authority.

2. Use the Restore Licensed Program (RSTLICPGM) command to install thesoftware:

RSTLICPGM LICPGM(4TIBEM1) DEV(*SAVF)SAVF(<TARGET_LIBRARY>/TIBEMSvrm)

The above command will restore library TIBEMSLIB as well as a number ofstream files into the /root file system of the IFS in EMI_HOME.

Parameters:

— LICPGM(4TIBEM1) – specifies the seven-character identifier of the licensedprogram that is restored.

— DEV(*SAVF) – the device name where the product resides; in this case, thedevice is a *SAVF whose name is specified in the SAVF parameter.

— SAVF(<TARGET_LIBRARY>/TIBEMSvrm) – *SAVF TIBEMSvrm resides inlibrary <TARGET_LIBRARY>.

Save File Names

All references to the version-specific numbers in save file names are generalizedin this book as TIBEMSvrm, where vrm refers to the version, release andmodification that make up the current release of the product.

For example, the save file for software release 8.2.0 of this product is namedTIBEMS820.

If no previous installations of TIBCO EMS Client for IBM i are present on thesystem, you can follow one path of the RSTLICPGM command. See the instructionsfor Single Installation below.

If a previous installation of TIBCO EMS Client for IBM i exists on the targetsystem, you must be careful on which parameters you specify on the RSTLICPGM.See the instructions for Multiple Installations below.



Multiple Installations

Perform the following steps to install the TIBCO EMS Client for IBM i software.All objects reside within *SAVF TIBEMSvrm.

1. Sign-on as QSECOFR, or a different user profile with similar authority.

2. If you are installing this release along side previous installations, perform thefollowing command:

RSTLICPGM LICPGM(4TIBEM1) DEV(*SAVF) RLS(VvRrMm)REPLACERLS(*NO) SAVF(<TARGET_LIBRARY>/TIBEMSvrm) LIB(yourlib)

This command restores the product in library yourlib, as well as a number ofstream files into the /root file system of the IFS in EMI_HOME.

Parameters:

— LICPGM(4TIBEM1) – specifies the seven-character identifier of the licensedprogram that is restored.

— DEV(*SAVF) – the device name where the product resides; in this case, thedevice is a *SAVF whose name is specified in the SAVF parameter.

— SAVF(<TARGET_LIBRARY>/TIBEMSvrm) – *SAVF TIBEMSvrm resides inlibrary <TARGET_LIBRARY>.

— RLS(VvRrMm) – specifies the version, release, and modification level of thelicensed program being restored. VvRrMm refers to the release level where vis the version number, r is the release number, and m is the modificationlevel. For example, for release 8.2.0, VvRrMm would be V8R2M0.

— REPLACERLS(*NO) – specifies the version, release, and modification level ofthe licensed program being replaced. *NO indicates that the licensedprogram currently installed on the system should not be replaced if therelease version is the same. The licensed program being restored must be adifferent release than the one currently installed. If the licensed programbeing restored exists in the same library as the installed program, anoverride parameter must be specified indicating to which library thelicensed program is restored.

— LIB – specifies the library into which the licensed program is beingrestored.


Installing the Software | 17

Dynamic NamingTIBCO EMS Client for IBM i is enabled for Dynamic Naming. This allows the enduser to install the product into a unique user-chosen product library name.

To install TIBCO EMS Client for IBM i using an alternate product library name,specify the LIB parameter in the RSTLICPGM command. For example:

RSTLICPGM LICPGM(4TIBEM1) DEV(*SAVF) SAVF(savflib/TIBEMSvrm)LIB(yourlib)

where savflib is a library name where the product save file was downloaded.

The above command installs the EMS Client into library yourlib instead of thedefault product library (which is TIBEMSLIB).

LIB(yourlib) is optional, and if excluded the product is installed in the libraryTIBEMSLIB.



Compiling the Sample Programs

The source code for the TIBCO EMS Client for IBM i sample programs is includedas part of the installation. In the instructions that follow:

• prodlib is the product library name used in the Restore Licensed Program(RSTLICPGM) command when TIBCO EMS Client for IBM i is installed. Bydefault this name is TIBEMSLIB. This applies to the name when used as alibrary name, for example TIBEMSLIB/LIBTIBEMS.

C Sample ProgramsC sample programs are provided in directory:

EMI_HOME/samples/c,

To compile the sample programs, follow these steps:

1. Start the QShell shell interpreter:QSH

2. Change to the samples directory:cd EMI_HOME/samples/c

3. Run the gmake utilitygmake -f makefile

The makefile in EMI_HOME/samples/c creates the C sample programs usingthe following default settings:

— The object modules and program objects are created in the library QGPL.

— The EMS Client binds the C samples with the service program that issearched from the TIBEMSLIB library.

— The target release of the resulting program object is *CURRENT.

To change any of these default settings, specify the following externalvariables for the makefile on the qshell command line:

— COMPILELIB to change where the object modules and program objects arecreated.

— CLIENTLIB to change where the LIBTIBEMS service program resides.

— TGTRLS to change the target release of the resulting program.

For example:gmake -f makefile CLIENTLIB=MYEMSLIB COMPILELIB=MYDEVLIBTGTRLS=V6R1M0


Compiling the Sample Programs | 19

The sample programs will be created in the library specified by COMPILELIB in themakefile. Symbolic links are also created in the EMI_HOME/samples/c directory.Both short names and long names symbolic links are created.

To delete all results of the compilation, *MODULE, *PGM and *SYMLNK, run thefollowing form of gmake:

gmake -f makefile clean COMPILELIB=MYEMSLIB

For additional details on compiling sample programs, see Compile and Bind onpage 36.

COBOL Sample ProgramsCompile the COBOL sample programs:

ADDLIBLE TIBEMSLIB

CRTCBLMOD MODULE(mylib/SXJCMP) SRCFILE(TIBEMSLIB/QCBLLESRC)OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

CRTCBLMOD MODULE(mylib/SXJCMC) SRCFILE(TIBEMSLIB/QCBLLESRC)OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

CRTPGM PGM(mylib/SXJCMP) MODULE(mylib/SXJCMP TIBEMSLIB/SXJ3SIN)BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

CRTPGM PGM(mylib/SXJCMC) MODULE(mylib/SXJCMC TIBEMSLIB/SXJ3SINTIBEMSLIB/MF@COBOL) BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

where mylib is a library name of your choice, and the product library name isTIBEMSLIB.

You must specify the same COMPILELIB that was specified before.



ILE RPG Sample ProgramsThe RPG samples are all provided pre-compiled and ready to run in your productlibrary, or you can compile them yourself. You can compile the samples in one ofthese ways:

• From QRPGLESRC— ADDLIBLE TIBEMSLIB

— CRTRPGMOD MODULE(yourlib/SXJRMP) SRCFILE(TIBEMSLIB/QRPGLESRC)

— CRTPGM PGM(yourlib/SXJRMP) MODULE(*PGM) ENTMOD(*PGM)BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

• From IFS— CRTRPGMOD MODULE(yourlib/SXJRMP)

SRCSTMF('EMI_HOME/samples/rpg/sxjrmp.rpgle')

— CRTPGM PGM(yourlib/SXJRMP) MODULE(*PGM) ENTMOD(*PGM)BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

where yourlib is a library name of your choice and the product library name isTIBEMSLIB.


Verifying the Installation | 21

Verifying the Installation

To verify that the TIBCO EMS Client for IBM i components have been correctlyinstalled and configured, perform the procedures listed below. These proceduresuse the sample programs created in Compiling the Sample Programs on page 18to publish and receive a message. For information on sample programs, seeTIBCO EMS Messaging Samples on page 42.

Before performing the procedure, ensure that the TIBCO EMS server is runningon port 7222 on server url-id1 (where url-id1 is the hostname where yourTIBCO EMS server is running).

Verification From QSHELL

Perform the following:

1. Start QSHELL:QSH


3. Run the tibemsMsgConsumer sample program (SXJ3MC):SXJ3MC -server tcp://url-id1:7222 -topic TEST1

ortibemsMsgConsumer -server tcp://url-id1:7222 -topic TEST1

4. From another QSHELL command entry screen, run the tibemsMsgProducersample program (SXJ3MP) with a message parameter:

SXJ3MP -server tcp://url-id1:7222 -topic TEST1 'Hello World'

ortibemsMsgProducer -server tcp://url-id1:7222 -topic TEST1'Hello World'

Note the message displays on the first QSHELL command entry screen.

5. This step is optional. If you have another EMS client on Windows, run thetibemsMsgProducer sample program as follows:

cd <directory-where-Windows-client-binary-resides>

tibemsMsgProducer -server tcp://url-id1:7222 -topic TEST1'From Windows'

Note the message displays on the first QSHELL command entry screen.

6. Press PF3 to end the two QSHELL sessions.



Verification From the Command Entry Screen in Batch

For additional details on running programs from the command entry screen, seeRunning Applications and C Sample Programs on page 28.

To verify your installation, perform the following:

1. Run the tibemsMsgConsumer sample program (SXJ3MC) as follows:SBMJOB CMD(CALL PGM(mylib/SXJ3MC) PARM('-server''tcp://url-id1:7222' '-topic' TEST1)) ALWMLTTHD(*YES)

where mylib is the library name that was used when you performed gmake -f

makefile. This name is the name used for external variable COMPILELIB, ifused. If COMPILELIB was not used, then the default QGPL.

Note the job number submitted, for example, 403517/USER1/USER1.

2. Run the tibemsMsgProducer sample program (SXJ3MP) with a messageparameter:

SBMJOB CMD(CALL PGM(mylib/SXJ3MP) PARM('-server''tcp://url-id1:7222' '-topic' TEST1 'Hello World'))ALWMLTTHD(*YES)

3. Run the tibemsMsgProducer program again with a different messageparameter:

SBMJOB CMD(CALL PGM(mylib/SXJ3MP) PARM('-server''tcp://url-id1:7222' '-topic' TEST1 'A World Apart'))ALWMLTTHD(*YES)

4. This step is optional. If you have another EMS client on Windows, run thetibemsMsgProducer sample program as follows:

cd <directory-where-Windows-client-binary-resides>tibemsMsgProducer -server tcp://url-id1:7222 -topic TEST1"From Windows"

5. Execute the ENDJOB command with the IMMED option:ENDJOB JOB(403517/USER1/USER1) OPTION(*IMMED)

6. Execute the DSPJOB command:DSPJOB 403517/USER1/USER1

7. Select option 4 to display the job’s spooled files.

8. Select option 5 next to file QPRINT. The contents of the printer file will containthe following:

------------------------------------------------------------------tibemsMsgConsumer SAMPLE------------------------------------------------------------------Server....................... tcp://url-id1:7222User......................... (null)Destination.................. TEST1------------------------------------------------------------------


Verifying the Installation | 23

Subscribing to destination: 'TEST1'Received TEXT message: Hello WorldReceived TEXT message: A World ApartReceived TEXT message: From Windows



Verifying SSL

You may optionally use the procedures listed below to verify that SSL connectionsto a TIBCO EMS server are configured correctly. These procedures use the samesample programs that were used in Verifying the Installation on page 21. Theprocedures also use the sample certificates provided with the TIBCO EMS Clientfor IBM i.

Importing Sample Certificates using the Digital Certificate ManagerThe following procedures may be used to import the server_root.cert.pemand client_root.cert.pem sample CA certificate files, and theclient_identity.p12 sample PKCS12 file. See the TIBCO Enterprise MessageService User’s Guide to learn more about these files.

These files to be imported are in the EMI_HOME/sample/certs directory. Thecertificates in these files are specific to IBM i, so they may be imported by theDCM. They are not compatible with the sample certificates shipped with EMS forother non-IBM i platforms.

In general, importing the CA certificate from the server_root.cert.pem fileallows the EMS Client for IBM i to authenticate the server certificate from theTIBCO EMS server during the SSL handshake. You must import from theclient_root.cert.pem file before importing from the client_identity.p12file so the DCM can authenticate the client certificate that the TIBCO EMS Clientfor IBM i will send to the EMS server during the SSL handshake.

1. Use a web browser to connect to the *ADMIN instance of the IBM HTTPServer and navigate to the Digital Certificate Manger as documented in IBMSystem i Security Digital Certificate Manager, Configuring DCM, StartingDigital Certificate Manager.

2. Within the Digital Certificate Manager, click Select a Certificate Store.

3. Select the *SYSTEM certificate store and click Continue.

4. On the page that opens, enter the password for the *SYSTEM certificate storeand click Continue.

5. In the left-hand navigation pane, click on Fast Path and then click on Workwith CA certificates. The page that opens lists CA certificates and their status.

6. Click Import.


Verifying SSL | 25

7. Use the Import Certificate Authority (CA) Certificate pages to:

a. Import the EMI_HOME/sample/certs/server_root.cert.pem file.

b. Assign this label to the certificate:TIB_EMS_IBMI_SAMPLE_SERVER_ROOT_001.

8. Use the Import Certificate Authority (CA) Certificate pages to:

a. Import the EMI_HOME/sample/certs/client_root.cert.pem file.

b. Assign this label to the certificate:TIB_EMS_IBMI_SAMPLE_CLIENT_ROOT_001.

9. In the left-hand navigation pane, click on Fast Path and then click on Workwith server and client certificates. The page that opens lists sever and clientcertificates and their common name.

10. Click Import.

11. Use the Import Server or Client Certificate pages to:

a. Import the EMI_HOME/sample/certs/client_identity.p12 file.

b. Specify the encryption password for the file is password.

c. Assign this label to the certificate: TIB_EMS_IBMI_SAMPLE_CLIENT_001.

Configuring the EMS Server for SSLThe samples in the EMI_HOME/sample/certs directory on IBM i must betransferred to the machine on which the EMS Server is running. It isrecommended that you create a new directory of your choice that will hold onlythe sample certificates transferred from IBM i. The procedures that follow refer tothis directory on the TIBCO EMS server as EMI_CERTS.

Details on how to configure the EMS Server for SSL may be found in TIBCOEnterprise Message Service User’s Guide. In general, the following procedures maybe used when modifying the tibemsd.conf configuration file.

1. Add a listen parameter to the EMS server configuration file to specify a porton which to listen for SSL connections:listen = ssl://url-id1:7243

2. Configure the EMS server to use the server certificate that can beauthenticated by IBM i:ssl_server_identity = EMI_CERTS/server.cert.pem

3. Configure the private key and password for the EMS server:ssl_server_key = EMI_CERTS/server.key.pemssl_password = password



4. Configure the EMS server to trust the client certificate that is sent from IBM i:ssl_server_trusted = EMI_CERTS/client_root.cert.pem

Once configured for SSL, start the EMS server and verify that the server is activeand listening on the secure socket port.

Sample Invocations from the QSHELL to Verify SSLThe following tibemsMsgConsumer and tibemsMsgProducer sample programinvocations use SSL connections to the TIBCO EMS server, and if successful verifya correct configuration:

1. From a QSHELL command entry screen, run the tibemsMsgConsumer sampleprogram:tibemsMsgConsumer -server ssl://url-id1:7243 -topic TEST1-ssl_ring '*SYSTEM' -ssl_label TIB_EMS_IBMI_SAMPLE_CLIENT_001-ssl_trace -ssl_noverifyhostname

2. From another QSHELL command entry screen, run the tibemsMsgProducersample program with a message parameter:tibemsMsgProducer -server ssl://url-id1:7243 -topic TEST1-ssl_ring '*SYSTEM' -ssl_label TIB_EMS_IBMI_SAMPLE_CLIENT_001-ssl_trace -ssl_noverifyhostname 'Hello World'

3. Press PF3 to end the two QSHELL sessions.


| 27

Chapter 3 Running and Developing Applications

This chapter describes how to submit and execute your applications utilizing theTIBCO EMS Client for IBM i. It also provides a checklist for C, RPG, and COBOLlanguage application programmers for IBM i.

Before performing these tasks, you must have completed the installation of theTIBCO EMS Client for IBM i software, and performed the Installation VerificationProgram (IVP) steps as described in Compiling the Sample Programs on page 18.

Topics.

• Running Applications and C Sample Programs, page 28

• Running Applications and RPG Sample Programs, page 30

• Running Applications and COBOL Sample Programs, page 33

• Programmer's Checklist for C Samples, page 36

• Programmer's Checklist for RPG Samples, page 38

• Programmer's Checklist for COBOL Samples, page 39


28 | Chapter 3 Running and Developing Applications

Running Applications and C Sample Programs

This section explains alternate methods for running your applications or the Csample programs provided with the product.

TIBCO EMS Client for IBM i program parameters that begin with the dashcharacter are case sensitive (for example, -server). Be sure to observe casesensitivity when editing any files that may require lower case parameters. On theCommand Entry Screen, any parameters that are not quoted will be folded toupper case.

Running Applications From the Command Entry ScreenThe following command submits the tibemsMsgProducer sample program(SXJ3MP) in library <mylib> to batch with multiple user threads enabled:

SBMJOB CMD(CALL PGM(<mylib>/SXJ3MP)PARM('-server' 'tcp://url-id1:7222''-topic' TEST1 'Hello World'))ALWMLTTHD(*YES)

The parameters passed to program SXJ3MP include the following name-valuepairs:• -server tcp://url-id1:7222

• -topic TEST1

The first pair specifies the TCP address of the TIBCO EMS server. The second pairspecifies the topic to which messages are published. The final parameter specifiesthe message text published on the topic.

SXJ3MP is compiled from sample source file tibemsMsgProducer.c. For details,see TIBCO EMS Messaging Samples on page 42.

Any application program that uses TIBCO EMS API calls must have the correctcase when specifying the API name.


Running Applications and C Sample Programs | 29

Running Applications From the QSHELL Command Entry ScreenQSHELL provides an interactive display with a multi-threaded environment. ThetibemsMsgProducer sample program (SXJ3MP) is easily invoked using a symboliclink:

cd EMI_HOME/samples/c

followed by one of the following forms:SXJ3MP -server tcp://url-id1:7222 -topic TEST1 'Hello World'

or

tibemsMsgProducer -server tcp://url-id1:7222 -topic TEST1'Hello World'

The tibemsMsgProducer sample program can also be invoked from the QSYS filesystem:

/QSYS.LIB/<mylib>.LIB/SXJ3MP.PGM-server tcp://url-id1:7222-topic TEST1 'Hello World'

The tibemsMsgProducer sample program can also be invoked native style usingthe system() function:

system "CALL PGM(<mylib>/SXJ3MP)PARM('-server' 'tcp://url-id1:7222''-topic' TEST1 'Hello World')"



Running Applications and RPG Sample Programs

The ILE RPG sample programs are multi-threaded applications, and must be runfrom subsystems that are enabled for multi-threading.

You can execute these jobs with the following command examples:

Executing fromQSHELL

• From QSHELL environment:system "CALL PGM(yourlib/SXJRMP) PARM('-server' 'server:port''-topic' 'my-topic' 'message')"

Submitting toBatch

• From batch:SBMJOB CMD(CALL PGM(yourlib/SXJRMP) PARM('-server' 'server:port''-topic' 'my-topic' 'message')) LOG(4 0 *SECLVL) ALWMLTTHD(*YES)

where

• yourlib is a library name of your choice.

• server:port is the name of the server and port where EMS is configured andrunning. For example, tcp://glatona-dt:7222.

• my-topic is the name of the topic (or queue) you wish to use. This name mustmatch the topic (or queue) name in the consumer and producer.

• message is the message to send. The current RPG sample programs do not allowembedded blanks.

For example, this command executes the sample job from batch:

SBMJOB CMD(CALL PGM(TIBEMSLIB/SXJRMP) PARM('-server''tcp://glatona-dt:7222' '-topic' 'my-topic1' 'testMessage'))LOG(4 0 *SECLVL) ALWMLTTHD(*YES)

The RPG samples are logging their output to printer file QSYSPRT. A secondprinter file, QPRINT, is created with output from the C API, tibemsMsg_Print().

When executing the samples in batch, the printer files are spooled to your outputqueue. When executing the samples interactively for QSHELL, the printer filesdisplay to your screen if the application ends correctly and the files are closedproperly. Otherwise, the printer files are spooled.

QSHELL

You must set the following environment variable in order to enablemulti-threaded jobs in QSHELL:

ADDENVVAR ENVVAR(QIBM_MULTI_THREADED) VALUE(Y) LEVEL(*SYS)


Running Applications and RPG Sample Programs | 31

Note that the *SYS environment variable may also be set at the *JOB level.

These additional examples show how to invoke the RPG samples for QSHELL:1. system "CALL PGM(TIBEMSLIB/SXJRMP) PARM('-server' 'server:port'

'-destination' 'my-dest' 'message')"

2. system "CALL PGM(TIBEMSLIB/SXJRMC) PARM('-server' 'server:port''-destination' 'my-dest' )"

3. system "CALL PGM(TIBEMSLIB/SXJRAMC) PARM('-server' 'server:port''-destination' 'my-dest' )"

where

• server:port is the name of the server and port where EMS is configured andrunning. For example, tcp://glatona-dt:7222.

• destination is either -queue or -topic. The destination must be the same forboth consumer and producer.

• my-dest is the name of the topic or queue you wish to use. This name mustmatch the topic or queue name in the consumer and producer.

• message is the message to send. The current RPG samples programs do notallow embedded blanks.

Data Conversion Plug-in SampleAn RPG sample and corresponding include file have been provided along withmatching TIBCO Active Matrix Business Works project that will show how theRPG sample on IBM i can participate in the interchange of data of any formbetween multiple platforms.

Source Location

The source for the sample exists both in the TIBCO EMS Client for IBM i productlibrary and in the Integrated File System (IFS), and is also provided pre-compiledin the product library.

EMI_HOME/samples/dcp/rpg/EMSRDCP1.rpgle

The TIBCO Active Matrix Business Works example is provided in a zip file in:

EMI_HOME/samples/dcp/am_bw/AM_BW_Mainframe_Sample_Project.zip.

Running the Sample

To execute this application:

1. Transfer the AM_BW_Mainframe_Sample_Project.zip file from IBM i to themachine where you are running TIBCO Designer.



2. Unzip the file.

3. Open the project in TIBCO Designer.

4. Change the Global variable JmsProviderUrl to the name of the server whereyour EMS server is configured and running. For example,tcp://glatona-dt:7222.

5. From your Tester tab, select and load the Receive-Send RPG Bytes messagefrom the Process Examples.

This places the project in receive mode.

6. Switch to the IBM i, and execute the following command:QSH CMD('system "CALL PGM(TIBEMSLIB/EMSRDCP1) PARM(''server:port'')"')

where server:port is the name of the server and port where EMS is configuredand running, as specified in step 4. For example:QSH CMD('system "CALL PGM(TIBEMSLIB/EMSRDCP1)PARM(''tcp://glatona-dt:7222'')"')

This program sends a bytes message made up of various data types and contentto the BusinessWorks project and waits for a response with modified data fromBusinessWorks.


Running Applications and COBOL Sample Programs | 33

Running Applications and COBOL Sample Programs

This section explains methods for running your applications or the COBOLsample programs provided with the product. The COBOL sample sources aredelivered in the IFS and in QCBLLESRC.

The Integrated File System (IFS) directory is:

EMI_HOME/samples/cobol

These COBOL programs have been written simply by writing their output usingthe DISPLAY statement to the *EXT queue which in effect is writing to the job log.This implies that to see this information for batch jobs one must have access to thejob log.

For samples that are executed from QSHELL, one will only see the output of theDISPLAY at job end. If the job is written as a never ending job, such as theconsumer samples, one will not see the output of the DISPLAY until the job ends.

Executing the EMS COBOL Sample Programs from QSHELLTo execute the message producer, SXJCMP (corresponds to tibemsMsgProducer),in QSHELL and send messages, follow the steps shown below from a 5250display monitor (each line is entered separately).

qsh <= from Command Entry screen> /qsys.lib/<mylib>.lib/sxjcmp.pgm <= one way of running producer> server tcp://url-id1:7222 <= enter your EMS server and port> queue testq <= enter your destination queue or topic> text This is my first message <= enter messages> text This is my second message <= these get queued up by the COBOL pgm> text This is my third message> <= ENTER ends the input process

The producer has sent the messages at this point.

To execute the message consumer, SXJCMC (corresponds totibemsMsgConsumer), in QSHELL and receive messages, follow the steps shownbelow from a second 5250 display monitor.

qsh <= from Command Entry screen> system "call <mylib>/sxjcmc" <= another way to run consumer> server tcp://url-id1:7222 <= enter your EMS server and port> queue testq <= enter your destination queue or topic> <= ENTER ends the input process



To send more messages, return to your first monitor and input the following:

> /qsys.lib/<mylib>.lib/sxjcmp.pgm> server tcp://url-id1:7222> queue testq> text new message>$

Submitting to BatchIf submitting these programs to batch, your input data is provided by way of theQINLINE file. Make sure the QINLINE file is found in the job’s *LIBL. Anexample is provided in TIBEMSLIB.

Edit the file TIBEMSLIB/QINLINE(QINLINE) to update the server and queueinformation before submitting the programs in batch.

EDTF FILE(TIBEMSLIB/QINLINE)

A sample QINLINE file may contain the following:

server tcp://url-id1:7222 <= enter your EMS server and portqueue testq <= enter your queue nametext This is my message <= this line is optional for Consumer

and is ignored if present* <= denotes end of input

Both Consumer and Producer can be submitted to batch or a combination of batchand QSHELL can be used. For example, execute the EMS COBOL sampleSXJCMC from QSHELL as before:

qsh <= from Command Entry screen> system "call <mylib>/sxjcmc" <= another way to run consumer> server tcp://url-id1:7222 <= enter your EMS server and port> queue testq <= enter your destination queue or topic> <= ENTER ends the input process

Submit the Producer to batch:SBMJOB CMD(CALL PGM(<mylib>/SXJCMP)) INLLIBL(<mylib> TIBEMSLIBQGPL) ALWMLTTHD(*YES)

The Consumer can be submitted to batch with the following command.SBMJOB CMD(CALL PGM(<mylib>/SXJCMC)) INLLIBL(<mylib> TIBEMSLIBQGPL) ALWMLTTHD(*YES)


Binding Your Application to the Correct Version of the EMS Client | 35

Binding Your Application to the Correct Version of the EMS Client

If you have multiple versions of the EMS Client installed, you must be aware ofwhich version of the EMS Client you bind and/or run your application with. Ifyou have two different versions of the EMS client installed, you can either bindyour application statically to one specific service program, or you candynamically bind the service program and control which version of the EMSClient is used at runtime.

For example, suppose you have two different versions of TIBCO EMS Client forIBM i installed:

• Software Release 7.0.0 in product library TIBEMS700

• Software Release 8.2.0 in product library TIBEMS820

Bind Statically

Bind the application statically to one specific service program. For example, bindto software release 8.2.0:

CRTPGM PGM(yourlib/SXJ3MP) MODULE(yourlib/SXJ3MP yourlib/SXJ3UTIL)BNDSRVPGM((TIBEMS820/LIBTIBEMS))

where yourlib is your application library.

Bind Dynamically

To bind the application dynamically, add one of the product libraries to the librarylist, then bind the program. This allows you to control which version of the EMSClient is used by modifying the library list.

For example:

ADDLIBLE TIBEMS820CRTPGM PGM(yourlib/SXJ3MP) MODULE(yourlib/SXJ3MP yourlib/SXJ3UTIL)BNDSRVPGM((*LIBL/LIBTIBEMS))

where yourlib is your application library.

To determine how your application has been bound, execute the followingexample to see in which library service program LIBTIBEMS is found:

DSPPGM PGM(yourlib/SXJRMC) DETAIL(*SRVPGM)



Programmer's Checklist for C Samples

A checklist for C language application programmers in i is provided below.

CodeWhen developing your applications you will need the client header files thatreside in the EMI_HOME/include directory. Sample program header files residein EMI_HOME/samples/c directory.

Compile and BindStandard ILE C Compiler commands are used:

• CRTCMOD – Create C Module

• CRTPGM – Create Program

The C samples can be compiled using native compiler commands or usingmakefile. Examples of both are provided below.

Compiling a Single Sample Program Using Native Compiler Commands

Note that SXJ3UTIL contains helper functions used by the other samples tohandle common activities. This should be compiled ahead of the other samplesand bound together with them:

CRTCMOD MODULE(yourlib/SXJ3UTIL)SRCSTMF('EMI_HOME/samples/c/tibemsUtilities.c') ENUM(4)INCDIR('EMI_HOME/include' 'EMI_HOME/samples/c')

Example using CRTCMOD:CRTCMOD MODULE(yourlib/SXJ3MP)SRCSTMF('EMI_HOME/samples/c/tibemsMsgProducer.c') ENUM(4)INCDIR('EMI_HOME/include')

where yourlib is the name of one of your development libraries.

Example using CRTPGM:CRTPGM PGM(yourlib/SXJ3MP) MODULE(yourlib/SXJ3MP yourlib/SXJ3UTIL)BNDSRVPGM((prodlib/LIBTIBEMS))

Compiling All Sample Programs Using Makefile

This procedure was performed to verify the installation of the product. Fordetails, see Compiling the Sample Programs on page 18.


Programmer's Checklist for C Samples | 37

Compiling a Single Sample Program Using Makefile

1. Start the QSHELL shell interpreter:QSH


3. Run the gmake utility and specify the individual sample program name inupper case (see the Sample Programs on page 41 for a list of program names):

gmake -f makefile <individual_sample_program_name>

To remove all *PGM and *MODULE objects, as well as all *SYMLNK related to thesample program, perform the following:

cd EMI_HOME/samples/c

gmake -f makefile clean COMPILELIB=MYDEVLIB

where COMPILELIB is the same library specified previously.

The makefile in EMI_HOME/samples/c creates the C sample programs using thefollowing default settings:

• The object modules and program objects are created in the library QGPL.

• The EMS Client binds the C samples with the service program that is searchedfrom the TIBEMSLIB library.

• The target release of the resulting program object is *CURRENT.

To change any of these default settings, specify the following external variablesfor the makefile on the qshell command line:

• COMPILELIB to change where the object modules and program objects arecreated.

• CLIENTLIB to change where the LIBTIBEMS service program resides.

• TGTRLS to change the target release of the resulting program.

For example:gmake -f makefile SXJ3MC CLIENTLIB=LEMS820DEV COMPILELIB=MYDEVLIBTGTRLS=V6R1M0

A set of helper functions for the C samples is provided in SXJ3UTIL ortibemsUtilities.c.



Programmer's Checklist for RPG Samples

CodeThe RPG sample source has been provided in both source physical fileTIBEMSLIB/QRPGLESRC, and in IFS directory:

EMI_HOME/samples/rpg

Compile and Bind• CRTRPGMOD – Create RPG module


Example of CRTRPGMOD:

ADDLIBLE TIBEMSLIBCRTRPGMOD MODULE(<mylib>/SXJRMP) SRCFILE(TIBEMSLIB/QRPGLESRC)

Example of CRTPGM:

CRTPGM PGM(<mylib>/SXJRMP) MODULE(*PGM) ENTMOD(*PGM)BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)


Programmer's Checklist for COBOL Samples | 39

Programmer's Checklist for COBOL Samples

CodeCOBOL samples SXJCMC and SXJCMP and their COBOL copybooks areprovided in source physical file QCBLLESRC in library TIBEMSLIB.

Compile and Bind• CRTCBLMOD – Create COBOL module


Example of CRTCBLMOD:

ADDLIBLE TIBEMSLIBCRTCBLMOD MODULE(<mylib>/SXJCMC) SRCFILE(TIBEMSLIB/QCBLLESRC)OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

Example of CRTPGM:

CRTPGM PGM(<mylib>/SXJCMC)MODULE(<mylib>/SXJCMC TIBEMSLIB/SXJ3SIN TIBEMSLIB/MF@COBOL)BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

Modules SXJ3SIN and MF@COBOL have been compiled and provided to you inTIBEMSLIB.


| 41

Appendix A Sample Programs

This appendix describes the sample programs included with the TIBCO EMSClient for IBM i.

Topics

• TIBCO EMS Messaging Samples, page 42

• Source Code, page 45


42 | Appendix A Sample Programs

TIBCO EMS Messaging Samples

C Sample ProgramsThis section describes the C sample programs for TIBCO EMS messaging. For allprograms, C functions use non-typed connections and sessions. Under QSHELL,symbolic links are added by the makefile for each sample program.

Type of EMS Sample IFS SourceFilename

NativeProgram andModule Name

Program Name UnderQSHELL

Asynchronous MessageConsumer

tibemsAsyncMsgConsumer.c

SXJ3AMC tibemsAsyncMsgConsumerSXJ3AMC

Queue Browser tibemsBrowser.c SXJ3BR tibemsBrowserSXJ3BR

Durable Topic Subscriber tibemsDurable.c SXJ3DTSB tibemsDurableSXJ3DTSB

Message Consumer tibemsMsgConsumer.c

SXJ3MC tibemsMsgConsumerSXJ3MC

Like SXJ3MC (above), butuses thetibemsXAResourceinterface to consumemessages using transactionsemantics.

tibemsXAMsgConsumer.c

SXJ3XAMC tibemsXAMsgConsumerSXJ3XAMC

Message Producer tibemsMsgProducer.c

SXJ3MP tibemsMsgProducerSXJ3MP

Like SXJ3MP (above), butuses the classic X/OpenDPT XA interface to sendmessages using transactionsemantics.

tibemsXAMsgProducer.c

SXJ3XAMP tibemsXAMsgProducerSXJ3XAMP

Message Consumerdemonstrating how toenumerate messageproperties and fields

tibemsMsg.c SXJ3MSG tibemsMsgSXJ3MSG


TIBCO EMS Messaging Samples | 43

RPG Sample ProgramsThis section describes the IBM RPG sample programs for TIBCO EMS messaging.The resulting programs are multi-threaded applications, and must be run onsubsystems that are enabled for multi-threading. For example, subsystem QINTER

is not enabled for multi-threading.

Helper functions used byother samples to handlecommon activities

tibemsUtilities.c SXJ3UTIL tibemsUtilitiesSXJ3UTIL

tibemsMsgProducerPerf tibemsMsgProducerPerf.c

SXJ3MPPF tibemsMsgProducerPerfSXJ3MPPF

tibemsMsgConsumerPerf tibemsMsgConsumerPerf.c

SXJ3MCPF tibemsMsgConsumerPerfSXJ3MCPF

Type of EMS Sample IFS SourceFilename

NativeProgram andModule Name

Program Name UnderQSHELL

Type of EMS SampleRPG SourceFilename and ShortName

Description

AsynchronousMessage Consumer

tibemsAsyncMsgConsumer

SXJRAMC

An example demonstrating the use of anasynchronous message consumer, using Cfunctions, operating on non-typed connectionsand sessions. This sample registers a listener onthe specified topic or queue, and prints allmessages asynchronously received on thatdestination. The destination (specified as aparameter) must exist in the topics or queuesconfiguration files, or the configuration filesshould allow dynamic creation of thatdestination. The sample configuration distributedwith TIBCO Enterprise Message Service allowsfor the creation of all topics and queues.

Queue Browser tibemsBrowser

SXJRBR

A simple example demonstrating the use of thequeue browsers, using C functions, operating onnon-typed connections and sessions.



Durable TopicSubscriber

tibemsDurable

SXJRDTSB

A simple durable topic subscriber. If started with-unsubscribe parameter, it unsubscribes thespecified durable subscriber, and exits.Otherwise, it creates a durable subscriber on thespecified topic, and receives and prints allmessages published to that topic.

Message Consumer tibemsMsgConsumer

SXJRMC

An example demonstrating use of the messageconsumer, using C functions, operating onnon-typed connections and sessions. This samplesynchronously consumes and prints all messagesreceived on the specified topic or queue. Thedestination (specified as a parameter) must existin the topics or queues configuration files, or theconfiguration files should allow dynamic creationof that destination. Sample configurationdistributed with TIBCO Enterprise MessageService allows creation of all topics and queues.

Message Producer tibemsMsgProducer

SXJRMP

An example demonstrating use of the messageproducer, using C functions, operating onnon-typed connections and sessions. This samplesends one or more text messages to the specifiedtopic or queue. The topic or queue (specified as aparameter) must exist in the topics or queuesconfiguration files, or the configuration filesshould allow dynamic creation of thatdestination. The sample configuration distributedwith TIBCO Enterprise Message Service allowscreation of all topics and queues.

Type of EMS SampleRPG SourceFilename and ShortName

Description


Source Code | 45

Source Code

The source code for the sample programs can be used for following purposes:

• To verify the installation.

• To show examples of how select APIs can be implemented in C, RPG, andCOBOL.

• To provide base code that can be adapted to customer applications.

The sample code sources are stored in the following locations:

C sample source code EMI_HOME/samples/c

C client header files EMI_HOME/include/tibems

RPG sample source code EMI_HOME/samples/rpg

and TIBEMSLIB/QRPGLESRC

COBOL sample source andcopybooks

EMI_HOME/samples/cobol

and TIBEMSLIB/QCBLLESRC

Data Conversion Plug-in samplesource code

EMI_HOME/samples/dcp/rpg

and TIBEMSLIB/QRPGLESRC


| 47

Appendix B EMS Client Programming in RPG

Coding your own applications in RPG requires that you extend the prototype fileto include all the TIBCO Enterprise Message Service calls that your applicationuses. Use the information in this section as a guide when you extend theprototype file, and when you code EMS Client programs in RPG.

Parameter passing protocol in C differs from the parameter passing protocol inRPG. By default RPG passes parameters by reference, unless you explicitly codeto pass by value. In contrast, C passes parameters by value (though you canexplicitly supply a pointer referencing a location).

The following table guides the translation from C to RPG. Each section of the tableaddresses a specific type of parameter passing in C, followed by the equivalentconstructs in RPG.

When C Passes a Non-String by Value

C Prototype foo(int order)

C Program Call int order;foo(order);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5d foo prd order 10i 0 value

RPG Program Call ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5D order S 10i 0 inz(37)C callp foo(order)

When C Passes a Non-String by Reference

C Prototype foo(int* order)

C Program Call int order;foo(&order);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5d foo prd order 10i 0

RPG Program Call ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5D order S 10i 0 inz(37)C callp foo(order)


48 | Appendix B EMS Client Programming in RPG

When C Passes a String by Value

C Prototype foo(char* desc)

C Program Call char* desc;foo(desc);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5d foo prd desc * value

RPG Program Call ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5D desc S 11A/free

desc = 'TIBRVLISTE' + X'00';foo(%addr(desc));

/end-free

When C Passes a String by Reference

C Prototype foo(char** desc)

C Program Call char* desc;foo(&desc);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5d foo prd desc *

RPG Program Call ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5D desc S 11AD pDesc S * inz(%addr(desc))/free

desc = 'TIBRVLISTE' + X'00';foo(pDesc);

/end-free


| 49

Appendix C Installed Objects

This appendix lists the objects that are installed with TIBCO EMS Client for IBM i.

Object Description

LIBTIBEMS *SRVPGM containing all exported EMS APIs for EMSapplications to bind to.

ZLIB *SRVPGM containing compression utilities used byLIBTIBEMS.

CRYPTO *SRVPGM containing OpenSSL Crypto component.

QCBLLESRC Source physical file containing sample COBOL sourceand copybooks.

QRPGLESRC Source physical file containing sample RPG sourceand include files.

MF@COBOLSXJ3SIN

Utility modules for binding into COBOL sampleprograms.

TIBIFSSAV *SAVF containing all *IFS stream files that are installedwith EMS client.

SXJRAMCSXJRBRSXJRDTSBSXJRMCSXJRMP

Precompiled RPG sample programs.

EMSRDCP1 Precompiled RPG sample program for DataConversion Plug-in.

QINLINE Sample input file for COBOL batch samples.

Additional objects required for restoring and deleting the client product.

EMSSYMLNKS *PGM used by RSTLICPGM and DLTLICPGM forhandling directory path EMI_HOME/...


50 | Appendix C Installed Objects

Objects in the /root file system

EMI_HOME/include/tibems — All C header files for application development

EMI_HOME/samples/c — C sample files and one header file

EMI_HOME/samples/cobol — COBOL source and copybooks for COBOLapplication development

EMI_HOME/samples/rpg — RPG source and includes for RPG applicationdevelopment

EMI_HOME/samples/dcp/rpg — RPG source and include file for DataConversion Plug-in sample

EMI_HOME/samples/dcp/am_bw — TIBCO Active Matrix Business Worksexample for running with the RPG Data Conversion Plug-in sample

EMI_HOME/samples/certs — Sample digital certificates that are compatiblewith the Digital Certificate Manager

TIBEMSMSGFTIBEMSvrmTIBEMSvrm

*MSGF*PRDDFN*PRDLOD

Other objects required by RSTLICPGM andDLTLICPGM.

Object Description


tibco ems client for ibm i installation and reference · ibm websphere development studio – ile...

Documents