TIBCO EMS Client for IBM i · IBM WebSphere Development Studio – ILE COBOL Programmer's Guide IBM...

TIBCO® EMS Client

for IBM i

Installation and ReferenceSoftware Release 7.0August 2012

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.TIBCO, The Power of Now, TIB, Information Bus , TIBCO Enterprise Message Service, TIBCO Rendezvous, TIBCO Enterprise, TIBCO SmartSockets, TIBCO ActiveMatrix BusinessWorks, and TIBCO Hawk are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, 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 BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1995-2012 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iii

Contents

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

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viTIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

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

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xHow to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

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) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

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

Uploading the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

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

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Dynamic Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Compiling the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16ILE RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

TIBCO EMS Client for IBM i Installation and Reference

iv | Contents

Chapter 3 Running and Developing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Running Applications and C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Running Applications From the Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Running Applications From the QSHELL Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Running Applications and RPG Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Data Conversion Plug-in Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Running Applications and COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Executing the EMS COBOL Sample Programs from QSHELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Submitting to Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

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

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

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

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

Appendix A Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

TIBCO EMS Messaging Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36C Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

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

Appendix C Installed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43


| v

Preface

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

Topics

• Related Documentation, page vi

• Typographical Conventions, page viii

• How to Contact TIBCO Support, page x

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


vi | Preface

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Enterprise Message Service DocumentationThe following documents form the TIBCO EMS documentation set:

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

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

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

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

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

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

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


Related Documentation | 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


viii | Preface

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

EMI_HOME

Many TIBCO products are installed within the same home directory: /usr/tibco. This directory is referenced in documentation as TIBCO_HOME.

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

code font Code font identifies commands, code examples, filenames, pathnames, and output 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 of particular interest.

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

italic font Italic font is used in the following ways:

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

• To introduce new terms For example: A portal page may contain several portlets. 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

Key combinations

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

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


Typographical Conventions | ix

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

The tip icon indicates an idea that could be useful, for example, a way to apply the 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

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

For example, the following command requires two parameters, which can be either 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 parameter can 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 the second parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


x | Preface

Connecting with TIBCO Resources

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

How to Access TIBCO DocumentationYou can access TIBCO documentation here:

http://docs.tibco.com

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

• For an overview of TIBCO Support, and information about getting started with 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 user name, you can request one.


http://www.tibcommunity.com

http://docs.tibco.com

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

https://support.tibco.com

| 1

Chapter 1 Introduction

This manual provides information about the TIBCO EMS Client for IBM i product. It is intended primarily for programmers who are responsible for installing and maintaining the software. Some of the information contained here may also be useful for application programmers involved in creating or modifying programs that work in conjunction with this product. We recommend that you read through this manual before attempting to install the product, and keep 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 to produce and consume messages that are transported via TIBCO EMS servers.

Messages are structured data that one application sends to another. TIBCO EMS servers, running on platforms outside the traditional System i environment, act as intermediaries for messages and route them to recipients. This message flow is illustrated 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 facilitate message communication.

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

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

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

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

TIBCO EMS Client for IBM i

IBM i

TIBCOEMSClient

TIBCOEMSClient

TIBCOEMSClient

TIBCOEMS

Server

UserApplication


Overview | 3

Limitations

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

• SSL (Secure Sockets Layer)

• LDAP (Lightweight Directory Access Protocol)

IBM System i PlatformThe IBM i platform is a midrange server offering that uses IBM's proprietary i operating system and includes an integrated database engine. The database is called DB2 UDB for IBM i. The file system, called Integrated File System (IFS), is comprised 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 system is called an object. Each object has an object type which is signified by a character string starting with the asterisk (*) character. For example, an executable program object is signified by the character string *PGM; a data queue object is signified by the character string *DTAQ.

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

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



System Requirements

An application that uses the TIBCO EMS Client for IBM i software runs as an IBM i job with multiple user threads enabled (ALWMLTTHD(*YES)). The product is supported on IBM i V5R3M0 and above.

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

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

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

• The TCP/IP protocol stack.

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

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

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

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


System Requirements | 5

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

• 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 the previous 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 scripts may already be installed on your system. These utilities are commonly located in one of two locations, and you can verify their presence 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 scripts under either of these two paths you can continue to compile the samples.

Installing the Utilities

If the scripts are not already installed on your system, you can obtain them by following the following steps provided by IBM in technical document 387414641, Ordering and Installing 5799PTL, iSeries Tools for Developers, located at:

http://www-912.ibm.com/8625680A007CA5C6/1AC66549A21402188625680B0002037E/6C46D578069FEFF38625705E0067DFFA





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

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

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


| 7

Chapter 2 Installation

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

Topics

• Distribution Media and Contents, page 8

• Uploading the Software, page 9

• Installing the Software, page 12

• Compiling the Sample Programs, page 15

• Verifying the Installation, page 18


8 | Chapter 2 Installation

Distribution Media and Contents

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

Obtaining the SoftwareTo obtain the TIBCO EMS Client for IBM i software, you can download it from the TIBCO 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 a CD that contains the same ZIP file as that obtained from the web. Contact TIBCO Software 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. For example, for software release 7.0.0, the file name is:

TIB_ems_7.0.0_ibmi_power.zip


Uploading the Software | 9

Uploading the Software

Once you have obtained the ZIP file, you need to upload the software to the System 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 the following:

— TIB_ems_version_ibmi_readme.txt – The readme for the current software release, where version is the TIBCO EMS Client for IBM i software release version. For example, for software release 7.0.0, the file name is TIB_ems_7.0.0_ibmi_readme.txt.

— TIBEMSvrm.SAV – TIBCO EMS Client for IBM i product, where vrm refers to the version, release and modification that make up the current release of the product. For example, for software release 7.0.0, the file name is TIBEMS700.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 the transfer:

cd <TARGET_LIBRARY>.LIB

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

8. Specify a binary transfer:bin

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

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

DSPSAVF <TARGET_LIBRARY>/TIBEMS700

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



Previous Releases of the Software

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

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

For example:

Resource ID Option Feature Description

2TIBEMS *BASE 5001 TIBCO EMS Client V5R1M0 2TIBEM1 *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 Feature ID 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 install the new release along side the existing releases. To install the new release along side any existing release, see Multiple Installations on page 13.

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

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

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

DLTLICPGM LICPGM(2TIBEM1) RLS(V6R1M0)


Previous Releases of the Software | 11

If the current release has not yet been installed and only one other release is installed on the sytem, you can delete the previous installation without release-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

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 the software:

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

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

Parameters:

— LICPGM(3TIBEM1) – specifies the seven-character identifier of the licensed program that is restored.

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

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

Save File Names

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

For example, the save file for software release 7.0.0 of this product is named TIBEMS700.

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

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


Installing the Software | 13

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 the following command:

RSTLICPGM LICPGM(3TIBEM1) 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 of stream files into the /root file system of the IFS in EMI_HOME.

Parameters:

— LICPGM(3TIBEM1) – specifies the seven-character identifier of the licensed program that is restored.

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

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

— RLS(VvRrMm) – specifies the version, release, and modification level of the licensed program being restored. VvRrMm refers to the release level where v is the version number, r is the release number, and m is the modification level. For example, for release 7.0.0, VvRrMm would be V7R0M0.

— REPLACERLS(*NO) – specifies the version, release, and modification level of the licensed program being replaced. *NO indicates that the licensed program currently installed on the system should not be replaced if the release version is the same. The licensed program being restored must be a different release than the one currently installed. If the licensed program being restored exists in the same library as the installed program, an override parameter must be specified indicating to which library the licensed program is restored.

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



Dynamic NamingTIBCO EMS Client for IBM i is enabled for Dynamic Naming. This allows the end user 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(3TIBEM1) 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 the default product library (which is TIBEMSLIB).

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


Compiling the Sample Programs | 15

Compiling the Sample Programs

The source code for the TIBCO EMS Client for IBM i sample programs is included as 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. By default this name is TIBEMSLIB. This applies to the name when used as a library 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 using the 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 is searched from the TIBEMSLIB library.

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

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

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

— 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=MYDEVLIB TGTRLS=V5R4M0



The sample programs will be created in the library specified by COMPILELIB in the makefile. 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 the following form of gmake:

gmake -f makefile clean COMPILELIB=MYEMSLIB

For additional details on compiling sample programs, see Compile and Bind on page 30.

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/SXJ3SIN TIBEMSLIB/MF@COBOL) BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

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

You must specify the same COMPILELIB that was specified before.


Compiling the Sample Programs | 17

ILE RPG Sample ProgramsThe RPG samples are all provided pre-compiled and ready to run in your product library, or you can compile them yourself. You can compile the samples in one of these 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 is TIBEMSLIB.



Verifying the Installation

To verify that the TIBCO EMS Client for IBM i components have been correctly installed and configured, perform the procedures listed below. These procedures use the sample programs created in Compiling the Sample Programs on page 15 to publish and receive a message. For information on sample programs, see TIBCO EMS Messaging Samples on page 36.

Before performing the procedure, ensure that the TIBCO EMS server is running on port 7222 on server url-id1 (where url-id1 is the hostname where your TIBCO 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 tibemsMsgProducer sample 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 the tibemsMsgProducer 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.


Verifying the Installation | 19

Verification From the Command Entry Screen in Batch

For additional details on running programs from the command entry screen, see Running Applications and C Sample Programs on page 22.

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, if used. 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 message parameter:

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 message parameter:

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 the tibemsMsgProducer 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 contain the following:

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



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


| 21

Chapter 3 Running and Developing Applications

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

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

Topics.

• Running Applications and C Sample Programs, page 22

• Running Applications and RPG Sample Programs, page 24

• Running Applications and COBOL Sample Programs, page 27

• Programmer's Checklist for C Samples, page 30

• Programmer's Checklist for RPG Samples, page 32

• Programmer's Checklist for COBOL Samples, page 33


22 | Chapter 3 Running and Developing Applications

Running Applications and C Sample Programs

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

TIBCO EMS Client for IBM i program parameters that begin with the dash character are case sensitive (for example, -server). Be sure to observe case sensitivity when editing any files that may require lower case parameters. On the Command Entry Screen, any parameters that are not quoted will be folded to upper 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-value pairs:• -server tcp://url-id1:7222

• -topic TEST1

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

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

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


Running Applications and C Sample Programs | 23

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

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 file system:

/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 using the 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 run from 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 and running. For example, tcp://glatona-dt:7222.

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

• message is the message to send. The current RPG sample programs do not allow embedded 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 second printer 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 output queue. When executing the samples interactively for QSHELL, the printer files display to your screen if the application ends correctly and the files are closed properly. Otherwise, the printer files are spooled.

QSHELL

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

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


Running Applications and RPG Sample Programs | 25

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 and running. For example, tcp://glatona-dt:7222.

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

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

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

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

Source Location

The source for the sample exists both in the TIBCO EMS Client for IBM i product library and in the Integrated File System (IFS), and is also provided pre-compiled in 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 the machine 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 where your 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 message from 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 configured and 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 content to the BusinessWorks project and waits for a response with modified data from BusinessWorks.


Running Applications and COBOL Sample Programs | 27

Running Applications and COBOL Sample Programs

This section explains methods for running your applications or the COBOL sample programs provided with the product. The COBOL sample sources are delivered 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 using the 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 the job log.

For samples that are executed from QSHELL, one will only see the output of the DISPLAY at job end. If the job is written as a never ending job, such as the consumer 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 5250 display 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 to tibemsMsgConsumer), in QSHELL and receive messages, follow the steps shown below 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 the QINLINE file. Make sure the QINLINE file is found in the job’s *LIBL. An example is provided in TIBEMSLIB.

Edit the file TIBEMSLIB/QINLINE(QINLINE) to update the server and queue information 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 batch and QSHELL can be used. For example, execute the EMS COBOL sample SXJCMC 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> TIBEMSLIB) ALWMLTTHD(*YES)

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


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

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 of which version of the EMS Client you bind and/or run your application with. If you have two different versions of the EMS client installed, you can either bind your application statically to one specific service program, or you can dynamically bind the service program and control which version of the EMS Client is used at runtime.

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

• Software Release 6.1.0 in product library TIBEMS610

• Software Release 7.0.0 in product library TIBEMS700

Bind Statically

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

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

where yourlib is your application library.

Bind Dynamically

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

For example:

ADDLIBLE TIBEMS700CRTPGM 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 following example to see in which library service program LIBTIBEMS is found:

DSPPGM PGM(TIBEMS700/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 that reside in the EMI_HOME/include directory. Sample program header files reside in 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 using makefile. 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 to handle common activities. This should be compiled ahead of the other samples and bound together with them:

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

Example using CRTCMOD:CRTCMOD MODULE(yourlib/SXJ3MP)SRCSTMF('EMI_HOME/samples/c/tibemsMsgProducer.c') DEFINE('_I5OS') 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))


Programmer's Checklist for C Samples | 31

Compiling All Sample Programs Using Makefile

This procedure was performed to verify the installation of the product. For details, see Compiling the Sample Programs on page 15.

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 in upper case (see the Sample Programs on page 35 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 the sample 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 the 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 is searched from the TIBEMSLIB library.

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

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

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

• 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=LEMS700DEV COMPILELIB=MYDEVLIB TGTRLS=V5R4M0

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



Programmer's Checklist for RPG Samples

CodeThe RPG sample source has been provided in both source physical file TIBEMSLIB/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 | 33

Programmer's Checklist for COBOL Samples

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

Compile and Bind• CRTCBLMOD – Create COBOL module


Example of CRTCBLMOD:

CRTCBLMOD 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 in TIBEMS.




| 35

Appendix A Sample Programs

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

Topics

• TIBCO EMS Messaging Samples, page 36

• Source Code, page 39


36 | Appendix A Sample Programs

TIBCO EMS Messaging Samples

C Sample ProgramsThis section describes the C sample programs for TIBCO EMS messaging. For all programs, 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 Source Filename

Native Program andModule Name

Program Name Under QSHELL

Asynchronous Message Consumer

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), but uses the tibemsXAResource interface to consume messages using transaction semantics.

tibemsXAMsgConsumer.c

SXJ3XAMC tibemsXAMsgConsumerSXJ3XAMC

Message Producer tibemsMsgProducer.c

SXJ3MP tibemsMsgProducerSXJ3MP

Like SXJ3MP (above), but uses the classic X/Open DPT XA interface to send messages using transaction semantics.

tibemsXAMsgProducer.c

SXJ3XAMP tibemsXAMsgProducerSXJ3XAMP

Message Consumer demonstrating how to enumerate message properties and fields

tibemsMsg.c SXJ3MSG tibemsMsgSXJ3MSG


TIBCO EMS Messaging Samples | 37

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 on subsystems that are enabled for multi-threading. For example, subsystem QINTER is not enabled for multi-threading.

Helper functions used by other samples to handle common activities

tibemsUtilities.c SXJ3UTIL tibemsUtilitiesSXJ3UTIL

tibemsMsgProducerPerf tibemsMsgProducerPerf.c

SXJ3MPPF tibemsMsgProducerPerfSXJ3MPPF

tibemsMsgConsumerPerf tibemsMsgConsumerPerf.c

SXJ3MCPF tibemsMsgConsumerPerfSXJ3MCPF

Type of EMS Sample IFS Source Filename

Native Program andModule Name

Program Name Under QSHELL

Type of EMS SampleRPG Source Filename and Short Name

Description

Asynchronous Message Consumer

tibemsAsyncMsgConsumer

SXJRAMC

An example demonstrating the use of an asynchronous message consumer, using C functions, operating on non-typed connections and sessions. This sample registers a listener on the specified topic or queue, and prints all messages asynchronously received on that destination. The destination (specified as a parameter) must exist in the topics or queues configuration files, or the configuration files should allow dynamic creation of that destination. The sample configuration distributed with TIBCO Enterprise Message Service allows for the creation of all topics and queues.

Queue Browser tibemsBrowser

SXJRBR

A simple example demonstrating the use of the queue browsers, using C functions, operating on non-typed connections and sessions.



Durable Topic Subscriber

tibemsDurable

SXJRDTSB

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

Message Consumer tibemsMsgConsumer

SXJRMC

An example demonstrating use of the message consumer, using C functions, operating on non-typed connections and sessions. This sample synchronously consumes and prints all messages received on the specified topic or queue. The destination (specified as a parameter) must exist in the topics or queues configuration files, or the configuration files should allow dynamic creation of that destination. Sample configuration distributed with TIBCO Enterprise Message Service allows creation of all topics and queues.

Message Producer tibemsMsgProducer

SXJRMP

An example demonstrating use of the message producer, using C functions, operating on non-typed connections and sessions. This sample sends one or more text messages to the specified topic or queue. The topic or queue (specified as a parameter) must exist in the topics or queues configuration files, or the configuration files should allow dynamic creation of that destination. The sample configuration distributed with TIBCO Enterprise Message Service allows creation of all topics and queues.

Type of EMS SampleRPG Source Filename and Short Name

Description


Source Code | 39

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, and COBOL.

• 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 and copybooks

EMI_HOME/samples/cobol

and TIBEMSLIB/QCBLLESRC

Data Conversion Plug-in sample source code

EMI_HOME/samples/dcp/rpg

and TIBEMSLIB/QRPGLESRC




| 41

Appendix B EMS Client Programming in RPG

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

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

The following table guides the translation from C to RPG. Each section of the table addresses a specific type of parameter passing in C, followed by the equivalent constructs 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)


42 | 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


| 43

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 EMS applications to bind to.

ZLIB *SRVPGM containing compression utilities used by LIBTIBEMS.

CRYPTO *SRVPGM containing openSSL Crypto component.

QCBLLESRC Source physical file containing sample COBOL source and copybooks.

QRPGLESRC Source physical file containing sample RPG source and include files.

MF@COBOLSXJ3SIN

Utility modules for binding into COBOL sample programs.

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

SXJRAMCSXJRBRSXJRDTSBSXJRMCSXJRMP

Precompiled RPG sample programs.

EMSRDCP1 Precompiled RPG sample program for Data Conversion 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 for handling directory path EMI_HOME/...


44 | 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 COBOL application development

EMI_HOME/samples/rpg — RPG source and includes for RPG application development

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

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

TIBEMSMSGFTIBEMSvrm TIBEMSvrm

*MSGF*PRDDFN*PRDLOD

Other objects required by RSTLICPGM and DLTLICPGM.

Object Description


Date post:	30-Aug-2018
Category:	Documents
Upload:	hoangcong
View:	225 times
Download:	0 times

TIBCO EMS Client for IBM i · IBM WebSphere Development Studio – ILE COBOL Programmer's Guide IBM...

Documents