TIBCO EMS Client for IBM i - TIBCO Product Documentation · PDF fileTIBCO® EMS Client for...

TIBCO® EMS Client

for IBM i

Installation and ReferenceSoftware Release 6.0July 2010

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 LICENSE.PDF) 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.TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Adapter, TIBCO Enterprise Message Service, and the TIBCO logo are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, 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.TXT 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 © 1999-2010 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

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Compiling the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15IBM RPG Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3 Running and Developing Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Running Applications and C Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Running Applications From the Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

TIBCO EMS Client for IBM i Installation and Reference

iv | Contents

Running Applications From the QSHELL Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Running Applications and RPG Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Data Conversion Plug-in Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Running Applications and COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Executing the EMS COBOL Sample Programs from QSHELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Submitting to Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

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

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

Appendix A Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

TIBCO EMS Messaging Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34C Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Appendix B Installed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39


| 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

• How to Contact TIBCO Customer Support, page viii


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 Installation Read the relevant sections of this manual before installing this product.

• TIBCO Enterprise Message Service Application Integration Guide This manual presents detailed instructions for integrating TIBCO EMS Client for IBM i with third-party products.

• 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

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows.

• For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site:

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

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

http://support.tibco.com

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


| 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 V5R4M0 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)The following tools can be utilized in QSHELL to help you compile the C samples with a makefile:

• gmake – the GNU make utility

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

You can obtain IBM Tools for Developers for IBM i (5799PTL) at the following IBM software download web site:

http://www.software.ibm.com

Click on "Downloads" link in the left column. On the subsequent page, click on "No-charge products, tools, and toolkit." Then enter 5799PTL in the Search field.


http://www.software.ibm.com



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

• Verifying the Installation, page 16


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_6.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 TIB_ems_6.0.0_ibmi_power.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_6.0._ibmi_power_readme.txt – provides a high level description of the product.

— TIBEMS600.SAV – TIBCO EMS Client for IBM i product

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 all file systems: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 TIBEMS600.SAV file resides:LCD <WINDOWS_DIRECTORY>

8. Specify a binary transfer:BIN

9. Transfer the TIBEMS600.SAV file as a *SAVF:PUT TIBEMS600.SAV TIBEMS600.SAVF

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

DSPSAVF <TARGET_LIBRARY>/TIBEMS600

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 GA

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

Resource Feature ID Option Feature Type Library Release

2TIBEMS *BASE 5001 *CODE TIBEMS V5R1M02TIBEM1 *BASE 5001 *CODE TIBEMS515 V5R1M5

You may now elect to either delete the previous releases of the product, or install the new release in its own library. To install the new release in a separate library, see Multiple Installations on page 12.

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.

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 5.1.5 only, run:

DLTLICPGM LICPGM(2TIBEM1) RLS(V5R1M5)


Previous Releases of the Software | 11

If the current release has not yet been installed, 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 TIBEMS600 .

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(2TIBEM1) DEV(*SAVF)SAVF(<TARGET_LIBRARY>/TIBEMS600)

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

Parameters:

— LICPGM(2TIBEM1) – 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>/TIBEMS600) – *SAVF TIBEMS600 resides in library <TARGET_LIBRARY> .

Multiple Installations

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

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

If no previous installations of TIBCO EMS Client for IBM i have been installed 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

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

RSTLICPGM LICPGM(2TIBEM1) DEV(*SAVF) RLS(V6R0M0) REPLACERLS(*NO) SAVF(<TARGET_LIBRARY>/TIBEMS600) LIB(TIBEMS600)

This command restores the product in library TIBEMS600 , as well as a number of stream files into the /root file system of the IFS in /usr/tibco/6.0.0/TIBEMS600 .

Parameters:

— LICPGM(2TIBEM1) – 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>/TIBEMS600) – *SAVF TIBEMS600 resides in library <TARGET_LIBRARY> .

Dynamic NamingTIBCO EMS Client for IBM i is enabled for Dynamic Naming, which 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(2TIBEM1) DEV(*SAVF) SAVF(savflib/TIBEMS600) LIB(TIBEMS600)

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

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

LIB(TIBEMS600) is optional, and if excluded will install the product in library TIBEMSLIB .



Compiling the Sample Programs

The source code for the TIBCO EMS Client for IBM i sample programs is included as part of the installation.

C Sample ProgramsCompile the C sample programs by performing the following:

1. Edit the makefile file using an editor, or use the following method:

WRKLNK

OBJ('/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c/Makefile')

— Option 2 to edit.

— Modify the following two lines in the file so that MODULE_LIB and PGM_LIB point to the libraries where you want your *module and *pgm objects to be created:

MODULE_LIB = YOURLIB1PGM_LIB = YOURLIB1

— F2 to save.

— F3 to save and exit.

2. Start QShell:QSH

3. Change to the samples directory:cd /usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c

4. Run the Gmake utility:gmake -f Makefile

The sample programs will be created in the library specified by PGM_LIB in makefile. Symbolic links are also created in the /usr/tibco/tibems/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

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


Compiling the Sample Programs | 15

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)

IBM RPG Sample ProgramsThe RPG samples are all provided pre-compiled and ready to run in your product library, or you can compile them yourself. To compile this source, you can use one of the following:

• 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('/usr/tibco/tibems/5.1.5/ TIBEMSLIB/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 14 to publish and receive a message. For information on sample programs, see TIBCO EMS Messaging Samples on page 34.

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

Verification From the Command Entry Screen

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

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 you specified for PGM_LIB in the makefile. 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 screen should display as follows:

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




| 19

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 14.

Topics.

• Running Applications and C Sample Programs, page 20

• Running Applications and RPG Sample Programs, page 22

• Running Applications and COBOL Sample Programs, page 25

• Programmer's Checklist for C Samples, page 28

• Programmer's Checklist for RPG Samples, page 30

• Programmer's Checklist for COBOL Samples, page 31


20 | 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 34.

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

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

cd /usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/cSXJ3MP -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 IBM RPG sample programs are multi-threaded applications, and must be run on 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 have been written simply by writing their output using the DSPLY opcode 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 DSPLY at job end. If the job is written as a never-ending job, such as our consumer samples, one will not see the output of the DSPLY until the job ends.

QSHELL

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


Running Applications and RPG Sample Programs | 23

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

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 TIBEMSLIB.

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/dcp/rpg/EMSRDCP1.rpgle

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

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/dcp/am_bw/AM_BW_Mainframe_Sample_Project.zip.

Note that TIBEMSLIB is the default product library name. If you have used dynamic naming to customize the product library name, the directory path above will reflect this name.



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

Running Applications and COBOL Sample Programs

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

The two COBOL sample sources are delivered in the IFS and in QCBLLESRC.

The Integrated File System (IFS) directory is:

/usr/tibco/tibems/6.0.0/TIBEMSLIB/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

Messages will start appearing after you press ENTER.

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


Running Applications and COBOL Sample Programs | 27

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)



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 /usr/tibco/tibems/6.0.0/TIBEMSLIB/include directory. Sample program header files reside in /usr/tibco/tibems/6.0.0/TIBEMSLIB/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

Example using CRTCMOD:CRTCMOD MODULE(<yourlib>/SXJ3MP)SRCSTMF('/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c/tibemsMsgProducer.c')INCDIR('/usr/tibco/tibems/6.0.0/TIBEMSLIB/include')

Example using CRTPGM:CRTPGM PGM(<yourlib>/SXJ3MP)MODULE(<yourlib>/SXJ3MP <yourlib>/SXJ3UTIL) BNDSRVPGM(TIBEMSLIB/LIBTIBEMS)

(note that SXJ3UTIL must be compiled separately similar to SXJ3MP above)

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 14.


Programmer's Checklist for C Samples | 29

Compiling a Single Sample Program Using Makefile

1. Edit the Makefile file using an editor, or use the following method:WRKLNK

OBJ('/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c/Makefile')

— Option 2 to edit.

— Modify the following two lines in the file so that MODULE_LIB and PGM_LIB point to the libraries where you want your *module and *pgm objects to be created:

MODULE_LIB = YOURLIB1PGM_LIB = YOURLIB1

— F2 to save changes.

— F3 to save and exit.

2. Start QSHELL:QSH


4. Run the gmake utility and specify the individual sample program name in upper case (see the "Native Program and Module Name" column in TIBCO EMS Messaging Samples on page 34 for a list of program names):

gmake -f Makefile <individual_sample_program_name>

Example:gmake -f Makefile SXJ3MC

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

cd /usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c

gmake -f Makefile clean

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:

/usr/tibco/tibems/6.0.0/TIBEMSLIB/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 | 31

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.




| 33

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 34

• Source Code, page 37


34 | 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 | 35

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

SXJ3UTIL 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 | 37

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 /usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c

C client header files /usr/tibco/tibems/6.0.0/TIBEMSLIB/include/tibems

RPG sample source code /usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/rpg

and TIBEMSLIB/QRPGLESRC

COBOL sample source and copybooks

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/cobol

and TIBEMSLIB/QCBLLESRC

Data Conversion Plug-in sample source code

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/dcp/rpg

and TIBEMSLIB/QRPGLESRC





| 39

Appendix B 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.

TIBIFS600 *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 /usr/tibco/tibems/...


40 | Appendix B Installed Objects

Objects in the /root file system

/usr/tibco/tibems/6.0.0/TIBEMSLIB/include/tibems — All C header files for application development

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/c — C sample files and one header file

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/cobol — COBOL source and copybooks for COBOL application development

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/rpg — RPG source and includes for RPG application development

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/dcp/rpg — RPG source and include file for Data Conversion Plug-in sample

/usr/tibco/tibems/6.0.0/TIBEMSLIB/samples/dcp/am_bw — TIBCO Active Matrix Business Works example for running with the RPG Data Conversion Plug-in sample

TIBEMSMSGFTIBEMS600 TIBEMS600

*MSGF*PRDDFN*PRDLOD

Other objects required by RSTLICPGM and DLTLICPGM.

Object Description


Date post:	11-Feb-2018
Category:	Documents
Upload:	nguyennhu
View:	225 times
Download:	1 times

TIBCO EMS Client for IBM i - TIBCO Product Documentation · PDF fileTIBCO® EMS Client for...

Documents