TIBCO Installation and Reference · TIBCO EMS Client for z/OS (CICS) Installation and Reference ... TIBCO Enterprise Message Service Central Administration

TIBCO® EMS Client for z/OS (CICS)Installation and ReferenceSoftware Release 8.4August 2017

Two-Second Advantage®

Important Information

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

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

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

TIBCO, the TIBCO logo, Two-Second Advantage, TIB, Information Bus, TIBCO Enterprise MessageService, TIBCO Rendezvous, TIBCO SmartSockets, TIBCO ActiveMatrix BusinessWorks, TIBCO Hawk,and TIBCO EMS Client for z/OS (CICS) are either registered trademarks or trademarks of TIBCOSoftware Inc. in the United States and/or other countries.

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

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

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

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

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

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

TIBCO Software Inc. Confidential Information

2

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

Contents

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

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

Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Protocol Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Language Environment (LE) Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

POSIX(ON) Run-time Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

User Profile Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

General Variables Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

FTP Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

CICS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Preinstallation Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

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

Complete Replacement Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Component Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Downloading from the TIBCO Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Installation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Requesting a DVD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

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

Transferring the Initial Installation File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Receiving the Initial Installation File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

PLTs Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Statements for Startup PLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Statements for Shutdown PLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Optional CEEOPTS Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Postinstallation Optional Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Verifying the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Running the CICS Messaging Consumer Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Running COBOL Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Running C Language Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Running the CICS Messaging Producer Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Running COBOL Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Running C Language Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Running the MVS Batch Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Compiling Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

3


Compiling C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Compiling COBOL Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Requirements for Starting Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Architecture and Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

S7MASTUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

S7M3PASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

S7M3EMSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

S7MATRUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

S7M3CLUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

S7M3STRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

S7MACURT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

S7M3STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Component Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Initial CICS User Application Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Subsequent CICS User Application Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Administrative Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

A Checklist for the Programmers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

C Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Codes and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Message Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Message Description Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

CEET Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

ABEND Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

System Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Transaction Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

CICS Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Message Consumer and Producer Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

JCL and General Procedure Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Sample Program Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71

Installed Data Set Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

4


TIBCO Documentation and Support Services

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

https://docs.tibco.com

Product-Specific Documentation

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

TIB_ems_zos_cics_version_docinfo.html

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

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

● TIBCO EMS Client for z/OS (CICS) Release Notes

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

● TIBCO Enterprise Message Service User’s Guide

● TIBCO Enterprise Message Service Central Administration

● TIBCO Enterprise Message Service Installation

● TIBCO Enterprise Message Service C & COBOL Reference

● TIBCO Enterprise Message Service Java API Reference

● TIBCO Enterprise Message Service .NET API Reference

● TIBCO Enterprise Message Service Release Notes

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

How to Contact TIBCO Support

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

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

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

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

https://support.tibco.com

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

5


https://docs.tibco.com


https://support.tibco.com

Product Overview

With TIBCO® EMS Client for z/OS (CICS), you can run applications in CICS Transaction Server toproduce and consume messages that are transported by TIBCO EMS servers.

Messages are structured data that one application sends to another. TIBCO EMS servers, running onplatforms outside the traditional CICS environment under z/OS, act as intermediaries for messages androute them to recipients. The following picture shows the message flow.

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. TIBCO EMS Client for z/OS (CICS) establishes connections to a TIBCO EMS server using standardTCP/IP (not CICS sockets).

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

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

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

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

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

This version of the TIBCO EMS Client for z/OS (CICS) does not support the following functions:● SSL (Secure Sockets Layer)

● Asynchronous message consumption

● Administration

● Assembler language

6


Installation Requirements

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

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

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

Protocol RequirementsThe TIBCO EMS Client for z/OS (CICS) is expected to be installed and operated within a previouslyexisting, fully functional and integrated network.

At a minimum, this includes the following requirements:

● The TCP/IP protocol stack within the z/OS Communications Server.

● A DNS server that provides the host name and host address of the z/OS client and the TIBCO EMSServer.

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

Ensure that you run a properly configured RESOLVER address space.

You must review your TCPCONFIG parameters to ensure that they meet the needs of the installation. Ifyou choose to run TIBCO EMS Client for z/OS (CICS) non-APF authorized, the RESTRICTLOWPORTSparameter must be used. If you want to control TCP buffering, to limit storage usage, or to supportlarge bandwidth devices, the TCPSENDBFRSIZE, TCPRCVBUFRSIZE, and TCPMAXRCVBUFRSIZE parametersmight be needed. It is good practice to override the IBM default of 16K by setting TCPRCVBUFRSIZE andTCPSENDBFRSIZE to a minimum value of 48K.

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

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

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

For more information, see Requirements for Starting Applications.

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 CICSaddress space.

Because of a z/OS limitation, only one TCB in an address space can have the POSIX(ON) run-timeoption. If you have other software that also requires this run-time option, that software and TIBCO EMSClient for z/OS (CICS) have to be in separate CICS regions.

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

7


User Profile RequirementsThe CICS region started task must have a unique user ID assigned by the RACF STARTED class or theICHRIN03 started procedure table.

The user ID 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 assigneduser ID and group, or by utilizing the BPX.DEFAULT.USER FACILITY class profile. It is good practiceto avoid running the associated started tasks as either privileged or trusted if you are using theBPX.DEFAULT.USER FACILITY class profile.

For details on user profile requirements, see Requirements for Starting Applications.

General Variables RequirementsBefore performing the installation, you must obtain the variables and data set HLQs (High LevelQualifiers).

All JCL and procedures supplied with TIBCO EMS Client for z/OS (CICS) have a standard namingconvention. You must replace TIBCO site-specific, installation-defined variables, such as JCL SETstatements, procedure overrides, SYSIN data, and system data set HLQ with user values. You must alsoreplace TIBCO Software variables before the JCL can be submitted for execution.

It is good practice that you copy the following table, review, and complete the entries. Columnheadings are defined as follows:

● Description: provide instructional information.

● Variable: provide the variable name as the variable name is displayed in the provided JCL and themember names. There might be several instances of the same variable within a specific member.

● User Value: insert the appropriate values for your site.

Description Variable User Value

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

<USERHLQ>

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

<USERVOL>

Replace these <JOBNAME> variables with userdefine values.

<JOBNAME>

FTP VariablesA checklist of variables or required items that you must obtain before performing the installationprocess is provided.

The data set suffix and member names are included as reference to where they occur.

● Description: provides instructional information.

● Suffix: lists the suffix of the data set containing the reference.

● Member: contains the variable in question. There might be several instances of the same variablewithin a specific member.

8


Description Suffix Member

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

INSTALL S7M$3FT

Obtain the data set and ormember name where your siteFTPDATA information islocated.

INSTALL S7M$3FT

CICS ComponentsYou can check the programs which TIBCO EMS Client for z/OS (CICS) provides.

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

Parameters Description

S7MACURT Parameters for starting the CEET. For details, see S7MACURT.

DFHPLTXI A DFHPLT is provided if you do not have one. This startup PLTlinks to program S7M3STRT, which initiates the CICS EMSExecution Environment using the parameters set inS7MACURT. This is an optional PLT change that is onlyneeded if starting the CEET automatically with CICSinitialization is desired. For details, see S7M3STRT.

DFHPLTXD A DFHPLT is provided if you do not have one. This shutdownPLT links to program S7M3STOP, which shuts down the CICSEMS Execution Environment correctly. For details, see S7M3STOP.

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

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

9


Preinstallation Tasks

Before installing the software, you must obtain the installation files and upload the files to the z/OS hostsystem.

Obtaining the SoftwareYou can obtain the software and installation files included in the distributed media by downloadingfrom the website or requesting a DVD.

The software is distributed in IBM XMIT format. For non DFSMSdss package, contact TIBCO Supportand request the desired media for your environment.

Complete Replacement PackageBy 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 performed with each installation.

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

Downloading from the TIBCO WebsiteYou can download the software from the TIBCO Software Product eDelivery Site.

Procedure

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

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

3. Download the appropriate files that are in the standard IBM XMIT format.

Installation FilesThe installation files that you have to download are in the standard IBM XMIT format.

Some TIBCO EMS Client for z/OS (CICS) installation file names, including the software package name,include the current three-digit software release version number. Throughout the documentation, thisversion number is referenced as version. For example, the distribution file name is referred to as:

TIB_ems_version_zos_cics.xmit.zip

where version is the TIBCO EMS Client for z/OS (CICS) software release version.

For software release 8.4.0, the distribution file name is:

TIB_ems_8.4.0_zos_cics.xmit.zip

The following table lists the installation files required for the software package:

10


Product Installation Files for z/OS Version 1.10 and Later

TIBCO EMS Client

for z/OS (CICS)

for DFSMSdss

Download this file:

TIB_ems_version_zos_cics.xmit.zip

The zip file contains these files:

TIB_ems_version_zos_cics.xmit.inst

TIB_ems_version_zos_cics.xmit.main

Requesting a DVDIf you do not want to download the software over the network, you can obtain a DVD containing thesoftware and load it directly onto your system.

The minimum time period for delivery of a DVD is five working days. Contact TIBCO Support andrequest the desired media for your environment.

To contact TIBCO Support, do one of the following options:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit http://www.tibco.com/services/support.

● If you already have a valid maintenance or support contract, visit http://support.tibco.com. Entry tothis site requires a user name and password. If you do not have a user name, you can request one.

Uploading the SoftwareAfter obtaining the software packages, you must upload the software packages to the z/OS MVS hostwith the FTP file-transfer utility of IBM.

To upload the software, perform the following tasks:

1. Transferring the Initial Installation File

2. Receiving the Initial Installation File

Transferring the Initial Installation FileTo transfer the EMS Client for z/OS (MVS) initial installation file from a LAN server or PC to the z/OSMVS host, you can use a JCL that contains the statements required for the file transfer.

The following sample JCL uses FTP to copy the EMS Client for z/OS (MVS) initial installation file froma LAN server or PC to the z/OS MVS 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>binaryLOCSITE RECFM=FB LRECL=80 BLKSIZE=27920 TR PRI=60 SEC=15get <userhlq>.xmit.inst' <USERHLQ>.XMIT.INST' (REPLACEquit //*

11



http://support.tibco.com

Receiving the Initial Installation FileAfter transferring the installation files to the z/OS host, you have to receive them during a TIBCO EMSClient for z/OS (CICS) installation on the z/OS host to receive other files and to create the appropriatelibraries.

To complete this process, you can use the <USERHLQ>.XMIT.INST file containing the JCL that is requiredto receive other files and to create the appropriate libraries. TIBCO supplied variables must besubstituted with the appropriate site-specific user values. See General Variables Requirements.

Procedure

1. From the ISPF Command Shell Panel, type the following command to receive the file that containsthe JCL required to begin a first-time installation:receive inda('<USERHLQ>.XMIT.INST')

TSO prompts you with the following information:INMR906A Enter restore parameters or 'DELETE' or 'END' +

2. Supply the following command:DA('<USERHLQ>.INSTALL')

After a successful receive, the following message is displayed:INMR001I Restore successful to data set '<USERHLQ>.INSTALL'

The data set name supplied is the output and it is populated with the members that are required foryou to continue with the installation.

12


Installing the Software

You can use the members that are located in the <USERHLQ>.INSTALL data set to install the CICScomponents for the TIBCO EMS Client for z/OS (CICS).

Edit the selected members indicated in the following steps, substitute the variables, follow anyinstructions contained in the member, and then submit the JCL for execution.

Prerequisites

This software supports only DFSMSdss sites.

Procedure

1. Make CLIST temporary fileChange the #JOBNAME, #USERHLQ, #USERVOL statement variables according to your sitesrequirements.

Member: S7M$1MKT

The following table defines the user substitution variables for the installation JCL.

File Tailoring Variables for Installation JCL

Variable Default and Structure User Value

USERHLQ TIBCO.S7M.VxRxMx

VOLSER Volume Serial TIB999

JOBNAME S7MEMS

First 6 characters

2. Execute file tailoring CLIST for installation JCLIf an error is made during input, press the attention key (PA1) and execute starting at Step 1 again.

Member: S7M$2EX1 (EX member)

3. Upload the TIBCO EMS Client for z/OS (CICS) installation files to your hostUse FTP to upload the files to your host.

Member: S7M$3FT

4. Define and allocate the TIBCO EMS Client for z/OS (CICS) product librariesOnly to be performed on initial installation

Member: S7M$4ALL

5. Convert the TIBCO EMS Client for z/OS (CICS) installation files to DFSMS dump formatMember: S7M$5RCThe following table defines the user substitution variables within JCL and parameter members thatare required during the file tailoring process. Ensure that you have all the necessary informationbefore executing Step 6.

13


File Tailoring Variables

Variable Default and Structure User Value

IBM Assembler LibrariesHLQ

ASM

*.SASMMAC2

COBOL for MVS LibrariesHLQ

IGY

*.SIGYCOMP

TIBCO EMS Server Location hostname: 7222

CICSHLQ

CICS System Libraries HLQ

CICSTS31.CICS

*.CICS.SDFHLOAD

CCSDHLQ

CICS DFHCSD HLQ

CICSTS31.REGION

*.DFHCSD

6. Execute file tailoring CLIST to update the product supplied variables

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

Member: S7M$6EX2 (EX member)

7. Populate the TIBCO EMS Client for z/OS (CICS) product data sets with all the updatesMember: S7M$7UPD

After completing this step, you have finished using the INSTALL library. Most of the subsequentsteps are located within the <USERHLQ>.JCL library.

8. CICS: Update CICS interface resource definitionsThis member updates the CICS System Definition (CSD) file with the Resource definitions necessaryfor TIBCO EMS Client for z/OS (CICS) to operate.

Data Set: <USERHLQ>.JCL

Member: S7MTSCSD

9. CICS: Update startup procedureThe <USERHLQ>.AUTH library that is installed as part of TIBCO EMS Client for z/OS (CICS) mustbe concatenated in the STEPLIB DDNAME of your CICS startup procedures.

Data Set: <Your CICS startup procedure data set>

Member: <Your CICS startup procedure>

10. CICS: Setup startup and shutdown PLTsData Set: <USERHLQ>.ASM

Member: DFHPLTXI and DFHPLTXDSee PLTs Setup for more details.

11. CICS: Setup error program exitCICS programs that use the TIBCO EMS Client for z/OS (CICS) must use the DFHPEP exit toanalyze CICS transaction abends and to provide recovery of the CICS transaction. If you are alreadyusing DFHPEP, you must merge DFHPEP of TIBCO with your code. If you are not using DFHPEP(or using the IBM default), compile the TIBCO DFHPEP (C program) into a loadlib concatenated inthe CICS DFHRPL.

14


Submit the JCL S7M3JCPL to assemble the DFHPEP program. The load module is put into the loadlibrary. Make sure this is the first DSN in the DFHRPL, or replace DFHPEP in the DFHRPLconcatenation list so this version of DFHPEP is used by CICS.

Data Set: <USERHLQ>.C

Member: DFHPEP

12. CICS: Setup default CEET parametersReview the default parameters for starting the CEET.

● HOSTPAGE

● NETWORK

● MAXCONN

● MAXWORK

● TRACE

● URL

● USERID

● PASSWORD

For details, see S7MACURT.

The CICS program sets up the CEET startup default parameters. Submit the JCL S7MASMLK toassemble the S7MACURT program in <USERHLQ>.ASM. The load module is put into the loadlibrary.


Member: S7MASMLK

13. Add DD JCL to CICS JCL for CEET Log

//TIBUOS7M DD SYSOUT=*

If you specify a CEEOPTS parameter then specify a matching DD name for the CEET log. Fordetails, see Optional CEEOPTS Definitions.

PLTs SetupYou must add statements to your SIT for setting up startup and shutdown PLTs.

● Statements for Startup PLT● Statements for Shutdown PLT

Statements for Startup PLTYou must add statements to your SIT for setting up startup PLTs.

A DFHPLT is provided if you do not have one. This startup PLT links to program S7M3STRT, whichbrings up the CICS EMS Execution Environment.

You must add the following statement to your SIT:

PLTPI=XI

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

DFHPLT TYPE=ENTRY,PROGRAM=S7M3STRT

Submit the JCL S7MASMLK to setup the TIBCO default PLT. This job creates module DFHPLTXI in theload library.

15


Statements for Shutdown PLTYou must add statements to your SIT for setting up shutdown PLTs.

A DFHPLT is provided if you do not have one. This shutdown PLT links to program S7M3STOP, whichbrings down the CICS EMS Execution Environment.

You must add the following statement to your SIT:

PLTSD=XD

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

DFHPLT TYPE=ENTRY,PROGRAM=S7M3STOP

Submit the JCL S7MASMLK to setup the TIBCO default PLT. This job creates module DFHPLTXD inthe load library.

Optional CEEOPTS DefinitionsYou can add a DDNAME "CEEOPTS" to the CICS JCL pointing at an input stream with the followingparameters for CEET. The input stream can be either a flat sequential file or a PDS member.ENVAR("S7MLOG=DDNAME")

DDNAME is the JCL DD for CEET log in the CICS JCL.

For example, in the CEEOPTS inut stream:ENVAR("S7MLOG=MYLOG")

Corresponding to this CICS JCL://MYLOG DD SYSOUT=*

16


Postinstallation Optional Tasks

After installation, you must verify that TIBCO EMS Client for z/OS (CICS) is correctly installed andconfigured. You can also run or compile the sample programs.

Verifying the InstallationAfter installing, you must complete several steps to verify that the software has been correctly installedand configured.

Before verifying the installation, you can use the following checklist to ensure that you have specifiedall the required settings to establish communications between the TIBCO EMS Client for z/OS (CICS)and the TIBCO EMS server.

Requirement Check

Is the <USERHLQ>AUTH library APF-authorized?

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

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

Have you restarted your Transaction Server region?

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

● Run the CICS messaging consumer sample program by invoking the appropriate transaction (youcan run either the COBOL or C sample). For details, see Running the CICS Messaging ConsumerSample Program.

● Run the CICS messaging producer sample program by invoking the appropriate transaction (youcan run either the COBOL or C sample). For details, see Running the CICS Messaging ProducerSample Program.

This product also includes a sample MVS consumer and producer for batch testing. The followingactions 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.

17


Running the CICS Messaging Consumer Sample ProgramYou can run either the COBOL or C sample programs to verify the installation.

Running COBOL Consumer

To verify the installation, you can run the COBOL Consumer by invoking the S7CC transaction at ablank 3270 screen.

Procedure

1. Starting with a blank screen, enter S7CC.The following screen is displayed.

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

SERVERURL of the TIBCO EMS server.

DestinationMessage destination type: 1 = queue, 2 = topic.

DestinationName of the queue or topic.

User NameUser name for the TIBCO EMS server, if needed.

PasswordPassword for the TIBCO EMS server, if needed.

3. Press Enter.If a problem occurs when setting up the Consumer process, an error message is displayed at thebottom of the screen. An error might be caused by an invalid value in one of the fields; check fieldvalues and re-enter.

18


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

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

Running C Language Consumer

To run this sample, invoke the S73C transaction at a blank 3270 screen.

Use the following syntax:

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

password

CICS translates parameter values to uppercase. The parameters are as follows:

Parameter Description

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

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

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

-user The user name to connect to the TIBCO EMS server.

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

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

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

An error message is displayed if a problem occurs when setting up the Consumer process. An errormight 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 bythe Consumer are printed to DDNAME CEEOUT. To stop the Consumer process, send the Consumer aTIBCO EMS text message that starts with STOP (uppercase), or stop the Work Thread using the S7MAtransaction.

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

Running COBOL Producer

To verify the installation, you can run the COBOL Producer by invoking the S7CP transaction at a blank3270 screen.

Procedure

1. Starting with a blank screen, enter S7CP.The following screen is displayed.

19


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

SERVERURL of the TIBCO EMS server.

DestinationMessage destination type: 1 = queue, 2 = topic.

DestinationName of the queue or topic.

User NameUser name for the TIBCO EMS server, if needed.

PasswordPassword for the TIBCO EMS server, if needed.

MessageText to be sent in the message.

3. Press Enter to send the message.If a problem occurs when setting up the Producer process, an error message is displayed at thebottom of the screen. An error could be caused by an invalid value in one of the fields; check fieldvalues and re-enter.

4. Edit the field values and press Enter to send subsequent messages, or press PF3 to exit.If you want to clear values from the fields, press PF5.

Running C Language Producer

To run this sample, invoke the S73P transaction at a blank 3270 screen.

Use the following syntax:

S73P -server server -count num {-topic topic-name | -queue queue-name} -user

username -password password -text msg-text

CICS translates parameter values to uppercase. The parameters are as follows:

20


Parameter Description

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

-count The number of times to repeat the message. Default is 1. Valid range is 1 to 99999.

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

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

-user The user name to connect to the TIBCO EMS server.

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

-text The text of the message.

The following example invokes a Producer that connects to a server with the URL emsserverurl:7222 andsends 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 is displayed if a problem occurs when setting up the Producer process. An errormight 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 programproduces a single message to the screen when it ends.

Running the MVS Batch ServicesYou can run TIBCO EMS messaging consumer batch program or TIBCO EMS messaging producerbatch program to communicate with the CICS messaging Consumer and Producer.

TIBCO EMS Messaging Consumer Batch Program

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


Member: RUNGMC

TIBCO EMS Messaging Producer Batch Program

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


Member: RUNGMP

Compiling Sample ProgramsTIBCO EMS Client for z/OS (CICS) sample programs are supplied as source and executable modules aspart of the installation. However, you might want to change the source code to perform additionalfunctions. JCL and procedures have been supplied to compile the sample programs that normally haveto be modified to be used within an environment.

Edit the data sets and selected members listed in the following sections. Substitute the variables, followany instructions that are contained in the member, and submit it for execution.

21


Compiling C ProgramsTo change the source code for performing additional functions, you can compile C programs.

● C language options file

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

Data Set: <USERHLQ>.CNTL

Member: OPTFGEN

● TIBCO EMS C language compilation JCL

The following JCL uses a procedure that might have to be modified so that it conforms to therequirements of your site and executes correctly.


Member: S7M3JCPL

Compiling COBOL ProgramsTo change the source code for performing additional functions, you can compile COBOL programs.

The following JCL uses a procedure that might have to be modified so that it conforms to therequirements of your site and executes correctly. This member compiles COBOL supplied sampleprograms.


Member: S7MCJCPL

Requirements for Starting ApplicationsBefore you start applications, some requirements must be met.

User Profile Requirements

The CICS region started task used to run the TIBCO EMS Client for z/OS (CICS) must have a uniqueuserid assigned by the RACF STARTED class or the ICHRIN03 started procedure table. The useridassigned must have a valid z/OS Unix security context, or OMVS segment, in both the userid profileand group profile. Alternatively, the BPX.DEFAULT.USER FACILITY class profile, or equivalent ifRACF is not used, can provide the appropriate z/OS Unix security context. Before attempting to runTIBCO EMS Client for z/OS (CICS), you must have your z/OS security administrator verify propersetup.

It is good practice that you do not establish resource limits within the OMVS segment of the userid.Instead, the values specified in BPXPRMxx must be used where possible. Additionally, you must avoidusing UID 0 (superuser) in the OMVS segment of the userid assigned to the CICS region started task.

Case Sensitivity

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

22


Architecture and Administration

To use TIBCO EMS Client for z/OS (CICS), it is good practice to know the architecture andadministration of this product. Before performing any administrative procedures, you must havecompleted the installation of the software, and have executed the IVP steps successfully.

System ArchitectureWithin a CICS region, product components are located in two separate environments – an applicationenvironment, and an EMS execution environment.

The following picture shows the main components and architecture of TIBCO EMS Client for z/OS(CICS).

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

CICS Application Environment

These product components perform the following functions:

● 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 theruntime interactions to the CEET Work Threads.

● S7MATRUE: releases CEET Work Threads upon transaction end.

● S7M3CLUP: an independent cleanup routine tied to transaction S7ML.

CICS EMS Execution Environment

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

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

The operation sequence of component is as follows:

23


1. Copy the TIBCO EMS function name and its associated parameter list from a “null delimitedcharacter 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 thereturn variable of the function call.

4. Return to calling application.

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

The operation sequence of component is as follows:

1. Check for a CEET workarea.

2. If a workarea is present, 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 operation sequence of component 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 (casesensitive) 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 ontransaction 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 containingS7M3EMSS 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 MAXCONNparameter in S7MACURT).

● Connection Thread – starts and stops Work Threads (up to the value specified in the MAXWORKparameter in S7MACURT).

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

24


● Language Environment Condition Handler – while supporting the Work Threads, it enablesrecovery from S0Cx abends so that only the Worker terminates, while the rest of the CEET remainsand 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”), asfollows:

● 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 TemporaryStorage.

If TEMPORAY STORAGE does not exist, S7MATRUE returns to CICS. If a Temporary Storage record isfound, S7MATRUE checks if there are open EMS connections. If so, a CICS LINK is issued forS7M3CLUP to clean up the open connections and handle the freeing up of the CEET Work Thread. IfS7MATRUE finds there are no open connections or other issues, S7MATRUE modifies the controlblocks and deletes the Temporary Storage.

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

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.

S7M3CLUP can perform the following functions:

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 atCICS initialization.

This component can perform the following functions:

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.

S7MACURTThe S7MACURT parameters are used for starting the CEET.

The following table shows the details.

25


Parameters Description

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 and16, 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).

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

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

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

Component InteractionThis section describes the main TIBCO EMS Client for z/OS (CICS) product components, how eachoperates, and the interaction between these components.

The following diagram shows the interactions that occur when a CICS user application issues a TIBCOEMS function call.

26


Initial CICS User Application Transaction

This topic describes the sequence of events that occur in a CICS transaction.

Initial TIBCO EMS Function Call

The following information describes the events that occur with the 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 andparameter 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 tostart 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 theConnection 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 parameterspassed by the user application in step 1.

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

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

27


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

15. S7MASTUB returns the data to the user application.

Subsequent TIBCO EMS Function Calls

The following information describes the events that occur on subsequent function calls.

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



4. S7M3PASS knows there is a Work Thread available in the CEET to support this CICS transaction, soS7M3PASS 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 modifiesthe data as needed based on the parameter list.



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

Final TIBCO EMS Function Call

The following information describes the events that occur in the final function call for this transaction.

1. The user application issues tibcoConnection_close.



4. S7M3PASS knows there is a Work Thread available in the CEET to support this CICS transaction, soS7M3PASS 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 modifiesthe data as needed based on the parameter list.



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 might or might not be thesame as that specified for the initial transaction.

The S7M3PASS component can cause a new Connection Thread to be started when the specified URLparameter is not the same, as described in the following contents.

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

28


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 Threadfor 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 aspreviously described.

Administrative CommandsTIBCO EMS Client for z/OS (CICS) provides an administrative transaction (S7MA) for controlling andmonitoring various functions.

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 CICSinstallation). Most CICS terminals only support uppercase text; however, you might have to uselowercase text; for example, user names and passwords for a secure TIBCO EMS server are casesensitive. The following parameters are provided to convert input text to lowercase or uppercase, andcan be used in combination on the command line:

● –L or -l (translates to lowercase)

● –U or -u (translates to uppercase)

For example, you specify the following commands on the command line:

S7MA –connstart –l –url SAMPLEURL -u -user sampleid

The resulting URL can be translated to sampleurl and the user can be translated to SAMPLEID.

Note that these parameters are useful for –url, -user, and –pwd. However, values for these cannot bemixed-case text, since such text is not supported by the S7MA transaction. For example, if a user ismixed-case, (such as MyUserName ), consult your administrator to change it to lowercase or uppercase.

29


Command SummaryYou can check the administrative commands.

Usage Commands

Starting/Stopping connstart – starts a new Connection Thread.

connstop – stops a Connection Thread and all associated WorkThreads.

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 codepage – displays the host and network code pages being used bythe CEET.

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.

help – displays all available commands.

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 Clientcurrently running.

Command DescriptionsThis section provide explanation and usage of each command. You can use different commands toperform different functions.

–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 pingcommand is sent to the Connection Thread.

30


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

This command starts a new Connection Thread. The urlName is the URL connection ID the newConnection Thread is to be known by. The system looks for a Connection Thread with the specifiedURL connection id. If found, the command is ignored; otherwise a new Connection Thread is startedusing 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 URLconnection ID to stop, the id is thread ID to stop. The system looks for a Connection Thread with thespecified URL connection id, or a Work Thread with the specified id; if found, the system terminates theconnection 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 Accessand Threads are affected by the setting of this command. When no option value is specified, the defaultvalue of off is used.

–display [–skip n]

This command displays the status of the CEET, listing all active threads. You can use the –skip noption to page forward in the list, or the F8 key to page forward and the F7 key to page backwards.

A sample display is shown as follows:S7M5400I 09:20:31 Total Thds:5 Mast Thds:1 Conn Thds:2 Work Thds:2ID CB ADDRESS TYPE TASKID STATE URL OR LAST COMMANDAM 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

● 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 linesrepresent information about active threads. The Master Thread displays on a single line (identified byMAST in the TYPE column). Each Work or Connection Thread is represented by a pair of lines, oneafter the other in the listing (identified by WORK or CONN in the TYPE column).

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.

31


Column Description

CB The type of control block.

AC – the ACMEM (CICS Application side); displays on the upper line foreach 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.

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. 0000000indicated 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 takecommands 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 thethread; the lower line displays the URL connection ID of the thread.

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

–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 CEEMSG.

–dumpall

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

–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 DDNAMECEEMSG.

32


–masterstart [–hostpage hostcodepage] [–netpage networkcodepage]

This command starts the Master Thread. If the Master Thread is already started, the command isignored. Only one Master Thread can exist. The optional hostcodepage and networkcodepageparameters specify the code pages to be used when starting the CEET. These override the defaultsspecified 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 youspecified the –force option, the Master Thread is terminated via an Operation System Stop.

–mastertrace –[off | on]

CEET. All Master events, Connection Access, and Work Threads are affected by the setting of thiscommand. 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 toscreen and DDNAME CEEOUT.

–print

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

–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 displayedusing the DISPLAY option. The Work Thread is freed up and can be used by another new CICStransaction. If a user’s CICS transaction is purged, the Work Thread is not released. With this command,you can free up the Work Thread if the Work Thread is in CMD mode. If the Work Thread is in WAITmode, the Work Thread will have to be stopped using S7MA -workstop.

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

This command starts a new Work Thread. The urlName is the URL connection you want the WorkThread to be started on. The system looks for an existing Connection Thread with this urlName. Iffound, that Connection Thread is used to start the new Work Thread; otherwise, a new ConnectionThread 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 theDISPLAY option. The Work Thread is terminated. If a user CICS transaction is purged the Work Threadis not released. With this command, you can 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 aCICS transaction is currently active and allocated to the Work Thread, that CICS transaction receives astatus return code.

33


A Checklist for the ProgrammersAll application programmers in CICS under z/OS environment must check the checklist.

● The first TIBCO EMS API call must be a successful tibcoemsConnection_Create – if unsuccessful, thetransaction does not have a CEET Work Thread, without which no TIBCO EMS API calls can beprocessed.

● The tibemsConnection_SetExceptionListener API is automatically done for the Work Thread when it isfirst started, so this API is available to the user transaction. Consequently, it is important thattransactions make sure the first tibcoemsConnection_Create is the one they use to receive messages. Inthis situation, the Work Thread can pass status back to the transaction for Connection disruptions. Ifthe transaction issues tibcoemsConnection_Create for other URLs, they will not be monitored, becauseonly 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 aSYSTCPD DD statement in the execution JCL. Contact the TCP/IP support personnel of yourorganization 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 are located in the <USERHLQ>.C data set.

— 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 are located in the <USERHLQ>.COB data set.

— The requirements are specified in the applicable compile procedure.

34


Codes and Messages

TIBCO EMS Client for z/OS (CICS) can produce the CICS transaction ABEND codes, system messages,and CICS transactional messages.

A tibems_status value represents an API return code and values ranging from 1000 to 9999 are specificto the TIBCO EMS Client for z/OS (CICS).

OverviewYou can get a general overview of the message identifiers, message description format, and the CEETlog.

Message IdentifiersAAA nnnn S <message text>

The parts of the format are as follows:

AAAThis is the product code. All ABEND codes and messages use the S7M product code that represents theTIBCO EMS Client for z/OS (CICS). Return codes do not include this product code in the messageidentifier.

nnnnIt is a four-digit number in the range 1001 through 6000, with the exception of ABEND codes (see thefollowing contents).

● 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 productcode prefix. Example: 1005.

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

SIt is the message severity code, which is separated from the message text by blanks. The severity codedefines the importance of the message.

● I — Informational. These types of messages are usually advisories or a reply to a requestperformed 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 isrequired, probably with help from your system support personnel.

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

Message identifierIt is in the form AAA nnnn S. You can see Message Identifiers for details.

Message text

35


It refers to the words and inserts which make up the message as displayed by the TIBCO EMS Clientfor z/OS (CICS).

ExplanationIt refers to the events leading to or following the production of the message.

User ResponseIt refers to the action recommended for the user (the console or system administrator or programmer).

System ActionIt refers to the action that has been or will be taken by the TIBCO EMS Client for z/OS (CICS).

DestinationIt refers to 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.

ABEND CodesTIBCO EMS Client for z/OS (CICS) can produce the CICS transaction ABEND codes.

The following table shows the details of the 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 iscritical to CEET organization.

User Response: Check system log for message S7M6203S. Analyze the CICSresponse 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 76characters 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 noother way to indicate the problem.

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


36


Code Description

S7M4 ABEND

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

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


S7ME ABEND

Explanation: The Enable for the S7MATRUE (TRUE) program failed. On the first callto CEET after the module S7M3EMSS is attached, the routine issues a ENABLEPROGRAM for S7MATRUE. If this command fails, the abend is issued.

The system issues the following statements:

EXEC CICS ENABLE PROGRAM('S7MATRUE'),START,

TALENGTH(TRUEWAL),TASKSTART

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

User Response: Check the system log and the DDNAME CEEOUT to determinewhy the S7MATRUE cannot be enabled as a CICS TRUE. Check that S7MATRUE isdefined properly. Try issuing command manually with CECI to check return codesfrom CICS response. Check that S7M3PASS is defined properly. S7ME produces adump; in the trace table you can find the CICS response code to the enable.


S7MF ABEND

Explanation: The Enable for the S7MATRUE (TRUE) program failed. On the first callto CEET after the module S7M3EMSS is attached, the routine issues a ENABLEPROGRAM for S7MATRUE. If this command fails, the abend is issued.

The CEET setup system issues the following statements:

EXEC CICS ENABLE PROGRAM('S7MATRUE'),START,


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

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


Return CodesA tibems_status value represents a return code that is passed back to the application after a TIBCO EMSAPI 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 TIBCOEnterprise Message Service C and COBOL Reference. Values ranging from 1000 to 9999 are specific toTIBCO EMS Client for z/OS (CICS) and are described in the following table.

37


Code Description

1005 Invalid URL pointer sent with Connection thread stop command.

Explanation: The user issued a Connection stop command for a Connection Threadprobably by a S7MA -connstop. The Master Thread received the command butcould not find a Connection Thread with the URL. The Master Thread ignores thecommand and the system returns 1005 status.

User Response: Check that the system is running properly by issuing S7MAcommands and check the system log for other errors. The user must verify the stateof the CEET system and issue a S7MA command and/or review the CEET log todetermine the reason for the Work Thread termination. Check to see if anotherprogram 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.

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

Explanation: The user issued a debug on command for a Connection Thread,probably by a S7MA -conntrace. The Connection Thread received the command, butwhen testing the ACMEM pointer, found it invalid. The Connection Threadterminates and the system returns 1006 status.

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

System Action: The Connection Thread is stopped as well as all Work Threadsassociated 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 by a S7MA -conntrace. The Connection Thread received the command, butwhen testing the ACMEM pointer, found it invalid. The Connection Threadterminates and the system returns 1007 status.

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

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

38


Code Description

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 WorkThread. Since a Work Thread has not been allocated to this CICS transaction, thesystem tries to allocate a free one or start a new one. Both allocation types havefailed. If the EMS Library API call is a tibemsConnection_Create, the system returns1008 status.

User Response: Check the number of Work Threads running using the S7MAtransaction. Check the system log and CEET log to determine why the Work Threadcould not be allocated. Possible reasons for this abend include the followingreasons:

● The maximum of 127 Work Threads was reached so no further Work Threadscan be started.

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

● A stop workthread or connection command was issued.

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

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

1009 Invalid ACMEM pointer sent with Connection Thread stop command.

Explanation: The user issued a stop command for a Connection Thread, probablyby a S7MA -connstop. The Connection Thread received the command, but whentesting the ACMEM pointer, found it invalid. The Connection Thread terminatesand the system returns 1009 status.

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

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

39


Code Description

1010 Invalid ACMEM pointer sent with Connection Thread start command.

Explanation: The user issued a start command for a Connection Thread, probablyby a S7MA -connstart. The Connection Thread received the command, but whentesting the ACMEM pointer, found it invalid. The Connection Thread terminatesand the system returns 1010 status.

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


1011 Invalid ACMEM pointer sent with Connection Thread ping command.

Explanation: The user issued a ping command for a Connection Thread, probablyby a S7MA -connping. The Connection Thread received the command, but whentesting the ACMEM pointer, found it invalid. The Connection Thread terminatesand the system returns 1011 status.

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


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 anddid not have a Work Thread allocated to the CICS transaction. First time calls mustbe either a connection request or a supervisory command. This error code can alsobe received if the Work Thread allocated to the CICS transaction terminates(normally or ABENDS) while the CICS transaction is running.

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

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

40


Code Description

1016 Function not found in command list.

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

User Response: The users have to verify the TIBCO function being used, correct theprogram, and retry the transaction.

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

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

Explanation: The user issued a stop command for a Work Thread, probably by aS7MA -workstop. The Connection Thread received the command, but when testingthe pointer, found it invalid or could not find the Work Thread. The ConnectionThread ignores the command and the system issues returns 1024 status.

User Response: Check that the system is running properly by issuing S7MAcommands and check the system log for other errors. The users have to verify thestate of the CEET system and issue a S7MA command and/or review the CEET log todetermine the reason for the Work Thread termination.

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

1040 Missing URL.

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

User Response: The user must verify that the tibemsConnection_Create API has avalid URL string.


1041 Invalid control block in CICS Application Environment.

Explanation: An invalid control block pointer was found in the CICS ApplicationEnvironment. The pointer to the control block is invalid or the start/end ID stored inthe control block is invalid. There is one control block in the CICS ApplicationEnvironment for each Connection and Work Thread in the CEET.

User Response: Contact TIBCO support and report the error. It is good practice toprovide the CEET log, DDNAME CEEOUT output, and CICS SYSLOG.


41


Code Description

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 blockfor each Connection and Work Thread in the CEET.



1043 The CEET is stopping.

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

User Response: The user programs have to take the steps necessary to terminate theprogram 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 does not honorany new Connection Thread Start, Work Thread Start or Work Thread Allocationrequests directly or indirectly (tibemsConnection_Create causes the CEET master toissue Connection Thread starts, Work Thread starts and/or Work Thread Allocationrequests).

User Response: The user programs have to take the steps necessary to terminate theprogram either normally or abnormally. If you want to restart CEET master, issue aS7MA -masterstart and reissue the transactions.


1045 The Connection Thread could not be started.

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

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


42


Code Description

1046 The Work Thread could not be started.

Explanation: A S7MA -workstart or a tibemsConnection_Create was issued, so theCEET master does not have an open Work Thread for the URL attempting to start anew Work Thread. The Work Thread could not be started. Messages in the systemlog should indicate why the Connection Thread was not started. The possiblereasons are as follows:

● Bad URL.

● The Master Thread was stopped.

● MAXWORK has been exceeded.

User Response: The user programs have to take the steps necessary to terminate theprogram either normally or abnormally. Check the CEET log for why the WorkThread could not be started.


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

Explanation: The Work Thread terminated when processing a tibems API function.The Work Thread terminated while processing a tibems API function for the usertransaction. Messages in the system log should indicate why the Work Thread wasnot started. The common reasons are as follows:

● 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 ConditionRaise (System exception like an S0Cx).

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

User Response: The user programs have to take the steps necessary to terminate theprogram either normally or abnormally. Check the system log for why the WorkThread could not be started.


1048 Invalid control block combination.

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

User Response: Contact TIBCO support and report the error. You are required toprovide the CEET log, DDNAME CEEOUT output, and CICS SYSLOG.


43


Code Description

1050 Invalid anchor control block in CICS Application Environment.

Explanation: Invalid anchor control block in CICS Application Environment wasdiscovered.

Either the pointer to the control block is not valid or the start ID of the control blockis invalid or end indicator of the control block is invalid. There is one control blockfor 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 blockis invalid or end indicator of the control block is invalid. There is one control blockfor the Master thread in the CEET.



1052 Master Thread has ended.

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

User Response: The user programs have to take the steps necessary to terminate theprogram, either normally or abnormally.

Contact TIBCO support and report the error. It is good practice to provide the CEETlog, DDNAME CEEOUT output, and CICS SYSLOG.


44


Code Description

1064 Work Thread stopped.

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

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

● The Work Thread to support the CICS transaction has terminated because of aproblem. Review the CEET log to determine the reason for the Work Threadtermination.

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


System MessagesTIBCO EMS Client for z/OS (CICS) can produce system messages.

The following table shows details about the system messages.

Code Description

S7M1000I S7M1000I hh:mm:ss.mmmm - Date MM/DD/YY

Explanation: This message indicates that the date has changed.

Destination: CEET log.

S7M1001I Connection Thread address Ended

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


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 ConnectionThread is invalid.


45


Code Description

S7M1101E Could not find open Connection ASMEM Control Block

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

User Response: Verify the number of Connection Threads that are running by usingtransaction S7MA. Stop Connection Threads that are no longer needed and retrytransaction. Remember — when stopping a Connection Thread, all Work Threadsassociated with the Connection Thread 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 iszero.


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


S7M1103E Invalid ACSTART pointer

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




S7M1104E Invalid ACIDE pointer

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




S7M1200I before Post of CICS transaction

Explanation: The trace point in Master before issuing Post.


46


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 AMMEMaddress 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 theURL given does not match any running Connection Threads.

User Response: Must check the URL ID of the Connection Thread you want toterminate 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 theASMEM address given does not match any running Connection Threads.

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

System Action: Ignore command to stop Connection Thread.


S7M1470E Invalid ASMEM pointer

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


System Action: Master ignores command.


47


Code Description

S7M1471E Invalid ASSTART pointer

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




S7M1472E Invalid ASIDE pointer

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




S7M1482S Invalid AMMEM pointer

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


System Action: Master Thread terminates.


S7M1483S Invalid AMSTART pointer

Explanation: Routine entered to test for valid AMMEM control block—the header IDis 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 tothe User.


48


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 tothe 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 thecontrol block in the CICS Application Environment and AMS is the control block forthe Master Thread in the CEET. Also shows the current version of the EMS Clientand 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 ConnectionThreads and Work Threads end.


S7M1502I time Maximum Connections:num Maximum Workers:num

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


S7M1503I time HostCodePage:hostcodepage, NetworkCodePage:networkcodepage

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


S7M1504I time Error:number, HostCodePage:hostcodepage,

NetworkCodePage:networkcodepage

Explanation: Message issued by CEET at startup to indicate an error was returnedfrom tibems_SetCodePages. The error number is the returned tibstatus. Error:74means 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.


49


Code Description

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 manyConnection Threads are still active.


S7M2011I work_cleanup_asmem POINT n

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


S7M2013E CONN ASMEM Invalid Start ignored

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


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


S7M2014E CONN ACMEM Invalid Start ignored

Explanation: This message indicates the Connection Thread has found an invalidConnection 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 justbefore posting the CICS transaction.


50


Code Description

S7M2022I before wait of Connection Thread

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


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

Explanation: When a Connection Thread starts, it issues a tibemsConnection_Createfor 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 theconnection cannot be made. Correct the problem and retry the transaction thatstarted the Connection Thread.

System Action: The Connection Thread is terminated.

S7M2101I CONN ASMEMPTR = address

Explanation: This message indicates the Connection Thread address of the ASMEMupon 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 tothe Work Thread for ASMEM address. The return code from the thread_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 threadcreate routine and issued a thread create—RC is the return code.


S7M2211I Work Watch Create—RC = RC

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


S7M2222E Command Not Found: command

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

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

System Action: The command is ignored.


51


Code Description

S7M2223I Cmd Address: address

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


S7M2224E BAD S7M_SUBTASK_PING—Ping Received

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


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


S7M2225E BAD S7M_SUBTASK_DBGF—Debug OFF Received

Explanation: This message indicates the Connection Thread received a trace offcommand 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 an endcommand 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 threadcreate routine but could not find an open ASMEM to use (128 permitted).

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

System Action: The command is ignored for Work Thread.


52


Code Description

S7M2229E BAD S7M_SUBTASK_START—START Received

Explanation: This message indicates the Connection Thread received a startcommand 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 invalidAMMEM pointer—the address is 0.




S7M2231E Invalid AMSTART pointer

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




S7M2237E Work Thread WThd not found on Conn thread CThd

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

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

System Action: The command is ignored for Connection Threads.


53


Code Description

S7M2237I BAD S7M_SUBTASK_DBGO—Debug ON Received

Explanation: This message indicates the Connection Thread received a trace oncommand from the CICS Application Environment for all Connection Threads withinvalid control block address.




S7M2238E Work Thread parm not present

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




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 ConnectionThread Conn thead ID and the Connection Thread could not find the Work Threadon its list of threads it has started.

User Response: Use S7MA to see if the Work Thread is still active (it might haveterminated before the command was processed). Use S7MA to determine whichConnection Thread controls the Work Thread. Issue a S7MA –workstop or S7MA –connstop for terminating 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 invalidAMMEM pointer—the end indicator is invalid.




S7M2250I WORK ASMEM address—ACMEM address

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


54


Code Description

S7M2310I Connection Thread Started for URL urlid

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


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 InvalidASMEM 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 InvalidACMEM for the Connection Thread during processing of the Work Start Command.




S7M2812E WORK ACMEM Invalid Start ignored

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


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


S7M2999I time Connection shutdown – number Work Threads Active

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


55


Code Description

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 theaddress of the ACMEM control block for this thread. asmem is the address of theASMEM control block for this thread. thread id is the thread ID of this Work Thread.


System Action: The EMS Work Thread is started.

S7M3014E WORK Thread # thead id tibemsErrorContext_Create EMS status: status

Explanation: The Work Thread issued an EMS API call fortibemsErrorContext_Create and EMS returned a nonzero status code. ThetibemsErrorContext_GetLastErrorStackTrace and thetibemsErrorContext_GetLastErrorString EMS API calls do not work on this specificWork Thread since the Context Object ID is not available.

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

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 theaddress of the ACMEM control block for this thread. asmem is the address of theASMEM 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 avalid ACMEM pointer.


S7M3110I Condition Handler Registration OK

Explanation: This message indicates the Work Thread is at the start point and sets aCondition Handler.


56


Code Description

S7M3200E Condition Handler Registration Failed

Explanation: This message indicates the Work Thread is at the start point and couldnot 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 ConnectionThreads, 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.


S7M3404I Processing Debug Off

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


S7M3405I Processing Debug On

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


S7M3500I Processing WTO Function

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


S7M3501I Beginning Command Table Search

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


57


Code Description

S7M3550E Function Found—Zero Address

Explanation: This message indicates the Work Thread found match for command insearch 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.


S7M3561E Function Not Found: command

Explanation: This message indicates the Work Thread did not find the command inthe 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 commandwas ignored.


S7M3750I EXC: function

Explanation: This message indicates the Work Thread command the program isgoing 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/waitroutine.


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.


58


Code Description

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 returncode. The trace entry is preceded by message S7M3570I. This is passed back to theUser 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 ispassed back to the User Program as the Tibco_status.


S7M3960E Bad ACMEM - ACSTART

Explanation: This message indicates the Work Thread found an invalid ACMEMcontrol block in the CICS Application Environment—the beginning of the controlblock as an ID that is missing. This is a major problem indicating that the ControlBlock has been corrupted.




S7M3961E Bad ACMEM - ACIDE

Explanation: This message indicates the Work Thread found an invalid ACMEMcontrol block in the CICS Application Environment—the end of the control block asan ID that is missing. This is a major problem indicating that the Control Block hasbeen corrupted.




59


Code Description

S7M3962E Bad ASMEM - ASSTART

Explanation: This message indicates the Work Thread found an invalid ASMEMcontrol block in the CEET—the beginning of the control block as an ID that ismissing. This is a major problem indicating that the Control Block has beencorrupted.




S7M3963E Bad ASMEM—ASIDE

Explanation: This message indicates the Work Thread found an invalid ASMEMcontrol block in the CEET—the end of the control block as an ID that is missing. Thisis 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 operatingsystem.


S7M4900I S7M3COND Entered # number

Explanation: This message indicates that a Work Thread Condition (ABEND) hasoccurred and the Condition Handler has been entered. This number is a count ofConditions (ABENDs).


S7M4902I token = token S0Cx Abend

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


S7M4908E Invalid ACMEM

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


System Action: The Work Thread continues to terminate.


60


Code Description

S7M4910I Func: S7M3COND Exited Error #:Num

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


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

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


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

Transaction MessagesTIBCO EMS Client for z/OS (CICS) can produce CICS transactional messages.

The following table shows the details of the transaction messages.

Codes Description Explanation

S7M5100I

(time description)

Cannot Find Task ID Explanation: User issued a S7MA –connstop. Thesystem did not find a matching –id, -addr or – urlsystem.

User Response: Issue S7MA to display activeinterfaces; verify command parameters and reissuecorrect command.


CICS EMS Master NotRunning - No TSPointer

Explanation: The CEET is not active.

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


CICS EMS TaskStopped

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

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


61



URL:urlname in CICSEMS Task cannot bereached

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

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


S7M3ADM -Unknownparameter:parm

Explanation: An unsupported S7MA sub-command had entered.

User Response: Review and correct the commandand submit again.


S7M5100E

(time description)

Cannot FindConnection Thread forWork Thread id

Explanation: User issued a S7MA –connstop. Thesystem did not find a matching –id, -addr or – urlitem.

User Response: issue S7MA to display activeinterfaces; verify command parameters and reissuecorrected command.


CICS EMS TaskStopped

Explanation: Before issuing this command, userissued a S7MA -masterstop and the CEET interfaceis not running.



EMS Task CB hasterminated with Code

Explanation: When starting the CICS EMS masterprogram, the program terminated with thefollowing Code Posted to the Task ECB. The TaskECB Post is from MVS and indicates why theprogram was terminated. The CEET interface is notrunning.

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

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

62



EMS Task CB hasterminated with Code

Explanation: When starting the CICS EMS masterprogram, the major control blocks (AM) werecorrupted. The CEET interface is not running.

User Response: Issue a S7MA -masterstop tocleanup 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. TheCEET interface is not running.

Invalid CONNASMEM ThreadPointer

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

User Response: Issue S7MA to display interfacesstatus.

System Action: The command stops the CEETinterface.

S7M5200I

(time description)

CICS EMS Master,Connection and WorkThreads Stopped

Explanation: User issued a S7MA -masterstop. Allthreads are stopped and none is started until aS7MA –masterstart is issued.


System Action: The CEET interface is terminated.

Connection PINGIssued Return Code =0

Explanation: The Connection Thread is sent aPING command and the return code is displayed.Return code of zero (0) indicates everything isworking correctly. A response of:

URL: urlName in CICS EMS Task cannot be

reached

means there is no Connection Thread for thespecified URL or the Connection Thread is notworking properly.

User Response: This is information about thestatus of the Connection Thread in response to, forexample:

S7MA –connping –url urlName

System Action: None.

63



Connection StartedError, EMS Status =number

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

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

System Action: The Connection Threadterminated.

Connection ThreadStarted

Explanation: The Connection Thread is nowstarted, for example:

S7MA –CONNSTART –URL urlName

User Response: This is information about thestatus of the Connection Thread. To change thatstatus, see S7MA -connstop.

System Action: The Connection Thread started.

Connection Threadand All Work ThreadsStopped

Explanation: The Connection Thread and all itsWork Threads have stopped, for example:

S7MA –connstop {–url urlName} |{–id id}

User Response: This is information about thestatus of the Connection Thread. To change thatstatus, see S7MA –connstart.

System Action: The Connection Thread and AllWork Threads stopped.

Num Control BlocksPrinted

Explanation: The list of active threads is listed toDDNAME CEEOUT. The output is similar to theS7MA display command. It indicates how manycontrol blocks were printed.

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

System Action: Printed CEET status to DDNAMECEEOUT.

number TCBs looked at- POSIX (ON) found

Explanation: Routine looked at all attached TCBsin the CICS address space and found a TCB withthe POSIX (ON) runtime option. Relatedinformation sent to screen and JES output.


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

64



number TCBs looked at- POSIX (ON) NOTfound

Explanation: Routine looked at all attached TCBsin the CICS address space and did not find a TCBwith the POSIX (ON) runtime option.


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

Master AlreadyRunning

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



Master Thread Started Explanation: The CEET is now started:

S7MA –masterstart

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

System Action: The CEET started.

Master Trace On Explanation: This command turns on the tracefeature on the Master Thread, all ConnectionThreads, and all Work Threads.

User Response: This is information about thestatus of all threads as a response to:

S7MA –mastertrace –on

System Action: All threads produce tracemessages to the CEET log.

Master Trace Off Explanation: This command turns off the tracefeature on the Master Thread, all ConnectionThreads, and all Work Threads.

User Response: This is information about thestatus of all threads as a response to:

S7MA –mastertrace –off

System Action: System no longer issues tracemessages to the CEET log.

65



Work Started Error,EMS Status = number

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

User Response: Lookup EMS status return code todetermine 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, forexample:

S7MA –workstart –url urlName

User Response: This is information about thestatus 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 thestatus 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. Thesystem did not find a matching –id, -addr or – urlsystem.

User Response: Issue S7MA to display activeinterfaces; verify command parameters and reissuecorrected command.


URL: url in CICS EMSTask cannot bereached

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

User Response: Issue S7MA to display activeinterfaces; verify command parameters and reissuecorrected command.


66



S7M5400I

(time description)

S7MA S7M5400I 09:20:31 Total Thds:5 Mast Thds:1 Conn Thds:2 Work Thds:2ID CB ADDRESS TYPE TASKID STATE URL OR LAST COMMANDAM 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 runningthreads by issuing a “S7MA” with no sub-options.The user can use the PF7 and PF8 key to backwardand forward page through the list.


System Action: Information displayed on terminalscreen.

S7M5401I time EMS Ver: numberBuild: timestamp

Max Connections:number Max Workers:number

IO: number Mic:number Ave: numberWait: number

Explanation: This is a display of the version andbuild time stamp (in the format Month Day Yearand Time) of the EMS Client currently running.Also shows the Maximum number of Connectionand Worker Threads. The IO number is the totalnumber of calls to the CEET, Mic is the total waittime for a CEET call in microseconds, Ave is theaverage, and Wait is the number of calls that had toissue a CICS WAIT.


System Action: Information displayed on terminalscreen.

S7M5902I token = condition eventtoken S0Cx Abend

Explanation: A critical error condition occurred ina Work Thread causing an ABEND. The conditionevent token is provided by the LanguageEnvironment. A CEEDUMP is taken and the WorkThread is terminated.

User Response: Analyze the last EMS API call tothis Work thread and check address pointers ofparameters passed to the EMS library; the dumpwill help with this. Correct problem and retry thetransaction.

System Action: The Work Thread is terminated.

67



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

Explanation: A CICS Application EnvironmentAnchor Pointer TS record with pointers to criticaldata could not be written. S7M3PASS issued a“EXEC CICS WRITEQ TS ” and did not receive a“NORMAL” response. response 1 and response 2 arethe CICS response codes for a EXEC CICS WRITEQTS.

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

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

Destination: DDNAME CEEOUT.

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

Explanation: The Enable for the S7MATRUE(TRUE) program failed. On the first call to theCEET after module S7M3EMSS is attached, theroutine issues an ENABLE PROGRAM forS7MATRUE. If this command fails, the abend isissued.

The system issues the following information:

EXEC CICS ENABLEPROGRAM('S7MATRUE'),START,


Without this program properly enabled, the CEETcannot cleanup transaction terminations that useEMS API calls. response 1 and response 2 are theCICS response codes for the preceding statement.


System Action: The transaction is abended witheither S7ME or S7MF and the CEET environment isnot setup.


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

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


System Action: The CICS transaction is terminatedwith a S7M1 abend.


68



S7M6204S No CommArea orCommArea too small

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

User Response: If the user is accessing S7M3PASSvia the S7MASTUB, then an internal problemexists. It is good practice to contact TIBCOtechnical support and provide system logs, CICSdumps, and Auxtrace. Check the LKED for the userprogram to ensure it includes S7MASTUB.

System Action: The CICS transaction is terminatedwith a S7M3 abend.


69


CICS Sample Programs

You are required to have CICS sample programs to build and run sample CICS transactions.

Message Consumer and Producer SamplesMessage consumer and producer sample programs are described as follows. The members pertainspecifically to CICS online.

Sample Type C Language COBOL

TIBCO EMS MessageConsumer

(Functions use non-typedconnections 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-typedconnections and sessions)

Source member: S7M3MP

Transaction ID: S73P

Source member: S7MCMP

Transaction ID: S7CP

BMS map used: S7MCMMP

For details on running the C and COBOL samples, see Verification of the Installation.

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

Source member: S7MPSM1

Transaction ID: S7P1

JCL and General Procedure SamplesThe following table shows the JCL samples and general procedure samples.

JCL samples are described as follows.

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

The general procedure samples are described as follows.

Member Description

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

70


Member Description

TIBCCCPL Procedure to compile, prelink, and link COBOL applications

TIB3CC17 Procedure to compile, prelink, and link C applications for z/OS v1.7 and lowercompiler

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

Sample Program Data SetsThe sample programs are contained in the following data sets:

Name Data Set

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

71


Installed Data Set Specifications

The following table shows all the installed data sets.

Data SetSpace (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

72


Documents

TIBCO Installation and Reference · TIBCO EMS Client for z/OS (CICS) Installation and Reference ... TIBCO Enterprise Message Service Central Administration