tibco ems client for z/os (cics) installation and … 4 abend codes, ... jcl and general procedure...

TIBCO® EMS Client

for z/OS (CICS)

Installation and ReferenceSoftware Release 6.0July 2010

Important Information

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

| iii

Contents

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viiiTIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viiiTIBCO EMS Client for z/OS (MVS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viiiThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Language Environment (LE). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5POSIX(ON) Run-time Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5User Profile Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

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

Before Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Distribution Media and Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Obtaining the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Checklist for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11CICS Installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Uploading the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Initial Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Running the CICS Messaging Consumer Sample Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Running the CICS Messaging Producer Sample Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Running the MVS Batch Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Optional Installation Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Compiling C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Compiling COBOL Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

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

iv | Contents

Starting Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29User Profile Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 3 Using the TIBCO EMS Client for z/OS (CICS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32S7MASTUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33S7M3PASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34S7M3EMSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35S7MATRUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35S7M3CLUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36S7M3STRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36S7MACURT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36S7M3STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Understanding Component Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Administrative Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Programmer's Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49C Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 4 ABEND Codes, Return Codes, and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Message Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Message Description Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53CEET Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

ABEND Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

System Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Transaction Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Appendix A CICS Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Message Consumer and Producer Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

JCL and General Procedure Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Sample Program Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Appendix B Installed Data Set Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107


Tables | v

Tables

Table 1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Table 2 General Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Table 3 Installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Table 4 File Tailoring Variables for Installation JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Table 5 File Tailoring Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Table 6 Pre-Start Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Table 7 Administrative Command Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 8 ABEND Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Table 9 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Table 10 System Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Table 11 Transaction Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Table 12 Message Consumer/Producer Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 13 General JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Table 14 General Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Table 15 Installed Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107


vi | Tables


| vii

Preface

This manual describes how to install and configure the TIBCO EMS Client for z/OS (CICS) software and is intended for z/OS programmers who set up and maintain the system. It will also be useful for application programmers who develop TIBCO EMS applications in CICS. This document also serves as a reference for sample programs, installation content, and TIBCO EMS operations in the CICS region.

Topics

• Related Documentation, page viii

• How to Contact TIBCO Customer Support, page x


viii | Preface

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Enterprise Message Service DocumentationThe following documents form the TIBCO Enterprise Message Service 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 Rendezvous OS/390 with third-party products.

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

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

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

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

TIBCO EMS Client for z/OS (MVS)• TIBCO EMS Client for z/OS (MVS) Installation and Reference If you wish to run

the TIBCO EMS Client for z/OS in a batch environment, refer to this manual for instructions on installion and operations.


Related Documentation | ix

Third Party DocumentationTable 1 lists IBM publications you may find useful. You can find many of the IBM documents in the following CD-ROM set:

• Online Library Omnibus Edition z/OS Collection

Table 1 Related Documents

Publication Title

IBM CICS Transaction Server for z/OS: CICS System Definition Guide

IBM CICS Transaction Server for z/OS: CICS Resource Definition Guide

IBM TCP/IP for OpenEdition MVS Applications Feature Guide

IBM Language Environment Programming Reference

IBM Online Library Omnibus Edition z/OS Collection


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

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

http://support.tibco.com

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


| 1

Chapter 1 Introduction

This manual provides information about the product TIBCO EMS Client for z/OS (CICS). It is intended primarily for programmers who are responsible for installing and maintaining the software. The information contained here will also be useful for application programmers involved in creating or modifying programs that work in conjunction with this product. TIBCO Software recommends that you read through this manual before attempting to install the product and that you keep a copy of this manual handy for future reference.

Topics

• Overview, page 2

• System Requirements, page 4


2 | Chapter 1 Introduction

Overview

The TIBCO EMS Client for z/OS (CICS) software allows applications running in CICS Transaction Server 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 CICS environment under z/OS, act as intermediaries for messages and route them to recipients. This message flow is illustrated in the diagram below:

Figure 1 CICS Application and TIBCO EMS Messaging

A CICS application participates in this messaging environment as follows:

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

2. The TIBCO EMS Client for z/OS (CICS) establishes connections to a TIBCO EMS server using standard TCP/IP (not CICS sockets).

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

4. Other TIBCO EMS clients exchange messages with the CICS application via the TIBCO EMS server.

TIBCO EMS API function calls are coded by programmers and included into the CICS application at compilation time. The product <USERHLQ>.LIBRARY dataset contains the objects that are included during the pre-link step of a compilation.

TIBCO EMS Client for

z/OS (CICS)

CICS

TIBCOEMSClient

TIBCOEMSClient

TIBCOEMSClient

TIBCOEMS

Server

UserApplication


Overview | 3

For details on the components that comprise the TIBCO EMS Client for z/OS (CICS), see System Architecture on page 32.

Refer to TIBCO Enterprise Message Service User’s Guide for a complete description of TIBCO EMS operations.

LimitationsThis version of the TIBCO EMS Client for z/OS (CICS) does not support the following:

• SSL (Secure Sockets Layer)

• Asynchronous message consumption

• Administration

• Assembler language



System Requirements

The product is supported on z/OS 1.7 and later (64-bit), including all z/OS versions currently supported by IBM. CICS Transaction Server 3.x.

Before installing the product in a CICS environment under z/OS, you must ensure that the following are installed and properly configured:

Storage RequirementsThe TIBCO EMS Client for z/OS (CICS) requires approximately 200 cylinders of Direct-Access Storage Device (DASD) space. This space calculation is based on IBM 3390 DASD devices.

TCP/IPThe TIBCO EMS Client for z/OS (CICS) 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 within the z/OS Communications Server.

• A DNS server that provides the hostname and host address of the z/OS client and the TIBCO EMS Server.

• Unrestricted network connectivity between the DNS, the TIBCO EMS Client for z/OS (CICS), and the TIBCO EMS Server.

Customers should be running a properly configured RESOLVER address space.

Customers should review their TCPCONFIG parameters to ensure that they meet the installation’s needs. If the customer chooses to run the TIBCO EMS Client for z/OS (CICS) non-APF authorized, the RESTRICTLOWPORTS parameter should be used. If customers want to control TCP buffering, to limit storage usage, or to support large bandwidth devices, the TCPSENDBFRSIZE, TCPRCVBUFRSIZE, and TCPMAXRCVBUFRSIZE parameters may be needed. TIBCO typically recommends customers override the IBM default of 16K by setting TCPRCVBUFRSIZE and TCPSENDBFRSIZE to a minimum value of 48K.


System Requirements | 5

Language Environment (LE)LE is the language environment. The Assembler, C and COBOL for MVS compilers are required for application development under this environment.

You must ensure the CICS region is LE enabled, and that the CICS region startup JCL and procedures include the LE run-time libraries.

Note that IBM TCP uses the OE socket interface. Therefore, all user ids running EMS client programs must have an OMVS UID and GID. Define these values in the OMVS segment of the USERID and GROUP records in RACF.

For more information, see User Profile Requirements on page 29.

POSIX(ON) Run-time OptionTIBCO EMS Client for z/OS (CICS) requires that it be able to creates a TCB with POSIX(ON) in the CICS address space. Due to a z/OS limitation, only one TCB in an address space can have the POSIX(ON) run-time option. If you have other software that also requires this run-time option, that software and TIBCO EMS Client for z/OS (CICS) will have to be in separate CICS regions.

For additional information on POSIX, refer to IBM Language Environment Programming Reference.

User Profile RequirementsThe CICS region started task must have a unique userid assigned by the RACF STARTED class or the ICHRIN03 started procedure table. The userid assigned must have a valid z/OS Unix security context, or OMVS segment, in both the userid profile and group profile. This can be accomplished by defining OMVS segments for the assigned userid and group, or by utilizing the BPX.DEFAULT.USER FACILITY class profile. If customers are using the BPX.DEFAULT.USER FACILITY class profile, IBM recommends that customers avoid running the associated started tasks as either privileged or trusted.

For details on user profile requirements, see Starting Applications on page 29.


| 7

Chapter 2 Installation

This chapter describes how to install the TIBCO EMS Client for z/OS (CICS) software.

Topics

• Before Installation, page 8

• Distribution Media and Contents, page 9

• Checklist for Installation, page 11

• Uploading the Software, page 13

• Installing the Software, page 15

• Verifying the Installation, page 21

• Optional Installation Changes, page 27

• Starting Applications, page 29


8 | Chapter 2 Installation

Before Installation

The table below provides a checklist of variables and data set HLQs (High Level Qualifiers) that you should obtain before performing the installation. All JCL and procedures supplied with the TIBCO EMS Client for z/OS (CICS) have a standard naming convention. You must replace TIBCO site-specific, installation-defined variables, such as JCL SET statements, procedure overrides, SYSIN data, and system data set HLQ with user values. You must also replace TIBCO Software variables before the JCL can be submitted for execution.

It is recommended that you copy of the table below, review, and complete the entries. Column headings are defined as follows:

Description—provides instructional information.

Variable—provides the variable name as it will appear in the provided JCL and the member names. There may be several instances of the same variable within a specific member.

User Value—insert the appropriate values for your site.

Table 2 General Variables

Description Variable User Value

Obtain a High Level Qualifier for your TIBCO EMS libraries. Typically, TIBCO.S7M is used.

<USERHLQ>

Obtain a hard disk Volume Serial where the TIBCO EMS files are to be installed.

<USERVOL>

Replace these <JOBNAME> variables with user define values.

<JOBNAM>


Distribution Media and Contents | 9

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 in IBM XMIT format.

Complete Replacement Package

By default, the TIBCO EMS Client for z/OS (CICS) software is delivered as a non SMP/E stand-alone, base function package. Subsequent modifications and updates are version and product dependent. Therefore, a complete product replacement is preformed with each installation.

Component Code

The component code for the TIBCO EMS Client for z/OS (CICS) is S7M . This component code is registered with the IBM product codes division.

Obtaining the SoftwareTo obtain the software, you can download it directly from the TIBCO Software web site, or you can request the software on CD.

Downloading from the Web Site

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

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

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

• Download the appropriate files, which are in the standard IBM XMIT format.

Product Installation Files for z/OS Version 1.7 and Later

TIBCO EMS Client for z/OS (CICS) for DFSMSdss

Download this file:

TIB_ems_6.0.0_zos18_cics.xmit.zip

The zip file contains these files:

TIB_ems_6.0.0_zos18_cics.xmit.instTIB_ems_6.0.0_zos18_cics.xmit.main



Requesting a CD

If you do not want to download the software over the network, you can obtain a CD containing the software and load it directly onto your system. The minimum time period for delivery of a CD is five working days. Contact TIBCO Support and request the desired media for your environment. For details, see How to Contact TIBCO Customer Support on page x.

Obtaining the Software for Non DFSMSdss Sites

The installation package is provided by request only for all versions of OS/390 or z/OS. For details, contact TIBCO Support.


Checklist for Installation | 11

Checklist for Installation

The table below provides a checklist of variables or required items that should be obtained before performing the installation process. The data set suffix and member names are included as reference to where they occur. Column headings are defined as follows:

Description—provides instructional information.

Suffix—lists the suffix of the data set containing the reference.

Member—contains the variable in question. There may be several instances of the same variable within a specific member.

CICS Installation ChecklistThe TIBCO EMS Client for z/OS (CICS) provides the following programs:

S7MACURT Parameters for starting the CEET. For details, see S7MACURT on page 36

DFHPLTXI A DFHPLT is provided if you do not have one. This startup PLT links to program S7M3STRT, which initiates the CICS EMS Execution Environment using the parameters set in S7MACURT. This is an optional PLT change that is only needed if starting the CEET automatically with CICS initialization is desired. For additional details, see S7M3STRT on page 36

DFHPLTXD A DFHPLT is provided if you do not have one. This shutdown PLT links to program S7M3STOP, which shuts down the CICS EMS Execution Environment correctly. For additional details, see S7M3STOP on page 37.

DFHPEP CICS programs that use the TIBCO EMS Client for z/OS (CICS) need to use the DFHPEP exit to analyze CICS transaction abends and provide recovery of the CICS transaction.

Table 3 Installation Checklist

Description Suffix Member

If you are transferring the installation files from a server, obtain the IP address or server name for the FTP process.

INSTALL S7M$3FTS7M$3FT@

Obtain the data set and or member name where your site FTPDATA information resides.

INSTALL S7M$3FTS7M$3FT@



For details on the use of these programs in the installation, see Steps 10, 11, and 12 of Installing the Software on page 15.

LINKPACK: module S7M3EMSS cannot be put in the LINKPACK (LPA) area.


Uploading the Software | 13

Uploading the Software

If you have acquired the TIBCO EMS Client for z/OS (CICS) software by downloading it from the TIBCO Software web site, you must upload the software to the z/OS host system using the FTP utility. Sample JCL to transfer the initial installation file is shown below.

Initial Installation

Sample JCL for FTP Upload

This sample JCL uses IBM's FTP to copy the initial installation file from a LAN server or PC to the z/OS CICS host.

//<JOBNAM> JOB (&SYSUID),'EMS FTP',CLASS=A//*// SET FTPADDR=10.10.2.99 < IP Address or Host Name//*//FTP EXEC PGM=FTP,REGION=0M,PARM='&FTPADDR (TIMEOUT 20'//SYSPRINT DD SYSOUT=* //OUTPUT DD SYSOUT=* //SYSTCPD DD DISP=SHR,DSN=TCPIP.PROFILE(FTPDATA) < Host Member //INPUT DD * <lan-userid> <lan-password> cd /<lan-file-dir> binary LOCSITE RECFM=FB LRECL=80 BLKSIZE=27920 TR PRI=60 SEC=15 get <userhlq>.xmit.inst' <USERHLQ>.XMIT.INST' (REPLACE quit //*



Receive the Initial Installation File

The <USERHLQ>.XMIT.INST file contains JCL that is required to receive other files and to create the appropriate libraries. To complete this process, the TIBCO-supplied variables must be substituted with the appropriate site-specific user values.

Perform the following steps:

1. From the ISPF Command Shell Panel, type the following command to receive a file containing the JCL required to begin a first-time installation:

receive inda('<USERHLQ>.XMIT.INST')

TSO prompts you with the following:

INMR906A Enter restore parameters or 'DELETE' or 'END' +

2. Supply the following:

DA('<USERHLQ>.INSTALL')

After a successful receive, the following message is displayed:

INMR001I Restore successful to dataset '<USERHLQ>.INSTALL'

The data set name supplied in step 2 is output and populated with the members that are required in order for you to continue with the installation.

This step must be performed during a TIBCO EMS Client for z/OS (CICS) installation on the z/OS MVS host.


Installing the Software | 15

Installing the Software

The following steps are required to install the CICS components for the TIBCO EMS Client for z/OS (CICS) product. All members used in Steps 1 – 7 reside within the <USERHLQ>.INSTALL dataset.

Edit the selected members listed in the steps below. Substitute the variables, follow any instructions contained in the member, and then submit the JCL for execution.

Table 4 defines the user substitution variables for the installation JCL.

STEP 1: Make CLIST temporary file

Change the #JOBNAME, #USERHLQ, #USERVOL statement variables according to your sites requirements.

Member: S7M$1MKT

Table 4 File Tailoring Variables for Installation JCL

Variable Default and Structure User Value

USERHLQ TIBCO.S7M.VxRxMx

VOLSERVolume Serial

TIB999

JOBNAME S7MEMSFirst 6 characters

STEP 2: Execute file tailoring CLIST for installation JCL

If an error is made during input, press the attention key (PA1) and execute starting at Step 1 again.

Member: S7M$2EX1 (EX member)



STEP 3: Upload the TIBCO EMS Client for z/OS (CICS) installation files to your host

Upload the files via FTP to your host

Member: • For DFSMSdss sites, use S7M$3FT

• For non DFSMSdss sites, use S7M$3FT@

STEP 4: Define and allocate the TIBCO EMS Client for z/OS (CICS) product libraries

Only to be performed on initial installation

Member: S7M$4ALL

STEP 5: Convert the TIBCO EMS Client for z/OS (CICS) installation files to DFSMS dump format

Member: • For DFSMSdss sites, use S7M$5RC

• For non DFSMSdss Sites, use S7M$5RC@



Table 5 defines the user substitution variables within JCL and parameter members that are required during the file tailoring process. Ensure that you have all the necessary information before executing this step.

After completing Step 7, you have finished using the INSTALL library. Most of the subsequent steps are located within the JCL library.

Table 5 File Tailoring Variables

Variable Default and Structure User Value

IBM Assembler

Libraries HLQ

ASM

*.SASMMAC2

COBOL for MVS

Libraries HLQ

IGY

*.SIGYCOMP

TIBCO EMS Server Location

hostname: 7222

CICSHLQ

CICS System Libraries HLQ

CICSTS31.CICS

*.CICS.SDFHLOAD

CCSDHLQ

CICS DFHCSD HLQ

CICSTS31.REGION

*.DFHCSD

STEP 6: Execute file tailoring CLIST to update the product supplied variables

If an error is made during input, press the attention key (PA1) and execute the CLIST again.

Member: S7M$6EX2 (EX member)

STEP 7: Populate the TIBCO EMS Client for z/OS (CICS) product datasets with all the updates

Member: S7M$7UPD



STEP 8: CICS: Update CICS interface resource definitions

This member updates the CICS System Definition (CSD) file with the Resource definitions necessary for TIBCO EMS Client for z/OS (CICS) to operate.

Data Set:

Member:

<USERHLQ>.JCL

S7MTSCSD

STEP 9: CICS: Update startup procedure

The <USERHLQ>.AUTH library that is installed as part of TIBCO EMS Client for z/OS (CICS) must be concatenated in the STEPLIB DDNAME of your CICS startup procedures.

Data Set:

Member:

<Your CICS startup procedure data set>

<Your CICS startup procedure>

STEP 10: CICS: Setup startup and shutdown PLTs

A DFHPLT is provided if you do not have one. This startup PLT links to program S7M3STRT, which brings up the CICS EMS Execution Environment. You must also add the following statement to your SIT:

PLTPI=XI

If you have a DFHPLTXI, the following must be added to the second phase (after DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM):

DFHPLT TYPE=ENTRY,PROGRAM=S7M3STRT

Submit the JCL S7MASMLK to setup the TIBCO default PLT. This job will create module DFHPLTXI in the load library.



A DFHPLT is provided if you do not have one. This shutdown PLT links to program S7M3STOP, which brings down the CICS EMS Execution Environment. You must also add the following statement to your SIT:

PLTSD=XD

If you have a DFHPLTSD, the following must be added to the second phase (after DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM):

DFHPLT TYPE=ENTRY,PROGRAM=S7M3STOP

Submit the JCL S7MASMLK to setup the TIBCO default PLT. This job will create module DFHPLTXD in the load library.

Data Set:

Member:

<USERHLQ>.ASM

DFHPLTXI and DFHPLTXD

STEP 11: CICS: Setup error program exit

CICS programs that use the TIBCO EMS Client for z/OS (CICS) need to use the DFHPEP exit to analyze CICS transaction abends and to provide recovery of the CICS transaction. If you are already using DFHPEP, then you must merge TIBCO’s DFHPEP with your code. If you are not using DFHPEP (or using the IBM default), compile the TIBCO DFHPEP (C program) into a loadlib concatenated in the CICS DFHRPL.

Submit the JCL S7M3JCPL to assemble the DFHPEP program. The load module will be put into the load library. Make sure this is the first DSN in the steplib, or replace DFHPEP in the STEPLIB concatenation list so this version of DFHPEP is used by CICS.

Data Set:

Member:

<USERHLQ>.C

DFHPEP



STEP 12: CICS: Setup default CEET parameters

Review the default parameters for starting the CEET.

• HOSTPAGE

• NETWORK

• MAXCONN

• MAXWORK

• TRACE

• URL

• USERID

• PASSWORD

For details, see S7MACURT on page 36.

CICS program sets up the CEET startup default parameters. Submit the JCL S7M3JCPL to assemble the S7MACURT program. The load module will be put into the load library.

Data Set:

Member:

<USERHLQ>.ASM

S7MACURT


Verifying the Installation | 21

Verifying the Installation

Use the checklist in Table 6 to ensure that you have specified all the required settings to establish communications between the TIBCO EMS Client for z/OS (CICS) and the TIBCO EMS server.

To verify that TIBCO EMS Client for z/OS (CICS) has been correctly installed and configured, perform the following actions from within the CICS region:

• Run the CICS messaging consumer sample program by invoking the appropriate transaction (you can run either the COBOL or C sample). For details, see Running the CICS Messaging Consumer Sample Program on page 22.

• Run the CICS messaging producer sample program by invoking the appropriate transaction (you can run either the COBOL or C sample). For details, see Running the CICS Messaging Producer Sample Program on page 24.

This product also includes a sample MVS consumer and producer for batch testing. The following actions are optional:

• Run the TIBCO EMS messaging consumer batch program by running the appropriate startup JCL.

• Run the TIBCO EMS messaging producer batch program by running the appropriate startup JCL.

For details, see Running the MVS Batch Services on page 26.

Table 6 Pre-Start Checklist

Requirement Check

Is the <USERHLQ>AUTH library APF-authorized?

Has the <USERHLQ>AUTH library been concatenated to the STEPLIB DDNAME of your CICS startup procedures?

Is the TIBCO EMS server running? Can you ping the IP address where the server is located or the DNS name from your host?

Have you restarted your Transaction Server region?



Running the CICS Messaging Consumer Sample ProgramYou can run either the COBOL or C sample program.

COBOL

To run this sample, invoke the S7CC transaction.

1. Starting with a blank screen, input S7CC. The following screen displays:

2. Specify the following (all fields are case-sensitive):

SERVER: URL of the TIBCO EMS serverDestination: Message destination type: 1 = queue, 2 = topicDestination: Name of the queue or topic.User Name: Authentic user name for TIBCO EMS server, if neededPassword: Authentic password for TIBCO EMS server, if needed

3. Press Enter. If there is a problem setting up the Consumer process, an error message will appear below the lower line of dashes. An error could be caused by an invalid value in one of the fields; check field values and re-enter.

When the Consumer process starts, the message Waiting on receive first message... appears below the bottom line. The screen is now locked; when a message is received, the message text appears in the Message field.

Press Enter again to receive subsequent messages, or press PF3 to exit. If you wish to clear values from the fields, press PF5.



C Language

To run this sample, invoke the S73C transaction at the command line, using the following syntax:

S73C -server server {-topic topic name | -queue queue name}-user username -password password

Parameters (CICS translates parameter values to uppercase):

The following example invokes a Consumer that connects to a server with the URL emsserverurl:7222 and listens on the topic my.topic.name:

S73C -server emsserverurl:7222 -topic my.topic.name

An error message displays if there is a problem setting up the Consumer process. An error could be caused by an invalid parameter value; check the parameter values and re-enter.

When the Consumer process starts, the screen is locked, waiting for a message. Messages received by the Consumer are printed to DDNAME CEEOUT. To stop the Consumer process, send the Consumer a TIBCO EMS text message that starts with STOP (uppercase), or stop the Work Thread using the S7MA transaction.

-server The URL of the TIBCO EMS server (CICS translates this to uppercase, the program reverts it to lowercase)

-topic If specifying a topic destination, the topic name.

-queue If specifying a queue destination, the queue name.

-username The username to connect to the TIBCO EMS server.

-password The password to connect to the TIBCO EMS server.



Running the CICS Messaging Producer Sample ProgramYou can run either the COBOL or C sample program.

COBOL

To run this sample, invoke the S7CP transaction.

1. Starting with a blank screen, input S7CP. The following screen displays:

2. Specify the following (all fields are case-sensitive):

SERVER: URL of the TIBCO EMS serverDestination: Message destination type: 1 = queue, 2 = topicDestination: Name of the queue or topic.User Name: Authentic user name for TIBCO EMS server, if neededPassword: Authentic password for TIBCO EMS server, if neededMessage: Text to be sent in the message.

3. Press Enter to send the message. If there is a problem setting up the Producer process, an error message will appear below the lower line of dashes. An error could be caused by an invalid value in one of the fields; check field values and re-enter.

To send subsequent messages, edit the field values and press Enter, or press PF3 to exit. If you wish to clear values from the fields, press PF5.



C Language

To run this sample, invoke the S73P transaction at the command line, using the following syntax:

S73P -server server {-topic topic name | -queue queue name}-user username -password password -text message text

Parameters (CICS translates parameter values to uppercase):

The following example invokes a Producer that connects to a server with the URL emsserverurl:7222 and sends the message this is a test on the topic my.topic.name:

S73P -server emsserverurl:7222 -topic my.topic.name-text this is a test

An error message displays if there is a problem setting up the Producer process. An error could be caused by an invalid parameter value; check the parameter values and re-enter.

Messages and other program information are printed to DDNAME CEEOUT. The Producer program produces a single message to the screen when it ends.

-server The URL of the TIBCO EMS server (CICS translates this to uppercase, the program reverts it to lowercase)

-topic If specifying a topic destination, the topic name.

-queue If specifying a queue destination, the queue name.

-username The username to connect to the TIBCO EMS server.

-password The password to connect to the TIBCO EMS server.

-text The text of the message.



Running the MVS Batch Services

TIBCO EMS Messaging Consumer Batch Program

This member initiates a TIBCO EMS consumer that receives messages from the producer. The JCL can be used to execute the C sample program.

Data Set: <USERHLQ>.JCLMember: RUNGMC

TIBCO EMS Messaging Producer Batch Program

This member initiates a TIBCO EMS producer that publishes a message to an executing consumer. The JCL can be used to execute the C sample program.

Data Set: <USERHLQ>.JCLMember: RUNGMP


Optional Installation Changes | 27

Optional Installation Changes

TIBCO EMS Client for z/OS (CICS) sample programs are supplied as source and executable modules as part of the installation. However, users may desire to change the source code to perform additional functions. JCL and procedures have been supplied to compile the sample programs that normally have to be modified to be used within a user's environment.

Edit the data sets and selected members listed in the steps below. Substitute the variables, follow any instructions that are contained in the member, and submit it for execution.

Compiling C Programs

Step 1a: C language options file

This member is the Options File used for TIBCO EMS C compiles that needs to include members from the system C and TIBCO EMS libraries.

Data Set:

Member:

<USERHLQ>.CNTL

OPTFS7MC

Step 1b: TIBCO EMS C language compilation JCL

The JCL listed below uses a procedure that may have to be modified so that it conforms to your site’s requirements and executes correctly.

Data Set:

Member:

<USERHLQ>.JCL

S7M3JCPL



Compiling COBOL Programs

Step 1c: TIBCO EMS COBOL compilation JCL

The JCL listed below uses a procedure that may have to be modified so that it conforms to your site's requirements and executes correctly. This member compiles COBOL supplied sample programs.

Data Set:

Member:

<USERHLQ>.JCL

S7MCJCPL


Starting Applications | 29

Starting Applications

User Profile RequirementsThe CICS region started task used to run the TIBCO EMS Client for z/OS (CICS) must have a unique userid assigned by the RACF STARTED class or the ICHRIN03 started procedure table. The userid assigned must have a valid z/OS Unix security context, or OMVS segment, in both the userid profile and group profile. Alternatively, the BPX.DEFAULT.USER FACILITY class profile, or equivalent if RACF is not used, can provide the appropriate z/OS Unix security context. Customers should have their z/OS security administrator verify proper setup prior to attempting to run the TIBCO EMS Client for z/OS (CICS).

TIBCO Software does not recommend establishing resource limits within the userid’s OMVS segment. Instead, the values specified in BPXPRMxx should be used where possible. Additionally, customers should avoid using UID 0 (superuser) in the OMVS segment of the userid assigned to the CICS region started task.

Case Sensitivity

TIBCO Messaging Applications

TIBCO messaging applications are case sensitive. Any application program that uses TIBCO EMS Client for z/OS (CICS) API calls must use the correct case when specifying the API call.


| 31

Chapter 3 Using the TIBCO EMS Client for z/OS (CICS)

This chapter describes the architecture and administration of the TIBCO EMS Client for z/OS (CICS). Before performing any administrative procedures, you must have completed the installation of the software, and have executed the IVP steps successfully (as described in Verifying the Installation on page 21).

Topics

• System Architecture, page 32

• Administrative Commands, page 42

• Programmer's Checklist, page 49


32 | Chapter 3 Using the TIBCO EMS Client for z/OS (CICS)

System Architecture

This section describes the architecture of the TIBCO EMS Client for z/OS (CICS). Within a CICS region, product components reside in two separate environments – an application environment, and an EMS execution environment, as shown below.

Figure 2 TIBCO EMS Client for z/OS (CICS) Main Components

The CICS EMS Execution Environment provides a task that is referred to by the acronym CEET (CICS EMS Execution Task).

CICS Application Environment

These product components perform the following:

• S7MASTUB – takes a TIBCO EMS function call and hands the call request to the S7M3PASS module.

• S7M3PASS – manages the interactions between CICS transactions and the CEET; also manages the run-time interactions to the CEET Work Threads

• S7MATRUE – releases CEET Work Threads upon transaction end.

• S7M3CLUP – an independent cleanup routine tied to transaction S7ML.

CICS LINK


CEET(CICS EMS

Execution Task)

S7MASTUB

Thin client layer passes request to

S7M3PASS

CICS EMS ExecutionEnvironment

CICS Region

S7M3PASS S7M3EMSSPOST and

WAIT routines

TIBCO EMS application

TIBCOEMS

Server


System Architecture | 33

CICS EMS Execution Environment

This environment provides the CEET, the primary component of which is module S7M3EMSS. This module executes all TIBCO EMS Client requests received from CICS transactions. Messages from the CEET are written to an output file called the CEET log. In the CICS JCL, it is either DDNAME SYSPRINT or SYSxxxxx, where xxxxx represents an auto-generated number.

Additional details for each component are provided in subsequent sections.

S7MASTUBThis component acts on TIBCO EMS application calls and passes the call and associated parameters provided by the user application to S7M3PASS .

This component’s sequence of operation is as follows:

1. Copy the TIBCO EMS function name and its associated parameter list from a “null delimited character string” to a string of 64 characters, which is then passed to a COMMAREA.

2. LINK to program S7M3PASS .

3. Upon return from S7M3PASS , the tibems_status return code is passed to the application in the return variable of the function call.

4. Return to calling application.



S7M3PASSThis component manages the interactions between CICS transactions and the CEET. It also manages the run-time interactions to the CEET Work Threads.

This component’s sequence of operation is as follows:

1. Check for a CEET workarea.

2. If a workarea is present, then a CEET Work Thread exists for this transaction.

3. Check if the request is an administration command; if not, it is a TIBCO EMS library call.

4. Send the TIBCO EMS library call to the CEET Work Thread (S7M3EMSS) via MVS Post.

5. Issue a CICS EXTERNAL WAIT for response from the CEET.

6. Upon Wait return—the return code is passed back to the caller.

7. Return to the CICS application.

When a workarea does not exist for this transaction, the component’s sequence of operation is as follows:

1. Classify the call to CEET as Master, Connection or Work.

2. Check if the Master Thread is running; if not, start the Master Thread.

3. If this is a Master command, send to the Master Thread and return response to caller.

4. If this is a Connection or Work command, check if CONN Interface Thread for this URL (case sensitive) is running, If not, start one by communicating with the Master.

5. If this is a Connection command, set the Connection Thread URL and return to caller.

6. If this is a Work Command, use an existing Worker or start a new Worker.

7. Create a workarea for the Worker used for all calls by this CICS application.

8. Create a TRUE (Task Related User Exit) for this transaction to release the Work Thread on transaction end.

9. Send TIBCO EMS library call to the CEET Worker.

10. Upon completion, the return code and response are passed back to the caller.



S7M3EMSSThis component is a CEET module that handles all TIBCO EMS requests. The library containing S7M3EMSS must be concatenated in the CICS STEPLIB and must be authorized. S7M3EMSS is attached under a separate TCB so it runs outside of CICS normal transaction processing. The program provides four processing areas:

• Master Thread – starts and stops Connection Threads (up to the value specified in the MAXCONN parameter in S7MACURT).

• Connection Thread – starts and stops Work Threads (up to the value specified in the MAXWORK parameter in S7MACURT).

• Work Thread – interfaces between the CICS application and the TIBCO EMS Client library. Receives EMS function calls, performs the execution, and returns both data and the return code.

• Language Environment Condition Handler – while supporting the Work Threads, it enables recovery from S0Cx abends so that only the Worker terminates, while the rest of the CEET remains and continues to service other CICS transactions.

S7MATRUEThis component releases Work Threads upon transaction completion (normal or abnormal). Only two types of entries to this module require work (all others are “RETURN TO CALLER”), as follows:

• S7M3PASS passes the Temporary Storage Id and control block (ACMEM) location to S7MATRUE, which then stores it for transaction recovery.

• There is a CICS call at transaction end, at which time S7MATRUE then checks for the Temporary Storage.

If a TEMPORAY STORAGE does not exist, S7MATRUE returns to CICS. If a Temporary Storage record is found, S7MATRUE checks if there are open EMS connections. If so, a CICS LINK is issued for S7M3CLUP to cleanup the open connections and handle the freeing up of the CEET Work Thread. If S7MATRUE finds there are no open connections or other issues, S7MATRUE modifies the control blocks and deletes the Temporary Storage.

The TRUE is automatically activated when S7M3PASS first starts the CEET by issuing the following:

EXEC CICS ENABLE PROGRAM(‘S7MATRUE’) TASKSTART START TALENGTH(64)

This causes S7MATRUE to be called at each transaction end.



S7M3CLUPThis independent cleanup module is called from either S7MATRUE or DFHPEP and performs the following:

1. Ensures that a CEET Work Thread is no longer associated with a Connection.

2. Releases the CEET Work Thread so that the next CICS application can reuse it.

3. If the CEET Work Thread has ended, cleans up definitions and allocations on behalf of the Worker.

4. Ensures that storage references to this Worker are cleared.

S7M3STRTThis component is used in conjunction with the startup PLT. It uses S7MACURT to start the CEET at CICS initialization and performs the following:

1. Load S7MACURT.

2. Start the CEET using the parameters in S7MACURT.

3. Start Trace if so specified.

4. Start Connection Thread and Work Thread for URL in S7MACURT if needed.

S7MACURTParameters for starting the CEET.

HOSTPAGE Default host code page for the CEET (default is IBM-1047).

NETWORK Default network code page for the CEET (default is ISO8859-1).

MAXCONN Maximum Connection Threads allowed (default is 2; must be between 2 and 16, inclusive).

MAXWORK Maximum Worker Threads allowed (default is 4; must be between 4 and 128, inclusive).

TRACE Sets trace on or off for the CEET started by S7M3STRT (default is OFF).

URL An EMS connection thread is automatically started for this URL by S7M3STRT (optional).



S7M3STOPThis component is used in conjunction with the shutdown PLT. If the CEET is active, this program will shut it down, terminating all Work Threads, Connection Threads and the master.

USERID User ID to be used with the URL above (optional).

PASSWORD Password to be used with the URL above (optional).



Understanding Component InteractionThe preceding sections identified the main TIBCO EMS Client for z/OS (CICS) product components and described how each operates; this section examines in detail the interaction between these components. The diagram below illustrates the interactions that occur when a CICS user application issues a TIBCO EMS function call.

Figure 3 TIBCO EMS Client for z/OS (CICS) Component Interaction

S7M3PASS

CICS LINK

S7MATRUE

(CICS Task-Related Exit – TRUE)

ATTACHS7M3EMSS

Start Connection for

URL

Start Work Thread for

URL

Send TIBCO EMS

Command to Work Thread


S7MASTUB

UserApplication

User starts with EMS Connect

Post/WaitInterface CEET

S7M3EMSSMaster

Connections

Worker Anchor

CICS EMS ExecutionEnvironment

Work ThreadInstance

CICS Region



Initial CICS User Application Transaction

This section describes the sequence of events that occur in a CICS transaction. First, we describe the events that occur with the initial TIBCO EMS function call, followed by those that occur on subsequent function calls, and finally, the events that occur in the final function call for this transaction.

Initial TIBCO EMS Function Call

1. The user application issues a tibcoConnection_create with a URL (case sensitive) parameter.

2. Control is transferred to S7MASTUB, which is LKED into the user application.

3. S7MASTUB converts the call to CICS LINK to S7M3PASS with the necessary function indicator and parameter list.

4. S7M3PASS knows a CEET is not running, so it attaches program S7M3EMSS.

5. S7M3PASS establishes an interface to the S7M3EMSS Master Thread.

6. S7M3PASS sees there is no Connection Thread for the URL, so S7M3PASS tells the Master Thread to start a Connection Thread.

7. S7M3PASS establishes an interface to the S7M3EMSS Connection Thread for the URL.

8. S7M3PASS sees there is no Work Thread for the Connection Thread, so S7M3PASS tells the Connection Thread to start a Work Thread.

9. S7M3PASS establishes an interface to the S7M3EMSS Work Thread for the URL.

10. S7M3PASS sends a tibcoConnection_create command with parameters to the Work Thread.

11. The Work Thread converts the command request to a TIBCO EMS “Call” with the parameters passed by the user application in step 1.

12. The TIBCO EMS library creates a tibcoConnection, returns a zero condition code, and sets up the Connection pointer in the tibcoConnection_create parameter list.

13. The Work Thread returns the data and return code to S7M3PASS.

14. S7M3PASS returns the data and return code to S7MASTUB.

15. S7MASTUB returns the data to the user application.



Subsequent TIBCO EMS Function Calls

1. The user application issues another TIBCO EMS function call.

2. Control is transferred to S7MASTUB , which is LKED into the user application.


4. S7M3PASS knows there is a Work Thread available in the CEET to support this CICS transaction, so S7M3PASS sends the TIBCO EMS function command with parameters to the Work Thread.


6. The TIBCO EMS library processes the TIBCO EMS function, returns a condition code, and modifies the data as needed based on the parameter list.

7. The Work Thread returns the data and return code to S7M3PASS .

8. S7M3PASS returns the data and return code to S7MASTUB .

9. S7MASTUB returns the data and return code to the user application.

Final TIBCO EMS Function Call

1. The user application issues tibcoConnection_close.

2. Control is transferred to S7MASTUB , which is LKED into the user application.


4. S7M3PASS knows there is a Work Thread available in the CEET to support this CICS transaction, so S7M3PASS sends the TIBCO EMS function command with parameters to the Work Thread.


6. The TIBCO EMS library processes the TIBCO EMS function, returns a condition code, and modifies the data as needed based on the parameter list.

7. The Work Thread returns the data and return code to S7M3PASS .

8. S7M3PASS returns the data and return code to S7MASTUB .

9. S7MASTUB returns the data and return code to the user application.

10. During CICS transaction end S7M3TRUE is called and releases the Work Thread.



Subsequent CICS User Application Transactions

For transactions after the initial transaction, the specified URL parameter may or may not be the same as that specified for the initial transaction. The S7M3PASS component will cause a new Connection Thread to be started when the specified URL parameter is not the same, as described below:

1. The user application issues a tibcoConnection_create with a URL (case sensitive) parameter.

2. S7M3PASS looks for the Connection Thread for the URL:

a. If found (same case sensitive URL), continue to next step.

b. If not found (new URL), S7M3PASS tells the Master Thread to start a new Connection Thread for the new URL, then continue.

3. S7M3PASS looks for a free Work Thread on the Connection Thread:

a. If a free Work Thread exists, it allocates the existing Work Thread.

b. If a free Work Thread does not exist, it starts a new Work Thread.

4. S7M3PASS establishes an interface to the S7M3EMSS Work Thread for the URL and continues as previously described.



Administrative Commands

The TIBCO EMS Client for z/OS (CICS) provides an administrative transaction (S7MA) for controlling and monitoring various functions. This section describes the commands provided with the S7MA transaction.

Command Syntax

The command syntax is as follows:

S7MA -command {-option | [-option value] | ...}

S7MA is followed by a hyphenated command, followed by one or more hyphenated command options. Some command options require a value. In addition, some commands have no options.

Case Sensitivity

You can issue commands from the CICS command line or the console (if supported by your CICS installation). Most CICS terminals only support uppercase text; however, you may need to use lowercase text (for example, user ids and passwords for a secure TIBCO EMS server are case sensitive). The following parameters are provided to covert input text to lowercase or uppercase, and can be used in combination at the command line:

• –L or -l (translates to lowercase)

• –U or -u (translates to uppercase)

For example, is you specify the following at the command line:S7MA –connstart –l –url SAMPLEURL -u -userid sampleid

The resulting URL would be translated to "sampleurl" and the userid would be translated to "SAMPLEID."

Note that these parameters are useful for –url, -userid, and –password. However, values for these cannot be mixed-case text, since such text is not supported by the S7MA transaction. For example, if a userid is mixed-case, (such as “UserId”), consult your administrator to change it to lowercase or uppercase.


Administrative Commands | 43

Command SummaryThe following table summarizes the administrative commands:

Table 7 Administrative Command Summary

Usage Commands

Starting/Stopping connstart – starts a new Connection Thread.

connstop – stops a Connection Thread and all associated Work Threads.

masterstart – starts the Master Thread.

masterstop – stops all threads.

workstart – starts a new Work Thread.

workstop – stops a Work Thread.

workrelease – releases a Work Thread.

Tracing conntrace – sets tracing on or off for all connections in the CEET.

mastertrace – sets tracing on or off for all communications in the CEET.

General connping – pings a Connection Thread.

display – displays the status of the CEET.

dumpac – produces a dump of all ACMEM control blocks in the CEET.

dumpall – produces a dump of all control blocks in the CEET.

dumpas – produces a dump of all ASMEM control blocks in the CEET.

posix – displays the current POSIX runtime option in the CICS region.

print – prints a listing of all active threads of the CEET.

version – displays the version and build timestamp of the EMS Client currently running.

S7MA -CODEPAGE – displays the host and network code pages being used by the CEET.



Command Descriptions

-CODEPAGE

This command displays the code pages being used by the CEET. Example:S7M5401I 15:14:38 HostCodePage:IBM-1047 NetworkCodePage:ISO8859-1

–connping –url urlName

This command pings a Connection Thread. The urlName is the URL connection id you want to ping. The system looks for a Connection Thread with the specified URL connection id; if found, the ping command is sent to the Connection Thread.

–connstart –url urlName [–user userName] [–password | –pwd password]

This command starts a new Connection Thread. The urlName is the URL connection id the new Connection Thread is to be known by. The system looks for a Connection Thread with the specified URL connection id. If found, the command is ignored; otherwise a new Connection Thread is started using the specified URL connection id.

–connstop [–url urlName] | [–id id]

This command stops a Connection Thread and all associated Work Threads. The urlName is the URL connection id to stop, the id is thread id to stop.The system looks for a Connection Thread with the specified URL connection id, or a Work Thread with the specified id; if found, the system terminates the connection and workers as gracefully as possible.

–conntrace –[off | on]

This command enables tracing to be set on or off for all connections in the CEET. All Connection Access and Threads are affected by the setting of this command. When no option value is specified, the default value of off is used.



–display [–skip n]

This command displays the status of the CEET, listing all active threads. Twenty lines are displayed; you can use the –skip n option to page forward in the list, or the F8 key to forward page and the F7 key to backward page. A sample display is shown below:

S7M5400I 09:20:31 Total Thds:5 Mast Thds:1 Conn Thds:2 Work Thds:2 ID CB ADDRESS TYPE TASKID STATE URL OR LAST COMMAND AM 000C2000 MAST CMD S7M_SUBTASK_START0002 AC 000C2640 WORK 0000085 tibemsDestination_Destroy0002 AS 1CB58068 WORK CMD C002 16543C002 AC 000C2460 CONN S7M_WORK_STARTC002 AS 1CB713A0 CONN CMD tcp://url-id1:72220001 AC 000C2280 WORK 0000074 tibemsMsgConsumer_Receive0001 AS 1CB57E20 WORK WAIT C001 8123C001 AC 000C20A0 CONN S7M_WORK_STARTC001 AS 1CB71158 CONN CMD tcp://url-id2:7222

The first line of the display provides the following information:

• Time of transaction execution

• Total Thds: total number of threads running

• Mast Thds: number of Master Threads running

• Conn Thds: number of Connection Threads running

• Work Thds: number of Work Threads running

The second line of the display contains column headings (in uppercase letters). Subsequent lines represent information about active threads. The Master Thread displays on a single line (identified by MAST in the TYPE column). Each Work or Connection Thread is represented by a pair of lines, one after the other in the listing (identified by WORK or CONN in the TYPE column, respectively).

The columns display the following thread information (from left to right):

Column Description

ID The identification of the Connection or Work Thread. Connection Threads begin with the letter C.

CB The type of control block. AC – the ACMEM (CICS Application side); displays on the upper line for each thread. AS – the ASMEM (CEET side); displays on the lower line for each thread. AM – anchor control block in CICS Application Environment.

ADDRESS The control block address.



–dumpac

This command produces a dump like the one printout of all ACMEM control blocks in the CEET. ACMEM control blocks are on the CICS side of the interface. The output is sent to DDNAME CEEOUT.

–dumpall

This command produces a dump like the one printout of all the control blocks in the CEET. The output is sent to DDNAME CEEOUT.

–dumpas

This command produces a dump like the one printout of all ASMEM control blocks in the CEET. ASMEM control blocks are on the Server side of the interface. The output is sent to DDNAME CEEOUT.

TYPE The type of thread. MAST – Master Thread, CONN – Connection Thread, WORK – Work Thread.

TASKID The CICS transaction id currently allocated to this Work Thread. 0000000 indicated an unallocated Work Thread. Displays only for Work Threads, on the upper line.

STATE The state of the thread. CMD – indicates the thread will take commands from CICS. WAIT – indicates the thread is in the TIBCO EMS library and will not take commands from CICS.

URL OR LAST COMMAND

Id information and last command sent to the thread.

Connection Threads – the upper line displays the last command sent to the thread; the lower line displays the URL connection id of the thread.

Work Threads – the upper line displays the last TIBCO EMS API call sent to the thread. Since the length of the call’s name may exceed the width of this column, the call name begins in the STATE column. The lower line displays the id (from the ID column) of the Connection Thread to which this Work Thread is associated, followed by a count of the TIBCO EMS API calls for the thread.

Column Description



–masterstart,[hostcodepage],[networkcodepage]

This command starts the Master Thread. If the Master Thread is already started, the command is ignored. Only one Master Thread can exist. The optional hostcodepage and networkcodepage parameters specify the code pages to be used when starting the CEET. These override the defaults specified in S7MACURT.

–masterstop [–force]

This command stops all threads, in the following sequence:

1. Sends a stop command to all CEET Work Threads so they can terminate normally.

2. Sends a stop command to all CEET Connection Threads so they can terminate normally.

3. Sends a stop command to the Master Thread. If the Master Thread does not terminate, and you specified the –force option, the Master Thread is terminated via an Operation System Stop.

–mastertrace –[off | on]

This command enables tracing to be set on or off for all communications with the CEET. All Master events, Connection Access, and Work Threads are affected by the setting of this command. When no option value is specified, the default value of off is used.

–posix [–tcbs]

This command displays TCBs and POSIX runtime options in the CICS region. Information is sent to screen and JES output.

–print

This command prints the status of the CEET, listing all active threads. The output is sent to DDNAME CEEOUT.

–version

This command displays the version and build timestamp of the EMS Client currently running.



–workrelease [–addr address] | [–taskid taskid]

This command releases the Work Thread based on the Work Thread ADDRESS or CICS taskid as displayed using the DISPLAY option. The Work Thread is freed up and can be used by another new CICS transaction. If a user’s CICS transaction is purged, the Work Thread is not released. This command allows the user to free up the Work Thread if the Work Thread is in CMD mode. If the Work Thread is in WAIT mode, the Work Thread will have to be stopped using S7MA -workstop.

–workstart –url urlName [–user userName] [–password | –pwd password]

This command starts a new Work Thread. The urlName is the URL connection you want the Work Thread to be started on. The system looks for an existing Connection Thread with this urlName. If found, that Connection Thread is used to start the new Work Thread; otherwise, a new Connection Thread is started for this urlName and then the Work Thread is started.

–workstop [–addr address] | [–id id]

This command stops the Work Thread based on the Work Thread address as displayed using the DISPLAY option. The Work Thread is terminated. If a user CICS transaction is purged the Work Thread is not released. This command allows the user to stop and free up the Work Thread—see also S7MA –workrelease—When the Work Thread is stopped the maximum running threads is reduced by one. If a CICS transaction is currently active and allocated to the Work Thread, that CICS transaction receives a status return code of 1064.


Programmer's Checklist | 49

Programmer's Checklist

All application programmers in CICS under z/OS environment should check the following.

• The first TIBCO EMS API call must be a successful tibcoemsConnection_Create – if unsuccessful, the transaction does not have a CEET Work Thread, without which no TIBCO EMS API calls can be processed.

• The tibemsConnection_SetExceptionListener API is automatically done for the Work Thread when it is first started, so this API is available to the user transaction. Consequently, it is important that transactions make sure the first tibcoemsConnection_Create is the one they use to receive messages. This allows the Work Thread to pass status back to the transaction for Connection disruptions. If the transaction issues tibcoemsConnection_Create for other URLs, they will not be monitored, since only one tibemsConnection_SetExceptionListener is issued for the first URL tibcoemsConnection_Create.

For details on the TIBCO EMS API, see TIBCO Enterprise Message Service C & COBOL API Reference.

Batch Applications

• Execution – The TIBCO EMS API uses the TCP/IP socket interface. Most installations require a SYSTCPD DD statement in the execution JCL. Contact your organization’s TCP/IP support personnel for additional details.

C LanguageC language application programmers in CICS under z/OS environment can use this checklist.

• Code – include the appropriate TIBCO EMS C header files.

• Compile, Pre-link, and Link

The sample JCL for compiling C programs is member S7M3JCPL .

— The application source files normally reside in the <USERHLQ>.C dataset.

— The requirements are specified in the applicable compile procedure.



COBOLCOBOL application programmers in the z/OS environment can use this checklist.

• Code – include the appropriate TIBCO EMS COBOL copybooks.

• Compile, Pre-link, and Link

The sample JCL for compiling COBOL programs is member S7MCJCPL .

— The application source files normally reside in the <USERHLQ>.COB dataset.

— The requirements are specified in the applicable compile procedure.


| 51

Chapter 4 ABEND Codes, Return Codes, and Messages

Topics

• Overview, page 52

• ABEND Codes, page 54

• Return Codes, page 56

• System Messages, page 67

• Transaction Messages, page 91


52 | Chapter 4 ABEND Codes, Return Codes, and Messages

Overview

This section describes the general format of ABEND codes, return codes, and messages.

Message IdentifiersThe TIBCO EMS Client for z/OS (CICS) issues messages in the following format:

AAA nnnn S <message text>

The parts of the format are as follows:

• AAA is the product code. All ABEND codes and messages use the S7M product code that represents the TIBCO EMS Client for z/OS (CICS). Return codes do not include this product code in the message identifier.

• nnnn is a four-digit number in the range 1001 through 6000, with the exception of ABEND codes (see below).

— System messages use four-digit numbers in the range of 1001 through 5000. Example: S7M1001E.

— CICS transaction messages use four-digit numbers in the range of 5001 through 6000. Example: S7M5100E.

— Return codes use four-digit numbers in the range of 1001 through 1100 without the S7M product code prefix. Example: 1005.

— ABEND codes use a single digit number in the range of 1 through 9 or a single letter in the range of A through Z. Examples: S7M1, S7ME.

• S is the message severity code, which is separated from the message text by blanks. The severity code defines the importance of the message.

— I — Informational. These types of messages are usually advisories or a reply to a request performed by TIBCO EMS Client for z/OS (CICS) users.

— E — Error. These tell you that something has gone wrong. Action by you is probably required.

— S — Severe error. These tell you that something has gone seriously wrong. Action by you is required, probably with help from your system support personnel.


Overview | 53

Message Description FormatThe description of each message is in the following format:

• Message identifier — in the form AAA nnnn S. (refer to Message Identifiers on page 52)

• Message text — the words and inserts which make up the message as displayed by the TIBCO EMS Client for z/OS (CICS).

• Explanation — the events leading to or following the production of the message.

• User Response — the action recommended for the user (the console or system administrator or programmer).

• System Action — the action that has been or will be taken by the TIBCO EMS Client for z/OS (CICS).

• Destination— the device to which the message is sent. Values are:

— Console — the MVS master terminal console

— Log, Trace and or Audit output files of TIBCO EMS Client for z/OS (CICS)

— SYSPRINT (System printer defined to the same DDNAME)

CEET LogMessages from the CEET are written to an output file called the CEET log. In the CICS JCL, it is either DDNAME SYSPRINT or SYSxxxxx, where xxxxx represents an auto-generated number.

For details on the CEET and CEET log, see System Architecture on page 32.



ABEND Codes

This section describes the CICS transaction ABEND codes produced by the TIBCO EMS Client for z/OS (CICS).

Table 8 ABEND Codes

Code Description

S7M1 ABEND

Explanation: S7M3PASS issued a “EXEC CICS ADDRESS EIB(dfheiptr) COMMAREA(comP)” and did not receive a “NORMAL” response. This CICS API is critical to CEET organization.

User Response: Check system log for message S7M6203S. Analyze the CICS response codes, correct problem and retry transaction.

System Action: The CICS transaction is terminated.

S7M3 ABEND

Explanation: For all LINKS to S7M3PASS, a CICS COMMAREA of at least 76 characters is required. A COMMAREA of at least 76 characters was not provided. This area is critical for communications. A S7M3 abend is issued since there is no other way to indicate the problem.

User Response: If the user is accessing S7M3PASS via the S7MASTUB, then an internal problem exists. Please contact TIBCO technical support and provide system logs, CICS dumps, and Auxtrace.


S7M4 ABEND

Explanation: S7M3PASS issued a WRITEQ TS during CEET setup and did not receive a “NORMAL” response. The TS record is critical to CEET organization.

User Response: Check system log for message S7M6200S. Analyze the CICS response codes. Possible reasons include Authority problems or TS not installed. Correct the problem and retry the transaction.



ABEND Codes | 55

S7ME ABEND

Explanation: The Enable for the S7MATRUE (TRUE) program failed. On the first call to CEET after the module S7M3EMSS is attached, the routine issues a ENABLE PROGRAM for S7MATRUE. If this command fails, the abend is issued. The system issues the following:

EXEC CICS ENABLE PROGRAM('S7MATRUE'),START,TALENGTH(TRUEWAL),TASKSTART

Without this program properly enabled, CEET cannot cleanup transaction terminations that use EMS API call.

User Response: Check the system log and the DDNAME CEEOUT to determine why the S7MATRUE cannot be enabled as a CICS TRUE. Check that S7MATRUE is defined properly. Try issuing command manually with CECI to check return codes from CICS response. Check that S7M3PASS is defined properly. S7ME will produce a dump; in the trace table you will find the CICS response code to the enable.


S7MF ABEND

Explanation: The Enable for the S7MATRUE (TRUE) program failed. On the first call to CEET after the module S7M3EMSS is attached, the routine issues a ENABLE PROGRAM for S7MATRUE. If this command fails, the abend is issued. The CEET setup system issues the following:

EXEC CICS ENABLE PROGRAM('S7MATRUE'),START,TALENGTH(TRUEWAL),TASKSTART

Without this program properly enabled, CEET cannot cleanup transaction terminations that use EMS API call.

User Response: Make sure S7MATRUE is defined in CICS as a program with Execkey = CICS.


Table 8 ABEND Codes

Code Description



Return Codes

A tibems_status value represents a return code that is passed back to the application after a TIBCO EMS API call has been performed. All tibems_status values are in decimal and range from 0 to 255.

For details on tibems_status values, reference the tibems header, copybook members, or see TIBCO Enterprise Message Service C and COBOL Reference. Values ranging from 1000 to 9999 are specific to the TIBCO EMS Client for z/OS (CICS) and are described in this section

Table 9 Return Codes

Code Description

1005 Invalid URL pointer sent with Connection thread stop command.

Explanation: The user issued a Connection stop command for a Connection Thread probably via a S7MA -connstop. The Master Thread received the command but could not find a Connection Thread with the URL. The Master Thread will ignore the command and the system returns 1005 status.

User Response: Check that the system is running properly by issuing S7MA commands and check the system log for other errors. The user should verify the state of the CEET system and issue a S7MA command and/or review the CEET log to determine the reason for the Work Thread termination. Check to see if another program or person has issued the Connection stop command just before you, resulting in a timing situation rather than a real issue.

System Action: The Master Thread ignores the command. The tibems_status (return code) is set to 1005.


Return Codes | 57

1006 Invalid ACMEM pointer sent with Connection Thread debug start command.

Explanation: The user issued a debug on command for a Connection Thread, probably via a S7MA -conntrace. The Connection Thread received the command, but when testing the ACMEM pointer, found it invalid. The Connection Thread will terminate and the system returns 1006 status.

User Response: Check that the system is running properly by issuing S7MA commands and check the system log for other errors. This is an internal error, so the CEET should be stopped and restarted at the first opportunity. Issue a S7MA -masterstop followed by a S7MA -masterstart. The user should verify the state of the CEET system and issue a S7MA command and/or review the CEET log to determine the reason for the Work Thread Termination.

System Action: The Connection Thread is stopped as well as all Work Threads associated with the connection. The tibems_status (return code) is set to 1006.

1007 Invalid ACMEM pointer sent with Connection Thread debug stop command.

Explanation: The user issued a debug on command for a Connection Thread, probably via a S7MA -conntrace. The Connection Thread received the command, but when testing the ACMEM pointer, found it invalid. The Connection Thread will terminate and the system returns 1007 status.

User Response: Check that the system is running properly by issuing S7MA commands and check the system log for other errors. This is an internal error, so the CEET should be stopped and restarted at the first opportunity. Issue a S7MA -masterstop followed by a S7MA -masterstart. The user should verify the state of the CEET system and issue a S7MA command and/or review the CEET log to determine the reason for the Work Thread Termination.

System Action: The Connection Thread is stopped as well as all Work Threads associated with the connection. The tibems_status (return code) is set to 1007.

1008 EMS API Function call to CEET cannot allocate a Work Thread.

Explanation: The user issued an EMS Library API call which must be sent to a Work Thread. Since a Work Thread has not been allocated to this CICS transaction, the system tries to allocate a free one or start a new one. Both allocation types have failed. If the EMS Library API call is a tibemsConnection_Create, the system returns 1008 status.


Code Description



User Response: Check the number of Work Threads running using the S7MA transaction. Check the system log and CEET log to determine why the Work Thread could not be allocated. Possible reasons for this abend include the following:

• The maximum of 127 Work Threads was reached so no further Work Threads can be started.

• The maximum of 16 Connection Threads was reached so no further Connection Threads can be started.

• A stop workthread or connection command was issued.

The user programs, when getting a 1008 tibems_status, should take whatever error processing needed and terminate – DO NOT issue any more EMS API calls since a Work Thread has not been allocated to the CICS transaction.

System Action: The function returns unsuccessfully to the application and the tibems_status (return code) is set to 1008. No Work Thread is allocated to the CICS transaction.

1009 Invalid ACMEM pointer sent with Connection Thread stop command.

Explanation: The user issued a stop command for a Connection Thread, probably via a S7MA -connstop. The Connection Thread received the command, but when testing the ACMEM pointer, found it invalid. The Connection Thread will terminate and the system returns 1009 status.

User Response: Check that the system is running properly by issuing S7MA commands and check the system log for other errors. This is an internal error, so the CEET should be stopped and restarted at the first opportunity. Issue a S7MA -masterstop followed by a S7MA -masterstart. The user should verify the state of the CEET system and issue a S7MA command and/or review the CEET log to determine the reason for the Work Thread termination.

System Action: The Connection Thread is stopped, as well as all Work Threads associated with the connection. The tibems_status (return code) is set to 1009.

1010 Invalid ACMEM pointer sent with Connection Thread start command.

Explanation: The user issued a start command for a Connection Thread, probably via a S7MA -connstart. The Connection Thread received the command, but when testing the ACMEM pointer, found it invalid. The Connection Thread will terminate and the system returns 1010 status.


Code Description


Return Codes | 59



1011 Invalid ACMEM pointer sent with Connection Thread ping command.

Explanation: The user issued a ping command for a Connection Thread, probably via a S7MA -connping. The Connection Thread received the command, but when testing the ACMEM pointer, found it invalid. The Connection Thread will terminate and the system returns 1011 status.



1012 Function call to CEET is not a Connection request or a Supervisory command.

Explanation: The user program issued an EMS Library API call to the CEET and did not have a Work Thread allocated to the CICS transaction. First time calls must be either a connection request or a supervisory command. This error code can also be received if the Work Thread allocated to the CICS transaction terminates (normally or ABENDS) while the CICS transaction is running.

User Response: The user should verify that the first EMS Library API functional call to CEET is a tibemsConnection_Create function with valid parameters, correct the program, and retry the transaction. The user programs, when getting a 1012 tibems_status, should take whatever error processing needed and terminate – DO NOT issue any more EMS API calls since a Work Thread has not been allocated to the CICS transaction.


Code Description



System Action: The function returns unsuccessfully to the application and the tibems_status (return code) is set to 1012. No Work Thread is allocated to the CICS transaction.

1016 Function not found in command list.

Explanation: The program issued a EMS Library API call to the CEET that is not a supported EMS API function. The CEET does not forward the function call to the EMS Library. The CEET immediately returns a tibems_status (return code) of 1016.

User Response: The user should verify the TIBCO function being used, correct the program, and retry the transaction.

System Action: The function returns unsuccessfully to the application and the tibems_status (return code) is set to 1016.

1024 Missing Work Thread pointer sent or Work Thread not found with Work Thread stop command.

Explanation: The user issued a stop command for a Work Thread, probably via a S7MA -workstop. The Connection Thread received the command, but when testing the pointer, found it invalid or could not find the Work Thread. The Connection Thread will ignore the command and the system issues returns 1024 status.

User Response: Check that the system is running properly by issuing S7MA commands and check the system log for other errors. The user should verify the state of the CEET system and issue a S7MA command and/or review the CEET log to determine the reason for the Work Thread termination.

System Action: The Work Thread is not stopped, the command is ignored. The tibems_status (return code) is set to 1024.


Code Description


Return Codes | 61

1040 Missing URL.

Explanation: The program issued a tibemsConnection Create API to the EMS Library, but without a URL parameter (null pointer or null string).

User Response: The user should verify that the tibemsConnection_Create API has a valid URL string.


1041 Invalid control block in CICS Application Environment.

Explanation: An invalid control block pointer was found in the CICS Application Environment.

The pointer to the control block is invalid or the start/end id stored in the control block is invalid. There is one control block in the CICS Application Environment for each Connection and Work Thread in the CEET.

User Response: Contact TIBCO support and report the error. Please be able to provide the CEET log, DDNAME CEEOUT output, and CICS SYSLOG.


1042 Invalid control block in the CEET.

Explanation: An invalid control block was found in the CEET.

Either the pointer, start id, or end indicator of the control block is invalid. There is one control block for each Connection and Work Thread in the CEET




Code Description



1043 The CEET is stopping.

Explanation: A S7MA -masterstop or S7MA -connstop was issued so the CEET will not honor any new Connection Thread Start, Work Thread Start or Work Thread Allocation requests directly or indirectly (tibemsConnection_Create will cause the CEET to issue Connection Thread starts, Work Thread starts and/or Work Thread Allocation requests).

User Response: The user program should take the steps necessary to terminate the program either normally or abnormally. If you want to restart the CEET master, issue a S7MA -masterstart and reissue the transactions.


1044 The CEET stopped.

Explanation: A S7MA -masterstop was issued so the CEET master will not honor any new Connection Thread Start, Work Thread Start or Work Thread Allocation requests directly or indirectly (tibemsConnection_Create will cause the CEET master to issue Connection Thread starts, Work Thread starts and/or Work Thread Allocation requests).

User Response: The user program should take the steps necessary to terminate the program either normally or abnormally. If you want to restart CEET master, issue a S7MA -masterstart and reissue the transactions.


1045 The Connection Thread could not be started.

Explanation: A S7MA -connstart or a tibemsConnection_Create was issued, so the CEET master is attempting to start a new Connection Thread. The Connection Thread could not be started. Messages in the system log should indicate why the Connection Thread was not started.

User Response: The user program should take the steps necessary to terminate the program either normally or abnormally. Check the CEET log for why the Connection Thread could not be started or the MAXCONN has been reached.



Code Description


Return Codes | 63

1046 The Work Thread could not be started.

Explanation: A S7MA -workstart or a tibemsConnection_Create was issued, so the CEET master does not have an open Work Thread for the URL attempting to start a new Work Thread. The Work Thread could not be started. Messages in the system log should indicate why the Connection Thread was not started. The following are possible reasons:

• Bad URL.

• The Master Thread was stopped.

• MAXWORK has been exceeded

User Response: The user program should take the steps necessary to terminate the program either normally or abnormally. Check the CEET log for why the Work Thread could not be started.



Code Description



1047 The Work Thread terminated while processing a tibems API function.

Explanation: The Work Thread terminated while processing a tibems API function. The Work Thread terminated while processing a tibems API function for the user transaction. Messages in the system log should indicate why the Work Thread was not started. The following are common reasons:

• The Work Thread was stopped.

• The Connection Thread was stopped.

• The Master Thread was stopped.

• Connection to the TIBCO EMS Server was lost.

• The Work Thread, Connection Thread or Master Thread had a Error Condition Raise (System exception like an S0Cx).

• Work Threads can get an S0Cx abend if an invalid address is passed to the EMS library by a tibems API call.

User Response: The user program should take the steps necessary to terminate the program either normally or abnormally. Check the system log for why the Work Thread could not be started.


1048 Invalid control block combination.

Explanation: A control block combination (one in the CICS Application Environment and one in the CEET) are out of synch.




Code Description


Return Codes | 65

1050 Invalid anchor control block in CICS Application Environment

Explanation: Invalid anchor control block in CICS Application Environment was discovered.

Either the pointer to the control block is not valid or the start id of the control block is invalid or end indicator of the control block is invalid. There is one control block for the Master thread in the CICS Application Environment.



1051 Invalid anchor control block in the CEET.

Explanation: Invalid anchor control block in the CEET was discovered.

Either the pointer to the control block is not valid or the start id of the control block is invalid or end indicator of the control block is invalid. There is one control block for the Master thread in the CEET.



1052 Master Thread has ended.

Explanation: The Master Thread has ended while processing a Master Command. All Connection Threads and Work Threads will also end. This is an internal error.

User Response: The user program should take the steps necessary to terminate the program, either normally or abnormally.

Contact TIBCO support and report the error. Please be able to provide the CEET log, DDNAME CEEOUT output, and CICS SYSLOG.



Code Description



1064 Work Thread stopped.

Explanation: The program issued a call to the EMS Library, but the Work Thread allocated to the CICS transaction is being or has been stopped. The Work Thread can stop for several reasons, including the following:

• A stop connection or stop Work Thread command was issued for this connection and/or Work Thread. Since the Work Thread is terminating, all EMS API calls are rejected and a return code indicating error returned.

• The Work Thread to support the CICS transaction has terminated due to a problem. Review the CEET log to determine the reason for the Work Thread termination.

User Response: The user should verify the state of the Work Thread and issue a S7MA command and/or review the CEET log to determine the reason for the Work Thread termination. DO NOT issue any more EMS API calls from that transaction since a Work Thread has not been allocated to the CICS transaction.



Code Description


System Messages | 67

System Messages

This section describes system messages produced by the TIBCO EMS Client for z/OS (CICS).

Table 10 System Messages

Code Description

S7M1001I Connection Thread address Ended

Explanation: When a Connection Thread ends, all Work Threads started by the Connection Thread also end.

Destination: CEET log.

S7M1002I cleanup_asmem POINT n

Explanation: This message indicates points 1 through 10 in the cleanup process.


S7M1100I ACMEM Invalid Start ignored

Explanation: The ACMEM address passed to the Master to start a Connection Thread is invalid.


S7M1101E Could not find open Connection ASMEM Control Block

Explanation: This message indicates that the Master received start command for a connection but could not find any open connection ASMEM control blocks—the system has 16 and all are in use.

User Response: Verify the number of Connection Threads that are running by using transaction S7MA. Stop Connection Threads that are no longer needed and retry transaction. Remember — when stopping a Connection Thread, all Work Threads associated with the Connection Thread will also terminate.

System Action: The Work Thread is not started. The rest of the interface continues.




S7M1102E Invalid ACMEM pointer

Explanation: Routine entered to test for valid ACMEM control block—the address is zero.


System Action: The command is ignored for Master and Connection Threads. For Work Threads, the thread terminates.


S7M1103E Invalid ACSTART pointer

Explanation: Routine entered to test for valid ACMEM control block—the header id is invalid.




S7M1104E Invalid ACIDE pointer

Explanation: Routine entered to test for valid ACMEM control block—the trailer id is invalid.




S7M1200I before Post of CICS transaction

Explanation: The trace point in Master before issuing Post.



Code Description



S7M1210I before Master Wait

Explanation: The trace point in Master before Wait.


S7M1301S Missing AMMEM pointer at startup

Explanation: The parameter passed to S7M3EMSS which is to be the AMMEM address is missing or invalid.


System Action: The Master Thread terminates.


S7M1451E S7M_SUBTASK_STOP—CANNOT Find URL

Explanation: The CEET received a stop command for a Connection Thread but the URL given does not match any running Connection Threads.

User Response: Must check the URL id of the Connection Thread you want to terminate and make sure you specify the url exactly (case sensitive).

System Action: Ignore command to stop Connection Thread.


S7M1452I S7M_SUBTASK_STOPAS—CANNOT Find AS

Explanation: A master received a stop command for a Connection Thread but the ASMEM address given does not match any running Connection Threads.

User Response: Must check the ASMEM address of the Connection Thread you want to terminate.

System Action: Ignore command to stop Connection Thread.



Code Description



S7M1470E Invalid ASMEM pointer

Explanation: Routine entered to test for valid ASMEM control block—the address is zero.


System Action: Master ignores command.


S7M1471E Invalid ASSTART pointer

Explanation: Routine entered to test for valid ASMEM control block—the header id is invalid.




S7M1472E Invalid ASIDE pointer

Explanation: Routine entered to test for valid ASMEM control block—the trailer id is invalid.





Code Description



S7M1482S Invalid AMMEM pointer

Explanation: Routine entered to test for valid AMMEM control block—the address is zero.


System Action: Master Thread terminates.


S7M1483S Invalid AMSTART pointer

Explanation: Routine entered to test for valid AMMEM control block—the header id is invalid.


System Action: Master Thread terminates.


S7M1484S Invalid AMIDE pointer

Explanation: The Master Thread could not find a match in its Command Table—command was not found in command list.


System Action: The Command is ignored and a return code of 8 is passed back to the User.



Code Description



S7M1492E Command Not Found: command

Explanation: The Master Thread could not find a match in its Command Table—command was not found in command list.


System Action: The Command is ignored and a return code of 8 is passed back to the User..


S7M1500I Master Started AM:addr, AMS:addr EMS Ver:number Build: timestamp

Explanation: This message is issued when the CEET (S7M3EMSS) is started. Parameters passed to S7M3EMSS are shown for reference purposes where AM is the control block in the CICS Application Environment and AMS is the control block for the Master Thread in the CEET. Also shows the current version of the EMS Client and the build time stamp (in the format Month Day Year and Time).


S7M1501I Master Thread Ended

Explanation: This message indicates that the CEET is terminating—all Connection Threads and Work Threads end.


S7M1502I time Maximum Connections:num Maximum Workers:num

Explanation: Message issued by CEET at startup to record maximum number of Connection and Worker Threads.


S7M1503I time HostCodePage:hostcodepage, NetworkCodePage:networkcodepage

Explanation: Message issued by CEET at startup to record code pages being used.



Code Description



S7M1504I time Error:number, HostCodePage:hostcodepage, NetworkCodePage:networkcodepage

Explanation: Message issued by CEET at startup to indicate an error was returned from tibems_SetCodePages. The error number is the returned tibstatus. Error:74 means that one of the code pages specified is invalid.

User Response: Correct the code page parameter in S7MACURT or on the S7MA –MASTERSTART command and restart the CEET.

System Action: CEET terminates.


S7M1900I Function: routine Entered

Explanation: The Master Thread entered function routine.


S7M1901I Function: routine Exited

Explanation: The Master Thread exited function routine.


S7M1999I time Master shutdown - number Connections Active

Explanation: This message issued at Master Thread shutdown indicates how many Connection Threads are still active.


S7M2011I work_cleanup_asmem POINT n

Explanation: This message indicates the Work Thread cleanup program has entered trace point n in the cleanup function.



Code Description



S7M2013E CONN ASMEM Invalid Start ignored

Explanation: This message indicates the Connection Thread has found an invalid Connection ASMEM pointer—the start indicator is invalid.


System Action: The command is ignored for Connection Threads. The Connection Thread and all its Work Threads terminate.


S7M2014E CONN ACMEM Invalid Start ignored

Explanation: This message indicates the Connection Thread has found an invalid Connection ACMEM pointer—the start indicator is invalid.




S7M2020I before Post of CICS client ecb

Explanation: This message indicates the Connection Thread is at the point just before posting the CICS transaction.


S7M2022I before wait of Connection Thread

Explanation: This message indicates the Connection Thread is at the point just before waiting for the next command.



Code Description



S7M2099E time Error opening tibemsConnection url, EMS Status: EMS status code

Explanation: When a Connection Thread starts, it issues a tibemsConnection_Create for the URL it was started on. If that connection create fails, this message is issued.

User Response: Analyze the EMS status return code and determine why the connection cannot be made. Correct the problem and retry the transaction that started the Connection Thread.

System Action: The Connection Thread is terminated.

S7M2101I CONN ASMEMPTR = address

Explanation: This message indicates the Connection Thread address of the ASMEM upon start of the program.


S7M2201E Work Task Monitor (join) for address Ended rc = RC

Explanation: This message indicates that a Work Thread monitor could not join to the Work Thread for ASMEM address. The return code from the pthread_join was RC.

User Response: The Work Thread must be restarted.

System Action: The Work Thread terminates.


S7M2210I Work Thread Create—RC = RC

Explanation: This message indicates the Connection Thread has entered the thread create routine and issued a thread create—RC is the return code.



Code Description



S7M2211I Work Watch Create—RC = RC

Explanation: This message indicates the Connection Thread has entered the thread create routine and issued a thread create to monitor the previously created Work Thread—RC is the return code.


S7M2222E Command Not Found: command

Explanation: This message indicates the Connection Thread has not found the command sent in the command list.

User Response: Check the syntax of the command sent to the Connection Thread.

System Action: The command is ignored.


S7M2223I Cmd Address: address

Explanation: This message indicates the Connection Thread has not found the command sent in the command list—address.


S7M2224E BAD S7M_SUBTASK_PING—Ping Received

Explanation: This message indicates the Connection Thread received a Ping command from the CICS Application Environment with a bad control block address.


System Action: The Connection Thread and all its Work Threads terminate.



Code Description



S7M2225E BAD S7M_SUBTASK_DBGF—Debug OFF Received

Explanation: This message indicates the Connection Thread received a trace off command from CICS for all Connection Threads with invalid ACMEM address.




S7M2226E BAD S7M_SUBTASK_STOP—STOP Received

Explanation: This message indicates the Connection Thread received a end command from the CICS client with a bad ACMEM address parameter.




S7M2228E Could not find open WORK ASMEM

Explanation: This message indicates the Connection Thread has entered the thread create routine but could not find an open ASMEM to use (there are 128 allowed).

User Response: Check to see how many Work Threads are running by issuing a S7MA CICS Transaction—the system maximum is 128 Work Threads.

System Action: The command is ignored for Work Thread.



Code Description



S7M2229E BAD S7M_SUBTASK_START—START Received

Explanation: This message indicates the Connection Thread received a start command from the CICS Application Environment with a bad control block address.




S7M2230E Invalid AMMEM pointer

Explanation: This message indicates the Connection Thread has found an invalid AMMEM pointer—the address is 0.




S7M2231E Invalid AMSTART pointer

Explanation: This message indicates the Connection Thread has found an invalid AMMEM pointer—the start indicator is invalid.





Code Description



S7M2237E Work Thread WThd not found on Conn thread CThd

Explanation: This message indicates the Connection Thread received a stop Work Thread command from the CICS Application Environment but the ASMEM WThd was not on the Connection Thread for ASMEM CThd.

User Response: Check that the Command to stop the Work Thread is on the Connection Thread Chain. Only the Connection Thread that started the Work Thread can stop it.

System Action: The command is ignored for Connection Threads.


S7M2237I BAD S7M_SUBTASK_DBGO—Debug ON Received

Explanation: This message indicates the Connection Thread received a trace on command from the CICS Application Environment for all Connection Threads with invalid control block address.




S7M2238E Work Thread parm not present

Explanation: This message indicates the Connection Thread received a stop Work Thread command from the CICS Application Environment with an invalid control block address.





Code Description



S7M2239E Work Thread thead id not found on Connection Thread Conn thead id

Explanation: A stop Work Thread thead id command was sent to a Connection Thread Conn thead id and the Connection Thread could not find the Work Thread on its list of threads it has started.

User Response: Use S7MA to see if the Work Thread is still active (it may have terminated before the command was processed). Use S7MA to determine which Connection Thread controls the Work Thread. Issue a S7MA –workstop or S7MA –connstop for terminate the Work Thread.

System Action: The stop Work Thread command is ignored.


S7M2240E Invalid AMIDE pointer

Explanation: This message indicates the Connection Thread has found an invalid AMMEM pointer—the end indicator is invalid.




S7M2250I WORK ASMEM address—ACMEM address

Explanation: This message indicates the addresses of the ASMEM and ACMEM control blocks, just before going to Work Thread main program.


S7M2310I Connection Thread Started for URL urlid

Explanation: This message indicates the Connection Thread is at the start point.



Code Description



S7M2311I Connection Thread # id Ended for URL url

Explanation: When a Connection Thread is ending, this message is issued.

User Response: none.

System Action: The EMS Connection Thread is terminated.

S7M2810E CONN ASMEM Invalid Start ignored.

Explanation: This message indicates the Connection Thread has detected an Invalid ASMEM for the Connection Thread during processing of the Work Start Command.




S7M2811E CONN ACMEM Invalid Start ignored

Explanation: This message indicates the Connection Thread has detected an Invalid ACMEM for the Connection Thread during processing of the Work Start Command.





Code Description



S7M2812E WORK ACMEM Invalid Start ignored

Explanation: This message indicates the Connection Thread has detected an Invalid Work ACMEM during processing of the Work Start Command.


System Action: The command is ignored for Work Thread. The Work Thread terminates.


S7M2999I time Connection shutdown – number Work Threads Active

Explanation: This message issued at Connection Thread shutdown indicates how many Work Threads are still active.


S7M3010I time WORK Thread # id Started AC:acmem, AS:asmem, PT: thread id

Explanation: When a Work Thread is started, this message is issued. acmem is the address of the ACMEM control block for this thread. asmem is the address of the ASMEM control block for this thread. thread id is the thread id of this Work Thread.


System Action: The EMS Work Thread is started.


Code Description



S7M3014E WORK Thread # thead id tibemsErrorContext_Create EMS status: status

Explanation: The Work Thread issued an EMS API call for tibemsErrorContext_Create and EMS returned a nonzero status code. The tibemsErrorContext_GetLastErrorStackTrace and the tibemsErrorContext_GetLastErrorString EMS API calls will not work on this specific Work Thread since the Context Object Id is not available.

User Response: Determine why EMS issued the non-zero status by looking up status in the EMS documentation. Correct the problem, then stop and start the Work Thread.

System Action: The Work Thread continues to run without ErrorContext functions.


S7M3030I time WORK Thread # id Ended AC:acmem, AS:asmem

Explanation: When a Work Thread is ending, this message is issued. acmem is the address of the ACMEM control block for this thread. asmem is the address of the ASMEM control block for this thread.


System Action: The EMS Work Thread is terminated.

S7M3100I Work Thread Started

Explanation: This message indicates the Work Thread is at the start point.


S7M3101I Initial ACMEM OK

Explanation: This message indicates the Work Thread is at the start point and has a valid ACMEM pointer.



Code Description



S7M3110I Condition Handler Registration OK

Explanation: This message indicates the Work Thread is at the start point and set a Condition Handler.


S7M3200E Condition Handler Registration Failed

Explanation: This message indicates the Work Thread is at the start point and could not set a Condition Handler.


System Action: The Work Thread continues to run without a Condition Handler—any S0C(x) condition (abend) terminates the CEET—Master Thread, All Connection Threads, and All Work Threads.


S7M3300I Processing LOOP Entered

Explanation: This message indicates the Work Thread is at the main process point.


S7M3400I Processing START Function

Explanation: This message indicates the Work Thread received a start function.


S7M3401I Processing PING Function

Explanation: This message indicates the Work Thread received a ping function.



Code Description



S7M3404I Processing Debug Off

Explanation: This message indicates the Work Thread should turn off the trace and debug feature.


S7M3405I Processing Debug On

Explanation: This message indicates the Work Thread should turn on the trace and debug feature.


S7M3500I Processing WTO Function

Explanation: This message indicates the Work Thread received a WTO function command.


S7M3501I Beginning Command Table Search

Explanation: This message indicates the Work Thread received a command—it is searching command table for match.


S7M3550E Function Found—Zero Address

Explanation: This message indicates the Work Thread found match for command in search table but the address of the routine to process command was missing.

User Response: Function is not available—try using a different EMS function.

System Action: The Work Thread ignores command and sets return code to 1016.



Code Description



S7M3561E Function Not Found: command

Explanation: This message indicates the Work Thread did not find the command in the search table.

User Response: The EMS API call is invalid, correct the user program.

System Action: The Work Thread ignores command and sets return code to 1016.


S7M3570I Command Ignored

Explanation: This message indicates the Work Thread that the previous command was ignored.


S7M3750I EXC: function

Explanation: This message indicates the Work Thread command the program is going to call.


S7M3810E Invalid Work Thread AS, Cannot check open EMS Connections


System Action: The Work Thread ends and a return code is passed back to the user..


S7M3900I Client Wait Entered

Explanation: This message indicates the Work Thread is entering the post/wait routine.



Code Description



S7M3901I Before WAIT for CICS Client

Explanation: This message indicates the Work Thread is just before wait routine.


S7M3902I After Wait

Explanation: This message indicates the Work Thread is just after wait routine.


S7M3910I Set Return Code to Zero

Explanation: This message indicates the Work Thread is setting zero (0) return code.


S7M3920I Set Return Code to 1004

Explanation: This trace message indicates the Work Thread is setting 1004 return code. The trace entry is preceded by message S7M3570I. This is passed back to the User Program as the Tibco_status.



Explanation: This message indicates the Work Thread is setting 1008 return code The return code is 1008. This is passed back to the User Program as the Tibco_status.



Explanation: This message indicates the Work Thread is setting 1016 return code. The trace entry is preceded by either message S7M3550E or S7M3561E. This is passed back to the User Program as the Tibco_status.



Code Description



S7M3960E Bad ACMEM - ACSTART

Explanation: This message indicates the Work Thread found an invalid ACMEM control block in the CICS Application Environment—the beginning of the control block as an id that is missing. This is a major problem indicating that the Control Block has been corrupted.


System Action: The Work Thread ends and a return code is passed back to the user.


S7M3961E Bad ACMEM - ACIDE

Explanation: This message indicates the Work Thread found an invalid ACMEM control block in the CICS Application Environment—the end of the control block as an id that is missing. This is a major problem indicating that the Control Block has been corrupted.





Code Description



S7M3962E Bad ASMEM - ASSTART

Explanation: This message indicates the Work Thread found an invalid ASMEM control block in the CEET—the beginning of the control block as an id that is missing. This is a major problem indicating that the Control Block has been corrupted.




S7M3963E Bad ASMEM—ASIDE

Explanation: This message indicates the Work Thread found an invalid ASMEM control block in the CEET—the end of the control block as an id that is missing. This is a major problem indicating that the Control Block has been corrupted.




S7M3999I Work Thread Exit

Explanation: This message indicates the Work Thread returning to the operating system.


S7M4900I S7M3COND Entered # number

Explanation: This message indicates that a Work Thread Condition (ABEND) has occurred and the Condition Handler has been entered.

This number is a count of Conditions (ABENDs).



Code Description



S7M4902I token = token S0Cx Abend

Explanation: This message indicates information given to the Condition Handler routine—The current condition token.


S7M4908E Invalid ACMEM

Explanation: This message indicates the CICS Application Environment control block or its pointer is invalid.


System Action: The Work Thread continues to terminate.


S7M4910I Func: S7M3COND Exited Error #:Num

Explanation: This message indicates a return to the LE environment from the Condition Handler.


S7M5000E eibfn:0402 - eibresp:4, eibresp2:0

Explanation: An error occurred in S7MA on issuing a CICS command—this is the function number and response codes.


System Action: This is information about the status of the CICS transaction displayed on terminal screen.


Code Description


Transaction Messages | 91

Transaction Messages

This section describes CICS transactional messages produced by the TIBCO EMS Client for z/OS (CICS).

Table 11 Transaction Messages

Codes Description

S7M5100I time description

Cannot Find Task ID

Explanation: User issued a S7MA –connstop. The system did not find a matching –id, -addr or – url system.

User Response: Issue S7MA to display active interfaces; verify command parameters and reissue correct command.


CICS EMS Master Not Running - No TS Pointer

Explanation: The CEET is not active.

User Response: This is information about the status of the CEET. To change that status see S7MA –masterstart.


CICS EMS Task Stopped

Explanation: The CEET is not active. A S7MA –masterstop was issued. No new Connection Thread or Work Threads will be started until a S7MA –masterstart is issued. A return code of 1044 is passed back to all EMS API calls that require a new Work Thread.

User Response: This is information about the status of the CEET. To change that status, see S7MA –masterstart




URL:urlname in CICS EMS Task can not be reached

Explanation: Means that there is no Connection Thread for the specified URL or the Connection Thread is not working properly.

User Response: This is information about the status of the CEET. Use S7MA to see status of all running threads.


S7M3ADM - Unknown parameter:parm

Explanation: An unsupported S7MA sub-command had entered.

User Response: Review and correct the command and submit again.


S7M5100E time description

Cannot Find Connection Thread for Work Thread id

Explanation: User issued a S7MA –connstop. The system did not find a matching –id, -addr or – url item.

User Response: issue S7MA to display active interfaces; verify command parameters and reissue corrected command.


CICS EMS Task Stopped

Explanation: User issued a S7MA -masterstop prior to this command and the CEET interface is not running.




Codes Description



EMS Task CB has terminated with Code

Explanation: While starting the CICS EMS master program, the program terminated with the following Code Posted to the Task ECB. The Task ECB Post is from MVS and indicates why the program was terminated. The CEET interface is not running.

User Response: Contact TIBCO Support and provide system logs, CICS dumps, and Auxtrace.

System Action: The command is ignored. The CEET interface is not running.

EMS Task CB has terminated with Code

Explanation: While starting the CICS EMS master program, the major control blocks (AM) were corrupted. The CEET interface is not running.

User Response: Issue a S7MA -masterstop to cleanup internal control blocks. Issue a S7MA -masterstart to restart the CEET. If failure persists, contact TIBCO Support and provide system logs, CICS dumps, and Auxtrace.

System Action: The command is ignored. The CEET interface is not running.

Invalid CONN ASMEM Thread Pointer

Explanation: If user issued a S7MA -masterstop, this may be a timing situation. The system is stopping the interface while being monitored.

User Response: Issue S7MA to display interfaces status.

System Action: The command stops the CEET interface.

S7M5200I time description

CICS EMS Master, Connection and Work Threads Stopped

Explanation: User issued a S7MA -masterstop. All threads are stopped and none will be started until a S7MA –masterstart is issued.


System Action: The CEET interface is terminated.


Codes Description



Connection PING Issued Return Code = 0

Explanation: The Connection Thread is sent a PING command and the return code is displayed. Return code of zero (0) indicates everything is working correctly. A response of: URL:urlName in CICS EMS Task can not be reached

means there is no Connection Thread for the specified URL or the Connection Thread is not working properly

User Response: This is information about the status of the Connection Thread in response to, for example:S7MA –connping –url urlName

System Action: none.

Connection Started Error, EMS Status = number

Explanation: User issued a S7MA –connstart. When trying to start an EMS connection, an error was issued from the EMS library. Check the EMS library status codes for reason. The Connection Thread terminated and is not available.

User Response: Lookup EMS status return code to determine why the connection could not be made. Correct situation and reissue command.

System Action: The Connection Thread terminated.

Connection Thread Started

Explanation: The Connection Thread is now started, for example: S7MA –CONNSTART –URL urlName

User Response: This is information about the status of the Connection Thread. To change that status see S7MA -connstop.

System Action: The Connection Thread started.


Codes Description



Connection Thread and All Work Threads Stopped

Explanation: The Connection Thread and all its Work Threads have stopped, for example: S7MA –connstop {–url urlName} |{–id id}

User Response: This is information about the status of the Connection Thread. To change that status see S7MA –connstart.

System Action: The Connection Thread and All Work Threads stopped.

Num Control Blocks Printed

Explanation: The list of active threads is listed to DDNAME CEEOUT. The output is similar to the S7MA display command. It indicates how many control blocks were printed.

User Response: This is information about the status of the threads as a response to: S7MA –print

System Action: Printed CEET status to DDNAME CEEOUT.

number TCBs looked at - POSIX (ON) found

Explanation: Routine looked at all attached TCBs in the CICS address space and found a TCB with the POSIX (ON) runtime option. Related information sent to screen and JES output.

User Response: None.

System Action: Display and print information on POSIX use in the CICS region.

number TCBs looked at - POSIX (ON) NOT found

Explanation: Routine looked at all attached TCBs in the CICS address space and did not find a TCB with the POSIX (ON) runtime option.


System Action: Display and print information on POSIX use in the CICS region.


Codes Description



Master Already Running

Explanation: User issued a S7MA –masterstart, but the CEET was already running.

User Response: none


Master Thread Started

Explanation: The CEET is now started:S7MA –masterstart

User Response: This is information about the status of the CEET. To change that status see S7MA –masterstop.

System Action: The CEET started.

Master Trace On

Explanation: This command turns on the trace feature on the Master Thread, all Connection Threads, and all Work Threads.

User Response: This is information about the status of all threads as a response to: S7MA –mastertrace –on

System Action: All threads will produce trace messages to the CEET log.

Master Trace Off

Explanation: This command turns off the trace feature on the Master Thread, all Connection Threads, and all Work Threads.

User Response: This is information about the status of all threads as a response to: S7MA –mastertrace –off

System Action: System no longer issues trace messages to the CEET log.


Codes Description



Work Started Error, EMS Status = number

Explanation: User issued a S7MA –workstart. When trying to start the EMS connection, an error was issued from the EMS library. Check the EMS library status return codes for reason. The Work Thread terminated and is not available.

User Response: Lookup EMS status return code to determine why the connection could not be made. Correct situation and reissue command.

System Action: The Work Thread is not started.

Work Thread Started

Explanation: The Work Thread is now started, for example: S7MA –workstart –url urlName

User Response: This is information about the status of the Work Thread. To change that status see S7MA –workstop.

System Action: The Work Thread started.

Work Thread: Terminated

Explanation: The Work Thread is now terminated, for example: S7MA –workstop –addr address

User Response: This is information about the status of the Work Thread. To change that status see S7MA -workstart.

System Action: The Work Thread terminated.

S7M5300E time description

Cannot Find Task ID

Explanation: User issued a S7MA –connstop. The system did not find a matching –id, -addr or – url system.

User Response: Issue S7MA to display active interfaces; verify command parameters and reissue corrected command.



Codes Description



URL:url in CICS EMS Task can not be reached

Explanation: User issued a S7MA -connping. The system did not find a matching URL.

User Response: Issue S7MA to display active interfaces; verify command parameters and reissue corrected command.


S7M5400I time descriptionS7MA

S7M5400I 09:20:31 Total Thds:5 Mast Thds:1 Conn Thds:2 Work Thds:2 ID CB ADDRESS TYPE TASKID STATE URL OR LAST COMMAND AM 000C2000 MAST CMD S7M_SUBTASK_START0002 AC 000C2640 WORK 0000085 tibemsDestination_Destroy0002 AS 1CB58068 WORK CMD C002 16543C002 AC 000C2460 CONN S7M_WORK_STARTC002 AS 1CB713A0 CONN CMD tcp://url-id1:72220001 AC 000C2280 WORK 0000074 tibemsMsgConsumer_Receive0001 AS 1CB57E20 WORK WAIT C001 8123C001 AC 000C20A0 CONN S7M_WORK_STARTC001 AS 1CB71158 CONN CMD tcp://url-id2:7222

Explanation: This is a display of all running threads by issuing a “S7MA” with no sub-options. The user can use the PF7 and PF8 key to backward and forward page through the list.


System Action: Information displayed on terminal screen.


Codes Description



S7M5401I time EMS Ver:number Build:timestampMax Connections: number Max Workers: numberIO: number Mic: number Ave: number Wait: number

Explanation: This is a display of the version and build time stamp (in the format Month Day Year and Time) of the EMS Client currently running. Also shows the Maximum number of Connection and Worker Threads. The IO number is the total number of calls to the CEET, Mic is the total wait time for a CEET call in microseconds, Ave is the average, and Wait is the number of calls that had to issue a CICS WAIT.


System Action: Information displayed on terminal screen.

S7M5902I token = condition event token S0Cx Abend

Explanation: A critical error condition occurred in a Work Thread causing an ABEND. The condition event token is provided by the Language Environment. A CEEDUMP is taken and the Work Thread is terminated.

User Response: Analyze the last EMS API call to this Work thread and check address pointers of parameters passed to the EMS library; the dump will help with this. Correct problem and retry the transaction.

System Action: The Work Thread is terminated.

S7M6200S EXEC CICS WRITEQ TS for Master Pointer - CICS Resp1:response 1 Resp2:response 2

Explanation: A CICS Application Environment Anchor Pointer TS record with pointers to critical data could not be written. S7M3PASS issued a “EXEC CICS WRITEQ TS ” and did not receive a “NORMAL” response. response 1 and response 2 are the CICS response codes for a EXEC CICS WRITEQ TS.

User Response: Analyze the CICS response codes, correct problem and retry transaction.

System Action: The transaction is abended with S7M4 and the CEET environment is not setup.

Destination: DDNAME CEEOUT.


Codes Description



S7M6201S EXEC CICS ENABLE PROGRAM(S7MATRUE) - CICS Resp1:response 1 Resp2:response 2

Explanation: The Enable for the S7MATRUE (TRUE) program failed. On the first call to the CEET after module S7M3EMSS is attached, the routine issues an ENABLE PROGRAM for S7MATRUE. If this command fails, the abend is issued. The system issues the following:

EXEC CICS ENABLE PROGRAM('S7MATRUE'),START, TALENGTH(TRUEWAL),TASKSTART

Without this program properly enabled, the CEET cannot cleanup transaction terminations that use EMS API calls. response 1 and response 2 are the CICS response codes for the above statement.


System Action: The transaction is abended with either S7ME or S7MF and the CEET environment is not setup.


S7M6203S EXEC CICS ADDRESS - CICS Resp1:response 1 Resp2:response 2

Explanation: S7M3PASS issued a “EXEC CICS ADDRESS ” and did not receive a “NORMAL” response. This CICS API is critical to CEET organization. response 1 and response 2 are the CICS response codes


System Action: The CICS transaction is terminated with a S7M1 abend.



Codes Description



S7M6204S No CommArea or CommArea too small

Explanation: For all LINKS to S7M3PASS, a CICS COMMAREA of at least 76 characters is required. A COMMAREA of at least 76 characters was not provided. This area is critical for communications. A S7M3 abend is issued since there is no other way to indicate the problem.

User Response: If the user is accessing S7M3PASS via the S7MASTUB, then an internal problem exists. Please contact TIBCO technical support and provide system logs, CICS dumps, and Auxtrace. Check the LKED for the user program to ensure it includes S7MASTUB.

System Action: The CICS transaction is terminated with a S7M3 abend.



Codes Description


| 103

Appendix A CICS Sample Programs

This appendix describes members required to build and run sample CICS transactions.

Topics

• Message Consumer and Producer Samples, page 104

• JCL and General Procedure Samples, page 105

• Sample Program Data Sets, page 106


104 | Appendix A CICS Sample Programs

Message Consumer and Producer Samples

Message consumer and producer sample programs are described below. The members pertain specifically to CICS online.

For details on running the C and COBOL samples, see Verifying the Installation on page 21.

In addition, a basic sample program in PL/1 is also provided:

Source member: S7MPSM1Transaction ID: S7P1

Table 12 Message Consumer/Producer Samples

Sample Type C Language COBOL

TIBCO EMS Message Consumer

(Functions use non-typed connections and sessions)

Source member: S7M3MC

Transaction ID: S73C

Source member: S7MCMC

Transaction ID: S7CC

BMS map used:S7MCMMP

TIBCO EMS Message Producer

(Functions use non-typed connections and sessions)

Source member: S7M3MP

Transaction ID: S73P

Source member: S7MCMP

Transaction ID: S7CP

BMS map used:S7MCMMP


JCL and General Procedure Samples | 105

JCL and General Procedure Samples

JCL and general procedure samples are described below.

Table 13 General JCL

Member Description

S7MCJCPL JCL to compile COBOL EMS API applications

S7M3JCPL JCL to compile C EMS API applications

RUNGMC JCL to run the standard MVS EMS message consumer

RUNGMMC JCL to run the standard MVS EMS multi-message consumer

RUNGMP JCL to run the standard MVS EMS message producer

Table 14 General Procedures

Member Description

TIB3CCPL Procedure to compile, prelink, and link C applications for z/OS v1.8 and up compiler

TIBCNCPL Procedure to compile, prelink, and link COBOL applications

TIB3NC17 Procedure to compile, prelink, and link C applications for z/OS v1.7 and lower compiler

SXJEXEC Procedure to execute the standard MVS EMS message consumer and producer programs (RUNGMC, RUNGMMC, RUNGMP)


106 | Appendix A CICS Sample Programs

Sample Program Data Sets

The sample programs are contained in the following data sets:

Assembler source code <USERHLQ>.ASM

COBOL source code <USERHLQ>.COB

Copybook <USERHLQ>.COPY

C source code <USERHLQ>.C

Header file <USERHLQ>.H

PL/I source code <USERHLQ>.PLI

Run JCL <USERHLQ>.JCL


| 107

Appendix B Installed Data Set Specifications

This appendix lists all of the installed data sets.

Table 15 Installed Data Sets

Data Set Space (1st/2nd) DSORG RECFM LRECL BLK

SIZE

<USERHLQ>.ASM CYL (3/1) PO FB 80 27920

<USERHLQ>.AUTH CYL (20/10) PO U 0 27920

<USERHLQ>.C CYL (10/1) PO VB 140 27998

<USERHLQ>.CNTL CYL (5/1) PO FB 80 27920

<USERHLQ>.CNTLSAMP CYL (5/1) PO FB 80 27920

<USERHLQ>.COB CYL (5/1) PO FB 80 27920

<USERHLQ>.COPY CYL (5/1) PO FB 80 27920

<USERHLQ>.H CYL (5/1) PO VB 140 27998

<USERHLQ>.INSTALL BLK (8/2) PO FB 80 27920

<USERHLQ>.JCL CYL (5/1) PO FB 80 27920

<USERHLQ>.JCLSAMP CYL (5/1) PO FB 80 27920

<USERHLQ>.LIBRARY CYL (20/1) PO FB 80 3120

<USERHLQ>.LOAD CYL (150/2) PO U 0 27920

<USERHLQ>.OBJ CYL (5/1) PO FB 80 27920

<USERHLQ>.PLI CYL (2/1) PO FB 80 27920

<USERHLQ>.PROC CYL (2/1) PO FB 80 27920

<USERHLQ>.PROCSAMP CYL (2/1) PO FB 80 27920


108 | Appendix B Installed Data Set Specifications
