TIBCO EMS Client for IBM i Installation and Reference · PDF fileExecuting the EMS COBOL Sample Programs from Qshell ... The database is called DB2. ... character string *PGM;

TIBCO® EMS Client for IBM iInstallation and ReferenceSoftware Release 8.4August 2017

Two-Second Advantage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (ORPROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO, the TIBCO logo, Two-Second Advantage, TIB, Information Bus, TIBCO Enterprise MessageService, TIBCO Rendezvous, TIBCO Enterprise, TIBCO SmartSockets, TIBCO ActiveMatrixBusinessWorks, TIBCO Hawk, and TIBCO EMS Client for IBM i are either registered trademarks ortrademarks of TIBCO Software Inc. in the United States and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform EnterpriseEdition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks ofOracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE 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 ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2010-2017 TIBCO Software Inc. All rights reserved.

TIBCO Software Inc. Confidential Information

2

TIBCO® EMS Client for IBM i Installation and Reference

Contents

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

IBM i Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

SSL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Installing and Verifying the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Obtaining the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

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

Managing Previous Releases of the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Identifying Previous Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Deleting Previous Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Performing a Single Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Performing Multiple Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Verifying From Qshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Verifying from the Command Entry Screen in Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Verifying SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Importing Sample Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Configuring the EMS Server for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Verifying SSL From Qshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Running and Developing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Running Applications and C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Running Applications From the Command Entry Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Running Applications From Qshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Running Applications and RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Running the Data Conversion Plug-in Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Running Applications and COBOL Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Executing the EMS COBOL Sample Programs from Qshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Submitting to Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Binding an Application to the Correct Version of EMS Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Compiling and Binding C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Compiling All Sample Programs Using the make.sh Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Compiling a Single Sample Program Using Native Compiler Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Compiling and Binding COBOL Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Compiling and Binding RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

3


TIBCO EMS Messaging Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

C Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

RPG Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

EMS Client Programming in RPG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Installed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4


TIBCO Documentation and Support Services

Documentation for this and other TIBCO products is available on the TIBCO Documentation site. Thissite is updated more frequently than any documentation that might be included with the product. Toensure that you are accessing the latest available help topics, visit:

https://docs.tibco.com

Product-Specific Documentation

Documentation for TIBCO products is bundled with the software. It is also available on the TIBCODocumentation site. To access the documentation web page for this product from a local softwareinstallation, open the following file:TIB_emsi5os_version_docinfo.html

where this file is shipped with the software package .zip file.

The following documents for this product can be found on the TIBCO Documentation site or afterdecompress the documentation .zip file:

● TIBCO EMS Client for IBM i Installation and Reference

● TIBCO EMS Client for IBM i Release Notes

The following documents provide additional information and can be found on the TIBCODocumentation site:

● TIBCO Enterprise Message Service User’s Guide

● TIBCO Enterprise Message Service Central Administration

● TIBCO Enterprise Message Service Installation

● TIBCO Enterprise Message Service C & COBOL Reference

● TIBCO Enterprise Message Service Java API Reference

● TIBCO Enterprise Message Service .NET API Reference

● TIBCO Enterprise Message Service Release Notes

● TIBCO EMS Client for z/OS (MVS) Installation and Reference

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support:

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

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

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

https://support.tibco.com

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

5


https://docs.tibco.com

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

https://support.tibco.com

Product Overview

The TIBCO EMS Client for IBM i software allows applications running on IBM i to produce andconsume messages that are transported by way of TIBCO EMS servers.

Messages are structured data that one application sends to another. TIBCO EMS servers, running onplatforms outside the traditional System i environment, act as intermediaries for messages and routethem to recipients. The following figure illustrates the message flow:

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. TIBCO EMS Client for IBM i establishes a connection with a TIBCO EMS server using standardTCP/IP.

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

4. Other TIBCO EMS clients communicate with the IBM i application through the TIBCO EMS server.TIBCO EMS API function calls are coded by programmers and included in the System i application atcompilation time. See TIBCO Enterprise Message Service User’s Guide for a complete description of TIBCOEMS operations.

This manual provides information about the TIBCO EMS Client for IBM i. It is intended primarily forprogrammers who are responsible for installing and maintaining the software. Some of the informationcontained here might also be useful for application programmers involved in creating or modifyingprograms that work in conjunction with this product. For the best practice, read through this manualbefore attempting to install the product, and keep a copy handy for future reference.

All references to the version-specific numbers in save file names are generalized in this book asTIBEMSvrm, where vrm refers to the version, release and modification that make up the current releaseof the product. For example, the save file for software release 8.4.0 of this product is named TIBEMS840.

IBM i PlatformThe IBM i platform is a midrange server offering that uses IBM's proprietary IBM i operating systemand includes an integrated database engine. The database is called DB2.

The file system, called Integrated File System (IFS), is comprised of and provides an umbrella forseveral different sub-file systems. The native file system used by IBM i is QSYS.LIB. Each entity in this

6


file system is called an object. Each object has an object type that is signified by a character stringstarting with the asterisk (*) character. For example, an executable program object is signified by thecharacter 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 todirectories in Windows and UNIX systems. A library is used to group objects of different typestogether. However, unlike a directory, a library cannot have another library as a child. Objects such asfiles (tables), programs, and other native System i type objects can exist only inside a library. An objectin 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 jobnumber assigned by the system when the job is started. Each job also has a library list associated withit. This is similar to the PATH variable on Windows or LD_LIBRARY_PATH variable on UNIX. When anobject is not explicitly qualified using a library name, the object is searched in 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.

7


System Requirements

Before installing the software, ensure that your system meets the following requirements.

Platform Requirements

An application that uses the TIBCO EMS Client for IBM i software runs as an IBM i job with multipleuser threads enabled (ALWMLTTHD(*YES)). Product support for platform and versions can be locatedin the readme documentation.

Storage Requirements

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

TCP/IP

The 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 host name and host address of the TIBCO EMS Client for IBM i andthe TIBCO EMS server.

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

Application Development Languages

The TIBCO EMS Client for IBM i is implemented using the ILE C compiler. Any ILE compiler on IBM ican be used for application development. Sample programs are provided in C, RPG, and COBOL withyour installation.

Qshell

Although not required, it is good practice to install Qshell (option 30 of the OS). This provides thefollowing benefits:

● Run your samples and applications in interactive mode.

● Compile all the C sample programs using a script.

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

SSL Prerequisites

The TIBCO EMS Client for IBM i uses the IBM System SSL facility to create secure connections to theEMS server. To use System SSL, ensure these prerequisites:

● Update IBM i to a Technology Refresh level that includes support for TLS 1.2 and TLS 1.1.

● Configure the Digital Certificate Manager (Option 34).

● Configure the IBM HTTP Server (5761DG1).

See SSL Requirements for more details.

8


SSL RequirementsTo use System SSL, ensure that you have configured Digital Certificate Manager (Option 34) and IBMHTTP Server (5761DG1).

Digital Certificate Manger

The Digital Certificate Manager (DCM) centralizes the management and use of certificates withincertificate stores on an IBM i system. It provides the functionality to create a local Certificate Authority(CA) that can be used to issue client certificates. The DCM can also be used to import certificatesobtained from other sources, such as the sample certificates shipped with the TIBCO EMS Client forIBM i.

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

IBM HTTP Server

The HTTP *ADMIN instance can be used to administer the DCM using a web browser. To administerthe DCM, a user profile with *ALLOBJ and *SECADM special authority is required.

For more information on how to start the HTTP *ADMIN instance and administer the DCM, see theIBM documentation for the Digital Certificate Manager.

Special Authority

Applications that use the TIBCO EMS Client for IBM i and SSL must have read access to a certificatestore. The application either has to be run with a user profile that has *ALLOBJ special authority, or theuser profile is given *RX data authority to the certificate store using the CHGAUT command.

You can find the path and file name for the object used with the CHGAUT command when using the webbrowser interface to the DCM and selecting the certificate store to open.

9


Installing and Verifying the Software

After preparing your system, you can install the software.

A complete installation includes the following:

1. Obtaining the Software

2. Uploading the Software

3. Managing Previous Releases of the Software

4. Installing the Software

5. Verifying the Installation

6. Verifying SSL

Before software release 5.1.5, TIBCO EMS Client for IBM i could not be installed multiple times on thesame system. It is now possible to install the current software release alongside previous releases.Before installing the software, identify any previously installed versions of the client, and then makeyour decision whether to install the software along with the previous version, or delete the previousinstallation; then install the software.

Obtaining the SoftwareFirst, you have to obtain the software and installation files included in the distribution media. Thesoftware is distributed as a *SAVF inside a ZIP file.

The following ZIP file is included in the distribution media:

TIB_ems_version_ibmi_power.zip

where version is the TIBCO EMS Client for IBM i software release version. For example, for softwarerelease 8.4.0, the file name is TIB_ems_8.4.0_ibmi_power.zip.

To obtain the TIBCO EMS Client for IBM i software, you can download it from the TIBCO SoftwareProduct eDelivery Site, or request a CD.

Downloading from the Web Site

To download the software from the TIBCO Software Product eDelivery Site, follow these steps:

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

2. Connect to the TIBCO Software Product eDelivery Site with the required information.

3. 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 thesame ZIP file as that obtained from the web. Contact TIBCO Software through email at [email protected] and request a CD for your System i product installation.

10


Uploading the SoftwareOnce you have obtained the ZIP file, you must upload the save file to the IBM i host system using theFTP file transfer utility.

Procedure

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

2. Extract this file to a temporary location on the PC.

The file contains the following:

● TIB_emsi5os_version_readme.txt: the readme for the current software release, where versionis the TIBCO EMS Client for IBM i software release version. For example, for software release8.4.0, the file name is TIB_emsi5os_8.4.0_readme.txt.

● TIB_emsi5os_version_license.pdf: the license file, in PDF format, for the current softwarerelease.

● TIB_emsi5os_version_license.txt: the license file, in text format, for the current softwarerelease.

● TIB_emsi5os_version_relnotes.pdf: the Release Notes for the current software release.● TIBEMSvrm.SAV: TIBCO EMS Client for IBM i product, where vrm refers to the version, release,

and modification that make up the current release of the product. For example, for softwarerelease 8.4.0, the file name is TIBEMS840.SAV.

3. From the temporary location on the PC, open an FTP session to the IBM i machine:ftp <YOUR_IBMi>

4. Enter the user ID and password when requested.

5. Select the file naming format for FTP commands:quote site namefmt 1

6. Change the working directory to the library on the IBM i machine that is to receive the save file:cd <TARGET_LIBRARY>.LIB

7. Change the local directory on the PC to where the TIBEMS840.SAV file is located:lcd <WINDOWS_DIRECTORY>

8. Specify a binary transfer:bin

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

10. Verify that the installation file uploading is successful by signing on to IBM i and displaying thecontents of the *SAVF.For example: DSPSAVF <TARGET_LIBRARY>/TIBEMS840A number of objects are displayed at the bottom half of the screen.

Managing Previous Releases of the SoftwareIf previous versions of TIBCO EMS Client for IBM i have been installed on the system, you can eitherdelete the previous releases of the product, or install the new release in its own library.

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

See identifying previous installations for more details on how to check if a previous version of thesoftware is already installed.

11


If a previous version of the software is already installed, do either of the following:

● Delete the previous releases of the product, see Deleting Previous Installations.

● Install the new release along side any existing release, see Performing Multiple Installation.

Identifying Previous InstallationsYou can use the DSPSFWRSC command to obtain information about the existing installations.

If TIBCO EMS Client for IBM i has been previously installed on the system, you can obtain informationabout the existing installations by executing the DSPSFWRSC command.

For example:Resource ID Option Feature Description2TIBEMS *BASE 5001 TIBCO EMS Client V5R1M02TIBEM1 *BASE 5001 TIBCO EMS Client for i5/OS V5R1M5 GA2TIBEM1 *BASE 5001 TIBCO EMS Client for IBM i V6R1M0 GA

If you Press F11, you can also see the product library name and release:Resource ID Option Feature Feature Type Library2TIBEMS *BASE 5001 *CODE TIBEMS V5R1M02TIBEM1 *BASE 5001 *CODE TIBEMS515 V5R1M52TIBEM1 *BASE 5001 *CODE TIBEMS610 V6R1M0

Deleting Previous InstallationsYou can use DLTLICPGM command to delete a previous installation of TIBCO EMS Client for IBM i.

When using the DLTLICPGM command, you have to specify the resource ID for the installation to beremoved. Obtain the resource ID by using the DSPSFWRSC command.

The deleting method is different depending on whether the current release is already installed:

● If you have already installed the current release and want to delete a previous release, ensure thatyou release-qualify the operation.

For example, to delete TIBCO EMS Client for IBM i release 6.1.0 only, run the following:

DLTLICPGM LICPGM(2TIBEM1) RLS(V6R1M0)

● If the current release is not installed and only one other release is installed on the system, you candelete the previous installation without release-qualifying DLTLICPGM. For example:

— To delete Software Release 5.1.0 with the resource ID 2TIBEMS, run the following:

DLTLICPGM LICPGM(2TIBEMS)

— To delete Software Release 5.1.5 with the resource ID 2TIBEM1, run the following:

DLTLICPGM LICPGM(2TIBEM1)

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

Installing the SoftwareAfter uploading the software to the IBM i machine, you can start your installation.

● If no previous installations of TIBCO EMS Client for IBM i are present on the system, you can followone path of the RSTLICPGM command to install the software.

For more information, see Performing Single Installation.

● If a previous installation of TIBCO EMS Client for IBM i exists on the target system, you must becareful about which parameters you specify with the RSTLICPGM command.

12


For more information, see Performing Multiple Installation.

Following either the single or multiple installation path also results in components being installed inthe IFS file system in a directory referred to as EMI_HOME. The value of EMI_HOME depends on theproduct release. For the 8.4.0 release, the value of EMI_HOME is /usr/tibco/tibems/8.4.0.

Dynamic Naming

TIBCO EMS Client for IBM i supports dynamic naming, which means that you can install the productinto a unique user-chosen product library name.

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

RSTLICPGM LICPGM(4TIBEM3) DEV(*SAVF) SAVF(savflib/TIBEMSvrm) LIB(prodlib)

where savflib is the library name where the product save file was uploaded.

In the example, the EMS client is installed into the prodlib library instead of the default product library,which is TIBEMSLIB. The LIB parameter is optional, and if not specified, the EMS client is installed inthe TIBEMSLIB library.

Performing a Single InstallationYou can use one path of the RSTLICPGM command to install TIBCO EMS Client for IBM i on an IBM imachine where no previous releases are installed.

Procedure

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

2. Run the following command to install the software:RSTLICPGM LICPGM(4TIBEM3) DEV(*SAVF) SAVF(savflib/TIBEMSvrm)

This command restores the TIBEMSLIB library and a number of stream files into the IFS file systemin subdirectories of EMI_HOME.

where:

LICPGM(4TIBEM3)

The seven-character identifier of the licensed program that is restored.

DEV(*SAVF)

The device name where the software is located. In this case, the device is a save file whose name isspecified in the SAVF parameter.

SAVF(savflib/TIBEMSvrm)

The TIBEMSvrm save file located in the savflib library.

Performing Multiple InstallationsYou can use the RSTLICPGM command with different parameters to install TIBCO EMS Client for IBM ion an IBM i machine where a previous release is installed.

Procedure

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

2. Run the following command to install the software along side with previous installations:RSTLICPGM LICPGM(4TIBEM3) DEV(*SAVF) RLS(VvRrMm) REPLACERLS(*NO)

SAVF(<TARGET_LIBRARY>/TIBEMSvrm) LIB(prodlib)

13


This command restores the software to the prodlib library and a number of stream files into the IFSfile system in subdirectories of EMI_HOME.

where:

LICPGM(4TIBEM3)

The seven-character identifier of the licensed program that is restored.

DEV(*SAVF)

The device name where the software is located. In this case, the device is a save file whose name isspecified in the SAVF parameter.

SAVF(savflib/TIBEMSvrm)

The *SAVF TIBEMSvrm save file located in the savflib library.

RLS(VvRrMm)

The version, release, and modification level of the licensed program being restored. VvRrMm refersto the release level:

● v is the version number.

● r is the release number.

● m is the modification level.

For example, for release 8.4.0, VvRrMm is V8R4M0.

REPLACERLS(*NO)The version, release, and modification level of the licensed program being replaced.

*NO indicates that the licensed program currently installed on the system will not be replaced if therelease version is the same. The licensed program being restored must be a different release thanthe one currently installed. If the licensed program being restored exists in the same library as theinstalled program, an override parameter must be specified indicating to which library thelicensed program is restored.

LIBThe library into which the licensed program is being restored.

Verifying the InstallationYou can verify the installation either from Qshell or from the Command Entry Screen in batch.

● Verifying From Qshell● Verifying From the Command Entry Screen in Batch

Verifying From QshellYou can verify the TIBCO EMS Client for IBM i installation from a Qshell environment by running theprovided C sample programs.

Prerequisites

Ensure that the TIBCO EMS server is running on port 7222 on server url-id1, where url-id1 is thehostname where your TIBCO EMS server is running.

Procedure

1. Start the Qshell environment:QSH

14


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

3. Run the tibemsMsgConsumer sample program (SXJ3MC) in one of the following ways:

● SXJ3MC -server tcp://url-id1:7222 -topic TEST1

● tibemsMsgConsumer -server tcp://url-id1:7222 -topic TEST1

4. From another Qshell environment, run the tibemsMsgProducer sample program (SXJ3MP) with amessage parameter in one of the following ways:

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

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

The message is displayed on the first Qshell command entry screen.

5. Optional: If you have another EMS client on Windows, run the tibemsMsgProducer sampleprogram:cd <directory-where-Windows-client-binary-resides> tibemsMsgProducer -server

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

The message is displayed on the first Qshell command entry screen.

6. Press PF3 to end the two Qshell environments.

Verifying from the Command Entry Screen in BatchYou can verify the TIBCO EMS Client for IBM i installation from the command entry screen in batch byrunning the provided C sample programs.

Prerequisites

Ensure that the TIBCO EMS server is running on port 7222 on server url-id1, where url-id1 is thehostname where your TIBCO EMS server is running.

Procedure

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

TEST1)) ALWMLTTHD(*YES)

where prodlib is the name of the library into which the product was restored using the RSTLICPGMcommand. If no LIB parameter was used with the RSTLICPGM command then the default libraryname is TIBEMSLIB

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

2. Run the tibemsMsgProducer sample program (SXJ3MP) with a message parameter:SBMJOB CMD(CALL PGM(prodlib/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(prodlib/SXJ3MP) PARM('-server' 'tcp://url-id1:7222' '-topic'

TEST1 'A World Apart')) ALWMLTTHD(*YES)

4. Optional: If you have another EMS client on Windows, run the tibemsMsgProducer sampleprogram as follows:cd <directory-where-Windows-client-binary-resides> tibemsMsgProducer -server

tcp://url-id1:7222 -topic TEST1 "From Windows"

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

15


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

7. Select option 4 to display the spooled files of the Job.

8. Select option 5 next to the QPRINT file.The contents of the printer file contains the following:------------------------------------------------------------------tibemsMsgConsumer SAMPLE------------------------------------------------------------------Server....................... tcp://url-id1:7222User......................... (null)Destination.................. TEST1------------------------------------------------------------------Subscribing to destination: 'TEST1'Received TEXT message: Hello WorldReceived TEXT message: A World ApartReceived TEXT message: From Windows

Verifying SSLYou can optionally use the listed procedures to verify if SSL connections to a TIBCO EMS server areconfigured correctly.

These procedures use the same sample programs that are used in verifying the installation, and also usethe sample certificates provided with the TIBCO EMS Client for IBM i.

Complete the following tasks to configure and verify SSL:

1. Importing Sample Certificates

2. Configuring the EMS Server for SSL

3. Verifying SSL From Qshell

Importing Sample CertificatesBefore configuring SSL, you have to import the sample certificates.

You can find the files to be imported in the EMI_HOME/sample/certs directory:

● Sample CA Certificate Files:

server_root.cert.pem

client_root.cert.pem

● Sample PKCS12 File:

client_identity.p12

The certificates in these files can be imported by Digital Certificate Manager (DCM). They arecompatible with the sample certificates shipped with EMS for platforms other than IBM i.

EMS Client for IBM i uses the CA certificate from server_root.cert.pem to authenticate the servercertificate that the TIBCO EMS server offers as identification during the SSL handshake.

In order to successfully import the file client_identity.p12 as a client certificate, theclient_root.cert.pem must first be imported as a CA certificate.

Procedure

1. Connect to the DCM browser interface.

16


Use a web browser to connect to the *ADMIN instance of the IBM HTTP Server. Navigate to DigitalCertificate Manger as documented in IBM i Security Digital Certificate Manager, Configuring DCM,Starting Digital Certificate Manager.

You can usually use this URL to directly access the Digital Certificate Manager:http://system_name:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0

2. Create a new certificate store.In Digital Certificate Manager, click Create New Certificate Store, select Other System CertificateStore, and click Continue.

3. Select Do not create a certificate in the certificate store and click Continue.

4. Enter a full path for the sample certificate store of /QIBM/USERDATA/ICSS/CERT/SERVER/TIBEMSSMP.KDB and use the password string password.

5. Confirm that the sample certificate store was created.Click OK.

6. In Digital Certificate Manager, click Select a Certificate Store.

7. Select the Other System Certificate Store and click Continue.

8. Enter the path and password for the sample certificate store that you created in step 4, and clickContinue.

9. In the left-hand navigation pane, click Fast Path, and then click Work with CA certificates.

The CA certificates and their status are displayed.

10. Click Import.The Import Certificate Authority (CA) Certificate page is displayed.

11. On the Import Certificate Authority (CA) Certificate page, import the EMI_HOME/sample/certs/server_root.cert.pem file, and specify TIBCO_EMS840_SERVER_ROOT as the CA certificate label.

12. On the Import Certificate Authority (CA) Certificate page, import the EMI_HOME/sample/certs/client_root.cert.pem file, and specify TIBCO_EMS840_CLIENT_ROOT as the CA certificate label.

13. In the left-hand navigation pane, click Fast Path, and then click Work with server and clientcertificates.

14. Click Import.The Work with Server and Client Certificates page is displayed.

15. On the Work with Server and Client Certificates page, import the EMI_HOME/sample/certs/client_identity.p12 file. Use password as the encryption password for this file. SpecifiyTIBCO_EMS840_CLIENT_IDENTITY as the certificate label.

Configuring the EMS Server for SSLAfter importing the certificates, you have to configure the EMS server to use SSL to secure thecommunication between the EMS server and client.

See TIBCO Enterprise Message Service User’s Guide for more details on how to configure SSL. Follow thisprocedure when modifying the tibemsd.conf configuration file.

Prerequisites

The samples in the EMI_HOME/sample/certs directory on IBM i are compatible with the samplecertificates in the sample/certs directory of EMS 8.4.0 servers on other platforms. This procedurerefers to this directory on the TIBCO EMS server as EMS_CERTS.

17


Procedure

1. To specify the port on which to listen for SSL connections, add the following listen parameter to theEMS server configuration file :listen = ssl://url-id1:7243

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

3. Configure the private key and password for the EMS server:ssl_server_key = EMS_CERTS/server.key.pem

ssl_password = password

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

What to do next

After configuring SSL, start the EMS server and verify that the server is active and listening on thesecure socket port.

Verifying SSL From QshellYou can use the tibemsMsgConsumer and tibemsMsgProducer sample programs to verify if SSL iscorrectly configured.

Procedure

1. From a Qshell environment, run the tibemsMsgConsumer sample program:tibemsMsgConsumer -server ssl://url-id1:7243 -topic TEST1 -ssl_ring '/QIBM/

USERDATA/ICSS/CERT/SERVER/TIBEMSSMP.KDB' -ssl_label TIBCO_EMS840_CLIENT_IDENTITY

-ssl_trace -ssl_debug_trace -ssl_noverifyhostname

2. From another Qshell environment, run the tibemsMsgProducer sample program with a messageparameter:tibemsMsgProducer -server ssl://url-id1:7243 -topic TEST1 -ssl_ring '/QIBM/

USERDATA/ICSS/CERT/SERVER/TIBEMSSMP.KDB' -ssl_label TIBCO_EMS840_CLIENT_IDENTITY

-ssl_trace -ssl_debug_trace -ssl_noverifyhostname 'Hello World'

3. Press PF3 to end the two Qshell environments.

18


Running and Developing Applications

After installing and configuring the product, you can submit and execute your applications utilizing theTIBCO EMS Client for IBM i to send and receive messages.

Prerequisites

Before performing these tasks, you must have completed the installation of the TIBCO EMS Client forIBM i software, and performed the Installation Verification Program (IVP) steps. See Installing theSoftware and Verifying the Installation for more details.

Running Applications and C Sample ProgramsYou can run the provided C sample programs to send and receive messages using TIBCO EMS.

Compiled versions of the C sample programs are available in the library where the product wasrestored using RSTLICPGM. You may also compile the C sample programs such that they are created in adevelopment library of your choice by following the instructions in Compiling and Binding C SamplePrograms.

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 might requirelower case parameters. On Command Entry Screen, any parameters that are not quoted are folded toupper case.

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

You can run the C sample programs either from Command Entry Screen or from Qshell.

Running Applications From the Command Entry Screen

The following command submits the tibemsMsgProducer sample program (SXJ3MP) to batch withmultiple user threads enabled:SBMJOB CMD(CALL PGM(<samplib>/SXJ3MP) PARM('-server' 'tcp://url-id1:7222' '-topic' TEST1 'Hello World')) ALWMLTTHD(*YES)

where samplib is either the library where the product was restored using RSTLICPGM, or is adevelopment library you have used for compiling your own versions of the sample programs.

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 towhich 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 EMSMessaging Samples

Running Applications From Qshell

The Qshell environment provides an interactive display with a multi-threaded environment. ThetibemsMsgProducer sample program (SXJ3MP) is easily invoked using a symbolic link:

19


cd EMI_HOME/samples/c

followed by one of the following forms:

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

or

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

You can also invoke the tibemsMsgProducer sample program in either of the following two ways:

● From the QSYS File System:/QSYS.LIB/samplib.LIB/SXJ3MP.PGM-server tcp://url-id1:7222-topic TEST1 'Hello World'

● Using the system Qshell Utility:system "CALL PGM(samplib/SXJ3MP)PARM('-server' 'tcp://url-id1:7222''-topic' TEST1 'Hello World')"

Running Applications and RPG Sample ProgramsYou can run the provided RPG sample programs to send and receive messages using TIBCO EMS.

Compiled versions of the RPG sample programs are available in the library where the product wasrestored using RSTLICPGM. You may also compile the RPG sample programs such that they are createdin a development library of your choice by following the instructions in Compiling and Binding RPGSample Programs.

The ILE RPG sample programs are multi-threaded applications, and must be run from subsystems thatare enabled for multi-threading.

Ensure that you have set the following environment variable to enable multi-threaded jobs in Qshell:

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

The *SYS environment variable might also be set at the *JOB level.

You can execute these jobs with the following command examples:

● Executing From Qshellsystem "CALL PGM(samplib/SXJRMP) PARM('-server' 'server:port''-destination' 'my-dest' 'message')"

The following are additional command examples show how to invoke the RPG samples fromQshell:

● system "CALL PGM(samplib/SXJRMP) PARM('-server' 'server:port''-destination' 'my-dest' 'message')"

● system "CALL PGM(samplib/SXJRMC) PARM('-server' 'server:port''-destination' 'my-dest' )"

● system "CALL PGM(samplib/SXJRAMC) PARM('-server' 'server:port''-destination' 'my-dest' )"

● Submitting to BatchSBMJOB CMD(CALL PGM(samplib/SXJRMP) PARM('-server' 'server:port''-destination' 'my-dest' 'message')) LOG(4 0 *SECLVL) ALWMLTTHD(*YES)

where:

samplib

The name of the library where the product was restored using RSTLICPGM, or the name of adevelopment library you have used for compiling your own versions of the sample programs.

20


server:port

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

-destination

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

my-dest

The name of the topic or queue that you want to use. This name must match the topic or queue namein the consumer and producer.

message

The message to send. The current RPG sample programs do not allow embedded blanks.

The RPG samples are logging their output to printer file QSYSPRT. A second printer file, QPRINT, iscreated with output from the C API, tibemsMsg_Print(). When executing the samples in batch, theprinter files are spooled to your output queue.

When executing the samples interactively in the Qshell environment, the printer files display to yourscreen if the application ends correctly and the files are closed properly. Otherwise, the printer files arespooled.

Running the Data Conversion Plug-in SampleAn RPG sample and corresponding file are provided with a TIBCO ActiveMatrix BusinessWorksproject. You can run the project to interchange data of any form between platforms.

The source for the sample exists both in the TIBCO EMS Client for IBM i product library and in theIntegrated File System (IFS), and is also provided pre-compiled in the product library:

EMI_HOME/samples/dcp/rpg/EMSRDCP1.rpgle

You can find the TIBCO ActiveMatrix BusinessWorks project in the EMI_HOME/samples/dcp/am_bw/AM_BW_Mainframe_Sample_Project.zip file.

Procedure

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

2. Extract the ZIP file.

3. Open the project in TIBCO Designer.

4. Change the value of the JmsProviderUrl global variable to the name of the server where your EMSserver is configured and running.For example, tcp://glatona-dt:7222.

5. From the Tester tab, select and load the Receive-Send RPG Bytes message from the ProcessExamples.

This places the project in receive mode.

6. Switch to the IBM i machine, and run 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, asspecified in Step 4 .This program sends a bytes message made up of various data types and content to theBusinessWorks project and waits for a response with modified data from BusinessWorks.

21


Running Applications and COBOL Sample ProgramsYou can run the provided COBOL sample programs to send and receive messages using TIBCO EMS.

Compiled versions of the COBOL sample programs are available in the library where the product wasrestored using RSTLICPGM. You may also compile the COBOL sample programs such that they arecreated in a development library of your choice by following the instructions in Compiling and BindingCOBOL Samples.

The COBOL sample programs have been written simply by writing their output using the DISPLAYstatement to the *EXT queue which in effect is writing to the job log. If you want to see this informationfor batch jobs, you must have access to the job log.

You can run the COBOL sample programs either from Qshell or from batch:

● Executing the EMS COBOL Sample Programs from Qshell

● Submitting to Batch

For samples that are executed from Qshell, you only see the output of the DISPLAY at job end. If the jobis written as a never ending job, such as the consumer samples, you cannot see the output of theDISPLAY until the job ends.

Executing the EMS COBOL Sample Programs from QshellWhen you run the COBOL sample programs from Qshell, you can either run the message producer orthe message consumer.

Executing the Message Producer

To execute the message producer, SXJCMP (corresponds to tibemsMsgProducer), in Qshell and sendmessages, follow the steps from a 5250 terminal. Note that each line is entered separately.qsh <= from Command Entry screen> /qsys.lib/samplib.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.

Executing the Message Consumer

To execute the message consumer, SXJCMC (corresponds to tibemsMsgConsumer), in Qshell andreceive messages, follow the steps from a 5250 terminal. Note that each line is entered separately.qsh <= from Command Entry screen> system "call samplib/sxjcmc" <= another way to run consumer> server tcp://url-id1:7222 <= enter your EMS server and port> queue testq <= enter your destination queue or topic> <= ENTER ends the input process

To send more messages, return to your first monitor and enter the following:> /qsys.lib/samplib.lib/sxjcmp.pgm> server tcp://url-id1:7222> queue testq> text new message>$

22


Submitting to BatchYou can also submit the provided COBOL sample programs to batch. If submitting these programs tobatch, 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 the product library. Asample QINLINE contains 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

Edit the file member prodlib/QINLINE(QINLINE) to update the server and queue information beforesubmitting the programs in batch.

Both the consumer and producer can be submitted to batch or a combination of batch and Qshell can beused.

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

● Submit the producer to batch:SBMJOB CMD(CALL PGM(samplib/SXJCMP)) INLLIBL(samplib prodlibQGPL) ALWMLTTHD(*YES)

● Submit the consumer to batch:SBMJOB CMD(CALL PGM(samplib/SXJCMC)) INLLIBL(samplib prodlibQGPL) ALWMLTTHD(*YES)

Binding an Application to the Correct Version of EMS ClientsIf you have multiple versions of the EMS clients installed, you can bind your application statically ordynamically to a service program.

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

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

● Software Release 8.3.0 in product library TIBEMS830

● Software Release 8.4.0 in product library TIBEMS840

Bind Statically

To bind the application statically to one specific service program, for example, to bind to softwarerelease 8.4.0, run the following command:CRTPGM PGM(samplib/SXJ3MP) MODULE(samplib/SXJ3MP samplib/SXJ3UTIL)BNDSRVPGM((TIBEMS840/LIBTIBEMS)) ACTGRP(*NEW)

where samplib is your development library.

23


Bind Dynamically

To bind the application dynamically, add one of the product libraries to the library list, and then bindthe program. Therefore, you can control which version of the EMS client is used by modifying thelibrary list. For example:ADDLIBLE TIBEMS840CRTPGM PGM(samplib/SXJ3MP) MODULE(samplib/SXJ3MP samplib/SXJ3UTIL)BNDSRVPGM((*LIBL/LIBTIBEMS)) ACTGRP(*NEW) TGTRLS(*CURRENT)

where samplib is your development library.

To check how your application has been bound, run the following command to see in which libraryservice program LIBTIBEMS is found:

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

Compiling and Binding C Sample ProgramsThis section shows how to compile and bind the provided C sample programs.

You can find the client header files that are required when developing your applications in theEMI_HOME/include directory. The C sample program source is located in the EMI_HOME/samples/cdirectory.

The following standard ILE C Compiler commands are used:

● CRTCMOD: create a C module

● CRTPGM: create a program

You can compile the C sample programs using native compiler commands or the provided make.shscript. The following are examples on how to compile C sample programs:

● Compiling a Single Sample Program Using Native Compiler Commands

● Compiling All Sample Programs Using the make.sh Script

Compiling All Sample Programs Using the make.sh ScriptThis section contains the instructions on how to compile all the C sample programs using the providedmake.sh script.

Procedure

1. Start the Qshell environment:QSH

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

3. Run the make.sh script:/bin/sh ./make.sh

The make.sh script in the EMI_HOME/samples/c directory creates the C sample programs using thefollowing default settings:

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

● The EMS client binds the C samples with the LIBTIBEMS service program located in theTIBEMSLIB library.

● The target release of the resulting program object is *CURRENT

24


4. Optional: If you want to change any of these default settings, export the following environmentvariables prior to running the make.sh script:

● Use the COMPILELIB environment variable to change where the object modules and programobjects are created.

● Use the CLIENTLIB environment variable to change where the LIBTIBEMS service program islocated.

● Use the TGTRLS environment variable to change the target release of the resulting program.

For example:export COMPILELIB=MYDEVLIBexport CLIENTLIB=MYEMSLIBexport TGTRLS=V7R1M0/bin/sh ./make.sh

5. To remove all *PGM and *MODULE objects, as well as all *SYMLNK related to the sample program,run the following:cd EMI_HOME/samples/c

/bin/sh ./make.sh clean

where COMPILELIB environment variable is set to the name of the library specified previously.

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

Compiling a Single Sample Program Using Native Compiler CommandsThis section contains different examples on how to compile a single C sample program by using thenative compiler commands.

SXJ3UTIL contains helper functions used by the other samples to handle common activities. You haveto compile it ahead of the other samples so that it may be bound together with them.CRTCMOD MODULE(samplib/SXJ3UTIL)SRCSTMF('EMI_HOME/samples/c/tibemsUtilities.c') ENUM(4)INCDIR('EMI_HOME/include' 'EMI_HOME/samples/c')

Example of CRTCMOD

CRTCMOD MODULE(samplib/SXJ3MP)SRCSTMF('EMI_HOME/samples/c/tibemsMsgProducer.c') ENUM(4)INCDIR('EMI_HOME/include')

where samplib is the name of your development library.

Example of CRTPGM

CRTPGM PGM(samplib/SXJ3MP) MODULE(samplib/SXJ3MP samplib/SXJ3UTIL)BNDSRVPGM((prodlib/LIBTIBEMS)) ACTGRP(*NEW)

Compiling and Binding COBOL SamplesThis section shows how to compile and bind the provided COBOL sample programs.

You can find the COBOL sample program source and copybooks in both the QCBLLESRC sourcephysical file of the product library, and in IFS directory EMI_HOME/samples/cobol.

The following standard ILE COBOL Compiler commands are used:

● CRTCBLMOD: create a COBOL module


25


Example of CRTCBLMOD

ADDLIBLE TIBEMSLIBCRTCBLMOD MODULE(samplib/SXJCMC) SRCFILE(prodlib/QCBLLESRC)OPTION(*APOST *NOMONOPRC) LINKLIT(*PRC)

where samplib is the name of your development library.

Example of CRTPGM

CRTPGM PGM(samplib/SXJCMC)MODULE(samplib/SXJCMC prodlib/SXJ3SIN prodlib/MF@COBOL)BNDSRVPGM(prodlib/LIBTIBEMS) ACTGRP(*NEW)

Modules SXJ3SIN and MF@COBOL have been compiled and are provided in the product library.

Compiling and Binding RPG Sample ProgramsThis section shows how to compile and bind the provided RPG sample programs.

You can find the RPG sample program source in both the QRPGLESRC source physical file of theproduct library, and in IFS directory EMI_HOME/samples/rpg.

The following standard ILE RPG Compiler commands are used:

● CRTRPGMOD: create an RPG module


Example of CRTRPGMOD

ADDLIBLE TIBEMSLIBCRTRPGMOD MODULE(samplib/SXJRUT) SRCFILE(prodlib/QRPGLESRC)CRTRPGMOD MODULE(samplib/SXJRMP) SRCFILE(prodlib/QRPGLESRC)

SXJRUT contains helper procedures used by the other samples to handle common activities. You mustcompile it ahead of the other samples so that it may be bound together with them.

Example of CRTPGM

CRTPGM PGM(samplib/SXJRMP) MODULE(samplib/SXJRMP samplib/SXJRUT) ENTMOD(*PGM)BNDSRVPGM(prodlib/LIBTIBEMS) ACTGRP(*NEW)

26


TIBCO EMS Messaging Samples

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

● C Sample Programs

● RPG Sample Programs

● Source Code

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 areadded by the make.sh script for each sample program.

Type of EMS SampleIFS SourceFilename

Native Programand ModuleName

Program Name UnderQshell

Asynchronous MessageConsumer

tibemsAsyncMsgCon

sumer.c

SXJ3AMC tibemsAsyncMsgConsumer

SXJ3AMC

Queue Browser tibemsBrowser.c SXJ3BR tibemsBrowser

SXJ3BR

Durable TopicSubscriber

tibemsDurable.c SXJ3DTSB tibemsDurable

SXJ3DTSB

Message Consumer tibemsMsgConsumer

.c

SXJ3MC tibemsMsgConsumer

SXJ3MC

Like SXJ3MC, but usesthe tibemsXAResourceinterface to consumemessages usingtransaction semantics.

tibemsXAMsgConsum

er.c

SXJ3XAMC tibemsXAMsgConsumer

SXJ3XAMC

Message Producer tibemsMsgProducer

.c

SXJ3MP tibemsMsgProducer

SXJ3MP

Like SXJ3MP, but usesthe classic X/Open DPTXA interface to sendmessages usingtransaction semantics.

tibemsXAMsgProduc

er.c

SXJ3XAMP tibemsXAMsgProducer

SXJ3XAMP

Message Consumerdemonstrating how toenumerate messageproperties and fields

tibemsMsg.c SXJ3MSG tibemsMsg

SXJ3MSG

27


Type of EMS SampleIFS SourceFilename

Native Programand ModuleName

Program Name UnderQshell

Helper functions usedby other samples tohandle commonactivities

tibemsUtilities.c SXJ3UTIL tibemsUtilities

SXJ3UTIL

tibemsMsgProducerPerf

tibemsMsgProducer

Perf.c

SXJ3MPPF tibemsMsgProducerPerf

SXJ3MPPF

tibemsMsgConsumerPerf

tibemsMsgConsumer

Perf.c

SXJ3MCPF tibemsMsgConsumerPerf

SXJ3MCPF

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

Type of EMSSample

RPG Source Filenameand Short Name Description

AsynchronousMessage Consumer

tibemsAsyncMsgConsum

er

SXJRAMC

An example demonstrating the use of anasynchronous message consumer, using Cfunctions, operating on non-typed connectionsand sessions.

This sample registers a listener on the specifiedtopic or queue, and prints all messagesasynchronously received on that destination. Thedestination (specified as a parameter) must existin the topics or queues configuration files, or theconfiguration files allows dynamic creation ofthat destination.

The sample configuration distributed with TIBCOEnterprise Message Service allows creation of alltopics and queues.

Queue Browser tibemsBrowser

SXJRBR

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

Durable TopicSubscriber

tibemsDurable

SXJRDTSB

A simple durable topic subscriber.

If started with -unsubscribe parameter, itunsubscribes the specified durable subscriber,and exits. Otherwise, it creates a durablesubscriber on the specified topic, and receives andprints all messages published to that topic.

28


Type of EMSSample

RPG Source Filenameand Short Name Description

Message Consumer tibemsMsgConsumer

SXJRMC

An example demonstrating use of the messageconsumer, using C functions, operating on non-typed connections and sessions.

This sample synchronously consumes and printsall messages received on the specified topic orqueue. The destination (specified as a parameter)must exist in the topics or queues configurationfiles, or the configuration files allows dynamiccreation of that destination.

Sample configuration distributed with TIBCOEnterprise Message Service allows creation of alltopics and queues.

Message Producer tibemsMsgProducer

SXJRMP

An example demonstrating use of the messageproducer, using C functions, operating on non-typed connections and sessions.

This sample sends one or more text messages tothe specified topic or queue. The topic or queue(specified as a parameter) must exist in the topicsor queues configuration files, or the configurationfiles allows dynamic creation of that destination.

The sample configuration distributed with TIBCOEnterprise Message Service allows creation of alltopics and queues.

Source CodeThis section describes the source code for the sample programs.

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.

Source Code Location

C Sample Source Code EMI_HOME/samples/c

C Client Header Files EMI_HOME/include/tibems

RPG Sample Source Code EMI_HOME/samples/rpg and TIBEMSLIB/QRPGLESRC

COBOL Sample Source andCopybooks

EMI_HOME/samples/cobol and TIBEMSLIB/QCBLLESRC

Data Conversion Plug-in SampleSource Code

EMI_HOME/samples/dcp/rpg and TIBEMSLIB/QRPGLESRC

29


EMS Client Programming in RPG

Use the information in this section as a guide when you extend the prototype file, and when you codeEMS Client programs in RPG.

Coding your own applications in RPG requires that you extend the prototype file to include all theTIBCO Enterprise Message Service calls that your application uses.

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

The following table guides the translation from C to RPG. Each section of the table addresses a specifictype of parameter passing in C, followed by the equivalent constructs in RPG.

When C Passes a Non-String by Value

C Prototype foo(int order)

C Program Call int order;

foo(order);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

d foo pr

d order 10i 0 value

RPG ProgramCall

...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

D order S 10i 0 inz(37)

C callp foo(order)

When C Passes a Non-String by Reference

C Prototype foo(int* order)

C Program Call int order;

foo(&order);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

d foo pr

d order 10i 0

RPG ProgramCall

...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

D order S 10i 0 inz(37)

C callp foo(order)

When C Passes a String by Value

C Prototype foo(char* desc)

30


C Program Call char* desc;

foo(desc);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

d foo pr

d desc * value

RPG ProgramCall

...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

D foo S 11A

/free

desc = 'TIBRVLISTE' + X'00';

foo(%addr(desc));

/end-free

When C Passes a String by Reference

C Prototype foo(char** desc)

C Program Call char* desc;

foo(&desc);

RPG Prototype ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

d foo pr

d desc *

RPG ProgramCall

...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5

D foo S 11A

D pDesc S * inz(%addr(desc))

/free

desc = 'TIBRVLISTE' + X'00';

foo(%addr(pDesc);

/end-free

31


Installed Objects

This section 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@COBOL

SXJ3SIN

Utility modules for binding into COBOL sample programs

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

SXJ3AMC

SXJ3BR

SXJ3DTSB

SXJ3MC

SXJ3MCPF

SXJ3MP

SXJ3MPPF

SXJ3MSG

SXJ3XAMC

SXJ3XAMP

Precompiled C sample programs

SXJCMC

SXJCMP

Precompiled COBOL sample programs

SXJRAMC

SXJRBR

SXJRDTSB

SXJRMC

SXJRMP

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

32


Object Description

EMSSYMLNKS *PGM used by RSTLICPGM and DLTLICPGM for handling directory pathEMI_HOME/...

TIBEMSMSGF

TIBEMSvrm

TIBEMSvrm

*MSGF

*PRDDFN

*PRDLOD

Other objects required by RSTLICPGM and DLTLICPGM

Objects in the IFS file system

The following objects are installed in the IFS file system.

Location Installed Objects

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

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

EMI_HOME/samples/cobol COBOL source and copybooks for COBOL applicationdevelopment

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

EMI_HOME/samples/dcp/rpg RPG source and include file for Data Conversion Plug-insample

EMI_HOME/samples/dcp/am_bw TIBCO ActiveMatrix BusinessWorks example forrunning with the RPG Data Conversion Plug-in sample

EMI_HOME/samples/certs Sample digital certificates that are compatible with theDigital Certificate Manager

33


Documents

TIBCO EMS Client for IBM i Installation and Reference · PDF fileExecuting the EMS COBOL Sample Programs from Qshell ... The database is called DB2. ... character string *PGM;