installation and reference - tibco software · ibm websphere development studio – ile cobol...

TIBCO® EMS Client

for i5/OS

Installation and ReferenceSoftware Release 5.1February 2009

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, Information Bus, The Power of Now, 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, J2EE, JMS 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-2009 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 i5/OS (5799PTL). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

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

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

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

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Compiling the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3 Running and Developing Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Running Applications and C Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Running Applications and COBOL Sample Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

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

Programmer's Checklist for COBOL Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

TIBCO EMS Client for i5/OS Installation and Reference

iv | Contents

Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Compile and Bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Appendix A Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

TIBCO EMS Messaging Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Appendix B Installed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27


| v

Preface

This manual describes how to install and configure the TIBCO EMS Client for i5/OS software. It is primarily intended for i5/OS programmers who are involved in setting up and maintaining the system, but is also useful for applications programmers.

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 Enterprise Message Service with third-party products.

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

• TIBCO Enterprise Message Service Java API Reference The Java API reference is available as JavaDoc, and you can access the reference only through the HTML documentation interface.

• TIBCO Enterprise Message Service .NET API Reference The .NET API reference is available in PDF and HTML format.

• TIBCO Enterprise Message Service Release Notes Release notes summarize new features, changes in functionality, and closed issues. 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 AS/400 – ILE Application Development Example

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

IBM WebSphere Development Studio – ILE COBOL Programmer's Guide

IBM WebSphere Development Studio – ILE COBOL Reference

IBM iSeries – TCP/IP Configuration and Reference


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 i5/OS 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 i5/OS software allows applications running on IBM System 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:

A System i application participates in this messaging environment as follows:

1. The System i application embeds TIBCO EMS API function calls to facilitate message communication.

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

3. The System 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 System 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

i5/OS

I5/OS

TIBCOEMSClient

TIBCOEMSClient

TIBCOEMSClient

TIBCOEMS

Server

UserApplication


Overview | 3

Limitations

This version of the TIBCO EMS Client for i5/OS does not support the following:

• SSL (Secure Sockets Layer)

• LDAP (Lightweight Directory Access Protocol)

IBM System i PlatformThe IBM System i platform is a midrange server offering that uses IBM's proprietary i5/OS operating system and includes an integrated database engine. The database is called DB2 UDB for i5/OS or simply DB2/400. 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 System 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 i5/OS software runs as an i5/OS job with multiple user threads enabled (ALWMLTTHD(*YES)). The product is supported on i5/OS V5R3M0 and above.

Before installing the product in an i5/OS environment, you must ensure that the following are installed and properly configured:

Storage RequirementsThe TIBCO EMS Client for i5/OS requires approximately 50 MB of auxiliary storage to install.

TCP/IPThe TIBCO EMS Client for i5/OS 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 i5/OS and the TIBCO EMS server.

• Unrestricted network connectivity between the DNS, the TIBCO EMS Client for i5/OS, 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 i5/OS 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 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 i5/OS (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 i5/OS (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 and tools."


http://www.software.ibm.com

| 7

Chapter 2 Installation

This chapter describes how to install the TIBCO EMS Client for i5/OS software.

Topics

• Distribution Media and Contents, page 8

• Uploading the Software, page 9

• Installing the Software, page 10

• Compiling the Sample Programs, page 11

• COBOL Sample Programs, page 12

• Verifying the Installation, page 13


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 i5/OS 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 Inc. 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_5.1.0_i5os_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_5.1.0_i5os_power.zip file to a PC that can connect to the System i host.

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

— README.TXT – provides a high level description of the product.

— TIBEMS510.SAV – TIBCO EMS Client for i5/OS product

3. From the temporary location on the PC, open a FTP session with the System i host:

FTP <YOUR_AS400>

4. Enter the user ID and password when requested.

5. Specify that the upcoming file transfer locations and names will be specified using IFS notation:

QUOTE SITE NAMEFMT 1

6. Change the default working directory (library) on the System i host that will receive the transfer:

CD <TARGET_LIBRARY>.LIB

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

8. Specify a binary transfer:BIN

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

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

DSPSAVF <TARGET_LIBRARY>/TIBEMS510

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



Installing the Software

Perform the following steps to install the TIBCO EMS Client for i5/OS software. All objects reside within *SAVF TIBEMS510.

1. Sign-on as QSECOFR.

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

RSTLICPGM LICPGM(2TIBEMS) DEV(*SAVF)SAVF(<TARGET_LIBRARY>/TIBEMS510)

Parameters:

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

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

If you have a previous release of the TIBCO EMS Client for i5/OS installed, you need perform a Delete Licensed Program:

DLTLICPGM LICPGM(2TIBEMS)


Compiling the Sample Programs | 11

Compiling the Sample Programs

The source code for TIBCO EMS Client for i5/OS sample programs is included as part of the installation.

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

1. Edit file makefile.i5 using an editor, or use the following method:WRKLNK OBJ('/usr/tibco/tibems/samples/c/Makefile.i5')

— 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

— F3 to save and exit.

2. Start QShell:QSH

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

4. Run the Gmake utility:gmake -f Makefile.i5

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.i5 clean

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



COBOL Sample ProgramsCompile the COBOL sample programs:

ADDLIBLE TIBEMS

CRTCBLMOD MODULE(<mylib>/SXJCMP) SRCFILE(TIBEMS/QCBLLESRC) OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

CRTCBLMOD MODULE(<mylib>/SXJCMC) SRCFILE(TIBEMS/QCBLLESRC) OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

CRTPGM PGM(<mylib>/SXJCMP) MODULE(<mylib>/SXJCMP TIBEMS/SXJ3SIN) BNDSRVPGM(TIBEMS/LIBTIBEMS)

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


Verifying the Installation | 13

Verifying the Installation

To verify that TIBCO EMS Client for i5/OS 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 11 to publish and receive a message. For information on sample programs, see TIBCO EMS Messaging Samples on page 24.

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

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'

6. Press PF3 to end the two QShell sessions.



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

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 jobs spooled files.

8. Select option 5 next to file QPRINT. The screen should display as follows:

------------------------------------------------------------------tibemsMsgConsumer SAMPLE ------------------------------------------------------------------Server....................... tcp://url-id1:7222User......................... (null)Topic......................... TEST1------------------------------------------------------------------Subscribing to topic: 'TEST1'Received TEXT message: Hello WorldReceived TEXT message: A World ApartReceived TEXT message: From Windows


| 15

Chapter 3 Running and Developing Applications

This chapter describes how to submit and execute your applications utilizing the TIBCO EMS Client for i5/OS. It also provides a checklist for C and COBOL language application programmers for the System i environment.

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

Topics.

• Running Applications and C Sample Programs, page 16

• Running Applications and COBOL Sample Programs, page 18

• Programmer's Checklist for C Samples, page 20

• Programmer's Checklist for COBOL Samples, page 22


16 | 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 i5/OS 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 Screen

The 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 24.

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

Running Applications From the QShell Command Entry Screen

QShell provides an interactive display and a multi-user thread environment. The tibemsMsgProducer sample program (SXJ3MP) is easily invoked using a symbolic link:

cd /usr/tibco/tibems/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 COBOL Sample Programs

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

Executing the EMS COBOL Sample Programs from QSHELL

To 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://gasparelatonanb <= enter your EMS server and port> queue glqueue <= 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://gasparelatonanb <= enter your EMS server and port> queue glqueue <= enter your destination queue or topic> <= ENTER ends the input process

Messages will start appearing after you press ENTER.


Running Applications and COBOL Sample Programs | 19

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

> /qsys.lib/<mylib>.lib/sxjcmp.pgm> server tcp://gasparelatonanb> queue glqueue> text new message> $

Submitting to Batch

If submitting these programs to batch, your input data is provided by way of the QINLINE file. Make sure that file QINLINE is found in the job’s *LIBL. An example is provided in TIBEMS. Edit the file TIBEMS/QINLINE(QINLINE) to suit your purposes first.

SBMJOB CMD(CALL PGM(<mylib>/SXJCMC)) INLLIBL(<mylib>) ALWMLTTHD(*YES)

QINLINE needs to contain your input lines. For example:

server tcp://GASPARELATONANBqueue glqueuetext This is my message* <= denotes end of input



Programmer's Checklist for C Samples

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

CodeWhen developing your applications you will need the client header files that reside in the /usr/tibco/tibems/clients/c/include directory. Sample program header files reside in /usr/tibco/tibems/samples/c directory.

Compile and BindStandard ILE C Compiler commands are used:

• CRTCMOD – Create C Module

• CRTPGM – Create Program

• CRTBNDC – Create Bound C 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/samples/c/tibemsMsgProducer.c')INCDIR('/usr/tibco/tibems/clients/c/include')

Example using CRTPGM:CRTPGM PGM(<yourlib>/SXJ3MP)MODULE(<yourlib>/SXJ3MP <yourlib>/SXJ3UTIL) BNDSRVPGM(TIBEMS/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 11.


Programmer's Checklist for C Samples | 21

Compiling a Single Sample Program Using Makefile

1. Edit file Makefile.i5 using an editor, or use the following method:WRKLNK OBJ('/usr/tibco/tibems/samples/c/Makefile.i5')

— 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

— 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 24 for a list of program names):

gmake -f Makefile.i5 <individual_sample_program_name>

Example:gmake -f Makefile.i5 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/samples/c

gmake -f Makefile.i5 clean

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



Programmer's Checklist for COBOL Samples

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

The samples provided are only valid for V5R4.

Compile and Bind• CRTCBLMOD – Create COBOL module

• CRTPGM – Create Program

Example of CRTCBLMOD:

CRTCBLMOD MODULE(<mylib>/SXJCMC) SRCFILE(TIBEMS/QCBLLESRC) OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

Example of CRTPGM:

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

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


| 23

Appendix A Sample Programs

This appendix describes the sample programs included with the TIBCO EMS Client for i5/OS.

Topics

• TIBCO EMS Messaging Samples, page 24

• Source Code, page 26


24 | Appendix A Sample Programs

TIBCO EMS Messaging Samples

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

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


26 | Appendix A Sample Programs

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

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

The sample programs are stored in the following locations:

C sample program source code

/usr/tibco/tibems/samples/c

C client header files /usr/tibco/tibems/clients/c/include/tibems

COBOL sample program source and copybooks

TIBEMS/QCBLLESRC


| 27

Appendix B Installed Objects

This appendix lists the objects that are installed with TIBCO EMS Client for i5/OS.

Objects in the /root file system

/usr/tibco/tibems/clients/c/include/tibems – All c header files for application development

/usr/tibco/tibems/samples/c – c sample files and one header file

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.

MF@COBOLSXJ3SIN

Utility modules for binding into COBOL sample programs.

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

Additional objects required for restoring and deleting the client product.

EMSSYMLNKS *PGM used by RSTLICPGM and DLTLICPGM for handling directory path /usr/tibco/tibems/...

TIBEMSMSGFTIBEMS510 TIBEMS510

*MSGF*PRDDFN*PRDLOD

Other objects required by RSTLICPGM and DLTLICPGM.


28 | Appendix B Installed Objects


installation and reference - tibco software · ibm websphere development studio – ile cobol...

Documents